toolroll 0.9.34 → 0.9.36

package/dist/flow-triggers.js

@@ -33,13 +33,16 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, write
 import { join } from "node:path";
 import { scanForSecrets } from "./evidence.js";
 import { flowCardText, flowDefinitionOf } from "./flow-engine.js";
+import { FlowContractError } from "./flows.js";
+import { parseContract } from "./contracts/contract.js";
+import { FLOW_ALIASES, FLOW_TRIGGER_KINDS, SECRETS_MAX, triggerConfigSchema, triggerInputSchema } from "./contracts/flow.js";
 import { describeSchedule, firstFireAt, nextFireAt, parseSchedule, WEEKDAYS } from "./routine.js";
 import { takeReply } from "./flow-replies.js";
 import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./mailbox.js";
 import { readFlowSecrets } from "./flow-secrets.js";
 import { tmpdir } from "node:os";
 import { envValue } from "./names.js";
-export const FLOW_TRIGGER_KINDS = ["button", "schedule", "github", "linear", "flow", "webhook", "email", "chat", "plane-review"];
+export { FLOW_TRIGGER_KINDS };
 export const CHAT_APP_NAMES = { slack: "Slack", discord: "Discord", teams: "Teams", telegram: "Telegram" };
 /** What each kind is called on the canvas. */
 export const FLOW_TRIGGER_WORDS = {
@@ -54,23 +57,30 @@ const HOOK_BYTES = 1_000_000;
 /** Authors GitHub says have write access to the repository. */
 const TEAM = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 // ------------------------------------------------------------ the terms
-function words(input, key, cap, required) {
-    const value = input[key];
-    if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
-        if (required)
-            throw new Error(`Say the trigger's ${key}.`);
-        return null;
+const HIDDEN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * 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 function readTriggerSettings(raw) {
+    const body = isRecord(raw) ? Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== null).map(([key, value]) => [key, key === "questions" && Array.isArray(value) ? value.filter(one => typeof one !== "string" || one.trim() !== "") : value])) : raw;
+    const read = parseContract(triggerInputSchema, body, FLOW_ALIASES);
+    if (!read.ok)
+        return read;
+    for (const [key, value] of Object.entries(read.value)) {
+        for (const [n, one] of (Array.isArray(value) ? value : [value]).entries()) {
+            if (typeof one !== "string")
+                continue;
+            const path = Array.isArray(value) ? `${key}[${n}]` : key;
+            if (HIDDEN.test(one))
+                return { ok: false, issues: [{ path, kind: "bad-value", line: `${path}: can't contain hidden characters` }] };
+            if (scanForSecrets(one).length > 0)
+                return { ok: false, issues: [{ path, kind: "bad-value", line: `${path}: looks like a key or password; keys never go in a trigger's settings` }] };
+        }
     }
-    if (typeof value !== "string")
-        throw new Error(`The trigger's ${key} must be plain text.`);
-    const trimmed = value.trim();
-    if (trimmed.length > cap)
-        throw new Error(`The trigger's ${key} is up to ${cap} characters.`);
-    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/.test(trimmed))
-        throw new Error(`The trigger's ${key} can't contain hidden characters.`);
-    if (scanForSecrets(trimmed).length > 0)
-        throw new Error("That looks like a key or password. Keys never go in a trigger's settings.");
-    return trimmed;
+    return read;
 }
 /** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in the routines' own form. */
 export function scheduleFromWords(text) {
@@ -116,111 +126,98 @@ export function githubRepoOf(path) {
         return 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 function validateTriggerConfig(raw, context) {
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-        throw new Error("Choose what starts cards.");
-    const input = raw;
-    const kind = input["kind"];
-    if (!FLOW_TRIGGER_KINDS.includes(kind))
-        throw new Error("Choose what starts cards: a button, a schedule, GitHub, Linear, another flow, a webhook, an email inbox, a chat channel or a plane review.");
-    const named = words(input, "zone", 60, false);
+    // Connecting a channel proves it's one the person is in: it happens in the channel, not here.
+    if (isRecord(raw) && raw["kind"] === "chat")
+        throw new FlowContractError([`kind: connect a chat channel from the channel itself: where Toolroll is in Slack, Discord, Teams or a Telegram group, send “flow ${context.flow.id}”`]);
+    const read = readTriggerSettings(raw);
+    if (!read.ok)
+        throw new FlowContractError(read.issues.map(one => one.line));
+    const input = read.value;
+    const refuse = (path, what) => { throw new FlowContractError([`${path}: ${what}`]); };
+    /** A setting's words, trimmed; blank is left out. */
+    const said = (value) => value === undefined || value.trim() === "" ? null : value.trim();
+    const named = said(input.zone);
     const zoneStage = named === null ? null : context.definition.stages.find(one => one.id === named || one.title.toLowerCase() === named.toLowerCase());
     if (named !== null && zoneStage === undefined)
-        throw new Error(`This flow has no zone called ${named}.`);
+        refuse("zone", `this flow has no zone called ${named}`);
     const zone = zoneStage?.id ?? null;
-    const choice = (key, options, fallback) => {
-        const value = input[key];
-        if (value === undefined || value === null || value === "")
-            return fallback;
-        if (!options.includes(value))
-            throw new Error(`Choose the trigger's ${key}: ${options.join(" or ")}.`);
-        return value;
-    };
-    switch (kind) {
+    switch (input.kind) {
         case "button": {
-            const label = words(input, "label", 40, true);
-            const asked = input["questions"];
-            const questions = (Array.isArray(asked) ? asked : typeof asked === "string" ? asked.split("\n") : [])
-                .map(one => typeof one === "string" ? one.trim() : "").filter(one => one !== "");
+            const label = said(input.label) ?? refuse("label", "required");
+            const questions = (Array.isArray(input.questions) ? input.questions : typeof input.questions === "string" ? input.questions.split("\n") : []).map(one => one.trim()).filter(one => one !== "");
             if (questions.length > 6)
-                throw new Error("A button asks at most 6 questions.");
-            for (const question of questions)
-                if (question.length > 80 || scanForSecrets(question).length > 0)
-                    throw new Error("Each question is a short line of plain text.");
+                refuse("questions", "at most 6 items");
+            questions.forEach((question, n) => { if (question.length > 80)
+                refuse(`questions[${n}]`, "at most 80 characters"); });
             return { kind: "button", label, questions: questions.length === 0 ? ["What needs doing?", "Details"] : questions, zone };
         }
         case "schedule": {
-            const said = words(input, "schedule", 80, true);
-            const schedule = scheduleFromWords(said);
-            if (schedule === null)
-                throw new Error("Say the schedule like “every 2 hours”, “daily 09:00 Europe/London”, “weekdays 09:00” or “monday 09:00”.");
+            const said_ = said(input.schedule) ?? refuse("schedule", "required");
+            const schedule = scheduleFromWords(said_) ?? refuse("schedule", "say it like “every 2 hours”, “daily 09:00 Europe/London”, “weekdays 09:00” or “monday 09:00”");
             // A script on a schedule (v90): each item it prints becomes a card.
-            const script = words(input, "script", 40, false);
+            const script = said(input.script);
             if (script !== null) {
                 if (context.store.flowScript(context.flow.repo, script) === null)
-                    throw new Error(`There's no script called ${script} in this project. Make it on the flow's Scripts panel first.`);
-                const asked = input["secrets"];
-                const secrets = asked === undefined || asked === null ? [] : Array.isArray(asked) ? asked : typeof asked === "string" ? asked.split(/[\s,]+/).filter(one => one !== "") : null;
-                if (secrets === null || secrets.length > 10 || secrets.some(one => typeof one !== "string" || !/^[A-Z][A-Z0-9_]{0,39}$/.test(one)))
-                    throw new Error("Name up to 10 saved secrets in capitals, like API_TOKEN.");
+                    refuse("script", `there's no script called ${script} in this project; make it on the flow's Scripts panel first`);
+                const secrets = input.secrets === undefined ? [] : Array.isArray(input.secrets) ? input.secrets : input.secrets.split(/[\s,]+/).filter(one => one !== "");
+                if (secrets.length > SECRETS_MAX || secrets.some(one => !/^[A-Z][A-Z0-9_]{0,39}$/.test(one)))
+                    refuse("secrets", "name up to 10 saved secrets in capitals, like API_TOKEN");
                 return { kind: "schedule", schedule, title: `Items from ${script}`, description: null, zone, script, ...(secrets.length === 0 ? {} : { secrets: [...new Set(secrets)] }) };
             }
-            return { kind: "schedule", schedule, title: words(input, "title", 200, true), description: words(input, "description", 2000, false), zone };
+            return { kind: "schedule", schedule, title: said(input.title) ?? refuse("title", "required"), description: said(input.description), zone };
         }
         case "github": {
-            const repo = words(input, "repo", 140, false) ?? githubRepoOf(context.flow.repo);
+            const repo = said(input.repo) ?? githubRepoOf(context.flow.repo);
             if (repo === null || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo))
-                throw new Error("Name the GitHub repository as owner/name.");
-            const watch = choice("watch", ["issues", "pulls", "checks"], "issues");
-            const label = watch === "checks" ? null : words(input, "label", 50, false);
-            const branch = watch === "checks" ? words(input, "branch", 100, false) ?? "main" : null;
+                refuse("repo", "name the GitHub repository as owner/name");
+            const watch = input.watch ?? "issues";
+            const label = watch === "checks" ? null : said(input.label);
+            const branch = watch === "checks" ? said(input.branch) ?? "main" : null;
             if (branch !== null && !/^[A-Za-z0-9._/-]+$/.test(branch))
-                throw new Error("That branch name isn't valid.");
-            return { kind: "github", repo, watch, label, branch, from: choice("from", ["team", "anyone"], "team"), delivery: choice("delivery", ["poll", "webhook"], "poll"), zone };
+                refuse("branch", "that branch name isn't valid");
+            return { kind: "github", repo: repo, watch, label, branch, from: input.from ?? "team", delivery: input.delivery ?? "poll", zone };
         }
         case "linear": {
-            const team = words(input, "team", 12, false), state = words(input, "state", 40, false), label = words(input, "label", 50, false);
+            const team = said(input.team), state = said(input.state), label = said(input.label);
             if (team !== null && !/^[A-Za-z0-9]+$/.test(team))
-                throw new Error("A Linear team is its short key, like ENG.");
+                refuse("team", "a Linear team is its short key, like ENG");
             if (team === null && label === null)
-                throw new Error("Name a Linear team or a label, so the trigger doesn't take every issue in the workspace.");
-            return { kind: "linear", team: team?.toUpperCase() ?? null, state, label, delivery: choice("delivery", ["poll", "webhook"], "poll"), zone };
+                refuse("team", "name a Linear team or a label, so the trigger doesn't take every issue in the workspace");
+            return { kind: "linear", team: team?.toUpperCase() ?? null, state, label, delivery: input.delivery ?? "poll", zone };
         }
         case "flow": {
-            const source = Number(input["flow"]);
-            const flow = Number.isSafeInteger(source) ? context.store.getFlow(source) : null;
+            const flow = context.store.getFlow(input.flow);
             const sourceDefinition = flow === null ? null : flowDefinitionOf(flow);
             if (flow === null || flow.state !== "active" || sourceDefinition === null || !context.store.accountCanAccess(context.actor, flow.repo))
-                throw new Error("Choose another flow in your projects.");
+                return refuse("flow", "choose another flow in your projects");
             if (flow.id === context.flow.id)
-                throw new Error("A flow can't start cards in itself; move them with a zone's next step instead.");
-            const when = words(input, "when", 60, false);
+                refuse("flow", "a flow can't start cards in itself; move them with a zone's next step instead");
+            const when = said(input.when);
             const stage = when === null ? sourceDefinition.stages.find(one => one.kind === "done") : sourceDefinition.stages.find(one => one.id === when || one.title.toLowerCase() === when.toLowerCase());
             if (stage === undefined)
-                throw new Error(`${flow.name} has no zone called ${when ?? "Done"}.`);
+                return refuse("when", `${flow.name} has no zone called ${when ?? "Done"}`);
             return { kind: "flow", flow: flow.id, when: stage.id, zone };
         }
         case "webhook":
-            return { kind: "webhook", title: words(input, "title", 120, false) ?? "Webhook", titleField: words(input, "titleField", 80, false), bodyField: words(input, "bodyField", 80, false), zone };
-        case "chat":
-            // Connecting a channel proves it's one the person is in: it happens in the channel, not here.
-            throw new Error(`Connect a chat channel from the channel itself: where Toolroll is in Slack, Discord, Teams or a Telegram group, send “flow ${context.flow.id}”.`);
+            return { kind: "webhook", title: said(input.title) ?? "Webhook", titleField: said(input.titleField), bodyField: said(input.bodyField), zone };
         case "plane-review": {
-            const at = words(input, "at", 5, false) ?? "07:30";
+            const at = said(input.at) ?? "07:30";
             const clock = /^(\d{1,2}):(\d{2})$/.exec(at);
-            const zoneName = words(input, "timeZone", 60, false) ?? localTimeZone();
+            const zoneName = said(input.timeZone) ?? localTimeZone();
             const schedule = clock === null ? null : scheduleFromWords(`daily ${clock[1]}:${clock[2]} ${zoneName}`);
             if (schedule === null)
-                throw new Error("Say the time it reviews the day as HH:MM, like 07:30, and a time zone like Europe/London.");
+                return refuse("at", "say the time it reviews the day as HH:MM, like 07:30, and a time zone like Europe/London");
             return { kind: "plane-review", schedule, zone };
         }
         case "email": {
-            const folder = words(input, "folder", 100, false) ?? "INBOX";
-            const sender = words(input, "sender", 300, false);
+            const folder = said(input.folder) ?? "INBOX";
+            const sender = said(input.sender);
             if (sender !== null && sendersOf(sender).length === 0)
-                throw new Error("Say whom mail comes from as addresses or domains, like priya@example.com or example.com.");
-            return { kind: "email", folder: /^inbox$/i.test(folder) ? "INBOX" : folder, sender: sender === null ? null : sendersOf(sender).join(", "), subject: words(input, "subject", 100, false), zone };
+                refuse("sender", "say whom mail comes from as addresses or domains, like priya@example.com or example.com");
+            return { kind: "email", folder: /^inbox$/i.test(folder) ? "INBOX" : folder, sender: sender === null ? null : sendersOf(sender).join(", "), subject: said(input.subject), zone };
         }
     }
 }
@@ -300,12 +297,26 @@ export function triggerHeadline(config, store) {
     }
 }
 export function triggerConfigOf(trigger) {
+    let raw;
     try {
-        return JSON.parse(trigger.configJson);
+        raw = JSON.parse(trigger.configJson);
     }
     catch {
         return null;
     }
+    const read = readTriggerConfig(raw);
+    return read.ok ? read.value : null;
+}
+/** What a saved trigger leaves out, it had as these (every release has saved them whole; a hand-made row may not). */
+const SAVED_DEFAULTS = {
+    button: { questions: ["What needs doing?", "Details"] }, schedule: { description: null }, github: { label: null, branch: null, from: "team", delivery: "poll" },
+    linear: { team: null, state: null, label: null, delivery: "poll" }, webhook: { title: "Webhook", titleField: null, bodyField: null }, email: { folder: "INBOX", sender: null, subject: null },
+};
+/** A saved trigger's config (`configJson`, which carries no version) read by its one schema, what it leaves out filled. */
+export function readTriggerConfig(raw) {
+    const kind = isRecord(raw) ? raw["kind"] : undefined;
+    const body = isRecord(raw) ? { zone: null, ...SAVED_DEFAULTS[kind], ...raw } : raw;
+    return parseContract(triggerConfigSchema, body);
 }
 /** Whether this trigger takes deliveries at a secret address rather than being checked. */
 export function takesDeliveries(config) {

package/dist/flows.d.ts

@@ -1,172 +1,57 @@
-export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "send", "choose", "done"];
-export type FlowStageKind = (typeof FLOW_STAGE_KINDS)[number];
-export declare const FLOW_COLORS: readonly ["slate", "blue", "violet", "amber", "green", "rose"];
-export type FlowColor = (typeof FLOW_COLORS)[number];
-export type FlowZone = {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    color: FlowColor;
-};
-/** One answer a sort zone can pick: its name, what it means (what Jev reads), and the zone it sends the card to. */
-export type FlowSortAnswer = {
-    answer: string;
-    means: string;
-    to: string;
-};
-/** Something else a sort zone notes on the card: a score on a scale of levels, or a yes/no. */
-export type FlowSortNote = {
-    id: string;
-    kind: "score" | "yes-no";
-    question: string;
-    levels: string[] | null;
-};
-/** sort: the question, its answers, how sure Jev must be to act alone (0.5–0.99), and what else it notes. */
-export type FlowSort = {
-    question: string;
-    answers: FlowSortAnswer[];
-    sureAt: number;
-    notes: FlowSortNote[];
-};
-/** request: what is called. The address's scheme and host are fixed; fill-ins go in its path and query (encoded), headers and body. */
-export type FlowRequest = {
-    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-    url: string;
-    headers: Record<string, string>;
-    body: string | null;
-};
-/** email: who it goes to, the subject and the text — all with fill-ins. */
-export type FlowEmail = {
-    to: string;
-    subject: string;
-    body: string;
-};
-/** tool: which of the project's tools (MCP servers), which of its functions, and the arguments as JSON with fill-ins. */
-export type FlowTool = {
-    server: string;
-    name: string;
-    args: string;
-};
-/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next).
- * "hours": until the clock is between `from` and `to` (like 22:00–06:00), in the computer's time zone unless one is named. */
-export type FlowWait = {
-    for: "reply" | "time" | "hours";
-    minutes: number;
-    from?: string;
-    to?: string;
-    timeZone?: string;
-};
-/** How a Pull request zone merges once checks pass. */
-export declare const FLOW_MERGE_METHODS: readonly ["squash", "merge", "rebase"];
-export type FlowMergeMethod = (typeof FLOW_MERGE_METHODS)[number];
-/** A choose zone's option: its button's words, and the zone it leads to (FLOW_END closes the card as Ignored). */
-export type FlowChoice = {
-    label: string;
-    to: string;
-};
-/** Where a choose option that ends the card leads. */
-export declare const FLOW_END = "end";
-/** How many options a choose zone offers. */
-export declare const CHOICES_MIN = 2, CHOICES_MAX = 4;
-/** A time limit on a zone (v91): after this long, the person it waits on is reminded, and a Holding or
- * "Person decides" zone can move the card on (`to`). */
-export type FlowLimit = {
-    minutes: number;
-    to: string | null;
-};
-export type FlowStage = {
-    id: string;
-    title: string;
-    kind: FlowStageKind;
-    zone: FlowZone;
-    /** task/report: what the agent is asked to do. `{{card.title}}`,
-     * `{{card.description}}`, `{{note}}` (the latest send-back note) and
-     * `{{stage.<id>}}` (an earlier zone's report) are filled in. */
-    instructions: string | null;
-    /** task: plan first (required), let Toolroll decide (auto), or build directly (skip). */
-    planning: "auto" | "required" | "skip" | null;
-    /** approval: the one person who decides, or null for any approver on the project. */
-    approver: string | null;
-    /** approval: the flow's owner decides (v86), whoever that is when the card arrives; `approver` is then unused. */
-    toOwner?: boolean;
-    /** notify: the message; update: the comment left on the issue. Same fill-ins. */
-    message: string | null;
-    /** update: also close the issue (Linear: move it to the team's done state). */
-    close: boolean | null;
-    /** check: the project script (by name) run with no AI. */
-    script: string | null;
-    /** check (v90): where it runs — a clean folder, or a copy of the card's work (the default for zones made before v90);
-     * the answers a script's "goto:" line may pick, each with the zone it leads to; and the flow secrets it gets as variables. */
-    runIn?: "folder" | "copy";
-    routes?: {
-        answer: string;
-        to: string;
-    }[];
-    secrets?: string[];
-    /** sort: what Jev is asked and where each answer leads. Its onFail is where a card goes when Jev isn't sure. */
-    sort: FlowSort | null;
-    /** request, email, tool (v87): what the step sends, and to where. */
-    request?: FlowRequest;
-    email?: FlowEmail;
-    tool?: FlowTool;
-    /** wait (v91): what it waits for, and how long. */
-    wait?: FlowWait;
-    /** Any zone but Wait and Done (v91): how long a card may sit here before someone is reminded. */
-    limit?: FlowLimit;
-    /** v92: the AI teammate (by handle) who decides a "Person decides" zone (handing hard ones to its person), or handles a "Teammate handles it" zone. */
-    teammate?: string;
-    /** v96: a "Teammate handles it" zone sends what the teammate writes back to whoever asked (the person who added the card, its chat thread, or the teammate's manager). */
-    reply?: boolean;
-    /** choose: the buttons the person picks from, in order. Its onFail is where a reply goes, with the reply as {{note}}. */
-    options?: FlowChoice[];
-    /** task: the project it builds in, when not the flow's own (one the flow's owner may file in). */
-    repo?: string;
-    /** pull-request: merge once checks pass, this way. Only allowed after a "Person decides" zone, and a card merges only when a person approved it after it was built. */
-    merge?: FlowMergeMethod;
-    /** Where a card goes when this zone's step succeeds, and when it fails or is sent back (sort: when it isn't sure). */
-    next: string | null;
-    onFail: string | null;
-};
-export type FlowDefinition = {
-    version: 1;
-    start: string;
-    stages: FlowStage[];
-};
+import { type ContractIssue, type ContractResult } from "./contracts/contract.js";
+import { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, type FlowDefinition, type FlowStage, type FlowStageKind, type FlowStepFields, type FlowWait, type ScriptLanguage, type TriggerInput } from "./contracts/flow.js";
+export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME };
+export type { FlowChoice, FlowColor, FlowDefinition, FlowEmail, FlowLimit, FlowMergeMethod, FlowRequest, FlowSort, FlowSortAnswer, FlowSortNote, FlowStage, FlowStageKind, FlowStepInput, FlowTool, FlowWait, FlowZone, ScriptLanguage, } from "./contracts/flow.js";
 /** What each kind is called and does, in the words the canvas uses. */
 export declare const FLOW_KIND_WORDS: Record<FlowStageKind, {
     label: string;
     about: string;
 }>;
