@crewhaus/provability 0.0.0-stage → 0.8.0

package/dist/private-address.js

@@ -0,0 +1,209 @@
+/**
+ * The private-address classifier, for the `cited` rung's `private_address`
+ * check (design §6.1): a citation of `http://169.254.169.254/` is not a
+ * source, however well-formed it is.
+ *
+ * The block below is the repo's ONE classifier, copied byte for byte from
+ * `@crewhaus/tool-fetch` — `apps/cli/src/tool-registry.test.ts` lists this
+ * package among the copies it sweeps, proves every copy identical and
+ * EXECUTES one. Never edit it here: change every copy at once, or none.
+ */
+// BEGIN SYNCHRONISED BLOCK — private-address classifier
+//
+// This block is BYTE-IDENTICAL across every package that guards an outbound
+// request. Do not edit one copy: `apps/cli/src/tool-registry.test.ts` hashes
+// them all and fails if any differs, and it asserts how many it found, because
+// a copy-scanning guard that matches nothing reports green.
+//
+// It exists in copies rather than a shared package because these files are
+// otherwise independent per-package networking layers; a guard proving the
+// copies are identical is cheaper and safer than the import graph a shared
+// package would need across `crawler`, `computer-use-driver` and ten tools.
+//
+// WHY IT PARSES INSTEAD OF MATCHING TEXT. Six copies were confirmed
+// exploitable on 2026-09-18 because they compared address STRINGS. The WHATWG
+// URL parser rewrites `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, so a
+// text check never sees the spelling it was written for; and `64:ff9b::a9fe:a9fe`
+// IS 169.254.169.254 on any network running DNS64/NAT64. Parsing numerically and
+// recursing into the embedded IPv4 is the only form that holds.
+//
+// WHAT IT CANNOT DO. RFC 6052 lets an operator choose any Network-Specific
+// Prefix for NAT64, so an embedded IPv4 behind an arbitrary NSP is undecidable
+// from the address alone. That case is configuration, and the callers that need
+// it resolve the host and re-check the ANSWER before dialling.
+// ---------------------------------------------------------------------------
+/**
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
+ */
+export function normalizeIpv4(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || /[^0-9a-fA-FxX.]/.test(trimmed))
+        return null;
+    const parts = trimmed.split(".");
+    if (parts.length === 0 || parts.length > 4)
+        return null;
+    const values = [];
+    for (const part of parts) {
+        if (part === "")
+            return null;
+        let value;
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            value = Number.parseInt(part.slice(2), 16);
+        else if (/^0[0-7]+$/.test(part))
+            value = Number.parseInt(part.slice(1), 8);
+        else if (/^\d+$/.test(part))
+            value = Number.parseInt(part, 10);
+        else
+            return null;
+        if (!Number.isFinite(value) || value < 0)
+            return null;
+        values.push(value);
+    }
+    // The short forms pack the remaining octets into the last part: `127.1` is
+    // 127.0.0.1, not 127.1.0.0. Getting this backwards is how a bypass survives.
+    const last = values[values.length - 1];
+    const leading = values.slice(0, -1);
+    if (leading.some((v) => v > 255))
+        return null;
+    const remaining = 4 - leading.length;
+    if (last >= 2 ** (8 * remaining))
+        return null;
+    const octets = [...leading];
+    for (let i = remaining - 1; i >= 0; i--)
+        octets.push((last >>> (8 * i)) & 0xff);
+    return octets.join(".");
+}
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export function parseIpv6(raw) {
+    let text = raw.trim().toLowerCase();
+    if (text.startsWith("["))
+        text = text.slice(1);
+    if (text.endsWith("]"))
+        text = text.slice(0, -1);
+    const zone = text.indexOf("%"); // fe80::1%eth0
+    if (zone !== -1)
+        text = text.slice(0, zone);
+    if (!text.includes(":"))
+        return null;
+    // A trailing dotted quad is the last two groups written in IPv4. Require all
+    // three dots: without that, `::1` parses as a one-part inet_aton address and
+    // takes a path that has nothing to do with what was written.
+    const dotted = /^(.*:)(\d+(?:\.\d+){3})$/.exec(text);
+    if (dotted !== null) {
+        const quad = normalizeIpv4(dotted[2]);
+        if (quad === null)
+            return null;
+        const o = quad.split(".").map((n) => Number.parseInt(n, 10));
+        const hi = (o[0] << 8) | o[1];
+        const lo = (o[2] << 8) | o[3];
+        text = `${dotted[1]}${hi.toString(16)}:${lo.toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const pieces = (part) => (part === "" ? [] : part.split(":"));
+    const head = pieces(halves[0]);
+    const tail = halves.length === 2 ? pieces(halves[1]) : [];
+    if (halves.length === 1 && head.length !== 8)
+        return null;
+    if (head.length + tail.length > 8)
+        return null;
+    const groups = [];
+    for (const piece of head) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    for (let i = head.length + tail.length; i < 8; i++)
+        groups.push(0);
+    for (const piece of tail) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    return groups.length === 8 ? groups : null;
+}
+/**
+ * The IPv4 address an IPv6 address carries, when it carries one.
+ *
+ * Every transition mechanism embeds a v4 address somewhere, and every one of
+ * them is a way to reach a v4 destination while wearing a v6 spelling that no
+ * v4 range check looks at. The NAT64 well-known prefix is the sharpest: a
+ * DNS64 resolver answers an IPv4-only name with `64:ff9b::<the v4>`, so
+ * `64:ff9b::a9fe:a9fe` IS the metadata service on any network that runs one.
+ */
+function embeddedIpv4(g) {
+    const quad = (hi, lo) => `${(hi >>> 8) & 0xff}.${hi & 0xff}.${(lo >>> 8) & 0xff}.${lo & 0xff}`;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const last = quad(g[6], g[7]);
+    if (zeros(0, 5) && g[5] === 0xffff)
+        return last; // ::ffff:0:0/96, IPv4-mapped
+    if (zeros(0, 4) && g[4] === 0xffff && g[5] === 0)
+        return last; // ::ffff:0:0:0/96, translated
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return last; // 64:ff9b::/96 and 64:ff9b:1::/48, NAT64
+    if (g[0] === 0x2002)
+        return quad(g[1], g[2]); // 2002::/16, 6to4
+    // ::a.b.c.d, IPv4-compatible: deprecated, still routed by some stacks, and
+    // not to be confused with `::` or `::1`, which are handled before this.
+    if (zeros(0, 6))
+        return last;
+    return null;
+}
+/** Ranges that are never a public RPC endpoint. */
+export function isPrivateIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null) {
+        const [a = 0, b = 0, c = 0, d = 0] = v4.split(".").map((n) => Number.parseInt(n, 10));
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local, and the metadata service
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 192 && b === 0 && c === 0)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // carrier-grade NAT
+        if (a === 198 && (b === 18 || b === 19))
+            return true; // benchmarking
+        if (a >= 224)
+            return true; // multicast, reserved, broadcast
+        return a === 255 && b === 255 && c === 255 && d === 255;
+    }
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return false;
+    if (groups.every((g) => g === 0))
+        return true; // ::, the unspecified address
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    const carried = embeddedIpv4(groups);
+    if (carried !== null)
+        return isPrivateIp(carried);
+    const head = groups[0];
+    if ((head & 0xfe00) === 0xfc00)
+        return true; // fc00::/7, unique-local
+    if ((head & 0xffc0) === 0xfe80)
+        return true; // fe80::/10, link-local
+    return (head & 0xff00) === 0xff00; // ff00::/8, multicast
+}
+// END SYNCHRONISED BLOCK

package/dist/purity.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which tools the `checked` rung may re-run (design §6.3, §10).
+ *
+ * Replay re-executes a tool with the input the log recorded and compares
+ * output digests, so it must only ever run a tool that cannot reach a
+ * network, a process or a filesystem write: the safety flags every
+ * registered tool declares already say which those are. One definition,
+ * here, so the gate's composition root and the preflight tool agree.
+ */
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+/**
+ * Pure: read-only, safe to run concurrently, not destructive, no sandbox,
+ * internal scope and no declared network or process capability. `Bash`,
+ * `Python`, every fetch and every write fail at least one of these, so none
+ * is ever replayed — a spec that lists one on `execution.allow` opts into
+ * "it ran" without "it reproduces", and the binding says `replayed: false`.
+ */
+export declare function isPureTool(tool: Pick<RegisteredTool, "readOnly" | "concurrencySafe" | "destructive" | "requiresSandbox" | "scope" | "ioCapability">): boolean;

package/dist/purity.js

@@ -0,0 +1,15 @@
+/**
+ * Pure: read-only, safe to run concurrently, not destructive, no sandbox,
+ * internal scope and no declared network or process capability. `Bash`,
+ * `Python`, every fetch and every write fail at least one of these, so none
+ * is ever replayed — a spec that lists one on `execution.allow` opts into
+ * "it ran" without "it reproduces", and the binding says `replayed: false`.
+ */
+export function isPureTool(tool) {
+    return (tool.readOnly &&
+        tool.concurrencySafe &&
+        !tool.destructive &&
+        !tool.requiresSandbox &&
+        tool.scope === "internal" &&
+        tool.ioCapability === undefined);
+}

package/dist/render.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The bundle beside the answer (design §5.4): one footer line, the JSON, the
+ * research report's `## Provability` section, and the retry nudge. Every
+ * surface renders the SAME bundle; these are its four spellings.
+ *
+ * The nudge is the one rendering the model reads, so it is the one with a
+ * trust rule (§5.1): it is composed from the model's own sentences, the
+ * evidence identifiers it cited, and fixed plain-words reasons — never from
+ * a fetched body (no excerpt) and never from judge text — so it crosses no
+ * trust boundary and needs no classification.
+ */
+import type { ProofBundle } from "./types";
+export type FooterOptions = {
+    /** Where the bundle was persisted, shown last (`.crewhaus/proofs/…/turn-7.json`). */
+    readonly path?: string;
+};
+/**
+ * One line, after the answer (design §5.4):
+ *
+ *   ── provability · grounded ✓ · 6/6 claims · 3 sources · 0 assumptions · <path>
+ *   ── provability · grounded ✗ · 4/6 claims · unmet: [2] [5] · 3 sources · 0 assumptions · <path>
+ *   ── provability · grounded ? unverified — <reason>
+ *
+ * `unmet:` lists the markers of the unmet claims' failing bindings — the
+ * reader finds them in the answer — and `+N uncited` for claims with none.
+ * Judge-waived bindings are counted separately: `6/6 claims (1 judge-waived)`,
+ * and so are refused assumptions: `3 assumptions (2 refused)`, and sources
+ * the run wrote itself: `3 sources (1 written by this run)`.
+ */
+export declare function renderFooter(bundle: ProofBundle, opts?: FooterOptions): string;
+/** The bundle as pretty-printed JSON (`render: json`, `--json`). */
+export declare function renderBundleJson(bundle: ProofBundle): string;
+/**
+ * The research report's `## Provability` section (design §5.4, §8): the
+ * floor, the verdict, the score, a table of every claim with its status,
+ * best rung and evidence, then the assumptions and the checkers whose
+ * proofs back `proven` claims, each with its formal statement beside the
+ * prose — the formalization gap shown, not hidden (§6.4).
+ */
+export declare function renderMarkdownSection(bundle: ProofBundle): string;
+/**
+ * The retry nudge (design §5.1): which claims fell short, in the model's own
+ * words, what each cited and why it did not count — and the standing
+ * instruction to run `ProvabilityPreflight` on the next draft. No excerpt,
+ * no fetched text, no judge text.
+ */
+export declare function renderNudge(bundle: ProofBundle): string;

package/dist/render.js

@@ -0,0 +1,315 @@
+import { claimReasons, clip } from "./verify";
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** An allowed assumption binding: never `ok` (it is not evidence), and not a failure either. */
+const allowedAssumption = (b) => b.kind === "assumption" && b.reason === undefined;
+/**
+ * The refs that failed in a failing answer's unmet claims (each once), and
+ * how many claims cite nothing. An allowed assumption beside failing
+ * evidence is not one of them: "[1] [A1]" with [1] wrong lists [1].
+ */
+function unmetRefs(bundle) {
+    const refs = [];
+    let uncited = 0;
+    for (const claim of bundle.claims) {
+        if (claim.status !== "unmet")
+            continue;
+        if (claim.bindings.length === 0)
+            uncited += 1;
+        for (const b of claim.bindings) {
+            if (!b.ok && !allowedAssumption(b) && !refs.includes(b.ref))
+                refs.push(b.ref);
+        }
+    }
+    return { refs, uncited };
+}
+/**
+ * Every assumption the answer rests on, accepted or refused — design §2:
+ * assumptions are always counted, so one refused (`forbid`, or past
+ * `max_assumptions`) still reads as an assumption, with how many were
+ * refused beside it: `3 assumptions (2 refused)`. The hypotheses an
+ * accepted proof rests on are assumptions too (§6.4, `hypotheses`): a
+ * proof that assumes its own conclusion does not read "0 assumptions".
+ */
+function assumptionsCount(bundle) {
+    return bundle.assumptions + (bundle.hypotheses ?? 0) + (bundle.assumptionsRefused ?? 0);
+}
+function assumptionsSegment(bundle) {
+    const refused = bundle.assumptionsRefused ?? 0;
+    const declared = plural(assumptionsCount(bundle), "assumption");
+    return refused > 0 ? `${declared} (${refused} refused)` : declared;
+}
+function claimsSegment(bundle) {
+    const counted = bundle.claimCount - bundle.assumptions;
+    let text = `${bundle.met}/${counted} ${counted === 1 ? "claim" : "claims"}`;
+    const notes = [];
+    if (bundle.vacuous !== undefined)
+        notes.push(bundle.vacuous);
+    if (bundle.judgeWaived > 0)
+        notes.push(`${bundle.judgeWaived} judge-waived`);
+    if (notes.length > 0)
+        text += ` (${notes.join(", ")})`;
+    return text;
+}
+/**
+ * One line, after the answer (design §5.4):
+ *
+ *   ── provability · grounded ✓ · 6/6 claims · 3 sources · 0 assumptions · <path>
+ *   ── provability · grounded ✗ · 4/6 claims · unmet: [2] [5] · 3 sources · 0 assumptions · <path>
+ *   ── provability · grounded ? unverified — <reason>
+ *
+ * `unmet:` lists the markers of the unmet claims' failing bindings — the
+ * reader finds them in the answer — and `+N uncited` for claims with none.
+ * Judge-waived bindings are counted separately: `6/6 claims (1 judge-waived)`,
+ * and so are refused assumptions: `3 assumptions (2 refused)`, and sources
+ * the run wrote itself: `3 sources (1 written by this run)`.
+ */
+export function renderFooter(bundle, opts = {}) {
+    const head = `── provability · ${bundle.level}`;
+    const tail = opts.path !== undefined && opts.path !== "" ? ` · ${opts.path}` : "";
+    if (bundle.verdict === "unverified") {
+        return `${head} ? unverified — ${clip(bundle.error ?? "the verifier failed", 200)}${tail}`;
+    }
+    const parts = [`${head} ${bundle.verdict === "pass" ? "✓" : "✗"}`, claimsSegment(bundle)];
+    if (bundle.verdict === "fail" || bundle.unmet > 0) {
+        const { refs, uncited } = unmetRefs(bundle);
+        const shown = refs.slice(0, 8);
+        const listed = [...shown, ...(refs.length > shown.length ? ["…"] : [])];
+        if (uncited > 0)
+            listed.push(listed.length > 0 ? `+${uncited} uncited` : `${uncited} uncited`);
+        if (listed.length > 0)
+            parts.push(`unmet: ${listed.join(" ")}`);
+    }
+    parts.push(sourcesSegment(bundle), assumptionsSegment(bundle));
+    return `${parts.join(" · ")}${tail}`;
+}
+/**
+ * "N sources", and how many of them the run wrote itself before it read
+ * them back (`selfWritten`, design §10): `2 sources (1 written by this run)`.
+ */
+function sourcesSegment(bundle) {
+    const sources = plural(bundle.sources, "source");
+    const own = bundle.selfWritten ?? 0;
+    return own > 0 ? `${sources} (${own} written by this run)` : sources;
+}
+/** The bundle as pretty-printed JSON (`render: json`, `--json`). */
+export function renderBundleJson(bundle) {
+    return JSON.stringify(bundle, null, 2);
+}
+/** A rung or reason in words: `not_fetched` → `not fetched`. */
+const words = (token) => token.replace(/_/g, " ");
+const cell = (text) => text.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+function bindingCell(b) {
+    if (allowedAssumption(b))
+        return `${b.ref} assumption`;
+    if (b.ok) {
+        const notes = [
+            ...(b.judgeWaived === true ? ["judge-waived"] : []),
+            ...(b.writtenBy !== undefined ? ["written by this run"] : []),
+        ];
+        return `${b.ref} ✓ ${b.rung}${notes.length > 0 ? ` (${notes.join(", ")})` : ""}`;
+    }
+    return `${b.ref} ✗ ${words(b.reason ?? "below_floor")}`;
+}
+function evidenceCell(claim) {
+    if (claim.bindings.length === 0)
+        return "✗ no citation";
+    const cells = claim.bindings.map(bindingCell).join("; ");
+    return claim.definition !== undefined
+        ? `${cells} (text of definition ${claim.definition})`
+        : cells;
+}
+const percent = (n) => `${Math.round(n * 100)}%`;
+/**
+ * The research report's `## Provability` section (design §5.4, §8): the
+ * floor, the verdict, the score, a table of every claim with its status,
+ * best rung and evidence, then the assumptions and the checkers whose
+ * proofs back `proven` claims, each with its formal statement beside the
+ * prose — the formalization gap shown, not hidden (§6.4).
+ */
+export function renderMarkdownSection(bundle) {
+    const lines = ["## Provability", ""];
+    const counted = bundle.claimCount - bundle.assumptions;
+    if (bundle.verdict === "unverified") {
+        lines.push(`**Floor:** \`${bundle.level}\` · **Verdict:** unverified — ${cell(bundle.error ?? "the verifier failed")}`, "", "The claims of this report were not checked: the verifier failed, so no verdict is given.");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push(`**Floor:** \`${bundle.level}\` · **Verdict:** ${bundle.verdict === "pass" ? "pass ✓" : "fail ✗"} · **Score:** ${bundle.met}/${counted} ${counted === 1 ? "claim" : "claims"} (${percent(bundle.score)}, threshold ${percent(bundle.threshold)}) · **Achieved:** \`${bundle.achieved}\``);
+    if (bundle.vacuous !== undefined)
+        lines.push("", `Vacuous pass: ${bundle.vacuous}.`);
+    if (bundle.judgeWaived > 0) {
+        lines.push("", `${plural(bundle.judgeWaived, "binding was", "bindings were")} accepted by the paraphrase-waiver judge${bundle.judgeModel !== undefined ? ` (${bundle.judgeModel})` : ""} — an opinion, not a deterministic check.`);
+    }
+    if ((bundle.selfWritten ?? 0) > 0) {
+        lines.push("", `${plural(bundle.selfWritten ?? 0, "source grounds", "sources ground")} only in text this run wrote there itself before reading it back — the run is its own source there.`);
+    }
+    if (bundle.claims.length > 0) {
+        lines.push("", "| # | Claim | Status | Best | Evidence |", "| --- | --- | --- | --- | --- |");
+        for (const claim of bundle.claims) {
+            lines.push(`| ${claim.index + 1} | ${cell(clip(claim.text, 160))} | ${claim.status} | ${claim.best} | ${cell(evidenceCell(claim))} |`);
+        }
+    }
+    // Declared assumptions, then the hypotheses each cited proof rests on.
+    const assumed = [];
+    for (const claim of bundle.claims) {
+        for (const b of claim.bindings) {
+            const refusal = b.reason !== undefined ? words(b.reason) : undefined;
+            if (b.kind === "assumption" && b.origin !== undefined) {
+                assumed.push({
+                    ref: b.ref,
+                    text: b.origin,
+                    flag: refusal !== undefined ? ` (${refusal})` : "",
+                });
+            }
+            else if (b.kind === "formal" && b.assumptions !== undefined) {
+                const of = `a hypothesis of ${b.origin ?? "the proof"}`;
+                for (const hypothesis of b.assumptions) {
+                    assumed.push({
+                        ref: b.ref,
+                        text: hypothesis,
+                        flag: ` (${refusal !== undefined ? `${of}; ${refusal}` : of})`,
+                    });
+                }
+            }
+        }
+    }
+    const refused = bundle.assumptionsRefused ?? 0;
+    lines.push("", `**Assumptions (${assumptionsCount(bundle)}${refused > 0 ? `, ${refused} refused` : ""}):**${assumed.length === 0 ? " none" : ""}`);
+    const seen = new Set();
+    for (const { ref, text, flag } of assumed) {
+        const key = `${ref} ${text}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        lines.push(`- ${ref} ${cell(text)}${flag}`);
+    }
+    if (bundle.checkers !== undefined && bundle.checkers.length > 0) {
+        lines.push("", "**Checkers:**");
+        const statements = new Map();
+        for (const claim of bundle.claims) {
+            for (const b of claim.bindings) {
+                if (b.kind === "formal" && b.origin !== undefined && b.statement !== undefined) {
+                    statements.set(b.origin, b.statement);
+                }
+            }
+        }
+        for (const checker of bundle.checkers) {
+            const statement = statements.get(checker.artifact);
+            // What the proof rests on, beside its statement (§6.4): the
+            // hypotheses, when any, then the axioms.
+            const hypotheses = checker.assumptions ?? [];
+            const assuming = hypotheses.length > 0
+                ? `assuming: ${hypotheses.map((h) => cell(clip(h, 120))).join("; ")}; `
+                : "";
+            lines.push(`- \`${checker.id}\` — ${checker.artifact}${statement !== undefined ? `: \`${cell(clip(statement, 200)).replace(/`/g, "'")}\`` : ""} (${assuming}axioms: ${checker.axioms.length === 0 ? "none" : checker.axioms.join(", ")})`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Each reason in plain words, for the nudge. ASCII only. */
+const REASON_WORDS = {
+    no_citation: "no citation - add a marker like [1] and a definition line [1]: <source> at the end of the answer",
+    no_definition: "the marker has no definition line - add one such as [1]: <source>",
+    not_locatable: "this is not a URL, a doi: or a workspace path, so it cannot be checked",
+    host_denied: "this host is not accepted as a source here (provability.sources)",
+    private_address: "a loopback, private or link-local address is not a source",
+    path_outside_workspace: "this path is outside the workspace",
+    path_missing: "this file does not exist in the workspace",
+    unresolved: "the URL did not answer a HEAD request with 2xx or 3xx",
+    not_fetched: "this run never fetched or read it - fetch or read it first, then cite it",
+    not_found_in_source: "the source was read, but the claim's words are not in it together - quote the source, or restate the claim in its words",
+    polarity_conflict: "the source has these words with a negation the claim lacks - check what it actually says",
+    not_independent: "needs more independent origins - also cite a different site that says the same",
+    tool_missing: "no tool call with this id was recorded - run the tool and cite its toolUseId",
+    tool_errored: "that tool call returned an error - rerun it and cite the successful call",
+    tool_not_allowed: "results of this tool do not count as evidence here (provability.execution.allow)",
+    value_absent: "the tool result does not contain the values the claim states - restate them exactly as the result gives them",
+    replay_mismatch: "re-running the tool with the logged input gave a different output - rerun it and cite the new call",
+    proof_missing: "no proof artifact has this id - run ProofCheck and cite the id it returns",
+    proof_rejected: "the checker rejected the proof - fix the proof or the claim",
+    claim_mismatch: "the proof is of a different statement than this sentence makes",
+    assumption_forbidden: "this assumption is not accepted (assumptions are forbidden, or there are too many) - prove the claim or drop it",
+    below_floor: "this evidence is below the floor",
+};
+/**
+ * Reasons whose `detail` the nudge repeats. Every detail the verifier writes
+ * is built from identifiers, the model's own words and checker verdicts —
+ * never a fetched body — but the nudge repeats only the ones that tell the
+ * model what to change, so what it reads stays short.
+ */
+const NUDGE_DETAIL = new Set([
+    "value_absent",
+    "not_found_in_source",
+    "proof_rejected",
+    "claim_mismatch",
+    "not_independent",
+    "below_floor",
+    "assumption_forbidden",
+    "unresolved",
+    "host_denied",
+    "tool_not_allowed",
+]);
+const MAX_NUDGE_CLAIMS = 20;
+/**
+ * Typography folded to ASCII — quotes, dashes and the ellipsis `clip` cuts
+ * with — applied to everything the nudge repeats (the model's sentences,
+ * the identifiers it cited, the verifier's details), so the nudge's own
+ * text is ASCII. Other characters of the model's own words are its own and
+ * are repeated as written.
+ */
+const ascii = (text) => text
+    .replace(/[‘’‛]/g, "'")
+    .replace(/[“”„‟]/g, '"')
+    .replace(/[—–−]/g, "-")
+    .replace(/…/g, "...");
+function nudgeLine(b) {
+    const reason = b.reason ?? "below_floor";
+    const at = b.origin !== undefined ? ` ${ascii(clip(b.origin, 160))}` : "";
+    const detail = NUDGE_DETAIL.has(reason) && b.detail !== undefined ? ` (${ascii(clip(b.detail, 300))})` : "";
+    return `   - ${b.ref}${at}: ${REASON_WORDS[reason]}${detail}`;
+}
+/**
+ * The retry nudge (design §5.1): which claims fell short, in the model's own
+ * words, what each cited and why it did not count — and the standing
+ * instruction to run `ProvabilityPreflight` on the next draft. No excerpt,
+ * no fetched text, no judge text.
+ */
+export function renderNudge(bundle) {
+    const counted = bundle.claimCount - bundle.assumptions;
+    if (bundle.verdict === "unverified") {
+        return "The provability gate could not verify your last answer (its verifier failed), so it was not graded. Keep citing every claim; run ProvabilityPreflight on your next draft.";
+    }
+    const lines = [];
+    lines.push(bundle.verdict === "pass"
+        ? `The provability gate accepted your last answer at the ${bundle.level} floor: ${bundle.met} of ${counted} claims meet it.`
+        : `The provability gate did not accept your last answer. Floor: ${bundle.level}. ${bundle.met} of ${counted} claims meet it; at least ${percent(bundle.threshold)} must.`);
+    const refused = bundle.assumptionsRefused ?? 0;
+    if (refused > 0) {
+        lines.push("", `${refused === 1 ? "1 declared assumption was" : `${refused} declared assumptions were`} refused (provability.assumptions is forbid, or there are more than provability.max_assumptions allows). A refused assumption fails the answer whatever the score: prove those claims, cite evidence for them, or drop them.`);
+    }
+    const unmet = bundle.claims.filter((claim) => claim.status === "unmet");
+    if (unmet.length > 0) {
+        lines.push("", "Claims that do not meet the floor:");
+        unmet.slice(0, MAX_NUDGE_CLAIMS).forEach((claim, i) => {
+            const where = claim.definition !== undefined
+                ? ` (the text after the source on your definition line ${claim.definition})`
+                : "";
+            lines.push(`${i + 1}. "${ascii(clip(claim.text, 200))}"${where}`);
+            if (claim.bindings.length === 0) {
+                lines.push(`   - ${REASON_WORDS[claimReasons(claim)[0] ?? "no_citation"]}`);
+                return;
+            }
+            for (const b of claim.bindings)
+                if (!b.ok && b.reason !== undefined)
+                    lines.push(nudgeLine(b));
+        });
+        if (unmet.length > MAX_NUDGE_CLAIMS) {
+            lines.push(`... and ${unmet.length - MAX_NUDGE_CLAIMS} more.`);
+        }
+    }
+    lines.push("", "Cite every claim with a marker such as [1] and close the answer with one definition line per marker: [1]: https://... (a page you fetched), ./path (a file you read), doi:..., tool:<toolUseId> (a computation you ran), proof:prf_... (a ProofCheck artifact), or assume: <text> (a declared assumption).");
+    if (unmet.some((claim) => claim.definition !== undefined)) {
+        lines.push('Text after the source on a definition line is shown to the reader, so it is checked as a claim citing that source: put a page title in quotes ([1]: https://... "Title") or leave it out.');
+    }
+    lines.push("Before you finish your next draft, run ProvabilityPreflight on it and fix every claim it reports.");
+    return lines.join("\n");
+}

package/dist/store.d.ts

@@ -0,0 +1,59 @@
+import type { ProofArtifactStore, ProofBundle } from "./types";
+/** The directory bundles of a run with no session go under. */
+export declare const NO_SESSION = "no-session";
+/** `<cwd>/.crewhaus/proofs/<specName>`: one spec's bundles and artifacts. */
+export declare function proofsRoot(cwd: string, specName: string): string;
+export type BundleListing = {
+    readonly sessionId: string;
+    readonly turnNumber: number;
+    /** Which pass of the turn: 1 for `turn-<n>.json`, k for `turn-<n>.<k>.json`. (0.8.0 additive, fix pass.) */
+    readonly pass: number;
+    readonly path: string;
+    readonly mtimeMs: number;
+};
+export interface BundleStore {
+    /** The proofs root this store writes under. */
+    readonly rootDir: string;
+    /**
+     * Persist a bundle as `<root>/<sessionId|no-session>/turn-<n>.json` — or,
+     * when a pass of that turn is already stored (a retry, a turn a resumed
+     * session numbers again), the next free `turn-<n>.<k>.json` — and return
+     * the path written. A stored bundle is never replaced: the `bundleHash`
+     * each pass's audit record and trace line carry names a bundle that is
+     * still there (design §5.3), and `provability audit` can read the
+     * failing pass a retry fixed.
+     */
+    put(bundle: ProofBundle, at: {
+        readonly sessionId?: string;
+        readonly turnNumber: number;
+    }): Promise<string>;
+    /** One pass of a turn — by default its last, the turn's standing bundle — or `undefined`. */
+    get(sessionId: string | undefined, turnNumber: number, pass?: number): Promise<ProofBundle | undefined>;
+    /** Each turn's last pass, newest first; `allPasses` lists every pass. */
+    list(opts?: {
+        readonly allPasses?: boolean;
+    }): Promise<ReadonlyArray<BundleListing>>;
+    /** Delete bundles (every pass) last written before `now - olderThanMs`; returns how many. */
+    prune(olderThanMs: number, now?: Date): Promise<number>;
+}
+/**
+ * The bundle store over a proofs root (`proofsRoot(cwd, specName)`).
+ * Tenant fencing is the caller's: on managed, pass the tenant's root.
+ */
+export declare function createBundleStore(opts: {
+    readonly rootDir: string;
+}): BundleStore;
+/**
+ * Proof artifacts under `<rootDir>/artifacts/<id>.json`, where `rootDir` is
+ * the proofs root (`proofsRoot(cwd, specName)`). An id is checked against
+ * `prf_<16 hex>` BEFORE it is put into a path: `get` answers `undefined` for
+ * any other string (a `proof:../../x` citation reads nothing), and `put`
+ * refuses one. Artifacts are immutable: `put` never replaces an existing id
+ * — a later check is a new artifact, so the one a bundle cited stays the
+ * one it was graded against.
+ */
+export declare function createFileArtifactStore(opts: {
+    readonly rootDir: string;
+}): ProofArtifactStore & {
+    readonly rootDir: string;
+};