run: one fail-closed device transaction with translating circles

Split BodyManager action upload into host-only _prepare_action_upload
(validation + pinned staging) and _upload_prepared_action_async (H2D);
_upload_action_async stays the checked wrapper for direct callers.
Simulation.run prepares outside the failure boundary, then runs action
upload, obs/diagnostic zeroing, step group, readback and sync as one
transaction: with translating circles or attached moving tables any
exception fails every circle and the Simulation (also for run(0) and an
empty registry). The inner _run_moving catch is removed (its only caller
is run). Stationary runs keep their failure policy; pending/hold-consume
and run(0) success behaviour unchanged. No kernel change.

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

docs/lifecycle.md

@@ -6,8 +6,8 @@ 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. |
+| 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, except translating circles on the uniform grid: their swept-band flags and cut links are rewritten on the device every advancing step (`MovingCircleCells`/`MovingCircleLinks`, docs/moving_bodies.md); the host flag mirror is then stale for those cells. Uniform grid otherwise: 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` without translating circles, `add_body`/`remove_body` before a sync) do not touch the device and stay callable; with translating circles `get_flags` reads the device flags back and refuses after a failure. Translating-circle targets follow the same rule: `set_body` validates before mutation, the applied offset commits only after a successful synchronized step, and a failed moving step fails the instance (docs/moving_bodies.md). `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:

docs/moving_bodies.md

@@ -1,17 +1,61 @@
-# Moving circles on the uniform dense grid — S0 DRAFT contract
+# Moving circles on the uniform dense grid
 
-Status: **DRAFT, not frozen** for the force RHS, kernels and physical
-acceptance. Host-only S1 (state, validation, guards; no kernels) is on branch
-`claude/moving-bodies-s1`; positive-step runs with a moving body are rejected
-until S2. When S2 lifts that guard, `run(n > 1)` with a pending target must
-raise `ValueError` before mutation (4a), and `run(0)` must not upload a motion
-record or consume the pending target. Base: main
-`b2034f87e03656c5f67ab88562a70d6c338b9918`. Scope approved by Frank (via TRON,
-thread C0C78UFKGRM/1793335557.460509): uniform-grid prescribed translation and
-single-cylinder free transverse VIV. Out of scope: refinement/blocked path,
-pinball assembly, EsoPull, shifted storage, D3Q19, DynamisLab, manuscript.
+## Status and user guide (current)
 
-Items marked **OPEN** are undecided; items marked **CANDIDATE** are proposals.
+Development-stage feature, integrated from the reviewed slices S1–S3a
+(production code identical to `653fd997`). Physical evidence and its limits:
+`docs/validation/moving_bodies_stage1.md`. The force used as a structural RHS
+is a declared stage choice, not an established result.
+
+*What it does.* Translating circles (with optional spin) on the dense
+double-buffer D2Q9 path: per-step cut links from an FP64 geometry record
+(M2 `MovingCircleLinks`), reclassification and refill of covered/uncovered
+cells (M1 `MovingCircleCells`), moving-wall Bouzidi with wall velocity
+`u + omega x r`, and separate per-body diagnostics.
+
+*API.*
+- `Simulation.add_body("circle", center=(x, y), radius=r,
+  translation=Translation(offset_box, max_speed))` before `initialize()`;
+  `offset_box = (x_min, x_max, y_min, y_max)` in lattice cells around the
+  base centre (must contain 0), `0 < max_speed ≤ .5`.
+- `set_body(id, offset=(dx, dy), vx=..., vy=..., omega=...)` sets a pending
+  target (validated against the applied offset: box, Euclidean step ≤ .5
+  cell, speed, no sliding hold); `vx`/`vy` are the interval wall velocity.
+- `run(1)` advances a pending target and commits it only after the step
+  synchronizes with `no_donor == 0`; `run(n > 1)` with a pending target
+  raises; without a target `run(n)` holds the geometry (spin allowed).
+  Direct `LBMStepper.step` refuses while a target is pending.
+- `moving_diagnostics()` returns per body the columns of
+  `MovingTables.DIAG` (CME, Wen term, link mass, cover/uncover momentum and
+  mass, eq_only, no_donor, crossings) accumulated since obs were zeroed;
+  `obs`/`read_force` keep their contract (CME on the body).
+- `get_flags()` reads device flags back when moving circles exist.
+
+*Supported:* dense double buffer, D2Q9, FP32 unshifted, SRT/MRT, circles,
+spin. *Rejected before mutation:* EsoPull, ddf shifting, D3Q19, refinement /
+blocked steppers, Jets or surface actuation on a moving circle,
+`sync_bodies` and checkpoints while a moving circle exists, swept bands that
+touch the domain edge, other bodies, sensors or force regions.
+
+*Failure lifecycle.* Device-side failures (upload, step, sync, no_donor)
+mark the Simulation failed; later run/step/sync/checkpoint calls and direct
+stepper calls refuse until `close()`.
+
+*Known limitations.* No mass correction at curved walls (static or moving);
+cover/uncover and Wen terms are diagnostics, not a selected force law; the
+host loop costs a fixed per-step synchronization (≈ 1 ms/step measured on a
+7.2 M-cell grid, run(1) class); outer boundaries are the single dense
+channel package (see `configs/CONFIG.md`).
+
+## Design record (staged contract, kept as written)
+
+The sections below are the contract the slices were reviewed against
+(S0 → S3a). They are kept unchanged for provenance; where they say "draft",
+"proposed" or "until S2/S3", the status above supersedes them.
+
+Original scope (Frank via TRON, thread C0C78UFKGRM/1793335557.460509):
+uniform-grid prescribed translation and single-cylinder free transverse VIV;
+base main `b2034f87e03656c5f67ab88562a70d6c338b9918`.
 
 ## 1. Working standards
 
