@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/src/knowledge/packs/docs.ts

@@ -0,0 +1,91 @@
+/**
+ * knowledge/packs/docs.ts — the docs pack, built into memory (PRD 38 §4.5).
+ *
+ * Parsers are the ONE builtin ingest parsers (markdown, HTML, plain text); their `extract`
+ * lives in `ingest/docsExtract.ts`. Partitions: one plane per top-level folder, no `allow`
+ * (so no verdicts). Findings: broken links and orphan documents. Judgement: claims,
+ * entities and contradictions per section.
+ */
+
+import { htmlParser, markdownParser, plainTextParser } from '../../ingest/parsers.js';
+import { DOCS_PACK_ID } from '../../ingest/docsExtract.js';
+import type { Finding, FindingRule, KnowledgeGraph, KnowledgePack, NodeRef } from '../model.js';
+import { findingId, MAX_FINDING_NODES, requestKeyFor } from '../findings.js';
+import { TOP_LEVEL_FOLDER } from '../partitions.js';
+import { basenameOf, compareStr, fileRefOf, pathOfRef } from '../refs.js';
+
+export { DOCS_PACK_ID };
+
+/** Targets with these extensions (or none) are documents; a link to anything else is not judged broken. */
+const DOC_TARGET = /(?:\.(?:md|markdown|mdx|html?|txt|rst|adoc)|\/[^./]*|^[^./]*)$/i;
+/** Entry documents are expected to have no inbound links. */
+const ENTRY_DOC = /^(readme|index|home|_index|summary)\.[a-z]+$/i;
+
+function fileOf(g: KnowledgeGraph): Map<NodeRef, NodeRef> {
+    return new Map(g.nodes.map((n) => [n.ref, fileRefOf(n.ref)] as const));
+}
+
+/** Links to documents that are not in the directory, grouped per linking file. */
+export const brokenLinkRule: FindingRule = {
+    id: 'docs.broken-link',
+    find(g) {
+        const kind = new Map(g.nodes.map((n) => [n.ref, n.kind] as const));
+        const file = fileOf(g);
+        const bySource = new Map<NodeRef, NodeRef[]>();
+        for (const e of g.edges) {
+            if (e.kind !== 'links' || kind.get(e.to) !== 'missing') continue;
+            if (!DOC_TARGET.test(pathOfRef(e.to) ?? '')) continue;
+            const source = file.get(e.from) ?? e.from;
+            const list = bySource.get(source) ?? [];
+            list.push(e.to);
+            bySource.set(source, list);
+        }
+        return [...bySource].sort((a, b) => compareStr(a[0], b[0])).map(([source, targets]): Finding => {
+            const unique = [...new Set(targets)].sort(compareStr);
+            const nodes = [source, ...unique];
+            return {
+                id: findingId('broken-link', nodes), kind: 'broken-link', pack: DOCS_PACK_ID,
+                nodes: nodes.slice(0, MAX_FINDING_NODES), severity: 'warn',
+                params: { count: unique.length, file: pathOfRef(source) ?? source },
+                requestKey: requestKeyFor('broken-link'),
+            };
+        });
+    },
+};
+
+/** Documents no other document links to (entry documents aside), as one finding. */
+export const orphanDocumentRule: FindingRule = {
+    id: 'docs.orphan',
+    find(g) {
+        const file = fileOf(g);
+        const linked = new Set<NodeRef>();
+        for (const e of g.edges) {
+            if (e.kind !== 'links') continue;
+            const from = file.get(e.from) ?? e.from, to = file.get(e.to) ?? e.to;
+            if (from !== to) linked.add(to);
+        }
+        const orphans = g.nodes
+            .filter((n) => n.pack === DOCS_PACK_ID && n.kind === 'file' && !linked.has(n.ref))
+            .filter((n) => !ENTRY_DOC.test(basenameOf(pathOfRef(n.ref) ?? '')))
+            .map((n) => n.ref).sort(compareStr);
+        if (orphans.length === 0) return [];
+        return [{
+            id: findingId('orphan', orphans), kind: 'orphan', pack: DOCS_PACK_ID,
+            nodes: orphans.slice(0, MAX_FINDING_NODES), severity: 'info',
+            params: { count: orphans.length }, requestKey: requestKeyFor('orphan'),
+        }];
+    },
+};
+
+export const DOCS_PACK: KnowledgePack = {
+    id: DOCS_PACK_ID,
+    parsers: [markdownParser, htmlParser, plainTextParser],
+    partitions: {
+        partitions: [
+            { id: TOP_LEVEL_FOLDER, order: 0, match: ['*/**'] },
+            { id: '(root)', order: 0, match: ['*'] },
+        ],
+    },
+    findings: [brokenLinkRule, orphanDocumentRule],
+    judgement: { nodeKinds: ['section'], claims: true, entities: true, contradictions: true },
+};

