toolroll 0.9.34 → 0.9.37

package/dist/contracts/project-knowledge.js

@@ -0,0 +1,93 @@
+/**
+ * Project knowledge (project-knowledge.ts): one schema for the saved knowledge (instructions and references, every
+ * revision in `knowledge_change` and the current one in `project_knowledge`), and for the selection a run is given and
+ * keeps (`knowledge_snapshot`). The rules JSON Schema cannot state — UTF-8 byte limits, control characters, secrets,
+ * the selection's total size — run in plain code when knowledge is written. A saved payload's digest is checked
+ * against its stored bytes before it is parsed, and it is upgraded only in memory: stored bytes are never rewritten.
+ */
+import { z } from "zod";
+import { limited, readVersioned, versioned } from "./contract.js";
+import { decisionLineSchema } from "./project-memory.js";
+/** How many references a project keeps, and how many a run is given. Text limits live in TEXT_LIMITS. */
+export const KNOWLEDGE_COUNTS = { references: 12, selected: 3, decisions: 8 };
+const written = limited;
+const saved = () => z.string();
+const referenceShape = (text) => ({
+    id: z.string(),
+    title: text("reference title", "knowledgeTitleBytes"),
+    content: text("reference text", "knowledgeReferenceBytes"),
+    /** A committed .md or .txt file the text was read from, at `sourceRevision` with blob `sourceSha`; null for a note. */
+    path: text("reference path", "knowledgePathBytes").nullable(),
+    sourceSha: z.string().nullable(),
+    sourceRevision: z.string().nullable(),
+});
+const knowledgeShape = (text) => ({
+    instructions: text("instructions", "knowledgeInstructionsBytes"),
+    references: z.array(z.strictObject(referenceShape(text))).max(KNOWLEDGE_COUNTS.references),
+});
+export const KNOWLEDGE_VERSION = 1;
+/** Knowledge as it is written. */
+export const knowledgeSchema = versioned(KNOWLEDGE_VERSION, knowledgeShape(written));
+/** Knowledge as it is read back. */
+export const savedKnowledgeSchema = versioned(KNOWLEDGE_VERSION, knowledgeShape(saved));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields)
+        if (Object.prototype.hasOwnProperty.call(body, field))
+            out[field] = body[field];
+    return out;
+}
+const REFERENCE_FIELDS = Object.keys(referenceShape(saved));
+/**
+ * Knowledge saved before it carried `version` (through 0.9.36: `{instructions, references}`), as version 1. Its
+ * readers took the fields they knew, so this keeps exactly those; values are never rewritten.
+ */
+export function upgradeKnowledgeV0(body) {
+    const references = body["references"];
+    return {
+        version: KNOWLEDGE_VERSION,
+        ...pick(body, ["instructions"]),
+        ...(references === undefined ? {} : { references: Array.isArray(references) ? references.map(one => (isRecord(one) ? pick(one, REFERENCE_FIELDS) : one)) : references }),
+    };
+}
+export const KNOWLEDGE_UPGRADES = { 0: upgradeKnowledgeV0 };
+/** Read saved knowledge: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export function readKnowledge(input) {
+    const read = readVersioned(savedKnowledgeSchema, input, KNOWLEDGE_UPGRADES);
+    if (!read.ok)
+        return read;
+    const { version: _version, ...knowledge } = read.value;
+    return { ok: true, value: knowledge };
+}
+/** What a person drafts on the Knowledge page or the CLI; each action reads the fields it needs. */
+export const knowledgeDraftSchema = z.strictObject({
+    instructions: z.string().optional(),
+    title: z.string().optional(),
+    content: z.string().optional(),
+    path: z.string().optional(),
+    id: z.string().optional(),
+});
+/** A source a run was not given, and why. */
+export const knowledgeOmissionSchema = z.strictObject({ title: z.string(), reason: z.string() });
+const selectionShape = (text) => ({
+    revision: z.int().min(0),
+    instructions: text("instructions", "knowledgeInstructionsBytes"),
+    references: z.array(z.strictObject(referenceShape(text))).max(KNOWLEDGE_COUNTS.references),
+    omitted: z.array(knowledgeOmissionSchema),
+    /** The run whose selection a reviewer inherited; null for a selection of its own. */
+    inheritedFrom: z.int().nullable(),
+    /** Settled decisions, one line each; absent when there are none. */
+    decisions: z.array(decisionLineSchema).max(KNOWLEDGE_COUNTS.decisions).optional(),
+    /** Source excerpts from the crew's checkout (repository-context.ts owns their shape); absent when not captured. */
+    repository: z.looseObject({}).optional(),
+});
+export const KNOWLEDGE_SELECTION_VERSION = 1;
+/** The selection a run is given, as it is frozen. The keys are in the order a selection has always been written. */
+export const knowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, selectionShape(written));
+/** A frozen selection as it is read back. */
+export const savedKnowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, selectionShape(saved));
+/** Read a frozen selection: version 1 (every selection ever frozen) as itself, a newer one refused plainly. */
+export function readKnowledgeSelection(input) {
+    return readVersioned(savedKnowledgeSelectionSchema, input);
+}

