toolroll 0.9.40 → 0.9.42

package/dist/observations.js

@@ -6,6 +6,7 @@ import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { canonicalAcceptance } from "./scope.js";
 import { readVerifiedArtifact, scanForSecrets, storeEvidence } from "./evidence.js";
+import { readObservationRequest } from "./contracts/observation-request.js";
 export const OBSERVATION_MAILBOX = "STANDING-ORDERS-OBSERVATIONS.json";
 export const OBSERVATION_CAPTURE = "machine focused observations v1";
 export const OBSERVATION_FILE = "REVIEW-OBSERVATIONS.json";
@@ -62,17 +63,20 @@ export function parseObservationCases(raw, ids) {
     if (Buffer.byteLength(raw) > 16 * 1024)
         throw Error("The observation request is too large.");
     const parsed = JSON.parse(raw);
-    if (parsed?.version !== 1 || !Array.isArray(parsed.observations) || parsed.observations.length < 1 || parsed.observations.length > 4 ||
-        Object.keys(parsed).some(k => k !== "version" && k !== "observations"))
+    const read = readObservationRequest(parsed);
+    // A problem inside one observation is that observation's; anything else is the request's shape.
+    if (!read.ok && read.issues.some(issue => !/^observations\[\d+\]/.test(issue.path)))
         throw Error("Use one to four focused test observations.");
-    const cases = parsed.observations;
-    for (const item of cases) {
-        if (!item || Object.keys(item).some(k => !["criterion", "at", "testPath", "testName"].includes(k)) || !ids.includes(item.criterion) ||
-            !["base", "head"].includes(item.at) || !pathOkay(item.testPath) || !/\.(test|spec)\.[cm]?[jt]sx?$/.test(item.testPath) ||
-            typeof item.testName !== "string" || item.testName.trim() === "" || item.testName.length > 500 || /[\u0000-\u001f\u007f]/.test(item.testName)) {
-            throw Error("An observation must name a requested criterion, base/head, one test file and one test name. Shell commands are not accepted.");
-        }
+    const bad = () => Error("An observation must name a requested criterion, base/head, one test file and one test name. Shell commands are not accepted.");
+    if (!read.ok)
+        throw bad();
+    for (const item of read.value.observations) {
+        if (!ids.includes(item.criterion) || !pathOkay(item.testPath) || !/\.(test|spec)\.[cm]?[jt]sx?$/.test(item.testPath) ||
+            item.testName.trim() === "" || item.testName.length > 500 || /[\u0000-\u001f\u007f]/.test(item.testName))
+            throw bad();
     }
+    // The cases as written: their key order is the receipt's, and two written in different orders are distinct, as before.
+    const cases = parsed.observations;
     if (new Set(cases.map(c => JSON.stringify(c))).size !== cases.length || ids.some(id => !cases.some(c => c.criterion === id)))
         throw Error("Every requested criterion needs a distinct observation.");
     return cases;

package/dist/operate.js

@@ -98,7 +98,8 @@ import { admissionRecorded, admitProject, commandLineActor } from "./project-adm
 import { leadClaim, leadSay, noteLeadWork } from "./lead-voice.js";
 import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
-import { envelopeJson } from "./envelope.js";
+// Every envelope is checked against its command's schema (logged, never refused), then serialized unchanged.
+import { checkedEnvelopeJson as envelopeJson } from "./contracts/cli.js";
 import { hasDisguisedText, hasForbiddenControls, validateNote } from "./decision.js";
 import { readVerifiedArtifact, readVerifiedReport, storeEvidence } from "./evidence.js";
 import { contractChangesOf, decodePlanContractRecord, describeContractChanges, encodePlannerSource, plannerSourceOf } from "./planner-source.js";

package/dist/process-recovery-native.d.ts

@@ -1,21 +1,11 @@
+import { type DarwinProcessIdentity } from "./contracts/native-census.js";
 export type PreparedDarwinProcessCensus = {
     sourcePath: string;
     executablePath: string;
     sourceSha256: string;
     executableSha256: string;
 };
-export type DarwinProcessIdentity = {
-    pid: number;
-    ppid: number | null;
-    uid: number | null;
-    birthMs: number | null;
-    uniqueId: string | null;
-    parentUniqueId: string | null;
-    traced: boolean | null;
-    executable: string | null;
-    originalParentVersion: number | null;
-    pidVersion?: number;
-};
+export type { DarwinProcessIdentity } from "./contracts/native-census.js";
 export type DarwinManagedService = {
     domain: string;
     label: string;
@@ -169,4 +159,3 @@ export declare function collectDarwinCoalitionSnapshot(args: {
     maxAttempts?: number;
     anchorPids?: number[];
 }): Promise<DarwinCoalitionRecoverySnapshot>;
-export {};

package/dist/process-recovery-native.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { hostname, release } from "node:os";
 import { join } from "node:path";
+import { darwinNativeCensusSchema, darwinProcessIdentitySchema, kernelIdInRange } from "./contracts/native-census.js";
 const digest = (data) => createHash("sha256").update(data).digest("hex");
 const cleanEnv = { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C", TZ: "UTC" };
 /** Facts only. Public KERN_PROC_ALL supplies birth/UID/trace metadata without
@@ -189,15 +190,17 @@ const nullable = (value, test) => value === null || test(value);
 const safeText = (value) => typeof value === "string" && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value);
 /** Strict parser also strips every field not in the facts contract. */
 export function parseDarwinNativeSnapshot(text) {
-    const v = JSON.parse(text);
-    if (!v || v.schema !== 1 || !nullable(v.bootId, (x) => typeof x === "string" && /^[a-fA-F0-9-]{36}$/.test(x)) || !isInt(v.collectorPid, 2) || typeof v.complete !== "boolean" || !Array.isArray(v.processes) || v.processes.length > 100_000 || !Array.isArray(v.errors) || !v.errors.every(x => ["kernel-process-table-unreadable", "process-membership-unreadable", "process-identity-unreadable", "boot-identity-unreadable", "coalition-counters-unreadable", "coalition-counters-changed", "coalition-count-mismatch", "anchor-identity-unreadable"].includes(x)))
+    const read = darwinNativeCensusSchema.safeParse(JSON.parse(text));
+    if (!read.success)
         throw new Error("malformed-native-census");
+    const v = read.data;
     const pids = new Set(), ids = new Set();
     const processes = v.processes.map((r) => {
-        if (!r || typeof r !== "object")
+        const row = darwinProcessIdentitySchema.safeParse(r);
+        if (!row.success)
             throw new Error("malformed-process-identity");
-        const p = r;
-        if (!isInt(p.pid, 1) || pids.has(p.pid) || !nullable(p.ppid, isInt) || !nullable(p.uid, isInt) || !nullable(p.birthMs, (n) => typeof n === "number" && Number.isFinite(n) && n > 0) || !nullable(p.uniqueId, isId) || p.uniqueId === "0" || (p.uniqueId !== null && ids.has(p.uniqueId)) || !nullable(p.parentUniqueId, isId) || (p.traced !== null && typeof p.traced !== "boolean") || !nullable(p.executable, safeText) || !nullable(p.originalParentVersion, (n) => isInt(n) && n <= 0xffffffff) || (p.pidVersion !== undefined && (!isInt(p.pidVersion) || p.pidVersion > 0xffffffff)))
+        const p = row.data;
+        if (pids.has(p.pid) || (p.uniqueId !== null && !kernelIdInRange(p.uniqueId)) || p.uniqueId === "0" || (p.uniqueId !== null && ids.has(p.uniqueId)) || (p.parentUniqueId !== null && !kernelIdInRange(p.parentUniqueId)))
             throw new Error("malformed-process-identity");
         pids.add(p.pid);
         if (p.uniqueId !== null)

package/dist/project-tools.d.ts

@@ -1,26 +1,6 @@
 import type { Store, ToolActionInfo } from "./store.js";
-/** One secret a tool needs: an env name for a local server, or the value behind an http header. */
-export type ToolSecret = {
-    name: string;
-    optional: boolean;
-};
-export type ToolSpec = {
-    name: string;
-    transport: "stdio" | "http";
-    /** stdio: the program and its arguments (no secrets in either). */
-    command: string | null;
-    args: string[];
-    /** http: the server's address. */
-    url: string | null;
-    /** Every secret the tool needs. stdio: each is an env variable of the server process. */
-    secrets: ToolSecret[];
-    /** http: the secret sent as `Authorization: Bearer <value>`. */
-    bearer: string | null;
-    /** http: header name → the secret sent as its raw value. */
-    headerSecrets: Record<string, string>;
-    /** What it does, in plain words. */
-    about: string;
-};
+import { type ToolSecret, type ToolSpec } from "./contracts/integration-metadata.js";
+export type { ToolSecret, ToolSpec };
 export type ToolTest = {
     at: string;
     ok: boolean;
@@ -68,7 +48,10 @@ export declare function catalogTool(id: string): (ToolSpec & {
 }) | null;
 /** What a build is held to: how the server starts and which secrets it names — never their values or its description. */
 export declare function toolDigest(spec: ToolSpec): string;
-/** A tool definition from any source (catalog, console form, the lead, an import), checked whole. Throws in plain words. */
+/**
+ * A tool definition from any source (catalog, console form, the lead, an import, a saved row), checked whole and made
+ * the spec its schema (src/contracts/integration-metadata.ts) says. Throws in plain words.
+ */
 export declare function validateToolSpec(input: Record<string, unknown>): ToolSpec;
 /** How the tool starts, in one line a person can check. Never a secret value. */
 export declare function toolCommandLine(spec: ToolSpec): string;
@@ -234,4 +217,3 @@ export declare function toolStanding(tool: ProjectTool, secretsSet: readonly str
 export declare function secretsSetFor(repo: string, tool: ToolSpec, home?: string): string[];
 /** A command line split into program and arguments, honouring "double" and 'single' quotes. */
 export declare function splitCommandLine(line: string): string[];
-export {};

package/dist/project-tools.js

@@ -23,9 +23,7 @@ import { isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { scanForSecrets } from "./evidence.js";
 import { namedPath } from "./names.js";
-const NAME = /^[a-z0-9][a-z0-9_-]{0,39}$/;
-const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
-const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
+import { HEADER_NAME, SECRET_NAME, TOOL_NAME as NAME, TOOL_SPEC_LIMITS as LIMITS, readToolSpec } from "./contracts/integration-metadata.js";
 /** Env names a tool may never claim: the process's own plumbing, every
  * provider credential, and anything that changes how a program or its
  * interpreter loads (a secret's value must stay data, never code). */
@@ -89,17 +87,20 @@ const str = (value, cap, what) => {
         throw new Error(`${what} cannot contain control characters.`);
     return value.trim();
 };
-/** A tool definition from any source (catalog, console form, the lead, an import), checked whole. Throws in plain words. */
+/**
+ * A tool definition from any source (catalog, console form, the lead, an import, a saved row), checked whole and made
+ * the spec its schema (src/contracts/integration-metadata.ts) says. Throws in plain words.
+ */
 export function validateToolSpec(input) {
-    const name = str(input["name"], 40, "A short name").toLowerCase();
+    const name = str(input["name"], LIMITS.name, "A short name").toLowerCase();
     if (!NAME.test(name))
-        throw new Error("The name is lowercase letters, numbers, - and _ (up to 40), starting with a letter or number.");
+        throw new Error(`The name is lowercase letters, numbers, - and _ (up to ${LIMITS.name}), starting with a letter or number.`);
     const transport = input["transport"] === "http" ? "http" : input["transport"] === "stdio" || input["transport"] === undefined ? "stdio" : null;
     if (transport === null)
         throw new Error("A tool runs as a local program or at a web address.");
     const secretsIn = Array.isArray(input["secrets"]) ? input["secrets"] : [];
-    if (secretsIn.length > 12)
-        throw new Error("A tool can name up to 12 secrets.");
+    if (secretsIn.length > LIMITS.secrets)
+        throw new Error(`A tool can name up to ${LIMITS.secrets} secrets.`);
     const secrets = [];
     for (const one of secretsIn) {
         const entry = typeof one === "string" ? { name: one, optional: false } : one;
@@ -115,14 +116,14 @@ export function validateToolSpec(input) {
     let command = null, args = [], url = null, bearer = null;
     const headerSecrets = {};
     if (transport === "stdio") {
-        command = str(input["command"], 400, "The command");
+        command = str(input["command"], LIMITS.command, "The command");
         const argsIn = input["args"] === undefined ? [] : input["args"];
-        if (!Array.isArray(argsIn) || argsIn.length > 40 || argsIn.some(arg => typeof arg !== "string" || arg.length > 400 || /[\u0000-\u001f\u007f]/.test(arg)))
-            throw new Error("Arguments are up to 40 plain words.");
+        if (!Array.isArray(argsIn) || argsIn.length > LIMITS.args || argsIn.some(arg => typeof arg !== "string" || arg.length > LIMITS.arg || /[\u0000-\u001f\u007f]/.test(arg)))
+            throw new Error(`Arguments are up to ${LIMITS.args} plain words.`);
         args = argsIn;
     }
     else {
-        url = str(input["url"], 500, "The address");
+        url = str(input["url"], LIMITS.url, "The address");
         let parsed;
         try {
             parsed = new URL(url);
@@ -149,14 +150,17 @@ export function validateToolSpec(input) {
             headerSecrets[header] = secret;
         }
     }
-    const about = typeof input["about"] === "string" && input["about"].trim() !== "" ? input["about"].trim().slice(0, 240)
+    const about = typeof input["about"] === "string" && input["about"].trim() !== "" ? input["about"].trim().slice(0, LIMITS.about)
         : TOOL_CATALOG.find(one => one.name === name)?.about
             ?? (transport === "http" ? `Tools from ${new URL(url).hostname}.` : `Tools from ${programName(command, args)}.`);
     const spec = { name, transport, command, args, url, secrets, bearer, headerSecrets, about };
     // Values belong in the secret store; a key typed into a command, argument or address is refused.
     if (scanForSecrets([command ?? "", ...args, url ?? "", about].join("\n")).length > 0)
         throw new Error("That looks like a key or token in the tool's settings. Name it as a secret instead; its value is set on the secure Tools screen.");
-    return spec;
+    const checked = readToolSpec(spec);
+    if (!checked.ok)
+        throw new Error(`That tool is not valid: ${checked.issues.map(issue => issue.line).join("; ")}`);
+    return checked.value;
 }
 /** What a local tool is, in a word: the package a runner like npx starts, else the program's own name. */
 function programName(command, args) {
@@ -251,7 +255,7 @@ function fromClaudeEntry(name, raw, source) {
         if (type === "stdio") {
             for (const [key, value] of Object.entries((entry["env"] ?? {})))
                 keep(key, value);
-            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 40), transport: "stdio", command: entry["command"], args: entry["args"] ?? [], secrets });
+            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, LIMITS.name), transport: "stdio", command: entry["command"], args: entry["args"] ?? [], secrets });
             return { spec, source, values };
         }
         if (type === "http") {
@@ -269,7 +273,7 @@ function fromClaudeEntry(name, raw, source) {
                 else if (keep(secret, value))
                     headerSecrets[header] = secret;
             }
-            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 40), transport: "http", url: entry["url"], secrets, bearer, headerSecrets });
+            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, LIMITS.name), transport: "http", url: entry["url"], secrets, bearer, headerSecrets });
             return { spec, source, values };
         }
     }
@@ -305,7 +309,7 @@ function fromCodexEntry(raw, environment) {
             const cwd = typeof transport["cwd"] === "string" ? transport["cwd"] : null;
             if (!isAbsolute(command) && command.includes("/") && cwd !== null && isAbsolute(cwd))
                 command = join(cwd, command);
-            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 40), transport: "stdio", command, args: transport["args"] ?? [], secrets });
+            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, LIMITS.name), transport: "stdio", command, args: transport["args"] ?? [], secrets });
             return { spec, source: "Codex on this computer", values };
         }
         if (transport["type"] === "streamable_http") {
@@ -322,7 +326,7 @@ function fromCodexEntry(raw, environment) {
                 if (keep(secret, value))
                     headerSecrets[header] = secret;
             }
-            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 40), transport: "http", url: transport["url"], secrets, bearer, headerSecrets });
+            const spec = validateToolSpec({ name: name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, LIMITS.name), transport: "http", url: transport["url"], secrets, bearer, headerSecrets });
             return { spec, source: "Codex on this computer", values };
         }
     }

