checkpoint: per-population meshes + analytics/physics correctness

Client viz:
- GemNodes renders one InstancedMesh per population (knowledge/ontology/
  agent) via forceMode + instanceIdBase; GraphManager partitions visible
  nodes by visual mode so a mixed graph shows each population's primitive
  instead of a single dominant geometry. KnowledgeRings + meshProxy track
  the knowledge-population mesh.
- Population SSOT: metadata.type is the authoritative classification (T1),
  resolved consistently across visual-state, filtering, and scaling.

Backend (analytics + GPU):
- Louvain modularity + parallel-race fixes, PageRank FFI, SSSP feed,
  anomaly routing; single-writer node_analytics; physics bounds SSOT
  and compact-settle profile in PhysicsConfig::default().

Docs + tests:
- Verified architecture diagrams, KNOWN_ISSUES, regenerated client/backend
  architecture docs; T1/T2/T4/T5 repro + wire-snapshot tests.

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

Author: jjohare

CLAUDE.md

@@ -76,6 +76,7 @@ Research + NotebookLM? --> /notebooklm, /perplexity-research, /gemini-url-contex
 Deep cited research? --> /deep-research (parallel agents, provenance, verification)
 Optimize a metric iteratively? --> /autoresearch (experiment loop, keep/discard)
 Add source verification? --> /provenance-tracking (.provenance.md sidecar)
+Owner's personal email (invoices, threads, "did X email me", find a name)? --> /email-search (ask_email; local gateway, privacy-filtered; NOT work mail/calendar)
 Security / compliance? --> /defense-security
 AEC (building architecture)? --> /studio [task]
 SEO / content optimisation? --> /toprank

client/src/api/settings/__tests__/repro_t4_ceiling_consistency.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Regression tests for T4: validation-ceiling consistency (TypeScript/client side).
+ *
+ * RESOLVED 2026-06-03. Previously the actor path-pattern ceilings were narrower
+ * than the canonical client defaults (repelK 120 > 100, maxVelocity 100 > 50,
+ * springK 12 > 10), so boot-time defaults were silently clamped. The backend now
+ * reads every (MIN, MAX) from a single source of truth,
+ * src/actors/gpu/physics_bounds.rs, so the actor path validator, the route
+ * validator and the canonical client defaults can never diverge again.
+ *
+ * These tests pin the UNIFIED ceilings (kept in sync with physics_bounds.rs) and
+ * assert the canonical DEFAULT_PHYSICS_SETTINGS values are ACCEPTED — i.e. each
+ * default sits inside the legal range and would not be clamped on boot. The
+ * Rust-side counterpart (tests/repro_t4_ceiling_consistency.rs) drives the real
+ * validate_physics_settings() with these same magnitudes.
+ *
+ * Fix spec: docs/architecture/diagrams/qe-T2-T4-writepaths-ceilings.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { DEFAULT_PHYSICS_SETTINGS } from '../defaults';
+
+// ---------------------------------------------------------------------------
+// Unified ceilings — single source of truth is
+// src/actors/gpu/physics_bounds.rs (MAX of each (MIN, MAX) Bound). Kept in sync
+// with the Rust constants; the Rust test pins the same magnitudes against the
+// real validator so a drift on either side is caught.
+// ---------------------------------------------------------------------------
+const SPRING_K_MAX = 500.0; // physics_bounds::SPRING_K.1
+const REPEL_K_MAX = 500.0; // physics_bounds::REPEL_K.1
+const MAX_VELOCITY_MAX = 1000.0; // physics_bounds::MAX_VELOCITY.1
+const MAX_FORCE_MAX = 5000.0; // physics_bounds::MAX_FORCE.1
+
+// Rust backstop constant — force_compute_actor.rs. Held equal to the unified
+// max_velocity ceiling so the backstop is only ever a safety net.
+const RUST_BACKSTOP_MAX_VELOCITY = 1000.0;
+
+// Canonical default magnitudes the fix must keep accepting (defaults.ts).
+const CANONICAL = { springK: 12.0, repelK: 120.0, maxVelocity: 100.0, maxForce: 150.0 };
+
+describe('T4 (resolved): canonical physics defaults are accepted by the unified ceilings', () => {
+  it('defaults.ts still carries the canonical magnitudes', () => {
+    expect(DEFAULT_PHYSICS_SETTINGS.springK).toBe(CANONICAL.springK);
+    expect(DEFAULT_PHYSICS_SETTINGS.repelK).toBe(CANONICAL.repelK);
+    expect(DEFAULT_PHYSICS_SETTINGS.maxVelocity).toBe(CANONICAL.maxVelocity);
+    expect(DEFAULT_PHYSICS_SETTINGS.maxForce).toBe(CANONICAL.maxForce);
+  });
+
+  it('repelK default (120) is within the unified ceiling (500) — not clamped', () => {
+    expect(DEFAULT_PHYSICS_SETTINGS.repelK!).toBeLessThanOrEqual(REPEL_K_MAX);
+  });
+
+  it('maxVelocity default (100) is within the unified ceiling (1000) — not clamped', () => {
+    expect(DEFAULT_PHYSICS_SETTINGS.maxVelocity!).toBeLessThanOrEqual(MAX_VELOCITY_MAX);
+  });
+
+  it('springK default (12) is within the unified ceiling (500) — not clamped', () => {
+    expect(DEFAULT_PHYSICS_SETTINGS.springK!).toBeLessThanOrEqual(SPRING_K_MAX);
+  });
+
+  it('maxForce default (150) is within the unified ceiling (5000) — not clamped', () => {
+    expect(DEFAULT_PHYSICS_SETTINGS.maxForce!).toBeLessThanOrEqual(MAX_FORCE_MAX);
+  });
+
+  it('the unified max_velocity ceiling equals the Rust backstop so the backstop never clamps healthy frames', () => {
+    expect(MAX_VELOCITY_MAX).toBe(RUST_BACKSTOP_MAX_VELOCITY);
+  });
+});

