@northtek/overstory 0.1.0

package/dist/build/builder.js

@@ -0,0 +1,223 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { loadCorpus } from '../core/corpus.js';
+import { applyVerification, verifyTree } from '../core/gate.js';
+import { loadTree, partialPath, saveTree, treePath } from '../core/store.js';
+import { aggregateClaims } from './aggregate.js';
+import { mapPool } from './pool.js';
+import { refineClaims } from './reflexion.js';
+import { summarizeFile } from './summarize.js';
+const lockPath = (root) => join(root, '.overstory', 'build.lock');
+const pidAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+};
+/** Concurrent builds on one root are last-writer-wins corruption — refuse, loudly.
+ * A lock owned by a dead process is stale and reclaimed. */
+const acquireLock = async (root) => {
+    const path = lockPath(root);
+    await mkdir(dirname(path), { recursive: true });
+    try {
+        const existing = JSON.parse(await readFile(path, 'utf8'));
+        if (existing.pid && pidAlive(existing.pid)) {
+            throw new Error(`another overstory build (pid ${existing.pid}) is already running for this root; wait for it, or delete ${path} if that process is gone`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('another overstory build'))
+            throw err;
+        // missing or unreadable lock file: free to claim
+    }
+    await writeFile(path, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), 'utf8');
+};
+export const dirOf = (file) => {
+    const d = dirname(file).replace(/\\/gu, '/');
+    return d === '.' ? '' : d;
+};
+/** All ancestor dir paths for a set of files, deepest first (so children exist before
+ * their parent aggregates). */
+export const dirPaths = (files) => {
+    const dirs = new Set();
+    for (const f of files) {
+        let d = dirOf(f);
+        while (d !== '') {
+            dirs.add(d);
+            d = dirOf(d);
+        }
+    }
+    return [...dirs].sort((a, b) => b.split('/').length - a.split('/').length || a.localeCompare(b));
+};
+/** Build (or refresh — same operation) the knowledge tree. Reuses any previous leaf whose
+ * source hash still matches, upgrades extractive leaves when an LLM provider is available,
+ * checkpoints progress after every leaf, and finishes with a full gate sweep. A killed
+ * build resumes from its partial checkpoint on the next run. */
+export const buildTree = async (root, opts = {}) => {
+    const provider = opts.provider ?? null;
+    const critic = opts.critic ?? provider;
+    const reflexionRounds = Number.isFinite(opts.reflexionRounds) ? opts.reflexionRounds : 1;
+    const emit = opts.onProgress ?? (() => { });
+    await acquireLock(root);
+    try {
+        return await buildTreeLocked(root, opts, provider, critic, reflexionRounds, emit);
+    }
+    finally {
+        await rm(lockPath(root), { force: true });
+    }
+};
+const buildTreeLocked = async (root, opts, provider, critic, reflexionRounds, emit) => {
+    emit({ phase: 'scan' });
+    const corpusOptions = {
+        ...(opts.include ? { include: opts.include } : {}),
+        ...(Number.isFinite(opts.maxFiles) ? { maxFiles: opts.maxFiles } : {}),
+    };
+    const corpus = await loadCorpus(root, corpusOptions);
+    const files = [...corpus.files.keys()];
+    const previous = (await loadTree(partialPath(root))) ?? (await loadTree(treePath(root)));
+    const nodes = {};
+    let reusedLeaves = 0;
+    let rebuiltLeaves = 0;
+    let done = 0;
+    let checkpointFailures = 0;
+    let checkpointChain = Promise.resolve();
+    const checkpoint = () => {
+        const snapshot = {
+            version: 1,
+            name: opts.name ?? basename(root),
+            root: 'root',
+            nodes: { ...nodes },
+            corpusFiles: Object.fromEntries(files.map((f) => [f, { hash: corpus.files.get(f).hash, lines: corpus.files.get(f).lines.length }])),
+            ...(Object.keys(corpusOptions).length ? { corpusOptions } : {}),
+            builtAt: new Date().toISOString(),
+            generator: opts.generator ?? '@northtek/overstory',
+        };
+        checkpointChain = checkpointChain
+            .then(() => saveTree(partialPath(root), snapshot))
+            .catch((err) => {
+            checkpointFailures += 1;
+            emit({
+                phase: 'warn',
+                message: `checkpoint write failed (#${checkpointFailures}): ${err instanceof Error ? err.message : String(err)} — a killed build will NOT resume from this point`,
+            });
+        });
+    };
+    await mapPool(files, provider?.concurrency ?? 8, async (file) => {
+        const id = `leaf:${file}`;
+        const hash = corpus.files.get(file).hash;
+        const prior = previous?.nodes[id];
+        const reusable = prior && prior.sourceHash === hash && (prior.builtWith === 'llm' || !provider);
+        if (reusable) {
+            nodes[id] = prior;
+            reusedLeaves += 1;
+            emit({ phase: 'leaves', done: ++done, total: files.length, file, reused: true });
+            return;
+        }
+        const { claims: raw } = await summarizeFile(provider, file, corpus, id);
+        let claims = raw;
+        if (provider && critic && reflexionRounds > 0 && claims.length > 0) {
+            const refined = await refineClaims(critic, file, claims, corpus, { maxRounds: reflexionRounds });
+            claims = refined.claims;
+        }
+        nodes[id] = {
+            id,
+            kind: 'leaf',
+            path: file,
+            title: basename(file),
+            summary: claims[0]?.text ?? '',
+            claims,
+            childIds: [],
+            sourceHash: hash,
+            builtWith: provider ? 'llm' : 'extractive',
+            provider: provider?.name,
+            builtAt: new Date().toISOString(),
+        };
+        rebuiltLeaves += 1;
+        emit({ phase: 'leaves', done: ++done, total: files.length, file, reused: false });
+        checkpoint();
+    });
+    await checkpointChain;
+    // Interior nodes, deepest first; the root last. Dirs are cheap relative to leaves and are
+    // always rebuilt so roll-ups never describe stale children.
+    const dirs = dirPaths(files);
+    const childrenOf = (dir) => {
+        const leaves = files.filter((f) => dirOf(f) === dir).map((f) => nodes[`leaf:${f}`]);
+        const subdirs = dirs.filter((d) => dirOf(d) === dir && d !== dir).map((d) => nodes[`dir:${d}`]);
+        return [...subdirs, ...leaves].filter(Boolean);
+    };
+    let aggDone = 0;
+    for (const dir of dirs) {
+        const children = childrenOf(dir);
+        const id = `dir:${dir}`;
+        const claims = await aggregateClaims(provider, dir, children, id);
+        nodes[id] = {
+            id,
+            kind: 'dir',
+            path: dir,
+            title: dir.split('/').pop() ?? dir,
+            summary: claims[0]?.text ?? '',
+            claims,
+            childIds: children.map((c) => c.id),
+            builtWith: provider ? 'llm' : 'extractive',
+            provider: provider?.name,
+            builtAt: new Date().toISOString(),
+        };
+        emit({ phase: 'aggregate', done: ++aggDone, total: dirs.length + 1 });
+    }
+    const rootChildren = childrenOf('');
+    const name = opts.name ?? basename(root);
+    const rootClaims = await aggregateClaims(provider, name, rootChildren, 'root');
+    nodes['root'] = {
+        id: 'root',
+        kind: 'root',
+        path: '',
+        title: name,
+        summary: rootClaims[0]?.text ?? '',
+        claims: rootClaims,
+        childIds: rootChildren.map((c) => c.id),
+        builtWith: provider ? 'llm' : 'extractive',
+        provider: provider?.name,
+        builtAt: new Date().toISOString(),
+    };
+    emit({ phase: 'aggregate', done: dirs.length + 1, total: dirs.length + 1 });
+    const tree = {
+        version: 1,
+        name,
+        root: 'root',
+        nodes,
+        corpusFiles: Object.fromEntries(files.map((f) => [f, { hash: corpus.files.get(f).hash, lines: corpus.files.get(f).lines.length }])),
+        ...(Object.keys(corpusOptions).length ? { corpusOptions } : {}),
+        builtAt: new Date().toISOString(),
+        generator: opts.generator ?? '@northtek/overstory',
+    };
+    emit({ phase: 'verify' });
+    const verification = verifyTree(tree, corpus);
+    const finalTree = applyVerification(tree, verification);
+    emit({ phase: 'save' });
+    await saveTree(treePath(root), finalTree);
+    await rm(partialPath(root), { force: true });
+    return { tree: finalTree, verification, corpus, reusedLeaves, rebuiltLeaves, checkpointFailures };
+};
+/** Read-only verification of an existing tree against the live corpus. Applies verdicts and
+ * healed positions in-memory; never writes. Null when no tree exists. The corpus is loaded
+ * with the OPTIONS THE TREE WAS BUILT WITH (caller may override) — verifying against a
+ * differently-scoped corpus yields wrong verdicts. */
+export const verifyExisting = async (root, opts = {}) => {
+    const stored = await loadTree(treePath(root));
+    if (!stored)
+        return null;
+    const corpus = await loadCorpus(root, {
+        include: opts.include ?? stored.corpusOptions?.include,
+        maxFiles: opts.maxFiles ?? stored.corpusOptions?.maxFiles,
+    });
+    const verification = verifyTree(stored, corpus);
+    const tree = applyVerification(stored, verification);
+    const staleFiles = [...new Set(Object.values(tree.nodes)
+            .filter((n) => n.kind === 'leaf')
+            .filter((n) => n.claims.some((c) => c.verdict === 'STALE' || c.verdict === 'OUT_OF_CORPUS'))
+            .map((n) => n.path))];
+    return { tree, verification, staleFiles };
+};

