FixedPatchStepper: level-indexed API, drop 15 fine/child compatibility views

- Hierarchy documents level/pair/shape/frame conventions; edge_frame(l)
  replaces the stepper's inline origin/spacing loop.
- Public per-level read-only state: layouts, boundaries, jets, leaf.
- set_jet_amplitude/read_raw_exchange/read_exchange_window: level= required.
- remap_child(child_objects=) -> remap_finest(objects=).
- _kernel_configs, _upload_boundary, _observed_boundary/_summarize split
  construction and observation duplication; behavior unchanged.
- fine_level_origin -> fine_level_offset (a (y, x) index, not an origin).
- docs: migration map in docs/development/src_coherence.md.

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

README.md

@@ -112,8 +112,9 @@ from CelerisLab.lbm.refinement_stepper import FixedPatchStepper
 cfg = LBMConfig(nx=32, ny=24, viscosity=.1)
 body = SimObject(0, geometry=CircleGeometry(16.0, 12.0, 2.15), center=(16.0, 12.0), radius=2.15,
                  surface_actuation=SurfaceActuation(0.7, 0.85, 0.002))  # angle, half-width, speed
-with CudaContext(0) as ctx, FixedPatchStepper(cfg, (8, 6, 24, 18), context=ctx,
-                                              fine_objects=[body], fine_block=(16, 20)) as run:
+with CudaContext(0) as ctx, FixedPatchStepper(cfg, context=ctx, refinements=[(8, 6, 24, 18)],
+                                              level_blocks=[None, (16, 20)],
+                                              level_objects=[(), (body,)]) as run:
     rest = np.asarray(compute_feq_d2q9(1.0, 0.0, 0.0), np.float32)[:, None, None]
     # (9, ny, nx) postcollision populations per level; non-leaf cells are discarded.
     run.initialize(np.broadcast_to(rest, (9, *run.patch.coarse_shape)),
@@ -123,7 +124,9 @@ with CudaContext(0) as ctx, FixedPatchStepper(cfg, (8, 6, 24, 18), context=ctx,
 ```
 
 Scope and limits:
-- D2Q9, SRT, FP32, double buffer, unshifted, no LES or forcing; fixed 2:1 patch(es), two levels (or one nested third).
+- The examples below use D2Q9, SRT, FP32, double buffer, unshifted, no LES or
+  forcing. Fixed 2:1 hierarchies use level lists of arbitrary depth; two- and
+  three-level examples below use that same constructor.
 - `coarse_boundary="periodic"` (default) or `"slot_reservoir"` (bottom slot, top
   reservoir; patch needs `y0 >= 4`, `y1 <= ny-4`). Periodic mode ignores the wall/slot config fields.
 - Object centers/radii use the coarse **cell-edge** frame (cell `I` spans `[I, I+1)`),
@@ -131,46 +134,51 @@ Scope and limits:
 - Bodies must be stationary circles whose whole boundary stencil lies in the fine
   active region, clear of the coarse/fine transfer cells; violations are rejected
   before any GPU allocation.
-- `fine_block=(by, bx)` stores the fine level in fixed-size blocks; `by`/`bx` must
+- `level_blocks=[None, (by, bx)]` stores the fine level in fixed-size blocks; `by`/`bx` must
   divide the WHOLE fine allocation, i.e. `2*(y1-y0)+8` by `2*(x1-x0)+8` including the
   four-cell ghost band. It gives results identical to dense storage and is
   infrastructure for future block AMR, not a speedup.
-- Several separated patches: pass a sequence of `(x0, y0, x1, y1)`
-  rectangles as `bounds`, at least 4 coarse cells apart, with both `fine_block`
-  and `base_block`. The fine level is then one level-wide grid `(2*ny, 2*nx)`:
+- Several regions: pass a sequence of `(x0, y0, x1, y1)` rectangles as
+  `refinements[0]`, with both levels blocked (`level_blocks`). Transfers are built once
+  from their union; adjacent, overlapping and concave unions are accepted when
+  their actual dependencies close. There is no fixed rectangle-gap rule.
+  The fine level is then one level-wide grid `(2*ny, 2*nx)`:
   `run.patch.fine_shape` gives it, `initialize`/`download` use it, and only the
-  patch windows (active region plus 4-cell ghost band, origin `(2*y0-4, 2*x0-4)`)
-  are stored; each window must align with `fine_block`. Order of rectangles does
-  not matter. `fine_objects`/`jets` work as for one patch: each circle (same
-  coarse cell-edge frame) must lie wholly inside one patch's active region with
+  grid-aligned tiles intersecting the union plus its four-cell ghost band are stored.
+  Block sizes must divide the level-wide grid; rectangle edges need not align
+  with tiles. Order of rectangles does not matter. L1 bodies/Jets (`level_objects[1]`/`level_jets[1]`) work
+  as for one patch: each circle (same coarse cell-edge frame) must lie wholly
+  inside the union's active region with
   its boundary stencil clear of transfer cells; a jet may not select links of two
-  different bodies, even across patches. No wall-touching patches or nesting yet.
+  different bodies, even across regions. Wall-touching patches remain unsupported.
+  For nesting, add further `refinements` entries as shown below.
 
   ```python
   cfg = LBMConfig(nx=32, ny=16, viscosity=.1)
   rest = np.asarray(compute_feq_d2q9(1.0, 0.0, 0.0), np.float32)[:, None, None]
   with CudaContext(0) as ctx, FixedPatchStepper(
-          cfg, ((4, 4, 12, 12), (16, 4, 24, 12)), context=ctx,
-          fine_block=(4, 4), base_block=(4, 4)) as run:
+          cfg, context=ctx, refinements=[((4, 4, 12, 12), (16, 4, 24, 12))],
+          level_blocks=[(4, 4), (4, 4)]) as run:
       run.initialize(np.broadcast_to(rest, (9, *run.patch.coarse_shape)),
                      np.broadcast_to(rest, (9, *run.patch.fine_shape)))  # (9, 32, 64)
       run.step(32)
       coarse_g, fine_g = run.download()  # coarse: NaN on every covered cell;
                                          # fine: NaN on every non-ACTIVE cell
   ```
-- Three levels (one nested chain): add `child=(x0, y0, x1, y1)` in
-  **L1 window cells** (the patch's fine grid including its 4-cell ghost band) and
-  `child_block`, with `fine_block` and `base_block`. L2 must sit inside L1's
-  ACTIVE cells, away from L1's ghost band and transfer footprint (checked before
-  any GPU allocation). `initialize` and `download` take/return three arrays; each
-  level is NaN on its non-ACTIVE (and child-covered) cells. One coarse step = 2 L1
-  steps = 4 L2 steps. One L1 patch only. Optional stationary circles and Jets
-  live on L2 via `child_objects` and `child_jets`; `fine_objects`/`jets` retain
-  their L1 meaning and must be empty in this mode. All object and Jet geometry
-  uses the **L0 edge frame**, not the child bounds' L1 window frame. L2 has
-  dx=dt=0.25, so prescribed lattice velocity is unchanged. Each whole body and
-  its BFL stencil must be inside L2 ACTIVE cells, outside the transfer footprint.
-  A Jet may select one physical body across multiple blocks, never two bodies.
+- Three-level nested windows: pass two scalar rectangles in `refinements` —
+  L1 in L0 cells, L2 in **L1 window cells** (the parent's fine grid including its
+  4-cell ghost band) — plus all three `level_blocks` entries. L2 must sit inside
+  L1's ACTIVE cells, away from L1's ghost band and transfer footprint (checked
+  before any GPU allocation). `initialize` and `download` take/return three
+  arrays; each level is NaN on its non-ACTIVE (and child-covered) cells. One
+  coarse step = 2 L1 steps = 4 L2 steps. One L1 window only in this scalar
+  chain. Optional stationary circles and Jets live on L2 via `level_objects[2]`
+  and `level_jets[2]`; L1 bodies/Jets retain their L1 meaning and must be empty
+  in this mode. All object and Jet geometry uses the **L0 edge frame**, not the
+  child bounds' L1 window frame. L2 has dx=dt=0.25, so prescribed lattice
+  velocity is unchanged. Each whole body and its BFL stencil must be inside L2
+  ACTIVE cells, outside the transfer footprint. A Jet may select one physical
+  body across multiple blocks, never two bodies.
 
   ```python
   from CelerisLab.body.geometry.circle import CircleGeometry
@@ -182,9 +190,9 @@ Scope and limits:
   jet = Jet(Tube((6.5, 8.), 0., 3., .3), Parallel(0.), amplitude=.002)
   rest = np.asarray(compute_feq_d2q9(1.0, 0.0, 0.0), np.float32)[:, None, None]
   with CudaContext(0) as ctx, FixedPatchStepper(
-          cfg, (4, 4, 12, 12), context=ctx, fine_block=(4, 4), base_block=(4, 4),
-          child=(8, 8, 16, 16), child_block=(4, 4),
-          child_objects=[body], child_jets=[jet]) as run:
+          cfg, context=ctx, refinements=[(4, 4, 12, 12), (8, 8, 16, 16)],
+          level_blocks=[(4, 4)] * 3, level_objects=[(), (), (body,)],
+          level_jets=[(), (), (jet,)]) as run:
       shapes = (run.patch.coarse_shape, run.patch.fine_shape, run.child_patch.fine_shape)
       run.initialize(*(np.broadcast_to(rest, (9, *s)) for s in shapes))  # 16², 24², 24²
       run.step(4)
@@ -192,14 +200,30 @@ Scope and limits:
       run.step(4)
       coarse_g, l1_g, l2_g = run.download()  # solids/covered/nonleaves are NaN
   ```
-- Not available: per-link surface exchange/force readout in blocked mode,
-  checkpoints, moving bodies, L1 bodies/Jets in a three-level chain,
-  several patches per level with nesting, dynamic refinement, `Simulation`
-  integration. Validation so far is storage/operator equivalence and short runs,
-  not accuracy, convergence or long-time stability. The new L2-body GPU gates
-  (layouts, masks, amplitude reversal, legacy equivalence) and independent
-  every-substep numerical replay remain required acceptance checks; CPU tests
-  alone do not establish GPU numerical correctness.
+- Level lists (the only constructor): `refinements[l]` describes level `l+1`
+  in allocated level-`l` integer cells; use a rectangle list for a union, or a
+  scalar rectangle for a single window (a scalar child requires a scalar
+  parent). `level_blocks`, `level_objects` and `level_jets` each have one entry
+  per level, including L0. Three or more levels require all-blocked storage and
+  bodies/Jets only on the finest level. Every adjacent pair must preserve
+  inherited ACTIVE coverage, valid donors/receivers, surviving pulls and the
+  upstream transfer footprint. Level `l` takes `2**l` steps per base interval.
+  This describes implemented topology and scheduling, not accuracy or
+  convergence qualification.
+- Blocked body levels can enable `observe_raw_exchange=True` and call
+  `read_raw_exchange(body_id, level=...)` after a completed base interval.
+  It reduces unique cut-link observations into wall/aperture/total force,
+  torque and mass exchange in base-lattice units per unit depth, for the last
+  base interval (default) or `window="last_substep"`.
+  `observe_window_exchange=True`, alongside `observe_raw_exchange=True`, enables
+  `start_exchange_window()` / `read_exchange_window(body_id, level=...)` across
+  completed base intervals. These are raw boundary-reaction diagnostics, not a general
+  stress or nozzle-load accuracy claim; dense body layouts are unsupported.
+- Not available: checkpoints, moving bodies, L1 bodies/Jets in a three-level
+  chain, automatic dynamic refinement, `Simulation` integration. Qualification
+  depends on the tested configuration; see [the validation scope](docs/validation/2d_scope.md).
+  CPU topology/schedule tests alone do not establish GPU numerical correctness,
+  general convergence or long-time stability.
 
 ## Installation
 
@@ -663,6 +687,17 @@ for step in range(steps):
 streak.render("streakline.png")
 ```
 
+## Validation campaigns
+
+- [Periodic Taylor–Green AMR](docs/validation/taylor_green.md): analytic periodic-decay pilot and frozen baseline-relative assessment.
+- [Matched refined DFG](docs/validation/refined_dfg.md): frozen SRT uniform/refined comparison, requiring channel GPU gates before execution.
+- [DFG 2D-2 Re100](docs/validation/dfg_re100.md): frozen periodicity and official-reference comparisons, with a declared noncanonical outlet.
+- [Uniform LES shear decay](docs/validation/uniform_les_flow.md): independent continuum-oracle flow diagnostic, baseline and isolated corrected source variants.
+- [Smagorinsky helper comparison](docs/validation/les_helpers.md): pinned baseline versus an output-local two-coefficient candidate, without production edits.
+- [Jet-circle control volume](docs/validation/jet_circle_cv.md): bounded AMR versus uniform-grid conservation diagnostic.
+
+The runners are in `tests/validation`, their CPU tests in `tests/unit`, and compact reference/source guards in `tests/validation/data`. Current Re100/Jet source guards explicitly pin the reviewed AMR-channel experiment; historical d79 evidence remains tied to its original checkpoint commits. New runs record actual Git HEAD separately from source origin. These campaigns preserve pinned production code; successful CPU checks alone do not establish GPU or physical validation. Keep generated results outside tracked files.
+
 ## Citation
 
 ```bibtex

docs/compatibility.md

@@ -0,0 +1,57 @@
+# Compatibility and API changes
+
+Changes that can make a previously accepted setup or call behave differently.
+Each entry names the commit, the affected entry points and the observable result.
+
+## Redundant periodic stepper alias removed
+
+`PeriodicPatchStepper` is no longer exported from `lbm.refinement_stepper`.
+Use `FixedPatchStepper` with the same arguments, including explicit
+`level_blocks`. The old name was an alias for that exact class; periodic
+boundaries remain the default. Existing imports of the old name must be updated.
+
+## 87c3a31: cut-link ownership is validated for every body
+
+`validate_cut_link_ownership` (`body/preprocess/flag_overlay.py`) now runs for
+passive bodies as well as Jet/aperture bodies. Every cut link must have an
+active fluid receiver (FLUID set, SOLID clear), and each `(receiver, direction)`
+population may have only one writer.
+
+Rejected with `ValueError`, before flags, populations or device buffers change:
+
+1. Overlapping or touching passive solids whose cut links write the same
+   population ("Boundary requires unique cut-link writers").
+2. A body whose cut-link receiver is a non-fluid cell, e.g. a channel wall row
+   or the inlet/outlet column ("Cut links must have active fluid receivers").
+
+Both were previously accepted silently for passive bodies; the interpolated
+boundary then had undefined results. The rules apply to the cut links of all
+bodies together, so a passive body overlapping a Jet body is rejected as well.
+The check runs in `Simulation.initialize`, runtime body sync (`sync_bodies`),
+checkpoint save and checkpoint load (`common/checkpoint.py`). Load validates
+before restoring anything, so a checkpoint whose saved geometry violates either
+rule no longer restores; rebuild the geometry with separated bodies.
+
+## 87c3a31: `Simulation.read_surface_exchange` accepts Jet-driven bodies
+
+`read_surface_exchange(id)` previously required `SurfaceActuation` on the body.
+It now also accepts bodies that own Jet aperture links, including Jets with zero
+or negative amplitude (the aperture test is geometric). Bodies with neither
+`SurfaceActuation` nor aperture links still raise
+`ValueError("Body has no surface actuation")`. The value is unchanged: the latest
+step's wall/aperture exchange, not total nozzle force.
+
+## 7afb5ad: `Simulation` fails closed after a Jet amplitude device-write failure
+
+`Simulation.set_jet_amplitude` previously only documented that a device error
+leaves the per-link velocity column undefined; the instance stayed usable.
+Now any error after input validation (internal stream creation or the upload)
+marks the Simulation failed. Every later device-touching public method,
+including the `stream` property (guard added in the follow-up repair commit on
+`claude/jet-update-consistency`), raises
+`RuntimeError("Simulation failed (...); close() and recreate it")`. The host
+amplitude keeps its previous value. `close()` still works and stays retryable;
+cached host readers and host staging calls are not blocked. Invalid input
+(`ValueError`/`IndexError`) is unchanged: it raises before any change and the
+instance stays usable. `FixedPatchStepper.set_jet_amplitude` already failed the
+instance (status `failed`) and is unchanged.

docs/development/les_dev8403956_integration.md

@@ -0,0 +1,62 @@
+# Selective LES normalization integration on dev8403956
+
+This change reuses the reviewed correction from 5465832 without merging its
+branch history. The only production change is the two closed-form coefficients
+18 -> 18 sqrt(2) and their explanatory comments in turbulence_smag.cuh. Its SHA256
+is a3db46c2e7d27530b2d1436e65cdbed0b72cc7e047bfbeef2a640877271b51aa.
+Defaults, iterative/deviatoric/capped closure, collision dispatch, AMR guards,
+and all other production source files are unchanged.
+
+## Separate source contract; unchanged experiment
+
+The single existing flow runner now accepts `--experiment dev8403956`.
+Its separate source_pins_dev8403956.json pins all 101 production files from the
+committed 8403956 baseline; corrected mode permits only the exact reviewed
+header substitution. Results record the actual checkout commit, import path,
+experiment name and manifest SHA256. No arbitrary manifest-path override exists.
+
+Omitting the option still selects the original historical source manifest.
+That manifest, the original paired receipts, scalar preparation manifests and
+independent continuum oracle are unchanged. Historical baseline and corrected
+receipts remain evidence for their own exact sources, not new dev receipts.
+Historical guards intentionally reject this different dev source tree. Eight
+production files already differed between the historical source snapshot and
+8403956; neither the old manifest nor its acceptance is silently regenerated.
+
+The physical experiment and every numerical acceptance threshold are unchanged:
+8 x 34 nodes, halfway y walls, periodic x, unforced D2Q9/SRT, shifted FP32,
+double-buffer streaming, Cs=0/.16/1, checkpoints 519/1038/2075. Each case has one
+actual advancing warm-up followed by complete initial-state restoration before
+READY. Total launches are 6,225 measured plus three warm-ups. Cs=1 remains an
+amplified diagnostic, not a physical coefficient recommendation.
+
+## Host checks
+
+    PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests/unit -p 'test_smagorinsky_normalization.py' -v
+    PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests/unit -p 'test_les_flow_*.py' -v
+
+The direct-current-header test is copied unchanged from reviewed 5465832:
+120 tensor parameter cases, Cs=0/equilibrium and omega guards, converged
+trace-free iterative comparison, and mutation detection in both lattice
+algebras. This is scalar D2/D3 algebra coverage, not 3D-flow qualification.
+Flow tests retain analytic/reference checks and add current named-source,
+reverse-patched baseline, variant rejection, unrelated-source tampering and
+immutable historical-default checks. The temporary baseline is constructed
+only inside a test directory; production is never reverse-patched.
+
+## Pending final-commit GPU gate
+
+After independent review and explicit executor authorization, run from the
+exact committed candidate checkout, selecting the authorized physical GPU:
+
+    CUDA_VISIBLE_DEVICES=<physical-GPU> PYTHONDONTWRITEBYTECODE=1 python tests/validation/run_uniform_les_flow.py --root "$PWD" --experiment dev8403956 --variant corrected --run-gpu --device 0 --output <new-evidence-directory>/corrected.json
+
+Retain all source hashes, exact commit/import/device identity, manifest hash,
+three READY/reset records, complete result JSON, stdout/stderr and actual exit.
+Require all frozen gates, DONE passed=true and exit 0. Compare with historical
+corrected evidence without relabeling it as current evidence. The old-vs-new
+normalization discrimination already exists; no new baseline GPU run is needed
+unless review finds a changed exercised uniform solver path.
+
+No GPU result is claimed by this integration preparation. This does not expand
+LES qualification to MRT, forcing, AMR LES or three-dimensional turbulent flows.

docs/development/projected_pair_explosion.md

@@ -0,0 +1,57 @@
+# Experimental projected G explosion
+
+`FixedPatchStepper(..., explosion="projected_linear")` changes only the existing
+G-to-G explosion reconstruction. The omitted/default `"constant"` selector retains
+the same kernel, launch arguments and device allocations. Projected mode adds two
+compact tables per adjacent pair; recursion, collision, BFL, restriction, buffer
+ownership and synchronized publication are unchanged. `remap_finest` preserves it.
+
+Runtime eligibility is periodic-root, fully blocked D2Q9/SRT/FP32, body/Jet-free,
+without LES; the fixed-patch backend has no forcing interface. Shifted and unshifted
+storage use the same reconstruction. One generic builder handles scalar windows,
+unique union rows and all adjacent hierarchy pairs without depth/rectangle caps.
+Donors are original explosion donors intersected with owned, uncovered ACTIVE
+cells. An axis uses centered differences only if both neighbors are legal;
+otherwise both addresses repeat the center. Nested layout periodicity is explicit.
+No covered cells, holes, inactive cells or stale halo copies enter the stencil.
+
+The 33-line kernel is unchanged from our `519473a` experiment and retains its
+mathematical attribution. Host tests cover union decomposition, concavity, narrow
+gaps, grazing packet paths, offsets, sparse/nested owner addresses, three/four-level
+source timing, unchanged constant dispatch, remapping and shifted/unshifted actual
+kernel arithmetic compiled as host C++. These are not CUDA or flow validation.
+
+## Reviewed bounded evidence
+
+The `1aa8110` CUDA gate, with production exactly `a135252`, passed exact-dev
+omitted/default and explicit-constant equivalence, per-population reconstruction,
+scalar/union/four-level scheduling, alternate layouts, and changed remapping in
+both storage modes. Operator maximum error was 2.98023224e-8; the eight-step
+concave replay maximum was 1.58037614e-7. Whole-step mass/momentum remain
+finite diagnostics, not an FP32 conservation certificate. Reviewed evidence:
+`7aa66ff0542175092753ea099f40b903ece0527e`.
+
+The fresh four-case `2cf9853` N128/256 Taylor–Green repeat retained all `11901a7`
+settings and gates. All 20 main scalar rows and 260 early-pressure samples matched
+the older receipts exactly; this is not field-array equality. Projected worst
+velocity was 0.001995299260844 versus 0.002 (only 0.235% margin), pressure
+0.012157174904932 and energy 0.001184362645162. Constant velocity
+0.004418076615223 failed its gate, so the aggregate verdict remains false.
+The projected early sampled pressure peak was 0.021621453573334; it remains a
+descriptive sampled maximum. Reviewed evidence: `90849a55cad4a0da9b72747da7bfe6eb75962a44`.
+
+The old N64 projected failures remain relevant. These results support only this
+bounded plumbing gate and short periodic Re100 smooth-decay experiment. They do
+not establish union/multilevel physics accuracy, convergence, long-time stability,
+body/Jet, boundary, forcing, MRT or LES suitability. Constant remains the default.
+
+## Separate LES source profile
+
+The two older LES source manifests and the historical default are unchanged and
+correctly reject this different source tree. The existing LES runner now offers
+`--experiment a135252`, pinning all 101 actual committed corrected source files.
+Its explicit baseline-header override describes only a synthetic isolated reverse
+control, never the committed a135252 header. The unchanged corrected-only uniform
+LES regression (Cs=0/.16/1) is the remaining integration gate; no LES result is
+inherited from the projected evidence. The separate historical jet-CV `channel.py`
+pin mismatch predates this port and is not addressed here.

docs/development/raw_exchange.md

@@ -0,0 +1,73 @@
+# Raw multilevel boundary exchange (opt-in candidate)
+
+Use `FixedPatchStepper(..., observe_raw_exchange=True)` and, after a successful
+base step, `read_raw_exchange(body_id, level=l, window="last_base_step")`.
+The alternative window is `"last_substep"`. Body IDs are object positions within
+the named level, not the object's original user label. The torque reference is
+that circle's geometry.center (the center used to construct BFL arms), reported
+in the root edge frame. A differing SimObject.center does not change this reference. Current geometry
+restrictions are unchanged: fixed complete bodies on the finest level, isolated
+from the transfer footprint. New observation currently requires blocked body
+storage; dense-body configurations raise before device allocation. Existing
+dense diagnostics are unchanged.
+
+Each result contains `wall`, `aperture`, `total`, with `force`, `torque`,
+`impulse`, `angular_impulse`, `mass_into_fluid`, and `mass_rate`. These are raw
+boundary momentum reaction, not validated stress or whole-nozzle mechanical
+load. No GI/advective correction or guessed thrust is added. Apertures retain
+their geometric classification when their prescribed velocity is zero.
+
+All results are base-lattice units per unit out-of-plane depth. For local
+spacing and timestep h=dt, raw `(jx,jy,tz,dm)` converts to impulse
+`(h*dt*jx,h*dt*jy,h*h*dt*tz)` and mass `h*h*dm`.
+The accumulator intentionally accepts h and dt separately to make the spatial
+and temporal conversion explicit; the current acoustic hierarchy supplies dt=h.
+The stored rx/ry arms run from geometry.center to the actual wall hit, not to
+the fluid node. For this raw exchange j=c_i(a+b), moving the arm from the fluid
+node to the hit adds q*c_i, whose cross product with j is zero. Thus either arm
+gives the same raw torque (up to floating-point rounding); this equivalence
+must not be assumed for a future nonparallel stress/advective correction.
+
+Force/torque are impulse/angular impulse divided by the reported window length.
+`dm=b-a` is positive into the exterior fluid, while j is the opposite of the
+fluid's momentum change across that cut link. Interpolated BFL can introduce
+mass drift; dm is an observation, not an assertion of impermeability.
+
+`last_base_step` means [t-1,t] even after step(n); `last_substep` means [t-h,t]
+and is not a common instantaneous sample across levels. A Jet amplitude set
+before step(1) applies to all its substeps. Reads are repeatable; step(0) leaves
+them unchanged. Initialization and a remap candidate invalidate observation.
+Only successful stream synchronization publishes a window; failed instances
+reject reads rather than returning partially advanced measurements.
+
+Storage is one FP32 [N,4] raw array and one FP64 [N,4] integral per measured
+level, plus row metadata. No substep history is stored. Same-stream sequencing
+is halo/restriction -> BFL -> independent row accumulation -> step. There are
+no accumulation atomics or body obs offsets (blocked n_objects remains zero).
+Disabled observation allocates neither observation buffer and launches no
+accumulation kernel. The standalone periodic block caller passes explicit
+null optional arguments.
+
+## Gates
+
+CPU (standard library unittest, plus existing NumPy dependency):
+
+    PYTHONPATH=src python -m unittest discover -s tests/unit -p test_raw_exchange.py -v
+
+GPU, explicitly on a CUDA host with the existing environment:
+
+    PYTHONPATH=src python -m unittest discover -s tests/validation/multigrid -p test_raw_exchange_gpu.py -v
+
+The GPU suite includes an independent actual-population cut-link census and
+ACTIVE-fluid momentum/mass ledger with non-body boundary flux, observation
+on/off population equivalence, dense/blocked row comparison, three block
+partitions, zero/step/reversed/disabled Jet amplitudes, depth-four eight-sample
+accumulation, and a short-time whole-domain uniform-fine comparison with the
+same physical geometry, viscosity and Jet velocity. The uniform reference
+uses a test-only adapter to the standalone kernel's optional inputs.
+
+These are implementation checks. They do not establish physical Jet/stress
+accuracy, long-time AMR error, or convergence order. Resolution/long-time
+studies and independently validated continuum load benchmarks remain separate.
+GPU gates were prepared but not run in the authoring environment (no CUDA,
+PyCUDA or nvcc); run them before merging this candidate.

docs/development/refinement_mrt.md

@@ -0,0 +1,34 @@
+# MRT reuse in blocked/refined stepping (candidate)
+
+Base `9805383`. Opt-in by `LBMConfig(collision="MRT")`; SRT remains the default and its
+kernel statements, including the shifted retained-delta/direct-momentum path, are unchanged
+under the alternate compile branch.
+
+## What changes
+- `blocks.cu` (`BlockStep`), `step/block_channel.cu` (`BlockChannelStep`) and `refinement.cu`
+  (`patch_collide`) gain a compile-time `COLLISION_MODEL == 2` branch that repeats the uniform
+  `collide_dispatch` sequence with zero forcing: `compute_rho_u`, omega clamp to
+  `[OMEGA_COLLISION_MIN, OMEGA_COLLISION_MAX]`, `collide_mrt_no_force`.
+- Kernel and host guards accept SRT or MRT only. TRT, LES, non-FP32 storage, non-double-buffer
+  streaming, and shifted dense/mixed refinement remain rejected.
+- Transfers, subcycling, BFL, raw exchange ledgers and channel closures are untouched. The
+  existing pressure-NEQ outlet selects its MRT branch (unknowns-only NEQ extrapolation) from
+  `COLLISION_MODEL`, so MRT channel parity must use uniform MRT as reference.
+
+## Contracts (existing operator, not redefined here)
+- Shifted storage uses the existing MRT representation (equilibrium moments from `rho - 1`),
+  not the SRT retained-delta/direct-momentum precision. Mass and momentum are conserved
+  moments (relaxation rate 0).
+- Kinetic rates are the operator's fixed `s_e = s_eps = s_q = 1.2` on every level; the shear
+  rate is the existing per-level omega. Under acoustic 2:1 scaling the physical bulk viscosity
+  therefore halves on each finer level. No rate rescaling is applied.
+- No LES, no external forcing (`d_params` force fields stay zero).
+- Shifted Jets stay SRT-only: `body/jets.py` keeps its existing guard. This extension does not
+  provide shifted MRT Jets.
+- `PeriodicBlockStepper` (uniform blocked stepper) remained SRT-only; it was removed in 8e1feff and its single-level capability, still SRT-only, is `FixedPatchStepper(refinements=[])`.
+
+## Evidence status
+CPU: `tests/unit/test_refinement_mrt.py` (host guards, source contract). GPU:
+`tests/validation/multigrid/test_refinement_mrt_gpu.py` (uniform-MRT channel parity, AMR MRT
+smoke) and unchanged SRT GPU tests. Strict parity may be subject to cross-kernel FMA
+contraction differences already documented for SRT. Not a DFG/benchmark validation.

docs/development/root_channel_candidate.md

@@ -0,0 +1,22 @@
+# Blocked AMR root channel increment
+
+Opt in with `FixedPatchStepper(..., coarse_boundary="channel", refinements=[bounds], level_blocks=[(by,bx), (fy,fx)])`. Every level must be blocked. The supported boundary is the existing uniform D2Q9/SRT/FP32 double-buffer channel: local Zou-He west inlet, pressure-NEQ east outlet, stationary halfway bounce-back y walls. Uniform and parabolic inlet profiles and shifted/unshifted storage are supported; the existing configuration guards still reject MRT/LES and incompatible storage. This does not change the external DFG MRT reference.
+
+`step/block_channel.cu` is a small root-only kernel. Fine kernels, transfer kernels and recursive hop scheduling are unchanged. Global coordinates and the global profile height/velocity are separate from block-local storage strides. Corner ownership and collision phases match `OneStep`:
+
+- y-edge ghosts (including corners): pull, pair swap, no collision
+- west ghosts at interior y: Zou-He reconstruction then SRT collision
+- east ghosts at interior y: pressure NEQ from the immutable left input node, no collision
+- physical fluid beside y walls: same-node opposite-input correction then collision
+
+The root uses the uniform SRT equilibrium arithmetic, including the existing shifted rho-minus-one path, to preserve matched-root semantics. Fine `BlockStep` retains its existing shifted direct-momentum/retained-density arithmetic. This increment is not a migration of fine arithmetic.
+
+Root halo topology stays wrapped like the uniform kernel, solely to reproduce its complete evolved ghost state as well as physical populations. It does not make the physical inlet/outlet periodic. Evolved root state includes boundary ghosts, while public fluid-leaf downloads exclude them. Initialization must provide finite positive-density root ghost states. Private raw snapshots preserve them exactly for same-representation continuation; public leaf-only downloads are not restart states. Channel remapping remains explicitly unsupported.
+
+`channel.py` checks the actual explosion donors and restriction receivers are uncovered bulk fluid and checks actual receiver-local restriction slots against pressure-donor and wall-correction reads. No arbitrary large padding or block-aligned patch restrictions are added. Keep the physical domain dimensions exact: choose legal root block divisors (including full width) instead of padding a benchmark domain. Stationary circles/Jets retain the existing finest-level and transfer-footprint rules.
+
+## Gates
+
+- `tests/unit/test_channel_root.py`: host semantics, minimal footprint, overlap rejection, raw-state/public-leaf separation; actual production uniform and blocked kernels under a CPU launch shim, five non-equilibrium steps, all corners, profiles, representations, y seams and a one-cell-wide block outlet donor.
+- `tests/validation/multigrid/test_channel_root_gpu.py`: exact uniform-versus-blocked full-state GPU parity; AMR finite-state and block-split invariance with/without a stationary circle and velocity Jet; amplitude update and raw snapshot round-trip.
+- GPU tests require explicit device admission by the caller. CPU-header algebra is not CUDA execution or external physical validation. The current increment does not establish DFG drag/lift/pressure acceptance or a performance speedup; those need matched SRT controls and a separate benchmark run.

docs/development/src_coherence.md

@@ -0,0 +1,62 @@
+# src coherence stage (from main 914906e)
+
+Owner direction 2026-10-28: unified style over historical compatibility, inside `src`.
+No numerical change is intended; kernel text was moved verbatim (PTX/bit parity is
+pending a GPU run).
+
+## Conventions (defined once, in `lbm.hierarchy.Hierarchy`)
+
+- Level `l = 0 .. depth-1` (0 = root). Pair `hierarchy.pairs[l-1]` builds level `l`.
+- Array shapes are `(ny, nx)`; rectangles, origins and centers are `(x, y)`.
+- FixedPatchStepper bodies/Jets use the root EDGE frame (root cell `i` = `[i, i+1)`);
+  uniform `Simulation` objects use the integer-NODE frame. Nothing converts between them.
+- `Hierarchy.edge_frame(l)` -> `((ox, oy), h)`: cell `(i, j)` of level `l`'s allocated
+  array (ghost band and holes included) covers `[o + h*i, o + h*(i+1))`. A scalar
+  FixedPatch2D window carries the half-coarse-cell ghost shift `bounds - HALO/2` in
+  `fine_origin`; a set's level-wide grid has origin 0. Level 1 boundaries are built from
+  the root config (the wall-aware fields live there); deeper ones from the parent frame.
+- `FixedPatch2D.fine_level_offset` (was `fine_level_origin`) is an array INDEX offset
+  `(y, x)`, not an `(x, y)` origin.
+
+## FixedPatchStepper migration map
+
+| removed / changed | replacement |
+|---|---|
+| `patch`, `child_patch` | `hierarchy.pairs[0]`, `hierarchy.pairs[1]` |
+| `base_layout`, `fine_layout`, `child_layout` (stepper properties) | `layouts[0]`, `layouts[1]`, `layouts[2]` (`FixedPatchSet2D.fine_layout(block)` is unchanged) |
+| `fine_boundary`, `child_boundary` | `boundaries[1]`, `boundaries[2]` (host geometry; `None` = no bodies/Jets) |
+| `_jets` | `jets[1]` |
+| `_boundaries[l]` (dict from L1, level keys) | `_level_boundaries[l]` (list from L0, `None` at L0 unless single-level static circles) |
+| `_fine_tables`, `_actuated`, `_jet_cache` | `_level_boundaries[1].tables` / `.actuated` / `.jet_cache` |
+| `_fine_leaf`, `_child_leaf` | `leaf[1]`, `leaf[2]` (copies) |
+| `_middle_kind` | `hierarchy.kinds[1]` |
+| `_boundary_hosts` (private) | `_boundaries` (private list behind `boundaries`) |
+| `remap_child(rects, child_objects=...)` | `remap_finest(rects, objects=...)` |
+| `set_jet_amplitude(i, a)` (implicit level 1) | `set_jet_amplitude(i, a, level=l)` (required) |
+| `read_raw_exchange(b)` / `read_exchange_window(b)` (implicit level 1) | `read_raw_exchange(b, level=l)` / `read_exchange_window(b, level=l)` (required) |
+| `_level_name(l)` "base/fine/child" messages | `"level l"` |
+| `refinement.MIN_PATCH_GAP` | deleted (no gap policy exists) |
+| `params.cuh HaloPlan`, `collide_trt_no_force` | deleted (zero references) |
+
+Kept: `step_count`, constructor keywords (`refinements`, `level_blocks`, `level_objects`,
+`level_jets`, `coarse_boundary`, `explosion`), `Simulation.set_jet_amplitude(i, a)` (one level),
+`RemapTopology.from_config(..., child_objects=, child_jets=)` (internal remap helper; "child" =
+the replaced level relative to its parent).
+
+## Responsibilities
+
+- Construction: `_check_levels` (inputs), `_kernel_configs` (per-level kernel configs),
+  `Hierarchy.edge_frame` (geometry frames), `_build_level` / `_build_pair` / `_upload_boundary`
+  (device). Observation reads share `_observed_boundary` + `_summarize`.
+- Blocked kernels: `operators/block_collision.cuh block_collide` is the one collision extension
+  point of `BlockStep` and `BlockChannelStep`. MRT shares one path; SRT keeps its two explicit
+  arithmetic variants (level: unclamped, no-force, shifted direct-momentum feq; channel: uniform
+  OneStep arithmetic with omega clamp), selected by `BLOCK_ROOT_BC`.
+- `explosion="projected_linear"` stays an optional capability; `"constant"` stays default.
+
+## Not done / open
+
+- No single-`Simulation` facade over FixedPatchStepper: the two own different state models
+  (uniform node frame, body sync, forcing, checkpoint vs. immutable blocked hierarchy, edge
+  frame, remap-as-new-instance). A facade would only forward calls; no concrete need found.
+- Tests, examples and validation callers are migrated separately (pinned runners stay frozen).

docs/evidence_index.md

@@ -0,0 +1,393 @@
+# Evidence index (draft, R0)
+
+Active-tree evidence at candidate 0f8fdbc30ea640c764b38ee598d8f4d135c81c85, classified for the release cleanup
+(thread C0C78UFKGRM 1793021833.593279). Draft for review: nothing is removed by this file.
+Recovery of any listed file: `git show 0f8fdbc3:<path>` (blob id given; an immutable tag is requested as anchor).
+
+Classes: K = conclusion kept in the active tree; K-code = tested research code kept; D-snapshot = pre-Gitea
+patch/diff transport (code landed in git from ed1a6ee on; not yet verified hunk by hunk); P-pin = generated hash inventories, git-status dumps and manifests;
+R-raw = run outputs, logs, signals, frames, one-shot run scripts and handoff notes. D, P, R leave the active tree in R1.
+No file under src/ or a test reads any of these paths (git grep at 0f8fdbc3); runners under tests/validation
+that read research/j* are handled in R2.
+
+| Class | Files | Bytes |
+|---|---:|---:|
+| K | 31 | 196,506 |
+| K-code | 3 | 24,324 |
+| D-snapshot | 18 | 338,948 |
+| P-pin | 50 | 979,177 |
+| R-raw | 142 | 3,790,554 |
+
+## (root)
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| BASELINE_JET_AMR.txt | R-raw | 5,244 | 62aa2a66dc05 |
+
+## output
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| round3_compatibility_summary.md | R-raw | 4,366 | f243318f5591 |
+
+## research/fine_surface_20261014
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 54,507 | 71a4543ead37 |
+| cpu_device_guard_cmd.txt | R-raw | 241 | 06e0f35d92b3 |
+| cpu_device_guard_exit.txt | R-raw | 2 | 573541ac9702 |
+| cpu_device_guard_stdout.txt | R-raw | 98 | 424d584a031c |
+| cpu_existing_runs.json | R-raw | 650 | 3179536407b7 |
+| cpu_final_run.json | R-raw | 386 | 523fadb3fec9 |
+| cpu_final_stdout.txt | R-raw | 99 | 9cfe73da3858 |
+| cpu_lifecycle_run.json | R-raw | 387 | 5b403b9e2f30 |
+| cpu_lifecycle_stdout.txt | R-raw | 112 | 3c5c49b285fa |
+| cpu_maps_stdout.txt | R-raw | 95 | 71dd87f9faf9 |
+| cpu_preallocation_run.json | R-raw | 337 | fa6e96d98cdd |
+| cpu_preallocation_stdout.txt | R-raw | 98 | 5d643576f251 |
+| cpu_shared_kernel_stdout.txt | R-raw | 98 | 8a0c046bb9b1 |
+| cpu_surface_command.txt | R-raw | 113 | 2a5ff31e8d06 |
+| cpu_surface_exit.txt | R-raw | 2 | 573541ac9702 |
+| cpu_surface_projection_command.txt | R-raw | 171 | 70b7f5c62c1a |
+| cpu_surface_projection_exit.txt | R-raw | 2 | 573541ac9702 |
+| cpu_surface_projection_stdout.txt | R-raw | 113 | efd37a149cc1 |
+| cpu_surface_stdout.txt | R-raw | 99 | 9cfe73da3858 |
+| gpu_preparation_run1.py | R-raw | 14,043 | ee586d035b7a |
+| gpu_run.json | R-raw | 2,943 | 15b8ba70d528 |
+| gpu_stdout.txt | R-raw | 5,424 | c5216e0267f3 |
+| gpu_test_run1.py | R-raw | 15,479 | f30376abc97f |
+| incremental.diff | D-snapshot | 53,853 | 318d92e7d177 |
+| manifest.json | P-pin | 8,411 | 8281338416af |
+| report.txt | K | 8,373 | 6b9e5123e414 |
+
+## research/fine_surface_joint_20261014
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline_00.json | P-pin | 21,302 | 4ae101ebd02b |
+| baseline_01.json | P-pin | 26,191 | 548cf7b3b494 |
+| baseline_02.json | P-pin | 22,440 | e0421e7a4052 |
+| baseline_03.json | P-pin | 8,584 | da99b45f32a4 |
+| blow_boundary.csv | R-raw | 12,536 | e13363b69457 |
+| blow_collisions.csv | R-raw | 19,145 | 5d5b395486bb |
+| blow_ledger.csv | R-raw | 15,977 | b43bbfd0b8d2 |
+| blow_propagation.csv | R-raw | 9,714 | f06d80d296ca |
+| blow_signals.npz | R-raw | 221,114 | 528adf75baa2 |
+| blow_summary.json | R-raw | 4,113 | 32285ac15be3 |
+| command.txt | R-raw | 232 | 510ecb2925dd |
+| criteria.txt | K | 7,480 | dd36e76a3be1 |
+| frozen.json | R-raw | 11,972 | b5a3324e8686 |
+| gpu_run.json | R-raw | 1,955 | 67ac4785f7e4 |
+| incremental.diff | D-snapshot | 625 | e03c132d22df |
+| integrity.json | P-pin | 826 | a8b6e4be88d2 |
+| manifest.json | P-pin | 4,388 | d2af50260c39 |
+| regions.json | R-raw | 27,525 | 7bba26904221 |
+| report.txt | K | 8,207 | d7571e068ad3 |
+| result.json | R-raw | 11,442 | 9580c2686e70 |
+| review.txt | K | 2,117 | bbe1d8a83d47 |
+| runner.py | R-raw | 5,847 | 812973acc000 |
+| stdout.txt | R-raw | 19,940 | c9218e2e48fc |
+| suction_boundary.csv | R-raw | 12,505 | b870be05e6c0 |
+| suction_collisions.csv | R-raw | 19,173 | 2de48c0a84ab |
+| suction_ledger.csv | R-raw | 16,208 | 92cf1f44911e |
+| suction_propagation.csv | R-raw | 9,720 | f017bcc3ca6f |
+| suction_signals.npz | R-raw | 220,058 | 66d06cf2d909 |
+| suction_summary.json | R-raw | 4,126 | d70a1d371950 |
+| validate.py | R-raw | 19,576 | 37441febd168 |
+| zero_boundary.csv | R-raw | 11,491 | 65c92e48c974 |
+| zero_collisions.csv | R-raw | 18,915 | 027cb8ff6b23 |
+| zero_ledger.csv | R-raw | 16,051 | 34a99bb89dd7 |
+| zero_signals.npz | R-raw | 127,958 | a966f093a9cd |
+| zero_summary.json | R-raw | 1,508 | 6e033f991438 |
+
+## research/fixed_patch_jet_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 69,721 | 91ad9c4d1e88 |
+| before.json | R-raw | 690 | 06e1b6278a29 |
+| fixed_patch_jet.py | R-raw | 9,646 | 6fbdcd9a076b |
+| incremental.patch | D-snapshot | 9,891 | b43129d82c69 |
+| manifest.json | P-pin | 1,967 | 08daa0248f60 |
+| notes.txt | K | 2,214 | 50070fe54efb |
+| results.json | R-raw | 1,100 | d959a6a1cc2c |
+| stdout.txt | R-raw | 1,272 | eccdc0f6b16a |
+
+## research/fixed_patch_jet_closure_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 72,692 | 8a157af82ecf |
+| cpu_results.json | R-raw | 628 | 8e4a1c090c93 |
+| cpu_stdout.txt | R-raw | 590 | d800b783fe47 |
+| incremental.patch | D-snapshot | 3,490 | a9a486c68afd |
+| layout_uncropped.png | R-raw | 51,785 | 0cf1cfa5e99d |
+| manifest.json | P-pin | 1,849 | 31cf0c739241 |
+| notes.txt | K | 3,023 | 0f7e7bdfd0e6 |
+
+## research/fixed_patch_jet_records_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 71,228 | a8e967f76e08 |
+| before.json | R-raw | 690 | ebd6f4251fc2 |
+| fixed_patch_jet.py | R-raw | 10,650 | f6b299885da0 |
+| incremental.patch | D-snapshot | 5,539 | c7f4d0c02ccc |
+| manifest.json | P-pin | 2,057 | 1d616c2541df |
+| notes.txt | K | 2,449 | b58cec14d359 |
+| results.json | R-raw | 1,136 | 788af64a6ebd |
+| stdout.txt | R-raw | 20,750 | a765b06deefa |
+
+## research/j1-2026-10-12
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| REVIEW.md | K | 7,667 | 8f469daef054 |
+| baseline-status.txt | P-pin | 2,601 | 64ca05ab952e |
+| baseline.json | P-pin | 23,052 | ab5852bcb0ef |
+| incremental.diff | D-snapshot | 29,912 | dd9c4e688888 |
+| results.json | R-raw | 68,294 | 56547aa8a678 |
+
+## research/j2-slot-2026-10-12
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| REVIEW.md | K | 12,930 | 69fa4d3bccd3 |
+| baseline-status.txt | P-pin | 2,825 | e711afb0016c |
+| baseline.json | P-pin | 24,660 | 286e023da94f |
+| incremental.diff | D-snapshot | 25,231 | 649f3b5d168d |
+| results.json | R-raw | 477,249 | b4272e25179d |
+
+## research/j3-coverage-2026-10-12
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| REVIEW.md | K | 11,409 | 5887cf73dce2 |
+| baseline-status.txt | P-pin | 3,055 | 78e88356caa3 |
+| baseline.json | P-pin | 30,407 | 095972547a7f |
+| incremental.diff | D-snapshot | 20,114 | f0d502dc5c5b |
+| negative-budget-20744.h5 | R-raw | 88,017 | 693b133be84d |
+| negative-end-20760.h5 | R-raw | 88,174 | 429270d263d4 |
+| restart-21280.h5 | R-raw | 88,062 | 74900affae38 |
+| restart-reference-21296.h5 | R-raw | 88,154 | 7510ee97885b |
+| results.json | R-raw | 296,314 | 7806b10e65cb |
+| verification.json | K | 1,468 | 78a07c47aea4 |
+
+## research/j3-lag-2026-10-12
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| REVIEW.md | K | 11,732 | 34fe5dbb2cae |
+| baseline-status.txt | P-pin | 2,968 | 6ae6094ea9d7 |
+| baseline.json | P-pin | 26,505 | 5c289d14ff30 |
+| end-21280.h5 | R-raw | 92,366 | f30b209179ab |
+| incremental.diff | D-snapshot | 15,790 | 5c6c485e1f75 |
+| results.json | R-raw | 21,718 | 2bf58939129c |
+| start-20760.h5 | R-raw | 92,247 | ae0abd05190c |
+
+## research/j3-offline-2026-10-12
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| REVIEW.md | K | 6,271 | a76e1b486bd2 |
+| lags.csv | R-raw | 1,104 | dd3136dd2dc2 |
+| localization.png | R-raw | 136,013 | 74b56f3e814c |
+| regions.csv | R-raw | 2,126 | 5d361e6872af |
+| results.json | R-raw | 8,852 | bf77b0f534d4 |
+
+## research/j3-reservoir-2026-10-12
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| REVIEW.md | K | 13,563 | a74b67a64e0d |
+| baseline-status.txt | P-pin | 2,896 | a318e077dfae |
+| baseline.json | P-pin | 25,571 | 060502ea7dd8 |
+| incremental.diff | D-snapshot | 22,898 | 8e2c79a86c98 |
+| results.json | R-raw | 182,747 | 7fd5e51a1785 |
+
+## research/refinement_example_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 8,286 | 591478100da8 |
+| before.json | R-raw | 818 | 7ab0962775b1 |
+| incremental.patch | D-snapshot | 8,682 | 7ad8719d0167 |
+| manifest.json | P-pin | 1,798 | bf1eee8a7cf8 |
+| notes.txt | K | 1,185 | 7ff019ad023d |
+| results.json | R-raw | 1,118 | 94697b0988b9 |
+| stdout.txt | R-raw | 325 | 501446f557f4 |
+
+## research/refinement_followup_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.txt | K | 4,887 | af65e889f20e |
+| baseline.json | P-pin | 5,343 | 7c60ad8ad692 |
+| cleanup.json | R-raw | 1,253 | 15cf342fba2e |
+| cpu_results.json | R-raw | 1,056 | 1166dffd2a09 |
+| cpu_results_attempt1.json | R-raw | 642 | d139d5508105 |
+| cpu_stdout.txt | R-raw | 499 | d1b33ea20563 |
+| cpu_stdout_attempt1.txt | R-raw | 879 | 6a9fe7fce39a |
+| gpu_before.json | R-raw | 589 | 46762a0ab207 |
+| gpu_before_no_launch.json | R-raw | 589 | 074982d1b2d4 |
+| gpu_rectangle_before.json | R-raw | 589 | 831e3793339f |
+| gpu_rectangle_before_no_launch_1791886104981638567.json | R-raw | 589 | c33885d50bfd |
+| gpu_rectangle_results.json | R-raw | 1,003 | 9c6da219ac6c |
+| gpu_rectangle_stdout.txt | R-raw | 332 | 9185bf303954 |
+| gpu_results.json | R-raw | 1,189 | 53e4f1c44de1 |
+| gpu_seed1_before.json | R-raw | 589 | c77ea3485f84 |
+| gpu_seed1_results.json | R-raw | 996 | b718e8af84e4 |
+| gpu_seed1_stdout.txt | R-raw | 306 | 4d7de0897137 |
+| gpu_stdout.txt | R-raw | 68 | b0956fe3cdb0 |
+| incremental.patch | D-snapshot | 16,836 | 9df25d8c177a |
+| manifest.json | P-pin | 4,410 | 177704d6f1ae |
+| run_gpu.py | R-raw | 5,237 | b5af3f0d4f79 |
+
+## research/refinement_prepare_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.txt | K | 8,939 | 8e210c28c7c5 |
+| baseline.json | P-pin | 46,348 | d5f257216b8d |
+| incremental.patch | D-snapshot | 15,751 | 0ddb32550584 |
+| manifest.json | P-pin | 2,113 | 9fd94ccf2c3e |
+| validation.json | R-raw | 3,567 | f057e7cbcd35 |
+| validation.txt | R-raw | 873 | 594daa45c58c |
+
+## research/refinement_slot_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 67,717 | d498081e7c50 |
+| before.json | R-raw | 690 | 430e76b3aa8a |
+| cpu_results.json | R-raw | 1,421 | 4f6bc4d9428f |
+| incremental.patch | D-snapshot | 18,676 | 67a3e8cc9e68 |
+| manifest.json | P-pin | 2,270 | 6515458290f4 |
+| notes.txt | K | 2,612 | 08a713ba4b37 |
+| results.json | R-raw | 1,160 | 03e683027ba8 |
+| stdout.txt | R-raw | 643 | d57b91769826 |
+
+## research/refinement_slot_followup_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 68,536 | 89a26ce79438 |
+| before.json | R-raw | 690 | e707df192ff2 |
+| incremental.patch | D-snapshot | 495 | c6f6fa11237d |
+| manifest.json | P-pin | 1,920 | 4840243a33aa |
+| notes.txt | K | 1,549 | 4b77583ca116 |
+| planar_velocity.cuh | R-raw | 1,911 | 87db7466c843 |
+| planar_velocity.sha256 | P-pin | 251 | 6694c4a1c1f0 |
+| results.json | R-raw | 1,050 | 6ef6eda854c6 |
+| stdout.txt | R-raw | 1,160 | 461860351c0c |
+
+## research/refinement_step_20261013
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.txt | K | 10,671 | 88d6f24743f5 |
+| baseline.json | P-pin | 40,620 | 20f61559dd38 |
+| cpu_validation.json | R-raw | 1,231 | 7999fd30018c |
+| gpu_failure_validation.json | R-raw | 868 | 5f6db65ee4f9 |
+| gpu_failure_validation.txt | R-raw | 248 | d9a570a1e9e9 |
+| gpu_validation.json | R-raw | 672 | 2028f59e1055 |
+| gpu_validation.txt | R-raw | 632 | 9699918ee127 |
+| incremental.patch | D-snapshot | 26,516 | d95f9347633d |
+| manifest.json | P-pin | 2,075 | 32a7f1a7309e |
+
+## research/repair-2026-10-10
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| TRON_HANDOFF.md | R-raw | 25,208 | a339786c7944 |
+| baseline-hashes.json | P-pin | 16,020 | 9b4e24cb1d10 |
+| baseline-status.txt | P-pin | 429 | 515be249b638 |
+| checkpoint-domain-2026-10-12.diff | D-snapshot | 14,443 | 035ed630dda1 |
+| classic-results.json | R-raw | 244,729 | 7297aa0d5bca |
+| classic-signals.npz | R-raw | 630,332 | 8cf6d1218aa0 |
+| final-gpu.log | R-raw | 191 | a0eec1a8ea31 |
+| final-unit.log | R-raw | 188 | 94efba2f1d42 |
+| provenance.json | P-pin | 1,020 | 25e22b4f0696 |
+| repair-architecture.md | K | 9,498 | 12051c3e8571 |
+| repair-numerical.md | K | 10,769 | 0c5757fe5f36 |
+| repair-state.md | K | 8,481 | 3c7f2d5b687a |
+| simplification-checks.log | R-raw | 1,045 | fa9d464be740 |
+
+## research/shear_refinement
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.md | K-code | 4,142 | 67bdd8ed622b |
+| boundary_shear_tagging.py | K-code | 13,859 | b5415a1c4ea1 |
+| example.py | K-code | 6,323 | 66295d3f0273 |
+
+## research/surface_actuation_20261014
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| baseline.json | P-pin | 54,139 | 0ad06888dbeb |
+| cpu_checkpoint_run.json | R-raw | 400 | 39681b60ff15 |
+| cpu_checkpoint_stdout.txt | R-raw | 114 | 929e4b8d4f46 |
+| cpu_initial.txt | R-raw | 620 | 29213c58a679 |
+| cpu_surface_command.txt | R-raw | 118 | 6d8c615a6e03 |
+| cpu_surface_exit.txt | R-raw | 2 | 573541ac9702 |
+| cpu_surface_stdout.txt | R-raw | 99 | ee9237fc26e5 |
+| gpu_run.json | R-raw | 1,698 | dc8f87eafaa9 |
+| gpu_stdout.txt | R-raw | 159 | b262891e52c3 |
+| incremental.diff | D-snapshot | 50,206 | 43090a1a8b11 |
+| manifest.json | P-pin | 7,527 | 35daa01271cb |
+| report.txt | K | 5,078 | 1162a6479f9f |
+
+## research/wall_seam_pulse_20261014
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| analyze.py | R-raw | 10,343 | ed7cf6999a49 |
+| interpretation.txt | K | 3,514 | 90935db2aa99 |
+| results.json | R-raw | 15,137 | 678a0759871a |
+| run.json | R-raw | 1,170 | 53e303fd0d5d |
+| sources.csv | R-raw | 2,313 | 40d3736b8ef1 |
+| stdout.txt | R-raw | 1,179 | 756d8c38e213 |
+
+## tests/validation/multigrid/cpuref_0_3_evidence
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.txt | K | 4,133 | 62897bfd9812 |
+| README_grok.md | K | 1,751 | 2d36e05661a8 |
+| baseline.json | P-pin | 39,291 | 188491096547 |
+| manifest.json | P-pin | 3,495 | 10c19f5fe5ca |
+| results_horsea.json | R-raw | 2,281 | 3b163384e376 |
+| stdout_grok.txt | R-raw | 7,143 | 5a0c270ea4ae |
+| stdout_horsea.txt | R-raw | 9,013 | adff8bb8d295 |
+
+## tests/validation/multigrid/local_stress_v1_evidence
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.txt | K | 8,239 | 3513fd294223 |
+| TABLE_local_stress_observable_v1.md | K | 2,967 | 6115dcde0f46 |
+| baseline.json | P-pin | 43,991 | ab631ea4f2ad |
+| comparison.json | R-raw | 13,248 | d7d1b36eb247 |
+| manifest.json | P-pin | 4,132 | c6c44d8125cd |
+| results_horsea.json | R-raw | 2,671 | 79bdf001f948 |
+| run_once.py | R-raw | 4,313 | fa9c5239e993 |
+| source_manifest.json | P-pin | 622 | 0516f1860407 |
+| stdout_horsea.txt | R-raw | 17,091 | a20c554693df |
+| stdout_local_stress_observable_v1.txt | R-raw | 12,238 | 692ffe1a05da |
+
+## tests/validation/multigrid/shear_v0_2_evidence
+
+| File | Class | Bytes | Blob |
+|---|---|---:|---|
+| README.txt | K | 7,220 | 772f74ad40ff |
+| baseline.json | P-pin | 41,751 | 70d9c9fa71c0 |
+| comparison.json | R-raw | 7,679 | 0af8736f9a01 |
+| joint_report.md | K | 6,110 | eed871221298 |
+| manifest.json | P-pin | 3,796 | b22d03a1ba9e |
+| results_horsea.json | R-raw | 1,957 | b2cd48a07a08 |
+| run_once.py | R-raw | 3,245 | 0b8d5e21f326 |
+| source_manifest.json | P-pin | 574 | 4d1c742690c7 |
+| stdout_grok.txt | R-raw | 7,950 | 0e80b1aba7f6 |
+| stdout_horsea.txt | R-raw | 11,421 | 3c867cdac197 |

docs/fixed_three_level_multipatch.md

@@ -1,23 +1,26 @@
-# Fixed three-level separated patches
+# Fixed three-level rectangle unions
 
-`FixedPatchStepper` supports exactly three static, blocked levels with separated
-rectangle sets on either adjacent pair. This is not general AMR: there is no
-per-region timestep, moving geometry, dynamic refinement or L1 body support.
+This page describes three-level `FixedPatchStepper` setups built from the
+`refinements` level list, with rectangle unions on either adjacent pair. The
+same constructor supports arbitrary depth; three or more levels require
+all-blocked storage and bodies/Jets only on the finest level. This is not
+general AMR: there is no per-region timestep, moving geometry, automatic
+dynamic refinement or L1 body support in the three-level form.
 All regions share one current/spare buffer pair per level. The existing schedule
 advances L0 once, L1 twice and L2 four times per base step, with aggregate transfers.
 No CUDA kernel changes are involved.
 
 ## Explicit coordinate frames
 
-Keep the existing scalar `child=(x0,y0,x1,y1)` for a single scalar parent patch.
-Its coordinates retain their original meaning: half-open integer indices in the
-allocated L1 window, including its ghost band.
+For a single scalar parent patch, pass a scalar rectangle as `refinements[1]`:
+`(x0,y0,x1,y1)` in half-open integer indices of the allocated L1 window,
+including its ghost band.
 
-The new keyword `child_rectangles_in_parent=[...]` is mutually exclusive with
-`child`. It accepts a scalar or a set parent and interprets every rectangle in
-the actual allocated L1 array, including ghost bands and holes. It never infers
-region-local coordinates. The physical root cell edge corresponding to an L1
-index `(x,y)` is `parent.fine_origin + (x,y)/2`:
+A rectangle list as `refinements[1]` accepts a scalar or a set parent and
+interprets every rectangle in the actual allocated L1 array, including ghost
+bands and holes. It never infers region-local coordinates. The physical root
+cell edge corresponding to an L1 index `(x,y)` is
+`parent.fine_origin + (x,y)/2`:
 
 - A scalar L1 parent has a shifted window origin.
 - A set L1 parent has origin `(0,0)` and public shape `(2*ny,2*nx)`.
@@ -30,20 +33,23 @@ are physically equivalent to parent set `[(4,4,12,12)]` with child set
 `[(8,8,16,16)]`. Reusing the same numbers after changing the parent frame can
 move the physical region.
 
-Both adjacent pairs require a Chebyshev gap of at least four in their own
-parent-cell units. The whole child union must preserve inherited ACTIVE
-coverage, uncovered ACTIVE donors/receivers, surviving pulls, and the upstream
+Both adjacent pairs are built from their unions, without a fixed rectangle-gap
+rule. Adjacent, overlapping and concave unions are accepted only when their
+actual transfer dependencies close. The whole child union must preserve
+inherited ACTIVE coverage, uncovered ACTIVE donors/receivers, surviving pulls, and the upstream
 restriction footprint. Sparse holes remain unowned; inherited INNER remains
-stream-only and OUTER remains invalid. Block sizes must align with every
-support edge, including its four-cell ghost band.
+stream-only and OUTER remains invalid. Block sizes must divide their allocated
+level grids. Sparse storage owns every grid-aligned tile intersecting the union
+plus its four-cell ghost band; rectangle and support edges need not align with
+tile edges.
 
 ## Example
 
 ```python
 run = FixedPatchStepper(
-    cfg, [(4, 4, 20, 28), (24, 4, 44, 28)], context=ctx,
-    base_block=(4, 4), fine_block=(4, 4), child_block=(4, 4),
-    child_rectangles_in_parent=[(16, 16, 32, 40), (56, 16, 80, 40)],
+    cfg, context=ctx,
+    refinements=[[(4, 4, 20, 28), (24, 4, 44, 28)], [(16, 16, 32, 40), (56, 16, 80, 40)]],
+    level_blocks=[(4, 4)] * 3,
 )
 ```
 
@@ -51,11 +57,11 @@ This example uses a 48x32 root. `initialize` and `download` use three Q-major
 dense arrays. Public arrays and masks still scale with the full allocated
 extent; sparse device buffers do not remove that host-memory limit.
 
-Stationary whole-circle `child_objects` and `child_jets` use root edge
+Stationary whole-circle L2 bodies and Jets (`level_objects[2]`, `level_jets[2]`) use root edge
 coordinates and a single L2 boundary object. Body IDs are physical object-list
 positions, not region IDs or caller `obj_id`. Complete boundary stencils must
 avoid the transfer footprint. Change a child Jet with
-`set_jet_amplitude(index, value, level=2)`; L1 bodies/Jets remain unsupported.
+`set_jet_amplitude(index, value, level=2)` (`level` is required); L1 bodies/Jets remain unsupported.
 
 ## Verification
 
@@ -65,6 +71,12 @@ CPU geometry, table, pre-CUDA rejection, schedule and cleanup tests:
 PYTHONPATH=src python -m unittest discover -s tests/unit -p 'test_refinement*.py' -v
 ```
 
+`tests/unit/test_union_refinement.py` covers union dependencies and tile
+ownership; `tests/unit/test_hierarchy.py` covers composed geometry through four
+levels. `tests/unit/test_raw_exchange.py` checks the four-level host schedule
+with CUDA mocks. These establish topology/control-flow coverage, not numerical
+qualification at every depth or interface shape.
+
 Explicit GPU gates are in
 `tests/validation/multigrid/test_refinement_three_level_multipatch_gpu.py`.
 They cover physical-frame equivalence, twins, asymmetric refinement, multiple

docs/lifecycle.md

@@ -0,0 +1,26 @@
+# Device state lifecycle (uniform Simulation, FixedPatchStepper)
+
+State is grouped by what a change invalidates. This file describes the code as
+it is; it adds no framework. Line references are to candidate 0f8fdbc3.
+
+| Class | Contents | How it changes | Owner rule |
+|---|---|---|---|
+| 1. Module and its globals | Compile-time (visible to the compiler, fixed per module): `config.h` macros incl. `NX`/`NY`, `COLLISION_MODEL`, `BLOCK_ROOT_BC`, `WALL_*`. Runtime per-module globals (not visible to the compiler; written by host code): `__constant__` `d_params`, `d_w`, `d_cx`, `d_cy`, `d_block_channel`, `d_block_wall`; plus bound kernel handles | Globals are written once by the owner right after `load_module`. Uniform grid: `Simulation._recompile` (construction, body-topology sync) loads a new module and re-uploads; `update_runtime_params` rewrites `d_params` (omega, force, n_objects) between runs. Steppers: never rewritten after construction, so they are immutable for the instance's lifetime although they are runtime values. The blocked slot/reservoir root reads its slot from the `d_block_wall` constant (the former dense route used `WALL_*` macros; both were bit-identical in the parity gates). | Every owner loads its own module (`compiler.load_module` = `module_from_file`, no cache). A loaded module is never shared between live owners: globals are per module, so sharing would share mutable `d_params`. |
+| 2. Geometry, layout, tables | flags, curved-link tables, block layouts and halo pairs, transfer (explode/coalesce) tables, block kinds | Immutable for the life of an instance. Uniform grid: rebuilt by body sync. `FixedPatchStepper`: a geometry change is a new instance (`remap_finest`), committed only after a successful transfer. | No in-place table edits. |
+| 3. Controls and dependent boundary columns | Jet amplitude -> per-link `surface_velocity`; body actions (uniform grid) | Between steps, without a table or module rebuild (`set_jet_amplitude`). | Input (index, level, amplitude) is validated before any device write; invalid input changes nothing and the instance stays usable. The host copy commits only after the upload returned. Any error after validation leaves the device column undefined and fails the instance: `FixedPatchStepper` status `failed`, `Simulation._failed`; every later device-touching public method (`Simulation`: `stream`, `set_jet_amplitude`, `initialize`, `sync_bodies`, `run`/`step`, `read_surface_exchange`, `read_body(s)`, `get_macroscopic`, `get_ddf`, `update_runtime_params`, `snapshot`, `restore`, save/load checkpoint) raises; cached host readers and host-side staging (e.g. `get_flags`, `add_body`/`remove_body` before a sync) do not touch the device and stay callable. `close()` still releases resources and stays retryable. |
+| 4. Per-step state | population double buffers and their parity, raw-exchange ledgers, observations | Device-only during `step(n)` / `run(n)`; buffer swaps are host-handle swaps. | Valid on the host only after the single wait at the end of the call. |
+
+Storage routes are separate concerns:
+
+- Original uniform grid (`uniform.cu`, `Simulation`): whole-domain `NX`/`NY`.
+- Blocked levels (`blocked.cu`; every `FixedPatchStepper` level, including the
+  single level of `refinements=[]`): `NX`/`NY` are one block window including halo.
+- Dense refinement levels (`refinement.cu`) were removed: `level_blocks` is
+  required and every refinement level is blocked.
+
+A single-rectangle refinement (`FixedPatch2D`) is stored in its own fine
+window frame (`FixedPatchStepper.__init__`,
+`BlockLayout2D.build(*pair.fine_shape, ...)`). Only a rectangle set
+(`FixedPatchSet2D`) uses the level-wide frame `(2*ny, 2*nx)`, whose
+`fine_layout` requires that full grid to be divisible by the tile
+(`refinement.py:240-252`).

docs/shifted_blocked_candidate.md

@@ -0,0 +1,61 @@
+# Opt-in shifted blocked candidate
+
+This candidate is based on fbe7377. The default remains unshifted. Enable with
+`LBMConfig(ddf_shifting=True)` only on the supported routes below.
+
+| Route | Candidate support |
+|---|---|
+| PeriodicBlockStepper, FP32 D2Q9 SRT double-buffer, no LES | shifted or unshifted |
+| FixedPatchStepper, every level blocked and same representation | shifted or unshifted |
+| Passive stationary circular BFL boundary and raw exchange | supported candidate scope |
+| Synchronized three-level child remap | private raw shifted snapshot, exact overlap/copy |
+| Dense root/refinement or mixed representation | rejected for shifted |
+| Slot/reservoir, surface actuation, velocity Jet | existing public shifted exclusion retained |
+| Other collision/lattice/storage/streaming/LES combinations | existing exclusions retained |
+
+The D2Q9 equilibrium helper accepts a retained density offset only in shifted
+compilation. BlockStep computes delta=sum(g) before adding the unit density;
+velocity uses the existing macro calculation. The existing SRT collision and
+all unshifted expressions remain. No global precision type or duplicate
+collision implementation is introduced. Ordinary shifted Simulation callers
+still use the existing rho−1 overload; this candidate does not change their
+numerical method.
+
+Public initialize receives physical populations and performs shifted subtraction
+in FP64 before the one FP32 storage cast. Public shifted download returns FP64
+physical populations with exact-rational D2Q9 background weights. Internal raw
+snapshots retain FP32 g and a representation tag; runtime remap never decodes
+and re-encodes overlap. Exact mass is interpreted as 1+sum(g), and momentum as
+sum(c*g); analyses should use raw values for tiny perturbation budgets. The
+FP32 BFL force constants have their own arithmetic rounding; no exact global
+conservation claim follows from shifting.
+
+Planar helper formulas include their shifted reference-density offsets and have
+actual-header host tests. Their public shifted route remains excluded until a
+separate test-gated migration. Next velocity-Jet work must validate physical
+wall density, incoming/outgoing populations, raw force/mass, ownership and
+transfer interactions before relaxing that restriction.
+
+Evidence so far: selected-cell CUDA replay favored retained-delta shifting;
+this is not full-solver validation. Host algebra/storage/remap tests and staged
+GPU continuation, three-grid cylinder physics, raw budgets, Couette helper
+stress and measured runtime are separate gates. Original failed experiments
+remain evidence; no acceptance threshold is relaxed.
+
+## Direct-input-momentum equilibrium candidate
+
+The shifted BlockStep now constructs the linear equilibrium term from input
+momentum j, without reconstructing rho*u. For opposite axis pairs the odd term
+is j/3; for diagonal pairs it is (jx +/- jy)/12, evaluated with explicit
+round-to-nearest division. The even term is
+w*[delta + 4.5*(c dot j)*(c dot u) - 1.5*(j dot u)].
+This is the same second-order D2Q9 equilibrium in exact arithmetic. Original SRT,
+storage, boundaries, and transfers are unchanged. No collision residual or force
+is corrected afterward. Existing four/five-argument equilibrium APIs are retained;
+only shifted blocked collision calls the new six-argument momentum helper.
+
+The all-fluid read-only CUDA replay reduced signed x-momentum error by 120–2285x
+at five sampled states, with lower mass/momentum and second-moment RMS errors.
+Signed mass bias was larger (~1e-12/cell/hop), so full evolving mass budgets remain
+mandatory. This local evidence does not establish physical convergence or speed.
+The unshifted default and its arithmetic path remain unchanged.

docs/supported_settings.md

@@ -0,0 +1,89 @@
+# Supported settings: 2D Jet + fixed multilevel refinement (candidate 888c8038)
+
+Every entry names the guard that enforces it (file and function or kernel guard,
+at source revision 888c80381c006e976be2af8a452288729fc17c1b) and, where one
+exists, an existing test that exercises it. A setting not listed here is not
+claimed. Observations at the end are tied to the exact case in which they were
+measured; they are not general bounds.
+
+## Lattice, storage, collision
+
+| Setting | Supported | Guard |
+|---|---|---|
+| Dimension / lattice | 2D D2Q9 only (3D refinement is future work) | `lbm/refinement.py` `FixedPatch2D.from_config`; `#error` guards in `lbm/kernels/blocked.cu` |
+| Precision / streaming | FP32 storage, double buffer | same guards |
+| Collision on refinement levels | SRT or MRT; TRT and LES rejected | `lbm/refinement.py` `FixedPatch2D.from_config` (re-checked for fine boundaries in `prepare_fine_boundary`) |
+| Shifted (ddf_shifting) storage | supported (every level is blocked); one representation on all levels | `lbm/refinement_stepper.py` `FixedPatchStepper._check_storage` |
+| Fine relaxation | 1/tau_fine must lie inside the configured omega guards | `lbm/refinement.py` `FixedPatch2D.from_config` |
+| Single blocked level `FixedPatchStepper(refinements=[], level_blocks=[(by, bx)], level_objects=[circles])` (replaces `PeriodicBlockStepper`, removed in 8e1feff) | doubly periodic, SRT only, no LES/Jets/projection/exchange observation, stationary passive circles; `download()` returns a 1-tuple | `lbm/refinement_stepper.py` `_check_levels`, `FixedPatchStepper.__init__`; `lbm/blocks.py` `static_circle_tables` |
+| Refinement storage | blocked on every level: `level_blocks` is required, one tile `(by, bx)` per level dividing that level; a whole-level tile (`(ny, nx)` at the root, the fine window shape for one rectangle) always divides. Dense and mixed dense/blocked storage were removed (parity of D/D, D/B and B/B recorded at 1573942 and 2469af7) | `lbm/refinement_stepper.py` `_check_levels`, `FixedPatchStepper.__init__` |
+
+Tests: `tests/unit/test_refinement_mrt.py`, `tests/validation/multigrid/test_refinement_mrt_gpu.py`,
+`tests/unit/test_shifted_storage.py`, `tests/unit/test_shifted_block_operators.py`.
+
+## Refinement hierarchy (`FixedPatchStepper(cfg, *, context, refinements, ...)`)
+
+| Setting | Supported | Guard |
+|---|---|---|
+| Depth | at least one refinement level; one entry per level in `level_blocks`/`level_objects`/`level_jets` | `lbm/refinement_stepper.py` `_check_levels` |
+| Single L1 rectangle | two-coarse-cell margin to the domain edge | `lbm/refinement.py` `FixedPatch2D.from_config` |
+| Several L1 rectangles (union) | require `level_blocks[0]` and `level_blocks[1]`; transfers must close (dependency checks, no fixed gap rule) | `lbm/refinement_stepper.py` `_check_levels`; `lbm/refinement.py` `_check_parent_pull_closure` |
+| Nested levels | depth >= 3 must be all blocked; a blocked level requires blocked levels below; a scalar child needs a scalar parent | `lbm/refinement_stepper.py` `_check_levels`; `lbm/hierarchy.py` `build_hierarchy` |
+| Nested transfer support | child only over inherited ACTIVE cells, donors/receivers uncovered ACTIVE, no child over the parent restriction footprint | `lbm/refinement.py` `_nested_kind` |
+| Tile shape | positive `(by, bx)`; the level allocation must be divisible by the tile (no partial tiles yet) | `lbm/refinement_stepper.py` `_check_levels`, `lbm/refinement.py` `FixedPatchSet2D.fine_layout` (shape); `lbm/blocks.py` `BlockLayout2D.build` (divisibility) |
+| Coarse boundary | `periodic`, `slot_reservoir` or `channel` | `lbm/refinement_stepper.py` `FixedPatchStepper.__init__` |
+| `slot_reservoir` | on-site velocity bottom slot, reservoir top, velocity 0, 2 <= slot width < nx, patch rows 4..ny-4 | `lbm/refinement_stepper.py` `FixedPatchStepper.__init__`; `lbm/refinement.py` `prepare_fine_boundary` |
+| `channel` | all levels blocked; Zou-He inlet, pressure-NEQ outlet, stationary bounce-back walls; transfers away from the closure | `lbm/channel.py` `validate_channel_config`, `validate_channel_transfers` |
+| Explosion | `constant` (default); `projected_linear` only periodic, all-blocked SRT, no bodies/Jets, no LES (experimental) | `lbm/refinement_stepper.py` `FixedPatchStepper.__init__` |
+| L2 runtime remap (`remap_finest`) | periodic three-level L2 sets only, no L0/L1 bodies, identical pinned boundary | `lbm/refinement_stepper.py` `FixedPatchStepper.remap_finest` |
+
+Tests: `tests/unit/test_refinement_three_level_multipatch.py`, `tests/validation/multigrid/test_refinement_multipatch.py`,
+`test_refinement_three_level.py`, `test_refinement_three_level_multipatch_gpu.py`, `test_refinement_blocked_base.py`,
+`test_refinement_blocked_fine.py`, `test_channel_root_gpu.py`, `tests/unit/test_channel_root.py`,
+`tests/unit/test_projected_pair_stepper.py`, `test_runtime_child_remap_gpu.py`, `test_pinned_body_remap_gpu.py`.
+
+## Bodies and Jets on refined levels
+
+| Setting | Supported | Guard |
+|---|---|---|
+| Bodies | stationary circles without sensor/force-region roles, entirely inside the patch union, fully resolved, disjoint, stencil away from the two-hop transfer footprint | `lbm/refinement.py` `prepare_fine_boundary` |
+| Level | not on L0; only on the finest level of a nested hierarchy | `lbm/refinement_stepper.py` `_check_levels` |
+| Jet condition | velocity only; `pressure` is reserved and raises NotImplementedError | `body/jets.py` `Jet.__post_init__` |
+| Jet geometry | each Jet selects resolved links of exactly one stationary body; no Jet/Jet or Jet/SurfaceActuation overlap; abs(amplitude) < 1 lattice | `body/jets.py` `Jet.__post_init__`, `jet_link_shapes`, `_surface_links` |
+| Jets with shifted storage | only in the all-blocked stepper with SRT and no LES | `body/jets.py` `_surface_links` |
+| SurfaceActuation | unshifted storage only | `body/objects.py` `SimObject.validate_surface_actuation` |
+| Raw boundary exchange (force) | blocked body levels only; the window ledger requires `observe_raw_exchange` | `lbm/refinement_stepper.py` `FixedPatchStepper.__init__` |
+| Checkpoint with Jets | refused | `simulation.py` `Simulation.save_checkpoint` |
+
+Raw exchange is the cut-link momentum reaction (wall + aperture), not a validated
+nozzle thrust or stress load. Jet amplitude is a lattice velocity, not a flow rate.
+
+Tests: `tests/unit/test_jets.py`, `test_jets_review.py`, `test_shifted_jets.py`, `test_raw_exchange.py`,
+`tests/validation/multigrid/test_refinement_jets.py`, `test_shifted_jets_gpu.py`, `test_raw_exchange_gpu.py`,
+`test_exchange_window.py`, `test_fine_surface_gpu.py`.
+
+## Observations from specific tested cases (not general bounds)
+
+- SRT channel root vs uniform OneStep, strict-parity test
+  `tests/validation/multigrid/test_channel_root_gpu.py::ChannelRootGPU::test_uniform_matched_root`:
+  in one of its 18 sub-cases (2 storage modes x 3 profile/clamp/damp settings x 3 blocks; which
+  one is not recorded), 1 of the 4320 compared values differs, max abs 2.33e-10, max rel 1.77e-7
+  (about 2 ULP). The test remains failed; its cause and any general bound are unresolved.
+- MRT root parity test
+  `tests/validation/multigrid/test_refinement_mrt_gpu.py::RefinementMRTGPU::test_uniform_matched_mrt_root`
+  (12 sub-cases: 2 storage modes x 2 profiles x 3 blocks, default outlet settings) passed bitwise
+  in the Horsea focused GPU run at K1 7813334 (2026-10-21).
+- Periodic Taylor-Green Re 100, measured at 36ffc8b1 (V3 matched pair, N128 depth 2):
+  every per-sample screen passed; the constant explosion's aggregate worst velocity L2,
+  0.004418, exceeds its preregistered 0.002 budget, while projected_linear passed that budget.
+- Curved-wall pressure (pilot harness, exact-q analytic annulus, tau 0.8): the coarse swirl r1
+  case exceeded its terminal density-gain cap (1.105e-4 vs 1e-4), so the frozen 9-case matrix
+  is NOT_ESTABLISHED. No validated fix exists. This is a pilot harness, not production code.
+- DFG 2D-1 Re 20 (V4, SRT, t* 60, pressure-NEQ outlet and local Zou-He inlet): refined and uniform
+  runs were NOT_STEADY under the frozen steady rule, so no interval verdict was given.
+
+## Not supported in this release
+
+3D, dynamic/automatic AMR (tagging, time-varying hierarchies beyond `remap_finest`),
+moving bodies on refined levels, pressure Jets, Jet checkpoints, LES or TRT on refined
+levels, partial (non-dividing) tiles.

docs/synchronized_leaf_remap.md

@@ -1,11 +1,15 @@
 # Synchronized leaf G remap and manual continuation
 
 This is a CPU state-transfer component, **not a runtime adaptive solver**.
-It changes only a separated L2 rectangle set in a three-level, body-free,
-periodic hierarchy. L0/L1 topology, relaxation parameters, direction order,
+It changes only an L2 rectangle union in a three-level periodic hierarchy.
+The body-free case is shown first; stationary L2 bodies/Jets follow the bounded
+support contract below. L0/L1 topology, relaxation parameters, direction order,
 physical frame and completed time remain unchanged. Existing geometry checks
-validate child support/nesting and separation. The CPU helper itself adds no CUDA, scheduler, allocator, boundary handling,
-collision or ghost refill. A bounded runtime adapter is described below.
+validate child support/nesting and actual transfer dependencies, without a fixed
+rectangle-gap rule. The three-level remap limit is unchanged by the stepper's
+arbitrary-depth level-list support. The CPU helper itself adds no CUDA,
+scheduler, allocator, boundary handling, collision or ghost refill. A bounded
+runtime adapter is described below.
 
 ```python
 from CelerisLab.lbm.refinement import FixedPatchSet2D
@@ -29,11 +33,13 @@ origin is retained. Physical lower edges are `origin + spacing*(x,y)` on L0,
 `origin + spacing*(parent.fine_origin + (x,y)/4)` on L2.
 
 Factory options `coarse_boundary` and `objects` must declare `"periodic"` and
-an empty body collection (all levels). LBMConfig's channel settings do not
-select this operator's boundary mode. Geometry metadata is factory-created;
+an empty collection; L2 bodies use `objects` as described below.
+LBMConfig's channel settings do not select this operator's boundary mode.
+Geometry metadata is factory-created;
 manual mutation/forging of metadata is unsupported. Caller certifies the
-actual state has no bodies/forcing, that all device work and old readers are
-quiescent, and that inputs are the **current owned-leaf postcollision G**.
+actual state matches the declared boundary and has no forcing, that all device
+work and old readers are quiescent, and that inputs are the **current owned-leaf
+postcollision G**.
 Count/phase stamps check consistency, not freshness or active-buffer identity.
 
 `current_g` is three NumPy Q-major arrays `(9,ny,nx)`. For blocked inputs,
@@ -71,11 +77,12 @@ PYTHONPATH=src python -m unittest discover -s tests/unit -p 'test_synchronized_r
 
 ## Explicit runtime continuation
 
-`replacement = current.remap_child(rectangles)` returns a new ready
+`replacement = current.remap_finest(rectangles)` returns a new ready
 `FixedPatchStepper` at the **same absolute step_count**. It supports only
-body-free periodic three-level runs whose existing L2 uses
-`child_rectangles_in_parent`. Scalar or union L1 parents are supported; scalar
-`child=` is deliberately rejected. L0/L1, relaxation and block sizes stay fixed.
+periodic three-level runs with no L0/L1 bodies and an existing L2
+`FixedPatchSet2D`; stationary L2 bodies/Jets follow the support contract below.
+Scalar or union L1 parents are supported; scalar `child=` is deliberately
+rejected. L0/L1, relaxation and block sizes stay fixed.
 No tagger, scheduler, in-place replacement, or general rollback is provided.
 
 The method holds the stepper lock, validates geometry, synchronizes its stream,
@@ -92,7 +99,7 @@ resources; an actual old-device synchronization/read failure marks the old
 stepper failed, consistent with its existing failure semantics.
 
 ```python
-replacement = current.remap_child([(20, 16, 36, 40)])
+replacement = current.remap_finest([(20, 16, 36, 40)])
 # Explicitly choose the returned continuation only after success.
 current.close()
 current = replacement
@@ -112,14 +119,15 @@ Per-population conservation is not an advancement target under collision.
 
 ### Bounded pinned-body extension
 
-`replacement = current.remap_child(rectangles, child_objects=original_objects)`
-also accepts stationary Circles in separated L2 rectangles. Every body’s
-**complete containing rectangle must remain identical**. Several bodies may
-share one pinned rectangle; there need not be any fluid-only rectangles.
-Separated fluid-only rectangles may be added, removed or moved. Existing
-nesting, four-cell gap, full-circle containment, reverse cut-link coverage and two-hop BFL
-transfer-footprint checks still apply. This is manual remapping, not adaptive
-body tracking or runtime body editing.
+`replacement = current.remap_finest(rectangles, objects=original_objects)`
+also accepts stationary Circles inside the L2 union. Each body's **physical
+boundary, complete BFL support and current per-link velocity must remain
+identical**. Rectangles are not pinned: they may be split, merged or resized,
+and other fluid coverage may change, including within the same connected union,
+provided that physical support is unchanged. Existing nesting, union transfer
+dependencies, full-circle containment, reverse cut-link
+coverage and two-hop BFL transfer-footprint checks still apply. This is manual
+remapping, not adaptive body tracking or runtime body editing.
 
 Supply all original root edge-frame definitions in their construction order.
 Do not pass `current.child_boundary.objects`: those are projected fine-local copies.
@@ -128,8 +136,8 @@ state, remapping reprojects the supplied definition onto the old topology and
 compares exact ordered circle centers/radii, flags, physical cut links, body
 IDs, q, lever arms, hits, BFL support,
 legacy SurfaceActuation specification and current per-link velocity against
-the existing boundary. Omission, changed geometry/actuation and changed body
-rectangle fail without device reads or allocations; reordered bodies fail
+the existing boundary. Omission, changed geometry/actuation or changed physical
+boundary/BFL support fail without device reads or allocations; reordered bodies fail
 too. Root object IDs are still assigned by list position, as in the constructor.
 
 Jets are taken from the live L2 boundary, including the most recent successful
@@ -141,12 +149,16 @@ boundary and velocities must match exactly.
 typed `FineBoundary2D`; it derives L2 fluid leaves as ACTIVE minus SOLID. No
 caller mask is accepted. Solids, ghosts and holes are never donors and remain
 NaN, physical-fluid overlap is exact, and exposed L1 still restricts all four
-old fluid children. The helper checks the old/new body pins and boundary too.
-Its immutable `pinned_rectangles` is a canonical, deduplicated tuple, empty for body-free layouts; rectangle input
-order does not affect it. Scalar-parent window offsets remain part of the
-coordinate conversion.
+old fluid children. The helper checks old/new physical boundary and velocity
+equality too. Its immutable `pinned_rectangles` is legacy containment metadata,
+not a remap eligibility constraint; it may be empty for a seam-spanning body.
+Scalar-parent window offsets remain part of the coordinate conversion.
 
-Focused CPU mocks: `tests/unit/test_pinned_body_remap.py`. GPU declarations:
+Focused CPU mocks: `tests/unit/test_pinned_body_remap.py`.
+`tests/unit/test_union_body_support.py` also checks seam-spanning circles,
+rectangle repartition/resize, unchanged physical support and live-Jet
+preservation. These host checks do not establish GPU evolution accuracy.
+GPU declarations:
 `tests/validation/multigrid/test_pinned_body_remap_gpu.py`, covering no-op
 next-step bitwise identity, moved-fluid A→B→A, current-amplitude preservation,
 physical boundary/velocity equality, source independence and absolute counts.

docs/validation/2d_scope.md

@@ -0,0 +1,53 @@
+# Bounded 2D implementation and validation scope
+
+This inventory starts from dev `8403956a9afc0b0bb89265cec374392013d89016` and
+integrates only the reviewed LES normalization production correction from
+`95cb6d2b9f43c1bdd46cbf27f03f0dfc0877cfb0`. The merged production bytes match that
+tested candidate exactly; the scope-test changes are retained from `53fad767`.
+GPU receipts remain associated with their exact tested commits, not relabeled as
+a new merged-commit run. Historical source identities and gates remain unchanged.
+
+## Implementation boundaries
+
+- Uniform D2Q9 supports SRT, TRT and MRT. An available collision selector does not
+  qualify every wall, inlet/outlet, forcing, storage or LES combination.
+- Fixed refinement supports SRT/MRT, FP32 and double-buffer streaming; TRT and LES
+  are rejected. Shifted refinement requires all-blocked storage. Refined channel
+  boundaries have narrower configuration guards than uniform boundaries.
+- Uniform checkpoints support compatible same-method continuation. Changing
+  collision or LES parameters is a different evolution, not exact continuation.
+  Jet checkpoints and refined checkpoints are unsupported; synchronized remapping
+  is not persistent restart.
+- Keep these conclusions 2D. Local D3Q19 operator tests do not establish a supported
+  3D Simulation runtime.
+
+## Evidence and remaining gaps
+
+| Area | Available evidence | Boundary of the conclusion |
+|---|---|---|
+| MRT cylinder flow and observation windows | Full matched uniform/refined MRT DFG and the window-ledger campaign passed their frozen periodicity, reference and matched-comparison gates. The window campaign used `185a919`; its MRT/no-LES numerical path remains unchanged. Current dev also contains independently scoped test/documentation changes and the LES correction, which do not extend MRT qualification. | This does not qualify other collision/boundary combinations or every refinement interface. Timing improvements are not additional accuracy evidence. |
+| Uniform forced channel | Six Poiseuille GPU cases on `8403956`: SRT/TRT/MRT at wall-normal resolutions H16/H32 passed. | This is the tested analytic channel configuration, not open-boundary or all-layout qualification. |
+| Uniform restart | Ten SRT/MRT checkpoint GPU tests passed on `8403956`; the separate representative TRT same-method double-buffer continuation GPU case also passed (one test). | This covers the tested same-method continuation configurations. No LES, Jet or refined checkpoint claim follows. |
+| Taylor–Green refinement | Independent topology checks are available. The actual-rate phase GPU regression passed one test across two layouts, with errors 1.584e-7 and 4.500e-9. | The physical interface-accuracy gap remains open. Passing topology and phase checks does not establish convergence or close that accuracy gate. |
+| Porous Couette and annulus | Prior campaign evidence exists and must remain associated with its original setup and source. | The reconstructed annulus is a validation helper, not qualification of a public boundary-condition API. Do not infer absence of evidence from a missing current rerun. |
+| LES normalization | The reviewed correction is integrated. Exact `95cb6d2` GPU validation passed all nine observations and frozen gates, with three warm-up/reset records, verified 101-source/import identity, DONE and exit 0. Last two SGS decrement relative errors were 6.276e-4 and 6.124e-5 against the unchanged 0.15 gate. | Scope is unforced uniform D2Q9/SRT, shifted FP32, double-buffer streaming and the tested wall-bounded x-periodic shear. No TRT/MRT LES, forcing, EsoPull, objects, refinement or 3D turbulence qualification follows. |
+
+Historical uniform SRT cylinder-startup and inlet-rounding findings remain separate
+from the passed MRT DFG result. Raw exchange/window consistency is a measurement
+contract, not a general stress or force-accuracy certification. Existing source-pinned
+runners may intentionally reject a newer checkout; never silently repin old receipts.
+
+## Remaining work
+
+The related host checks passed (67 checks); they do not replace the GPU or
+physical-accuracy evidence above. Preserve the existing SRT checkpoint cases,
+historical LES manifests and all frozen numerical criteria.
+
+Continue the TG accuracy investigation using its actual fine-level rates and
+the established analytic convention. Keep the physical accuracy gate open until
+the relevant comparison passes. Review this integration independently before
+publication; no new merged-commit GPU run is claimed here.
+
+No repeat of the accepted full MRT DFG or Cartesian expansion across unsupported
+combinations is required by this document. Main integration remains a separate
+review of complete, bounded feature scope.

docs/validation/dfg_re100.md

@@ -0,0 +1,60 @@
+# DFG 2D-2 Re100 GPU campaign (validation-only)
+
+## Current experimental source provenance
+
+This development branch now includes the reviewed AMR-channel source changes originating in `5338864748ac67fe2544487c059ba149ebf916da` and `47b05bc8abfc957fe876b0c63bdb386e3c6cbaa5`. The current full-source manifest pins the latter reviewed source snapshot, including the new channel files. This is an explicit new experiment; neither source review nor host tests transfer historical d79 GPU/flow acceptance to it. The channel GPU gate has not yet run at integration time.
+
+New run JSON records the source-origin pin plus `checkout_revision` (actual Git HEAD), `checkout_dirty`, and the experimental-source label. The origin pin is not claimed to be the run's checkout commit. Numerical definitions and thresholds are unchanged. Runs require a Git checkout for this runtime identity; source hash checks remain active.
+
+Historical d79 Re100/Jet execution stays reproducible at `69e9b78de9483a5ff21e2d0c74311d240bfaf88c`; the d79 LES diagnostic checkpoint is `20ae6770924df15f31305aad56e44a54a3dd4d88`. Their manifests and existing result files are not rewritten. Use those commits to reproduce or interpret old d79 evidence. The current AMR-channel experiment requires its own GPU and applicable flow evidence.
+
+## Scope and locked definitions
+
+Explicitly pinned AMR-channel experimental production snapshot (see provenance below). Uniform D2Q9/MRT, shifted FP32, double buffer, no LES, stationary cylinder and no-slip walls. This is not an AMR, jet, or full canonical-outlet certification.
+
+Physical geometry: [0,2.2] × [0,0.41], center (0.2,0.2), radius .05, rho=1, nu=.001, inlet mean=1 and peak=1.5. D is lattice diameter; dx=.1/D, dt=U_lattice*dx, nu_lattice=U_lattice*D/100. U_lattice=.01 gives peak inlet Mach .02598. Existing local Zou–He inlet is selected in validation config only. Existing pressure-NEQ outlet is unclamped: **it does not impose the canonical vector do-nothing condition nu*d_n(u)-p*n=0**. The existing production channel-flow initial condition is used, not zero velocity. Periodic eligibility is delayed to t*=250 (25 physical seconds), with fixed end t*=300 (30 seconds).
+
+Official source: https://wwwold.mathematik.tu-dortmund.de/~featflow/en/benchmarks/cfdbenchmarking/flow/dfg_benchmark2_re100.html
+
+The 20141124 official newer reference archive has higher-order line-integration force data and supersedes the older example table for this comparison. The compact tests/validation/data/dfg_re100/reference_cycle.json preserves the last complete lift-minimum cycle from lv6/dt4. Reference Cd=[3.164266,3.227392], Cl=[-1.021286,.986571], pressure difference=[2.420371,2.507013], St=.301841. These are derived sampled extrema, not exact analytical values. Official mean=(min+max)/2 and amplitude=max-min; separate time averages are also recorded.
+
+## Exact commands and startup ownership
+
+Use the existing CUDA/PyCUDA environment; no package installation or production edits required. From the repository root, use a new task-owned output path:
+
+    export PYTHONPATH="$PWD/src${PYTHONPATH:+:$PYTHONPATH}"
+    python -m pytest -q tests/unit/test_re100.py
+    CUDA_VISIBLE_DEVICES=0 python tests/validation/run_dfg_re100.py --diameter 20 --speed .01 --mode pilot --output output/validation/pilot_d20_u001 > pilot.log 2>&1
+
+Pilot is t*=5 (10,000 steps), with dense .02-t* sampling to calibrate diagnostic cost. It cannot pass periodicity or external benchmark validation. Root launch owner reviews health, memory, timing and stdout before full runs; the full pair is not launched automatically.
+
+    CUDA_VISIBLE_DEVICES=0 python tests/validation/run_dfg_re100.py --diameter 40 --speed .01 --mode full --output output/validation/full_d40_u001 > d40.log 2>&1
+    CUDA_VISIBLE_DEVICES=1 python tests/validation/run_dfg_re100.py --diameter 80 --speed .01 --mode full --output output/validation/full_d80_u001 > d80.log 2>&1
+
+These are separate invocations, not a parallel shell script. A single root launch owner serializes startup/compilation across all Horsea work. Do not launch the next process until the previous log contains an explicit `READY {...}` line. READY comes after the first physical sample, including Simulation initialize, sim.run, read_force and get_macroscopic, so lazy runtime/diagnostic paths are exercised. That sample remains in the physical trajectory/history. No hidden warmup/reset, no later new diagnostic kernel. Do not treat a process merely existing as READY. Keep separate output directories and retain exit codes/logs. GPU assignment is chosen by root after checking existing workloads; shown indices are examples of physical device selection.
+
+## Measurement, frozen criteria and outcomes
+
+Force uses advancing link-momentum exchange, accumulated in batches <=100 steps, combined in FP64; Cd/Cl=2F/(U_lattice² D). Force timestamp is the batch midpoint. Pressure uses fluid-only h/2h extrapolation to cylinder front/back points and physical conversion 1/(3 U_lattice²), at each sample endpoint. For phase comparisons endpoint pressure is interpolated to the same cycle phase. Both raw times are saved.
+
+Before t*=240 sample width=.5; afterwards .02 (about 166 samples per lift cycle). Pilot uses dense sampling throughout. Extract complete lift-minimum-to-minimum cycles using quadratic local minimum locations, accepting periods 2–5 t*. Latest five complete cycles must be consecutive with the last ending no more than 5 t* before the final observation, and must start at or after t*=250. Eligibility requires lift amplitude >=.2, period range/mean <=.005, Cd/Cl/pressure min and max ranges <=.005 absolute, cycle-mean mass range/mean <=1e-4, and each cycle's mean mass-flux imbalance <=.005. Instantaneous flux equality is not required in this unsteady compressible LBM diagnostic.
+
+Reference gates: Cd extrema relative errors <=2%, Cl extrema absolute errors <=.03, pressure extrema relative errors <=2%, St relative error <=2%. These are predeclared engineering tolerances, not official uncertainty intervals. Phase-aligned waveform RMS errors, extrema, midpoint means, time means, amplitudes, outlet residual, sampled density bounds and Mach are all reported. Waveform RMS is diagnostic (no retroactive gate). No threshold changes after GPU results. At cap, failed periodicity stays incomplete. Invalid/nonfinite state, rho outside [.5,1.5], or sampled max Mach>.2 causes a safety stop; this is a gross-health guard, not a Mach-independence claim.
+
+A case_reference_pass requires both periodicity and reference gates. Every raw case keeps suite_validated=false. The two-grid comparison must report each case and errors; matched-Mach D40/D80 is evidence of resolution sensitivity only, not an asymptotic convergence order. If either fails or finer errors increase materially, report the failure instead of adjusting thresholds. No full canonical/AMR/Mach-independent validation claim is allowed.
+
+## Resource and calibration plan
+
+D20: 441×84=37,044 nodes, pilot 10,000 steps. D40: 881×166=146,246 nodes, 1,200,000 full steps. D80: 1761×330=581,130 nodes, 2,400,000 full steps. Main double-buffer DDF arrays alone cost 72 bytes/node: 2.7/10.5/41.8 MB decimal. Flags, masks, macro host arrays, body buffers and CUDA context/JIT memory add overhead; root verifies actual free GPU/host memory and disk before launch. Conservative per-process reservation: 1 GiB VRAM and 2 GiB host RAM, excluding shared/compiler overhead; measurements take precedence.
+
+Historical Re20 D80 U=.01 step throughput was ~6082 MLUPS (45.9 seconds/480k steps). At equal throughput D80 Re100 full advancing steps would take ~229 seconds, excluding dense full-field downloads/reduction and compile overhead. D40 estimate must be calibrated, not assumed proportional. Pilot records startup_seconds, step_seconds, measurement_seconds, mlups. For each full grid, calibrate a same-grid pilot if D20 cannot predict cost adequately. Full has about 3480 records (480 coarse+3000 dense); use measured seconds/step × full steps plus seconds/record ×3480 plus startup. D20-to-D80 extrapolation is only a rough planning upper/lower guide, not an ETA commitment.
+
+Only geometry.npz, one final_field.npz, history.csv, summary.json and stdout/stderr are persisted. No per-step or repeated full-field snapshots. D80 final float64 rho/ux/uy plus mask are <15 MB uncompressed; history/summary several MB, compact versioned reference/source guards <50 KiB. Budget <100 MB per case and <500 MB whole campaign including logs and optional externally retained archives, safely below 2 GiB; root still checks baseline Horsea usage. Retain sparse evidence only.
+
+## CPU validation and remaining execution
+
+Ten tests cover geometry/units/config, pressure scaling, periodic and nonperiodic synthetic histories, immutable production hashes, and self-reference comparison. CUDA execution is not available in the preparation environment and has not been claimed. Run pilot first on Horsea; do not confuse successful CPU tests with GPU readiness.
+
+## Reference provenance and reproduction
+
+Only the compact derived cycle is versioned. Its source URL, official ZIP SHA-256, column selection, and cycle-selection description are embedded in reference_cycle.json. Raw archives and GPU results are not repository inputs. To reproduce it, obtain the exact archive identified there, verify its SHA-256, and extract logs/results_cc2d_bench2_referencenew/bdforces_q2_lv6_dt4 and pointvalues_q2_lv6_dt4. Use physical time column 2 multiplied by 10, drag/lift columns 4/5, and pressure columns 7 minus 12 (one-based columns). Build rows with mass=flux_in=flux_out=1, then call periodic.extract(rows, min_time=0) and select the last complete cycle. The source guard is tests/validation/data/dfg_re100/source_manifest.json; it verifies the current reviewed production snapshot rather than equating its origin with the validation branch HEAD.

docs/validation/dfg_re20.md

@@ -0,0 +1,49 @@
+# DFG 2D-1 (Re 20) against the official reference intervals
+
+`tests/validation/run_dfg_re20.py` runs the steady DFG 2D-1 case on the refined
+channel root (D40 root, D80 wide fine patch) and on the uniform D80 grid. Geometry,
+inflow, initial state, layout and observation are those of the pinned Re100 runner
+(`run_refined_dfg.py`, `re100_helpers.py`, both unchanged); only the lattice
+viscosity is set for Re 20 (root tau 0.56, fine 0.62, uniform 0.62, lattice speed 0.01).
+
+Label: "compared against the official reference bands", not a full benchmark
+certification: the outlet is pressure-NEQ (`neq_extrap`), not do-nothing, and the
+inlet is local Zou-He.
+
+## Quantities
+
+- Cd = 2 Fx / (rho U^2 D), Cl = 2 Fy / (rho U^2 D), interval means over each sample.
+- p_diff = p(0.15, 0.2) - p(0.25, 0.2), linear extrapolation to the exact surface
+  points (`re100_helpers.pressure_probes`). The helper returns dp / (rho U^2) in
+  scaled units; p_diff = dp * 0.04 for U = 0.2 m/s, rho = 1. Both are reported.
+- Official intervals (Schaefer & Turek 1996): Cd [5.57, 5.59], Cl [0.0104, 0.0110],
+  p_diff [0.1172, 0.1176].
+
+## Bounds and steady rule (frozen before any run)
+
+- End time t* = 60 (30 s physical): 240,000 refined root steps, 480,000 uniform steps.
+- One sample every t* = 0.5 (0.25 s) at the end of a synchronized root step; Cd and
+  Cl are interval means. Trailing window t* 50..60 inclusive (21 samples).
+- Steady rule (our engineering choice, not official): in the window, for each of Cd,
+  Cl, p_diff, max - min <= 10 % and |least-squares slope x window| <= 2 % of its
+  official interval width (range 2e-3 / 6e-5 / 4e-5; slope 4e-4 / 1.2e-5 / 8e-6).
+  Absolute limits, so the small Cl is never a divisor. Never relaxed after a run.
+- The verdict uses the window mean; the distance to the nearest interval edge is
+  reported for each quantity (negative outside).
+- Force sign: fluid on cylinder, x along the inflow, y up from the bottom wall; Cd > 0
+  and the official Cl > 0 (`cd_positive` is reported).
+- Not steady at t* = 60: status `NOT_STEADY`, no interval verdict. Health limits
+  (Mach <= 0.2, rho in [0.5, 1.5]) stop the run with `UNHEALTHY`.
+- Steady: `WITHIN_INTERVALS` or `OUTSIDE_INTERVALS`, with the per-quantity verdict.
+
+## Run
+
+```
+python tests/validation/run_dfg_re20.py --output <new-dir> --plan
+CUDA_VISIBLE_DEVICES=<n> python tests/validation/run_dfg_re20.py --case both \
+    --collision SRT --output <new-dir> --max-wall-seconds <cap>
+```
+
+The uniform D80 control separates method error from refinement error. `--plan` writes `plan.json` only. A GPU run writes `plan.json` and `result.json`
+(per case: lattice parameters, every sample, window ranges, status, verdict).
+Host contract tests: `tests/unit/test_dfg_re20.py`.

docs/validation/jet_circle_cv.md

@@ -0,0 +1,115 @@
+# Jet-circle closed-control-volume pilot
+
+## Current experimental source provenance
+
+This development branch now includes the reviewed AMR-channel source changes originating in `5338864748ac67fe2544487c059ba149ebf916da` and `47b05bc8abfc957fe876b0c63bdb386e3c6cbaa5`. The current full-source manifest pins the latter reviewed source snapshot, including the new channel files. This is an explicit new experiment; neither source review nor host tests transfer historical d79 GPU/flow acceptance to it. The channel GPU gate has not yet run at integration time.
+
+New run JSON records the source-origin pin plus `checkout_revision` (actual Git HEAD), `checkout_dirty`, and the experimental-source label. The origin pin is not claimed to be the run's checkout commit. Numerical definitions and thresholds are unchanged. Runs require a Git checkout for this runtime identity; source hash checks remain active.
+
+Historical d79 Re100/Jet execution stays reproducible at `69e9b78de9483a5ff21e2d0c74311d240bfaf88c`; the d79 LES diagnostic checkpoint is `20ae6770924df15f31305aad56e44a54a3dd4d88`. Their manifests and existing result files are not rewritten. Use those commits to reproduce or interpret old d79 evidence. The current AMR-channel experiment requires its own GPU and applicable flow evidence.
+
+Status: CPU preparation only. No GPU run or production change. Current source origin: reviewed AMR-channel snapshot 47b05bc8abfc957fe876b0c63bdb386e3c6cbaa5; this new experiment has no inherited d79 GPU acceptance. tests/validation/data/jet_circle_cv/source_manifest.json checks all tracked source file hashes before importing GPU code.
+
+## Execute only after root-owned GPU serialization
+
+From the repository root, with REPO set to the repository root and an absent output directory:
+
+```sh
+PYTHONPATH=src python -m pytest -q tests/unit/test_jet_circle_cv.py
+python tests/validation/run_jet_circle_cv.py --repo "$REPO" --output "$OUTPUT" --plan
+CUDA_VISIBLE_DEVICES="$VERIFIED_IDLE_GPU" python tests/validation/run_jet_circle_cv.py --repo "$REPO" --output "$OUTPUT"
+```
+
+The runner does not select, reserve, or contact a GPU machine. It requires one explicit CUDA_VISIBLE_DEVICES value, at least 1 GiB free, and refuses an existing output directory. It imports existing PyCUDA; no installation. Default pilot: 800 base steps, 8 output windows, at most 1800 seconds after READY. READY is printed only after both steppers compile, execute one base/two fine warmup hops, exercise download/raw paths, and reset initial state/time. A pre-READY silence may be compilation, not stepping progress. Root owns any overall startup timeout and all launch serialization.
+
+## Physical/numerical case
+
+Periodic root box 192 by 128, center (96,64) in root cell-edge coordinates, D=24.084, U0=.03, nu=.0072252, Re_D=100, beta=Vj/U0=.1, rho0=1. Unforced D2Q9 SRT FP32, no DDF shifting, no LES. The slightly noninteger diameter was selected solely to avoid q clipping at all three planned scales. Circle is stationary. Two uniform radial sectors at pi/2 and 3pi/2, half-width pi/12: top blows outward +.003, bottom sucks inward -.003; remaining wall has zero velocity. This periodic transient is NOT DFG, infinite-stream drag, or statistical high-Re validation. End time is t*=t U0/D approximately .9965.
+
+AMR bounds (48,32,144,96). Finest dx=dt=.5 in root lattice units, nu_fine=2 nu, finest D=48.168. Full-domain fine reference is 384 by 256 with exactly the same finest spacing, timestep, viscosity, collision and storage. Root tau=.5216756, fine tau=.5433512, Mach approximately .05196.
+
+AMR uses actual public FixedPatchStepper Jet construction and raw observation. The uniform blocked reference reuses the existing test_raw_exchange_gpu.py optional-input validation adapter: production Jet-derived velocity/force-arm arrays feed the unchanged blocked curved kernel. Its normal public PeriodicBlockStepper API is passive-only. This does not claim there is no uniform Jet route anywhere: Simulation.add_jet exists, but the same-blocked-kernel adapter removes a backend/storage confound for this comparison. No new public backend is introduced. Runtime asserts matching directions, q, fallback and true hit coordinates after frame conversion; both sectors must resolve links. Unclamped q/no fallback is required.
+
+## Independent measurements and signs
+
+Two closed rectangles: (72,44,120,84) and (64,40,128,88), wholly within the finest patch. Every contour face has two active-fluid stencil layers. Capture physical postcollision populations at t=0 and every completed base interval. Collision conserves density/momentum; these are valid endpoint moments, NOT precollision stress estimates.
+
+For each contour, M and P sum fluid-cell rho and rho*u times h^2, excluding the staircase solid. Face midpoint quadrature integrates rho*u dot n and [rho*u*u+p*I-mu*(grad u+grad u.T)] dot n. Velocity gradients use centered differences in root-length units, mu=rho*nu, p=(rho-1)/3. Constant pressure subtraction integrates to zero on a closed rectangle. No raw exchange enters these field quantities.
+
+Trapezoidal time integration samples every base step over the SAME reported [step_start,step_end] as cumulative raw impulses/masses. For each window:
+
+- mass into fluid through body surface = delta M + integral outer mass flux
+- raw boundary reaction target = -delta P - integral outer momentum-minus-traction flux
+
+Raw rows are [Jx,Jy,angular impulse,mass into fluid]; each uniform fine hop scales by [.25,.25,.125,.25], exactly as the AMR interval ledger. Both fine hops are accumulated. AMR observation time endpoints and the public raw reduction are checked. Reports separate total, wall, aperture, blowing and suction raw rows. Coefficients divide force by .5*rho0*U0^2*D. These are momentum reactions including aperture transport; neither raw aperture nor total raw reaction is labelled solid-only hydrodynamic traction.
+
+Independent aperture mass estimates integrate measured rho*u dot e_r over true arcs using 64-point Gauss quadrature and nearest active-fluid samples. No target velocity or raw row enters this estimate. Reports include maximum sampling distance, actual signed raw mass rates and nominal signed volume flux ±2*(pi/12)*R*Vj. Near-wall nearest-node sampling is only a first-order diagnostic, not certified wall extrapolation. Nominal volume flux is not asserted to equal measured mass flow at finite density variation.
+
+Inventory near the circle is a staircase-cell approximation; its geometric error and face/time quadrature errors can appear in CV residuals. Two-contour spread and grid refinement are essential. No exact continuum force value, solid traction recovery, jet hardware load, or physics acceptance is claimed. Output status is deliberately PILOT_DIAGNOSTIC_ONLY even on successful execution.
+
+## Scope, refinement, resources
+
+Default one pilot only. Estimated device envelope 128 MiB, required free 1 GiB; bounded JSON only, conservatively under 2 MiB, no population snapshots or per-step logs. Every base step downloads both fields for independent quadrature, so PCIe/CPU diagnostic cost is intentional. Six CPU tests cover descriptor/source identity, uniform flux cancellation, affine convective divergence, quadratic viscous sign/coefficient, matched geometry/Jet selection and diffusive scaling.
+
+Optional --scale 2 or 4 doubles/quadruples all lengths and divides U,V by that scale, holds lattice nu fixed, and scales steps/windows by scale^2: physical Re and t* match, Mach decreases. Source and geometry guards repeat. Device estimate scales as scale^2; memory gate requires twice the estimate or 1 GiB, whichever is greater. Scale 4 is not part of default authorization/readiness. --re 400 requires --allow-re400 and a separate reviewed root launch decision after Re100 evidence; no automatic promotion.
+
+Compare AMR/reference velocity error, signed reaction coefficients, each contour's independently measured reaction and residual, contour spread, signed mass budgets, and measured aperture flux. Freeze numerical tolerances only after agreeing a scientifically appropriate convergence criterion; this preparation imposes only structural/finite-state guards. A completed pilot cannot establish convergence.
+
+Follow-on design retained: porous Couette crossflow with u=U*expm1(Re_V*y/H)/expm1(Re_V), v=V and unequal exact wall shear. It requires validation-only planar geometry and is intentionally not implemented here.
+
+### Amplitude, geometry, and high-Re limits
+
+Both Jet amplitudes are constant throughout the run and every fine substep; geometry is fixed. There is no runtime switch, per-step forcing schedule, or moving-wall velocity in this campaign. Construction/packing happens once, with identical uploaded amplitudes in the uniform adapter. This avoids any substep timing ambiguity from amplitude changes.
+
+Every case records actual tau_root and tau_fine. For this fixed s=1 geometry and speed, Re400 would give nu=.0018063, tau_root=.5054189 and tau_fine=.5108378, close to the SRT limit .5. The implemented Re choices are a bounded campaign menu, not a universal physical Reynolds-number ceiling. Higher-Re evidence may require a larger initial resolved geometry or a different justified grid/relaxation design before launch. Diffusive refinement at constant lattice nu improves spatial/Mach resolution but does not move tau farther from .5; simply selecting scale=2 does not cure a poor tau. No all-Re, LES or three-dimensional realism claim follows from this pilot.
+
+The source guard checks production file content against the current reviewed source origin, not validation-branch HEAD. This runner is validation-only; generated results and frozen execution-package archives are not committed.
+
+## Measurement-only continuation (frozen design before execution)
+
+The original 800-step pilot and its audit remain historical evidence, not an acceptance target. The following adds diagnostics only; it neither modifies production kernels nor adjusts velocity commands to improve measured flux. Use the canonical validation Git branch, with the same source-manifest check and checkout provenance record. No standalone replacement source archive is needed.
+
+Run the pair serially under root-owned GPU allocation, from the checked-out repository:
+
+```sh
+python tests/unit/test_jet_circle_cv.py -v
+python tests/unit/test_jet_cv_measurements.py -v
+CUDA_VISIBLE_DEVICES="$VERIFIED_IDLE_GPU" python tests/validation/run_jet_circle_cv.py --repo "$PWD" --output "$NEW_OUTPUT_S1" --continuation --steps 3200 --scale 1
+CUDA_VISIBLE_DEVICES="$VERIFIED_IDLE_GPU" python tests/validation/run_jet_circle_cv.py --repo "$PWD" --output "$NEW_OUTPUT_S2" --continuation --steps 3200 --scale 2
+python tests/validation/analyze_jet_cv_continuation.py "$NEW_OUTPUT_S1" "$NEW_OUTPUT_S2" --output "$COMPARISON_JSON"
+```
+
+Both output directories must be absent. `--plan` prints configuration without CUDA. `--continuation` deliberately accepts only Re100, scale1/2, and 3200 reference steps: a bounded campaign, not a physical Re ceiling. Actual steps are 3200 and 12800, reaching the same t*=3.986048829. Physical circle/box/contours and beta remain fixed; all root lengths grow by s, U and jet speed shrink by s, lattice nu remains .0072252. Both runs retain tau_root=.5216756 and tau_fine=.5433512, with Mach .0519615/s. This diffusive refinement changes the finite-Mach/compressibility error as well as grid resolution; it is not an isolated spatial-error order study.
+
+### Units, cadence, and reconstructibility
+
+Reference length/time are one scale-1 root lattice length/time; density reference is one. Convert scale-s root quantities by: length /s, time /s², velocity times s, mass /s², momentum and impulse /s, force times s, angular impulse /s², pressure times s². Volume and mass rates are unchanged. The nominal signed aperture volume rate is ±.0189155293672 in reference units at every scale. A mass flux divided by rho_ref times that rate is a reference-density diagnostic, not an actual-volume-flow ratio. Saved Q and M remain separate.
+
+Exact raw observations accumulate every completed base interval, including both fine substeps. Field downloads occur only at shared reference times 0..100 at dt=1, then 100..3200 at dt=4: 876 samples per run, compared with 3201/12801 possible every-base samples. Every 100-reference-time window boundary is included. Trapezoidal integration uses the actual variable time gap, with the raw ledger covering exactly the same endpoints. No missing sample is silently treated as unit dt. Sampling is denser during abrupt startup; it is not a guarantee of resolving all high-frequency acoustic modes. Offline coarsening can expose some time-quadrature sensitivity but cannot rule out unresolved-frequency aliasing.
+
+`samples_s*.npz` stores at every sample: density minima/maxima/max perturbation and max speed for uniform fluid, AMR root leaves and AMR fine leaves; composite full-domain mass; CV endpoint inventory and flux; separate advective, pressure and negative-viscous-traction momentum fluxes; nearest-fluid mass proxy; extrapolation ray primitive values; linear/quadratic reconstructed Q and M; and cumulative raw wall/aperture/total/blowing/suction rows. Associated JSON identifies axes, units, conversion factors, hashes and snapshot metadata. Composite AMR mass sums root leaves at area1 and fine leaves at area.25, then divides by s². Covered cells are excluded. Global periodic mass change minus total raw body mass is reported, so a transfer/interface mass error cannot hide behind the two contours lying wholly within the fine patch.
+
+Five compressed primitive snapshots at reference times 0,100,800,1600,3200 retain rho, reference velocity, origin and spacing for uniform, AMR root and AMR fine grids. Inactive/solid entries are NaN. These are full primitive grids at sparse times, not downsampled images or distributions. They permit independent spatial quadrature, field inspection, masks and inventory reconstruction. Per-sample split flux/inventory arrays allow independent temporal integration without rerunning GPU work. FP32 saved primitive snapshots introduce their own rounding; FP64 sampled diagnostic/ray arrays remain in the sample file.
+
+### Independent aperture estimators and limitations
+
+Thirty-two Gauss points per true aperture arc, with rays at distances 1.5,2.5,3.5 finest-cell widths into the fluid, sample rho,u,v by bilinear interpolation using only active fluid nodes. No commanded wall value or raw population enters reconstruction. Linear and quadratic outward-normal extrapolations separately reconstruct rho and u; integrate Q=integral(u.n ds) and M=integral(rho*u.n ds). Retain ray positions, normals, weights, primitive samples and coefficients, making every estimate reproducible. The nearest-fluid 64-point mass proxy is preserved for continuity with the pilot and remains explicitly a proxy.
+
+Neither estimator is an exact wall value or validated wall model. Extrapolation amplifies noise and may yield unphysical density; do not clamp it to force agreement. Sector endpoints contain nonsmooth prescribed velocity changes, and interpolation may mix their neighborhood. Linear-versus-quadratic spread, ray density extrema, resolution changes and analytic manufactured tests constrain interpretation, but their agreement is not proof of low bias. Two grids alone cannot establish asymptotic convergence. Nominal geometry/profile flux is exact for the commanded uniform radial profile; comparison with reconstructed Q diagnoses estimator plus numerical-boundary error, not automatically a Jet defect. Raw reaction remains momentum transport plus traction; no nozzle-load or solid-only force claim.
+
+### Predeclared comparison criteria
+
+These criteria are fixed before the continuation runs. There is no new physical acceptance threshold and no tolerance fitted to the pilot:
+
+1. Structural validity: exact source/provenance, matched geometry/parameters, unclamped q/no fallback, both apertures resolved, finite positive active-node density and finite velocity at every saved field sample, complete scheduled samples, contiguous matching raw intervals, and all declared files/hashes. Runtime does not promise positivity between saved samples.
+2. Report every window's signed and gross quantities, maximum sampled errors, and early (reference t<=800) versus later (t>800) norms separately. Normalize mass residual by rho_ref*abs(Q_command)*window_duration, and reaction residual by .5*rho_ref*U_ref²*D_ref*duration. Avoid dividing by a near-zero net mass or instantaneous force.
+3. Recompute contour residuals using the complete sampled grid and every second/fourth sample, always retaining endpoints. Save their changes as a temporal-sensitivity proxy, not an error bound. Compare both contours and both backends; show mass, Cx and Cy components separately.
+4. A directionally resolved reduction in a component's RMS CV residual is flagged only if coarse-minus-fine RMS exceeds twice the largest observed temporal coarsening change. This is an evidence-of-trend flag, never a physics PASS. If a component plateaus or grows, decompose temporal/spatial/staircase/boundary effects before proposing production changes.
+5. Compare reconstructed Q/command and M/(rho_ref*command) separately, at identical physical windows, retaining both extrapolations. Regard refinement improvement as persuasive only when it exceeds estimator spread and temporal variation. Inspect density and global mass alongside it. Agreement of AMR and uniform ledgers alone cannot validate their shared boundary treatment.
+6. Four D/U in a periodic unforced domain remains transient consistency evidence. Two scales do not prove order, stable shedding, infinite-stream drag, all-Re capability, or readiness to promote Re400. Formal physical acceptance needs an additional reference/error budget and appropriate time/domain evidence.
+
+### Runtime and storage budget
+
+Actual earlier scale-1 pilot cost was 52.3884s launch-to-exit, 46.1414s after READY for800 steps with full-field diagnostics every base step. A naive same-diagnostic3200-step scale-1 extrapolation is about210s; the new876 field samples reduce transfer count but add ray diagnostics and compression. Use conservative planning envelopes210–500s for scale1 and900–3200s for scale2, not timing guarantees. The scale2 conservative envelope accounts for4x cells and4x root steps; sparse sampling mitigates but does not eliminate that cost. Post-READY safety caps are1200s and5400s respectively, replacing the unsuitable fixed1800s assumption. Root owns compilation/startup timeout and serial launch decisions.
+
+Device-envelope estimates remain128/512MiB for s1/s2, at least1GiB free (or twice estimate). Output estimate is under64MiB per run including five primitive snapshots and876 sample records; no all-time populations are saved. Plan/metadata and sampled files are rewritten at each100-reference-time window to retain bounded partial evidence if interrupted. READY still follows compiled warmup and state/time reset, before measured stepping begins.

docs/validation/les_helpers.md

@@ -0,0 +1,40 @@
+# Smagorinsky baseline/candidate helper diagnostic
+
+This validation-only diagnostic compares exact d79 production headers with a temporary candidate. It does not modify production source. The candidate changes only the D2Q9 and D3Q19 closed-form factors from 18 to 18 sqrt(2), plus comments defining |S| = sqrt(2 S:S) and self-consistent effective tau. The small reviewed patch and expected header hashes are in `tests/validation/les/data`; no copied headers, solver trees, raw results, or binary fixtures are versioned.
+
+## Prepare and verify on the CPU
+
+From the repository root, choose a new output directory:
+
+```sh
+python tests/validation/les/prepare.py --output-dir output/les-host/candidate
+python tests/validation/les/test_candidate.py --candidate-dir output/les-host/candidate --output output/les-host/host_results.json
+```
+
+Preparation checks both actual production header hashes against d79, copies only `descriptors.cuh` and `turbulence_smag.cuh` into output-local baseline/patched include trees, applies the reviewed patch only to the latter, and verifies all four resulting hashes. It refuses an existing candidate directory. The host test verifies candidate hashes again and refuses an existing evidence file. The Git branch HEAD may include validation commits; header content, rather than HEAD identity, is the pin.
+
+The independent host oracle constructs second-order Hermite populations and solves the independently derived quadratic by bisection:
+
+    tau * (tau - tau0) = 9 Cs^2 ||Pi_neq|| / (sqrt(2) rho)
+
+There are **736 parameter cases**, covering D2Q9/D3Q19; Cs=0,.08,.16,.24; tau0=.6,.8,1.2; rho=.7,1,1.3; equilibrium, isotropic stress, pure shear, and trace-free diagonal extension; all coordinate planes and both signs; density-scaled Pi and separate fixed-Pi/nonunit-rho probes. The test checks quadratic residuals, closed/default-three/converged-200 iterations, bit-identical unchanged iterative output, and an additional explicit cap-active manufactured probe. Existing g++ and Python stdlib are sufficient; no installation is attempted. Compilation products are temporary. Previously reviewed host maxima were omega error 1.394302e-7 and quadratic residual 1.201202e-7; this is not CUDA fast-math evidence.
+
+## Authorized GPU diagnostic
+
+Use the existing working PyCUDA/NumPy environment and an explicitly selected device, through the same serialized GPU launch owner as the other campaigns:
+
+```sh
+CUDA_VISIBLE_DEVICES="$VERIFIED_IDLE_GPU" python tests/validation/les/run_gpu.py --run-gpu --device 0 --output-dir output/les-gpu
+```
+
+Device 0 is the logical device after CUDA visibility filtering. The output directory must not exist. The runner materializes and verifies the isolated include trees under `output/les-gpu/candidate`, then runs baseline and patched processes sequentially. Each process compiles one SourceModule at a time synchronously and synchronizes each probe. There are no background jobs, worker pools, or parallel compiler calls. No machine contact, device selection, reservation, or environment setup is performed by the runner.
+
+Each version has exactly **48 scalar GPU cases**, 96 total: D2Q9/D3Q19, Cs=.16/0, equilibrium/shear/isotropic/cap-active manufactured stress, and closed/default-three/converged-200 branches. This is the frozen GPU matrix, not the expanded 736-case host matrix. Outputs `baseline.json` and `patched.json` contain raw scalar omega values and device name. Completion means only the diagnostic executed; an independent comparison against the declared host oracle is still required. A failed run leaves partial evidence for inspection and must not be overwritten.
+
+## Interpretation and limits
+
+Full-stress versus deviatoric-stress selection, iterative viscosity cap, iteration count/relaxation, omega guards, collision dispatch, and AMR guards remain unchanged. Closed and iterative paths intentionally remain different for isotropic or cap-active stresses. No settings or Cs defaults change. High stress is a helper diagnostic, not an admissible flow-state claim.
+
+The corrected scalar formula is justified only under the stated stress-strain estimate. MRT full-trace stress does not generally share one shear relaxation rate, so its bulk coupling remains uncertified. Force-corrected non-equilibrium stress and Guo-force interaction also remain uncertified. These manufactured tests are unforced and do not cover full TRT/MRT collision, streaming modes, shifted storage, walls/Jets, flow solutions, or 3D turbulence. Existing guard statements are preserved, not newly comprehensively tested; the main matrix is guard-inactive. No AMR LES support is added or enabled.
+
+Production integration and removal of this temporary candidate fixture are separate decisions after GPU and applicable flow evidence. CPU success alone does not approve a production change.

docs/validation/refined_dfg.md

@@ -0,0 +1,70 @@
+# Matched SRT uniform / refined DFG Re100 preparation
+
+Status: CPU-preflight checked; **not GPU executed or approved to execute**. No physical acceptance or speedup claim. No production source changes. Root owns GPU admission and integration.
+
+## Frozen setup
+
+Canonical source snapshot: integrated commit `cd3a657f9d3833e812c3cca173525f165b48710a`. Production origin remains candidate `47b05bc8abfc957fe876b0c63bdb386e3c6cbaa5` (on `5338864`, on `69e9b78`); production files are byte-identical. The integrated Re100 helper header/PIN records that origin explicitly. Both commit identities are retained in the manifest. `tests/validation/data/refined_dfg/source_manifest.json` hashes all production source files plus the existing DFG geometry/pressure helper, periodicity helper and official reference cycle. An integrated checkout may have a different commit but must have identical pinned file contents. No MRT external-reference run is reused as the matched uniform control.
+
+Both cases: SRT, shifted FP32, double buffer, no LES, no applied force, stationary cylinder, local Zou–He parabolic inlet, halfway y walls, identical pressure-NEQ outlet with **all nine nonequilibrium components damped by 0.5**, backflow clamp disabled. This outlet is not the exact canonical DFG do-nothing condition. Raw cylinder reaction observation is a diagnostic, not applied forcing.
+
+Physical units use D=0.1 m, mean U=1 m/s, ν=0.001 m²/s, density reference=1; domain 2.2×0.41 m, cylinder center (0.2,0.2) m. Uniform D80: 1761×330, dx=0.00125 m, dt=0.0000125 s, ν_lattice=.008. Refined root D40: 881×166, dx=.0025 m, dt=.000025 s, ν_lattice=.004; fine dx/dt/ν match uniform D80. All lattice mean speeds are .01.
+
+Fixed half-open patch **(40,24,320,140)** in root edge coordinates maps to x=[.09875,.79875] m, y=[.0575,.3475] m. The body and about six diameters of downstream wake are fine; wall layers and far wake remain coarse. Bounds are frozen before outcomes, not tuned afterward. Geometry-only leaf-count and nominal collision-work ratios to uniform are ~.419 and ~.321. These omit real launch/transfer/halo/measurement costs and are not measured speedups. The narrow root block height is legal but potentially expensive; do not infer speed from leaf count.
+
+Exact root dimensions are tiled by (by,bx)=(2,881); no padding. Fine allocated shape (240,568), including four-cell halos, uses (8,8). `host_geometry` calls production channel transfer-overlap checks and complete fine cut-link/donor/transfer guards before any CUDA import.
+
+### Half-cell conversion
+
+Uniform integer nodes have physical coordinates (i*dx, (j-.5)*dx). Root edge coordinates therefore map to ((X-.5)*dx_root, (Y-1)*dx_root). Body edge center=(80.5,81), radius=20; wall edges Y=1,165; source planes X=.5,880.5. Fine local body nodes are `(body_edge - fine_origin)/.5 - .5`.
+
+Body and physical wall planes match exactly. The axes have different phases. With fine origin O=(38,22):
+
+- x_f = [O_x+(j+.5)/2-.5] dx40 = (j+75.5) dx80, versus x_uniform = i dx80. Fine x samples have a half-fine-cell (quarter-root-cell) offset.
+- y_f = [O_y+(k+.5)/2-1] dx40 = (k+42.5) dx80, versus y_uniform = (l-.5) dx80. The y samples align exactly for l=k+43.
+
+This difference follows from the inlet's ghost-node plane versus the half-way y-wall planes. The host phase test checks both mappings. Compare interpolated observables, not pointwise arrays or bitwise equality; x-phase error, the different fine collision arithmetic, wall resolution, and coarse/fine transfer effects all contribute to discrepancies. No field-difference acceptance is claimed by this runner. Initial fluid state samples the same analytic parabolic equilibrium as uniform production initialization; root boundary ghosts start at rest. It is not asserted to be bitwise identical across different grids/arithmetic.
+
+## Observations and gates
+
+- Every AMR base step is individually followed by `read_raw_exchange(..., window='last_base_step')`: two fine substeps, root-lattice per-unit-depth impulse integrated over [n,n+1]. `step(n)` alone retains only its last base interval, so it cannot support averaging the whole batch.
+- Uniform `Simulation.run(batch)` / `read_force` gives the mean over that batch; multiply by batch before accumulating. Cd/Cl divide the interval mean reaction by 0.5 U_lattice² D_lattice in each case. Force unit is ρ dx³/dt² per depth, so fine-uniform lattice force is twice root force for the same physical load.
+- Force timestamps are observation-interval midpoints. Pressure uses physical decoded postcollision density at the interval end, extrapolated from fluid-only points one/two **fine** cells outside the cylinder using existing `pressure_probes`. Pressure difference is normalized by ρ_ref U_physical². Existing periodic helpers align pressure onto force cycles.
+- Public AMR downloads exclude nonleaves. Fixed geometry masks, not state-dependent finiteness masks, check all fluid populations and sum ρ dx_level²; covered root cells, body, boundaries and fine halos are excluded. Corrupt NaN fluid cannot disappear from the mass check. Mass is per-unit-depth ρ_ref·m². Uniform uses its physical fluid flags and dx². Different sampling of the circular boundary means initial discrete fluid volume can differ slightly; compare temporal stability, not identical absolute mass.
+- Flux samples root/uniform x-index 2 and -3, summed with dx and physical velocity conversion. Those planes differ by grid-scale offsets; cycle-average inlet/outlet balance is the gate, not direct pointwise flux equality.
+- Dense measurement width Δt*=.02 in the pilot and for t*≥240, otherwise .5. Pilot ends t*=5; full ends t*=300. Same existing five-cycle periodicity, mass, flux, and reference gates are imported without modification. Both official-reference diagnostics and refined-versus-uniform cycle comparisons are written. `matched_case_pass` refers only to matched SRT agreement, not certification of canonical DFG or the broader suite.
+- Safety stop: nonfinite state/reaction, Mach>.2, or density outside [.5,1.5]. GPU durations include required exchange reads and synchronization in stepping; full wall time also includes host measurements. Do not report pure-kernel throughput from these numbers.
+
+## Commands
+
+From the repository root, CPU only:
+
+```sh
+PYTHONPATH=src python tests/unit/test_refined_dfg.py
+python tests/validation/run_refined_dfg.py --mode plan --output /tmp/refined-dfg-plan-new
+```
+
+Fourteen CPU tests are retained in tests/unit/test_refined_dfg.py. Plan JSON is configuration output only; no preparation result files are committed. The initial attempt to use pytest was unavailable in this interpreter; tests use standard-library unittest and NumPy instead.
+
+Only after root channel GPU gates pass and root explicitly admits an idle physical GPU, root may run:
+
+```sh
+CUDA_VISIBLE_DEVICES=<admitted-device> timeout --signal=TERM --kill-after=30s <caller-hard-budget>s python tests/validation/run_refined_dfg.py --mode pilot --gpu-gates-approved --max-wall-seconds <caller-soft-budget> --output <new-pilot-directory>
+CUDA_VISIBLE_DEVICES=<admitted-device> timeout --signal=TERM --kill-after=30s <caller-hard-budget>s python tests/validation/run_refined_dfg.py --mode full --gpu-gates-approved --max-wall-seconds <caller-soft-budget> --pilot-results <completed-pilot-directory> --output <new-full-directory>
+```
+
+`--gpu-gates-approved` is a caller attestation, not proof that GPU tests ran. Full mode additionally requires both matched healthy pilots through t*=5 with identical source hashes, bounds and runner hash. No GPU/Mac/remote operation has been performed for this preparation. Pilot/full outputs must be new/empty. Uniform runs first; an unhealthy case stops the campaign. A full run that fails periodic/matched gates exits nonzero.
+
+## Bounded execution and receipt validation
+
+No pilot throughput is known yet; the caller must set a finite positive `--max-wall-seconds` rather than treating an invented estimate as calibration. After valid pilots, the full-run calibrated budget is 3 × sum_over_cases[startup_seconds + 60 × (pilot_wall_seconds − startup_seconds)]. The full run uses the smaller of that estimate and the caller's explicit ceiling. This uses total measured pilot evolution/observation cost and the full/pilot physical-time ratio (300/5); 3× is a declared safety margin, not a runtime guarantee. The plan records both budgets.
+
+The campaign deadline begins before the first case initialization. Cooperative checks surround initialization, every AMR root step or uniform ≤100-step batch, and measurements. On observed expiry, the runner stops, writes a nonpassing `wall_time_limit` receipt, and exits 3. A blocking CUDA call cannot be interrupted by these checks: the external `timeout` watchdog is required, with a hard budget chosen slightly above the soft budget to permit cleanup. Hard termination may leave partial CSV data and no final receipt; that never qualifies as a completed pilot.
+
+Each case emits `READY` with strict finite JSON and saves `ready.json` only after its first healthy complete observation, after initialization, actual stepping, force readback, macro/pressure/mass/flux paths and CSV flush all succeeded. No early initialization-only READY is emitted.
+
+Full-run pilot validation rejects nonfinite JSON constants and numeric overflow, wrong case/mode/status, nonboolean health, missing/duplicate/out-of-order rows, wrong step counts or observation times, missing numeric observations, health-limit violations, absent/mismatched READY receipts and invalid timing calibration. It requires exactly 250 observations spanning the full dense t*=5 pilot, source/runner hashes and frozen bounds. Tests include the reviewer's exact NaN-endpoint regression and malformed receipt variants. Synthetic test fixtures exist only in temporary directories and are not simulation results.
+
+## Integrated source import guard
+
+The runner's source defaults to this repository root. Before geometry or GPU work, it verifies the pinned source/helper/reference contents and requires the imported CelerisLab package to be exactly `<source>/src/CelerisLab/__init__.py`. An installed DynamisLab copy or another cached checkout is rejected. Integration changes paths/readability and this explicit import assertion; geometry, numerical definitions, gates, and receipt validation remain frozen. Any new path-formatted runner has its own hash, so old preparation pilot receipts cannot authorize a full run of this integrated runner.

docs/validation/refined_dfg_mrt.md

@@ -0,0 +1,71 @@
+# Matched MRT DFG pilot preparation
+
+Preparation only: this test-only extension reuses the existing runner and existing MRT
+operator. GPU admission awaits reviewed MRT capability results; no pilot/full execution
+is implied by CPU preflight. No production, historical SRT manifest, reference data,
+periodic gate, geometry, initialization or observation algorithm is changed here.
+
+## Selection and provenance
+
+Use `--collision MRT` for **both** uniform D80 and refined root D40/fine D80. There are
+no independently selectable collision models per case. Default remains SRT.
+
+MRT verifies `data/refined_dfg/source_manifest_mrt.json`, pinned to reviewed numerical
+source snapshot `3ea131e92c057843034f11a1c574301a2430dfce`, including the shared geometry,
+pressure/cycle helpers and official reference. Test-only commits may change HEAD without
+changing this numerical source pin. Plan, READY, case summaries and comparison separately
+record `checkout_revision` and `checkout_dirty` using existing source-provenance helper;
+the runner hash remains separate. Collision is recorded in every receipt, and full-mode
+validation rejects missing or different collision labels in plan, either summary or either
+READY receipt, in addition to existing source/runner/health/time checks.
+
+The historical SRT manifest remains byte-for-byte unchanged. SRT on the MRT candidate
+checkout deliberately fails that source pin; use a matching historical checkout via
+`--source` for SRT. No fallback or automatic repinning is permitted. Historical SRT
+failure/diagnostic evidence remains attached to its original source and runner hashes;
+it cannot authorize an MRT full run. The existing failed-observation step-reporting
+undercount is not changed in this narrowly scoped selection patch.
+
+## Frozen physical comparison
+
+All settings remain those documented in `refined_dfg.md`: U_lattice=.01, physical mean
+U=1 m/s, D=.1 m, shear ν=.001 m²/s, fixed physical domain/body/wall planes, patch
+(40,24,320,140), shifted FP32 double buffers, no LES/forcing/Jets, finest dx=.00125 m,
+finest dt=.0000125 s, unchanged half-cell frame conversion and axis-specific phase.
+Force interval accumulation, physical leaf mass, pressure interpolation, flux sampling,
+safety thresholds, t*=5 pilot and t*=300 cap are unchanged. Existing accuracy/periodicity
+criteria are imported unchanged. Both MRT cases are fresh runs; old MRT or SRT results
+are not substituted as controls.
+
+Both cases use the **existing MRT pressure-NEQ branch**: only unknown directions q2/6/8
+are extrapolated. This differs from SRT's all-nine .5-damped branch; the retained
+`srt_neq_damp=.5` configuration value is inactive under MRT. Backflow clamp remains off.
+The outlet is still noncanonical relative to exact DFG do-nothing conditions.
+
+The reused MRT operator keeps fixed kinetic rates `s_e=s_eps=s_q=1.2` on all levels;
+only the shear rate follows existing per-level viscosity. Physical bulk relaxation
+therefore differs between coarse and fine levels. Transfer operators and subcycling
+are unchanged. This is the candidate's declared behavior, not a new fully mode-scaled
+MRT transfer scheme. Do not tune rates, the patch or gates after seeing outcomes.
+Capability smoke/parity gates do not establish DFG accuracy or speedup.
+
+## CPU and admission commands
+
+From this checkout:
+
+```sh
+python tests/unit/test_refined_dfg.py
+python tests/validation/run_refined_dfg.py --collision MRT --mode plan --output /tmp/new-mrt-dfg-plan
+```
+
+After root verifies the candidate MRT root/parity/refinement capability results and admits
+an idle device, the paired pilot may use the existing bounds and external watchdog:
+
+```sh
+CUDA_VISIBLE_DEVICES=<admitted-device> timeout --signal=TERM --kill-after=30s <hard-budget>s python tests/validation/run_refined_dfg.py --collision MRT --mode pilot --gpu-gates-approved --max-wall-seconds <soft-budget> --output <new-mrt-pilot-directory>
+```
+
+The flag is caller attestation, not evidence. An unhealthy first case prevents the second.
+Existing strict pilot receipt validation and calibrated wall-time controls remain; full
+mode is not being admitted as part of this preparation. Root must review both healthy
+pilot outcomes and separately decide any full-run admission.

docs/validation/refined_dfg_timing.md

@@ -0,0 +1,58 @@
+# Refined DFG MRT timing harness (measurement only)
+
+`tests/validation/time_refined_dfg.py` times the matched MRT refined/uniform DFG Re100 setup of
+`run_refined_dfg.py` (same configuration, geometry and initial state functions). No numerical,
+physics-gate or production change; no force or accuracy result is produced.
+
+| Variant | Loop | Force reads |
+|---|---|---|
+| A | refined `step(1)` + `read_raw_exchange` per base step | runner-like force-read workload (values discarded) |
+| B | refined `step(1)` only, no host reads (`observe_raw_exchange` stays on) | timing-only |
+| C | refined single `step(N)` | timing-only; ledger keeps the final base interval only |
+| E | uniform `sim.run(<=100)` + `read_force` | runner-like force-read workload (values discarded) |
+| E' | uniform single `sim.run(2N)` | timing-only; at most a whole-window average, different summation order |
+
+- No variant retains a valid force history; A/E omit the runner's interval aggregation and
+  validation, and no variant includes macro/probe/CSV costs. Results are not full benchmark
+  throughput.
+- Status lines: `CONSTRUCTED` (construction/JIT complete) and `WARM_READY` (first warm-up and
+  health check passed) per case.
+- Equal simulated duration: N refined base steps vs 2N uniform D80 steps.
+- Every repeat starts from the same fresh state (refined `initialize`, uniform `snapshot/restore`)
+  and the same warm-up; construction/JIT, warm-up, downloads and parity checks are untimed.
+- The actual stepping stream is synchronized explicitly before and after each timed loop; the
+  wall timer (`time.perf_counter`) is the only source. No CUDA-event span is called kernel time.
+- `--max-wall-seconds` is required for GPU runs (outer timeout, checked between variants and
+  every 100 steps in per-step loops).
+- Final populations and NaN masks must be bitwise identical to the first A repeat (A/B/C) or the
+  first E repeat (E/E'); refined and uniform grids are never compared. Leaf/fluid populations
+  must be finite. Physical health (finite leaf/fluid macros, rho in [0.5, 1.5], max Mach <= 0.2,
+  the existing runner limits) is checked after warm-up and after each timed window. Matching NaN
+  is accepted only as a storage mask; any infinity or level-count mismatch fails parity. All
+  parity/health checks are untimed.
+- Cases run sequentially (uniform, then refined) in one process with startup serialized;
+  variants are interleaved within each repeat. A-B and B-C are measured comparative
+  differences under GPU variability, not exact causal decompositions.
+
+Usage (root selects one verified idle GPU):
+
+    PYTHONPATH=src python -m unittest tests/unit/test_time_refined_dfg.py
+    python tests/validation/time_refined_dfg.py --output <new> --plan
+    CUDA_VISIBLE_DEVICES=<gpu> python tests/validation/time_refined_dfg.py --output <new> --max-wall-seconds <s>
+
+Defaults: 2000 base steps, 200 warm-up base steps, 3 repeats. Profiler capture and the
+`observe_raw_exchange=False` variant are deferred until these measurements exist.
+
+## A versus observation-window ledger (`tests/validation/time_window_dfg.py`)
+
+Measurement-only comparison on the same shifted-MRT refined setup: A (per-base `step(1)` +
+`read_raw_exchange`, summed per 80-base-step interval), W (`start_exchange_window`, `step(80)`,
+one window read) and W1 (window with 80 x `step(1)`, isolating the read pattern from call
+batching). Same fresh state, warm-up and simulated duration; populations must be bitwise equal
+to the first A repeat and per-interval total impulses within the documented engineering
+tolerance, all outside timing. The candidate source is recorded (checkout revision, dirty flag,
+file hashes); frozen refined-DFG manifests/results are not used or changed.
+
+    PYTHONPATH=src python -m unittest tests/unit/test_time_window_dfg.py
+    python tests/validation/time_window_dfg.py --output <new> --plan
+    CUDA_VISIBLE_DEVICES=<gpu> python tests/validation/time_window_dfg.py --output <new> --max-wall-seconds <s>

docs/validation/refined_dfg_window.md

@@ -0,0 +1,117 @@
+# 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.

docs/validation/taylor_green.md

@@ -0,0 +1,161 @@
+# Periodic 2D Taylor–Green AMR campaign (prepared, not GPU-qualified)
+
+This validation harness complements DFG Re100 and Jet/body tests. It measures
+smooth 2D periodic decay and errors crossing fixed refinement interfaces at
+Re_L=100 and 1000. It does **not** certify 3D turbulence, LES, Jet performance,
+wall conditions, dynamic refinement or general high-Re flows.
+
+## Reference and conventions
+
+Primary implementation-author documentation, checked 2026-10-18:
+- TensorMesh, exact velocity and pressure with a consistent phase:
+  https://docs.tensor-mesh.com/example_gallery/fluid/taylor_green.html
+- AeroSim Nassu, 2D decay, energy and lattice-length Re definition:
+  https://docs.aerosim.io/nassu/validation/analytical/04_taylor_green_vortex_2d/README.html
+
+We use the TensorMesh phase, rescaled to length L=N root cells:
+
+    k = 2*pi/L; A(t) = U*exp(-2*nu*k*k*t)
+    ux = -A*cos(k*x)*sin(k*y)
+    uy =  A*sin(k*x)*cos(k*y)
+    p/rho0 = -A*A/4 * (cos(2*k*x)+cos(2*k*y))
+    E = <|u|^2>/2 = U*U/4 * exp(-4*nu*k*k*t)
+
+Pressure is kinematic, with rho0=1. A global velocity sign reversal leaves
+pressure unchanged; exchanging sine/cosine without the corresponding pressure
+phase can reverse its sign. CPU tests independently check momentum residuals.
+The nonlinear acceleration is a pressure gradient, **not zero**; the AeroSim
+page's prose calling advection zero is not adopted. Do not mix phase variants
+from different references. The formulas above are verified by substitution,
+not by trusting a copied pressure expression.
+
+Re_L=U*L/nu, not Re_k=U/(nu*k)=Re_L/(2*pi). U=.03 in lattice units,
+Ma=U/cs=.0519615, cs^2=1/3, nu_root=.03*N/Re_L. Acoustic refinement uses
+h_l=dt_l=2^-l: lattice velocity stays U, nu_l=2^l*nu_root and
+ tau_l=.5+3*nu_l. The worst root tau is .50288 (N32/Re1000), omega=1.98855,
+inside the existing config guard. No viscosity clamping or guard override.
+
+All initial arrays are physical FP64 equilibrium populations, supplied to the
+public shifted-FP32 postcollision-G initializer. rho=1+3p at each true cell
+center. These are valid equilibrium postcollision states, but do not include
+Chapman–Enskog nonequilibrium stress; startup acoustic/kinetic error remains in
+the measurements and is shared with uniform baselines. The incompressible
+reference is not an exact finite-Mach LBM solution. This is why resolution alone
+need not remove the full error floor.
+
+## Geometry and workload
+
+All patches use level-wide union form, so origins are zero, including fine
+arrays with holes. Coordinates are (index+.5)*2^-level. Metrics integrate only
+ACTIVE leaves, each weighted by 4^-level. Covered cells and halo cells never
+enter norms or mass. Geometry tests prove exact single coverage at root-cell
+resolution. All blocks are 8x8, and both root dimensions are periodic.
+
+At each root N=32,64:
+- 2 levels: L1 rectangle (N/8,N/8,7N/8,3N/4), in L0 indices.
+- 3 levels: same L1 plus L2 rectangle (3N/4,N/2,3N/2,5N/4), in L1 indices.
+
+These off-axis boundaries cross nonzero flow and gradients rather than sitting
+only on symmetry or stagnation lines. Whole geometry scales with N.
+
+16 cases: at each Re, uniform N=32,64,128,256 plus AMR (root32/root64)x(depth2/depth3).
+Each AMR case therefore has both a same-root uniform baseline and a uniform
+baseline at its finest spacing. Uniform N is its own lattice length, so nu and
+step count are scaled to represent the same nondimensional solution.
+Samples t*=tU/L = 0,.12,.24,.36,.48. End time is 16*N base steps, a meaningful
+.48 domain turnover or 3.016 vortex-scale turnover times (scale 1/k).
+At Re1000 energy decays about 7.3%; at Re100 about 53.1%. No plots or full fields;
+each case writes five diagnostic rows and provenance, incrementally.
+
+## Running (GPU owner must schedule launches)
+
+CPU checks, from the repository root:
+
+    PYTHONPATH=src python -m unittest discover -s tests/validation/taylor_green -p 'test_*.py' -v
+
+One GPU case, on the scheduled worker after checking occupancy:
+
+    CUDA_VISIBLE_DEVICES=<physical-id> python tests/validation/taylor_green/run_case.py --repo /path/to/reviewed/checkout --re 100 --n 32 --depth 1 --output output/taylor_green/re100_n32_d1.json
+
+Depth 1 is uniform. Run uniform cases before AMR for each Re; inspect baseline
+screening failures before proceeding. For a complete matrix, repeat the uniform
+call with N=32,64,128,256 and AMR calls with N=32,64 / depth=2,3, at each Re.
+Use serial process startup on the parent's assigned Horsea GPUs. This harness
+does not schedule or acquire GPUs. No GPU was used during preparation.
+
+    python tests/validation/taylor_green/assess.py output/taylor_green/re*_n*_d*.json --output output/taylor_green/assessment.json
+
+The local API/geometry review used clean staging commit
+cd3a657f9d3833e812c3cca173525f165b48710a. This is **not** a claim of results on d79
+or any historical commit. Each runtime output records actual Git HEAD/dirty
+state, an aggregate source-tree hash, plus SHA256 of all harness Python files. Assessment refuses dirty checkouts and mixed source
+or harness identities. Keep reports outside the checkout or .gitignore them so
+new outputs do not change its dirty flag between cases. The source-tree hash excludes bytecode caches; production qualification requires
+a clean checkout.
+The runner uses the existing PeriodicBlockStepper / FixedPatchStepper periodic
+paths only. It does not depend on the new channel-root implementation.
+
+## Preregistered assessment, before any GPU results
+
+All sampled times must satisfy finite screening ceilings:
+- Relative composite velocity L2 <= 5%
+- Relative globally gauge-adjusted pressure L2 <= 15%
+- Relative kinetic-energy error <= 5%
+- Composite mass drift from downloaded t0 <= 1e-5
+
+These are screening budgets, not literature-certified tolerances. Acceptance
+also requires all 16 cases, common source/harness, correct nondimensional times
+and viscosity, and baseline-relative checks on worst post-startup-sample errors:
+- AMR error <= max(2 * same-root uniform error, declared numerical floor).
+- Root64 AMR error <= max(.9 * root32 AMR error, floor), for each depth/Re.
+- Uniform256 error <= max(.9 * uniform32 error, floor).
+
+Floors: velocity .002, pressure .02, energy .004. They are declared low-Mach /
+equilibrium-startup budgets, not fitted to observed results. Ma^2=.0027 motivates
+their scale; it is an asymptotic expectation, not a proof of those coefficients.
+The coarse baseline sets the AMR budget because much of the domain remains
+coarse. The finest uniform error and AMR/fine ratio are always reported, with no
+claim that partial refinement should match a fully fine domain. A pass below a
+floor is bounded accuracy, not a measured convergence order. Report errors and
+ratios even for a pass. Failure requires diagnosis or a separately preregistered
+follow-up, never retroactive tolerance tuning. Higher Re is deliberately absent;
+Re100/1000 must first be stable, resolved and reviewed.
+
+Diagnostics use one global pressure gauge, direct cell-center analytic values,
+kinetic energy per unit reference mass, and actual leaf cell areas. Composite
+midpoint quadrature introduces a small initial energy integration error, retained
+rather than subtracted. Mass drift is relative to downloaded t0, so density
+initialization and mixed-grid quadrature do not masquerade as time drift.
+
+## Pilot scheduling and transfer-consistency scope
+
+Start with one uniform case and one matched AMR case; the 16-case matrix is a
+qualification plan, not authorization to launch every case automatically. The
+GPU owner reviews the pilot before expanding it. Each process prints a flushed
+READY only after initialization, a real base step exercising every level's
+kernel/halo/transfer path, and a finite positive-density download check. That
+step belongs to the measured trajectory; it is not discarded warmup. PROGRESS
+messages contain each of the five diagnostic samples. READY alone is not an
+accuracy pass. Reports include per-level active cells, hops and collision updates.
+
+The complete matrix costs 768,540,672 active collision updates and 21,504 root
+intervals, excluding ghost streaming, halos, transfers and diagnostic work.
+Uniform N256 is the largest case (268,435,456 updates / 4096 intervals per Re).
+AMR N64/depth3 needs 50,987,008 updates / 1024 intervals. These are work counts,
+not GPU wall-time estimates. Baseline comparisons remain available on failed
+screens and partial pilots; absent/nonfinite operands are null, never passing.
+
+Acoustic viscosity scaling and unchanged lattice velocity do not by themselves
+prove nonequilibrium-stress consistency across refinement interfaces. A smooth
+collocated Chapman–Enskog postcollision nonequilibrium has a (tau-1)*h factor;
+the existing implementation instead uses volumetric piecewise-constant explosion
+and stream-only ghosts. Whether that actual transfer construction achieves the
+needed stress accuracy is an unresolved question for this pilot to measure.
+It is not a proven defect, and a collocated-state scaling factor must not be
+inserted into this different transfer operator without a separate derivation
+and validation. This campaign measures the current operator and makes no
+theoretical stress-consistency certification or production-kernel change.
+
+## Repository integration
+
+The four Python harness files remain together under tests/validation/taylor_green, so runtime provenance hashes precisely this harness directory. Formatting changes produce a new harness identity; preparation and integrated receipts must not be mixed. All analytic definitions, numerical floors, assessment gates, sample times, and source-import assertions are unchanged. Production source is unchanged from the cd3 snapshot; these periodic tests do not waive the separate channel GPU gate.

docs/validation/uniform_les_flow.md

@@ -0,0 +1,90 @@
+# Bounded uniform-grid LES flow validation: prepared, GPU NOT RUN
+
+## Status and scope
+
+Prepared for independent review, then an explicitly authorized Horsea run only. No production files were edited, no normalization patch was applied to a full solver checkout, and no GPU was used. This is a small end-to-end **wall-bounded, x-periodic** shear-decay test, not a fully periodic 2D test. It exercises the actual production Simulation → Stepper → OneStep → Smagorinsky → SRT dispatch and double-buffer pull streaming, plus existing halfway bounce-back walls.
+
+The original fully periodic-y plan is unsupported at the pinned revision: both `one_step_double.cu:90` and `one_step_esopull.cu:133` replace wall-adjacent incoming populations for every fluid node on y=1 and NY-2 regardless of its neighboring flags. `tests/validation/run_poiseuille.py:1–10` already documents this. Merely changing all flags to FLUID does not remove this behavior. The present test deliberately matches those real walls; it does not modify the kernels or claim a periodic-y public API.
+
+Only unforced SRT, D2Q9, FP32 shifted storage and double-buffer streaming are included. No MRT/TRT, force correction, EsoPull, AMR, Jet, 3D turbulence or physical LES coefficient calibration is certified. In continuum this unidirectional incompressible shear is trace-free; small finite-Mach/discretization stresses in the LBM are not asserted to vanish exactly. The underlying scalar-helper audit remains the cleaner normalization isolation.
+
+## Exact source contract
+
+Baseline is explicitly repinned to the production snapshot in `cd3a657f9d3833e812c3cca173525f165b48710a`, whose reviewed AMR-channel source origin is `47b05bc8abfc957fe876b0c63bdb386e3c6cbaa5`. This new experiment does not inherit historical d79 GPU/flow acceptance. The original preparation remains associated with d79; its results are not rewritten.
+
+`tests/validation/data/les_flow/source_pins.json` records all 101 tracked production source files from that snapshot. The runner checks every hash before importing CelerisLab or touching a GPU. It accepts only:
+
+- `--variant baseline`: all baseline hashes, including helper SHA256 `ff7f000297ee0817e255ad9fcb6a13b647e3ddd5b206518d35f38d2895a9f501`.
+- `--variant corrected`: the same source bytes except helper SHA256 `a3db46c2e7d27530b2d1436e65cdbed0b72cc7e047bfbeef2a640877271b51aa`, from the independently reviewed `tests/validation/les/data/smagorinsky_normalization.patch` artifact.
+
+The runner records the actual checkout commit and exact imported package. It never applies a patch itself. Run it against separate isolated full checkouts. The patch candidate's minimal header tree is not a runnable solver checkout. A source mismatch is a blocker, not permission to regenerate pins from an arbitrary new checkout.
+
+Relevant pinned implementation evidence:
+
+- `tests/integration/test_numerical_gpu.py:24–85`: equilibrium construction, installation of spatial postcollision state, count=1 adapter, raw population observation and x-periodic/walled flags.
+- `tests/validation/run_poiseuille.py:29–78`: production Simulation use with periodic x, halfway y walls and downloaded populations.
+- `src/CelerisLab/lbm/kernels/core/layout.cuh:87–104`: actual modulo neighbors.
+- `src/CelerisLab/lbm/kernels/boundary/bounce_back.cuh:18–38`: incoming populations copied from opposite local input directions.
+- `src/CelerisLab/lbm/kernels/operators/helpers.cuh:53–61`: LES effective omega feeds actual SRT collision.
+- `src/CelerisLab/cuda/compiler_v2.py:56–95`: compiler snapshots into private temporary build directories; package sources are not rewritten.
+
+## Geometry, units and initial state
+
+8×34 nodes: 8 periodic-x columns, 32 fluid rows, 2 ghost-wall rows. Relative to the bottom physical wall, fluid centers are y=0.5,...,31.5; physical halfway walls are y=0 and 32. Every x edge fluid node is explicitly FLUID; all top/bottom ghost nodes are SOLID|BC_WALL. Thus unused inlet/outlet configuration has no inlet/outlet flags to act on. There are no bodies, Jets or external forces.
+
+Lattice units: dx_LBM=dt_LBM=1, rho=1, nu=0.02, tau0=0.56, U=0.04, H=32. Initial u_x(y)=U sin(pi y/H), u_y=0. The maximum Mach number is 0.0693. Height-based Re=U H/nu=64; a wavelength-based Re would differ and is not used. No dimensional physical length/time/viscosity is asserted without a user-supplied unit mapping.
+
+Initialize equilibrium populations, encode shifted FP32, upload both DB buffers and set completed-count=1 following the existing integration-test adapter. That count is storage metadata: physical elapsed time starts at 0 after installation. Observe density and momentum directly from current postcollision populations, adding the descriptor weights in float64; do not mix in cached macro fields. This uses a clearly labeled validation-only raw state/flag adapter, not a promised public `set_periodic` or `set_velocity_profile` API.
+
+Cases: LES enabled/closed-form with Cs=0 (molecular control), Cs=.16 (ordinary-coefficient sanity), then Cs=1 (amplified normalization diagnostic). Cs=1 is intentionally not a physically recommended SGS coefficient. Initial peak modeled nu_t/nu = Cs² Δ² U(pi/H)/nu = 0.19635; estimated effective tau remains near 0.56–0.5718, far from omega guards. Standard default Cs=.16 yields a much weaker signal at these safe parameters and is not used to make a decisive short-run normalization claim. No defaults are changed.
+
+Observe at elapsed steps 519, 1038, 2075, approximately 0.1, 0.2, 0.4 molecular decay times. Three cases total 6225 measured advancing launches plus 3 warm-up launches per checkout (6228 total), three snapshots each. Population buffers contain only 272×9 FP32 entries each (about 9.6 KiB), apart from ordinary driver/compiler/context overhead. No frames, trajectories or heavy output. Full result JSON is a few tens of KiB. Runtime depends on compilation/device; no performance claim is made.
+
+## Independent continuum reference
+
+For u=(u(y),0), |S|=sqrt(2 S:S)=|du/dy|. Therefore
+
+    du/dt = d/dy [(nu + (Cs Delta)^2 |du/dy|) du/dy],
+    u(0,t)=u(H,t)=0.
+
+`tests/validation/les_flow_oracle.py` integrates this equation directly with centered finite-volume face fluxes and SSPRK2, at 128 and 256 cells on the same physical H=32 domain. Stability step size uses the nonlinear flux derivative nu+2(Cs Delta)^2|gradient|. Boundary face gradients use the zero Dirichlet value across a half cell. It does not import or reproduce the LBM quadratic/helper. A separate fixed-n=256 test halves the CFL factor from .4 to .2 for Cs=0,.16,1 at every checkpoint, requiring relative changes below 1e-8; measured maximum is 1.8141e-10. This isolates temporal error from the spatial-refinement test.
+
+Crucially the SGS filter Delta=1 stays fixed as the CPU oracle mesh changes from dy=.25 to .125. Confusing oracle spacing with filter width would change the PDE and invalidate convergence. Future LBM grid refinement also needs an explicit physical-unit/filter-width scaling contract; this artifact does not silently reinterpret Cs or Delta when resizing H.
+
+Cs=0 is checked directly against U sin(pi y/H) exp[-nu(pi/H)^2 t]. The nonlinear reference includes evolving higher harmonics, rather than assuming it remains a sine. At the final time, host oracle predicts 5.1706% SGS reduction in the fundamental amplitude and 1.5409% full-profile separation between standard and old coefficient conventions. The old convention reference is computed by changing continuum Cs to Cs/2^(1/4), purely as a diagnostic; it does not replace standard acceptance.
+
+## Predeclared criteria (do not tune after seeing GPU results)
+
+- Initial decoded profile relative L2 <= 1e-5; otherwise no advancing test.
+- Molecular Cs=0 profile error against analytic decay <= 0.003 at every checkpoint.
+- Cs=1 full-profile error against standard nonlinear oracle <= 0.005 at every checkpoint.
+- Oracle 128/256-grid interpolated relative difference <= 8e-5 at every checkpoint.
+- Relative error in SGS fundamental-amplitude decrement <= 0.15 at the last two checkpoints. Decrement is measured from actual Cs=0 amplitude minus actual Cs=1 amplitude; reference uses analytic Cs=0 minus the nonlinear oracle. The first checkpoint remains a transient diagnostic for this increment gate.
+- Fluid mean-density drift <= 5e-5, max |u_y| <= 1e-5 and x-column velocity spread <= 1e-6 at every checkpoint; finite populations, strictly positive finite fluid density and finite decoded velocity/profile/diagnostics required throughout observations, including startup and warm-up.
+
+Reasons: molecular 0.3% leaves room for finite-lattice dispersion, equilibrium-start kinetic transient and FP32 error at H=32; nonlinear 0.5% is substantially below the predicted 1.54% old-vs-standard separation. The 15% increment tolerance is below the old convention's approximately 29% viscosity-coefficient deficit, while allowing continuum/lattice differences. Directly subtracting the two measured amplitudes reduces common lattice error. Oracle convergence is over 60 times tighter than the nonlinear profile bound. These are declared engineering test gates, not GPU-validated uncertainty estimates; a failure requires diagnosis/refinement and an explicitly revised experiment, never a post-hoc tolerance edit to obtain a pass.
+
+Both baseline and candidate are judged against the same standard convention. Baseline is expected to fail SGS criteria if the flow reproduces the scalar finding; an exit 1 with valid evidence is useful. The runner reports old-convention profile error but never masks baseline failure. Candidate passing alone is insufficient if baseline does not demonstrate meaningful discrimination. Review both results and source pins together.
+
+## Host verification and later GPU commands
+
+From the repository root, using existing Python/NumPy and the existing pytest environment:
+
+    PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python -m pytest -q tests/unit/test_les_flow_oracle.py tests/unit/test_les_flow_runner.py
+
+Nine tests cover analytic decay, independent-oracle mesh convergence, symmetry/positivity/energy decay, filter invariance, fixed-grid timestep halving, signal discrimination, invalid density/velocity rejection, source pins/candidate/tamper rejection and the no-GPU-without-opt-in CLI guard. The integrated tests preserve those checks. No PyCUDA import or GPU run is required for them. Cs=.16 uses the same 0.5% full-profile safety/sanity bound; its SGS increment is not a discriminatory normalization gate.
+
+The source-guard tests materialize temporary candidate headers with the existing reviewed LES preparation tool; the GPU entrypoint uses `tests/validation/run_uniform_les_flow.py`, `tests/validation/les_flow_oracle.py`, and `tests/validation/data/les_flow/source_pins.json` in that repository layout.
+
+After review, make isolated full baseline and corrected checkouts of the exact base. Apply only `tests/validation/les/data/smagorinsky_normalization.patch` to the corrected checkout; do not edit the benchmark/production tree. On authorized Horsea, with existing NumPy, PyCUDA, nvcc and driver, run sequentially and select the authorized physical GPU explicitly:
+
+    CUDA_VISIBLE_DEVICES=<physical-GPU> PYTHONDONTWRITEBYTECODE=1 python tests/validation/run_uniform_les_flow.py --run-gpu --device 0 --root <isolated-baseline> --variant baseline --output <new-evidence-dir>/baseline.json
+    CUDA_VISIBLE_DEVICES=<physical-GPU> PYTHONDONTWRITEBYTECODE=1 python tests/validation/run_uniform_les_flow.py --run-gpu --device 0 --root <isolated-corrected> --variant corrected --output <new-evidence-dir>/corrected.json
+
+`--device 0` is the logical ordinal within CUDA_VISIBLE_DEVICES. Do not use a shell `&&` between these: baseline's expected standard-criterion failure must not suppress the corrected run. Existing output files are refused. A JSON `READY` line is printed separately for each case only after source verification, compilation, initialization, raw-state installation, one actual advancing OneStep launch, post-warm-up macro validation, complete restoration of both DB buffers/flags/count to the initial state, profile readback and CUDA synchronization. It gives source identity, device, Cs, warm-up/reset confirmation, installed-profile error and maximum measured steps. This is the first trustworthy startup checkpoint, not a statement that the physics passed. `DONE` is printed after all three cases and all criteria; failures/compile errors before that remain incomplete runs.
+
+Deliver both JSON files and stdout/stderr with artifact hashes. Review before any production integration. AMR LES guards remain untouched.
+
+## Isolated candidate preparation
+
+Use the current validation commit for two separate full checkouts, preserving the baseline. In the corrected checkout only, apply `tests/validation/les/data/smagorinsky_normalization.patch` with `git apply`; do not commit that experimental production change or update the pins. The runner requires exactly the baseline bytes plus the reviewed helper hash. The header-only scalar diagnostic tree is insufficient for this end-to-end flow. Baseline and corrected commands must run as separate Python processes; package import caching must never combine their implementations. Both reject an imported CelerisLab package outside the explicitly supplied checkout, including an installed DynamisLab copy. Retain the actual checkout commit, variant, exact header hash, and experimental source label with each result.

examples/fixed_patch_circle.py

@@ -1,9 +1,9 @@
 """Public API demo: fixed 2:1 patch with a stationary, optionally actuated circle.
 
 From this checkout, after checking the selected physical GPU is idle:
-    PYTHONPATH="$PWD/src" CUDA_VISIBLE_DEVICES=0 python examples/fixed_patch_circle.py --fine-block 16 20
-    ... --speed -0.002 --fine-block 16 20 --mode slot_reservoir
-Omit --fine-block for the (equivalent) dense fine storage.
+    PYTHONPATH="$PWD/src" CUDA_VISIBLE_DEVICES=0 python examples/fixed_patch_circle.py
+    ... --speed -0.002 --mode slot_reservoir
+Both levels use blocked storage (--base-block, --fine-block tiles).
 
 A short smoke run (default 128 coarse steps): it shows setup, stepping and
 fluid-only diagnostics, not a developed flow, accuracy or long-time stability.
@@ -71,8 +71,10 @@ def main():
     parser.add_argument("--mode", choices=("periodic", "slot_reservoir"), default="periodic")
     parser.add_argument("--speed", type=float, default=.002,
                         help="normal surface velocity, coarse lattice units (+ blows, - sucks, 0 passive)")
-    parser.add_argument("--fine-block", type=int, nargs=2, metavar=("BY", "BX"),
-                        help="blocked fine storage; must divide the whole fine allocation (32 x 40 here)")
+    parser.add_argument("--base-block", type=int, nargs=2, metavar=("BY", "BX"), default=(12, 8),
+                        help="root tile; must divide the 24 x 32 root")
+    parser.add_argument("--fine-block", type=int, nargs=2, metavar=("BY", "BX"), default=(16, 20),
+                        help="fine tile; must divide the whole fine allocation (32 x 40 here)")
     parser.add_argument("--steps", type=int, default=128)
     args = parser.parse_args()
     if args.steps < 0:
@@ -86,20 +88,20 @@ def main():
     body = SimObject(0, geometry=CircleGeometry(*CENTER, RADIUS), center=CENTER, radius=RADIUS,
                      surface_actuation=spec)
     cfg = config(args.mode)
-    fine_block = tuple(args.fine_block) if args.fine_block else None
     # The caller owns the CUDA context; the stepper must be closed first (the
     # nested with-statement does that).
     with CudaContext(0) as context, FixedPatchStepper(
-            cfg, BOUNDS, context=context, coarse_boundary=args.mode,
-            fine_objects=[body], fine_block=fine_block) as run:
+            cfg, context=context, coarse_boundary=args.mode, refinements=[BOUNDS],
+            level_blocks=[tuple(args.base_block), tuple(args.fine_block)],
+            level_objects=[(), (body,)]) as run:
         p = run.patch
         # Rest equilibrium is already postcollision G, so no initial collision is
         # needed. Non-leaf entries (covered, ghost, solid) are discarded by initialize.
         rest = np.asarray(compute_feq_d2q9(1.0, 0.0, 0.0), np.float32)[:, None, None]
         run.initialize(np.broadcast_to(rest, (9, *p.coarse_shape)),
                        np.broadcast_to(rest, (9, *p.fine_shape)))
-        storage = f"blocked {fine_block}" if fine_block else "dense"
-        print(f"mode={args.mode} fine storage={storage} speed={args.speed:+g} "
+        storage = f"blocked root {tuple(args.base_block)} fine {tuple(args.fine_block)}"
+        print(f"mode={args.mode} storage={storage} speed={args.speed:+g} "
               f"(fine allocation {p.fine_shape[0]}x{p.fine_shape[1]}, fine origin {p.fine_origin})")
         masks = leaf_masks(run, args.mode)
         start = leaf_diagnostics(*run.download(), masks)

examples/fixed_patch_jet.py

@@ -31,6 +31,7 @@ from CelerisLab.lbm.refinement import ACTIVE
 from CelerisLab.lbm.refinement_stepper import FixedPatchStepper
 
 BOUNDS, AMPLITUDE, WIDTH = (16, 4, 32, 28), .02, 12
+LEVEL_BLOCKS = [(12, 8), (8, 8)]  # blocked storage: 48x48 root, 56x40 fine window
 TIMES, MAX_MACH, MAX_SECONDS = (0, 300, 1200), .1, 120
 
 
@@ -132,7 +133,8 @@ def main():
                   lattice_model='D2Q9', collision='SRT', streaming='double_buffer',
                   store_precision='FP32', ddf_shifting=False, les_enabled=False)
     report = dict(config=dict(nx=48, ny=48, bounds=BOUNDS, W=WIDTH, A=AMPLITUDE, nu=.1,
-                              rho=1, tau_coarse=.8, tau_fine=1.1, coarse_boundary='slot_reservoir'),
+                              rho=1, tau_coarse=.8, tau_fine=1.1, coarse_boundary='slot_reservoir',
+                              level_blocks=LEVEL_BLOCKS),
                   guards=dict(check_every=50, positive_density=True, finite=True,
                               max_Mach=MAX_MACH, max_seconds=MAX_SECONDS,
                               timing='cooperative checks, not an exact interruption deadline'),
@@ -148,8 +150,9 @@ def main():
                   samples=[], status='running', last_synchronized_coarse_step=0)
     start, run = time.monotonic(), None
     try:
-        with CudaContext(0) as context, FixedPatchStepper(cfg, BOUNDS, context=context,
-                coarse_boundary='slot_reservoir') as run:
+        with CudaContext(0) as context, FixedPatchStepper(cfg, context=context,
+                coarse_boundary='slot_reservoir', refinements=[BOUNDS],
+                level_blocks=LEVEL_BLOCKS) as run:
             p = run.patch
             masks = [np.ones(p.coarse_shape, bool), p.fine_kind == ACTIVE]
             masks[0][[0, -1]] = False

examples/fixed_periodic_patch.py

@@ -16,7 +16,7 @@ from CelerisLab.config import load_lbm_config
 from CelerisLab.cuda.context import CudaContext
 from CelerisLab.lbm.equilibrium import compute_feq_d2q9, compute_macro_from_ddf
 from CelerisLab.lbm.refinement import ACTIVE
-from CelerisLab.lbm.refinement_stepper import PeriodicPatchStepper
+from CelerisLab.lbm.refinement_stepper import FixedPatchStepper
 
 
 def shear_equilibrium(shape, origin, dx, period):
@@ -48,7 +48,8 @@ def main():
                   nx=16, ny=16, viscosity=.1, velocity=1e-3, rho=1.0,
                   lattice_model="D2Q9", collision="SRT", streaming="double_buffer",
                   store_precision="FP32", ddf_shifting=False, les_enabled=False)
-    with CudaContext(0) as context, PeriodicPatchStepper(cfg, (4, 4, 12, 12), context=context) as run:
+    with CudaContext(0) as context, FixedPatchStepper(cfg, context=context, refinements=[(4, 4, 12, 12)],
+                                                           level_blocks=[(16, 16), (24, 24)]) as run:
         p = run.patch
         coarse = shear_equilibrium(p.coarse_shape, (0, 0), 1.0, cfg.ny)
         fine = shear_equilibrium(p.fine_shape, p.fine_origin, .5, cfg.ny)

src/CelerisLab/body/jets.py

@@ -9,6 +9,11 @@ whose links are evaluated; callers convert frames/units before evaluation.
 One physical link (receiver, direction) may be driven by at most one jet, and
 one jet may drive the links of only one body (checked at assignment, any amplitude).
 
+``condition`` names the prescribed boundary type. Only ``"velocity"`` (the
+default: amplitude is a signed lattice velocity, not a flow rate) is
+implemented; ``"pressure"`` is reserved and rejected at construction, before
+any amplitude validation, so it never reaches assignment or a kernel.
+
 Edge rule: the lateral bound |s| < 1 is exclusive (the profile vanishes
 there for parabolic/quartic); Sector r_min/r_max and Tube 0 <= along <= length
 are inclusive. Jets are immutable; an amplitude change replaces the Jet.
@@ -25,6 +30,9 @@ from dataclasses import dataclass, replace
 
 import numpy as np
 
+CONDITIONS = ("velocity",)
+RESERVED_CONDITIONS = ("pressure",)
+
 PROFILES = {
     "uniform": lambda s: np.ones_like(s),
     "parabolic": lambda s: 1 - s*s,
@@ -122,7 +130,8 @@ class Parallel:
 
 @dataclass(frozen=True)
 class Jet:
-    """Region (Sector|Tube), field (Radial|Parallel), profile name, signed amplitude.
+    """Region (Sector|Tube), field (Radial|Parallel), profile name, signed amplitude,
+    prescribed boundary condition (velocity only; pressure reserved).
 
     Frozen: change amplitude with ``with_amplitude`` (validated, new object);
     the cached per-link shapes stay valid because region/field/profile cannot change.
@@ -131,8 +140,14 @@ class Jet:
     field: object
     profile: str = "uniform"
     amplitude: float = 0.0
+    condition: str = "velocity"
 
     def __post_init__(self):
+        # The condition decides what amplitude and field mean: check it first.
+        if self.condition in RESERVED_CONDITIONS:
+            raise NotImplementedError(f"{self.condition} jets are reserved but not implemented")
+        if self.condition not in CONDITIONS:
+            raise ValueError(f"Jet condition must be one of {CONDITIONS + RESERVED_CONDITIONS}")
         if self.profile not in PROFILES:
             raise ValueError(f"Jet profile must be one of {sorted(PROFILES)}")
         _finite(self.amplitude)
@@ -189,24 +204,33 @@ def edge_to_node_frame(points):
 
 
 def surface_link_velocity(objects, cfg, flags, fluid_idx, dir, body_id, rx, ry,
-                          jets=(), hits=None):
+                          jets=(), hits=None, *, _shifted_blocked=False):
     """Per-link prescribed surface velocity (n, 2) FP32 and aperture mask.
 
+    See _surface_links, which also returns the unit-amplitude jet shapes.
+    """
+    return _surface_links(objects, cfg, flags, fluid_idx, dir, body_id, rx, ry, jets, hits,
+                          _shifted_blocked=_shifted_blocked)[:2]
+
+
+def _surface_links(objects, cfg, flags, fluid_idx, dir, body_id, rx, ry,
+                   jets=(), hits=None, *, _shifted_blocked=False):
+    """(velocity, aperture, jet shape, jet id); the last two are None without jets.
+
     Host-only and storage-neutral: rows follow the given physical cut-link
-    order. Returns (None, None) when neither an object carries surface
+    order. Returns all None when neither an object carries surface
     actuation nor a jet is given. Jets need true FP64 ``hits`` (n, 2) and may
     not share a link with each other or with a legacy aperture.
+    Shifted storage is privately enabled only by the all-blocked stepper.
     """
     enabled = [obj for obj in objects if obj.surface_actuation is not None]
     if not enabled and not jets:
-        return None, None
-    from ..lbm.descriptors import FLUID, SOLID
-    if np.any((flags[fluid_idx] & FLUID) == 0) or np.any(flags[fluid_idx] & SOLID):
-        raise ValueError("Surface cut links must have active fluid receivers")
-    if len(np.unique(fluid_idx.astype(np.uint64)*cfg.nq+dir)) != len(dir):
-        raise ValueError("Surface boundary requires unique cut-link writers")
+        return None, None, None, None
+    from .preprocess.flag_overlay import validate_cut_link_ownership
+    validate_cut_link_ownership(flags, fluid_idx, dir, cfg.nq)
     surface_velocity = np.zeros((len(dir), 2), np.float32)
     surface_aperture = np.zeros(len(dir), bool)
+    shape = jet_id = None
     for obj in enabled:
         obj.validate_surface_actuation(cfg)
         selected = body_id == obj.obj_id
@@ -219,7 +243,9 @@ def surface_link_velocity(objects, cfg, flags, fluid_idx, dir, body_id, rx, ry,
         if hits is None or len(hits) != len(dir):
             raise ValueError("Jets require true hit points row-aligned with the cut links")
         if (cfg is None or not cfg.is_d2q9 or cfg.store_precision != "FP32"
-                or cfg.streaming != "double_buffer" or cfg.ddf_shifting):
+                or cfg.streaming != "double_buffer"
+                or (cfg.ddf_shifting and not (_shifted_blocked is True
+                    and cfg.collision == "SRT" and not cfg.les_enabled))):
             raise ValueError("Jets require D2Q9/FP32/unshifted/double_buffer")
         shape, jet_id = jet_link_shapes(jets, hits)
         driven = jet_id >= 0
@@ -237,4 +263,4 @@ def surface_link_velocity(objects, cfg, flags, fluid_idx, dir, body_id, rx, ry,
             raise ValueError("Jet overlaps a SurfaceActuation aperture")
         surface_velocity[driven] = jet_link_velocity(jets, shape, jet_id)[driven]
         surface_aperture |= driven
-    return surface_velocity, surface_aperture
+    return surface_velocity, surface_aperture, shape, jet_id

src/CelerisLab/body/manager.py

@@ -11,7 +11,7 @@ Responsibilities:
 
 Design::
   Packed ``obs`` layout matches ``generate_config(..., n_objects=count)`` and
-  ``config_obs.h`` macros. Host sizing uses :func:`~CelerisLab.cuda.compiler_v2.obs_layout`.
+  ``config_obs.h`` macros. Host sizing uses :func:`~CelerisLab.cuda.compiler.obs_layout`.
 
   Pending edits are lightweight: only the "intent" (add / remove) is stored.
   All derived quantities (flags, compact lists, GPU buffers) are built at
@@ -27,8 +27,8 @@ import pycuda.driver as cuda
 
 from .objects import SimObject
 from .registry import BodyRegistry
-from .preprocess.flag_overlay import merge_flag_masks
-from ..cuda.compiler_v2 import obs_layout
+from .preprocess.flag_overlay import merge_flag_masks, validate_cut_link_ownership
+from ..cuda.compiler import obs_layout
 from ..cuda.obs_layout import ObsLayout
 from ..lbm.descriptors import (
     FLUID, SOLID,
@@ -369,9 +369,9 @@ class ObjectManager:
 
         Args:
             objects: List of SimObject instances to process.
-            domain_flags: Optional uint16 flags for donor-cell classification.
+            domain_flags: Optional uint16 flags for receiver/donor classification.
             sensor_cell_counts_out: Int array to fill with per-object sensor
-                cell counts.  If provided, ``fill(0)`` is called first.
+                cell counts after the full geometry has passed validation.
             hits_out: List that receives one FP64 (n, 2) array of true hit
                 points row-aligned with the cut-link columns (for Jets).
 
@@ -394,8 +394,8 @@ class ObjectManager:
         active_fluid = ((domain_flags & FLUID) != 0) & ((domain_flags & SOLID) == 0)
         force_owners: set[int] = set()
 
-        if sensor_cell_counts_out is not None:
-            sensor_cell_counts_out.fill(0)
+        sensor_counts = (np.zeros_like(sensor_cell_counts_out)
+                         if sensor_cell_counts_out is not None else None)
 
         ez = None
         if self.cfg and self.cfg.is_d3q19:
@@ -430,9 +430,9 @@ class ObjectManager:
                 if len(cells) > 0:
                     s_cells.append(cells)
                     s_ids.append(ids)
-                    if (sensor_cell_counts_out is not None
-                            and 0 <= obj.obj_id < sensor_cell_counts_out.size):
-                        sensor_cell_counts_out[obj.obj_id] = int(len(cells))
+                    if (sensor_counts is not None
+                            and 0 <= obj.obj_id < sensor_counts.size):
+                        sensor_counts[obj.obj_id] = int(len(cells))
             if obj.is_force_region and hasattr(obj, 'get_sensor_list'):
                 cells, ids = obj.get_sensor_list(self.nx, self.ny, self.nz)
                 keep = active_fluid[cells]
@@ -461,8 +461,9 @@ class ObjectManager:
         r_fr_ids = np.concatenate(fr_ids) if fr_ids else np.zeros(0, dtype=np.int32)
 
         r_hit = np.concatenate(cl_hit) if cl_hit else np.zeros((0, 2))
-        if hits_out is not None:
-            hits_out.append(r_hit)
+        # Passive walls need the same ownership guarantees as driven walls.
+        # Overlapping solids are not a supported union-boundary operation.
+        validate_cut_link_ownership(domain_flags, r_idx, r_dir, self.nq)
         if self.jets or any(obj.surface_actuation is not None for obj in objects):
             # Reject unresolved apertures/ownership before sync or restart mutates state.
             from ..lbm.curved_links import CurvedLinkSoA
@@ -470,6 +471,11 @@ class ObjectManager:
             links.assign_host(r_idx, r_dir, r_q, r_bid, r_rx, r_ry, r_rz, r_fallback)
             links.assign_surface(objects, self.cfg, domain_flags, jets=self.jets, hits=r_hit)
 
+        if sensor_cell_counts_out is not None:
+            sensor_cell_counts_out[:] = sensor_counts
+        if hits_out is not None:
+            hits_out.append(r_hit)
+
         return (
             r_idx, r_dir, r_q, r_bid,
             r_rx, r_ry, r_rz, r_fallback,
@@ -487,8 +493,6 @@ class ObjectManager:
                 the caller has already prepared and uploaded the final flag field
                 for this geometry, such as during initialization.
         """
-        self._telemetry_field = field
-
         next_flags = self.build_flags(field.build_channel_flags()) if rebuild_flags else field.flag
         hits = []
 
@@ -499,6 +503,7 @@ class ObjectManager:
             fr_cells, fr_obj_id,
         ) = self.build_compact_lists(domain_flags=next_flags, hits_out=hits)
 
+        self._telemetry_field = field
         if rebuild_flags:
             field.flag = next_flags
             field.upload_flags()

src/CelerisLab/body/preprocess/flag_overlay.py

@@ -1,6 +1,6 @@
 # CelerisLab/body/preprocess/flag_overlay.py
 """
-Flag overlay: merge per-object flag masks onto a clean domain base.
+Flag overlay and cut-link ownership checks against the merged domain.
 """
 
 from __future__ import annotations
@@ -12,6 +12,15 @@ import numpy as np
 from ...lbm.descriptors import FLUID, SOLID, SENSOR_FLAG, FRC_REGION
 
 
+def validate_cut_link_ownership(flags, fluid_idx, directions, nq):
+    """Reject solid receivers and multiple writers to one population."""
+    if np.any((flags[fluid_idx] & FLUID) == 0) or np.any(flags[fluid_idx] & SOLID):
+        raise ValueError("Cut links must have active fluid receivers")
+    writers = fluid_idx.astype(np.uint64) * nq + directions
+    if len(np.unique(writers)) != len(directions):
+        raise ValueError("Boundary requires unique cut-link writers")
+
+
 def merge_flag_masks(
     base: np.ndarray,
     masks: List[np.ndarray],

src/CelerisLab/config.py

@@ -7,7 +7,7 @@ Two JSON files:
   config_body.json – object list
 
 LBMConfig / BodyConfig are plain dataclasses; they translate to
-macro dicts consumed by `cuda/compiler_v2.py` for header generation.
+macro dicts consumed by `cuda/compiler.py` for header generation.
 """
 
 import json

src/CelerisLab/configs/CONFIG.md

@@ -60,14 +60,14 @@ Python `config.py` 只负责读取和校验，不是配置位置。显式配置
 
 **`lbm/kernels/config/*.h` 由编译器根据 `LBMConfig` 自动生成，请勿手改。**
 
-仓库中检入的 `config/*.h` 可能是历史版本。`compiler_v2.generate_config` 会复制 kernel 源码到独立临时构建目录，并在副本中生成配置；不会改写包内头文件或 PTX。返回目录须显式传给 `compile_kernel(build_dir=...)`，编译结果与配置摘要均保存在该目录。`Simulation` 负责目录清理；直接使用编译器的调用者须调用 `cleanup_build_dir()`。跳过生成配置直接编译仓库中的 `kernel_v2.cu` 属不受支持用法。
+仓库中检入的 `config/*.h` 可能是历史版本。`compiler.generate_config` 会复制 kernel 源码到独立临时构建目录，并在副本中生成配置；不会改写包内头文件或 PTX。返回目录须显式传给 `compile_kernel(build_dir=...)`，编译结果与配置摘要均保存在该目录。`Simulation` 负责目录清理；直接使用编译器的调用者须调用 `cleanup_build_dir()`。跳过生成配置直接编译仓库中的 `uniform.cu` 属不受支持用法。
 
 ```
 config_lbm.json
   ↓  load_lbm_config()
 config.py:LBMConfig       (读取 + 校验)
   ↓  to_macros()
-cuda/compiler_v2.py       (独立构建目录中生成 config/*.h)
+cuda/compiler.py          (独立构建目录中生成 config/*.h)
   ↓
 config_grid.h             → NX, NY, NZ, NT, LATTICE_MODEL；
                             DIM / NQ 由 LATTICE_MODEL 推导写入（与 grid.lattice_model 一致，非 JSON 顶层字段）

src/CelerisLab/cuda/__init__.py

@@ -1,4 +1,4 @@
 """CUDA build helpers (compilation itself does not need a live context)."""
-from . import compiler_v2 as compiler
+from . import compiler
 
 __all__ = ["compiler"]

src/CelerisLab/cuda/compiler.py

@@ -1,11 +1,13 @@
-# CelerisLab/cuda/compiler_v2.py
+# CelerisLab/cuda/compiler.py
 """
 Kernel configuration, compilation, and module loading.
 
-Workflow:
+Owners call build_module(cfg, entry, arch=...), then set_params(module, omega, ...).
+build_module runs, in a private directory it removes afterwards:
   1. build_dir = generate_config(lbm_cfg, n_objects) — isolated source snapshot
-  2. compile_kernel(arch, build_dir=build_dir)       — nvcc -ptx kernel_v2.cu
+  2. compile_kernel(arch, source=entry, build_dir=build_dir) — nvcc -ptx
   3. load_module(ptx_path)              — PyCUDA module from PTX
+Entries: uniform.cu (uniform grid), blocked.cu (every blocked level, single or refined).
 """
 
 from __future__ import annotations
@@ -16,7 +18,6 @@ import shutil
 import tempfile
 import hashlib
 import json
-from contextvars import ContextVar
 from dataclasses import asdict
 from pathlib import Path
 from typing import Optional
@@ -33,9 +34,6 @@ _KERNEL_DIR = os.path.join(
 )
 
 
-_last_build_dir = ContextVar("celeris_last_build_dir", default=None)
-_last_ptx_path = ContextVar("celeris_last_ptx_path", default=None)
-
 
 def kernel_path(filename: str) -> str:
     return os.path.join(_KERNEL_DIR, filename)
@@ -54,14 +52,16 @@ def _write(path: str, content: str):
 
 
 def generate_config(cfg: LBMConfig, n_objects: int = 0,
-                    *, build_root: Optional[str] = None) -> str:
+                    *, build_root: Optional[str] = None, block_root_bc: int = 0) -> str:
     """Snapshot kernels and render headers in a fresh private directory.
 
-    Returns its path. Pass it explicitly to compile_kernel for interleaved
-    builds. Legacy generate_config(); compile_kernel() remains context-local.
-    The caller owns cleanup_build_dir() once the loaded module is no longer
+    Returns its path; pass it to compile_kernel(build_dir=...). The caller owns cleanup_build_dir() once the loaded module is no longer
     needed for recompilation/debugging. No package files are changed.
+    block_root_bc specializes a blocked root module; fine/dense builds use 0.
     """
+    if (isinstance(block_root_bc, bool) or not isinstance(block_root_bc, int)
+            or block_root_bc not in (0, 1, 2)):
+        raise ValueError("block_root_bc must be an integer mode 0, 1 or 2")
     macros = cfg.to_macros()
     if isinstance(n_objects, bool) or not isinstance(n_objects, int) or n_objects < 0:
         raise ValueError("n_objects must be a nonnegative integer")
@@ -71,20 +71,19 @@ def generate_config(cfg: LBMConfig, n_objects: int = 0,
     try:
         shutil.copytree(_KERNEL_DIR, build_dir, dirs_exist_ok=True,
                         ignore=shutil.ignore_patterns("*.ptx", "*.cubin", "*.tmp"))
-        _render_config(macros, n_objects, os.path.join(build_dir, "config"))
+        _render_config(macros, n_objects, os.path.join(build_dir, "config"),
+                       block_root_bc=block_root_bc)
         digest = hashlib.sha256()
         for path in sorted(Path(build_dir).rglob("*")):
             if path.is_file():
                 digest.update(str(path.relative_to(build_dir)).encode())
                 digest.update(path.read_bytes())
         metadata = {"source_sha256": digest.hexdigest(), "config": asdict(cfg),
-                    "n_objects": n_objects}
+                    "n_objects": n_objects, "block_root_bc": block_root_bc}
         _write(os.path.join(build_dir, ".celeris-build"), json.dumps(metadata, sort_keys=True))
     except BaseException:
         shutil.rmtree(build_dir)
         raise
-    _last_build_dir.set(build_dir)
-    _last_ptx_path.set(None)
     return build_dir
 
 
@@ -96,12 +95,9 @@ def cleanup_build_dir(build_dir: Optional[str]) -> None:
     if path == Path(_KERNEL_DIR).resolve() or not (path / ".celeris-build").is_file():
         raise ValueError("Refusing to remove a directory not owned by the compiler")
     shutil.rmtree(path)
-    if _last_build_dir.get() == str(build_dir):
-        _last_build_dir.set(None)
-        _last_ptx_path.set(None)
 
 
-def _render_config(m: dict, n_objects: int, cdir: str):
+def _render_config(m: dict, n_objects: int, cdir: str, *, block_root_bc: int = 0):
     _write(os.path.join(cdir, "config_grid.h"), f"""{_HEADER}\
 // Layer: Global / Grid
 #ifndef CELERIS_CONFIG_GRID_H
@@ -165,6 +161,9 @@ def _render_config(m: dict, n_objects: int, cdir: str):
 #define STORE_PRECISION  {m['STORE_PRECISION']}
 #define USE_DDF_SHIFTING {m['USE_DDF_SHIFTING']}
 
+// Internal blocked root mode: 0=periodic/fine, 1=slot/reservoir, 2=channel.
+#define BLOCK_ROOT_BC {block_root_bc}
+
 #define USE_LES {m['USE_LES']}
 #define LES_CS  {m['LES_CS']}
 #define LES_CLOSED_FORM {m['LES_CLOSED_FORM']}
@@ -241,13 +240,9 @@ def _render_config(m: dict, n_objects: int, cdir: str):
 # ---------------------------------------------------------------------------
 # Compilation
 # ---------------------------------------------------------------------------
-def compile_kernel(arch: str = "sm_70", source: str = "kernel_v2.cu",
-                   output: Optional[str] = None, *,
-                   build_dir: Optional[str] = None) -> str:
-    """Compile a generated private source snapshot; never use package headers."""
-    # A failed attempt must not make implicit load_module() reuse older code.
-    _last_ptx_path.set(None)
-    build_dir = build_dir or _last_build_dir.get()
+def compile_kernel(arch: str = "sm_70", source: str = "uniform.cu",
+                   output: Optional[str] = None, *, build_dir: str) -> str:
+    """Compile the snapshot in build_dir (from generate_config); never package headers."""
     if not build_dir or not (Path(build_dir) / ".celeris-build").is_file():
         raise RuntimeError("Call generate_config() and pass its build_dir before compiling")
     root = Path(build_dir).resolve()
@@ -272,23 +267,36 @@ def compile_kernel(arch: str = "sm_70", source: str = "kernel_v2.cu",
     finally:
         if os.path.exists(tmp):
             os.unlink(tmp)
-    _last_ptx_path.set(str(dst))
     return str(dst)
 
 
-def load_module(ptx_path: Optional[str] = None):
-    """Load explicit PTX or the last PTX compiled in this Python context."""
-    ptx_path = ptx_path or _last_ptx_path.get()
-    if not ptx_path:
-        raise RuntimeError("No compiled PTX; call compile_kernel() first")
+def load_module(ptx_path: str):
+    """Load one compiled PTX file as a new PyCUDA module."""
     import pycuda.driver as cuda
     return cuda.module_from_file(ptx_path)
 
 
-# ---------------------------------------------------------------------------
-# Back-compat helpers (used by test scripts)
-# ---------------------------------------------------------------------------
+def build_module(cfg: LBMConfig, source: str, *, arch: str, n_objects: int = 0,
+                 block_root_bc: int = 0):
+    """Generate, compile and load one private module; the build directory is removed.
 
-def compile_kernel_v2(arch: str = "sm_70") -> str:
-    """Alias for compile_kernel() kept for test-script compatibility."""
-    return compile_kernel(arch=arch)
+    The single build path of every owner (Simulation, FixedPatchStepper levels).
+    Each call returns a NEW module: callers must not share it, because its
+    globals (d_params, ...) are mutable per module.
+    """
+    build_dir = generate_config(cfg, n_objects=n_objects, block_root_bc=block_root_bc)
+    try:
+        return load_module(compile_kernel(arch, source=source, build_dir=build_dir))
+    finally:
+        cleanup_build_dir(build_dir)
+
+
+def set_params(module, omega: float, fx: float = 0.0, fy: float = 0.0, fz: float = 0.0,
+               n_objects: int = 0) -> None:
+    """Write the module's __constant__ LBMParams (core/params.cuh layout)."""
+    import struct
+    import pycuda.driver as cuda
+    ptr, size = module.get_global("d_params")
+    if size != struct.calcsize("=ffffI"):
+        raise RuntimeError("LBMParams host/device layout mismatch")
+    cuda.memcpy_htod(ptr, struct.pack("=ffffI", omega, fx, fy, fz, n_objects))

src/CelerisLab/cuda/obs_layout.py

@@ -2,7 +2,7 @@
 """Packed ``obs`` buffer layout for force / torque / sensor telemetry.
 
 Usage::
-    Host code (e.g. ``ObjectManager``) and ``compiler_v2.generate_config`` must use
+    Host code (e.g. ``ObjectManager``) and ``compiler.generate_config`` must use
     the same ``dim`` and ``n_objects`` so allocation sizes match device macros.
 
 Design::

src/CelerisLab/lbm/block_stepper.py

@@ -1,272 +0,0 @@
-# CelerisLab/lbm/block_stepper.py
-"""Opt-in periodic backend for one BlockLayout2D level, optional static circles.
-
-D2Q9/SRT/FP32 unforced double buffers. Each step refreshes every halo from
-its owner core, then pulls/collides core cells into the spare buffer, then
-swaps. Only halo pair tables are uploaded; dense ownership stays on the host.
-The caller owns the CudaContext and must close this backend before it.
-Optional ``objects`` are stationary passive circles (static linear BFL via
-receiver-local staging: halo refresh -> cut links -> pull, no copy between).
-No force/actuation readout, motion, walls, refinement, checkpoint or runtime
-parameter mutation; wall/slot/inlet fields in cfg are ignored.
-"""
-from dataclasses import replace
-from numbers import Integral
-import struct
-from threading import RLock
-
-import numpy as np
-import pycuda.driver as cuda
-
-from ..cuda import compiler_v2 as compiler
-from .blocks import NQ, BlockLayout2D, blocked_link_tables
-from .descriptors import D2Q9_EX, D2Q9_EY, FLUID, SOLID
-
-MAX_GRID_DIM = 65535  # CUDA gridDim.y/z limit (rows, blocks)
-
-
-def _static_circles(layout, objects):
-    """Host tables for stationary circles; rejects before any CUDA work.
-
-    Every periodic neighbor of every fluid core is inspected, including domain
-    edges that CircleGeometry does not enumerate, so clipped or incomplete
-    geometry cannot pass. Each physical link has one receiver-owning block.
-    """
-    from ..body.geometry.circle import CircleGeometry
-
-    ny, nx = layout.shape
-    flags = np.full(ny * nx, FLUID, np.uint16)
-    for obj in objects:
-        if (type(obj.geometry) is not CircleGeometry or obj.is_sensor or obj.is_force_region
-                or obj.surface_actuation is not None
-                or any(getattr(obj.state, name) != 0 for name in ("vx", "vy", "omega"))
-                or any(vars(obj.control).values())):
-            raise ValueError("Block bodies must be stationary passive circles")
-        cx, cy = obj.geometry.center
-        radius = obj.geometry._radius
-        if not np.isfinite([cx, cy, radius]).all() or radius <= 0:
-            raise ValueError("Block circle center/radius must be finite with radius > 0")
-        mask = obj.geometry.build_flag_mask(nx, ny)
-        solid = (mask & SOLID) != 0
-        if not solid.any() or np.any(flags[solid] & SOLID):
-            raise ValueError("Block circles must be resolved and disjoint")
-        flags[solid] = mask[solid]
-    solid = ((flags & SOLID) != 0).reshape(ny, nx)
-    if solid[[0, -1]].any() or solid[:, [0, -1]].any():
-        raise ValueError("Block circles must not touch the domain edge")
-    links = [link for obj in objects
-             for link in obj.geometry.build_cut_links(nx, ny, domain_flags=flags)]
-    def source(r, q):
-        y, x = divmod(r, nx)
-        return (y + D2Q9_EY[q]) % ny, (x + D2Q9_EX[q]) % nx
-    receivers = {(int(link.fluid_idx), int(link.dir)) for link in links}
-    required = {(int(r), q) for r in np.flatnonzero(~solid.ravel())
-                for q in range(1, NQ) if solid[source(r, q)]}
-    if len(receivers) != len(links) or receivers != required:
-        raise ValueError("Cut links must cover every fluid pull from a solid exactly once")
-    tables, _ = blocked_link_tables(
-        layout, flags, np.array([link.fluid_idx for link in links], np.uint32),
-        np.array([link.dir for link in links], np.uint8),
-        np.array([link.q for link in links], np.float32),
-        np.array([link.fallback for link in links], np.uint8))
-    return dict(solid=solid, **tables)
-
-
-class PeriodicBlockStepper:
-    """G->G stepping of Q-major (9, ny, nx) postcollision populations.
-
-    On a device/launch failure the instance becomes unusable: close and
-    recreate it rather than assuming a partially advanced buffer rolled back.
-    """
-    def __init__(self, cfg, layout, *, context, objects=()):
-        if not isinstance(layout, BlockLayout2D) or layout.periodic != (True, True):
-            raise ValueError("PeriodicBlockStepper requires a doubly periodic BlockLayout2D")
-        checked = replace(cfg)
-        checked.validate()
-        if (not checked.is_d2q9 or checked.collision != "SRT"
-                or checked.streaming != "double_buffer" or checked.store_precision != "FP32"
-                or checked.ddf_shifting or checked.les_enabled
-                or (checked.ny, checked.nx) != layout.shape):
-            raise ValueError("PeriodicBlockStepper requires matching D2Q9/SRT/FP32/"
-                             "unshifted/double_buffer config without LES")
-        ly, lx = layout.local_shape
-        pairs = len(layout.halo_dst)
-        tpb = checked.threads_per_block
-        if layout.nblocks > MAX_GRID_DIM or ly > MAX_GRID_DIM or not 0 < pairs < 2**31:
-            raise ValueError("block count, block rows or halo pairs exceed launch limits")
-        objects = tuple(objects)  # an empty iterable takes the body-free path
-        self.boundary = _static_circles(layout, objects) if objects else None
-        links = 0 if self.boundary is None else len(self.boundary["cell"])
-        if links >= 2**31:
-            raise ValueError("cut links exceed launch limits")
-        self.layout = layout
-        self.ctx = context
-        self._links = links
-        self._link_grid = ((links + tpb - 1) // tpb, 1)
-        # Wall/slot fields are not applied; neutralize them like the fine patch level.
-        self._local_cfg = replace(checked, nx=lx, ny=ly, y_wall_bc="bounce_back", top_wall_bc="velocity",
-                                  wall_slot_width=0, wall_normal_velocity=0.0, velocity=0.0)
-        self._block = (tpb, 1, 1)
-        self._grid = ((lx + tpb - 1) // tpb, ly, layout.nblocks)
-        self._copy_grid = ((pairs + tpb - 1) // tpb, 1)
-        self._bytes = int(np.prod(layout.blocked_shape)) * 4
-        self._lock = RLock()
-        self._status = "new"
-        self._step_count = 0
-        self._allocations = []
-        self._stream = self._module = self._copy = self._step = self._curved = None
-        self._tables = {}
-        with self.ctx.activate():
-            try:
-                free, _ = cuda.mem_get_info()
-                tables = sum(a.nbytes for k, a in (self.boundary or {}).items() if k != "solid")
-                if 2 * self._bytes + layout.halo_dst.nbytes + layout.halo_src.nbytes + tables > free:
-                    raise MemoryError("blocked buffers exceed free device memory")
-                self._stream = cuda.Stream()
-                config = self._local_cfg
-                config.validate()
-                if not np.isclose(config.omega, 1 / (3 * checked.viscosity + .5), rtol=1e-14, atol=0):
-                    raise RuntimeError("block omega/tau mismatch")
-                build = compiler.generate_config(config)
-                try:
-                    ptx = compiler.compile_kernel(self.ctx.sm_arch, source="blocks.cu", build_dir=build)
-                    module = compiler.load_module(ptx)
-                finally:
-                    compiler.cleanup_build_dir(build)
-                ptr, size = module.get_global("d_params")
-                if size != struct.calcsize("=ffffI"):
-                    raise RuntimeError("LBMParams host/device layout mismatch")
-                cuda.memcpy_htod(ptr, struct.pack("=ffffI", config.omega, 0, 0, 0, 0))
-                self._module = module
-                self._current = self._allocate(self._bytes)
-                self._spare = self._allocate(self._bytes)
-                self._dst = self._upload(layout.halo_dst)
-                self._src = self._upload(layout.halo_src)
-                self._copy = module.get_function("BlockHaloCopy")
-                self._step = module.get_function("BlockStep")
-                if self.boundary is not None:
-                    self._tables = {k: self._upload(a) for k, a in self.boundary.items() if k != "solid"}
-                    self._curved = module.get_function("BlockCurvedBoundary")
-            except BaseException:
-                try:
-                    self.close()
-                except Exception:
-                    pass  # Preserve the original construction failure.
-                raise
-
-    def _allocate(self, size):
-        pointer = cuda.mem_alloc(size)
-        self._allocations.append(pointer)
-        return pointer
-
-    def _upload(self, array):
-        array = np.ascontiguousarray(array)
-        pointer = self._allocate(array.nbytes)
-        cuda.memcpy_htod(pointer, array)
-        return pointer
-
-    def _require(self, *states):
-        if self._status not in states:
-            raise RuntimeError(f"Block stepper is {self._status}; expected {' or '.join(states)}")
-
-    @property
-    def step_count(self):
-        return self._step_count
-
-    def initialize(self, g):
-        """Upload dense G_0; the spare buffer starts NaN so stale halos cannot hide."""
-        with self._lock, self.ctx.activate():
-            self._require("new", "ready")
-            dense = np.array(g, dtype=np.float32, order="C", copy=True)
-            if dense.shape != (NQ, *self.layout.shape):
-                raise ValueError("Expected a Q-major (9, ny, nx) array")
-            fluid = np.ones(self.layout.shape, bool) if self.boundary is None else ~self.boundary["solid"]
-            if not np.isfinite(dense[:, fluid]).all() or (dense[:, fluid].sum(axis=0) <= 0).any():
-                raise ValueError("Fluid populations must be finite with positive density")
-            dense[:, ~fluid] = np.nan  # Solid cores are deliberately invalid.
-            blocked = self.layout.to_blocked(dense)
-            spare = np.full_like(blocked, np.nan)
-            try:
-                cuda.memcpy_htod(self._current, blocked)
-                cuda.memcpy_htod(self._spare, spare)
-                self._step_count = 0
-                self._status = "ready"
-            except BaseException:
-                self._status = "failed"
-                raise
-
-    def step(self, n=1):
-        """Advance n steps: halo refresh, then core pull/collide, per step."""
-        if isinstance(n, bool) or not isinstance(n, Integral) or n < 0:
-            raise ValueError("n must be a nonnegative integer")
-        with self._lock, self.ctx.activate():
-            self._require("ready")
-            kw = dict(block=self._block, stream=self._stream)
-            try:
-                self._status = "advancing"
-                for _ in range(n):
-                    self._copy(self._current, self._dst, self._src,
-                               np.uint32(len(self.layout.halo_dst)), grid=self._copy_grid, **kw)
-                    if self._curved is not None:
-                        t = self._tables
-                        self._curved(self._current, t["block"], t["cell"], t["dir"], t["q"],
-                                     t["fallback"], np.uint32(self._links), np.uintp(0),  # no actuation
-                                     grid=self._link_grid, **kw)
-                    self._step(self._current, self._spare, np.uint32(self.layout.halo),
-                               self._tables.get("flags", np.uintp(0)), np.uintp(0),  # no kind
-                               grid=self._grid, **kw)
-                    self._stream.synchronize()
-                    self._current, self._spare = self._spare, self._current
-                    self._step_count += 1
-                self._status = "ready"
-            except BaseException:
-                self._status = "failed"
-                raise
-
-    def download(self):
-        """Return dense (9, ny, nx) FP32 core populations; no host cache."""
-        with self._lock, self.ctx.activate():
-            self._require("ready")
-            blocked = np.empty(self.layout.blocked_shape, np.float32)
-            try:
-                cuda.memcpy_dtoh(blocked, self._current)
-            except BaseException:
-                self._status = "failed"
-                raise
-            return self.layout.to_dense(blocked)
-
-    def close(self):
-        """Release owned resources; retain them for retry if context activation fails."""
-        with self._lock:
-            if self._status == "closed":
-                return
-            self._status = "failed"
-            with self.ctx.activate():
-                self._status = "closed"
-                error = None
-                try:
-                    if self._stream is not None:
-                        self._stream.synchronize()
-                except Exception as exc:
-                    error = exc
-                self._copy = self._step = self._curved = self._module = None
-                self._tables = {}
-                for pointer in self._allocations:
-                    try:
-                        pointer.free()
-                    except Exception as exc:
-                        error = error or exc
-                self._allocations.clear()
-                self._stream = None
-                if error is not None:
-                    raise error
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *exc):
-        try:
-            self.close()
-        except Exception:
-            if exc[0] is None:
-                raise

src/CelerisLab/lbm/blocks.py

@@ -31,7 +31,7 @@ receiver-local boundary values: the solid's owner-core copy of that slot may
 be stale, which is distinct from the unique core ownership of stored state.
 No moving geometry is implied.
 """
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from numbers import Integral
 from types import SimpleNamespace
 
@@ -373,3 +373,84 @@ def blocked_link_tables(layout, flags, fluid_idx, dir, q, fallback):
                   dir=columns[1].astype(np.uint8), q=columns[2].astype(np.float32),
                   fallback=columns[3].astype(np.uint8))
     return tables, mapped
+
+
+# One blocked level as FixedPatchStepper builds and launches it (any depth). Raw argument orders of the blocked.cu kernels live only here.
+
+def level_config(cfg, layout, tau):
+    """Kernel config of one blocked level: NX/NY = block window incl. halo.
+
+    Physical wall/slot/inlet fields are neutralized; a blocked root gets them
+    from its module globals (d_block_wall/d_block_channel) instead.
+    """
+    ly, lx = layout.local_shape
+    local = replace(cfg, nx=lx, ny=ly, y_wall_bc="bounce_back", top_wall_bc="velocity",
+                    wall_slot_width=0, wall_normal_velocity=0.0, velocity=0.0)
+    local.validate()
+    if not np.isclose(local.omega, 1 / tau, rtol=1e-14, atol=0):
+        raise RuntimeError("block level omega/tau mismatch")
+    return local
+
+
+def launch_halo_copy(kernel, buffer, dst, src, count, *, block, stream):
+    """BlockHaloCopy over ``count`` uploaded (dst, src) block-cell pairs."""
+    kernel(buffer, dst, src, np.uint32(count),
+           grid=((count + block[0] - 1) // block[0], 1), block=block, stream=stream)
+
+
+def launch_curved_boundary(kernel, buffer, tables, count, *, block, stream,
+                           velocity=None, rx=None, ry=None, raw=None):
+    """BlockCurvedBoundary on uploaded link tables; None = no actuation/observation."""
+    none = np.uintp(0)
+    kernel(buffer, tables["block"], tables["cell"], tables["dir"], tables["q"], tables["fallback"],
+           np.uint32(count), none if velocity is None else velocity,
+           none if rx is None else rx, none if ry is None else ry, none if raw is None else raw,
+           grid=((count + block[0] - 1) // block[0], 1), block=block, stream=stream)
+
+
+def static_circle_tables(layout, objects):
+    """Host tables for stationary circles; rejects before any CUDA work.
+
+    Every periodic neighbor of every fluid core is inspected, including domain
+    edges that CircleGeometry does not enumerate, so clipped or incomplete
+    geometry cannot pass. Each physical link has one receiver-owning block.
+    """
+    from ..body.geometry.circle import CircleGeometry
+    from .descriptors import FLUID, SOLID
+
+    ny, nx = layout.shape
+    flags = np.full(ny * nx, FLUID, np.uint16)
+    for obj in objects:
+        if (type(obj.geometry) is not CircleGeometry or obj.is_sensor or obj.is_force_region
+                or obj.surface_actuation is not None
+                or any(getattr(obj.state, name) != 0 for name in ("vx", "vy", "omega"))
+                or any(vars(obj.control).values())):
+            raise ValueError("Block bodies must be stationary passive circles")
+        cx, cy = obj.geometry.center
+        radius = obj.geometry._radius
+        if not np.isfinite([cx, cy, radius]).all() or radius <= 0:
+            raise ValueError("Block circle center/radius must be finite with radius > 0")
+        mask = obj.geometry.build_flag_mask(nx, ny)
+        solid = (mask & SOLID) != 0
+        if not solid.any() or np.any(flags[solid] & SOLID):
+            raise ValueError("Block circles must be resolved and disjoint")
+        flags[solid] = mask[solid]
+    solid = ((flags & SOLID) != 0).reshape(ny, nx)
+    if solid[[0, -1]].any() or solid[:, [0, -1]].any():
+        raise ValueError("Block circles must not touch the domain edge")
+    links = [link for obj in objects
+             for link in obj.geometry.build_cut_links(nx, ny, domain_flags=flags)]
+    def source(r, q):
+        y, x = divmod(r, nx)
+        return (y + D2Q9_EY[q]) % ny, (x + D2Q9_EX[q]) % nx
+    receivers = {(int(link.fluid_idx), int(link.dir)) for link in links}
+    required = {(int(r), q) for r in np.flatnonzero(~solid.ravel())
+                for q in range(1, NQ) if solid[source(r, q)]}
+    if len(receivers) != len(links) or receivers != required:
+        raise ValueError("Cut links must cover every fluid pull from a solid exactly once")
+    tables, _ = blocked_link_tables(
+        layout, flags, np.array([link.fluid_idx for link in links], np.uint32),
+        np.array([link.dir for link in links], np.uint8),
+        np.array([link.q for link in links], np.float32),
+        np.array([link.fallback for link in links], np.uint8))
+    return dict(solid=solid, **tables)

src/CelerisLab/lbm/channel.py

@@ -0,0 +1,54 @@
+"""Host contract for the blocked root's uniform SRT/MRT channel boundary.
+
+Boundary ghosts are evolved state, but are not physical fluid leaves. Halo
+ownership remains periodic to reproduce the uniform kernel's wrapped pulls.
+No boundary closure is applied on a fine level.
+"""
+import numpy as np
+
+
+def channel_masks(shape):
+    """Physical fluid and bulk-transfer masks in GLOBAL root coordinates."""
+    ny, nx = shape
+    fluid = np.zeros(shape, bool)
+    fluid[1:ny - 1, 1:nx - 1] = True
+    bulk = fluid.copy()
+    bulk[[1, ny - 2]] = False
+    return fluid, bulk
+
+
+def validate_channel_config(cfg, blocks):
+    if any(block is None for block in blocks):
+        raise ValueError("channel requires all-blocked levels")
+    if (cfg.inlet_scheme != "zou_he_local" or cfg.outlet_mode != "neq_extrap"
+            or cfg.y_wall_bc != "bounce_back" or cfg.top_wall_bc != "velocity"
+            or cfg.wall_slot_width != 0 or cfg.wall_normal_velocity != 0):
+        raise ValueError("channel requires Zou-He inlet, pressure NEQ outlet and stationary bounce-back y walls")
+
+
+def validate_channel_transfers(pair, layout, targets):
+    """Reject actual exchange/closure overlap, not a padded geometric envelope.
+
+    Explosion donors and restriction receivers must use ordinary bulk collision
+    semantics. Restriction writes receiver-local source slots; these may not
+    overwrite the channel's extra immutable-input reads (pressure donor and
+    same-node halfway-wall corrections). The slot check deliberately respects
+    block seams, rather than treating different halo images as the same slot.
+    """
+    ny, nx = pair.coarse_shape
+    _, bulk = channel_masks(pair.coarse_shape)
+    legal = bulk.ravel() & ~pair.covered.ravel()
+    receivers = pair.coalesce_coarse % (ny * nx)
+    if not legal[pair.ghost_coarse].all() or not legal[receivers].all():
+        raise ValueError("channel transfer donors and receivers must be uncovered bulk fluid")
+    owner = layout.owner
+    reads = []
+    # Outlet closes from the full previous-step state at its left neighbor.
+    donor = owner[1:-1, -1].astype(np.int64) - 1
+    for q in range(9):
+        reads.append(layout.slot(donor, q))
+    for y, directions in ((1, (4, 6, 7)), (ny - 2, (3, 5, 8))):
+        for q in directions:
+            reads.append(layout.slot(owner[y, 1:-1], q))
+    if np.intersect1d(targets, np.concatenate(reads)).size:
+        raise ValueError("channel restriction writes overlap immutable boundary closure reads")

src/CelerisLab/lbm/curved_links.py

@@ -94,12 +94,10 @@ class CurvedLinkSoA:
         """
         self.surface_velocity = self.aperture = None
         self.jets, self.jet_shape, self.jet_id = tuple(jets), None, None
-        self.surface_velocity, self.aperture = surface_link_velocity(
+        from ..body.jets import _surface_links
+        self.surface_velocity, self.aperture, self.jet_shape, self.jet_id = _surface_links(
             objects, cfg, flags, self.fluid_idx, self.dir, self.body_id, self.rx, self.ry,
             jets=self.jets, hits=hits)
-        if self.jets:
-            from ..body.jets import jet_link_shapes
-            self.jet_shape, self.jet_id = jet_link_shapes(self.jets, hits)
 
     def set_jet_amplitude(self, index, amplitude, stream=None):
         """Rewrite jet rows from cached shapes; re-upload only the velocity column.

src/CelerisLab/lbm/hierarchy.py

@@ -0,0 +1,122 @@
+# CelerisLab/lbm/hierarchy.py
+"""Host-only geometry of a fixed 2:1 refinement hierarchy of any depth (numpy, no CUDA).
+
+Loops the existing adjacent-pair logic of refinement.py; it adds no transfer rule.
+``refinements[l]`` describes level l+1 in level-l integer cells: a scalar
+(x0, y0, x1, y1) is one FixedPatch2D window (its level keeps the window shape), a
+sequence of rectangles is a FixedPatchSet2D on the level-wide grid (origin 0).
+A scalar child is only accepted under a scalar parent. Every pair after the first
+is built by nest_patch/nest_patch_set, whose _nested_kind validates coverage,
+donors/receivers, surviving pulls and the parent's upward restriction footprint.
+"""
+from dataclasses import dataclass, replace
+from numbers import Integral
+
+import numpy as np
+
+from .refinement import (ACTIVE, OUTER_GHOST, FixedPatch2D, FixedPatchSet2D,
+                         _middle_config, nest_patch, nest_patch_set)
+
+
+@dataclass(frozen=True, eq=False)
+class Hierarchy:
+    """configs[l]: validated LBMConfig of level l; pairs[l]: tables of (l, l+1);
+    kinds[l]: composed per-cell kind (child coverage OUTER on every non-finest level).
+
+    Index conventions (the single place they are defined):
+      * level l = 0 (root) .. depth-1; pair index p = l-1 builds level l from level p;
+      * array shapes are (ny, nx); rectangles, origins and centers are (x, y);
+      * the root EDGE frame puts root cell i at [i, i+1), centers at i+.5 (bodies and
+        Jets of FixedPatchStepper); uniform Simulation objects use the integer-NODE frame;
+      * cell (i, j) of level l's allocated array (ghost band and holes included) covers
+        [o + h*i, o + h*(i+1)) with (o, h) = edge_frame(l); level 1 is built from the root
+        config directly, deeper levels from their parent frame (see edge_frame).
+    """
+    configs: tuple
+    pairs: tuple
+    kinds: tuple
+
+    @property
+    def depth(self):
+        return len(self.kinds)
+
+    def edge_frame(self, level):
+        """(origin (x, y), spacing) of level ``level``'s array in the root edge frame.
+
+        Each pair's fine_origin is in parent cells: zero for a set (level-wide grid),
+        the shifted window origin for a scalar FixedPatch2D.
+        """
+        origin, spacing = (0.0, 0.0), 1.0
+        for pair in self.pairs[:level]:
+            origin = tuple(o + spacing * f for o, f in zip(origin, pair.fine_origin))
+            spacing /= 2
+        return origin, spacing
+
+
+def is_rectangle(value):
+    value = tuple(value)
+    return len(value) == 4 and all(isinstance(v, (Integral, np.integer))
+                                   and not isinstance(v, (bool, np.bool_)) for v in value)
+
+
+def build_hierarchy(cfg, refinements, *, wall_aware=False):
+    """Geometry for len(refinements) + 1 levels; wall_aware marks base rows 0 and -1 OUTER."""
+    configs, pairs, kinds = [_validated(cfg)], [], []
+    for level, entry in enumerate(refinements):
+        scalar = is_rectangle(entry)
+        if not scalar and not tuple(entry):
+            raise ValueError("every refinement level needs at least one rectangle")
+        if level == 0:
+            pair = (FixedPatch2D if scalar else FixedPatchSet2D).from_config(configs[0], entry)
+            kind = np.where(pair.covered, OUTER_GHOST, ACTIVE).astype(np.uint8)
+            if wall_aware:
+                kind[[0, -1]] = OUTER_GHOST
+        elif scalar:
+            if not isinstance(pairs[-1], FixedPatch2D):
+                raise ValueError("a scalar child requires a scalar parent; use a rectangle list")
+            pair, kind = nest_patch(configs[level - 1], pairs[-1], entry)
+        else:
+            pair, kind = nest_patch_set(configs[level - 1], pairs[-1], entry)
+        kinds.append(np.asarray(kind))
+        pairs.append(pair)
+        configs.append(_validated(_middle_config(configs[level], pair)))
+        _check_chain(configs[level], configs[level + 1], pair)
+    if pairs:
+        kinds.append(pairs[-1].fine_kind)
+    else:
+        kind = np.full((cfg.ny, cfg.nx), ACTIVE, np.uint8)
+        if wall_aware:
+            kind[[0, -1]] = OUTER_GHOST
+        kinds.append(kind)
+    return Hierarchy(tuple(configs), tuple(pairs), tuple(kinds))
+
+
+def _validated(cfg):
+    """LBMConfig.omega is computed only by validate(); replace() copies it stale."""
+    cfg = replace(cfg)
+    cfg.validate()
+    return cfg
+
+
+def _check_chain(coarse, fine, pair):
+    if not (np.isclose(pair.tau_coarse, 1 / coarse.omega, rtol=1e-12, atol=0)
+            and np.isclose(pair.tau_fine, 1 / fine.omega, rtol=1e-12, atol=0)
+            and tuple(pair.fine_shape) == (fine.ny, fine.nx)):
+        raise RuntimeError("level config chain is inconsistent with the pair tables")
+
+
+def leaf_partition(h):
+    """Base-cell fraction published as ACTIVE over all levels (exact: powers of two).
+
+    Window (scalar) levels are offset by their fine_level_offset first.
+    """
+    base = np.zeros(h.kinds[0].shape)
+    oy = ox = 0
+    for level, kind in enumerate(h.kinds):
+        if level:
+            pair = h.pairs[level - 1]
+            py, px = (pair.fine_level_offset if isinstance(pair, FixedPatch2D) else (0, 0))
+            oy, ox = 2 * oy + py, 2 * ox + px
+        y, x = np.nonzero(kind == ACTIVE)
+        np.add.at(base, ((y + oy) >> level, (x + ox) >> level), 0.25 ** level)
+    return base

src/CelerisLab/lbm/kernels/blocked.cu

@@ -0,0 +1,47 @@
+// CelerisLab/lbm/kernels/blocked.cu
+// One fixed-size blocked level (lbm/blocks.py layout), specialized at compile
+// time for periodic/fine, slot/reservoir or channel stepping. Separate
+// compilation entry: NX, NY are the block window including halo, so index_f
+// and linear_index address one block; blockIdx.z selects the block, whose
+// populations start at b*NQ*TOTAL_CELLS (block-contiguous, Q-major inside).
+#include <stdint.h>
+#include <math.h>
+#include "config.h"
+#include "core/precision.cuh"
+#include "core/descriptors.cuh"
+#include "core/layout.cuh"
+#include "core/params.cuh"
+#include "core/flags.cuh"
+#include "core/obs.cuh"
+#include "core/cell_kind.cuh"
+#include "operators/macro.cuh"
+#include "operators/collision_srt.cuh"
+#if COLLISION_MODEL == 2
+#include "operators/collision_mrt.cuh"
+#endif
+#include "streaming/pull_double_buffer.cuh"
+#include "boundary/curved_boundary.cuh"
+
+#if DIM != 2 || NQ != 9 || (COLLISION_MODEL != 0 && COLLISION_MODEL != 2) || STORE_PRECISION != 0 || USE_LES || STREAMING_MODEL != 0
+#error "Blocks require FP32 D2Q9 SRT or MRT double buffers without LES"
+#endif
+#ifndef BLOCK_ROOT_BC
+#error "Blocks require a generated BLOCK_ROOT_BC mode"
+#elif BLOCK_ROOT_BC < 0 || BLOCK_ROOT_BC > 2
+#error "BLOCK_ROOT_BC must be 0, 1 or 2"
+#endif
+
+#if BLOCK_ROOT_BC == 1
+#include "boundary/block_wall.cuh"
+#endif
+#include "operators/block_collision.cuh"
+
+// Kernels, in definition order: transfers, boundary staging, then the one full
+// step selected for this module (BlockStep, or BlockChannelStep for a channel root).
+#include "step/block_transfer.cu"
+#include "step/block_boundary.cu"
+#if BLOCK_ROOT_BC != 2
+#include "step/block_step.cu"
+#else
+#include "step/block_channel.cu"
+#endif

src/CelerisLab/lbm/kernels/blocks.cu

@@ -1,133 +0,0 @@
-// CelerisLab/lbm/kernels/blocks.cu
-// One periodic level of fixed-size blocks (lbm/blocks.py layout). Separate
-// compilation entry: NX, NY are the block window including halo, so index_f
-// and linear_index address one block; blockIdx.z selects the block, whose
-// populations start at b*NQ*TOTAL_CELLS (block-contiguous, Q-major inside).
-#include <stdint.h>
-#include <math.h>
-#include "config.h"
-#include "core/precision.cuh"
-#include "core/descriptors.cuh"
-#include "core/layout.cuh"
-#include "core/params.cuh"
-#include "core/flags.cuh"
-#include "core/obs.cuh"
-#include "operators/macro.cuh"
-#include "operators/collision_srt.cuh"
-#include "streaming/pull_double_buffer.cuh"
-#include "boundary/curved_boundary.cuh"
-#include "boundary/planar_velocity.cuh"
-
-#if DIM != 2 || NQ != 9 || COLLISION_MODEL != 0 || STORE_PRECISION != 0 || USE_DDF_SHIFTING || USE_LES || STREAMING_MODEL != 0
-#error "Blocks require unshifted FP32 D2Q9 SRT double buffers without LES"
-#endif
-
-// Fixed-patch cell kinds, matching refinement.py ACTIVE/INNER_GHOST/OUTER_GHOST.
-constexpr unsigned char KIND_ACTIVE = 0u, KIND_INNER = 1u, KIND_OUTER = 2u;
-
-// Zero-initialized for ordinary blocks/fine levels. Set only for parent walls;
-// NX/NY remain local storage strides, never physical wall coordinates.
-struct BlockWall { unsigned int nx, ny, slot_width; float amplitude; };
-extern "C" { __constant__ BlockWall d_block_wall; }
-
-// Halo refresh: block cell ids b*TOTAL_CELLS+c, sources are always core cells.
-extern "C" __global__ void BlockHaloCopy(
-    fpxx* f, const uint64_t* dst, const uint64_t* src, unsigned int count)
-{
-    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
-    if (row >= count) return;
-    const uint64_t d = dst[row], s = src[row];
-    fpxx* to = f + (d / TOTAL_CELLS) * NQ * TOTAL_CELLS;
-    const fpxx* from = f + (s / TOTAL_CELLS) * NQ * TOTAL_CELLS;
-    for (unsigned int q = 0; q < NQ; ++q)
-        to[index_f(d % TOTAL_CELLS, q)] = from[index_f(s % TOTAL_CELLS, q)];
-}
-
-// Fixed-patch explosion into blocked fine storage: target = owner block cell
-// id of a patch-ghost cell; donors are parent block cell ids. Dense parent
-// storage is the one-window case with coarse_cells = full domain size.
-extern "C" __global__ void BlockExplode(
-    const fpxx* coarse, fpxx* fine, const uint64_t* target, const uint64_t* donor,
-    unsigned int count, unsigned long coarse_cells)
-{
-    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
-    if (row >= count) return;
-    const uint64_t t = target[row];
-    fpxx* to = fine + (t / TOTAL_CELLS) * NQ * TOTAL_CELLS;
-    const uint64_t d = donor[row];
-    const fpxx* from = coarse + (d / coarse_cells) * NQ * coarse_cells;
-    for (unsigned int q = 0; q < NQ; ++q)
-        to[index_f(t % TOTAL_CELLS, q)] = from[q * coarse_cells + d % coarse_cells];
-}
-
-// Targets are receiver-local SOURCE slots for the immediately following pull.
-// Keep child summation order identical to PatchCoarseStep; no collision here.
-extern "C" __global__ void BlockCoalesce(
-    const fpxx* fine, fpxx* coarse, const uint64_t* target, const uint64_t* children,
-    unsigned int count)
-{
-    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
-    if (row >= count) return;
-    const uint64_t* s = children + 4ul * row;
-    coarse[target[row]] = 0.25f * (fine[s[0]] + fine[s[1]] + fine[s[2]] + fine[s[3]]);
-}
-
-// Static cut links, receiver-local staging: cell is the receiver's local core
-// cell, so the existing BFL writes the solid-source window image that this
-// block's next pull reads (no halo copy between this kernel and BlockStep).
-// surface_velocity (nullable, 2 floats per link): prescribed fluid velocity on
-// fixed geometry, same convention as CurvedBoundaryKernel. No exchange output.
-extern "C" __global__ void BlockCurvedBoundary(
-    fpxx* f, const uint32_t* block, const uint32_t* cell, const unsigned char* dir,
-    const float* q, const unsigned char* fallback, unsigned int count,
-    const float* surface_velocity)
-{
-    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
-    if (row >= count) return;
-    float Uw = 0.0f, Vw = 0.0f;
-    if (surface_velocity != nullptr) {
-        const float u = surface_velocity[2 * row], v = surface_velocity[2 * row + 1];
-        if (u != 0.0f || v != 0.0f) { Uw = u; Vw = v; }
-    }
-    apply_bouzidi_link(dir[row], q[row], cell[row], f + (unsigned long)block[row] * NQ * TOTAL_CELLS,
-                       Uw, Vw, 0.0f, 0.0f, fallback[row], nullptr, -1);
-}
-
-// Pull/collide/store core cells only; halo cells of out are left untouched.
-// flags (block cell ids, nullable): solid cores store NaN and never collide.
-// kind (block cell ids, nullable = all ACTIVE): OUTER skips the pull and
-// stores NaN, INNER pulls without collision, ACTIVE pulls and collides.
-extern "C" __global__ void BlockStep(const fpxx* in, fpxx* out, unsigned int halo,
-                                     const uint16_t* flags, const unsigned char* kind) {
-    unsigned int x, y; unsigned long k;
-    index_from_thread(x, y, k);
-    if (x < halo || y < halo || x >= NX - halo || y >= NY - halo) return;
-    const unsigned long base = (unsigned long)blockIdx.z * NQ * TOTAL_CELLS;
-    const unsigned long cell = (unsigned long)blockIdx.z * TOTAL_CELLS + k;
-    const unsigned char cell_kind = kind != nullptr ? kind[cell] : KIND_ACTIVE;
-    float f[NQ];
-    if (cell_kind == KIND_OUTER || (flags != nullptr && is_solid(flags[cell]))) {
-        for (int q = 0; q < NQ; ++q) f[q] = NAN;
-    } else {
-        unsigned long j[NQ];
-        compute_neighbors(x, y, j);  // Core neighbors stay inside the window: no wrap.
-        stream_pull_load(k, f, in + base, j);
-        if (cell_kind == KIND_ACTIVE) {
-            if (d_block_wall.nx != 0) {
-                const unsigned int bx = NX - 2 * halo, by = NY - 2 * halo;
-                const unsigned int nbx = d_block_wall.nx / bx;
-                const unsigned int gx = (blockIdx.z % nbx) * bx + x - halo;
-                const unsigned int gy = (blockIdx.z / nbx) * by + y - halo;
-                if (gy == 1)
-                    reconstruct_bottom_velocity(f, 0.0f, bottom_wall_normal_velocity(
-                        gx, d_block_wall.nx, d_block_wall.slot_width, d_block_wall.amplitude));
-                else if (gy == d_block_wall.ny - 2) reconstruct_top_reservoir(f, RHO);
-            }
-            float rho, ux, uy, feq[NQ];
-            compute_rho_u(f, rho, ux, uy);
-            compute_feq(rho, ux, uy, feq);
-            collide_srt_no_force(f, feq, d_params.omega);
-        }
-    }
-    stream_pull_store(k, f, out + base);
-}

src/CelerisLab/lbm/kernels/boundary/block_wall.cuh

@@ -0,0 +1,20 @@
+// Physical parent walls; NX/NY remain local storage strides.
+#ifndef CELERIS_BOUNDARY_BLOCK_WALL_CUH
+#define CELERIS_BOUNDARY_BLOCK_WALL_CUH
+
+#include "planar_velocity.cuh"
+
+struct BlockWall { unsigned int nx, ny, slot_width; float amplitude; };
+extern "C" { __constant__ BlockWall d_block_wall; }
+
+__device__ __forceinline__ void block_wall(float* f, unsigned int x, unsigned int y,
+                                         unsigned int halo) {
+    unsigned int gx, gy;
+    block_global_xy(x, y, halo, d_block_wall.nx, gx, gy);
+    if (gy == 1)
+        reconstruct_bottom_velocity(f, 0.0f, bottom_wall_normal_velocity(
+            gx, d_block_wall.nx, d_block_wall.slot_width, d_block_wall.amplitude));
+    else if (gy == d_block_wall.ny - 2) reconstruct_top_reservoir(f, RHO);
+}
+
+#endif

src/CelerisLab/lbm/kernels/boundary/bounce_back.cuh

@@ -15,10 +15,13 @@
 // D2Q9 y-wall half-way bounce-back for pull double-buffer streaming.
 // ---------------------------------------------------------------------------
 #if LATTICE_MODEL == LATTICE_D2Q9
-__device__ inline void apply_wall_bb_d2q9_y_pull(unsigned int y,
-                                                  float* __restrict__ f,
-                                                  const fpxx* __restrict__ fi_in,
-                                                  unsigned long k)
+// Rows 1 and top_row (= physical ny - 2) next to walls at rows 0 and ny - 1.
+// y is the physical row; k addresses the node in fi_in (a block window may
+// have NX/NY strides different from the physical extent).
+__device__ inline void apply_wall_bb_d2q9_rows(unsigned int y, unsigned int top_row,
+                                               float* __restrict__ f,
+                                               const fpxx* __restrict__ fi_in,
+                                               unsigned long k)
 {
     if (y == 1) {
         // Directions sourced from y=0 wall in pull step: +y, +x+y, -x+y.
@@ -26,14 +29,22 @@ __device__ inline void apply_wall_bb_d2q9_y_pull(unsigned int y,
         f[5] = load_ddf(fi_in, index_f(k, 6u));
         f[8] = load_ddf(fi_in, index_f(k, 7u));
     }
-    else if (y == (unsigned int)(NY - 2)) {
-        // Directions sourced from y=NY-1 wall in pull step: -y, -x-y, +x-y.
+    else if (y == top_row) {
+        // Directions sourced from the y = ny - 1 wall in pull step: -y, -x-y, +x-y.
         f[4] = load_ddf(fi_in, index_f(k, 3u));
         f[6] = load_ddf(fi_in, index_f(k, 5u));
         f[7] = load_ddf(fi_in, index_f(k, 8u));
     }
 }
 
+__device__ inline void apply_wall_bb_d2q9_y_pull(unsigned int y,
+                                                  float* __restrict__ f,
+                                                  const fpxx* __restrict__ fi_in,
+                                                  unsigned long k)
+{
+    apply_wall_bb_d2q9_rows(y, (unsigned int)(NY - 2), f, fi_in, k);
+}
+
 // ---------------------------------------------------------------------------
 // D2Q9 y-wall free-slip (specular reflection) for pull double-buffer streaming.
 //

src/CelerisLab/lbm/kernels/boundary/curved_boundary.cuh

@@ -82,7 +82,8 @@ __device__ inline void apply_bouzidi_link(
     float Uw, float Vw,
     float rx, float ry,
     unsigned char fallback_class,
-    float* __restrict__ obs, int body_id, float* link_exchange = nullptr)
+    float* __restrict__ obs, int body_id, float* link_exchange = nullptr,
+    float* link_mass = nullptr)
 {
     const unsigned int dir_opp = (unsigned int)opp_dir((int)dir);
 
@@ -120,6 +121,10 @@ __device__ inline void apply_bouzidi_link(
     // corrected incoming population into the adjacent fluid node.
     store_ddf(fi, index_f(k_s, dir_opp), f_reflected);
 
+    // Equal opposite weights cancel even with shifted DDFs.
+    if (link_mass != nullptr)
+        *link_mass = f_reflected - f_toward;
+
     if (obs != nullptr || link_exchange != nullptr) {
 #if USE_DDF_SHIFTING
         const float w_i = (float)d_w[dir];

src/CelerisLab/lbm/kernels/boundary/inlet/common.cuh

@@ -27,18 +27,22 @@
 #define INLET_REGULARIZED_NEQ_DAMP 0.50f
 #endif
 
-__device__ __forceinline__ float inlet_target_u(float y_coord) {
+__device__ __forceinline__ float inlet_target_u(float y_coord, unsigned int ny, float velocity) {
 #if INLET_PROFILE == 0
-    return U0;
+    return velocity;
 #else
-    const float y_clamped = fminf((float)(NY - 2), fmaxf(1.0f, y_coord));
-    const float H = fmaxf((float)(NY - 2), 1.0f);
+    const float y_clamped = fminf((float)(ny - 2), fmaxf(1.0f, y_coord));
+    const float H = fmaxf((float)(ny - 2), 1.0f);
     const float eta = (y_clamped - 0.5f) / H;
     const float shape = fmaxf(0.0f, 4.0f * eta * (1.0f - eta));
-    return U0 * 1.5f * shape;
+    return velocity * 1.5f * shape;
 #endif
 }
 
+__device__ __forceinline__ float inlet_target_u(float y_coord) {
+    return inlet_target_u(y_coord, NY, U0);
+}
+
 #if LATTICE_MODEL == LATTICE_D2Q9
 __device__ __forceinline__ float west_velocity_rho_closure_d2q9(
     const float* __restrict__ f,

src/CelerisLab/lbm/kernels/boundary/planar_velocity.cuh

@@ -1,6 +1,6 @@
 // On-site D2Q9 Zou-He velocity closure, paired lattice ordering.
 // Input is poststream f at the arrival time. Only unknown populations change;
-// the caller owns collision/store. No force, shifting or off-lattice walls.
+// the caller owns collision/store. No force or off-lattice walls. Shifted storage uses unit reference density.
 #ifndef CELERIS_BOUNDARY_PLANAR_VELOCITY_CUH
 #define CELERIS_BOUNDARY_PLANAR_VELOCITY_CUH
 #include <math.h>
@@ -28,7 +28,11 @@ __device__ __forceinline__ float bottom_wall_normal_velocity(unsigned int x)
 
 __device__ __forceinline__ void reconstruct_bottom_velocity(float* f, float u, float v)
 {
-    const float rho = (f[0] + f[1] + f[2] + 2.0f*(f[4] + f[6] + f[7])) / (1.0f-v);
+    const float rho = (
+#if USE_DDF_SHIFTING
+        1.0f +
+#endif
+        f[0] + f[1] + f[2] + 2.0f*(f[4] + f[6] + f[7])) / (1.0f-v);
     f[3] = f[4] + (2.0f/3.0f)*rho*v;
     f[5] = f[6] + 0.5f*(f[2]-f[1]) + 0.5f*rho*u + (1.0f/6.0f)*rho*v;
     f[8] = f[7] + 0.5f*(f[1]-f[2]) - 0.5f*rho*u + (1.0f/6.0f)*rho*v;
@@ -36,7 +40,11 @@ __device__ __forceinline__ void reconstruct_bottom_velocity(float* f, float u, f
 
 __device__ __forceinline__ void reconstruct_top_velocity(float* f, float u, float v)
 {
-    const float rho = (f[0] + f[1] + f[2] + 2.0f*(f[3] + f[5] + f[8])) / (1.0f+v);
+    const float rho = (
+#if USE_DDF_SHIFTING
+        1.0f +
+#endif
+        f[0] + f[1] + f[2] + 2.0f*(f[3] + f[5] + f[8])) / (1.0f+v);
     f[4] = f[3] - (2.0f/3.0f)*rho*v;
     f[6] = f[5] + 0.5f*(f[1]-f[2]) - 0.5f*rho*u - (1.0f/6.0f)*rho*v;
     f[7] = f[8] + 0.5f*(f[2]-f[1]) + 0.5f*rho*u - (1.0f/6.0f)*rho*v;
@@ -46,7 +54,12 @@ __device__ __forceinline__ void reconstruct_top_velocity(float* f, float u, floa
 // J_y=rho*v follows from known poststream populations (ordinary D2Q9).
 __device__ __forceinline__ void reconstruct_top_reservoir(float* f, float rho)
 {
-    const float jy = f[0]+f[1]+f[2]+2.0f*(f[3]+f[5]+f[8])-rho;
+#if USE_DDF_SHIFTING
+    const float density_offset = rho - 1.0f;
+#else
+    const float density_offset = rho;
+#endif
+    const float jy = f[0]+f[1]+f[2]+2.0f*(f[3]+f[5]+f[8])-density_offset;
     f[4] = f[3] - (2.0f/3.0f)*jy;
     f[6] = f[5] + 0.5f*(f[1]-f[2]) - (1.0f/6.0f)*jy;
     f[7] = f[8] + 0.5f*(f[2]-f[1]) - (1.0f/6.0f)*jy;

src/CelerisLab/lbm/kernels/config/config_method.h

@@ -8,6 +8,9 @@
 #define STORE_PRECISION  0
 #define USE_DDF_SHIFTING 0
 
+// Internal blocked root mode: 0=periodic/fine, 1=slot/reservoir, 2=channel.
+#define BLOCK_ROOT_BC 0
+
 #define USE_LES 0
 #define LES_CS  0.160000f
 #define LES_CLOSED_FORM 1

src/CelerisLab/lbm/kernels/core/cell_kind.cuh

@@ -0,0 +1,16 @@
+// CelerisLab – core/cell_kind.cuh
+// Fixed-patch cell kinds stored per block cell, matching lbm/refinement.py
+// ACTIVE/INNER_GHOST/OUTER_GHOST: OUTER is invalid (stores NaN, no pull),
+// INNER streams without collision, ACTIVE pulls and collides.
+#ifndef CELERIS_CORE_CELL_KIND_CUH
+#define CELERIS_CORE_CELL_KIND_CUH
+
+constexpr unsigned char KIND_ACTIVE = 0u, KIND_INNER = 1u, KIND_OUTER = 2u;
+
+// NaN populations mark a cell without valid state (OUTER ghost or solid core).
+__device__ __forceinline__ void fill_invalid(float* f)
+{
+    for (int q = 0; q < NQ; ++q) f[q] = NAN;
+}
+
+#endif

src/CelerisLab/lbm/kernels/core/layout.cuh

@@ -53,6 +53,18 @@ __device__ __forceinline__ void index_from_thread(unsigned int& x,
     k = (unsigned long)y * NX + x;
 }
 
+// Global cell of window cell (x, y) in block blockIdx.z of a row-major,
+// full-domain block layout domain_nx cells wide. NX/NY are the local strides.
+__device__ __forceinline__ void block_global_xy(unsigned int x, unsigned int y,
+                                                unsigned int halo, unsigned int domain_nx,
+                                                unsigned int& gx, unsigned int& gy)
+{
+    const unsigned int bx = NX - 2 * halo, by = NY - 2 * halo;
+    const unsigned int nbx = domain_nx / bx;
+    gx = (blockIdx.z % nbx) * bx + x - halo;
+    gy = (blockIdx.z / nbx) * by + y - halo;
+}
+
 // ---------------------------------------------------------------------------
 // Neighbor list (periodic BCs via modular arithmetic)
 // ---------------------------------------------------------------------------

src/CelerisLab/lbm/kernels/core/params.cuh

@@ -44,16 +44,4 @@ struct RigidBodyControl2D {
     int   control_mode;           // 0=force, 1=velocity, 2=displacement
 };
 
-// ============================================================================
-// Halo plan (multi-GPU / AMR 预留)
-// ============================================================================
-struct HaloPlan {
-    int       face_id;
-    int       peer_gpu;
-    int       level;
-    size_t    count;
-    int*      send_idx;
-    int*      recv_idx;
-};
-
 #endif // CELERIS_CORE_PARAMS_CUH

src/CelerisLab/lbm/kernels/operators/block_collision.cuh

@@ -0,0 +1,43 @@
+// The one collision extension point of the blocked steps (BlockStep, BlockChannelStep).
+// Compile-time selection: MRT shares one path; SRT keeps two explicit arithmetic
+// variants, unchanged from their original kernels:
+//   level  (BLOCK_ROOT_BC 0/1): unclamped omega, no forcing term; shifted storage
+//          builds feq from the retained drho and direct momentum (numerical variant);
+//   channel (BLOCK_ROOT_BC 2): matches uniform OneStep SRT arithmetic (omega clamp,
+//          zero Guo forcing term, compute_feq).
+#ifndef CELERIS_OPERATORS_BLOCK_COLLISION_CUH
+#define CELERIS_OPERATORS_BLOCK_COLLISION_CUH
+
+#include "../core/params.cuh"
+#include "macro.cuh"
+#include "collision_srt.cuh"
+#if COLLISION_MODEL == 2
+#include "collision_mrt.cuh"
+#endif
+
+__device__ __forceinline__ void block_collide(float* f) {
+#if COLLISION_MODEL == 2
+    collide_mrt_unforced(f);
+#elif BLOCK_ROOT_BC == 2
+    float rho, ux, uy, feq[NQ], forcing[NQ] = {};
+    compute_rho_u(f, rho, ux, uy);
+    compute_feq(rho, ux, uy, feq);
+    const float omega = fminf(OMEGA_COLLISION_MAX, fmaxf(OMEGA_COLLISION_MIN, d_params.omega));
+    collide_srt(f, feq, forcing, omega);
+#else
+    float rho, ux, uy, feq[NQ];
+    compute_rho_u(f, rho, ux, uy);
+#if USE_DDF_SHIFTING
+    // Preserve the density perturbation before adding the unit reference.
+    const float drho = f[0]+f[1]+f[2]+f[3]+f[4]+f[5]+f[6]+f[7]+f[8];
+    const float jx = f[1]-f[2]+f[5]-f[6]+f[7]-f[8];
+    const float jy = f[3]-f[4]+f[5]-f[6]-f[7]+f[8];
+    compute_feq_from_momentum(drho, jx, jy, ux, uy, feq);
+#else
+    compute_feq(rho, ux, uy, feq);
+#endif
+    collide_srt_no_force(f, feq, d_params.omega);
+#endif
+}
+
+#endif

src/CelerisLab/lbm/kernels/operators/bounce_back_swap.cuh

@@ -0,0 +1,14 @@
+// CelerisLab – operators/bounce_back_swap.cuh
+// Full-way bounce-back at a wall node: swap every opposite pair (paired
+// order q, q+1). Needs only NQ; shared by the uniform and blocked steps.
+#ifndef CELERIS_OPERATORS_BOUNCE_BACK_SWAP_CUH
+#define CELERIS_OPERATORS_BOUNCE_BACK_SWAP_CUH
+
+__device__ __forceinline__ void bounce_back_swap(float* f) {
+    #pragma unroll
+    for (int i = 1; i < NQ; i += 2) {
+        float t = f[i]; f[i] = f[i+1]; f[i+1] = t;
+    }
+}
+
+#endif

src/CelerisLab/lbm/kernels/operators/collision_mrt.cuh

@@ -114,6 +114,16 @@ __device__ __forceinline__ void collide_mrt_no_force(float* __restrict__ g,
     collide_mrt(g, rho, ux, uy, Fin, omega);
 }
 
+// Unforced MRT with the clamped device omega, as in collide_dispatch with zero
+// forcing. Shared by the blocked, channel-root and dense-patch collisions.
+__device__ __forceinline__ void collide_mrt_unforced(float* __restrict__ g)
+{
+    float rho, ux, uy;
+    compute_rho_u(g, rho, ux, uy);
+    collide_mrt_no_force(g, rho, ux, uy,
+        fminf(OMEGA_COLLISION_MAX, fmaxf(OMEGA_COLLISION_MIN, d_params.omega)));
+}
+
 #elif LATTICE_MODEL == LATTICE_D3Q19
 
 __device__ __forceinline__ void collide_mrt(float* __restrict__ g,

src/CelerisLab/lbm/kernels/operators/collision_trt.cuh

@@ -57,25 +57,4 @@ __device__ __forceinline__ void collide_trt(float* __restrict__ f,
     }
 }
 
-__device__ __forceinline__ void collide_trt_no_force(float* __restrict__ f,
-                                                     const float* __restrict__ feq,
-                                                     float omega)
-{
-    const float wp = omega;
-    const float wm = compute_omega_minus(wp);
-
-    f[0] = f[0] - wp * (f[0] - feq[0]);
-
-    #pragma unroll
-    for (int i = 1; i < NQ; i += 2) {
-        const int ib = i + 1;
-        const float fi = f[i], fb = f[ib];
-        const float feqi = feq[i], feqb = feq[ib];
-        const float delta_s = 0.5f * ((fi - feqi) + (fb - feqb));
-        const float delta_a = 0.5f * ((fi - feqi) - (fb - feqb));
-        f[i]  = fi  - wp * delta_s - wm * delta_a;
-        f[ib] = fb  - wp * delta_s + wm * delta_a;
-    }
-}
-
 #endif // CELERIS_OPERATORS_COLLISION_TRT_CUH

src/CelerisLab/lbm/kernels/operators/helpers.cuh

@@ -5,12 +5,7 @@
 #ifndef CELERIS_OPERATORS_HELPERS_CUH
 #define CELERIS_OPERATORS_HELPERS_CUH
 
-__device__ __forceinline__ void bounce_back_swap(float* f) {
-    #pragma unroll
-    for (int i = 1; i < NQ; i += 2) {
-        float t = f[i]; f[i] = f[i+1]; f[i+1] = t;
-    }
-}
+#include "bounce_back_swap.cuh"
 
 __device__ __forceinline__ void collide_dispatch(
     float* f, float rho_n,

src/CelerisLab/lbm/kernels/operators/macro.cuh

@@ -64,11 +64,12 @@ __device__ __forceinline__ void compute_rho_u(const float* __restrict__ f,
 #if LATTICE_MODEL == LATTICE_D2Q9
 
 __device__ __forceinline__ void compute_feq(float rho, float ux, float uy,
-                                            float* __restrict__ feq)
-{
+                                            float* __restrict__ feq
 #if USE_DDF_SHIFTING
-    const float rhom1 = rho - 1.0f;          // perturbation density
+                                            , float rhom1
 #endif
+                                            )
+{
     const float ux3 = 3.0f * ux;
     const float uy3 = 3.0f * uy;
     const float c3  = -1.5f * (ux * ux + uy * uy);  // = -|u|²/(2cs²)
@@ -112,6 +113,39 @@ __device__ __forceinline__ void compute_feq(float rho, float ux, float uy,
     #undef FEQ_CORE
 }
 
+#if USE_DDF_SHIFTING
+// Shifted D2Q9 equilibrium using input momentum in the linear term.
+// Algebraically identical to the usual second-order equilibrium; explicit
+// rational divisions avoid 3*w rounding and the rho*(j/rho) round trip.
+__device__ __forceinline__ void compute_feq_from_momentum(
+    float delta, float jx, float jy, float ux, float uy,
+    float* __restrict__ feq)
+{
+    const float common = fmaf(-1.5f, fmaf(jx, ux, jy * uy), delta);
+    feq[0] = W0_VAL * common;
+    const float jp[4] = {jx, jy, jx + jy, jx - jy};
+    const float up[4] = {ux, uy, ux + uy, ux - uy};
+    #pragma unroll
+    for (int p = 0; p < 4; ++p) {
+        const float weight = p < 2 ? WS_VAL : WE_VAL;
+        const float odd = __fdiv_rn(jp[p], p < 2 ? 3.0f : 12.0f);
+        const float even = weight * fmaf(4.5f * jp[p], up[p], common);
+        feq[1 + 2*p] = even + odd;
+        feq[2 + 2*p] = even - odd;
+    }
+}
+#endif
+
+#if USE_DDF_SHIFTING
+// Existing callers recover the offset from rho; blocked shifted collision
+// supplies sum(g) directly to the overload above, retaining small perturbations.
+__device__ __forceinline__ void compute_feq(float rho, float ux, float uy,
+                                            float* __restrict__ feq)
+{
+    compute_feq(rho, ux, uy, feq, rho - 1.0f);
+}
+#endif
+
 #elif LATTICE_MODEL == LATTICE_D3Q19
 
 __device__ __forceinline__ void compute_feq(float rho, float ux, float uy, float uz,

src/CelerisLab/lbm/kernels/operators/turbulence_smag.cuh

@@ -5,7 +5,9 @@
 //   nu_t = (C_s * Delta)^2 * |S|,  Delta = 1 (lattice unit)
 //   omega_eff = 1 / (3*(nu + nu_t) + 0.5)
 //
-// |S| is estimated from non-equilibrium second-order moments using tau0.
+// |S| = sqrt(2 S_ij S_ij), with Delta = 1 in lattice units.
+// The stress estimate uses self-consistent tau_eff; tau0 is molecular.
+// Closed form uses full stress. Iteration uses deviatoric stress and a cap.
 // ============================================================================
 
 #ifndef CELERIS_OPERATORS_TURBULENCE_SMAG_CUH
@@ -65,12 +67,12 @@ __device__ __forceinline__ float compute_omega_smag(const float* __restrict__ f,
 
 #if LES_CLOSED_FORM
     // Closed-form Smagorinsky (no iteration):
-    //   ω = 2 / (τ₀ + √(τ₀² + 18·Cs²·√Q / ρ))
+    //   ω = 2 / (τ₀ + √(τ₀² + 18·√2·Cs²·√Q / ρ))
     // where Q = Πneq_ij · Πneq_ij (Frobenius norm squared)
     const float Q = pixx*pixx + piyy*piyy + 2.0f*pixy*pixy;
     const float sqrtQ = sqrtf(fmaxf(Q, 0.0f));
     const float smag_const_sq = LES_CS * LES_CS;
-    const float discriminant = tau0*tau0 + 18.0f * smag_const_sq * sqrtQ / rho_safe;
+    const float discriminant = tau0*tau0 + 18.0f * sqrtf(2.0f) * smag_const_sq * sqrtQ / rho_safe;
     const float tau_eff = 0.5f * (tau0 + sqrtf(fmaxf(discriminant, tau0*tau0)));
     return clamp_omega(1.0f / fmaxf(tau_eff, 0.500001f));
 #else
@@ -140,7 +142,7 @@ __device__ __forceinline__ float compute_omega_smag(const float* __restrict__ f,
                   + 2.0f*(pixy*pixy + pixz*pixz + piyz*piyz);
     const float sqrtQ = sqrtf(fmaxf(Q, 0.0f));
     const float smag_const_sq = LES_CS * LES_CS;
-    const float discriminant = tau0*tau0 + 18.0f * smag_const_sq * sqrtQ / rho_safe;
+    const float discriminant = tau0*tau0 + 18.0f * sqrtf(2.0f) * smag_const_sq * sqrtQ / rho_safe;
     const float tau_eff = 0.5f * (tau0 + sqrtf(fmaxf(discriminant, tau0*tau0)));
     return clamp_omega(1.0f / fmaxf(tau_eff, 0.500001f));
 #else

src/CelerisLab/lbm/kernels/refinement.cu

@@ -1,120 +0,0 @@
-// Fixed, unforced internal 2:1 patch. Separate compilation entry;
-// default OneStep/channel kernels are deliberately not included.
-#include <stdint.h>
-#include <math.h>
-#include "config.h"
-#include "core/precision.cuh"
-#include "core/descriptors.cuh"
-#include "core/layout.cuh"
-#include "core/params.cuh"
-#include "core/flags.cuh"
-#include "core/obs.cuh"
-#include "operators/macro.cuh"
-#include "operators/collision_srt.cuh"
-#include "streaming/pull_double_buffer.cuh"
-#include "boundary/planar_velocity.cuh"
-#include "boundary/curved_boundary.cuh"
-
-extern "C" {
-#include "step/curved_double.cu"
-}
-
-#if DIM != 2 || NQ != 9 || COLLISION_MODEL != 0 || STORE_PRECISION != 0 || USE_DDF_SHIFTING || USE_LES || STREAMING_MODEL != 0
-#error "Refinement requires unshifted FP32 D2Q9 SRT double buffers without LES"
-#endif
-
-// Enabled only in the validation build; no diagnostic arrays in normal builds.
-#ifdef CELERIS_REFINEMENT_AUDIT
-extern "C" {
-__device__ unsigned int collision_counts[TOTAL_CELLS];
-__device__ unsigned int explosion_counts[TOTAL_CELLS];
-__device__ unsigned int incoming_counts[NQ * TOTAL_CELLS];
-}
-#endif
-
-__device__ __forceinline__ void patch_collide(float* f, unsigned long k) {
-    float rho, ux, uy, feq[NQ];
-    compute_rho_u(f, rho, ux, uy);
-    compute_feq(rho, ux, uy, feq);
-    collide_srt_no_force(f, feq, d_params.omega);
-#ifdef CELERIS_REFINEMENT_AUDIT
-    ++collision_counts[k];
-#endif
-}
-
-extern "C" __global__ void PatchExplode(
-    const float* coarse, float* fine, const uint32_t* targets,
-    const uint32_t* donors, unsigned int count, unsigned long coarse_cells)
-{
-    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
-    if (row >= count) return;
-    for (unsigned int q = 0; q < NQ; ++q)
-        fine[index_f(targets[row], q)] = coarse[q * coarse_cells + donors[row]];
-#ifdef CELERIS_REFINEMENT_AUDIT
-    ++explosion_counts[targets[row]];
-#endif
-}
-
-extern "C" __global__ void PatchFineStep(const float* in, float* out, const uint16_t* flags) {
-    unsigned int x, y; unsigned long k;
-    index_from_thread(x, y, k);
-    if (x >= NX || y >= NY) return;
-    float f[NQ];
-    // Outer halo is invalid after EACH hop, including when reusing the buffer
-    // that held explosion data. Inner halo only streams; it never collides.
-    if (x < 2 || y < 2 || x >= NX - 2 || y >= NY - 2
-            || (flags != nullptr && is_solid(flags[k]))) {
-        for (int q = 0; q < NQ; ++q) f[q] = NAN;
-    } else {
-        unsigned long j[NQ];
-        compute_neighbors(x, y, j);  // These interior targets never wrap.
-        stream_pull_load(k, f, in, j);
-        if (x >= 4 && y >= 4 && x < NX - 4 && y < NY - 4)
-            patch_collide(f, k);
-    }
-    stream_pull_store(k, f, out);
-}
-
-extern "C" __global__ void PatchCoarseStep(
-    const float* in, float* out, const float* fine,
-    const uint64_t* targets, const uint64_t* children, unsigned int count,
-    unsigned int x0, unsigned int y0, unsigned int x1, unsigned int y1,
-    unsigned int wall_aware)
-{
-    unsigned int x, y; unsigned long k;
-    index_from_thread(x, y, k);
-    if (x >= NX || y >= NY) return;
-    // Both buffers were poisoned at initialization; covered cells stay invalid.
-    if (x >= x0 && x < x1 && y >= y0 && y < y1) return;
-    if (wall_aware && (y == 0 || y == NY - 1)) return;
-    unsigned long j[NQ];
-    compute_neighbors(x, y, j);
-    float f[NQ];
-    stream_pull_load(k, f, in, j);
-    if (x >= x0 - 1 && x <= x1 && y >= y0 - 1 && y <= y1) {
-        for (unsigned int q = 1; q < NQ; ++q) {
-            uint64_t slot = index_f(k, q);
-            unsigned int lo = 0, hi = count;
-            while (lo < hi) {
-                unsigned int mid = lo + (hi - lo) / 2;
-                if (targets[mid] < slot) lo = mid + 1;
-                else hi = mid;
-            }
-            if (lo < count && targets[lo] == slot) {
-                const uint64_t* s = children + 4ul * lo;
-                f[q] = 0.25f * (fine[s[0]] + fine[s[1]] + fine[s[2]] + fine[s[3]]);
-#ifdef CELERIS_REFINEMENT_AUDIT
-                ++incoming_counts[slot];
-#endif
-            }
-        }
-    }
-    // Includes the eight grazing-corner links with UNCOVERED coarse donors.
-    // All replacement arrivals must be in place before computing rho/u.
-    if (wall_aware) {
-        if (y == 1) reconstruct_bottom_velocity(f, 0.0f, bottom_wall_normal_velocity(x));
-        else if (y == NY - 2) reconstruct_top_reservoir(f, RHO);
-    }
-    patch_collide(f, k);
-    stream_pull_store(k, f, out);
-}

src/CelerisLab/lbm/kernels/step/aux_kernels.cu

@@ -3,7 +3,7 @@
 // ApplyEsoPullCurvedKernel, SensorKernel, ForceRegionKernel.
 //
 // Launched on compact lists (n_curved / n_sensor / n_cells threads).
-// Included by kernel_v2.cu.  No standalone compilation.
+// Included by uniform.cu.  No standalone compilation.
 //
 // Double-buffer mode:
 //   CurvedBoundaryKernel runs BEFORE OneStep.

src/CelerisLab/lbm/kernels/step/block_boundary.cu

@@ -0,0 +1,42 @@
+// CelerisLab/lbm/kernels/step/block_boundary.cu
+// Receiver-local curved-boundary staging and its raw-exchange accumulation.
+// Part of the blocked.cu compilation entry; relies on its includes and guards.
+
+// Static cut links, receiver-local staging: cell is the receiver's local core
+// cell, so the existing BFL writes the solid-source window image that this
+// block's next pull reads (no halo copy between this kernel and BlockStep).
+// surface_velocity (nullable, 2 floats per link): prescribed fluid velocity on
+// fixed geometry, same convention as CurvedBoundaryKernel. Optional raw rows
+// (jx,jy,torque,dm) are unique physical links, never body-observation slots.
+extern "C" __global__ void BlockCurvedBoundary(
+    fpxx* f, const uint32_t* block, const uint32_t* cell, const unsigned char* dir,
+    const float* q, const unsigned char* fallback, unsigned int count,
+    const float* surface_velocity, const float* rx, const float* ry, float* raw)
+{
+    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
+    if (row >= count) return;
+    float Uw = 0.0f, Vw = 0.0f;
+    if (surface_velocity != nullptr) {
+        const float u = surface_velocity[2 * row], v = surface_velocity[2 * row + 1];
+        if (u != 0.0f || v != 0.0f) { Uw = u; Vw = v; }
+    }
+    apply_bouzidi_link(dir[row], q[row], cell[row], f + (unsigned long)block[row] * NQ * TOTAL_CELLS,
+                       Uw, Vw, rx ? rx[row] : 0.0f, ry ? ry[row] : 0.0f,
+                       fallback[row], nullptr, -1, raw ? raw + 4ul * row : nullptr,
+                       raw ? raw + 4ul * row + 3 : nullptr);
+}
+
+// Same-stream BFL -> this row-owned accumulation -> pull step. No atomics,
+// no cross-row reduction and no history allocation proportional to substeps.
+extern "C" __global__ void BlockAccumulateExchange(
+    const float* raw, double* integral, unsigned int count, double h, double dt)
+{
+    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
+    if (row >= count) return;
+    const unsigned long k = 4ul * row;
+    const double impulse = h * dt;
+    integral[k] += impulse * (double)raw[k];
+    integral[k + 1] += impulse * (double)raw[k + 1];
+    integral[k + 2] += h * impulse * (double)raw[k + 2];
+    integral[k + 3] += h * h * (double)raw[k + 3];
+}

src/CelerisLab/lbm/kernels/step/block_channel.cu

@@ -0,0 +1,54 @@
+#if BLOCK_ROOT_BC != 2
+#error "BlockChannelStep requires BLOCK_ROOT_BC == 2"
+#endif
+
+// Root-only blocked counterpart of OneStep's D2Q9/SRT channel closure.
+// NX/NY are LOCAL strides; all physical boundary decisions use global coordinates.
+#include "../core/cell_kind.cuh"
+#include "../operators/bounce_back_swap.cuh"
+#include "../boundary/bounce_back.cuh"
+#include "../boundary/inlet/common.cuh"
+#include "../boundary/inlet/zou_he_local.cuh"
+#include "../boundary/outlet/pressure_neq.cuh"
+
+struct BlockChannel { unsigned int nx, ny; float velocity; };
+extern "C" { __constant__ BlockChannel d_block_channel; }
+
+// Same signature as BlockStep so the AMR hop/transfer schedule is unchanged.
+extern "C" __global__ void BlockChannelStep(
+    const fpxx* in, fpxx* out, unsigned int halo,
+    const uint16_t* flags, const unsigned char* kind)
+{
+    unsigned int x, y; unsigned long k;
+    index_from_thread(x, y, k);
+    if (x < halo || y < halo || x >= NX - halo || y >= NY - halo) return;
+    unsigned int gx, gy;
+    block_global_xy(x, y, halo, d_block_channel.nx, gx, gy);
+    const unsigned long base = (unsigned long)blockIdx.z * NQ * TOTAL_CELLS;
+    const unsigned long cell = (unsigned long)blockIdx.z * TOTAL_CELLS + k;
+    float f[NQ];
+    if (kind != nullptr && kind[cell] == KIND_OUTER) {
+        fill_invalid(f);
+    } else {
+        unsigned long j[NQ];
+        compute_neighbors(x, y, j);
+        stream_pull_load(k, f, in + base, j);
+        const bool wall = gy == 0 || gy == d_block_channel.ny - 1;
+        const bool outlet = gx == d_block_channel.nx - 1;
+        if (wall) {
+            bounce_back_swap(f);  // Wall owns all four corners; ghosts never collide.
+        } else if (gx == 0) {
+            apply_zou_he_left_velocity_inlet_d2q9(
+                f, inlet_target_u((float)gy, d_block_channel.ny, d_block_channel.velocity), 0.0f);
+        } else if (outlet) {
+            // Immutable input donor, receiver-local (also valid across a block seam).
+            float donor[NQ];
+            load_node(in + base, k - 1, donor);
+            apply_pressure_outlet_d2q9(f, donor);
+        } else {
+            apply_wall_bb_d2q9_rows(gy, d_block_channel.ny - 2, f, in + base, k);
+        }
+        if (!wall && !outlet) block_collide(f);
+    }
+    stream_pull_store(k, f, out + base);
+}

src/CelerisLab/lbm/kernels/step/block_step.cu

@@ -0,0 +1,35 @@
+// CelerisLab/lbm/kernels/step/block_step.cu
+// Generic blocked pull/collide/store for periodic/fine and slot/reservoir levels.
+// Part of the blocked.cu compilation entry; relies on its includes and guards.
+#if BLOCK_ROOT_BC == 2
+#error "BlockStep is not built for the channel root (BLOCK_ROOT_BC == 2)"
+#endif
+
+// Pull/collide/store core cells only; halo cells of out are left untouched.
+// flags (block cell ids, nullable): solid cores store NaN and never collide.
+// kind (block cell ids, nullable = all ACTIVE): OUTER skips the pull and
+// stores NaN, INNER pulls without collision, ACTIVE pulls and collides.
+extern "C" __global__ void BlockStep(const fpxx* in, fpxx* out, unsigned int halo,
+                                     const uint16_t* flags, const unsigned char* kind) {
+    unsigned int x, y; unsigned long k;
+    index_from_thread(x, y, k);
+    if (x < halo || y < halo || x >= NX - halo || y >= NY - halo) return;
+    const unsigned long base = (unsigned long)blockIdx.z * NQ * TOTAL_CELLS;
+    const unsigned long cell = (unsigned long)blockIdx.z * TOTAL_CELLS + k;
+    const unsigned char cell_kind = kind != nullptr ? kind[cell] : KIND_ACTIVE;
+    float f[NQ];
+    if (cell_kind == KIND_OUTER || (flags != nullptr && is_solid(flags[cell]))) {
+        fill_invalid(f);
+    } else {
+        unsigned long j[NQ];
+        compute_neighbors(x, y, j);  // Core neighbors stay inside the window: no wrap.
+        stream_pull_load(k, f, in + base, j);
+        if (cell_kind == KIND_ACTIVE) {
+#if BLOCK_ROOT_BC == 1
+            block_wall(f, x, y, halo);
+#endif
+            block_collide(f);
+        }
+    }
+    stream_pull_store(k, f, out + base);
+}

src/CelerisLab/lbm/kernels/step/block_transfer.cu

@@ -0,0 +1,78 @@
+// CelerisLab/lbm/kernels/step/block_transfer.cu
+// Same-level halo refresh and 2:1 explosion/coalescence between blocked levels.
+// Part of the blocked.cu compilation entry; relies on its includes and guards.
+
+// Halo refresh: block cell ids b*TOTAL_CELLS+c, sources are always core cells.
+extern "C" __global__ void BlockHaloCopy(
+    fpxx* f, const uint64_t* dst, const uint64_t* src, unsigned int count)
+{
+    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
+    if (row >= count) return;
+    const uint64_t d = dst[row], s = src[row];
+    fpxx* to = f + (d / TOTAL_CELLS) * NQ * TOTAL_CELLS;
+    const fpxx* from = f + (s / TOTAL_CELLS) * NQ * TOTAL_CELLS;
+    for (unsigned int q = 0; q < NQ; ++q)
+        to[index_f(d % TOTAL_CELLS, q)] = from[index_f(s % TOTAL_CELLS, q)];
+}
+
+// Fixed-patch explosion into blocked fine storage: target = owner block cell
+// id of a patch-ghost cell; donors are parent block cell ids and coarse_cells
+// is the parent's block window size.
+extern "C" __global__ void BlockExplode(
+    const fpxx* coarse, fpxx* fine, const uint64_t* target, const uint64_t* donor,
+    unsigned int count, unsigned long coarse_cells)
+{
+    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
+    if (row >= count) return;
+    const uint64_t t = target[row];
+    fpxx* to = fine + (t / TOTAL_CELLS) * NQ * TOTAL_CELLS;
+    const uint64_t d = donor[row];
+    const fpxx* from = coarse + (d / coarse_cells) * NQ * coarse_cells;
+    for (unsigned int q = 0; q < NQ; ++q)
+        to[index_f(t % TOTAL_CELLS, q)] = from[q * coarse_cells + d % coarse_cells];
+}
+
+// Experimental Schornbaum--Ruede (arXiv:1508.07982, Algorithm 2)
+// and Chen et al. (doi:10.1016/j.physa.2005.09.036) population interpolation.
+// Independent implementation of the mathematical stencil; no upstream source copied.
+// Stencil cells are owner cores; a disabled axis repeats its center twice.
+extern "C" __global__ void BlockExplodeProjected(
+    const fpxx* coarse, fpxx* fine, const uint64_t* target, const uint64_t* donor,
+    unsigned int count, unsigned long coarse_cells,
+    const uint64_t* neighbors, const float* offsets)
+{
+    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
+    if (row >= count) return;
+    const uint64_t t = target[row], d = donor[row];
+    fpxx* to = fine + (t / TOTAL_CELLS) * NQ * TOTAL_CELLS;
+    for (unsigned int q = 0; q < NQ; ++q) {
+        float v[4];
+        for (unsigned int a = 0; a < 4; ++a) {
+            const uint64_t n = neighbors[4ul * row + a];
+            v[a] = coarse[(n / coarse_cells) * NQ * coarse_cells
+                          + q * coarse_cells + n % coarse_cells];
+        }
+        float gx = .5f * (v[1] - v[0]), gy = .5f * (v[3] - v[2]);
+        const float ex = d_cx[q], ey = d_cy[q];
+        if (q != 0) {
+            const float along = (ex * gx + ey * gy) / (ex * ex + ey * ey);
+            gx -= ex * along;
+            gy -= ey * along;
+        }
+        to[index_f(t % TOTAL_CELLS, q)] =
+            coarse[(d / coarse_cells) * NQ * coarse_cells + q * coarse_cells + d % coarse_cells]
+            + offsets[2ul * row] * gx + offsets[2ul * row + 1] * gy;
+    }
+}
+
+// Targets are receiver-local SOURCE slots for the immediately following pull.
+// Child summation order ((c0 + c1) + c2) + c3 is part of the numerics; no collision here.
+extern "C" __global__ void BlockCoalesce(
+    const fpxx* fine, fpxx* coarse, const uint64_t* target, const uint64_t* children,
+    unsigned int count)
+{
+    unsigned int row = blockIdx.x * blockDim.x + threadIdx.x;
+    if (row >= count) return;
+    const uint64_t* s = children + 4ul * row;
+    coarse[target[row]] = 0.25f * (fine[s[0]] + fine[s[1]] + fine[s[2]] + fine[s[3]]);
+}

src/CelerisLab/lbm/kernels/step/esopull_macro.cu

@@ -3,7 +3,7 @@
 //
 // Decodes the EsoPull backing layout into physical distributions, then
 // computes rho/ux/uy.  Output is SoA: rho_out[N], ux_out[N], uy_out[N].
-// Included by kernel_v2.cu.  No standalone compilation.
+// Included by uniform.cu.  No standalone compilation.
 //
 // This kernel is the sole path for macroscopic diagnostics in EsoPull mode.
 // It uses the shared semantic helper layer (esopull_semantic_helpers.cuh).

src/CelerisLab/lbm/kernels/step/esopull_sync.cu

@@ -5,7 +5,7 @@
 // or encodes physical DDF back to EsoPull backing layout.
 // Each thread handles one cell from a compact index list.
 //
-// Included by kernel_v2.cu.  No standalone compilation.
+// Included by uniform.cu.  No standalone compilation.
 // ============================================================================
 
 #ifndef CELERIS_STEP_ESOPULL_SYNC_CU

src/CelerisLab/lbm/kernels/step/init_flow.cu

@@ -1,6 +1,6 @@
 // CelerisLab – step/init_flow.cu
 // Channel-flow initialization kernels (double-buffer and EsoPull).
-// Included by kernel_v2.cu after all headers.  No standalone compilation.
+// Included by uniform.cu after all headers.  No standalone compilation.
 // ============================================================================
 
 #ifndef CELERIS_STEP_INIT_FLOW_CU
@@ -73,9 +73,9 @@ __device__ __forceinline__ uint16_t finalize_domain_flag(
 }
 
 // ============================================================================
-// InitTubeFlow_v2 — double-buffer channel initialization
+// InitTubeFlow — double-buffer channel initialization
 // ============================================================================
-__global__ void InitTubeFlow_v2(uint16_t* flag, fpxx* fi)
+__global__ void InitTubeFlow(uint16_t* flag, fpxx* fi)
 {
 #if DIM == 2
     unsigned int x, y; unsigned long k;

src/CelerisLab/lbm/kernels/step/one_step_double.cu

@@ -1,6 +1,6 @@
 // CelerisLab – step/one_step_double.cu
 // Double-buffer PULL streaming step kernel.
-// Included by kernel_v2.cu.  No standalone compilation.
+// Included by uniform.cu.  No standalone compilation.
 // ============================================================================
 
 #ifndef CELERIS_STEP_ONE_STEP_DOUBLE_CU

src/CelerisLab/lbm/kernels/step/one_step_esopull.cu

@@ -1,6 +1,6 @@
 // CelerisLab – step/one_step_esopull.cu
 // Esoteric-Pull single-buffer step kernel.
-// Included by kernel_v2.cu.  No standalone compilation.
+// Included by uniform.cu.  No standalone compilation.
 //
 // CURVED BC: supported via PrepareEsoPullCurvedKernel + ApplyEsoPullCurvedKernel
 // in aux_kernels.cu, launched by stepper.py before EsoPullStep.

src/CelerisLab/lbm/kernels/streaming/pull_double_buffer.cuh

@@ -21,6 +21,14 @@
 //   i.e. the population traveling in direction i at node n
 //   arrived from the node at n - c_i  = neighbor in direction opp(i)
 // ---------------------------------------------------------------------------
+// load_node: all NQ populations of node n as stored (no streaming).
+__device__ __forceinline__ void load_node(const fpxx* __restrict__ fi, unsigned long n,
+                                          float* __restrict__ f)
+{
+    for (int q = 0; q < NQ; ++q)
+        f[q] = load_ddf(fi, index_f(n, q));
+}
+
 __device__ __forceinline__ void stream_pull_load(unsigned long n,
                                                  float* __restrict__ f,
                                                  const fpxx* __restrict__ fi,

src/CelerisLab/lbm/kernels/uniform.cu

@@ -1,4 +1,4 @@
-// CelerisLab – kernel_v2.cu
+// CelerisLab – uniform.cu
 // ============================================================================
 // Compilation entry point (Stage 2 Architecture).
 //
@@ -7,7 +7,7 @@
 //
 // File layout (each <300 lines):
 //   operators/helpers.cuh  — bounce_back_swap, collide_dispatch
-//   step/init_flow.cu      — InitTubeFlow_v2, InitEsoPull
+//   step/init_flow.cu      — InitTubeFlow, InitEsoPull
 //   step/one_step_double.cu — OneStep (pull double-buffer)
 //   step/one_step_esopull.cu — EsoPullStep (single-buffer)
 //   step/aux_kernels.cu    — CurvedBoundaryKernel, SensorKernel

src/CelerisLab/lbm/population_storage.py

@@ -0,0 +1,24 @@
+"""Private D2Q9 FP32 storage boundary for the opt-in blocked steppers."""
+from dataclasses import dataclass
+import numpy as np
+
+# Unit-density reference weights in FP64; sum(w)=1 matches rho=1+sum(g).
+_WEIGHTS = np.array([4/9, 1/9, 1/9, 1/9, 1/9, 1/36, 1/36, 1/36, 1/36],
+                    dtype=np.float64)[:, None, None]
+
+
+@dataclass(frozen=True, eq=False)
+class _StoredPopulations:
+    values: tuple
+    shifted: bool
+
+
+def _encode_physical(values, shifted):
+    if not shifted:
+        return np.array(values, dtype=np.float32, order="C", copy=True)
+    return np.ascontiguousarray(np.asarray(values, dtype=np.float64) - _WEIGHTS,
+                                dtype=np.float32)
+
+
+def _decode_stored(values, shifted):
+    return values.astype(np.float64) + _WEIGHTS if shifted else values

src/CelerisLab/lbm/raw_exchange.py

@@ -0,0 +1,47 @@
+"""Host-only reduction of raw cut-link observations; no stress/GI correction.
+
+Rows are unique physical links. All quantities are 2D, per unit out-of-plane
+thickness; centers are in the root edge frame, torque is about the named body.
+"""
+import numpy as np
+
+
+def summarize_exchange(rows, body_ids, aperture, *, body_id, level, h,
+                       time_end, window, reference_center, duration=None):
+    """Reduce FP64 interval integrals or convert FP32 last-substep raw rows.
+
+    dt_l=h_l under acoustic 2:1 refinement. Local momentum j -> base force
+    h*j -> impulse h*dt*j; torque adds one h; mass is h**2*dm.
+    window="window" reduces an FP64 observation-window ledger spanning
+    ``duration`` (integer >= 1) base intervals; rates divide by that duration.
+    """
+    if window not in ("last_base_step", "last_substep", "window"):
+        raise ValueError("unknown exchange window")
+    if window == "window":
+        if isinstance(duration, bool) or not isinstance(duration, (int, np.integer)) or duration < 1:
+            raise ValueError("window duration must be an integer number of base intervals >= 1")
+    elif duration is not None:
+        raise ValueError("duration applies only to window='window'")
+    values = np.array(rows, dtype=np.float64, copy=True)
+    if window == "window":
+        duration = float(duration)
+    else:
+        duration = 1.0 if window == "last_base_step" else h
+    if window == "last_substep":
+        values *= np.array([h*h, h*h, h*h*h, h*h])
+    selected = np.asarray(body_ids) == body_id
+    aperture = np.asarray(aperture, bool)
+
+    def reduce(mask):
+        integral = values[mask].sum(axis=0, dtype=np.float64)
+        return dict(impulse=integral[:2].copy(), angular_impulse=float(integral[2]),
+                    mass_into_fluid=float(integral[3]), force=integral[:2] / duration,
+                    torque=float(integral[2] / duration), mass_rate=float(integral[3] / duration))
+
+    return dict(wall=reduce(selected & ~aperture), aperture=reduce(selected & aperture),
+                total=reduce(selected), body_id=int(body_id), level=int(level),
+                time_start=time_end-duration, time_end=time_end, dt=h,
+                sample_count=(round(duration/h) if window == "window"
+                              else round(1/h) if window == "last_base_step" else 1),
+                window=window, units="base_lattice_per_unit_depth",
+                definition="raw_boundary_exchange", reference_center=tuple(reference_center), valid=True)

src/CelerisLab/lbm/refinement.py

@@ -52,17 +52,17 @@ class FixedPatch2D:
     def from_config(cls, cfg: LBMConfig, bounds) -> "FixedPatch2D":
         """Prepare maps without changing cfg or allocating coarse-sized tables.
 
-        The initial backend contract is D2Q9/SRT/FP32/unshifted/double_buffer,
+        The backend contract is D2Q9/SRT or MRT/FP32/double_buffer,
         without LES. Two coarse cells of margin keep all halo donors in bounds;
         this does NOT certify that those donors are fluid or periodic.
         """
         checked = replace(cfg)
         checked.validate()
-        if (not checked.is_d2q9 or checked.collision != "SRT"
+        if (not checked.is_d2q9 or checked.collision not in ("SRT", "MRT")
                 or checked.streaming != "double_buffer"
                 or checked.store_precision != "FP32"
-                or checked.ddf_shifting or checked.les_enabled):
-            raise ValueError("FixedPatch2D requires D2Q9/SRT/FP32/unshifted/double_buffer without LES")
+                or checked.les_enabled):
+            raise ValueError("FixedPatch2D requires D2Q9/SRT or MRT/FP32/double_buffer without LES")
         bounds = tuple(bounds)
         if len(bounds) != 4 or any(isinstance(v, (bool, np.bool_))
                                    or not isinstance(v, Integral) for v in bounds):
@@ -115,8 +115,9 @@ class FixedPatch2D:
         return self.bounds[0] - HALO / 2, self.bounds[1] - HALO / 2
 
     @property
-    def fine_level_origin(self) -> tuple[int, int]:
-        """(y, x) of this window's first cell on the level-wide 2:1 fine grid."""
+    def fine_level_offset(self) -> tuple[int, int]:
+        """Array index (y, x) of this window's first cell on the level-wide 2:1 fine grid
+        (an index offset, not an (x, y) origin)."""
         return 2 * self.bounds[1] - HALO, 2 * self.bounds[0] - HALO
 
     @property
@@ -151,20 +152,16 @@ class FixedPatch2D:
             raise ValueError("levels are not synchronized: fine_steps must equal 2*coarse_steps")
 
 
-MIN_PATCH_GAP = 4  # coarse cells: the full 4-fine-cell supports stay disjoint
 
 
 @dataclass(frozen=True, eq=False)
 class FixedPatchSet2D:
-    """Several separated FixedPatch2D rectangles sharing one 2:1 fine level.
+    """Rectangles describing one 2:1 fine union, with unique transfer ownership.
 
-    The fine level is the whole (2*ny, 2*nx) grid in level coordinates; only
-    the patch supports (active region + HALO ghost band) are stored, by a
-    sparse BlockLayout2D from fine_layout(). Tables have FixedPatch2D meaning
-    and row/child order, re-addressed to level cells: ghost_fine are level
-    fine cells, coalesce_fine are q*N+cell level slots; coarse ids unchanged.
-    Patches are kept in canonical (y0, x0) order, so input order is irrelevant.
-    Active regions must be >= MIN_PATCH_GAP coarse cells apart (Chebyshev).
+    Input patches remain canonical metadata. Numerical kinds and tables are
+    built once from their union; adjacent, overlapping and concave unions are
+    accepted when their actual transfer dependencies close. Sparse storage owns
+    every whole tile intersecting the support, independent of rectangle edges.
     """
     coarse_shape: tuple[int, int]
     patches: tuple
@@ -182,42 +179,43 @@ class FixedPatchSet2D:
         if not rectangles:
             raise ValueError("at least one patch rectangle is required")
         patches = sorted((FixedPatch2D.from_config(cfg, r) for r in rectangles),
-                         key=lambda p: (p.bounds[1], p.bounds[0]))
-        for i, a in enumerate(patches):
-            for b in patches[i + 1:]:
-                (ax0, ay0, ax1, ay1), (bx0, by0, bx1, by1) = a.bounds, b.bounds
-                if max(ay0 - by1, by0 - ay1, ax0 - bx1, bx0 - ax1) < MIN_PATCH_GAP:
-                    raise ValueError(f"patches {a.bounds} and {b.bounds} are closer "
-                                     f"than {MIN_PATCH_GAP} coarse cells")
+                         key=lambda p: (p.bounds[1], p.bounds[0], p.bounds[3], p.bounds[2]))
         ny, nx = patches[0].coarse_shape
-        fy, fx = 2 * ny, 2 * nx
-        if fy * fx * 9 > np.iinfo(np.uint64).max // 2:
-            raise ValueError("fine level exceeds 64-bit indexing")
-        kind = np.full((fy, fx), OUTER_GHOST, np.uint8)
-        ghost_fine, coalesce_fine = [], []
-        for p in patches:
-            y0, x0 = p.fine_level_origin
-            ly, lx = p.fine_shape
-            kind[y0:y0 + ly, x0:x0 + lx] = p.fine_kind
-            gy, gx = np.divmod(p.ghost_fine.astype(np.int64), lx)
-            ghost_fine.append((gy + y0) * fx + gx + x0)
-            q, cell = np.divmod(p.coalesce_fine.astype(np.int64), ly * lx)
-            cy, cx = np.divmod(cell, lx)
-            coalesce_fine.append(q * fy * fx + (cy + y0) * fx + cx + x0)
-        ghost_coarse = np.concatenate([p.ghost_coarse for p in patches])
-        coalesce_coarse = np.concatenate([p.coalesce_coarse for p in patches])
         covered = np.zeros((ny, nx), bool)
         for p in patches:
             covered |= p.covered
-        cells = ny * nx
-        if (covered.ravel()[ghost_coarse].any()
-                or covered.ravel()[coalesce_coarse % np.uint64(cells)].any()
-                or len(np.unique(coalesce_coarse)) != len(coalesce_coarse)):
-            raise ValueError("patch transfers overlap another patch")
-        return cls((ny, nx), tuple(patches), patches[0].tau_coarse, patches[0].tau_fine,
-                   _readonly(kind, np.uint8), _readonly(np.concatenate(ghost_fine), np.uint64),
-                   _readonly(ghost_coarse, np.uint32), _readonly(coalesce_coarse, np.uint64),
-                   _readonly(np.concatenate(coalesce_fine), np.uint64).reshape(-1, 4))
+        fy, fx = 2 * ny, 2 * nx
+        if fy * fx * 9 > np.iinfo(np.uint64).max // 2:
+            raise ValueError("fine level exceeds 64-bit indexing")
+        active = np.kron(covered, np.ones((2, 2), bool))
+        inner = _dilate(active, 2)
+        support = _dilate(active, HALO)
+        kind = np.full((fy, fx), OUTER_GHOST, np.uint8)
+        kind[inner] = INNER_GHOST
+        kind[active] = ACTIVE
+        gy, gx = np.nonzero(support & ~active)
+        ghost_fine = (gy * fx + gx).astype(np.uint64)
+        ghost_coarse = ((gy >> 1) * nx + (gx >> 1)).astype(np.uint32)
+        targets, children = [], []
+        ry, rx = np.nonzero(_dilate(covered, 1) & ~covered)
+        for y, x in zip(ry.tolist(), rx.tolist()):
+            for q in range(1, 9):
+                if _closed_union_contains(covered, 2 * x + 1 - D2Q9_EX[q], 2 * y + 1 - D2Q9_EY[q]):
+                    targets.append(q * ny * nx + y * nx + x)
+                    children.append([q * fy * fx + (2 * y + dy) * fx + 2 * x + dx
+                                     for dy in (0, 1) for dx in (0, 1)])
+        targets = np.asarray(targets, np.uint64)
+        children = np.asarray(children, np.uint64).reshape(-1, 4)
+        cells = np.asarray(children % np.uint64(fy * fx), np.intp)
+        if not (kind.ravel()[cells] == INNER_GHOST).all():
+            raise ValueError("coalesce children must be INNER ghost cells")
+        pair = cls((ny, nx), tuple(patches), patches[0].tau_coarse, patches[0].tau_fine,
+                   _readonly(kind, np.uint8), _readonly(ghost_fine, np.uint64),
+                   _readonly(ghost_coarse, np.uint32), _readonly(targets, np.uint64),
+                   _readonly(children, np.uint64))
+        _transfer_footprint(pair)
+        _check_parent_pull_closure(pair)
+        return pair
 
     @property
     def fine_shape(self) -> tuple[int, int]:
@@ -240,22 +238,61 @@ class FixedPatchSet2D:
         return mask
 
     def fine_layout(self, block):
-        """Sparse non-periodic layout storing exactly the patch supports."""
+        """Sparse non-periodic tiles covering union support; domain divisibility remains."""
         from .blocks import BlockLayout2D
         block = tuple(block)
         if len(block) != 2 or any(isinstance(v, (bool, np.bool_)) or not isinstance(v, Integral)
                                   or v <= 0 for v in block):
             raise ValueError("fine block must be two positive integers (by, bx)")
         by, bx = map(int, block)
-        origins = set()
-        for p in self.patches:
-            y0, x0 = p.fine_level_origin
-            ly, lx = p.fine_shape
-            if y0 % by or x0 % bx or ly % by or lx % bx:
-                raise ValueError(f"patch {p.bounds} support is not aligned to fine blocks {block}")
-            origins.update((y, x) for y in range(y0, y0 + ly, by) for x in range(x0, x0 + lx, bx))
+        support = _dilate(self.fine_kind == ACTIVE, HALO)
+        ty, tx = np.nonzero(support)
+        origins = sorted({(int(y) // by * by, int(x) // bx * bx) for y, x in zip(ty, tx)})
         return BlockLayout2D.build(*self.fine_shape, by, bx, periodic=(False, False),
-                                   origins=sorted(origins))
+                                   origins=origins)
+
+
+def _dilate(mask, steps):
+    """Chebyshev dilation with a zero (non-periodic) exterior."""
+    out = np.asarray(mask, bool)
+    for _ in range(steps):
+        grown = out.copy()
+        grown[1:] |= out[:-1]
+        grown[:-1] |= out[1:]
+        wide = grown.copy()
+        wide[:, 1:] |= grown[:, :-1]
+        wide[:, :-1] |= grown[:, 1:]
+        out = wide
+    return out
+
+
+def _closed_union_contains(covered, mx, my):
+    """Does doubled point (mx, my) lie in a closed covered square [2X, 2X+2] x [2Y, 2Y+2]?"""
+    xs = (mx // 2 - 1, mx // 2) if mx % 2 == 0 else ((mx - 1) // 2,)
+    ys = (my // 2 - 1, my // 2) if my % 2 == 0 else ((my - 1) // 2,)
+    ny, nx = covered.shape
+    return any(0 <= y < ny and 0 <= x < nx and covered[y, x] for y in ys for x in xs)
+
+
+def _check_parent_pull_closure(pair):
+    """Every uncovered parent cell pulling q from a covered cell needs its (R, q) row; no row
+    may stage into an uncovered parent cell unless its link passes the closed union."""
+    ny, nx = pair.coarse_shape
+    rows = set(map(int, pair.coalesce_coarse))
+    if len(rows) != len(pair.coalesce_coarse):
+        raise ValueError("duplicate coalesce writer (receiver, q)")
+    covered = pair.covered
+    for y, x in zip(*np.nonzero(~covered)):
+        for q in range(1, 9):
+            sy, sx = y - D2Q9_EY[q], x - D2Q9_EX[q]
+            if 0 <= sy < ny and 0 <= sx < nx and covered[sy, sx]:
+                if q * ny * nx + y * nx + x not in rows:
+                    raise ValueError("a surviving parent ACTIVE pull lacks its coalesce row")
+    for slot in rows:
+        q, cell = divmod(slot, ny * nx)
+        y, x = divmod(cell, nx)
+        if covered[y, x] or not _closed_union_contains(covered, 2*x + 1 - D2Q9_EX[q], 2*y + 1 - D2Q9_EY[q]):
+            raise ValueError("coalesce row outside the union boundary")
 
 
 @dataclass(frozen=True, eq=False)
@@ -323,14 +360,14 @@ def nest_patch(cfg, parent, child_bounds):
 
 
 def nest_patch_set(cfg, parent, child_rectangles_in_parent):
-    """Separated child union in the parent's allocated L1 array coordinates.
+    """Child rectangle union in the parent's allocated L1 array coordinates.
 
     The root edge coordinate of L1 index (x, y) is
     ``parent.fine_origin + (x, y)/2``. For a set parent its origin is zero;
     a scalar parent's window includes its ghost band and has a shifted origin.
     The child set allocates a dense public extent twice that L1 array, while
-    its blocked storage omits holes. Both adjacent pairs retain gap >= 4 in
-    their respective parent-cell units. Validate support over the whole union.
+    its blocked storage omits holes. Validate the actual adjacent-pair support over the whole union;
+    no rectangle-gap policy is imposed.
     """
     child = FixedPatchSet2D.from_config(
         _middle_config(cfg, parent), child_rectangles_in_parent)
@@ -373,8 +410,19 @@ def _nested_kind(parent, child):
     return _readonly(composed, np.uint8)
 
 
+def _circle_in_coverage(covered, cx, cy, radius):
+    """Exact disk versus uncovered parent squares; no containing-rectangle rule."""
+    ny, nx = covered.shape
+    if cx-radius < 0 or cy-radius < 0 or cx+radius > nx or cy+radius > ny:
+        return False
+    y, x = np.nonzero(~covered)
+    dx = np.maximum(np.maximum(x-cx, cx-(x+1)), 0.)
+    dy = np.maximum(np.maximum(y-cy, cy-(y+1)), 0.)
+    return not np.any(dx*dx + dy*dy < radius*radius)
+
+
 def prepare_fine_boundary(cfg, patch, objects, *, wall_aware=False, jets=(),
-                          parent_origin=(0., 0.), parent_spacing=1.):
+                          parent_origin=(0., 0.), parent_spacing=1., _shifted_blocked=False):
     """Project fixed circles and reject boundary/transfer overlap before CUDA.
 
     Input centers/radii and Jets are in the root edge frame. ``parent_origin``
@@ -386,7 +434,7 @@ def prepare_fine_boundary(cfg, patch, objects, *, wall_aware=False, jets=(),
     Original objects are not retained or mutated. No runtime geometry updates.
     ``patch`` may be a FixedPatchSet2D: objects are then projected once onto
     the level-wide fine grid (fine_origin (0, 0)); each circle must lie inside
-    one patch, body ids are the positions in ``objects`` (never patch ids), and
+    the union, body ids are the positions in ``objects`` (never patch ids), and
     jets and the (receiver, dir) writer checks run once over the whole level.
     ``jets`` use the same coarse cell-edge frame as the objects; their
     selection is checked against true fine hits here. Jet amplitudes need no
@@ -403,8 +451,8 @@ def prepare_fine_boundary(cfg, patch, objects, *, wall_aware=False, jets=(),
     checked = replace(cfg)
     checked.validate()
     if (patch.coarse_shape != (cfg.ny, cfg.nx) or not checked.is_d2q9
-            or checked.collision != "SRT" or checked.streaming != "double_buffer"
-            or checked.store_precision != "FP32" or checked.ddf_shifting or checked.les_enabled
+            or checked.collision not in ("SRT", "MRT") or checked.streaming != "double_buffer"
+            or checked.store_precision != "FP32" or checked.les_enabled
             or patch.tau_coarse != 3*checked.viscosity+.5):
         raise ValueError("Fine boundary requires the matching fixed-patch configuration")
     from ..body.geometry.circle import CircleGeometry
@@ -416,7 +464,6 @@ def prepare_fine_boundary(cfg, patch, objects, *, wall_aware=False, jets=(),
     flags = np.full(nx * ny, FLUID, np.uint16)
     active = patch.fine_kind.ravel() == ACTIVE
     local, links = [], []
-    rects = patch.bounds if isinstance(patch, FixedPatchSet2D) else (patch.bounds,)
     covered = patch.covered
     dx = dt = .5 * parent_spacing
     fine_origin = origin + parent_spacing * np.asarray(patch.fine_origin)
@@ -430,9 +477,8 @@ def prepare_fine_boundary(cfg, patch, objects, *, wall_aware=False, jets=(),
         px, py = (np.asarray((cx, cy)) - origin) / parent_spacing
         pr = radius / parent_spacing
         if (not np.isfinite([cx, cy, radius]).all() or radius <= 0
-                or not any(x0 <= px-pr and px+pr <= x1 and y0 <= py-pr
-                           and py+pr <= y1 for x0, y0, x1, y1 in rects)):
-            raise ValueError("Entire fine circle must lie inside one physical patch")
+                or not _circle_in_coverage(covered, px, py, pr)):
+            raise ValueError("Entire fine circle must lie inside the physical patch union")
         center = tuple((v-o)/dx-.5 for v, o in zip((cx, cy), fine_origin))
         spec = obj.surface_actuation
         if spec is not None:
@@ -509,7 +555,7 @@ def prepare_fine_boundary(cfg, patch, objects, *, wall_aware=False, jets=(),
         jet_cfg.validate()
         fluid_idx, dirs, _, body_id, rx, ry, _, _ = packed
         surface_link_velocity(local, jet_cfg, flags, fluid_idx, dirs, body_id, rx, ry,
-                              jets=jets, hits=hits)
+                              jets=jets, hits=hits, _shifted_blocked=_shifted_blocked)
     return FineBoundary2D(tuple(local), _readonly(flags, np.uint16),
                           tuple(_readonly(a, a.dtype) for a in packed),
                           _readonly(sorted(boundary), np.uint32),

src/CelerisLab/lbm/refinement_tables.py

@@ -0,0 +1,154 @@
+# CelerisLab/lbm/refinement_tables.py
+"""Host-only (numpy) mapping of fixed-patch transfer and boundary tables to block storage.
+
+No CUDA import: CPU tests import these directly. refinement_stepper re-exports the names.
+"""
+from dataclasses import dataclass, replace
+
+import numpy as np
+
+from .blocks import blocked_link_tables
+from ..body.jets import _surface_links
+from .descriptors import D2Q9_EX, D2Q9_EY
+from .refinement import ACTIVE, OUTER_GHOST
+
+
+def blocked_fine_tables(patch, layout, order):
+    """Remap fixed-patch fine tables to owner-core blocked storage (host only).
+
+    Returns (explosion target block cells, coalescence child slots in the same
+    rows/child order as ``patch.coalesce_fine[order]``, per-block-cell kind with
+    unused halo entries OUTER). Coarse donors/targets are unchanged.
+    """
+    owner = layout.owner.ravel().astype(np.intp)
+    cells = patch.fine_shape[0] * patch.fine_shape[1]
+    q, cell = np.divmod(patch.coalesce_fine[order], np.uint64(cells))
+    kind = blocked_kind(layout, patch.fine_kind)
+    return (owner[patch.ghost_fine.astype(np.intp)].astype(np.uint64),
+            layout.slot(owner[cell.astype(np.intp)], q), kind)
+
+
+def blocked_kind(layout, dense_kind):
+    """Per-block-cell kind; unused halo entries and unstored holes stay OUTER."""
+    owner = layout.owner.ravel().astype(np.intp)
+    owned = layout.owned.ravel()  # sparse multipatch levels leave holes unstored
+    kind = np.full(layout.nblocks * int(np.prod(layout.local_shape)), OUTER_GHOST, np.uint8)
+    kind[owner[owned]] = np.asarray(dense_kind).ravel()[owned]
+    return kind
+
+def blocked_base_tables(patch, layout, order, wall_aware=False, *, composed_kind=None):
+    """Parent donor cells and receiver-local arrival slots, in transfer row order.
+
+    Stage arrivals only after child reads and parent halo gather, immediately
+    before parent pull. Source *owner* slots are wrong at block seams.
+    Nested pairs must pass composed_kind to retain inherited INNER/OUTER and
+    sparse holes; donors and receivers must be owned, uncovered ACTIVE cells.
+    """
+    owner = layout.owner.ravel()
+    q, receiver = np.divmod(patch.coalesce_coarse[order], np.uint64(owner.size))
+    if composed_kind is None:
+        dense_kind = np.where(patch.covered, OUTER_GHOST, ACTIVE).astype(np.uint8)
+        if wall_aware:
+            dense_kind[[0, -1]] = OUTER_GHOST
+    else:
+        dense_kind = np.asarray(composed_kind)
+        if dense_kind.shape != patch.coarse_shape:
+            raise ValueError("composed parent kind has the wrong shape")
+    donors = patch.ghost_coarse.astype(np.intp)
+    receivers = receiver.astype(np.intp)
+    legal = layout.owned.ravel() & (dense_kind.ravel() == ACTIVE) & ~patch.covered.ravel()
+    if not legal[donors].all() or not legal[receivers].all():
+        raise ValueError("child donors/receivers need owned uncovered parent ACTIVE cells")
+    offset = (np.asarray(D2Q9_EY)[q.astype(np.intp)] * layout.local_shape[1]
+              + np.asarray(D2Q9_EX)[q.astype(np.intp)])
+    source = owner[receivers].astype(np.int64) - offset
+    return (owner[donors].astype(np.uint64), layout.slot(source, q),
+            blocked_kind(layout, dense_kind))
+
+
+def projected_explosion_tables(pair, parent_layout, composed_parent_kind):
+    """Experimental transverse linear explosion, in the pair's existing row order.
+
+    Schornbaum & Rüde (2016), arXiv:1508.07982, Algorithm 2, following
+    Chen et al., doi:10.1016/j.physa.2005.09.036. Independently implemented
+    from the mathematics: centered gradients, perpendicular projection and
+    child offsets +/-1/4. The kernel applies the projection per population.
+
+    Only original explosion donors that are owned, uncovered ACTIVE cells
+    may supply gradients. Both axis neighbors must be legal; otherwise repeat
+    the center twice for zero slope. Owner-core addresses avoid stale halos.
+    The same rule applies to scalar windows, unions and every adjacent pair;
+    nested layouts retain their own per-axis (usually nonperiodic) topology.
+    """
+    ny, nx = pair.coarse_shape
+    kind = np.asarray(composed_parent_kind)
+    if parent_layout.shape != pair.coarse_shape or kind.shape != pair.coarse_shape:
+        raise ValueError("projected explosion parent layout/kind has the wrong shape")
+    donor = pair.ghost_coarse.astype(np.intp)
+    legal = np.zeros(ny * nx, bool)
+    legal[donor] = True
+    legal &= (parent_layout.owned.ravel() & ~pair.covered.ravel()
+              & (kind.ravel() == ACTIVE))
+    if not legal[donor].all():
+        raise ValueError("projected explosion donors need owned uncovered parent ACTIVE cells")
+    y, x = np.divmod(donor, nx)
+    neighbors = np.repeat(donor[:, None], 4, axis=1)
+    for axis, (dx, dy) in enumerate(((1, 0), (0, 1))):
+        minus = ((y - dy) % ny) * nx + (x - dx) % nx
+        plus = ((y + dy) % ny) * nx + (x + dx) % nx
+        valid = legal[minus] & legal[plus]
+        if not parent_layout.periodic[axis]:
+            coordinate, extent = (x, nx) if axis == 0 else (y, ny)
+            valid &= (coordinate > 0) & (coordinate < extent - 1)
+        neighbors[valid, 2 * axis] = minus[valid]
+        neighbors[valid, 2 * axis + 1] = plus[valid]
+    fy, fx = np.divmod(pair.ghost_fine, pair.fine_shape[1])
+    ox, oy = pair.fine_origin
+    offsets = np.column_stack((ox + (fx + .5) / 2 - (x + .5),
+                               oy + (fy + .5) / 2 - (y + .5)))
+    return (np.ascontiguousarray(parent_layout.owner.ravel()[neighbors], dtype=np.uint64),
+            np.ascontiguousarray(offsets, dtype=np.float32))
+
+
+# Required device columns plus optional actuation; observation arms are uploaded
+# separately only when enabled. body_id/aperture remain host reduction metadata.
+BLOCKED_BOUNDARY_DEVICE_COLUMNS = ("block", "cell", "dir", "q", "fallback", "surface_velocity")
+
+
+@dataclass
+class _BlockedBoundary:
+    """One level's stationary BFL data and mutable Jet velocity column."""
+    host: object
+    tables: dict
+    jets: tuple
+    actuated: bool
+    jet_cache: object = None
+    flags: object = None
+    device: object = None
+    kernel: object = None
+    last_raw: object = None
+    interval_integral: object = None
+    accumulate: object = None
+    window_integral: object = None  # optional observation-window FP64 ledger
+
+
+def _prepare_blocked_boundary(boundary, layout, cfg, jets, *, _shifted_blocked=False):
+    if boundary is None or layout is None:
+        return None
+    fluid_idx, dirs, q, body_id, rx, ry, _, fallback = boundary.curved_host
+    tables, _ = blocked_link_tables(layout, boundary.flags, fluid_idx, dirs, q, fallback)
+    # blocked_link_tables/map_cut_links already rejects repeated (fluid_idx, dir),
+    # independently of body_id, and repeated local writers.
+    tables.update(body_id=np.asarray(body_id, np.int32), rx=np.asarray(rx, np.float32),
+                  ry=np.asarray(ry, np.float32), aperture=np.zeros(len(dirs), bool))
+    actuated = bool(jets) or any(o.surface_actuation is not None for o in boundary.objects)
+    jet_cache = None
+    if actuated:
+        cfg = replace(cfg)
+        cfg.validate()
+        tables["surface_velocity"], tables["aperture"], shape, jet_id = _surface_links(
+            boundary.objects, cfg, boundary.flags, fluid_idx, dirs, body_id, rx, ry,
+            jets=jets, hits=boundary.curved_hits, _shifted_blocked=_shifted_blocked)
+        if jets:
+            jet_cache = (shape, jet_id)
+    return _BlockedBoundary(boundary, tables, jets, actuated, jet_cache)

src/CelerisLab/lbm/stepper.py

@@ -28,7 +28,7 @@ class LBMStepper:
             self.boundary_values_gpu = cuda.mem_alloc((6 * cfg.nx + 2 * cfg.ny * cfg.nq) * 4)
         else:
             self.step_fn = module.get_function("OneStep")
-            self.init_fn = module.get_function("InitTubeFlow_v2")
+            self.init_fn = module.get_function("InitTubeFlow")
 
         self.curved_fn = module.get_function("CurvedBoundaryKernel")
         self.prepare_esopull_curved_fn = module.get_function("PrepareEsoPullCurvedKernel")

src/CelerisLab/lbm/synchronized_remap.py

@@ -1,7 +1,7 @@
 """CPU-only whole-volume G transfer, not a runtime adaptive solver.
 
 Periodic three-level grids with fixed L0/L1 topology are supported, including
-stationary circles pinned inside unchanged L2 rectangles. The caller
+stationary circles with unchanged physical boundary/BFL support. The caller
 certifies that current owned leaves are quiescent,
 unshifted D2Q9 postcollision G at the supplied completed base interval.
 No device buffers, device boundary state, ghosts, collision or time advance
@@ -16,17 +16,19 @@ from .refinement import (ACTIVE, FixedPatch2D, FixedPatchSet2D, FineBoundary2D,
                          nest_patch_set, prepare_fine_boundary)
 from .descriptors import SOLID
 from ..body.jets import surface_link_velocity
+from .population_storage import _StoredPopulations
 
 
 @dataclass(frozen=True, eq=False)
 class RemapTopology:
-    """Validated fixed parent and separated L2 set; use ``from_config``.
+    """Validated fixed parent and L2 union; use ``from_config``.
 
     Child rectangles are in the parent's allocated L1 coordinates, including
     its window offset/halo when the parent is a scalar patch. Dense masks are
     rebuilt from geometry, never inferred from finite values in input arrays.
-    ``pinned_rectangles`` canonically lists each body-containing rectangle once;
-    fluid-only layouts have no pins.
+    ``pinned_rectangles`` is legacy metadata for single-rectangle containment.
+    Eligibility pins physical boundary/stencil data, not entire rectangles or
+    connected fluid regions; each topology independently validates transfer closure.
     """
     parent: object
     child: FixedPatchSet2D
@@ -37,7 +39,7 @@ class RemapTopology:
 
     @classmethod
     def from_config(cls, cfg, parent, child_rectangles, *, coarse_boundary="periodic", objects=(),
-                    child_objects=(), child_jets=()):
+                    child_objects=(), child_jets=(), _shifted_blocked=False):
         if coarse_boundary != "periodic" or tuple(objects) or cfg.nz != 1:
             raise ValueError("remap requires periodic 2D state; use child_objects for a pinned L2 body")
         if type(parent) not in (FixedPatch2D, FixedPatchSet2D):
@@ -49,7 +51,7 @@ class RemapTopology:
                            viscosity=2 * cfg.viscosity)
         boundary = prepare_fine_boundary(
             fine_cfg, child, child_objects, jets=child_jets,
-            parent_origin=parent.fine_origin, parent_spacing=.5)
+            parent_origin=parent.fine_origin, parent_spacing=.5, _shifted_blocked=_shifted_blocked)
         pinned, velocity = (), None
         child_leaf = child.fine_kind == ACTIVE
         if boundary is not None:
@@ -59,11 +61,14 @@ class RemapTopology:
             for obj in child_objects:
                 cx, cy = (np.asarray(obj.geometry.center) - parent.fine_origin) * 2
                 radius = obj.geometry._radius * 2
-                containing.add(next(r for r in child.bounds if
-                                    r[0] <= cx-radius and cx+radius <= r[2] and
-                                    r[1] <= cy-radius and cy+radius <= r[3]))
+                match = next((r for r in child.bounds if
+                              r[0] <= cx-radius and cx+radius <= r[2] and
+                              r[1] <= cy-radius and cy+radius <= r[3]), None)
+                if match is not None:
+                    containing.add(match)
             pinned = tuple(sorted(containing))
-            velocity = boundary_velocity(cfg, child, boundary, child_jets)
+            velocity = boundary_velocity(cfg, child, boundary, child_jets,
+                                         _shifted_blocked=_shifted_blocked)
             if velocity is not None:
                 velocity.setflags(write=False)
         masks = (~parent.covered, middle_kind == ACTIVE, child_leaf)
@@ -72,7 +77,7 @@ class RemapTopology:
         return cls(parent, child, masks, boundary, pinned, velocity)
 
 
-def boundary_velocity(cfg, child, boundary, jets=()):
+def boundary_velocity(cfg, child, boundary, jets=(), *, _shifted_blocked=False):
     """Physical cut-link order; never blocked addresses or stale Jet snapshots."""
     local_cfg = replace(cfg, nx=child.fine_shape[1], ny=child.fine_shape[0],
                         viscosity=4 * cfg.viscosity)
@@ -80,7 +85,7 @@ def boundary_velocity(cfg, child, boundary, jets=()):
     fluid, dirs, _, ids, rx, ry, _, _ = boundary.curved_host
     velocity, _ = surface_link_velocity(
         boundary.objects, local_cfg, boundary.flags, fluid, dirs, ids, rx, ry,
-        jets=jets, hits=boundary.curved_hits)
+        jets=jets, hits=boundary.curved_hits, _shifted_blocked=_shifted_blocked)
     return velocity
 
 
@@ -115,6 +120,7 @@ class RemapCandidate:
     phase: str
     origin: tuple
     spacing: float
+    shifted: bool = False
 
 
 def _same_parent(a, b):
@@ -123,7 +129,7 @@ def _same_parent(a, b):
             and a.tau_coarse == b.tau_coarse and a.tau_fine == b.tau_fine)
 
 
-def _read_leaves(topology, arrays, layouts):
+def _read_leaves(topology, arrays, layouts, *, shifted=False):
     """Unpack only owned cores; nonleaf values are not evidence of validity."""
     if len(arrays) != 3 or len(layouts) != 3:
         raise ValueError("expected three G arrays and three layouts")
@@ -137,8 +143,10 @@ def _read_leaves(topology, arrays, layouts):
             a = layout.to_dense(a)
         if a.shape != (9, *leaf.shape):
             raise ValueError("G must have Q-major (9, ny, nx) shape")
+        if shifted and a.dtype != np.float32:
+            raise ValueError("shifted stored populations must be FP32")
         values = a[:, leaf]
-        if not np.isfinite(values).all() or (values.sum(axis=0, dtype=np.float64) <= 0).any():
+        if not np.isfinite(values).all() or (values.sum(axis=0, dtype=np.float64) + int(shifted) <= 0).any():
             raise ValueError("required leaf donors must be finite with positive density")
         result.append(a)
     if len({a.dtype for a in result}) != 1:
@@ -163,14 +171,27 @@ def remap_synchronized(old, new, old_g, *, base_count, level_steps, phase,
     the source dtype. No equilibrium reconstruction or nonequilibrium scaling.
     All destination nonleaves are NaN. Inputs and their write flags are intact.
     """
+    return _remap(old, new, old_g, base_count=base_count, level_steps=level_steps,
+                  phase=phase, origin=origin, spacing=spacing, layouts=layouts)
+
+
+def _remap_stored(old, new, snapshot, *, shifted, **kwargs):
+    """Private same-representation transfer; public remap remains physical."""
+    if (not isinstance(snapshot, _StoredPopulations) or type(shifted) is not bool
+            or type(snapshot.shifted) is not bool or snapshot.shifted != shifted):
+        raise ValueError("stored population representation mismatch")
+    return _remap(old, new, snapshot.values, shifted=shifted, **kwargs)
+
+
+def _remap(old, new, old_g, *, base_count, level_steps, phase,
+           origin=(0., 0.), spacing=1., layouts=None, shifted=False):
     if (not isinstance(old, RemapTopology) or not isinstance(new, RemapTopology)
             or not _same_parent(old.parent, new.parent)
             or old.child.tau_fine != new.child.tau_fine):
         raise ValueError("remap requires unchanged L0/L1 geometry and relaxation")
-    if (old.pinned_rectangles != new.pinned_rectangles
-            or not same_physical_boundary(old.boundary, new.boundary)
+    if (not same_physical_boundary(old.boundary, new.boundary)
             or not np.array_equal(old.surface_velocity, new.surface_velocity)):
-        raise ValueError("remap requires the identical pinned body rectangles and physical boundary")
+        raise ValueError("remap requires the identical pinned physical boundary and BFL support")
     if not isinstance(level_steps, (tuple, list)):
         raise ValueError("level_steps must be three completed integer counts")
     counts = (base_count, *level_steps)
@@ -187,7 +208,7 @@ def remap_synchronized(old, new, old_g, *, base_count, level_steps, phase,
     if (frame.shape != (2,) or not np.isfinite(frame).all()
             or not np.isscalar(spacing) or not np.isfinite(spacing) or spacing <= 0):
         raise ValueError("frame needs a finite (x,y) origin and positive spacing")
-    source = _read_leaves(old, old_g, (None,)*3 if layouts is None else layouts)
+    source = _read_leaves(old, old_g, (None,)*3 if layouts is None else layouts, shifted=shifted)
     candidate = [np.full((9, *mask.shape), np.nan, dtype=source[0].dtype)
                  for mask in new.leaf_masks]
     for level, (before, after) in enumerate(zip(old.leaf_masks, new.leaf_masks)):
@@ -208,6 +229,6 @@ def remap_synchronized(old, new, old_g, *, base_count, level_steps, phase,
     # Scale first to avoid an overflowing intermediate sum for finite FP64 G.
     mean = sum(source[2][:, cy, cx].astype(np.float64) * .25 for cy, cx in children)
     candidate[1][:, y, x] = mean
-    _read_leaves(new, candidate, (None,)*3)
+    _read_leaves(new, candidate, (None,)*3, shifted=shifted)
     return RemapCandidate(new, tuple(candidate), int(base_count), tuple(map(int, level_steps)),
-                          phase, tuple(map(float, frame)), float(spacing))
+                          phase, tuple(map(float, frame)), float(spacing), shifted)

src/CelerisLab/simulation.py

@@ -25,7 +25,7 @@ import pycuda.driver as cuda
 
 from .config import LBMConfig, BodyConfig, load_lbm_config, load_body_config
 from .cuda.context import CudaContext, context_bound
-from .cuda import compiler_v2 as compiler
+from .cuda import compiler
 from .lbm.field import LBMField
 from .lbm.stepper import LBMStepper
 from .body.objects import SimObject
@@ -46,8 +46,8 @@ class Simulation:
                  device_id: int = 0):
         # Internal stream for async DTOH coordination
         self._stream: Optional[cuda.Stream] = None
-        self._build_dir = None
         self._closed = False
+        self._failed = None  # reason after an uncertain device write; only close() remains
 
         # Load configs
         self.lbm_cfg = load_lbm_config(lbm_config_path)
@@ -59,9 +59,7 @@ class Simulation:
         try:
             with self.ctx.activate():
                 arch = self._resolve_compile_arch()
-                self._build_dir = compiler.generate_config(self.lbm_cfg, n_objects=0)
-                self._ptx_path = compiler.compile_kernel(arch=arch, build_dir=self._build_dir)
-                self._module = compiler.load_module(self._ptx_path)
+                self._module = compiler.build_module(self.lbm_cfg, "uniform.cu", arch=arch)
                 self._compiled_n_objects = 0
                 self._allocation_signature = self.lbm_cfg.allocation_signature()
                 self._compiled_viscosity = self.lbm_cfg.viscosity
@@ -92,6 +90,7 @@ class Simulation:
     @context_bound
     def stream(self) -> cuda.Stream:
         """Internal CUDA stream for async DTOH coordination."""
+        self._require_usable()
         if self._stream is None:
             self._stream = cuda.Stream()
         return self._stream
@@ -175,15 +174,27 @@ class Simulation:
     def set_jet_amplitude(self, index: int, amplitude: float) -> None:
         """Change one jet's signed amplitude; re-uploads per-link velocity only.
 
-        Invalid input changes nothing. A device error leaves the host amplitude
-        unchanged but the device column undefined: treat it like any other CUDA
-        exception here and close/recreate the Simulation before stepping again.
+        Invalid input raises before any change. Any error after validation
+        (stream creation or upload) leaves the host amplitude unchanged but the
+        device column undefined, so the Simulation is marked failed: every later
+        device-touching public method (incl. ``stream``) raises; close() still
+        works. Close and recreate it.
         """
+        self._require_usable()
         jet = self.bodies.jets[index].with_amplitude(amplitude)
         if self._initialized:
-            self.field.curved.set_jet_amplitude(index, amplitude, self.stream)
+            try:
+                self.field.curved.set_jet_amplitude(index, amplitude, self.stream)
+            except BaseException as exc:
+                self._failed = f"jet amplitude upload failed: {exc!r}"
+                raise
         self.bodies.jets[index] = jet  # later geometry syncs keep the new amplitude
 
+    def _require_usable(self):
+        failed = getattr(self, "_failed", None)
+        if failed is not None:
+            raise RuntimeError(f"Simulation failed ({failed}); close() and recreate it")
+
     def remove_body(self, id: int) -> None:
         """Remove a body from the simulation.
 
@@ -336,13 +347,20 @@ class Simulation:
     def read_surface_exchange(self, id: int):
         """Latest step's wall/aperture (Fx,Fy,Tz) exchange, not total nozzle force.
 
+        Supports SurfaceActuation and Jet-driven bodies, including zero-amplitude
+        apertures. Passive bodies without an aperture are rejected.
         Unlike read_body this is not accumulated/time-averaged. It resets after
         geometry sync or checkpoint load; advance before interpreting it.
         """
-        if self.bodies.get(id).surface_actuation is None:
+        self._require_usable()
+        obj = self.bodies.get(id)
+        curved = self.field.curved
+        has_aperture = (curved.aperture is not None
+                        and np.any(curved.aperture & (curved.body_id == id)))
+        if obj.surface_actuation is None and not has_aperture:
             raise ValueError("Body has no surface actuation")
         self.stream.synchronize()
-        return self.field.curved.surface_exchange(id)
+        return curved.surface_exchange(id)
 
     @context_bound
     def read_body(self, id: int, *,
@@ -362,6 +380,7 @@ class Simulation:
             BodyTelemetry with fields ``force``, ``torque``, ``sensor``.
             ``sensor`` is a dim-length array of zeros for non-sensor bodies.
         """
+        self._require_usable()
         if self.bodies.obs_pinned is None:
             raise RuntimeError("No obs buffer. Call run() first.")
         if stream is None:
@@ -381,6 +400,7 @@ class Simulation:
         This is the most efficient readback for DRL control loops
         (single contiguous D2H copy, no Python per-body overhead).
         """
+        self._require_usable()
         if self.bodies.obs_pinned is None:
             raise RuntimeError("No obs buffer. Call run() first.")
         if stream is None:
@@ -406,15 +426,8 @@ class Simulation:
         self.lbm_cfg.validate_runtime()
         self._assert_allocation_contract()
         arch = self._resolve_compile_arch()
-        next_dir = compiler.generate_config(self.lbm_cfg, n_objects=expected_n_objects)
-        try:
-            next_ptx = compiler.compile_kernel(arch=arch, build_dir=next_dir)
-            next_module = compiler.load_module(next_ptx)
-        except Exception:
-            compiler.cleanup_build_dir(next_dir)
-            raise
-        old_dir = self._build_dir
-        self._build_dir, self._ptx_path, self._module = next_dir, next_ptx, next_module
+        self._module = compiler.build_module(self.lbm_cfg, "uniform.cu", arch=arch,
+                                             n_objects=expected_n_objects)
         self._compiled_n_objects = int(expected_n_objects)
 
         # Reconnect field and stepper to new module
@@ -432,7 +445,6 @@ class Simulation:
         self.stepper._step_count = _prev_step_count
 
         self._assert_object_count_contract(expected_count=expected_n_objects)
-        compiler.cleanup_build_dir(old_dir)
 
     def recompile(self):
         """Re-generate config headers and recompile kernel.
@@ -451,18 +463,22 @@ class Simulation:
     @context_bound
     def initialize(self):
         """Initialize flow field and sync objects to GPU."""
-        # Recompile if objects were added after construction.
+        self._require_usable()
         self._assert_allocation_contract()
+        # Validate the complete geometry before flags, populations or modules
+        # change. Compact-list construction publishes no outputs on failure.
+        next_flags = self.bodies.build_flags(self.field.build_channel_flags())
+        if self.bodies.jets and self.bodies.count == 0:
+            raise ValueError("Jets need bodies with cut links")
+        self.bodies.build_compact_lists_for(self.bodies.objects, next_flags)
+
+        # Recompile if objects were added after construction.
         if self._read_generated_n_objects() != self.bodies.count:
             self.recompile()
 
-        self.field.flag = self.field.build_channel_flags()
-        if self.bodies.count > 0:
-            self.field.flag = self.bodies.build_flags(self.field.flag)
+        self.field.flag = next_flags
         self.field.upload_flags()
 
-        if self.bodies.jets and self.bodies.count == 0:
-            raise ValueError("Jets need bodies with cut links")
         self.stepper.initialize()
         if self.bodies.count > 0:
             self.bodies.sync_to_gpu(self.field, rebuild_flags=False)
@@ -480,6 +496,7 @@ class Simulation:
         In EsoPull mode, the backing layout is decoded to physical DDF on
         GPU for the patched cells only, patched on host, then encoded back.
         """
+        self._require_usable()
         if not self._initialized:
             raise RuntimeError("Call initialize() before sync_bodies()")
 
@@ -575,6 +592,7 @@ class Simulation:
                 sensor) on GPU and reset the step accumulator before stepping.
             checkpoint_interval: Nonnegative integer; if >0, save every N steps.
         """
+        self._require_usable()
         if not self._initialized:
             raise RuntimeError("Call initialize() first")
         steps = operator.index(steps)
@@ -639,10 +657,12 @@ class Simulation:
     @context_bound
     def get_macroscopic(self) -> Dict[str, np.ndarray]:
         """Download DDF and return rho, ux, uy [, uz]."""
+        self._require_usable()
         return self.field.get_macroscopic(step_id=self.stepper.step_count)
 
     @context_bound
     def get_ddf(self) -> np.ndarray:
+        self._require_usable()
         self.field.download_ddf(step_id=self.stepper.step_count)
         return self.field.ddf.copy()
 
@@ -656,23 +676,27 @@ class Simulation:
 
         Accepted: omega, fx, fy, fz, n_objects.
         """
+        self._require_usable()
         self.field.update_params(**kwargs)
 
     # -- Snapshots -----------------------------------------------------------
     @context_bound
     def snapshot(self):
         """Snapshot the flow field; restore keeps the current clock and controls."""
+        self._require_usable()
         self.field.snapshot(step_id=self.stepper.step_count)
 
     @context_bound
     def restore(self):
         """Restore the saved flow field at the current streaming parity."""
+        self._require_usable()
         self.field.restore(step_id=self.stepper.step_count)
 
     # -- Checkpoint / Restore (HDF5) ----------------------------------------
     @context_bound
     def save_checkpoint(self, path: str = None):
         """Save full simulation state to an HDF5 file."""
+        self._require_usable()
         from .common.checkpoint import save_checkpoint
         if self.bodies.jets:
             raise NotImplementedError("Jets are not checkpointed yet")
@@ -682,6 +706,7 @@ class Simulation:
     @context_bound
     def load_checkpoint(self, path: str):
         """Restore simulation state from an HDF5 checkpoint."""
+        self._require_usable()
         from .common.checkpoint import load_checkpoint
         if not self._initialized:
             self.initialize()
@@ -706,8 +731,6 @@ class Simulation:
                 self._module = None
                 self._stream = None
             ctx.close()
-        compiler.cleanup_build_dir(getattr(self, "_build_dir", None))
-        self._build_dir = None
         self._closed = True
 
     def __enter__(self):

tests/__init__.py

@@ -0,0 +1 @@
+"""CelerisLab test package; keeps shared test helpers independent of discovery paths."""

tests/integration/test_checkpoint_bodies_gpu.py

@@ -0,0 +1,66 @@
+"""Checkpoint save -> load round trip for a scene with passive bodies. Requires GPU.
+
+A fresh Simulation with the same scene, restored from the checkpoint must hold the same populations,
+flags, body count and step count, and must stay bitwise identical to the original
+after both continue for the same number of steps. Checkpoints with Jets are
+refused (documented limitation) and are not covered here.
+"""
+
+import os
+import tempfile
+import unittest
+
+import numpy as np
+
+from ._cases import make_sim
+
+# Three separated cylinders (pinball-like); cut-link receivers stay in bulk fluid.
+CIRCLES = (((40, 32), 6), ((56, 22), 6), ((56, 42), 6))
+
+
+def scene():
+    sim = make_sim()
+    sim.initialize()
+    for center, radius in CIRCLES:
+        sim.add_body("circle", center=center, radius=radius)
+    sim.sync_bodies()
+    return sim
+
+
+class CheckpointBodiesGPU(unittest.TestCase):
+    def test_round_trip_is_bitwise_and_continues_identically(self):
+        sim = scene()
+        sim.run(60)
+        with tempfile.NamedTemporaryFile(suffix=".h5", delete=False) as f:
+            path = f.name
+        restored = None
+        try:
+            saved = sim.save_checkpoint(path)
+            # The loader requires the same body count and geometry: rebuild the scene.
+            restored = scene()
+            restored.load_checkpoint(saved)
+
+            self.assertEqual(restored.bodies.count, len(CIRCLES))
+            self.assertEqual(restored.stepper.step_count, sim.stepper.step_count)
+            np.testing.assert_array_equal(restored.get_flags(), sim.get_flags())
+            a, b = sim.get_ddf(), restored.get_ddf()
+            self.assertEqual(a.dtype, b.dtype)
+            self.assertEqual(a.tobytes(), b.tobytes())
+
+            sim.run(40)
+            restored.run(40)
+            self.assertEqual(restored.stepper.step_count, sim.stepper.step_count)
+            a, b = sim.get_ddf(), restored.get_ddf()
+            self.assertTrue(np.isfinite(a).all())
+            self.assertEqual(a.tobytes(), b.tobytes())
+            for i in range(len(CIRCLES)):
+                self.assertTrue(np.all(np.isfinite(restored.read_force(i))))
+        finally:
+            if restored is not None:
+                restored.close()
+            os.unlink(path)
+            sim.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_jet_update_gpu.py

@@ -0,0 +1,53 @@
+"""Direct Simulation Jet control upload; boundary-law accuracy is tested elsewhere."""
+import numpy as np
+import pycuda.driver as cuda
+
+from CelerisLab.body.jets import Jet, Radial, Sector
+from CelerisLab.lbm.descriptors import FLUID
+from ._cases import make_sim
+
+
+def test_simulation_jet_amplitude_upload_and_continued_steps():
+    # Same grid/circle/sector as the existing uniform surface-actuation fixture.
+    center = (16., 12.)
+    with make_sim(nx=32, ny=24, velocity=0) as sim:
+        sim.add_body("circle", center=center, radius=4.3)
+        index = sim.add_jet(Jet(Sector(center, .7, .85, 4.4),
+                                Radial(center, inward=False), "quartic", .002))
+        sim.initialize()
+        curved = sim.field.curved
+        shape, jet_id = curved.jet_shape.copy(), curved.jet_id.copy()
+        flags = sim.get_flags()
+        driven = jet_id == index
+        assert driven.any() and (~driven).any()
+        velocity_pointer = int(curved.surface_velocity_gpu)
+        previous = None
+        for interval, amplitude in enumerate((.002, -.001)):
+            if interval:
+                count = sim.stepper.step_count
+                sim.set_jet_amplitude(index, amplitude)
+                assert sim.stepper.step_count == count  # update does not step
+            expected = np.zeros_like(curved.surface_velocity)
+            expected[driven] = (amplitude * shape[driven]).astype(np.float32)
+            actual = np.empty_like(expected)
+            with sim.ctx.activate():
+                cuda.memcpy_dtoh(actual, curved.surface_velocity_gpu)
+            np.testing.assert_array_equal(actual, expected)  # actual device column
+            np.testing.assert_array_equal(curved.surface_velocity, expected)
+            assert np.any(actual[driven] != 0)
+            if previous is not None:
+                assert not np.array_equal(actual[driven], previous[driven])
+            previous = actual.copy()
+            assert sim.bodies.jets[index].amplitude == amplitude
+            assert curved.jets[index].amplitude == amplitude
+            assert int(curved.surface_velocity_gpu) == velocity_pointer
+            np.testing.assert_array_equal(curved.jet_shape, shape)
+            np.testing.assert_array_equal(curved.jet_id, jet_id)
+            np.testing.assert_array_equal(sim.get_flags(), flags)
+            sim.run(2)
+            assert sim.stepper.step_count == 2 * (interval + 1)
+            assert sim._failed is None
+            macro = sim.get_macroscopic()
+            fluid = (flags.reshape(24, 32) & FLUID) != 0
+            assert all(np.isfinite(value[fluid]).all() for value in macro.values())
+            assert np.all(macro["rho"][fluid] > 0)

tests/integration/test_runtime_contracts_gpu.py

@@ -6,14 +6,14 @@ import pycuda.driver as cuda
 import pytest
 
 import CelerisLab
-from CelerisLab.cuda import compiler_v2
+from CelerisLab.cuda import compiler
 from ._cases import make_sim
 
 
 def test_source_provenance():
     root = Path(__file__).resolve().parents[2] / "src/CelerisLab"
     assert Path(CelerisLab.__file__).resolve().parent == root
-    assert Path(compiler_v2.kernel_path("kernel_v2.cu")).resolve() == root / "lbm/kernels/kernel_v2.cu"
+    assert Path(compiler.kernel_path("uniform.cu")).resolve() == root / "lbm/kernels/uniform.cu"
 
 
 def test_two_contexts_interleaved_and_non_lifo_close():
@@ -21,7 +21,7 @@ def test_two_contexts_interleaved_and_non_lifo_close():
     first = make_sim(nx=32, ny=16)
     second = make_sim(nx=48, ny=24, streaming="esopull", shifted=True)
     try:
-        assert first._build_dir != second._build_dir
+        assert first._module is not second._module
         assert cuda.Context.get_current() == before
         first.initialize()
         second.initialize()

tests/integration/test_state_gpu.py

@@ -65,9 +65,14 @@ def test_shifted_topology_add_remove_preserves_cache_and_finite_flow(streaming,p
         assert np.max(macro['rho'][fluid]) < 1.5
 
 
-@pytest.mark.parametrize('streaming',['double_buffer','esopull'])
-def test_checkpoint_exact_continuation_and_controls(streaming,tmp_path):
-    with make_sim(nx=48,ny=24,streaming=streaming,shifted=True) as sim:
+@pytest.mark.parametrize('collision,streaming', [
+    pytest.param('SRT', 'double_buffer', id='double_buffer'),
+    pytest.param('SRT', 'esopull', id='esopull'),
+    pytest.param('TRT', 'double_buffer', id='trt-double_buffer'),
+])
+def test_checkpoint_exact_continuation_and_controls(collision,streaming,tmp_path):
+    # Same collision throughout save/load/continue; this is not a method-switch restart.
+    with make_sim(nx=48,ny=24,streaming=streaming,shifted=True,collision=collision) as sim:
         sim.add_body('circle',center=(14,12),radius=3)
         sim.add_body('force_region',center=(30,12),radius=2)
         sim.initialize()

tests/unit/cpp/channel_root.cpp

@@ -0,0 +1,85 @@
+// Actual production step kernels under a CPU launch shim. No CUDA claim.
+#include <cmath>
+#include <cstdio>
+#include <cstdint>
+#include <vector>
+#define __device__
+#define __constant__
+#define __global__
+#define __forceinline__ inline
+#define __launch_bounds__(...)
+#define LATTICE_D2Q9 0
+#define LATTICE_D3Q19 1
+#define LATTICE_MODEL 0
+#define NQ 9
+#define DIM 2
+#define NZ 1
+#define NT 1
+#define COLLISION_MODEL 0
+#define BLOCK_ROOT_BC 2
+#define USE_LES 0
+#define RHO 1.f
+#define U0 .025f
+#define OMEGA_COLLISION_MIN .01f
+#define OMEGA_COLLISION_MAX 1.99f
+#define Y_WALL_BC 0
+#define OUTLET_MODE 0
+struct Dim {unsigned int x=0,y=0,z=0;} threadIdx,blockIdx,blockDim;
+inline float __fdiv_rn(float a,float b){return a/b;}
+#include "core/precision.cuh"
+#include "core/descriptors.cuh"
+#include "core/layout.cuh"
+#include "core/params.cuh"
+#include "core/flags.cuh"
+#include "operators/macro.cuh"
+#include "operators/collision_srt.cuh"
+#include "streaming/pull_double_buffer.cuh"
+#if UNIFORM
+#include "operators/forcing_guo.cuh"
+#include "operators/helpers.cuh"
+#include "boundary/bounce_back.cuh"
+#include "boundary/inlet_outlet.cuh"
+#include "step/one_step_double.cu"
+#else
+#include "core/cell_kind.cuh"
+#include "step/block_channel.cu"
+#endif
+int main(){
+    constexpr int gx=24,gy=20,n=gx*gy;
+    std::vector<float> state(9*n),next(9*n);
+    for(int q=0;q<9;q++)for(int y=0;y<gy;y++)for(int x=0;x<gx;x++)
+        state[q*n+y*gx+x]=d_w[q]*(1.f+.001f*std::sin(float(x+3*y+q)))-USE_DDF_SHIFTING*d_w[q];
+    d_params={1.25f,0,0,0,0};
+#if UNIFORM
+    std::vector<uint16_t> flags(n,FLAG_FLUID);
+    for(int y=0;y<gy;y++)for(int x=0;x<gx;x++){
+        if(y==0||y==gy-1) flags[y*gx+x]=FLAG_SOLID|FLAG_BC_WALL;
+        else if(x==0) flags[y*gx+x]=FLAG_SOLID|FLAG_BC_INLET;
+        else if(x==gx-1) flags[y*gx+x]=FLAG_SOLID|FLAG_BC_OUTLET;
+    }
+#else
+    constexpr int bx=NX-2,by=NY-2,nbx=gx/bx,nby=gy/by;
+    std::vector<float> input(nbx*nby*9*TOTAL_CELLS),output(input.size());
+    d_block_channel={gx,gy,U0};
+#endif
+    for(int step=0;step<5;step++){
+#if UNIFORM
+        for(int y=0;y<gy;y++)for(int x=0;x<gx;x++){
+            blockIdx={unsigned(x),unsigned(y),0};OneStep(flags.data(),state.data(),next.data());
+        }
+#else
+        // Populate cores and every wrapped halo from the same dense source.
+        for(int b=0;b<nbx*nby;b++)for(int y=0;y<NY;y++)for(int x=0;x<NX;x++)for(int q=0;q<9;q++){
+            int xx=((b%nbx)*bx+x-1+gx)%gx, yy=((b/nbx)*by+y-1+gy)%gy;
+            input[b*9*TOTAL_CELLS+q*TOTAL_CELLS+y*NX+x]=state[q*n+yy*gx+xx];
+        }
+        for(int b=0;b<nbx*nby;b++)for(int y=1;y<NY-1;y++)for(int x=1;x<NX-1;x++){
+            blockIdx={unsigned(x),unsigned(y),unsigned(b)};
+            BlockChannelStep(input.data(),output.data(),1,nullptr,nullptr);
+            for(int q=0;q<9;q++)next[q*n+((b/nbx)*by+y-1)*gx+(b%nbx)*bx+x-1]=output[b*9*TOTAL_CELLS+q*TOTAL_CELLS+y*NX+x];
+        }
+#endif
+        state.swap(next);
+    }
+    for(float f:state)printf("%.9g\n",f);
+}

tests/unit/cpp/collision_regression.cpp

@@ -13,6 +13,8 @@
 #define OMEGA_COLLISION_MAX 1.99f
 struct Params {float omega, fx, fy, fz;} d_params;
 #include "core/descriptors.cuh"
+// Host round-to-nearest shim; CUDA intrinsic behavior is tested on-device.
+inline float __fdiv_rn(float a, float b) { return a / b; }
 #include "operators/macro.cuh"
 #include "operators/collision_srt.cuh"
 #include "operators/collision_trt.cuh"

tests/unit/cpp/semantic_regression.cpp

@@ -34,6 +34,8 @@ inline int obs_torque_index(int,int){return 0;}
 #include "core/descriptors.cuh"
 #include "core/precision.cuh"
 #include "core/layout.cuh"
+// Host round-to-nearest shim; CUDA intrinsic behavior is tested on-device.
+inline float __fdiv_rn(float a, float b) { return a / b; }
 #include "operators/macro.cuh"
 #include "operators/collision_srt.cuh"
 #include "operators/collision_trt.cuh"

tests/unit/cpp/shifted_block_operators.cpp

@@ -0,0 +1,45 @@
+#include <cmath>
+#include <cstdio>
+#include <initializer_list>
+#define __device__
+#define __constant__
+#define __forceinline__ inline
+#define LATTICE_D2Q9 0
+#define LATTICE_MODEL 0
+#define NQ 9
+#define DIM 2
+#define USE_DDF_SHIFTING 1
+#define WALL_NORMAL_VELOCITY 0.f
+#define WALL_SLOT_WIDTH 0
+#define NX 16
+#include "core/descriptors.cuh"
+// Host round-to-nearest shim; CUDA intrinsic behavior is tested on-device.
+inline float __fdiv_rn(float a, float b) { return a / b; }
+#include "operators/macro.cuh"
+#include "operators/collision_srt.cuh"
+#include "boundary/planar_velocity.cuh"
+void emit(const float* f) {for(int q=0;q<9;q++) printf("%.9g ",f[q]);puts("");}
+int main() {
+    for(float delta : {0.f, 0x1p-30f, -0x1p-30f, .0002f})
+    for(float u : {0.f,.005f}) {
+        float eq[9]; compute_feq(1.f+delta,u,-.2f*u,eq,delta);
+        printf("E %.9g %.9g %.9g\n",delta,u,-.2f*u);emit(eq);
+    }
+    for(float delta : {0.f, 0x1p-30f, -0x1p-30f, .04f, -.01f})
+    for(float jx : {0.f,.005f,-.02f}) {
+        const float jy = -.2f*jx, rho = 1.f+delta;
+        const float ux = jx/rho, uy = jy/rho;
+        float eq[9];compute_feq_from_momentum(delta,jx,jy,ux,uy,eq);
+        printf("J %.9g %.9g %.9g %.9g %.9g\n",delta,jx,jy,ux,uy);emit(eq);
+    }
+    for(int mode : {0,1,2}) for(float rho : {1.f,1.04f}) {
+        float f[9];const float u=.007f,v=.003f;
+        compute_feq(rho,u,v,f,rho-1.f);
+        for(int q=0;q<9;q++)f[q]+=.00001f*(q-4);
+        printf("B %d %.9g %.9g %.9g\n",mode,rho,u,v);emit(f);
+        if(mode==0)reconstruct_bottom_velocity(f,u,v);
+        else if(mode==1)reconstruct_top_velocity(f,u,v);
+        else reconstruct_top_reservoir(f,rho);
+        emit(f);
+    }
+}

tests/unit/historical_tree.py

@@ -0,0 +1,46 @@
+"""Check historical source manifests against their own recorded commit, not today's checkout."""
+
+import io
+from pathlib import Path
+import subprocess
+import tarfile
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def _require(commit):
+    """Missing recorded history is an explicit failure, never a skip or a repin."""
+    found = subprocess.run(
+        ["git", "-C", str(ROOT), "cat-file", "-e", commit + "^{commit}"],
+        capture_output=True,
+    )
+    if found.returncode:
+        raise AssertionError(
+            f"Required history missing: commit {commit} is not in this clone; "
+            "fetch it instead of repinning or substituting"
+        )
+
+
+def tracked(commit, prefix="src"):
+    """Tracked paths under prefix at the recorded commit."""
+    _require(commit)
+    return set(
+        subprocess.check_output(
+            ["git", "-C", str(ROOT), "ls-tree", "-r", "--name-only", commit, prefix],
+            text=True,
+        ).splitlines()
+    )
+
+
+def historical_tree(commit, dest):
+    """Extract the tracked tree of the recorded commit into dest."""
+    _require(commit)
+    archive = subprocess.check_output(
+        ["git", "-C", str(ROOT), "archive", "--format=tar", commit]
+    )
+    dest = Path(dest)
+    dest.mkdir(parents=True, exist_ok=True)
+    extra = {"filter": "data"} if hasattr(tarfile, "data_filter") else {}
+    with tarfile.open(fileobj=io.BytesIO(archive)) as tar:
+        tar.extractall(dest, **extra)
+    return dest

tests/unit/test_build_contracts.py

@@ -83,6 +83,32 @@ assert abs(sum(compute_feq_d2q9(1.,0.,0.)) - 1.) < 1e-6
 
 
 class BuildContracts(unittest.TestCase):
+    def test_block_root_modes_are_rendered_and_recorded(self):
+        with tempfile.TemporaryDirectory() as root:
+            for mode in (0, 1, 2):
+                with self.subTest(mode=mode):
+                    build = compiler.generate_config(LBMConfig(), build_root=root, block_root_bc=mode)
+                    try:
+                        method = Path(build, "config/config_method.h").read_text()
+                        self.assertIn(f"#define BLOCK_ROOT_BC {mode}\n", method)
+                        metadata = json.loads(Path(build, ".celeris-build").read_text())
+                        self.assertEqual(metadata["block_root_bc"], mode)
+                        self.assertNotIn("block_root_bc", metadata["config"])
+                    finally:
+                        compiler.cleanup_build_dir(build)
+            build = compiler.generate_config(LBMConfig(), build_root=root)
+            try:
+                self.assertEqual(json.loads(Path(build, ".celeris-build").read_text())["block_root_bc"], 0)
+            finally:
+                compiler.cleanup_build_dir(build)
+
+    def test_invalid_block_root_mode_fails_before_snapshot(self):
+        for mode in (-1, 3, True, False, 1.0, "1", None):
+            with self.subTest(mode=mode), patch.object(compiler.tempfile, "mkdtemp") as allocate:
+                with self.assertRaisesRegex(ValueError, "block_root_bc"):
+                    compiler.generate_config(LBMConfig(), block_root_bc=mode)
+                allocate.assert_not_called()
+
     @staticmethod
     def fake_compile(command, check):
         source = Path(command[-3])
@@ -100,8 +126,7 @@ class BuildContracts(unittest.TestCase):
             def work(nx, count):
                 build = compiler.generate_config(LBMConfig(nx=nx), count, build_root=root)
                 barrier.wait()
-                # Compatibility form is context-local even without explicit path.
-                output = compiler.compile_kernel()
+                output = compiler.compile_kernel(build_dir=build)
                 data = json.loads(Path(output).read_text())
                 self.assertEqual(data, {"nx": nx, "objects": count})
                 metadata = json.loads(Path(output + ".json").read_text())
@@ -130,7 +155,7 @@ class BuildContracts(unittest.TestCase):
             compiler.cleanup_build_dir(a)
             compiler.cleanup_build_dir(b)
             with self.assertRaises(RuntimeError):
-                compiler.compile_kernel()
+                compiler.compile_kernel(build_dir=a)  # removed snapshot is never compiled
 
     def test_failed_compile_cannot_implicitly_load_previous_artifact(self):
         with tempfile.TemporaryDirectory() as root:
@@ -143,8 +168,7 @@ class BuildContracts(unittest.TestCase):
                 with self.assertRaises(subprocess.CalledProcessError):
                     compiler.compile_kernel(build_dir=build)
             self.assertEqual(Path(previous).read_bytes(), old_bytes)
-            with self.assertRaisesRegex(RuntimeError, "No compiled PTX"):
-                compiler.load_module()
+            self.assertEqual(sorted(Path(build).glob("uniform-*.ptx")), [])  # no partial output
             compiler.cleanup_build_dir(build)
 
 

tests/unit/test_channel_parity_diagnostic.py

@@ -0,0 +1,47 @@
+"""CPU-only traceback capture checks; no CUDA or GPU test import."""
+import importlib.util
+from pathlib import Path
+from types import SimpleNamespace
+import numpy as np
+
+PATH = Path(__file__).resolve().parents[1] / 'validation/multigrid/channel_parity_diagnostic/discover.py'
+spec = importlib.util.spec_from_file_location('channel_discovery', PATH)
+discovery = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(discovery)
+
+
+def test_captures_exact_original_frame_and_arrays():
+    def test_uniform_matched_root():
+        cfg = SimpleNamespace(velocity=.025)
+        shifted, profile, clamp, damping, block = True, 'parabolic', False, .8, (4, 1)
+        expected = np.array([.001], np.float32)
+        actual = np.nextafter(expected, np.float32(1))
+        np.testing.assert_array_equal(actual, expected)
+    try:
+        test_uniform_matched_root()
+    except AssertionError as exc:
+        config, expected, actual = discovery.capture_case(exc)
+    assert config['shifted'] == 1 and config['profile'] == 'parabolic'
+    assert config['clamp'] == 0 and config['damping'] == .8
+    assert config['block'] == [4, 1] and config['steps'] == 8
+    np.testing.assert_array_equal(actual, np.nextafter(expected, np.float32(1)))
+    assert expected.flags.owndata and actual.flags.owndata
+
+
+def test_other_assertion_does_not_guess_case():
+    def test_uniform_matched_root():
+        cfg = SimpleNamespace(velocity=.025)
+        shifted, profile, clamp, damping, block = False, 'uniform', True, .5, (20, 24)
+        expected = actual = np.array([np.nan], np.float32)
+        assert np.isfinite(expected).all()
+    try:
+        test_uniform_matched_root()
+    except AssertionError as exc:
+        assert discovery.capture_case(exc) is None
+
+
+def test_unrelated_array_assertion_does_not_guess_case():
+    try:
+        np.testing.assert_array_equal([1], [2])
+    except AssertionError as exc:
+        assert discovery.capture_case(exc) is None

tests/unit/test_channel_root.py

@@ -0,0 +1,102 @@
+"""Root-channel host contract and actual-header CPU parity (no CUDA evidence)."""
+from dataclasses import replace
+import numpy as np
+import pytest
+
+from CelerisLab.config import LBMConfig
+from CelerisLab.lbm.blocks import BlockLayout2D
+from CelerisLab.lbm.channel import channel_masks, validate_channel_config, validate_channel_transfers
+from CelerisLab.lbm.refinement import FixedPatch2D
+from CelerisLab.lbm.refinement_tables import blocked_base_tables
+from .test_numerical_operators import compile_run
+
+
+@pytest.mark.parametrize("shift", [0, 1])
+@pytest.mark.parametrize("profile", [0, 1])
+@pytest.mark.parametrize("clamp,damping", [(1, ".5f"), (0, ".8f")])
+def test_actual_kernel_uniform_parity(tmp_path, shift, profile, clamp, damping):
+    """Nonuniform ghosts, corners, top wall, global profile and outlet halo donor."""
+    defines = dict(USE_DDF_SHIFTING=shift, INLET_PROFILE=profile,
+                   OUTLET_BACKFLOW_CLAMP=clamp, OUTLET_SRT_NEQ_DAMP=damping)
+    uniform = np.array(compile_run(tmp_path, "channel_root.cpp", dict(
+        defines, UNIFORM=1, NX=24, NY=20)), np.float32)
+    assert np.isfinite(uniform).all()
+    for by, bx in ((20, 24), (5, 6), (4, 1)):
+        blocked = np.array(compile_run(tmp_path, "channel_root.cpp", dict(
+            defines, UNIFORM=0, NX=bx+2, NY=by+2)), np.float32)
+        np.testing.assert_array_equal(blocked, uniform)
+
+
+def transfer(bounds, block=(4, 6)):
+    cfg = LBMConfig(nx=24, ny=20, viscosity=.1)
+    pair = FixedPatch2D.from_config(cfg, bounds)
+    layout = BlockLayout2D.build(20, 24, *block)
+    targets = blocked_base_tables(pair, layout, np.argsort(pair.coalesce_coarse))[1]
+    return pair, layout, targets
+
+
+def test_masks_and_minimal_footprint():
+    fluid, bulk = channel_masks((20, 24))
+    assert fluid.sum() == 18*22 and bulk.sum() == 16*22
+    assert fluid[1, 1] and not bulk[1, 1]
+    assert bulk[2, 1] and not fluid[0, 0]
+    # No tile alignment or artificial large padding: closest legal x donor is x=1.
+    validate_channel_transfers(*transfer((3, 4, 19, 16)))
+    for bounds in ((2, 4, 19, 16), (3, 3, 19, 16), (3, 4, 22, 16), (3, 4, 19, 17)):
+        with pytest.raises(ValueError, match="bulk"):
+            validate_channel_transfers(*transfer(bounds))
+
+
+def test_actual_closure_read_conflicts():
+    pair, layout, targets = transfer((6, 6, 18, 14))
+    validate_channel_transfers(pair, layout, targets)
+    for target in (layout.slot(int(layout.owner[5, -1]) - 1, 2),  # integer under NumPy 1 and 2
+                   layout.slot(layout.owner[1, 4], 4),
+                   layout.slot(layout.owner[-2, 4], 3)):
+        with pytest.raises(ValueError, match="immutable"):
+            validate_channel_transfers(pair, layout, np.append(targets, target))
+
+
+def test_channel_scope():
+    cfg = LBMConfig(nx=24, ny=20, viscosity=.1)
+    validate_channel_config(cfg, [(4, 6), (4, 4)])
+    with pytest.raises(ValueError, match="all-blocked"):
+        validate_channel_config(cfg, [None, (4, 4)])
+    for change in (dict(inlet_scheme="equilibrium"), dict(outlet_mode="zero_gradient"),
+                   dict(y_wall_bc="free_slip"), dict(wall_slot_width=2)):
+        with pytest.raises(ValueError, match="channel requires"):
+            validate_channel_config(replace(cfg, **change), [(4, 6), (4, 4)])
+
+
+def test_evolved_ghost_snapshot_and_physical_download():
+    from contextlib import nullcontext
+    from unittest.mock import Mock
+    from .test_refinement_three_level_multipatch import host_module
+    host = host_module()
+    storage = {}
+    host.compiler.build_module.return_value.get_global.side_effect = lambda name: (name, 12 if name == "d_block_channel" else 20)
+    host.cuda.mem_alloc.side_effect = lambda size: Mock()
+    host.cuda.memcpy_htod.side_effect = lambda ptr, a: storage.__setitem__(id(ptr), np.array(a, copy=True))
+    host.cuda.memcpy_dtoh.side_effect = lambda a, ptr: np.copyto(a, storage[id(ptr)])
+    context = Mock(activate=nullcontext, sm_arch="sm_70")
+    cfg = LBMConfig(nx=24, ny=20, viscosity=.1, velocity=.025)
+    backend = host.FixedPatchStepper(cfg, context=context, coarse_boundary="channel",
+                                    refinements=[(6, 6, 18, 14)], level_blocks=[(4, 6), (4, 4)])
+    try:
+        weights = np.array([4/9]+[1/9]*4+[1/36]*4)[:, None, None]
+        arrays = [np.broadcast_to(weights, level.shape).copy() for level in backend._levels]
+        arrays[0][:, 0, 0] *= 1.001
+        backend.initialize(*arrays)
+        snapshot = backend._download_raw()
+        assert np.isfinite(snapshot.values[0][:, 0, :]).all()
+        assert np.isnan(backend.download()[0][:, 0, :]).all()
+        backend._initialize_raw(snapshot)
+        for a, b in zip(snapshot.values, backend._download_raw().values):
+            np.testing.assert_array_equal(a, b)
+        arrays[0][0, 0, 0] = np.nan
+        with pytest.raises(ValueError, match="finite"):
+            backend.initialize(*arrays)
+        assert backend._levels[0].kernel == host.compiler.build_module.return_value.get_function("BlockChannelStep")
+        assert [call.kwargs["block_root_bc"] for call in host.compiler.build_module.call_args_list] == [2, 0]
+    finally:
+        backend.close()

tests/unit/test_dfg_re20.py

@@ -0,0 +1,79 @@
+"""CPU-only contract tests for run_dfg_re20. Not CUDA or DFG acceptance evidence."""
+
+import sys
+from pathlib import Path
+import unittest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "validation"))
+import run_dfg_re20 as v  # noqa: E402
+import run_refined_dfg as rr  # noqa: E402
+
+h, _ = rr.helpers(rr.DEFAULT_SOURCE)
+
+
+def rows(values, tstar_end=v.TSTAR_MAX):
+    n = int(round(tstar_end / v.SAMPLE_TSTAR))
+    return [dict(tstar=(i + 1) * v.SAMPLE_TSTAR, **values(i)) for i in range(n)]
+
+
+class Re20Contract(unittest.TestCase):
+    def test_lattice_parameters_and_bounds(self):
+        root, uniform = v.lattice_parameters(40), v.lattice_parameters(80)
+        self.assertAlmostEqual(root["tau"], 0.56, places=12)
+        self.assertAlmostEqual(uniform["tau"], 0.62, places=12)
+        self.assertEqual((root["steps"], root["interval"]), (240000, 2000))
+        self.assertEqual((uniform["steps"], uniform["interval"]), (480000, 4000))
+        self.assertAlmostEqual(v.plan()["refined_fine_tau"], 0.62, places=12)
+
+    def test_config_only_changes_viscosity(self):
+        base = v._re100_config(h, 40, "SRT", "none")
+        cfg, body, p = v.config(h, 40, "SRT")
+        self.assertAlmostEqual(cfg["physics"]["viscosity"], 0.01 * 40 / 20, places=15)
+        self.assertEqual((p["re"], p["viscosity"]), (20.0, cfg["physics"]["viscosity"]))
+        base[0]["physics"]["viscosity"] = cfg["physics"]["viscosity"]
+        self.assertEqual(base[0], cfg)
+        self.assertEqual(base[1], body)
+        with self.assertRaisesRegex(ValueError, "no Jets"):
+            v.config(h, 40, "MRT", "zero")
+
+    def test_units(self):
+        s = v.sample([2.0, -0.5], 4, 40, 3.0)
+        den = rr.SPEED**2 * 40 / 2
+        self.assertAlmostEqual(s["cd"], 2.0 / 4 / den)
+        self.assertAlmostEqual(s["cl"], -0.5 / 4 / den)
+        self.assertAlmostEqual(s["p_diff"], 3.0 * 0.04)
+        self.assertEqual(s["dp_scaled"], 3.0)
+
+    def test_steady_and_verdict(self):
+        inside = dict(cd=5.58, cl=0.0106, p_diff=0.1174)
+        out = v.summarize(rows(lambda i: inside))
+        self.assertEqual((out["status"], out["steady"], out["window_samples"]),
+                         ("WITHIN_INTERVALS", True, 21))
+        self.assertTrue(out["cd_positive"])
+        self.assertAlmostEqual(out["edge_distance"]["cl"], 0.0002)
+        self.assertTrue(all(out["verdict"].values()))
+        low = v.summarize(rows(lambda i: dict(inside, cl=0.0100)))
+        self.assertEqual(low["status"], "OUTSIDE_INTERVALS")
+        self.assertFalse(low["verdict"]["cl"])
+
+    def test_slow_drift_gives_no_verdict(self):
+        # Range 2e-5 passes (limit 6e-5); slope * window 2e-5 exceeds 1.2e-5.
+        out = v.summarize(rows(lambda i: dict(cd=5.58, cl=0.0106 + 1e-6 * i, p_diff=0.1174)))
+        self.assertEqual((out["status"], out["verdict"]), ("NOT_STEADY", None))
+        self.assertLessEqual(out["ranges"]["cl"], out["range_limits"]["cl"])
+        self.assertGreater(out["drifts"]["cl"], out["slope_limits"]["cl"])
+
+    def test_noise_range(self):
+        quiet = v.summarize(rows(lambda i: dict(cd=5.58, cl=0.0106 + 2e-5 * (i % 2), p_diff=0.1174)))
+        self.assertTrue(quiet["steady"])  # within the range limit, no trend
+        noisy = v.summarize(rows(lambda i: dict(cd=5.58, cl=0.0106 + 1e-4 * (i % 2), p_diff=0.1174)))
+        self.assertEqual(noisy["status"], "NOT_STEADY")
+        self.assertGreater(noisy["ranges"]["cl"], noisy["range_limits"]["cl"])
+
+    def test_incomplete_run_gives_no_verdict(self):
+        out = v.summarize(rows(lambda i: dict(cd=5.58, cl=0.0106, p_diff=0.1174), tstar_end=30))
+        self.assertEqual((out["status"], out["verdict"]), ("INCOMPLETE", None))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_example_tiles.py

@@ -0,0 +1,70 @@
+"""The public examples run all-blocked: their level tiles must reach the device unchanged.
+
+Host only: a context whose activation raises proves construction (layouts, tables,
+boundary checks) succeeded up to the first CUDA call.
+"""
+import ast
+from dataclasses import replace
+from pathlib import Path
+import unittest
+from unittest.mock import Mock
+
+from CelerisLab.body.geometry.circle import CircleGeometry
+from CelerisLab.body.objects import SimObject
+from CelerisLab.config import LBMConfig
+from CelerisLab.lbm.refinement_stepper import FixedPatchStepper
+
+EXAMPLES = Path(__file__).resolve().parents[2] / "examples"
+
+
+def literal(name, constant):
+    """Module-level literal from an example, read without importing it (no pycuda)."""
+    tree = ast.parse((EXAMPLES / name).read_text())
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                names = target.elts if isinstance(target, ast.Tuple) else [target]
+                for i, t in enumerate(names):
+                    if isinstance(t, ast.Name) and t.id == constant:
+                        value = node.value.elts[i] if isinstance(target, ast.Tuple) else node.value
+                        return ast.literal_eval(value)
+    raise KeyError(constant)
+
+
+def forbidden():
+    return Mock(activate=Mock(side_effect=AssertionError("CUDA reached")), sm_arch="sm_70")
+
+
+class ExampleTiles(unittest.TestCase):
+    def test_fixed_patch_jet_tiles(self):
+        bounds, blocks = literal("fixed_patch_jet.py", "BOUNDS"), literal("fixed_patch_jet.py", "LEVEL_BLOCKS")
+        width, amplitude = literal("fixed_patch_jet.py", "WIDTH"), literal("fixed_patch_jet.py", "AMPLITUDE")
+        cfg = LBMConfig(nx=48, ny=48, viscosity=.1, velocity=0., wall_slot_width=width,
+                        wall_normal_velocity=amplitude, y_wall_bc="on_site_velocity",
+                        top_wall_bc="reservoir")
+        with self.assertRaisesRegex(AssertionError, "CUDA reached"):
+            FixedPatchStepper(cfg, context=forbidden(), coarse_boundary="slot_reservoir",
+                              refinements=[bounds], level_blocks=[tuple(b) for b in blocks])
+
+    def test_fixed_periodic_patch_tiles(self):
+        with self.assertRaisesRegex(AssertionError, "CUDA reached"):
+            FixedPatchStepper(LBMConfig(nx=16, ny=16, viscosity=.1, velocity=1e-3), context=forbidden(),
+                              refinements=[(4, 4, 12, 12)], level_blocks=[(16, 16), (24, 24)])
+
+    def test_fixed_patch_circle_default_tiles(self):
+        bounds = literal("fixed_patch_circle.py", "BOUNDS")
+        nx, ny = literal("fixed_patch_circle.py", "NX"), literal("fixed_patch_circle.py", "NY")
+        center, radius = literal("fixed_patch_circle.py", "CENTER"), literal("fixed_patch_circle.py", "RADIUS")
+        body = SimObject(0, geometry=CircleGeometry(*center, radius), center=center, radius=radius)
+        periodic = LBMConfig(nx=nx, ny=ny, viscosity=.1)
+        slot = replace(periodic, velocity=0, wall_normal_velocity=.001, wall_slot_width=8,
+                       y_wall_bc="on_site_velocity", top_wall_bc="reservoir")
+        for mode, cfg in (("periodic", periodic), ("slot_reservoir", slot)):
+            with self.subTest(mode=mode), self.assertRaisesRegex(AssertionError, "CUDA reached"):
+                FixedPatchStepper(cfg, context=forbidden(), coarse_boundary=mode,
+                                  refinements=[bounds], level_blocks=[(12, 8), (16, 20)],
+                                  level_objects=[(), (body,)])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_hierarchy.py

@@ -0,0 +1,97 @@
+"""CPU geometry tests for lbm.hierarchy (no CUDA). Geometry construction only, not LBM numerics."""
+import unittest
+
+import numpy as np
+from CelerisLab.config import LBMConfig
+from CelerisLab.lbm import refinement as r
+from CelerisLab.lbm.hierarchy import build_hierarchy, leaf_partition
+
+CFG = LBMConfig(nx=48, ny=48, viscosity=.02)
+L1 = [(6, 6, 26, 26), (32, 30, 42, 42)]   # L0 cells; L1 ACTIVE x/y 12..52 and x 64..84, y 60..84
+L2 = [(20, 20, 44, 44), (72, 68, 76, 76)]  # L1 cells; L2 ACTIVE 40..88 and x 144..152, y 136..152
+L3 = [(56, 56, 72, 72)]                    # L2 cells
+FOUR = [L1, L2, L3]
+SMALL = LBMConfig(nx=16, ny=16, viscosity=.1)
+
+
+class FourLevels(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.h = build_hierarchy(CFG, FOUR)
+
+    def test_config_chain(self):
+        self.assertEqual(self.h.depth, 4)
+        for level, c in enumerate(self.h.configs):
+            self.assertEqual((c.ny, c.nx), (48 << level, 48 << level))
+            self.assertAlmostEqual(c.viscosity, .02 * 2 ** level, places=12)
+            self.assertEqual(self.h.kinds[level].shape, (c.ny, c.nx))
+        for level, p in enumerate(self.h.pairs):
+            self.assertAlmostEqual(p.tau_coarse, 1 / self.h.configs[level].omega, places=12)
+            self.assertAlmostEqual(p.tau_fine, 1 / self.h.configs[level + 1].omega, places=12)
+
+    def test_partition_and_composition(self):
+        h = self.h
+        np.testing.assert_array_equal(leaf_partition(h), np.ones((48, 48)))
+        for level in (1, 2):
+            covered, raw = h.pairs[level].covered, h.pairs[level - 1].fine_kind
+            self.assertTrue((h.kinds[level][covered] == r.OUTER_GHOST).all())
+            np.testing.assert_array_equal(h.kinds[level][~covered], raw[~covered])
+        np.testing.assert_array_equal(h.kinds[3], h.pairs[2].fine_kind)
+
+    def test_depth_is_list_length(self):
+        for depth in range(1, 5):
+            h = build_hierarchy(CFG, FOUR[:depth - 1])
+            self.assertEqual(h.depth, depth)
+            np.testing.assert_array_equal(leaf_partition(h), np.ones((48, 48)))
+            for level in range(depth - 1):
+                np.testing.assert_array_equal(h.kinds[level], self.h.kinds[level])
+
+    def test_illegal_coverage_reports_first_guard(self):
+        cases = [([L1, [(10, 20, 30, 44)]], "inherited ACTIVE"),
+                 ([L1, L2[:1] + [(54, 54, 58, 58)]], "inherited ACTIVE"),
+                 ([L1, L2, [(40, 40, 60, 60)]], "donors/receivers"),
+                 ([L1, L2, [(41, 41, 60, 60)]], "donors/receivers")]
+        for levels, reason in cases:
+            with self.subTest(levels=levels), self.assertRaisesRegex(ValueError, reason):
+                build_hierarchy(CFG, levels)
+        build_hierarchy(CFG, [L1, L2, [(56, 56, 64, 64), (66, 56, 72, 64)]])  # gap 2 closes
+        build_hierarchy(CFG, [L1, L2, [(42, 42, 60, 60)]])  # minimal legal margin
+
+
+class LegacyForms(unittest.TestCase):
+    def test_scalar_parent_and_child_match_existing_calls(self):
+        local = r.FixedPatch2D.from_config(SMALL, (4, 4, 12, 12))
+        child, kind = r.nest_patch(SMALL, local, (8, 8, 16, 16))
+        h = build_hierarchy(SMALL, [(4, 4, 12, 12), (8, 8, 16, 16)])
+        np.testing.assert_array_equal(h.kinds[0], np.where(local.covered, r.OUTER_GHOST, r.ACTIVE))
+        np.testing.assert_array_equal(h.kinds[1], kind)
+        np.testing.assert_array_equal(h.kinds[2], child.fine_kind)
+        for name in ("ghost_fine", "ghost_coarse", "coalesce_coarse", "coalesce_fine"):
+            np.testing.assert_array_equal(getattr(h.pairs[1], name), getattr(child, name))
+        np.testing.assert_array_equal(leaf_partition(h), np.ones((16, 16)))
+
+    def test_set_child_under_scalar_parent(self):
+        local = r.FixedPatch2D.from_config(SMALL, (4, 4, 12, 12))
+        child, kind = r.nest_patch_set(SMALL, local, [(8, 8, 16, 16)])
+        h = build_hierarchy(SMALL, [(4, 4, 12, 12), [(8, 8, 16, 16)]])
+        np.testing.assert_array_equal(h.kinds[1], kind)
+        np.testing.assert_array_equal(h.pairs[1].coalesce_fine, child.coalesce_fine)
+        np.testing.assert_array_equal(leaf_partition(h), np.ones((16, 16)))
+
+    def test_scalar_child_under_set_parent_is_rejected(self):
+        with self.assertRaisesRegex(ValueError, "scalar parent"):
+            build_hierarchy(SMALL, [[(4, 4, 12, 12)], (12, 12, 20, 20)])
+
+    def test_wall_rows_and_single_level(self):
+        h = build_hierarchy(SMALL, [(4, 4, 12, 12)], wall_aware=True)
+        self.assertTrue((h.kinds[0][[0, -1]] == r.OUTER_GHOST).all())
+        one = build_hierarchy(SMALL, [])
+        self.assertEqual(one.depth, 1)
+        self.assertTrue((one.kinds[0] == r.ACTIVE).all())
+        walled = build_hierarchy(SMALL, [], wall_aware=True)  # regression: no refinement
+        self.assertTrue((walled.kinds[0][[0, -1]] == r.OUTER_GHOST).all())
+        self.assertTrue((walled.kinds[0][1:-1] == r.ACTIVE).all())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_jet_circle_cv.py

@@ -0,0 +1,181 @@
+"""CPU-only science, geometry, units, and source tests; no PyCUDA import."""
+
+import sys
+from pathlib import Path
+import unittest
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[2]
+REPO = ROOT
+sys.path.insert(0, str(ROOT / "tests/validation"))
+sys.path.insert(0, str(ROOT / "tests/unit"))
+sys.path.insert(0, str(REPO / "src"))
+from run_jet_circle_cv import (
+    CX,
+    CY,
+    W,
+    case,
+    state,
+    cv,
+    cv_from_macros,
+    aperture_probe,
+    measured_aperture_flux,
+    PIN,
+    verify,
+)
+
+
+def eq(rho, u, v):
+    cu = CX[:, None, None] * u + CY[:, None, None] * v
+    return W[:, None, None] * rho * (1 + 3 * cu + 4.5 * cu**2 - 1.5 * (u * u + v * v))
+
+
+class Host(unittest.TestCase):
+    def test_public_macros_pressure_advection_and_cropped_frames(self):
+        for h, origin, shape, rect in (
+            (.5, (0., 0.), (48, 64), (5., 4., 25., 20.)),
+            (.5, (.25, .5), (48, 64), (5.25, 4., 25.25, 20.)),
+            (.25, (.375, .75), (96, 128), (5.125, 4., 25.125, 20.)),
+        ):
+            y, x = np.indices(shape)
+            x = origin[0] + h * (x + .5)
+            k, u, v = 1e-5, .02, -.01
+            rho = 1 + 3 * k * x  # p=(rho-1)/3=k*x
+            ux, uy, fluid = np.full(shape, u), np.full(shape, v), np.ones(shape, bool)
+            result = cv_from_macros(rho, ux, uy, fluid, origin, rect, .004, h)
+            expected = 320 * np.array([3*k*u, k + 3*k*u*u, 3*k*u*v])
+            np.testing.assert_allclose(result[1], expected, rtol=1e-11, atol=1e-13)
+            np.testing.assert_allclose(result, cv(eq(rho, u, v), fluid, origin, rect, .004, h), atol=1e-12)
+            x0, y0, x1, y1 = np.rint((np.array(rect)-np.tile(origin, 2))/h).astype(int)
+            selection = np.s_[y0-2:y1+2, x0-2:x1+2]
+            cropped_origin = np.asarray(origin) + h*np.array([x0-2, y0-2])
+            cropped = cv_from_macros(rho[selection], ux[selection], uy[selection],
+                                    fluid[selection], cropped_origin, rect, .004, h)
+            np.testing.assert_array_equal(cropped, result)
+
+    def test_public_macros_full_normal_viscous_stress(self):
+        y, x = np.indices((48, 64))
+        x = (x + .5) * .5
+        rho, ux, uy, fluid = np.ones_like(x), 1e-4*x*x, np.zeros_like(x), np.ones(x.shape, bool)
+        args = (rho, ux, uy, fluid, (0., 0.), (5., 4., 25., 20.))
+        _, viscous = cv_from_macros(*args, .004)
+        _, inviscid = cv_from_macros(*args, 0.)
+        np.testing.assert_allclose(viscous-inviscid, [0, -4*.004*1e-4*320, 0], atol=1e-13)
+        with self.assertRaisesRegex(ValueError, "matching 2D"):
+            cv_from_macros(rho, ux, uy[:-1], fluid, (0, 0), (5, 4, 25, 20), .004)
+
+    def test_descriptor_and_uniform_closed_flux(self):
+        from CelerisLab.lbm.descriptors import D2Q9_EX, D2Q9_EY
+
+        np.testing.assert_array_equal(CX, D2Q9_EX)
+        np.testing.assert_array_equal(CY, D2Q9_EY)
+        rho = np.full((48, 64), 1.01)
+        g = eq(rho, 0.023, -0.017)
+        inventory, flux = cv(g, np.ones((48, 64), bool), (0, 0), (5, 4, 25, 20), 0.0072)
+        np.testing.assert_allclose(
+            inventory, 320 * 1.01 * np.array([1, 0.023, -0.017]), atol=1e-12
+        )
+        np.testing.assert_allclose(flux, 0, atol=1e-14)
+
+    def test_affine_velocity_independent_divergence(self):
+        y, x = np.mgrid[:48, :64]
+        x = (x + 0.5) * 0.5
+        y = (y + 0.5) * 0.5
+        a = 0.001
+        g = eq(np.ones_like(x), a * x, -a * y)
+        _, flux = cv(g, np.ones(x.shape, bool), (0, 0), (5, 4, 25, 20), 0.0072)
+        np.testing.assert_allclose(
+            flux, [0, a * a * 320 * 15, a * a * 320 * 12], atol=1e-13
+        )
+
+    def test_quadratic_viscous_flux_sign_and_units(self):
+        y, x = np.mgrid[:48, :64]
+        y = (y + 0.5) * 0.5
+        a = 0.0001
+        nu = 0.0072
+        g = eq(np.ones_like(y), a * y * y, np.zeros_like(y))
+        _, flux = cv(g, np.ones(y.shape, bool), (0, 0), (5, 4, 25, 20), nu)
+        np.testing.assert_allclose(flux, [0, -2 * nu * a * 320, 0], atol=2e-14)
+
+    def test_geometry_adapter_match_and_apertures(self):
+        from CelerisLab.config import LBMConfig
+        from CelerisLab.body.geometry.circle import CircleGeometry
+        from CelerisLab.body.objects import SimObject
+        from CelerisLab.body.jets import Jet, Sector, Radial, jet_link_shapes
+        from CelerisLab.lbm.refinement import FixedPatch2D, prepare_fine_boundary
+        from CelerisLab.lbm.descriptors import SOLID
+
+        c = case()
+        center = np.array(c["center"])
+        r = c["diameter"] / 2
+        cfg = LBMConfig(nx=c["nx"], ny=c["ny"], viscosity=c["nu"])
+        cfg.validate()
+        patch = FixedPatch2D.from_config(cfg, c["bounds"])
+        obj = SimObject(0, CircleGeometry(*center, r), center=tuple(center), radius=r)
+        jets = [
+            Jet(
+                Sector(tuple(center), a, np.pi / 12, r + 0.1),
+                Radial(tuple(center), inward=False),
+                "uniform",
+                s * c["jet_speed"],
+            )
+            for a, s in [(np.pi / 2, 1), (3 * np.pi / 2, -1)]
+        ]
+        host = prepare_fine_boundary(cfg, patch, [obj], jets=jets)
+        shape, ids = jet_link_shapes(jets, host.curved_hits)
+        self.assertTrue((ids == 0).any() and (ids == 1).any() and (ids < 0).any())
+        self.assertGreater(host.curved_host[2].min(), 0.010001)
+        self.assertFalse(np.any(host.curved_host[-1]))
+        links = CircleGeometry(*(2 * center - 0.5), 2 * r).build_cut_links(
+            2 * c["nx"], 2 * c["ny"]
+        )
+        np.testing.assert_array_equal([v.dir for v in links], host.curved_host[1])
+        np.testing.assert_allclose(
+            [v.q for v in links], host.curved_host[2], atol=2e-7, rtol=0
+        )
+        np.testing.assert_allclose(
+            np.array([[v.hit_x, v.hit_y] for v in links]) * 0.5 + 0.25,
+            host.curved_hits,
+            atol=2e-12,
+        )
+        fluid = (host.flags.reshape(patch.fine_shape) & SOLID) == 0
+        g = state((9, *patch.fine_shape), c["u"])
+        g[:, ~fluid] = np.nan
+        for contour in c["contours"]:
+            cv(g, fluid, patch.fine_origin, contour, c["nu"])
+        probe = aperture_probe(fluid, patch.fine_origin, center, r)
+        measured = measured_aperture_flux(g, probe)
+        np.testing.assert_allclose(
+            measured, 0, atol=1e-14
+        )  # x-directed flow has zero flux on symmetric top/bottom arcs
+        print(
+            "GEOMETRY",
+            dict(
+                links=len(links),
+                aperture_counts=[int((ids == i).sum()) for i in [0, 1]],
+                q_min=float(host.curved_host[2].min()),
+                q_max=float(host.curved_host[2].max()),
+                fallbacks=int(np.count_nonzero(host.curved_host[-1])),
+                sample_distances=[p[-1] for p in probe],
+            ),
+        )
+
+    def test_diffusive_scaling(self):
+        a, b = case(1), case(2)
+        self.assertEqual(a["re_d"], b["re_d"])
+        self.assertEqual(a["nu"], b["nu"])
+        self.assertEqual(a["final_t_star"], b["final_t_star"])
+        self.assertEqual(a["steps"] * 4, b["steps"])
+
+    def test_source_pin(self):
+        from tempfile import TemporaryDirectory
+        from historical_tree import historical_tree
+
+        with self.assertRaisesRegex(RuntimeError, "Source hash mismatch"):
+            verify(REPO)
+        with TemporaryDirectory() as directory:
+            verify(historical_tree(PIN, directory))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_jet_condition.py

@@ -0,0 +1,32 @@
+"""Jet boundary-condition hook: velocity implemented, pressure reserved (host only, no CUDA)."""
+import pytest
+
+from CelerisLab.body.jets import Jet, Parallel, Tube
+
+
+def region():
+    return Tube((16., 12.), 0., 3., .7)
+
+
+def test_default_is_velocity_and_survives_amplitude_change():
+    jet = Jet(region(), Parallel(0.), amplitude=.01)
+    assert jet.condition == "velocity"
+    assert jet.with_amplitude(-.02).condition == "velocity"
+    # positional calls keep their meaning; condition is the new last field
+    assert (Jet(region(), Parallel(0.), "parabolic", .01, "velocity")
+            == Jet(region(), Parallel(0.), "parabolic", .01))
+
+
+def test_pressure_is_rejected_before_amplitude_validation():
+    # An amplitude that the velocity check would reject must not decide the error.
+    for amplitude in (0., 5., float("nan")):
+        with pytest.raises(NotImplementedError, match="pressure jets are reserved"):
+            Jet(region(), Parallel(0.), amplitude=amplitude, condition="pressure")
+    with pytest.raises(NotImplementedError):
+        Jet(region(), None, profile="no-such-profile", condition="pressure")
+
+
+def test_unknown_condition_is_a_value_error():
+    for condition in ("Velocity", "flow_rate", "", None):
+        with pytest.raises(ValueError, match="condition"):
+            Jet(region(), Parallel(0.), amplitude=.01, condition=condition)

tests/unit/test_jet_cv_measurements.py

@@ -0,0 +1,182 @@
+"""Manufactured references for continuation instrumentation, no CUDA."""
+
+import sys
+from pathlib import Path
+import tempfile
+import unittest
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "validation"))
+from jet_cv_measurements import (
+    sample_steps,
+    factors,
+    ray_geometry,
+    reconstruct_aperture,
+    contour_terms,
+    LINEAR,
+    QUADRATIC,
+    OFFSETS,
+    MeasurementRecorder,
+)
+from run_jet_circle_cv import (
+    case,
+    CX,
+    CY,
+    W,
+    cv,
+    aperture_probe,
+    measured_aperture_flux,
+)
+from analyze_jet_cv_continuation import integrate, analyze
+
+
+class Measurements(unittest.TestCase):
+    def test_common_physical_schedule(self):
+        a = sample_steps(case(1, steps=3200))
+        b = sample_steps(case(2, steps=3200))
+        np.testing.assert_array_equal(a, b / 4)
+        self.assertEqual(len(a), 876)
+        self.assertEqual(a[-1], 3200)
+        self.assertTrue(all(t in a for t in range(0, 3201, 100)))
+        self.assertEqual(len(a[a <= 100]), 101)
+
+    def test_reference_factors(self):
+        f = factors(2)
+        self.assertEqual(f["mass"], 0.25)
+        self.assertEqual(f["impulse"], 0.5)
+        self.assertEqual(f["force"], 2)
+        self.assertEqual(f["mass_rate"], 1)
+
+    def test_extrapolation_polynomials(self):
+        self.assertAlmostEqual(LINEAR @ (2 + 3 * OFFSETS), 2)
+        self.assertAlmostEqual(QUADRATIC @ (2 + 3 * OFFSETS + 4 * OFFSETS**2), 2)
+
+    def test_independent_linear_field_volume_and_mass(self):
+        h = 0.5
+        y, x = np.mgrid[:64, :64]
+        x = (x + 0.5) * h
+        y = (y + 0.5) * h
+        rho = 1 + 0.001 * x
+        vel = np.array([0.01 + 0.0001 * x, -0.02 + 0.0002 * y])
+        center = np.array([16.0, 16.0])
+        r = 5
+        fluid = (x - center[0]) ** 2 + (y - center[1]) ** 2 > r * r
+        geo = ray_geometry(fluid, (0.0, 0.0), center, r)
+        ray, est = reconstruct_aperture(rho, vel, geo)
+        points = center + r * geo["normal"]
+        rr = 1 + 0.001 * points[..., 0]
+        uv = np.stack(
+            (0.01 + 0.0001 * points[..., 0], -0.02 + 0.0002 * points[..., 1]), axis=-1
+        )
+        un = np.sum(uv * geo["normal"], axis=-1)
+        exact = np.stack(
+            (np.sum(un * geo["ds"], axis=1), np.sum(rr * un * geo["ds"], axis=1)),
+            axis=-1,
+        )
+        np.testing.assert_allclose(est, np.broadcast_to(exact, est.shape), atol=1e-15)
+        self.assertGreater(np.max(abs(est[:, :, 0] - est[:, :, 1])), 1e-4)
+
+    def test_split_contour_stress(self):
+        y, x = np.mgrid[:48, :64]
+        y = (y + 0.5) * 0.5
+        rho = np.ones_like(y)
+        v = np.array([1e-4 * y * y, np.zeros_like(y)])
+        terms = contour_terms(rho, v, (0, 0), (5, 4, 25, 20), 0.0072)
+        np.testing.assert_allclose(terms[:2], 0, atol=1e-15)
+        np.testing.assert_allclose(terms[2], [-2 * 0.0072 * 1e-4 * 320, 0], atol=1e-15)
+
+    def test_recorder_snapshot_and_reconstructible_arrays(self):
+        h = 0.5
+        y, x = np.mgrid[:64, :64]
+        x = (x + 0.5) * h
+        y = (y + 0.5) * h
+        fluid = (x - 16) ** 2 + (y - 16) ** 2 > 25
+        fine_leaf = fluid.copy()
+        fine_leaf[:, :4] = False
+        root_leaf = np.zeros((32, 32), bool)
+        root_leaf[:, :2] = True
+
+        def equilibrium(ny, nx):
+            cu = CX[:, None, None] * 0.01
+            return np.broadcast_to(
+                W[:, None, None] * (1 + 3 * cu + 4.5 * cu * cu - 1.5 * 0.01**2),
+                (9, ny, nx),
+            ).copy()
+
+        ug = equilibrium(64, 64)
+        levels = [equilibrium(32, 32), ug.copy()]
+        c = dict(
+            scale=1,
+            center=[16, 16],
+            diameter=10,
+            u=0.01,
+            nu=0.0072,
+            contours=[[9, 9, 23, 23], [7, 7, 25, 25]],
+        )
+        data = {
+            name: [cv(ug, mask, (0, 0), r, c["nu"]) for r in c["contours"]]
+            for name, mask in [("uniform_adapter", fluid), ("amr_api", fine_leaf)]
+        }
+        with tempfile.TemporaryDirectory() as tmp:
+            rec = MeasurementRecorder(
+                c, tmp, fluid, [root_leaf, fine_leaf], (0, 0), CX, CY
+            )
+            rec.capture(0, ug, levels, data, {k: np.zeros(2) for k in data}, 0.0)
+            rec.records[-1]["raw_cumulative"] = np.zeros((2, 5, 4))
+            rec.flush()
+            a = np.load(Path(tmp) / "samples_s1.npz")
+            self.assertEqual(a["arc_ray_values"].shape, (1, 2, 3, 2, 32, 3))
+            np.testing.assert_allclose(
+                a["global_mass_reference"][0, 0], a["global_mass_reference"][0, 1]
+            )
+            snap = np.load(Path(tmp) / "fields_s1_tref0.npz")
+            np.testing.assert_allclose(
+                snap["uniform_velocity_reference"][0][fluid], 0.01, rtol=1e-7
+            )
+
+    def test_offline_mass_force_normalization(self):
+        import json
+
+        c = case(2, steps=3200)
+        s = 2
+        t = np.arange(0, 3201, 100)
+        n = len(t)
+        inv = np.zeros((n, 2, 2, 3))
+        inv[:, :, :, 0] = 100 * s * s
+        inv[:, :, :, 1] = -t[:, None, None] * 0.002 * s
+        raw = np.zeros((n, 2, 5, 4))
+        raw[:, :, 2, 0] = t[:, None] * 0.002 * s
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp)
+            (path / "samples_s2.json").write_text(
+                json.dumps(dict(case=c, sample_file="samples_s2.npz"))
+            )
+            np.savez(
+                path / "samples_s2.npz",
+                t_reference=t,
+                cv_inventory=inv,
+                cv_flux=np.zeros_like(inv),
+                raw_cumulative=raw,
+                arc_estimates=np.zeros((n, 2, 2, 2, 2)),
+                global_mass_reference=np.ones((n, 2)) * 100,
+                level_stats=np.broadcast_to([1, 1, 0, 0.03, 100], (n, 3, 5)),
+                velocity_error=np.zeros(n),
+            )
+            result = analyze(path)
+            self.assertEqual(len(result["windows"]), 32)
+            np.testing.assert_allclose(
+                result["windows"][0]["normalized_cv_residual"], 0, atol=1e-14
+            )
+            f0 = 0.5 * 0.03**2 * 24.084
+            np.testing.assert_allclose(
+                result["windows"][0]["raw_reaction_coefficient"], [[0.002 / f0, 0]] * 2
+            )
+
+    def test_nonuniform_trapezoidal_time_units(self):
+        t = np.array([0.0, 1.0, 2.0, 4.0, 8.0])
+        y = np.stack((3 * t + 2, 2 * t - 7), axis=-1)
+        np.testing.assert_allclose(integrate(t, y), [112, 8], atol=1e-15)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_jet_update_failure.py

@@ -0,0 +1,149 @@
+"""Jet amplitude update failure contract (host doubles only, no CUDA numerics).
+
+Both owners validate before any device write, commit host state only after the
+upload returns, and refuse every later call except close() after an uncertain
+device write.
+"""
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+pytest.importorskip("pycuda.driver")
+from CelerisLab import simulation as module
+from CelerisLab.body.jets import Jet, Radial, Sector
+from tests.unit.test_pinned_body_remap import ready
+from tests.unit.test_simulation_lifecycle import make_simulation
+
+BAD = (float("nan"), float("inf"), 1.)
+
+
+class Curved:
+    """Records uploads; ``fail`` raises once the write was attempted."""
+    def __init__(self):
+        self.writes, self.fail = [], False
+
+    def set_jet_amplitude(self, index, amplitude, stream):
+        self.writes.append((index, amplitude))
+        if self.fail:
+            raise RuntimeError("upload failed")
+
+
+def simulation(monkeypatch):
+    sim = make_simulation(monkeypatch)
+    jet = Jet(Sector((6., 5.), 0., .5, 4.), Radial((6., 5.)), "uniform", 1e-3)
+    sim._failed, sim._initialized = None, True
+    sim.bodies, sim.field = SimpleNamespace(jets=[jet]), SimpleNamespace(curved=Curved())
+    return sim, jet
+
+
+def test_simulation_invalid_input_writes_nothing_and_stays_usable(monkeypatch):
+    sim, jet = simulation(monkeypatch)
+    for amplitude in BAD:
+        with pytest.raises(ValueError):
+            sim.set_jet_amplitude(0, amplitude)
+    with pytest.raises(IndexError):
+        sim.set_jet_amplitude(1, 2e-3)
+    assert sim.field.curved.writes == [] and sim.bodies.jets[0] is jet and sim._failed is None
+    sim.set_jet_amplitude(0, 2e-3)  # retry after a rejected input
+    assert sim.field.curved.writes == [(0, 2e-3)] and sim.bodies.jets[0].amplitude == 2e-3
+    sim.close()
+
+
+def test_simulation_upload_failure_keeps_host_and_blocks_reuse(monkeypatch):
+    sim, jet = simulation(monkeypatch)
+    sim.field.curved.fail = True
+    with pytest.raises(RuntimeError, match="upload failed"):
+        sim.set_jet_amplitude(0, 2e-3)
+    assert sim.bodies.jets[0] is jet and sim._failed is not None
+    sim.field.curved.fail = False
+    for call in (lambda: sim.set_jet_amplitude(0, 2e-3), lambda: sim.run(1), sim.step,
+                 sim.sync_bodies, sim.initialize, sim.get_ddf, sim.get_macroscopic,
+                 lambda: sim.read_surface_exchange(0), lambda: sim.read_body(0),
+                 sim.read_bodies, sim.snapshot, sim.restore, sim.save_checkpoint,
+                 lambda: sim.load_checkpoint("x.h5"), lambda: sim.update_runtime_params(omega=1.)):
+        with pytest.raises(RuntimeError, match="Simulation failed"):
+            call()
+    assert sim.field.curved.writes == [(0, 2e-3)]
+    sim.close()  # cleanup still works
+    assert sim._closed and sim.ctx.is_closed
+
+
+def test_simulation_stream_creation_failure_fails_closed(monkeypatch):
+    sim, jet = simulation(monkeypatch)
+    created = []
+    def stream():
+        created.append(1)
+        raise RuntimeError("stream creation failed")
+    monkeypatch.setattr(module.cuda, "Stream", stream, raising=False)
+    sim._stream = None
+    with pytest.raises(RuntimeError, match="stream creation failed"):
+        sim.set_jet_amplitude(0, 2e-3)
+    assert sim.bodies.jets[0] is jet and sim._failed is not None
+    assert sim.field.curved.writes == [] and created == [1]
+    for call in (lambda: sim.stream, lambda: sim.set_jet_amplitude(0, 2e-3)):
+        with pytest.raises(RuntimeError, match="Simulation failed"):
+            call()
+    assert created == [1]  # the public stream property does not retry creation
+    sim.ctx.detach_failure = True
+    with pytest.raises(RuntimeError, match="detach failed"):
+        sim.close()
+    assert not sim._closed
+    sim.close()  # close stays retryable after the failure
+    assert sim._closed and sim.ctx.is_closed
+
+
+def test_simulation_before_initialize_commits_host_only(monkeypatch):
+    sim, _ = simulation(monkeypatch)
+    sim._initialized = False
+    sim.set_jet_amplitude(0, -2e-3)
+    assert sim.field.curved.writes == [] and sim.bodies.jets[0].amplitude == -2e-3
+    sim.close()
+
+
+def stepper_state(run):
+    boundary = run._level_boundaries[2]
+    return boundary.tables["surface_velocity"].copy(), boundary.jets, run._level_jets[2]
+
+
+def test_stepper_invalid_input_writes_nothing_and_stays_ready():
+    run, module, _, _, _ = ready()
+    try:
+        velocity, jets, level_jets = stepper_state(run)
+        module.cuda.memcpy_htod.reset_mock()
+        for args, kw, error in [((0, a), {"level": 2}, ValueError) for a in BAD] + [
+                ((1, .01), {"level": 2}, IndexError), ((0, .01), {"level": 3}, ValueError)]:
+            with pytest.raises(error):
+                run.set_jet_amplitude(*args, **kw)
+        module.cuda.memcpy_htod.assert_not_called()
+        np.testing.assert_array_equal(run._level_boundaries[2].tables["surface_velocity"], velocity)
+        assert (run._level_boundaries[2].jets, run._level_jets[2]) == (jets, level_jets)
+        assert run._status == "ready"
+        run.set_jet_amplitude(0, .017, level=2)
+        assert run._level_jets[2][0].amplitude == .017
+    finally:
+        run.close()
+
+
+@pytest.mark.parametrize("where", ["upload", "synchronize"])
+def test_stepper_device_failure_keeps_host_and_blocks_reuse(where):
+    run, module, _, _, _ = ready()
+    try:
+        velocity, jets, level_jets = stepper_state(run)
+        if where == "upload":
+            module.cuda.memcpy_htod.side_effect = RuntimeError("upload failed")
+        else:
+            run._stream.synchronize.side_effect = RuntimeError("upload failed")
+        with pytest.raises(RuntimeError, match="upload failed"):
+            run.set_jet_amplitude(0, .017, level=2)
+        np.testing.assert_array_equal(run._level_boundaries[2].tables["surface_velocity"], velocity)
+        assert (run._level_boundaries[2].jets, run._level_jets[2]) == (jets, level_jets)
+        assert run._status == "failed"
+        module.cuda.memcpy_htod.side_effect = None
+        run._stream.synchronize.side_effect = None
+        for call in (lambda: run.set_jet_amplitude(0, .017, level=2), run.step, run.download):
+            with pytest.raises(RuntimeError, match="failed"):
+                call()
+    finally:
+        run.close()
+    assert run._status == "closed"