toolroll 0.9.34 → 0.9.37

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 {};

package/dist/coding-handoff.js

@@ -10,6 +10,8 @@ import { parseAcceptanceCriteria, proposeGuarded } from './scope.js';
 import { validateTaskText } from './task-text.js';
 import { PROOF_LIMITS } from './proof.js';
 import { readPreparedEvidence } from './prepared-evidence.js';
+import { parseCodingHandoffReceipt } from './contracts/coding-handoff.js';
+import { parseCodingSessionDocument } from './contracts/coding-workspace.js';
 import { BRANCH_PREFIXES, taskBranch } from './names.js';
 const PREFIX = 'coding:';
 const SHA = /^[a-f0-9]{40}$/;
@@ -84,7 +86,7 @@ function sessionFor(db, store, sessionId, actor) {
     const row = db.prepare('SELECT owner,generation,repo,document FROM coding_session WHERE id=?').get(sessionId);
     if (!row || row['owner'] !== actor)
         throw Error('This coding session is not available to your account.');
-    const session = JSON.parse(String(row['document']));
+    const session = parseCodingSessionDocument(String(row['document']));
     const generation = actorGeneration(store, actor, String(row['repo']));
     if (row['generation'] !== generation || session.id !== sessionId || session.owner !== actor || session.generation !== generation || session.repo !== row['repo'])
         throw Error('The coding session no longer matches your account or project.');
@@ -132,18 +134,22 @@ function makeReceipt(terms) {
     const id = learningSha(JSON.stringify(terms)).slice(0, 32), taskId = `coding-review-${id}`;
     return { ...terms, id, taskId, branch: taskBranch(taskId) };
 }
-function parseReceipt(row) {
+/** The saved bytes are verified before they are parsed; identity and branch are checked on the parsed terms. */
+export function parseReceipt(row) {
     const payload = String(row['payload']);
     if (learningSha(payload) !== row['sha'])
         throw Error('The coding handoff receipt could not be verified.');
-    const receipt = JSON.parse(payload);
+    const read = parseCodingHandoffReceipt(payload);
+    if (!read.ok)
+        throw Error(`The coding handoff receipt could not be read: ${read.issues.map(issue => issue.line).join('; ')}`);
+    const receipt = read.value;
     const { id, taskId, branch, ...terms } = receipt;
     const expected = makeReceipt(terms);
-    if (receipt.version !== 1 || row['id'] !== id || id !== expected.id || taskId !== expected.taskId || !BRANCH_PREFIXES.some(prefix => branch === `${prefix}${taskId}`) || !SHA.test(receipt.base) || !SHA.test(receipt.candidate))
+    if (row['id'] !== id || id !== expected.id || taskId !== expected.taskId || !BRANCH_PREFIXES.some(prefix => branch === `${prefix}${taskId}`) || !SHA.test(receipt.base) || !SHA.test(receipt.candidate))
         throw Error('The coding handoff receipt identity could not be verified.');
     return receipt;
 }
-function sealPayload(receipt, scopeDigest) {
+export function sealPayload(receipt, scopeDigest) {
     return JSON.stringify({ version: 1, id: receipt.id, receiptSha256: learningSha(JSON.stringify(receipt)), scopeDigest });
 }
 function verifySeal(db, receipt, digest) {

package/dist/coding-types.d.ts

@@ -1,29 +1,5 @@
-import type { CodingContext } from './coding-context.js';
-export type CodingStatus = 'starting' | 'ready' | 'working' | 'needs-input' | 'stopping' | 'interrupted' | 'failed' | 'uncertain' | 'closed';
-export type CodingSession = {
-    id: string;
-    owner: string;
-    generation: number;
-    repo: string;
-    title: string;
-    provider: 'codex';
-    model: string | null;
-    branch: string;
-    base: string;
-    worktree: string;
-    nativeThreadId: string | null;
-    turnId: string | null;
-    status: CodingStatus;
-    error: string | null;
-    createdAt: string;
-    updatedAt: string;
-    deliveryReviewRequired?: boolean;
-    initialRequest?: {
-        requestId: string;
-        prompt: string;
-    };
-    context?: CodingContext;
-};
+export type { CodingSession, CodingStatus } from './contracts/coding-workspace.js';
+import type { CodingSession } from './contracts/coding-workspace.js';
 export type CodingItem = {
     id: string;
     type: string;

package/dist/coding-workspace.d.ts

@@ -60,6 +60,8 @@ export declare class CodingWorkspace {
     constructor(options: Options);
     private authorize;
     private read;
+    /** Preserve legacy reads, but never mutate an unidentified row or save an unreadable record's error projection. */
+    private catalogRow;
     private admit;
     private releaseOperation;
     list(actor: CodingActor): CodingSession[];