toolroll 0.9.52 → 0.9.54

package/dist/chat-flow.d.ts

@@ -1,10 +1,38 @@
+/**
+ * Flow decisions in Slack, Discord and Teams (v88): the Approve / Edit /
+ * Send back that Telegram has (telegram-flow.ts), on the notice itself.
+ *
+ * - The notice carries the draft (split over as many parts as it needs, so
+ *   what is approved is what was read) and the buttons on its last part.
+ * - Approve decides through the same door as the console (decideFlowCard),
+ *   as the paired person, for exactly the visit the notice was about, then
+ *   repaints the notice with what happened and no buttons.
+ * - Edit and Send back open a prompt: the person's next message in their
+ *   chat with Toolroll is the new draft (which comes back with fresh
+ *   buttons) or the note. "cancel" leaves it, and a prompt lapses after
+ *   30 minutes. Chat apps can't all name the message a reply answers, so
+ *   the prompt says plainly what the next message does.
+ *
+ * Every button is one opaque token for one visit of one card, on the part it
+ * rides: a tap on any other message, from anyone but the paired person, or
+ * for a card that moved on, changes nothing.
+ *
+ * A "Send to me" visit (flow-send.ts) is one notice with its links; a "Person
+ * chooses" visit is the same with the zone's own options as buttons. Instead
+ * of a tap, a reply in the notice's thread is the note for where replies go;
+ * the first other message in their chat is asked about once ("Use this as
+ * your note?"), and everything else goes to the lead as usual. Choices are
+ * made through chooseFlowCard, by that person alone, for exactly that visit,
+ * and spend that visit's buttons in every chat app.
+ */
+import type { ChatProvider } from "./contracts/chat-tables.js";
 import { type ChatBinding, type ChatContent, type ChatEvent, type ChatState } from "./chat-delivery-state.js";
 import type { Store } from "./store.js";
 export type ChatFlowAction = "approve" | "edit" | "send-back";
 export declare const CHAT_FLOW_LABELS: Record<ChatFlowAction, string>;
 /** Words kept as written, line breaks and all; only control characters go. */
 export declare function chatFlowText(text: string): string;
