toolroll 0.9.34 → 0.9.37

package/dist/demo.js

@@ -38,6 +38,7 @@ import { fileTaskProposal, fileRoutineProposal } from "./proposal.js";
 import { storeEvidence, budgetedStatJson, imageDimensions } from "./evidence.js";
 import { parseProof, adjudicate } from "./proof.js";
 import { sealVerificationReceipt } from "./verification-evidence.js";
+import { HANDOFF_VERSION, readHandoffArtifact } from "./contracts/handoff.js";
 import { parseExecutionPlanDocument, milestonesOf } from "./plan.js";
 import { maybeTriggerRepair } from "./dispose.js";
 import { deflateSync } from "node:zlib";
@@ -84,8 +85,21 @@ index 11aa0b2..c44d1f7 100644
 +    expect(settle(1005, 0.031)).toBe(31.16);
 +  });
 `;
+/** A demo run's handoff artifact: the run's own identity around the story's conclusion and lists, written through
+ * the handoff schema like a real one. */
+function demoHandoffBytes(store, runId, told) {
+    const run = store.getRun(runId);
+    const head = run.headRevision ?? run.baseRevision ?? "0".repeat(40);
+    const read = readHandoffArtifact({
+        version: HANDOFF_VERSION, taskId: store.externalIdFor(run.taskRef) ?? String(run.taskRef), runId, provider: run.provider,
+        sessionId: null, branch: run.branch ?? "", worktree: run.worktree ?? "", base: run.baseRevision ?? head, head, ...told,
+        freshness: { stampedAt: run.startedAt, currentAsOf: head },
+    });
+    if (!read.ok)
+        throw new Error(`demo handoff: ${read.issues.map(issue => issue.line).join("; ")}`);
+    return Buffer.from(JSON.stringify(read.value, null, 2), "utf8");
+}
 const DEMO_HANDOFF = {
-    schema: 1,
     outcome: "built",
     committed: true,
     conclusion: "Fixed the payout rounding drift: settle() now rounds at cent precision instead of accumulating half-cent errors. Added boundary tests against the ledger fixtures. All 214 tests pass.",
@@ -123,7 +137,6 @@ index 2b3c4d5..8e9f0a1 100644
  };
 `;
 const DEMO_FAILED_HANDOFF = {
-    schema: 1,
     outcome: "built",
     committed: true,
     conclusion: "Removed LEGACY_PAYOUT from settlement and config. The admin override still reads it, so one reference remains.",
@@ -193,7 +206,6 @@ index a1b2c3d..d4e5f6a 100644
 +export const EMPTY_STATE_ILLUSTRATION = "quiet-inbox";
 `;
 const DEMO_COPY_HANDOFF = {
-    schema: 1,
     outcome: "built",
     committed: true,
     conclusion: "Rewrote the inbox's empty-state copy so it explains why the list is empty instead of just saying so.",
@@ -605,7 +617,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         filesTruncated: false,
     };
     storeEvidence(store, evidenceRoot, doneRun, "diff-stat", "diff-stat.json", budgetedStatJson(stat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(8.5));
-    storeEvidence(store, evidenceRoot, doneRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(8.4));
+    storeEvidence(store, evidenceRoot, doneRun, "handoff", "handoff.json", demoHandoffBytes(store, doneRun, DEMO_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(8.4));
     // The evidence bundle (Priority 2): a validated proof, its claimed
     // screenshot stored as immutable image evidence, the plane's own re-run
     // check, and the closed verdict — computed once, exactly as the real
@@ -669,7 +681,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         filesTruncated: false,
     };
     storeEvidence(store, evidenceRoot, failedRun, "diff-stat", "diff-stat.json", budgetedStatJson(failedStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(5.6));
-    storeEvidence(store, evidenceRoot, failedRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_FAILED_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(5.6));
+    storeEvidence(store, evidenceRoot, failedRun, "handoff", "handoff.json", demoHandoffBytes(store, failedRun, DEMO_FAILED_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(5.6));
     storeEvidence(store, evidenceRoot, failedRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_FAILED_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(5.6));
     const failedAdjudicated = adjudicate({
         proofArtifactPresent: true,
@@ -734,7 +746,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         filesTruncated: false,
     };
     storeEvidence(store, evidenceRoot, copyReviewRun, "diff-stat", "diff-stat.json", budgetedStatJson(copyStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(3.6));
-    storeEvidence(store, evidenceRoot, copyReviewRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_COPY_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(3.5));
+    storeEvidence(store, evidenceRoot, copyReviewRun, "handoff", "handoff.json", demoHandoffBytes(store, copyReviewRun, DEMO_COPY_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(3.5));
     storeEvidence(store, evidenceRoot, copyReviewRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_COPY_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(3.5));
     const copyReviewProofParse = parseProof(JSON.stringify(DEMO_COPY_PROOF));
     const copyReviewAdjudicated = adjudicate({
@@ -815,10 +827,15 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     };
     storeEvidence(store, evidenceRoot, reviewedRun, "diff-stat", "diff-stat.json", budgetedStatJson(reviewedStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(4.6));
     const DEMO_REPAIR_HANDOFF = {
-        summary: "Added a TODO comment marking the per-account lock — ran out of turns before wiring the actual guard.",
-        filesTouched: ["src/payout-limiter.ts"],
+        outcome: "built",
+        committed: true,
+        conclusion: "Added a TODO comment marking the per-account lock — ran out of turns before wiring the actual guard.",
+        changes: ["Marked the per-account lock in src/payout-limiter.ts."],
+        verification: [],
+        followUps: [],
+        decisionsIncorporated: [],
     };
-    storeEvidence(store, evidenceRoot, reviewedRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_REPAIR_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(4.5));
+    storeEvidence(store, evidenceRoot, reviewedRun, "handoff", "handoff.json", demoHandoffBytes(store, reviewedRun, DEMO_REPAIR_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(4.5));
     const DEMO_REPAIR_PROOF = {
         version: 1,
         criteria: [
@@ -1389,7 +1406,7 @@ export function createDemoLead(input) {
         };
         const shotPath = `evidence/${plan.kind}.png`;
         const png = demoScreenshot(plan.screenshot.accent);
-        const handoff = { schema: 1, outcome: "built", committed: true, conclusion: plan.conclusion, changes: diffs.map(one => `Changed ${one.path}.`), verification: [plan.checks[0]], followUps: [], decisionsIncorporated: [] };
+        const handoff = { outcome: "built", committed: true, conclusion: plan.conclusion, changes: diffs.map(one => `Changed ${one.path}.`), verification: [plan.checks[0]], followUps: [], decisionsIncorporated: [] };
         const proof = {
             version: 1,
             criteria: [
@@ -1404,7 +1421,7 @@ export function createDemoLead(input) {
         const synthetic = "[demo: scripted]";
         storeEvidence(store, evidenceRoot, run, "terminal-diff", "terminal-diff.patch", Buffer.from(diffs.map(one => one.patch).join(""), "utf8"), `git diff --no-ext-diff --no-textconv --no-color ${base.slice(0, 8)}..HEAD (exit 0) ${synthetic}`, at);
         storeEvidence(store, evidenceRoot, run, "diff-stat", "diff-stat.json", budgetedStatJson(stat), `parsed from git diff --numstat -z ${synthetic}`, at);
-        storeEvidence(store, evidenceRoot, run, "handoff", "handoff.json", Buffer.from(JSON.stringify(handoff, null, 2), "utf8"), `composed at completion ${synthetic}`, at);
+        storeEvidence(store, evidenceRoot, run, "handoff", "handoff.json", demoHandoffBytes(store, run, handoff), `composed at completion ${synthetic}`, at);
         storeEvidence(store, evidenceRoot, run, "proof", "proof.json", Buffer.from(JSON.stringify(proof, null, 2), "utf8"), `agent-authored proof (validated, re-serialized) ${synthetic}`, at);
         storeEvidence(store, evidenceRoot, run, "screenshot", `screenshot-${plan.kind}.png`, png, `agent-claimed screenshot at ${shotPath} (validated png) ${synthetic}`, at);
         const log = `=== Attempt summary ===\n- Project check · attempt 1: (exit 0)\n\n=== Project check · attempt 1 ===\n$ ${DEMO_CHECK_COMMAND}\n(exit 0)\n\n--- stdout ---\n${plan.checkOutput}\n--- stderr ---\n`;

package/dist/discord-chat.js

@@ -5,7 +5,9 @@ import { chatFlowButtons } from "./chat-flow.js";
 import { refuseResultShots, resultShotsPruned, shotWaitsUntil } from "./result-shots.js";
 import { channelInbox } from "./chat-inbox.js";
 import { roomCommand } from "./chat-rooms.js";
-import { ChatState, ChatDeliveryError, chatHash, } from "./chat-delivery-state.js";
+import { ChatState, ChatDeliveryError, chatHash, partContent, } from "./chat-delivery-state.js";
+import { readChatPart } from "./contracts/chat-content.js";
+import { readDiscordButtonToken, readDiscordComponentInteraction } from "./contracts/discord-callback.js";
 import { processChatEvent, planChatNotifications, channelAccess, chatObject as object, planRoomMessages, } from "./chat-delivery.js";
 import { chatResultHref } from "./chat-controls.js";
 import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
@@ -69,21 +71,25 @@ export function receiveDiscord(state, identity, type, raw, now) {
             };
     }
     else if (type === "INTERACTION_CREATE") {
-        const data = object(body.data), message = object(body.message);
-        if (body.type !== 3 ||
-            body.application_id !== identity.app ||
-            (isRoom ? object(body.channel).type !== 0 : object(body.channel).type !== 1) ||
-            object(message.author).id !== identity.bot ||
-            message.channel_id !== body.channel_id ||
-            !/^so_[a-f0-9]{32}$/.test(String(data.custom_id)))
+        // Only a tap on one of this bot's own messages, in a DM (or a followed guild text channel), from this app.
+        const interaction = readDiscordComponentInteraction(body);
+        if (!interaction.ok)
             return false;
-        member = isRoom ? object(object(body.member).user).id : object(body.user).id;
-        channel = body.channel_id;
-        id = body.id;
-        ts = message.id;
-        thread = message.id;
+        const tap = interaction.value;
+        if (tap.application_id !== identity.app ||
+            tap.channel.type !== (isRoom ? 0 : 1) ||
+            tap.message.author.id !== identity.bot ||
+            tap.message.channel_id !== tap.channel_id)
+            return false;
+        member = isRoom ? tap.member?.user.id : tap.user?.id;
+        channel = tap.channel_id;
+        id = tap.id;
+        ts = tap.message.id;
+        thread = tap.message.id;
         kind = "action";
-        payload = { token: String(data.custom_id).slice(3) };
+        // A button that isn't one Toolroll made is answered with why, once the tap is proved to be the paired person's below.
+        const button = readDiscordButtonToken(tap);
+        payload = button.ok ? { token: button.value } : { problem: button.issues.map(issue => issue.line).join("; ") };
     }
     else
         return false;
@@ -94,9 +100,10 @@ export function receiveDiscord(state, identity, type, raw, now) {
         !discordId(thread) ||
         member === identity.bot)
         return false;
+    const words = "text" in payload ? payload.text ?? "" : "";
     // v89: a channel that feeds a flow takes anyone's message (as a card, with no say over anything); "flow 12" connects one.
-    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "discord", identity.installation, String(channel), String(payload.text ?? "")) : { watched: false, command: false };
-    const roomish = isRoom && (state.room(identity.installation, String(channel)) !== null || (kind === "message" && roomCommand(String(payload.text ?? "")) !== null) || inbox.watched || inbox.command);
+    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "discord", identity.installation, String(channel), words) : { watched: false, command: false };
+    const roomish = isRoom && (state.room(identity.installation, String(channel)) !== null || (kind === "message" && roomCommand(words) !== null) || inbox.watched || inbox.command);
     if (isRoom && !roomish)
         return false;
     const binding = state.bindingFor(identity.installation, member);
@@ -116,7 +123,7 @@ export function receiveDiscord(state, identity, type, raw, now) {
         member,
         ts,
         thread,
-        payload: JSON.stringify(payload),
+        payload,
         created: now.toISOString(),
     });
 }
@@ -200,7 +207,7 @@ export async function deliverDiscordPart(options) {
         const session = event.session === null ? null : store.getMateSession(event.session), repos = await channelAccess(shared, binding, session?.ceilingDigest);
         if (event.kind === "notice" && options.canNotify?.() === false)
             return false;
-        const content = JSON.parse(row.payload);
+        const content = partContent(row.payload);
         const destination = content.channel ?? binding.channel;
         if (content.task &&
             !repos.includes(store.lookupRef(content.task)?.repo ?? ""))
@@ -398,9 +405,13 @@ export async function deliverDiscordPart(options) {
         return true;
     }
     catch (error) {
+        if (error instanceof ChatDeliveryError && error.permanent) {
+            state.prepare("UPDATE chat_part SET state='dropped',next_at=NULL,problem=? WHERE id=?").run(error.message, row.id);
+            return true;
+        }
         // No permission to attach files here: one plain line instead of the result's screenshots.
-        const content = JSON.parse(row.payload);
-        if (content.image && content.shot && error instanceof DiscordError && error.code === DISCORD_REFUSED) {
+        const saved = readChatPart(row.payload), content = saved.ok ? saved.value : null;
+        if (content !== null && content.image && content.shot && error instanceof DiscordError && error.code === DISCORD_REFUSED) {
             refuseResultShots(state, store, row, content, "Discord", options.clock?.() ?? new Date());
             return true;
         }

package/dist/evidence.d.ts

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

package/dist/evidence.js

@@ -21,6 +21,7 @@ import { LIMITS } from "./decision.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 import { parseReport, REPORT_LIMITS } from "./scout-report.js";
 import { parseProof, PROOF_LIMITS } from "./proof.js";
+import { HANDOFF_VERSION, readHandoffArtifact } from "./contracts/handoff.js";
 import { encodeBaseTreeSnapshot, parseBaseTreeSnapshot } from "./peek.js";
 /** The park mailbox pattern. Each run's actual name carries a nonce; see `mailboxName`. */
 export const MAILBOX_PREFIX = "STANDING-ORDERS-PARK-";
@@ -618,7 +619,10 @@ export function parseNumstat(raw, base, head) {
  * repo-only; a provider session is memory, not a freshness proof.
  */
 export function storeHandoffArtifact(store, root, payload, now) {
-    return storeEvidence(store, root, payload.runId, "handoff", "handoff.json", Buffer.from(JSON.stringify(payload, null, 2), "utf8"), "machine-authored handoff (exit 0)", now);
+    const read = readHandoffArtifact({ version: HANDOFF_VERSION, ...payload });
+    if (!read.ok)
+        throw new Error(`The handoff does not match its contract: ${read.issues.map(issue => issue.line).join("; ")}`);
+    return storeEvidence(store, root, payload.runId, "handoff", "handoff.json", Buffer.from(JSON.stringify(read.value, null, 2), "utf8"), "machine-authored handoff (exit 0)", now);
 }
 /**
  * High-confidence secret shapes ONLY (audit IV-7): a detector that cries

package/dist/flow-engine.js

@@ -19,6 +19,7 @@ import { cardFollowers, notifyPeople } from "./flow-people.js";
 import { DRAFT_CHARS, keptDraft } from "./flow-draft.js";
 import { chooseStep, flowPersonOf, sendStep } from "./flow-send.js";
 import { parseSoul, teammateLabel } from "./teammates.js";
+import { withStageHandoff } from "./contracts/stage-output.js";
 /** The flow's drawing, or null when it can't be read (the card then says so and waits). */
 export function flowDefinitionOf(flow) {
     try {
@@ -302,7 +303,7 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
             const checks = assignmentOf(store, current, now, { principal: "operator", repos: [repo] }, options.evidenceRoot)?.receipt?.checks ?? null;
             if (checks?.status === "failed") {
                 const said = `The checks failed on its result: ${checks.detail}`;
-                store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: `${said} (task ${current})` }, primaryTask: current }, now);
+                store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, { text: `${said} (task ${current})` }), primaryTask: current }, now);
                 if (stage.onFail !== null)
                     onward("fail", said);
                 else if (card.waiting !== `${said} Look at the result, then move the card on or back.`)
@@ -310,27 +311,21 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
                 return;
             }
         }
-        const outputs = { ...card.outputs };
+        let handoff = { text: `Result ready on task ${current}.` };
         if (stage.kind === "report") {
             const ref = store.lookupRef(current);
             const summary = ref === null ? null : reportSummaryFor(store, options.evidenceRoot, ref.id);
-            // The summary whole (a report's summary is within TEXT_LIMITS.reportSummary bytes; an older, longer one is linked).
-            outputs[stage.id] = summary !== null && "summary" in summary ? passOn(summary.summary, TEXT_LIMITS.stageOutput, { label: `task ${current}`, href: null }).text : "The report is ready on its task.";
             // {{stage.<id>.items}} and {{stage.<id>.report}}: what it found and the whole report, for the zones after it.
             // A visit's report replaces the last visit's, so nothing stale is left behind.
             const view = ref === null || options.evidenceRoot === undefined ? null : readVerifiedReport(store, options.evidenceRoot, ref.id);
             const found = view?.ok === true ? reportFillIns(view.report) : { items: "", report: "" };
-            for (const [part, text] of Object.entries(found)) {
-                if (text === "")
-                    delete outputs[`${stage.id}.${part}`];
-                else
-                    outputs[`${stage.id}.${part}`] = text;
-            }
-        }
-        else {
-            outputs[stage.id] = `Result ready on task ${current}.`;
+            handoff = {
+                // The summary whole (a report's summary is within TEXT_LIMITS.reportSummary bytes; an older, longer one is linked).
+                text: summary !== null && "summary" in summary ? passOn(summary.summary, TEXT_LIMITS.stageOutput, { label: `task ${current}`, href: null }).text : "The report is ready on its task.",
+                ...(found.items === "" ? {} : { items: found.items }), ...(found.report === "" ? {} : { report: found.report }),
+            };
         }
-        store.updateFlowCard(card.id, { outputs, ...(stage.kind === "task" ? { primaryTask: current } : {}), waiting: null }, now);
+        store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, handoff), ...(stage.kind === "task" ? { primaryTask: current } : {}), waiting: null }, now);
         // A "Send to me" or "Person chooses" zone next reads what this task produced: the task goes with the card there.
         const following = stage.next === null ? undefined : flowDefinitionStage(definition, stage.next);
         onward("ok", undefined, following?.kind === "send" || following?.kind === "choose" ? current : undefined);
@@ -380,8 +375,10 @@ function goalCuts(store, taskId, goal) {
         if (seen.has(match[1]))
             continue;
         seen.add(match[1]);
-        const text = fillFlowText(`{{${match[1]}}}`, card);
-        if (text === "" || goal.includes(text))
+        // An output too long to pass on is kept whole on the card (src/contracts/stage-output.ts): the agent gets it whole.
+        const whole = match[2] !== undefined && match[3] === undefined ? card.attached[match[2]] : undefined;
+        const text = whole ?? fillFlowText(`{{${match[1]}}}`, card);
+        if (text === "" || (whole === undefined && goal.includes(text)))
             continue;
         cuts.push({ label: flowValueLabel(match[1], id => titleIn(definition, id)), text: text.slice(0, FLOW_ATTACHED_LIMIT) });
     }
@@ -496,7 +493,7 @@ export function decideFlowCard(store, input, now) {
             return { ok: false, message: `Keep the draft to ${DRAFT_CHARS.toLocaleString("en-US")} characters; this is ${input.draft.trim().length.toLocaleString("en-US")}.` };
         }
         if (draft !== null && typeof input.draft === "string" && input.draft.trim() !== "" && input.draft.trim() !== card.outputs[draft.id]?.trim()) {
-            store.updateFlowCard(card.id, { outputs: { ...card.outputs, [draft.id]: keptDraft(input.draft) } }, now);
+            store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, draft.id, { text: keptDraft(input.draft) }) }, now);
             store.addFlowComment({ card: card.id, author: input.actor, body: "Edited the draft before approving it.", mentions: [] }, now);
         }
         if (stage.next === null) {

package/dist/flow-gallery.d.ts

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

package/dist/flow-items.d.ts

@@ -8,17 +8,10 @@
  * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
  * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
  */
-export type FlowSendItem = {
-    title: string;
-    why: string;
-    url: string;
-    /** Where the link goes, by name: "Mobbin", "Linear", "Apple". */
-    source: string;
-    /** One line: how it plugs in (from the why, else the image's own caption). */
-    plug: string;
-    /** The item's screenshot (its evidence id in the report's run), when it has one. */
-    shot: number | null;
-};
+import type { FlowSendItem } from "./contracts/flow-send.js";
+/** One item as the message lists it, and kept items read back (src/contracts/flow-send.ts). */
+export type { FlowSendItem };
+export { readFlowItems } from "./contracts/flow-send.js";
 /** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
 export declare function itemSource(url: string): string;
 /** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
@@ -42,5 +35,3 @@ export declare function cleanFlowMessage(message: FlowMessage, clean: (text: str
  * blocks (else between lines). Every link stays.
  */
 export declare function fitFlowMessage(message: FlowMessage, limit: number, measure: (shaped: string) => number): string[];
-/** Items read back from a kept content; anything malformed is left out. */
-export declare function readFlowItems(raw: unknown): FlowSendItem[];

package/dist/flow-items.js

@@ -8,6 +8,7 @@
  * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
  * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
  */
+export { readFlowItems } from "./contracts/flow-send.js";
 const PLUG_CHARS = 160;
 const NAMES = {
     "mobbin.com": "Mobbin", "github.com": "GitHub", "figma.com": "Figma", "dribbble.com": "Dribbble", "behance.net": "Behance",
@@ -135,18 +136,3 @@ export function fitFlowMessage(message, limit, measure) {
         return [compose(message, 0, 0, title)];
     return pack(blocks(message, Infinity, Infinity, Infinity), "\n\n", fits, block => pack(block.split("\n"), "\n", fits, line => chop(line, fits)));
 }
-/** Items read back from a kept content; anything malformed is left out. */
-export function readFlowItems(raw) {
-    if (!Array.isArray(raw))
-        return [];
-    return raw.flatMap((one) => {
-        if (typeof one !== "object" || one === null)
-            return [];
-        const item = one;
-        const text = (key) => typeof item[key] === "string" ? item[key] : null;
-        const [title, why, url, source, plug] = [text("title"), text("why"), text("url"), text("source"), text("plug")];
-        if (title === null || why === null || url === null || source === null || plug === null || !/^https?:\/\//.test(url))
-            return [];
-        return [{ title, why, url, source, plug, shot: typeof item["shot"] === "number" && Number.isSafeInteger(item["shot"]) ? item["shot"] : null }];
-    });
-}

package/dist/flow-send.d.ts

@@ -1,5 +1,5 @@
 import { type FlowDecision } from "./flow-engine.js";
-import { type FlowSendItem } from "./flow-items.js";
+import { type FlowChoiceAnswer, type FlowSendContent, type FlowSendLink } from "./contracts/flow-send.js";
 import { type FlowDefinition, type FlowStage } from "./flows.js";
 import { type FlowCardRow, type FlowRow, type Store } from "./store.js";
 /** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
@@ -8,39 +8,14 @@ export declare const FLOW_SEND_KEY: RegExp;
 export declare const FLOW_CHOOSE_KEY: RegExp;
 /** What the person is asked under the buttons. */
 export declare const REPLY_ASK = "Or reply with what you'd change.";
-export type FlowSendLink = {
-    label: string;
-    path: string;
-} | {
-    label: string;
-    url: string;
-};
-export type FlowSendContent = {
-    /** The card's title and the step it comes from. */
-    title: string;
-    /** The step it comes from, when known. */
-    from?: string;
-    summary: string;
-    links: FlowSendLink[];
-    /** The build's result whose screenshots go with it, when it saved any. */
-    shots: {
-        taskId: string;
-        run: number;
-    } | null;
-    /** After research: the report's items, numbered in this order in every message and screenshot caption (flow-items.ts). */
-    items?: FlowSendItem[];
-    /** choose: the options as they were offered, and whether a reply is taken. */
-    options?: {
-        choice: number;
-        label: string;
-    }[];
-    reply?: boolean;
-};
+/** A visit's content and its links (src/contracts/flow-send.ts). */
+export type { FlowSendContent, FlowSendLink };
 /** Who a card's "Send to me" and "Person chooses" zones are for: its owner, else the flow's. */
 export declare function flowPersonOf(card: Pick<FlowCardRow, "owner">, flow: Pick<FlowRow, "owner">): string;
 /** What a visit sends its person, worked out from the card as it is now. */
 export declare function flowSendContent(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, evidenceRoot?: string): FlowSendContent;
-/** A kept content, read back; null when it can't be. */
+/** A kept content, read back (src/contracts/flow-send.ts: one kept before it carried a version reads as it did); null
+ * when it can't be, and the visit's content is worked out again. */
 export declare function readFlowSend(json: string): FlowSendContent | null;
 /** The words of a sent visit: its title, summary and pull request (the one link that isn't a page of Toolroll's). */
 export declare function flowSendText(content: FlowSendContent): string;
@@ -71,13 +46,7 @@ export declare function flowChoiceAt(store: Store, cardId: number, entry: number
  * reply (`choice` null) that becomes the note for where replies go. `where` names the place it was made, for the card's
  * history and the ledger: "Telegram", "Slack", "the console".
  */
-export declare function chooseFlowCard(store: Store, input: {
-    card: number;
-    entry?: number;
-    choice: number | null;
-    label?: string;
-    to?: string;
-    note: string | null;
+export declare function chooseFlowCard(store: Store, input: FlowChoiceAnswer & {
     actor: string;
     where: string;
     repos: readonly string[];

package/dist/flow-send.js

@@ -17,7 +17,9 @@ import { assignmentOf } from "./assignment.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 import { withActor } from "./actor.js";
 import { flowCardHref, flowDefinitionOf, revisionWithNote } from "./flow-engine.js";
-import { itemPlug, itemSource, readFlowItems } from "./flow-items.js";
+import { itemPlug, itemSource } from "./flow-items.js";
+import { withStageHandoff } from "./contracts/stage-output.js";
+import { flowSendForStore, readFlowChoiceAnswer, readFlowItems, readFlowSendPayload } from "./contracts/flow-send.js";
 import { notifyPeople } from "./flow-people.js";
 import { readVerifiedReport } from "./evidence.js";
 import { FLOW_END, replyTarget } from "./flows.js";
@@ -120,21 +122,18 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
         ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
     };
 }
-/** A kept content, read back; null when it can't be. */
+/** A kept content, read back (src/contracts/flow-send.ts: one kept before it carried a version reads as it did); null
+ * when it can't be, and the visit's content is worked out again. */
 export function readFlowSend(json) {
+    let raw;
     try {
-        const raw = JSON.parse(json);
-        if (typeof raw.title !== "string" || typeof raw.summary !== "string" || !Array.isArray(raw.links))
-            return null;
-        if (raw.items === undefined)
-            return raw;
-        const items = readFlowItems(raw.items);
-        const { items: _, ...rest } = raw;
-        return items.length === 0 ? rest : { ...rest, items };
+        raw = JSON.parse(json);
     }
     catch {
         return null;
     }
+    const read = readFlowSendPayload(raw);
+    return read.ok ? read.value : null;
 }
 /** The words of a sent visit: its title, summary and pull request (the one link that isn't a page of Toolroll's). */
 export function flowSendText(content) {
@@ -153,7 +152,7 @@ function keep(store, flow, definition, stage, card, now, evidenceRoot) {
     if (kept !== null && read !== null)
         return { content: read, person: kept.person, fresh: false };
     const content = flowSendContent(store, flow, definition, stage, card, now, evidenceRoot);
-    const fresh = store.recordFlowSend({ card: card.id, entry: card.entry, stage: stage.id, person, contentJson: JSON.stringify(content) }, now);
+    const fresh = store.recordFlowSend({ card: card.id, entry: card.entry, stage: stage.id, person, contentJson: flowSendForStore(content) }, now);
     return { content, person, fresh };
 }
 /** One notice to the person, and its screenshots after it. Never as anyone's own act: they asked for it in the flow. */
@@ -174,7 +173,7 @@ export function sendStep(store, flow, definition, stage, card, now, evidenceRoot
     const { content, person, fresh } = keep(store, flow, definition, stage, card, now, evidenceRoot);
     if (!fresh)
         return;
-    store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: flowSendText(content) } }, now);
+    store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, { text: flowSendText(content) }) }, now);
     enqueue(store, flow, card, person, content, { key: `flow-send:${card.id}:${card.entry}`, kind: "flow-card", attention: false,
         subject: `${flow.name}: ${content.title}`, body: [content.summary, ...content.links.filter((one) => "url" in one).map(one => `${one.label}: ${one.url}`)].join("\n\n") }, now);
 }
@@ -217,11 +216,16 @@ const via = (where) => where === "" ? "" : ` in ${where}`;
  * history and the ledger: "Telegram", "Slack", "the console".
  */
 export function chooseFlowCard(store, input, now) {
-    const card = store.getFlowCard(input.card);
+    // The answer itself (src/contracts/flow-send.ts): an option that isn't one of the places offered is a changed option.
+    const { actor: _actor, where: _where, repos: _repos, evidenceRoot: _root, ...given } = input;
+    const answer = readFlowChoiceAnswer(given);
+    if (!answer.ok)
+        return { ok: false, message: answer.issues.every(one => one.path === "choice") ? "Those options changed since; nothing was changed." : "That card is no longer waiting." };
+    const card = store.getFlowCard(answer.value.card);
     const flow = card === null ? null : store.getFlow(card.flow);
     if (card === null || flow === null || card.state !== "active" || !input.repos.includes(flow.repo))
         return { ok: false, message: "That card is no longer waiting." };
-    const visit = flowChoiceAt(store, card.id, input.entry ?? card.entry);
+    const visit = flowChoiceAt(store, card.id, answer.value.entry ?? card.entry);
     if (visit === null)
         return { ok: false, message: "That card has moved on since; nothing was changed." };
     const { stage, definition, person } = visit;