toolroll 0.9.53 → 0.9.54

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.9.54 — 2026-10-09
+
+- **One chat core.** Telegram, Slack, Discord and Teams now share one chat
+  core, and 70 old chat tables are gone.
+- **Nothing to redo.** Chat history and pairings carry over on upgrade.
+- **Consent stays put.** An existing approval consent still covers only the
+  chat providers it named.
+
 ## 0.9.53 — 2026-10-08
 
 - **Fewer features to learn.** Contests, held sessions and fallback chains

package/dist/chat-ask.js

@@ -7,14 +7,14 @@ export function chatAskText(ask) {
 /** The live buttons on one part, in the order they were minted: the options, then "Something else". None when the part
  * is not in its owner's own chat with Toolroll (a room), where a tap could not be their message. */
 export function chatAskButtons(state, part, now) {
-    const row = state.prepare("SELECT p.payload,e.channel,b.channel AS own FROM chat_part p JOIN chat_event e ON e.id=p.event JOIN chat_binding b ON b.id=e.binding WHERE p.id=?").get(part);
+    const row = state.prepare("SELECT p.payload,e.channel,b.channel AS own FROM chat_part p JOIN chat_event e ON e.provider=p.provider AND e.id=p.event JOIN chat_binding b ON b.provider=e.provider AND b.id=e.binding WHERE p.provider=:provider AND p.id=?").get(part);
     if (row === undefined)
         return [];
     const content = partContent(String(row["payload"]));
     if ((content.channel ?? row["channel"]) !== row["own"])
         return [];
     const options = content.ask?.options ?? [];
-    return state.prepare("SELECT token,choice FROM chat_ask_action WHERE part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
+    return state.prepare("SELECT token,choice FROM chat_ask_action WHERE provider=:provider AND part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
         .map(one => {
         const label = one.choice === null ? MATE_ASK_OTHER : options[Number(one.choice)] ?? null;
         return label === null ? null : { token: String(one.token), label: label.slice(0, 75), words: one.choice === null };
@@ -27,20 +27,20 @@ const EDIT_WINDOW_MS = 86_400_000;
 /** Show the question again with what happened, and without its buttons: one edit, under the part's own time. A question
  * too old to edit gets the line once as a new message instead. */
 function repaint(state, part, event, line, now) {
-    const row = state.prepare("SELECT payload,created FROM chat_part WHERE id=?").get(part);
+    const row = state.prepare("SELECT payload,created FROM chat_part WHERE provider=:provider AND id=?").get(part);
     if (row === undefined || new Date(String(row["created"])).getTime() + EDIT_WINDOW_MS <= now.getTime()) {
         state.plan(event.id, [{ text: line }], now);
         return;
     }
     const before = partContent(String(row["payload"]));
     const content = { text: `${before.text}\n\n${line}`.slice(0, 3400), edit: event.ts, ...(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);
     state.finish(event.id);
 }
 /** A tapped ask button, inside the action's transaction; false when the token isn't one. */
 export function applyChatAskTap(options, event, binding, token, now) {
     const { store, state } = options;
-    const action = state.prepare("SELECT a.*,p.message,e.binding AS owner,e.channel FROM chat_ask_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.turn,a.choice,a.expires,a.consumed,p.message,e.binding AS owner,e.channel FROM chat_ask_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 false;
     const say = (text) => state.plan(event.id, [{ text }], now);
@@ -64,7 +64,7 @@ export function applyChatAskTap(options, event, binding, token, now) {
         return true;
     }
     if (found.state !== "open" || expired) {
-        state.prepare("UPDATE chat_ask_action SET consumed=? WHERE part=? AND consumed IS NULL").run(now.toISOString(), part);
+        state.prepare("UPDATE chat_ask_action SET consumed=? WHERE provider=:provider AND part=? AND consumed IS NULL").run(now.toISOString(), part);
         // The question is shown again without its buttons, so a later tap has nothing to press.
         repaint(state, part, event, found.state === "answered" ? "This question was already answered." : "This question expired. If it still matters, send your answer as a message.", now);
         return true;
@@ -79,10 +79,10 @@ export function applyChatAskTap(options, event, binding, token, now) {
         say("That option is no longer there.");
         return true;
     }
-    state.prepare("UPDATE chat_ask_action SET consumed=? WHERE part=? AND consumed IS NULL").run(now.toISOString(), part);
+    state.prepare("UPDATE chat_ask_action SET consumed=? WHERE provider=:provider AND part=? AND consumed IS NULL").run(now.toISOString(), part);
     // The option is the owner's next message, answered like one they typed.
     state.enqueue({
-        id: chatHash(`${state.channel}:ask:${event.id}`).slice(0, 32), installation: event.installation, binding: binding.id, kind: "message",
+        id: chatHash(`${state.provider}:ask:${event.id}`).slice(0, 32), installation: event.installation, binding: binding.id, kind: "message",
         channel: event.channel, member: event.member, ts: event.ts, thread: event.thread,
         payload: { text: option, originalLength: option.length }, created: now.toISOString(),
     });

package/dist/chat-core.d.ts

@@ -0,0 +1,171 @@
+import type { ChatProvider } from "./contracts/chat-tables.js";
+import type { Database, Statement, Store } from "./store.js";
+export type { ChatProvider };
+/** One person's chat in one app (chat_binding). */
+export type ChatBinding = {
+    provider: ChatProvider;
+    id: number;
+    installation: string;
+    team: string;
+    app: string;
+    member: string;
+    channel: string;
+    approver: string;
+    generation: number;
+    created: string;
+    created_by: string | null;
+    pair_event: string | null;
+    revoked: string | null;
+    revoked_by: string | null;
+};
+export type ChatRoom = {
+    id: number;
+    installation: string;
+    chat: string;
+    kind: "group" | "private";
+    conversation: string;
+    boundBy: string;
+    boundAt: string;
+    binding: number;
+    cursor: number;
+};
+export type PairingResult = {
+    ok: true;
+    binding: ChatBinding;
+    replay: boolean;
+    first: boolean;
+} | {
+    ok: false;
+    reason: "unknown-code" | "already-bound";
+};
+export type LeaseResult = {
+    ok: true;
+    generation: number;
+    cursor: number;
+} | {
+    ok: false;
+    reason: "busy";
+    holder: string;
+    until: string;
+};
+export declare const chatHash: (text: string) => string;
+export declare const PAIRING_CODE_TTL_MS: number;
+/** Tables whose rows carry a per-provider number the core assigns. */
+type Numbered = "chat_binding" | "chat_part" | "chat_room" | "chat_flow_prompt" | "chat_question_prompt" | "chat_note_draft";
+export declare function readChatBinding(row: Record<string, unknown>): ChatBinding;
+export declare class ChatCore {
+    readonly store: Store;
+    readonly provider: ChatProvider;
+    constructor(store: Store, provider: ChatProvider);
+    get db(): Database;
+    /** A statement bound to this provider. Its SQL must name `:provider`; one that doesn't is refused before it runs. */
+    prepare(sql: string): Statement;
+    /** The next number in this provider's run of a table (rows keep the numbers they were given). */
+    nextId(table: Numbered): number;
+    /** Every unrevoked binding of an installation, oldest first (liveness is checked per binding with `live`). */
+    bindings(installation: string): ChatBinding[];
+    /** The unrevoked binding one member holds, if any. */
+    bindingFor(installation: string, member: string): ChatBinding | null;
+    /** The exact binding, while unrevoked. */
+    bindingById(id: number): ChatBinding | null;
+    /** The oldest unrevoked binding: the single-person reading kept for status lines and fixtures. */
+    binding(installation: string): ChatBinding | null;
+    /** Unrevoked, and its person still an approver, unrevoked, at the generation it was paired under. */
+    live(binding: Pick<ChatBinding, "id" | "approver" | "generation">): boolean;
+    /** Every live binding of an installation, oldest first. */
+    liveBindings(installation: string): ChatBinding[];
+    /** Mint-time half of pairing: a fresh code replaces this person's outstanding ones (a teammate's stay theirs). */
+    savePairing(code: {
+        hash: string;
+        installation: string | null;
+        approver: string;
+        generation: number;
+        by: string;
+    }, now: Date, ttlMs?: number): void;
+    /**
+     * Consume a code and create the binding, in one transaction, by the same rules in every app: the code is unexpired,
+     * unconsumed and for this installation; its person is still an approver at the generation it was minted under; the
+     * member holds no other live pairing here, and the person no other live pairing on this installation. The
+     * conditional UPDATE is the consumption: exactly one caller wins however many race. The same event replayed (an app
+     * redelivering) finds its finished binding. Success retires the person's other outstanding codes. `first`: the
+     * member never paired with this installation before (a first pairing starts its notifications from now).
+     */
+    consumePairing(attempt: {
+        hash: string;
+        installation: string;
+        team: string;
+        app: string;
+        member: string;
+        channel: string;
+        event: string | null;
+    }, now: Date): PairingResult;
+    /** End one person's pairing and everything their chat could still do: its buttons, prompts, queued messages and unsent parts. */
+    revokeBinding(binding: Pick<ChatBinding, "id">, now?: Date, by?: string | null): boolean;
+    /** End every pairing of an installation (its app was disconnected), and every code still waiting for one. */
+    revoke(installation: string, now?: Date, by?: string | null): void;
+    room(installation: string, chat: string): ChatRoom | null;
+    rooms(installation: string): ChatRoom[];
+    /**
+     * Point a chat at a team conversation: an earlier choice for the same chat is revoked in the same transaction, and
+     * delivery starts from now (the conversation's history is read in the console, never replayed into a chat that
+     * just arrived). A conversation another group of this app already follows refuses.
+     */
+    bindRoom(args: {
+        installation: string;
+        chat: string;
+        kind: "group" | "private";
+        conversation: string;
+        by: string;
+        binding: number;
+    }, now: Date): {
+        ok: true;
+        room: ChatRoom;
+    } | {
+        ok: false;
+        reason: "group-taken";
+    };
+    unbindRoom(installation: string, chat: string, by: string, now: Date): boolean;
+    /** Forward only: a cursor never moves back, and a revoked room keeps its last position. */
+    advanceRoomCursor(id: number, messageId: number): boolean;
+    /** The shared rooms engine's view of this installation's rooms (chat-rooms.ts). */
+    roomBackend(installation: string, now: Date): import("./chat-rooms.js").RoomBackend;
+    /**
+     * Take or renew the installation's one worker lease. A holder renews at its generation; an expired holder is taken
+     * over at the next generation, and the poll cursor rides the lease, so a stale generation can neither poll nor move it.
+     */
+    acquire(installation: string, owner: string, ttlMs: number, now: Date): LeaseResult;
+    /** Hand the lease back (it ends now), so the next worker is not told busy for the rest of its time. */
+    release(installation: string, owner: string, now: Date): void;
+    owns(installation: string, owner: string, now?: Date): boolean;
+    /** The poll cursor moves forward only, and only under the generation that read it. */
+    advanceCursor(installation: string, owner: string, generation: number, cursor: number, now: Date): boolean;
+    /** When the app said to wait (a rate limit): "" when it hasn't. */
+    retryAt(installation: string): string;
+    /** Wait at least until then before the next send; a later wait already asked for stands. */
+    deferUntil(installation: string, until: string): void;
+    /** What is wrong with the connection right now (null: nothing), as the lease holder last saw it. */
+    setProblem(installation: string, owner: string, problem: string | null): void;
+    /** The worker reached the app. */
+    setConnected(installation: string, owner: string, now: Date): void;
+    /** The worker stopped: no holder, no connection. */
+    stop(installation: string, owner: string): void;
+    /** The connection as settings show it. */
+    runtime(installation: string): {
+        connected: string | null;
+        problem: string | null;
+        leaseUntil: string | null;
+    } | null;
+    /** Where the app pushes this installation's updates (null: the worker asks for them), and what's wrong, if anything. */
+    setPush(installation: string, push: {
+        url: string | null;
+        problem: string | null;
+    }, now: Date): void;
+    push(installation: string): {
+        url: string | null;
+        problem: string | null;
+        at: string | null;
+    } | null;
+    /** Small transport facts an app must remember per chat (a Teams service URL). Never credentials. */
+    meta(installation: string, key: string): string | null;
+    setMeta(installation: string, key: string, value: string, now: Date): void;
+}

package/dist/chat-core.js

@@ -0,0 +1,288 @@
+/**
+ * The chat core every app shares (Telegram, Slack, Discord, Teams): who is paired, the one-time codes that pair
+ * them, the rooms they follow, one live worker per installation, and the small facts a transport remembers. One
+ * object is bound to one provider, and every query it runs names that provider (`:provider`), so an id or a member
+ * from one app never reaches another app's rows. Adapters keep only their transport: sign-in, receiving (webhooks or
+ * polling), formatting and sending.
+ *
+ * Imports the store's types only, so the store can build its Telegram methods on it.
+ */
+import { createHash } from "node:crypto";
+export const chatHash = (text) => createHash("sha256").update(text).digest("hex");
+export const PAIRING_CODE_TTL_MS = 10 * 60_000;
+const str = (value) => (value === null || value === undefined ? null : String(value));
+export function readChatBinding(row) {
+    return {
+        provider: String(row["provider"]), id: Number(row["id"]), installation: String(row["installation"]),
+        team: String(row["team"]), app: String(row["app"]), member: String(row["member"]), channel: String(row["channel"]),
+        approver: String(row["approver"]), generation: Number(row["generation"]), created: String(row["created"]),
+        created_by: str(row["created_by"]), pair_event: str(row["pair_event"]), revoked: str(row["revoked"]), revoked_by: str(row["revoked_by"]),
+    };
+}
+function readRoom(row) {
+    return { id: Number(row["id"]), installation: String(row["installation"]), chat: String(row["chat"]), kind: row["kind"] === "group" ? "group" : "private",
+        conversation: String(row["conversation"]), boundBy: String(row["bound_by"]), boundAt: String(row["bound"]), binding: Number(row["binding"]), cursor: Number(row["cursor"]) };
+}
+export class ChatCore {
+    store;
+    provider;
+    constructor(store, provider) {
+        this.store = store;
+        this.provider = provider;
+    }
+    get db() {
+        return this.store.handle;
+    }
+    /** A statement bound to this provider. Its SQL must name `:provider`; one that doesn't is refused before it runs. */
+    prepare(sql) {
+        if (!/:provider\b/.test(sql))
+            throw new Error(`a chat query must name its provider: ${sql.slice(0, 80)}`);
+        const statement = this.db.prepare(sql), bound = { provider: this.provider };
+        return {
+            run: (...params) => statement.run(bound, ...params),
+            get: (...params) => statement.get(bound, ...params),
+            all: (...params) => statement.all(bound, ...params),
+        };
+    }
+    /** The next number in this provider's run of a table (rows keep the numbers they were given). */
+    nextId(table) {
+        return Number(this.prepare(`SELECT COALESCE(MAX(id), 0) + 1 AS n FROM ${table} WHERE provider = :provider`).get()?.["n"] ?? 1);
+    }
+    // ---- pairings ---------------------------------------------------------------------------------------------------
+    /** Every unrevoked binding of an installation, oldest first (liveness is checked per binding with `live`). */
+    bindings(installation) {
+        return this.prepare("SELECT * FROM chat_binding WHERE provider = :provider AND installation = ? AND revoked IS NULL ORDER BY id")
+            .all(installation).map(readChatBinding);
+    }
+    /** The unrevoked binding one member holds, if any. */
+    bindingFor(installation, member) {
+        const row = this.prepare("SELECT * FROM chat_binding WHERE provider = :provider AND installation = ? AND member = ? AND revoked IS NULL").get(installation, member);
+        return row === undefined ? null : readChatBinding(row);
+    }
+    /** The exact binding, while unrevoked. */
+    bindingById(id) {
+        const row = this.prepare("SELECT * FROM chat_binding WHERE provider = :provider AND id = ? AND revoked IS NULL").get(id);
+        return row === undefined ? null : readChatBinding(row);
+    }
+    /** The oldest unrevoked binding: the single-person reading kept for status lines and fixtures. */
+    binding(installation) {
+        return this.bindings(installation)[0] ?? null;
+    }
+    /** Unrevoked, and its person still an approver, unrevoked, at the generation it was paired under. */
+    live(binding) {
+        const current = this.bindingById(binding.id);
+        const account = this.store.accountOf(binding.approver);
+        return current !== null && current.approver === binding.approver && current.generation === binding.generation &&
+            account?.role === "approver" && account.revokedAt === null && account.generation === binding.generation;
+    }
+    /** Every live binding of an installation, oldest first. */
+    liveBindings(installation) {
+        return this.bindings(installation).filter(binding => this.live(binding));
+    }
+    /** Mint-time half of pairing: a fresh code replaces this person's outstanding ones (a teammate's stay theirs). */
+    savePairing(code, now, ttlMs = PAIRING_CODE_TTL_MS) {
+        this.store.transact(() => {
+            this.prepare("UPDATE chat_pair SET consumed = ? WHERE provider = :provider AND approver = ? AND consumed IS NULL").run(now.toISOString(), code.approver);
+            this.prepare("INSERT INTO chat_pair (provider, hash, installation, approver, generation, created, created_by, expires) VALUES (:provider, ?, ?, ?, ?, ?, ?, ?)")
+                .run(code.hash, code.installation, code.approver, code.generation, now.toISOString(), code.by, new Date(now.getTime() + ttlMs).toISOString());
+        });
+    }
+    /**
+     * Consume a code and create the binding, in one transaction, by the same rules in every app: the code is unexpired,
+     * unconsumed and for this installation; its person is still an approver at the generation it was minted under; the
+     * member holds no other live pairing here, and the person no other live pairing on this installation. The
+     * conditional UPDATE is the consumption: exactly one caller wins however many race. The same event replayed (an app
+     * redelivering) finds its finished binding. Success retires the person's other outstanding codes. `first`: the
+     * member never paired with this installation before (a first pairing starts its notifications from now).
+     */
+    consumePairing(attempt, now) {
+        return this.store.transact(() => {
+            const stamp = now.toISOString();
+            const code = this.prepare("SELECT * FROM chat_pair WHERE provider = :provider AND hash = ?").get(attempt.hash);
+            if (code === undefined || (code["installation"] !== null && code["installation"] !== attempt.installation))
+                return { ok: false, reason: "unknown-code" };
+            if (code["consumed"] !== null) {
+                const mine = attempt.event !== null && code["consumed_event"] === attempt.event && code["consumed_member"] === attempt.member && code["consumed_channel"] === attempt.channel;
+                const live = mine ? this.bindingFor(attempt.installation, attempt.member) : null;
+                return live !== null && live.channel === attempt.channel && this.live(live)
+                    ? { ok: true, binding: live, replay: true, first: false }
+                    : { ok: false, reason: "unknown-code" };
+            }
+            if (String(code["expires"]) <= stamp)
+                return { ok: false, reason: "unknown-code" };
+            const approver = String(code["approver"]), generation = Number(code["generation"]);
+            const account = this.store.accountOf(approver);
+            if (account?.role !== "approver" || account.revokedAt !== null || account.generation !== generation)
+                return { ok: false, reason: "unknown-code" };
+            if (this.bindingFor(attempt.installation, attempt.member) !== null)
+                return { ok: false, reason: "already-bound" };
+            if (this.bindings(attempt.installation).some(one => one.approver === approver && this.live(one)))
+                return { ok: false, reason: "already-bound" };
+            const consumed = this.prepare(`UPDATE chat_pair SET consumed = ?, consumed_channel = ?, consumed_member = ?, consumed_event = ?
+        WHERE provider = :provider AND hash = ? AND consumed IS NULL AND expires > ?`).run(stamp, attempt.channel, attempt.member, attempt.event, attempt.hash, stamp);
+            if (Number(consumed.changes) !== 1)
+                return { ok: false, reason: "unknown-code" };
+            this.prepare("UPDATE chat_pair SET consumed = ? WHERE provider = :provider AND approver = ? AND consumed IS NULL").run(stamp, approver);
+            const first = this.prepare("SELECT 1 AS hit FROM chat_binding WHERE provider = :provider AND installation = ? AND member = ? LIMIT 1").get(attempt.installation, attempt.member) === undefined;
+            const id = this.nextId("chat_binding");
+            this.prepare(`INSERT INTO chat_binding (provider, id, installation, team, app, member, channel, approver, generation, created, created_by, pair_event)
+        VALUES (:provider, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, attempt.installation, attempt.team, attempt.app, attempt.member, attempt.channel, approver, generation, stamp, approver, attempt.event);
+            return { ok: true, binding: this.bindingById(id), replay: false, first };
+        });
+    }
+    /** End one person's pairing and everything their chat could still do: its buttons, prompts, queued messages and unsent parts. */
+    revokeBinding(binding, now = new Date(), by = null) {
+        return this.store.transact(() => {
+            const stamp = now.toISOString();
+            const revoked = Number(this.prepare("UPDATE chat_binding SET revoked = ?, revoked_by = ? WHERE provider = :provider AND id = ? AND revoked IS NULL").run(stamp, by, binding.id).changes) > 0;
+            this.prepare("UPDATE chat_action SET consumed = ? WHERE provider = :provider AND binding = ? AND consumed IS NULL").run(stamp, binding.id);
+            for (const table of ["chat_flow_action", "chat_flow_choice", "chat_question_action"])
+                this.prepare(`UPDATE ${table} SET consumed = ? WHERE provider = :provider AND binding = ? AND consumed IS NULL`).run(stamp, binding.id);
+            for (const table of ["chat_flow_prompt", "chat_question_prompt"])
+                this.prepare(`UPDATE ${table} SET consumed = ? WHERE provider = :provider AND binding = ? AND consumed IS NULL`).run(stamp, binding.id);
+            this.prepare("UPDATE chat_event SET state = 'dropped', payload = '{}', problem = 'Chat disconnected', result = COALESCE(result, 'revoked') WHERE provider = :provider AND binding = ? AND state = 'queued'").run(binding.id);
+            this.prepare(`UPDATE chat_part SET state = 'dropped', problem = 'Chat disconnected' WHERE provider = :provider AND state = 'pending'
+        AND event IN (SELECT id FROM chat_event WHERE provider = :provider AND binding = ?)`).run(binding.id);
+            return revoked;
+        });
+    }
+    /** End every pairing of an installation (its app was disconnected), and every code still waiting for one. */
+    revoke(installation, now = new Date(), by = null) {
+        this.store.transact(() => {
+            for (const binding of this.bindings(installation))
+                this.revokeBinding(binding, now, by);
+            this.prepare("UPDATE chat_pair SET consumed = ? WHERE provider = :provider AND (installation = ? OR installation IS NULL) AND consumed IS NULL").run(now.toISOString(), installation);
+            this.prepare("UPDATE chat_event SET state = 'dropped', payload = '{}', problem = 'Chat disconnected', result = COALESCE(result, 'revoked') WHERE provider = :provider AND installation = ? AND state = 'queued' AND kind <> 'update'").run(installation);
+            this.prepare(`UPDATE chat_part SET state = 'dropped', problem = 'Chat disconnected' WHERE provider = :provider AND state = 'pending'
+        AND event IN (SELECT id FROM chat_event WHERE provider = :provider AND installation = ?)`).run(installation);
+        });
+    }
+    // ---- rooms (team conversations) ---------------------------------------------------------------------------------
+    room(installation, chat) {
+        const row = this.prepare("SELECT * FROM chat_room WHERE provider = :provider AND installation = ? AND chat = ? AND revoked IS NULL").get(installation, chat);
+        return row === undefined ? null : readRoom(row);
+    }
+    rooms(installation) {
+        return this.prepare("SELECT * FROM chat_room WHERE provider = :provider AND installation = ? AND revoked IS NULL ORDER BY id").all(installation).map(readRoom);
+    }
+    /**
+     * Point a chat at a team conversation: an earlier choice for the same chat is revoked in the same transaction, and
+     * delivery starts from now (the conversation's history is read in the console, never replayed into a chat that
+     * just arrived). A conversation another group of this app already follows refuses.
+     */
+    bindRoom(args, now) {
+        return this.store.transact(() => this.store.savepoint(() => {
+            const stamp = now.toISOString();
+            if (args.kind === "group") {
+                const group = this.prepare("SELECT installation, chat FROM chat_room WHERE provider = :provider AND conversation = ? AND kind = 'group' AND revoked IS NULL").get(args.conversation);
+                if (group !== undefined && (group["installation"] !== args.installation || group["chat"] !== args.chat))
+                    return { ok: false, reason: "group-taken" };
+            }
+            this.prepare("UPDATE chat_room SET revoked = ?, revoked_by = ? WHERE provider = :provider AND installation = ? AND chat = ? AND revoked IS NULL").run(stamp, args.by, args.installation, args.chat);
+            const thread = this.db.prepare("SELECT thread FROM team_conversation WHERE id = ?").get(args.conversation);
+            if (thread === undefined)
+                throw new Error("no such team conversation");
+            const cursor = Number(this.db.prepare("SELECT COALESCE(MAX(id), 0) AS n FROM mate_message WHERE thread = ?").get(Number(thread["thread"]))?.["n"] ?? 0);
+            this.prepare("INSERT INTO chat_room (provider, id, installation, chat, kind, conversation, binding, bound_by, bound, cursor) VALUES (:provider, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(this.nextId("chat_room"), args.installation, args.chat, args.kind, args.conversation, args.binding, args.by, stamp, cursor);
+            return { ok: true, room: this.room(args.installation, args.chat) };
+        }));
+    }
+    unbindRoom(installation, chat, by, now) {
+        return Number(this.prepare("UPDATE chat_room SET revoked = ?, revoked_by = ? WHERE provider = :provider AND installation = ? AND chat = ? AND revoked IS NULL").run(now.toISOString(), by, installation, chat).changes) > 0;
+    }
+    /** Forward only: a cursor never moves back, and a revoked room keeps its last position. */
+    advanceRoomCursor(id, messageId) {
+        return Number(this.prepare("UPDATE chat_room SET cursor = ? WHERE provider = :provider AND id = ? AND cursor < ? AND revoked IS NULL").run(messageId, id, messageId).changes) > 0;
+    }
+    /** The shared rooms engine's view of this installation's rooms (chat-rooms.ts). */
+    roomBackend(installation, now) {
+        const roomOf = (room) => room === null ? null : { id: room.id, chatId: room.chat, kind: room.kind, conversation: room.conversation, boundBy: room.boundBy, binding: room.binding, cursor: room.cursor };
+        return {
+            room: chat => roomOf(this.room(installation, chat)),
+            bind: args => {
+                const bound = this.bindRoom({ installation, chat: args.chatId, kind: args.kind, conversation: args.conversation, by: args.by, binding: args.binding }, now);
+                return bound.ok ? { ok: true } : bound;
+            },
+            unbind: (chat, by) => this.unbindRoom(installation, chat, by, now),
+            grant: id => { const binding = this.bindingById(id); return binding === null || !this.live(binding) ? null : { approver: binding.approver, generation: binding.generation, chatId: binding.channel }; },
+        };
+    }
+    // ---- the worker -------------------------------------------------------------------------------------------------
+    /**
+     * Take or renew the installation's one worker lease. A holder renews at its generation; an expired holder is taken
+     * over at the next generation, and the poll cursor rides the lease, so a stale generation can neither poll nor move it.
+     */
+    acquire(installation, owner, ttlMs, now) {
+        return this.store.transact(() => {
+            const stamp = now.toISOString(), until = new Date(now.getTime() + ttlMs).toISOString();
+            const row = this.prepare("SELECT * FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation);
+            if (row === undefined) {
+                this.prepare("INSERT INTO chat_runtime (provider, installation, owner, lease_until, generation, heartbeat) VALUES (:provider, ?, ?, ?, 1, ?)").run(installation, owner, until, stamp);
+                return { ok: true, generation: 1, cursor: 0 };
+            }
+            const holder = str(row["owner"]), held = holder !== null && str(row["lease_until"]) !== null && String(row["lease_until"]) > stamp;
+            if (held && holder !== owner)
+                return { ok: false, reason: "busy", holder: holder, until: String(row["lease_until"]) };
+            const generation = held ? Number(row["generation"]) : Number(row["generation"]) + 1;
+            this.prepare("UPDATE chat_runtime SET owner = ?, lease_until = ?, generation = ?, heartbeat = ? WHERE provider = :provider AND installation = ?").run(owner, until, generation, stamp, installation);
+            return { ok: true, generation, cursor: Number(row["cursor"]) };
+        });
+    }
+    /** Hand the lease back (it ends now), so the next worker is not told busy for the rest of its time. */
+    release(installation, owner, now) {
+        this.prepare("UPDATE chat_runtime SET lease_until = ? WHERE provider = :provider AND installation = ? AND owner = ?").run(now.toISOString(), installation, owner);
+    }
+    owns(installation, owner, now = new Date()) {
+        return this.prepare("SELECT 1 AS hit FROM chat_runtime WHERE provider = :provider AND installation = ? AND owner = ? AND lease_until > ?").get(installation, owner, now.toISOString()) !== undefined;
+    }
+    /** The poll cursor moves forward only, and only under the generation that read it. */
+    advanceCursor(installation, owner, generation, cursor, now) {
+        return Number(this.prepare(`UPDATE chat_runtime SET cursor = ?, heartbeat = ? WHERE provider = :provider AND installation = ? AND owner = ? AND generation = ? AND cursor < ?`)
+            .run(cursor, now.toISOString(), installation, owner, generation, cursor).changes) > 0;
+    }
+    /** When the app said to wait (a rate limit): "" when it hasn't. */
+    retryAt(installation) {
+        return String(this.prepare("SELECT retry_at FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation)?.["retry_at"] ?? "");
+    }
+    /** Wait at least until then before the next send; a later wait already asked for stands. */
+    deferUntil(installation, until) {
+        this.prepare(`INSERT INTO chat_runtime (provider, installation, retry_at) VALUES (:provider, ?, ?)
+      ON CONFLICT (provider, installation) DO UPDATE SET retry_at = CASE WHEN retry_at IS NULL OR retry_at < excluded.retry_at THEN excluded.retry_at ELSE retry_at END`).run(installation, until);
+    }
+    /** What is wrong with the connection right now (null: nothing), as the lease holder last saw it. */
+    setProblem(installation, owner, problem) {
+        this.prepare("UPDATE chat_runtime SET problem = ? WHERE provider = :provider AND installation = ? AND owner = ?").run(problem, installation, owner);
+    }
+    /** The worker reached the app. */
+    setConnected(installation, owner, now) {
+        this.prepare("UPDATE chat_runtime SET connected = ?, problem = NULL WHERE provider = :provider AND installation = ? AND owner = ?").run(now.toISOString(), installation, owner);
+    }
+    /** The worker stopped: no holder, no connection. */
+    stop(installation, owner) {
+        this.prepare("UPDATE chat_runtime SET owner = NULL, lease_until = NULL, connected = NULL WHERE provider = :provider AND installation = ? AND owner = ?").run(installation, owner);
+    }
+    /** The connection as settings show it. */
+    runtime(installation) {
+        const row = this.prepare("SELECT connected, problem, lease_until FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation);
+        return row === undefined ? null : { connected: str(row["connected"]), problem: str(row["problem"]), leaseUntil: str(row["lease_until"]) };
+    }
+    /** Where the app pushes this installation's updates (null: the worker asks for them), and what's wrong, if anything. */
+    setPush(installation, push, now) {
+        this.prepare("UPDATE chat_runtime SET push_url = ?, push_problem = ?, push_at = ? WHERE provider = :provider AND installation = ?").run(push.url, push.problem, now.toISOString(), installation);
+    }
+    push(installation) {
+        const row = this.prepare("SELECT push_url, push_problem, push_at, owner FROM chat_runtime WHERE provider = :provider AND installation = ?").get(installation);
+        return row === undefined || row["owner"] === null && row["push_at"] === null ? null : { url: str(row["push_url"]), problem: str(row["push_problem"]), at: str(row["push_at"]) };
+    }
+    // ---- small facts ------------------------------------------------------------------------------------------------
+    /** Small transport facts an app must remember per chat (a Teams service URL). Never credentials. */
+    meta(installation, key) {
+        return str(this.prepare("SELECT value FROM chat_meta WHERE provider = :provider AND installation = ? AND key = ?").get(installation, key)?.["value"]);
+    }
+    setMeta(installation, key, value, now) {
+        this.prepare(`INSERT INTO chat_meta (provider, installation, key, value, updated) VALUES (:provider, ?, ?, ?, ?)
+      ON CONFLICT (provider, installation, key) DO UPDATE SET value = excluded.value, updated = excluded.updated`).run(installation, key, value, now.toISOString());
+    }
+}

package/dist/chat-decide.d.ts

@@ -9,8 +9,9 @@
  * their own chat; otherwise, and for a plan that widens permissions, exceeds the limit or touches protected paths, the
  * card keeps its link.
  *
- * Channel-agnostic: Telegram renders these today, and Slack, Discord and Teams reach the same acts through the same
- * tokens (the `channel` column). Every act runs through the door the console uses. */
+ * The same in every chat app: Telegram's bridge and the shared engine Slack, Discord and Teams run on (chat-delivery.ts)
+ * offer, mint and answer these through the same tokens (the `channel` column). Every act runs through the door the
+ * console uses. */
 import { DECIDE_ACTS } from "./contracts/chat-callback-rows.js";
 import { type ChatApprovalLimits } from "./chat-approval.js";
 import { type VerifiedApprover } from "./principal.js";
@@ -78,10 +79,11 @@ export type DecideOffer = {
     text: string | null;
     rows: Array<Array<ActSpec | DecideLink>>;
 };
-/** What lets this person's chat approve on this repository now: their lasting chat-approval setting (chat-approval.ts),
- * or else a live signed mode carrying the chatApprove term, signed by them. `digest` names that authority for the
+/** What lets this person's chat on `channel` approve on this repository now: their lasting chat-approval setting
+ * (chat-approval.ts), or else a live signed mode carrying the chatApprove term, signed by them, that names this chat
+ * app (a mode signed before the term named its apps covers Telegram alone). `digest` names that authority for the
  * ledger; the yes itself is the person's tap and is sealed as theirs, so it doesn't lapse when the authority does. */
-export declare function chatApproveMode(store: Store, repo: string | null, approver: string, now: Date): {
+export declare function chatApproveMode(store: Store, repo: string | null, approver: string, now: Date, channel: DecideChannel): {
     ok: true;
     digest: string;
     limits: ChatApprovalLimits;
@@ -94,7 +96,7 @@ export declare function chatApproveMode(store: Store, repo: string | null, appro
 export declare function permissionPlainWords(profile: Scope["profile"] | null | undefined): string | null;
 /** A plan this person's chat may approve now: the term, the plan's exact bytes, and none of the reasons it must open
  * Toolroll instead. `digest` binds the scope and the plan document the card shows. */
-export declare function planInChat(store: Store, taskId: string, approver: string, now: Date, root?: string): {
+export declare function planInChat(store: Store, taskId: string, approver: string, now: Date, channel: DecideChannel, root?: string): {
     ok: true;
     modeDigest: string;
     source: "setting" | "mode";
@@ -105,7 +107,7 @@ export declare function planInChat(store: Store, taskId: string, approver: strin
     why: string;
 };
 /** A ready pull request this person's chat may merge now, bound to the exact commit. */
-export declare function mergeInChat(store: Store, taskId: string, run: number, approver: string, now: Date): {
+export declare function mergeInChat(store: Store, taskId: string, run: number, approver: string, now: Date, channel: DecideChannel): {
     ok: true;
     modeDigest: string;
     source: "setting" | "mode";
@@ -119,7 +121,7 @@ export declare function mergeInChat(store: Store, taskId: string, run: number, a
 export declare function planCardText(store: Store, taskId: string, scope: Scope, root?: string, channel?: DecideChannel): string;
 /** The acts a card about this target can take in chat right now, or null when none can (the card keeps its own
  * link). Reads only; nothing is minted. */
-export declare function decideOffer(store: Store, target: DecideTarget, who: VerifiedApprover, now: Date, root?: string, channel?: DecideChannel): DecideOffer | null;
+export declare function decideOffer(store: Store, target: DecideTarget, who: VerifiedApprover, now: Date, channel: DecideChannel, root?: string): DecideOffer | null;
 /** One fingerprint of what the card offers, without its tokens: a repaint with the same offer keeps its buttons. */
 export declare function offerFingerprint(offer: DecideOffer): string;
 /** The card's buttons, minted now (message unknown until it is sent: `placeDecideTokens` puts them on it). */