toolroll 0.9.34 → 0.9.36

package/dist/proof.js

@@ -19,7 +19,9 @@
  * so the review itself stays testable without a filesystem or a database.
  */
 import { hasForbiddenControls } from "./decision.js";
-import { EVIDENCE_KINDS } from "./scope.js";
+import { contractProblemOf } from "./contracts/contract.js";
+import { PROOF_LIMITS, proofPayloadBody, readProofPayload } from "./contracts/proof.js";
+export { PROOF_LIMITS } from "./contracts/proof.js";
 /** Shared by preflight and final adjudication; presentation text is never a rubric. */
 function criterionContractProblems(approved, answer) {
     if (answer === undefined)
@@ -57,248 +59,96 @@ export function proofSubmissionProblems(proof, rubric) {
     problems.push(...failedMetChecks(proof).map(failedCheckWords));
     return problems;
 }
-/** Caps are BYTES of UTF-8, matching the scout report's rule: a payload is
- * the same size whatever script it is written in. */
-export const PROOF_LIMITS = {
-    payload: 64 * 1024,
-    criteria: 12,
-    criterionId: 40,
-    criterionStatement: 300,
-    criterionHow: 500,
-    evidencePerCriterion: 4,
-    evidenceRef: 300,
-    checks: 12,
-    checkCommand: 300,
-    checkSummary: 300,
-    changed: 64,
-    changedPath: 300,
-    caveats: 8,
-    caveat: 300,
-    screenshots: 8,
-    screenshotPath: 300,
-    screenshotCaption: 300,
-};
 function refuse(reason, message) {
     return { ok: false, problems: [{ reason, message }] };
 }
-function describe(value) {
-    if (value === undefined)
-        return "nothing";
-    if (value === null)
-        return "null";
-    if (typeof value === "string")
-        return `a ${value.length}-char string`;
-    return `a ${Array.isArray(value) ? "array" : typeof value}`;
-}
-function prose(value, field, cap, problems) {
-    if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
-        problems.push({ reason: `missing-${field}`, message: `${field} is required` });
-        return null;
-    }
-    if (typeof value !== "string") {
-        problems.push({ reason: `bad-${field}`, message: `${field} must be a string (got ${describe(value)})` });
-        return null;
-    }
-    if (Buffer.byteLength(value, "utf8") > cap) {
-        problems.push({ reason: `${field}-too-long`, message: `${field} is over ${cap} bytes` });
-        return null;
-    }
-    if (hasForbiddenControls(value)) {
-        problems.push({ reason: `${field}-controls`, message: `${field} carries control characters that could become terminal escapes` });
-        return null;
-    }
-    return value;
-}
-/** A repository-relative path: no leading slash, no drive letter, no `.`/`..`
- * segment, no backslash, no control character. The same shape
- * `readVerifiedArtifact` enforces on an evidence key, applied here to a
- * path an agent claims rather than one the machine already wrote. */
-function relativePath(value, field, cap, problems) {
-    const raw = prose(value, field, cap, problems);
-    if (raw === null)
-        return null;
-    const segments = raw.split("/");
-    const wellFormed = !raw.startsWith("/") &&
-        segments.every(segment => segment.length > 0 && segment !== "." && segment !== ".." && !segment.includes("\\"));
-    if (!wellFormed) {
-        problems.push({ reason: `${field}-not-relative`, message: `${field} must be a normalized repository-relative path (got ${describe(value)})` });
-        return null;
-    }
-    return raw;
-}
-/** `evidence` is optional on a criterion (absent → `[]`, exactly like every
- * other list here) — the mandatory PRESENCE of an answer for a SIGNED
- * criterion is `adjudicate`'s concern, not the parser's; this only proves
- * the shape of what is there. */
-function parseEvidenceRefs(value, field, problems) {
-    if (value === undefined || value === null)
-        return [];
-    if (!Array.isArray(value)) {
-        problems.push({ reason: `bad-${field}`, message: `${field} must be an array (got ${describe(value)})` });
-        return null;
-    }
-    if (value.length > PROOF_LIMITS.evidencePerCriterion) {
-        problems.push({ reason: `${field}-too-many`, message: `${field} lists ${value.length} — cap is ${PROOF_LIMITS.evidencePerCriterion}` });
-        return null;
-    }
-    const refs = [];
-    let bad = false;
-    for (const [index, entry] of value.entries()) {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-            problems.push({ reason: `${field}[${index}]-shape`, message: `${field}[${index}] must be an object` });
-            bad = true;
-            continue;
-        }
-        const one = entry;
-        const kind = one["kind"];
-        if (typeof kind !== "string" || !EVIDENCE_KINDS.includes(kind)) {
-            problems.push({
-                reason: `${field}[${index}]-bad-kind`,
-                message: `${field}[${index}].kind must draw from ${EVIDENCE_KINDS.join(", ")} (got ${describe(kind)})`,
-            });
-            bad = true;
-            continue;
-        }
-        const ref = prose(one["ref"], `${field}[${index}].ref`, PROOF_LIMITS.evidenceRef, problems);
-        if (ref === null) {
-            bad = true;
-            continue;
-        }
-        refs.push({ kind: kind, ref });
-    }
-    return bad ? null : refs;
-}
-function parseCriteria(value, problems) {
-    if (value === undefined || value === null)
-        return [];
-    if (!Array.isArray(value)) {
-        problems.push({ reason: "bad-criteria", message: `criteria must be an array (got ${describe(value)})` });
-        return [];
-    }
-    if (value.length > PROOF_LIMITS.criteria) {
-        problems.push({ reason: "criteria-too-many", message: `criteria lists ${value.length} — cap is ${PROOF_LIMITS.criteria}` });
-        return [];
-    }
-    const criteria = [];
-    const seen = new Set();
-    for (const [index, entry] of value.entries()) {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-            problems.push({ reason: `criteria[${index}]-shape`, message: `criteria[${index}] must be an object` });
-            continue;
-        }
-        const one = entry;
-        const id = prose(one["id"], `criteria[${index}].id`, PROOF_LIMITS.criterionId, problems);
-        if (id !== null && seen.has(id)) {
-            problems.push({ reason: `criteria[${index}]-duplicate-id`, message: `criterion id "${id}" appears twice` });
-        }
-        else if (id !== null) {
-            seen.add(id);
-        }
-        const statement = prose(one["statement"], `criteria[${index}].statement`, PROOF_LIMITS.criterionStatement, problems);
-        const how = prose(one["how"], `criteria[${index}].how`, PROOF_LIMITS.criterionHow, problems);
-        const verdict = one["verdict"];
-        if (verdict !== "met" && verdict !== "not-met" && verdict !== "not-checked" && verdict !== "pending-verification") {
-            problems.push({
-                reason: `criteria[${index}]-bad-verdict`,
-                message: `criteria[${index}].verdict must be "met", "not-met", "not-checked", or "pending-verification" (got ${describe(verdict)})`,
-            });
-            continue;
-        }
-        const evidence = parseEvidenceRefs(one["evidence"], `criteria[${index}].evidence`, problems);
-        if (id === null || statement === null || how === null || evidence === null)
-            continue;
-        criteria.push({ id, statement, how, verdict, evidence });
-    }
-    return criteria;
-}
-function parseChecks(value, problems) {
-    if (value === undefined || value === null)
-        return [];
-    if (!Array.isArray(value)) {
-        problems.push({ reason: "bad-checks", message: `checks must be an array (got ${describe(value)})` });
-        return [];
-    }
-    if (value.length > PROOF_LIMITS.checks) {
-        problems.push({ reason: "checks-too-many", message: `checks lists ${value.length} — cap is ${PROOF_LIMITS.checks}` });
-        return [];
-    }
-    const checks = [];
-    for (const [index, entry] of value.entries()) {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-            problems.push({ reason: `checks[${index}]-shape`, message: `checks[${index}] must be an object` });
-            continue;
-        }
-        const one = entry;
-        const command = prose(one["command"], `checks[${index}].command`, PROOF_LIMITS.checkCommand, problems);
-        const summary = prose(one["summary"], `checks[${index}].summary`, PROOF_LIMITS.checkSummary, problems);
-        const exitCode = one["exitCode"];
-        if (typeof exitCode !== "number" || !Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) {
-            problems.push({
-                reason: `checks[${index}]-bad-exit-code`,
-                message: `checks[${index}].exitCode must be an integer 0-255 (got ${describe(exitCode)})`,
+/** Every text field of a proof body (version 2 shape) that the schema saw as a string. */
+function textFields(body) {
+    const out = [];
+    const text = (path, value, bytes, relative) => {
+        if (typeof value === "string")
+            out.push({ path, value, bytes, ...(relative ? { relative } : {}) });
+    };
+    const records = (field) => {
+        const list = body[field];
+        return Array.isArray(list) ? list.flatMap((one, index) => (typeof one === "object" && one !== null && !Array.isArray(one) ? [[index, one]] : [])) : [];
+    };
+    for (const [index, one] of records("criteria")) {
+        text(`criteria[${index}].id`, one["id"], PROOF_LIMITS.criterionId);
+        text(`criteria[${index}].statement`, one["statement"], PROOF_LIMITS.criterionStatement);
+        text(`criteria[${index}].how`, one["how"], PROOF_LIMITS.criterionHow);
+        const evidence = one["evidence"];
+        if (Array.isArray(evidence)) {
+            evidence.forEach((ref, at) => {
+                if (typeof ref === "object" && ref !== null)
+                    text(`criteria[${index}].evidence[${at}].ref`, ref["ref"], PROOF_LIMITS.evidenceRef);
             });
-            continue;
         }
-        if (command === null || summary === null)
-            continue;
-        checks.push({ command, summary, exitCode });
     }
-    return checks;
-}
-function parseStringList(value, field, cap, itemCap, problems) {
-    if (value === undefined || value === null)
-        return [];
-    if (!Array.isArray(value)) {
-        problems.push({ reason: `bad-${field}`, message: `${field} must be an array (got ${describe(value)})` });
-        return [];
+    for (const [index, one] of records("checks")) {
+        text(`checks[${index}].command`, one["command"], PROOF_LIMITS.checkCommand);
+        text(`checks[${index}].summary`, one["summary"], PROOF_LIMITS.checkSummary);
     }
-    if (value.length > cap) {
-        problems.push({ reason: `${field}-too-many`, message: `${field} lists ${value.length} — cap is ${cap}` });
-        return [];
+    for (const field of ["changed", "caveats"]) {
+        const list = body[field];
+        if (Array.isArray(list))
+            list.forEach((one, index) => text(`${field}[${index}]`, one, field === "changed" ? PROOF_LIMITS.changedPath : PROOF_LIMITS.caveat));
     }
-    const out = [];
-    for (const [index, entry] of value.entries()) {
-        const item = prose(entry, `${field}[${index}]`, itemCap, problems);
-        if (item !== null)
-            out.push(item);
+    for (const [index, one] of records("screenshots")) {
+        text(`screenshots[${index}].path`, one["path"], PROOF_LIMITS.screenshotPath, true);
+        text(`screenshots[${index}].caption`, one["caption"], PROOF_LIMITS.screenshotCaption);
     }
     return out;
 }
-function parseScreenshots(value, problems) {
-    if (value === undefined || value === null)
-        return [];
-    if (!Array.isArray(value)) {
-        problems.push({ reason: "bad-screenshots", message: `screenshots must be an array (got ${describe(value)})` });
-        return [];
-    }
-    if (value.length > PROOF_LIMITS.screenshots) {
-        problems.push({ reason: "screenshots-too-many", message: `screenshots lists ${value.length} — cap is ${PROOF_LIMITS.screenshots}` });
-        return [];
-    }
-    const screenshots = [];
-    const seen = new Set();
-    for (const [index, entry] of value.entries()) {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-            problems.push({ reason: `screenshots[${index}]-shape`, message: `screenshots[${index}] must be an object` });
-            continue;
-        }
-        const one = entry;
-        const path = relativePath(one["path"], `screenshots[${index}].path`, PROOF_LIMITS.screenshotPath, problems);
-        const caption = prose(one["caption"], `screenshots[${index}].caption`, PROOF_LIMITS.screenshotCaption, problems);
-        if (path !== null && seen.has(path)) {
-            problems.push({ reason: `screenshots[${index}]-duplicate-path`, message: `screenshot path "${path}" appears twice` });
-            continue;
-        }
-        if (path === null || caption === null)
+/**
+ * The rules JSON Schema cannot state, in plain code with path-named errors: blank text, UTF-8 byte limits, control
+ * characters, normalized repository-relative screenshot paths (no leading slash, `.`/`..` segment or backslash — the
+ * shape `readVerifiedArtifact` enforces on an evidence key), and unique criterion ids and screenshot paths. A field
+ * the schema already refused is not reported twice.
+ */
+function proofRuleProblems(body, contract) {
+    const named = (path) => contract.some(problem => problem.message.startsWith(`${path}:`));
+    const problems = [];
+    for (const field of textFields(body)) {
+        if (named(field.path))
             continue;
-        seen.add(path);
-        screenshots.push({ path, caption });
-    }
-    return screenshots;
+        const { path, value } = field;
+        if (value.trim() === "")
+            problems.push({ reason: `missing-${path}`, message: `${path}: must not be blank` });
+        else if (Buffer.byteLength(value, "utf8") > field.bytes)
+            problems.push({ reason: `${path}-too-long`, message: `${path}: over ${field.bytes.toLocaleString("en-US")} bytes` });
+        else if (hasForbiddenControls(value))
+            problems.push({ reason: `${path}-controls`, message: `${path}: carries control characters that could become terminal escapes` });
+        else if (field.relative && (value.startsWith("/") || !value.split("/").every(segment => segment.length > 0 && segment !== "." && segment !== ".." && !segment.includes("\\")))) {
+            problems.push({ reason: `${path}-not-relative`, message: `${path}: must be a normalized repository-relative path` });
+        }
+    }
+    const unique = (field, key, what) => {
+        const list = body[field];
+        if (!Array.isArray(list) || named(field))
+            return;
+        const seen = new Set();
+        list.forEach((one, index) => {
+            const value = typeof one === "object" && one !== null ? one[key] : undefined;
+            if (typeof value !== "string")
+                return;
+            if (seen.has(value))
+                problems.push({ reason: `${field}[${index}]-duplicate-${key}`, message: `${field}[${index}].${key}: ${what} ${JSON.stringify(value)} appears twice` });
+            seen.add(value);
+        });
+    };
+    unique("criteria", "id", "criterion id");
+    unique("screenshots", "path", "screenshot path");
+    return problems;
 }
+/**
+ * Read a proof: the payload byte cap and JSON first, then the proof schema (version 2 as itself, the version 1 a
+ * builder writes upgraded, a newer one refused plainly), then the plain-code rules. Every problem names its path and
+ * is reported at once; fail closed.
+ */
 export function parseProof(raw) {
     if (Buffer.byteLength(raw, "utf8") > PROOF_LIMITS.payload) {
-        return refuse("too-large", `the payload is over ${PROOF_LIMITS.payload} bytes`);
+        return refuse("too-large", `payload: over ${PROOF_LIMITS.payload.toLocaleString("en-US")} bytes`);
     }
     let parsed;
     try {
@@ -307,29 +157,20 @@ export function parseProof(raw) {
     catch (error) {
         return refuse("not-json", `the payload is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return refuse("not-an-object", "the payload must be one JSON object");
-    }
-    const body = parsed;
-    const problems = [];
-    if (body["version"] !== 1) {
-        problems.push({ reason: "bad-version", message: `version must be 1 (got ${describe(body["version"])})` });
-    }
-    const criteria = parseCriteria(body["criteria"], problems);
-    const checks = parseChecks(body["checks"], problems);
-    const changed = parseStringList(body["changed"], "changed", PROOF_LIMITS.changed, PROOF_LIMITS.changedPath, problems);
-    const caveats = parseStringList(body["caveats"], "caveats", PROOF_LIMITS.caveats, PROOF_LIMITS.caveat, problems);
-    const screenshots = parseScreenshots(body["screenshots"], problems);
-    if (problems.length > 0)
+    const body = proofPayloadBody(parsed);
+    if (body === null)
+        return refuse("not-an-object", "payload: must be one JSON object");
+    const read = readProofPayload(parsed);
+    const contract = read.ok ? [] : read.issues.map(contractProblemOf);
+    if (contract.some(problem => problem.reason === "newer-version" || problem.reason === "bad-version"))
+        return { ok: false, problems: contract };
+    const problems = [...contract, ...proofRuleProblems(body, contract)];
+    if (!read.ok || problems.length > 0)
         return { ok: false, problems };
-    return {
-        ok: true,
-        proof: { version: 1, criteria, checks, changed, caveats, screenshots },
-    };
+    return { ok: true, proof: read.value };
 }
-/** Re-serialize the validated shape, never the agent's raw bytes (the
- * scout report's rule, `scout.ts`): what is stored and later hash-verified
- * is exactly what this parser admitted, key order and all. */
+/** Serialize the validated shape, never the agent's raw bytes (the scout report's rule, `scout.ts`): what is stored
+ * and later hash-verified is exactly what the schema admitted, in its key order. */
 export function serializeProof(proof) {
     return JSON.stringify(proof, null, 2);
 }

package/dist/result-evidence-readers.d.ts

@@ -0,0 +1,42 @@
+/** Shared verified readers for result screens and the compact CLI review. */
+import type { Artifact } from "./store.js";
+export declare const SCREENSHOT_CAPTURE: RegExp;
+/** What the run page shows of the terminal diff — verified bytes or a named problem, never silence. */
+export type TerminalDiffView = {
+    patch: {
+        text: string;
+        truncated: boolean;
+        artifactId: number;
+    } | {
+        problem: string;
+    } | null;
+    stat: {
+        base: string;
+        head: string;
+        fileCount: number;
+        additions: number;
+        deletions: number;
+        binaryCount: number;
+        filesTruncated: boolean;
+        files: {
+            path: string;
+            additions: number | null;
+            deletions: number | null;
+            renamedFrom?: string;
+        }[];
+    } | {
+        problem: string;
+    } | null;
+};
+/** A compact, typed view of the agent-authored handoff. Older v1
+ * artifacts simply have no lists, while v2 can present the useful answer
+ * before the raw diff and evidence below it. */
+export type StructuredHandoffView = {
+    conclusion: string;
+    changes: string[];
+    verification: string[];
+    followUps: string[];
+};
+export declare function structuredHandoffView(artifacts: Artifact[], root: string, displayText?: (text: string) => string): StructuredHandoffView | null;
+/** A failed capture or unverifiable bytes keep their problem; absence returns null. */
+export declare function terminalDiffView(artifacts: Artifact[], root: string): TerminalDiffView | null;

package/dist/result-evidence-readers.js

@@ -0,0 +1,91 @@
+import { readVerifiedArtifact } from "./evidence.js";
+import { hasForbiddenControls } from "./decision.js";
+import { parseHandoffArtifact } from "./contracts/handoff.js";
+const CAPTURE_EXIT = /\(exit ([0-9]{1,4})\)\s*$/;
+export const SCREENSHOT_CAPTURE = /^agent-claimed screenshot at (.+) \(validated (?:png|jpeg)\)/;
+const oneLineOf = (text, cap) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= cap ? flat : `${flat.slice(0, cap - 1)}…`;
+};
+export function structuredHandoffView(artifacts, root, displayText = text => text) {
+    const artifact = [...artifacts].reverse().find(one => one.kind === "handoff");
+    if (artifact === undefined)
+        return null;
+    const read = readVerifiedArtifact(root, artifact);
+    if (!read.ok)
+        return null;
+    const parsed = parseHandoffArtifact(read.content.toString("utf8"));
+    if (!parsed.ok)
+        return null;
+    const handoff = parsed.value;
+    const conclusion = oneLineOf(displayText(handoff.conclusion), 600);
+    if (conclusion === "" || hasForbiddenControls(conclusion))
+        return null;
+    const list = (items) => (items ?? [])
+        .filter(one => one.trim() !== "" && !hasForbiddenControls(one))
+        .slice(0, 8)
+        .map(one => oneLineOf(one, 240));
+    return { conclusion, changes: list(handoff.changes), verification: list(handoff.verification), followUps: list(handoff.followUps) };
+}
+/** A failed capture or unverifiable bytes keep their problem; absence returns null. */
+export function terminalDiffView(artifacts, root) {
+    const patchArtifact = artifacts.find(one => one.kind === "terminal-diff");
+    const statArtifact = artifacts.find(one => one.kind === "diff-stat");
+    if (patchArtifact === undefined && statArtifact === undefined)
+        return null;
+    const view = { patch: null, stat: null };
+    if (patchArtifact !== undefined) {
+        const exit = CAPTURE_EXIT.exec(patchArtifact.capture);
+        if (exit !== null && exit[1] !== "0") {
+            view.patch = { problem: `capture failed — ${patchArtifact.capture}` };
+        }
+        else {
+            const read = readVerifiedArtifact(root, patchArtifact);
+            view.patch = read.ok
+                ? { text: read.content.toString("utf8"), truncated: patchArtifact.truncated, artifactId: patchArtifact.id }
+                : { problem: `stored but unverifiable — ${read.problem}` };
+        }
+    }
+    if (statArtifact !== undefined) {
+        const exit = CAPTURE_EXIT.exec(statArtifact.capture);
+        if (exit !== null && exit[1] !== "0") {
+            view.stat = { problem: `capture failed — ${statArtifact.capture}` };
+        }
+        else {
+            const read = readVerifiedArtifact(root, statArtifact);
+            if (!read.ok) {
+                view.stat = { problem: `stored but unverifiable — ${read.problem}` };
+            }
+            else {
+                try {
+                    const parsed = JSON.parse(read.content.toString("utf8"));
+                    // Every field this page renders is type-proved (arc 6, finding 7):
+                    // "an object with a base key" was accepting any shape at all.
+                    const count = (value) => typeof value === "number" && Number.isFinite(value);
+                    const wellFormed = parsed !== null &&
+                        typeof parsed === "object" &&
+                        typeof parsed["base"] === "string" &&
+                        typeof parsed["head"] === "string" &&
+                        count(parsed["fileCount"]) &&
+                        count(parsed["additions"]) &&
+                        count(parsed["deletions"]) &&
+                        count(parsed["binaryCount"]) &&
+                        typeof parsed["filesTruncated"] === "boolean" &&
+                        Array.isArray(parsed["files"]) &&
+                        parsed["files"].every(one => one !== null &&
+                            typeof one === "object" &&
+                            typeof one["path"] === "string" &&
+                            (count(one["additions"]) || one["additions"] === null) &&
+                            (count(one["deletions"]) || one["deletions"] === null));
+                    view.stat = wellFormed
+                        ? parsed
+                        : { problem: "stat is not the shape this page knows" };
+                }
+                catch {
+                    view.stat = { problem: "stat did not parse as JSON" };
+                }
+            }
+        }
+    }
+    return view;
+}