@northtek/overstory 0.1.0

package/dist/query/ask.d.ts

@@ -0,0 +1,53 @@
+import { Bm25Index } from '../core/bm25.js';
+import type { Claim, CorpusSnapshot, Tree, Verdict } from '../core/types.js';
+import type { ChatProvider } from '../llm/provider.js';
+export interface EvidenceItem {
+    claimId: string;
+    nodeId: string;
+    nodePath: string;
+    text: string;
+    verdict?: Verdict;
+    faithfulness?: Claim['faithfulness'];
+    spans: Array<{
+        file: string;
+        startLine: number;
+        endLine: number;
+        text: string;
+    }>;
+    score: number;
+}
+export interface AnswerSentence {
+    text: string;
+    refs: string[];
+    verdict: Verdict;
+}
+export interface AskResult {
+    question: string;
+    sentences: AnswerSentence[];
+    /** Sentences the model produced that cite nothing verifiable — shown flagged, never mixed in. */
+    unverifiable: string[];
+    /** VERIFIED fraction of answer sentences, 0..1. */
+    grounding: number;
+    evidence: EvidenceItem[];
+    subqueries: string[];
+    mode: 'llm' | 'extractive';
+}
+export declare const buildClaimIndex: (tree: Tree) => {
+    index: Bm25Index;
+    byId: Map<string, {
+        claim: Claim;
+        nodeId: string;
+    }>;
+};
+/** BSHR over the tree: Brainstorm subqueries -> Search claims (BM25) -> Hypothesize an
+ * answer grounded in evidence claim ids -> Refine through the gate (every sentence
+ * re-verified transitively; unverifiable sentences quarantined, never blended in). */
+export interface AskPhaseEvent {
+    phase: 'brainstorm' | 'search' | 'write' | 'gate';
+    subqueries?: string[];
+    evidenceCount?: number;
+}
+export declare const ask: (question: string, tree: Tree, corpus: CorpusSnapshot, provider: ChatProvider | null, opts?: {
+    k?: number;
+    onPhase?: (e: AskPhaseEvent) => void;
+}) => Promise<AskResult>;

