@seanhogg/builderforce-memory 2026.10.27 → 2026.10.29

package/src/knowledge/build.ts

@@ -0,0 +1,266 @@
+/**
+ * knowledge/build.ts — `buildGraph`: join perception (extracted, computed) with memory
+ * (stored facts and relations) into one bounded {@link KnowledgeGraph} (PRD 38 §4.1).
+ *
+ *   1. extracted nodes/edges (analyzer output merges its badges into the same refs);
+ *   2. facts become nodes, joined to sources by `fileAnchors.path`; a model fact whose
+ *      anchor hash differs from the source's current hash is `stale`;
+ *   3. stored relations become edges; near-duplicate pairs become `near-duplicate` edges
+ *      (an exact `duplicate` between the same pair wins); live changes badge nodes and
+ *      `runFiles` become `co-changed` edges;
+ *   4. partitions, areas, verdicts; PageRank importance; findings; then truncation.
+ *
+ * Deterministic: equal input ⇒ byte-identical JSON. Every list is sorted, every sort ends
+ * on ref, objects are built with a fixed key order.
+ */
+
+import { areaOfPath } from '../working/codemapAreas.js';
+import { sha256Hex } from '../retrieval/knowledge-index/sha256.js';
+import type {
+    BuildGraphInput, BuildGraphOptions, Extracted, KEdge, KNode, KnowledgeGraph, NodeRef,
+    PartitionRegistry, StoredFact,
+} from './model.js';
+import { computeFindings } from './findings.js';
+import { pageRank } from './importance.js';
+import { loadPartitions, partitionOf, verdictOf } from './partitions.js';
+import { entityName } from './resolve.js';
+import {
+    basenameOf, canonicalJson, compareStr, factRef, pathOfRef, round6, sortBy, srcRef,
+} from './refs.js';
+import { truncateGraph } from './truncate.js';
+
+export const DEFAULT_MAX_NODES = 400;
+export const MAX_NODES_CAP = 2000;
+const LABEL_CHARS = 120;
+
+const edgeId = (from: string, to: string, kind: string) => `${from}\u0000${to}\u0000${kind}`;
+export const compareEdges = (a: KEdge, b: KEdge): number =>
+    compareStr(a.from, b.from) || compareStr(a.to, b.to) || compareStr(a.kind, b.kind);
+
+/** sha-256 over the canonical input: equal inputs (in any order) ⇒ equal digests. */
+export function graphDigest(input: BuildGraphInput): string {
+    return sha256Hex(canonicalJson({
+        rootId: input.rootId,
+        packs: input.packs.map((p) => p.id).sort(compareStr),
+        extracted: sortBy(input.extracted, (e) => e.sourceRef, (e) => e.sourceHash).map(canonicalExtracted),
+        facts: sortBy(input.facts, (f) => f.key).map((f) => ({ ...f, fileAnchors: sortBy(f.fileAnchors, (a) => a.path) })),
+        relations: sortBy(input.relations, (r) => r.from, (r) => r.to, (r) => r.kind),
+        live: input.live && {
+            changes: sortBy(input.live.changes, (c) => c.path),
+            runFiles: nonEmpty(input.live.runFiles) && [...input.live.runFiles!].sort(compareStr),
+        },
+        nearDuplicates: nonEmpty(input.nearDuplicates) && sortBy(input.nearDuplicates!, (p) => p.a, (p) => p.b),
+    }));
+}
+
+/** An absent list and an empty list mean the same input, so they hash the same. */
+const nonEmpty = (xs: readonly unknown[] | undefined): boolean | undefined => (xs && xs.length > 0) || undefined;
+
+function canonicalExtracted(e: Extracted) {
+    return {
+        sourceRef: e.sourceRef, sourceHash: e.sourceHash,
+        nodes: sortBy(e.nodes, (n) => n.ref),
+        edges: [...e.edges].sort(compareEdges),
+        keys: sortBy(e.keys, (k) => k.ref, (k) => k.key),
+    };
+}
+
+function mergeBadges(a?: Record<string, number | string>, b?: Record<string, number | string>) {
+    if (!a) return b && { ...b };
+    if (!b) return { ...a };
+    const out = { ...a };
+    // Commutative: on a conflict the larger value (as a string) wins, whatever the order.
+    for (const [k, v] of Object.entries(b)) out[k] = k in out && String(out[k]) >= String(v) ? out[k]! : v;
+    return out;
+}
+
+function oneLine(text: string): string {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > LABEL_CHARS ? `${flat.slice(0, LABEL_CHARS - 1)}…` : flat;
+}
+
+class GraphBuilder {
+    readonly nodes = new Map<NodeRef, KNode>();
+    readonly edges = new Map<string, KEdge>();
+
+    node(n: KNode): void {
+        const prior = this.nodes.get(n.ref);
+        if (!prior) { this.nodes.set(n.ref, { ...n, ...(n.badges ? { badges: { ...n.badges } } : {}) }); return; }
+        const badges = mergeBadges(prior.badges, n.badges);
+        if (badges) prior.badges = badges;
+    }
+
+    edge(e: KEdge): void {
+        const id = edgeId(e.from, e.to, e.kind);
+        const prior = this.edges.get(id);
+        if (!prior) { this.edges.set(id, { ...e }); return; }
+        prior.weight = Math.max(prior.weight, e.weight);
+        if (e.cycle) prior.cycle = true;
+        if (e.confidence !== undefined) prior.confidence = Math.max(prior.confidence ?? 0, e.confidence);
+    }
+
+    has(from: NodeRef, to: NodeRef, kind: string): boolean {
+        return this.edges.has(edgeId(from, to, kind));
+    }
+}
+
+function factNode(f: StoredFact, rootId: string, g: GraphBuilder): KNode {
+    const ref = factRef(f.key);
+    const kind = f.key.startsWith('ent:') ? 'entity' : f.key.startsWith('claim:') ? 'claim' : 'fact';
+    const anchors = sortBy(f.fileAnchors, (a) => a.path);
+    const anchoredPack = anchors.map((a) => g.nodes.get(srcRef(rootId, a.path))?.pack).find(Boolean);
+    const pack = kind === 'entity' ? f.key.split(':')[1] || 'memory' : anchoredPack ?? 'memory';
+    const stale = f.origin === 'model' && anchors.some((a) => {
+        const current = g.nodes.get(srcRef(rootId, a.path))?.sourceHash;
+        return !!a.contentHash && !!current && current !== a.contentHash;
+    });
+    const first = anchors[0];
+    return {
+        ref, kind, label: oneLine(kind === 'entity' ? f.content || entityName(ref) : f.content), pack,
+        importance: 0, origin: f.origin,
+        ...(first?.contentHash ? { sourceHash: first.contentHash } : {}),
+        ...(stale ? { stale: true } : {}),
+        ...(first?.line !== undefined ? { badges: { line: first.line } } : {}),
+    };
+}
+
+export function buildGraph(input: BuildGraphInput, opts: BuildGraphOptions = {}): KnowledgeGraph {
+    const { rootId } = input;
+    const g = new GraphBuilder();
+    const sources = new Set<string>();
+
+    for (const ex of sortBy(input.extracted, (e) => e.sourceRef, (e) => e.sourceHash)) {
+        if (ex.sourceRef.startsWith('src:')) sources.add(ex.sourceRef);
+        for (const n of sortBy(ex.nodes, (x) => x.ref)) g.node({ ...n, origin: 'extracted' });
+        for (const e of [...ex.edges].sort(compareEdges)) g.edge({ ...e, origin: 'extracted' });
+    }
+
+    const facts = sortBy(input.facts, (f) => f.key);
+    for (const f of facts) g.node(factNode(f, rootId, g));
+    for (const f of facts) {
+        for (const a of sortBy(f.fileAnchors, (x) => x.path)) {
+            const to = srcRef(rootId, a.path);
+            if (g.nodes.has(to)) g.edge({ from: factRef(f.key), to, kind: 'about', weight: 1, origin: f.origin });
+        }
+    }
+
+    for (const r of sortBy(input.relations, (x) => x.from, (x) => x.to, (x) => x.kind)) {
+        g.edge({
+            from: r.from, to: r.to, kind: r.kind, weight: r.weight, origin: r.origin,
+            ...(r.confidence !== undefined ? { confidence: r.confidence } : {}),
+        });
+    }
+
+    for (const p of sortBy(input.nearDuplicates ?? [], (x) => x.a, (x) => x.b)) {
+        if (p.a === p.b || p.a.startsWith('ent:') || p.b.startsWith('ent:')) continue;
+        const [a, b] = (compareStr(p.a, p.b) < 0 ? [p.a, p.b] : [p.b, p.a]) as [NodeRef, NodeRef];
+        if (!g.nodes.has(a) || !g.nodes.has(b) || g.has(a, b, 'duplicate') || g.has(b, a, 'duplicate')) continue;
+        g.edge({ from: a, to: b, kind: 'near-duplicate', weight: round6(p.similarity), origin: 'extracted' });
+    }
+
+    const changed = applyLive(input, g);
+    closeEndpoints(g);
+    const registries = new Map(input.packs.map((p) => [p.id, loadPartitions(p)] as const));
+    placeNodes(rootId, g, registries);
+
+    const rank = pageRank([...g.nodes.keys()], [...g.edges.values()]);
+    for (const n of g.nodes.values()) n.importance = rank.get(n.ref) ?? 0;
+
+    const allNodes = [...g.nodes.values()].map(finalNode).sort((a, b) => compareStr(a.ref, b.ref));
+    const allEdges = [...g.edges.values()].map(finalEdge).sort(compareEdges);
+    const packs = input.packs.map((p) => p.id).sort(compareStr);
+    const full: KnowledgeGraph = {
+        scope: { rootId, packs, digest: graphDigest(input) },
+        nodes: allNodes, edges: allEdges, findings: [],
+        stats: { sources: sources.size, nodes: allNodes.length, edges: allEdges.length, stale: 0, truncated: false },
+    };
+    full.findings = computeFindings(full, input.packs, registries, input.nearDuplicates ?? []);
+    full.stats.stale = allNodes.filter((n) => n.stale).length;
+
+    const maxNodes = Math.min(MAX_NODES_CAP, Math.max(1, Math.floor(opts.maxNodes ?? DEFAULT_MAX_NODES)));
+    const cut = truncateGraph(full, { maxNodes, focus: opts.focus ?? [], changed });
+    return {
+        ...full,
+        nodes: cut.nodes,
+        edges: cut.edges,
+        stats: { ...full.stats, nodes: cut.nodes.length, edges: cut.edges.length, truncated: cut.truncated },
+    };
+}
+
+function applyLive(input: BuildGraphInput, g: GraphBuilder): NodeRef[] {
+    const changed: NodeRef[] = [];
+    if (!input.live) return changed;
+    for (const c of sortBy(input.live.changes, (x) => x.path)) {
+        const ref = srcRef(input.rootId, c.path);
+        if (!g.nodes.has(ref)) continue;
+        g.node({ ...g.nodes.get(ref)!, badges: { added: c.added, removed: c.removed, status: c.status } });
+        changed.push(ref);
+    }
+    const run = [...new Set(input.live.runFiles ?? [])].sort(compareStr)
+        .map((p) => srcRef(input.rootId, p)).filter((r) => g.nodes.has(r));
+    for (let i = 0; i < run.length; i++) {
+        for (let j = i + 1; j < run.length; j++) {
+            g.edge({ from: run[i]!, to: run[j]!, kind: 'co-changed', weight: 1, origin: 'agent' });
+        }
+    }
+    return changed;
+}
+
+/** A missing `src:` endpoint becomes a `missing` placeholder (a broken link); a missing fact drops the edge. */
+function closeEndpoints(g: GraphBuilder): void {
+    for (const [id, e] of [...g.edges.entries()].sort((a, b) => compareStr(a[0], b[0]))) {
+        const ends = [e.from, e.to].filter((end) => !g.nodes.has(end));
+        if (ends.some((end) => pathOfRef(end) === undefined)) { g.edges.delete(id); continue; }
+        for (const end of ends) {
+            const path = pathOfRef(end)!;
+            const other = g.nodes.get(end === e.from ? e.to : e.from);
+            g.node({
+                ref: end, kind: 'missing', label: basenameOf(path) || path, pack: other?.pack ?? 'memory',
+                importance: 0, origin: 'extracted', badges: { missing: 1 },
+            });
+        }
+    }
+}
+
+function placeNodes(rootId: string, g: GraphBuilder, registries: Map<string, PartitionRegistry>): void {
+    for (const n of g.nodes.values()) {
+        const path = pathOfRef(n.ref);
+        if (path === undefined) continue;
+        const reg = registries.get(n.pack);
+        const partition = reg ? partitionOf(path, reg) : undefined;
+        if (partition !== undefined) n.partition = partition;
+        const area = areaOfPath(path);
+        if (area) n.area = srcRef(rootId, area);
+    }
+    for (const e of g.edges.values()) {
+        const from = g.nodes.get(e.from), to = g.nodes.get(e.to);
+        const reg = from && registries.get(from.pack);
+        if (!from || !to || !reg || from.pack !== to.pack) continue;
+        const verdict = verdictOf(from.partition, to.partition, reg);
+        if (verdict) e.verdict = verdict;
+    }
+}
+
+function finalNode(n: KNode): KNode {
+    const badges = n.badges && Object.keys(n.badges).length
+        ? Object.fromEntries(Object.keys(n.badges).sort(compareStr).map((k) => [k, n.badges![k]!]))
+        : undefined;
+    return {
+        ref: n.ref, kind: n.kind, label: n.label, pack: n.pack,
+        ...(n.partition !== undefined ? { partition: n.partition } : {}),
+        ...(n.area !== undefined ? { area: n.area } : {}),
+        importance: n.importance, origin: n.origin,
+        ...(n.sourceHash !== undefined ? { sourceHash: n.sourceHash } : {}),
+        ...(n.stale ? { stale: true } : {}),
+        ...(badges ? { badges } : {}),
+    };
+}
+
+export function finalEdge(e: KEdge): KEdge {
+    return {
+        from: e.from, to: e.to, kind: e.kind, weight: round6(e.weight), origin: e.origin,
+        ...(e.confidence !== undefined ? { confidence: round6(e.confidence) } : {}),
+        ...(e.verdict ? { verdict: e.verdict } : {}),
+        ...(e.cycle ? { cycle: true } : {}),
+    };
+}

