marpaia · Sep 25, 2026 · Sep 24, 2026 · Sep 25, 2026
diff --git a/docs/architecture/0014-native-controllers.md b/docs/architecture/0014-native-controllers.md
@@ -28,8 +28,12 @@ A controller-backed model resumes through `resume(context, checkpoint)`. The ope
 1. compute and validate host regulation;
 2. apply cell attributes, species, and fixed-state updates;
 3. apply division requests and division callbacks;
-4. execute `Simulation.step(dt)` for growth and typed rate plans; and
-5. execute exactly `MechanicsConfig.passes` contact/relaxation passes when mechanics is configured.
+4. apply requested cell removals;
+5. execute `Simulation.step(dt)` for growth and typed rate plans;
+6. apply flow drift when enabled in the mechanics configuration; and
+7. execute exactly `MechanicsConfig.passes` contact/relaxation passes when mechanics is configured and cells remain.
+
+`UniformLengthDivision.jitter_z` controls only the random perturbation added to daughter orientation: `None` disables jitter, `False` adds XY-only jitter, and `True` adds XYZ jitter. Native normalization can change an inherited nonzero Z component even when the added Z perturbation is zero. Division places daughters along the parent's three-dimensional axis; subsequent contact relaxation and flow drift remain three-dimensional. See the [planarity diagnostics and tutorial audit](../tutorials/planarity.md) for reproducible examples and the limits of finite-height confinement.
 
 The standard payload records a stable model ID and version, completed-step counter, model JSON state, random stream, and every mechanics parameter. `NativeController.from_checkpoint` validates and restores that payload while the checkpoint's native state retains rate plans, signal grids, geometry, and lineage. Exact mechanics passes are a new explicit native-controller contract. The legacy adapter separately preserves the intent of `max_substeps` as a bounded new-contact frontier: it performs at most `max_substeps - 1` solves and stops when rediscovery produces no contact identity not seen earlier in the biological step. This distinction is checkpointed and supported by recorded colony trajectories; native models never inherit the legacy heuristic silently.
 