package/src/knowledge/partitions.test.ts

@@ -0,0 +1,98 @@
+/**
+ * src/knowledge/partitions.test.ts
+ * The verdict table, glob matching, top-level-folder partitions and override validation.
+ */
+
+import { globToRegExp, loadPartitions, matchGlob, partitionOf, verdictOf } from './partitions.js';
+import type { KnowledgePack, PartitionRegistry } from './model.js';
+import { DOCS_PACK } from './packs/docs.js';
+
+const LAYERS: PartitionRegistry = {
+    partitions: [
+        { id: 'presentation', order: 0, match: ['**/routes/**', '**/components/**'] },
+        { id: 'application', order: 1, match: ['**/application/**'] },
+        { id: 'domain', order: 2, match: ['**/domain/**'] },
+        { id: 'infrastructure', order: 3, match: ['**/infrastructure/**', '**/db/**'] },
+    ],
+    allow: {
+        presentation: ['application', 'domain'],
+        application: ['domain'],
+        domain: [],
+        infrastructure: ['domain', 'application'],
+    },
+};
+
+describe('verdictOf — the table', () => {
+    it.each([
+        ['presentation', 'presentation', 'same'],
+        ['presentation', 'application', 'allowed'],
+        ['presentation', 'domain', 'allowed'],
+        ['infrastructure', 'application', 'allowed'],
+        ['domain', 'presentation', 'upward'],
+        ['application', 'presentation', 'upward'],
+        ['infrastructure', 'presentation', 'upward'],
+        ['presentation', 'infrastructure', 'skips'],
+        ['application', 'infrastructure', 'skips'],
+        ['domain', 'infrastructure', 'skips'],
+    ])('%s → %s is %s', (from, to, verdict) => {
+        expect(verdictOf(from, to, LAYERS)).toBe(verdict);
+    });
+
+    it('gives no verdict without allow, or with an unpartitioned end', () => {
+        expect(verdictOf('presentation', 'domain', { partitions: LAYERS.partitions })).toBeUndefined();
+        expect(verdictOf(undefined, 'domain', LAYERS)).toBeUndefined();
+        expect(verdictOf('domain', undefined, LAYERS)).toBeUndefined();
+    });
+});
+
+describe('globs and partitionOf', () => {
+    it('matches ** across folders and * within one', () => {
+        expect(matchGlob('api/src/routes/x.ts', '**/routes/**')).toBe(true);
+        expect(matchGlob('routes/x.ts', '**/routes/**')).toBe(true);
+        expect(matchGlob('api/src/router/x.ts', '**/routes/**')).toBe(false);
+        expect(matchGlob('a/b.md', '*')).toBe(false);
+        expect(matchGlob('b.md', '*')).toBe(true);
+        expect(matchGlob('x.ts', '*.{ts,tsx}')).toBe(true);
+        expect(globToRegExp('a.b').test('aXb')).toBe(false);
+    });
+
+    it('takes the first matching rule', () => {
+        expect(partitionOf('api/db/routes/q.ts', LAYERS)).toBe('presentation');
+        expect(partitionOf('api/db/q.ts', LAYERS)).toBe('infrastructure');
+        expect(partitionOf('README.md', LAYERS)).toBeUndefined();
+    });
+
+    it('the docs pack partitions by top-level folder, with no verdicts', () => {
+        const reg = loadPartitions(DOCS_PACK);
+        expect(partitionOf('contracts/lease.md', reg)).toBe('contracts');
+        expect(partitionOf('contracts/deep/x.md', reg)).toBe('contracts');
+        expect(partitionOf('README.md', reg)).toBe('(root)');
+        expect(verdictOf('contracts', 'policy', reg)).toBeUndefined();
+    });
+});
+
+describe('loadPartitions', () => {
+    const pack: KnowledgePack = { id: 'code', parsers: [], partitions: LAYERS };
+
+    it('returns the pack default without an override', () => {
+        expect(loadPartitions(pack)).toBe(LAYERS);
+        expect(loadPartitions({ id: 'x', parsers: [] })).toEqual({ partitions: [] });
+    });
+
+    it('accepts a valid override', () => {
+        const reg = loadPartitions(pack, { partitions: [{ id: 'ui', order: 0, match: ['ui/**'] }, { id: 'core', order: 1, match: ['core/**'] }], allow: { ui: ['core'] } });
+        expect(reg.allow).toEqual({ ui: ['core'] });
+        expect(partitionOf('ui/a.ts', reg)).toBe('ui');
+    });
+
+    it.each([
+        ['not an object', 'nope'],
+        ['no partitions', {}],
+        ['bad order', { partitions: [{ id: 'a', order: 'x', match: ['a/**'] }] }],
+        ['bad match', { partitions: [{ id: 'a', order: 0, match: [1] }] }],
+        ['duplicate ids', { partitions: [{ id: 'a', order: 0, match: ['a'] }, { id: 'a', order: 1, match: ['b'] }] }],
+        ['unknown allow target', { partitions: [{ id: 'a', order: 0, match: ['a'] }], allow: { a: ['b'] } }],
+    ])('rejects an override with %s', (_why, override) => {
+        expect(() => loadPartitions(pack, override)).toThrow(TypeError);
+    });
+});

