DynamisLab/docs/JFM_WYQ/ROUND3_BOTTOM_UP/03_CONTRACTS_METRICS.md

Round 3 Wave-A revised candidate — Section 2 contracts and metrics

Section question and bounded answer

Question. What must be fixed about the plant, executable chain, actuation, observations, roles and estimands before later comparisons answer the same physical question rather than merely share a label?

Bounded answer. Valid comparisons use separate Legacy and V5 executable chains, each with its own plant, action convention, calibration and role artifacts. The policy performs wake-signature matching from forces and sparse downstream velocities; independent field matching uses spatial L2 as the primary evidence and DTW only as complementary, case-specific signal evidence, with periodic, event, mean-field and steady windows kept distinct. This is a revised candidate for second audit, not a ready module.

Layer 1 — six-paragraph near-prose section draft

Paragraph 1 — plant and chain

The comparison begins with a declared plant, not with a policy score. The fluidic pinball comprises three ordered circular bodies and a downstream three-probe signature plane, while Kármán and Illusion introduce different target constructions. In the active V5 Kármán chain, CelerisLab uses a 2000×600 D2Q9 FP32 MRT configuration with double-buffer streaming, uniform regularized inflow, neq_extrap outlet and free-slip lateral walls. The V5 body order is front, top, bottom; its common lattice convention is L0=20, D=20, U0=0.01, and Re_code=U0(2L0)/nu, so re100 corresponds to Re_D=50. V5 Illusion translates the pinball and obtains the non-zero target from a separate target-cylinder acquisition; its historical target_diam parameter is passed as a radius ratio. Legacy uses the separate LegacyCelerisLab plant and historical geometry/API, so a shared case label never licenses numerical pooling. [V5 train/env; Legacy role authority]

Paragraph 2 — actuation, sign and readback

A normalized action becomes a physical rotation only after body order, sign and persistence have been fixed. In V5, a=(a_front,a_top,a_bottom) lies in [-1,1]^3 and maps to

[ \omega_i=-\frac{(12a_i+b_i)U_0}{R},\qquad b_i=0, ]

with R=L0/2 and an explicit weight-0.1 exponential smoother. The negative sign and front/top/bottom order belong in the plant schematic and every downstream action-law comparison. They must not be transferred to Legacy: Legacy SR and acquisition use the native (front, upper, lower) ordering, \alpha=\omega/U_0, and Re_D=Re_code/2 for its Kármán notation, with its own action scale/bias and FlowField.run persistence. CelerisLab uploads a host-side set_body value at the next run; force readback is an [f_x,f_y] vector whose time normalization is explicit, while sensor readback is footprint-area averaged and optionally time averaged. [V5 environments; Legacy SR/action authority; CelerisLab API]

Paragraph 3 — observations, calibration and objective

The execution contract is wake-signature matching rather than an assertion of full-field observability. V5 Kármán supplies six controlled-body force components followed by six velocity channels, ordered as the two components of each of the three probes; V5 Illusion appends reconstructed target drag and lift. Solver readback, calibrated force and sensor scales, and online observation whitening are separate operations: active V5 calibration stores native units, while SB3 VecNormalize whitens observations only and must travel with the selected policy. The historical Legacy compatibility path may use SENSOR_CC=78 before its old-policy scaling; that factor is not active V5 calibration. Roles are likewise explicit: target is a reference trajectory, zero is physical-zero/uncontrolled, controlled is the policy trajectory, and constant is a contextual comparator where acquired. Force terms and six-channel sensor similarity form the reward; aggregation and target comparison are case-specific, with V5 Kármán averaging controlled-body forces against zero and V5 Illusion summing them against one target body. [V5 training pipeline; Legacy acquisition authority]

Paragraph 4 — field matching and signal complement

The independent field comparison is registered before performance is inspected. The current downstream ROI is the fixed rectangle -6≤(x-x_s)/D≤14 and |(y-y_0)/D|≤5, a 20D×10D box guarded against known solids but not proven by persisted solver masks. For periodic roles, the primary estimand is the U0-normalised area-RMS difference between complete-cycle mean velocity fields, reported both absolutely and relative to the same-case zero comparator through η=1-E_controlled/E_zero. The eight-slot phase diagnostic uses independently phased centre-probe transverse-velocity crossings and nearest saved snapshots; it is not a repeated-crossing ensemble. DTW remains a complementary sparse-signal measure, not a spatial L2 surrogate, physical delay or causal test. This hierarchy asks separately whether the persistent field and the evolving signature approach the target. [wake-L2 authority]

