@crewhaus/tool-proof 0.0.0-stage → 0.8.1

package/dist/lib/check.js

@@ -0,0 +1,260 @@
+import { sha256Of } from "@crewhaus/provability";
+/**
+ * Input bounds. The statement and proof bounds are the largest any shipped
+ * checker accepts (`BUILTIN_LIMITS.maxStatementChars`, `.maxProofChars`), so
+ * the schema never refuses what a checker would take; each checker applies
+ * its own tighter limit and says so. A claim is one sentence of an answer.
+ */
+export const PROOF_INPUT_LIMITS = {
+    checkerChars: 64,
+    claimChars: 2_000,
+    statementChars: 20_000,
+    proofChars: 1_000_000,
+};
+/** Checker output kept in an artifact (proof-checker's "a few KB"). */
+export const OUTPUT_CHARS = 4_000;
+/** A counterexample or a reason, as recorded. */
+const DETAIL_CHARS = 2_000;
+/**
+ * The most UTF-8 bytes a proof tool's report may be. The runtime spills any
+ * tool result over 10 KB (`@crewhaus/tool-result-store`'s
+ * `DEFAULT_THRESHOLD_BYTES`, 10 240) to a file and shows the model only its
+ * first 10 KB, so a report past that loses its tail — and the tail is where
+ * a JSON report's instructions would sit. Every report is cut to fit under
+ * it, with the instructions placed first, so the model always reads the
+ * whole of it.
+ */
+export const REPORT_BYTES = 9_000;
+/** How a ProofCheck report spends its bytes; `output` gets what is left. */
+const REPORT_REASON_BYTES = 1_200;
+const REPORT_COUNTEREXAMPLE_BYTES = 1_800;
+const REPORT_LIST_BYTES = 2_400;
+/** One assumption or axiom as listed (the artifact keeps each whole). */
+const LISTED_CHARS = 300;
+/**
+ * How much longer than `formal.timeoutMs` one check may take before it is
+ * recorded as a rejection: a container start and the checker's own
+ * reporting. The sandbox checkers stop themselves at `formal.timeoutMs`;
+ * this is the backstop for a plugin checker that never settles.
+ */
+export const CHECK_GRACE_MS = 30_000;
+/** Keep the head and the tail of long text, marking the cut. */
+export function clipMiddle(text, cap) {
+    if (text.length <= cap)
+        return text;
+    const head = text.slice(0, Math.floor(cap * 0.7));
+    const tail = text.slice(text.length - Math.floor(cap * 0.25));
+    return `${head}\n… ${text.length - head.length - tail.length} characters omitted …\n${tail}`;
+}
+/** Text clipped to `cap` characters, an ellipsis marking the cut. */
+export function clip(text, cap) {
+    return text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
+}
+/** The UTF-8 bytes `value` takes in a compact JSON report. */
+export function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+}
+/**
+ * `text` cut (by `cut`, `clipMiddle` by default) until it takes at most
+ * `maxBytes` as a JSON string. Measured, not estimated: escaping turns a
+ * newline into two bytes and a control character into six, and a character
+ * can take three bytes of UTF-8. Empty when not even the cut marker fits.
+ */
+export function fitText(text, maxBytes, cut = clipMiddle) {
+    if (jsonBytes(text) <= maxBytes)
+        return text;
+    let cap = text.length;
+    for (let attempt = 0; attempt < 12 && cap > 0; attempt++) {
+        const candidate = cut(text, cap);
+        const size = jsonBytes(candidate);
+        if (size <= maxBytes)
+            return candidate;
+        cap = Math.min(cap - 1, Math.floor((cap * maxBytes) / size) - 8);
+    }
+    return "";
+}
+const strings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+const text = (value) => typeof value === "string" && value.trim() !== "" ? value : undefined;
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+const CANCELLED = Symbol("cancelled");
+const TIMED_OUT = Symbol("timed out");
+/**
+ * Run `checker` and return a well-formed `CheckResult`, whatever it does.
+ * A checker that throws has not proved anything: the result is a rejection
+ * whose reason names the failure, and it is persisted like any rejection.
+ * So is one that does not settle within `timeoutMs`. An abort of `signal`
+ * stops the wait too, with a rejection the caller recognises by the aborted
+ * signal and does not save. Neither stops a checker that ignores its signal
+ * — nothing can — but the call returns, so one hung plugin cannot hang the
+ * turn.
+ */
+export async function runChecker(checker, input, opts = {}) {
+    const { signal, timeoutMs } = opts;
+    const started = performance.now();
+    const elapsed = () => Math.round(performance.now() - started);
+    const rejection = (reason) => ({
+        ok: false,
+        checker: checker.id,
+        assumptions: [],
+        axioms: [],
+        output: "",
+        reason,
+        durationMs: elapsed(),
+    });
+    if (signal?.aborted === true)
+        return rejection("the check was cancelled");
+    let timer;
+    let onAbort;
+    const stops = [];
+    if (signal !== undefined) {
+        stops.push(new Promise((resolve) => {
+            onAbort = () => resolve(CANCELLED);
+            signal.addEventListener("abort", onAbort, { once: true });
+        }));
+    }
+    if (timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs >= 0) {
+        stops.push(new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+        }));
+    }
+    let raw;
+    try {
+        // `Promise.race` subscribes to the check, so one that rejects after the
+        // race was decided is handled, not an unhandled rejection.
+        raw = await Promise.race([
+            Promise.resolve().then(() => checker.check({
+                claim: input.claim,
+                statement: input.statement,
+                proof: input.proof,
+                ...(signal !== undefined ? { signal } : {}),
+            })),
+            ...stops,
+        ]);
+    }
+    catch (err) {
+        return rejection(`the ${checker.id} checker failed: ${clip(errorMessage(err), 300)}`);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort !== undefined)
+            signal?.removeEventListener("abort", onAbort);
+    }
+    if (raw === CANCELLED)
+        return rejection("the check was cancelled");
+    if (raw === TIMED_OUT) {
+        return rejection(`the ${checker.id} checker did not finish within ${timeoutMs} ms, so nothing was proved`);
+    }
+    const r = (typeof raw === "object" && raw !== null ? raw : {});
+    const reason = text(r["reason"]);
+    const counterexample = text(r["counterexample"]);
+    const duration = r["durationMs"];
+    const ok = r["ok"] === true;
+    return {
+        ok,
+        checker: checker.id,
+        assumptions: strings(r["assumptions"]),
+        axioms: strings(r["axioms"]),
+        output: typeof r["output"] === "string" ? r["output"] : "",
+        ...(reason !== undefined
+            ? { reason }
+            : ok
+                ? {}
+                : { reason: `the ${checker.id} checker did not accept the proof` }),
+        ...(counterexample !== undefined ? { counterexample } : {}),
+        durationMs: typeof duration === "number" && Number.isFinite(duration) && duration >= 0
+            ? Math.round(duration)
+            : elapsed(),
+    };
+}
+/**
+ * The artifact for one check — accepted or rejected alike: a rejected proof
+ * is persisted too, because proof pressure is signal (the `action_proof`
+ * rule from tool-plan), and `proof_rejected` in a bundle can then name the
+ * checker's reason. The `checker` is the id the model asked for, which is
+ * the registry's identity for the checker that ran.
+ */
+export function toArtifact(args) {
+    const { result } = args;
+    const output = clipMiddle(result.output, OUTPUT_CHARS);
+    return {
+        version: 1,
+        id: args.id,
+        checker: args.checker.id,
+        claim: args.input.claim,
+        statement: args.input.statement,
+        proof: args.input.proof,
+        ok: result.ok,
+        assumptions: [...result.assumptions],
+        axioms: [...result.axioms],
+        output,
+        ...(result.counterexample !== undefined
+            ? { counterexample: clip(result.counterexample, DETAIL_CHARS) }
+            : {}),
+        ...(result.reason !== undefined ? { reason: clip(result.reason, DETAIL_CHARS) } : {}),
+        outputDigest: sha256Of(output),
+        checkedAt: args.checkedAt.toISOString(),
+        durationMs: result.durationMs,
+    };
+}
+/** The `proof_checked` payload: the trace event's fields, and the event-log line's whole payload. */
+export function proofCheckedFields(artifact) {
+    return {
+        checker: artifact.checker,
+        ok: artifact.ok,
+        artifactId: artifact.id,
+        durationMs: artifact.durationMs ?? 0,
+        axioms: [...artifact.axioms],
+    };
+}
+/** The marker a ProofCheck report's lists end with: the artifact keeps every item. */
+const keptInArtifact = (rest) => `… and ${rest} more (the artifact keeps them all)`;
+/**
+ * As many of `items` as fit in `maxBytes`, each clipped to `itemChars`, in
+ * order, then `more(n)` counting the n left out — which the caller says
+ * where to find (the artifact keeps a ProofCheck's whole).
+ */
+export function listed(items, maxBytes, more = keptInArtifact, itemChars = LISTED_CHARS) {
+    const shown = [];
+    // Room for the marker, so adding it never breaks the budget.
+    const reserve = jsonBytes(more(items.length)) + 1;
+    let used = 2; // the brackets
+    for (const item of items) {
+        const cell = clip(item, itemChars);
+        const cost = jsonBytes(cell) + (shown.length > 0 ? 1 : 0);
+        if (used + cost + (shown.length + 1 < items.length ? reserve : 0) > maxBytes)
+            break;
+        shown.push(cell);
+        used += cost;
+    }
+    const rest = items.length - shown.length;
+    return rest > 0 ? [...shown, more(rest)] : shown;
+}
+/**
+ * What the model reads back: the verdict, the artifact id and one
+ * instruction — how to cite it, or what to do instead — first, then why
+ * (reason, counterexample), what the proof rests on and the checker's
+ * output. The whole report fits in {@link REPORT_BYTES}, the output taking
+ * what the rest leaves; the artifact keeps everything whole.
+ */
+export function checkReport(artifact) {
+    const next = artifact.ok
+        ? `cite it as [n]: proof:${artifact.id} — put [n] on the sentence that states this claim, with the same words, figures and polarity, or the gate reports claim_mismatch`
+        : `not proven, so this artifact cannot back a claim (the gate reports proof_rejected)${artifact.counterexample !== undefined ? "; the counterexample shows where it fails" : ""} — fix the statement or the proof and run ProofCheck again, or do not state the claim`;
+    const head = {
+        ok: artifact.ok,
+        id: artifact.id,
+        checker: artifact.checker,
+        next,
+        ...(artifact.reason !== undefined
+            ? { reason: fitText(artifact.reason, REPORT_REASON_BYTES) }
+            : {}),
+        ...(artifact.counterexample !== undefined
+            ? { counterexample: fitText(artifact.counterexample, REPORT_COUNTEREXAMPLE_BYTES) }
+            : {}),
+    };
+    const assumptions = listed(artifact.assumptions, REPORT_LIST_BYTES / 2);
+    const axioms = listed(artifact.axioms, REPORT_LIST_BYTES - jsonBytes(assumptions));
+    const rest = REPORT_BYTES - jsonBytes({ ...head, assumptions, axioms, output: "" });
+    return { ...head, assumptions, axioms, output: fitText(artifact.output, rest) };
+}

