Add shape probe: measure "1-D = scalar" boundary compliance

[ocots]

Summary

• Adds probe/shape/ — a diagnostic (not a test suite) that drives a type-recording OCP through CTDirect's ADNLP transcription to measure, without modifying any source, what shapes reach the user's dynamics/lagrange/mayer/path/boundary functions today, and the cost of each candidate fix (getter-level vs. call-boundary coercion). Mirrors CTFlows.jl/probe/cpu.
• Ground-truth for the "1-D = scalar" work (Handbook philosophy/dimension-and-shape.md), part of roadmap #610 §7 / discussion #609 §7.

Closes #613

Test plan

• julia --project=probe/shape probe/shape/probe_shape.jl runs clean and prints the capability matrices

[github-actions]

Breakage test results
Date: 2026-07-27 20:02:25

Name	Latest	Stable
OptimalControl	compat: v1.0.12	compat: v1.0.12

[ocots]

Why Option B (call-boundary coercion), not Option A (getter-level coercion)

Two places could apply the only/identity coercion: inside the NLP-vector getters (get_OCP_state_at_time_step, get_OCP_control_at_time_step, get_OCP_variable), or immediately before each call into a CTModels user function (dynamics, lagrange, mayer, path_constraints_nl, boundary_constraints_nl).

Option A looks cheaper at first glance — three functions instead of ~16 call sites — but the probe shows it's incomplete by construction, not just costlier:

• The getters are not solely a user-function boundary. They also feed get_time_grid (→ CTModels.final_time(ocp, v) — works either way, CTModels has a ctNumber method), build_OCP_solution's v[:] = <result> (breaks on a scalar: ArgumentError), and trapeze's x_next += h*(w_i + w_{i+1}) (breaks on a scalar: MethodError). Those two are fixable, but they're evidence the getters carry more consumers than the "shape it for the user" job.
• The decisive one: the IRK / IRK-stagewise stage state never passes through a getter at all. work_xij is a work buffer built by in-place accumulation (@. work_xij = work_xij + h * a_jl * k_il) and handed straight to dynamics(...). Coercing the getters can't touch it — it would need a second, separate coercion mechanism at the IRK dynamics/Lagrange call sites, with the IRK path silently non-compliant if anyone forgot to add it.

So Option A reduces to Option B + a second mechanism + two internal-algebra rewrites. Option B — precomputing cx/cu/cv once from the OCP's declared dimensions and applying them right before each user-function call, buffers left untouched — is complete in one pass, matches "the shape contract is set by whoever calls the function" (Handbook), and is exactly the shape CTFlows already ships (_dim_coerce/_coerce_state in CTFlows.Systems/CTFlows.Flows). It's also the form that survives the §3 recipe rework: the coercion becomes a shape ingredient carried by the recipe, applied at the emission points — the getters Option A would touch are precisely what §3 replaces with layout index-range accessors.

Explicitly out of scope here (and why)

• GPU-safe only (CTFlows' _safe_only). CTDirect's ADNLP transcription is CPU-only today, so plain Base.only is correct and avoids pulling GPUArraysCore into CTDirect for no reason. If/when a GPU-backed ADNLP path exists, swapping in a _safe_only-equivalent is a one-function change (same call sites, same signature).
• ExaModels / Exa backend. That transcription still lives in CTParser, not CTDirect (roadmap [Roadmap] Consolidate CTDirect following the Handbook philosophy #610 §5 — "own the ExaModels transcription"). Exa is functional-style (no in-place buffer), so its shape boundary needs separate treatment once it's repatriated here; bolting a CPU-ADNLP-shaped fix onto it now would likely need redoing.
• ode/variable.jl (direct-shooting variable-step ODE). Not even included in CTDirect.jl today, and has an error("type ?") mid-file — it's half-finished independently of this work. Align it under §10 (multiple shooting rework) instead of carrying dead code through this change.
• Promoting the coercion primitive to CTBase.Core. CTBase.Core.make_coerce already exists but dispatches on the runtime value (make_coerce(::Number) = only), which is the opposite of what the Handbook asks for here (dimension-declared, not value-typed). Since CTFlows and CTDirect would need different onlys (GPU-safe vs. plain) if unified today, sharing a primitive is a cross-package decision better made once §5 forces the GPU question, not before.

Detailed audit (measured capability matrices, full call-site inventory, test sketches) to follow in a separate comment/report on this PR.

[ocots]

Scope note: existing test problems are not migrated to scalar style here.

The implementation adds one new test problem (test/problems/scalar_style_integrator.jl) written in the idiomatic scalar style (r[1] = -x + u, no [1] on the inputs), used purely as a non-regression pin: it fails today (MethodError) and passes once the call-boundary coercion lands.

All the existing test problems (both @def-based and functional-API) are left untouched. This is intentional and not risky: every 1-D user function already in the repo is [1]-indexed (u[1], v[1], etc.), so it evaluates identically whether it's handed a Number or a length-1 vector — that's exactly the "safe common denominator" the Handbook's migration note describes. There is nothing to fix for correctness.

That said, rewriting them to drop the now-unnecessary [1] indexing would be more consistent with the "1-D = scalar" convention once this lands, and would make the existing suite a better advertisement of the idiom for anyone reading it. I'm deliberately leaving that as a follow-up cleanup PR rather than bundling it here, to keep this diff mechanical and easy to review.

[codecov]

Codecov Report

❌ Patch coverage is 96.72131% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.25%. Comparing base (f8b7732) to head (30faf01).

Files with missing lines	Patch %	Lines
src/ode/midpoint.jl	80.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #614      +/-   ##
==========================================
+ Coverage   70.64%   71.25%   +0.61%     
==========================================
  Files          14       14              
  Lines        1366     1395      +29     
==========================================
+ Hits          965      994      +29     
  Misses        401      401              

☔ 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.