@northtek/overstory 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { buildTree, verifyExisting } from '../build/builder.js';
+import { loadCorpus } from '../core/corpus.js';
+import { loadTree, treePath } from '../core/store.js';
+import { resolveProviders } from '../llm/resolve.js';
+import { runStdioServer } from '../mcp/server.js';
+import { serve } from '../serve/server.js';
+import { ask } from '../query/ask.js';
+import { buildSiteData } from '../site/data.js';
+import { generateSiteHtml } from '../site/generate.js';
+import { verifyTree } from '../core/gate.js';
+const HELP = `overstory — a knowledge tree of your codebase where every claim carries a receipt.
+Local-first: nothing leaves this machine.
+
+Usage:
+  overstory build  [path]   Build or refresh the tree (resumable; reuses unchanged files)
+  overstory serve  [path]   Open the app: ask your codebase, every answer notarized
+  overstory verify [path]   Check every receipt against the current code (exit 1 if any fail)
+  overstory ask "question" [path]   Answer from the tree with per-sentence receipts
+  overstory fix    [path]   Paste-ready fix prompts for your agent, grounded in receipts
+  overstory publish [path]  Publish your tree to the registry (re-verified server-side)
+  overstory site   [path]   Export the shareable single-file explorer
+  overstory mcp    [path]   Serve MCP tools over stdio (map/search/node/verify)
+
+Options:
+  --provider <auto|ollama|anthropic|none>   LLM for summaries (default auto; none = extractive)
+  --model <name>            Override the provider model
+  --rounds <n>              Reflexion critique rounds (default 1)
+  --include <glob>          Only include matching paths (repeatable)
+  --max-files <n>           Corpus cap (default 5000)
+  --out <file>              Output path for site
+  --port <n>                Port for serve (default 7433)
+  --json                    Machine-readable output
+`;
+/** A mis-typed numeric flag must error, never silently disable the cap it configures. */
+const numFlag = (raw, flag) => {
+    const n = Number(raw);
+    if (raw === undefined || !Number.isFinite(n) || n < 0) {
+        throw new Error(`${flag} requires a non-negative number (got "${raw ?? ''}")`);
+    }
+    return n;
+};
+const parseArgs = (argv) => {
+    const flags = { provider: 'auto', rounds: 1, include: [], json: false };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--json')
+            flags.json = true;
+        else if (a === '--provider')
+            flags.provider = argv[++i] ?? 'auto';
+        else if (a === '--model')
+            flags.model = argv[++i];
+        else if (a === '--rounds')
+            flags.rounds = numFlag(argv[++i], '--rounds');
+        else if (a === '--include')
+            flags.include.push(argv[++i] ?? '');
+        else if (a === '--max-files')
+            flags.maxFiles = numFlag(argv[++i], '--max-files');
+        else if (a === '--out')
+            flags.out = argv[++i];
+        else if (a === '--port')
+            flags.port = numFlag(argv[++i], '--port');
+        else if (a === '--help' || a === '-h')
+            positional.push('help');
+        else
+            positional.push(a);
+    }
+    const cmd = positional.shift() ?? 'help';
+    return { cmd, positional, flags };
+};
+const log = (msg) => {
+    process.stderr.write(`${msg}\n`);
+};
+const resolveProvider = (flags) => resolveProviders({ provider: flags.provider, model: flags.model, onNotice: log });
+const main = async () => {
+    const { cmd, positional, flags } = parseArgs(process.argv.slice(2));
+    const rootArg = positional[cmd === 'ask' ? 1 : 0];
+    const root = resolve(rootArg ?? '.');
+    if (cmd === 'help') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (rootArg !== undefined && !existsSync(root)) {
+        log(cmd === 'ask'
+            ? `path not found: ${root} — quote multi-word questions: overstory ask "your question here"`
+            : `path not found: ${root}`);
+        return 2;
+    }
+    if (cmd === 'build') {
+        const { provider, critic } = await resolveProvider(flags);
+        log(`overstory build — ${root}`);
+        log(provider ? `provider: ${provider.name} (reflexion rounds: ${flags.rounds})` : 'provider: extractive (no LLM)');
+        const started = Date.now();
+        let lastLine = '';
+        const result = await buildTree(root, {
+            provider,
+            critic,
+            reflexionRounds: flags.rounds,
+            include: flags.include.length ? flags.include : undefined,
+            maxFiles: flags.maxFiles,
+            onProgress: (e) => {
+                if (e.phase === 'leaves' && e.total) {
+                    lastLine = `  leaves ${e.done}/${e.total} ${e.reused ? '(reused) ' : ''}${e.file ?? ''}`;
+                    log(lastLine);
+                }
+                else if (e.phase === 'aggregate' && e.done === 1)
+                    log('  rolling up directories…');
+                else if (e.phase === 'verify')
+                    log('  gate sweep: verifying every receipt…');
+                else if (e.phase === 'warn')
+                    log(`  WARNING: ${e.message ?? 'unknown'}`);
+            },
+        });
+        const secs = ((Date.now() - started) / 1000).toFixed(1);
+        const pct = Math.round(result.verification.freshness * 100);
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({
+                nodes: Object.keys(result.tree.nodes).length,
+                claims: result.verification.verdicts.size,
+                freshness: result.verification.freshness,
+                reusedLeaves: result.reusedLeaves,
+                rebuiltLeaves: result.rebuiltLeaves,
+                skipped: result.corpus.skipped,
+                seconds: Number(secs),
+            }) + '\n');
+        }
+        else {
+            log(`done in ${secs}s — ${Object.keys(result.tree.nodes).length} nodes, ${result.verification.verdicts.size} claims, ${pct}% verified (${result.reusedLeaves} leaves reused, ${result.rebuiltLeaves} rebuilt)`);
+            log(`tree: ${treePath(root)}`);
+            log(`next: overstory site  ·  overstory ask "what does this repo do?"  ·  overstory mcp`);
+        }
+        return 0;
+    }
+    if (cmd === 'verify') {
+        const result = await verifyExisting(root, { include: flags.include.length ? flags.include : undefined, maxFiles: flags.maxFiles });
+        if (!result) {
+            log('No tree found (or the tree file is invalid). Run: overstory build');
+            return 2;
+        }
+        const pct = Math.round(result.verification.freshness * 100);
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({ freshness: result.verification.freshness, staleFiles: result.staleFiles }) + '\n');
+        }
+        else {
+            log(`${pct}% of claims verified against the current code`);
+            if (result.staleFiles.length > 0) {
+                log(`stale evidence in: ${result.staleFiles.join(', ')}`);
+                log('run: overstory build   (rebuilds only what changed)');
+            }
+        }
+        return result.verification.freshness === 1 ? 0 : 1;
+    }
+    if (cmd === 'ask') {
+        const question = positional[0];
+        if (!question) {
+            log('usage: overstory ask "your question" [path]');
+            return 2;
+        }
+        const tree = await loadTree(treePath(root));
+        if (!tree) {
+            log('No tree found. Run: overstory build');
+            return 2;
+        }
+        const { provider } = await resolveProvider(flags);
+        const corpus = await loadCorpus(root, tree.corpusOptions ?? {});
+        const result = await ask(question, tree, corpus, provider);
+        if (flags.json) {
+            process.stdout.write(JSON.stringify(result) + '\n');
+            return 0;
+        }
+        process.stdout.write(`\n${result.question}\n\n`);
+        for (const s of result.sentences) {
+            const refs = s.refs.map((r) => r.replace(/^leaf:/u, '')).join(', ');
+            process.stdout.write(`  [${s.verdict}] ${s.text}\n           receipts: ${refs}\n`);
+        }
+        if (result.unverifiable.length > 0) {
+            process.stdout.write(`\n  quarantined (no verifiable citation — do not trust):\n`);
+            for (const u of result.unverifiable)
+                process.stdout.write(`  [UNVERIFIABLE] ${u}\n`);
+        }
+        process.stdout.write(`\n  grounding: ${Math.round(result.grounding * 100)}% of sentences verified · mode: ${result.mode}\n`);
+        return 0;
+    }
+    if (cmd === 'site') {
+        const tree = await loadTree(treePath(root));
+        if (!tree) {
+            log('No tree found. Run: overstory build');
+            return 2;
+        }
+        const corpus = await loadCorpus(root, tree.corpusOptions ?? {});
+        const verification = verifyTree(tree, corpus);
+        const html = generateSiteHtml(buildSiteData(tree, verification, corpus));
+        const out = flags.out ?? join(root, '.overstory', 'site.html');
+        await writeFile(out, html, 'utf8');
+        log(`explorer written: ${out} (${(html.length / 1024).toFixed(0)} KB, single file, works offline)`);
+        return 0;
+    }
+    if (cmd === 'fix') {
+        const { scanFindings } = await import('../fix/scan.js');
+        const { findingsToMarkdown } = await import('../fix/prompts.js');
+        const tree = await loadTree(treePath(root));
+        if (!tree) {
+            log('No tree found. Run: overstory build   (then fix)');
+            return 2;
+        }
+        const corpus = await loadCorpus(root, tree.corpusOptions ?? {});
+        const verification = verifyTree(tree, corpus);
+        // Scan the WHOLE repo, not the tree's build scope — a scope of src/** literally cannot
+        // see tests/, which turns "untested module" into a lie.
+        const scanCorpus = tree.corpusOptions?.include
+            ? await loadCorpus(root, { maxFiles: tree.corpusOptions.maxFiles })
+            : corpus;
+        const findings = scanFindings(scanCorpus, tree, verification);
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({ findings }) + '\n');
+            return 0;
+        }
+        if (findings.length === 0) {
+            log('No findings — this tree is clean by every deterministic check.');
+            return 0;
+        }
+        const md = findingsToMarkdown(findings, tree.name);
+        const out = flags.out ?? join(root, '.overstory', 'fixes.md');
+        await writeFile(out, md, 'utf8');
+        const sev = (n) => findings.filter((f) => f.severity === n).length;
+        log(`${findings.length} findings (${sev(1)} fix-first, ${sev(2)} soon, ${sev(3)} when convenient) — each rendered as a paste-ready, receipt-grounded prompt`);
+        for (const f of findings.slice(0, 10))
+            log(`  [${f.severity === 1 ? '!' : f.severity === 2 ? '~' : '·'}] ${f.title}`);
+        if (findings.length > 10)
+            log(`  … ${findings.length - 10} more`);
+        log(`prompts: ${out}   (also in the app: overstory serve → Fixes)`);
+        return 0;
+    }
+    if (cmd === 'publish') {
+        const { DEFAULT_REGISTRY, checkPublished, detectGithubRepo } = await import('../registry/publishClient.js');
+        const tree = await loadTree(treePath(root));
+        if (!tree) {
+            log('No tree found. Run: overstory build   (then publish)');
+            return 2;
+        }
+        // Local preflight: the registry will verify against GitHub; verify here first so the
+        // instructions we print are ones that will actually succeed.
+        const local = await verifyExisting(root);
+        if (local && local.verification.freshness < 1) {
+            log(`your tree is ${Math.round(local.verification.freshness * 100)}% verified locally — run overstory build first (stale: ${local.staleFiles.join(', ')})`);
+            return 1;
+        }
+        const repoFlagIdx = process.argv.indexOf('--repo');
+        const repoFlag = repoFlagIdx >= 0 ? process.argv[repoFlagIdx + 1] : undefined;
+        const parsed = repoFlag?.includes('/')
+            ? { owner: repoFlag.split('/')[0], repo: repoFlag.split('/')[1] }
+            : await detectGithubRepo(root);
+        if (!parsed) {
+            log('Could not detect a GitHub remote. Pass --repo owner/name.');
+            return 2;
+        }
+        const registry = process.env.OVERSTORY_REGISTRY ?? DEFAULT_REGISTRY;
+        log('publishing is a git push: your repo is the database, the registry stores nothing.');
+        const result = await checkPublished(registry, parsed.owner, parsed.repo);
+        if (flags.json) {
+            process.stdout.write(JSON.stringify(result) + '\n');
+            return result.published && result.freshness === 1 ? 0 : 1;
+        }
+        if (!result.published) {
+            log('your tree is not in the repo yet. Commit and push it:');
+            log('  git add -f .overstory/tree.json');
+            log('  git commit -m "docs: overstory tree" && git push');
+            log('then run overstory publish again to confirm the registry sees it.');
+            return 1;
+        }
+        const pct = Math.round((result.freshness ?? 0) * 100);
+        log(`published (${result.source}) — ${pct}% verified against GitHub @ ${result.sha?.slice(0, 7)}`);
+        if (pct < 100)
+            log('note: your pushed code is ahead of your pushed tree — rebuild, recommit tree.json, push.');
+        if (result.url)
+            log(`hosted: ${result.url}`);
+        if (result.badge)
+            log(`badge:  ${result.badge}`);
+        return pct === 100 ? 0 : 1;
+    }
+    if (cmd === 'serve') {
+        const tree = await loadTree(treePath(root));
+        if (!tree) {
+            log('No tree found. Run: overstory build   (then serve)');
+            return 2;
+        }
+        const { provider } = await resolveProvider(flags);
+        await serve(root, {
+            provider,
+            port: flags.port,
+            onReady: (address) => {
+                log(`overstory is up: ${address}`);
+                log('ask your codebase — every answer is notarized against the code');
+                try {
+                    // best-effort browser open; the URL above is the contract
+                    import('node:child_process').then(({ spawn }) => spawn(process.platform === 'win32' ? 'cmd' : 'open', process.platform === 'win32' ? ['/c', 'start', '', address] : [address], { detached: true, stdio: 'ignore' }).unref());
+                }
+                catch {
+                    /* fine — user opens the printed URL */
+                }
+            },
+        });
+        return 0;
+    }
+    if (cmd === 'mcp') {
+        await runStdioServer(root);
+        return 0;
+    }
+    process.stdout.write(HELP);
+    return 2;
+};
+// process.exitCode (not process.exit) lets in-flight handles drain — hard exits race
+// undici/libuv teardown on Windows. The mcp command stays alive via its stdio transport.
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`overstory: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/core/bm25.d.ts

@@ -0,0 +1,19 @@
+export interface Bm25Doc {
+    id: string;
+    text: string;
+}
+export interface Bm25Hit {
+    id: string;
+    score: number;
+}
+export declare const tokenize: (text: string) => string[];
+/** Small classic BM25 — no dependencies, deterministic, fast enough for tens of
+ * thousands of claims. */
+export declare class Bm25Index {
+    private docs;
+    private df;
+    private totalLength;
+    constructor(docs?: Bm25Doc[]);
+    add(doc: Bm25Doc): void;
+    search(query: string, k?: number): Bm25Hit[];
+}

package/dist/core/bm25.js

@@ -0,0 +1,48 @@
+const K1 = 1.4;
+const B = 0.75;
+export const tokenize = (text) => text
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/u)
+    .filter((t) => t.length >= 2);
+/** Small classic BM25 — no dependencies, deterministic, fast enough for tens of
+ * thousands of claims. */
+export class Bm25Index {
+    docs = new Map();
+    df = new Map();
+    totalLength = 0;
+    constructor(docs = []) {
+        for (const d of docs)
+            this.add(d);
+    }
+    add(doc) {
+        const tokens = tokenize(doc.text);
+        this.docs.set(doc.id, { tokens, length: tokens.length });
+        this.totalLength += tokens.length;
+        for (const t of new Set(tokens))
+            this.df.set(t, (this.df.get(t) ?? 0) + 1);
+    }
+    search(query, k = 10) {
+        const qTokens = [...new Set(tokenize(query))];
+        if (qTokens.length === 0 || this.docs.size === 0)
+            return [];
+        const n = this.docs.size;
+        const avgLen = this.totalLength / n;
+        const hits = [];
+        for (const [id, { tokens, length }] of this.docs) {
+            let score = 0;
+            for (const q of qTokens) {
+                const df = this.df.get(q);
+                if (!df)
+                    continue;
+                const tf = tokens.filter((t) => t === q).length;
+                if (tf === 0)
+                    continue;
+                const idf = Math.log(1 + (n - df + 0.5) / (df + 0.5));
+                score += idf * ((tf * (K1 + 1)) / (tf + K1 * (1 - B + B * (length / (avgLen || 1)))));
+            }
+            if (score > 0)
+                hits.push({ id, score });
+        }
+        return hits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, k);
+    }
+}

package/dist/core/chunk.d.ts

@@ -0,0 +1,5 @@
+import type { SpanRef } from './types.js';
+/** Structural chunker: whole small files; markdown by top-level headings; code by
+ * column-0 declarations; fixed windows as the honest fallback. Chunks are contiguous,
+ * 1-based, inclusive, and cover the file exactly. */
+export declare const chunkFile: (file: string, raw: string) => SpanRef[];

package/dist/core/chunk.js

@@ -0,0 +1,91 @@
+import { normalizeText, sha256, splitLines } from './hash.js';
+const SINGLE_CHUNK_MAX_LINES = 400;
+const TARGET_CHUNK_LINES = 200;
+const HARD_SEGMENT_MAX_LINES = 300;
+const MARKDOWN_RE = /\.(md|mdx|markdown)$/iu;
+const HEADING_RE = /^#{1,2} /u;
+/** Top-level declaration starts across the common languages (column 0 only). */
+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|@\w)/u;
+const spanFrom = (file, lines, startLine, endLine) => {
+    const text = lines.slice(startLine - 1, endLine).join('\n');
+    return { file, startLine, endLine, text, contentHash: sha256(text) };
+};
+/** Group boundary line numbers (1-based, ascending, first must be 1) into contiguous spans,
+ * packing adjacent segments up to the target size without ever splitting a segment. */
+const packSegments = (file, lines, boundaries) => {
+    const chunks = [];
+    const total = lines.length;
+    const segments = boundaries.map((start, i) => ({
+        start,
+        end: i + 1 < boundaries.length ? boundaries[i + 1] - 1 : total,
+    }));
+    let current = null;
+    const flush = () => {
+        if (current)
+            chunks.push(spanFrom(file, lines, current.start, current.end));
+        current = null;
+    };
+    for (const seg of segments) {
+        const segLen = seg.end - seg.start + 1;
+        if (segLen > HARD_SEGMENT_MAX_LINES) {
+            // Oversized single segment: flush what we have, then window it so no chunk
+            // outgrows an LLM context.
+            flush();
+            for (let s = seg.start; s <= seg.end; s += HARD_SEGMENT_MAX_LINES) {
+                chunks.push(spanFrom(file, lines, s, Math.min(s + HARD_SEGMENT_MAX_LINES - 1, seg.end)));
+            }
+            continue;
+        }
+        if (!current) {
+            current = { ...seg };
+        }
+        else if (current.end - current.start + 1 + segLen <= TARGET_CHUNK_LINES) {
+            current.end = seg.end;
+        }
+        else {
+            flush();
+            current = { ...seg };
+        }
+    }
+    flush();
+    return chunks;
+};
+/** Structural chunker: whole small files; markdown by top-level headings; code by
+ * column-0 declarations; fixed windows as the honest fallback. Chunks are contiguous,
+ * 1-based, inclusive, and cover the file exactly. */
+export const chunkFile = (file, raw) => {
+    const norm = normalizeText(raw);
+    const lines = splitLines(norm);
+    const total = lines.length;
+    if (total === 0)
+        return [];
+    if (MARKDOWN_RE.test(file)) {
+        const headings = lines.reduce((acc, line, i) => {
+            if (HEADING_RE.test(line))
+                acc.push(i + 1);
+            return acc;
+        }, []);
+        if (headings.length > 1 || (headings.length === 1 && headings[0] !== 1)) {
+            const boundaries = headings[0] === 1 ? headings : [1, ...headings];
+            return packSegments(file, lines, boundaries).length <= 1
+                ? boundaries.map((start, i) => spanFrom(file, lines, start, i + 1 < boundaries.length ? boundaries[i + 1] - 1 : total))
+                : boundaries.map((start, i) => spanFrom(file, lines, start, i + 1 < boundaries.length ? boundaries[i + 1] - 1 : total));
+        }
+        // fall through: unstructured markdown treated like generic text
+    }
+    if (total <= SINGLE_CHUNK_MAX_LINES)
+        return [spanFrom(file, lines, 1, total)];
+    const decls = lines.reduce((acc, line, i) => {
+        if (DECL_RE.test(line))
+            acc.push(i + 1);
+        return acc;
+    }, []);
+    if (decls.length > 1) {
+        const boundaries = decls[0] === 1 ? decls : [1, ...decls];
+        return packSegments(file, lines, boundaries);
+    }
+    const windows = [];
+    for (let s = 1; s <= total; s += TARGET_CHUNK_LINES)
+        windows.push(s);
+    return packSegments(file, lines, windows);
+};

package/dist/core/corpus.d.ts

@@ -0,0 +1,21 @@
+import type { CorpusSnapshot } from './types.js';
+export interface LoadOptions {
+    /** Minimal glob filters over posix-relative paths (`*`, `**`, `?`). */
+    include?: string[];
+    maxFileBytes?: number;
+    maxFiles?: number;
+    /** Use `git ls-files` for gitignore-aware listing when the root is a repo. Default true;
+     * always falls back to the walker if git is unavailable or errors. */
+    useGit?: boolean;
+}
+export interface SkippedFile {
+    file: string;
+    reason: 'binary' | 'too-large' | 'unreadable' | 'file-cap';
+}
+export interface LoadedCorpus extends CorpusSnapshot {
+    skipped: SkippedFile[];
+}
+/** Load a corpus snapshot: gitignore-aware when possible, default excludes always,
+ * binaries and oversized files skipped with reasons, content normalized, order
+ * deterministic. */
+export declare const loadCorpus: (root: string, opts?: LoadOptions) => Promise<LoadedCorpus>;

package/dist/core/corpus.js

@@ -0,0 +1,112 @@
+import { execFile } from 'node:child_process';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { normalizeText, sha256, splitLines } from './hash.js';
+const execFileP = promisify(execFile);
+const DEFAULT_EXCLUDED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', 'target', 'vendor', 'coverage',
+    '.next', '.nuxt', '.overstory', '.cache', '__pycache__', '.venv', 'venv',
+    '.idea', '.vscode', '.turbo', '.pytest_cache',
+]);
+/** Machine-generated files that add noise, not knowledge. */
+const EXCLUDED_FILENAMES = new Set([
+    'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'Cargo.lock',
+    'poetry.lock', 'uv.lock', 'Gemfile.lock', 'composer.lock', 'go.sum',
+]);
+const BINARY_EXTENSIONS = /\.(png|jpe?g|gif|webp|ico|icns|pdf|zip|gz|tgz|bz2|7z|rar|exe|dll|so|dylib|wasm|pyd|class|jar|woff2?|ttf|otf|eot|mp[34]|mov|avi|sqlite|db|bin|pack|idx|lock)$/iu;
+const globToRegex = (glob) => {
+    const part = (p) => p
+        .replace(/[.+^${}()|[\]\\]/gu, '\\$&')
+        .replace(/\*/gu, '[^/]*')
+        .replace(/\?/gu, '.');
+    const source = glob.split('**').map(part).join('.*');
+    return new RegExp(`^${source}$`, 'u');
+};
+const listViaGit = async (root) => {
+    try {
+        const { stdout } = await execFileP('git', ['ls-files', '-co', '--exclude-standard'], {
+            cwd: root,
+            timeout: 10_000,
+            maxBuffer: 32 * 1024 * 1024,
+        });
+        const files = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+        return files.length > 0 ? files : null;
+    }
+    catch {
+        return null;
+    }
+};
+const walk = async (root, rel = '') => {
+    const abs = rel === '' ? root : join(root, rel);
+    const entries = await readdir(abs, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory()) {
+            if (DEFAULT_EXCLUDED_DIRS.has(entry.name))
+                continue;
+            files.push(...(await walk(root, childRel)));
+        }
+        else if (entry.isFile()) {
+            files.push(childRel);
+        }
+    }
+    return files;
+};
+const looksBinary = (buf) => {
+    const probe = buf.subarray(0, 8000);
+    return probe.includes(0);
+};
+/** Load a corpus snapshot: gitignore-aware when possible, default excludes always,
+ * binaries and oversized files skipped with reasons, content normalized, order
+ * deterministic. */
+export const loadCorpus = async (root, opts = {}) => {
+    // Number.isFinite (not ??): NaN from a mis-parsed flag must fall back to the safe
+    // default, never silently disable a cap.
+    const maxFileBytes = Number.isFinite(opts.maxFileBytes) ? opts.maxFileBytes : 1_000_000;
+    const maxFiles = Number.isFinite(opts.maxFiles) ? opts.maxFiles : 5_000;
+    const includeRes = opts.include?.map(globToRegex);
+    let candidates = (opts.useGit ?? true) ? await listViaGit(root) : null;
+    if (!candidates)
+        candidates = await walk(root);
+    candidates = candidates
+        .map((f) => f.replace(/\\/gu, '/'))
+        .filter((f) => !f.split('/').some((part) => DEFAULT_EXCLUDED_DIRS.has(part)))
+        .filter((f) => !EXCLUDED_FILENAMES.has(f.split('/').pop() ?? ''))
+        .sort();
+    const files = new Map();
+    const skipped = [];
+    for (const rel of candidates) {
+        if (includeRes && !includeRes.some((re) => re.test(rel)))
+            continue;
+        if (files.size >= maxFiles) {
+            skipped.push({ file: rel, reason: 'file-cap' });
+            continue;
+        }
+        if (BINARY_EXTENSIONS.test(rel)) {
+            skipped.push({ file: rel, reason: 'binary' });
+            continue;
+        }
+        try {
+            const info = await stat(join(root, rel));
+            if (info.size > maxFileBytes) {
+                skipped.push({ file: rel, reason: 'too-large' });
+                continue;
+            }
+            const buf = await readFile(join(root, rel));
+            if (looksBinary(buf)) {
+                skipped.push({ file: rel, reason: 'binary' });
+                continue;
+            }
+            const norm = normalizeText(buf.toString('utf8'));
+            files.set(rel, { hash: sha256(norm), lines: splitLines(norm) });
+        }
+        catch {
+            skipped.push({ file: rel, reason: 'unreadable' });
+        }
+    }
+    return { root, files, skipped };
+};

package/dist/core/gate.d.ts

@@ -0,0 +1,25 @@
+import type { Claim, ClaimVerification, CorpusSnapshot, SpanRef, SpanVerification, Tree, TreeVerification } from './types.js';
+/** Builder-side helper: cite lines start..end (1-based, inclusive) of a file as it
+ * currently exists in the corpus. Throws if the file is absent — you cannot honestly
+ * cite what you cannot see. */
+export declare const makeSpan: (file: string, startLine: number, endLine: number, corpus: CorpusSnapshot) => SpanRef;
+/** Mechanical span verification against the live corpus. Assumes an internally
+ * consistent receipt (text/hash agreement is enforced upstream in verifyClaim).
+ * Self-heals when the cited text merely moved (edits above the span). */
+export declare const verifySpan: (span: SpanRef, corpus: CorpusSnapshot) => SpanVerification;
+/** Fail-closed claim verification. A claim is VERIFIED only when every citation
+ * verifies. Any internally inconsistent receipt (text/hash mismatch — a forgery or
+ * corruption) voids the claim's grounding entirely: UNGROUNDED. Interior claims
+ * (citing child claims) verify transitively; staleness propagates upward.
+ *
+ * `path` holds only the claims on the CURRENT recursion path (backtracked on return):
+ * true cycles fail closed, while duplicate citations of the same evidence — a common
+ * LLM habit — and diamond-shaped grounding verify correctly. Duplicate refs within one
+ * claim are verified once (evidence is idempotent). */
+export declare const verifyClaim: (claim: Claim, tree: Tree, corpus: CorpusSnapshot, path?: Set<string>) => ClaimVerification;
+/** Verify every claim in the tree. Freshness is the VERIFIED fraction (1.0 for an
+ * empty tree — nothing claimed, nothing wrong). */
+export declare const verifyTree: (tree: Tree, corpus: CorpusSnapshot) => TreeVerification;
+/** Write verdicts + healed span positions back into a (copied) tree. Healing updates only
+ * line numbers — text and hash are untouched, so the receipt itself never changes. */
+export declare const applyVerification: (tree: Tree, verification: TreeVerification) => Tree;