CelerisLab/docs/validation/refined_dfg_window.md

# Opt-in observation-window ledger in the DFG runner

This test-only integration adds `--exchange-window` to `run_refined_dfg.py`. It uses the
existing production ledger; no collision, boundary, transfer, physical setup, reference,
periodicity gate or acceptance threshold changes. Default remains the historical
per-base-step observation path. Uniform stepping/force accumulation is unchanged.

For the refined case, each existing observation interval opens a new ledger at completed
base step `begin`, advances exactly the same `n` base intervals, and reads the integrated
root-lattice impulse for `[begin, begin+n]`. The contract requires root units, `window`
kind, `2*n` fine samples, matching endpoints, and fine dt=.5. The existing coefficient
calculation still divides this impulse by `n` and `.5*U_lattice**2*D_root`; force timestamps
remain `(begin+n/2)*U_lattice/D_root`. It does not divide an already averaged force again.
Pressure/macro/physical-leaf mass measurements and safety checks remain at the original
interval end. Pilot interval is 80 root steps; early full-run intervals remain 2000, and
any final shortened interval uses its actual `n`.

The opt-in uses one `step(n)` call and one window read per observation, rather than `n`
Python calls/readbacks. Internal subcycling and per-base synchronization remain owned by
the same backend. Cooperative deadline checks surround that complete interval; unlike
the default path they cannot interrupt between base steps inside `step(n)`. The existing
external hard watchdog is still required. The full-run cadence/cap is documented here,
but this preparation does not admit a full run or a GPU operation.

## Provenance and receipt separation

`source_manifest_window.json` pins the reviewed a233c9032487a6006e950d1e327079b00466c410
snapshot (production ledger origin d930) plus existing helper/reference files. Both SRT
and MRT are supported by this explicit opt-in source pin; collision selection remains
independent and shared by the two cases. Existing SRT and MRT manifests are untouched.
Default mode continues to reject the changed candidate under those historical pins;
use a matching historical `--source` checkout to run its default path. There is no
silent repinning, source fallback, or reuse of historical outputs as candidate evidence.

Plan, READY, summaries, timeout/comparison receipts now record `observation_mode` as
`last_base_step` or `window`, alongside collision and actual checkout provenance. On a
uniform receipt this labels its **paired campaign's refined observation mode**, not a
change to uniform observation. Full-mode pilot validation rejects missing or mismatched
mode labels in the plan, either case summary, and either READY receipt. Source/runner
hash, collision, completeness and health checks remain. Cross-mode pilot reuse is denied.

The earlier short A/W/W1 timing/capability evidence is not a full-run speedup or accuracy
claim. Mathematical impulse integration/units are unchanged; floating-point reduction
order can differ, so bitwise equality of force sums is not promised. Physics acceptance
continues to use the existing frozen gates. Historical failures/results are untouched.

CPU preparation commands, from the repository root:

```sh
python tests/unit/test_refined_dfg.py
PYTHONPATH=src python -m unittest tests.unit.test_raw_exchange_window tests.unit.test_time_window_dfg -v
python tests/validation/run_refined_dfg.py --collision MRT --exchange-window --mode plan --output /tmp/new-window-dfg-plan
```

Root must independently review and admit any execution. An admitted paired pilot uses
the existing watchdog, device selection, `--gpu-gates-approved`, positive
`--max-wall-seconds` and a new output directory, adding only `--exchange-window` to the
selected collision's pilot command. No GPU or remote action was performed for this patch.

## Public Jet diagnostic option

`--collision MRT --exchange-window --jet-scenario zero|fixed|reverse` selects
unshifted FP32, no LES, constant transfer on both existing public backends. Default
`none` and the historical manifests remain unchanged. `zero` registers both Jets at
zero amplitude and retains every existing DFG verdict, including pressure. `fixed`
uses outward radial parabolic sectors at pi/2 and 3pi/2, half-width pi/12, peaks
(+.001,-.001). Both use the existing D40/D80 geometry and U=.01. Sector origins are
(80.5,81) in root edge coordinates and (160,160.5) in uniform node coordinates;
radial extent is [0,1.005R]. `reverse` keeps those peaks through t*=300, updates both
public setters at that completed boundary, and continues to 305 with opposite signs.

Fixed diagnostic windows are 250–260, 260–270, 270–280, 280–290 and 290–300; reversal
adds 300–305. Histories retain exact interval endpoints and root/uniform lattice
impulses. The refined window uses total exchange; uniform uses public `read_force`
batch averages. Driven windows report mean/min/max/RMS Cd/Cl without applying DFG
reference or periodicity gates. Exit zero means healthy execution, not qualification;
`matched_case_pass` remains false. No independent CV or stress-load claim is made.

This opt-in records current source/helper hashes with the existing manifest format,
checkout revision/dirty state and runner hash. Pilot/full must match that snapshot
and the exact scenario. It does not relabel current source as historical evidence.
Use the existing bounded plan/pilot/full commands with the three option flags above;
full requires the matching completed t*=5 paired pilot. `step_seconds` includes force
readback; observation/overhead and total wall time are separate, not kernel throughput.

Add `--observe-cv` to record independent scalar control-volume samples from the
already downloaded public macros. The pilot exercises this path at t*=.02..5;
full records 501 endpoints at 290..300. Each `cv_history.jsonl` row contains actual
root time, preceding interval start/duration/impulse, and two inventories/outward
fluxes ordered [mass,Px,Py]. Exclude the first row's preceding impulse: that row
supplies the initial inventory. Uniform native impulse converts by .5² to root
units; refined ledger impulse is already in root units. Explicit native-aligned
contours differ by .25 root cells in x and are recorded in the plan. Cropping
retains the two-cell face-gradient stencils. No fields or per-link arrays are saved.
`cv_observation_seconds` is the CV portion of observation/overhead time. Helper hash
and the observation flag must match pilot/full. Time integration, temporal
coarsening and any physical assessment remain separate offline work.

## Bounded resolution and placement controls

Defaults remain `--case both --uniform-diameter 80 --placement wide`. Single-case
runs use `--case uniform` or `--case refined` and never report a matched-case pass.
Their own reference/periodicity or driven-diagnostic results remain available.
A single zero-Jet full run exits successfully only when its periodicity and the
unchanged complete DFG reference verdict pass; driven completion is not qualification.

The D160 option requires `--case uniform --uniform-diameter 160` and an explicit
public Jet scenario. U and Jet speeds stay .01 and ±.001; viscosity is .016,
grid 3521×658, center (320,320.5), radius80. CV uses root spacing/time factor .25,
origin (.375,.75), impulse factor .0625, root viscosity .004, and x-face shift .125.

`--case refined --placement compact` selects root bounds (48,48,128,128), fine
168×168 and origin (46,46), with the same D40/fineD80 body/Jet resolution. Its CV
contours are (52,52,112,112) and (50,50,120,120); complete face-gradient stencils
are clear of both solids and the transfer footprint. Compact is refined-only.
CV metadata gives each grid's spacing/origin/contours explicitly. Case, uniform
diameter and placement must match the newly completed pilot in every receipt.