Release wave (reference driver): QUBODrivers 0.6 / QUBOTools 0.13 compat + benchmark conformance

[bernalde]

Part of the benchmarking-readiness epic: JuliaQUBO/QUBO.jl#40 (WS2 — coordinated driver release wave). Blocked by the QUBODrivers metadata/seed standardization and conformance-suite issues on that epic (WS1) — adopt both in a single PR here so the package is only touched once.

Problem

QUBO.jl v0.6 requires QUBODrivers = "0.6" / QUBOTools = "0.13". MQLib.jl's current compat is:

QUBODrivers = "0.4, 0.5"
QUBOTools   = "0.12"

The intersection with QUBO.jl v0.6 (and with the QUBOLib-served QOBLib benchmarking stack) is empty — this package cannot be installed alongside the rest of the ecosystem. A scheduled ecosystem-resolution canary is being added to QUBO.jl that will stay red until this lands.

Package-specific work

• Suggested first driver in the wave (pure JLL binary, no Python, already has a RandomSeed["seed"] attribute and per-iteration timing) — its conformance run becomes the reference template posted on the epic.
• QUBOTools = "0.12" is the tightest pin in the ecosystem — widen to "0.12, 0.13" after verifying the format/API surface used (model read + SampleSet construction) is unchanged in 0.13.
• MQLib heuristics are time-limit driven: declare enforces_time_limit = true and make sure MOI.TimeLimitSec maps to the heuristic runtime parameter (it already scales num_reads to the time limit — document the semantics).
• 37 heuristics selectable: expose the heuristic name as a sweep-able attribute and record it under metadata["algorithm"]["name"] so campaign results distinguish them.

Common work (all drivers in the wave)