diff --git a/docs/development/planar-mechanics-followup.md b/docs/development/planar-mechanics-followup.md
@@ -0,0 +1,40 @@
+# Proposed follow-up: explicit planar cell mechanics
+
+Status: specification only; not implemented. The [planarity investigation](../tutorials/planarity.md) found expected three-dimensional responses, including Z-directed degenerate contacts and inherited tilt. `jitter_z=False` must retain its current orientation-perturbation meaning. A strict planar tutorial needs a separately selected native mechanical mode.
+
+## Public contract and state ownership
+
+Add a native mechanical dimensionality setting with `spatial_3d` as the backward-compatible default and `planar_xy` with an explicit finite `plane_z`. This is simulation state shared by Python, CPU, Metal, and CUDA, not a viewer option or controller-only callback. Preserve the existing three-coordinate geometry API and existing capsule length, radius, and volume conventions.
+
+For `planar_xy`, all mobile cell centers satisfy `position.z == plane_z` and all directions satisfy `direction.z == 0`, within a documented float32 representation tolerance after every public geometry mutation and completed native stage. The plane's stored value is its canonical float32 representation. Reject non-finite or unrepresentable heights. Initialization and explicit geometry edits reject appreciably off-plane centers, directions with nonzero Z beyond the declared input tolerance, and directions with no finite nonzero XY component; canonicalize accepted roundoff to exact stored plane Z and normalized XY direction. Do not silently flatten tilted checkpoint geometry or switch modes on an occupied simulation.
+
+## Translation, rotation, growth, and division
+
+Solve only the two in-plane translation components and rotation about Z. Assemble/project mechanical Jacobians, forces, increments, and residuals in those degrees of freedom; projecting a completed 3D solve afterwards is insufficient because its contact response was computed in a different space. Fixed cells obey the same planar geometry validation and remain stationary.
+
+Growth changes length without introducing Z. Division uses the planar parent axis to place daughters, keeps both centers on the configured plane, and preserves the existing volume and lineage contracts. A model requesting an XYZ geometry edit or incompatible division jitter must receive a clear validation error, so a mistakenly configured tutorial does not appear to work through silent filtering. XY-only or absent division jitter works unchanged.
+
+## Contacts and external boundaries
+
+Compute planar closest-segment contacts and normals in XY. Crossing rods and coincident parallel rods must receive deterministic in-plane separating directions instead of the 3D cross-product/fallback directions. Specify canonical axis signs, cell-ID ordering, tie breaks, and normal sign conventions centrally; test cell order reversal and both equivalent representations of a rod axis. The same overlapping input and solver parameters must produce matching contact identities and tolerance-equivalent corrections on all available backends.
+
+The first implementation should support Z-extruded lateral planes, axis-aligned boxes, and Z-aligned cylinders whose planar cross-sections are well-defined and whose finite-height caps fully clear a capsule on the chosen plane. Validate this compatibility when adding constraints and when adding or resizing cells. Reject tilted planes, spheres, or cap intersections until their planar mechanical semantics are explicitly implemented. A floor/ceiling touching a planar capsule must not create an unsatisfiable out-of-plane force. This mode models discs/capsules constrained to a plane within a compatible device; it does not replace finite-height 3D confinement.
+
+## Flow and chemical fields
+
+Project sampled drift velocity onto XY before applying mobile-cell translation. Deliberately ignore the normal component as a kinematic constraint and document that this is not a resolved reaction-force or momentum-conservation model. Preserve in-plane interpolation, obstacle handling, boundary behavior, and fixed-cell exclusions. Keep signal grids and chemistry independently three-dimensional: a 3D concentration field may be sampled at `plane_z`; a shallow grid does not automatically opt the cells into planar mode.
+
+## Checkpoint, resume, and diagnostics
+
+Version the native checkpoint schema to persist dimensionality and canonical plane height. Old checkpoints migrate explicitly to `spatial_3d`; missing or invalid fields in the new schema fail validation. Validate planar geometry and compatible constraints before exposing a restored simulation, without silently repairing incompatible data. Preserve mode and plane across CPU/Metal/CUDA restoration, controller restart, and clone/export paths. Reject a resume request whose requested mechanics mode conflicts with saved state.
+
+Expose the mode and plane in scene/analysis metadata so diagnostics can distinguish an intended invariant from a visual appearance. Coordinate that schema change with the existing metadata owner; do not infer dimensionality from channel labels, camera view, signal-grid depth, or jitter configuration.
+
+## Acceptance and validation
+
+- Shared native fixtures cover separated cells, overlapping parallel rods, crossing rods, order-reversed pairs, arbitrary in-plane orientations, division, long growth runs, and mixed mobile/fixed cells. Check both center Z and direction Z after each relevant stage, including zero-duration controller steps.
+- Test all public construction and geometry-edit paths: accepted roundoff canonicalizes consistently; inherited tilt and invalid heights fail clearly; default 3D behavior and its existing conformance fixtures remain unchanged.
+- Verify planar contacts separate overlap in XY with finite residuals and deterministic identities, including degenerate ties. Check force/rotation consistency and convergence rather than only final projection onto the plane.
+- Exercise each supported boundary, each rejected incompatible boundary, cell growth approaching a cap, and a prescribed flow with nonzero Z velocity. In-plane drift is preserved and out-of-plane drift is suppressed only in planar mode.
+- Round-trip checkpoints with each mode, migrate old data, reject malformed/inconsistent planar state, and compare resumed trajectories against uninterrupted execution. Run the same fixture contract on CPU, Metal, and CUDA; report unavailable accelerator hardware instead of substituting CPU.
+- Add an opt-in tutorial using the new mode and a paired finite-height 3D example. Documentation explains the distinct mechanical assumptions and retains the current definition of `jitter_z`.
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
@@ -28,6 +28,8 @@ These lessons develop the biological rules used within devices and in standalone
 
 The [analysis tutorial](analysis.md) covers checkpoints, contact graphs, and quantitative output. Continue with [analysis recipes](../analysis/recipes.md) for reproducible Parquet/Zarr datasets and Polars queries.
 
+The [dimensionality audit and planarity diagnostic](planarity.md) explain XY-only division jitter, finite-height confinement, and reproducible causes of out-of-plane cell motion.
+
 ## Working with the examples
 
 Teaching models are under [`examples/tutorials`](../../examples/tutorials). Scenario parameters are JSON values passed with `--parameter`; every command in the tutorials can be run from the repository root.