Paragraph 5 — case-specific evaluation windows

The estimand changes with the dynamics and must be named in every result row. Periodic Kármán and periodic Illusion can use complete-cycle mean-field L2 and a separately reported eight-slot phase diagnostic, with native or normalized DTW labelled by its own window and formula. Vortex comparisons, if exact roles exist, use event-relative downstream snapshots at declared offsets and retain event labels rather than calling them phase. Erase uses a mean-field comparison only when target, controlled and zero roles are exact; the historical unsupported route is not repaired by relabelling. Steady comparisons use a late snapshot or profile, not a temporal periodic mean. Pipeline Level-2/Level-3 or Stage-3 short/standard terminology must also remain separate from the spatial L2 metric. [case-metric authority; wake-L2 authority]

Paragraph 6 — compact CFD qualification and scope

The numerical qualification is a compact contract check, not a second results section. The retained CelerisLab K2 rotating-cylinder package uses D2Q9 MRT, FP32, double-buffer streaming, Bouzidi moving boundaries, no LES and neq_extrap outlet under the Kan99b open-flow convention; it is a partial pass because the stored mean-lift sign disagrees with the reference even though the accepted frequency, drag and fluctuation observables fall within their declared bands. The retained Sah04 S2 confined-cylinder package provides a named Strouhal check under its parabolic/channel-stabilised, no-slip and realised-Re convention. These anchors qualify selected solver observables only; they do not qualify a DRL policy, SR law, CCD interpretation or cloaking mechanism. Full matrices, hashes, sensitivity rows and smoke diagnostics belong in the supplement. [CelerisLab validation dossier; Kan99b/Sah04 authorities]

Layer 2 — paragraph and claim-to-evidence ledger

