Align with CTBase 0.29 / CTModels 0.18 / ExaModels 0.12

[ocots]

Closes #325. Closes #323. Closes #322. Closes #339. Closes #230. Closes #341. Closes #342. Closes #343. Closes #344.

Problem

CTSolvers 0.5.3 already declares ExaModels = "0.12", but its extension only reads backend metadata. The package that actually emits ExaCore / variable / constraint / objective calls is CTParser, from def_exa in src/onepass.jl — and ExaModels 0.12 deleted that mutable builder API (src/deprecated.jl is gone, along with variable, parameter, subexpr, constraint! and LegacyExaCore).

So CTSolvers' declared 0.12 support was nominal until this: any :exa solve failed at run time, inside generated code, with UndefVarError: variable not defined in ExaModels. CTParser is the one package in the stack whose source had to change.

Public API changes

1. The :exa emission requires ExaModels ≥ 0.12

Supporting both is not practical: CTParser does not depend on ExaModels (the module is reached through prefix_exa()), so it cannot branch on the version at macro-expansion time.

# Before — emitted against ExaModels 0.9–0.11
c = ExaModels.ExaCore(base_type; backend, minimize)
x = ExaModels.variable(c, n, 0:grid_size; lvar, uvar, start)
ExaModels.constraint(c, expr for j in 0:grid_size-1; lcon, ucon)
ExaModels.objective(c, expr for j in 0:grid_size-1)

# After — emitted against ExaModels 0.12
c = ExaModels.ExaCore(base_type; backend, minimize)   # unchanged
c, x = ExaModels.add_var(c, n, 0:grid_size; lvar, uvar, start)
c, _ = ExaModels.add_con(c, expr for j in 0:grid_size-1; lcon, ucon)
c, _ = ExaModels.add_obj(c, expr for j in 0:grid_size-1)

ExaCore is called exactly as before. Under 0.12 it no longer warns — the deprecation shim is gone — so no concrete keyword is passed. That is deliberate: with the 0.12 default (Vector{Any} block storage) typeof(core) is invariant across every add_*, so rebinding the core costs nothing, whereas concrete = Val(true) changes the core's type on each add_* and would recompile the builder once per block.

2. Untyped String errors become CTException subtypes

Seventeen sites typed by the Handbook's choice rule — a single argument's value out of domain is IncorrectArgument, a relational/state/timing contract is PreconditionError.

# Before
catch e
    e == "unknown numerical scheme: gauss_legendre_2 (possible choices are ...)"
end

# After
catch e
    e isa CTBase.IncorrectArgument
end

Two of those took an actual call. A bound-length mismatch relates two things — the bounds to each other, or to the constrained range — which is the Handbook's own heuristic for PreconditionError. And :fun is a perfectly valid backend name: what is forbidden is toggling it, a state contract rather than a bad value, so that is PreconditionError while an unrecognised backend name is IncorrectArgument.

An unplanned blocker, upstream

ExaModels ships ext/ExaModelsOptimalControl.jl — the successor to 0.9's ExaModelsLinearAlgebra — but never declares it in [extensions], so Julia never loads it. Everything it provides is unreachable: dot, * on node vectors and matrices, det, norm, tr, diag, convert/promote_rule/zero/one for AbstractNode, and the Null zero/one elimination. LinearAlgebra is still in ExaModels' [weakdeps] with nothing referencing it, and OptimalControl — the trigger the rename implies — is not in [weakdeps] at all. True of main as well as of the 0.12.0 release.

That is not cosmetic: it breaks a real @def feature. A dynamics written as ∂(x)(t) == A * x(t) + B * u(t), or an objective using dot(q, x(t)), applies those operators to arrays of ExaModels nodes while the model is being built.

The shipped file still works verbatim against 0.12 once loaded by hand, so this PR carries a port of it as ext/CTParserExaModels.jl, triggered by ExaModels + LinearAlgebra weak dependencies. CTParser is the package that emits the ExaModels code, so it is the natural owner of that contract until upstream wires its own extension up. Upstream question — asked as "what is the intended direction?" rather than as a patch: madsuite-org/ExaModels.jl#323.

Two details from the port worth knowing about: upstream's Section F (ExaModels.add_con(core, ::AbstractVector)) is broken as written and is not ported, and enabling the Null zero elimination surfaces a genuine ambiguity in ExaModels' own src/simdfunction.jl:142-143 that is worked around here, with the reasoning in a comment.