package/dist/build/inmemory.d.ts

@@ -0,0 +1,16 @@
+import type { LoadedCorpus } from '../core/corpus.js';
+import type { Tree, TreeVerification } from '../core/types.js';
+import type { ChatProvider } from '../llm/provider.js';
+export interface InMemoryBuildOptions {
+    name: string;
+    provider?: ChatProvider | null;
+    generator?: string;
+}
+/** Build a complete verified tree from an in-memory corpus — no disk, no locks, no
+ * checkpoints. This is the registry's engine (serverless, deterministic when provider is
+ * null); the disk builder in builder.ts keeps its resume/checkpoint machinery for long
+ * local LLM builds. */
+export declare const buildTreeFromCorpus: (corpus: LoadedCorpus, opts: InMemoryBuildOptions) => Promise<{
+    tree: Tree;
+    verification: TreeVerification;
+}>;

package/dist/build/inmemory.js

@@ -0,0 +1,79 @@
+import { basename } from 'node:path';
+import { applyVerification, verifyTree } from '../core/gate.js';
+import { aggregateClaims } from './aggregate.js';
+import { dirOf, dirPaths } from './builder.js';
+import { summarizeFile } from './summarize.js';
+/** Build a complete verified tree from an in-memory corpus — no disk, no locks, no
+ * checkpoints. This is the registry's engine (serverless, deterministic when provider is
+ * null); the disk builder in builder.ts keeps its resume/checkpoint machinery for long
+ * local LLM builds. */
+export const buildTreeFromCorpus = async (corpus, opts) => {
+    const provider = opts.provider ?? null;
+    const files = [...corpus.files.keys()];
+    const nodes = {};
+    for (const file of files) {
+        const id = `leaf:${file}`;
+        const { claims } = await summarizeFile(provider, file, corpus, id);
+        nodes[id] = {
+            id,
+            kind: 'leaf',
+            path: file,
+            title: basename(file),
+            summary: claims[0]?.text ?? '',
+            claims,
+            childIds: [],
+            sourceHash: corpus.files.get(file).hash,
+            builtWith: provider ? 'llm' : 'extractive',
+            provider: provider?.name,
+            builtAt: new Date().toISOString(),
+        };
+    }
+    const dirs = dirPaths(files);
+    const childrenOf = (dir) => {
+        const leaves = files.filter((f) => dirOf(f) === dir).map((f) => nodes[`leaf:${f}`]);
+        const subdirs = dirs.filter((d) => dirOf(d) === dir && d !== dir).map((d) => nodes[`dir:${d}`]);
+        return [...subdirs, ...leaves].filter(Boolean);
+    };
+    for (const dir of dirs) {
+        const children = childrenOf(dir);
+        const id = `dir:${dir}`;
+        const claims = await aggregateClaims(provider, dir, children, id);
+        nodes[id] = {
+            id,
+            kind: 'dir',
+            path: dir,
+            title: dir.split('/').pop() ?? dir,
+            summary: claims[0]?.text ?? '',
+            claims,
+            childIds: children.map((c) => c.id),
+            builtWith: provider ? 'llm' : 'extractive',
+            provider: provider?.name,
+            builtAt: new Date().toISOString(),
+        };
+    }
+    const rootChildren = childrenOf('');
+    const rootClaims = await aggregateClaims(provider, opts.name, rootChildren, 'root');
+    nodes['root'] = {
+        id: 'root',
+        kind: 'root',
+        path: '',
+        title: opts.name,
+        summary: rootClaims[0]?.text ?? '',
+        claims: rootClaims,
+        childIds: rootChildren.map((c) => c.id),
+        builtWith: provider ? 'llm' : 'extractive',
+        provider: provider?.name,
+        builtAt: new Date().toISOString(),
+    };
+    const tree = {
+        version: 1,
+        name: opts.name,
+        root: 'root',
+        nodes,
+        corpusFiles: Object.fromEntries(files.map((f) => [f, { hash: corpus.files.get(f).hash, lines: corpus.files.get(f).lines.length }])),
+        builtAt: new Date().toISOString(),
+        generator: opts.generator ?? '@northtek/overstory',
+    };
+    const verification = verifyTree(tree, corpus);
+    return { tree: applyVerification(tree, verification), verification };
+};