package/dist/contracts/project-memory.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Project memory's decisions (project-memory.ts): one schema for a decision as its row reads, the record its history
+ * keeps, the change a person or the lead drafts, and the one line a brief carries. The rules JSON Schema cannot state —
+ * UTF-8 byte limits, blank text, control characters and secrets — run in plain code (`clean`) when a decision is
+ * written; a row is read as it was written, and its digest is checked against the row before anything trusts it.
+ */
+import { z } from "zod";
+export declare const DECISION_STATUSES: readonly ["active", "superseded", "retired"];
+export declare const DECISION_SOURCES: readonly ["conversation", "task", "result", "manual", "backward-pass"];
+/** A decision as it is recorded, in the order its digest lists the fields. */
+export declare const decisionRecordSchema: z.ZodObject<{
+    repo: z.ZodString;
+    revision: z.ZodInt;
+    claim: z.ZodString;
+    why: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        superseded: "superseded";
+    }>;
+    supersedes: z.ZodNullable<z.ZodInt>;
+    decidedBy: z.ZodString;
+    decidedAt: z.ZodString;
+    sourceKind: z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>;
+    sourceRef: z.ZodNullable<z.ZodString>;
+    recordedBy: z.ZodString;
+}, z.core.$strict>;
+/** A decision as its row reads. */
+export declare const decisionSchema: z.ZodObject<{
+    repo: z.ZodString;
+    revision: z.ZodInt;
+    claim: z.ZodString;
+    why: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        superseded: "superseded";
+    }>;
+    supersedes: z.ZodNullable<z.ZodInt>;
+    decidedBy: z.ZodString;
+    decidedAt: z.ZodString;
+    sourceKind: z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>;
+    sourceRef: z.ZodNullable<z.ZodString>;
+    recordedBy: z.ZodString;
+    id: z.ZodInt;
+}, z.core.$strict>;
+export type Decision = z.infer<typeof decisionSchema>;
+export type DecisionRecord = z.infer<typeof decisionRecordSchema>;
+/** What a person or the lead asks to record; only the choice and its reason are required. */
+export declare const decisionDraftSchema: z.ZodObject<{
+    claim: z.ZodString;
+    why: z.ZodString;
+    decidedBy: z.ZodOptional<z.ZodString>;
+    decidedAt: z.ZodOptional<z.ZodString>;
+    sourceKind: z.ZodOptional<z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>>;
+    sourceRef: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
+}, z.core.$strict>;
+export type DecisionDraft = z.infer<typeof decisionDraftSchema>;
+/** One decision in a brief: its id, the choice and when; the why loads on demand by id. */
+export declare const decisionLineSchema: z.ZodObject<{
+    id: z.ZodInt;
+    claim: z.ZodString;
+    decidedAt: z.ZodString;
+}, z.core.$strict>;
+export type DecisionLine = z.infer<typeof decisionLineSchema>;
+export declare const DECISION_CHANGE_VERSION = 1;
+/**
+ * One entry of a decision's history (`decision_change.payload`): the record when it was made, or the reason its status
+ * changed. Entries written before this carried `version` are the same shapes without it; nothing reads them back.
+ */
+export declare const decisionChangeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    repo: z.ZodString;
+    revision: z.ZodInt;
+    claim: z.ZodString;
+    why: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        superseded: "superseded";
+    }>;
+    supersedes: z.ZodNullable<z.ZodInt>;
+    decidedBy: z.ZodString;
+    decidedAt: z.ZodString;
+    sourceKind: z.ZodEnum<{
+        "backward-pass": "backward-pass";
+        conversation: "conversation";
+        manual: "manual";
+        result: "result";
+        task: "task";
+    }>;
+    sourceRef: z.ZodNullable<z.ZodString>;
+    recordedBy: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    reason: z.ZodString;
+}, z.core.$strict>]>;
+export type DecisionChange = z.infer<typeof decisionChangeSchema>;