package/src/knowledge/cards.ts

@@ -0,0 +1,130 @@
+/**
+ * knowledge/cards.ts — `toCards`: one knowledge-index card per graph node
+ * (design: Builderforce.ai/docs/design/deterministic-knowledge-index.md, "Cards").
+ *
+ * | kind            | text                                                              | keys                          |
+ * |-----------------|-------------------------------------------------------------------|-------------------------------|
+ * | file            | path · area · partition · symbols · doc line · top-5 neighbours   | path, basename, symbols, area |
+ * | section         | file · breadcrumb · first 400 chars · outgoing link targets       | file path, slug, front matter |
+ * | entity (ent:)   | name · type · top-5 mentioning sources                            | normalized name, aliases      |
+ * | claim           | subject predicate object · quote · source section                 | subject/object entity keys    |
+ * | area            | path · partition · top-10 members                                 | path                          |
+ *
+ * `hash` is the index's own text hash (`hashDocText`), so an unchanged card is never re-embedded.
+ */
+
+import { hashDocText } from '../retrieval/knowledge-index/digest.js';
+import type { IndexDoc, KEdge, KNode, KnowledgeGraph, NodeRef } from './model.js';
+import { byImportance } from './importance.js';
+import { entityName } from './resolve.js';
+import { basenameOf, compareStr, fileRefOf, normalizeKey, pathOfRef, slugOf } from './refs.js';
+
+const SEP = ' · ';
+const EXCERPT_CHARS = 400;
+
+export function toCards(g: KnowledgeGraph): IndexDoc[] {
+    const byRef = new Map(g.nodes.map((n) => [n.ref, n] as const));
+    const outEdges = new Map<NodeRef, KEdge[]>();
+    const inEdges = new Map<NodeRef, KEdge[]>();
+    const push = (m: Map<NodeRef, KEdge[]>, k: NodeRef, e: KEdge) => {
+        const l = m.get(k) ?? [];
+        l.push(e);
+        m.set(k, l);
+    };
+    for (const e of g.edges) { push(outEdges, e.from, e); push(inEdges, e.to, e); }
+    const label = (r: NodeRef) => byRef.get(r)?.label ?? pathOfRef(r) ?? r;
+    const ctx: CardCtx = { byRef, outEdges, inEdges, label, members: membersByArea(g.nodes) };
+
+    return g.nodes.map((n) => {
+        const { text, keys } = cardOf(n, ctx);
+        const uniqueKeys = [...new Set(keys.filter(Boolean))].sort(compareStr);
+        return { id: n.ref, text, ...(uniqueKeys.length ? { keys: uniqueKeys } : {}), hash: hashDocText(text) };
+    }).sort((a, b) => compareStr(a.id, b.id));
+}
+
+interface CardCtx {
+    byRef: Map<NodeRef, KNode>;
+    outEdges: Map<NodeRef, KEdge[]>;
+    inEdges: Map<NodeRef, KEdge[]>;
+    label(r: NodeRef): string;
+    members: Map<NodeRef, KNode[]>;
+}
+
+function membersByArea(nodes: readonly KNode[]): Map<NodeRef, KNode[]> {
+    const out = new Map<NodeRef, KNode[]>();
+    for (const n of nodes) {
+        if (!n.area || n.kind !== 'file') continue;
+        const l = out.get(n.area) ?? [];
+        l.push(n);
+        out.set(n.area, l);
+    }
+    return out;
+}
+
+/** Neighbour refs (either direction), heaviest first, then by ref. */
+function topNeighbours(ref: NodeRef, ctx: CardCtx, n: number): NodeRef[] {
+    const scored = new Map<NodeRef, number>();
+    for (const e of ctx.outEdges.get(ref) ?? []) scored.set(e.to, Math.max(scored.get(e.to) ?? 0, e.weight));
+    for (const e of ctx.inEdges.get(ref) ?? []) scored.set(e.from, Math.max(scored.get(e.from) ?? 0, e.weight));
+    return [...scored].sort((a, b) => b[1] - a[1] || compareStr(a[0], b[0])).slice(0, n).map(([r]) => r);
+}
+
+const badge = (n: KNode | undefined, k: string): string | undefined => {
+    const v = n?.badges?.[k];
+    return v === undefined || v === '' ? undefined : String(v);
+};
+
+const frontMatter = (n: KNode | undefined): string[] =>
+    Object.keys(n?.badges ?? {}).filter((k) => k.startsWith('fm.')).sort(compareStr)
+        .flatMap((k) => String(n!.badges![k]).split(',').map((v) => normalizeKey(v)));
+
+function cardOf(n: KNode, ctx: CardCtx): { text: string; keys: string[] } {
+    const path = pathOfRef(n.ref) ?? '';
+    const join = (parts: Array<string | undefined>) => parts.filter((p) => p !== undefined && p !== '').join(SEP);
+    switch (n.kind) {
+        case 'file': {
+            const contained = (ctx.outEdges.get(n.ref) ?? []).filter((e) => e.kind === 'contains')
+                .map((e) => ctx.byRef.get(e.to)).filter((c): c is KNode => c?.kind === 'symbol');
+            const symbols = contained.map((s) => s.label).sort(compareStr);
+            return {
+                text: join([path, n.area && pathOfRef(n.area), n.partition, symbols.join(', '), badge(n, 'doc'),
+                    topNeighbours(n.ref, ctx, 5).map(ctx.label).join(', ')]),
+                keys: [path, basenameOf(path), ...symbols, n.area ? pathOfRef(n.area) ?? '' : ''],
+            };
+        }
+        case 'section': {
+            const file = ctx.byRef.get(fileRefOf(n.ref));
+            const links = (ctx.outEdges.get(n.ref) ?? []).filter((e) => e.kind === 'links')
+                .map((e) => pathOfRef(e.to) ?? e.to).sort(compareStr);
+            return {
+                text: join([path, badge(n, 'breadcrumb') ?? n.label, badge(n, 'excerpt')?.slice(0, EXCERPT_CHARS), links.join(', ')]),
+                keys: [path, slugOf(n.label), ...frontMatter(file)],
+            };
+        }
+        case 'entity': {
+            const sources = (ctx.inEdges.get(n.ref) ?? []).filter((e) => e.kind === 'mentions' || e.kind === 'about')
+                .map((e) => ctx.byRef.get(e.from)).filter((s): s is KNode => !!s);
+            const about = (ctx.outEdges.get(n.ref) ?? []).filter((e) => e.kind === 'about')
+                .map((e) => ctx.byRef.get(e.to)).filter((s): s is KNode => !!s);
+            const top = [...new Map([...sources, ...about].map((s) => [s.ref, s])).values()].sort(byImportance).slice(0, 5);
+            const name = entityName(n.ref);
+            return {
+                text: join([n.label, badge(n, 'type'), top.map((s) => s.label).join(', ')]),
+                keys: [normalizeKey(name), normalizeKey(n.label.replace(/\s*\([^)]*\)\s*$/, '')),
+                    ...String(badge(n, 'aliases') ?? '').split(',').map(normalizeKey)],
+            };
+        }
+        case 'claim': {
+            const out = ctx.outEdges.get(n.ref) ?? [];
+            const sections = out.filter((e) => e.kind === 'about').map((e) => ctx.label(e.to)).sort(compareStr);
+            const entities = out.filter((e) => e.kind === 'mentions' && e.to.startsWith('ent:')).map((e) => normalizeKey(entityName(e.to)));
+            return { text: join([n.label, sections.join(', ')]), keys: entities };
+        }
+        case 'area': {
+            const members = [...(ctx.members.get(n.ref) ?? [])].sort(byImportance).slice(0, 10).map((m) => m.label);
+            return { text: join([path, n.partition, members.join(', ')]), keys: [path] };
+        }
+        default:
+            return { text: join([n.label, n.kind, path]), keys: [normalizeKey(n.label), path] };
+    }
+}