Paragraph / claim	Exact provenance and contract	Comparator, metric, ROI/window and status
P1: V5 plant	src/drl_pinball/train/TRAIN_PIPELINE.md §§1–2; train/env_karman.py; DATA_DICTIONARY.md; active V5 Kármán, CelerisLab 2000×600, D2Q9 FP32 MRT, double buffer, regularized uniform inlet, neq_extrap, free-slip; body order front/top/bottom; L0=20, D=20, U0=.01; Re_code=U0(2L0)/nu	Same matched config/calibration/target for target, zero and controlled; case/seed/role-specific; field window is the registered downstream ROI below; supported executable contract, not independently rerun
P1: V5 Illusion geometry	train/env_illusion.py lines 50–60, 157–184; active V5 Illusion target acquisition and translated controlled plant; target cylinder exists only during target construction; target_diam*L0 is passed as radius	Target versus controlled only under matched target/calibration identity; periodic or case-specific metric later; supported executable contract
P1: Legacy separation	ROUND1_BOTTOM_UP/01_DRL_CONTROL_AND_CASES.md §§4–5; src/drl_pinball/legacy_test/README.md; Legacy Kármán/Illusion role artifacts and LegacyCelerisLab API	No cross-chain score pooling; Legacy evidence is retained historical unless current artifact says otherwise; read authority, raw payload artifact-audit deferred
P2: V5 action	train/env_karman.py _action_to_omega; env_illusion.py _action_to_omega; active V5, action (front,top,bottom), [-1,1], b=0, \omega=-(12a+b)U0/R, R=L0/2, EMA weight .1	Record command, applied omega, body ID/order and sign per trajectory; supported source contract
P2: Legacy action/SR convention	ROUND1_BOTTOM_UP/01_DRL_CONTROL_AND_CASES.md §§6–7; src/SR_analysis current Kármán authority; Legacy Kármán SR, native (front,upper,lower), \alpha=\omega/U0, Re_D=Re_code/2, distinct scale/bias and FlowField.run EMA	Legacy SR comparisons remain Legacy-only; formula/action artifacts and closed-loop trajectory are the comparator; active Kármán scope, read authority
P2: readback	CelerisLab/README.md §§API/telemetry; CELERISLAB_VALIDATION_DOSSIER.md §§3–4; CelerisLab current solver/API, set_body host action uploaded at next run; force [f_x,f_y], normalize=True per-step average, sensor area normalization always applied and time normalization separate	Record sampling interval and normalization; no force-tensor transpose; array/API orientation safeguard is stated once here; read authority, implementation not rerun
P3: V5 observations	train/env_karman.py module contract and _normalize_obs; env_illusion.py; active V5, Kármán 12-vector = six forces then six sensor components; Illusion 14-vector adds target C_D,C_L	Reward uses the corresponding target role; observation order is not field metric; supported source contract
P3: normalization	TRAIN_PIPELINE.md §§4–5; DESIGN_DECISIONS.md; active V5 native calibration-v2 scales plus observation-only VecNormalize; Legacy compatibility SENSOR_CC=78 path	Selected policy requires matching normalizer; inference freezes training=False; native V5 and Legacy scaling not comparable; supported contract, retained-policy compatibility artifact-audit deferred
P3: roles/reward	legacy_test/README.md §§standardized acquisition; TRAIN_PIPELINE.md §§3–5; DESIGN_DECISIONS.md; target, zero, controlled, constant; Kármán controlled-force mean versus zero, Illusion controlled-force sum versus one target; sensor similarity is reward-adjacent	Target has no policy reward; native DTW and normalized offline DTW retain separate formulas/windows; reward is not field error; supported role contract, exact selected artifacts artifact-audit deferred
P4: ROI	WAKE_L2_AND_SENSOR_PLACEMENT_RESEARCH_NOTES.md §§3–5; src/drl_pinball/eval/wake_l2.py, schema drl-pinball-wake-l2-v2; registered -6≤(x-x_s)/D≤14, `	(y-y0)/D
P4: periodic L2 hierarchy	Wake-L2 note §§5–6; wake_l2.py; periodic target/controlled/zero roles; E_mean is complete-cycle arithmetic mean-field error; E_phase8 is eight independently phased nearest snapshots; η=1-E_ctl/E_zero	L2 primary field matching; mean and phase windows distinct; phase8 not ensemble and DTW not L2; implemented where role schema passes, raw external fields artifact-audit deferred
P5: case-specific semantics	ROUND1_BOTTOM_UP/08_EXPERIMENT_AND_CASE_METRICS.md §§4–5; ROUND2_TOP_DOWN/05_REVISED_STRUCTURE_FREEZE.md §§2,5; wake-L2 note §§5–7; periodic, vortex event-offset, Illusion, Erase mean-field and steady late/profile contracts	No pooled efficacy/phase score; exact Vortex/Erase roles are needed only for future quantitative panels; current authority defines semantics, event/role payloads artifact-audit deferred
P5: pipeline terminology	.cursor/rules/jfm-round3-section-drafting.mdc line 11; relevant package stage/level documentation	Level-2/Level-3 and Stage-3 short/standard are pipeline labels; spatial L2 is field error; no “L2 gate” wording; current drafting rule
P6: CelerisLab qualification	docs/JFM_WYQ/CELERISLAB_VALIDATION_DOSSIER.md §§3,6–10; Kan99b K2 and Sah04 S2 manifest-backed full artifacts; current solver revision recorded by dossier	K2: Kan99b Re=U∞D/nu, partial pass due mean-lift sign; S2: Sah04 realised-Re Strouhal check; named windows and artifacts in manifest; qualification evidence, selected artifacts not rerun here
P6: qualification boundary	Same dossier §§5,10–12; CelerisLab/README.md FP16S/EsoPull limitations	Selected numerical observables only; no DRL/SR/CCD/mechanism validation; full matrix and hashes supplement; K2 sign issue remains a genuine blocker only for claims using affected lift convention

Figure, equation and table contracts

1. Plant/action/sensor/ROI schematic. Shows the two lanes, body order, V5 negative action sign, Legacy action distinction, probe plane and registered ROI. It does not establish optimal placement, observability, chain equivalence or a solver-exact mask.
2. Legacy/V5 contract table. Defines solver, geometry, body/action/Re convention, normalization and role names. It does not authorize pooled statistics or transfer of the V5 action map to Legacy SR.
3. Definitions block. Reuses chain-specific Re/action equations, observation/reward role definitions, E_mean, E_phase8 and η. It does not turn reward into field error or DTW into delay.
4. Compact CFD table. Gives the selected K2/S2 qualification status and essential configuration; full matrices and artifact identities belong in the supplement. It does not validate policy, SR, CCD or cloaking mechanism.

Claim ladder

Green. Legacy and V5 are separate executable chains; each later comparison must carry its plant, body/action/Re convention, calibration, role, comparator, metric and window. V5 action order/sign/smoothing, readback semantics, observation normalization, role definitions, wake-signature reward, and L2-primary/DTW-complementary hierarchy are executable contracts. K2 is a partial Kan99b qualification and S2 is a named-condition Sah04 solver anchor.

Amber. Sparse probes are physically motivated signature monitors, not optimal or fully observable. Reward/DTW can define wake-signature matching, while L2 independently tests registered field matching. Mean, phase, event and steady estimands may support different bounded comparisons under their own roles.

Red. Do not pool Legacy/V5 values or transfer V5 action signs/maps to Legacy SR; call DTW a physical delay, causal test or field equivalence; relabel event snapshots as phase; call steady late snapshots temporal means; use a validation Level/Stage as an “L2 gate”; claim solver qualification proves DRL/SR/CCD/cloaking mechanism; or call all Kan99b/Sah04 matrix cases completed.

Imports, exports, bridge and genuine blockers

Imports. Round-2 frozen terminology and hierarchy; Round-1 DRL/action/role and metric dossiers; current V5 environments, training/evaluation and data-dictionary authorities; Legacy acquisition/SR authority; wake-L2 implementation/rationale; and the CelerisLab validation dossier and benchmark specifications.

Audited exports — exact canonical wording for Modules 04–06.

• Legacy/V5: Legacy and V5 define separate executable evidence chains; never pool their numbers or imply numerical continuation/equivalence.
• Action: V5 uses body order (front, top, bottom) and \omega=-(12a+b)U0/R with zero bias and weight-0.1 smoothing. Legacy SR uses native (front, upper, lower), \alpha=\omega/U0 and Re_D=Re_code/2; the V5 map does not apply to Legacy SR.
• Observation/reward: Wake-signature matching uses forces plus six sparse downstream velocity observations. Force aggregation and target comparison are case-specific; calibration scales, Legacy SENSOR_CC=78 compatibility, and V5 observation-only VecNormalize are distinct layers.
• Evaluation: Field matching uses spatial L2 as primary evidence and DTW as complementary, signal-level and case-specific evidence. Periodic complete-cycle mean L2, eight-slot phase diagnostics, transient event-offset L2, Illusion/Erase mean-field comparisons and steady late/profile errors are distinct estimands.
• Qualification: CelerisLab qualification is compact and configuration-specific; Kan99b K2 is a partial pass because the mean-lift sign/convention remains unresolved, while qualification does not establish a control or mechanism claim.

Final bridge. With these definitions fixed, Module 04 can lead with independent Kármán field matching, while Modules 05–06 can interpret Legacy SR and field structure without silently changing plant, action sign, Reynolds convention, role or metric.

Genuine blockers. The Kan99b force/lift sign remains a blocker only for claims that use that affected lift comparison. Exact Vortex/Erase target-control-zero roles remain blockers only for proposed future quantitative panels. A selected-policy reproducibility claim is blocked if its exact model/normalizer/target identity is not bound; authority-led external fields, masks and hashes are artifact-audit deferred, not blockers.

Concise source coverage ledger

Status	Sources and reason	Evidence state / boundary
read	Round-3 revised rule, master and quality gate; Round-2 freeze/style guide; Round-1 DRL, coverage and metrics dossiers; current V5 environment/training/evaluation/data-dictionary authorities; Legacy acquisition/SR authorities; wake-L2 note/code; CelerisLab dossier, README and Kan99b/Sah04 specifications	Read in full for this revision; not independently rerun or universally artifact-audited
mapped	Broader package indexes and manifests referenced by the read authorities	Mapped only; not claimed read-full or artifact-audited
not-covered	Raw selected model/normalizer/target bundles, external reproduction payloads, solver-exact masks and unretained benchmark matrix cases	Authority-led artifact-audit deferred; no values inferred
external-inaccessible	External/symlink-backed field roots and source exports not exposed in the visible checkout	Authority-led deferral; no essential internal contract is established from inaccessible material

Anti-index / anti-AI audit

• Layer 1 now contains six concise near-prose paragraphs with short source tags; repeated template labels and inline evidence blocks have been removed.
• Layer 2 carries exact provenance, chain, geometry, role, Re, comparator, metric, ROI/window and status without making the narrative a path inventory.
• Contracts no longer narrate Kármán performance, SR, CCD or cross-case success; detailed outcomes are retained only where needed to define qualification boundaries.
• Pipeline Level/Stage terminology is separated from spatial L2, and no validation item is called an “L2 gate”.
• Authority-led artifact gaps are marked artifact-audit deferred; only affected lift-sign claims, exact future Vortex/Erase roles and selected-policy identity can block downstream claims.
• The action-sign/body-order warning is preserved; the force-array orientation safeguard appears once in the ledger rather than as a repeated tyx/txy theme.
• This is a revised candidate for second audit, not a readiness declaration.