package/dist/contracts/project-memory.js

@@ -0,0 +1,51 @@
+/**
+ * Project memory's decisions (project-memory.ts): one schema for a decision as its row reads, the record its history
+ * keeps, the change a person or the lead drafts, and the one line a brief carries. The rules JSON Schema cannot state —
+ * UTF-8 byte limits, blank text, control characters and secrets — run in plain code (`clean`) when a decision is
+ * written; a row is read as it was written, and its digest is checked against the row before anything trusts it.
+ */
+import { z } from "zod";
+import { limited, versioned } from "./contract.js";
+export const DECISION_STATUSES = ["active", "superseded", "retired"];
+export const DECISION_SOURCES = ["conversation", "task", "result", "manual", "backward-pass"];
+const written = limited;
+const saved = () => z.string();
+const recordShape = (text) => ({
+    repo: z.string(),
+    revision: z.int().min(1),
+    claim: text("decision", "decisionClaimBytes"),
+    why: text("reason", "decisionWhyBytes"),
+    status: z.enum(DECISION_STATUSES),
+    supersedes: z.int().nullable(),
+    // An omitted draft author defaults to the account name, which has never had the explicit author's byte limit.
+    decidedBy: z.string(),
+    decidedAt: z.string(),
+    sourceKind: z.enum(DECISION_SOURCES),
+    sourceRef: text("source", "decisionSourceBytes").nullable(),
+    recordedBy: z.string(),
+});
+/** A decision as it is recorded, in the order its digest lists the fields. */
+export const decisionRecordSchema = z.strictObject(recordShape(written));
+/** A decision as its row reads. */
+export const decisionSchema = z.strictObject({ id: z.int(), ...recordShape(saved) });
+/** What a person or the lead asks to record; only the choice and its reason are required. */
+export const decisionDraftSchema = z.strictObject({
+    claim: z.string(),
+    why: z.string(),
+    decidedBy: z.string().optional(),
+    decidedAt: z.string().optional(),
+    sourceKind: z.enum(DECISION_SOURCES).optional(),
+    sourceRef: z.string().nullable().optional(),
+    supersedes: z.int().nullable().optional(),
+});
+/** One decision in a brief: its id, the choice and when; the why loads on demand by id. */
+export const decisionLineSchema = z.strictObject({ id: z.int(), claim: z.string(), decidedAt: z.string() });
+export const DECISION_CHANGE_VERSION = 1;
+/**
+ * One entry of a decision's history (`decision_change.payload`): the record when it was made, or the reason its status
+ * changed. Entries written before this carried `version` are the same shapes without it; nothing reads them back.
+ */
+export const decisionChangeSchema = z.union([
+    versioned(DECISION_CHANGE_VERSION, recordShape(written)),
+    versioned(DECISION_CHANGE_VERSION, { reason: limited("reason", "decisionRetireBytes") }),
+]);

