docs: sync src_coherence with the landed slices

Stage history and verification, historical label on the migration map,
host-preparation/device order, pair accessors, per-level state split into
fixed plan structure / mutable boundary data / runtime _Level, the two
block_collide families, and the deferred items with their evidence needs.
Doc-only.

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

docs/development/src_coherence.md

@@ -1,8 +1,11 @@
 # 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
+No numerical change is intended. Stages after 5f69eba: 65339ab (one boundary/Jet record,
-pending a GPU run).
+host preparation helpers, pair accessors), c5a3cdb (`block_collide` families), 442979b
+(exchange metadata on the boundary record). Each was checked by parent/candidate
+config.h/PTX comparison and host/GPU equality runs; c5a3cdb changed the PTX of the two
+channel-root SRT modules only (omega load/clamp moved, outputs exact).
 
 ## Conventions (defined once, in `lbm.hierarchy.Hierarchy`)
 
@@ -28,6 +31,9 @@ pending a GPU run).
 
 ## FixedPatchStepper migration map
 
+Historical: left column = names at or after 914906e that no longer exist; right column =
+the current name.
+
 | removed / changed | replacement |
 |---|---|
 | `patch`, `child_patch` | `hierarchy.pairs[0]`, `hierarchy.pairs[1]` |
@@ -58,19 +64,35 @@ the replaced level relative to its parent).
 
 ## Responsibilities
 
-- Construction: `_check_levels` (inputs), `_kernel_configs` (per-level kernel configs),
+- Construction: `_check_levels` (inputs); host preparation, numpy only, before any device
-  `Hierarchy.edge_frame` (geometry frames), `_build_level` / `_build_pair` / `_upload_boundary`
+  work: `_level_layouts`, `_kernel_configs` (per-level kernel configs), `_host_boundaries`,
-  (device). Observation reads share `_observed_boundary` + `_summarize`.
+  `_prepare_blocked_boundary`, `_fluid_leaves`; `Hierarchy.edge_frame` (geometry frames);
-- Lifecycles: `_layouts`, `_level_cfgs`, `_boundaries`, `_leaf`, `_state` are the immutable
+  then `_planned_bytes()` (memory preflight) and `_build_level` / `_build_pair` /
-  construction plan (only a record's Jets/velocity column change, in `set_jet_amplitude`). They
+  `_upload_boundary` (device). A construction failure closes the partial instance.
-  are built and read by `_planned_bytes()` before any device allocation and stay readable after
+  Observation reads share `_observed_boundary` + `_summarize`.
-  `close()` (public views). `_Level` stays device-only: created after the memory preflight,
+- Pair accessors: `rectangles` (a scalar FixedPatch2D gives `(bounds,)`) and
-  cleared on `close()`; its `.layout`/`.boundary` are references into the plan for `_hop`.
+  `fine_level_offset` (`(0, 0)` for a set) on both pair types; the types and their
-  Folding the plan into `_Level` would mix both lifecycles in one record.
+  storage frames stay distinct.
+- Per-level state, by lifecycle:
+  - Fixed plan structure (built once in `__init__`, read by `_planned_bytes()` before any
+    allocation, readable after `close()` through the public views): `_layouts`,
+    `_level_cfgs`, `_leaf`, `_state`, and in each `_boundaries[l]` record the host geometry
+    `.host`, link tables, `.jet_cache`, `.spacing`, `.centers`.
+  - Mutable boundary data in the same record: `.jets` and `.tables["surface_velocity"]`,
+    changed only by `set_jet_amplitude` (host prepare -> device write -> commit; an uncertain
+    write fails the instance); device handles (`.flags`, `.device`, `.kernel`, ledgers) are
+    set by `_upload_boundary` and cleared by `close()`.
+  - Runtime: `_levels` (`_Level`) holds compiled modules, kernels, the two population
+    buffers (swapped per step) and transfer/kind handles. It is created only after the
+    memory preflight and cleared on `close()`; `.layout`/`.boundary` reference the plan for
+    `_hop`. Folding the plan into `_Level` would mix both lifecycles in one record.
 - 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
+  point of `BlockStep` and `BlockChannelStep`. It computes rho/u once and reads no runtime
-  arithmetic variants (level: unclamped, no-force, shifted direct-momentum feq; channel: uniform
+  force (`d_params.fx/fy`). Two compile-time families: uniform-equivalent (MRT on any level,
-  OneStep arithmetic with omega clamp), selected by `BLOCK_ROOT_BC`.
+  SRT on the channel root `BLOCK_ROOT_BC == 2`): clamped omega, `collide_mrt_no_force` or
+  `collide_srt` with its zero Guo term; and level SRT (`BLOCK_ROOT_BC` 0/1): unclamped omega,
+  `collide_srt_no_force`, with the shifted direct-momentum feq under `USE_DDF_SHIFTING`.
+  The uniform path keeps `collide_dispatch` (runtime force, LES, TRT).
 - `explosion="projected_linear"` stays an optional capability; `"constant"` stays default.
 
 ## Not done / open
@@ -80,6 +102,12 @@ the replaced level relative to its parent).
   `FixedPatchStepper._kernel_configs` (reset only on level 1 of a slot_reservoir root;
   generates each level's config.h). Folding them needs a config.h/PTX diff gate.
 - No single-`Simulation` facade over FixedPatchStepper: the two own different state models
-  (uniform node frame, body sync, forcing, checkpoint vs. immutable blocked hierarchy, edge
+  (uniform node frame, body sync, forcing, checkpoint vs. fixed blocked hierarchy, edge
   frame, remap-as-new-instance). A facade would only forward calls; no concrete need found.
+- Deferred, each needing its own evidence first: sharing the channel-root cell/donor selector
+  with OneStep (the closure functions are already shared; a shared selector changes uniform
+  signatures and needs a uniform PTX gate); merging FixedPatch2D into FixedPatchSet2D
+  (different origin, ghost band, layout size and addressing; needs a geometry/parity table and
+  would need tiles that are not grid-aligned); one `clamp_omega` helper for uniform and
+  blocked paths (it lives in the hash-pinned LES header `turbulence_smag.cuh`).
 - Tests, examples and validation callers are migrated separately (pinned runners stay frozen).