package/dist/query/ask.js

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { Bm25Index } from '../core/bm25.js';
+import { verifyClaim } from '../core/gate.js';
+const subquerySchema = z.object({ subqueries: z.array(z.string().min(2)).min(1).max(4) });
+// refs accepts evidence NUMBERS ([1]-style — reliable for small local models) or raw claim
+// ids (API-grade models); both map back to claim ids before gating.
+const answerSchema = z.object({
+    answer: z
+        .array(z.object({ text: z.string().min(3), refs: z.array(z.union([z.number().int(), z.string()])).min(1) }))
+        .min(1)
+        .max(12),
+});
+const ANSWER_SYSTEM = `You answer questions about a codebase using ONLY the verified evidence claims provided. Every sentence must cite the claim ids that support it. If the evidence cannot answer the question, say exactly that in one sentence citing the closest evidence — never fill gaps from general knowledge.`;
+export const buildClaimIndex = (tree) => {
+    const byId = new Map();
+    const index = new Bm25Index();
+    for (const node of Object.values(tree.nodes)) {
+        for (const claim of node.claims) {
+            byId.set(claim.id, { claim, nodeId: node.id });
+            index.add({ id: claim.id, text: `${claim.text} ${node.path} ${node.title}` });
+        }
+    }
+    return { index, byId };
+};
+const evidenceFor = (tree, hits, byId) => hits.map(({ id, score }) => {
+    const { claim, nodeId } = byId.get(id);
+    return {
+        claimId: id,
+        nodeId,
+        nodePath: tree.nodes[nodeId].path,
+        text: claim.text,
+        verdict: claim.verdict,
+        faithfulness: claim.faithfulness,
+        spans: claim.citations
+            .filter((c) => c.kind === 'span')
+            .map((c) => ({ file: c.span.file, startLine: c.span.startLine, endLine: c.span.endLine, text: c.span.text })),
+        score,
+    };
+});
+export const ask = async (question, tree, corpus, provider, opts = {}) => {
+    const k = opts.k ?? 8;
+    const emit = opts.onPhase ?? (() => { });
+    const { index, byId } = buildClaimIndex(tree);
+    // Brainstorm
+    emit({ phase: 'brainstorm' });
+    let subqueries = [question];
+    if (provider) {
+        try {
+            const raw = await provider.chat(`Decompose this question about a codebase into 2-4 short search subqueries (keywords, synonyms, likely file/module names). Return ONLY JSON: {"subqueries":["..."]}\n\nQuestion: ${question}`, { json: true });
+            const first = raw.indexOf('{');
+            subqueries = [question, ...subquerySchema.parse(JSON.parse(first >= 0 ? raw.slice(first, raw.lastIndexOf('}') + 1) : raw)).subqueries];
+        }
+        catch {
+            /* heuristic fallback: the question alone */
+        }
+    }
+    // Search (dedupe, best score wins)
+    emit({ phase: 'search', subqueries });
+    const merged = new Map();
+    for (const q of subqueries) {
+        for (const hit of index.search(q, k)) {
+            merged.set(hit.id, Math.max(merged.get(hit.id) ?? 0, hit.score));
+        }
+    }
+    const hits = [...merged.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, k);
+    const evidence = evidenceFor(tree, hits, byId);
+    // No provider: the verified evidence claims ARE the answer (extractive mode).
+    if (!provider) {
+        const sentences = evidence.map((e) => ({
+            text: e.text,
+            refs: [e.claimId],
+            verdict: verifyClaim(byId.get(e.claimId).claim, tree, corpus).verdict,
+        }));
+        const verified = sentences.filter((s) => s.verdict === 'VERIFIED').length;
+        return {
+            question, sentences, unverifiable: [], evidence, subqueries,
+            grounding: sentences.length === 0 ? 0 : verified / sentences.length,
+            mode: 'extractive',
+        };
+    }
+    // Hypothesize
+    emit({ phase: 'write', evidenceCount: evidence.length });
+    const evidenceBlock = evidence.map((e, i) => `[${i + 1}] (${e.nodePath || 'root'}) ${e.text}`).join('\n');
+    const sentences = [];
+    const unverifiable = [];
+    const refToClaimId = (r) => {
+        if (typeof r === 'number')
+            return evidence[r - 1]?.claimId ?? null;
+        const numeric = /^\[?(\d{1,2})\]?$/u.exec(r.trim());
+        if (numeric)
+            return evidence[Number(numeric[1]) - 1]?.claimId ?? null;
+        return byId.has(r) ? r : null;
+    };
+    try {
+        const raw = await provider.chat(`Answer the question using ONLY this numbered evidence. Every answer sentence cites the evidence numbers that support it.\n\nReturn ONLY JSON: {"answer":[{"text":"one sentence","refs":[1,2]}]}\n\nEVIDENCE:\n${evidenceBlock}\n\nQUESTION: ${question}`, { json: true, system: ANSWER_SYSTEM });
+        const first = raw.indexOf('{');
+        const parsed = answerSchema.parse(JSON.parse(first >= 0 ? raw.slice(first, raw.lastIndexOf('}') + 1) : raw));
+        // Refine: every sentence goes through the gate transitively.
+        emit({ phase: 'gate' });
+        for (const s of parsed.answer) {
+            const validRefs = [...new Set(s.refs.map(refToClaimId).filter((r) => r !== null))];
+            if (validRefs.length === 0) {
+                unverifiable.push(s.text.trim());
+                continue;
+            }
+            const composite = {
+                id: 'answer',
+                text: s.text,
+                citations: validRefs.map((r) => ({ kind: 'claim', ref: { nodeId: byId.get(r).nodeId, claimId: r } })),
+            };
+            sentences.push({ text: s.text.trim(), refs: validRefs, verdict: verifyClaim(composite, tree, corpus).verdict });
+        }
+    }
+    catch {
+        // Provider failed mid-answer: degrade to extractive honestly.
+        return { ...(await ask(question, tree, corpus, null, opts)), subqueries, mode: 'extractive' };
+    }
+    const verified = sentences.filter((s) => s.verdict === 'VERIFIED').length;
+    return {
+        question, sentences, unverifiable, evidence, subqueries,
+        grounding: sentences.length === 0 ? 0 : verified / sentences.length,
+        mode: 'llm',
+    };
+};

