Insert Stage 9 (Solver & Run Integrity), renumber Stages 9-15 to 10-16

README.md

@@ -8,9 +8,9 @@
 
 **Current Version:** 0.3.0 — cut 2026-09-03 when Stage 7 (Rendering Annotations) closed (`docs/planning/releases.md`).
 
-PyFlow has completed **Stage 7 (Rendering Annotations)** and has not yet
-begun Stage 9 (Better Numerics) -- Stage 8 (Recording & Playback), added
-2026-09-07, comes first. Stage 0 built
+PyFlow has completed **Stage 8 (Recording & Playback)** and has not yet
+begun Stage 10 (Better Numerics) -- Stage 9 (Solver & Run Integrity),
+added 2026-09-12, comes first. Stage 0 built
 the engineering
 foundations; Stage 1 added the first real engine code -- a
 `CoordinateSystem`, a `Mesh` with a structured Cartesian implementation,
@@ -131,7 +131,24 @@ need to find it.
 
 ## Current Phase
 
-Stage 9 — Better Numerics -- not yet started. Stage 8 (Recording &
+Stage 9 — Solver & Run Integrity -- opened 2026-09-12, not yet
+complete. It exists because an end-to-end audit that day found four
+defects behind a green `make ci`, two of which falsify use cases **Stage
+4 wrote down for itself**: solid walls turned out to be permeable to
+advection (a sealed box loses 14.27% of a purely advected tracer in 400
+steps), and a diverged run reported `pyflow exited cleanly` with exit 0
+because the render loop swallowed the engine's own
+`DivergenceDidNotConvergeError`. Two more: nothing checks a configured
+timestep against the stability limit, so refining a shipped demo's mesh
+blows up silently at step 17; and `BoundaryFaceConfig.velocity` is a
+validated, documented configuration field that no engine code reads.
+See `docs/planning/roadmap.md`'s own Stage 9 section for the criteria
+and the measurements. It is placed before Better Numerics by dependency,
+not preference -- Stage 10's own Rayleigh-Bénard criterion measures
+convection between heated walls, which is not meaningful while those
+walls leak.
+
+Stage 8 (Recording &
 Playback) was **reopened and reclosed on the same day, 2026-09-09**: an
 audit, prompted by the maintainer's own suspicion that it "never
 actually went through a design/planning session," found the suspicion
@@ -153,8 +170,8 @@ its exit on 2026-09-11 -- each edit to this paragraph has so far landed
 in the same change as the roadmap event it describes, unlike the
 multi-day staleness windows the two paragraphs below describe for
 Stages 7 and 8's own *earlier* drafts. Don't read this as the pattern
-solved; read Stage 9's own eventual entry here as the next real test of
-it.
+solved; read Stage 10 (Better Numerics)'s own eventual entry here as
+the next real test of it.
 
 **And read the exit audit before trusting that record too far.** This
 paragraph tracks whether *this section* stays current, which it has.
@@ -345,8 +362,8 @@ together). A config with no solved velocity at all (Heat Diffusion's
 own shape) still has nothing for this to render, and is rejected the
 same way it always was.
 
-Stage 9 (Better Numerics) follows Stage 8 (Recording & Playback, added
-2026-09-07) -- better advection and diffusion
+Stage 10 (Better Numerics) follows Stage 9 (Solver & Run Integrity,
+added 2026-09-12) -- better advection and diffusion
 schemes, and with them the quantitative Rayleigh-Bénard comparison Stage
 6 deliberately deferred rather than met on a first-order-upwind solver.
 **Its eight completion criteria were written on 2026-09-04, before the

adr/ADR-004-compute-rendering-class.md

@@ -102,7 +102,8 @@ Alternatives Considered below.
   wgpu, CUDA-GL interop) remains unproven for every candidate in this
   class and is accepted as a known, deferred risk, not resolved by this
   decision. If profiling ever shows the round-trip has become a real
