REGRESSION - NEW FEATURE - Pin the declared integrator as Delta-prime provenance

The Galerkin and STRIDE-like BVP Delta-prime are converging on one canonical
SingularSurfaces/ path, so the numbers alone no longer say which formalism
produced them: a deck switched from riccati to galerkin would be compared
against the other formalism's gold with no signal. The schema forbids echoing
control values into output groups, and the subgroup name that used to carry
provenance is going away, so the pin reads the deck's own declaration out of the
Input/gpec_toml_raw rerun snapshot -- the one group where control values belong.

Adds a 'toml_key:<dotted.path>' extraction yielding a 'token' value type,
compared by exact equality and classed topological, since no tolerance means
anything between "riccati" and "galerkin". A key the deck leaves unset pins as
"<unset>", so starting or stopping declaring one is itself a change.

Pinned on the four Delta-prime-bearing cases. The two Galerkin cases pin
integrator AND gal_flag, because the Galerkin Delta-prime is currently the
additive gal_flag path over a riccati sweep rather than a standalone integrator;
when the standalone integrator lands and gal_flag retires, these fail loudly,
which is the intent -- a deliberate formalism change must regenerate the gold.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: d-burg

regression-harness/cases/diiid_n1_riccati.toml

@@ -10,6 +10,18 @@ name = "diiid_n1_riccati"
 description = "DIII-D-like equilibrium, n=1, Riccati integrator Δ' matrix"
 example_dir = "examples/DIIID-like_riccati_deltaprime_example"
 
+# Which formalism produced the Δ′ below. The Δ′ matrix is written to one canonical
+# SingularSurfaces/ path whichever integrator computed it, so the numbers alone cannot say
+# whether a gold pinned from the BVP is being compared against a Galerkin run. Pinning the
+# deck's declared choice makes a formalism swap a loud failure instead of a silent re-gold.
+[quantities.integrator]
+h5path = "Input/gpec_toml_raw"
+type = "token"
+extract = "toml_key:ForceFreeStates.integrator"
+label = "integrator (Δ′ provenance)"
+noise_threshold = 0
+order = 1
+
 # Tearing stability Δ' — the msing×msing BVP matrix diagonal, and the raw side-major
 # outer-region matrix it is projected from.
 [quantities.delta_prime]

regression-harness/cases/diiid_slayer_n1.toml

@@ -9,6 +9,17 @@ description = "DIII-D-like H-mode equilibrium, n=1, SLAYER tearing-mode analysis
 example_dir = "examples/DIIID-like_SLAYER_example"
 
 # Per-surface SLAYER layer parameters (geometry + dimensionless)
+# Which formalism produced the Δ′ this case's layer physics consumes. The Δ′ matrix lands on
+# one canonical SingularSurfaces/ path whichever integrator computed it, so pinning the deck's
+# declared choice is what keeps a BVP-derived gold from being compared against a Galerkin run.
+[quantities.integrator]
+h5path = "Input/gpec_toml_raw"
+type = "token"
+extract = "toml_key:ForceFreeStates.integrator"
+label = "integrator (Δ′ provenance)"
+noise_threshold = 0
+order = 1
+
 [quantities.slayer_ising]
 h5path = "Tearing/PerSurface/rational_index"
 type = "real_vector"

regression-harness/cases/gal_resistive_diiid.toml

@@ -10,6 +10,28 @@ description = "DIII-D-like, n=1, RDCON outer-region Galerkin Δ′ with rpec coi
 example_dir = "examples/DIIID-like_gal_resistive_example"
 
 # Number of resonant surfaces in the gal domain
+# Which formalism produced the Galerkin Δ′ below. Both this deck's `integrator` and its
+# `gal_flag` are pinned because the Galerkin Δ′ is currently the additive path (gal_flag
+# layered on a riccati sweep) rather than a standalone integrator, so the pair is what names
+# the formalism. Once the standalone `integrator = "galerkin"` lands and gal_flag is retired,
+# these pins fail loudly — which is the intent: a deliberate formalism change must regenerate
+# the gold rather than silently re-pointing it at different physics.
+[quantities.integrator]
+h5path = "Input/gpec_toml_raw"
+type = "token"
+extract = "toml_key:ForceFreeStates.integrator"
+label = "integrator (Δ′ provenance)"
+noise_threshold = 0
+order = 1
+
+[quantities.gal_flag]
+h5path = "Input/gpec_toml_raw"
+type = "token"
+extract = "toml_key:ForceFreeStates.gal_flag"
+label = "gal_flag (Δ′ provenance)"
+noise_threshold = 0
+order = 2
+
 [quantities.gal_msing]
 h5path = "ForceFreeStates/Solutions/GalerkinIntegration/rational_count"
 type = "int_scalar"

regression-harness/cases/gal_resistive_pe.toml

@@ -14,6 +14,28 @@ example_dir = "examples/DIIID-like_gal_resistive_pe_example"
 # any whole-profile ξ/ξ′ norm (those diverge at the rationals and are ill-posed as benchmarks).
 
 # Surface locations / count (sanity)
