# 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|≤5`, `D=20`; geometry guard because solver masks not persisted | Controlled and zero versus target on same case/role window; `U0`-normalised area-RMS; exact solver-mask audit deferred, not a blocker when authority binds ROI |
| 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.