package/dist/query/notarize.d.ts

@@ -0,0 +1,40 @@
+import { Bm25Index } from '../core/bm25.js';
+import type { Claim, CorpusSnapshot, Tree, TreeVerification } from '../core/types.js';
+export interface NotarizeInput {
+    text: string;
+    citations: Array<{
+        file: string;
+        startLine: number;
+        endLine: number;
+    }>;
+}
+export interface NotarizedClaim {
+    text: string;
+    verdict: 'RESOLVED' | 'OUT_OF_CORPUS' | 'UNGROUNDED';
+    receipts: Array<{
+        file: string;
+        lines: string;
+        text: string;
+    } | {
+        missing: string;
+    }>;
+    corroboration: {
+        claimId: string;
+        text: string;
+        score: number;
+    } | null;
+}
+/** Mechanical notarization of externally-drafted claims (host agents, serve API):
+ * citations must resolve in the live corpus; receipt text is returned so the caller can
+ * self-check support; VERIFIED tree claims corroborate when they match. Deliberately never
+ * a claim of semantic truth — verdict names say RESOLVED, not TRUE. */
+export declare const notarizeClaims: (claims: NotarizeInput[], tree: Tree, corpus: CorpusSnapshot, verification: TreeVerification, index: Bm25Index, byId: Map<string, {
+    claim: Claim;
+    nodeId: string;
+}>) => {
+    results: NotarizedClaim[];
+    summary: {
+        resolved: number;
+        of: number;
+    };
+};

package/dist/query/notarize.js

@@ -0,0 +1,31 @@
+/** Mechanical notarization of externally-drafted claims (host agents, serve API):
+ * citations must resolve in the live corpus; receipt text is returned so the caller can
+ * self-check support; VERIFIED tree claims corroborate when they match. Deliberately never
+ * a claim of semantic truth — verdict names say RESOLVED, not TRUE. */
+export const notarizeClaims = (claims, tree, corpus, verification, index, byId) => {
+    const results = claims.map((claim) => {
+        if (claim.citations.length === 0)
+            return { text: claim.text, verdict: 'UNGROUNDED', receipts: [], corroboration: null };
+        const receipts = [];
+        let bad = false;
+        for (const c of claim.citations) {
+            const file = corpus.files.get(c.file.replace(/\\/gu, '/'));
+            if (!file || c.startLine > file.lines.length || c.endLine < c.startLine) {
+                receipts.push({ missing: `${c.file}:${c.startLine}-${c.endLine}` });
+                bad = true;
+                continue;
+            }
+            receipts.push({
+                file: c.file,
+                lines: `${c.startLine}-${Math.min(c.endLine, file.lines.length)}`,
+                text: file.lines.slice(c.startLine - 1, Math.min(c.endLine, file.lines.length)).join('\n').slice(0, 800),
+            });
+        }
+        const top = index.search(claim.text, 1)[0];
+        const corroboration = top && verification.verdicts.get(top.id) === 'VERIFIED'
+            ? { claimId: top.id, text: byId.get(top.id).claim.text, score: Number(top.score.toFixed(3)) }
+            : null;
+        return { text: claim.text, verdict: bad ? 'OUT_OF_CORPUS' : 'RESOLVED', receipts, corroboration };
+    });
+    return { results, summary: { resolved: results.filter((r) => r.verdict === 'RESOLVED').length, of: results.length } };
+};

