docs: correct refinement topology and diagnostics scope

README.md

@@ -123,7 +123,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 can use level lists of arbitrary depth; the
+  legacy two/three-level forms are shown below.
 - `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)`),
@@ -135,16 +137,20 @@ Scope and limits:
   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
+  `bounds`, with both `fine_block` and `base_block`. 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. `fine_objects`/`jets` 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, use the level lists or legacy child forms below.
 
   ```python
   cfg = LBMConfig(nx=32, ny=16, viscosity=.1)
@@ -158,7 +164,7 @@ Scope and limits:
       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
+- Legacy three-level scalar 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
@@ -192,14 +198,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: `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.
+  These lists are mutually exclusive with the legacy patch keywords. 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