@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/src/knowledge/importance.ts

@@ -0,0 +1,72 @@
+/**
+ * knowledge/importance.ts — deterministic PageRank (node size in the view, the
+ * truncation order, the cards' "top neighbours").
+ *
+ * Fixed iterations, damping 0.85, weighted out-edges, dangling mass spread uniformly,
+ * nodes iterated in ref order so the floating-point sums are the same everywhere.
+ * Scores are normalized so the top node is 1, and rounded to 6 decimals.
+ */
+
+import type { KNode, NodeRef } from './model.js';
+import { compareStr, round6 } from './refs.js';
+
+export const PAGERANK_DAMPING = 0.85;
+export const PAGERANK_ITERATIONS = 40;
+
+export function pageRank(
+    refs: readonly NodeRef[],
+    edges: ReadonlyArray<{ from: NodeRef; to: NodeRef; weight: number }>,
+    iterations: number = PAGERANK_ITERATIONS,
+    damping: number = PAGERANK_DAMPING,
+): Map<NodeRef, number> {
+    const order = [...new Set(refs)].sort(compareStr);
+    const n = order.length;
+    const out = new Map<NodeRef, number>();
+    if (n === 0) return out;
+    const index = new Map(order.map((r, i) => [r, i] as const));
+    const outWeight = new Float64Array(n);
+    const inbound: Array<Array<{ from: number; w: number }>> = order.map(() => []);
+    const sorted = [...edges].sort((a, b) => compareStr(a.from, b.from) || compareStr(a.to, b.to));
+    for (const e of sorted) {
+        const f = index.get(e.from), t = index.get(e.to);
+        const w = e.weight > 0 ? e.weight : 0;
+        if (f === undefined || t === undefined || f === t || w === 0) continue;
+        outWeight[f] += w;
+        inbound[t]!.push({ from: f, w });
+    }
+    let rank = new Float64Array(n).fill(1 / n);
+    for (let it = 0; it < iterations; it++) {
+        let dangling = 0;
+        for (let i = 0; i < n; i++) if (outWeight[i] === 0) dangling += rank[i]!;
+        const next = new Float64Array(n);
+        const base = (1 - damping) / n + (damping * dangling) / n;
+        for (let i = 0; i < n; i++) {
+            let sum = 0;
+            for (const { from, w } of inbound[i]!) sum += (rank[from]! * w) / outWeight[from]!;
+            next[i] = base + damping * sum;
+        }
+        rank = next;
+    }
+    let max = 0;
+    for (let i = 0; i < n; i++) max = Math.max(max, rank[i]!);
+    for (let i = 0; i < n; i++) out.set(order[i]!, max > 0 ? round6(rank[i]! / max) : 0);
+    return out;
+}
+
+/** Importance descending, then ref — the one order "top N" means everywhere. */
+export function byImportance(a: Pick<KNode, 'importance' | 'ref'>, b: Pick<KNode, 'importance' | 'ref'>): number {
+    return b.importance - a.importance || compareStr(a.ref, b.ref);
+}
+
+/** Area importance: the sum of its members' importance, renormalized so the top area is 1. */
+export function areaImportance(members: ReadonlyMap<NodeRef, readonly number[]>): Map<NodeRef, number> {
+    const sums = new Map<NodeRef, number>();
+    let max = 0;
+    for (const area of [...members.keys()].sort(compareStr)) {
+        const sum = members.get(area)!.reduce((s, v) => s + v, 0);
+        sums.set(area, sum);
+        max = Math.max(max, sum);
+    }
+    for (const [area, sum] of sums) sums.set(area, max > 0 ? round6(sum / max) : 0);
+    return sums;
+}