package/dist/registry/github.d.ts

@@ -0,0 +1,28 @@
+import type { LoadedCorpus } from '../core/corpus.js';
+export interface GithubSnapshot {
+    corpus: LoadedCorpus;
+    /** Commit sha, recovered from the tarball's root directory name. */
+    sha: string;
+    ref: string;
+}
+export interface FetchOptions {
+    ref?: string;
+    maxTarballBytes?: number;
+    maxFiles?: number;
+    maxFileBytes?: number;
+    fetchImpl?: typeof fetch;
+}
+interface TarEntry {
+    name: string;
+    type: string;
+    data: Buffer;
+}
+/** Minimal ustar reader — enough for GitHub codeload tarballs. Handles pax extended
+ * headers ('x' path overrides) and skips the pax_global_header ('g'). */
+export declare const readTar: (tar: Buffer) => TarEntry[];
+/** Turn a GitHub codeload tarball into an in-memory corpus. The tarball's root directory
+ * is `{repo}-{sha}/` — the sha comes free, no API call needed. */
+export declare const snapshotFromTarball: (tarball: Buffer, ref: string, opts?: FetchOptions) => GithubSnapshot;
+/** Fetch a public GitHub repo snapshot via codeload — no git, no API token, one request. */
+export declare const fetchGithubSnapshot: (owner: string, repo: string, opts?: FetchOptions) => Promise<GithubSnapshot>;
+export {};

package/dist/registry/github.js