package/dist/provider.d.ts

@@ -19,14 +19,10 @@
  * shell the model itself launches (Codex provider review, Q5).
  */
 import { type ExecResult, type RunOptions } from "./exec.js";
-export type ProviderId = "claude" | "codex" | "openrouter" | "gemini";
+import { MODEL_ID, type AgentSpec, type ProviderId } from "./contracts/provider.js";
+export type { AgentSpec, ProviderId } from "./contracts/provider.js";
 export declare const PROVIDER_IDS: readonly ProviderId[];
 export declare function isProviderId(value: string): value is ProviderId;
-/** Which harness runs, on which model. model null = the harness's default. */
-export type AgentSpec = {
-    provider: ProviderId;
-    model: string | null;
-};
 /** 'review' (v29) is the reviewer's artifact-only pass — plan-shaped in
  * every clamp: read, comment, never build. */
 export type Phase = "plan" | "build" | "repair" | "review";
@@ -36,7 +32,7 @@ export type Phase = "plan" | "build" | "repair" | "review";
  * TOML-hostile characters — but NOT alphanumeric-only, which would refuse
  * real ids carrying `/ . : -` (Codex provider review, Q5).
  */
-export declare const MODEL_ID: RegExp;
+export { MODEL_ID };
 export declare function validModelId(model: string | null): boolean;
 /** The one semantic request every provider renders into its own argv. */
 export type Invocation = {
@@ -297,4 +293,3 @@ export type ProviderInspection = {
     measuresCost: boolean;
 };
 export declare function inspectionOf(provider: ProviderId): ProviderInspection;
-export {};

package/dist/provider.js

@@ -24,9 +24,10 @@ import { runStreamJsonl, runClaudeStreamJsonl, runGeminiStreamJsonl } from "./ex
 import { scanForSecrets } from "./evidence.js";
 import { FINDINGS_MODEL_SCHEMA } from "./contracts/review-findings.js";
 import { REVIEW_OUTPUT_LIMITS } from "./structured-output.js";
-export const PROVIDER_IDS = ["claude", "codex", "openrouter", "gemini"];
+import { agentSpecSchema, MODEL_ID, modelIdSchema, PROVIDER_ID_VALUES, providerIdSchema } from "./contracts/provider.js";
+export const PROVIDER_IDS = PROVIDER_ID_VALUES;
 export function isProviderId(value) {
-    return PROVIDER_IDS.includes(value);
+    return providerIdSchema.safeParse(value).success;
 }
 /**
  * Model ids cross providers ("anthropic/claude-sonnet-4.5", "gpt-5-codex",
@@ -34,9 +35,10 @@ export function isProviderId(value) {
  * TOML-hostile characters — but NOT alphanumeric-only, which would refuse
  * real ids carrying `/ . : -` (Codex provider review, Q5).
  */
-export const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+export { MODEL_ID };
 export function validModelId(model) {
-    return model === null || MODEL_ID.test(model);
+    // Not a string reads as its text, as the regex always read it (an untyped row's `undefined` passes as "undefined").
+    return model === null || modelIdSchema.safeParse(String(model)).success;
 }
 const USAGE_JSON_CAP = 8 * 1024;
 /** Empty and whitespace-only identities are absence, never resumable ids. */
@@ -919,17 +921,19 @@ export function auditOf(provider) {
  * across a 300-model catalog.
  */
 export function validateSpec(spec) {
-    if (!isProviderId(spec.provider)) {
-        return { ok: false, problem: `unknown provider \`${String(spec.provider)}\` — one of ${PROVIDER_IDS.join(", ")}` };
-    }
-    if (!validModelId(spec.model)) {
-        return { ok: false, problem: "a model id is 1–128 characters of letters, digits, and . _ : / - (never leading with a dash)" };
+    // A refusal names the field, never the value: a pasted credential must not travel on in a problem.
+    const parsed = agentSpecSchema.safeParse({ provider: spec.provider, model: spec.model === null ? null : String(spec.model) });
+    if (!parsed.success) {
+        const field = parsed.error.issues[0]?.path[0];
+        if (field === "provider")
+            return { ok: false, problem: `provider: unknown provider — one of ${PROVIDER_IDS.join(", ")}` };
+        return { ok: false, problem: "model: a model id is 1–128 characters of letters, digits, and . _ : / - (never leading with a dash)" };
     }
     if (spec.provider === "openrouter" && spec.model === null) {
-        return { ok: false, problem: "openrouter needs an explicit model — there is no default across its catalog" };
+        return { ok: false, problem: "model: openrouter needs an explicit model — there is no default across its catalog" };
     }
     if (spec.provider === "gemini" && spec.model === null) {
-        return { ok: false, problem: "gemini needs an explicit model — the harness default drifts with its releases" };
+        return { ok: false, problem: "model: gemini needs an explicit model — the harness default drifts with its releases" };
     }
     return { ok: true };
 }

package/dist/recipes.d.ts

@@ -1,32 +1,8 @@
 import type { Store } from "./store.js";
-import { type AcceptanceCriterion } from "./scope.js";
+import { type RecipeDocument } from "./contracts/recipes.js";
 export declare const RECIPE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS workflow_recipe (\n  id TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0),\n  repo TEXT NOT NULL, document TEXT NOT NULL, digest TEXT NOT NULL,\n  author TEXT NOT NULL, created_at TEXT NOT NULL,\n  PRIMARY KEY(id, revision)\n);\nCREATE INDEX IF NOT EXISTS workflow_recipe_project ON workflow_recipe(repo, id, revision DESC);\nCREATE TRIGGER IF NOT EXISTS workflow_recipe_no_update BEFORE UPDATE ON workflow_recipe\nBEGIN SELECT RAISE(ABORT, 'recipe revisions are immutable'); END;\nCREATE TRIGGER IF NOT EXISTS workflow_recipe_no_delete BEFORE DELETE ON workflow_recipe\nBEGIN SELECT RAISE(ABORT, 'recipe revisions are immutable'); END;\nCREATE TABLE IF NOT EXISTS workflow_preview (\n  token TEXT PRIMARY KEY, actor TEXT NOT NULL, repo TEXT NOT NULL,\n  document TEXT NOT NULL, digest TEXT NOT NULL, source TEXT NOT NULL,\n  created_at TEXT NOT NULL, expires_at TEXT NOT NULL,\n  task_id TEXT REFERENCES task(id), routine_id INTEGER REFERENCES routine(id),\n  saved_id TEXT, saved_revision INTEGER,\n  CHECK(task_id IS NULL OR routine_id IS NULL),\n  FOREIGN KEY(saved_id, saved_revision) REFERENCES workflow_recipe(id, revision)\n);\nCREATE INDEX IF NOT EXISTS workflow_preview_project ON workflow_preview(repo, created_at DESC);\nCREATE INDEX IF NOT EXISTS workflow_preview_source ON workflow_preview(repo, source, created_at DESC)\nWHERE task_id IS NOT NULL OR routine_id IS NOT NULL;\n";
-type RecipeFields = {
-    format: "standing-orders-recipe";
-    name: string;
-    description: string;
-    goal: string;
-    outOfScope: string | null;
-    touches: string[];
-    acceptance: AcceptanceCriterion[];
-    planning: "auto" | "required" | "skip";
-    deliverable: "branch" | "report";
-    schedule: string | null;
-    costCeilingUsd: number | null;
-};
-export type RecipeInput = {
-    key: string;
-    label: string;
-    defaultValue: string | null;
-};
-export type RecipeDocument = RecipeFields & ({
-    version: 1;
-    inputs?: never;
-} | {
-    version: 2;
-    inputs: RecipeInput[];
-});
-export declare const RECIPE_INPUT_LIMIT = 8;
+export type { RecipeDocument, RecipeInput } from "./contracts/recipes.js";
+export declare const RECIPE_INPUT_LIMIT: 8;
 export type RecipeAnswers = ReadonlyMap<string, string>;
 export type Recipe = {
     id: string;
@@ -78,4 +54,3 @@ export declare function workflowSteps(document: RecipeDocument): {
     detail: string;
 }[];
 export declare function recipeScheduleWords(document: RecipeDocument, now: Date): string;
-export {};

package/dist/recipes.js

@@ -9,6 +9,7 @@ import { validateTaskText, fileTaskProposal, fileRoutineProposal } from "./propo
 import { parseSchedule, firstFireAt, describeSchedule, validateRoutineTerms } from "./routine.js";
 import { applyModeToNewFiling } from "./plan-auto.js";
 import { canonicalProject } from "./project.js";
+import { RECIPE_FORMAT, RECIPE_LIMITS, readRecipeDocument } from "./contracts/recipes.js";
 import { resolve } from "node:path";
 export const RECIPE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS workflow_recipe (
@@ -35,7 +36,7 @@ CREATE INDEX IF NOT EXISTS workflow_preview_project ON workflow_preview(repo, cr
 CREATE INDEX IF NOT EXISTS workflow_preview_source ON workflow_preview(repo, source, created_at DESC)
 WHERE task_id IS NOT NULL OR routine_id IS NOT NULL;
 `;
-export const RECIPE_INPUT_LIMIT = 8;
+export const RECIPE_INPUT_LIMIT = RECIPE_LIMITS.inputs;
 export class RecipeError extends Error {
     status;
     constructor(message, status = 400) {
@@ -43,63 +44,93 @@ export class RecipeError extends Error {
         this.status = status;
     }
 }
-const keys = ["format", "version", "name", "description", "goal", "outOfScope", "touches", "acceptance", "planning", "deliverable", "schedule", "costCeilingUsd"];
 const honest = (text) => !hasForbiddenControls(text) && !hasDisguisedText(text);
 const recipeProject = (repo) => canonicalProject(repo) ?? resolve(repo);
+/** What a refusal at each top-level field tells the person, after the path-named line. */
+const FIELD_ADVICE = {
+    name: "Name, goal, exclusions, and allowed paths must be readable text.", description: "Name, goal, exclusions, and allowed paths must be readable text.",
+    goal: "Name, goal, exclusions, and allowed paths must be readable text.", outOfScope: "Name, goal, exclusions, and allowed paths must be readable text.",
+    touches: "Name, goal, exclusions, and allowed paths must be readable text.",
+    planning: "Choose a supported planning and result type.", deliverable: "Choose a supported planning and result type.",
+    schedule: "Choose a valid schedule.", costCeilingUsd: "The weekly budget must be a positive dollar amount.",
+};
+const FIELDS_MISMATCH = "Recipe fields do not match this version. Recipes contain work definitions, not permissions, credentials, or agent settings.";
+/** The one refusal a recipe structure gets: its first path-named line, with the advice for that field. */
+function structureError(issues) {
+    const top = issues.find(one => one.kind === "unknown-key" && one.path === "payload") ?? issues.find(one => one.kind === "required" && !/[.[]/.test(one.path));
+    if (top !== undefined)
+        return new RecipeError(`${top.line}. ${FIELDS_MISMATCH}`);
+    const first = issues[0];
+    const field = first.path.split(/[.[]/)[0];
+    if (field === "acceptance") {
+        if (issues.some(one => one.path.startsWith("acceptance") && one.kind === "unknown-key")) {
+            return new RecipeError(`${issues.find(one => one.path.startsWith("acceptance") && one.kind === "unknown-key").line}. Success checks have unsupported fields.`);
+        }
+        return new RecipeError(issues.filter(one => one.path.startsWith("acceptance")).map(one => one.line).join("; "));
+    }
+    if (field === "inputs") {
+        const advice = first.path === "inputs" ? "Add between 1 and 8 questions, or remove the empty questions to save a fixed recipe."
+            : /\.key$/.test(first.path) ? "Give each question a unique key: lowercase letters, numbers, or underscores, starting with a letter (up to 32 characters)."
+                : /\.label$/.test(first.path) ? "Give each question a readable label of up to 80 characters."
+                    : /\.defaultValue$/.test(first.path) && first.kind !== "required" ? "Default answers must be plain text up to 500 characters, without input placeholders."
+                        : "Questions contain only a key, label, and optional default answer.";
+        return new RecipeError(`${first.line}. ${advice}`);
+    }
+    // Zod states `positive` as an exclusive minimum ("at least 0"); the advice says it plainly.
+    if (field === "costCeilingUsd" && first.kind === "bad-value")
+        return new RecipeError(`costCeilingUsd: ${FIELD_ADVICE[field]}`);
+    return new RecipeError(`${first.line}. ${FIELD_ADVICE[field] ?? FIELDS_MISMATCH}`);
+}
 /** Reject unknown fields, including approval/provider settings, on import. */
 export function parseRecipe(input) {
     if (typeof input !== "object" || input === null || Array.isArray(input))
         throw new RecipeError("Choose a recipe document.");
-    if (Buffer.byteLength(JSON.stringify(input), "utf8") > 32_768)
+    if (Buffer.byteLength(JSON.stringify(input), "utf8") > RECIPE_LIMITS.documentBytes)
         throw new RecipeError("A recipe must be at most 32 KB.");
     const raw = input;
-    if (raw.format !== "standing-orders-recipe" || (raw.version !== 1 && raw.version !== 2))
-        throw new RecipeError("This recipe format/version is not supported.");
-    const expected = raw.version === 2 ? [...keys, "inputs"] : keys;
-    if (Object.keys(raw).some(key => !expected.includes(key)) || expected.some(key => !Object.hasOwn(raw, key)))
-        throw new RecipeError("Recipe fields do not match this version. Recipes contain work definitions, not permissions, credentials, or agent settings.");
-    if (typeof raw.name !== "string" || typeof raw.description !== "string" || typeof raw.goal !== "string" || (raw.outOfScope !== null && typeof raw.outOfScope !== "string") || !Array.isArray(raw.touches) || raw.touches.some(path => typeof path !== "string"))
-        throw new RecipeError("Name, goal, exclusions, and allowed paths must be readable text.");
-    if (raw.description.length > 400 || !honest(raw.description))
-        throw new RecipeError("Keep the description within 400 characters, without hidden text.");
-    const bad = validateTaskText({ title: raw.name, goal: raw.goal, outOfScope: raw.outOfScope, touches: raw.touches });
+    if (raw.format !== RECIPE_FORMAT)
+        throw new RecipeError("format: This recipe format/version is not supported.");
+    if (raw.version !== 1 && raw.version !== 2) {
+        const newer = typeof raw.version === "number" && Number.isInteger(raw.version) && raw.version > 2;
+        throw new RecipeError(`version: ${newer ? `made by a newer Toolroll (version ${raw.version}). ` : ""}This recipe format/version is not supported.`);
+    }
+    const read = readRecipeDocument(raw);
+    if (!read.ok)
+        throw structureError(read.issues);
+    const doc = read.value;
+    if (doc.description.length > RECIPE_LIMITS.description || !honest(doc.description))
+        throw new RecipeError("description: Keep the description within 400 characters, without hidden text.");
+    const bad = validateTaskText({ title: doc.name, goal: doc.goal, outOfScope: doc.outOfScope, touches: doc.touches });
     if (bad !== null)
         throw new RecipeError(bad.message);
-    if (!["auto", "required", "skip"].includes(String(raw.planning)) || !["branch", "report"].includes(String(raw.deliverable)))
-        throw new RecipeError("Choose a supported planning and result type.");
-    if (raw.schedule !== null && (typeof raw.schedule !== "string" || parseSchedule(raw.schedule) === null))
-        throw new RecipeError("Choose a valid schedule.");
-    if (raw.costCeilingUsd !== null && (typeof raw.costCeilingUsd !== "number" || !Number.isFinite(raw.costCeilingUsd) || raw.costCeilingUsd <= 0))
-        throw new RecipeError("The weekly budget must be a positive dollar amount.");
-    if (raw.schedule === null && raw.costCeilingUsd !== null)
-        throw new RecipeError("A weekly budget applies to a repeating workflow. One-time work uses the project's task budget.");
-    if (raw.deliverable === "report" && raw.schedule !== null)
-        throw new RecipeError("Report recipes run once. Repeating workflows currently produce code changes.");
-    if (raw.schedule !== null && raw.planning === "required")
-        throw new RecipeError("Plan-first recipes run once. Repeating workflows reuse their approved scope; choose direct execution or run once.");
-    if (!Array.isArray(raw.acceptance) || raw.acceptance.some(one => typeof one !== "object" || one === null || Object.keys(one).some(key => !["id", "statement", "how", "evidence"].includes(key))))
-        throw new RecipeError("Success checks have unsupported fields.");
+    if (doc.schedule !== null && parseSchedule(doc.schedule) === null)
+        throw new RecipeError("schedule: Choose a valid schedule.");
+    if (doc.schedule === null && doc.costCeilingUsd !== null)
+        throw new RecipeError("costCeilingUsd: A weekly budget applies to a repeating workflow. One-time work uses the project's task budget.");
+    if (doc.deliverable === "report" && doc.schedule !== null)
+        throw new RecipeError("deliverable: Report recipes run once. Repeating workflows currently produce code changes.");
+    if (doc.schedule !== null && doc.planning === "required")
+        throw new RecipeError("planning: Plan-first recipes run once. Repeating workflows reuse their approved scope; choose direct execution or run once.");
     const parsed = parseAcceptanceCriteria(raw.acceptance);
     if (parsed.problems.length > 0 || parsed.criteria.length === 0)
-        throw new RecipeError(parsed.problems.map(one => one.message).join("; ") || "Add at least one success check.");
-    const fields = { format: "standing-orders-recipe", name: raw.name.trim(), description: raw.description.trim(), goal: raw.goal.trim(), outOfScope: raw.outOfScope?.trim() || null,
-        touches: [...raw.touches], acceptance: parsed.criteria, planning: raw.planning, deliverable: raw.deliverable, schedule: raw.schedule, costCeilingUsd: raw.costCeilingUsd };
-    const document = raw.version === 1 ? { ...fields, version: 1 } : { ...fields, version: 2, inputs: parseRecipeInputs(raw.inputs) };
+        throw new RecipeError(parsed.problems.map(one => one.message).join("; ") || "acceptance: Add at least one success check.");
+    const fields = { format: RECIPE_FORMAT, name: doc.name.trim(), description: doc.description.trim(), goal: doc.goal.trim(), outOfScope: doc.outOfScope?.trim() || null,
+        touches: [...doc.touches], acceptance: parsed.criteria, planning: doc.planning, deliverable: doc.deliverable, schedule: doc.schedule, costCeilingUsd: doc.costCeilingUsd };
     // Keep v1's canonical key order stable: existing immutable digests must survive.
-    const ordered = { format: document.format, version: document.version, name: document.name, description: document.description, goal: document.goal,
-        outOfScope: document.outOfScope, touches: document.touches, acceptance: document.acceptance, planning: document.planning, deliverable: document.deliverable,
-        schedule: document.schedule, costCeilingUsd: document.costCeilingUsd, ...(document.version === 2 ? { inputs: document.inputs } : {}) };
+    const ordered = { format: fields.format, version: doc.version, name: fields.name, description: fields.description, goal: fields.goal,
+        outOfScope: fields.outOfScope, touches: fields.touches, acceptance: fields.acceptance, planning: fields.planning, deliverable: fields.deliverable,
+        schedule: fields.schedule, costCeilingUsd: fields.costCeilingUsd, ...(doc.version === 2 ? { inputs: parseRecipeInputs(doc.inputs) } : {}) };
     if (ordered.version === 2)
         validateInputReferences(ordered);
-    if (document.schedule !== null) {
-        const problems = validateRoutineTerms({ repo: "/recipe-preview", ...document, requirements: [], schedule: document.schedule, singleFlight: true });
+    if (ordered.schedule !== null) {
+        const problems = validateRoutineTerms({ repo: "/recipe-preview", ...ordered, requirements: [], schedule: ordered.schedule, singleFlight: true });
         if (problems.length)
             throw new RecipeError(problems.map(one => `${one.field}: ${one.problem}`).join("; "));
     }
     return ordered;
 }
 export function importRecipe(text) {
-    if (Buffer.byteLength(text, "utf8") > 32_768)
+    if (Buffer.byteLength(text, "utf8") > RECIPE_LIMITS.documentBytes)
         throw new RecipeError("A recipe must be at most 32 KB.");
     let value;
     try {
@@ -112,23 +143,19 @@ export function importRecipe(text) {
 }
 export const recipeDigest = (document) => createHash("sha256").update(JSON.stringify(document)).digest("hex");
 export const exportRecipe = (document) => JSON.stringify(parseRecipe(document), null, 2) + "\n";
-/** Inputs are literal work text, never a program, path grant, or shell fragment. */
-function parseRecipeInputs(raw) {
-    if (!Array.isArray(raw) || raw.length < 1 || raw.length > RECIPE_INPUT_LIMIT)
-        throw new RecipeError("Add between 1 and 8 questions, or remove the empty questions to save a fixed recipe.");
+/** Inputs are literal work text, never a program, path grant, or shell fragment. Their shape is already read. */
+function parseRecipeInputs(inputs) {
     const seen = new Set();
-    return raw.map(input => {
-        if (input === null || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some(key => !["key", "label", "defaultValue"].includes(key)))
-            throw new RecipeError("Questions contain only a key, label, and optional default answer.");
-        const { key, label, defaultValue } = input;
-        if (typeof key !== "string" || !/^[a-z][a-z0-9_]{0,31}$/.test(key) || ["constructor", "prototype"].includes(key) || seen.has(key))
-            throw new RecipeError("Give each question a unique key: lowercase letters, numbers, or underscores, starting with a letter (up to 32 characters).");
-        if (typeof label !== "string" || !label.trim() || label.length > 80 || !honest(label))
-            throw new RecipeError("Give each question a readable label of up to 80 characters.");
-        if (defaultValue !== null && (typeof defaultValue !== "string" || defaultValue.length > 500 || !honest(defaultValue) || /\{\{|\}\}/.test(defaultValue)))
-            throw new RecipeError("Default answers must be plain text up to 500 characters, without input placeholders.");
+    return inputs.map(({ key, label, defaultValue }, index) => {
+        const at = `inputs[${index}]`;
+        if (!/^[a-z][a-z0-9_]{0,31}$/.test(key) || ["constructor", "prototype"].includes(key) || seen.has(key))
+            throw new RecipeError(`${at}.key: Give each question a unique key: lowercase letters, numbers, or underscores, starting with a letter (up to 32 characters).`);
+        if (!label.trim() || label.length > RECIPE_LIMITS.label || !honest(label))
+            throw new RecipeError(`${at}.label: Give each question a readable label of up to 80 characters.`);
+        if (defaultValue !== null && (defaultValue.length > RECIPE_LIMITS.answer || !honest(defaultValue) || /\{\{|\}\}/.test(defaultValue)))
+            throw new RecipeError(`${at}.defaultValue: Default answers must be plain text up to 500 characters, without input placeholders.`);
         seen.add(key);
-        return { key, label: label.trim(), defaultValue: typeof defaultValue === "string" ? defaultValue.trim() || null : null };
+        return { key, label: label.trim(), defaultValue: defaultValue === null ? null : defaultValue.trim() || null };
     });
 }
 const inputToken = /\{\{\s*([a-z][a-z0-9_]{0,31})\s*\}\}/g;