package/src/knowledge/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `@seanhogg/builderforce-memory/knowledge` — the knowledge graph: facts connected to each
+ * other and to the sources they came from (PRD 38, Builderforce.ai/docs/specs/38-prd-knowledge-graph.md).
+ *
+ * Pure TypeScript: runs in the browser, a Worker and Node. Hosts supply ports only — a
+ * DirectorySource, a KnowledgeStore, a JudgementPort — never graph logic.
+ */
+
+export type {
+    NodeRef, Origin, StoredOrigin, KNode, EdgeVerdict, KEdge, Extracted, ExtractContext, Finding, FindingRule,
+    PartitionRule, PartitionRegistry, JudgementSpec, JudgementRequest, JudgedClaim, JudgedEntity, JudgementResult,
+    JudgementPort, AnalyzerPort, KnowledgeParser, KnowledgePack, StoredFact, StoredRelation, Scope, ScopeRecord,
+    KnowledgeStore, DirectorySource, LiveOverlay, KnowledgeGraph, ReviewPlan, ReviewProgress, ReviewReport,
+    ReviewArgs, BuildGraphInput, BuildGraphOptions, TraceStep, Trace,
+} from './model.js';
+
+export { buildGraph, graphDigest, DEFAULT_MAX_NODES, MAX_NODES_CAP } from './build.js';
+export { truncateGraph, TRUNCATION_HARD_CAP, UNANCHORED_AREA } from './truncate.js';
+export type { TruncateOptions } from './truncate.js';
+export { pageRank, byImportance, areaImportance, PAGERANK_DAMPING, PAGERANK_ITERATIONS } from './importance.js';
+export {
+    loadPartitions, partitionOf, partitionOrder, verdictOf, globToRegExp, matchGlob, TOP_LEVEL_FOLDER,
+} from './partitions.js';
+export {
+    traceGraph, toMermaid, DEFAULT_TRACE_EDGE_KINDS, DEFAULT_TRACE_DEPTH, DEFAULT_TRACE_STEPS, UNPARTITIONED_LANE,
+} from './trace.js';
+export type { LanedTrace, TraceOptions } from './trace.js';
+export {
+    computeFindings, genericFindings, findingId, requestKeyFor, components, CLONE_GROUP_BADGE, MAX_FINDING_NODES,
+} from './findings.js';
+export {
+    resolveEntities, knownKeysOf, possibleSameFindings, normalizeKey, entityName, entityKey,
+} from './resolve.js';
+export type { ResolvedEntity } from './resolve.js';
+export { toCards } from './cards.js';
+export { planReview, planDetail, AVG_SECTION_BYTES } from './plan.js';
+export type { PlanOptions, PlannedFile, PlanDetail } from './plan.js';
+export { reviewDirectory, assertStoredBatch } from './review.js';
+export {
+    validateExtract, validateCompare, DEFAULT_REVIEW_MODEL_CALLS, REVIEW_FACT_SOURCE,
+} from './judge.js';
+export {
+    composePacks, ignoreMatcher, isBinaryPath, isBinaryText, mediaTypeOfPath, resolveRelativePath,
+    DEFAULT_MAX_FILE_BYTES, IGNORE_FILES, filesManifestKey, judgedManifestKey,
+} from './sources.js';
+export { srcRef, pathOfRef, fileRefOf, factRef, factKeyOf, slugOf, canonicalJson, compareStr } from './refs.js';
+export { DOCS_PACK, DOCS_PACK_ID, brokenLinkRule, orphanDocumentRule } from './packs/docs.js';
+export { frontMatterOf, SECTION_INDEX_BADGE } from '../ingest/docsExtract.js';
+export { LocalSnapshotStore, localSnapshotStore } from './stores/localSnapshotStore.js';
+export type { SnapshotPersistence, KnowledgeSnapshot, LocalSnapshotStoreOptions } from './stores/localSnapshotStore.js';
+
+// The knowledge index (search, expand, near-duplicate pairs) ships on the same subpath.
+export * from '../retrieval/knowledge-index/index.js';

package/src/knowledge/judge.ts