package/dist/build/pool.d.ts

@@ -0,0 +1,3 @@
+/** Ordered concurrency-limited map. Item errors reject the whole pool — callers make
+ * per-item work non-throwing (fallbacks) before pooling. */
+export declare const mapPool: <T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>) => Promise<R[]>;

package/dist/build/pool.js

@@ -0,0 +1,16 @@
+/** Ordered concurrency-limited map. Item errors reject the whole pool — callers make
+ * per-item work non-throwing (fallbacks) before pooling. */
+export const mapPool = async (items, limit, fn) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+};

package/dist/build/reflexion.d.ts

@@ -0,0 +1,15 @@
+import type { Claim, CorpusSnapshot } from '../core/types.js';
+import type { ChatProvider } from '../llm/provider.js';
+export interface ReflexionOptions {
+    maxRounds?: number;
+}
+export interface ReflexionResult {
+    claims: Claim[];
+    rounds: number;
+    stop: 'converged' | 'max-rounds' | 'no-progress' | 'critique-failed';
+}
+/** Reflexion refinement (Shinn 2023 shape, RAIN stop discipline): critique -> apply
+ * revisions -> re-critique revised claims. UNSUPPORTED claims without a revision stay
+ * visible and flagged (abstention over confident prose, never silent deletion). A failed
+ * critique leaves faithfulness 'unchecked' — honest, not upgraded. */
+export declare const refineClaims: (provider: ChatProvider, file: string, claims: Claim[], corpus: CorpusSnapshot, opts?: ReflexionOptions) => Promise<ReflexionResult>;

