Phase D PR1: recipe API for implicit residual equations (strain-coupled scalar state)

[petlenz]

What

First PR of the strain-coupled-state frontier (verified reachable by the Mode-B spike). Adds the recipe IR + API to declare a scalar state defined by an implicit residual R(x, inputs) = 0 (solved by a Newton solver), rather than a rate dx/dt = f(x).

Why a new mechanism: a rate is scalar_expression-typed, hence strain-independent by construction (the cas scalar node set has no bridge to a tensor leaf). A residual is expected to depend on the tensor strain — that's the coupling — so it's tensor_to_scalar-typed (a scalar built from the scalar state/params AND tensor inputs, e.g. x − c·trace(ε)). Confirmed x − c·trace(ε) auto-builds as t2s, no manual wrapping.

This is purely the recipe API — no emission yet (PR2 = NumSimMaterialTarget Mode-B emission; PR3 = e2e golden).

API

• struct ResidualEquation { state_variable_idx; expression_holder<tensor_to_scalar_expression> residual; doc; }
• add_scalar_residual_equation(ScalarStateVariableHandle const&, residual, doc="")
• residual_equations() accessor.

Validation

• All residual leaves (scalar and tensor) must be declared symbols — unlike a rate, a residual may reference inputs (the coupling).
• The residual must reference its own state (else ∂R/∂x ≡ 0 — a singular Newton Jacobian).
• A state carries a rate XOR a residual — never both (enforced both directions).

Refactor

Extracted the shared handle-resolution (cross-recipe-hijack + bare-leaf defenses + index lookup) into resolve_scalar_state_var_index_, now used by both add_scalar_evolution_equation and add_scalar_residual_equation (caller-name parameterized; the one message-asserting test preserved). Plus a shared assert_state_var_unbound_ for the XOR guard.

Tests

6 new (RecipeTest): store-strain-coupled-residual, undeclared-leaf, state-must-appear, rate↔residual mutual exclusion (both orders), cross-recipe handle rejection. Full suite 280 pass.

Scoped tight: no RecipeView (pass-view) forwarding — PR2's target reads ConstitutiveModel directly; will add when a pass needs it.

🤖 Generated with Claude Code