toolroll 0.9.36 → 0.9.38

package/dist/chat-delivery-state.js

@@ -1,136 +1,10 @@
 /** Durable private-chat receipts. Each transport has its own tables and lease. */
 import { createHash, randomBytes } from "node:crypto";
 import { MATE_ASK_TTL_MS } from "./store.js";
-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",
-];
+import { chatSchema, chatTables } from "./contracts/chat-tables.js";
+import { readChatPart, savedChatEventBody, savedChatPart } from "./contracts/chat-content.js";
+export { savedChatPart };
+export { chatSchema, chatTables };
 export const chatHash = (text) => createHash("sha256").update(text).digest("hex");
 export class ChatState {
     store;
@@ -275,8 +149,9 @@ export class ChatState {
             return this.bindingFor(identity.installation, member);
         });
     }
+    /** Save a received event with its body (contracts/chat-content.ts), versioned. */
     enqueue(event) {
-        return (Number(this.prepare("INSERT OR IGNORE INTO chat_event(id,installation,binding,kind,channel,member,ts,thread,payload,created) VALUES(?,?,?,?,?,?,?,?,?,?)").run(event.id, event.installation, event.binding, event.kind, event.channel, event.member, event.ts, event.thread, event.payload, event.created).changes) === 1);
+        return (Number(this.prepare("INSERT OR IGNORE INTO chat_event(id,installation,binding,kind,channel,member,ts,thread,payload,created) VALUES(?,?,?,?,?,?,?,?,?,?)").run(event.id, event.installation, event.binding, event.kind, event.channel, event.member, event.ts, event.thread, savedChatEventBody(event.payload), event.created).changes) === 1);
     }
     event(id) {
         return (this.prepare("SELECT * FROM chat_event WHERE id=?").get(id) ?? null);
@@ -296,7 +171,7 @@ export class ChatState {
     plan(event, parts, now) {
         this.store.transact(() => {
             for (const [ordinal, part] of parts.entries()) {
-                const inserted = this.prepare("INSERT OR IGNORE INTO chat_part(event,ordinal,payload,created) VALUES(?,?,?,?)").run(event, ordinal, JSON.stringify(part), now.toISOString());
+                const inserted = this.prepare("INSERT OR IGNORE INTO chat_part(event,ordinal,payload,created) VALUES(?,?,?,?)").run(event, ordinal, savedChatPart(part), now.toISOString());
                 if (Number(inserted.changes) && part.proposal)
                     this.tokens(Number(inserted.lastInsertRowid), part.proposal, ["confirm", "dismiss"], now);
                 if (Number(inserted.changes) && part.question)
@@ -332,16 +207,23 @@ export class ChatState {
         return !!this.prepare("SELECT 1 FROM chat_runtime WHERE installation=? AND owner=? AND lease_until>?").get(installation, owner, now.toISOString());
     }
 }
-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}_`));
+/** A saved part's content. One that can't be read is a delivery problem that names the field, never a guess. */
+export function partContent(payload) {
+    const read = readChatPart(payload);
+    if (!read.ok)
+        throw new ChatDeliveryError(`This saved message can't be read: ${read.issues.map(issue => issue.line).join("; ")}`, 0, false, true);
+    return read.value;
+}
 export class ChatDeliveryError extends Error {
     code;
     retryMs;
     uncertain;
-    constructor(code, retryMs = 5000, uncertain = false) {
+    permanent;
+    constructor(code, retryMs = 5000, uncertain = false, permanent = false) {
         super(code);
         this.code = code;
         this.retryMs = retryMs;
         this.uncertain = uncertain;
+        this.permanent = permanent;
     }
 }

package/dist/chat-delivery.js

@@ -7,7 +7,9 @@ import { shapeReplyParts } from "./reply-shape.js";
 import { warmTurn } from "./chat-warmth.js";
 import { confirmMateProposal, dismissMateProposal, } from "./mate-doors.js";
 import { ceilingDigestOf, verifyApproverStanding } from "./principal.js";
-import { ChatState, ChatDeliveryError, chatHash, } from "./chat-delivery-state.js";
+import { ChatState, ChatDeliveryError, chatHash, savedChatPart, } from "./chat-delivery-state.js";
+import { readChatActionBody, readChatMessageBody, readChatPairBody, readChatPart } from "./contracts/chat-content.js";
+import { readProposalActionRow } from "./contracts/chat-callback-rows.js";
 import { answerChatFlowPrompt, answerChoiceMessage, applyChatFlowTap, flowDecisionParts, flowSendParts } from "./chat-flow.js";
 import { connectChannel, FLOW_WORDS, takeChannelMessage, watchedChannel } from "./chat-inbox.js";
 import { triggerConfigOf } from "./flow-triggers.js";
@@ -84,7 +86,10 @@ export async function processChatEvent(options) {
             if (!state.owns(identity.installation, options.owner, nowOf(options)) ||
                 !options.current())
                 return false;
-            const paired = state.pair(identity, String(object(JSON.parse(event.payload)).hash), event.member, event.channel, nowOf(options));
+            const body = readChatPairBody(event.payload);
+            const paired = body.ok
+                ? state.pair(identity, body.value.hash, event.member, event.channel, nowOf(options))
+                : null;
             if (!paired) {
                 state.finish(event.id, true);
                 return true;
@@ -112,7 +117,12 @@ export async function processChatEvent(options) {
             applyChatAction(options, event, binding, repos);
             return true;
         }
-        const input = object(JSON.parse(event.payload));
+        const body = readChatMessageBody(event.payload);
+        if (!body.ok) {
+            state.plan(event.id, [{ text: `That message couldn't be read (${body.issues.map(issue => issue.line).join("; ")}). Send it again.` }], nowOf(options));
+            return true;
+        }
+        const input = body.value;
         if (typeof input.unsupported === "string") {
             state.plan(event.id, [{ text: input.unsupported }], nowOf(options));
             return true;
@@ -193,8 +203,7 @@ export async function processChatEvent(options) {
         if (text.length > MATE_MESSAGE_MAX_CHARS) {
             state.plan(event.id, [
                 {
-                    text: tooLongText(Number(object(JSON.parse(event.payload)).originalLength) ||
-                        text.length),
+                    text: tooLongText(input.originalLength || text.length),
                 },
             ], nowOf(options));
             return true;
@@ -237,7 +246,8 @@ export async function processChatEvent(options) {
             const contexts = state
                 .prepare("SELECT p.payload FROM chat_part p JOIN chat_event e ON e.id=p.event WHERE e.binding=? AND e.channel=? AND (p.message=? OR e.thread=?) AND p.state='sent' ORDER BY p.id DESC LIMIT 100")
                 .all(binding.id, binding.channel, event.thread, event.thread)
-                .map((row) => JSON.parse(String(row.payload)))
+                // Context only: a part that can't be read adds none.
+                .flatMap((row) => { const read = readChatPart(String(row.payload)); return read.ok ? [read.value] : []; })
                 // A card is about the task it names, or the one confirming it filed.
                 .map((c) => {
                 if (c.task || c.proposal === undefined)
@@ -385,6 +395,11 @@ export async function processChatEvent(options) {
         const problem = error instanceof ChatDeliveryError
             ? error
             : new ChatDeliveryError(`${options.label} is waiting to retry`);
+        if (problem.permanent) {
+            state.plan(event.id, [{ text: problem.message }], nowOf(options));
+            state.prepare("UPDATE chat_event SET next_at=NULL,problem=? WHERE id=?").run(problem.message, event.id);
+            return true;
+        }
         state
             .prepare("UPDATE chat_runtime SET problem=? WHERE installation=? AND owner=?")
             .run(problem.message, identity.installation, options.owner);
@@ -405,8 +420,11 @@ async function channelInboxEvent(options, event) {
     const binding = event.binding === null ? null : state.bindingById(event.binding);
     if (binding !== null && event.channel === binding.channel)
         return false;
-    const input = object(JSON.parse(event.payload));
-    const text = String(input.text ?? "");
+    const body = readChatMessageBody(event.payload);
+    // One that can't be read is answered, by path, on the ordinary path.
+    if (!body.ok)
+        return false;
+    const text = body.value.text ?? "";
     if (FLOW_WORDS.test(text.trim())) {
         // Only a paired approver connects a channel, and only to a flow in their projects.
         if (binding === null || !state.live(binding)) {
@@ -450,7 +468,14 @@ export function applyChatAction(options, event, binding, repos) {
             event.member !== binding.member ||
             (event.channel !== binding.channel && state.room(options.identity.installation, event.channel)?.kind !== "group"))
             return;
-        const token = String(object(JSON.parse(event.payload)).token);
+        // A button the paired person tapped whose data couldn't be read is answered plainly: what was wrong, and that nothing was done.
+        const body = readChatActionBody(event.payload);
+        if (!body.ok || "problem" in body.value) {
+            const problem = body.ok ? ("problem" in body.value ? body.value.problem : "") : body.issues.map(issue => issue.line).join("; ");
+            state.plan(event.id, [{ text: `That button couldn't be read (${problem}). Nothing was done.` }], now);
+            return;
+        }
+        const token = body.value.token;
         // A flow decision's button (v88) is answered by the flow's own door.
         if (applyChatFlowTap({ store, state, label: options.label }, event, binding, token, repos, now))
             return;
@@ -460,16 +485,19 @@ export function applyChatAction(options, event, binding, repos) {
         // The lead's question to its owner: the tapped option becomes their next message.
         if (applyChatAskTap({ store, state }, event, binding, token, now))
             return;
-        const action = state
+        const saved = state
             .prepare("SELECT a.*,p.message,e.binding,e.channel,e.thread FROM chat_action a JOIN chat_part p ON p.id=a.part JOIN chat_event e ON e.id=p.event WHERE token=?")
             .get(token);
+        // The saved button, read by its schema: one that can't be read is a spent button, never a guess.
+        const read = saved === undefined ? null : readProposalActionRow({ ...saved });
+        const action = read?.ok === true ? read.value : null;
         const invalid = !action ||
             action.binding !== binding.id ||
             action.channel !== event.channel ||
             action.message !== event.ts ||
             (options.state.channel === "slack" && action.thread !== event.thread) ||
             action.consumed !== null ||
-            String(action.expires) <= now.toISOString();
+            action.expires <= now.toISOString();
         if (invalid) {
             state.plan(event.id, [
                 {
@@ -478,7 +506,7 @@ export function applyChatAction(options, event, binding, repos) {
             ], now);
             return;
         }
-        const proposal = store.getMateProposal(Number(action.proposal));
+        const proposal = store.getMateProposal(action.proposal);
         const verified = verifyApproverStanding(store, binding.approver, binding.generation, repos);
         if (!proposal || !verified.ok) {
             state.finish(event.id, true);
@@ -490,14 +518,14 @@ export function applyChatAction(options, event, binding, repos) {
             edit: event.ts,
         };
         const preview = proposalPreview(store, proposal, repos, options.state.channel);
-        const phase = String(action.phase);
+        const phase = action.phase;
         if (proposal.state !== "pending")
             content = { text: proposalOutcomeText(proposal), edit: event.ts };
         else if (!preview.buttons ||
             preview.text.length > (options.maxProposal ?? 10_000))
             content = { ...content, text: "Review this action in Toolroll." };
         else if (phase === "cancel") {
-            state.tokens(Number(action.part), proposal.id, ["confirm", "dismiss"], now);
+            state.tokens(action.part, proposal.id, ["confirm", "dismiss"], now);
         }
         else if (phase === "dismiss") {
             const dismissed = dismissMateProposal(store, verified.who, proposal.id, now);
@@ -512,7 +540,7 @@ export function applyChatAction(options, event, binding, repos) {
             proposal.kind === "answer" &&
             proposal.payload.reversible === false) {
             content = { ...content, phase: "armed" };
-            state.tokens(Number(action.part), proposal.id, ["yes", "cancel"], now);
+            state.tokens(action.part, proposal.id, ["yes", "cancel"], now);
         }
         else {
             const outcome = confirmMateProposal(store, verified.who, proposal.id, now, {
@@ -524,7 +552,7 @@ export function applyChatAction(options, event, binding, repos) {
             });
             if (!outcome.ok && outcome.reason === "needs-confirm") {
                 content = { ...content, phase: "armed" };
-                state.tokens(Number(action.part), proposal.id, ["yes", "cancel"], now);
+                state.tokens(action.part, proposal.id, ["yes", "cancel"], now);
             }
             else {
                 content = {
@@ -540,7 +568,7 @@ export function applyChatAction(options, event, binding, repos) {
         // Repaint the original persisted card; retain one placement and fresh tokens.
         state
             .prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?")
-            .run(JSON.stringify(content), Number(action.part));
+            .run(savedChatPart(content), action.part);
         if (!content.proposal)
             state
                 .prepare("UPDATE chat_action SET consumed=? WHERE proposal=? AND consumed IS NULL")
@@ -607,7 +635,7 @@ export async function planRoomMessages(options) {
             const id = chatHash(`${state.channel}:room:${room.id}:${message.id}`);
             const target = carrier;
             store.transact(() => {
-                if (parts.length > 0 && state.enqueue({ id, installation: identity.installation, binding: target.id, kind: "message", channel: room.chat, member: target.member, ts: "", thread: "", payload: "{}", created: now.toISOString() }))
+                if (parts.length > 0 && state.enqueue({ id, installation: identity.installation, binding: target.id, kind: "message", channel: room.chat, member: target.member, ts: "", thread: "", payload: {}, created: now.toISOString() }))
                     state.plan(id, parts, now);
                 state.advanceRoomCursor(room.id, message.id);
             });
@@ -629,13 +657,13 @@ function planQuietCard(options, binding, notification, now) {
     if (card.message !== null) {
         if (card.digest === shown)
             return;
-        state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(JSON.stringify(content), now.toISOString(), Number(card.message));
+        state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(savedChatPart(content), now.toISOString(), Number(card.message));
         store.setChatCardMessage(card.id, card.message, shown);
         return;
     }
     const id = chatHash(`${state.channel}:card:${binding.id}:${card.id}`);
     state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-        ts: "", thread: "", payload: "{}", created: now.toISOString() });
+        ts: "", thread: "", payload: {}, created: now.toISOString() });
     state.plan(id, [content], now);
     const part = state.prepare("SELECT id FROM chat_part WHERE event=?").get(id);
     if (part !== undefined)
@@ -659,13 +687,13 @@ function planFinished(options, binding, taskRef, run, now, notification = null)
     if (batch.message !== null) {
         if (batch.digest === shown)
             return true;
-        state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(JSON.stringify(content), now.toISOString(), Number(batch.message));
+        state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(savedChatPart(content), now.toISOString(), Number(batch.message));
         store.setChatBatchMessage(batch.id, batch.message, shown);
         return true;
     }
     const id = chatHash(`${state.channel}:batch:${binding.id}:${batch.id}`);
     state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-        ts: "", thread: "", payload: "{}", created: now.toISOString() });
+        ts: "", thread: "", payload: {}, created: now.toISOString() });
     state.plan(id, [content], now);
     const part = state.prepare("SELECT id FROM chat_part WHERE event=?").get(id);
     if (part !== undefined)
@@ -714,7 +742,7 @@ function planResultShots(options, binding, notification, repos, id, now) {
                 image: image(plan.shots[0].artifact, plan.shots[0].sha256), shot: { follows: null }, ...where }]
             : plan.shots.map(one => ({ text: one.caption, image: image(one.artifact, one.sha256), shot: { follows }, ...where }));
     state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-        ts: "", thread: "", payload: "{}", created: now.toISOString() });
+        ts: "", thread: "", payload: {}, created: now.toISOString() });
     state.plan(id, parts, now);
 }
 /** One progress card per exact result; separate urgent facts retain their own review link. */
@@ -770,11 +798,11 @@ export async function planChatNotifications(options) {
                         const earlier = leadSayEarlier(store, notification).map(one => state.prepare("SELECT id FROM chat_part WHERE event=?")
                             .get(chatHash(`${options.state.channel}:notice:${binding.id}:${one}`))).find(one => one !== undefined);
                         if (earlier !== undefined) {
-                            state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(JSON.stringify(content), now.toISOString(), Number(earlier.id));
+                            state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(savedChatPart(content), now.toISOString(), Number(earlier.id));
                             return;
                         }
                         state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-                            ts: "", thread: "", payload: "{}", created: now.toISOString() });
+                            ts: "", thread: "", payload: {}, created: now.toISOString() });
                         state.plan(id, [content], now);
                         return;
                     }
@@ -826,7 +854,7 @@ export async function planChatNotifications(options) {
                                 member: binding.member,
                                 ts: "",
                                 thread: "",
-                                payload: "{}",
+                                payload: {},
                                 created: now.toISOString(),
                             });
                             state.plan(id, [content], now);
@@ -843,20 +871,20 @@ export async function planChatNotifications(options) {
                         const parts = flowDecisionParts(store, notification, state.channel);
                         if (parts !== null) {
                             state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-                                ts: "", thread: "", payload: "{}", created: now.toISOString() });
+                                ts: "", thread: "", payload: {}, created: now.toISOString() });
                             state.plan(id, parts, now);
                         }
                     }
                     else if (personal && flowSendParts(store, notification, state.channel) !== null) {
                         // A flow's "Send to me" (flow-send.ts): what was done, with its links as buttons.
                         state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-                            ts: "", thread: "", payload: "{}", created: now.toISOString() });
+                            ts: "", thread: "", payload: {}, created: now.toISOString() });
                         state.plan(id, flowSendParts(store, notification, state.channel), now);
                     }
                     else if (notification.kind === "flow-card" && questionParts(store, notification, binding) !== null) {
                         // A teammate's question (v93): its options and "Answer in words" on the notice, for the person it asks.
                         state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
-                            ts: "", thread: "", payload: "{}", created: now.toISOString() });
+                            ts: "", thread: "", payload: {}, created: now.toISOString() });
                         state.plan(id, questionParts(store, notification, binding), now);
                     }
                     else if (notification.pushClass !== null || personal || quiet) {
@@ -869,7 +897,7 @@ export async function planChatNotifications(options) {
                             member: binding.member,
                             ts: "",
                             thread: "",
-                            payload: "{}",
+                            payload: {},
                             created: now.toISOString(),
                         });
                         state.plan(id, [

package/dist/chat-flow.js

@@ -34,7 +34,8 @@ import { renderReply } from "./reply-shape.js";
 import { deciderOf, replyTarget } from "./flows.js";
 import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
 import { verifyApproverStanding } from "./principal.js";
-import { chatHash } from "./chat-delivery-state.js";
+import { chatHash, partContent, savedChatPart } from "./chat-delivery-state.js";
+import { readHeldWords } from "./contracts/chat-content.js";
 import { FLOW_DECIDE_KEY, flowDecisionAt } from "./telegram-flow.js";
 import { phoneCommand } from "./telegram-status.js";
 export const CHAT_FLOW_LABELS = { approve: "Approve", edit: "Edit", "send-back": "Send back" };
@@ -144,11 +145,11 @@ const retire = (state, card, entry, now) => {
 /** Show the tapped notice again with what happened, and without its buttons. */
 function repaint(state, part, event, line) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
-    const before = row === undefined ? { text: "" } : JSON.parse(String(row["payload"]));
+    const before = row === undefined ? { text: "" } : partContent(String(row["payload"]));
     // An item list (flow-items.ts) stays whole and keeps its bold titles and labelled links; only plain text is capped.
     const content = { text: before.voice === true ? `${before.text}\n\n${line}` : `${before.text}\n\n${line}`.slice(0, PART_CHARS + 400), edit: event.ts, ...(before.voice === true ? { voice: true } : {}),
         ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
-    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(JSON.stringify(content), part);
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(savedChatPart(content), part);
 }
 /**
  * A tapped flow button, inside the action's transaction. false when the
@@ -351,8 +352,9 @@ function applyChatNoteTap(options, event, binding, token, repos, now) {
     }
     state.prepare("UPDATE chat_flow_note SET consumed=?,words=NULL WHERE part=?").run(now.toISOString(), part);
     const held = state.event(String(tapped["held"]));
-    const words = typeof tapped["words"] === "string" ? JSON.parse(tapped["words"]) : null;
-    if (held === null || words === null || typeof words.text !== "string") {
+    const kept = typeof tapped["words"] === "string" ? readHeldWords(tapped["words"]) : null;
+    const words = kept?.ok === true ? kept.value : null;
+    if (held === null || words === null) {
         repaint(state, part, event, "That message is no longer kept; nothing was changed.");
         state.finish(event.id);
         return true;
@@ -360,7 +362,7 @@ function applyChatNoteTap(options, event, binding, token, repos, now) {
     if (tapped["answer"] === "no") {
         // Passed on as the message it was, to the lead, once.
         state.enqueue({ id: chatHash(`${held.id}:lead`), installation: held.installation, binding: held.binding, kind: "message", channel: held.channel, member: held.member,
-            ts: held.ts, thread: held.thread, payload: JSON.stringify({ ...words, lead: true }), created: now.toISOString() });
+            ts: held.ts, thread: held.thread, payload: { ...words, lead: true }, created: now.toISOString() });
         repaint(state, part, event, "Passed to the lead.");
         state.finish(event.id);
         return true;

package/dist/chat-inbox.js

@@ -116,7 +116,7 @@ export function replyInChannel(store, source, visit, text, now) {
     const id = chatHash(`${source.app}:flow-reply:${visit.card}:${visit.entry}`);
     store.transact(() => {
         if (state.enqueue({ id, installation: grant.installation, binding: grant.id, kind: "message", channel: source.conversation, member: grant.member,
-            ts: source.thread, thread: source.thread, payload: "{}", created: now.toISOString() }))
+            ts: source.thread, thread: source.thread, payload: {}, created: now.toISOString() }))
             state.plan(id, [{ text: text.slice(0, 3500), channel: source.conversation }], now);
     });
     return { ok: true };

package/dist/coding-context.d.ts

@@ -1,43 +1,6 @@
 import type { Store } from './store.js';
-export type CodingContextMetadata = {
-    version: 1;
-    repo: string;
-    identity: string;
-    baseRevision: string;
-    knowledge: {
-        revision: number;
-        selectionSha256: string;
-        references: {
-            id: string;
-            title: string;
-            path: string | null;
-            sourceSha: string | null;
-            sourceRevision: string | null;
-        }[];
-        omitted: {
-            title: string;
-            reason: string;
-        }[];
-    };
-    skills: {
-        revision: number;
-        packages: {
-            name: string;
-            sha256: string;
-            skillFile: string;
-        }[];
-    };
-    directory: string | null;
-    files: {
-        path: string;
-        sha256: string;
-    }[];
-};
-export type CodingContext = {
-    text: string;
-    metadata: CodingContextMetadata;
-    sha256: string;
-};
+import { type CodingContext } from './contracts/coding-context.js';
+export type { CodingContext, CodingContextMetadata } from './contracts/coding-context.js';
 /**
  * Call before thread/start with the canonical project and the exact worktree
  * base. Persist the returned object with the coding session and reuse it on

package/dist/coding-context.js

@@ -5,6 +5,7 @@ import { basename, dirname, join, resolve, relative, isAbsolute, sep } from 'nod
 import { KNOWLEDGE_GUIDANCE, selectProjectKnowledge } from './project-knowledge.js';
 import { materializeProjectSkills, PROJECT_SKILLS_GUIDANCE, selectProjectSkills } from './project-skills.js';
 import { identityMatches, learningIdentity, learningSha } from './project-learning.js';
+import { CODING_CONTEXT_VERSION } from './contracts/coding-context.js';
 function freeze(value) {
     if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
         for (const child of Object.values(value))
@@ -70,7 +71,7 @@ export function prepareCodingContext(store, args) {
         directory,
         files: captured.skills.packages.flatMap(skill => skill.files.map(file => ({ path: `${skill.name}/${file.path}`, sha256: fileDigest(Buffer.from(file.base64, 'base64')) }))),
     };
-    return freeze({ text, metadata, sha256: digest(text, metadata) });
+    return freeze({ version: CODING_CONTEXT_VERSION, text, metadata, sha256: digest(text, metadata) });
 }
 /** Integrity check for a persisted capture. The caller must separately recheck current account access. */
 export function verifyCodingContext(context, repo, baseRevision) {

package/dist/coding-handoff.d.ts

@@ -1,28 +1,7 @@
-import { type AcceptanceCriterion } from './scope.js';
+import { type CodingHandoffReceipt } from './contracts/coding-handoff.js';
 import type { Store } from './store.js';
-export type CodingHandoffPreview = {
-    sessionId: string;
-    repo: string;
-    base: string;
-    candidate: string;
-    title: string;
-    originalPrompt: string;
-    changedPaths: string[];
-};
-type ReceiptTerms = CodingHandoffPreview & {
-    version: 1;
-    identity: string;
-    actor: string;
-    generation: number;
-    goal: string;
-    acceptance: AcceptanceCriterion[];
-    outOfScope: string;
-};
-export type CodingHandoffReceipt = ReceiptTerms & {
-    id: string;
-    taskId: string;
-    branch: string;
-};
+export type { CodingHandoffReceipt } from './contracts/coding-handoff.js';
+export type CodingHandoffPreview = Pick<CodingHandoffReceipt, 'sessionId' | 'repo' | 'base' | 'candidate' | 'title' | 'originalPrompt' | 'changedPaths'>;
 export type CodingHandoffInput = {
     sessionId: string;
     repo: string;
@@ -42,6 +21,9 @@ export declare function codingHandoffPreview(store: Store, input: {
     sessionId: string;
     actor: string;
 }): CodingHandoffPreview;
+/** The saved bytes are verified before they are parsed; identity and branch are checked on the parsed terms. */
+export declare function parseReceipt(row: Record<string, unknown>): CodingHandoffReceipt;
+export declare function sealPayload(receipt: CodingHandoffReceipt, scopeDigest: string): string;
 /** Returns null only for ordinary tasks. A coding marker always requires its receipt. */
 export declare function readCodingHandoff(store: Store, taskId: string): Handoff | null;
 /** No agent dispatch, approval, push, or modification of an existing Git ref. */
@@ -54,4 +36,3 @@ export declare function verifyCodingHandoffBase(store: Store, input: {
     branch: string;
     head: string;
 }): void;
-export {};