package/src/knowledge/docs.test.ts

@@ -0,0 +1,118 @@
+/**
+ * src/knowledge/docs.test.ts
+ * The docs pack: the builtin parsers' `extract` (sections, contains, relative and wiki
+ * links, mentions, front-matter keys) and its findings (broken link, orphan), plus cards.
+ */
+
+import { htmlParser, markdownParser, plainTextParser } from '../ingest/parsers.js';
+import type { SourceDocument } from '../ingest/types.js';
+import { buildGraph } from './build.js';
+import { toCards } from './cards.js';
+import type { ExtractContext, Extracted, NodeRef } from './model.js';
+import { DOCS_PACK } from './packs/docs.js';
+import { asPathSource, resolveRelativePath } from './sources.js';
+import { ref, ROOT } from './testkit.test-util.js';
+
+const FILES: Record<string, string> = {
+    'README.md': '# Home\nSee [the guide](docs/guide.md) and [[notes]].\n',
+    'docs/guide.md': '---\ntitle: The Guide\ntags: [Alpha, beta]\n---\n# Guide\nIntro about the Lease.\n## Setup\nSee [missing](./nope.md), [ext](https://x.com) and ![img](pic.png).\n',
+    'notes.md': '# Notes\nBack to [home](README.md), [the page](docs/page.html) and [[docs/plain.txt]].\n',
+    'docs/orphan.md': '# Lonely\nNobody links here.\n',
+    'docs/page.html': '<html><title>Page</title><body><a href="guide.md">g</a></body></html>',
+    'docs/plain.txt': 'Plain text pointing at [[guide]].',
+};
+
+const ctx: ExtractContext = {
+    rootId: ROOT,
+    knownKeys: new Map<string, NodeRef>([['lease', 'ent:docs:lease']]),
+    resolvePath: resolveRelativePath,
+};
+
+function source(path: string): SourceDocument {
+    return asPathSource({ id: path, tenantId: 't', content: { kind: 'text', text: FILES[path]! } }, path, `h:${path}`);
+}
+
+function extract(path: string): Extracted {
+    const src = source(path);
+    const parser = [markdownParser, htmlParser, plainTextParser].find((p) => p.accepts(src))!;
+    return parser.extract!(src, parser.parse(src), ctx);
+}
+
+const all = Object.keys(FILES).map(extract);
+const kinds = (ex: Extracted, kind: string) => ex.edges.filter((e) => e.kind === kind).map((e) => `${e.from} -> ${e.to}`);
+
+describe('docs extract', () => {
+    it('emits a file node and section nodes from the heading breadcrumb, joined by contains', () => {
+        const guide = extract('docs/guide.md');
+        expect(guide.sourceRef).toBe(ref('docs/guide.md'));
+        expect(guide.sourceHash).toBe('h:docs/guide.md');
+        expect(guide.nodes.map((n) => `${n.kind}:${n.ref}`)).toEqual([
+            `file:${ref('docs/guide.md')}`,
+            `section:${ref('docs/guide.md')}#guide`,
+            `section:${ref('docs/guide.md')}#guide/setup`,
+        ]);
+        expect(kinds(guide, 'contains')).toEqual([
+            `${ref('docs/guide.md')} -> ${ref('docs/guide.md')}#guide`,
+            `${ref('docs/guide.md')}#guide -> ${ref('docs/guide.md')}#guide/setup`,
+        ]);
+        expect(guide.nodes.every((n) => n.origin === 'extracted')).toBe(true);
+        expect(guide.nodes[0]!.label).toBe('The Guide');
+    });
+
+    it('resolves relative and wiki links; skips external links and images', () => {
+        expect(kinds(extract('README.md'), 'links')).toEqual([
+            `${ref('README.md')}#home -> ${ref('docs/guide.md')}`,
+            `${ref('README.md')}#home -> ${ref('notes.md')}`,
+        ]);
+        expect(kinds(extract('docs/guide.md'), 'links')).toEqual([`${ref('docs/guide.md')}#guide/setup -> ${ref('docs/nope.md')}`]);
+        expect(kinds(extract('docs/page.html'), 'links')).toEqual([`${ref('docs/page.html')} -> ${ref('docs/guide.md')}`]);
+        expect(kinds(extract('docs/plain.txt'), 'links')).toEqual([`${ref('docs/plain.txt')}#body -> ${ref('docs/guide.md')}`]);
+    });
+
+    it('mentions known keys by exact normalized match', () => {
+        expect(kinds(extract('docs/guide.md'), 'mentions')).toEqual([`${ref('docs/guide.md')}#guide -> ent:docs:lease`]);
+        expect(kinds(extract('notes.md'), 'mentions')).toEqual([]);
+    });
+
+    it('keys carry the path, basename, heading slugs and front-matter values', () => {
+        const keys = extract('docs/guide.md').keys.map((k) => k.key);
+        expect(keys).toEqual(expect.arrayContaining(['docs/guide.md', 'guide', 'guide.md', 'the guide', 'alpha', 'beta', 'setup']));
+    });
+
+    it('is pure: the same source extracts to the same output', () => {
+        expect(JSON.stringify(extract('docs/guide.md'))).toBe(JSON.stringify(extract('docs/guide.md')));
+    });
+});
+
+describe('docs findings and cards', () => {
+    const g = buildGraph({ rootId: ROOT, extracted: all, facts: [], relations: [], packs: [DOCS_PACK] });
+
+    it('reports a broken link per linking file', () => {
+        const broken = g.findings.filter((f) => f.kind === 'broken-link');
+        expect(broken).toHaveLength(1);
+        expect(broken[0]!.nodes).toEqual([ref('docs/guide.md'), ref('docs/nope.md')]);
+        expect(broken[0]!.requestKey).toBe('knowledgeGraph.fix.brokenLink');
+        expect(g.nodes.find((n) => n.ref === ref('docs/nope.md'))?.kind).toBe('missing');
+    });
+
+    it('reports orphan documents (entry documents aside)', () => {
+        const orphan = g.findings.find((f) => f.kind === 'orphan');
+        expect(orphan?.nodes).toEqual([ref('docs/orphan.md')]);
+    });
+
+    it('places docs on top-level folder planes without verdicts', () => {
+        expect(g.nodes.find((n) => n.ref === ref('docs/guide.md'))?.partition).toBe('docs');
+        expect(g.nodes.find((n) => n.ref === ref('README.md'))?.partition).toBe('(root)');
+        expect(g.edges.some((e) => e.verdict)).toBe(false);
+    });
+
+    it('cards: one per node, a section carries its breadcrumb and excerpt', () => {
+        const cards = toCards(g);
+        expect(cards.map((c) => c.id)).toEqual(g.nodes.map((n) => n.ref));
+        const setup = cards.find((c) => c.id === `${ref('docs/guide.md')}#guide/setup`)!;
+        expect(setup.text).toContain('Guide › Setup');
+        expect(setup.text).toContain('docs/nope.md');
+        expect(setup.keys).toEqual(expect.arrayContaining(['docs/guide.md', 'setup', 'alpha']));
+        expect(setup.hash).toMatch(/^[0-9a-f]{64}$/);
+    });
+});