client/src/api/settings/defaults.ts

@@ -15,35 +15,38 @@ export const DEFAULT_PHYSICS_SETTINGS: Partial<PhysicsSettings> = {
   iterations: 50,
   warmupIterations: 100,
   coolingRate: 0.001,
-  globalSpeed: 0.5,
-  damping: 0.85,
+  globalSpeed: 0.4,
+  damping: 0.9,
 
-  // --- Core forces ---
-  springK: 15.0,
-  repelK: 1200.0,
-  restLength: 80.0,
-  centerGravityK: 0.05,
-  gravity: 0.0001,
-  maxForce: 1000.0,
+  // --- Core forces (canonical compact profile — settles within ~400u bounds) ---
+  springK: 12.0,
+  repelK: 120.0,
+  restLength: 50.0,
+  centerGravityK: 0.2,
+  gravity: 0.002,
+  maxForce: 150.0,
   maxVelocity: 100.0,
 
   // --- Repulsion & spacing ---
-  maxRepulsionDist: 1000.0,
+  maxRepulsionDist: 400.0,
   separationRadius: 2.1155233,
   gridCellSize: 50.0,
   repulsionSofteningEpsilon: 0.0001,
 
   // --- Bounds ---
-  enableBounds: false,
-  boundsSize: 2000.0,
+  // Soft-cube containment sized to the ~400-unit graph envelope. Client fallback
+  // only — the backend PhysicsSettings::default() is the single source of truth
+  // and is hydrated over these on connect.
+  enableBounds: true,
+  boundsSize: 400.0,
   boundaryDamping: 0.95,
 
   // --- Layout forces (FA2 / dual-graph) ---
   linLogMode: true,
   scalingRatio: 10.0,
   adaptiveSpeed: true,
   ssspAlpha: 1.5,
-  graphSeparationX: 1000.0,
+  graphSeparationX: 0.0,
   axisCompressionZ: 0.9,
 
   // --- Per-population spring strength (independent KG/ontology/agent layout control) ---
@@ -140,6 +143,11 @@ export const DEFAULT_CLUSTER_HULLS = {
   // ADR-031 D6: opt-in fabricated spatial-grid hulls. Default OFF — when server
   // clusters are absent, show an empty state, never a fabricated grid.
   spatialFallback: false,
+  // ADR-031 D6: opt-in Louvain-community hulls. Default OFF — community_id is
+  // real but optimised for modularity not spatial locality, so its hulls overlap
+  // into a blob. The honest default community signal is per-node colour
+  // (nodes.colorScheme: 'community'); enable this only when you want the volumes.
+  communityFallback: false,
 };
 
 // ADR-031 D6: ship qualityGates defaults so correct server analytics render by
@@ -197,7 +205,10 @@ export const DEFAULT_INTERACTION_SETTINGS = {
 
 export const DEFAULT_NODES_SETTINGS = {
   baseColor: '#4a6fa5',
-  colorScheme: 'type' as 'type' | 'domain' | 'base',
+  // ADR-031 D6: default to 'community' so the live Louvain partition renders out
+  // of the box. Nodes the server left unclustered (community_id 0) fall through
+  // to per-type colouring in computeColor, so the default is never all-grey.
+  colorScheme: 'community' as 'type' | 'domain' | 'base' | 'community' | 'cluster' | 'centrality' | 'sssp',
   sizeScheme: 'hybrid' as 'degree' | 'fileSize' | 'hybrid',
   perNodeGlow: true,
   metalness: 0.1,

client/src/features/analytics/store/nodeAnalyticsStore.ts

@@ -176,17 +176,29 @@ class NodeAnalyticsStore {
             showCentrality?: boolean;
             showSSSP?: boolean;
           };
-          visualisation?: { clusterHulls?: { enabled?: boolean } };
+          visualisation?: {
+            clusterHulls?: { enabled?: boolean };
+            graphs?: { logseq?: { nodes?: { colorScheme?: string } } };
+          };
         }
       | undefined;
     const qg = s?.qualityGates;
+    // ADR-031 D6: an analytic colour scheme consumes the analytics buffer even
+    // when every quality gate is off, so ingestion must stay live for it.
+    const colorScheme = s?.visualisation?.graphs?.logseq?.nodes?.colorScheme;
+    const analyticColorScheme =
+      colorScheme === 'community' ||
+      colorScheme === 'cluster' ||
+      colorScheme === 'centrality' ||
+      colorScheme === 'sssp';
     return Boolean(
       qg?.showClusters ||
         qg?.showAnomalies ||
         qg?.showCommunities ||
         qg?.showCentrality ||
         qg?.showSSSP ||
-        s?.visualisation?.clusterHulls?.enabled,
+        s?.visualisation?.clusterHulls?.enabled ||
+        analyticColorScheme,
     );
   }
 }

