feat(ontology): GPU-resident semantic force system (PRD-018)

Turn OWL axioms into GPU physics forces so the 3D layout encodes ontology
semantics: SubClassOf/hasPart/partOf -> Attract, EquivalentClass/sameAs ->
Colocate, DisjointWith -> Separate. Whelk EL reasoner materialises inferred
axioms; mapper emits 18,933 live-kernel constraints dispatched to CUDA via the
reused ConstraintData[] buffer (ADR-098, zero SimParams ABI change). Deletes the
redundant ontology_constraints.cu kernel and unified_gpu_compute/ontology.rs.

Force boundaries tuned so the layout is legible rather than collapsed into one
blob: Colocate rest 2->10, SubClass rest 60->90, Disjoint min-dist 200->350,
Colocate weight 0.95->0.85. Global strength defaults to 0.6 with a reversible
constraint_buffer_base; the weights slider now re-scales the base (count
preserved) instead of clobbering the GPU buffer to 0.

Client: new Ontology Forces sub-tab (live readout, enable/disable, strength
slider -> PUT /ontology-physics/weights, Re-sync -> POST /admin/sync), inferred
edge rendering, SPARQL console, and System Status ontology rigour fields. Adds
canonical IRI resolver, vocab registry, SHACL gate, and SPARQL migrations.

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

Author: jjohare

Cargo.lock

@@ -8,6 +8,7 @@ import { useSettingsStore } from '../../../store/settingsStore'
 import { BinaryNodeData, getActualNodeId } from '../../../types/binaryProtocol'
 import { GemNodes, GemNodesHandle } from './GemNodes'
 import { GlassEdges, GlassEdgesHandle } from './GlassEdges'
+import { InferredEdges } from './InferredEdges'
 import { KnowledgeRings } from './KnowledgeRings'
 import { ClusterHulls } from './ClusterHulls'
 import { useGraphEventHandlers } from '../hooks/useGraphEventHandlers'