-/** A project script's name: short, lowercase, dashes — how zones and chat refer to it. */
-export declare const SCRIPT_NAME: RegExp;
-/** The languages a project script is written in (v90). */
-export declare const SCRIPT_LANGUAGES: readonly ["shell", "python", "node"];
-export type ScriptLanguage = (typeof SCRIPT_LANGUAGES)[number];
 export declare const LANGUAGE_WORDS: Record<ScriptLanguage, string>;
 /** How an answer is named to Jev: its words as a short key. */
 export declare const sortKeyOf: (answer: string) => string;
 /** The default for "sure enough to act alone". */
 export declare const SORT_SURE_AT = 0.8;
-/** The longest a zone waits or a limit runs: 30 days. */
-export declare const LONGEST_WAIT_MINUTES: number;
 /** "3 days", "4 hours", "90 minutes", "1 week" (or a number of minutes) as minutes; null when it isn't one. */
 export declare function durationMinutes(value: unknown): number | null;
 /** Minutes in the words people use: "3 days", "1 day 4 hours", "45 minutes". */
 export declare function durationWords(minutes: number): string;
 /** "22:00", "9:30" as "HH:MM"; null when it isn't a time of day. */
 export declare function clockTime(value: unknown): string | null;
+export declare function knownTimeZone(zone: string): boolean;
 /** Whether a time falls inside an "hours" wait (22:00–06:00 runs past midnight), in its time zone or this computer's. */
 export declare function withinHours(wait: Pick<FlowWait, "from" | "to" | "timeZone">, now: Date): boolean;
 /** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
 export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">, flow: {
     owner: string;
 }): string | null;
-/** A flow as drawn on the canvas, checked whole. Throws in plain words. */
-/** `stored`: reading a flow saved earlier, which keeps working under rules added since (its cards say what's wrong). */
+/** A flow refused by its contract: every problem, each naming its path (`stages[2].instructions: required`). */
+export declare class FlowContractError extends Error {
+    readonly lines: readonly string[];
+    constructor(lines: readonly string[]);
+}
+/** What JSON Schema can't say about a drawing, each named by its path: paths lead to zones that exist and never back into
+ * their own zone, answers and options have names of their own, a web address's host is written out, tool arguments are a
+ * JSON object, an hours wait's times differ in a real time zone, and a merge comes after a person's decision. */
+export declare function drawingProblems(definition: FlowDefinition): ContractIssue[];
+/**
+ * Read a flow's drawing: the canvas's, a step list's once built, or one saved earlier (`stored`, which keeps working under
+ * rules added since: its instructions keep the length they were saved with). A version 1 drawing is read as every release
+ * has read it (canonicalStage), then the schema checks it, then drawingProblems; a newer version is refused plainly.
+ */
+export declare function readFlowDefinition(input: unknown, options?: {
+    stored?: boolean;
+}): ContractResult<FlowDefinition>;
+/** A refusal of the drawing a step list or flow file became, in its words: `stages[2].sort.answers[0].to` is
+ * `steps[2].answers[0].goesTo` (each zone is the step at its index), and a zone's failure path is the step's own name for it. */
+export declare function inStepWords(line: string, list: "steps" | "zones", kinds: readonly (string | undefined)[]): string;
+/** A flow as drawn on the canvas, checked whole (readFlowDefinition). Throws FlowContractError, naming every path. */
 export declare function validateFlowDefinition(input: unknown, options?: {
     stored?: boolean;
 }): FlowDefinition;
