Add experimental kinematic flow coupling

[marpaia]

Purpose

This experimental layer defines how a solved fluid velocity moves rod-shaped cells and how a model updates spatial reaction fields during a run. It is the first stack layer that couples flow to cell geometry.

Key methodological contributions

• Endpoint-sampled kinematic drift: each non-fixed rod samples the velocity field at both capsule centerline endpoints. Translation is the mean endpoint velocity times dt; rotation is dt * (axis cross (v2 - v1)) / length, capped by the mechanics rotation limit. Degenerate rods do not rotate.
• Explicit operator splitting: drift runs after growth and before ordinary contact relaxation, which resolves overlaps with cells and walls introduced by the drift step. Sampling clamps to the grid boundary, and an all-solid stencil returns zero velocity.
• Backend-independent coupling contract: drift operates on committed host state, so CPU, Metal, and CUDA simulations share one rule without separate fluid-force kernels.
• Checkpoint-stable coupling: flow_drift is validated and restored with the closed mechanics configuration. A regression test compares uninterrupted uniform-flow motion with save/load/resume and requires identical simulation and controller state.
• Runtime reaction feedback: Simulation.set_signal_reaction validates and atomically replaces affine grid source and loss fields, enabling models to refresh spatial sinks such as colony-dependent degradation.
• Implicit transport correctness: Crank-Nicolson convergence is measured relative to the residual at the start of the linear solve, with a float32 resolution floor, so resolvable weak cell-grid exchange is not silently accepted as zero against a large background field.

Scientific scope

• This is passive kinematic advection, not force-balanced hydrodynamics. It has no cell drag law, wall-dependent slip, fluid force or torque in the mechanics solve, hydrodynamic cell-cell interaction, or Brownian motion.
• The split update is first-order in time. max_speed * dt must remain small relative to a cell radius, and timestep sensitivity is required for quantitative use.
• Colony-to-flow feedback still uses PR Add numerical flow solvers for device authoring #3's phenomenological mobility closure and requires coefficient, grid, and refresh-cadence sensitivity evidence.

Stack

PR 3 of 5.

Base: #3 (marpaia/microfluidics-flow-solvers)

Next: #5 (marpaia/microfluidics-device-assets)

Validation

• Exact Add experimental kinematic flow coupling #4 Python suite: 261 passed, 40 skipped
• Full pre-commit suite, including Ruff, clang-format, and Pyright: passed
• Metal native conformance on the unchanged native source at the stacked head: 21 of 21 passed
• CUDA 12.8 compile check on the unchanged native source at the stacked head: passed; no NVIDIA runtime was exercised