1. Bump compat: QUBODrivers = "0.6" (drop pre-0.5 entries unless there's a reason to keep them) and QUBOTools = "0.13" where it is a direct dependency. Fix any breakage from the upgrade.
2. Adopt the QUBODrivers metadata schema: metadata["time"]["effective"] (backend solve time) always set; seeds recorded under metadata["seeds"]; backend name/version under metadata["backend"].
3. Declare capability traits honestly (supports_seed, honors_final_reads, enforces_time_limit).
4. Adopt the standard RandomSeed attribute where the backend supports seeding (alias any existing seed attribute to it; keep the old one as deprecated).
5. CI runs the upgraded QUBODrivers.test(Optimizer) with benchmark_conformance = true.
6. Tag a release and verify it registers (General registry compat must match).

Checkpoints (anti-drift)

• Before starting: wait for the reference driver run posted on the epic (first wave driver, suggested MQLib.jl) and use its conformance output as the template — deviations should be deliberate, not accidental.
• Mid-PR: post the conformance-suite output here (all sets, including which are trait-skipped and why).
• Before merge: resolve a temp environment with QUBO@0.6 + this branch via Pkg.develop — the actual coexistence check, not just compat-file edits.

Acceptance criteria

• Registered release with QUBODrivers 0.6 / QUBOTools 0.13 compat, conformance suite green in CI, package resolves alongside QUBO.jl v0.6.

[bernalde]

Additional evidence from the QUBODrivers conformance-suite PR:

While working through JuliaQUBO/QUBODrivers.jl#52 / JuliaQUBO/QUBODrivers.jl#50, I tried to run the new benchmark conformance suite against unchanged registered MQLib as the external-driver checkpoint.

Command attempted:

julia --project=/tmp/qubodrivers-pr52-mqlib -e 'using Pkg; Pkg.activate("/tmp/qubodrivers-pr52-mqlib"; shared=false); Pkg.develop(path="/tmp/QUBODrivers-issue-50"); Pkg.add(["MQLib", "Test"]); using Test, QUBODrivers, MQLib; QUBODrivers.test(MQLib.Optimizer)'

Result: package resolution fails before QUBODrivers.test(MQLib.Optimizer) can run.

Observed failure:

• Local QUBODrivers v0.6.0 requires QUBOTools 0.10-0.13.
• Registered MQLib versions compatible with QUBODrivers v0.6.0 resolve only to old MQLib versions (0.1.0-0.1.2 in the resolver trace).
• Those MQLib versions pull Anneal constraints that conflict with the QUBOTools range required by QUBODrivers v0.6.
• The resolver reports no valid Anneal versions left, so the external-driver conformance run cannot start.

This confirms the compat work in this issue is a prerequisite before MQLib can participate in the QUBODrivers v0.6 benchmark conformance suite.

[bernalde]

Conformance-suite checkpoint for the MQLib.jl release-wave branch.

Branch: fix/issue-26-qubodrivers-compat
QUBODrivers test source: /tmp/QUBODrivers-issue-50 at 7731eee (feat: add benchmark conformance checks (#50), merged upstream via JuliaQUBO/QUBODrivers.jl#52).

Command:

julia --project=/tmp/mqlib-issue26-conformance -e 'using Test, MQLib; import MQLib: MOI, QUBODrivers; println("supports_seed=", QUBODrivers.supports_seed(MQLib.Optimizer)); println("honors_final_reads=", QUBODrivers.honors_final_reads(MQLib.Optimizer)); println("enforces_time_limit=", QUBODrivers.enforces_time_limit(MQLib.Optimizer)); @testset verbose=true "MQLib benchmark conformance" begin QUBODrivers.test(MQLib.Optimizer; examples=false, benchmark_conformance=true) do model MOI.set(model, MOI.Silent(), true); MOI.set(model, MQLib.Heuristic(), first(MQLib.heuristics())) end end'

Output:

supports_seed=true
honors_final_reads=true
enforces_time_limit=true
Test Summary:                                    | Pass  Total   Time
MQLib benchmark conformance                      |  115    115  20.3s
  ☢ QUBODrivers' Test Suite for «MQLib v0.1.0» ☢ |  115    115  14.9s
    → Interface                                  |  101    101   7.8s
    → Benchmark Conformance                      |   14     14   7.2s

Benchmark conformance groups:

• Metadata Conformance: active, passed.
• Timing Sanity: active, passed.
• Seed Determinism: active because supports_seed=true, passed.
• Reads Semantics: active with honors_final_reads=true, passed.
• Time Limit Acceptance: active with enforces_time_limit=true, passed.
• Termination Status: active, passed.

Trait-skipped sets: none.

[bernalde]

Branch hygiene note for PR automation:

This issue is part of the release-wave cleanup. A PR for this issue should be treated as ready only if:

• the PR base is the repository default branch (main);
• the branch was created from, or rebased onto, current origin/main;
• it is not stacked on any parked fix/*, feature/*, docs/*, or codex/* branch;
• any prerequisite parked PRs are merged, closed, or explicitly marked superseded.

Current PR: #27 (fix/issue-26-qubodrivers-compat -> main), currently clean and green at the time of this note.

When updating or recreating the PR body, include a Branch Hygiene section with:

• Base branch: main
• Created/rebased from: origin/main
• Stacked on experimental branch: no
• Prerequisite parked branches: merged / closed / superseded, with links

[bernalde]

@JuliaRegistrator register branch=main

[JuliaRegistrator]

Registration pull request created: JuliaRegistries/General/157879

Recommendation: add release notes

Release notes help your users know what has changed in the new version. For breaking releases in particular, it's recommended to document what breaking changes were made (or point to where changes can be found, such as a changelog).

To add release notes, just add markdown formatted text underneath the comment after the text "Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add release notes to this registration, just re-invoke JuliaRegistrator and the PR will be updated.

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.7.0 -m "<description of version>" d7ac0c94caa5cabffab02ec0200a65c9baca2121
git push origin v0.7.0

[bernalde]

@JuliaRegistrator register

[JuliaRegistrator]

Registration pull request updated: JuliaRegistries/General/157879

Recommendation: add release notes

Release notes help your users know what has changed in the new version. For breaking releases in particular, it's recommended to document what breaking changes were made (or point to where changes can be found, such as a changelog).

To add release notes, just add markdown formatted text underneath the comment after the text "Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add release notes to this registration, just re-invoke JuliaRegistrator and the PR will be updated.

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.7.0 -m "<description of version>" d7ac0c94caa5cabffab02ec0200a65c9baca2121
git push origin v0.7.0

[bernalde]

@JuliaRegistrator register branch=main

Release notes:

Breaking changes

• The package now requires QUBODrivers 0.6.1 and QUBOTools 0.13 for the release-wave driver interface. Environments pinned to older QUBODrivers or QUBOTools versions must update their manifests.

Changelog

• Updated compatibility to QUBODrivers 0.6.1 and QUBOTools 0.13.
• Added QUBODrivers benchmark metadata, final-read, and time-limit conformance declarations for the MQLib optimizer.
• Kept the released MQLib driver as the reference implementation for downstream driver updates.

[JuliaRegistrator]

Registration pull request updated: JuliaRegistries/General/157879

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.7.0 -m "<description of version>" d7ac0c94caa5cabffab02ec0200a65c9baca2121
git push origin v0.7.0