@@ -0,0 +1,231 @@
+/**
+ * knowledge/judge.ts — the judgement pass of a review: the only step that costs model
+ * calls (PRD 38 §4.3).
+ *
+ *   • extract: one call per changed section of a judged kind → claims (`claim:<hash>`) and
+ *     entities (`ent:<pack>:<name>`) as `model` facts anchored with the file's content
+ *     hash, plus `about` / `mentions` relations;
+ *   • compare: near-duplicate claim pairs → `contradicts` / `agrees` relations.
+ *
+ * Every response is schema-validated; invalid items are dropped and counted. The budget
+ * (calls and a deadline) is shared across the whole review.
+ */
+
+import { hashText } from '../ingest/hash.js';
+import type {
+    JudgedClaim, JudgedEntity, JudgementPort, JudgementResult, NodeRef, StoredFact, StoredRelation,
+} from './model.js';
+import type { SimilarPair } from '../retrieval/knowledge-index/types.js';
+import { entityKey, normalizeKey } from './resolve.js';
+import { compareStr, factRef } from './refs.js';
+
+export const DEFAULT_REVIEW_MODEL_CALLS = 200;
+export const REVIEW_FACT_SOURCE = 'knowledge-review';
+const MAX_TERM = 200;
+const MAX_NAME = 120;
+const MAX_QUOTE_CHARS = 300;
+const MAX_QUOTE_LINES = 3;
+
+export interface JudgeBudget {
+    modelCalls: number;
+    deadline: number;
+    used: number;
+    now(): number;
+}
+
+export const budgetLeft = (b: JudgeBudget): boolean => b.used < b.modelCalls && b.now() < b.deadline;
+
+/** Facts and relations a review will write, keyed for upsert. */
+export class JudgedBatch {
+    readonly facts = new Map<string, StoredFact>();
+    readonly relations = new Map<string, StoredRelation>();
+    judged = 0;
+    unjudged = 0;
+    invalid = 0;
+
+    fact(f: StoredFact): void { this.facts.set(f.key, f); }
+
+    relation(r: StoredRelation): void { this.relations.set(`${r.from}\u0000${r.to}\u0000${r.kind}`, r); }
+
+    take(): { facts: StoredFact[]; relations: StoredRelation[] } {
+        const out = {
+            facts: [...this.facts.values()].sort((a, b) => compareStr(a.key, b.key)),
+            relations: [...this.relations.values()].sort((a, b) =>
+                compareStr(a.from, b.from) || compareStr(a.to, b.to) || compareStr(a.kind, b.kind)),
+        };
+        this.facts.clear();
+        this.relations.clear();
+        return out;
+    }
+}
+
+const str = (v: unknown, max: number, allowEmpty = false): string | undefined => {
+    if (typeof v !== 'string') return undefined;
+    const t = v.trim();
+    return (t || allowEmpty) && t.length <= max ? t : undefined;
+};
+
+function validClaim(c: unknown): JudgedClaim | undefined {
+    if (!c || typeof c !== 'object') return undefined;
+    const o = c as Record<string, unknown>;
+    const subject = str(o['subject'], MAX_TERM), predicate = str(o['predicate'], MAX_TERM), object = str(o['object'], MAX_TERM);
+    if (!subject || !predicate || !object || typeof o['quote'] !== 'string') return undefined;
+    const quote = (o['quote'] as string).split(/\r?\n/).slice(0, MAX_QUOTE_LINES).join('\n').trim().slice(0, MAX_QUOTE_CHARS);
+    return { subject, predicate, object, quote };
+}
+
+function validEntity(e: unknown): JudgedEntity | undefined {
+    if (!e || typeof e !== 'object') return undefined;
+    const o = e as Record<string, unknown>;
+    const name = str(o['name'], MAX_NAME), type = str(o['type'], MAX_NAME, true);
+    return name && normalizeKey(name) && type !== undefined ? { name, type: type || 'thing' } : undefined;
+}
+
+/** The valid claims and entities a response holds for `ref`; everything else counted invalid. */
+export function validateExtract(result: unknown, ref: NodeRef): { claims: JudgedClaim[]; entities: JudgedEntity[]; invalid: number } {
+    const out = { claims: [] as JudgedClaim[], entities: [] as JudgedEntity[], invalid: 0 };
+    if (!result || typeof result !== 'object') { out.invalid = 1; return out; }
+    const r = result as Partial<JudgementResult>;
+    out.invalid += typeof r.invalid === 'number' && r.invalid > 0 ? Math.floor(r.invalid) : 0;
+    if (!Array.isArray(r.extract)) { out.invalid += 1; return out; }
+    for (const item of r.extract as unknown[]) {
+        const it = item as { ref?: unknown; claims?: unknown; entities?: unknown } | null;
+        if (!it || it.ref !== ref || !Array.isArray(it.claims) || !Array.isArray(it.entities)) { out.invalid += 1; continue; }
+        for (const c of it.claims) { const v = validClaim(c); if (v) out.claims.push(v); else out.invalid += 1; }
+        for (const e of it.entities) { const v = validEntity(e); if (v) out.entities.push(v); else out.invalid += 1; }
+    }
+    return out;
+}
+
+export function validateCompare(result: unknown, a: NodeRef, b: NodeRef): { relation?: 'contradicts' | 'agrees' | 'unrelated'; confidence: number; invalid: number } {
+    if (!result || typeof result !== 'object') return { confidence: 0, invalid: 1 };
+    const r = result as Partial<JudgementResult>;
+    let invalid = typeof r.invalid === 'number' && r.invalid > 0 ? Math.floor(r.invalid) : 0;
+    for (const item of Array.isArray(r.compare) ? r.compare : []) {
+        const ok = item && ((item.a === a && item.b === b) || (item.a === b && item.b === a))
+            && ['contradicts', 'agrees', 'unrelated'].includes(item.relation)
+            && typeof item.confidence === 'number' && item.confidence >= 0 && item.confidence <= 1;
+        if (ok) return { relation: item.relation, confidence: item.confidence, invalid };
+        invalid += 1;
+    }
+    return { confidence: 0, invalid: Math.max(invalid, 1) };
+}
+
+/** One model call, or a counted invalid when the port throws (an abort is re-thrown). */
+async function call(port: JudgementPort, req: Parameters<JudgementPort['judge']>[0], b: JudgeBudget): Promise<unknown> {
+    b.used += 1;
+    try {
+        return await port.judge(req);
+    } catch (err) {
+        if (req.signal?.aborted) throw err;
+        return undefined;
+    }
+}
+
+export interface SectionToJudge { ref: NodeRef; text: string }
+
+export interface ExtractArgs {
+    port: JudgementPort;
+    pack: string;
+    path: string;
+    fileHash: string;
+    sections: readonly SectionToJudge[];
+    budget: JudgeBudget;
+    batch: JudgedBatch;
+    /** Entity facts by key: stored ones plus this review's, merged across files. */
+    entities: Map<string, StoredFact>;
+    signal?: AbortSignal;
+    /** Called for each section actually judged (for the judged-sections manifest). */
+    onJudged(ref: NodeRef): void;
+}
+
+/** Judges each section within the budget; the rest are counted `unjudged`. */
+export async function judgeSections(a: ExtractArgs): Promise<Array<{ ref: NodeRef; text: string }>> {
+    const claims: Array<{ ref: NodeRef; text: string }> = [];
+    const anchor = { path: a.path, contentHash: a.fileHash };
+    for (const section of a.sections) {
+        if (!budgetLeft(a.budget)) { a.batch.unjudged += 1; continue; }
+        const result = await call(a.port, {
+            kind: 'extract', items: [{ ref: section.ref, text: section.text, sourceHash: a.fileHash }],
+            ...(a.signal ? { signal: a.signal } : {}),
+        }, a.budget);
+        const v = validateExtract(result, section.ref);
+        a.batch.invalid += v.invalid;
+        a.batch.judged += 1;
+        a.onJudged(section.ref);
+        const rel = (from: NodeRef, to: NodeRef, kind: string) =>
+            a.batch.relation({ from, to, kind, weight: 1, origin: 'model', sourceHash: a.fileHash });
+
+        const entityRefs = new Map<string, NodeRef>();
+        for (const e of v.entities) {
+            const key = entityKey(a.pack, e.name);
+            const prior = a.entities.get(key);
+            const anchors = [...(prior?.fileAnchors ?? []).filter((x) => x.path !== a.path), anchor]
+                .sort((x, y) => compareStr(x.path, y.path));
+            const fact: StoredFact = {
+                key, content: prior?.content ?? `${e.name} (${e.type})`, source: REVIEW_FACT_SOURCE,
+                importance: prior?.importance ?? 0.5, origin: prior?.origin ?? 'model', fileAnchors: anchors,
+            };
+            a.entities.set(key, fact);
+            a.batch.fact(fact);
+            entityRefs.set(normalizeKey(e.name), key);
+            rel(section.ref, key, 'mentions');
+        }
+        for (const c of v.claims) {
+            const key = `claim:${hashText([section.ref, c.subject, c.predicate, c.object].join('\u0000'))}`;
+            const text = `${c.subject} ${c.predicate} ${c.object}`;
+            a.batch.fact({
+                key, content: c.quote ? `${text} — “${c.quote}”` : text, source: REVIEW_FACT_SOURCE,
+                importance: 0.5, origin: 'model', fileAnchors: [anchor],
+            });
+            const ref = factRef(key);
+            rel(ref, section.ref, 'about');
+            for (const term of [c.subject, c.object]) {
+                const ent = entityRefs.get(normalizeKey(term));
+                if (ent) rel(ref, ent, 'mentions');
+            }
+            claims.push({ ref, text });
+        }
+    }
+    return claims;
+}
+
+export interface CompareArgs {
+    port: JudgementPort;
+    pairs: readonly SimilarPair[];
+    /** Claim ref → text and the content hash it was judged from. */
+    claims: ReadonlyMap<string, { text: string; hash: string }>;
+    budget: JudgeBudget;
+    batch: JudgedBatch;
+    signal?: AbortSignal;
+}
+
+/** Near-duplicate claim pairs, most similar first, compared within the budget. */
+export async function compareClaims(a: CompareArgs): Promise<void> {
+    const pairs = [...a.pairs]
+        .filter((p) => p.a !== p.b && a.claims.has(p.a) && a.claims.has(p.b))
+        .map((p) => (compareStr(p.a, p.b) <= 0 ? p : { a: p.b, b: p.a, similarity: p.similarity }))
+        .sort((x, y) => y.similarity - x.similarity || compareStr(x.a, y.a) || compareStr(x.b, y.b));
+    const seen = new Set<string>();
+    for (const p of pairs) {
+        const id = `${p.a}\u0000${p.b}`;
+        if (seen.has(id)) continue;
+        seen.add(id);
+        if (!budgetLeft(a.budget)) { a.batch.unjudged += 1; continue; }
+        const ca = a.claims.get(p.a)!, cb = a.claims.get(p.b)!;
+        const A = p.a as NodeRef, B = p.b as NodeRef;
+        const result = await call(a.port, {
+            kind: 'compare',
+            items: [{ ref: A, text: ca.text, sourceHash: ca.hash }, { ref: B, text: cb.text, sourceHash: cb.hash }],
+            ...(a.signal ? { signal: a.signal } : {}),
+        }, a.budget);
+        const v = validateCompare(result, A, B);
+        a.batch.invalid += v.invalid;
+        a.batch.judged += 1;
+        if (v.relation === 'contradicts' || v.relation === 'agrees') {
+            a.batch.relation({
+                from: A, to: B, kind: v.relation, weight: 1, origin: 'model', confidence: v.confidence, sourceHash: ca.hash,
+            });
+        }
+    }
+}