client/src/features/graph/components/ClusterHulls.tsx

@@ -6,6 +6,7 @@ import {
   nodeAnalyticsStore,
   ANALYTICS_STRIDE,
   ANALYTICS_CLUSTER_OFFSET,
+  ANALYTICS_COMMUNITY_OFFSET,
 } from '../../analytics/store/nodeAnalyticsStore';
 
 // ============================================================================
@@ -81,6 +82,15 @@ function getDomainHullColor(domain: string): string {
   return DOMAIN_COLORS[domain] ?? DEFAULT_COLOR;
 }
 
+// ADR-031 D6: Louvain community hull colour. Matches GemNodes' community node
+// hue (multiply-by-83 mod 360, HSL 0.65/0.5) so a hull and its member nodes
+// read as the same region.
+const _communityHullColor = new THREE.Color();
+function getCommunityHullColor(communityId: number): string {
+  const hue = ((communityId * 83) % 360) / 360;
+  return `#${_communityHullColor.setHSL(hue, 0.65, 0.5).getHexString()}`;
+}
+
 interface ClusterPoint {
   id: string;
   x: number;
@@ -264,11 +274,17 @@ export const ClusterHulls: React.FC<ClusterHullsProps> = ({
     const analytics = analyticsRef.current;
     const positions = nodePositionsRef.current;
 
-    // Detect whether any real cluster_id is present (stride ANALYTICS_STRIDE).
+    // Detect which server signals are present (stride ANALYTICS_STRIDE).
+    // cluster_id (DBSCAN/k-means) is the preferred grouping; community_id
+    // (Louvain) is the fallback when no DBSCAN run has populated cluster_id.
     let hasClusterId = false;
+    let hasCommunityId = false;
     if (analytics) {
       for (const idx of nodeIdToIndexMap.values()) {
-        if (analytics[idx * ANALYTICS_STRIDE + ANALYTICS_CLUSTER_OFFSET] > 0) { hasClusterId = true; break; }
+        const a = idx * ANALYTICS_STRIDE;
+        if (analytics[a + ANALYTICS_CLUSTER_OFFSET] > 0) hasClusterId = true;
+        if (analytics[a + ANALYTICS_COMMUNITY_OFFSET] > 0) hasCommunityId = true;
+        if (hasClusterId) break; // cluster_id wins outright; stop early
       }
     }
 
@@ -293,6 +309,30 @@ export const ClusterHulls: React.FC<ClusterHullsProps> = ({
       return { map, colorByKey };
     }
 
+    // ADR-031 D6: no DBSCAN cluster_id, but the live graph carries Louvain
+    // community_id. Community_id is real server structure, but Louvain optimises
+    // graph modularity, not spatial locality — a community's members scatter
+    // across the disc, so its convex hull blankets the whole graph and the
+    // hulls overlap into an uninspectable blob. So community hulls are an opt-in
+    // tier (default off), same as the fabricated spatial fallback; the honest
+    // default community signal is per-node colour (colorScheme: 'community').
+    // Cluster hulls (DBSCAN, spatially compact) remain default-on above.
+    const communityFallback = settings?.visualisation?.clusterHulls?.communityFallback === true;
+    if (hasCommunityId && communityFallback) {
+      for (let ni = 0; ni < nodes.length; ni++) {
+        const node = nodes[ni];
+        const nodeIndex = nodeIdToIndexMap.get(node.id);
+        if (nodeIndex === undefined) continue;
+        const communityId = analytics![nodeIndex * ANALYTICS_STRIDE + ANALYTICS_COMMUNITY_OFFSET];
+        if (!(communityId > 0)) continue;
+        const key = `community-${communityId}`;
+        let arr = map.get(key);
+        if (!arr) { arr = []; map.set(key, arr); colorByKey.set(key, getCommunityHullColor(communityId)); }
+        arr.push(node.id);
+      }
+      return { map, colorByKey };
+    }
+
     // No server clusters. The JS spatial-grid heuristic fabricates clusters and
     // masks missing server data, so it is opt-in (default off). When off, return
     // an empty map → the layer shows nothing.
@@ -313,7 +353,7 @@ export const ClusterHulls: React.FC<ClusterHullsProps> = ({
     // Spatial clusters carry no semantic key; hullEntries colours them by rank.
     return { map: buildSpatialClusters(pts, SPATIAL_TARGET_CELLS), colorByKey };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [nodes, nodeIdToIndexMap, nodePositionsRef, tick, settings?.visualisation?.clusterHulls?.spatialFallback]);
+  }, [nodes, nodeIdToIndexMap, nodePositionsRef, tick, settings?.visualisation?.clusterHulls?.spatialFallback, settings?.visualisation?.clusterHulls?.communityFallback]);
 
   // ---- Build hull geometries from current positions ----
   const hullEntries = useMemo(() => {