GPU runner capability detection (#339)

The CI phase above swapped the retired kkt runner for occidata, but the suite still had no notion of which runner it was executing on. Both :exa GPU tiers were gated behind a bare short-circuit on CUDA.functional(), so a correctly-skipped run on a CPU laptop and a silently-broken one on occidata — device present but not functional — produced the identical output: a green run with the GPU tier simply absent. That is the anti-pattern the Handbook's philosophy/testing.md §"Capability-gated tests" forbids.

test/runtests.jl now carries the single capability module the Handbook asks for, aligned with CTSolvers (its #189 / #217):

module TestCapabilities
const CUDA_FUNCTIONAL  = CUDA.functional()
const ON_GPU_RUNNER    = any(gpu -> occursin(gpu, get(ENV, "RUNNER_NAME", "")), ("kkt", "occidata"))
const GPU_SOLVER_ARMED = isdefined(MadNLPGPU, :CUDSSSolver)
end

The substring match is deliberate: RUNNER_NAME is set by the GitHub Actions runner agent itself — no CI.yml or CTActions change needed — to the runner's registered name, and ours are registered as kkt-runner / occidata-runner, whereas the CI.yml runs_on label is the bare kkt / occidata. Detection covers both runners per the issue, even though only occidata is a live target today.

GPU_SOLVER_ARMED diverges from CTSolvers' MadNLPGPU.CUDSSSolver isa Type on purpose: the symbol only exists once MadNLPGPUCUDAExt loads, so that form would throw UndefVarError at module load and abort the whole run instead of failing one assertion. It asserts the same thing.

The two GPU tiers now branch to Test.@test_skip, and a new test/test_environment_contract.jl enforces the contract centrally: the MadNLPGPU/CUDSS extension must be armed on every runner (this is what catches the CUDSS wiring regression), a device must be present on kkt/occidata, and the silent-guard anti-pattern must not reappear anywhere under test/. CTSolvers' companion isdefined(Main, ...) audit is not ported — it exists because every CTSolvers suite file is wrapped in its own module, whereas CTParser's tests are a mix of module-wrapped and flat files included straight into Main, where the idiom is legitimate.

Verified by faking the runner on a CPU box, which is the only way to exercise the loud-failure path locally:

$ RUNNER_NAME=occidata-runner julia --project -e 'using Pkg; Pkg.test(;test_args=["environment_contract"])'
GPU driver required on the GPU runner: Test Failed at test/test_environment_contract.jl:82
$ RUNNER_NAME=kkt-runner julia --project -e 'using Pkg; Pkg.test(;test_args=["environment_contract"])'
GPU driver required on the GPU runner: Test Failed at test/test_environment_contract.jl:82

The audit proved itself the same way, unprompted: its first run failed on the explanatory comments I had just written into the two test files, which spelled out the literal pattern. Reworded, green.

Phases

• A — compat bounds. :fun groups green at 1054/1054; :exa groups red on purpose at that commit, reproducing the breakage inside the real suite.
• B — 23 emission sites moved to the functional builder API, plus the one direct ExaCore use in test_exa_linalg.jl.
• B2 — the unregistered upstream extension, ported (above).
• C — 17 throw(String) sites typed, and the 19 @test_throws String assertions with them.
• D — qualified the ExaModels import in test/runtests.jl ([Dev] Check warning when using ExaModels (constraint) #230).
• E — full suite green, docs build clean.
• F — CHANGELOG.md + BREAKING.md created with the Handbook's retroactive bootstrap (baseline v0.8.15), version bumped to 0.9.0.
• CI — the retired kkt self-hosted runner replaced by occidata, trigger labels renamed to the ecosystem's run ci <target> form.
• G — GPU runner capability detection for kkt and occidata, visible Test.@test_skip on CPU runners, and the test_environment_contract.jl meta-test (Add consistent GPU runner capability detection for kkt and occidata #339).
• H — version bumped to 0.9.2-beta, CHANGELOG.md + BREAKING.md entries (no breaking changes: test-suite and metadata only).
• I — 0.9.3-beta prep; @def/@init docstring examples moved from @example to static julia fences so they render when transcluded into consumer docs (@def/@init docstrings use ```@example fences, which Documenter never executes when transcluded into a consumer's @docs block #341).
• J — 0.9.4-beta prep; [compat] widened to CTBase = "0.29, 0.30" (Widen [compat] to admit CTBase 0.30 (needed for CTFlows 0.18's Makie backend, one level down from CTDirect#629) #342). No source change.
• K — a constraint bound that depends on v, the state, the control or the time is rejected with a CTBase.ParsingError naming the cause, instead of a leaked internal gensym UndefVarError from generated code. Backend-agnostic (:fun and :exa). (x(0) == v with v the variable reports UndefVarError: v##NNNN not defined in Main`` instead of a clear message #343, merged as fix(parser): reject constraint bounds that depend on v/x/u/t (#343) #345)
• L — @def name … end true trace mode prints the parsed model once: the :exa re-parse inside def_fun no longer inherits the log flag. (@def name … end true (trace mode) prints the parsed model twice #344, merged as fix(parser): print the trace once in @def trace mode (#344) #347)
• M — version bumped to 0.9.5-beta; CHANGELOG.md + BREAKING.md entries for x(0) == v with v the variable reports UndefVarError: v##NNNN not defined in Main`` instead of a clear message #343 / @def name … end true (trace mode) prints the parsed model twice #344 (no breaking changes: x(0) == v with v the variable reports UndefVarError: v##NNNN not defined in Main`` instead of a clear message #343 only affects inputs that already errored, @def name … end true (trace mode) prints the parsed model twice #344 is trace-only output).

Test results

file	result
test_aqua.jl	11/11 (piracies=true unchanged)
test_control_zero.jl	37/37
test_dynamics_exa.jl	100/100 + 4 skipped
test_environment_contract.jl	2/2 + 1 skipped
test_exa_linalg.jl	491/491
test_initial_guess.jl	199/199
test_onepass_exa.jl	601/601 + 4 skipped
test_onepass_exa_bis.jl	176/176
test_onepass_fun.jl	638/638
test_onepass_fun_bis.jl	129/129
test_prefix.jl	15/15
test_prefix_bis.jl	42/42
test_utils.jl	93/93
test_utils_bis.jl	58/58
total	2592/2592, 9 skipped

No errors, no failures, and no WARNING: … conflicts with an existing identifier in the log. CPU only locally — the occidata GPU job runs on this PR via its label.

Update (phases I–M). Full suite re-run green after each addition. Latest run: 2594 pass, 9 broken (pre-existing), 0 fail/error — the count moved from 2592 with the #338 follow-up already noted plus +3 from the #343 tests and +1 from the #344 test, minus test-set reshuffles on the :exa side.

The 9 skips are the point of #339: they are the 4 GPU scheme tiers per :exa test file, plus the "device only required on kkt/occidata" skip, all now visible as Broken in the summary instead of vanishing. On occidata the first 8 become real runs and the ninth becomes an asserted pass. The total moved 2580 → 2592 for reasons mostly unrelated to #339: +2 from the new file, and +5 in each of test_onepass_exa.jl and test_onepass_fun_bis.jl from the #338 fix, which landed after the earlier table was written.

Follow-up

• CTDirect.jl still pins ExaModels = "0.11" and consumes this generated code — it needs a matching bump.
• This branch now also carries the 0.9.3 → 0.9.5-beta release prep and the x(0) == v with v the variable reports UndefVarError: v##NNNN not defined in Main`` instead of a clear message #343 / @def name … end true (trace mode) prints the parsed model twice #344 parser fixes; Project.toml is at 0.9.5-beta.

🤖 Generated with Claude Code

[ocots]

@jbcaillau please review.

[codecov]

Codecov Report

❌ Patch coverage is 86.49635% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.71%. Comparing base (1d5b387) to head (5db77ee).

Files with missing lines	Patch %	Lines
ext/CTParserExaModels.jl	83.18%	37 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #326      +/-   ##
==========================================
- Coverage   98.22%   95.71%   -2.52%     
==========================================
  Files           4        5       +1     
  Lines        1073     1307     +234     
==========================================
+ Hits         1054     1251     +197     
- Misses         19       56      +37     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ocots]

Added since the initial review — phases I–M

Beyond the original ExaModels 0.12 / typed-errors / CI scope, this branch now also carries:

I — 0.9.3-beta prep (985e6ea)

@def / @init docstring examples moved from ```@example to static ```julia fences. Documenter does not execute @example blocks when the docstrings are transcluded into a consumer's @docs block, so they produced warnings downstream. Closes #341.

J — 0.9.4-beta prep, CTBase 0.30 (adb0477)

[compat] widened to CTBase = "0.29, 0.30". No source change — needed one level down for CTFlows 0.18's Makie backend. Closes #342.

K — constraint bounds must be effective (#343, merged as #345)

A constraint whose bound referenced v / the state / the control / the time, e.g. x₂(0) == v, was rejected — but with a leaked internal gensym:

Line 7: x₂(0) == v
UndefVarError: `v##286` not defined in `Main`

lb / ub are evaluated once at build time and cannot see a function-argument name (for :fun the gensym is never bound at all). p_constraint! now checks both bounds, before the :fun / :exa dispatch, and returns a CTBase.ParsingError naming the cause and pointing to x₂(0) - v == 0. The constrained side may still reference the variable (e.g. 0 ≤ r(0) - z ≤ 1) — only the bounds are restricted. Tests in test_onepass_fun.jl and test_onepass_exa.jl.

L — trace mode prints once (#344, merged as #347)

@def name … end true printed the parsed model twice when :exa was active: def_fun re-parses via def_exa(e; log=log) to embed the ExaModels builder, and that second pass re-emitted the trace. The :exa sub-parse now runs with log=false. Test captures stdout of def_fun(…; log=true) and asserts one occurrence of each trace marker.

M — 0.9.5-beta prep (5db77ee)

Project.toml → 0.9.5-beta; CHANGELOG.md and BREAKING.md sections for #343 / #344. No breaking changes: #343 only changes the exception type for input that already failed to build, #344 is trace-only output.

Status

Full suite green after M: 2594 pass, 9 broken (pre-existing), 0 fail/error (CPU-only locally; occidata GPU job runs on the PR).