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 a233c90324 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:

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.