toolroll 0.9.34 → 0.9.37

package/dist/contracts/contract.js

@@ -12,12 +12,13 @@ import { limitRule, TEXT_LIMITS } from "../text-limits.js";
  * A string bounded by its TEXT_LIMITS entry, never a literal. The limit rule rides along as the field's description,
  * so a model reads the bound before it writes. Zod counts UTF-16 code units; for a limit named in bytes this is the
  * schema's necessary bound (a string within N bytes is within N code units), and the byte count itself is checked in
- * plain code after parsing.
+ * plain code after parsing. `shorten: false` is for a contract with no shorten turn (a parked decision): its
+ * description states the bound without promising one.
  */
-export function limited(field, limitKey) {
+export function limited(field, limitKey, options = {}) {
     const limit = TEXT_LIMITS[limitKey];
     const unit = limitKey.endsWith("Bytes") ? "bytes" : "characters";
-    return z.string().max(limit, { error: `over ${limit.toLocaleString("en-US")} ${unit}` }).describe(limitRule(field, limit, unit));
+    return z.string().max(limit, { error: `over ${limit.toLocaleString("en-US")} ${unit}` }).describe(limitRule(field, limit, unit, options.shorten ?? true));
 }
 /** A versioned payload envelope: a strict object whose `version` is exactly `version`. */
 export function versioned(version, shape) {
@@ -41,55 +42,190 @@ function got(input) {
         return "an array";
     return typeof input === "object" ? "an object" : `a ${typeof input}`;
 }
-function issuesOf(issue) {
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The schema at `path`, including whether that value may be omitted, following arrays, wrappers and unions. */
+function nodeAt(schema, input, path) {
+    let node = schema, value = input;
+    let optional = false;
+    for (let at = 0; node !== undefined;) {
+        const def = node._zod.def;
+        if (def.type === "optional" || def.type === "nullable" || def.type === "readonly") {
+            if (def.type === "optional")
+                optional = true;
+            node = def["innerType"];
+            continue;
+        }
+        if (def.type === "lazy") {
+            node = def["getter"]();
+            continue;
+        }
+        if (def.type === "union") {
+            const options = def["options"];
+            const by = def["discriminator"];
+            const wanted = by !== undefined && isRecord(value) ? value[by] : undefined;
+            node = options.find(option => {
+                const shape = option._zod.def["shape"];
+                if (shape === undefined)
+                    return false;
+                if (by === undefined)
+                    return true;
+                const literal = shape[by]?._zod.def;
+                return literal !== undefined && literal["values"]?.includes(wanted) === true;
+            });
+            continue;
+        }
+        if (at === path.length)
+            return { def, optional };
+        const part = path[at++];
+        optional = false;
+        if (def.type === "array" && typeof part === "number") {
+            node = def["element"];
+            value = Array.isArray(value) ? value[part] : undefined;
+            continue;
+        }
+        if (def.type === "object" && typeof part === "string") {
+            const shape = def["shape"];
+            node = shape[part] ?? def["catchall"];
+            value = isRecord(value) ? value[part] : undefined;
+            continue;
+        }
+        return null;
+    }
+    return null;
+}
+/** Edit distance, for "did you mean" (short strings only). */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let last = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const was = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, last + (a[i - 1] === b[j - 1] ? 0 : 1));
+            last = was;
+        }
+    }
+    return row[b.length];
+}
+/** The allowed key an unknown one most likely meant, or null. */
+function suggestion(key, known, options) {
+    if (known === null || known.length === 0)
+        return null;
+    const alias = options.aliases?.[key]?.find(one => known.includes(one));
+    if (alias !== undefined)
+        return alias;
+    const close = known
+        .map(one => ({ one, far: one.toLowerCase() === key.toLowerCase() ? 0 : distance(one.toLowerCase(), key.toLowerCase()) }))
+        .filter(({ one, far }) => far <= (Math.min(one.length, key.length) >= 6 ? 2 : 1))
+        .sort((a, b) => a.far - b.far);
+    return close[0]?.one ?? null;
+}
+function issuesOf(issue, where = {}) {
     const at = pathOf(issue.path);
     const one = (kind, what) => ({ path: at, kind, line: `${at}: ${what}` });
     switch (issue.code) {
-        case "unrecognized_keys":
-            return issue.keys.map(key => ({ path: at, kind: "unknown-key", line: `${at}: unknown key '${key}'` }));
+        case "unrecognized_keys": {
+            const def = where.schema === undefined ? undefined : nodeAt(where.schema, where.input, issue.path)?.def;
+            const known = def?.type === "object" ? Object.keys(def["shape"]) : null;
+            return issue.keys.map(key => {
+                const meant = suggestion(key, known, where.options ?? {});
+                return { path: at, kind: "unknown-key", line: `${at}: unknown key '${key}'${meant === null ? "" : ` (did you mean ${meant}?)`}` };
+            });
+        }
         case "invalid_type": {
             const missing = "input" in issue ? issue.input === undefined : / received undefined$/.test(issue.message);
-            if (missing)
+            // Keep required-null wording for required fields; an optional field given null has the wrong type, and so does
+            // any null when the caller distinguishes null from missing.
+            const optional = where.schema !== undefined && nodeAt(where.schema, where.input, issue.path)?.optional === true;
+            if (missing || (!optional && !where.options?.distinguishNull && "input" in issue && issue.input === null && issue.expected !== "null"))
                 return [one("required", "required")];
-            return [one("wrong-type", `must be ${issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : `a ${issue.expected}`}${"input" in issue ? ` (got ${got(issue.input)})` : ""}`)];
+            const expected = issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : issue.expected === "int" ? "an integer" : issue.expected === "null" ? "null" : `a ${issue.expected}`;
+            return [one("wrong-type", `must be ${expected}${"input" in issue ? ` (got ${got(issue.input)})` : ""}`)];
         }
         case "too_big":
             if (issue.origin === "array" || issue.origin === "set")
                 return [one("too-many", `at most ${String(issue.maximum)} items`)];
+            if (issue.origin === "number" || issue.origin === "int" || issue.origin === "bigint")
+                return [one("bad-value", `at most ${String(issue.maximum)}`)];
             return [one("too-long", issue.origin === "string" && issue.message.startsWith("over ") ? issue.message : `at most ${String(issue.maximum)}${issue.origin === "string" ? " characters" : ""}`)];
         case "too_small":
             if (issue.origin === "string" && Number(issue.minimum) === 1)
                 return [one("empty", "must not be empty")];
             if (issue.origin === "array" || issue.origin === "set")
                 return [one("too-few", `at least ${String(issue.minimum)} item${Number(issue.minimum) === 1 ? "" : "s"}`)];
+            if (issue.origin === "number" || issue.origin === "int" || issue.origin === "bigint")
+                return [one("bad-value", `at least ${String(issue.minimum)}`)];
             return [one("too-few", `at least ${String(issue.minimum)}`)];
         case "invalid_value":
             return [one("bad-value", `must be ${issue.values.length === 1 ? JSON.stringify(issue.values[0]) : `one of ${issue.values.map(value => JSON.stringify(value)).join(", ")}`}`)];
-        case "invalid_union":
+        case "invalid_union": {
+            // A discriminated union names its choices (`steps[0].kind: must be one of "inbox", "task", ...`).
+            const by = issue.discriminator, options = issue.options;
+            if (typeof by === "string" && Array.isArray(options)) {
+                const given = "input" in issue && isRecord(issue.input) ? issue.input[by] : undefined;
+                const path = at === "payload" || issue.path.at(-1) === by ? at : `${at}.${by}`;
+                const missing = given === undefined || (given === null && !where.options?.distinguishNull);
+                const line = missing ? "required" : `must be one of ${options.map(value => JSON.stringify(value)).join(", ")}`;
+                return [{ path, kind: missing ? "required" : "bad-value", line: `${path}: ${line}` }];
+            }
             return [one("invalid", "does not match any allowed shape")];
+        }
+        case "invalid_format":
+            // A pattern's own words say what it wants (`must be a short id: lowercase letters, numbers and dashes`).
+            return [one("bad-value", issue.message.startsWith("Invalid") ? `must match ${issue.format === "regex" ? issue.pattern ?? "its pattern" : issue.format}` : issue.message)];
         default:
             return [one("invalid", issue.message)];
     }
 }
