engine: C-LEARN full simulation blocked by non-macro issues (circular dep, dimension mismatches, unknown dep) -- the macro epic's deferred 'tracked separately' follow-up

[bpowers]

Summary

Full end-to-end simulation of the C-LEARN hero model (test/xmutil_test_models/C-LEARN v77 for Vensim.mdl) against its in-repo Vensim reference output (test/xmutil_test_models/Ref.vdf) is blocked by a set of non-macro correctness issues in C-LEARN / the native MDL parser / the engine. This is the "C-LEARN full simulation / non-macro blockers" follow-up that the Vensim macro design (docs/design-plans/2026-05-13-macros.md, line 19; Phase 7 plan lines 5, 31, 63, 108, 166) repeatedly and explicitly scopes out of the macro epic and promises is "tracked separately." This issue is that tracking item.

These are NOT macro bugs. Phase 7 verified macros.AC6.2: C-LEARN's four macros (SAMPLE UNTIL, SSHAPE, RAMP FROM TO, INIT) parse, register, and expand with zero macro-attributable diagnostics after the #554 fix landed. The macro layer is clean. The blockers below are pre-existing engine/parser/model-logic issues the macro epic deliberately deferred.

Symptom

simulates_clearn() (src/simlin-engine/tests/simulate.rs, ~line 949, currently #[ignore]d) does the full path: open_vensim -> compile_vm -> Vm::run_to_end -> parse Ref.vdf -> ensure_vdf_results. It cannot run because compile_vm fails with NotSimulatable: model 'main' has circular dependencies before the VM is even constructed, entirely due to the non-macro issues below. The #[ignore] comment (simulate.rs:912-945) documents the macro work as complete and names these non-macro causes.

The non-macro blockers (from compiling C-LEARN; all on the main model)

1. Model-logic CircularDependency on main.previous_emissions_intensity_vs_refyr. This is a real main-variable circular dependency, distinct from the project-level macro-registry false-recursion that engine: macro whose body wraps a same-canonical-name intrinsic (INIT = INITIAL(x)) causes false recursion cycle, blocking C-LEARN macro expansion #554 addressed (that one was init -> init at the macro-registry level; this one is attributed to an actual main variable).
2. MismatchedDimensions on c_in_mixed_layer, heat_in_atmosphere_and_upper_ocean, c_in_deep_ocean_net_flow, heat_in_deep_ocean_net_flow -- subscript/dimension issues in C-LEARN's carbon/heat ocean-layer equations.
3. UnknownDependency on emissions_with_cumulative_constraints.
4. Non-time $ reference surfacing as DoesNotExist on "goal_1.5_for_temperature". This is a documented, accepted limitation, not a defect to fix in the normal sense. Phase 3 of the macro design explicitly deprioritized / does not support the non-time $ escape; it correctly surfaces as an ordinary unresolved-reference diagnostic (no macro name, no macro-instance variable, not a registry-build error) and was deliberately classified as a non-macro blocker, not a macro bug. If non-time $ support is ever desired it could become its own separate, lower-priority item; it should not be conflated with the genuine defects (1-3) above.
5. Unit-inference warnings (non-fatal).

Why it matters

These collectively block full end-to-end validation of the C-LEARN hero model against the checked-in Vensim DSS reference (Ref.vdf) -- the canonical correctness signal for a flagship Vensim model. They are pre-existing C-LEARN / native-MDL-parser / engine issues, independent of macros (the macro layer is clean per AC6.2). Without resolving them, simulates_clearn() stays #[ignore]d and we have no automated end-to-end C-LEARN simulation regression gate.

Components affected

• src/simlin-engine -- dependency analysis / cycle detection (blocker 1), dimension/subscript checking (blocker 2), reference resolution (blockers 3, 4)
• src/simlin-engine/src/mdl/ (native MDL parser) -- likely involved in the dimension and reference-resolution blockers for C-LEARN's specific equations
• src/simlin-engine/tests/simulate.rs -- simulates_clearn() (the #[ignore]d end-to-end test that will be un-ignored once these are resolved)
• Test fixtures: test/xmutil_test_models/C-LEARN v77 for Vensim.mdl, test/xmutil_test_models/Ref.vdf

Recommended remediation

Triage each non-macro blocker (1-3) individually for full C-LEARN simulation; they likely have independent root causes (cycle detection vs. dimension checking vs. reference resolution) and may warrant being split into focused child issues once triaged. Blocker 4 (non-time $) is a separately-documented accepted macro-design limitation -- treat it as a known limitation, optionally its own lower-priority item only if non-time $ support is ever desired; do NOT block C-LEARN simulation triage on it (it could be tolerated/diagnosed distinctly). Once blockers 1-3 (and a decision on 4) are resolved, un-#[ignore] simulates_clearn() and confirm it matches Ref.vdf.

Relationship to existing issues (all DISTINCT, not duplicates)

• engine: C-LEARN macro expansion blocks 1 simulation test #349 ("engine: C-LEARN macro expansion blocks 1 simulation test"): filed pre-macro-implementation; its premise -- that C-LEARN can't simulate because macro expansion is not implemented -- is now obsolete. Macro expansion works and is clean (AC6.2). engine: C-LEARN macro expansion blocks 1 simulation test #349's simulates_clearn test is this issue's end-to-end test; the remaining blocker is the non-macro set tracked here, not macro expansion. (engine: C-LEARN macro expansion blocks 1 simulation test #349 can be closed or re-pointed at this issue once triaged.)
• engine: macro whose body wraps a same-canonical-name intrinsic (INIT = INITIAL(x)) causes false recursion cycle, blocking C-LEARN macro expansion #554 (macro INIT = INITIAL(x) false self-recursion in the macro registry): a macro-specific correctness bug, now fixed; that fix is why the macro layer is clean. Distinct subsystem (macro registry) and symptom (project-level recursive macro: init -> init) from blocker 1's real main-variable cycle.
• Incremental compiler panics on C-LEARN model (catch_unwind workaround) #363 (incremental compiler panics on C-LEARN via salsa / catch_unwind): different symptom (panic vs. NotSimulatable/diagnostics) and subsystem (incremental/salsa pipeline).
• engine: Vensim macro formal parameter named like a control variable (Final Time, etc.) is silently dropped on MDL import #552 / engine: single-parameter Vensim macro invocation is silently rewritten to LOOKUP on MDL import #553 / engine: XMILE macro-invocation argument recovery relies on undocumented Phase-4 ModuleReference emission order (latent silent-reorder bug) #557 / engine: SourceVariable.model_name is a misnamed correctness trap (it is the Module reference target, empty for non-Module vars -- not the owning model) #558: all macro-specific (formal-parameter dropping, 1-param->LOOKUP rewrite, XMILE arg-order reliance, SourceVariable.model_name trap). Different code paths, root causes, and symptoms; none covers C-LEARN's non-macro simulation blockers.

Discovery context

Identified during Phase 7 (hero validation of C-LEARN) of the Vensim macro support epic (branch macros; design plan docs/design-plans/2026-05-13-macros.md + docs/implementation-plans/2026-05-13-macros/phase_07.md). Phase 7 verified macros.AC6.2 (zero macro-attributable diagnostics) and confirmed simulates_clearn() is blocked solely on these out-of-scope non-macro issues. The design explicitly promised these would be "tracked separately"; this issue fulfills that promise.