@@ -126,9 +170,9 @@ acts as a sliding wall. One moving step consumes one target.
 | `run(1)` without pending | hold: `c_old == c_new`, no cover/uncover, links at `applied`, translational `u_w = 0` |
 | `run(n > 1)` with pending | `ValueError` before mutation (single-step-only moving API) |
 | `run(n > 1)`, no pending | allowed: hold for n steps, translational `u_w = 0`, spin only |
-| `run(0)` | no motion upload, no commit; `pending` kept |
-| validation failure | `ValueError`, nothing mutated, retry allowed |
-| upload/launch/sync failure after enqueue | simulation unusable; `applied` and `pending` are not reported as device truth; no re-entry |
+| `run(0)` | no motion upload, no commit; `pending` kept; action upload and obs/diagnostic zeroing still run |
+| validation failure (incl. action validation and pinned staging in `run`) | `ValueError`/error before any device work, nothing mutated, retry allowed |
+| failure of any device work in `run` (action upload, obs/diagnostic zeroing, record upload, launch, readback, sync), also for `run(0)` | simulation unusable, every translating circle failed; `applied` and `pending` are not reported as device truth; no re-entry |
 
 Displacement norm: Euclidean per-step `|c_new - c_old|_2 ≤ 0.5` lattice
 cells (declared bound; CANDIDATE value).

docs/supported_settings.md

@@ -82,6 +82,13 @@ Tests: `tests/unit/test_jets.py`, `test_jets_review.py`, `test_shifted_jets.py`,
 - 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.
 
+## Moving circles (dense `Simulation`, uniform grid only)
+
+Translating circles with optional spin are supported on the dense double
+buffer D2Q9 FP32 path only (not on `FixedPatchStepper` or refined levels).
+API, supported/rejected modes and limits: `docs/moving_bodies.md`; stage-1
+evidence: `docs/validation/moving_bodies_stage1.md`.
+
 ## Not supported in this release
 
 3D, dynamic/automatic AMR (tagging, time-varying hierarchies beyond `remap_finest`),

docs/validation/moving_bodies_stage1.md

