toolroll 0.9.103 → 0.9.105

package/dist/contracts/project-skills.js

@@ -1,21 +1,7 @@
-/**
- * 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,
@@ -26,51 +12,34 @@ export const SKILL_LIMITS = {
 };
 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.js

@@ -1,17 +1,9 @@
-/**
- * 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 { TEXT_LIMITS } from "../text-limits.js";
 import { EVIDENCE_KINDS } from "../scope.js";
 import { limited, readVersioned, versioned } from "./contract.js";
 import { isRecord } from "../is-record.js";
-/** How many entries each proof list may hold. Text limits live in TEXT_LIMITS. */
 export const PROOF_COUNTS = { criteria: 12, evidencePerCriterion: 4, checks: 12, changed: 64, caveats: 8, screenshots: 8 };
-/** Every proof limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
 export const PROOF_LIMITS = {
     payload: TEXT_LIMITS.proofPayloadBytes,
     ...PROOF_COUNTS,
@@ -28,14 +20,10 @@ export const PROOF_LIMITS = {
 };
 export const CRITERION_VERDICTS = ["met", "not-met", "not-checked", "pending-verification"];
 const line = (field) => limited(field, "proofLineBytes").min(1);
-/** 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 const criterionEvidenceSchema = z.strictObject({
     kind: z.enum(EVIDENCE_KINDS),
     ref: line("evidence ref"),
 });
-/** One criterion the proof answers. `pending-verification` asserts all agent-owned work is met and only the
- * machine-owned final check remains. */
 export const proofCriterionSchema = z.strictObject({
     id: limited("criterion id", "proofCriterionIdBytes").min(1),
     statement: line("criterion statement"),
@@ -48,14 +36,11 @@ export const proofCheckSchema = z.strictObject({
     summary: line("check summary"),
     exitCode: z.int().min(0).max(255),
 });
-/** A screenshot the proof claims; its path is where the file lived in the worktree, its bytes are checked by the
- * caller. */
 export const proofScreenshotSchema = z.strictObject({
     path: line("screenshot path"),
     caption: line("screenshot caption"),
 });
 export const PROOF_VERSION = 2;
-/** The proof as stored and as every reader returns it: every list present, nothing unknown. */
 export const proofSchema = versioned(PROOF_VERSION, {
     criteria: z.array(proofCriterionSchema).max(PROOF_COUNTS.criteria),
     checks: z.array(proofCheckSchema).max(PROOF_COUNTS.checks),
@@ -63,7 +48,6 @@ export const proofSchema = versioned(PROOF_VERSION, {
     caveats: z.array(line("caveat")).max(PROOF_COUNTS.caveats),
     screenshots: z.array(proofScreenshotSchema).max(PROOF_COUNTS.screenshots),
 });
-/** The listed fields of `body`, a null or missing one left out (the old parser read null text as missing). */
 function pick(body, fields) {
     const out = {};
     for (const field of fields) {
@@ -73,11 +57,6 @@ function pick(body, fields) {
     return out;
 }
 const each = (value, fields) => (Array.isArray(value) ? value.map(one => (isRecord(one) ? pick(one, fields) : one)) : value);
-/**
- * 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 function upgradeProofV1(body) {
     const list = (field) => (body[field] === undefined || body[field] === null ? [] : body[field]);
     const criteria = list("criteria");
@@ -98,13 +77,11 @@ export function upgradeProofV1(body) {
     };
 }
 export const PROOF_UPGRADES = { 1: upgradeProofV1 };
-/** The payload as version 2 (upgraded from version 1 when needed), for the plain-code rules; null for a non-object. */
 export function proofPayloadBody(input) {
     if (!isRecord(input))
         return null;
     return input["version"] === 1 ? upgradeProofV1(input) : input;
 }
-/** Read a proof payload: version 2 as itself, version 1 upgraded, a newer one refused plainly. */
 export function readProofPayload(input) {
     return readVersioned(proofSchema, input, PROOF_UPGRADES);
 }

package/dist/contracts/provider.js

@@ -1,12 +1,3 @@
-/**
- * Which harness runs, on which model (provider.ts `AgentSpec`): a provider id and a model id, null for the harness's
- * default. One schema for the pair; `ProviderId` and `AgentSpec` are derived from it. Model ids cross providers
- * ("anthropic/claude-sonnet-4.5", "gpt-5-codex", "opus"): bounded and printable, never leading with a dash (argv
- * safety), and no TOML-hostile characters. That OpenRouter and Gemini need an explicit model runs after parsing.
- *
- * A refusal names its field and never repeats the value it was given: a provider or model field is where a pasted
- * credential would land, and a refusal is shown, logged and sent on.
- */
 import { z } from "zod";
 export const PROVIDER_ID_VALUES = ["claude", "codex", "openrouter", "gemini", "opencode", "cursor", "cline", "qwen", "goose"];
 export const providerIdSchema = z.enum(PROVIDER_ID_VALUES);

package/dist/contracts/recipes.js

@@ -1,23 +1,9 @@
-/**
- * A recipe document (recipes.ts): reusable work a person imports, exports, previews and saves. One schema for both
- * versions, a discriminated union on `version` — version 1 is fixed work, version 2 adds questions whose answers fill
- * `{{key}}` placeholders. Recipes are strict and always were: every key is required, and an unknown one (an approval,
- * provider or credential setting smuggled in) is refused by name.
- *
- * A success check is the scope's own saved criterion (src/contracts/scope.ts), strict about its keys. The reader fills
- * an absent or empty `how` with null before parsing, as the scope reader always has. What JSON Schema can't say runs
- * in recipes.ts after parsing, each refusal naming its field: the 32 KB size, text and placeholder rules, schedules,
- * the budget/schedule/deliverable/planning combinations, question keys and the scope reader's byte, control-character
- * and duplicate checks. Saved recipes and previews keep their exact bytes, so their digests still match.
- */
 import { z } from "zod";
 import { parseContract, versioned } from "./contract.js";
 import { savedCriterionSchema } from "./scope.js";
 import { isRecord } from "../is-record.js";
 export const RECIPE_FORMAT = "standing-orders-recipe";
-/** Numbers the recipe rules use, in plain code after parsing (bytes of the whole document, characters of a field). */
 export const RECIPE_LIMITS = { documentBytes: 32_768, description: 400, inputs: 8, label: 80, answer: 500 };
-/** A question a version 2 recipe asks: its key, its label and an optional default answer (null for none). */
 export const recipeInputSchema = z.strictObject({
     key: z.string(),
     label: z.string(),
@@ -39,13 +25,11 @@ const recipeFields = {
 export const recipeV1Schema = versioned(1, recipeFields);
 export const recipeV2Schema = versioned(2, { ...recipeFields, inputs: z.array(recipeInputSchema).min(1).max(RECIPE_LIMITS.inputs) });
 export const recipeDocumentSchema = z.discriminatedUnion("version", [recipeV1Schema, recipeV2Schema]);
-/** A success check as the scope reader reads it: an absent or empty `how` is null; every other key, known or not, as given. */
 function checkBody(entry) {
     if (!isRecord(entry) || (entry["how"] !== undefined && entry["how"] !== ""))
         return entry;
     return { ...entry, how: null };
 }
-/** Read a recipe's structure (format and version already checked): every refusal is a path-named issue. */
 export function readRecipeDocument(input) {
     const body = Array.isArray(input["acceptance"]) ? { ...input, acceptance: input["acceptance"].map(checkBody) } : input;
     return input["version"] === 2 ? parseContract(recipeV2Schema, body) : parseContract(recipeV1Schema, body);

package/dist/contracts/release-check.js

@@ -1,36 +1,19 @@
-/**
- * The release check's structured results (docs/plans/release-once.md, parts 2 and 3): what the orchestrator
- * (`scripts/release-check.mjs`) reports on its last stdout line, what the plane seals before and after a check runs
- * (the inventory, the execution context, a targeted plan and its obligation snapshot), and the identities every one of
- * them names. Only the plane writes the sealed payloads, from typed values; the report comes from the check itself and
- * is read strictly — anything that doesn't match is no report.
- *
- * Coverage trusts test code (Alex, 2026-10-25): a test runs as the same user as the harness, so these results guard
- * against accidental damage — stray processes, leftover files, output that looks like a report — not a hostile test.
- * Authority decisions never read them.
- */
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
-/** The parts a release check is made of. */
 export const CHECK_PARTS = ["typecheck", "build", "unit", "flows", "app", "flows-real", "app-real", "upgrade"];
 export const JOURNEY_SCRIPTS = ["app", "flows"];
 const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
-/** A repository path as a tree names it: relative, normalized, no control characters. */
 const repoPath = z.string().min(1).max(512).regex(/^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))[^\u0000-\u001f\\]+$/);
 const name = z.string().min(1).max(2000);
 const groupName = z.string().min(1).max(200).regex(/^[A-Za-z0-9._/-]+$/);
 const versionName = z.string().regex(/^\d+\.\d+\.\d+$/);
 const count = z.int().min(0).max(1_000_000);
-/** What the orchestrator reports, as the last line of its output: `TOOLROLL_CHECK_REPORT <json>`, at most 256 KiB. */
 export const CHECK_REPORT_PREFIX = "TOOLROLL_CHECK_REPORT ";
 export const CHECK_REPORT_MAX_BYTES = 256 * 1024;
 export const checkReportSchema = versioned(1, {
-    /** The nonce the plane wrote on the check's stdin: the report is this run's. */
     nonce: hex64,
     mode: z.enum(["full", "targeted"]),
-    /** The digest of the targeted plan the orchestrator ran, as it received it; null for a full check. */
     planDigest: hex64.nullable(),
-    /** The orchestrator's own exit code. */
     exitCode: z.int().min(0).max(255),
     parts: z.array(z.strictObject({
         part: z.enum(CHECK_PARTS),
@@ -38,20 +21,14 @@ export const checkReportSchema = versioned(1, {
         ran: z.boolean(),
         code: z.int().min(0).max(255).nullable(),
         timedOut: z.boolean(),
-        /** When it started, the signal that ended it, whether the check stopped it (another part's failure or the check's
-         * own limit) and whether it could start at all — each apart from its code. Absent from an older orchestrator. */
         startedAt: z.string().max(40).nullable().optional(),
         signal: z.string().max(20).nullable().optional(),
         stopped: z.boolean().optional(),
         spawnFailed: z.boolean().optional(),
     })).max(CHECK_PARTS.length),
-    /** The unit suite, from the Vitest main process's fd-3 lines: every file's outcome, and the identities that failed,
-     * were skipped, passed on a retry or were asked about. Null when the unit part didn't run. */
     units: z.strictObject({
         reusedFromCI: z.boolean(),
-        /** Vitest reached the end of its run and said so. */
         finished: z.boolean(),
-        /** Errors no test owned (an unhandled rejection, a worker crash). */
         runErrors: count,
         files: z.array(z.strictObject({
             file: repoPath,
@@ -66,27 +43,21 @@ export const checkReportSchema = versioned(1, {
             flaky: z.boolean(),
         })).max(5000),
     }).nullable(),
-    /** Each journey script's run: the groups it ran and every journey's outcome in each. */
     journeys: z.array(z.strictObject({
         script: z.enum(JOURNEY_SCRIPTS),
         kind: z.enum(["scripted", "real"]),
         finished: z.boolean(),
-        /** The runner listed its groups before any started (an empty list is an explicit "none of this kind"); absent or
-         * false, the run has no inventory and nothing it lacks can be told from nothing it owed. */
         inventoried: z.boolean().optional(),
         groups: z.array(z.strictObject({
             group: groupName,
             state: z.enum(["passed", "failed", "not-run"]),
-            /** Passed only on the runner's retry. */
             retried: z.boolean(),
-            /** It ended with no result line to read, or only the browser-error check failed. */
             unattributed: z.boolean(),
             journeys: z.array(z.strictObject({ name, state: z.enum(["passed", "failed", "skipped"]) })).max(500),
         })).max(200),
     })).max(4),
     upgrades: z.strictObject({
         finished: z.boolean(),
-        /** The upgrade path listed its versions before any ran. */
         inventoried: z.boolean().optional(),
         versions: z.array(z.strictObject({ version: versionName, state: z.enum(["passed", "failed", "not-run"]) })).max(500),
     }).nullable(),
@@ -94,20 +65,12 @@ export const checkReportSchema = versioned(1, {
 export function readCheckReport(input) {
     return readVersioned(checkReportSchema, input);
 }
-/** What a check must account for, sealed before it runs: the unit files (from the verified tree and Vitest's include
- * globs) and the parts selected. The journey groups and upgrade versions come from the check's own report and are
- * sealed beside these after it ran. */
 export const checkInventorySchema = versioned(1, {
     units: z.array(repoPath).max(20_000),
-    /** The parts the check owes. For a full check the plane decides them before it runs (check-report.ts
-     * fullObligationsOf) and they ride on the handshake; every one needs an outcome. */
     parts: z.array(z.enum(CHECK_PARTS)).max(CHECK_PARTS.length),
-    /** Whether CI's run of the exact commit may stand in for the local unit suite. Absent is no. */
     ciSubstitute: z.boolean().optional(),
-    /** Whether the plane prepared it as a release's check (sealed with the attempt; absent on older inventories). */
     release: z.boolean().optional(),
 });
-/** The sealed inventory artifact: what was sealed before the run, and what the run declared. */
 export const sealedInventorySchema = versioned(1, {
     sealed: checkInventorySchema,
     declared: z.strictObject({
@@ -115,49 +78,34 @@ export const sealedInventorySchema = versioned(1, {
         versions: z.array(versionName).max(500),
     }),
 });
-/** Where a check ran: what has to match for an earlier result to stand beside a later one. */
 export const checkContextSchema = versioned(1, {
     node: z.string().max(40),
     platform: z.string().max(40),
     arch: z.string().max(40),
-    /** The verified blob id of package-lock.json, or null when the tree has none. */
     lockfile: z.string().max(64).nullable(),
-    /** One digest over every harness file's verified blob id. */
     harness: hex64,
     grant: z.strictObject({ id: z.int(), digest: z.string().max(128) }),
     access: z.string().max(40),
 });
-/** A targeted check's plan: exactly what it runs, sealed before it runs. */
 export const targetedPlanSchema = versioned(1, {
-    /** The full check A whose sealed evidence every obligation comes from. */
     base: z.int().min(1),
     units: z.array(repoPath).max(5000),
     sanity: z.array(repoPath).max(200),
     groups: z.array(z.strictObject({ script: z.enum(JOURNEY_SCRIPTS), kind: z.enum(["scripted", "real"]), groups: z.array(groupName).max(200) })).max(4),
     versions: z.array(versionName).max(500),
-    /** Whole parts to run again (a part-level outcome at A). */
     parts: z.array(z.enum(CHECK_PARTS)).max(CHECK_PARTS.length),
-    /** The required identities: each must be reported, and pass. */
     required: z.array(z.string().min(1).max(2600)).max(5000),
 });
-/** The earlier targeted runs of this generation a targeted attempt took into account, sealed with it. */
 export const obligationSnapshotSchema = versioned(1, {
     authority: z.int().min(1),
     base: z.int().min(1),
     earlier: z.array(z.strictObject({ run: z.int().min(1), reportDigest: z.string().max(64).nullable(), failed: z.array(z.string().min(1).max(2600)).max(5000) })).max(200),
 });
-// ------------------------------------------------------------------ advisory learning lines (docs/plans/learning-loops.md)
-/** The advisory learning line a check prints before its report: `TOOLROLL-LEARN <json>`, at most 64 KiB, holding only
- * the requested identities that ran. Never part of the report: buildReport, reportLine and fullCheckProblem don't read
- * it, and a missing, malformed or oversized one loses learning evidence only. */
 export const LEARN_PREFIX = "TOOLROLL-LEARN ";
 export const LEARN_MAX_BYTES = 64 * 1024;
 export const LEARN_MAX_IDENTITIES = 200;
-/** An exact case: a unit test (`unit:<file>::<name>`) or a journey (`journey:<script>:<kind>:<group>::<name>`), never a
- * file, group, part or version; one line, no control characters, at most 2600 characters. */
 const EXACT_CASE = /^(?:unit:[^\u0000-\u001f\\:][^\u0000-\u001f\\]*?::[^\u0000-\u001f]+|journey:(?:app|flows):(?:scripted|real):[A-Za-z0-9._/-]{1,200}::[^\u0000-\u001f]+)$/;
 export const isExactCase = (identity) => typeof identity === "string" && identity.length <= 2600 && EXACT_CASE.test(identity);
-/** What the plane asks a check to report for learning: exact cases only, first seen first, at most 200. */
 export function learnRequest(identities) {
     return [...new Set(identities.filter(isExactCase))].slice(0, LEARN_MAX_IDENTITIES);
 }
@@ -165,21 +113,12 @@ export const learnLineSchema = z.strictObject({
     nonce: hex64,
     results: z.array(z.strictObject({ identity: z.string().min(1).max(2600), state: z.enum(["passed", "failed", "skipped"]) })).max(LEARN_MAX_IDENTITIES),
 });
-// ------------------------------------------------------------------ identities
-/** A unit test: its file and full name. */
 export const unitIdentity = (file, testName) => `unit:${file}::${testName}`;
-/** A unit file. */
 export const fileIdentity = (file) => `file:${file}`;
-/** A journey group of a script and kind. */
 export const groupIdentity = (script, kind, group) => `group:${script}:${kind}:${group}`;
-/** One journey in its group. */
 export const journeyIdentity = (script, kind, group, journey) => `journey:${script}:${kind}:${group}::${journey}`;
-/** An upgrade version. */
 export const versionIdentity = (version) => `upgrade:${version}`;
-/** A whole part. */
 export const partIdentity = (part) => `part:${part}`;
-/** One fd-3 result line a harness process writes (test/release-reporter.ts, scripts/check-results.mjs). The
- * orchestrator reads only these shapes; anything else on the pipe is passed over. */
 export const checkResultLineSchema = z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("unit-case"), file: repoPath, name, state: z.enum(["passed", "failed", "skipped"]), flaky: z.boolean() }),
     z.strictObject({ kind: z.literal("unit-file"), file: repoPath, state: z.enum(["passed", "failed", "skipped"]), passed: count, failed: count, skipped: count, flaky: z.boolean() }),

package/dist/contracts/release-terms.js

@@ -1,24 +1,13 @@
-/**
- * A release scope's terms (docs/plans/release-once.md, part 1): what a person agrees to when they approve a release —
- * the repository (from Toolroll's records), version, head branch, pull request and base, the approved commit and its
- * tree, the effective carry policy, the release check grant, the sealed check access (fenced) and the expiry. Part of
- * the scope digest when present; read strictly, so a row that doesn't match is a stated problem, never authority.
- */
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
-/** The carry rules this runtime knows (release-carry.ts CARRY_RULES). A sealed policy naming any other refuses. */
 export const CARRY_RULES_VERSION = 1;
 export const releasePolicySchema = versioned(1, {
     rules: z.literal(CARRY_RULES_VERSION),
-    /** False: every later commit asks again ("Ask for every release commit", or `toolroll release --no-carry`). */
     carry: z.boolean(),
-    /** The project's own protection: everything (protectProject) or these paths, which never carry. */
     protectProject: z.boolean(),
     protectedPaths: z.array(z.string().min(1).max(400)).max(200),
     limits: z.strictObject({ lines: z.int().min(0).max(1_000_000), files: z.int().min(0).max(100_000), churn: z.int().min(0).max(1_000_000) }),
-    /** "Carry release approvals when checks aren't sandboxed" (a person's project setting, off by default). Absent (a
-     * policy sealed before it existed): off. */
     unsandboxedCarry: z.boolean().optional(),
 });
 const sha = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
@@ -32,8 +21,6 @@ export const releaseTermsSchema = versioned(1, {
     approvedTree: sha,
     policy: releasePolicySchema,
     grant: z.strictObject({ id: z.int(), digest: z.string().min(1).max(128) }),
-    /** The check access the release check runs with at approval: the fence, or (only with unsandboxedCarry sealed in the
-     * policy) a wider one. Never wider later: a check that reaches further than this stops the release. */
     access: z.enum(["sandboxed", "sign-ins", "unsandboxed"]),
     expiresAt: z.iso.datetime(),
 });
@@ -43,15 +30,12 @@ export function readReleaseTerms(input) {
 export function readReleasePolicy(input) {
     return readVersioned(releasePolicySchema, input);
 }
-/** The digest a scope binds for its release terms, domain-separated from every other digest input. */
 export function releaseTermsDigest(terms) {
     return createHash("sha256").update(`release-terms:${JSON.stringify(terms)}`).digest("hex");
 }
-/** The digest of an effective policy, as release_authority.policy_digest holds it. */
 export function releasePolicyDigest(policy) {
     return createHash("sha256").update(`release-policy:${JSON.stringify(policy)}`).digest("hex");
 }
-/** Strict stored terms: null column → null; anything that isn't exactly terms → a problem. */
 export function storedReleaseTerms(raw) {
     if (raw === null || raw === undefined)
         return { ok: true, terms: null };
@@ -67,19 +51,10 @@ export function storedReleaseTerms(raw) {
     const read = readReleaseTerms(parsed);
     if (!read.ok)
         return { ok: false, problem: `the release terms don't match their contract (${read.issues[0]?.line ?? "invalid"})` };
-    // Bytes exactly as this code writes them (store.ts serializeReleaseTerms): a reordered or padded row is not what was signed.
     if (JSON.stringify(read.value) !== raw)
         return { ok: false, problem: "the release terms are not stored exactly as written" };
     return { ok: true, terms: read.value };
 }
-/**
- * A release check's purpose (docs/plans/pipeline-speed.md, P0): what a person agrees to when they approve a release
- * whose later commits can't carry (its checks run outside the sandbox, or carrying is off) — this exact candidate is a
- * release's check. It never carries a later commit, never lets CI stand in for the check's units and never approves
- * itself; it lets the plane hold the check to the release's strict report rules and rerun it, on this identical
- * candidate under this same approval, after a failure the plane itself confirmed as infrastructure. Part of the scope
- * digest when present; read strictly. A scope carries terms or this purpose, never both.
- */
 export const releaseCheckPurposeSchema = versioned(1, {
     purpose: z.literal("release-check"),
     repo: z.string().min(1).max(4096),
@@ -95,11 +70,9 @@ export const releaseCheckPurposeSchema = versioned(1, {
 export function readReleaseCheckPurpose(input) {
     return readVersioned(releaseCheckPurposeSchema, input);
 }
-/** The digest a scope binds for its release check purpose, domain-separated from the terms' and every other input. */
 export function releaseCheckPurposeDigest(purpose) {
     return createHash("sha256").update(`release-check-purpose:${JSON.stringify(purpose)}`).digest("hex");
 }
-/** Strict stored purpose: null column → null; anything that isn't exactly a purpose, as written → a problem. */
 export function storedReleaseCheckPurpose(raw) {
     if (raw === null || raw === undefined)
         return { ok: true, purpose: null };

package/dist/contracts/retention.js

@@ -1,24 +1,12 @@
-/**
- * Retention settings (retention.ts): which kinds of data have a period, and how long each is kept — a whole number of
- * days from 1 to 3650, or null for forever. One schema for the kind, the period and the full set of periods; the
- * types retention.ts exports are derived from them.
- *
- * `retention_setting` rows are read by the store (`retentionChosen`, item 18's to move onto `retentionRowSchema`): a
- * row's kind and days as SQLite's CHECK constraint keeps them, unknown columns ignored. Text a person types ("90d",
- * "1y", "forever") is turned into days in plain code (retention.ts `parsePeriod`) and then checked by this schema.
- */
 import { z } from "zod";
 export const RETENTION_KIND_VALUES = ["evidence", "checkouts", "chat", "notifications"];
 export const retentionKindSchema = z.enum(RETENTION_KIND_VALUES);
 export const RETENTION_DAYS = { min: 1, max: 3650 };
-/** A period: whole days from 1 to 3650, or null for forever. */
 export const retentionDaysSchema = z.int().min(RETENTION_DAYS.min).max(RETENTION_DAYS.max).nullable();
-/** Every kind's period, as the sweep and the settings page read them. */
 export const retentionPeriodsSchema = z.object({
     evidence: retentionDaysSchema,
     checkouts: retentionDaysSchema,
     chat: retentionDaysSchema,
     notifications: retentionDaysSchema,
 });
-/** A saved `retention_setting` row: only a kind someone chose has one. */
 export const retentionRowSchema = z.object({ kind: retentionKindSchema, days: retentionDaysSchema });

package/dist/contracts/review-findings.js

@@ -1,19 +1,8 @@
-/**
- * The automatic build review's findings (build-review.ts): one schema for the reply a reviewer gives, the `findings`
- * a Claude reviewer's `--json-schema` describes (provider.ts, inside the review channel it shares with evidence
- * reviews), and what `build_review.findings_json` keeps. `parseBuildFindings` (reviewer.ts) reads a reply through it;
- * a saved row is the same payload, written by `settle` after that read.
- *
- * As before, controls and runs of whitespace collapse to one space before text limits are checked. Unknown keys
- * are ignored in both the review envelope and each finding.
- */
 import { z } from "zod";
 import { TEXT_LIMITS } from "../text-limits.js";
 import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
 export const FINDING_SEVERITIES = ["HIGH", "MEDIUM", "LOW"];
-/** How many findings one review may raise. */
 export const FINDINGS_MAX = 40;
-/** One finding: how bad, where (a path and the closest line), and how it fails, in one sentence. */
 export const buildFindingSchema = z.object({
     severity: z.enum(FINDING_SEVERITIES),
     file: limited("file", "reviewPath").min(1).describe(`file: at most ${TEXT_LIMITS.reviewPath} characters, on one line.`),
@@ -24,9 +13,7 @@ export const FINDINGS_VERSION = 1;
 export const buildFindingsSchema = versioned(FINDINGS_VERSION, {
     findings: z.array(buildFindingSchema).max(FINDINGS_MAX),
 }).strip();
-/** The `findings` a reviewer's structured reply may carry (provider.ts's review channel), from the same schema. */
 export const FINDINGS_MODEL_SCHEMA = toModelSchema(buildFindingsSchema.shape.findings);
-/** Read a findings payload: version 1 as itself, a newer one refused plainly, anything else by path. */
 export function readBuildFindings(input) {
     if (typeof input === "object" && input !== null && !Array.isArray(input)) {
         const body = input;

package/dist/contracts/route-results.js

@@ -1,19 +1,10 @@
-/**
- * Result records (docs/plans/results-routing.md, slice 1): the words and shapes a task family's result record is kept
- * and shown in. A policy path (release-auto.ts EVAL_POLICY): the states, reasons and the execution-class table decide
- * what a cheaper model's evidence is, so a change to them needs a person.
- */
 import { z } from "zod";
-/** A record's lifecycle. Only mature and rejected records are decided; pending and provisional never count anywhere. */
 export const RECORD_STATES = ["pending", "provisional", "mature", "rejected", "not-counted"];
-/** Why a record was rejected, in the order they are checked. */
 export const REJECT_REASONS = ["model-failures", "task-failed", "cancelled-after-result", "high-finding", "person-revision", "proof-refuted", "check-failed"];
-/** Why a record is not counted. Never counted as good, never as 0. */
 export const NOT_COUNTED_REASONS = [
     "before-records", "not-eligible", "mixed-cohort", "mixed-models", "model-not-reported", "infrastructure-only", "cancelled-before-result",
     "no-check", "check-unavailable", "touched-protected", "changed-files-unknown", "unanswered",
 ];
-/** The plain words for each reason. */
 export const REASON_WORDS = Object.freeze({
     "model-failures": "two or more attempts failed on the model's own account",
     "task-failed": "the task failed",
@@ -35,19 +26,14 @@ export const REASON_WORDS = Object.freeze({
     "changed-files-unknown": "changed files unknown",
     "unanswered": "no answer in 30 days",
 });
-/** Why a run was refused a cohort before dispatch: any of these makes its record not counted ("not eligible"). */
 export const INELIGIBLE_REASONS = ["no-sealed-route", "not-built-in", "large", "risky", "unsized", "strict", "evidence-demands", "automerge", "release", "protected"];
-/** Who a revision came from (task_ref.revision_origin). Only `person` rejects a record. */
 export const REVISION_ORIGINS = ["person", "automatic-review", "flow", "lead", "machine"];
-/** A failed run's execution class, kept before the tick normalizes its reason (run.exec_class). */
 export const EXEC_CLASSES = ["model", "infrastructure"];
-/** The build leg's sealed selection, as a run's cohort keeps it (route v3 `selection`; earlier routes by `chosen`). */
 export const selectionSchema = z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("rule"), rule: z.number().int().positive(), ruleGeneration: z.number().int().positive() }),
     z.strictObject({ kind: z.literal("trial"), rule: z.number().int().positive(), reservation: z.number().int().positive() }),
     z.strictObject({ kind: z.enum(["configured", "override", "pin"]) }),
 ]);
-/** One record as `toolroll models results --json` returns it. */
 export const resultRecordSchema = z.strictObject({
     task: z.string(),
     repo: z.string().nullable(),
@@ -62,7 +48,6 @@ export const resultRecordSchema = z.strictObject({
     decidedAt: z.string().nullable(),
     failures: z.strictObject({ model: z.number().int(), infrastructure: z.number().int() }),
     spend: z.strictObject({ apiMicrousd: z.number().int(), subscriptionRuns: z.number().int(), subscriptionTokens: z.number().int(), unknownRuns: z.number().int(), remediationRuns: z.number().int() }),
-    /** Counts that keep accumulating after the verdict is final, until the record closes. */
     personRevisions: z.number().int(),
     firstCheckPassed: z.boolean().nullable(),
     turns: z.strictObject({ known: z.number().int(), unknownRuns: z.number().int() }),