-/** A Zod error as path-named issues, in the error's own order. */
-export function contractIssues(error) {
-    return error.issues.flatMap(issuesOf);
+/**
+ * A Zod error as path-named issues, in the error's own order. Given the schema and input it came from, an unknown key
+ * also says which allowed key it most likely meant (`unknown key 'onFail' (did you mean ifFails?)`).
+ */
+export function contractIssues(error, where = {}) {
+    return error.issues.flatMap(issue => issuesOf(issue, where));
 }
 /** A Zod error as path-named lines: `steps[0].routes[0].goesTo: required`, `routes[0]: unknown key 'to'`. */
-export function contractError(error) {
-    return contractIssues(error).map(issue => issue.line);
+export function contractError(error, where = {}) {
+    return contractIssues(error, where).map(issue => issue.line);
+}
+/**
+ * A contract issue as a problem with a reason code built from its path — `missing-goal`, `criteria[0].how-too-long`,
+ * `checks-too-many`, `payload-unknown-key`, `bad-version`, `newer-version` — so callers that branch on a reason, and
+ * durable outcomes that recorded one, read the same as before the contract.
+ */
+export function contractProblemOf(issue) {
+    const at = issue.path;
+    const reason = (() => {
+        switch (issue.kind) {
+            case "required":
+            case "empty":
+            case "too-few":
+                return `missing-${at}`;
+            case "too-long":
+                return `${at}-too-long`;
+            case "too-many":
+                return `${at}-too-many`;
+            case "unknown-key":
+                return `${at}-unknown-key`;
+            case "newer-version":
+                return "newer-version";
+            default:
+                return `bad-${at}`;
+        }
+    })();
+    return { reason, message: issue.line };
 }
 /** Parse with the input reported, so a missing field reads `required` rather than a wrong type. */
-export function parseContract(schema, input) {
+export function parseContract(schema, input, options = {}) {
     const parsed = schema.safeParse(input, { reportInput: true });
-    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, issues: contractIssues(parsed.error) };
+    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, issues: contractIssues(parsed.error, { schema, input, options }) };
 }
 /**
  * Read a versioned payload. The current version parses as itself; an older known version (0 for a payload saved
  * before it carried `version`) is upgraded by its adapter and then parsed by the same schema; a newer version is
  * refused plainly; anything else is an unknown version.
  */
-export function readVersioned(schema, input, upgrades = {}) {
+export function readVersioned(schema, input, upgrades = {}, options = {}) {
     const current = schema.shape.version.value;
     if (typeof input !== "object" || input === null || Array.isArray(input)) {
         return { ok: false, issues: [{ path: "payload", kind: "wrong-type", line: `payload: must be an object (got ${got(input)})` }] };
@@ -97,7 +233,7 @@ export function readVersioned(schema, input, upgrades = {}) {
     const body = input;
     const version = Object.prototype.hasOwnProperty.call(body, "version") ? body["version"] : 0;
     if (version === current)
-        return parseContract(schema, body);
+        return parseContract(schema, body, options);
     if (typeof version === "number" && Number.isInteger(version) && version > current) {
         return { ok: false, issues: [{ path: "version", kind: "newer-version", line: `version: made by a newer Toolroll (version ${version}; this one reads up to ${current})` }] };
     }
@@ -105,7 +241,7 @@ export function readVersioned(schema, input, upgrades = {}) {
     if (upgrade === undefined) {
         return { ok: false, issues: [{ path: "version", kind: "bad-value", line: `version: unknown version ${JSON.stringify(version)} (this Toolroll reads ${current}${Object.keys(upgrades).length === 0 ? "" : ` and ${Object.keys(upgrades).join(", ")}`})` }] };
     }
-    return parseContract(schema, upgrade(body));
+    return parseContract(schema, upgrade(body), options);
 }
 /** The Zod node kinds a model-facing schema may use: each says exactly what its JSON Schema says. */
 const MODEL_FACING_TYPES = new Set(["string", "number", "int", "boolean", "null", "literal", "enum", "array", "object", "optional", "nullable", "union", "tuple", "record", "lazy", "readonly", "unknown", "any"]);

package/dist/contracts/decision.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A parked decision (§7): one schema for the question an agent puts to a person — its recap, the question, two to six
+ * options each saying whether it can be undone, and the option it recommends. Agents hand it back as a file (the park
+ * mailbox); `DECISION_MODEL_SCHEMA` is exported for the scout contract migration to wire into structured output.
+ * `parseDecision` (decision.ts) reads decisions through `readDecisionPayload`. The options are what the `decision`
+ * row keeps. The existing unversioned format ignores unknown fields, including a field named `version`.
+ *
+ * What JSON Schema cannot say runs after parsing, in decision.ts, each with a path-named error: text is not blank once
+ * trimmed, carries no control characters (a label or assignee is one line), option ids are unique, the recommendation
+ * names one of them, and a deadline is a timestamp.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many options fit on one screen, and the fewest that make a decision. */
+export declare const DECISION_OPTIONS_MIN = 2;
+export declare const DECISION_OPTIONS_MAX = 6;
+/** Option ids travel in URLs, CLI arguments, and CAS updates — they are identifiers, not prose. */
+export declare const OPTION_ID: RegExp;
+/** One option: its id, a one-line label, what choosing it does, and whether it can be undone (never defaulted). */
+export declare const decisionOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    consequence: z.ZodString;
+    reversible: z.ZodBoolean;
+}, z.core.$strip>;
+export type DecisionOption = z.infer<typeof decisionOptionSchema>;
+export declare const decisionSchema: z.ZodObject<{
+    urgency: z.ZodLiteral<"blocking">;
+    recap: z.ZodString;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        consequence: z.ZodString;
+        reversible: z.ZodBoolean;
+    }, z.core.$strip>>;
+    recommendation: z.ZodString;
+    assignee: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deadline: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DecisionPayload = z.infer<typeof decisionSchema>;
+/** The decision schema for the scout migration's question branch. */
+export declare const DECISION_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Read the existing decision format, ignoring keys it never used. */
+export declare function readDecisionPayload(input: unknown): ContractResult<DecisionPayload>;

package/dist/contracts/decision.js

@@ -0,0 +1,45 @@
+/**
+ * A parked decision (§7): one schema for the question an agent puts to a person — its recap, the question, two to six
+ * options each saying whether it can be undone, and the option it recommends. Agents hand it back as a file (the park
+ * mailbox); `DECISION_MODEL_SCHEMA` is exported for the scout contract migration to wire into structured output.
+ * `parseDecision` (decision.ts) reads decisions through `readDecisionPayload`. The options are what the `decision`
+ * row keeps. The existing unversioned format ignores unknown fields, including a field named `version`.
+ *
+ * What JSON Schema cannot say runs after parsing, in decision.ts, each with a path-named error: text is not blank once
+ * trimmed, carries no control characters (a label or assignee is one line), option ids are unique, the recommendation
+ * names one of them, and a deadline is a timestamp.
+ */
+import { z } from "zod";
+import { limited, parseContract, toModelSchema } from "./contract.js";
+/** How many options fit on one screen, and the fewest that make a decision. */
+export const DECISION_OPTIONS_MIN = 2;
+export const DECISION_OPTIONS_MAX = 6;
+/** Option ids travel in URLs, CLI arguments, and CAS updates — they are identifiers, not prose. */
+export const OPTION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** Decisions have no shorten turn: an over-long field is refused, so the model is not told it will be asked. */
+const NO_SHORTEN = { shorten: false };
+/** One option: its id, a one-line label, what choosing it does, and whether it can be undone (never defaulted). */
+export const decisionOptionSchema = z.object({
+    id: limited("option id", "decisionOptionId", NO_SHORTEN).regex(OPTION_ID, { error: "must be letters, digits, - or _, starting with a letter or digit" }),
+    label: limited("option label", "decisionLabel", NO_SHORTEN).min(1),
+    consequence: limited("option consequence", "decisionConsequence", NO_SHORTEN).min(1),
+    reversible: z.boolean(),
+});
+export const decisionSchema = z.object({
+    /** Required rather than defaulted: an agent that did not say whether the loop can continue has not composed a decision. */
+    urgency: z.literal("blocking"),
+    recap: limited("recap", "decisionRecap", NO_SHORTEN).min(1),
+    question: limited("question", "decisionQuestion", NO_SHORTEN).min(1),
+    options: z.array(decisionOptionSchema).min(DECISION_OPTIONS_MIN).max(DECISION_OPTIONS_MAX),
+    /** An option's id, alone or as "<id>: why". */
+    recommendation: limited("recommendation (an option's id, or \"<id>: why\")", "decisionRecommendation", NO_SHORTEN).min(1),
+    assignee: limited("assignee", "decisionAssignee", NO_SHORTEN).min(1).nullable().optional(),
+    /** An ISO 8601 timestamp. */
+    deadline: z.string().nullable().optional(),
+});
+/** The decision schema for the scout migration's question branch. */
+export const DECISION_MODEL_SCHEMA = toModelSchema(decisionSchema);
+/** Read the existing decision format, ignoring keys it never used. */
+export function readDecisionPayload(input) {
+    return parseContract(decisionSchema, input);
+}

package/dist/contracts/discord-callback.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A Discord button tap (discord-chat.ts `receiveDiscord`): the component interaction Discord sends over the gateway,
+ * and the button data Toolroll put on it. The interaction is Discord's, so fields Toolroll doesn't read are ignored;
+ * the button's `custom_id` (`so_` and a one-time token) is Toolroll's. A tap from the paired person on Toolroll's own
+ * message whose button can't be read is answered with why (`data.custom_id: not a Toolroll button`), and nothing is done.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** The interaction around a tap (type 3: a message component): the app, the person, the channel, the message. */
+export declare const discordComponentInteractionSchema: z.ZodObject<{
+    type: z.ZodLiteral<3>;
+    id: z.ZodString;
+    application_id: z.ZodString;
+    channel_id: z.ZodString;
+    guild_id: z.ZodOptional<z.ZodString>;
+    channel: z.ZodObject<{
+        type: z.ZodInt;
+    }, z.core.$strip>;
+    member: z.ZodOptional<z.ZodObject<{
+        user: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    user: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    message: z.ZodObject<{
+        id: z.ZodString;
+        channel_id: z.ZodString;
+        author: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    data: z.ZodObject<{
+        custom_id: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DiscordComponentInteraction = z.infer<typeof discordComponentInteractionSchema>;
+/** Toolroll's button data: `so_` and a one-time token. */
+export declare const discordButtonSchema: z.ZodObject<{
+    custom_id: z.ZodString;
+}, z.core.$strip>;
+export declare function readDiscordComponentInteraction(body: unknown): ContractResult<DiscordComponentInteraction>;
+/** The tapped button's one-time token. */
+export declare function readDiscordButtonToken(interaction: DiscordComponentInteraction): ContractResult<string>;

package/dist/contracts/discord-callback.js

@@ -0,0 +1,34 @@
+/**
+ * A Discord button tap (discord-chat.ts `receiveDiscord`): the component interaction Discord sends over the gateway,
+ * and the button data Toolroll put on it. The interaction is Discord's, so fields Toolroll doesn't read are ignored;
+ * the button's `custom_id` (`so_` and a one-time token) is Toolroll's. A tap from the paired person on Toolroll's own
+ * message whose button can't be read is answered with why (`data.custom_id: not a Toolroll button`), and nothing is done.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+const user = z.object({ id: z.string() });
+/** The interaction around a tap (type 3: a message component): the app, the person, the channel, the message. */
+export const discordComponentInteractionSchema = z.object({
+    type: z.literal(3),
+    id: z.string(),
+    application_id: z.string(),
+    channel_id: z.string(),
+    guild_id: z.string().optional(),
+    channel: z.object({ type: z.int() }),
+    member: z.object({ user }).optional(),
+    user: user.optional(),
+    message: z.object({ id: z.string(), channel_id: z.string(), author: user }),
+    data: z.object({ custom_id: z.unknown().optional() }),
+});
+/** Toolroll's button data: `so_` and a one-time token. */
+export const discordButtonSchema = z.object({
+    custom_id: z.string().regex(/^so_[a-f0-9]{32}$/, { error: "not a Toolroll button" }),
+});
+export function readDiscordComponentInteraction(body) {
+    return parseContract(discordComponentInteractionSchema, body);
+}
+/** The tapped button's one-time token. */
+export function readDiscordButtonToken(interaction) {
+    const read = parseContract(z.object({ data: discordButtonSchema }), { data: interaction.data });
+    return read.ok ? { ok: true, value: read.value.data.custom_id.slice(3) } : read;
+}

package/dist/contracts/flow-card.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A flow card's state (docs/plans/zod-revamp.md, item 8): what the flow engine, its steps and its Send to me and
+ * Person chooses zones read and write (flow-engine.ts, flow-steps.ts, flow-send.ts), as the store keeps it in
+ * `flow_card`. Its columns are versioned by the database's own schema version; the one payload in it, what finished
+ * zones handed on (`outputs_json`), carries its own version (stage-output.ts).
+ *
+ * `flowCardSchema` is the card as read; `flowCardChangeSchema` what one update may change. Where it came from
+ * (`source_json`, written by triggers) keeps its own type in the store.
+ */
+import { z } from "zod";
+export declare const FLOW_CARD_STATES: readonly ["active", "done", "cancelled"];
+export type FlowCardState = (typeof FLOW_CARD_STATES)[number];
+export declare const flowCardSchema: z.ZodObject<{
+    id: z.ZodInt;
+    flow: z.ZodInt;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    stage: z.ZodString;
+    entry: z.ZodInt;
+    state: z.ZodEnum<{
+        active: "active";
+        cancelled: "cancelled";
+        done: "done";
+    }>;
+    task: z.ZodNullable<z.ZodString>;
+    primaryTask: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+    waiting: z.ZodNullable<z.ZodString>;
+    outputs: z.ZodObject<{}, z.core.$catchall<z.ZodString>>;
+    attached: z.ZodObject<{}, z.core.$catchall<z.ZodString>>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    owner: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FlowCardFields = z.infer<typeof flowCardSchema>;
+/** What one update of a card may change; whatever is left out stays as it is. Outputs replace the card's whole;
+ * an attachment goes with the output it belongs to. */
+export declare const flowCardChangeSchema: z.ZodObject<{
+    task: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    primaryTask: z.ZodOptional<z.ZodString>;
+    waiting: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    outputs: z.ZodOptional<z.ZodObject<{}, z.core.$catchall<z.ZodString>>>;
+    attached: z.ZodOptional<z.ZodObject<{}, z.core.$catchall<z.ZodString>>>;
+    state: z.ZodOptional<z.ZodEnum<{
+        cancelled: "cancelled";
+        done: "done";
+    }>>;
+}, z.core.$strict>;
+export type FlowCardChange = z.infer<typeof flowCardChangeSchema>;

package/dist/contracts/flow-card.js

@@ -0,0 +1,46 @@
+/**
+ * A flow card's state (docs/plans/zod-revamp.md, item 8): what the flow engine, its steps and its Send to me and
+ * Person chooses zones read and write (flow-engine.ts, flow-steps.ts, flow-send.ts), as the store keeps it in
+ * `flow_card`. Its columns are versioned by the database's own schema version; the one payload in it, what finished
+ * zones handed on (`outputs_json`), carries its own version (stage-output.ts).
+ *
+ * `flowCardSchema` is the card as read; `flowCardChangeSchema` what one update may change. Where it came from
+ * (`source_json`, written by triggers) keeps its own type in the store.
+ */
+import { z } from "zod";
+import { cardOutputsSchema } from "./stage-output.js";
+export const FLOW_CARD_STATES = ["active", "done", "cancelled"];
+export const flowCardSchema = z.strictObject({
+    id: z.int().min(1),
+    flow: z.int().min(1),
+    title: z.string(),
+    description: z.string().nullable(),
+    /** The zone it is in, and which visit to that zone this is (each move is a fresh one). */
+    stage: z.string(),
+    entry: z.int().min(1),
+    state: z.enum(FLOW_CARD_STATES),
+    /** The task its zone filed this visit, and the card's main build. */
+    task: z.string().nullable(),
+    primaryTask: z.string().nullable(),
+    /** The latest note it was sent back or replied to with ({{note}}). */
+    note: z.string().nullable(),
+    /** What it waits for, in words. */
+    waiting: z.string().nullable(),
+    /** What finished zones handed on ({{stage.…}}), and any too long to pass on, whole. */
+    outputs: cardOutputsSchema.shape.outputs,
+    attached: cardOutputsSchema.shape.attached,
+    createdBy: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    owner: z.string().nullable(),
+});
+/** What one update of a card may change; whatever is left out stays as it is. Outputs replace the card's whole;
+ * an attachment goes with the output it belongs to. */
+export const flowCardChangeSchema = z.strictObject({
+    task: flowCardSchema.shape.task.optional(),
+    primaryTask: z.string().optional(),
+    waiting: flowCardSchema.shape.waiting.optional(),
+    outputs: flowCardSchema.shape.outputs.optional(),
+    attached: flowCardSchema.shape.attached.optional(),
+    state: z.enum(["done", "cancelled"]).optional(),
+});