package/src/knowledge/findings.ts

@@ -0,0 +1,159 @@
+/**
+ * knowledge/findings.ts — what a person can act on (PRD 38 §3.5).
+ *
+ * Generic findings, for every pack: cycle, clone group, near-duplicate, partition
+ * violation, unpartitioned share, stale knowledge — plus `possible-same` entities. Packs
+ * add their own through {@link FindingRule}s. Every finding has a stable id (a hash of its
+ * kind and refs) and a `requestKey` under `knowledgeGraph.fix.*`: the fixed, prefilled
+ * Fix-with-agent request, never a model call.
+ */
+
+import { hashText } from '../ingest/hash.js';
+import type { Finding, KEdge, KNode, KnowledgeGraph, KnowledgePack, NodeRef, PartitionRegistry } from './model.js';
+import type { SimilarPair } from '../retrieval/knowledge-index/types.js';
+import { possibleSameFindings } from './resolve.js';
+import { compareStr, round6 } from './refs.js';
+
+/** Node badge naming the clone group (e.g. a jscpd issue id) its `duplicate` edges belong to. */
+export const CLONE_GROUP_BADGE = 'cloneGroup';
+/** Refs listed on one grouped finding, at most (the count rides in params). */
+export const MAX_FINDING_NODES = 50;
+
+const SEVERITY_RANK = { error: 0, warn: 1, info: 2 } as const;
+
+export function findingId(kind: string, refs: readonly string[]): string {
+    return `${kind}:${hashText([...refs].sort(compareStr).join('\u0000'))}`;
+}
+
+/** `clone-group` → `knowledgeGraph.fix.cloneGroup`. */
+export function requestKeyFor(kind: string): string {
+    return `knowledgeGraph.fix.${kind.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())}`;
+}
+
+function finding(kind: string, pack: string, nodes: NodeRef[], severity: Finding['severity'], params: Finding['params']): Finding {
+    const sorted = [...new Set(nodes)].sort(compareStr);
+    return {
+        id: findingId(kind, sorted), kind, pack, nodes: sorted.slice(0, MAX_FINDING_NODES), severity, params,
+        requestKey: requestKeyFor(kind),
+    };
+}
+
+/** Connected components over edges, each sorted; components sorted by first ref. */
+export function components(edges: readonly KEdge[]): NodeRef[][] {
+    const parent = new Map<NodeRef, NodeRef>();
+    const find = (x: NodeRef): NodeRef => {
+        let r = x;
+        while (parent.get(r) !== r) r = parent.get(r)!;
+        parent.set(x, r);
+        return r;
+    };
+    for (const e of edges) {
+        for (const r of [e.from, e.to]) if (!parent.has(r)) parent.set(r, r);
+        const a = find(e.from), b = find(e.to);
+        if (a !== b) parent.set(compareStr(a, b) < 0 ? b : a, compareStr(a, b) < 0 ? a : b);
+    }
+    const groups = new Map<NodeRef, NodeRef[]>();
+    for (const r of [...parent.keys()].sort(compareStr)) {
+        const root = find(r);
+        let g = groups.get(root);
+        if (!g) groups.set(root, (g = []));
+        g.push(r);
+    }
+    return [...groups.values()].sort((a, b) => compareStr(a[0]!, b[0]!));
+}
+
+export function genericFindings(g: KnowledgeGraph, registries: ReadonlyMap<string, PartitionRegistry>): Finding[] {
+    const byRef = new Map(g.nodes.map((n) => [n.ref, n] as const));
+    const packOf = (ref: NodeRef) => byRef.get(ref)?.pack ?? 'memory';
+    const out: Finding[] = [];
+
+    for (const refs of components(g.edges.filter((e) => e.cycle))) {
+        out.push(finding('cycle', packOf(refs[0]!), refs, 'warn', { nodes: refs.length }));
+    }
+
+    // Clone groups: duplicate edges grouped by the clone-group badge, else by component.
+    const dup = g.edges.filter((e) => e.kind === 'duplicate');
+    const byBadge = new Map<string, KEdge[]>();
+    const unbadged: KEdge[] = [];
+    for (const e of dup) {
+        const badge = byRef.get(e.from)?.badges?.[CLONE_GROUP_BADGE] ?? byRef.get(e.to)?.badges?.[CLONE_GROUP_BADGE];
+        if (badge === undefined) { unbadged.push(e); continue; }
+        const list = byBadge.get(String(badge)) ?? [];
+        list.push(e);
+        byBadge.set(String(badge), list);
+    }
+    const groups: Array<{ group: string; refs: NodeRef[] }> = [
+        ...[...byBadge].map(([group, es]) => ({ group, refs: es.flatMap((e) => [e.from, e.to]) })),
+        ...components(unbadged).map((refs) => ({ group: '', refs })),
+    ];
+    for (const { group, refs } of groups) {
+        const unique = [...new Set(refs)];
+        out.push(finding('clone-group', packOf(unique.sort(compareStr)[0]!), unique, 'warn', { group, members: unique.length }));
+    }
+
+    for (const e of g.edges) {
+        if (e.kind === 'near-duplicate') {
+            out.push(finding('near-duplicate', packOf(e.from), [e.from, e.to], 'info', { similarity: round6(e.weight) }));
+        }
+        if (e.verdict === 'upward' || e.verdict === 'skips') {
+            const from = byRef.get(e.from), to = byRef.get(e.to);
+            out.push(finding('partition-violation', packOf(e.from), [e.from, e.to], e.verdict === 'upward' ? 'error' : 'warn', {
+                verdict: e.verdict, from: from?.partition ?? '', to: to?.partition ?? '', kind: e.kind,
+            }));
+        }
+    }
+
+    for (const [pack, reg] of [...registries].sort((a, b) => compareStr(a[0], b[0]))) {
+        if (!reg.allow) continue;
+        const files = g.nodes.filter((n) => n.pack === pack && n.kind === 'file');
+        const loose = files.filter((n) => n.partition === undefined).map((n) => n.ref);
+        if (loose.length === 0) continue;
+        out.push(finding('unpartitioned', pack, loose, 'info', {
+            count: loose.length, total: files.length, share: Math.round((loose.length / files.length) * 100),
+        }));
+    }
+
+    out.push(...staleFindings(g, byRef));
+    return out;
+}
+
+/** One finding per source whose stored knowledge went stale (unanchored stale nodes: one each). */
+function staleFindings(g: KnowledgeGraph, byRef: ReadonlyMap<NodeRef, KNode>): Finding[] {
+    const about = new Map<NodeRef, NodeRef>();
+    for (const e of g.edges) if (e.kind === 'about' && !about.has(e.from)) about.set(e.from, e.to);
+    const bySource = new Map<NodeRef, NodeRef[]>();
+    for (const n of g.nodes) {
+        if (!n.stale) continue;
+        const target = about.get(n.ref) ?? n.ref;
+        const list = bySource.get(target) ?? [];
+        list.push(n.ref);
+        bySource.set(target, list);
+    }
+    return [...bySource].map(([source, refs]) =>
+        finding('stale', byRef.get(source)?.pack ?? 'memory', [source, ...refs], 'warn', { count: refs.length }));
+}
+
+/** Generic + possible-same + every pack's rules; deduped by id; severity, then id. */
+export function computeFindings(
+    g: KnowledgeGraph,
+    packs: readonly KnowledgePack[],
+    registries: ReadonlyMap<string, PartitionRegistry>,
+    nearDuplicates: readonly SimilarPair[],
+): Finding[] {
+    const all = [...genericFindings(g, registries), ...possibleSameFindings(nearDuplicates)];
+    for (const pack of [...packs].sort((a, b) => compareStr(a.id, b.id))) {
+        for (const rule of pack.findings ?? []) {
+            for (const f of rule.find(g)) {
+                all.push({
+                    ...f,
+                    id: f.id || findingId(f.kind, f.nodes),
+                    nodes: [...new Set(f.nodes)].sort(compareStr),
+                    requestKey: f.requestKey ?? requestKeyFor(f.kind),
+                });
+            }
+        }
+    }
+    const byId = new Map<string, Finding>();
+    for (const f of all) if (!byId.has(f.id)) byId.set(f.id, f);
+    return [...byId.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || compareStr(a.id, b.id));
+}