Semantic topic clusters: local embeddings replace Louvain

Louvain only ever found the reasoning chains (the graph is disconnected
by nature — every connected component became its own cluster) and
edge-orphans could never join anything. Clusters are now RELATED TOPICS:
propositions grouped by meaning.

- Embedder (src/server/embeddings.ts): in-process transformers.js v4
  running EmbeddingGemma-300M q8 (MTEB 68.4, ~300MB one-time download),
  MRL-truncated to 512d, "title: none | text:" prefix on 100% of inputs,
  L2-normalized so cosine = dot. Model/dim mismatch voids the ledger
  (full re-embed). Injected at the composition root — the agent layer
  never imports the server layer (architecture law).
- Ledger (data/graph/embeddings.json): model + dim + vectors + the
  persisted cluster partition. Reclustering runs at the END of every
  embedding batch (post-merge hook, both front doors) — never per read
  (the agglomerative pass is ~1.5s at 338 nodes).
- Clustering (src/core/semantic-clusters.ts): hand-rolled average-linkage
  agglomerative over cosine (npm HDBSCAN is an abandoned alpha). Stragglers
  stay singletons by default; attachStragglers is the all-in toggle.
  Threshold 0.60 swept on the real graph: 26 topics, 74/90 edge-orphans
  land in real topics, 10 stragglers.
- Consumers (snapshot, settle, namer, replay) read the persisted
  partition — one cluster concept everywhere; core-survival label
  matching unchanged (20/26 topics kept labels).
- Louvain retired: detectCommunities + graphology* deps deleted
  (graphology-louvain had leaked into the client bundle since the
  clusters wave); scripts/bench-graph.ts (dead FA2 bench) removed.
- scripts/embed-graph.ts: backfill/cold-start (338 nodes in 150s
  including the one-time model download).

src/store/graph.ts

@@ -29,9 +29,10 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { LEDGER_FILES, POSITIONS_FILE, SOURCES_FILE } from "../../config.ts";
+import { EMBEDDINGS_FILE, LEDGER_FILES, POSITIONS_FILE, SOURCES_FILE } from "../../config.ts";
 import type {
 	ClusterLabeling,
+	EmbeddingsLedger,
 	GraphEdge,
 	GraphNode,
 	ExtractionRunUsage,
@@ -216,6 +217,12 @@ export const graphStore: GraphStore = {
 	writePositions(positions: Record<string, Position>): void {
 		writePositionMap(positions);
 	},
+	readEmbeddings(): EmbeddingsLedger {
+		return readEmbeddingsLedger();
+	},
+	writeEmbeddings(ledger: EmbeddingsLedger): void {
+		writeEmbeddingsLedger(ledger);
+	},
 };
 
 /** positions.json — { positions, updatedAt }. Read-modify-write, NOT
@@ -252,6 +259,57 @@ function writePositionMap(positions: Record<string, Position>): void {
 	);
 }
 
+/** embeddings.json — the whole EmbeddingsLedger at once. Missing/corrupt
+ *  file reads as an EMPTY ledger (model "") so consumers see "nothing
+ *  embedded yet" rather than an error; the embedder backfills. */
+function readEmbeddingsLedger(): EmbeddingsLedger {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(EMBEDDINGS_FILE, "utf-8");
+	} catch {
+		return { model: "", dim: 0, vectors: {}, clusters: [], updatedAt: "" };
+	}
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (!isRecord(parsed)) return { model: "", dim: 0, vectors: {}, clusters: [], updatedAt: "" };
+		const model = typeof parsed.model === "string" ? parsed.model : "";
+		const dim = typeof parsed.dim === "number" && Number.isFinite(parsed.dim) ? parsed.dim : 0;
+		const vectors: Record<string, number[]> = {};
+		if (isRecord(parsed.vectors)) {
+			for (const [id, value] of Object.entries(parsed.vectors)) {
+				if (
+					Array.isArray(value) &&
+					value.length > 0 &&
+					value.every((x) => typeof x === "number" && Number.isFinite(x))
+				) {
+					vectors[id] = value as number[];
+				}
+			}
+		}
+		const clusters: Array<{ members: string[] }> = [];
+		if (Array.isArray(parsed.clusters)) {
+			for (const c of parsed.clusters) {
+				if (
+					isRecord(c) &&
+					Array.isArray(c.members) &&
+					c.members.length > 0 &&
+					c.members.every((m) => typeof m === "string")
+				) {
+					clusters.push({ members: [...(c.members as string[])] });
+				}
+			}
+		}
+		return { model, dim, vectors, clusters, updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "" };
+	} catch {
+		return { model: "", dim: 0, vectors: {}, clusters: [], updatedAt: "" };
+	}
+}
+
+function writeEmbeddingsLedger(ledger: EmbeddingsLedger): void {
+	fs.mkdirSync(path.dirname(EMBEDDINGS_FILE), { recursive: true });
+	fs.writeFileSync(EMBEDDINGS_FILE, JSON.stringify(ledger, null, "\t"), "utf-8");
+}
+
 const isPosition = (v: unknown): v is Position =>
 	isRecord(v) && typeof v.x === "number" && Number.isFinite(v.x) && typeof v.y === "number" && Number.isFinite(v.y);