package/dist/contracts/project-skills.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Project skills (project-skills.ts): one schema for a skill package (`skill_package`), a project's selection of
+ * versions (`project_skill_change`), and the versions a run is pinned to (`skill_snapshot`, and the snapshot a reviewer
+ * reads). The rules JSON Schema cannot state — UTF-8 byte limits, base64, path safety, YAML metadata, secrets, the
+ * selection's total size — run in plain code (`validateSkill`, `changeSkills`) when a skill is imported or chosen.
+ *
+ * Two payloads carry no envelope, on purpose. A package is content-addressed: its digest is its version, so the same
+ * folder imported before and after this contract is the same version. A selection maps skill names to versions, and
+ * `version` is itself a valid skill name, so a key there would collide with one; an older runtime also reads every
+ * value in it as a choice. Both are read exactly as they have always been written.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many files a package holds, how many versions a project enables and a person's library keeps. Text limits live
+ * in TEXT_LIMITS. */
+export declare const SKILL_COUNTS: {
+    readonly files: 64;
+    readonly enabled: 8;
+    readonly library: 100;
+};
+/** Every skill limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export declare const SKILL_LIMITS: {
+    readonly files: 64;
+    readonly packageBytes: number;
+    readonly fileBytes: number;
+    readonly bodyBytes: number;
+    readonly enabled: 8;
+    readonly selectionBytes: number;
+};
+/** A skill name: lowercase words joined by hyphens. */
+export declare const SKILL_NAME: RegExp;
+export declare const skillFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    base64: z.ZodString;
+}, z.core.$strict>;
+/** A package as it is imported. */
+export declare const skillPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodString;
+    requirements: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A package as it is read back. */
+export declare const savedSkillPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodString;
+    requirements: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A package with its version (the digest of its bytes). */
+export declare const savedSkillSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodString;
+    requirements: z.ZodString;
+    warnings: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+    sha: z.ZodString;
+}, z.core.$strict>;
+export type SkillFile = z.infer<typeof skillFileSchema>;
+export type SkillPackage = z.infer<typeof skillPackageSchema>;
+export type SavedSkill = z.infer<typeof savedSkillSchema>;
+/** One skill's chosen version, and whether it is on. */
+export declare const skillChoiceSchema: z.ZodObject<{
+    sha: z.ZodString;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+/** A project's selection: each skill name and its chosen version. */
+export declare const skillSelectionSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    sha: z.ZodString;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>>;
+export type SkillChoice = z.infer<typeof skillChoiceSchema>;
+export type SkillSelection = z.infer<typeof skillSelectionSchema>;
+export declare const SKILLS_SNAPSHOT_VERSION = 1;
+/** The versions a run is pinned to, as frozen: the packages by digest. */
+export declare const savedSkillsSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodInt;
+    identity: z.ZodString;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    test: z.ZodBoolean;
+    packageShas: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** The same snapshot with each package read, as a run and its reviewer get it. */
+export declare const skillsSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodInt;
+    identity: z.ZodString;
+    inheritedFrom: z.ZodNullable<z.ZodInt>;
+    test: z.ZodBoolean;
+    packages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        source: z.ZodString;
+        requirements: z.ZodString;
+        warnings: z.ZodArray<z.ZodString>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            base64: z.ZodString;
+        }, z.core.$strict>>;
+        sha: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SavedSkillsSnapshot = z.infer<typeof savedSkillsSnapshotSchema>;
+export type SkillsSnapshot = z.infer<typeof skillsSnapshotSchema>;
+/** Read a frozen snapshot: version 1 (every snapshot ever frozen) as itself, a newer one refused plainly. */
+export declare function readSkillsSnapshotPayload(input: unknown): ContractResult<SavedSkillsSnapshot>;

package/dist/contracts/project-skills.js