package/src/knowledge/model.ts

@@ -0,0 +1,312 @@
+/**
+ * The knowledge graph model — memory's structure for KNOWLEDGE: facts connected to each
+ * other and to the sources they came from (PRD: Builderforce.ai/docs/specs/38-prd-knowledge-graph.md).
+ *
+ * Generic: it knows sources, entities, facts and relations — never imports or headings.
+ * Packs (docs builtin, code registered by the host) supply that meaning as DATA.
+ *
+ * Store judgement, compute perception: `extracted` nodes/edges are recomputed from sources
+ * (cached by content hash) and are NEVER written to a KnowledgeStore; `model`/`human`/`agent`
+ * ones are stored with the content hash they were judged from and go stale when it changes.
+ */
+
+import type { IngestManifest, SourceDocument, ParsedSection } from '../ingest/types.js';
+import type { IndexDoc, SimilarPair } from '../retrieval/knowledge-index/types.js';
+
+/** `src:${rootId}::${path}` · `ent:${pack}:${normalizedName}` · `fact:${key}` (claims are `fact:claim:${hash}`). */
+export type NodeRef = `src:${string}` | `ent:${string}` | `fact:${string}`;
+
+export type Origin = 'extracted' | 'model' | 'human' | 'agent';
+export type StoredOrigin = Exclude<Origin, 'extracted'>;
+
+export interface KNode {
+    ref: NodeRef;
+    /** Pack-defined: 'file' | 'section' | 'symbol' | 'area' | 'entity' | 'claim' | 'fact' … */
+    kind: string;
+    label: string;
+    pack: string;
+    partition?: string;
+    area?: NodeRef;
+    /** PageRank over the joined graph, normalized 0–1 (areas: sum of members, renormalized). */
+    importance: number;
+    origin: Origin;
+    sourceHash?: string;
+    stale?: boolean;
+    /** Pack data, e.g. { added, removed }, { unused: 'file' }, { line: 12 }. */
+    badges?: Record<string, number | string>;
+}
+
+export type EdgeVerdict = 'allowed' | 'same' | 'skips' | 'upward';
+
+export interface KEdge {
+    from: NodeRef;
+    to: NodeRef;
+    /** 'references' | 'links' | 'contains' | 'mentions' | 'duplicate' | 'near-duplicate'
+     *  | 'contradicts' | 'agrees' | 'supersedes' | 'about' | 'co-changed' — a new kind is a value. */
+    kind: string;
+    weight: number;
+    origin: Origin;
+    confidence?: number;
+    verdict?: EdgeVerdict;
+    cycle?: boolean;
+}
+
+/** Output of a pack's deterministic extractor (or analyzer) for one source. Never stored. */
+export interface Extracted {
+    sourceRef: NodeRef;
+    sourceHash: string;
+    nodes: KNode[];
+    edges: KEdge[];
+    /** Exact keys for entity resolution and the index's exact tier. */
+    keys: Array<{ ref: NodeRef; key: string }>;
+}
+
+export interface ExtractContext {
+    rootId: string;
+    /** Normalized entity keys known so far (for `mentions`). */
+    knownKeys: ReadonlyMap<string, NodeRef>;
+    /** Resolves a relative link/import from `fromPath` to a root-relative path, or undefined. */
+    resolvePath(fromPath: string, target: string): string | undefined;
+}
+
+/** A finding a person can act on. `kind` is pack-defined; `requestKey` names an i18n template. */
+export interface Finding {
+    id: string;
+    kind: string;
+    pack: string;
+    nodes: NodeRef[];
+    severity: 'info' | 'warn' | 'error';
+    /** Numbers/strings for the label and the Fix-with-agent template. */
+    params: Record<string, string | number>;
+    /** i18n key of the fixed Fix-with-agent request (e.g. 'knowledgeGraph.fix.cloneGroup'). */
+    requestKey?: string;
+}
+
+export interface FindingRule {
+    id: string;
+    find(graph: KnowledgeGraph): Finding[];
+}
+
+export interface PartitionRule {
+    id: string;
+    /** 0 = top. */
+    order: number;
+    /** Globs over the source path; first matching rule wins. */
+    match: string[];
+}
+
+export interface PartitionRegistry {
+    partitions: PartitionRule[];
+    /** from-partition → partitions it may use. Absent ⇒ no verdicts. */
+    allow?: Record<string, string[]>;
+}
+
+/** What the judgement model is asked for one section kind; output is schema-validated. */
+export interface JudgementSpec {
+    /** Node kinds whose text is judged (e.g. ['section']). */
+    nodeKinds: string[];
+    /** Ask for claims[] / entities[] per node; and contradicts|agrees for near-duplicate claim pairs. */
+    claims: boolean;
+    entities: boolean;
+    contradictions: boolean;
+}
+
+export interface JudgementRequest {
+    kind: 'extract' | 'compare';
+    /** extract: one node's text; compare: two claims. */
+    items: Array<{ ref: NodeRef; text: string; sourceHash: string }>;
+    signal?: AbortSignal;
+}
+
+export interface JudgedClaim { subject: string; predicate: string; object: string; quote: string }
+export interface JudgedEntity { name: string; type: string }
+
+export interface JudgementResult {
+    extract?: Array<{ ref: NodeRef; claims: JudgedClaim[]; entities: JudgedEntity[] }>;
+    compare?: Array<{ a: NodeRef; b: NodeRef; relation: 'contradicts' | 'agrees' | 'unrelated'; confidence: number }>;
+    /** Items dropped for invalid output. */
+    invalid: number;
+}
+
+/** A routed model call. Hosts implement it (VS Code/on-prem: local engines → gateway; web: POST …/knowledge/judge). */
+export interface JudgementPort {
+    judge(req: JudgementRequest): Promise<JudgementResult>;
+}
+
+/** Host-run tools for a pack (code: dependency-cruiser/jscpd/knip). Returns extra extracted edges/badges. */
+export interface AnalyzerPort {
+    analyse(rootId: string, signal?: AbortSignal): Promise<Extracted[]>;
+}
+
+/** A host-supplied parser that also extracts graph structure. `extract` is the optional ingest extension. */
+export interface KnowledgeParser {
+    id: string;
+    accepts(source: SourceDocument): boolean;
+    parse(source: SourceDocument): ParsedSection[];
+    extract?(source: SourceDocument, sections: ParsedSection[], ctx: ExtractContext): Extracted;
+}
+
+export interface KnowledgePack {
+    /** 'docs' | 'code' */
+    id: string;
+    parsers: KnowledgeParser[];
+    partitions?: PartitionRegistry;
+    findings?: FindingRule[];
+    judgement?: JudgementSpec;
+    analyzers?: AnalyzerPort;
+}
+
+export interface StoredFact {
+    /** project_facts.key — judgement nodes use `ent:<pack>:<name>` / `claim:<hash>` namespaces. */
+    key: string;
+    content: string;
+    source: string;
+    importance: number;
+    origin: StoredOrigin;
+    fileAnchors: Array<{ path: string; line?: number; contentHash?: string }>;
+    updatedAt?: string;
+    createdBy?: number | null;
+}
+
+export interface StoredRelation {
+    from: NodeRef;
+    to: NodeRef;
+    kind: string;
+    weight: number;
+    origin: StoredOrigin;
+    confidence?: number;
+    sourceHash?: string;
+    staleAt?: string | null;
+}
+
+export interface Scope {
+    rootId: string;
+}
+
+export interface ScopeRecord {
+    rootId: string;
+    title: string;
+    packs: string[];
+    lastDigest?: string;
+    lastReviewedAt?: string;
+}
+
+/** Where knowledge is persisted: the platform API adapter or the local snapshot adapter. */
+export interface KnowledgeStore {
+    scopes(): Promise<ScopeRecord[]>;
+    facts(scope: Scope): Promise<StoredFact[]>;
+    relations(scope: Scope): Promise<StoredRelation[]>;
+    write(batch: { scope: ScopeRecord; facts: StoredFact[]; relations: StoredRelation[] }): Promise<void>;
+    /** Marks model facts/relations judged from `sourceRef` at a hash other than `currentHash` stale. */
+    markStale(scope: Scope, sourceRef: NodeRef, currentHash: string): Promise<void>;
+    /** Extracted output cache, by content hash (never knowledge — perception). */
+    getExtracted?(hash: string): Promise<Extracted[] | undefined>;
+    putExtracted?(hash: string, extracted: Extracted[]): Promise<void>;
+}
+
+/** Where files come from: one adapter per host. */
+export interface DirectorySource {
+    rootId: string;
+    title: string;
+    list(): AsyncIterable<{ path: string; hash: string; size: number }>;
+    read(path: string): Promise<SourceDocument>;
+    watch?(cb: (paths: string[]) => void): () => void;
+}
+
+export interface LiveOverlay {
+    changes: Array<{ path: string; status: string; added: number; removed: number }>;
+    /** Files touched together in one run → co-changed edges. */
+    runFiles?: string[];
+}
+
+export interface KnowledgeGraph {
+    scope: { rootId: string; packs: string[]; digest: string };
+    nodes: KNode[];
+    edges: KEdge[];
+    findings: Finding[];
+    stats: { sources: number; nodes: number; edges: number; stale: number; truncated: boolean };
+}
+
+export interface ReviewPlan {
+    rootId: string;
+    files: number;
+    byPack: Record<string, number>;
+    unchanged: number;
+    changed: string[];
+    removed: string[];
+    skipped: Array<{ path: string; reason: 'ignored' | 'binary' | 'too-large' | 'no-pack' }>;
+    /** ≈ judgement calls for changed files (sections of judged kinds). */
+    estimatedModelCalls: number;
+}
+
+export interface ReviewProgress {
+    phase: 'plan' | 'extract' | 'resolve' | 'judge' | 'write' | 'index' | 'done';
+    done: number;
+    total: number;
+    path?: string;
+}
+
+export interface ReviewReport {
+    rootId: string;
+    digest: string;
+    extracted: number;
+    judged: number;
+    /** Sections left extracted-only because the budget ran out. */
+    unjudged: number;
+    invalidJudgements: number;
+    factsWritten: number;
+    relationsWritten: number;
+    staleMarked: number;
+    aborted: boolean;
+    durationMs: number;
+}
+
+export interface ReviewArgs {
+    source: DirectorySource;
+    store: KnowledgeStore;
+    packs: KnowledgePack[];
+    manifest: IngestManifest;
+    judgement?: JudgementPort;
+    /** Near-duplicate claim pairs to compare / possible-same entities; from the knowledge index. */
+    similar?: (ids: string[]) => Promise<SimilarPair[]>;
+    budget: { modelCalls: number; ms: number };
+    signal?: AbortSignal;
+    onProgress?(p: ReviewProgress): void;
+}
+
+export interface BuildGraphInput {
+    rootId: string;
+    extracted: Extracted[];
+    facts: StoredFact[];
+    relations: StoredRelation[];
+    packs: KnowledgePack[];
+    live?: LiveOverlay;
+    nearDuplicates?: SimilarPair[];
+}
+
+export interface BuildGraphOptions {
+    /** Default 400; cap 2000. */
+    maxNodes?: number;
+    focus?: NodeRef[];
+}
+
+export interface TraceStep {
+    from: NodeRef;
+    to: NodeRef;
+    depth: number;
+    kind: string;
+    verdict?: EdgeVerdict;
+    cycle?: boolean;
+    back?: boolean;
+}
+
+export interface Trace {
+    from: NodeRef;
+    /** Partitions present, in registry order (lanes). */
+    lanes: string[];
+    steps: TraceStep[];
+    truncated: boolean;
+}
+
+/** Re-exported for card consumers. */
+export type { IndexDoc };