@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/src/knowledge/stores/localSnapshotStore.ts

@@ -0,0 +1,159 @@
+/**
+ * knowledge/stores/localSnapshotStore.ts — a {@link KnowledgeStore} over one JSON snapshot,
+ * for a folder not linked to a project (PRD 38 §4.2, §5.1).
+ *
+ * Persistence is a port (`read`/`write` of the whole snapshot string), so this module has
+ * no `fs`: the memory MCP host persists it beside its own snapshot through its shared JSON
+ * file, a browser host in IndexedDB. Upserts use the platform's unique keys — a fact by
+ * `key`, a relation by `(from, to, kind)`, a scope by `rootId` — so linking a folder later
+ * uploads the same rows idempotently. The snapshot is written canonically (sorted), so
+ * equal content is equal bytes.
+ */
+
+import type {
+    Extracted, KnowledgeStore, NodeRef, Scope, ScopeRecord, StoredFact, StoredRelation,
+} from '../model.js';
+import { canonicalJson, compareStr, pathOfRef } from '../refs.js';
+
+export interface SnapshotPersistence {
+    read(): Promise<string | undefined>;
+    write(snapshot: string): Promise<void>;
+}
+
+export interface KnowledgeSnapshot {
+    version: 1;
+    scopes: ScopeRecord[];
+    facts: Record<string, StoredFact[]>;
+    relations: Record<string, StoredRelation[]>;
+    extracted: Record<string, Extracted[]>;
+}
+
+export interface LocalSnapshotStoreOptions {
+    /** ISO clock for `staleAt`. Default `new Date().toISOString()`. */
+    now?(): string;
+}
+
+const relKey = (r: Pick<StoredRelation, 'from' | 'to' | 'kind'>) => `${r.from}\u0000${r.to}\u0000${r.kind}`;
+
+function empty(): KnowledgeSnapshot {
+    return { version: 1, scopes: [], facts: {}, relations: {}, extracted: {} };
+}
+
+function parse(text: string | undefined): KnowledgeSnapshot {
+    if (!text) return empty();
+    try {
+        const s = JSON.parse(text) as Partial<KnowledgeSnapshot>;
+        return {
+            version: 1,
+            scopes: Array.isArray(s.scopes) ? s.scopes : [],
+            facts: s.facts && typeof s.facts === 'object' ? s.facts : {},
+            relations: s.relations && typeof s.relations === 'object' ? s.relations : {},
+            extracted: s.extracted && typeof s.extracted === 'object' ? s.extracted : {},
+        };
+    } catch {
+        // A corrupt snapshot is rebuilt by the next review rather than failing every read.
+        return empty();
+    }
+}
+
+export class LocalSnapshotStore implements KnowledgeStore {
+    private snapshot: KnowledgeSnapshot | undefined;
+    /** Serializes mutations so two writers never interleave a read-modify-write. */
+    private queue: Promise<unknown> = Promise.resolve();
+    private readonly now: () => string;
+
+    constructor(private readonly persistence: SnapshotPersistence, opts: LocalSnapshotStoreOptions = {}) {
+        this.now = opts.now ?? (() => new Date().toISOString());
+    }
+
+    private async load(): Promise<KnowledgeSnapshot> {
+        if (!this.snapshot) this.snapshot = parse(await this.persistence.read());
+        return this.snapshot;
+    }
+
+    private mutate(fn: (s: KnowledgeSnapshot) => void): Promise<void> {
+        const run = this.queue.then(async () => {
+            const s = await this.load();
+            fn(s);
+            await this.persistence.write(serialize(s));
+        });
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+
+    async scopes(): Promise<ScopeRecord[]> {
+        await this.queue;
+        return [...(await this.load()).scopes];
+    }
+
+    async facts(scope: Scope): Promise<StoredFact[]> {
+        await this.queue;
+        return [...((await this.load()).facts[scope.rootId] ?? [])];
+    }
+
+    async relations(scope: Scope): Promise<StoredRelation[]> {
+        await this.queue;
+        return [...((await this.load()).relations[scope.rootId] ?? [])];
+    }
+
+    write(batch: { scope: ScopeRecord; facts: StoredFact[]; relations: StoredRelation[] }): Promise<void> {
+        const bad = [...batch.facts, ...batch.relations].find((x) => (x.origin as string) === 'extracted');
+        if (bad) return Promise.reject(new Error('knowledge: extracted output is never stored'));
+        return this.mutate((s) => {
+            const rootId = batch.scope.rootId;
+            const prior = s.scopes.find((x) => x.rootId === rootId);
+            const merged: ScopeRecord = { ...(prior ?? {}), ...stripUndefined(batch.scope) } as ScopeRecord;
+            s.scopes = [...s.scopes.filter((x) => x.rootId !== rootId), merged];
+
+            const facts = new Map((s.facts[rootId] ?? []).map((f) => [f.key, f] as const));
+            for (const f of batch.facts) facts.set(f.key, { ...f });
+            s.facts[rootId] = [...facts.values()];
+
+            const relations = new Map((s.relations[rootId] ?? []).map((r) => [relKey(r), r] as const));
+            for (const r of batch.relations) relations.set(relKey(r), { ...r });
+            s.relations[rootId] = [...relations.values()];
+        });
+    }
+
+    markStale(scope: Scope, sourceRef: NodeRef, currentHash: string): Promise<void> {
+        const path = pathOfRef(sourceRef);
+        return this.mutate((s) => {
+            const at = this.now();
+            const onSource = (ref: NodeRef) => path !== undefined && pathOfRef(ref) === path;
+            s.relations[scope.rootId] = (s.relations[scope.rootId] ?? []).map((r) =>
+                r.origin === 'model' && !r.staleAt && r.sourceHash !== currentHash && (onSource(r.from) || onSource(r.to))
+                    ? { ...r, staleAt: at }
+                    : r);
+        });
+    }
+
+    async getExtracted(hash: string): Promise<Extracted[] | undefined> {
+        await this.queue;
+        return (await this.load()).extracted[hash];
+    }
+
+    putExtracted(hash: string, extracted: Extracted[]): Promise<void> {
+        return this.mutate((s) => { s.extracted[hash] = extracted; });
+    }
+}
+
+export function localSnapshotStore(persistence: SnapshotPersistence, opts?: LocalSnapshotStoreOptions): LocalSnapshotStore {
+    return new LocalSnapshotStore(persistence, opts);
+}
+
+function stripUndefined<T extends object>(o: T): Partial<T> {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>;
+}
+
+/** Canonical: scopes by rootId, facts by key, relations by (from, to, kind), keys sorted. */
+function serialize(s: KnowledgeSnapshot): string {
+    const sortRecord = <T>(rec: Record<string, T[]>, by: (a: T, b: T) => number) =>
+        Object.fromEntries(Object.keys(rec).sort(compareStr).map((k) => [k, [...rec[k]!].sort(by)]));
+    return canonicalJson({
+        version: 1,
+        scopes: [...s.scopes].sort((a, b) => compareStr(a.rootId, b.rootId)),
+        facts: sortRecord(s.facts, (a, b) => compareStr(a.key, b.key)),
+        relations: sortRecord(s.relations, (a, b) => compareStr(relKey(a), relKey(b))),
+        extracted: s.extracted,
+    });
+}

package/src/knowledge/testkit.test-util.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared fixtures for the knowledge tests: an in-memory DirectorySource that records its
+ * reads, an in-memory snapshot persistence, a fake JudgementPort and node/edge builders.
+ */
+
+import { hashText } from '../ingest/hash.js';
+import type {
+    DirectorySource, Extracted, JudgementPort, JudgementRequest, JudgementResult, KEdge, KNode, NodeRef,
+} from './model.js';
+import { LocalSnapshotStore, type SnapshotPersistence } from './stores/localSnapshotStore.js';
+import { srcRef } from './refs.js';
+
+export const ROOT = 'r';
+
+export interface SpySource extends DirectorySource {
+    files: Record<string, string>;
+    reads: string[];
+}
+
+export function memSource(files: Record<string, string>, rootId = ROOT): SpySource {
+    const src: SpySource = {
+        rootId, title: 'Fixture', files, reads: [],
+        async *list() {
+            for (const path of Object.keys(src.files)) {
+                const text = src.files[path]!;
+                yield { path, hash: hashText(text), size: text.length };
+            }
+        },
+        async read(path: string) {
+            src.reads.push(path);
+            return { id: path, tenantId: 't', content: { kind: 'text', text: src.files[path]! } };
+        },
+    };
+    return src;
+}
+
+export function memPersistence(): SnapshotPersistence & { value?: string } {
+    const p: SnapshotPersistence & { value?: string } = {
+        async read() { return p.value; },
+        async write(s: string) { p.value = s; },
+    };
+    return p;
+}
+
+export function memStore(): LocalSnapshotStore {
+    return new LocalSnapshotStore(memPersistence(), { now: () => '2026-10-28T00:00:00.000Z' });
+}
+
+/** Answers every extract with one claim + one entity, every compare with `contradicts`. */
+export function fakeJudge(
+    shape: (req: JudgementRequest) => JudgementResult = defaultJudgement,
+): JudgementPort & { requests: JudgementRequest[] } {
+    const port = {
+        requests: [] as JudgementRequest[],
+        async judge(req: JudgementRequest) {
+            port.requests.push(req);
+            return shape(req);
+        },
+    };
+    return port;
+}
+
+function defaultJudgement(req: JudgementRequest): JudgementResult {
+    if (req.kind === 'compare') {
+        return { compare: [{ a: req.items[0]!.ref, b: req.items[1]!.ref, relation: 'contradicts', confidence: 0.9 }], invalid: 0 };
+    }
+    return {
+        extract: req.items.map((it) => ({
+            ref: it.ref,
+            claims: [{ subject: 'Lease', predicate: 'ends', object: it.text.split(/\s+/)[0] ?? 'x', quote: it.text.slice(0, 20) }],
+            entities: [{ name: 'Lease', type: 'contract' }],
+        })),
+        invalid: 0,
+    };
+}
+
+export function fileNode(path: string, extra: Partial<KNode> = {}): KNode {
+    return {
+        ref: srcRef(ROOT, path), kind: 'file', label: path, pack: 'docs', importance: 0, origin: 'extracted',
+        sourceHash: `h:${path}`, ...extra,
+    };
+}
+
+export function edge(from: string, to: string, kind = 'links', extra: Partial<KEdge> = {}): KEdge {
+    return { from: srcRef(ROOT, from), to: srcRef(ROOT, to), kind, weight: 1, origin: 'extracted', ...extra };
+}
+
+export function extractedOf(node: KNode, edges: KEdge[] = []): Extracted {
+    return { sourceRef: node.ref, sourceHash: node.sourceHash ?? '', nodes: [node], edges, keys: [] };
+}
+
+export const ref = (path: string): NodeRef => srcRef(ROOT, path);

package/src/knowledge/trace.test.ts

@@ -0,0 +1,91 @@
+/**
+ * src/knowledge/trace.test.ts
+ * traceGraph's order (weight, then ref; each node once; back/cycle steps) and the Mermaid
+ * sequence diagram drawn from it.
+ */
+
+import { toMermaid, traceGraph } from './trace.js';
+import type { KnowledgeGraph, NodeRef, PartitionRegistry } from './model.js';
+import { edge, fileNode, ref, ROOT } from './testkit.test-util.js';
+
+const REG: PartitionRegistry = {
+    partitions: [
+        { id: 'presentation', order: 0, match: ['ui/**'] },
+        { id: 'application', order: 1, match: ['app/**'] },
+        { id: 'domain', order: 2, match: ['dom/**'] },
+        { id: 'infrastructure', order: 3, match: ['infra/**'] },
+    ],
+    allow: {},
+};
+
+const graph: KnowledgeGraph = {
+    scope: { rootId: ROOT, packs: ['code'], digest: 'd' },
+    nodes: [
+        fileNode('ui/A.ts', { partition: 'presentation' }),
+        fileNode('app/B.ts', { partition: 'application' }),
+        fileNode('dom/C.ts', { partition: 'domain' }),
+        fileNode('infra/D.ts', { partition: 'infrastructure' }),
+    ],
+    edges: [
+        edge('ui/A.ts', 'dom/C.ts', 'references'),
+        edge('ui/A.ts', 'app/B.ts', 'references', { weight: 2 }),
+        edge('app/B.ts', 'infra/D.ts', 'references', { verdict: 'skips' }),
+        edge('app/B.ts', 'dom/C.ts', 'references'),
+        edge('dom/C.ts', 'ui/A.ts', 'references', { cycle: true }),
+        edge('ui/A.ts', 'infra/D.ts', 'contains'),
+    ],
+    findings: [],
+    stats: { sources: 4, nodes: 4, edges: 6, stale: 0, truncated: false },
+};
+
+const name = (r: NodeRef) => r.slice(r.lastIndexOf('/') + 1, -3);
+
+describe('traceGraph', () => {
+    const t = traceGraph(graph, ref('ui/A.ts'), { edgeKinds: ['references'], registry: REG });
+
+    it('walks heaviest edge first, then by ref; each node once; marks back and cycle steps', () => {
+        expect(t.steps.map((s) => `${name(s.from)}>${name(s.to)}@${s.depth}${s.back ? ' back' : ''}${s.cycle ? ' cycle' : ''}`)).toEqual([
+            'A>B@1',
+            'B>C@2',
+            'C>A@3 back cycle',
+            'B>D@2',
+            'A>C@1 back',
+        ]);
+        expect(t.truncated).toBe(false);
+    });
+
+    it('orders lanes by partition order', () => {
+        expect(t.lanes).toEqual(['presentation', 'application', 'domain', 'infrastructure']);
+    });
+
+    it('is stable across edge order', () => {
+        const shuffled = { ...graph, edges: [...graph.edges].reverse() };
+        expect(traceGraph(shuffled, ref('ui/A.ts'), { edgeKinds: ['references'], registry: REG })).toEqual(t);
+    });
+
+    it('stops at maxSteps and maxDepth', () => {
+        expect(traceGraph(graph, ref('ui/A.ts'), { edgeKinds: ['references'], maxSteps: 2 })).toMatchObject({ truncated: true });
+        const shallow = traceGraph(graph, ref('ui/A.ts'), { edgeKinds: ['references'], maxDepth: 1 });
+        expect(shallow.steps.every((s) => s.depth === 1)).toBe(true);
+        expect(shallow.truncated).toBe(true);
+    });
+});
+
+describe('toMermaid', () => {
+    it('draws lanes as participants and steps as messages', () => {
+        const t = traceGraph(graph, ref('ui/A.ts'), { edgeKinds: ['references'], registry: REG });
+        expect(toMermaid(t, name)).toBe([
+            'sequenceDiagram',
+            '    participant P0 as presentation',
+            '    participant P1 as application',
+            '    participant P2 as domain',
+            '    participant P3 as infrastructure',
+            '    P0->>P1: A references B',
+            '    P1->>P2: B references C',
+            '    P2-->>P0: C references A [cycle]',
+            '    P1->>P3: B references D [skips]',
+            '    P0-->>P2: A references C',
+            '',
+        ].join('\n'));
+    });
+});

package/src/knowledge/trace.ts

@@ -0,0 +1,111 @@
+/**
+ * knowledge/trace.ts — "how does this reach that" (PRD 38 §3.4).
+ *
+ * `traceGraph` walks the chosen edge kinds depth-first from one node: heaviest edge first,
+ * then by target ref; each node is entered once; reaching a visited node is a `back` step
+ * (also `cycle` when the edge carries the cycle flag). Lanes are the partitions the trace
+ * touches — code layers or doc folders — and `toMermaid` draws them as a sequence diagram.
+ */
+
+import type { KEdge, KnowledgeGraph, NodeRef, PartitionRegistry, Trace, TraceStep } from './model.js';
+import { partitionOrder } from './partitions.js';
+import { compareStr } from './refs.js';
+
+export const DEFAULT_TRACE_EDGE_KINDS: readonly string[] = ['references', 'links', 'mentions'];
+export const DEFAULT_TRACE_DEPTH = 4;
+export const DEFAULT_TRACE_STEPS = 60;
+/** The lane of a node with no partition. */
+export const UNPARTITIONED_LANE = '(none)';
+
+/** A trace that also knows each ref's lane (what {@link toMermaid} draws participants from). */
+export interface LanedTrace extends Trace {
+    laneOf: Record<string, string>;
+}
+
+export interface TraceOptions {
+    edgeKinds?: string[];
+    maxDepth?: number;
+    maxSteps?: number;
+    /** Orders lanes by partition order; without it lanes keep first-visit order. */
+    registry?: PartitionRegistry;
+}
+
+export function traceGraph(g: KnowledgeGraph, from: NodeRef, opts: TraceOptions = {}): LanedTrace {
+    const kinds = new Set(opts.edgeKinds ?? DEFAULT_TRACE_EDGE_KINDS);
+    const maxDepth = opts.maxDepth ?? DEFAULT_TRACE_DEPTH;
+    const maxSteps = opts.maxSteps ?? DEFAULT_TRACE_STEPS;
+    const partition = new Map(g.nodes.map((n) => [n.ref, n.partition] as const));
+    const out = new Map<NodeRef, KEdge[]>();
+    for (const e of g.edges) {
+        if (!kinds.has(e.kind)) continue;
+        const list = out.get(e.from) ?? [];
+        list.push(e);
+        out.set(e.from, list);
+    }
+    for (const list of out.values()) {
+        list.sort((a, b) => b.weight - a.weight || compareStr(a.to, b.to) || compareStr(a.kind, b.kind));
+    }
+
+    const steps: TraceStep[] = [];
+    const visited = new Set<NodeRef>([from]);
+    let truncated = false;
+    const walk = (node: NodeRef, depth: number): void => {
+        for (const e of out.get(node) ?? []) {
+            if (steps.length >= maxSteps) { truncated = true; return; }
+            const back = visited.has(e.to);
+            steps.push({
+                from: e.from, to: e.to, depth: depth + 1, kind: e.kind,
+                ...(e.verdict ? { verdict: e.verdict } : {}),
+                ...(back && e.cycle ? { cycle: true } : {}),
+                ...(back ? { back: true } : {}),
+            });
+            if (back) continue;
+            visited.add(e.to);
+            if (depth + 1 < maxDepth) walk(e.to, depth + 1);
+            else if ((out.get(e.to) ?? []).length > 0) truncated = true;
+        }
+    };
+    if (partition.has(from)) walk(from, 0);
+
+    const laneOf: Record<string, string> = {};
+    const lanes: string[] = [];
+    for (const ref of [from, ...steps.flatMap((s) => [s.from, s.to])]) {
+        if (ref in laneOf) continue;
+        const lane = partition.get(ref) ?? UNPARTITIONED_LANE;
+        laneOf[ref] = lane;
+        if (!lanes.includes(lane)) lanes.push(lane);
+    }
+    if (opts.registry) {
+        const reg = opts.registry;
+        const order = (l: string) => partitionOrder(l, reg) ?? Number.MAX_SAFE_INTEGER;
+        lanes.sort((a, b) => order(a) - order(b) || compareStr(a, b));
+    }
+    return { from, lanes, steps, truncated, laneOf };
+}
+
+/** Mermaid text is line- and statement-delimited; keep labels on one safe line. */
+function safe(text: string): string {
+    return text.replace(/[\r\n]+/g, ' ').replace(/[;#:]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * A `sequenceDiagram`: lanes are participants, steps are messages. A back step is dashed;
+ * an upward/skipping step and a cycle are named in the message.
+ */
+export function toMermaid(t: Trace, label: (r: NodeRef) => string): string {
+    const laned = (t as Partial<LanedTrace>).laneOf;
+    // Without lanes every node is its own participant.
+    const laneOf = (ref: NodeRef): string => laned?.[ref] ?? ref;
+    const lanes = laned ? t.lanes : [...new Set([t.from, ...t.steps.flatMap((s) => [s.from, s.to])])];
+    const id = new Map(lanes.map((l, i) => [l, `P${i}`] as const));
+    const lines = ['sequenceDiagram'];
+    for (const lane of lanes) lines.push(`    participant ${id.get(lane)} as ${safe(laned ? lane : label(lane as NodeRef))}`);
+    for (const s of t.steps) {
+        const arrow = s.back ? '-->>' : '->>';
+        const notes = [s.verdict === 'upward' || s.verdict === 'skips' ? s.verdict : '', s.cycle ? 'cycle' : '']
+            .filter(Boolean).map((n) => ` [${n}]`).join('');
+        const text = safe(`${label(s.from)} ${s.kind} ${label(s.to)}`) + notes;
+        lines.push(`    ${id.get(laneOf(s.from))}${arrow}${id.get(laneOf(s.to))}: ${text}`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/src/knowledge/truncate.ts

@@ -0,0 +1,118 @@
+/**
+ * knowledge/truncate.ts — the graph opens bounded (PRD 38 §5.3).
+ *
+ * Always kept: focus nodes, every node named by a finding, changed nodes, and the 1-hop
+ * neighbours of all of those (up to the hard cap). The rest of the budget goes by
+ * importance (then ref). Everything else folds into `area` nodes; edges are re-pointed to
+ * the areas, merged, and self-loops dropped.
+ */
+
+import type { EdgeVerdict, KEdge, KNode, KnowledgeGraph, NodeRef } from './model.js';
+import { areaImportance, byImportance } from './importance.js';
+import { compareStr, pathOfRef, srcRef } from './refs.js';
+
+/** Hard cap on nodes, however many the keep rules ask for. */
+export const TRUNCATION_HARD_CAP = 2000;
+/** The area of folded nodes that are not under any source path (unanchored facts). */
+export const UNANCHORED_AREA = '(memory)';
+
+const VERDICT_RANK: Record<EdgeVerdict, number> = { same: 0, allowed: 1, skips: 2, upward: 3 };
+
+export interface TruncateOptions {
+    maxNodes: number;
+    focus: readonly NodeRef[];
+    changed: readonly NodeRef[];
+}
+
+export function truncateGraph(g: KnowledgeGraph, opts: TruncateOptions): { nodes: KNode[]; edges: KEdge[]; truncated: boolean } {
+    if (g.nodes.length <= opts.maxNodes) return { nodes: g.nodes, edges: g.edges, truncated: false };
+    const byRef = new Map(g.nodes.map((n) => [n.ref, n] as const));
+    const neighbours = new Map<NodeRef, Set<NodeRef>>();
+    const link = (a: NodeRef, b: NodeRef) => {
+        let s = neighbours.get(a);
+        if (!s) neighbours.set(a, (s = new Set()));
+        s.add(b);
+    };
+    for (const e of g.edges) { link(e.from, e.to); link(e.to, e.from); }
+
+    const kept: NodeRef[] = [];
+    const keptSet = new Set<NodeRef>();
+    const keep = (ref: NodeRef) => {
+        if (keptSet.has(ref) || !byRef.has(ref) || kept.length >= TRUNCATION_HARD_CAP) return;
+        keptSet.add(ref);
+        kept.push(ref);
+    };
+    const findingRefs = [...g.findings].sort((a, b) => compareStr(a.id, b.id)).flatMap((f) => f.nodes);
+    const seeds = [...[...opts.focus].sort(compareStr), ...findingRefs, ...[...opts.changed].sort(compareStr)];
+    for (const s of seeds) keep(s);
+    const seeded = [...kept];
+    for (const s of seeded) {
+        const around = [...(neighbours.get(s) ?? [])].map((r) => byRef.get(r)!).filter(Boolean).sort(byImportance);
+        for (const n of around) keep(n.ref);
+    }
+    for (const n of [...g.nodes].sort(byImportance)) {
+        if (kept.length >= opts.maxNodes) break;
+        keep(n.ref);
+    }
+
+    // Fold the rest into areas.
+    const aboutTarget = new Map<NodeRef, NodeRef>();
+    for (const e of g.edges) if (e.kind === 'about' && !aboutTarget.has(e.from)) aboutTarget.set(e.from, e.to);
+    const rootId = g.scope.rootId;
+    const areaOf = (n: KNode): NodeRef => {
+        if (n.area) return n.area;
+        const target = aboutTarget.get(n.ref);
+        const area = target && byRef.get(target)?.area;
+        return area ?? (pathOfRef(n.ref) !== undefined ? n.ref : srcRef(rootId, UNANCHORED_AREA));
+    };
+    const fold = new Map<NodeRef, NodeRef>();
+    const members = new Map<NodeRef, KNode[]>();
+    for (const n of g.nodes) {
+        if (keptSet.has(n.ref)) continue;
+        const area = areaOf(n);
+        fold.set(n.ref, area);
+        let m = members.get(area);
+        if (!m) members.set(area, (m = []));
+        m.push(n);
+    }
+    const imp = areaImportance(new Map([...members].map(([a, ms]) => [a, ms.map((n) => n.importance)] as const)));
+    const areaNodes: KNode[] = [...members.keys()].filter((a) => !keptSet.has(a)).map((area) => {
+        const ms = members.get(area)!;
+        const partition = mostCommon(ms.map((n) => n.partition));
+        return {
+            ref: area, kind: 'area', label: pathOfRef(area) ?? area, pack: mostCommon(ms.map((n) => n.pack)) ?? 'memory',
+            ...(partition !== undefined ? { partition } : {}),
+            importance: imp.get(area) ?? 0, origin: 'extracted' as const,
+            badges: { members: ms.length },
+        };
+    });
+
+    const edges = new Map<string, KEdge>();
+    for (const e of g.edges) {
+        const from = fold.get(e.from) ?? e.from, to = fold.get(e.to) ?? e.to;
+        if (from === to) continue;
+        const id = `${from}\u0000${to}\u0000${e.kind}`;
+        const prior = edges.get(id);
+        if (!prior) { edges.set(id, { ...e, from, to }); continue; }
+        prior.weight += e.weight;
+        if (e.cycle) prior.cycle = true;
+        if (e.confidence !== undefined) prior.confidence = Math.max(prior.confidence ?? 0, e.confidence);
+        if (e.verdict && (!prior.verdict || VERDICT_RANK[e.verdict] > VERDICT_RANK[prior.verdict])) prior.verdict = e.verdict;
+    }
+    const nodes = [...g.nodes.filter((n) => keptSet.has(n.ref)), ...areaNodes].sort((a, b) => compareStr(a.ref, b.ref));
+    const outEdges = [...edges.values()]
+        .map((e) => ({ ...e, weight: Math.round(e.weight * 1e6) / 1e6 }))
+        .sort((a, b) => compareStr(a.from, b.from) || compareStr(a.to, b.to) || compareStr(a.kind, b.kind));
+    return { nodes, edges: outEdges, truncated: true };
+}
+
+/** The most frequent defined value; ties go to the smallest. */
+function mostCommon(values: ReadonlyArray<string | undefined>): string | undefined {
+    const counts = new Map<string, number>();
+    for (const v of values) if (v !== undefined) counts.set(v, (counts.get(v) ?? 0) + 1);
+    let best: string | undefined;
+    for (const [v, c] of [...counts].sort((a, b) => compareStr(a[0], b[0]))) {
+        if (best === undefined || c > counts.get(best)!) best = v;
+    }
+    return best;
+}

package/src/memory/SemanticRecall.ts

@@ -14,6 +14,7 @@
 
 import { tokenize, jaccardSimilarity } from '../similarity/index.js';
 import { hybridRetrieve, denseSearch, HnswIndex, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
+import { compareScoreThenId } from '../retrieval/order.js';
 import type { MemoryEntry, RankedRecall, ScoredMemory, SSMRuntimeRef } from './types.js';
 
 export interface SemanticRecallOptions {
@@ -80,7 +81,8 @@ export class SemanticRecall {
         }
         const queryTokens = new Set(tokenize(query));
         const scored = all.map((entry) => ({ entry, score: jaccardSimilarity(queryTokens, new Set(tokenize(entry.content))) }));
-        scored.sort((a, b) => b.score - a.score);
+        // Jaccard is an exact ratio: the lexical quantum, then the fact key.
+        scored.sort((a, b) => compareScoreThenId(a.score, a.entry.key, b.score, b.entry.key));
         return this._floor(scored).slice(0, topK);
     }
 

package/src/retrieval/HybridRetriever.ts

@@ -22,6 +22,7 @@ import { mmrSelect } from './mmr.js';
 import { denseSearch } from './hnsw.js';
 import { calculateTemporalDecayMultiplier } from './decay.js';
 import { cosineSimilarity } from '../similarity/index.js';
+import { compareHits } from './order.js';
 
 export interface RetrievalCandidate {
     id: string;
@@ -146,7 +147,7 @@ export function hybridRetrieve(
     const factor = new Map(fused.map(f => [f.id, signalFactor(byId.get(f.id)!, opts, now)]));
     const weighted = fused
         .map(f => ({ id: f.id, score: f.score * factor.get(f.id)! }))
-        .sort((a, b) => b.score - a.score);
+        .sort(compareHits);
 
     // ── Rerank (MMR over the weighted top, using whatever vectors we have) ────
     const rerank = opts.rerank ?? true;
@@ -166,6 +167,7 @@ export function hybridRetrieve(
                 similarity: (a, b) => cosineSimilarity(a.vector, b.vector),
                 lambda: opts.mmrLambda ?? 0.7,
                 topK,
+                idOf: (c) => c.id,
             }).map(c => c.id);
             // MMR only ranks the vectored subset; append any remaining ids after.
             const seen = new Set(reranked);

package/src/retrieval/bm25.ts

@@ -23,6 +23,7 @@
  */
 
 import { tokenize } from '../similarity/index.js';
+import { compareHits } from './order.js';
 
 /** Splits text into the terms BM25 scores over. */
 export type Bm25Tokenizer = (text: string) => string[];
@@ -91,8 +92,9 @@ export function bm25TermScore(frequency: number, idf: number, lengthNorm: number
 }
 
 /**
- * Scores every document against `query` with Okapi BM25, returning hits sorted by
- * descending score (documents with no query-term overlap score 0 and are dropped).
+ * Scores every document against `query` with Okapi BM25, returning hits in
+ * {@link compareHits} order — score descending, then id (documents with no
+ * query-term overlap score 0 and are dropped).
  * Builds the index inline — for a recall over a bounded candidate set (the memory
  * store / a vector pre-filter) this is O(N·terms) and needs no persistence.
  */
@@ -136,6 +138,6 @@ export function bm25Search(query: string, docs: Bm25Doc[], opts: Bm25Options = {
         if (score > 0) hits.push({ id: d.id, score });
     }
 
-    hits.sort((a, b) => b.score - a.score);
+    hits.sort(compareHits);
     return hits;
 }

package/src/retrieval/fusion.ts

@@ -8,6 +8,8 @@
  * Pure and zero-dependency.
  */
 
+import { compareHits } from './order.js';
+
 export interface RankedList {
     /** Ordered ids, most relevant first. */
     ids: string[];
@@ -35,7 +37,8 @@ export function rrfTerm(rank: number, k: number = RRF_DEFAULT_K): number {
 /**
  * Reciprocal Rank Fusion over any number of ranked lists.
  * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
- * contribution of low-ranked items; the canonical TREC value.
+ * contribution of low-ranked items; the canonical TREC value. Ordered by
+ * {@link compareHits}: fused score descending, then id.
  */
 export function reciprocalRankFusion(lists: RankedList[], k = RRF_DEFAULT_K): FusedHit[] {
     const acc = new Map<string, number>();
@@ -47,5 +50,5 @@ export function reciprocalRankFusion(lists: RankedList[], k = RRF_DEFAULT_K): Fu
     }
     return [...acc.entries()]
         .map(([id, score]) => ({ id, score }))
-        .sort((a, b) => b.score - a.score);
+        .sort(compareHits);
 }