fix(gpu): apply identical Z-axis disc projection in bad-frame fallback

The bad-frame fallback re-projected last-good positions with a divergent
Y-axis separation, so a rejected frame would briefly re-orient or collapse
the two discs. Route the fallback through project_node_xy with the same
per-population centroids and fixed DISC_RIM_RADIUS rim-clamp as the healthy
path and ForceFullBroadcast, keeping all three projection call sites in sync.

Reconcile the architecture diagrams with the landed code: decoupled rim
radius (DISC_RIM_RADIUS=2600, not sep*0.85), single PUT/broadcast write
path, population SSOT via metadata["type"], and reader-vs-writer ownership
in the analytics wire.

Co-Authored-By: jjohare <github@thedreamlab.uk>

Author: jjohare

docs/architecture/diagrams/01-settings-flow.md

@@ -52,7 +52,7 @@ sequenceDiagram
     Note over SQLite: settings_routes.rs:405 — persisted after<br/>in-memory update succeeds
     REST_PUT-->>SApi: 200 OK {new PhysicsSettings}
 
-    Note over ZS,SApi: PARALLEL PATH (also triggered by updatePhysics):<br/>physicsSlice.ts:130 — notifyPhysicsUpdate fires<br/>settingsApi.updatePhysics() DIRECTLY,<br/>bypassing autoSaveManager entirely
+    Note over ZS,SApi: SINGLE PUT PATH (T2 resolved 2026-06-03):<br/>physicsSlice.ts:129-139 — notifyPhysicsUpdate is now a NO-OP<br/>for persistence. It used to fire settingsApi.updatePhysics()<br/>DIRECTLY (a 2nd PUT per commit / double warmup reset).<br/>Persistence is owned solely by the debounced autoSaveManager<br/>path, so each change reaches the backend exactly once.
 ```
 
 ---

docs/architecture/diagrams/03-interaction-events.md

@@ -77,8 +77,8 @@ sequenceDiagram
     Handlers->>GI: updateNodePosition(nodeId, pos)
     Handlers->>Handlers: throttledWebSocketUpdate (100ms)
 
-    Handlers->>WS: sendMessage("nodeDragUpdate", {nodeId, position})<br/>+ sendNodePositionUpdates([{nodeId, position, velocity:{0,0,0}}])
-    Note over Handlers: Two sends per throttle tick:<br/>JSON "nodeDragUpdate" + legacy binary frame
+    Handlers->>WS: sendMessage("nodeDragUpdate", {nodeId, position, timestamp})
+    Note over Handlers: Single send per throttle tick (T2 resolved 2026-06-03):<br/>JSON "nodeDragUpdate" only. The legacy binary frame<br/>(sendNodePositionUpdates) was removed —<br/>useGraphEventHandlers.ts:60-68 — it sent a redundant<br/>SECOND frame per drag move.
 
     WS->>Server: WS frames received
     Server->>Physics: UpdateNodePosition (server-authoritative pin)
@@ -207,13 +207,13 @@ sequenceDiagram
 
     User->>Slider: drag slider (e.g. repelK)
     Slider->>Store: updateSettings(draft => draft[path] = value)
-    Store->>Store: notifyPhysicsUpdate(graphName, params)
-    Store->>API: settingsApi.updatePhysics(params)<br/>→ GET current + PUT merged (endpoints.ts:79-97)
+    Store->>Store: notifyPhysicsUpdate(graphName, params)<br/>NO-OP for persistence (physicsSlice.ts:129-139)
 
     Slider->>ASM: autoSaveManager.queueChange(path, value) (debounced ~500ms)
     ASM->>API: updateSettingsByPaths([{path, value}])<br/>→ routes to updatePhysics if path contains .physics.
+    API->>Server: PUT /api/settings/physics
 
-    Note over API,Server: Both paths call PUT /api/settings/physics<br/>physicsSlice.notifyPhysicsUpdate fires immediately (no debounce)<br/>autoSaveManager fires after debounce (~500ms)<br/>→ DOUBLE PUT for every slider move
+    Note over API,Server: SINGLE PUT per slider move (T2 resolved 2026-06-03):<br/>notifyPhysicsUpdate no longer fires an immediate PUT.<br/>Only the debounced autoSaveManager path (~500ms) persists,<br/>so the change reaches the backend exactly once.
 ```
 
 ---