@@ -0,0 +1,113 @@
+import { gunzipSync } from 'node:zlib';
+import { normalizeText, sha256, splitLines } from '../core/hash.js';
+const 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',
+]);
+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 octal = (buf) => {
+    const s = buf.toString('ascii').replace(/\0/gu, '').trim();
+    return s.length === 0 ? 0 : parseInt(s, 8);
+};
+/** Minimal ustar reader — enough for GitHub codeload tarballs. Handles pax extended
+ * headers ('x' path overrides) and skips the pax_global_header ('g'). */
+export const readTar = (tar) => {
+    const entries = [];
+    let offset = 0;
+    let paxPath = null;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every((b) => b === 0))
+            break; // end-of-archive blocks
+        const rawName = header.subarray(0, 100).toString('utf8').replace(/\0.*$/u, '');
+        const prefix = header.subarray(345, 500).toString('utf8').replace(/\0.*$/u, '');
+        const size = octal(header.subarray(124, 136));
+        const type = header.subarray(156, 157).toString('ascii') || '0';
+        const dataStart = offset + 512;
+        const data = tar.subarray(dataStart, dataStart + size);
+        offset = dataStart + Math.ceil(size / 512) * 512;
+        if (type === 'x' || type === 'X') {
+            // pax extended header: records "len key=value\n"; capture a path override.
+            const text = data.toString('utf8');
+            const match = /(?:^|\n)\d+ path=([^\n]+)\n/u.exec(text);
+            paxPath = match ? match[1] : null;
+            continue;
+        }
+        if (type === 'g')
+            continue; // pax_global_header
+        const name = paxPath ?? (prefix ? `${prefix}/${rawName}` : rawName);
+        paxPath = null;
+        if (type === '0' || type === '')
+            entries.push({ name, type, data: Buffer.from(data) });
+    }
+    return entries;
+};
+const looksBinary = (buf) => buf.subarray(0, 8000).includes(0);
+/** Turn a GitHub codeload tarball into an in-memory corpus. The tarball's root directory
+ * is `{repo}-{sha}/` — the sha comes free, no API call needed. */
+export const snapshotFromTarball = (tarball, ref, opts = {}) => {
+    const maxFiles = opts.maxFiles ?? 5_000;
+    const maxFileBytes = opts.maxFileBytes ?? 1_000_000;
+    const entries = readTar(gunzipSync(tarball));
+    if (entries.length === 0)
+        throw new Error('empty tarball');
+    const rootDir = entries[0].name.split('/')[0];
+    const shaMatch = /-([0-9a-f]{7,40})$/u.exec(rootDir);
+    const sha = shaMatch ? shaMatch[1] : rootDir;
+    const files = new Map();
+    const skipped = [];
+    const sorted = entries
+        .map((e) => ({ ...e, rel: e.name.split('/').slice(1).join('/') }))
+        .filter((e) => e.rel.length > 0)
+        .sort((a, b) => a.rel.localeCompare(b.rel));
+    for (const entry of sorted) {
+        const rel = entry.rel;
+        if (rel.split('/').some((part) => EXCLUDED_DIRS.has(part)))
+            continue;
+        if (EXCLUDED_FILENAMES.has(rel.split('/').pop() ?? ''))
+            continue;
+        if (files.size >= maxFiles) {
+            skipped.push({ file: rel, reason: 'file-cap' });
+            continue;
+        }
+        if (BINARY_EXTENSIONS.test(rel) || looksBinary(entry.data)) {
+            skipped.push({ file: rel, reason: 'binary' });
+            continue;
+        }
+        if (entry.data.length > maxFileBytes) {
+            skipped.push({ file: rel, reason: 'too-large' });
+            continue;
+        }
+        const norm = normalizeText(entry.data.toString('utf8'));
+        files.set(rel, { hash: sha256(norm), lines: splitLines(norm) });
+    }
+    return { corpus: { root: `github:${ref}`, files, skipped }, sha, ref };
+};
+/** Fetch a public GitHub repo snapshot via codeload — no git, no API token, one request. */
+export const fetchGithubSnapshot = async (owner, repo, opts = {}) => {
+    if (!/^[\w.-]+$/u.test(owner) || !/^[\w.-]+$/u.test(repo))
+        throw new Error('invalid owner/repo');
+    const ref = opts.ref ?? 'HEAD';
+    if (!/^[\w][\w./-]*$/u.test(ref) || ref.includes('..'))
+        throw new Error('invalid ref');
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const maxTarballBytes = opts.maxTarballBytes ?? 40_000_000;
+    const res = await fetchImpl(`https://codeload.github.com/${owner}/${repo}/tar.gz/${ref}`, {
+        signal: AbortSignal.timeout(60_000),
+        headers: { 'user-agent': 'overstory-registry' },
+    });
+    if (res.status === 404)
+        throw new Error(`GitHub repo not found (or private): ${owner}/${repo}@${ref}`);
+    if (!res.ok)
+        throw new Error(`GitHub tarball fetch failed: HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > maxTarballBytes) {
+        throw new Error(`repo too large for the registry (${Math.round(buf.length / 1e6)}MB tarball; cap ${Math.round(maxTarballBytes / 1e6)}MB)`);
+    }
+    return snapshotFromTarball(buf, ref, opts);
+};

package/dist/registry/publishClient.d.ts

@@ -0,0 +1,25 @@
+export declare const DEFAULT_REGISTRY: string;
+/** Parse owner/repo out of any common GitHub remote form. */
+export declare const parseGithubRemote: (url: string) => {
+    owner: string;
+    repo: string;
+} | null;
+export declare const detectGithubRepo: (root: string) => Promise<{
+    owner: string;
+    repo: string;
+} | null>;
+export interface CheckResponse {
+    published: boolean;
+    source?: string;
+    sha?: string;
+    freshness?: number;
+    verified?: number;
+    claims?: number;
+    url?: string;
+    badge?: string;
+    hint?: string;
+}
+/** Zero-storage publishing: the tree lives in YOUR repo (.overstory/tree.json or a release
+ * asset). This asks the registry to fetch your tree from your repo and verify it against
+ * your code — the registry stores nothing, ever. */
+export declare const checkPublished: (registry: string, owner: string, repo: string, fetchImpl?: typeof fetch) => Promise<CheckResponse>;

package/dist/registry/publishClient.js

@@ -0,0 +1,39 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileP = promisify(execFile);
+export const DEFAULT_REGISTRY = process.env.OVERSTORY_REGISTRY ?? 'https://overstory-virid.vercel.app';
+/** Parse owner/repo out of any common GitHub remote form. */
+export const parseGithubRemote = (url) => {
+    const match = /github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/u.exec(url.trim());
+    return match ? { owner: match[1], repo: match[2] } : null;
+};
+export const detectGithubRepo = async (root) => {
+    try {
+        const { stdout } = await execFileP('git', ['remote', 'get-url', 'origin'], { cwd: root, timeout: 5_000 });
+        return parseGithubRemote(stdout);
+    }
+    catch {
+        return null;
+    }
+};
+/** Zero-storage publishing: the tree lives in YOUR repo (.overstory/tree.json or a release
+ * asset). This asks the registry to fetch your tree from your repo and verify it against
+ * your code — the registry stores nothing, ever. */
+export const checkPublished = async (registry, owner, repo, fetchImpl = fetch) => {
+    const res = await fetchImpl(`${registry.replace(/\/$/u, '')}/api/check`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(120_000),
+        headers: { 'content-type': 'application/json', 'user-agent': 'overstory-cli' },
+        body: JSON.stringify({ owner, repo }),
+    });
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        throw new Error(`registry returned HTTP ${res.status} with a non-JSON body — check OVERSTORY_REGISTRY points at the registry root`);
+    }
+    if (!res.ok && res.status !== 404)
+        throw new Error(body.error ?? `registry returned HTTP ${res.status}`);
+    return body;
+};

package/dist/registry/registry.d.ts

@@ -0,0 +1,35 @@
+import type { Tree, TreeVerification } from '../core/types.js';
+import type { GithubSnapshot } from './github.js';
+export interface InstantTreeResult {
+    tree: Tree;
+    verification: TreeVerification;
+    sha: string;
+}
+/** Deterministic, LLM-free tree for any public repo snapshot — the paste-a-URL path. */
+export declare const instantTree: (snapshot: GithubSnapshot, name: string) => Promise<InstantTreeResult>;
+export interface PublishVerdict {
+    accepted: boolean;
+    freshness: number;
+    claims: number;
+    verified: number;
+    /** Present when rejected: the receipts that failed, capped for response size. */
+    failures: Array<{
+        claimId: string;
+        text: string;
+        verdict: string;
+    }>;
+}
+/** The registry's core adjudication: an uploaded tree is accepted ONLY if every receipt
+ * verifies against the snapshot the server fetched itself from GitHub. Nothing partial is
+ * hosted — a 99% tree is a rejection with the failing 1% listed. The uploader is never
+ * trusted; the code is. */
+export declare const adjudicatePublish: (rawTree: unknown, snapshot: GithubSnapshot) => {
+    verdict: PublishVerdict;
+    tree: Tree | null;
+};
+/** Re-verification of a stored tree against a fresh snapshot (freshness decay over time). */
+export declare const reverify: (tree: Tree, snapshot: GithubSnapshot) => {
+    freshness: number;
+    verified: number;
+    claims: number;
+};

package/dist/registry/registry.js

@@ -0,0 +1,57 @@
+import { buildTreeFromCorpus } from '../build/inmemory.js';
+import { verifyTree } from '../core/gate.js';
+import { treeSchema } from '../core/store.js';
+/** Deterministic, LLM-free tree for any public repo snapshot — the paste-a-URL path. */
+export const instantTree = async (snapshot, name) => {
+    const { tree, verification } = await buildTreeFromCorpus(snapshot.corpus, {
+        name,
+        provider: null,
+        generator: '@northtek/overstory registry (extractive)',
+    });
+    return { tree, verification, sha: snapshot.sha };
+};
+/** The registry's core adjudication: an uploaded tree is accepted ONLY if every receipt
+ * verifies against the snapshot the server fetched itself from GitHub. Nothing partial is
+ * hosted — a 99% tree is a rejection with the failing 1% listed. The uploader is never
+ * trusted; the code is. */
+export const adjudicatePublish = (rawTree, snapshot) => {
+    let tree;
+    try {
+        tree = treeSchema.parse(rawTree);
+    }
+    catch {
+        return {
+            tree: null,
+            verdict: { accepted: false, freshness: 0, claims: 0, verified: 0, failures: [{ claimId: '-', text: 'tree failed schema validation', verdict: 'INVALID' }] },
+        };
+    }
+    const verification = verifyTree(tree, snapshot.corpus);
+    const failures = [];
+    if (verification.freshness < 1) {
+        for (const node of Object.values(tree.nodes)) {
+            for (const claim of node.claims) {
+                const verdict = verification.verdicts.get(claim.id);
+                if (verdict && verdict !== 'VERIFIED' && failures.length < 20) {
+                    failures.push({ claimId: claim.id, text: claim.text.slice(0, 160), verdict });
+                }
+            }
+        }
+    }
+    const verified = [...verification.verdicts.values()].filter((v) => v === 'VERIFIED').length;
+    return {
+        tree: verification.freshness === 1 ? tree : null,
+        verdict: {
+            accepted: verification.freshness === 1,
+            freshness: verification.freshness,
+            claims: verification.verdicts.size,
+            verified,
+            failures,
+        },
+    };
+};
+/** Re-verification of a stored tree against a fresh snapshot (freshness decay over time). */
+export const reverify = (tree, snapshot) => {
+    const verification = verifyTree(tree, snapshot.corpus);
+    const verified = [...verification.verdicts.values()].filter((v) => v === 'VERIFIED').length;
+    return { freshness: verification.freshness, verified, claims: verification.verdicts.size };
+};

package/dist/registry/repoTree.d.ts

@@ -0,0 +1,9 @@
+import type { Tree } from '../core/types.js';
+export interface RepoTreeResult {
+    tree: Tree;
+    source: string;
+}
+/** Fetch the tree the repo owner committed to their own repository. Null when they haven't
+ * published one (the instant extractive tree is the fallback). Schema-invalid trees are
+ * treated as absent — never rendered. */
+export declare const fetchRepoTree: (owner: string, repo: string, ref?: string, fetchImpl?: typeof fetch, maxBytes?: number) => Promise<RepoTreeResult | null>;

package/dist/registry/repoTree.js

@@ -0,0 +1,32 @@
+import { treeSchema } from '../core/store.js';
+/** Where a repo's own published tree may live — the OWNER's repo is the database; the
+ * registry stores nothing. Checked in order. */
+const candidates = (owner, repo, ref) => [
+    `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/.overstory/tree.json`,
+    `https://github.com/${owner}/${repo}/releases/latest/download/overstory-tree.json`,
+];
+/** Fetch the tree the repo owner committed to their own repository. Null when they haven't
+ * published one (the instant extractive tree is the fallback). Schema-invalid trees are
+ * treated as absent — never rendered. */
+export const fetchRepoTree = async (owner, repo, ref = 'HEAD', fetchImpl = fetch, maxBytes = 30_000_000) => {
+    for (const url of candidates(owner, repo, ref)) {
+        try {
+            const res = await fetchImpl(url, {
+                signal: AbortSignal.timeout(30_000),
+                headers: { 'user-agent': 'overstory-registry' },
+                redirect: 'follow',
+            });
+            if (!res.ok)
+                continue;
+            const text = await res.text();
+            if (text.length > maxBytes)
+                continue;
+            const tree = treeSchema.parse(JSON.parse(text));
+            return { tree, source: url.includes('raw.githubusercontent') ? '.overstory/tree.json' : 'release asset' };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+};

package/dist/serve/app.d.ts

@@ -0,0 +1,4 @@
+/** The served application shell. All data is client-fetched from /api/*; this template has
+ * zero server-side interpolation. Client JS avoids backticks entirely (template-literal
+ * safety inside this TS string). */
+export declare const appHtml: () => string;