-type ChatApp = "slack" | "discord" | "teams";
+type ChatApp = ChatProvider;
 /** A "Send to me" notice as chat parts: what was done, then its links; null when it isn't one. */
 export declare function flowSendParts(store: Store, notification: {
     dedupeKey: string;

package/dist/chat-flow.js

@@ -1,30 +1,3 @@
-/**
- * Flow decisions in Slack, Discord and Teams (v88): the Approve / Edit /
- * Send back that Telegram has (telegram-flow.ts), on the notice itself.
- *
- * - The notice carries the draft (split over as many parts as it needs, so
- *   what is approved is what was read) and the buttons on its last part.
- * - Approve decides through the same door as the console (decideFlowCard),
- *   as the paired person, for exactly the visit the notice was about, then
- *   repaints the notice with what happened and no buttons.
- * - Edit and Send back open a prompt: the person's next message in their
- *   chat with Toolroll is the new draft (which comes back with fresh
- *   buttons) or the note. "cancel" leaves it, and a prompt lapses after
- *   30 minutes. Chat apps can't all name the message a reply answers, so
- *   the prompt says plainly what the next message does.
- *
- * Every button is one opaque token for one visit of one card, on the part it
- * rides: a tap on any other message, from anyone but the paired person, or
- * for a card that moved on, changes nothing.
- *
- * A "Send to me" visit (flow-send.ts) is one notice with its links; a "Person
- * chooses" visit is the same with the zone's own options as buttons. Instead
- * of a tap, a reply in the notice's thread is the note for where replies go;
- * the first other message in their chat is asked about once ("Use this as
- * your note?"), and everything else goes to the lead as usual. Choices are
- * made through chooseFlowCard, by that person alone, for exactly that visit,
- * and spend that visit's buttons in every chat app.
- */
 import { LIMITS } from "./decision.js";
 import { keptDraft } from "./flow-draft.js";
 import { decideFlowCard, flowCardHref, flowDefinitionOf } from "./flow-engine.js";
@@ -77,7 +50,7 @@ function sendLinks(paths) {
 }
 /** The most an item list's part carries here, as the app renders it — a Slack section (2,800), Discord's plain message
  * content (2,000), a Teams message as long as Telegram's — less room for the line a tap adds under it. */
-const ITEMS_LIMIT = { slack: PART_CHARS - 300, discord: 2000 - 300, teams: 4096 - 300 };
+const ITEMS_LIMIT = { slack: PART_CHARS - 300, discord: 2000 - 300, teams: 4096 - 300, telegram: 4096 - 300 };
 /** After research (flow-items.ts): the message with each item numbered under the summary, its words cleaned as every
  * other flow message's are, in as few parts as the app's limit allows (one, unless head, links and tail alone overflow). */
 function itemsText(content, subject, app) {
@@ -129,27 +102,27 @@ export function flowDecisionParts(store, notification, app) {
 /** The live buttons on one part, in the order they were minted: a decision's, a choice's options in their order, or
  * "Use this as your note?" Yes / No. `key` is unique on the part (Slack names each button by it). */
 export function chatFlowButtons(state, part, now) {
-    const decide = state.prepare("SELECT token,action FROM chat_flow_action WHERE part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
+    const decide = state.prepare("SELECT token,action FROM chat_flow_action WHERE provider=:provider AND part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), action: one.action, label: CHAT_FLOW_LABELS[one.action], key: one.action.replace("-", "_") }));
-    const choose = state.prepare("SELECT token,choice,label FROM chat_flow_choice WHERE part=? AND consumed IS NULL AND expires>? ORDER BY choice").all(part, now.toISOString())
+    const choose = state.prepare("SELECT token,choice,label FROM chat_flow_choice WHERE provider=:provider AND part=? AND consumed IS NULL AND expires>? ORDER BY choice").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), action: "choose", label: String(one.label), key: `choose_${Number(one.choice)}` }));
-    const note = state.prepare("SELECT token,answer FROM chat_flow_note WHERE part=? AND consumed IS NULL AND expires>? ORDER BY answer DESC").all(part, now.toISOString())
+    const note = state.prepare("SELECT token,answer FROM chat_flow_note WHERE provider=:provider AND part=? AND consumed IS NULL AND expires>? ORDER BY answer DESC").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), action: "note", label: one.answer === "yes" ? "Yes" : "No", key: `note_${one.answer}` }));
     return [...decide, ...choose, ...note];
 }
 const retire = (state, card, entry, now) => {
-    state.prepare("UPDATE chat_flow_action SET consumed=? WHERE card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
-    state.prepare("UPDATE chat_flow_choice SET consumed=? WHERE card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
-    state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
+    state.prepare("UPDATE chat_flow_action SET consumed=? WHERE provider=:provider AND card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
+    state.prepare("UPDATE chat_flow_choice SET consumed=? WHERE provider=:provider AND card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
+    state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE provider=:provider AND card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
 };
 /** 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 row = state.prepare("SELECT payload FROM chat_part WHERE provider=:provider AND id=?").get(part);
     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(savedChatPart(content), part);
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE provider=:provider AND id=?").run(savedChatPart(content), part);
 }
 /**
  * A tapped flow button, inside the action's transaction. false when the
@@ -158,7 +131,7 @@ function repaint(state, part, event, line) {
  */
 export function applyChatFlowTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
-    const action = state.prepare("SELECT a.*,p.message,e.binding AS owner,e.channel FROM chat_flow_action a JOIN chat_part p ON p.id=a.part JOIN chat_event e ON e.id=p.event WHERE a.token=?").get(token);
+    const action = state.prepare("SELECT a.token,a.part,a.card,a.entry,a.action,a.expires,a.consumed,p.message,e.binding AS owner,e.channel FROM chat_flow_action a JOIN chat_part p ON p.provider=a.provider AND p.id=a.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE a.provider=:provider AND a.token=?").get(token);
     if (action === undefined)
         return applyChatChoiceTap(options, event, binding, token, repos, now) || applyChatNoteTap(options, event, binding, token, repos, now);
     const say = (text) => state.plan(event.id, [{ text }], now);
@@ -202,9 +175,9 @@ export function applyChatFlowTap(options, event, binding, token, repos, now) {
         return true;
     }
     // One open prompt per person: the newest question is the one the next message answers.
-    state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
-    state.prepare("UPDATE chat_question_prompt SET consumed=? WHERE binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
-    state.prepare("INSERT INTO chat_flow_prompt(binding,card,entry,mode,created,expires) VALUES(?,?,?,?,?,?)")
+    state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE provider=:provider AND binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
+    state.prepare("UPDATE chat_question_prompt SET consumed=? WHERE provider=:provider AND binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
+    state.prepare("INSERT INTO chat_flow_prompt(provider,id,binding,card,entry,mode,created,expires) VALUES(:provider,(SELECT COALESCE(MAX(id),0)+1 FROM chat_flow_prompt WHERE provider=:provider),?,?,?,?,?,?)")
         .run(binding.id, card, entry, kind, now.toISOString(), new Date(now.getTime() + PROMPT_MS).toISOString());
     const back = waiting.stage.onFail === null ? "the zone before" : flowDefinitionOf(waiting.flow)?.stages.find(one => one.id === waiting.stage.onFail)?.title ?? waiting.stage.onFail;
     say(kind === "edit"
@@ -215,7 +188,7 @@ export function applyChatFlowTap(options, event, binding, token, repos, now) {
 /** A tapped option of a "Person chooses" notice; false when the token isn't one. */
 function applyChatChoiceTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
-    const tapped = state.prepare("SELECT c.*,p.message,e.binding AS owner,e.channel FROM chat_flow_choice c JOIN chat_part p ON p.id=c.part JOIN chat_event e ON e.id=p.event WHERE c.token=?").get(token);
+    const tapped = state.prepare("SELECT c.token,c.part,c.card,c.entry,c.choice,c.label,c.expires,c.consumed,p.message,e.binding AS owner,e.channel FROM chat_flow_choice c JOIN chat_part p ON p.provider=c.provider AND p.id=c.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE c.provider=:provider AND c.token=?").get(token);
     if (tapped === undefined)
         return false;
     const say = (text) => state.plan(event.id, [{ text }], now);
@@ -270,8 +243,9 @@ function replyAsNote(options, binding, said, cutShort, visit, repos, now) {
 }
 /** The choice a part's message carries, by the message any of its parts was posted as (a long notice is several). */
 function choiceOnMessage(state, binding, channel, message) {
-    const row = state.prepare(`SELECT c.card,c.entry,MAX(c.consumed IS NULL) AS live FROM chat_part p JOIN chat_event e ON e.id=p.event
-    JOIN chat_part q ON q.event=p.event JOIN chat_flow_choice c ON c.part=q.id WHERE e.binding=? AND e.channel=? AND p.message=? GROUP BY c.card,c.entry ORDER BY MAX(c.rowid) DESC LIMIT 1`)
+    const row = state.prepare(`SELECT c.card,c.entry,MAX(c.consumed IS NULL) AS live FROM chat_part p JOIN chat_event e ON e.provider=p.provider AND e.id=p.event
+    JOIN chat_part q ON q.provider=p.provider AND q.event=p.event JOIN chat_flow_choice c ON c.provider=q.provider AND c.part=q.id
+    WHERE p.provider=:provider AND e.binding=? AND e.channel=? AND p.message=? GROUP BY c.card,c.entry ORDER BY MAX(c.rowid) DESC LIMIT 1`)
         .get(binding.id, channel, message);
     return row === undefined ? null : { card: Number(row["card"]), entry: Number(row["entry"]), live: Number(row["live"]) === 1 };
 }
@@ -315,8 +289,8 @@ export function answerChoiceMessage(options, event, binding, input, now, repos)
         if (said === "" || phoneCommand(said) !== null)
             return false;
         // The newest choice of theirs still open here that takes a reply and hasn't asked yet.
-        const open = state.prepare(`SELECT DISTINCT c.card,c.entry FROM chat_flow_choice c JOIN chat_part p ON p.id=c.part JOIN chat_event e ON e.id=p.event
-      WHERE e.binding=? AND c.consumed IS NULL AND c.expires>? AND NOT EXISTS (SELECT 1 FROM chat_flow_note n WHERE n.card=c.card AND n.entry=c.entry) ORDER BY c.rowid DESC`)
+        const open = state.prepare(`SELECT DISTINCT c.card,c.entry FROM chat_flow_choice c JOIN chat_part p ON p.provider=c.provider AND p.id=c.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event
+      WHERE c.provider=:provider AND e.binding=? AND c.consumed IS NULL AND c.expires>? AND NOT EXISTS (SELECT 1 FROM chat_flow_note n WHERE n.provider=c.provider AND n.card=c.card AND n.entry=c.entry) ORDER BY c.rowid DESC`)
             .all(binding.id, now.toISOString());
         for (const one of open) {
             const visit = flowChoiceAt(store, Number(one.card), Number(one.entry));
@@ -327,7 +301,7 @@ export function answerChoiceMessage(options, event, binding, input, now, repos)
             state.plan(event.id, [{ text: `Use this as your note on “${visit.card.title}”?\nYes sends it to ${to}. No passes it to the lead.`,
                     note: { card: visit.card.id, entry: visit.card.entry, held: event.id } }], now);
             // What it said is kept beside its question until answered: the event's own copy is cleared once it is handled.
-            state.prepare("UPDATE chat_flow_note SET words=? WHERE held=?").run(JSON.stringify({ text: input.text, ...(input.originalLength === undefined ? {} : { originalLength: input.originalLength }) }), event.id);
+            state.prepare("UPDATE chat_flow_note SET words=? WHERE provider=:provider AND held=?").run(JSON.stringify({ text: input.text, ...(input.originalLength === undefined ? {} : { originalLength: input.originalLength }) }), event.id);
             return true;
         }
         return false;
@@ -336,7 +310,7 @@ export function answerChoiceMessage(options, event, binding, input, now, repos)
 /** Yes or No to "Use this as your note?"; false when the token isn't one. */
 function applyChatNoteTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
-    const tapped = state.prepare("SELECT n.*,p.message,e.binding AS owner,e.channel FROM chat_flow_note n JOIN chat_part p ON p.id=n.part JOIN chat_event e ON e.id=p.event WHERE n.token=?").get(token);
+    const tapped = state.prepare("SELECT n.token,n.part,n.card,n.entry,n.held,n.words,n.answer,n.expires,n.consumed,p.message,e.binding AS owner,e.channel FROM chat_flow_note n JOIN chat_part p ON p.provider=n.provider AND p.id=n.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE n.provider=:provider AND n.token=?").get(token);
     if (tapped === undefined)
         return false;
     const say = (text) => state.plan(event.id, [{ text }], now);
@@ -350,7 +324,7 @@ function applyChatNoteTap(options, event, binding, token, repos, now) {
         state.finish(event.id);
         return true;
     }
-    state.prepare("UPDATE chat_flow_note SET consumed=?,words=NULL WHERE part=?").run(now.toISOString(), part);
+    state.prepare("UPDATE chat_flow_note SET consumed=?,words=NULL WHERE provider=:provider AND part=?").run(now.toISOString(), part);
     const held = state.event(String(tapped["held"]));
     const kept = typeof tapped["words"] === "string" ? readHeldWords(tapped["words"]) : null;
     const words = kept?.ok === true ? kept.value : null;
@@ -390,12 +364,12 @@ export function answerChatFlowPrompt(options, event, binding, input, repos, now)
     if (event.channel !== binding.channel)
         return false;
     return store.transact(() => {
-        const prompt = state.prepare("SELECT * FROM chat_flow_prompt WHERE binding=? AND consumed IS NULL AND expires>? ORDER BY id DESC LIMIT 1").get(binding.id, now.toISOString());
+        const prompt = state.prepare("SELECT * FROM chat_flow_prompt WHERE provider=:provider AND binding=? AND consumed IS NULL AND expires>? ORDER BY id DESC LIMIT 1").get(binding.id, now.toISOString());
         if (prompt === undefined)
             return false;
         const id = Number(prompt["id"]), card = Number(prompt["card"]), entry = Number(prompt["entry"]), mode = String(prompt["mode"]);
         const say = (text) => state.plan(event.id, [{ text }], now);
-        const close = () => state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE id=?").run(now.toISOString(), id);
+        const close = () => state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE provider=:provider AND id=?").run(now.toISOString(), id);
         const said = input.text.trim();
         if (/^cancel\.?$/i.test(said)) {
             close();

package/dist/chat-messages.d.ts

@@ -0,0 +1,319 @@
+import { ChatCore } from "./chat-core.js";
+import type { Notification, NotificationReceipt, Run, TelegramAction, TelegramBinding, TelegramConversation, TelegramConversationPart, TelegramConversationPartPlan, TelegramDelivery, TelegramDigest, TelegramFlowAction, TelegramFlowChoice, TelegramFlowPrompt, TelegramProposalAction } from "./store.js";
+/** v83: a notification for another person, settled for this destination without sending. */
+export declare const TELEGRAM_SKIPPED_ELSEWHERE = "skipped:for-another-person";
+/** A met promise the lead made on another chat: reported there, settled here without sending. */
+export declare const TELEGRAM_SKIPPED_OTHER_CHAT = "skipped:for-another-chat";
+/** A fact this person is not messaged about: the lead's work, their own act, or a project they muted. */
+export declare const TELEGRAM_SKIPPED_QUIET = "skipped:quiet";
+/** A destination receipt (`d` = notification_delivery) that still owes a
+ * send: not delivered, and not explicitly skipped as pre-pairing history.
+ * Every reader of Telegram receipts that means "undelivered" uses this, so
+ * a skip settles the row without ever pretending to be a delivery. */
+export declare const TELEGRAM_UNSETTLED = "d.delivered_at IS NULL AND (d.receipt IS NULL OR d.receipt NOT LIKE 'skipped:%')";
+/**
+ * Why the store itself holds a Telegram delivery back: authority,
+ * provenance, ordering, a switched-off channel, or a wait it imposed. A
+ * row held for one of these is waiting on policy, not failing on the wire.
+ * Every other error recorded on a receipt came from an actual send, and
+ * THAT is delivery trouble (`pendingForAttention`). One table, so the
+ * fences and the tally can never disagree about the words.
+ */
+export declare const TELEGRAM_HOLD_REASONS: Readonly<{
+    authority: "Telegram pairing or actor authorization changed";
+    destination: "Telegram destination changed";
+    claim: "Telegram delivery claim expired or changed";
+    rateLimit: "Telegram rate limit is still active";
+    resolved: "Notification no longer needs delivery";
+    provenance: "Notification has no trusted project provenance";
+    installation: "Installation notification requires instance access";
+    project: "Notification project is not currently authorized and enrolled";
+    task: "Notification task provenance changed";
+    order: "Earlier task notification is still undelivered";
+    disabled: "Telegram delivery is disabled";
+}>;
+export declare class ChatMessages extends ChatCore {
+    createDecisionAction(action: {
+        token: string;
+        binding: number;
+        decision: number;
+        optionId: string;
+        phase: "choose" | "confirm" | "cancel";
+        chatId: string;
+        messageId?: string;
+        ttlMs?: number;
+        /** Binds an irreversible confirmation to the EXACT note it showed. */
+        noteDigest?: string;
+    }, now: Date): void;
+    /** Which decision an outbound Telegram message carried. Recorded after the
+     * send returns its id; a send whose record was lost routes nothing. */
+    recordDecisionMessage(binding: number, chatId: string, messageId: string, decision: number, now: Date): void;
+    /** The decision behind an exact replied-to message, or nothing. Never "the latest". */
+    decisionForMessage(binding: number, chatId: string, messageId: string): number | null;
+    /** The one live, unexpired draft for a decision, if any. */
+    liveNoteDraft(binding: number, decision: number, now: Date): {
+        id: number;
+        note: string;
+        updateId: number;
+        state: string;
+    } | null;
+    /**
+     * Persist a validated note as the live draft. A newer update SUPERSEDES
+     * the old draft — drafts are immutable, and only a GREATER update_id may
+     * replace one, so out-of-order delivery cannot resurrect an older note
+     * (Codex free-text review, state machine). Returns false when an older
+     * or equal update tried.
+     */
+    saveNoteDraft(draft: {
+        binding: number;
+        decision: number;
+        updateId: number;
+        messageId: string;
+        replyTo: string;
+        note: string;
+    }, now: Date, ttlMs?: number): boolean;
+    /** Move a draft between states; the caller owns the transaction story. */
+    setNoteDraftState(id: number, state: "pending" | "armed" | "superseded" | "consumed" | "discarded"): void;
+    createFlowActions(at: {
+        binding: number;
+        chatId: string;
+        card: number;
+        entry: number;
+    }, actions: readonly {
+        token: string;
+        action: TelegramFlowAction["action"];
+    }[], now: Date, days?: number): void;
+    flowAction(token: string): TelegramFlowAction | null;
+    placeFlowActions(tokens: readonly string[], messageId: string): void;
+    /** Retire every button (and prompt) for one visit of a card, in every chat app: it was decided, or its draft replaced. */
+    retireFlowVisit(card: number, entry: number, now: Date): void;
+    recordFlowPrompt(prompt: TelegramFlowPrompt, now: Date, hours?: number): void;
+    /** The live prompt a message replies to, if any. */
+    flowPrompt(chatId: string, messageId: string, now: Date): TelegramFlowPrompt | null;
+    createFlowChoices(at: {
+        binding: number;
+        chatId: string;
+        card: number;
+        entry: number;
+    }, choices: readonly {
+        token: string;
+        choice: number;
+        label: string;
+    }[], now: Date, days?: number): void;
+    flowChoice(token: string): TelegramFlowChoice | null;
+    placeFlowChoices(tokens: readonly string[], messageId: string): void;
+    createQuestionActions(at: {
+        binding: number;
+        chatId: string;
+        question: number;
+    }, choices: readonly {
+        token: string;
+        choice: string | null;
+    }[], now: Date, days?: number): void;
+    questionAction(token: string): {
+        token: string;
+        binding: number;
+        question: number;
+        choice: string | null;
+        chatId: string;
+        messageId: string | null;
+        expiresAt: string;
+        consumedAt: string | null;
+    } | null;
+    placeQuestionActions(tokens: readonly string[], messageId: string): void;
+    /** Retire every button and prompt for a question, in every chat app: it was answered (anywhere). */
+    retireQuestion(question: number, now: Date): void;
+    recordQuestionPrompt(prompt: {
+        chatId: string;
+        messageId: string;
+        binding: number;
+        question: number;
+    }, now: Date, hours?: number): void;
+    questionPrompt(chatId: string, messageId: string, now: Date): {
+        chatId: string;
+        messageId: string;
+        binding: number;
+        question: number;
+    } | null;
+    decisionAction(token: string): TelegramAction | null;
+    /**
+     * Kill every live confirm/cancel challenge on a decision. Cancel means
+     * cancelled: a confirm that survived its own cancellation would be an
+     * irreversible choice still armed after the person said stop.
+     */
+    consumeChallenges(decision: number, now: Date): void;
+    /** Consume once. False means somebody already did, or it expired — either way, no. */
+    consumeDecisionAction(token: string, now: Date): boolean;
+    /** Stamp the message a choose-action's keyboard actually landed on. */
+    placeDecisionActions(tokens: readonly string[], messageId: string): void;
+    /** A Telegram message this bot sent that showed one task (v79): a reply to
+     * it is about that task (and that result, when it showed one). A message
+     * edited to show something else forgets it. */
+    recordTaskMessage(binding: TelegramBinding, messageId: string, taskId: string | null, run: number | null, now: Date): void;
+    /** v98: an update Telegram pushed, kept (queued, with its body) until the bridge applies it; false when it's already kept or applied. */
+    queueUpdate(botId: string, updateId: number, payload: string, now: Date): boolean;
+    /** v98: pushed updates waiting for the bridge, oldest first. */
+    inbox(botId: string, limit: number): {
+        updateId: number;
+        payload: string;
+    }[];
+    /** A pushed update the bridge is done with: applied (then its receipt stays), or unreadable (then it is gone). */
+    dropInbox(updateId: number): void;
+    /** True if this update has not been applied before. The (provider, id) key is the idempotency; a pushed update waiting
+     * in the inbox is applied in place. A receipt names only its update, as it always has. */
+    markUpdateApplied(updateId: number, result: string, now: Date): boolean;
+    /** Persist one ordinary message before its update is acknowledged (event m<update id>). The caller's transaction also marks the update applied. */
+    enqueueMessage(row: {
+        binding: TelegramBinding;
+        updateId: number;
+        messageId: string;
+        replyTo: string | null;
+        request: string;
+        text: string;
+        context: string | null;
+        taskId: string | null;
+        sourceRun: number | null;
+    }, now: Date): number;
+    /** Whether a message from this chat is already waiting on, or being answered from, this bot message (a tapped question). */
+    messageWaitingOn(binding: number, messageId: string): boolean;
+    getMessage(id: number): TelegramConversation | null;
+    listMessages(botId: string): TelegramConversation[];
+    /**
+     * Claim the oldest message that still needs a turn: queued, or running
+     * under a claim that lapsed (a crash mid-turn), and not deferred past now.
+     * One at a time per bot — the mate runs one turn per approver anyway.
+     */
+    claimMessage(botId: string, owner: string, ttlMs: number, now: Date, only?: "turns" | "replies"): TelegramConversation | null;
+    /** Extend a held claim; false means it lapsed and somebody else may hold the row. */
+    renewMessage(id: number, owner: string, ttlMs: number, now: Date): boolean;
+    /**
+     * Bind the session a turn is about to be dispatched under, BEFORE the
+     * dispatch: the engine receipts the request inside that session, so a
+     * later attempt — after a crash, even after the session was ended and
+     * replaced from the console — reads the receipt where it was written
+     * instead of resolving today's session and finding nothing there.
+     */
+    bindMessageSession(id: number, owner: string, session: number): boolean;
+    /** Bind the admitted turn to its row as soon as the engine's receipt names it. */
+    bindMessageTurn(id: number, owner: string, session: number, turn: number): boolean;
+    /**
+     * Settle a claimed row: done or failed with its outcome word, or back to
+     * queued for a later attempt (a busy engine). Only the claim holder may;
+     * a lapsed claim settles nothing, so a reclaimer's outcome stands.
+     */
+    finishMessage(id: number, owner: string, result: {
+        state: "done" | "failed";
+        outcome: string;
+        replyMessageId?: string | null;
+    } | {
+        state: "queued";
+        outcome: string;
+        nextAttemptAt: string;
+    }, now: Date): boolean;
+    /**
+     * Replies the assistant wrote that still have not reached the person
+     * `since` ago or longer (status and the console show them with a Retry):
+     * the message's row, whose it is, when the oldest unsent part was
+     * written, and the last send error.
+     */
+    unsentReplies(botId: string | null, approver: string | null, since: Date): {
+        conversation: number;
+        approver: string;
+        since: string;
+        error: string | null;
+    }[];
+    /** Send unsent replies on the next bridge pass instead of waiting out their backoff; returns how many. */
+    retryReplies(approver: string | null, now: Date): number;
+    /**
+     * Persist the whole outbound half of a turn — every reply part and every
+     * card, with the cards' tokens already minted — in one transaction, BEFORE
+     * any send. Only the claim holder may, and only once: a row that already
+     * has parts keeps them (a retry resumes, never re-plans). The turn's
+     * identity rides the row too, so the parts answer to exactly that turn.
+     */
+    planReplyParts(id: number, owner: string, turn: {
+        session: number;
+        turn: number;
+    }, parts: readonly TelegramConversationPartPlan[], now: Date): boolean;
+    replyParts(conversation: number): TelegramConversationPart[];
+    /**
+     * Settle one send attempt under the row's claim. A confirmed message id
+     * is the only success: the part is sent, and a reply part's id becomes
+     * the row's reply id. Anything else leaves the part pending with its
+     * attempt counted, its error named, its next attempt scheduled, and —
+     * when the answer was lost rather than refused — its uncertainty counted.
+     * A lapsed claim settles nothing, so a reclaimer's outcome stands.
+     */
+    settleReplyPart(conversation: number, ordinal: number, owner: string, outcome: {
+        ok: true;
+        messageId: string;
+    } | {
+        ok: false;
+        error: string;
+        uncertain: boolean;
+        retryAt: string;
+    }, now: Date): boolean;
+    /** A card whose proposal no longer waits (confirmed or dismissed from another surface, or gone) is moot: dropped with the reason, never sent. */
+    dropReplyPart(conversation: number, ordinal: number, owner: string, reason: string, now: Date): boolean;
+    /** The exact task/run bindings of one outbound message this bot sent: a
+     * plain fact names one, a digest part may name several, (v64) a confirmed
+     * result image names its exact task and run, the lead's reply names the
+     * task its turn was about, a card names its task, and (v79) a status
+     * message names the task it showed. */
+    messageBindings(binding: TelegramBinding, messageId: string): {
+        taskId: string | null;
+        taskRef: number | null;
+        run: number | null;
+        project: string | null;
+    }[];
+    createProposalAction(action: {
+        token: string;
+        binding: number;
+        proposal: number;
+        phase: TelegramProposalAction["phase"];
+        chatId: string;
+        messageId?: string;
+        ttlMs?: number;
+    }, now: Date): void;
+    proposalAction(token: string): TelegramProposalAction | null;
+    /** Consume once. False means somebody already did, or it expired. */
+    consumeProposalAction(token: string, now: Date): boolean;
+    /** Kill every live token on a proposal — after it resolves, or when a challenge is cancelled. */
+    consumeProposalActions(proposal: number, now: Date, phases?: readonly TelegramProposalAction["phase"][]): void;
+    /** Stamp the message a card's keyboard actually landed on. */
+    placeProposalActions(tokens: readonly string[], messageId: string): void;
+    destination(binding: TelegramBinding): string;
+    /** A progress card belongs to one builder result, including its root review.
+     * Do not combine planners, correction children, or separate build attempts. */
+    progressRun(row: Pick<Notification, "taskRef" | "run">): Run | null;
+    /** Reuse a confirmed message in this exact destination. A mixed digest,
+     * decision, image, or message naming another attempt is never editable. The
+     * outbound history survives a restart even if the final receipt was lost. */
+    progressMessage(binding: TelegramBinding, result: Run): string | null;
+    /** The existing outbox, with a separate receipt for this exact pairing. */
+    claimDeliveries(binding: TelegramBinding, owner: string, ttlMs: number, now: Date, only?: "all" | "urgent"): TelegramDelivery[];
+    /** Synchronous final fence, called AFTER each asynchronous enrollment read. */
+    deliveryProblem(row: TelegramDelivery, binding: TelegramBinding, owner: string, projects: readonly string[], now: Date, batch?: readonly number[]): string | null;
+    claimHeld(row: TelegramDelivery, owner: string, now: Date): boolean;
+    /** A confirmed network message remains history even if authority changed
+     * while it was in flight. It only binds the OLD destination, never new work. */
+    recordMessage(row: TelegramDelivery, binding: TelegramBinding, messageId: string, now: Date): void;
+    /** The newest confirmed message this notification became at one destination, if any. */
+    messageOf(notification: number, destination: string): string | null;
+    finalizeDelivery(row: TelegramDelivery, binding: TelegramBinding, owner: string, outcome: {
+        ok: true;
+        receipt: string | null;
+    } | {
+        ok: false;
+        error: string;
+        retryAt?: string;
+    }, now: Date): boolean;
+    /** The notifications this pairing holds, each with its delivery state there. */
+    deliveries(binding: TelegramBinding): NotificationReceipt[];
+    /** The digest cadence: null everyMs = off. */
+    digest(): TelegramDigest;
+    /** Set (or clear, with null) the cadence. Turning it on starts the
+     * window NOW — nothing held before the choice is dumped at once. */
+    setDigest(everyMs: number | null, by: string, now: Date): void;
+    markDigestSent(now: Date): void;
+}