package/dist/build/reflexion.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { makeSpan } from '../core/gate.js';
+import { numberedLines } from './summarize.js';
+// Local models emit `null` and empty strings for omitted fields — nullish(), never
+// optional()-only, or the whole critique silently dies at the parse (live-verified failure
+// mode: qwen2.5:14b returns "revisedStartLine": null on SUPPORTED claims).
+const critiqueSchema = z.object({
+    claims: z.array(z.object({
+        id: z.string(),
+        verdict: z.enum(['SUPPORTED', 'UNSUPPORTED']),
+        revisedText: z.string().nullish(),
+        revisedStartLine: z.number().int().min(1).nullish(),
+        revisedEndLine: z.number().int().min(1).nullish(),
+    })),
+    missing: z
+        .array(z.object({ text: z.string().nullish(), startLine: z.number().int().min(1).nullish(), endLine: z.number().int().min(1).nullish() }))
+        .nullish(),
+});
+const CRITIQUE_SYSTEM = `You are an adversarial fact-checker for a provenance-gated knowledge tree. Your job is to REFUTE claims: a claim is SUPPORTED only if a skeptical reader would agree the cited lines directly state or straightforwardly imply it. Judge only against the cited lines shown — not general knowledge. Flag overreach, speculation, and misattribution. Do not reward fluent wording.`;
+const critiquePrompt = (file, sourceLines, claims) => {
+    const claimBlock = claims
+        .map((c) => {
+        const spans = c.citations
+            .filter((x) => x.kind === 'span')
+            .map((x) => `lines ${x.span.startLine}-${x.span.endLine}`)
+            .join(', ');
+        return `- id=${c.id} [cites ${spans || 'NOTHING'}]: ${c.text}`;
+    })
+        .join('\n');
+    return `Fact-check each claim against the source. For UNSUPPORTED claims, provide a corrected revisedText + revised line range when a defensible correction exists; otherwise leave it flagged. List up to 3 important facts the claims MISS (with their line ranges).
+
+Return ONLY JSON: {"claims":[{"id":"...","verdict":"SUPPORTED"|"UNSUPPORTED","revisedText":"...?","revisedStartLine":N?,"revisedEndLine":N?}],"missing":[{"text":"...","startLine":N,"endLine":N}]}
+
+CLAIMS:
+${claimBlock}
+
+SOURCE ${file}:
+${numberedLines(sourceLines, 1)}`;
+};
+/** Reflexion refinement (Shinn 2023 shape, RAIN stop discipline): critique -> apply
+ * revisions -> re-critique revised claims. UNSUPPORTED claims without a revision stay
+ * visible and flagged (abstention over confident prose, never silent deletion). A failed
+ * critique leaves faithfulness 'unchecked' — honest, not upgraded. */
+export const refineClaims = async (provider, file, claims, corpus, opts = {}) => {
+    const maxRounds = opts.maxRounds ?? 1;
+    const entry = corpus.files.get(file);
+    if (!entry || claims.length === 0)
+        return { claims, rounds: 0, stop: 'converged' };
+    let working = claims.map((c) => ({ ...c }));
+    let previousUnchecked = -1;
+    let rounds = 0;
+    for (let round = 0; round < maxRounds; round++) {
+        const targets = working.filter((c) => c.faithfulness !== 'supported');
+        if (targets.length === 0)
+            return { claims: working, rounds, stop: 'converged' };
+        let parsed = null;
+        for (let attempt = 0; attempt < 2 && !parsed; attempt++) {
+            try {
+                const raw = await provider.chat(attempt === 0
+                    ? critiquePrompt(file, entry.lines, targets)
+                    : `${critiquePrompt(file, entry.lines, targets)}\n\nYour previous output was not valid JSON for the requested shape. Return ONLY the JSON object.`, { json: true, system: CRITIQUE_SYSTEM });
+                const first = raw.indexOf('{');
+                const last = raw.lastIndexOf('}');
+                parsed = critiqueSchema.parse(JSON.parse(first >= 0 ? raw.slice(first, last + 1) : raw));
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        if (!parsed)
+            return { claims: working, rounds, stop: 'critique-failed' };
+        rounds += 1;
+        const byId = new Map(parsed.claims.map((v) => [v.id, v]));
+        const total = entry.lines.length;
+        working = working.map((c) => {
+            const v = byId.get(c.id);
+            if (!v || c.faithfulness === 'supported')
+                return c;
+            if (v.verdict === 'SUPPORTED')
+                return { ...c, faithfulness: 'supported' };
+            const revised = v.revisedText?.trim();
+            if (revised && revised.length >= 3 && v.revisedStartLine && v.revisedEndLine && v.revisedStartLine <= total) {
+                return {
+                    ...c,
+                    text: revised,
+                    citations: [
+                        { kind: 'span', span: makeSpan(file, v.revisedStartLine, Math.min(v.revisedEndLine, total), corpus) },
+                    ],
+                    faithfulness: 'unchecked', // revision must survive its own critique
+                };
+            }
+            return { ...c, faithfulness: 'unsupported' };
+        });
+        for (const m of parsed.missing ?? []) {
+            const text = m.text?.trim();
+            if (!text || text.length < 3 || !m.startLine || !m.endLine || m.startLine > total)
+                continue;
+            const span = makeSpan(file, m.startLine, Math.min(m.endLine, total), corpus);
+            if (span.text.trim().length === 0)
+                continue; // a blank line grounds nothing
+            working.push({
+                id: `${claims[0].id.split('#')[0]}#m${working.length}`,
+                text,
+                citations: [{ kind: 'span', span }],
+                faithfulness: 'unchecked',
+            });
+        }
+        const unchecked = working.filter((c) => c.faithfulness === 'unchecked').length;
+        if (unchecked === 0)
+            return { claims: working, rounds, stop: 'converged' };
+        if (unchecked === previousUnchecked)
+            return { claims: working, rounds, stop: 'no-progress' };
+        previousUnchecked = unchecked;
+    }
+    return { claims: working, rounds, stop: 'max-rounds' };
+};

package/dist/build/summarize.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { Claim, CorpusSnapshot, SpanRef } from '../core/types.js';
+import type { ChatProvider } from '../llm/provider.js';
+declare const claimDraftSchema: z.ZodObject<{
+    text: z.ZodString;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+}, z.core.$strip>;
+export type ClaimDraft = z.infer<typeof claimDraftSchema>;
+export declare const numberedLines: (lines: string[], startLine: number) => string;
+/** Parse provider output into claim drafts. Tolerates prose-wrapped JSON. Throws on failure. */
+export declare const parseClaimDrafts: (raw: string) => ClaimDraft[];
+/** Deterministic no-LLM claims: declarations, headings, or an honest content statement.
+ * Supported-by-construction (text is derived mechanically from the cited lines). */
+export declare const extractiveClaims: (file: string, span: SpanRef, corpus: CorpusSnapshot) => Omit<Claim, 'id'>[];
+export interface SummarizeResult {
+    claims: Claim[];
+    /** True when any chunk fell back from LLM to extractive. */
+    degraded: boolean;
+}
+/** Summarize one file into claims. Provider null = pure extractive. LLM chunks that fail
+ * JSON parsing get ONE stricter retry, then fall back to extractive for that chunk — a
+ * build never dies on a bad response. */
+export declare const summarizeFile: (provider: ChatProvider | null, file: string, corpus: CorpusSnapshot, idPrefix: string) => Promise<SummarizeResult>;
+export {};

package/dist/build/summarize.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { chunkFile } from '../core/chunk.js';
+import { makeSpan } from '../core/gate.js';
+const DECL_RE = /^(export\s|function\s|class\s|def\s|async def\s|fn\s|pub\s|impl\s|interface\s|type\s|const\s|let\s|var\s|struct\s|enum\s|mod\s|module\s|public\s|private\s)/u;
+const HEADING_RE = /^(#{1,3}) (.+)$/u;
+const claimDraftSchema = z.object({
+    text: z.string().min(3),
+    startLine: z.number().int().min(1),
+    endLine: z.number().int().min(1),
+});
+const claimsSchema = z.object({ claims: z.array(claimDraftSchema).min(1).max(12) });
+export const numberedLines = (lines, startLine) => lines.map((l, i) => `${startLine + i}: ${l}`).join('\n');
+const SUMMARIZE_SYSTEM = `You are a precise code/document summarization engine inside a provenance-gated knowledge tree. Every claim you emit will be mechanically verified against the cited lines and audited by humans clicking the receipt. Emit only claims the cited lines directly support. Never speculate.`;
+const summarizePrompt = (file, span) => {
+    const lines = span.text.split('\n');
+    return `Summarize this ${file.endsWith('.md') ? 'documentation section' : 'source code'} into 3-8 atomic factual claims. Each claim must be one self-contained sentence a reader could verify by reading ONLY the cited lines.
+
+Return ONLY JSON: {"claims":[{"text":"...","startLine":N,"endLine":N}]}
+Rules: cite the NARROWEST line range that supports the claim; startLine/endLine are the absolute line numbers shown; no claim without its lines.
+
+FILE ${file} (lines ${span.startLine}-${span.endLine}):
+${numberedLines(lines, span.startLine)}`;
+};
+/** Parse provider output into claim drafts. Tolerates prose-wrapped JSON. Throws on failure. */
+export const parseClaimDrafts = (raw) => {
+    const attempt = (s) => {
+        try {
+            return claimsSchema.parse(JSON.parse(s)).claims;
+        }
+        catch {
+            return null;
+        }
+    };
+    const direct = attempt(raw);
+    if (direct)
+        return direct;
+    const first = raw.indexOf('{');
+    const last = raw.lastIndexOf('}');
+    if (first >= 0 && last > first) {
+        const inner = attempt(raw.slice(first, last + 1));
+        if (inner)
+            return inner;
+    }
+    throw new Error('unparseable claims JSON');
+};
+/** Deterministic no-LLM claims: declarations, headings, or an honest content statement.
+ * Supported-by-construction (text is derived mechanically from the cited lines). */
+export const extractiveClaims = (file, span, corpus) => {
+    const lines = span.text.split('\n');
+    const claims = [];
+    for (let i = 0; i < lines.length && claims.length < 6; i++) {
+        const abs = span.startLine + i;
+        const heading = HEADING_RE.exec(lines[i]);
+        if (heading) {
+            // Cite the whole section (to the next heading or span end, capped) so the
+            // receipt shows the evidence, not just the headline.
+            let end = i + 1;
+            while (end < lines.length && !HEADING_RE.test(lines[end]) && end - i < 12)
+                end++;
+            claims.push({
+                text: `Documents "${heading[2].trim()}".`,
+                citations: [{ kind: 'span', span: makeSpan(file, abs, span.startLine + end - 1, corpus) }],
+                faithfulness: 'supported',
+            });
+            continue;
+        }
+        if (DECL_RE.test(lines[i])) {
+            claims.push({
+                text: `Declares \`${lines[i].trim().replace(/\s*[{(=].*$/u, '').slice(0, 100)}\`.`,
+                citations: [{ kind: 'span', span: makeSpan(file, abs, abs, corpus) }],
+                faithfulness: 'supported',
+            });
+        }
+    }
+    if (claims.length === 0) {
+        const firstLine = lines.find((l) => l.trim().length > 0) ?? '';
+        claims.push({
+            text: `Contains ${lines.length} lines beginning "${firstLine.trim().slice(0, 60)}".`,
+            citations: [{ kind: 'span', span: makeSpan(file, span.startLine, span.endLine, corpus) }],
+            faithfulness: 'supported',
+        });
+    }
+    return claims;
+};
+/** Summarize one file into claims. Provider null = pure extractive. LLM chunks that fail
+ * JSON parsing get ONE stricter retry, then fall back to extractive for that chunk — a
+ * build never dies on a bad response. */
+export const summarizeFile = async (provider, file, corpus, idPrefix) => {
+    const entry = corpus.files.get(file);
+    if (!entry)
+        throw new Error(`summarizeFile: ${file} not in corpus`);
+    // An empty (or whitespace-only) file has nothing to claim. Emitting a claim over empty
+    // content would be voided by the gate anyway (empty receipts are forgeries by definition)
+    // — so don't create it. The explorer's "file is empty" state covers the rendering.
+    if (entry.lines.every((l) => l.trim() === ''))
+        return { claims: [], degraded: false };
+    const spans = chunkFile(file, entry.lines.join('\n'));
+    const out = [];
+    let degraded = false;
+    for (const span of spans) {
+        if (!provider) {
+            out.push(...extractiveClaims(file, span, corpus));
+            continue;
+        }
+        let drafts = null;
+        for (let attempt = 0; attempt < 2 && !drafts; attempt++) {
+            try {
+                const raw = await provider.chat(attempt === 0
+                    ? summarizePrompt(file, span)
+                    : `${summarizePrompt(file, span)}\n\nYour previous output was not valid JSON. Return ONLY the JSON object, nothing else.`, { json: true, system: SUMMARIZE_SYSTEM });
+                drafts = parseClaimDrafts(raw);
+            }
+            catch {
+                drafts = null;
+            }
+        }
+        if (!drafts) {
+            degraded = true;
+            out.push(...extractiveClaims(file, span, corpus));
+            continue;
+        }
+        const total = entry.lines.length;
+        const before = out.length;
+        for (const d of drafts) {
+            if (d.startLine > total || d.endLine < d.startLine)
+                continue; // hallucinated range: drop
+            const span = makeSpan(file, d.startLine, Math.min(d.endLine, total), corpus);
+            if (span.text.trim().length === 0)
+                continue; // cites a blank line: can never verify, drop now
+            out.push({
+                text: d.text.trim(),
+                citations: [{ kind: 'span', span }],
+                faithfulness: 'unchecked',
+            });
+        }
+        if (out.length === before) {
+            // Every draft had a hallucinated range — reject the batch loudly, not silently.
+            degraded = true;
+            out.push(...extractiveClaims(file, span, corpus));
+        }
+    }
+    return {
+        claims: out.map((c, i) => ({ ...c, id: `${idPrefix}#${i}` })),
+        degraded,
+    };
+};

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};