package/dist/lib/checkers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The proof checkers a harness proves with, and what `ProofCheckers` says
+ * about each (design §6.4, §7).
+ *
+ * The checkers come from `@crewhaus/proof-checker`'s `createDefaultCheckers`
+ * in the configured preference order (`formal.checkers`), with the builtin
+ * certificate checker always among them: it needs no sandbox, so a harness
+ * can always prove something. The sandbox checkers (`smt`, `lean4`) are
+ * always LISTED when configured — with no sandbox they say why in
+ * `available()` and refuse in `check()` — so the model sees what it could
+ * prove with and why it cannot right now, instead of a checker silently
+ * missing (the registry's own rule).
+ *
+ * The sandbox is created lazily, on the first call that needs the checkers,
+ * the way tool-code-execution creates its own: importing the package (the
+ * CLI imports every tool package) must not touch a container runtime.
+ */
+import { type CheckerAvailability, type ProofChecker, type SandboxLike } from "@crewhaus/proof-checker";
+import type { ProvabilityConfig } from "@crewhaus/provability";
+/** The id of the checker that is always present. */
+export declare const BUILTIN_ID = "builtin";
+/**
+ * How long `ProofCheckers` waits on one checker's `available()`. The sandbox
+ * checkers bound their own probe (a cold image pull is slow, so 20 s), and
+ * remember the answer; this is the backstop for a plugin checker that never
+ * answers, so one hung probe cannot hang the listing.
+ */
+export declare const AVAILABILITY_TIMEOUT_MS = 30000;
+/** One checker as `ProofCheckers` reports it. */
+export type CheckerListing = {
+    readonly id: string;
+    readonly available: boolean;
+    /** Why it cannot run here, when it cannot. */
+    readonly reason?: string;
+    /** The checker's own paragraph on its statement language. */
+    readonly language: string;
+};
+/**
+ * `checker.available()`, bounded and total: a throw, a malformed answer or
+ * no answer within `timeoutMs` reads as unavailable, with the reason.
+ */
+export declare function probeChecker(checker: ProofChecker, timeoutMs?: number): Promise<CheckerAvailability>;
+/** Every checker with its probed availability, in preference order. Probes run in parallel. */
+export declare function listCheckers(checkers: ReadonlyArray<ProofChecker>, timeoutMs?: number): Promise<CheckerListing[]>;
+/** `formal.checkers` in order, with the builtin appended when the config left it out. */
+export declare function defaultCheckerIds(config: ProvabilityConfig): string[];
+/** The container images the configured sandbox checkers run (what the sandbox must allow). */
+export declare function sandboxImages(config: ProvabilityConfig): string[];
+export type DefaultCheckerDeps = {
+    /** Whether a container sandbox may be used (CREWHAUS_SANDBOX, or the loop said one is wired). */
+    readonly sandboxAvailable: boolean;
+    /** Build the sandbox; `@crewhaus/sandbox`'s `createSandbox` in production. */
+    readonly createSandbox: (opts: {
+        readonly allowedImages: ReadonlyArray<string>;
+    }) => SandboxLike;
+};
+/**
+ * The default checkers for `config`: `formal.checkers` in order plus the
+ * builtin, with a sandbox for the sandbox checkers when one is available.
+ * Without one they are present and unavailable, saying why.
+ */
+export declare function buildDefaultCheckers(config: ProvabilityConfig, deps: DefaultCheckerDeps): ProofChecker[];

package/dist/lib/checkers.js

@@ -0,0 +1,136 @@
+/**
+ * The proof checkers a harness proves with, and what `ProofCheckers` says
+ * about each (design §6.4, §7).
+ *
+ * The checkers come from `@crewhaus/proof-checker`'s `createDefaultCheckers`
+ * in the configured preference order (`formal.checkers`), with the builtin
+ * certificate checker always among them: it needs no sandbox, so a harness
+ * can always prove something. The sandbox checkers (`smt`, `lean4`) are
+ * always LISTED when configured — with no sandbox they say why in
+ * `available()` and refuse in `check()` — so the model sees what it could
+ * prove with and why it cannot right now, instead of a checker silently
+ * missing (the registry's own rule).
+ *
+ * The sandbox is created lazily, on the first call that needs the checkers,
+ * the way tool-code-execution creates its own: importing the package (the
+ * CLI imports every tool package) must not touch a container runtime.
+ */
+import { DEFAULT_LEAN4_IMAGE, DEFAULT_SMT_IMAGE, createDefaultCheckers, } from "@crewhaus/proof-checker";
+/** The id of the checker that is always present. */
+export const BUILTIN_ID = "builtin";
+/**
+ * How long `ProofCheckers` waits on one checker's `available()`. The sandbox
+ * checkers bound their own probe (a cold image pull is slow, so 20 s), and
+ * remember the answer; this is the backstop for a plugin checker that never
+ * answers, so one hung probe cannot hang the listing.
+ */
+export const AVAILABILITY_TIMEOUT_MS = 30_000;
+const message = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * `checker.available()`, bounded and total: a throw, a malformed answer or
+ * no answer within `timeoutMs` reads as unavailable, with the reason.
+ */
+export async function probeChecker(checker, timeoutMs = AVAILABILITY_TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({
+            ok: false,
+            reason: `the ${checker.id} checker did not say whether it can run within ${timeoutMs} ms`,
+        }), timeoutMs);
+    });
+    try {
+        const answer = await Promise.race([
+            Promise.resolve()
+                .then(() => checker.available())
+                .catch((err) => ({
+                ok: false,
+                reason: `the ${checker.id} checker's availability probe failed: ${message(err)}`,
+            })),
+            timeout,
+        ]);
+        if (typeof answer !== "object" || answer === null || typeof answer.ok !== "boolean") {
+            return { ok: false, reason: `the ${checker.id} checker gave no availability answer` };
+        }
+        if (answer.ok)
+            return { ok: true };
+        return {
+            ok: false,
+            reason: typeof answer.reason === "string" && answer.reason.trim() !== ""
+                ? answer.reason
+                : `the ${checker.id} checker cannot run here`,
+        };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Every checker with its probed availability, in preference order. Probes run in parallel. */
+export async function listCheckers(checkers, timeoutMs = AVAILABILITY_TIMEOUT_MS) {
+    return Promise.all(checkers.map(async (checker) => {
+        const availability = await probeChecker(checker, timeoutMs);
+        return {
+            id: checker.id,
+            available: availability.ok,
+            ...(availability.ok ? {} : { reason: availability.reason }),
+            language: typeof checker.language === "string" ? checker.language : "",
+        };
+    }));
+}
+/** `formal.checkers` in order, with the builtin appended when the config left it out. */
+export function defaultCheckerIds(config) {
+    const ids = [...new Set(config.formal.checkers)];
+    return ids.includes(BUILTIN_ID) ? ids : [...ids, BUILTIN_ID];
+}
+/** The container images the configured sandbox checkers run (what the sandbox must allow). */
+export function sandboxImages(config) {
+    const ids = defaultCheckerIds(config);
+    const images = [];
+    if (ids.includes("smt"))
+        images.push(DEFAULT_SMT_IMAGE);
+    // `formal.image` is the lean4 override (the Mathlib case) — proof-checker's
+    // reading of the spec key, which the gate's composition root shares.
+    if (ids.includes("lean4"))
+        images.push(config.formal.image ?? DEFAULT_LEAN4_IMAGE);
+    return images;
+}
+/**
+ * A sandbox that could not be built stands in as one whose every exec
+ * throws the reason: the sandbox checkers' probe then reports WHY ("could
+ * not be probed: CREWHAUS_SANDBOX=… is not a sandbox backend") instead of
+ * the generic "no sandbox is configured".
+ */
+function brokenSandbox(err) {
+    const reason = message(err);
+    return {
+        backend: "unavailable",
+        async exec() {
+            throw new Error(`the sandbox could not be created: ${reason}`);
+        },
+    };
+}
+/**
+ * The default checkers for `config`: `formal.checkers` in order plus the
+ * builtin, with a sandbox for the sandbox checkers when one is available.
+ * Without one they are present and unavailable, saying why.
+ */
+export function buildDefaultCheckers(config, deps) {
+    const ids = defaultCheckerIds(config);
+    const images = sandboxImages(config);
+    let sandbox;
+    if (images.length > 0 && deps.sandboxAvailable) {
+        try {
+            sandbox = deps.createSandbox({ allowedImages: images });
+        }
+        catch (err) {
+            sandbox = brokenSandbox(err);
+        }
+    }
+    return createDefaultCheckers({
+        ids,
+        timeoutMs: config.formal.timeoutMs,
+        forbid: config.formal.forbid,
+        ...(config.formal.image !== undefined ? { images: { lean4: config.formal.image } } : {}),
+        ...(sandbox !== undefined ? { sandbox } : {}),
+    });
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The configuration the proof tools run under when nobody hands them one.
+ *
+ * The composition root (`@crewhaus/evaluation-service`) builds the tools with
+ * the spec's lowered `provability:` block, so the gate and the tools agree on
+ * the floor, the checkers, the artifacts root and the evidence. The builtin
+ * instances — what a spec gets by listing `proofCheck` in `tools:` with no
+ * `provability:` block — have no block to read, so they run under the
+ * compiler's own defaults at the `grounded` floor: the values
+ * `lowerProvability` resolves for a bare `provability: grounded`
+ * (packages/compiler/src/index.ts, the IrProvability doc in
+ * packages/ir/src/index.ts). Copied rather than imported: a tool package
+ * does not import the compiler.
+ */
+import { type ProvabilityConfig } from "@crewhaus/provability";
+/** The floor the builtin instances preflight against (design §7). */
+export declare const DEFAULT_FLOOR: "grounded";
+/**
+ * `execution.allow`'s default, before the category grammar expands it
+ * (compiler `PROVABILITY_DEFAULT_EXECUTION_ALLOW`): the read-only computations
+ * and gates, less the one destructive verify tool (design §6.3).
+ * `apps/cli/src/provability-default-allow.test.ts` holds the two copies equal.
+ */
+export declare const DEFAULT_EXECUTION_SELECTORS: ReadonlyArray<string>;
+/** The spec name proofs are filed under when neither the caller nor the run names one. */
+export declare const DEFAULT_SPEC_NAME = "default";
+/**
+ * The lowered defaults at the `grounded` floor. Built on call, not at import:
+ * the expansion walks the category registry, and the CLI imports every tool
+ * package whether a spec lists it or not.
+ */
+export declare function defaultProvabilityConfig(): ProvabilityConfig;
+/**
+ * A config handed in by a caller, checked once at construction: a tool built
+ * on a block with no valid floor would throw on every call instead, far from
+ * the mistake. Only the floor is checked — `verifyDocument` reads the rest
+ * and refuses what it cannot use, and the lowering already resolved it.
+ */
+export declare function assertConfig(config: ProvabilityConfig): ProvabilityConfig;

package/dist/lib/config.js

@@ -0,0 +1,71 @@
+/**
+ * The configuration the proof tools run under when nobody hands them one.
+ *
+ * The composition root (`@crewhaus/evaluation-service`) builds the tools with
+ * the spec's lowered `provability:` block, so the gate and the tools agree on
+ * the floor, the checkers, the artifacts root and the evidence. The builtin
+ * instances — what a spec gets by listing `proofCheck` in `tools:` with no
+ * `provability:` block — have no block to read, so they run under the
+ * compiler's own defaults at the `grounded` floor: the values
+ * `lowerProvability` resolves for a bare `provability: grounded`
+ * (packages/compiler/src/index.ts, the IrProvability doc in
+ * packages/ir/src/index.ts). Copied rather than imported: a tool package
+ * does not import the compiler.
+ */
+import { ProvabilityError, isProvabilityLevel, } from "@crewhaus/provability";
+import { expandToolSelectors } from "@crewhaus/tool-categories";
+/** The floor the builtin instances preflight against (design §7). */
+export const DEFAULT_FLOOR = "grounded";
+/**
+ * `execution.allow`'s default, before the category grammar expands it
+ * (compiler `PROVABILITY_DEFAULT_EXECUTION_ALLOW`): the read-only computations
+ * and gates, less the one destructive verify tool (design §6.3).
+ * `apps/cli/src/provability-default-allow.test.ts` holds the two copies equal.
+ */
+export const DEFAULT_EXECUTION_SELECTORS = [
+    "all-compute",
+    "all-verify",
+    "-goldenUpdate",
+];
+/** The spec name proofs are filed under when neither the caller nor the run names one. */
+export const DEFAULT_SPEC_NAME = "default";
+/**
+ * The lowered defaults at the `grounded` floor. Built on call, not at import:
+ * the expansion walks the category registry, and the CLI imports every tool
+ * package whether a spec lists it or not.
+ */
+export function defaultProvabilityConfig() {
+    return {
+        level: DEFAULT_FLOOR,
+        onFail: "retry",
+        maxRetries: 1,
+        threshold: 1,
+        scope: "session",
+        assumptions: "allow",
+        render: "footer",
+        sources: { allow: [], deny: [], bibliographic: false, resolve: "off" },
+        grounded: { coverage: 0.8, windowTokens: 60, independent: 1 },
+        execution: {
+            allow: [...expandToolSelectors(DEFAULT_EXECUTION_SELECTORS).tools],
+            replay: true,
+            maxReplays: 20,
+        },
+        formal: {
+            checkers: ["builtin", "smt"],
+            forbid: ["sorry", "axiom", "native_decide"],
+            timeoutMs: 30_000,
+        },
+    };
+}
+/**
+ * A config handed in by a caller, checked once at construction: a tool built
+ * on a block with no valid floor would throw on every call instead, far from
+ * the mistake. Only the floor is checked — `verifyDocument` reads the rest
+ * and refuses what it cannot use, and the lowering already resolved it.
+ */
+export function assertConfig(config) {
+    if (!isProvabilityLevel(config?.level)) {
+        throw new ProvabilityError("config", `tool-proof: config.level must be one of cited, grounded, checked, proven (got ${JSON.stringify(config?.level)})`);
+    }
+    return config;
+}

package/dist/lib/context.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What a proof tool reads off the call's `ToolExecuteContext`: the run's
+ * session, its trace bus, its event log and where its session logs live.
+ *
+ * The runtime threads its `RunContext` through `ctx.runContext` where it can
+ * and always through the opaque bridge (`ctx.bridge.runContext`, the field
+ * tool-code-execution's `resolveEventBus` and tool-plan's `identityOf` read).
+ * The bridge also carries the run's `eventLog`, its `sessionRootDir` and
+ * whether a sandbox backend is wired (`RuntimeBridge`,
+ * packages/agent-context-isolation). All of it is read STRUCTURALLY, so this
+ * package imports no runtime wiring, and every field is optional: a bare
+ * unit call (a test, a CLI verb) has none of it, and the tools then work
+ * against the defaults rather than failing.
+ */
+import type { ToolExecuteContext } from "@crewhaus/tool-catalog";
+import type { TraceEventBus } from "@crewhaus/trace-event-bus";
+/** The slice of a `RunContext` the tools read. */
+export type RunContextLike = {
+    readonly sessionId?: unknown;
+    readonly turnNumber?: unknown;
+    readonly eventBus?: TraceEventBus;
+    readonly logger?: {
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    };
+    /** Not on today's `RunContext`; read when a runtime carries it (design §7). */
+    readonly specName?: unknown;
+};
+/** The slice of an event log the tools append to. */
+export type EventLogLike = {
+    append(event: {
+        readonly kind: "proof_checked";
+        readonly payload: unknown;
+    }): Promise<void>;
+};
+/** The slice of `RuntimeBridge` the tools read. */
+export type BridgeLike = {
+    readonly runContext?: RunContextLike;
+    readonly eventLog?: EventLogLike;
+    readonly sessionRootDir?: unknown;
+    readonly sandboxAvailable?: unknown;
+};
+/** The run's context: `ctx.runContext` first, the bridge's otherwise. */
+export declare function runContextOf(ctx: ToolExecuteContext | undefined): RunContextLike | undefined;
+/** The run's session id, when it has a well-formed one. */
+export declare function sessionIdOf(ctx: ToolExecuteContext | undefined): string | undefined;
+/** The run's trace bus, or undefined off the loop (publishing is then a no-op). */
+export declare function eventBusOf(ctx: ToolExecuteContext | undefined): TraceEventBus | undefined;
+/** The run's session event log, when the runtime handed one over. */
+export declare function eventLogOf(ctx: ToolExecuteContext | undefined): EventLogLike | undefined;
+/** Where the run's session logs live, when the runtime said. */
+export declare function sessionRootOf(ctx: ToolExecuteContext | undefined): string | undefined;
+/** Whether the loop was told a sandbox backend is wired (`runChatLoop({ sandboxAvailable })`). */
+export declare function bridgeSandboxAvailable(ctx: ToolExecuteContext | undefined): boolean;
+/** The spec name the run carries, when it carries a valid one. */
+export declare function specNameOf(ctx: ToolExecuteContext | undefined): string | undefined;
+/** Log a warning on the run's logger; silent off the loop. Never throws. */
+export declare function warn(ctx: ToolExecuteContext | undefined, msg: string, fields?: Record<string, unknown>): void;