+# Which formalism produced the Galerkin Δ′ below. Both this deck's `integrator` and its
+# `gal_flag` are pinned because the Galerkin Δ′ is currently the additive path (gal_flag
+# layered on a riccati sweep) rather than a standalone integrator, so the pair is what names
+# the formalism. Once the standalone `integrator = "galerkin"` lands and gal_flag is retired,
+# these pins fail loudly — which is the intent: a deliberate formalism change must regenerate
+# the gold rather than silently re-pointing it at different physics.
+[quantities.integrator]
+h5path = "Input/gpec_toml_raw"
+type = "token"
+extract = "toml_key:ForceFreeStates.integrator"
+label = "integrator (Δ′ provenance)"
+noise_threshold = 0
+order = 1
+
+[quantities.gal_flag]
+h5path = "Input/gpec_toml_raw"
+type = "token"
+extract = "toml_key:ForceFreeStates.gal_flag"
+label = "gal_flag (Δ′ provenance)"
+noise_threshold = 0
+order = 2
+
 [quantities.pe_rational_q]
 h5path = "PerturbedEquilibrium/SingularCoupling/rational_q"
 type = "real_vector"

regression-harness/src/extractor.jl

@@ -112,6 +112,24 @@ function apply_extraction(spec::QuantitySpec, raw)::ExtractedQuantity
         json_str = JSON.json(pairs; allownan=true)
         return ExtractedQuantity(name, label, nothing, nothing, json_str, "json_array", threshold)
 
+    elseif startswith(spec.extract, "toml_key:")
+        # "toml_key:<dotted.path>": pin a deck's declared control value, read out of the
+        # `Input/gpec_toml_raw` rerun snapshot. Used to record which formalism a case asked
+        # for, because the Δ′ matrix is written to one canonical `SingularSurfaces/` path
+        # whichever integrator produced it, so the numbers alone no longer say. Reading it
+        # from `Input/` respects the schema rule that control values live nowhere else.
+        # A key the deck leaves unset pins as "<unset>", so a deck that starts or stops
+        # declaring one is itself a change rather than being silently absorbed.
+        keypath = spec.extract[(length("toml_key:")+1):end]
+        table = TOML.parse(raw isa AbstractString ? raw : String(raw))
+        node = table
+        for key in split(keypath, ".")
+            node = (node isa AbstractDict && haskey(node, key)) ? node[key] : nothing
+            node === nothing && break
+        end
+        token = node === nothing ? "<unset>" : string(node)
+        return ExtractedQuantity(name, label, nothing, nothing, token, "token", threshold)
+
     elseif spec.extract == "checksum"
         bytes = reinterpret(UInt8, vec(collect(raw)))
         hash = bytes2hex(sha256(bytes))
@@ -218,7 +236,7 @@ function compare_values(q1::NamedTuple, q2::NamedTuple)
         status = max_diff <= threshold ? "OK" : "CHANGED"
         return (max_diff, rel_diff, status)
 
-    elseif vtype == "checksum"
+    elseif vtype == "checksum" || vtype == "token"
         t1 = q1.value_text
         t2 = q2.value_text
         if t1 === nothing || t2 === nothing

regression-harness/src/golden.jl

@@ -223,6 +223,9 @@ function infer_class(spec::QuantitySpec)::String
     spec.type == "runtime" && return "diagnostic"
     spec.name in ("nstep", "nstep_total") && return "diagnostic"
     spec.type == "int_scalar" && return "topological"
+    # A declared control token is an exact-match gate, like a count: there is no tolerance
+    # that means anything between "riccati" and "galerkin".
+    startswith(spec.extract, "toml_key:") && return "topological"
     name = spec.name
     # sing_psi / sing_q are deliberately absent: singular-surface locations come from a root
     # search, not pure spline/quadrature, so they take the measured physics_converged path.
@@ -269,6 +272,15 @@ function compare_to_golden(q::NamedTuple, g::GoldenValue)
         gold = JSON.parse(g.value_text; allownan=true)
         length(got) == length(gold) && return _compare_arrays(got, gold, g, within)
         return (false, NaN, "length $(length(gold)) → $(length(got))")
+
+    elseif g.value_type == "token"
+        # A token names a discrete choice (which integrator produced the Δ′), so there is no
+        # tolerance to apply: it matches or the run is answering a different question than the
+        # gold does. Deviation is reported as 1.0 on mismatch rather than NaN so it sorts as a
+        # real failure in reports.
+        (q.value_text === nothing || g.value_text === nothing) && return (false, NaN, "missing token")
+        matched = q.value_text == g.value_text
+        return (matched, matched ? 0.0 : 1.0, matched ? "" : "$(g.value_text) → $(q.value_text)")
     end
 
     return (false, NaN, "unsupported value type $(g.value_type)")

regression-harness/src/types.jl

@@ -8,8 +8,9 @@ Specification for a single quantity to extract from gpec.h5.
 struct QuantitySpec
     name::String
     h5path::String          # HDF5 dataset path (e.g. "ForceFreeStates/FreeBoundaryStability/eigenmode_energies"), empty for runtime
-    type::String            # "complex_vector", "real_vector", "real_scalar", "int_scalar", "real_matrix", "runtime"
-    extract::String         # "value", "real_first", "imag_first", "abs_first", "norm", "all_real", "all_complex", "checksum"
+    type::String            # "complex_vector", "real_vector", "real_scalar", "int_scalar", "real_matrix", "token", "runtime"
+    extract::String         # "value", "real_first", "imag_first", "abs_first", "norm", "all_real", "all_complex",
+    # "diagonal_complex", "first_<N>", "first_<N>_complex", "checksum", "toml_key:<dotted.path>"
     label::String           # Human-readable label for reports
     noise_threshold::Float64 # Absolute changes below this are noise
     order::Int              # Display order in reports (lower = earlier)