-  bottleneck (most likely at Stage 13's 3D scale, where cost scales as
+  bottleneck (most likely at Stage 14 (Three Dimensions)'s 3D scale,
+  where cost scales as
   N³ rather than N²), that interop engineering will need to be done
   then.
 - **No production-scale validation as strong as Warp's Newton/Isaac Lab
@@ -173,7 +174,7 @@ interface so a future swap (e.g. if the Array API standard matures
 further, or if a specific instance's GPU story regresses) is an
 implementation change, not an architectural one.
 
-Re-profile the host round-trip's cost before Stage 13 (Three
+Re-profile the host round-trip's cost before Stage 14 (Three
 Dimensions) rather than
 assuming §4.1's 2D-scale estimate still holds -- that is the point at
 which this decision's accepted risk was identified as most likely to

adr/ADR-005-compute-rendering-instances.md

@@ -153,5 +153,6 @@ budget for this as real implementation work, not assume it is free.
 
 Re-evaluate the DLPack-based zero-copy path between PyTorch and
 wgpu/pygfx if profiling ever shows the host round-trip has become a real
-bottleneck -- per `ADR-004`, most likely at Stage 13's 3D scale, not
+bottleneck -- per `ADR-004`, most likely at Stage 14 (Three
+Dimensions)'s 3D scale, not
 before.

docs/architecture/compute-and-rendering-stack.md

@@ -148,7 +148,7 @@ uniform grid) at a generous 2048×2048 cells with four `float32` fields
 At a more MVP-realistic 512×512 with the same four fields (~4.2 MB), the
 cost is **sub-millisecond either way** -- not a real constraint at all.
 
-**Where this changes:** 3D (Stage 13, Three Dimensions) scales as N³,
+**Where this changes:** 3D (Stage 14, Three Dimensions) scales as N³,
 not N². A 512³ grid
 with the same four fields is ~4.3 GB/frame -- the same fallback would be
 disqualifying at that scale, not merely slow. That is explicitly future