docs/architecture/diagrams/05-wire-analytics-types.md

@@ -95,20 +95,20 @@ sequenceDiagram
     participant CL   as ClusteringActor<br/>(GPU)
     participant AD   as AnomalyDetectionActor<br/>(GPU)
     participant MAP  as node_analytics<br/>Arc<RwLock<HashMap<u32,NodeAnalytics>>>
-    participant CC   as ClientCoordinatorActor<br/>(single-writer consolidation)
+    participant CC   as ClientCoordinatorActor<br/>(READER — broadcast encoder, NOT a writer)
     participant ENC  as encode_node_data_extended_with_sssp()<br/>src/utils/binary_protocol.rs
     participant WS   as WebSocket<br/>(V5 frame)
     participant DEC  as parseBinaryNodeData()<br/>client/src/types/binaryProtocol.ts
     participant WRK  as graph.worker.ts<br/>binary-processor.ts
     participant GEM  as GemNodes.tsx<br/>(render channel)
 
-    Note over PR,AD: GPU kernel results read back to CPU
-    PR  ->> MAP: write entry.centrality = normalised_pagerank<br/>(single writer, resets stale nodes to 0.0)
-    CL  ->> MAP: write entry.cluster_id (1-based, 0=unclustered)<br/>write entry.community_id (Louvain)
-    AD  ->> MAP: write entry.anomaly (LOF/z-score, 0.0–1.0)
+    Note over PR,AD: GPU kernel results read back to CPU.<br/>WRITE OWNERSHIP: each analytics actor is the sole writer of its OWN<br/>field(s) into node_analytics. ClusteringActor owns cluster_id +<br/>community_id (ADR-031 D3 single writer, write_cluster_id_from_assignments);<br/>PageRankActor owns centrality; AnomalyDetectionActor owns anomaly.<br/>ClientCoordinatorActor does NOT write — it only reads at broadcast time.
+    PR  ->> MAP: write entry.centrality = normalised_pagerank<br/>(sole writer of centrality, resets stale nodes to 0.0)
+    CL  ->> MAP: write entry.cluster_id (1-based, 0=unclustered)<br/>write entry.community_id (Louvain)<br/>(sole writer of cluster_id + community_id)
+    AD  ->> MAP: write entry.anomaly (LOF/z-score, 0.0–1.0)<br/>(sole writer of anomaly)
 
-    Note over CC: Physics tick broadcast
-    CC  ->> MAP: node_analytics.read().ok()
+    Note over CC: Physics tick broadcast — CC READS only
+    CC  ->> MAP: node_analytics.read().ok()<br/>(client_coordinator_actor.rs:813,954,1491 — reader)
     MAP -->> CC: Option<&HashMap<u32, NodeAnalytics>>
     CC  ->> ENC: encode_node_data_extended_with_sssp(<br/>  nodes, …, sssp_data=None, analytics_data)
     Note over ENC: Writes 52 B per node into Vec<u8>.<br/>Strips flag bits from node_id before<br/>HashMap lookup (base_id = id & NODE_ID_MASK).

docs/architecture/diagrams/06-gpu-physics.md

@@ -87,7 +87,7 @@ sequenceDiagram
 
     note over FCA: Good frame:<br/>  Clamp positions to MAX_COORD, velocities to MAX_VELOCITY_MAGNITUDE<br/>  Reset consecutive_bad_frames = 0<br/>  Snapshot -> last_good_positions (pristine physics state)
 