+/** A drawing's refusal as the canvas shows it: each line as it is, after the name of the zone it is about, so a person
+ * finds it on the canvas (`Build · stages[1].instructions: required`). */
+export declare function withZoneNames(lines: readonly string[], input: unknown): string;
 /** The instructions 0.9.26 and earlier read from a saved zone: they re-check this length on every read, and a flow with a
  * longer one won't load. A saved zone keeps its first part under it, and the rest in `instructionsMore`, which they ignore. */
 export declare const FLOW_INSTRUCTIONS_STORED = 4000;
@@ -217,86 +102,21 @@ export declare function cardEmailOf(card: {
     title: string;
     description: string | null;
 }): string;
-/** A step as the lead describes it, in list order. A step that keeps an
- * existing zone (by `id`) carries over whatever it leaves out. */
-export type FlowStepInput = {
-    id?: string;
-    title?: string;
-    kind?: FlowStageKind;
-    instructions?: string;
-    planning?: "auto" | "required" | "skip";
-    decider?: string | null;
-    message?: string;
-    script?: string;
-    close?: boolean;
-    /** check (v90): "folder" (a clean folder) or "copy" (a copy of the card's work); the answers a "goto:" line picks, each with the step it goes to; saved secrets it gets. */
-    runIn?: "folder" | "copy";
-    routes?: {
-        answer?: string;
-        goesTo?: string;
-    }[];
-    secrets?: string[];
-    /** sort: the question, each answer with what it means and the step it goes to, how sure Jev must be (a percentage), and up to 3 other things to note. */
-    question?: string;
-    answers?: {
-        answer?: string;
-        means?: string;
-        goesTo?: string;
-    }[];
-    sureAt?: number;
-    alsoNote?: {
-        question?: string;
-        kind?: "score" | "yes-no";
-        levels?: string[];
-    }[];
-    /** request: method, address, headers and body; email: to, subject, body; tool: the tool (server), its function (tool) and arguments. */
-    method?: FlowRequest["method"];
-    url?: string;
-    headers?: Record<string, string>;
-    body?: string;
-    to?: string;
-    subject?: string;
-    server?: string;
-    tool?: string;
-    args?: Record<string, unknown> | string;
-    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes.
-     * "hours": until the clock is between `from` and `until` ("22:00", "06:00"). */
-    waitFor?: "reply" | "time" | "hours";
-    wait?: string | number;
-    ifNoReply?: string;
-    from?: string;
-    until?: string;
-    /** pull-request: merge once checks pass (true is squash). Needs a decision before it. */
-    merge?: boolean | FlowMergeMethod;
-    /** Any step but wait and done (v91): remind after this long ("2 days"; "none" removes it), and on holding and approval steps, move the card to this step then. */
-    remindAfter?: string | number;
-    thenMoveTo?: string;
-    /** v92: the AI teammate (by name) who decides an approval step (handing hard ones to its decider) or handles a teammate step. */
-    teammate?: string;
-    /** v96: a teammate step sends what it writes back to whoever asked. */
-    reply?: boolean;
-    /** choose: 2 to 4 buttons, each with its words and the step it goes to ("end" ignores the card); where a reply goes instead
-     * (the reply is its {{note}}; the nearest earlier build or research step when left out). ifNoReply (with remindAfter) moves it on. */
-    options?: {
-        label?: string;
-        goesTo?: string;
-    }[];
-    ifReplied?: string;
-    /** task: the project it builds in (path), when not the flow's own. */
-    repo?: string;
-    next?: string;
-    ifFails?: string;
-    ifNotSure?: string;
-};
 /** What a draft zone asks for when the steps leave it out. */
 export declare const DRAFT_DEFAULT = "Write a short, friendly reply to the person who sent this card, in plain words.";
 /** Steps as the lead's flow tool and `toolroll flows` take them: "me" as a decider is the person asking, stored by name. */
 export declare function stepsFor(steps: unknown, name: string): unknown;
