toolroll 0.9.34 → 0.9.37

package/dist/contracts/chat-callback-rows.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The saved side of a chat button: the row its one-time token names. A proposal card's buttons in Slack, Discord and
+ * Teams (`chat_action`, read with the part and event it rides) and a result's, plan's, failure's or pull request's own
+ * buttons (`chat_decide_action`, chat-decide.ts). SQLite's own CHECKs bound them when written; these say what a
+ * reader may rely on, so a row that isn't that is refused by column, never read as a guess.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** A proposal card's button (chat-delivery.ts), with the part's message and the event's binding, channel and thread. */
+export declare const proposalActionRowSchema: z.ZodObject<{
+    token: z.ZodString;
+    part: z.ZodInt;
+    proposal: z.ZodInt;
+    phase: z.ZodEnum<{
+        cancel: "cancel";
+        confirm: "confirm";
+        dismiss: "dismiss";
+        yes: "yes";
+    }>;
+    expires: z.ZodString;
+    consumed: z.ZodNullable<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+    binding: z.ZodNullable<z.ZodInt>;
+    channel: z.ZodString;
+    thread: z.ZodString;
+}, z.core.$strict>;
+export type ProposalActionRow = z.infer<typeof proposalActionRowSchema>;
+export declare function readProposalActionRow(row: unknown): ContractResult<ProposalActionRow>;
+export declare const DECIDE_ACTS: readonly ["accept", "changes", "retry", "approve", "not-now", "merge"];
+export declare const DECIDE_PHASES: readonly ["offer", "yes", "cancel"];
+/** A decide button (chat-decide.ts): who and where it was sent, what it does to which task and run, and the stamp it holds. */
+export declare const decideActionRowSchema: z.ZodObject<{
+    token: z.ZodString;
+    channel: z.ZodString;
+    binding: z.ZodInt;
+    chat: z.ZodString;
+    message: z.ZodNullable<z.ZodString>;
+    act: z.ZodEnum<{
+        accept: "accept";
+        approve: "approve";
+        changes: "changes";
+        merge: "merge";
+        "not-now": "not-now";
+        retry: "retry";
+    }>;
+    phase: z.ZodEnum<{
+        cancel: "cancel";
+        offer: "offer";
+        yes: "yes";
+    }>;
+    task_id: z.ZodString;
+    run: z.ZodNullable<z.ZodInt>;
+    digest: z.ZodString;
+    created_at: z.ZodString;
+    expires_at: z.ZodString;
+    consumed_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type DecideActionRow = z.infer<typeof decideActionRowSchema>;
+export declare function readDecideActionRow(row: unknown): ContractResult<DecideActionRow>;

package/dist/contracts/chat-callback-rows.js

@@ -0,0 +1,46 @@
+/**
+ * The saved side of a chat button: the row its one-time token names. A proposal card's buttons in Slack, Discord and
+ * Teams (`chat_action`, read with the part and event it rides) and a result's, plan's, failure's or pull request's own
+ * buttons (`chat_decide_action`, chat-decide.ts). SQLite's own CHECKs bound them when written; these say what a
+ * reader may rely on, so a row that isn't that is refused by column, never read as a guess.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+const when = z.string();
+/** A proposal card's button (chat-delivery.ts), with the part's message and the event's binding, channel and thread. */
+export const proposalActionRowSchema = z.strictObject({
+    token: z.string(),
+    part: z.int(),
+    proposal: z.int(),
+    phase: z.enum(["confirm", "dismiss", "yes", "cancel"]),
+    expires: when,
+    consumed: when.nullable(),
+    message: z.string().nullable(),
+    binding: z.int().nullable(),
+    channel: z.string(),
+    thread: z.string(),
+});
+export function readProposalActionRow(row) {
+    return parseContract(proposalActionRowSchema, row);
+}
+export const DECIDE_ACTS = ["accept", "changes", "retry", "approve", "not-now", "merge"];
+export const DECIDE_PHASES = ["offer", "yes", "cancel"];
+/** A decide button (chat-decide.ts): who and where it was sent, what it does to which task and run, and the stamp it holds. */
+export const decideActionRowSchema = z.strictObject({
+    token: z.string().regex(/^d:[a-f0-9]{24}$/),
+    channel: z.string(),
+    binding: z.int(),
+    chat: z.string(),
+    message: z.string().nullable(),
+    act: z.enum(DECIDE_ACTS),
+    phase: z.enum(DECIDE_PHASES),
+    task_id: z.string(),
+    run: z.int().nullable(),
+    digest: z.string(),
+    created_at: when,
+    expires_at: when,
+    consumed_at: when.nullable(),
+});
+export function readDecideActionRow(row) {
+    return parseContract(decideActionRowSchema, row);
+}

package/dist/contracts/chat-content.d.ts

@@ -0,0 +1,276 @@
+/**
+ * What Slack, Discord and Teams keep between steps (chat-delivery-state.ts): one schema for a received event's body
+ * (`chat_event.payload`, by the event's kind) and one for a planned message part (`chat_part.payload`), the message a
+ * button rides and the content a delivery repaints. Both are saved with `version`; a body or part saved before they
+ * carried one reads as it did then (its known fields; a reader then passed any others by unread).
+ *
+ * An event body lives only until the event is handled (then it is `{}`); a part lives as long as its message.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** One planned message part, as delivery reads it. */
+export declare const chatContentShape: {
+    text: z.ZodString;
+    /** Where the part is sent when not the binding's own DM: a room's channel. */
+    channel: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodInt>;
+    image: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+        artifact: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    /** A screenshot sent with a result (result-shots.ts): it follows that result's message part, in its thread when
+     * the app allows; a refused upload becomes one plain line, and one removed by retention goes quietly. */
+    shot: z.ZodOptional<z.ZodObject<{
+        follows: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    task: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodInt>;
+    edit: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodLiteral<"armed">>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
+    also: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    /** A flow decision's buttons ride this part (v88): minted when it is planned. */
+    flow: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        actions: z.ZodArray<z.ZodEnum<{
+            approve: "approve";
+            edit: "edit";
+            "send-back": "send-back";
+        }>>;
+    }, z.core.$strict>>;
+    /** A flow's "Person chooses" buttons ride this part: minted when it is planned. */
+    choose: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        options: z.ZodArray<z.ZodObject<{
+            choice: z.ZodInt;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    /** "Use this as your note?" Yes / No about the person's message `held` (an event id), for one choice's visit. */
+    note: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        held: z.ZodString;
+    }, z.core.$strict>>;
+    /** A teammate's question's buttons ride this part (v93): each option, then one to answer in words (choice null). */
+    question: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        choices: z.ZodArray<z.ZodObject<{
+            choice: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    /** The lead's question to its owner rides this part: its options, then "Something else". */
+    ask: z.ZodOptional<z.ZodObject<{
+        turn: z.ZodInt;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    /** The lead's own reply, already shaped (reply-shape.ts): the channel renders its bold anchors and labelled links in its own format. */
+    voice: z.ZodOptional<z.ZodLiteral<true>>;
+};
+export declare const chatContentSchema: z.ZodObject<{
+    text: z.ZodString;
+    channel: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodInt>;
+    image: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+        artifact: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    shot: z.ZodOptional<z.ZodObject<{
+        follows: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    task: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodInt>;
+    edit: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodLiteral<"armed">>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    also: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    flow: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        actions: z.ZodArray<z.ZodEnum<{
+            approve: "approve";
+            edit: "edit";
+            "send-back": "send-back";
+        }>>;
+    }, z.core.$strict>>;
+    choose: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        options: z.ZodArray<z.ZodObject<{
+            choice: z.ZodInt;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    note: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        held: z.ZodString;
+    }, z.core.$strict>>;
+    question: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        choices: z.ZodArray<z.ZodObject<{
+            choice: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    ask: z.ZodOptional<z.ZodObject<{
+        turn: z.ZodInt;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    voice: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type ChatContent = z.infer<typeof chatContentSchema>;
+export declare const CHAT_PART_VERSION = 1;
+export declare const savedChatPartSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    text: z.ZodString;
+    channel: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodInt>;
+    image: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+        artifact: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    shot: z.ZodOptional<z.ZodObject<{
+        follows: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    task: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodInt>;
+    edit: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodLiteral<"armed">>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    also: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    flow: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        actions: z.ZodArray<z.ZodEnum<{
+            approve: "approve";
+            edit: "edit";
+            "send-back": "send-back";
+        }>>;
+    }, z.core.$strict>>;
+    choose: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        options: z.ZodArray<z.ZodObject<{
+            choice: z.ZodInt;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    note: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        held: z.ZodString;
+    }, z.core.$strict>>;
+    question: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        choices: z.ZodArray<z.ZodObject<{
+            choice: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    ask: z.ZodOptional<z.ZodObject<{
+        turn: z.ZodInt;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    voice: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/** A saved part's content (`version` is the saved form's, not the content's). */
+export declare function readChatPart(raw: string): ContractResult<ChatContent>;
+/** A part as it is saved. */
+export declare function savedChatPart(content: ChatContent): string;
+export declare const CHAT_EVENT_VERSION = 1;
+/** `pair <code>`: only the code's hash is kept. */
+export declare const chatPairBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    hash: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A message: its words (cut at the lead's limit, `originalLength` saying how long it was), or a plain line to answer
+ * with instead (`unsupported`: a file the app can't take). A room's or notice's carrier event has none. `about` is the
+ * task its turn is about, once chosen; `lead` is a held message passed to the lead as it was (chat-flow.ts).
+ */
+export declare const chatMessageBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    text: z.ZodOptional<z.ZodString>;
+    originalLength: z.ZodOptional<z.ZodInt>;
+    unsupported: z.ZodOptional<z.ZodString>;
+    about: z.ZodOptional<z.ZodObject<{
+        task: z.ZodString;
+        run: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    lead: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/**
+ * A button: the one-time token it carried, or, when the app's callback came from the paired person but its data
+ * couldn't be read, the path-named line saying why — answered plainly, and nothing is done.
+ */
+export declare const chatTokenBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    token: z.ZodString;
+}, z.core.$strict>;
+export declare const chatProblemBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    problem: z.ZodString;
+}, z.core.$strict>;
+export declare const chatActionBodySchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    token: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    problem: z.ZodString;
+}, z.core.$strict>]>;
+/** A notice carries its parts, not a body. */
+export declare const chatNoticeBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export type ChatPairBody = z.infer<typeof chatPairBodySchema>;
+export type ChatMessageBody = z.infer<typeof chatMessageBodySchema>;
+export type ChatActionBody = z.infer<typeof chatActionBodySchema>;
+/** What a writer hands `ChatState.enqueue`: a body of the event's kind, without `version` (it is stamped on saving). */
+export type ChatEventBody = Omit<ChatPairBody, "version"> | Omit<ChatMessageBody, "version"> | {
+    token: string;
+} | {
+    problem: string;
+} | Record<string, never>;
+export declare function savedChatEventBody(body: ChatEventBody): string;
+/** A pair event's body. */
+export declare function readChatPairBody(raw: string): ContractResult<ChatPairBody>;
+/** A message event's body. */
+export declare function readChatMessageBody(raw: string): ContractResult<ChatMessageBody>;
+/** An action event's body: a token, or the reason its callback couldn't be read. */
+export declare function readChatActionBody(raw: string): ContractResult<ChatActionBody>;
+/** Words held for "Use this as your note?" (`chat_flow_note.words`): the held message's own text and length. */
+export declare const heldWordsSchema: z.ZodObject<{
+    text: z.ZodString;
+    originalLength: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+export type HeldWords = z.infer<typeof heldWordsSchema>;
+export declare function readHeldWords(raw: string): ContractResult<HeldWords>;

package/dist/contracts/chat-content.js

@@ -0,0 +1,127 @@
+/**
+ * What Slack, Discord and Teams keep between steps (chat-delivery-state.ts): one schema for a received event's body
+ * (`chat_event.payload`, by the event's kind) and one for a planned message part (`chat_part.payload`), the message a
+ * button rides and the content a delivery repaints. Both are saved with `version`; a body or part saved before they
+ * carried one reads as it did then (its known fields; a reader then passed any others by unread).
+ *
+ * An event body lives only until the event is handled (then it is `{}`); a part lives as long as its message.
+ */
+import { z } from "zod";
+import { parseContract, readVersioned, versioned } from "./contract.js";
+const id = z.int().min(1);
+const link = z.strictObject({ label: z.string(), path: z.string() });
+/** One planned message part, as delivery reads it. */
+export const chatContentShape = {
+    text: z.string(),
+    /** Where the part is sent when not the binding's own DM: a room's channel. */
+    channel: z.string().optional(),
+    proposal: id.optional(),
+    image: z.strictObject({ taskId: z.string(), run: z.int(), artifact: z.int(), sha256: z.string() }).optional(),
+    /** A screenshot sent with a result (result-shots.ts): it follows that result's message part, in its thread when
+     * the app allows; a refused upload becomes one plain line, and one removed by retention goes quietly. */
+    shot: z.strictObject({ follows: z.int().nullable() }).optional(),
+    task: z.string().optional(),
+    run: z.int().optional(),
+    edit: z.string().optional(),
+    phase: z.literal("armed").optional(),
+    link: link.optional(),
+    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
+    also: z.array(link).optional(),
+    /** A flow decision's buttons ride this part (v88): minted when it is planned. */
+    flow: z.strictObject({ card: id, entry: z.int(), actions: z.array(z.enum(["approve", "edit", "send-back"])) }).optional(),
+    /** A flow's "Person chooses" buttons ride this part: minted when it is planned. */
+    choose: z.strictObject({ card: id, entry: z.int(), options: z.array(z.strictObject({ choice: z.int(), label: z.string() })) }).optional(),
+    /** "Use this as your note?" Yes / No about the person's message `held` (an event id), for one choice's visit. */
+    note: z.strictObject({ card: id, entry: z.int(), held: z.string() }).optional(),
+    /** A teammate's question's buttons ride this part (v93): each option, then one to answer in words (choice null). */
+    question: z.strictObject({ id, choices: z.array(z.strictObject({ choice: z.string().nullable(), label: z.string() })) }).optional(),
+    /** The lead's question to its owner rides this part: its options, then "Something else". */
+    ask: z.strictObject({ turn: id, options: z.array(z.string()) }).optional(),
+    /** The lead's own reply, already shaped (reply-shape.ts): the channel renders its bold anchors and labelled links in its own format. */
+    voice: z.literal(true).optional(),
+};
+export const chatContentSchema = z.strictObject(chatContentShape);
+export const CHAT_PART_VERSION = 1;
+export const savedChatPartSchema = versioned(CHAT_PART_VERSION, chatContentShape);
+/** A saved body or part from before `version`, as version `version`: the fields its schema knows, nothing else. */
+function knownFields(version, fields) {
+    return (body) => {
+        const out = { version };
+        for (const field of fields)
+            if (Object.hasOwn(body, field))
+                out[field] = body[field];
+        return out;
+    };
+}
+const PART_UPGRADES = { 0: knownFields(CHAT_PART_VERSION, Object.keys(chatContentShape)) };
+/** JSON text, then the schema; `payload: not JSON` for bytes that aren't. */
+function fromJson(raw, read) {
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "invalid", line: "payload: not JSON" }] };
+    }
+    return read(body);
+}
+/** A saved part's content (`version` is the saved form's, not the content's). */
+export function readChatPart(raw) {
+    const read = fromJson(raw, body => readVersioned(savedChatPartSchema, body, PART_UPGRADES));
+    if (!read.ok)
+        return read;
+    const { version: _version, ...content } = read.value;
+    return { ok: true, value: content };
+}
+/** A part as it is saved. */
+export function savedChatPart(content) {
+    return JSON.stringify({ version: CHAT_PART_VERSION, ...content });
+}
+// ---- event bodies ------------------------------------------------------------------------------------------------
+export const CHAT_EVENT_VERSION = 1;
+/** `pair <code>`: only the code's hash is kept. */
+export const chatPairBodySchema = versioned(CHAT_EVENT_VERSION, { hash: z.string() });
+/**
+ * A message: its words (cut at the lead's limit, `originalLength` saying how long it was), or a plain line to answer
+ * with instead (`unsupported`: a file the app can't take). A room's or notice's carrier event has none. `about` is the
+ * task its turn is about, once chosen; `lead` is a held message passed to the lead as it was (chat-flow.ts).
+ */
+export const chatMessageBodySchema = versioned(CHAT_EVENT_VERSION, {
+    text: z.string().optional(),
+    originalLength: z.int().min(0).optional(),
+    unsupported: z.string().optional(),
+    about: z.strictObject({ task: z.string(), run: z.int().nullable() }).optional(),
+    lead: z.literal(true).optional(),
+});
+/**
+ * A button: the one-time token it carried, or, when the app's callback came from the paired person but its data
+ * couldn't be read, the path-named line saying why — answered plainly, and nothing is done.
+ */
+export const chatTokenBodySchema = versioned(CHAT_EVENT_VERSION, { token: z.string().regex(/^[a-f0-9]{32}$/, { error: "must be a Toolroll button token" }) });
+export const chatProblemBodySchema = versioned(CHAT_EVENT_VERSION, { problem: z.string().min(1) });
+export const chatActionBodySchema = z.union([chatTokenBodySchema, chatProblemBodySchema]);
+/** A notice carries its parts, not a body. */
+export const chatNoticeBodySchema = versioned(CHAT_EVENT_VERSION, {});
+export function savedChatEventBody(body) {
+    return JSON.stringify({ version: CHAT_EVENT_VERSION, ...body });
+}
+const upgradeBody = (fields) => ({ 0: knownFields(CHAT_EVENT_VERSION, fields) });
+/** A pair event's body. */
+export function readChatPairBody(raw) {
+    return fromJson(raw, body => readVersioned(chatPairBodySchema, body, upgradeBody(["hash"])));
+}
+/** A message event's body. */
+export function readChatMessageBody(raw) {
+    return fromJson(raw, body => readVersioned(chatMessageBodySchema, body, upgradeBody(Object.keys(chatMessageBodySchema.shape))));
+}
+/** An action event's body: a token, or the reason its callback couldn't be read. */
+export function readChatActionBody(raw) {
+    return fromJson(raw, (body) => typeof body === "object" && body !== null && !Array.isArray(body) && Object.hasOwn(body, "problem")
+        ? readVersioned(chatProblemBodySchema, body, upgradeBody(["problem"]))
+        : readVersioned(chatTokenBodySchema, body, upgradeBody(["token"])));
+}
+/** Words held for "Use this as your note?" (`chat_flow_note.words`): the held message's own text and length. */
+export const heldWordsSchema = z.strictObject({ text: z.string(), originalLength: z.int().min(0).optional() });
+export function readHeldWords(raw) {
+    return fromJson(raw, body => parseContract(heldWordsSchema, body));
+}

package/dist/contracts/chat-tables.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The Slack, Discord and Teams receipt tables (chat-delivery-state.ts keeps their rows). A leaf: it imports nothing, so
+ * the store can create these tables without loading the chat state modules that themselves import the store.
+ */
+export declare const chatSchema: (channel: "slack" | "discord" | "teams") => string;
+export declare const chatTables: (channel: "slack" | "discord" | "teams") => string[];

package/dist/contracts/chat-tables.js

@@ -0,0 +1,136 @@
+/**
+ * The Slack, Discord and Teams receipt tables (chat-delivery-state.ts keeps their rows). A leaf: it imports nothing, so
+ * the store can create these tables without loading the chat state modules that themselves import the store.
+ */
+const CHAT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_binding (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, installation TEXT NOT NULL,
+ team TEXT NOT NULL, app TEXT NOT NULL, member TEXT NOT NULL, channel TEXT NOT NULL,
+ approver TEXT NOT NULL, generation INTEGER NOT NULL, created TEXT NOT NULL, revoked TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS chat_one_binding_member ON chat_binding(installation, member) WHERE revoked IS NULL;
+CREATE TABLE IF NOT EXISTS chat_pair (
+ hash TEXT PRIMARY KEY, installation TEXT NOT NULL, approver TEXT NOT NULL,
+ generation INTEGER NOT NULL, expires TEXT NOT NULL, consumed TEXT
+);
+CREATE TABLE IF NOT EXISTS chat_event (
+ id TEXT PRIMARY KEY, installation TEXT NOT NULL, binding INTEGER REFERENCES chat_binding(id),
+ kind TEXT NOT NULL CHECK(kind IN ('message','action','pair','notice')),
+ channel TEXT NOT NULL, member TEXT NOT NULL, ts TEXT NOT NULL, thread TEXT NOT NULL,
+ payload TEXT NOT NULL, created TEXT NOT NULL,
+ session INTEGER REFERENCES mate_session(id), state TEXT NOT NULL DEFAULT 'queued' CHECK(state IN ('queued','done','dropped')),
+ next_at TEXT, problem TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_pending_event ON chat_event(installation,state,next_at);
+CREATE TABLE IF NOT EXISTS chat_part (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, event TEXT NOT NULL REFERENCES chat_event(id), ordinal INTEGER NOT NULL,
+ payload TEXT NOT NULL, state TEXT NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','sent','dropped')),
+ message TEXT, file TEXT, uploaded INTEGER NOT NULL DEFAULT 0, attempts INTEGER NOT NULL DEFAULT 0,
+ uncertain INTEGER NOT NULL DEFAULT 0, next_at TEXT, problem TEXT, created TEXT NOT NULL,
+ UNIQUE(event,ordinal)
+);
+CREATE TABLE IF NOT EXISTS chat_action (
+ token TEXT PRIMARY KEY, part INTEGER NOT NULL REFERENCES chat_part(id),
+ proposal INTEGER NOT NULL REFERENCES mate_proposal(id), phase TEXT NOT NULL CHECK(phase IN ('confirm','dismiss','yes','cancel')),
+ expires TEXT NOT NULL, consumed TEXT
+);
+CREATE TABLE IF NOT EXISTS chat_progress (
+ binding INTEGER NOT NULL REFERENCES chat_binding(id), run INTEGER NOT NULL REFERENCES run(id),
+ part INTEGER NOT NULL REFERENCES chat_part(id), digest TEXT NOT NULL,
+ PRIMARY KEY(binding,run)
+);
+CREATE TABLE IF NOT EXISTS chat_runtime (
+ installation TEXT PRIMARY KEY, owner TEXT, lease_until TEXT, connected TEXT,
+ problem TEXT, retry_at TEXT, notification INTEGER NOT NULL DEFAULT 0
+);
+`;
+/** v73: a chat's place in the shared team conversations — a channel follows one
+ * conversation, a DM may select one. Rows are revoked, never deleted. */
+const CHAT_ROOM_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_room (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, installation TEXT NOT NULL, chat TEXT NOT NULL,
+ kind TEXT NOT NULL CHECK(kind IN ('group','private')), conversation TEXT NOT NULL,
+ binding INTEGER NOT NULL REFERENCES chat_binding(id),
+ bound_by TEXT NOT NULL, bound TEXT NOT NULL, cursor INTEGER NOT NULL DEFAULT 0,
+ revoked TEXT, revoked_by TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS chat_room_live ON chat_room(installation, chat) WHERE revoked IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS chat_room_group ON chat_room(conversation) WHERE revoked IS NULL AND kind='group';
+CREATE TABLE IF NOT EXISTS chat_meta (
+ installation TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, updated TEXT NOT NULL,
+ PRIMARY KEY(installation, key)
+);
+`;
+/** v88: flow decisions in the chat app, as on Telegram (telegram-flow.ts).
+ * A button is one opaque token for one visit (card, entry) of one card, on
+ * the part it rides; Edit and Send back open a prompt the person's next
+ * message in their DM answers. */
+const CHAT_FLOW_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_flow_action (
+ token TEXT PRIMARY KEY, part INTEGER NOT NULL REFERENCES chat_part(id),
+ card INTEGER NOT NULL REFERENCES flow_card(id), entry INTEGER NOT NULL,
+ action TEXT NOT NULL CHECK(action IN ('approve','edit','send-back')), expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_flow_action_visit ON chat_flow_action(card, entry);
+CREATE TABLE IF NOT EXISTS chat_flow_prompt (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, binding INTEGER NOT NULL REFERENCES chat_binding(id),
+ card INTEGER NOT NULL REFERENCES flow_card(id), entry INTEGER NOT NULL,
+ mode TEXT NOT NULL CHECK(mode IN ('edit','send-back')), created TEXT NOT NULL, expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_flow_prompt_open ON chat_flow_prompt(binding, consumed);
+`;
+/** A flow's "Person chooses" zone in the chat app (flow-send.ts): one button per option (choice is its index, label its words
+ * when sent) for one visit of one card, on the part it rides. A reply in that notice's thread is the note; chat_flow_note
+ * is "Use this as your note?" Yes / No about one other message (held: its event; words: what it said, kept only until
+ * answered, as an event's own payload is cleared once it is handled), asked once per visit.
+ * Never in CHAT_TABLES: an older database has no such table until this schema creates it. */
+const CHAT_FLOW_CHOICE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_flow_choice (
+ token TEXT PRIMARY KEY, part INTEGER NOT NULL REFERENCES chat_part(id),
+ card INTEGER NOT NULL REFERENCES flow_card(id), entry INTEGER NOT NULL,
+ choice INTEGER NOT NULL, label TEXT NOT NULL, expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_flow_choice_visit ON chat_flow_choice(card, entry);
+CREATE TABLE IF NOT EXISTS chat_flow_note (
+ token TEXT PRIMARY KEY, part INTEGER NOT NULL REFERENCES chat_part(id),
+ card INTEGER NOT NULL REFERENCES flow_card(id), entry INTEGER NOT NULL,
+ held TEXT NOT NULL, words TEXT, answer TEXT NOT NULL CHECK(answer IN ('yes','no')), expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_flow_note_visit ON chat_flow_note(card, entry);
+`;
+/** v93: a teammate's question in the chat app. One button per option (choice)
+ * and one to answer in words (choice NULL); that one opens a prompt the
+ * person's next message in their DM answers. Never in CHAT_TABLES: an older
+ * database has no such tables until this schema creates them. */
+const CHAT_QUESTION_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_question_action (
+ token TEXT PRIMARY KEY, part INTEGER NOT NULL REFERENCES chat_part(id),
+ question INTEGER NOT NULL REFERENCES teammate_question(id), choice TEXT, expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_question_action_question ON chat_question_action(question);
+CREATE TABLE IF NOT EXISTS chat_question_prompt (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, binding INTEGER NOT NULL REFERENCES chat_binding(id),
+ question INTEGER NOT NULL REFERENCES teammate_question(id), created TEXT NOT NULL, expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_question_prompt_open ON chat_question_prompt(binding, consumed);
+`;
+/** The lead's question to its owner (ask_owner) in the chat app: one button per option (choice is its index) and one for
+ * "Something else" (choice NULL). A tap sends the option as the owner's next message. Never in CHAT_TABLES. */
+const CHAT_ASK_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_ask_action (
+ token TEXT PRIMARY KEY, part INTEGER NOT NULL REFERENCES chat_part(id) ON DELETE CASCADE,
+ turn INTEGER NOT NULL, choice INTEGER, expires TEXT NOT NULL, consumed TEXT
+);
+CREATE INDEX IF NOT EXISTS chat_ask_action_turn ON chat_ask_action(turn);
+`;
+const CHAT_TABLES = [
+    "chat_binding",
+    "chat_pair",
+    "chat_event",
+    "chat_part",
+    "chat_action",
+    "chat_progress",
+    "chat_runtime",
+];
+export const chatSchema = (channel) => (CHAT_SCHEMA + CHAT_ROOM_SCHEMA + CHAT_FLOW_SCHEMA + CHAT_FLOW_CHOICE_SCHEMA + CHAT_QUESTION_SCHEMA + CHAT_ASK_SCHEMA).replaceAll("chat_", `${channel}_`);
+export const chatTables = (channel) => CHAT_TABLES.map((name) => name.replace("chat_", `${channel}_`));