-    note over FCA: DISC PROJECTION (display-only, applied to broadcast buffer):<br/>  population_centroids_xy(): per-population median X,Y<br/>  project_node_xy() per node:<br/>    dx=pos.x-cx, dy=pos.y-cy; rim-clamp to r_max=sep*0.85<br/>    pos.x = dx, pos.y = dy  (re-centred around population median)<br/>    pos.z = pos.z*face_scale + target_z  (flatten Z, offset by ±sep)<br/>  Knowledge: target_z=-sep  Ontology: target_z=+sep  Agent: target_z=0
+    note over FCA: DISC PROJECTION (display-only, applied to broadcast buffer):<br/>  population_centroids_xy(): per-population median X,Y<br/>  project_node_xy() per node:<br/>    dx=pos.x-cx, dy=pos.y-cy; rim-clamp to r_max=DISC_RIM_RADIUS=2600 (fixed, DECOUPLED from sep)<br/>    pos.x = dx, pos.y = dy  (re-centred around population median)<br/>    pos.z = pos.z*face_scale + target_z  (flatten Z, offset by ±sep)<br/>  Knowledge: target_z=-sep  Ontology: target_z=+sep  Agent: target_z=0
 
     FCA->>GS: UpdateNodePositions (projected broadcast positions)
 
@@ -142,7 +142,7 @@ flowchart LR
     B -->|No| E["broadcast_buffer = raw physics\n(no transform)"]
     B -->|Yes| C["population_centroids_xy()\nmedian X,Y per population\n(Knowledge=0, Ontology=1, Agent=2)"]
 
-    C --> D["project_node_xy() per node\n  dx = pos.x - centroid_x\n  dy = pos.y - centroid_y\n  rim-clamp to r_max = sep*0.85\n  pos.x = dx\n  pos.y = dy\n  pos.z = pos.z*(1-flatten) + target_z\nAxis asymmetry: X/Y re-centred on\nPER-POPULATION median;\nZ flattened around GLOBAL origin (0)"]
+    C --> D["project_node_xy() per node\n  dx = pos.x - centroid_x\n  dy = pos.y - centroid_y\n  rim-clamp to r_max = DISC_RIM_RADIUS = 2600\n  (fixed const, DECOUPLED from sep — small sep\n   keeps discs full-size)\n  pos.x = dx\n  pos.y = dy\n  pos.z = pos.z*face_scale + target_z\n  (face_scale = 1 - flatten)\nAxis asymmetry: X/Y re-centred on\nPER-POPULATION median;\nZ flattened + separated on the SAME axis (Z)"]
 
     D --> E["broadcast_buffer = projected positions\n(display-only: clients see discs)"]
     E --> F["UpdateNodePositions -> GraphService -> WebSocket clients"]
@@ -169,10 +169,15 @@ discs would never stabilise.
 
 **Costs of the current design:**
 - Every step allocates and reads `last_good_positions` (O(N) clone, host memory).
-- The projection is computed twice when a divergent frame falls back to
-  `last_good_positions` (lines 1731-1763 also project the fallback snapshot).
+- The projection is computed a third time when a divergent frame falls back to
+  `last_good_positions` (lines 1744-1779). As of 2026-06-03 the fallback calls the
+  SAME `project_node_xy` (Z-separation + per-population median re-centre +
+  `DISC_RIM_RADIUS` rim-clamp) as the main path. It previously separated on the
+  Y axis with no centroid/rim-clamp, so a bad frame briefly re-oriented the discs
+  onto a different axis — that inconsistency is now removed.
 - `ForceFullBroadcast` must independently re-implement the same projection
-  (lines 2299-2321), creating a second code path that must stay in sync.
+  (near line 2327, `let r_max = DISC_RIM_RADIUS`), creating a second code path
+  that must stay in sync.
 - Population classification from `metadata["type"]` is a string-match at graph
   upload time (lines 607-633); the result is cached in `node_population` but
   is not re-verified if metadata changes without a graph reload.
@@ -313,12 +318,12 @@ counter and delays convergence detection.
 
 ### Projection per-step apply/undo cost
 