+/** An edit's steps with what a kept step leaves out of its kind and name filled from the zone it keeps (by id), so each
+ * reads as the one schema its kind has. Anything else it leaves out carries over when the flow is drawn (flowFromSteps). */
+export declare function withKeptSteps(steps: unknown, previous: FlowDefinition | null): unknown;
+/** A flow's steps, read by their one schema: `steps[0].routes[0]: unknown key 'to' (did you mean goesTo?)`. */
+export declare function readFlowSteps(input: unknown, previous?: FlowDefinition | null): ContractResult<FlowStepFields[]>;
 /**
  * A flow from an ordered list of steps: ids from names, each step leading
  * to the next, a Done zone at the end when none is listed, and a decision
  * sending work back to the nearest earlier step that does work. New zones
- * are laid out in rows; zones kept from `previous` keep their place.
+ * are laid out in rows; zones kept from `previous` keep their place. Throws
+ * FlowContractError, each line naming the step's path (`steps[2].next: ...`).
  */
 export declare function flowFromSteps(input: unknown, previous?: FlowDefinition | null): FlowDefinition;
 /** What confirming a new or changed flow means, in the canvas's words: each step's job and path, what changed, and that the usual approvals still apply. */
@@ -310,6 +130,5 @@ export declare const FLOW_TEMPLATES: readonly {
     label: string;
     about: string;
     definition: FlowDefinition;
-    trigger?: Record<string, unknown>;
+    trigger?: TriggerInput;
 }[];
-export {};