@@ -0,0 +1,76 @@
+/**
+ * Project skills (project-skills.ts): one schema for a skill package (`skill_package`), a project's selection of
+ * versions (`project_skill_change`), and the versions a run is pinned to (`skill_snapshot`, and the snapshot a reviewer
+ * reads). The rules JSON Schema cannot state — UTF-8 byte limits, base64, path safety, YAML metadata, secrets, the
+ * selection's total size — run in plain code (`validateSkill`, `changeSkills`) when a skill is imported or chosen.
+ *
+ * Two payloads carry no envelope, on purpose. A package is content-addressed: its digest is its version, so the same
+ * folder imported before and after this contract is the same version. A selection maps skill names to versions, and
+ * `version` is itself a valid skill name, so a key there would collide with one; an older runtime also reads every
+ * value in it as a choice. Both are read exactly as they have always been written.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, versioned } from "./contract.js";
+/** How many files a package holds, how many versions a project enables and a person's library keeps. Text limits live
+ * in TEXT_LIMITS. */
+export const SKILL_COUNTS = { files: 64, enabled: 8, library: 100 };
+/** Every skill limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export const SKILL_LIMITS = {
+    files: SKILL_COUNTS.files,
+    packageBytes: TEXT_LIMITS.skillPackageBytes,
+    fileBytes: TEXT_LIMITS.skillFileBytes,
+    bodyBytes: TEXT_LIMITS.skillBodyBytes,
+    enabled: SKILL_COUNTS.enabled,
+    selectionBytes: TEXT_LIMITS.skillSelectionBytes,
+};
+const written = limited;
+const saved = () => z.string();
+/** A skill name: lowercase words joined by hyphens. */
+export const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const fileShape = (text) => ({
+    /** Relative to the skill folder; no hidden parts, `.` or `..`. */
+    path: text("file path", "skillPath"),
+    /** The file's bytes, base64 (each at most TEXT_LIMITS.skillFileBytes once decoded). */
+    base64: z.string(),
+});
+const packageShape = (text) => ({
+    name: text("skill name", "skillNameBytes").regex(SKILL_NAME),
+    description: text("description", "skillDescriptionBytes"),
+    /** Where it was imported from: an uploaded folder or a GitHub folder pinned to a commit. */
+    source: text("source", "skillSourceBytes"),
+    /** SKILL.md's `compatibility`, or empty. */
+    requirements: text("requirements", "skillRequirementsBytes"),
+    warnings: z.array(z.string()),
+    files: z.array(z.strictObject(fileShape(text))).min(1).max(SKILL_COUNTS.files),
+});
+export const skillFileSchema = z.strictObject(fileShape(written));
+/** A package as it is imported. */
+export const skillPackageSchema = z.strictObject(packageShape(written));
+/** A package as it is read back. */
+export const savedSkillPackageSchema = z.strictObject(packageShape(saved));
+/** A package with its version (the digest of its bytes). */
+export const savedSkillSchema = z.strictObject({ ...packageShape(saved), sha: z.string() });
+/** One skill's chosen version, and whether it is on. */
+export const skillChoiceSchema = z.strictObject({ sha: z.string(), enabled: z.boolean() });
+/** A project's selection: each skill name and its chosen version. */
+export const skillSelectionSchema = z.record(z.string(), skillChoiceSchema);
+const snapshotFacts = {
+    /** The selection revision the versions came from; 0 for none. */
+    revision: z.int().min(0),
+    /** The project identity they were chosen under, or `unconfigured`. */
+    identity: z.string(),
+    /** The run a reviewer or later attempt inherited them from. */
+    inheritedFrom: z.int().nullable(),
+    /** A skill test: the one package is the version under test. */
+    test: z.boolean(),
+};
+export const SKILLS_SNAPSHOT_VERSION = 1;
+/** The versions a run is pinned to, as frozen: the packages by digest. */
+export const savedSkillsSnapshotSchema = versioned(SKILLS_SNAPSHOT_VERSION, { ...snapshotFacts, packageShas: z.array(z.string()) });
+/** The same snapshot with each package read, as a run and its reviewer get it. */
+export const skillsSnapshotSchema = versioned(SKILLS_SNAPSHOT_VERSION, { ...snapshotFacts, packages: z.array(savedSkillSchema) });
+/** Read a frozen snapshot: version 1 (every snapshot ever frozen) as itself, a newer one refused plainly. */
+export function readSkillsSnapshotPayload(input) {
+    return readVersioned(savedSkillsSnapshotSchema, input);
+}