@@ -0,0 +1,46 @@
+# Moving circles — stage-1 evidence (development level)
+
+Owner criterion (Yanqi via TRON): prescribed motion and one free VIV case both
+"reasonably close" to a predeclared reference = development-stage success.
+This is practical closeness, not a formal validation claim. Every number
+below is from Astra's receipts as posted in Slack C0C78UFKGRM thread
+1793335557.460509; raw outputs stay on Horsea under `/tmp/celeris-results-*`
+and the Mac evidence directory (not in git).
+
+## Code
+
+- Production: `src/` identical to `653fd997` (slices S1 `983020b6`,
+  S2a `b920a303`, S3a `653fd997`). CPU suites and GPU hold/crossing gates
+  passed on those slices (G0a/G0b population-bitwise; X1 crossing ledger).
+- Research drivers: `research/duetsch_re100_kc5/` (`dd37883d`, capture
+  `a0aea3b9`) and `research/viv_re150/` (`fb507aa1`), run as committed.
+
+## Prescribed in-line oscillation (Dütsch et al. 1998, Re 100, KC 5)
+
+- Protocol: `docs/validation/duetsch_re100_kc5_protocol.md`.
+- Frozen settling gate (.002 F_ref waveform): **FAILED** and kept on record:
+  D40 domain stage (20/40/60 D, 11.25 T) and the 60 D duration diagnostic
+  (31.25 T, 0/28 pairs; last waveform drift .00613 F_ref).
+- Unscored late-cycle CME fits c_d ≈ 2.02–2.05, c_i ≈ 1.46–1.48 vs the
+  paper's computed (2.09, 1.45); fields clean and symmetric (owner view).
+  The owner accepts ~0.61 % cycle drift at D40 for this stage; the gate is
+  not re-scored.
+- Fig. 8 LDA profiles: qualitative only (no digitized ordinates).
+
+## Free transverse VIV (Kolahdouz §4.1.1 setup, Qin §4.5 target)
+
+- Predeclaration: `docs/validation/viv_re150_predeclare.md` (agreed at
+  `1abfe954` under its former name `leontini_viv_predeclare.md`); run at `fb507aa1`, single case, D = 40, 75 D × 60 D.
+- Result: status `scored`, 336,384 steps (t U/D = 336.4); A_max = .5464 D vs
+  .520 D (+5.1 %, inside the declared ±10 % band); mean half peak-to-peak
+  .5448 D; f/f_n = .955; block drifts .78/.29/.18 %, last-five spreads
+  .15/.11/.10 %; finite, no_donor = 0, no seed; 337.7 s, ~1.0 ms/step.
+
+## Limitations (binding)
+
+- One resolution (D40) per case; no grid or time convergence.
+- Structural RHS = CME + Wen is a theory-motivated stage choice; CME-only
+  and node-impulse variants were not run as RHS; no force law is validated.
+- Boundary mismatches: NEQ outlet with backflow clamp vs traction outlet;
+  finite box; the strict Dütsch settling failure is unexplained.
+- No mass correction at curved walls; ~1 ms/step host-coupled overhead.

docs/validation/viv_re150_predeclare.md

@@ -1,4 +1,6 @@
-# Single-cylinder free transverse VIV — PREDECLARATION (agreed at 1abfe954)
+# Single-cylinder free transverse VIV, Re 150 (Kolahdouz/Qin) — PREDECLARATION (agreed at 1abfe954)
+
+(File renamed from `leontini_viv_predeclare.md`; the Leontini Re 200 case is only the queued second case below.)
 
 Stage goal (Yanqi via TRON): prescribed Dütsch case + one VIV case both
 "reasonably close" to a predeclared reference = development-stage success, then

research/viv_re150/run.py

@@ -1,4 +1,4 @@
-"""One-shot predeclared VIV run (docs/validation/leontini_viv_predeclare.md).
+"""One-shot predeclared VIV run (docs/validation/viv_re150_predeclare.md).
 
 Re 150, U* = 5, m/(rho D^2) = 2, zeta = 0, D = 40 on a 75 D x 60 D native
 channel (uniform inlet, NEQ outlet, free-slip y walls), cylinder at

research/viv_re150/viv.py

@@ -1,6 +1,6 @@
 """Pure logic of the predeclared Re 150 free transverse VIV case (stdlib only).
 
-Contract: docs/validation/leontini_viv_predeclare.md. Oscillator update with a
+Contract: docs/validation/viv_re150_predeclare.md. Oscillator update with a
 constant force over one lattice step, response-cycle tracking with fixed y = 0
 crossings, eligibility, 10-cycle blocks, settling/scoring with deterministic
 restart, and the conditional seed.

src/CelerisLab/body/manager.py

@@ -629,10 +629,17 @@ class ObjectManager:
         cuda.memcpy_dtoh_async(self.obs_pinned, self.obs_gpu, stream)
 
     def _upload_action_async(self, stream: cuda.Stream) -> None:
-        """Async H2D of host action array to action_gpu.
+        """Checked async H2D of host action array to action_gpu."""
+        if self._prepare_action_upload():
+            self._upload_prepared_action_async(stream)
+
+    def _prepare_action_upload(self) -> bool:
+        """Validate the action array and stage it in pinned memory; no device work.
 
         Single gate for every action path (setters or direct ``action`` edits):
         surface-actuated and Jet-driven bodies must keep zero motion slots.
+        Returns False when there is nothing to upload. Restaging assumes no
+        copy from ``_action_pinned`` is in flight (``run`` ends with a sync).
         """
         slot = 3*(self.cfg.dim if self.cfg else 2)
         for obj in self.objects:
@@ -643,10 +650,14 @@ class ObjectManager:
             self.validate_jet_motion(obj.obj_id, {"vx": self.action[base], "vy": self.action[base+1],
                                                   "omega": self.action[base+slot-1]})
         if self.action_gpu is None or self.action.size == 0:
-            return
+            return False
         if self._action_pinned is None or self._action_pinned.size != self.action.size:
             self._action_pinned = cuda.pagelocked_empty(self.action.size, np.float32)
         self._action_pinned[:] = self.action
+        return True
+
+    def _upload_prepared_action_async(self, stream: cuda.Stream) -> None:
+        """Enqueue H2D of the staged ``_action_pinned`` (see ``_prepare_action_upload``)."""
         cuda.memcpy_htod_async(self.action_gpu, self._action_pinned, stream)
 
     @property

src/CelerisLab/body/motion.py

@@ -99,7 +99,12 @@ class MovingCircle:
         return self.centre(self.applied), self.centre(offset), velocity
 
     def advance(self, upload: Callable, step: Callable, synchronize: Callable) -> None:
-        """Upload the record, run one step and commit only after a successful sync.
+        """Single-circle transaction helper (unit tests): upload, step, sync, commit.
+
+        Not the production path: ``Simulation._run_moving`` batches all circles,
+        adds the ``no_donor`` gate and uses ``commit``/``fail`` directly.
+
+        Upload the record, run one step and commit only after a successful sync.
 
         Any exception after the upload is attempted leaves device geometry
         unknown: the circle is marked failed, never reports applied state again,

src/CelerisLab/configs/CONFIG.md

@@ -86,6 +86,20 @@ step/one_step_*.cu         → kernel 编排
 - 转速 `omega` 属于运行时状态，可在步进期间更新；该更新不改变 `N_OBJS` 或 `OBS_*` 内存布局，因此**不需要**因 `omega` 变化触发重新编译。
 - 力矩观测从 `obs` 的 torque segment 读取；force / torque / sensor 段统一由 `config_obs.h` 宏描述。
 
+### 外边界能力（Outer boundaries, dense `Simulation`）
+
+The dense path supports one channel package, not four independently
+selectable sides:
+- left x = 0: velocity inlet (`method.inlet.scheme`, `profile`, `physics.velocity`);
+- right x = nx−1: outlet (`method.outlet.mode`; `neq_extrap` holds rho = 1 with
+  a `max(u, 0)` backflow clamp when `backflow_clamp` is set);
+- bottom and top: one shared `y_wall_bc` (`bounce_back` halfway or
+  `free_slip`); corners are walls.
+`y_wall_bc = "on_site_velocity"` switches to x-periodic with on-site y planes
+and requires an object-free domain. There is no x/y-periodic or symmetry
+option for domains with bodies; adding outer BC types is a separate design
+question, not covered by these keys.
+
 ### 稳定性默认窗口（Stability defaults）
 
 - 默认 `method.omega_guard = {min: 0.01, max: 1.99}`，用于约束碰撞频率与 LES 有效粘度路径。

src/CelerisLab/lbm/stepper.py

@@ -21,7 +21,7 @@ class LBMStepper:
 
         self._esopull = (cfg.streaming == "esopull")
         # Set by the owner when a step would be wrong (translating circles
-        # excluded from the packed links before the moving kernels exist).
+        # without attached moving tables, a pending target, or a failed step).
         self.blocked: str | None = None
         self.moving = None  # MovingTables attached by the owner (translating circles)
 
@@ -39,8 +39,10 @@ class LBMStepper:
         self.apply_esopull_curved_fn = module.get_function("ApplyEsoPullCurvedKernel")
         self.sensor_fn = module.get_function("SensorKernel")
         self.force_region_fn = module.get_function("ForceRegionKernel")