@@ -560,6 +561,14 @@ const GraphManager: React.FC<GraphManagerProps> = ({ onDragStateChange }) => {
         colorOverride={settings?.visualisation?.interaction?.selectionHighlightColor || '#00FFFF'}
       />
 
+      {/* Inferred-graph edges (urn:ngm:graph:ontology:inferred) rendered in a
+          distinct dashed-amber style, gated by the InferencePanel toggle.
+          Additive overlay — does not touch the GlassEdges instanced pipeline. */}
+      <InferredEdges
+        nodePositionsRef={nodePositionsRef}
+        nodeIdToIndexMap={nodeIdToIndexMap}
+      />
+
       <KnowledgeRings
         nodes={knowledgeNodes}
         perNodeVisualModeMap={perNodeVisualModeMap}

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

@@ -0,0 +1,132 @@
+/**
+ * InferredEdges — R3F overlay that renders edges from the inferred named graph
+ * (`urn:ngm:graph:ontology:inferred`) in a visually-distinct style: dashed,
+ * amber. Mirrors ontosphere's amber-dashed convention (PRD-018 WS-2, ADR-099 D4).
+ *
+ * Why a separate overlay (reuse-first, GPU-only-solving compliant):
+ *  - It does NOT modify the optimised GlassEdges instanced pipeline or the
+ *    GraphManager per-frame edge hot loop — zero risk to the asserted-edge path.
+ *  - It does NO solving/layout. It reads node positions from the SAB-backed
+ *    `nodePositionsRef` (the same buffer GlassEdges/labels read) and draws line
+ *    segments between the inferred (source → target) node pairs each frame.
+ *  - Gated by the `showInferred` toggle. Empty inferred set → renders nothing.
+ *
+ * Positions: `nodePositionsRef.current` is a Float32Array laid out [x,y,z] per
+ * node, indexed by the node's render index via `nodeIdToIndexMap`.
+ */
+
+import React, { useMemo, useRef, useEffect } from 'react';
+import { useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useInferredEdgesStore } from '../../ontology/store/useInferredEdgesStore';
+
+/** Default differentiated style — amber, dashed. Matches ADR-099 D4 convention. */
+const INFERRED_COLOR = 0xffb000; // amber
+const DASH_SIZE = 1.4;
+const GAP_SIZE = 0.9;
+const LINE_OPACITY = 0.85;
+
+interface InferredEdgesProps {
+  /** SAB-backed node positions, [x,y,z] per node, shared with GlassEdges. */
+  nodePositionsRef: React.MutableRefObject<Float32Array | null>;
+  /** Map from string node id to its index in the position buffer. */
+  nodeIdToIndexMap: Map<string, number>;
+}
+
+export const InferredEdges: React.FC<InferredEdgesProps> = ({
+  nodePositionsRef,
+  nodeIdToIndexMap,
+}) => {
+  const showInferred = useInferredEdgesStore((s) => s.showInferred);
+  const inferredEdges = useInferredEdgesStore((s) => s.inferredEdges);
+
+  // Resolve each inferred edge to a (srcIndex, tgtIndex) pair once per data
+  // change. Edges whose endpoints aren't in the current render set are dropped.
+  const resolved = useMemo(() => {
+    const pairs: Array<[number, number]> = [];
+    for (const e of inferredEdges) {
+      const si = nodeIdToIndexMap.get(String(e.sourceId));
+      const ti = nodeIdToIndexMap.get(String(e.targetId));
+      if (si !== undefined && ti !== undefined) pairs.push([si, ti]);
+    }
+    return pairs;
+  }, [inferredEdges, nodeIdToIndexMap]);
+
+  // Pre-allocated geometry sized to the resolved edge count (2 verts/edge).
+  const geometry = useMemo(() => {
+    const geo = new THREE.BufferGeometry();
+    const positions = new Float32Array(Math.max(resolved.length, 1) * 2 * 3);
+    geo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+    return geo;
+  }, [resolved.length]);
+
+  const material = useMemo(
+    () =>
+      new THREE.LineDashedMaterial({
+        color: INFERRED_COLOR,
+        dashSize: DASH_SIZE,
+        gapSize: GAP_SIZE,
+        transparent: true,
+        opacity: LINE_OPACITY,
+        depthWrite: false,
+      }),
+    [],
+  );
+
+  const linesRef = useRef<THREE.LineSegments | null>(null);
+
+  // Dispose GPU resources on unmount / geometry swap.
+  useEffect(() => {
+    return () => {
+      geometry.dispose();
+    };
+  }, [geometry]);
+  useEffect(() => {
+    return () => {
+      material.dispose();
+    };
+  }, [material]);
+
+  // Per-frame: pull current positions from the SAB and update the line buffer.
+  useFrame(() => {
+    if (!showInferred || resolved.length === 0) {
+      if (linesRef.current) linesRef.current.visible = false;
+      return;
+    }
+    const positions = nodePositionsRef.current;
+    if (!positions) return;
+
+    const attr = geometry.getAttribute('position') as THREE.BufferAttribute;
+    const arr = attr.array as Float32Array;
+    let w = 0;
+    for (let i = 0; i < resolved.length; i++) {
+      const [si, ti] = resolved[i];
+      const so = si * 3;
+      const to = ti * 3;
+      arr[w++] = positions[so];
+      arr[w++] = positions[so + 1];
+      arr[w++] = positions[so + 2];
+      arr[w++] = positions[to];
+      arr[w++] = positions[to + 1];
+      arr[w++] = positions[to + 2];
+    }
+    attr.needsUpdate = true;
+    geometry.setDrawRange(0, resolved.length * 2);
+    if (linesRef.current) {
+      linesRef.current.visible = true;
+      // Dashes require per-vertex line distances; recompute as positions move.
+      linesRef.current.computeLineDistances();
+    }
+  });
+
+  if (resolved.length === 0) return null;
+
+  return (
+    <lineSegments ref={linesRef} frustumCulled={false}>
+      <primitive object={geometry} attach="geometry" />
+      <primitive object={material} attach="material" />
+    </lineSegments>
+  );
+};
+
+export default InferredEdges;

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

@@ -9,6 +9,14 @@
  *  - nodeIdToIndexMap: O(1) lookup from string node ID to its index in graphData.nodes
  *  - filteredEdges: edges whose both endpoints survive filtering (same as graphData.edges
  *    today since edge filtering is position-based, but provided for future use)
+ *
+ * Population scope (PRD-018 WS-4): this hook filters by quality/authority/
+ * linked-page/degree — NOT by population type. Restricting the rendered graph to
+ * a single population (knowledge | ontology | agent) is done SERVER-SIDE via
+ * `graphDataManager.setGraphTypeFilter(...)` → `?graph_type=` so the whole graph
+ * is no longer transferred-then-filtered. The two layers are orthogonal: the
+ * server scopes *which population* is fetched; this hook scopes *which of those
+ * fetched nodes* pass quality/visibility thresholds.
  */
 
 import { useMemo, useEffect } from 'react';

client/src/features/graph/hooks/useGraphFiltering.ts

@@ -14,22 +14,47 @@ interface RawGraphResponse {
   settlementState?: { isSettled: boolean; stableFrameCount: number; kineticEnergy: number };
 }
 
+/**
+ * Server-side graph-type filter (PRD-018 WS-4). Sent as `?graph_type=` so the
+ * backend returns only the requested population instead of the whole graph
+ * (which the client then filtered locally — the transfer this eliminates).
+ * `null` / `'all'` → no filter param → server returns the full graph.
+ */
+export type GraphTypeFilter = 'knowledge' | 'ontology' | 'agent' | 'all' | null;
+
 /**
  * Fetch raw graph data from the backend REST API with up to `maxRetries`
  * attempts and exponential back-off.  Returns a validated `GraphData` object
  * with string-coerced node/edge IDs and enriched positions.
+ *
+ * @param graphType   Multi-graph identity (`logseq`/`visionclaw`) — diagnostic only.
+ * @param graphTypeFilter Server-side population filter → `?graph_type=`. When
+ *   `null`/`'all'` the whole graph is requested (back-compat default).
  */
-export async function fetchGraphData(graphType: string): Promise<GraphData> {
+export async function fetchGraphData(
+  graphType: string,
+  graphTypeFilter: GraphTypeFilter = null,
+): Promise<GraphData> {
   const maxRetries   = 3;
   const initialDelay = 500;
 
+  // Build the request URL: only append ?graph_type= for a concrete population.
+  const requestUrl =
+    graphTypeFilter && graphTypeFilter !== 'all'
+      ? `/graph/data?graph_type=${encodeURIComponent(graphTypeFilter)}`
+      : '/graph/data';
+
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     try {
       if (debugState.isEnabled()) {
-        logger.info(`Fetching initial ${graphType} graph data (attempt ${attempt}/${maxRetries})`);
+        logger.info(
+          `Fetching initial ${graphType} graph data` +
+            (graphTypeFilter && graphTypeFilter !== 'all' ? ` (graph_type=${graphTypeFilter})` : '') +
+            ` (attempt ${attempt}/${maxRetries})`,
+        );
       }
 
-      const response = await unifiedApiClient.get('/graph/data', { timeout: 10000 });
+      const response = await unifiedApiClient.get(requestUrl, { timeout: 10000 });
 
       const responseData: RawGraphResponse = response.data.data || response.data;
 
@@ -141,9 +166,14 @@ export function scheduleEmptyDataRetry(
   existingTimerRef: number | null,
   onSuccess: () => Promise<unknown>,
   onReschedule: (handle: number) => void,
+  graphTypeFilter: GraphTypeFilter = null,
 ): void {
   const MAX_ATTEMPTS = 20;
   const INTERVAL_MS  = 15_000;
+  const retryUrl =
+    graphTypeFilter && graphTypeFilter !== 'all'
+      ? `/graph/data?graph_type=${encodeURIComponent(graphTypeFilter)}`
+      : '/graph/data';
 
   if (attempt > MAX_ATTEMPTS) {
     logger.warn(`T6 empty-data retry: reached ${MAX_ATTEMPTS} attempts (${MAX_ATTEMPTS * INTERVAL_MS / 1000}s). Giving up.`);
@@ -157,18 +187,18 @@ export function scheduleEmptyDataRetry(
   const handle = window.setTimeout(async () => {
     console.info(`[GraphDataManager] T6 empty-data retry attempt ${attempt}/${MAX_ATTEMPTS}`);
     try {
-      const response = await unifiedApiClient.get('/graph/data', { timeout: 10000 });
+      const response = await unifiedApiClient.get(retryUrl, { timeout: 10000 });
       const responseData = response.data.data || response.data;
       const nodes = Array.isArray(responseData?.nodes) ? responseData.nodes : [];
       if (nodes.length > 0) {
         console.info(`[GraphDataManager] T6 empty-data retry: received ${nodes.length} nodes on attempt ${attempt}. Triggering full load.`);
         await onSuccess();
       } else {
-        scheduleEmptyDataRetry(attempt + 1, null, onSuccess, onReschedule);
+        scheduleEmptyDataRetry(attempt + 1, null, onSuccess, onReschedule, graphTypeFilter);
       }
     } catch (err) {
       logger.warn(`T6 empty-data retry attempt ${attempt} failed:`, createErrorMetadata(err));
-      scheduleEmptyDataRetry(attempt + 1, null, onSuccess, onReschedule);
+      scheduleEmptyDataRetry(attempt + 1, null, onSuccess, onReschedule, graphTypeFilter);
     }
   }, INTERVAL_MS) as unknown as number;
 

client/src/features/graph/managers/dataManager/restClient.ts

@@ -11,7 +11,7 @@ import { useWorkerErrorStore } from '../../../store/workerErrorStore';
 import { ensureNodeHasValidPosition, validateNodeMappings } from './dataManager/nodeUtils';
 import { buildNodeIdMaps, upsertNodeIdEntry, setDataAndNotify, topologyHash } from './dataManager/topology';
 import { ListenerRegistry } from './dataManager/listeners';
-import { fetchGraphData, scheduleEmptyDataRetry } from './dataManager/restClient';
+import { fetchGraphData, scheduleEmptyDataRetry, type GraphTypeFilter } from './dataManager/restClient';
 import { handleBinaryFrame, sendNodePositions as _sendNodePositions, enableBinaryUpdates as _enableBinaryUpdates } from './dataManager/wsClient';
 
 // Re-export types for backward compat
@@ -42,6 +42,8 @@ class GraphDataManager {
   // ── Worker / graph type ─────────────────────────────────────────────────
   private workerInitialized: boolean = false;
   private graphType: 'logseq' | 'visionclaw' = 'logseq';
+  // Server-side population filter (PRD-018 WS-4). null/'all' = whole graph.
+  private graphTypeFilter: GraphTypeFilter = null;
   private workerUnsubscribers: Array<() => void> = [];
 
   // ── User interaction state ──────────────────────────────────────────────
@@ -166,10 +168,24 @@ class GraphDataManager {
     return this.graphType;
   }
 
+  /**
+   * Set the server-side population filter (PRD-018 WS-4). When set to a concrete
+   * population the next `fetchInitialData` sends `?graph_type=` so only that
+   * subset is transferred instead of the whole graph. `null`/`'all'` clears it.
+   */
+  public setGraphTypeFilter(filter: GraphTypeFilter): void {
+    this.graphTypeFilter = filter;
+    if (debugState.isEnabled()) logger.info(`Graph type filter set to: ${filter ?? 'all'}`);
+  }
+
+  public getGraphTypeFilter(): GraphTypeFilter {
+    return this.graphTypeFilter;
+  }
+
   // ── REST data fetch ───────────────────────────────────────────────────
 
   public async fetchInitialData(): Promise<GraphData> {
-    const validatedData = await fetchGraphData(this.graphType);
+    const validatedData = await fetchGraphData(this.graphType, this.graphTypeFilter);
 
     await this.setGraphData(validatedData);
 
@@ -183,6 +199,7 @@ class GraphDataManager {
         this.retryTimeout,
         () => this.fetchInitialData(),
         handle => { this.retryTimeout = handle; },
+        this.graphTypeFilter,
       );
     }