diff --git a/docs/tutorials/biophysics-and-growth.md b/docs/tutorials/biophysics-and-growth.md
@@ -2,6 +2,8 @@
 
 This tutorial introduces cell geometry, growth, division, lineage, cell types, mechanical constraints, and competition. Its five runnable scenarios are defined in `examples/tutorials/biophysics.py`.
 
+The `basics`, `two_types`, and `competition` scenarios add XY-only division jitter but retain unrestricted 3D mechanics. `short_cells` adds XYZ jitter. `box` also adds XYZ jitter and has a floor and four lateral walls, with no ceiling. None guarantees a planar colony; see [division jitter and out-of-plane motion](planarity.md) for the full contract and reproducible diagnostics.
+
 ## 1. A founder that grows and divides
 
 Run the basic model:

diff --git a/docs/tutorials/discrete-state-and-contacts.md b/docs/tutorials/discrete-state-and-contacts.md
@@ -2,6 +2,8 @@
 
 This tutorial uses plasmid segregation and conjugation to show how discrete biological state, stochastic events, and contact-dependent behavior fit into a MicroSimulator model.
 
+Both models start with centers at Z=0 and axes in XY, and division adds no orientation jitter. Neither has mechanical Z confinement: daughters inherit the parent axis and contact relaxation remains three-dimensional. See [division jitter and out-of-plane motion](planarity.md).
+
 New founders preserve their requested length unless it exceeds the single sampled division target. This also handles the rare short Gaussian target in the conjugation model without rejection sampling. Checkpoint restoration keeps stored lengths and targets. See [founder initialization](biophysics-and-growth.md#length-and-volume).
 
 ## 1. Incompatible plasmid segregation

diff --git a/docs/tutorials/flow-solvers.md b/docs/tutorials/flow-solvers.md
@@ -2,6 +2,8 @@
 
 The [pillar-channel model](../../examples/tutorials/pillar_channel.py) combines cylindrical walls, a depth-integrated flow calculation, attached founder lineages, and released daughters:
 
+Cells retain three-dimensional mechanics inside the channel walls at Z=±3. XY-only division jitter and depth-integrated flow do not impose a planar cell constraint; fixed founders remain attached while released daughters can move and tilt within the finite-height chamber. See the [dimensionality audit](planarity.md).
+
 ```console
 uv run microsimulator view --model examples/tutorials/pillar_channel.py --seed 7 --dt 0.01 --backend metal --open
 ```

diff --git a/docs/tutorials/intracellular-dynamics.md b/docs/tutorials/intracellular-dynamics.md
@@ -2,6 +2,8 @@
 
 This tutorial introduces intracellular concentrations, growth dilution, typed rate equations, gene-circuit feedback, and quantitative time-course analysis. The runnable scenarios are collected in `examples/tutorials/gene_expression.py`.
 
+All five scenarios use XY-only division jitter and start with centers at Z=0, but add no mechanical walls. Their cells retain three-dimensional translations and rotations. See [division jitter and out-of-plane motion](planarity.md) before treating a planar-looking trajectory as a strict 2D model.
+
 All five gene-expression scenarios request a founder centerline length of 3.5 and cap it at the one sampled division target. Initial concentrations are unchanged; the smaller biomass can change total initial amount. See [founder initialization and volume conventions](biophysics-and-growth.md#length-and-volume).
 
 ## The native species contract

diff --git a/docs/tutorials/microfluidics.md b/docs/tutorials/microfluidics.md
@@ -2,6 +2,8 @@
 
 This tutorial connects device geometry, flowing media, and cell biology in runnable MicroSimulator models. The [modeling guide](../microfluidics.md) introduces the workflow and the choice of flow solver. Four examples cover the range:
 
+These models use XY-only division jitter and finite-height 3D confinement. A thin cavity can encourage a monolayer, but it does not force a common center Z or eliminate tilt; walls are soft constraints whose residual depends on relaxation tolerance and passes. The [dimensionality audit](planarity.md) lists each device and reproduces these distinctions.
+
 The microfluidic-trap, Danino, biopixel, and pillar tutorial founders request centerline length 3.5, capped at their single sampled target in [3.2, 3.8]. Attachment, position, radius, and concentrations are preserved. This affects new construction only; saved geometry is restored unchanged. See [founder initialization and volume conventions](biophysics-and-growth.md#length-and-volume).
 
 | Model | Device | Demonstrates |