package/src/knowledge/partitions.ts

@@ -0,0 +1,119 @@
+/**
+ * knowledge/partitions.ts — ordered groups of sources and who may use whom (PRD 38 §4.4).
+ *
+ * Generic: code layers and doc folders are both a {@link PartitionRegistry}. An edge's
+ * verdict is `same`, `allowed`, `upward` (to a lower order, i.e. a layer above) or
+ * `skips` (anything else), and is set only when the registry defines `allow` and both
+ * ends are partitioned.
+ *
+ * A rule whose id is {@link TOP_LEVEL_FOLDER} names its partition after the path's first
+ * folder — the docs pack's "one plane per top-level folder" with no per-folder rows.
+ */
+
+import type { EdgeVerdict, KnowledgePack, PartitionRegistry, PartitionRule } from './model.js';
+
+/** Rule id meaning "the matched path's top-level folder". */
+export const TOP_LEVEL_FOLDER = '*';
+
+const globCache = new Map<string, RegExp>();
+
+/**
+ * A glob as a RegExp over `/`-separated paths: `**` spans folders (`**\/` may match none),
+ * `*` and `?` stay within one segment, `{a,b}` is alternation.
+ */
+export function globToRegExp(glob: string): RegExp {
+    const cached = globCache.get(glob);
+    if (cached) return cached;
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i]!;
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                const slashAfter = glob[i + 2] === '/';
+                re += slashAfter ? '(?:.*/)?' : '.*';
+                i += slashAfter ? 2 : 1;
+            } else re += '[^/]*';
+        } else if (ch === '?') re += '[^/]';
+        else if (ch === '{') {
+            const close = glob.indexOf('}', i);
+            if (close < 0) { re += '\\{'; continue; }
+            re += `(?:${glob.slice(i + 1, close).split(',').map(escapeRe).join('|')})`;
+            i = close;
+        } else re += escapeRe(ch);
+    }
+    const compiled = new RegExp(`^${re}$`);
+    globCache.set(glob, compiled);
+    return compiled;
+}
+
+function escapeRe(s: string): string {
+    return s.replace(/[.+^${}()|[\]\\*?]/g, '\\$&');
+}
+
+export function matchGlob(path: string, glob: string): boolean {
+    return globToRegExp(glob).test(path);
+}
+
+/** The partition a root-relative path belongs to: the first matching rule, in registry order. */
+export function partitionOf(path: string, reg: PartitionRegistry): string | undefined {
+    for (const rule of reg.partitions) {
+        if (!rule.match.some((g) => matchGlob(path, g))) continue;
+        if (rule.id !== TOP_LEVEL_FOLDER) return rule.id;
+        const slash = path.indexOf('/');
+        return slash > 0 ? path.slice(0, slash) : undefined;
+    }
+    return undefined;
+}
+
+/** The order of a partition (folder partitions from {@link TOP_LEVEL_FOLDER} share that rule's). */
+export function partitionOrder(id: string, reg: PartitionRegistry): number | undefined {
+    const rule = reg.partitions.find((r) => r.id === id) ?? reg.partitions.find((r) => r.id === TOP_LEVEL_FOLDER);
+    return rule?.order;
+}
+
+export function verdictOf(from: string | undefined, to: string | undefined, reg: PartitionRegistry): EdgeVerdict | undefined {
+    if (!reg.allow || from === undefined || to === undefined) return undefined;
+    if (from === to) return 'same';
+    if (reg.allow[from]?.includes(to)) return 'allowed';
+    const fromOrder = partitionOrder(from, reg);
+    const toOrder = partitionOrder(to, reg);
+    if (fromOrder !== undefined && toOrder !== undefined && toOrder < fromOrder) return 'upward';
+    return 'skips';
+}
+
+/**
+ * A pack's registry, or a validated `.builderforce/partitions.json` override. Throws a
+ * `TypeError` naming the first problem when the override is not a {@link PartitionRegistry}.
+ */
+export function loadPartitions(pack: KnowledgePack, override?: unknown): PartitionRegistry {
+    if (override === undefined || override === null) return pack.partitions ?? { partitions: [] };
+    const fail = (why: string): never => { throw new TypeError(`partitions.json: ${why}`); };
+    if (typeof override !== 'object' || Array.isArray(override)) fail('expected an object');
+    const o = override as Record<string, unknown>;
+    if (!Array.isArray(o['partitions'])) fail('`partitions` must be an array');
+    const partitions: PartitionRule[] = (o['partitions'] as unknown[]).map((raw, i) => {
+        const r = raw as Record<string, unknown> | null;
+        if (!r || typeof r !== 'object') fail(`partitions[${i}] must be an object`);
+        if (typeof r!['id'] !== 'string' || !r!['id']) fail(`partitions[${i}].id must be a non-empty string`);
+        if (typeof r!['order'] !== 'number' || !Number.isFinite(r!['order'])) fail(`partitions[${i}].order must be a number`);
+        const match = r!['match'];
+        if (!Array.isArray(match) || !match.every((g) => typeof g === 'string' && g)) {
+            fail(`partitions[${i}].match must be an array of globs`);
+        }
+        return { id: r!['id'] as string, order: r!['order'] as number, match: [...(match as string[])] };
+    });
+    const ids = new Set(partitions.map((p) => p.id));
+    if (ids.size !== partitions.length) fail('partition ids must be unique');
+    if (o['allow'] === undefined) return { partitions };
+    const allowRaw = o['allow'];
+    if (!allowRaw || typeof allowRaw !== 'object' || Array.isArray(allowRaw)) fail('`allow` must be an object');
+    const allow: Record<string, string[]> = {};
+    for (const [from, to] of Object.entries(allowRaw as Record<string, unknown>)) {
+        if (!ids.has(from)) fail(`allow.${from} names an unknown partition`);
+        if (!Array.isArray(to) || !to.every((t) => typeof t === 'string' && ids.has(t))) {
+            fail(`allow.${from} must list known partition ids`);
+        }
+        allow[from] = [...(to as string[])];
+    }
+    return { partitions, allow };
+}