-The disc projection at `force_compute_actor.rs:1816-1831` and the restore at
-`1964-1969` both iterate over all nodes (O(N)) on the hot path every frame that
-has `project=true`. The `last_good_positions.clear()` and rebuild at `1797-1808`
+The disc projection at `force_compute_actor.rs:1829-1846` and the restore at
+`1979-1984` both iterate over all nodes (O(N)) on the hot path every frame that
+has `project=true`. The `last_good_positions.clear()` and rebuild at `1811-1821`
 also copies all N `(node_id, Vec3, Vec3)` triples. For graphs with tens of
 thousands of nodes this is three O(N) passes per frame on the Tokio actor thread
 (not offloaded to `spawn_blocking`), adding CPU-side latency to the
-broadcast-critical path. The `ForceFullBroadcast` handler at `2293-2335` performs
-its own independent projection pass with a separate `population_centroids_xy` call,
-duplicating the computation outside the main loop.
+broadcast-critical path. The `ForceFullBroadcast` handler (around line 2327)
+performs its own independent projection pass with a separate
+`population_centroids_xy` call, duplicating the computation outside the main loop.

docs/architecture/diagrams/qe-T1-population-ssot.md

@@ -1,8 +1,19 @@
 # QE-T1 — Node Population Has No Single Source of Truth
 
