fix: validate passive boundary ownership and expose Jet exchange

src/CelerisLab/body/jets.py

@@ -216,11 +216,8 @@ def surface_link_velocity(objects, cfg, flags, fluid_idx, dir, body_id, rx, ry,
     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")
+    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)
     for obj in enabled:

src/CelerisLab/body/manager.py

@@ -27,7 +27,7 @@ import pycuda.driver as cuda
 
 from .objects import SimObject
 from .registry import BodyRegistry
-from .preprocess.flag_overlay import merge_flag_masks
+from .preprocess.flag_overlay import merge_flag_masks, validate_cut_link_ownership
 from ..cuda.compiler_v2 import obs_layout
 from ..cuda.obs_layout import ObsLayout
 from ..lbm.descriptors import (
@@ -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/simulation.py

@@ -336,13 +336,19 @@ 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:
+        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, *,
@@ -451,18 +457,21 @@ class Simulation:
     @context_bound
     def initialize(self):
         """Initialize flow field and sync objects to GPU."""
-        # Recompile if objects were added after construction.
         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)