@@ -173,7 +173,7 @@ project's near/medium-term scope -- revised there.
 | **Python 3.14 support** | Confidence varies per library at this snapshot and needs a direct check before A2c, not assumed from this document -- new-release lag is exactly the pattern the version-review policy in `docs/practices.md` exists to catch. |
 | **Licence vs. BSD-3-Clause** | All candidates above are permissively licensed at this snapshot to the best of this survey's knowledge (BSD/MIT/Apache-2.0-family) -- **confidence: medium**, worth a direct check per final candidate rather than trusted wholesale. |
 | **Headless / CI capable** | Hard requirement, from `docs/implementation/golden-demos.md` via D5. NumPy/CuPy/PyTorch/JAX's *compute* side is unaffected (no display needed). On the *rendering* side, now the live question since Class 2 was decided: **wgpu/pygfx has the strongest confirmed story of any general-purpose renderer surveyed** (verified 2026-08-15 -- own CI runs headless via LavaPipe as standard practice, not just documented as possible). **VisPy's is real but rougher** (verified 2026-08-15 -- EGL backend exists, but a headless-rendering-without-sudo issue has sat open and unaddressed since 2023, and other EGL issues recur through its history). **VTK's and ModernGL/glfw-family's headless claims were not re-verified live this session** -- they rest on the original May-2026 snapshot ("VTK has established offscreen support," "ModernGL/glfw can run headless via EGL/OSMesa with known extra setup") and should be checked with the same rigour before A2c finalises if either becomes a live candidate. (Taichi GGUI's headless support was confirmed live 2026-08-15 during the Class 3 evaluation, now moot since Class 2 was chosen -- kept here for the record.) |
-| **2D now, 3D at Stage 13 (Three Dimensions) without a rewrite** | VTK/PyVista strongest here (3D-native). VisPy, wgpu/pygfx and Taichi GGUI all support 3D. Thin layers (ModernGL) support it but every capability (camera, projection) is ours to build. |
+| **2D now, 3D at Stage 14 (Three Dimensions) without a rewrite** | VTK/PyVista strongest here (3D-native). VisPy, wgpu/pygfx and Taichi GGUI all support 3D. Thin layers (ModernGL) support it but every capability (camera, projection) is ours to build. |
 | **Capability Level 9 (GPU execution)** | Only the GPU-capable axis-1 candidates are relevant at all; among those, Taichi's story is the most coherent *because* compute and render already share a device and runtime. The others would need the interop work in §4 regardless of whether Level 9 is pursued, if a GPU array library is chosen now for compute alone. |
 | **Multiple renderers (maintainer's stated ambition)** | The NumPy row is renderer-agnostic almost by definition -- any renderer can consume it, which is what keeps a second renderer cheap. Every 🟡/❔ cell above represents *renderer-specific* plumbing that would need re-doing per additional renderer if a GPU array library couples tightly to one. Taichi GGUI is the extreme case: choosing it as the primary renderer effectively forecloses easily adding a second, different renderer for the *same* field data, because the coupling **is** the point of that class. |
 | **Proven for this domain specifically** | Checked live, 2026-08-15, for the Class 2 array libraries. **JAX-Fluids** (differentiable compressible/two-phase CFD, runs CPU/GPU/TPU) and **PhiFlow** (multi-backend differentiable PDE/fluid framework -- "the exact same code runs a 2D NumPy sim or a 3D GPU PyTorch/JAX sim") both exist and validate the *compute-side* pattern -- swappable NumPy-shaped backends genuinely work for fluid simulation, not just in theory. **Caveats, checked rather than assumed:** both are themselves stale as dependencies would be judged in this survey -- JAX-Fluids' latest release is 2025-03-21 (~17 months old), PhiFlow's is 2025-08-02 (~1 year old) -- though this matters less here than Taichi's staleness does, since PyFlow would not depend on either package, only take them as evidence the architecture works. **More importantly: neither resolves the rendering-coupling question above.** PhiFlow's own answer to visualization is a web-based interactive UI (`view()`), not a native desktop render loop -- architecturally different from what `roadmap.md` TASK-007 specifies (window, render loop, clean shutdown). These projects prove the compute pattern; they sidestep the native-rendering question rather than answering it. **Also checked and explicitly ruled out as evidence: JAX-CFD**, Google's own earlier CFD-in-JAX project, carries an explicit "no longer maintained" notice from Google in its own commit history (2026-02-24) -- it very nearly went into this survey as a positive data point before that was found; JAX-Fluids and PhiFlow are the sources actually being cited here. |
@@ -205,7 +205,8 @@ round-trip (or spiking the DLPack/CUDA-GL interop path from §4).
   point of a GPU array library," is very likely a non-issue at this
   project's near/medium-term scale (sub-millisecond at MVP grid sizes,
   single-digit milliseconds even at a generous 2048×2048) -- a real cost
-  only reappears at Stage 13's 3D scale, later work. This meaningfully
+  only reappears at Stage 14 (Three Dimensions)'s 3D scale, later work.
+  This meaningfully
   de-risks Class 2 relative to the first survey pass.
 - *Proven for the domain:* CuPy, PyTorch and JAX are all independently
   and currently well-maintained (verified live, §2), and the

docs/architecture/icds.md

@@ -166,7 +166,8 @@ transported, not a discretisation decision. **That reasoning is why it
 does not live under `numerics` at all: it moved to `FluidConfig` in
 TASK-041 (2026-08-28, Stage 5's design question four), and this entry
 still said `numerics.diffusion_coefficient` until 2026-09-04** -- found
-while drafting Stage 9's completion criteria, which is a stage that
+while drafting Stage 10 (Better Numerics)'s completion criteria, which
+is a stage that
 reads this ICD for what its own "improved diffusion" work would have to
 change. A config setting the old name is rejected at load with a named
 error pointing at the new one, so the stale entry named a field no run

docs/planning/CLAUDE.md

@@ -29,7 +29,7 @@ The two files are gated against each other, so adding a section to the
 shape without explaining it in the specification fails the build.
 
 **A `sketched` stage may already carry some of them, so check before
-writing rather than assuming a blank.** Stage 9 (Better Numerics) was
+writing rather than assuming a blank.** Stage 10 (Better Numerics) was
 given its eight Completion Criteria and its **Serves** line on
 2026-09-04, while still sketched -- earlier than the rule asks, at the
 maintainer's request. What it deliberately does *not* have is **Use