package/dist/contracts/proof.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The builder's proof: one schema for the file a builder writes (the proof manifest), the `proof.json` the machine
+ * stores, and the reader that reads both back (`parseProof` in proof.ts). The rules JSON Schema cannot state — UTF-8
+ * byte limits, blank text, control characters, relative screenshot paths and duplicate ids or paths — run in plain
+ * code after parsing, each with a path-named error.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many entries each proof list may hold. Text limits live in TEXT_LIMITS. */
+export declare const PROOF_COUNTS: {
+    readonly criteria: 12;
+    readonly evidencePerCriterion: 4;
+    readonly checks: 12;
+    readonly changed: 64;
+    readonly caveats: 8;
+    readonly screenshots: 8;
+};
+/** Every proof limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export declare const PROOF_LIMITS: {
+    readonly criteria: 12;
+    readonly evidencePerCriterion: 4;
+    readonly checks: 12;
+    readonly changed: 64;
+    readonly caveats: 8;
+    readonly screenshots: 8;
+    readonly payload: number;
+    readonly criterionId: 40;
+    readonly criterionStatement: 300;
+    readonly criterionHow: 500;
+    readonly evidenceRef: 300;
+    readonly checkCommand: 300;
+    readonly checkSummary: 300;
+    readonly changedPath: 300;
+    readonly caveat: 300;
+    readonly screenshotPath: 300;
+    readonly screenshotCaption: 300;
+};
+export declare const CRITERION_VERDICTS: readonly ["met", "not-met", "not-checked", "pending-verification"];
+/** One typed reference a criterion cites: an existing check's command, screenshot's path, a path in `changed`, or
+ * (kind `manual-review`) free text pointing at nothing machine-checkable. */
+export declare const criterionEvidenceSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>;
+    ref: z.ZodString;
+}, z.core.$strict>;
+/** One criterion the proof answers. `pending-verification` asserts all agent-owned work is met and only the
+ * machine-owned final check remains. */
+export declare const proofCriterionSchema: z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    how: z.ZodString;
+    verdict: z.ZodEnum<{
+        met: "met";
+        "not-checked": "not-checked";
+        "not-met": "not-met";
+        "pending-verification": "pending-verification";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>;
+        ref: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const proofCheckSchema: z.ZodObject<{
+    command: z.ZodString;
+    summary: z.ZodString;
+    exitCode: z.ZodInt;
+}, z.core.$strict>;
+/** A screenshot the proof claims; its path is where the file lived in the worktree, its bytes are checked by the
+ * caller. */
+export declare const proofScreenshotSchema: z.ZodObject<{
+    path: z.ZodString;
+    caption: z.ZodString;
+}, z.core.$strict>;
+export declare const PROOF_VERSION = 2;
+/** The proof as stored and as every reader returns it: every list present, nothing unknown. */
+export declare const proofSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        how: z.ZodString;
+        verdict: z.ZodEnum<{
+            met: "met";
+            "not-checked": "not-checked";
+            "not-met": "not-met";
+            "pending-verification": "pending-verification";
+        }>;
+        evidence: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                "changed-path": "changed-path";
+                check: "check";
+                "manual-review": "manual-review";
+                screenshot: "screenshot";
+            }>;
+            ref: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    checks: z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        summary: z.ZodString;
+        exitCode: z.ZodInt;
+    }, z.core.$strict>>;
+    changed: z.ZodArray<z.ZodString>;
+    caveats: z.ZodArray<z.ZodString>;
+    screenshots: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        caption: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ParsedProof = z.infer<typeof proofSchema>;
+export type ParsedCriterion = z.infer<typeof proofCriterionSchema>;
+export type CriterionEvidenceRef = z.infer<typeof criterionEvidenceSchema>;
+export type ParsedCheck = z.infer<typeof proofCheckSchema>;
+export type ParsedScreenshot = z.infer<typeof proofScreenshotSchema>;
+/**
+ * A version 1 proof — what a builder writes (`{ "version": 1, "screenshots": [...] }`) and every proof stored through
+ * 0.9.34 — as version 2. Version 1 read only the fields it knew and ignored any others, and read a missing or null
+ * list (a criterion's `evidence` too) as empty; this keeps exactly that. Values themselves are never rewritten.
+ */
+export declare function upgradeProofV1(body: Record<string, unknown>): Record<string, unknown>;
+export declare const PROOF_UPGRADES: {
+    readonly 1: typeof upgradeProofV1;
+};
+/** The payload as version 2 (upgraded from version 1 when needed), for the plain-code rules; null for a non-object. */
+export declare function proofPayloadBody(input: unknown): Record<string, unknown> | null;
+/** Read a proof payload: version 2 as itself, version 1 upgraded, a newer one refused plainly. */
+export declare function readProofPayload(input: unknown): ContractResult<ParsedProof>;