package/src/knowledge/plan.ts

@@ -0,0 +1,115 @@
+/**
+ * knowledge/plan.ts — `planReview`: the confirm chip's numbers (PRD 38 §4.3).
+ *
+ * A walk plus a manifest diff by hash, nothing more: a file whose hash is unchanged is
+ * never read. The only reads are the ignore files (`.gitignore`, `.builderforce/ignore`)
+ * when the listing has them. Binary files (by extension), oversized files and files no
+ * pack accepts are skipped with a reason.
+ */
+
+import type { IngestManifest } from '../ingest/types.js';
+import type { DirectorySource, KnowledgePack, ReviewPlan } from './model.js';
+import {
+    composePacks, DEFAULT_MAX_FILE_BYTES, filesManifestKey, IGNORE_FILES, ignoreMatcher, isBinaryPath,
+    manifestMap, stubSource,
+} from './sources.js';
+import { compareStr, sortBy } from './refs.js';
+
+/** ≈ bytes per judged section, for the estimate (the plan does not read changed files). */
+export const AVG_SECTION_BYTES = 1500;
+/** ≈ one compare call per this many judged sections when contradictions are asked for. */
+const SECTIONS_PER_COMPARE = 10;
+
+export interface PlanOptions {
+    /** Per-file size cap in bytes. Default 2 MB. */
+    maxFileBytes?: number;
+}
+
+export interface PlannedFile {
+    path: string;
+    hash: string;
+    size: number;
+    pack: string;
+    changed: boolean;
+}
+
+export interface PlanDetail {
+    plan: ReviewPlan;
+    /** Every included file (changed and unchanged), sorted by path. */
+    files: PlannedFile[];
+    /** The manifest's prior `path → hash`. */
+    prior: Map<string, string>;
+}
+
+export async function planReview(
+    source: DirectorySource,
+    manifest: IngestManifest,
+    packs: KnowledgePack[],
+    opts: PlanOptions = {},
+): Promise<ReviewPlan> {
+    return (await planDetail(source, manifest, packs, opts)).plan;
+}
+
+export async function planDetail(
+    source: DirectorySource,
+    manifest: IngestManifest,
+    packs: readonly KnowledgePack[],
+    opts: PlanOptions = {},
+): Promise<PlanDetail> {
+    const maxBytes = opts.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const listed: Array<{ path: string; hash: string; size: number }> = [];
+    for await (const entry of source.list()) listed.push({ ...entry, path: entry.path.replace(/\\/g, '/').replace(/^\.?\//, '') });
+    const entries = sortBy(listed, (e) => e.path);
+
+    const ignoreTexts: string[] = [];
+    for (const name of IGNORE_FILES) {
+        if (!entries.some((e) => e.path === name)) continue;
+        const doc = await source.read(name);
+        if (doc.content.kind === 'text') ignoreTexts.push(doc.content.text);
+    }
+    const ignored = ignoreMatcher(ignoreTexts);
+    const composed = composePacks(packs);
+    const prior = await manifestMap(manifest, filesManifestKey(source.rootId));
+    const packById = new Map(packs.map((p) => [p.id, p] as const));
+
+    const files: PlannedFile[] = [];
+    const skipped: ReviewPlan['skipped'] = [];
+    const byPack: Record<string, number> = {};
+    let estimatedSections = 0;
+    let compareSections = 0;
+    for (const e of entries) {
+        if (ignored(e.path)) { skipped.push({ path: e.path, reason: 'ignored' }); continue; }
+        if (isBinaryPath(e.path)) { skipped.push({ path: e.path, reason: 'binary' }); continue; }
+        if (e.size > maxBytes) { skipped.push({ path: e.path, reason: 'too-large' }); continue; }
+        const hit = composed.resolve(stubSource(e.path));
+        if (!hit) { skipped.push({ path: e.path, reason: 'no-pack' }); continue; }
+        const changed = prior.get(e.path) !== e.hash;
+        files.push({ path: e.path, hash: e.hash, size: e.size, pack: hit.pack.id, changed });
+        byPack[hit.pack.id] = (byPack[hit.pack.id] ?? 0) + 1;
+        const spec = packById.get(hit.pack.id)?.judgement;
+        if (changed && spec && (spec.claims || spec.entities)) {
+            const sections = Math.max(1, Math.ceil(e.size / AVG_SECTION_BYTES));
+            estimatedSections += sections;
+            if (spec.contradictions) compareSections += sections;
+        }
+    }
+
+    const present = new Set(entries.map((e) => e.path));
+    const removed = [...prior.keys()].filter((p) => !present.has(p)).sort(compareStr);
+    const changed = files.filter((f) => f.changed).map((f) => f.path);
+    const sortedByPack = Object.fromEntries(Object.keys(byPack).sort(compareStr).map((k) => [k, byPack[k]!]));
+    return {
+        plan: {
+            rootId: source.rootId,
+            files: files.length,
+            byPack: sortedByPack,
+            unchanged: files.length - changed.length,
+            changed,
+            removed,
+            skipped,
+            estimatedModelCalls: estimatedSections + Math.ceil(compareSections / SECTIONS_PER_COMPARE),
+        },
+        files,
+        prior,
+    };
+}

package/src/knowledge/refs.ts

@@ -0,0 +1,108 @@
+/**
+ * knowledge/refs.ts — the NodeRef grammar and the deterministic primitives every
+ * knowledge module shares (ordering, canonical JSON, entity keys).
+ *
+ * Pure and import-free of `ingest` runtime code, so ingest's extractors can use it
+ * without an import cycle.
+ *
+ *   src:${rootId}::${path}            a source file (or an area: a directory path)
+ *   src:${rootId}::${path}#${slug}    a section of a source
+ *   ent:${pack}:${normalizedName}     an entity (also its project_facts key)
+ *   fact:${key}                       any other fact (claims: fact:claim:${hash})
+ */
+
+import type { NodeRef } from './model.js';
+
+/** Code-unit ordering — never `localeCompare`, whose result depends on the host's ICU. */
+export function compareStr(a: string, b: string): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
+export function srcRef(rootId: string, path: string): NodeRef {
+    return `src:${rootId}::${path}`;
+}
+
+/** The root-relative path of a `src:` ref (the section suffix dropped), else undefined. */
+export function pathOfRef(ref: string): string | undefined {
+    if (!ref.startsWith('src:')) return undefined;
+    const at = ref.indexOf('::');
+    if (at < 0) return undefined;
+    const rest = ref.slice(at + 2);
+    const hash = rest.indexOf('#');
+    return hash < 0 ? rest : rest.slice(0, hash);
+}
+
+/** The ref of the file a `src:` ref belongs to (itself for a file). */
+export function fileRefOf(ref: NodeRef): NodeRef {
+    const hash = ref.startsWith('src:') ? ref.indexOf('#', ref.indexOf('::')) : -1;
+    return hash < 0 ? ref : (ref.slice(0, hash) as NodeRef);
+}
+
+/** The node ref of a stored fact key: `ent:` keys are refs already; the rest are `fact:`. */
+export function factRef(key: string): NodeRef {
+    return key.startsWith('ent:') ? (key as NodeRef) : `fact:${key}`;
+}
+
+/** The stored fact key of a fact/entity ref (inverse of {@link factRef}). */
+export function factKeyOf(ref: NodeRef): string | undefined {
+    if (ref.startsWith('ent:')) return ref;
+    if (ref.startsWith('fact:')) return ref.slice(5);
+    return undefined;
+}
+
+/**
+ * The normalized key of a name: NFKC, case-folded, punctuation stripped (dashes,
+ * underscores and slashes read as spaces so `run-store` and `run store` agree),
+ * whitespace collapsed.
+ */
+export function normalizeKey(name: string): string {
+    return name
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[\p{Pd}\p{Pc}/\\]+/gu, ' ')
+        .replace(/[\p{P}\p{S}]+/gu, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/** A heading slug: the normalized key with spaces as dashes. */
+export function slugOf(text: string): string {
+    return normalizeKey(text).replace(/ /g, '-') || 'section';
+}
+
+export function basenameOf(path: string): string {
+    const i = path.lastIndexOf('/');
+    return i < 0 ? path : path.slice(i + 1);
+}
+
+/** Rounds to 6 decimals so floating noise never reaches the JSON. */
+export function round6(n: number): number {
+    return Math.round(n * 1e6) / 1e6;
+}
+
+/** JSON with object keys sorted and `undefined` members dropped — the canonical form for digests. */
+export function canonicalJson(value: unknown): string {
+    return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(sortKeys);
+    if (value === null || typeof value !== 'object') return value;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort(compareStr)) {
+        const v = (value as Record<string, unknown>)[key];
+        if (v !== undefined) out[key] = sortKeys(v);
+    }
+    return out;
+}
+
+/** Sorts a copy by the given string keys, in order. */
+export function sortBy<T>(items: readonly T[], ...keys: Array<(t: T) => string>): T[] {
+    return [...items].sort((a, b) => {
+        for (const key of keys) {
+            const c = compareStr(key(a), key(b));
+            if (c !== 0) return c;
+        }
+        return 0;
+    });
+}

package/src/knowledge/resolve.ts

@@ -0,0 +1,78 @@
+/**
+ * knowledge/resolve.ts — deterministic entity resolution (PRD 38 §4.3).
+ *
+ *   • Exact: names whose normalized keys ({@link normalizeKey}) are equal are ONE entity.
+ *   • Near: pairs the knowledge index calls similar become `possible-same` findings for a
+ *     person to judge. They are never merged automatically.
+ */
+
+import type { Finding, NodeRef } from './model.js';
+import type { SimilarPair } from '../retrieval/knowledge-index/types.js';
+import { hashText } from '../ingest/hash.js';
+import { compareStr, normalizeKey, round6 } from './refs.js';
+
+export { normalizeKey };
+
+export interface ResolvedEntity {
+    key: string;
+    /** The canonical ref (the smallest of the group). */
+    ref: NodeRef;
+    /** Every ref with this key, sorted. */
+    refs: NodeRef[];
+}
+
+/** Groups refs by exact normalized key. Empty keys are ignored. Sorted by key. */
+export function resolveEntities(entries: ReadonlyArray<{ ref: NodeRef; key: string }>): ResolvedEntity[] {
+    const groups = new Map<string, Set<NodeRef>>();
+    for (const { ref, key } of entries) {
+        const k = normalizeKey(key);
+        if (!k) continue;
+        let g = groups.get(k);
+        if (!g) groups.set(k, (g = new Set()));
+        g.add(ref);
+    }
+    return [...groups.keys()].sort(compareStr).map((key) => {
+        const refs = [...groups.get(key)!].sort(compareStr);
+        return { key, ref: refs[0]!, refs };
+    });
+}
+
+/** Normalized key → canonical ref, for an extractor's `ctx.knownKeys`. */
+export function knownKeysOf(resolved: readonly ResolvedEntity[]): Map<string, NodeRef> {
+    return new Map(resolved.map((r) => [r.key, r.ref] as const));
+}
+
+/**
+ * `possible-same` findings from near-duplicate pairs between two DIFFERENT entities (pairs
+ * already merged by key, or naming a non-entity, are not reported).
+ */
+export function possibleSameFindings(pairs: readonly SimilarPair[], pack = 'memory'): Finding[] {
+    const seen = new Set<string>();
+    const out: Finding[] = [];
+    for (const p of pairs) {
+        if (!p.a.startsWith('ent:') || !p.b.startsWith('ent:') || p.a === p.b) continue;
+        const [a, b] = compareStr(p.a, p.b) <= 0 ? [p.a, p.b] : [p.b, p.a];
+        if (normalizeKey(entityName(a)) === normalizeKey(entityName(b))) continue;
+        const id = `possible-same:${hashText(`${a}\u0000${b}`)}`;
+        if (seen.has(id)) continue;
+        seen.add(id);
+        out.push({
+            id, kind: 'possible-same', pack, nodes: [a as NodeRef, b as NodeRef], severity: 'info',
+            params: { similarity: round6(p.similarity) },
+            requestKey: 'knowledgeGraph.fix.possibleSame',
+        });
+    }
+    return out.sort((x, y) => compareStr(x.id, y.id));
+}
+
+/** The name part of `ent:<pack>:<name>`. */
+export function entityName(ref: string): string {
+    const rest = ref.startsWith('ent:') ? ref.slice(4) : ref;
+    const colon = rest.indexOf(':');
+    return colon < 0 ? rest : rest.slice(colon + 1);
+}
+
+/** The stored key of an entity named `name` in `pack`. */
+export function entityKey(pack: string, name: string): NodeRef {
+    return `ent:${pack}:${normalizeKey(name)}`;
+}