toolroll 0.9.33 → 0.9.36

package/dist/desktop-update.d.ts

@@ -125,6 +125,7 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -138,7 +139,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/evidence.d.ts

@@ -15,6 +15,8 @@
  */
 import { type ParsedReport, type ReportImage } from "./scout-report.js";
 import { type ParsedProof } from "./proof.js";
+import { type HandoffArtifact } from "./contracts/handoff.js";
+export type { HandoffArtifact } from "./contracts/handoff.js";
 import type { Artifact, Store } from "./store.js";
 import type { ExecResult } from "./exec.js";
 /** The park mailbox pattern. Each run's actual name carries a nonce; see `mailboxName`. */
@@ -254,45 +256,6 @@ export type DiffStat = {
  * recorded as null — never coerced to zero.
  */
 export declare function parseNumstat(raw: string, base: string, head: string): DiffStat;
-/** The freshness-stamped handoff artifact's shape (M6.10). */
-export type HandoffArtifact = {
-    schema: 1;
-    taskId: string;
-    runId: number;
-    provider: string;
-    /** v47: the exact model that ran, and the sealed route leg it ran as —
-     * provenance a later reader can hold against the approval. Absent on
-     * artifacts written before routes existed. */
-    model?: string;
-    route?: {
-        digest: string;
-        phase: "plan" | "build" | "repair" | "review";
-        provider: string;
-        model: string | null;
-        chosen: "recommended" | "override" | "pinned" | "legacy" | "fallback";
-    };
-    sessionId: string | null;
-    branch: string;
-    worktree: string;
-    base: string;
-    head: string;
-    outcome: "built" | "no-change";
-    committed: boolean;
-    /** Decision ids whose answers were in this run's brief — causality, not time. */
-    decisionsIncorporated: number[];
-    /** The agent's conclusion — agent-reported, and labeled so by its position here. */
-    conclusion: string;
-    /** Structured operator-facing output. Optional for artifacts written by
-     * older versions; readers treat absence as an empty list. */
-    changes?: string[];
-    verification?: string[];
-    followUps?: string[];
-    freshness: {
-        stampedAt: string;
-        /** A successor proves this against the branch before trusting anything above. */
-        currentAsOf: string;
-    };
-};
 /**
  * Write the handoff artifact (M6.10): the machine's own statement of where
  * a finished run left the world — workspace identity, exact base and head,
@@ -301,7 +264,7 @@ export type HandoffArtifact = {
  * context. This is what makes a cold takeover context-bearing rather than
  * repo-only; a provider session is memory, not a freshness proof.
  */
-export declare function storeHandoffArtifact(store: Store, root: string, payload: HandoffArtifact, now: Date): number;
+export declare function storeHandoffArtifact(store: Store, root: string, payload: Omit<HandoffArtifact, "version">, now: Date): number;
 /**
  * High-confidence secret shapes ONLY (audit IV-7): a detector that cries
  * wolf trains people to approve wolves. Each pattern is a format no

package/dist/evidence.js

@@ -18,9 +18,10 @@ import { closeSync, existsSync, constants, fstatSync, mkdirSync, openSync, readd
 import { join, sep } from "node:path";
 import { namedPath } from "./names.js";
 import { LIMITS } from "./decision.js";
-import { PLAN_LIMITS } from "./plan.js";
+import { TEXT_LIMITS } from "./text-limits.js";
 import { parseReport, REPORT_LIMITS } from "./scout-report.js";
 import { parseProof, PROOF_LIMITS } from "./proof.js";
+import { HANDOFF_VERSION, readHandoffArtifact } from "./contracts/handoff.js";
 import { encodeBaseTreeSnapshot, parseBaseTreeSnapshot } from "./peek.js";
 /** The park mailbox pattern. Each run's actual name carries a nonce; see `mailboxName`. */
 export const MAILBOX_PREFIX = "STANDING-ORDERS-PARK-";
@@ -84,7 +85,7 @@ export const EVIDENCE_CAPS = {
     diff: 256 * 1024,
     status: 64 * 1024,
     "park-payload": LIMITS.payload,
-    plan: PLAN_LIMITS.document,
+    plan: TEXT_LIMITS.planDocumentBytes,
     "terminal-diff": 256 * 1024,
     "diff-stat": 32 * 1024,
     // The enveloped base snapshot (live peek): 20k entries of path+sha+size.
@@ -618,7 +619,10 @@ export function parseNumstat(raw, base, head) {
  * repo-only; a provider session is memory, not a freshness proof.
  */
 export function storeHandoffArtifact(store, root, payload, now) {
-    return storeEvidence(store, root, payload.runId, "handoff", "handoff.json", Buffer.from(JSON.stringify(payload, null, 2), "utf8"), "machine-authored handoff (exit 0)", now);
+    const read = readHandoffArtifact({ version: HANDOFF_VERSION, ...payload });
+    if (!read.ok)
+        throw new Error(`The handoff does not match its contract: ${read.issues.map(issue => issue.line).join("; ")}`);
+    return storeEvidence(store, root, payload.runId, "handoff", "handoff.json", Buffer.from(JSON.stringify(read.value, null, 2), "utf8"), "machine-authored handoff (exit 0)", now);
 }
 /**
  * High-confidence secret shapes ONLY (audit IV-7): a detector that cries

package/dist/flow-gallery.d.ts

@@ -1,4 +1,5 @@
 import { type FlowDefinition, type FlowStepInput } from "./flows.js";
+import type { TriggerInput } from "./contracts/flow.js";
 import type { Store } from "./store.js";
 export declare const GALLERY_GROUPS: readonly [{
     readonly id: "ship";
@@ -46,7 +47,7 @@ export type GalleryTemplate = {
     /** The steps in Toolroll's own repository, when they differ. */
     ownSteps?: FlowStepInput[];
     definition?: FlowDefinition;
-    triggers: Record<string, unknown>[];
+    triggers: TriggerInput[];
     scripts?: {
         name: string;
         about: string;
@@ -100,7 +101,7 @@ export type GalleryBuilt = {
     repo: string;
     answers: GalleryAnswers;
     definition: FlowDefinition;
-    triggers: Record<string, unknown>[];
+    triggers: TriggerInput[];
     scripts: {
         name: string;
         about: string;

package/dist/flow-share.d.ts

@@ -1,39 +1,11 @@
-import { type ScriptDraft } from "./flow-scripts.js";
 import { type FlowDefinition } from "./flows.js";
+import { FLOW_FILE_FORMAT, FLOW_FILE_VERSION, type FlowFile, type FlowFileParameter, type FlowFileScript } from "./contracts/flow.js";
 import type { FlowRow, Store } from "./store.js";
-export declare const FLOW_FILE_FORMAT = "toolroll-flow";
-export declare const FLOW_FILE_VERSION = 1;
+export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
+export type { FlowFile, FlowFileParameter, FlowFileScript };
 /** The largest flow file Toolroll reads or fetches. */
 export declare const FLOW_FILE_MAX_BYTES: number;
 export declare const FLOW_FILE_SUFFIX = ".toolroll-flow.json";
-/** Something the import asks for: `{{param.<id>}}` in a zone or trigger is replaced by its value. */
-export type FlowFileParameter = {
-    id: string;
-    about: string;
-    default?: string;
-    optional?: boolean;
-};
-export type FlowFileScript = {
-    name: string;
-    about: string;
-    language: ScriptDraft["language"];
-    timeoutMinutes: number;
-    body?: string;
-    file?: string;
-};
-export type FlowFile = {
-    format: typeof FLOW_FILE_FORMAT;
-    version: typeof FLOW_FILE_VERSION;
-    name: string;
-    about: string;
-    needs: string[];
-    parameters: FlowFileParameter[];
-    /** The zones in the lead's step vocabulary, the start first. */
-    zones: Record<string, unknown>[];
-    /** Each trigger's settings, as `toolroll flows trigger add` takes them. */
-    triggers: Record<string, unknown>[];
-    scripts: FlowFileScript[];
-};
 export type FlowExported = {
     file: FlowFile;
     json: string;
@@ -42,9 +14,15 @@ export type FlowExported = {
 };
 /** A flow as a file: its zones and paths, its triggers' settings and the scripts it runs, nothing of this installation's. */
 export declare function exportFlow(store: Store, flow: FlowRow, dir: string | null): FlowExported;
+/** A flow file refused: why, in plain words, each problem naming its path in the file (`zones[0].routes[0]: ...`). */
 export declare class FlowFileError extends Error {
 }
-/** Read a flow file: its size, its JSON, its format and version, and every zone, trigger, script and parameter. Throws FlowFileError in plain words. */
+/**
+ * Read a flow file: its size, its JSON and format, then its one schema (flowFileSchema: every zone, trigger, script
+ * and parameter, strict about unknown keys — `zones[0].routes[0]: unknown key 'to' (did you mean goesTo?)`), and a
+ * newer version refused plainly. Then what the schema can't say: no keys in a trigger, ids and names used once, each
+ * {{param.x}} declared, every script valid and the zones a flow. Throws FlowFileError in plain words.
+ */
 export declare function parseFlowFile(text: string): FlowFile;
 /** --param k=v lines (or a form's fields) as values; refuses parameters the file doesn't ask for. */
 export declare function parameterValues(file: FlowFile, given: Record<string, string>): Record<string, string>;

package/dist/flow-share.js

@@ -21,29 +21,30 @@ import { flowDefinitionOf } from "./flow-engine.js";
 import { readFlowSecrets } from "./flow-secrets.js";
 import { scriptDigest, validateScript } from "./flow-scripts.js";
 import { addFlowTriggerTo, describeTrigger, HOOK_PATH, readHooksBase, triggerConfigOf, validateTriggerConfig } from "./flow-triggers.js";
-import { durationMinutes, durationWords, flowTerms, LANGUAGE_WORDS, validateFlowDefinition } from "./flows.js";
+import { durationMinutes, durationWords, FlowContractError, flowTerms, inStepWords, LANGUAGE_WORDS, validateFlowDefinition } from "./flows.js";
+import { readVersioned } from "./contracts/contract.js";
+import { FLOW_ALIASES, FLOW_FILE_FORMAT, FLOW_FILE_VERSION, flowFileSchema, PARAMETER_ID } from "./contracts/flow.js";
 import { parseSchedule } from "./routine.js";
-export const FLOW_FILE_FORMAT = "toolroll-flow";
-export const FLOW_FILE_VERSION = 1;
+export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
 /** The largest flow file Toolroll reads or fetches. */
 export const FLOW_FILE_MAX_BYTES = 256 * 1024;
 export const FLOW_FILE_SUFFIX = ".toolroll-flow.json";
 const PARAM = /\{\{\s*param\.([a-z0-9][a-z0-9-]{0,39})\s*\}\}/g;
-const PARAM_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const REMOVED = "[removed]";
 // ------------------------------------------------------------------ export
 /** A zone in the lead's words: only what it says, in the order a person reads it. */
 function stepOf(stage, ask) {
     const step = { id: stage.id, title: stage.title, kind: stage.kind };
     const words = (minutes) => durationMinutes(durationWords(minutes)) === minutes ? durationWords(minutes) : minutes;
-    if (stage.instructions !== null)
+    // Only what the step's kind says: words a zone kept from a kind it was before stay behind.
+    if (stage.instructions !== null && (stage.kind === "task" || stage.kind === "report" || stage.kind === "draft" || stage.kind === "teammate"))
         step["instructions"] = stage.instructions;
     if (stage.kind === "task")
         step["planning"] = stage.planning;
     if (stage.kind === "approval")
         step["decider"] = stage.toOwner === true ? "owner" : stage.approver === null ? "anyone"
             : ask({ id: `decider-${stage.id}`.slice(0, 40), about: `Who decides at ${stage.title}: a person's sign-in name, owner (the flow's owner) or anyone`, default: "owner" });
-    if (stage.message !== null)
+    if (stage.message !== null && (stage.kind === "notify" || stage.kind === "update"))
         step["message"] = stage.message;
     if (stage.kind === "update")
         step["close"] = stage.close;
@@ -239,26 +240,28 @@ export function exportFlow(store, flow, dir) {
         format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name: flow.name,
         about: ordered.map(one => one.title).join(" → "),
         needs: needsOf(definition, triggers, scripts.map(one => one.name)),
-        parameters, zones, triggers, scripts,
+        // Zones and triggers in the file's words (stepOf, triggerOf): what flowFileSchema reads back (flow-share.test.ts).
+        parameters, zones: zones, triggers: triggers, scripts,
     };
     const file = scrubDeep(raw, scrubber(values, names), null, false);
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "flow";
     return { file, json: `${JSON.stringify(file, null, 2)}\n`, fileName: `${slug}${FLOW_FILE_SUFFIX}`, left };
 }
 // ------------------------------------------------------------------ reading
+/** A flow file refused: why, in plain words, each problem naming its path in the file (`zones[0].routes[0]: ...`). */
 export class FlowFileError extends Error {
 }
 const refuse = (message) => { throw new FlowFileError(message); };
 /** A zone from the file as the canvas stores it: references by id (or by title), the rest checked by validateFlowDefinition. */
 function stageInputOf(step, index, find) {
-    const title = typeof step["title"] === "string" ? step["title"] : `zone ${index + 1}`;
+    const at = `zones[${index}]`;
     const kind = step["kind"];
     const object = (key) => {
         const value = step[key];
         if (value === undefined || value === null)
             return undefined;
         if (typeof value !== "object" || Array.isArray(value))
-            refuse(`Zone ${title}: ${key} must be an object.`);
+            refuse(`${at}.${key}: must be an object`);
         return value;
     };
     const list = (key) => {
@@ -266,59 +269,60 @@ function stageInputOf(step, index, find) {
         if (value === undefined || value === null)
             return undefined;
         if (!Array.isArray(value) || value.some(one => one === null || typeof one !== "object" || Array.isArray(one)))
-            refuse(`Zone ${title}: ${key} must be a list.`);
+            refuse(`${at}.${key}: must be a list of objects`);
         return value;
     };
     const decider = step["decider"];
     if (decider !== undefined && decider !== null && typeof decider !== "string")
-        refuse(`Zone ${title}: decider must be plain text.`);
+        refuse(`${at}.decider: must be a string`);
     const toOwner = kind === "approval" && typeof decider === "string" && decider.trim().toLowerCase() === "owner";
     const anyone = decider === undefined || decider === null || (typeof decider === "string" && /^(anyone|any approver|)$/i.test(decider.trim()));
-    const at = object("at") ?? {};
-    const failKey = step["ifNotSure"] ?? step["ifNoReply"] ?? step["ifReplied"] ?? step["ifFails"];
-    const minutes = (value) => value === undefined ? undefined : durationMinutes(value) ?? refuse(`Zone ${title}: say a time like "3 days" (up to 30 days).`);
+    const place = object("at") ?? {};
+    const [failKey, fail] = ["ifNotSure", "ifNoReply", "ifReplied", "ifFails"].map(key => [key, step[key]]).find(([, value]) => value !== undefined && value !== null) ?? ["ifFails", undefined];
+    const minutes = (value, key) => value === undefined ? undefined : durationMinutes(value) ?? refuse(`${at}.${key}: say a time like "3 days" (up to 30 days)`);
     const sureAt = step["sureAt"];
     return {
         id: step["id"], title: step["title"], kind,
-        zone: { x: at["x"], y: at["y"] ?? 0, w: at["w"], h: at["h"], color: at["color"] },
+        zone: { x: place["x"], y: place["y"] ?? 0, w: place["w"], h: place["h"], color: place["color"] },
         instructions: step["instructions"], planning: step["planning"],
         ...(toOwner ? { toOwner: true } : { approver: anyone ? null : decider }),
         message: step["message"], close: step["close"], script: step["script"], runIn: step["runIn"],
-        routes: list("routes")?.map(one => ({ answer: one["answer"], to: find(one["goesTo"], title) })),
+        routes: list("routes")?.map((one, n) => ({ answer: one["answer"], to: find(one["goesTo"], `${at}.routes[${n}].goesTo`) })),
         secrets: step["secrets"],
-        ...(kind === "sort" ? { sort: { question: step["question"], answers: (list("answers") ?? []).map(one => ({ answer: one["answer"], means: one["means"], to: find(one["goesTo"], title) })),
+        ...(kind === "sort" ? { sort: { question: step["question"], answers: (list("answers") ?? []).map((one, n) => ({ answer: one["answer"], means: one["means"], to: find(one["goesTo"], `${at}.answers[${n}].goesTo`) })),
                 sureAt: typeof sureAt === "number" && sureAt > 1 ? sureAt / 100 : sureAt, notes: list("alsoNote") ?? [] } } : {}),
         ...(kind === "request" ? { request: { method: step["method"], url: step["url"], headers: object("headers") ?? {}, body: step["body"] } } : {}),
         ...(kind === "email" ? { email: { to: step["to"], subject: step["subject"], body: step["body"] } } : {}),
         ...(kind === "tool" ? { tool: { server: step["server"], name: step["tool"], args: typeof step["args"] === "object" && step["args"] !== null ? JSON.stringify(step["args"]) : step["args"] } } : {}),
-        ...(kind === "wait" ? { wait: step["waitFor"] === "hours" ? { for: "hours", from: step["from"], to: step["until"], timeZone: step["timeZone"] } : { for: step["waitFor"] ?? "reply", minutes: minutes(step["wait"] ?? "3 days") } } : {}),
+        ...(kind === "wait" ? { wait: step["waitFor"] === "hours" ? { for: "hours", from: step["from"], to: step["until"], timeZone: step["timeZone"] } : { for: step["waitFor"] ?? "reply", minutes: minutes(step["wait"] ?? "3 days", "wait") } } : {}),
         merge: step["merge"], teammate: step["teammate"], reply: step["reply"],
-        ...(kind === "choose" ? { options: (list("options") ?? []).map(one => ({ label: one["label"], to: one["goesTo"] === "end" ? "end" : find(one["goesTo"], title) })) } : {}),
-        ...(step["remindAfter"] === undefined ? {} : { limit: { minutes: minutes(step["remindAfter"]), to: find(step["thenMoveTo"], title) } }),
-        next: find(step["next"], title), onFail: find(failKey, title),
+        ...(kind === "choose" ? { options: (list("options") ?? []).map((one, n) => ({ label: one["label"], to: one["goesTo"] === "end" ? "end" : find(one["goesTo"], `${at}.options[${n}].goesTo`) })) } : {}),
+        ...(step["remindAfter"] === undefined ? {} : { limit: { minutes: minutes(step["remindAfter"], "remindAfter"), to: find(step["thenMoveTo"], `${at}.thenMoveTo`) } }),
+        next: find(step["next"], `${at}.next`), onFail: find(fail, `${at}.${failKey}`),
     };
 }
 /** The zones as a flow, checked whole. Throws in plain words. */
 function definitionOf(zones) {
     const ids = zones.map(one => one["id"]);
-    const find = (ref, from) => {
+    const find = (ref, path) => {
         if (ref === undefined || ref === null || ref === "")
             return null;
         if (typeof ref !== "string")
-            return refuse(`Zone ${from}: a path names a zone by its id.`);
+            return refuse(`${path}: names a zone by its id`);
         const hit = zones.find(one => one["id"] === ref.trim()) ?? zones.find(one => typeof one["title"] === "string" && one["title"].trim().toLowerCase() === ref.trim().toLowerCase());
         if (hit === undefined)
-            return refuse(`Zone ${from}: there's no zone called ${ref}.`);
-        return typeof hit["id"] === "string" ? hit["id"] : refuse(`Zone ${from}: every zone needs an id.`);
+            return refuse(`${path}: there's no zone called ${ref}`);
+        return typeof hit["id"] === "string" ? hit["id"] : refuse(`zones[${zones.indexOf(hit)}].id: required`);
     };
-    if (ids.some(one => typeof one !== "string"))
-        refuse("Every zone needs an id: lowercase letters, numbers and dashes.");
+    ids.forEach((one, index) => { if (typeof one !== "string")
+        refuse(`zones[${index}].id: required`); });
     const stages = zones.map((step, index) => stageInputOf(step, index, find));
+    // Its zones are the file's, in order: a zone's problem names the file's zone.
     try {
         return validateFlowDefinition({ version: 1, start: stages[0]?.["id"], stages });
     }
     catch (error) {
-        return refuse(error instanceof Error ? error.message : "Those zones aren't a flow.");
+        return refuse(error instanceof FlowContractError ? error.lines.map(line => inStepWords(line, "zones", zones.map(one => typeof one["kind"] === "string" ? one["kind"] : undefined))).join("\n") : error instanceof Error ? error.message : "Those zones aren't a flow.");
     }
 }
 const plainText = (value, cap, what, required) => {
@@ -328,17 +332,22 @@ const plainText = (value, cap, what, required) => {
         return refuse(`The file's ${what} must be plain text.`);
     if (value.length > cap)
         return refuse(`The file's ${what} is longer than ${cap} characters.`);
-    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f‪-‮⁦-⁩]/.test(value))
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u202a-\u202e\u2066-\u2069]/.test(value))
         return refuse(`The file's ${what} has hidden characters in it.`);
     return value.trim();
 };
-/** Read a flow file: its size, its JSON, its format and version, and every zone, trigger, script and parameter. Throws FlowFileError in plain words. */
+/**
+ * Read a flow file: its size, its JSON and format, then its one schema (flowFileSchema: every zone, trigger, script
+ * and parameter, strict about unknown keys — `zones[0].routes[0]: unknown key 'to' (did you mean goesTo?)`), and a
+ * newer version refused plainly. Then what the schema can't say: no keys in a trigger, ids and names used once, each
+ * {{param.x}} declared, every script valid and the zones a flow. Throws FlowFileError in plain words.
+ */
 export function parseFlowFile(text) {
     if (Buffer.byteLength(text, "utf8") > FLOW_FILE_MAX_BYTES)
         refuse(`That file is too big: a flow file is at most ${FLOW_FILE_MAX_BYTES / 1024} KB.`);
     let raw;
     try {
-        raw = JSON.parse(text.replace(/^/, ""));
+        raw = JSON.parse(text.replace(/^\uFEFF/, ""));
     }
     catch {
         return refuse("That isn't a flow file: it isn't valid JSON.");
@@ -348,75 +357,48 @@ export function parseFlowFile(text) {
     const input = raw;
     if (input["format"] !== FLOW_FILE_FORMAT)
         refuse("That isn't a Toolroll flow file: its format isn't \"toolroll-flow\".");
-    if (input["version"] !== FLOW_FILE_VERSION)
-        refuse(typeof input["version"] === "number" && input["version"] > FLOW_FILE_VERSION
-            ? `This flow file is version ${input["version"]}; this Toolroll reads version ${FLOW_FILE_VERSION}. Update Toolroll, then import it.`
-            : `This flow file has no version Toolroll reads; it should say "version": ${FLOW_FILE_VERSION}.`);
-    const name = plainText(input["name"], 80, "name", true);
-    const about = plainText(input["about"], 600, "about line", false);
-    const array = (key, cap) => {
-        const value = input[key];
-        if (value === undefined || value === null)
-            return [];
-        if (!Array.isArray(value))
-            return refuse(`The file's ${key} must be a list.`);
-        if (value.length > cap)
-            return refuse(`The file has more than ${cap} ${key}.`);
-        return value;
-    };
-    const needs = array("needs", 40).map(one => plainText(one, 80, "needs", true));
-    const parameters = array("parameters", 20).map((one) => {
-        if (one === null || typeof one !== "object" || Array.isArray(one))
-            return refuse("Each parameter is an object with an id and what it asks for.");
-        const row = one;
-        const id = typeof row["id"] === "string" && PARAM_ID.test(row["id"]) ? row["id"] : refuse("Each parameter needs a short id: lowercase letters, numbers and dashes.");
-        const fallback = row["default"] === undefined || row["default"] === null ? undefined : plainText(row["default"], 200, `default for ${id}`, false);
-        return { id, about: plainText(row["about"], 200, `question for ${id}`, true), ...(fallback === undefined ? {} : { default: fallback }), ...(row["optional"] === true ? { optional: true } : {}) };
-    });
-    if (new Set(parameters.map(one => one.id)).size !== parameters.length)
-        refuse("Two parameters have the same id.");
-    const rawZones = array("zones", 24);
-    if (rawZones.length === 0)
-        refuse("The file has no zones.");
-    if (rawZones.some(one => one === null || typeof one !== "object" || Array.isArray(one)))
-        refuse("Each zone is an object with an id, a title and a kind.");
-    const zones = rawZones;
-    const triggers = array("triggers", 10).map(one => {
-        if (one === null || typeof one !== "object" || Array.isArray(one))
-            return refuse("Each trigger is an object with a kind.");
-        const kind = one["kind"];
+    // Triggers that name something on the installation they were made on stay there; say so, not that the kind is unknown.
+    (Array.isArray(input["triggers"]) ? input["triggers"] : []).forEach((one, index) => {
+        const kind = one !== null && typeof one === "object" ? one["kind"] : undefined;
         if (kind === "chat")
-            return refuse("A chat channel trigger can't come from a file: connect the channel from the channel itself.");
+            refuse(`triggers[${index}].kind: a chat channel trigger can't come from a file; connect the channel from the channel itself`);
         if (kind === "flow")
-            return refuse("A trigger from another flow can't come from a file: it names a flow on the installation it was made on.");
-        if (!["button", "schedule", "github", "linear", "webhook", "email", "plane-review"].includes(kind))
-            return refuse(`The file has a trigger Toolroll doesn't know: ${String(kind)}.`);
+            refuse(`triggers[${index}].kind: a trigger from another flow can't come from a file; it names a flow on the installation it was made on`);
+    });
+    const read = readVersioned(flowFileSchema, input, {}, FLOW_ALIASES);
+    if (!read.ok)
+        return refuse(read.issues.map(one => one.line).join("\n"));
+    const file = read.value;
+    const name = file.name.trim(), about = (file.about ?? "").trim();
+    if (name === "")
+        refuse("name: must not be empty");
+    const parameters = (file.parameters ?? []).map(one => ({ ...one, about: one.about.trim(), ...(one.default === undefined ? {} : { default: one.default.trim() }) }));
+    if (new Set(parameters.map(one => one.id)).size !== parameters.length)
+        refuse("parameters: two have the same id");
+    const triggers = file.triggers ?? [];
+    triggers.forEach((one, index) => {
         for (const [key, value] of Object.entries(one))
             if (typeof value === "string" && scanForSecrets(value).length > 0)
-                refuse(`A ${String(kind)} trigger's ${key} looks like a key or password. Keys never go in a flow file.`);
-        return one;
+                refuse(`triggers[${index}].${key}: looks like a key or password; keys never go in a flow file`);
     });
-    const scripts = array("scripts", 20).map((one) => {
-        if (one === null || typeof one !== "object" || Array.isArray(one))
-            return refuse("Each script is an object with a name.");
-        const row = one;
+    const scripts = (file.scripts ?? []).map((row, index) => {
         let draft;
         try {
             draft = validateScript(row);
         }
         catch (error) {
-            return refuse(`Script ${typeof row["name"] === "string" ? row["name"] : "(unnamed)"}: ${error instanceof Error ? error.message : "it isn't valid."}`);
+            return refuse(`scripts[${index}]: ${error instanceof Error ? error.message : "it isn't valid."}`);
         }
         return { name: draft.name, about: draft.about, language: draft.language, timeoutMinutes: draft.timeoutMinutes, ...(draft.file === null ? { body: draft.body } : { file: draft.file }) };
     });
     if (new Set(scripts.map(one => one.name)).size !== scripts.length)
-        refuse("Two scripts have the same name.");
+        refuse("scripts: two have the same name");
     // Every {{param.x}} names a parameter the file declares.
-    for (const match of JSON.stringify([zones, triggers]).matchAll(PARAM))
+    for (const match of JSON.stringify([file.zones, triggers]).matchAll(PARAM))
         if (!parameters.some(one => one.id === match[1]))
             refuse(`The file uses {{param.${match[1]}}} but doesn't say what it asks for.`);
-    definitionOf(zones);
-    return { format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name, about, needs, parameters, zones, triggers, scripts };
+    definitionOf(file.zones);
+    return { format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name, about, needs: (file.needs ?? []).map(one => one.trim()), parameters, zones: file.zones, triggers, scripts };
 }
 /** --param k=v lines (or a form's fields) as values; refuses parameters the file doesn't ask for. */
 export function parameterValues(file, given) {

package/dist/flow-starters.d.ts

@@ -1,4 +1,5 @@
 import { type FlowStepInput } from "./flows.js";
+import type { TriggerInput } from "./contracts/flow.js";
 import type { FlowRow, Store } from "./store.js";
 export declare const STARTER_IDS: readonly ["ci-fix", "issue-task", "overnight", "plane-review"];
 export type StarterId = (typeof STARTER_IDS)[number];
@@ -22,7 +23,7 @@ export type StarterFlow = {
     ownSteps?: FlowStepInput[];
     trigger: (where: {
         branch: string;
-    }) => Record<string, unknown>;
+    }) => TriggerInput;
 };
 export declare const STARTER_FLOWS: readonly StarterFlow[];
 /** The morning plane review's steps: find the cause, fix it, open a pull request; any failure waits for a person. */

package/dist/flow-triggers.d.ts

@@ -1,77 +1,12 @@
 import type { Runner } from "./backend.js";
 import { type FlowAct } from "./flow-engine.js";
-import type { FlowDefinition } from "./flows.js";
+import { type FlowDefinition } from "./flows.js";
+import { type ContractResult } from "./contracts/contract.js";
+import { FLOW_TRIGGER_KINDS, type ChatApp, type FlowTriggerKind, type TriggerConfig, type TriggerInput } from "./contracts/flow.js";
 import { type MailReader } from "./mailbox.js";
 import type { FlowCardSource, FlowRow, FlowTriggerRow, Store } from "./store.js";
-export declare const FLOW_TRIGGER_KINDS: readonly ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat", "plane-review"];
-export type FlowTriggerKind = (typeof FLOW_TRIGGER_KINDS)[number];
-export type TriggerConfig = {
-    kind: "button";
-    label: string;
-    questions: string[];
-    zone: string | null;
-}
-/** `script` (v90): run this project script on the schedule and make a card of each item it prints, instead of one card titled `title`. */
- | {
-    kind: "schedule";
-    schedule: string;
-    title: string;
-    description: string | null;
-    zone: string | null;
-    script?: string;
-    secrets?: string[];
-} | {
-    kind: "github";
-    repo: string;
-    watch: "issues" | "pulls" | "checks";
-    label: string | null;
-    branch: string | null;
-    from: "team" | "anyone";
-    delivery: "poll" | "webhook";
-    zone: string | null;
-} | {
-    kind: "linear";
-    team: string | null;
-    state: string | null;
-    label: string | null;
-    delivery: "poll" | "webhook";
-    zone: string | null;
-} | {
-    kind: "flow";
-    flow: number;
-    when: string;
-    zone: string | null;
-} | {
-    kind: "webhook";
-    title: string;
-    titleField: string | null;
-    bodyField: string | null;
-    zone: string | null;
-}
-/** `sender`: addresses or domains, comma-separated; `subject`: words the subject must contain. */
- | {
-    kind: "email";
-    folder: string;
-    sender: string | null;
-    subject: string | null;
-    zone: string | null;
-}
-/** A channel in a chat app; `binding` is the pairing of the person who connected it (whose chat answers there). */
- | {
-    kind: "chat";
-    app: ChatApp;
-    installation: string;
-    chat: string;
-    binding: number;
-    zone: string | null;
-}
-/** `schedule`: always daily, in the routines' form ("daily:07:30@Europe/London"). */
- | {
-    kind: "plane-review";
-    schedule: string;
-    zone: string | null;
-};
-export type ChatApp = "slack" | "discord" | "teams" | "telegram";
+export { FLOW_TRIGGER_KINDS };
+export type { ChatApp, FlowTriggerKind, TriggerConfig, TriggerInput };
 export declare const CHAT_APP_NAMES: Record<ChatApp, string>;
 /** What each kind is called on the canvas. */
 export declare const FLOW_TRIGGER_WORDS: Record<FlowTriggerKind, string>;
@@ -79,11 +14,18 @@ export declare const FLOW_TRIGGER_WORDS: Record<FlowTriggerKind, string>;
 export declare const POLL_EVERY_MS: number;
 /** At most this many cards from one check or one delivery; the rest wait for the next. */
 export declare const CARDS_PER_CHECK = 10;
+/**
+ * A trigger's settings read by their one schema (`label: required`, `unknown key 'flows'`). A setting given as null is
+ * left out, and a button's blank question lines are dropped, as every release has read them. Then what the schema can't
+ * say, named by its path: no hidden characters and nothing that looks like a key, anywhere in the settings.
+ */
+export declare function readTriggerSettings(raw: unknown): ContractResult<TriggerInput>;
 /** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in the routines' own form. */
 export declare function scheduleFromWords(text: string): string | null;
 /** A GitHub repository as owner/name, read from a project's origin remote when it is on GitHub. */
 export declare function githubRepoOf(path: string): string | null;
-/** A trigger's settings, checked whole against the flow it starts cards in. Throws in plain words. */
+/** A trigger's settings, checked whole against the flow it starts cards in (readTriggerSettings, then the flow, its zones,
+ * the project's scripts and the schedule). Throws FlowContractError, each line naming its setting. */
 export declare function validateTriggerConfig(raw: unknown, context: {
     store: Store;
     flow: FlowRow;
@@ -105,6 +47,8 @@ export declare function triggerHeadline(config: TriggerConfig, store: Store): {
     detail: string;
 };
 export declare function triggerConfigOf(trigger: FlowTriggerRow): TriggerConfig | null;
+/** A saved trigger's config (`configJson`, which carries no version) read by its one schema, what it leaves out filled. */
+export declare function readTriggerConfig(raw: unknown): ContractResult<TriggerConfig>;
 /** Whether this trigger takes deliveries at a secret address rather than being checked. */
 export declare function takesDeliveries(config: TriggerConfig): boolean;
 /** A webhook's signing secret (GitHub: made here; Linear: pasted from Linear). 0600, beside the database, never a column. */
@@ -267,4 +211,3 @@ export type FormAnswer = {
 export declare function flowFormPage(store: Store, token: string, now: Date): FormAnswer;
 /** POST a shared form: at most one card per submission, keys refused, a limit per hour, and quiet about what a bot did wrong. */
 export declare function receiveFlowForm(store: Store, token: string, fields: URLSearchParams, now: Date): FormAnswer;
-export {};