-        self.moving_fn = None if self._esopull else module.get_function("MovingCircleLinks")
-        self.moving_cells_fn = None if self._esopull else module.get_function("MovingCircleCells")
+        # Moving-circle kernels exist only in D2Q9 double-buffer modules.
+        moving = not self._esopull and cfg.is_d2q9
+        self.moving_fn = module.get_function("MovingCircleLinks") if moving else None
+        self.moving_cells_fn = module.get_function("MovingCircleCells") if moving else None
 
         tpb = cfg.threads_per_block
         self.block = (tpb, 1, 1)

src/CelerisLab/simulation.py

@@ -28,7 +28,7 @@ from .cuda.context import CudaContext, context_bound
 from .cuda import compiler
 from .lbm.descriptors import FLUID
 
-# Translating circles step only through their moving tables (fixed centre in S2a).
+# Translating circles step only through their moving tables (attached at initialize).
 PENDING_BLOCKED = "a pending translation target is advanced only by Simulation.run(1)"
 MOVING_BLOCKED = ("translating circles need the moving kernels and their tables (attached "
                   "at initialize); "
@@ -122,8 +122,9 @@ class Simulation:
                 D2Q9/FP32/unshifted/DB only; set before initialization or stage
                 a new body. No runtime motion or amplitude setter.
             translation: ``body.motion.Translation`` declaring a translating
-                circle (before initialize only; docs/moving_bodies.md). Until
-                the moving kernels exist, positive-step runs are rejected.
+                circle (before initialize only; docs/moving_bodies.md).
+                Positive-step runs are rejected until ``initialize()`` has
+                attached its moving tables.
             **kwargs: passed to the geometry constructor.
 
         Returns:
@@ -215,6 +216,12 @@ class Simulation:
         self._failed = f"moving circle step failed: {exc!r}"
         self.stepper.blocked = self._failed  # direct stepper calls are refused as well
 
+    def _fail_moving_run(self, exc: BaseException) -> None:
+        # Device work was attempted with translating circles (or their tables) present.
+        for obj in self._moving_bodies():
+            obj.motion.fail(exc)
+        self._fail_moving(exc)  # also when tables are attached but no circle is registered
+
     def _attach_moving(self) -> None:
         # Direct stepper calls stay blocked until the moving tables exist.
         tables = getattr(self, "_moving_tables", None)
@@ -241,7 +248,8 @@ class Simulation:
         self._require_usable()
         tables = self.stepper.moving
         if tables is None:
-            return np.zeros((0, 6), np.float32)
+            from .body.motion import MovingTables
+            return np.zeros((0, MovingTables.DIAG_FLOATS), np.float32)
         self.stream.synchronize()
         return tables.download_diagnostics()
 
@@ -360,8 +368,11 @@ class Simulation:
         Args:
             id: body_id from add_body().
             omega: rotation speed (lattice units).  ``None`` = no change.
-            vx: translation velocity x (future).  ``None`` = no change.
-            vy: translation velocity y (future).  ``None`` = no change.
+            vx: translation velocity x. For a translating circle: the
+                interval wall velocity of the target, only together with
+                ``offset``; otherwise stored in the body state (not applied
+                to stationary walls).  ``None`` = no change.
+            vy: translation velocity y; same rules as ``vx``.
             offset: target centre offset of a translating circle; with vx/vy
                 (default 0) it replaces the pending target after validation
                 against the applied offset (docs/moving_bodies.md, 4a). Only
@@ -729,9 +740,20 @@ class Simulation:
         if stream is None:
             stream = self.stream
 
-        # Async upload action
-        if upload_act and self.bodies.count > 0:
-            self.bodies._upload_action_async(stream)
+        # Host-only action validation and staging: a rejection here stays retryable.
+        staged = upload_act and self.bodies.count > 0 and self.bodies._prepare_action_upload()
+        watched = bool(moving) or self.stepper.moving is not None
+        try:
+            self._run_steps(steps, stream, staged, sync_obs, zero_obs, checkpoint_interval)
+        except BaseException as exc:
+            if watched:  # device work was attempted: motion state is unknown
+                self._fail_moving_run(exc)
+            raise
+
+    def _run_steps(self, steps, stream, staged, sync_obs, zero_obs, checkpoint_interval):
+        """Device part of ``run``: action upload, obs zeroing, step group, sync."""
+        if staged:
+            self.bodies._upload_prepared_action_async(stream)
 
         # Zero obs segments before step group
         if zero_obs:
@@ -778,30 +800,28 @@ class Simulation:
     def _run_moving(self, steps, stream, sync_obs):
         """Steps with translating circles: hold, or one advancing step that commits
         each pending target only after synchronization and a zero ``no_donor`` count
-        (docs/moving_bodies.md 4a, 5). Any failure leaves the Simulation unusable."""
+        (docs/moving_bodies.md 4a, 5). ``run`` fails the Simulation on any exception."""
         tables = self.stepper.moving
         circles = [(obj.motion, obj.obj_id) for obj in self._moving_bodies()]
-        try:
-            advancing = tables.upload_records(circles, stream)
-            self.stepper._step(steps, action_gpu=self.bodies.action_gpu,
-                               obs_gpu=self.bodies.obs_gpu, stream=stream, advance=advancing)
-            self.bodies.increment_obs_steps(steps)
-            if sync_obs:
-                self.bodies.download_obs_full_async(stream)
-            stream.synchronize()
+        pending = any(motion.pending is not None for motion, _ in circles)
+        advancing = tables.upload_records(circles, stream)
+        self.stepper._step(steps, action_gpu=self.bodies.action_gpu,
+                           obs_gpu=self.bodies.obs_gpu, stream=stream, advance=advancing)
+        self.bodies.increment_obs_steps(steps)
+        if sync_obs:
+            self.bodies.download_obs_full_async(stream)
+        stream.synchronize()
+        if advancing:
+            no_donor = tables.download_diagnostics()[:, tables.DIAG.index("no_donor")]
+            if np.any(no_donor > 0):
+                raise RuntimeError("translating circle refill found no donor cell")
+        if pending:  # a target equal to the applied offset is consumed as a hold step
+            for motion, _ in circles:
+                motion.commit()
             if advancing:
-                no_donor = tables.download_diagnostics()[:, tables.DIAG.index("no_donor")]
-                if np.any(no_donor > 0):
-                    raise RuntimeError("translating circle refill found no donor cell")
-                for motion, _ in circles:
-                    motion.commit()
                 tables.upload_records(circles, stream)  # first hold: old = new = applied, u = 0
                 stream.synchronize()
-                self._attach_moving()
-        except BaseException as exc:
-            for motion, _ in circles:  # device geometry/state unknown after any failure
-                motion.fail(exc)
-            raise
+            self._attach_moving()
 
     def step(self, n: int = 1):
         """Advance *n* steps (convenience for interactive use)."""

tests/unit/test_duetsch_protocol.py

@@ -11,6 +11,20 @@ _spec = importlib.util.spec_from_file_location(
 p = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(p)
 
+def _load(rel, name):
+    """Load a research driver module under a unique name (no bare ``import run``)."""
+    import sys
+    path = Path(__file__).resolve().parents[2] / rel
+    sys.path.insert(0, str(path.parent))  # for the driver's own sibling imports
+    try:
+        spec = importlib.util.spec_from_file_location(name, path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+    finally:
+        sys.path.remove(str(path.parent))
+    return mod
+
+
 T = 2520
 
 
@@ -93,12 +107,7 @@ def test_exact_point_inside_body_is_missing_even_with_fluid_corners():
 
 def test_generated_config_passes_the_real_loader(tmp_path):
     import json
-    import sys
-    sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "research/duetsch_re100_kc5"))
-    try:
-        import run
-    finally:
-        sys.path.pop(0)
+    run = _load("research/duetsch_re100_kc5/run.py", "duetsch_run")
     from CelerisLab.config import load_lbm_config
     cfg_dict, u_max, n = run.config(20, 10.0, 2520)
     path = tmp_path / "config_lbm.json"
@@ -111,13 +120,7 @@ def test_generated_config_passes_the_real_loader(tmp_path):
 
 
 def _analyze():
-    import sys
-    sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "research/duetsch_re100_kc5"))
-    try:
-        import analyze
-    finally:
-        sys.path.pop(0)
-    return analyze
+    return _load("research/duetsch_re100_kc5/analyze.py", "duetsch_analyze")
 
 
 def test_hf_energy_is_parseval_weighted():

tests/unit/test_moving_bodies.py

@@ -113,7 +113,8 @@ def moving_simulation(monkeypatch, *, moving=True):
     sim._failed, sim._initialized = None, True
     sim.bodies = SimpleNamespace(objects=[obj], count=1, jets=[], action_gpu=None, obs_gpu=None,
                                  has_pending_edit=lambda: False,
-                                 _upload_action_async=lambda s: writes.append("action"),
+                                 _prepare_action_upload=lambda: True,
+                                 _upload_prepared_action_async=lambda s: writes.append("action"),
                                  zero_obs_async=lambda s: writes.append("obs"),
                                  increment_obs_steps=lambda n: writes.append("count"),
                                  download_obs_full_async=lambda s: writes.append("download"))
@@ -297,6 +298,44 @@ def test_run_one_advances_and_commits_after_sync(monkeypatch):
     assert ("step", 3, False) in writes and motion.applied == (0., .25)
 
 
+def test_zero_motion_target_is_consumed_by_run_one(monkeypatch):
+    sim, writes, motion = advancing_simulation(monkeypatch)
+    motion.set_target((0., 0.), (0., 0.))          # equal to applied: a hold target
+    sim._attach_moving()
+    assert sim.stepper.blocked == module.PENDING_BLOCKED
+    sim.run(1, stream=STREAM)
+    assert motion.pending is None and motion.applied == (0., 0.)
+    assert sim.stepper.blocked is None and ("step", 1, False) in writes
+    writes.clear()
+    sim.run(3, stream=STREAM)                      # no stale latch
+    assert ("step", 3, False) in writes
+
+
+@pytest.mark.parametrize("streaming,d2q9,bound", [("double_buffer", True, True),
+                                                  ("double_buffer", False, False),
+                                                  ("esopull", True, False)])
+def test_moving_kernels_bound_only_for_d2q9_double_buffer(monkeypatch, streaming, d2q9, bound):
+    from CelerisLab.lbm import stepper as stepper_module
+    monkeypatch.setattr(stepper_module.cuda, "mem_alloc", lambda n: object())
+    moving = {"MovingCircleLinks", "MovingCircleCells"}
+
+    def get_function(name):
+        if name in moving and not (d2q9 and streaming == "double_buffer"):
+            raise KeyError(name)                 # absent from D3Q19 / EsoPull modules
+        return lambda *a, **k: None
+    cfg = SimpleNamespace(streaming=streaming, threads_per_block=128, is_d2q9=d2q9,
+                          nx=16, ny=8, nz=4, nq=9 if d2q9 else 19)
+    stepper = stepper_module.LBMStepper(SimpleNamespace(), SimpleNamespace(get_function=get_function), cfg)
+    assert (stepper.moving_fn is not None) == bound and (stepper.moving_cells_fn is not None) == bound
+
+
+def test_moving_diagnostics_empty_shape_matches_layout(monkeypatch):
+    from CelerisLab.body.motion import MovingTables
+    sim = make_simulation(monkeypatch)
+    sim._failed, sim.stepper = None, SimpleNamespace(moving=None)
+    assert sim.moving_diagnostics().shape == (0, MovingTables.DIAG_FLOATS)
+
+
 @pytest.mark.parametrize("failure", ("upload", "first_sync", "no_donor", "hold_upload",
                                      "hold_sync"))
 def test_failed_advance_fails_simulation(monkeypatch, failure):
@@ -323,6 +362,78 @@ def test_failed_advance_fails_simulation(monkeypatch, failure):
         sim.run(1, stream=STREAM)
 
 
+def raising(log, name, site):
+    def call(*a, **k):
+        log.append(name)
+        if name == site:
+            raise RuntimeError(f"{name} failed")
+    return call
+
+
+def two_circle_simulation(monkeypatch, site):
+    # No owner hooks: run itself must fail the Simulation and every circle.
+    sim, writes, first = advancing_simulation(monkeypatch)
+    second = SimpleNamespace(motion=circle(), obj_id=1, center=(80., 40.), radius=10.)
+    sim.bodies.objects.append(second)
+    sim.bodies._upload_prepared_action_async = raising(writes, "action", site)
+    sim.bodies.zero_obs_async = raising(writes, "obs", site)
+    sim.bodies.download_obs_full_async = raising(writes, "download", site)
+    sim.stepper.moving.zero_diagnostics = raising(writes, "zero_diag", site)
+    step = raising(writes, "step", site)
+    sim.stepper._step = lambda n, advance=False, **k: step()
+    return sim, (first, second.motion), SimpleNamespace(synchronize=raising(writes, "sync", site))
+
+
+@pytest.mark.parametrize("steps,site", [(n, s) for n in (0, 1, 3)
+                                        for s in ("action", "obs", "zero_diag", "step", "download", "sync")
+                                        if not (n == 0 and s == "step")])  # run(0) launches nothing
+def test_device_failure_in_run_fails_every_circle(monkeypatch, steps, site):
+    sim, motions, stream = two_circle_simulation(monkeypatch, site)
+    if steps < 2:
+        motions[0].set_target((0., .25), (0., .05))
+    with pytest.raises(RuntimeError, match=f"{site} failed"):
+        sim.run(steps, stream=stream)
+    assert all(m.failed for m in motions) and sim._failed is not None
+    assert sim.stepper.blocked == sim._failed
+    assert motions[0].applied == (0., 0.)  # nothing committed before the first sync
+    with pytest.raises(RuntimeError, match="Simulation failed"):
+        sim.run(1, stream=STREAM)
+
+
+def test_action_rejection_stays_retryable_before_device_work(monkeypatch):
+    sim, writes, motion = advancing_simulation(monkeypatch)
+    motion.set_target((0., .25), (0., .05))
+
+    def reject():
+        raise ValueError("bad action")
+    sim.bodies._prepare_action_upload = reject
+    for steps in (0, 1):
+        with pytest.raises(ValueError, match="bad action"):
+            sim.run(steps, stream=STREAM)
+    assert writes == [] and sim._failed is None and sim.stepper.blocked is None
+    assert not motion.failed and motion.pending is not None
+    sim.bodies._prepare_action_upload = lambda: True
+    sim.run(1, stream=STREAM)
+    assert motion.applied == (0., .25) and motion.pending is None
+
+
+def test_attached_tables_without_circles_fail_closed(monkeypatch):
+    sim, writes, _ = advancing_simulation(monkeypatch)
+    sim.bodies.objects = []
+    sim.stepper.moving.zero_diagnostics = raising(writes, "zero_diag", "zero_diag")
+    with pytest.raises(RuntimeError, match="zero_diag failed"):
+        sim.run(0, stream=STREAM)
+    assert sim._failed is not None and sim.stepper.blocked == sim._failed
+
+
+def test_stationary_run_failure_policy_unchanged(monkeypatch):
+    sim, writes = moving_simulation(monkeypatch, moving=False)
+    sim.bodies.zero_obs_async = raising(writes, "obs", "obs")
+    with pytest.raises(RuntimeError, match="obs failed"):
+        sim.run(2, stream=STREAM)
+    assert sim._failed is None and sim.stepper.blocked is None
+
+
 def test_failed_hold_step_blocks_the_direct_stepper(monkeypatch):
     # No target is pending, so only the failure latch can refuse direct steps.
     from CelerisLab.lbm.stepper import LBMStepper

tests/unit/test_viv_logic.py

@@ -8,6 +8,20 @@ _spec = importlib.util.spec_from_file_location(
 viv = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(viv)
 
+def _load(rel, name):
+    """Load a research driver module under a unique name (no bare ``import run``)."""
+    import sys
+    path = Path(__file__).resolve().parents[2] / rel
+    sys.path.insert(0, str(path.parent))  # for the driver's own sibling imports
+    try:
+        spec = importlib.util.spec_from_file_location(name, path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+    finally:
+        sys.path.remove(str(path.parent))
+    return mod
+
+
 D, U = 40, 0.04
 
 
@@ -72,12 +86,7 @@ def test_seed_reset_discards_incomplete_cycle_and_proof():
 
 def test_viv_config_passes_the_real_loader(tmp_path):
     import json
-    import sys
-    sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "research/viv_re150"))
-    try:
-        import run
-    finally:
-        sys.path.pop(0)
+    run = _load("research/viv_re150/run.py", "viv_run")
     from CelerisLab.config import load_lbm_config
     cfg_dict, nx, ny = run.config()
     path = tmp_path / "config_lbm.json"