-**Anomaly**: T1 (cartography audit #1). **Status**: REPRODUCED, defect confirmed.
+> **✅ SUPERSEDED — FIX LANDED 2026-06-03.** This is a frozen pre-fix reproduction
+> report, retained for historical context. Population now has a single source of
+> truth: `metadata["type"]`, read via `Node::population_type()` / `Node::population()`
+> (`crates/visionclaw-domain/src/models/node.rs:271,283`) and consumed uniformly by
+> `graph_state_actor.rs:242,288` and the GPU path. **Note:** the fix chose the
+> OPPOSITE field from this report's §6 fix-spec — `metadata["type"]` is authoritative,
+> NOT `node_type`. `ontology_enrichment_service` no longer rewrites `node_type`, so
+> the two fields can no longer desync. Authoritative current model:
+> `02-population-handoff.md §7` and `00-anomaly-register.md`. The §2/§4 truth tables
+> below describe pre-fix divergent behaviour that no longer occurs.
+
+**Anomaly**: T1 (cartography audit #1). **Status**: RESOLVED (was: REPRODUCED, defect confirmed).
 **Author**: agentic-QE investigator. **Date**: 2026-06-03.
-**Scope**: reproduction evidence + failing regression test + fix spec. **No production code changed.**
+**Scope**: reproduction evidence + failing regression test + fix spec. **No production code changed *by this report*.**
 
 ---
 

docs/architecture/diagrams/qe-T2-T4-writepaths-ceilings.md

@@ -1,6 +1,20 @@
 # QE Anomaly Report: T2 (Doubled Write/Dispatch Paths) + T4 (Validation-Ceiling Mismatches)
 
-> Status: REPRODUCTION EVIDENCE — do NOT fix here. Minimal fix specs at bottom.
+> **✅ SUPERSEDED — FIXES LANDED 2026-06-03.** This is a frozen pre-fix reproduction
+> report. Both anomalies are resolved:
+> - **T2** (doubled write/dispatch): the duplicate `notifyPhysicsUpdate` DIRECT PUT
+>   is now a no-op (`physicsSlice.ts:129-138`); slider commits take a single PUT path.
+>   The legacy binary drag frame is removed (`useGraphEventHandlers.ts:61-64`) — one
+>   JSON `nodeDragUpdate` per tick. Backend physics propagation routes solely via
+>   `propagate_physics_to_gpu` (no direct-GPU fallback).
+> - **T4** (validation-ceiling mismatch): resolved by the physics-bounds SSOT in
+>   `src/actors/gpu/physics_bounds.rs`.
+>
+> Authoritative current state: `00-anomaly-register.md` (resolution table T2/T4).
+> Reproduction evidence below is retained for historical context. Note line cites
+> may be stale (e.g. `force_compute_actor.rs:2188` warmup assignment is now at L2203).
+
+> Status: ~~REPRODUCTION EVIDENCE — do NOT fix here~~ → RESOLVED. Minimal fix specs at bottom.
 > Investigator: QE static analysis pass, 2026-06-03
 
 ---

docs/architecture/diagrams/qe-T5-analytics-shadow.md

@@ -1,7 +1,22 @@
 # QE T5 — Analytics Shadow: Data-Path Audit and Dual-Modularity Evidence
 
+> **✅ SUPERSEDED — FIXES LANDED 2026-06-03.** This is a frozen pre-fix reproduction
+> report. Both defects are resolved:
+> - **Claim 1 (hulls never render / handler never writes `node_analytics`)**: the
+>   clustering spawn task now routes its `Vec<Cluster>` through the
+>   `WriteClusterAnalytics` message (`analytics_messages.rs:138`; handled at
+>   `clustering_actor.rs:1193`, `gpu_manager_actor.rs:857`, `analytics_supervisor.rs:422`),
+>   covering both the GPU and CPU-fallback branches via the single writer.
+> - **Claim 2 (dual divergent modularity)**: the CPU shadow `calculate_modularity`
+>   is DELETED (only removal comments remain at `clustering_actor.rs:409,886`); a single
+>   `modularity_csr` with `MODULARITY_GATE=0.3` (`clustering_actor.rs:1336`) remains.
+>
+> Authoritative current state: `07-analysis-clustering.md` (§3b, PARALLEL-1) and
+> `00-anomaly-register.md`. Hulls render on explicit clustering trigger; auto-trigger
+> remains opt-in/OFF by default. Evidence below is retained for historical context.
+
 **Audit date**: 2026-06-03  
-**Status**: CONFIRMED DEFECT — reproduction test in `tests/qe_t5_shadow_modularity.rs`
+**Status**: ~~CONFIRMED DEFECT~~ → RESOLVED — reproduction test in `tests/qe_t5_shadow_modularity.rs`
 
 ---
 

src/actors/gpu/force_compute_actor.rs

@@ -1745,19 +1745,30 @@ impl Handler<ComputeForces> for ForceComputeActor {
                                         if let Some(_seq) = actor.backpressure.try_acquire() {
                                             let mut node_updates =
                                                 Vec::with_capacity(actor.last_good_positions.len());
+                                            // Compute population centroids from the last-known-good
+                                            // layout so the fallback applies the IDENTICAL projection
+                                            // as the healthy path (Z-separation, per-population median
+                                            // re-centre, fixed DISC_RIM_RADIUS rim-clamp) instead of a
+                                            // divergent Y-separation. A bad frame must not briefly
+                                            // re-orient or collapse the two discs.
+                                            let centroids = if project {
+                                                population_centroids_xy(
+                                                    &actor.node_population,
+                                                    |i| {
+                                                        let (_, p, _) = actor.last_good_positions[i];
+                                                        (p.x, p.y)
+                                                    },
+                                                    actor.last_good_positions.len(),
+                                                )
+                                            } else {
+                                                Default::default()
+                                            };
+                                            let r_max = DISC_RIM_RADIUS;
                                             for (idx, (node_id, pos, vel)) in actor.last_good_positions.iter().enumerate() {
-                                                // Apply the same display-only projection to the
-                                                // fallback so a divergent frame doesn't briefly
-                                                // collapse the two discs back together.
                                                 let mut p = *pos;
                                                 if project {
                                                     if let Some(&pop) = actor.node_population.get(idx) {
-                                                        p.z *= face_scale;
-                                                        match pop {
-                                                            GraphPopulation::Knowledge => p.y -= sep,
-                                                            GraphPopulation::Ontology => p.y += sep,
-                                                            GraphPopulation::Agent => {}
-                                                        }
+                                                        project_node_xy(&mut p, pop, &centroids, sep, face_scale, r_max);
                                                     }
                                                 }
                                                 node_updates.push((*node_id, BinaryNodeDataClient::new(