@sigrun/ext-gateway 0.0.0-stage → 0.1.1

package/dist/outbound/settled.js

@@ -0,0 +1,271 @@
+/**
+ * onRunSettled (spec §8.6's "which runs deliver" + the M7 access
+ * re-check): the engine's `runSettled` factory handler. ONLY ENQUEUES —
+ * the per-channel delivery workers own the platform calls.
+ *
+ * - Every key in `bindings.keysOf(conversationId)` that is not dead
+ *   gets a final (whoever started the run — ruling 4: a webui submit
+ *   into a bound conversation delivers to the chat).
+ * - Access is RE-CHECKED per delivery (M7): `meta` + `accessOf` for
+ *   the binding's user — the LINKED user for DMs, the group owner for
+ *   groups. A failed check UNBINDS the chat, logs it, and enqueues
+ *   nothing.
+ * - An answered run renders the answer's text blocks (thinking and
+ *   tool calls are never shown); an answer with NO text blocks gets
+ *   the pinned "(no text reply)" notice (Review Focus 4 — an empty
+ *   send is a platform rejection, never an honest reply).
+ * - The origin-chat streaming hand-off runs through `deps.streams`:
+ *   rendered chunks cross to the registry at this layer while the
+ *   boolean answer decides whether the origin's finals enqueue.
+ * - An unanswered run notifies the ORIGIN chat only (from
+ *   `deps.origins`): the pinned "Stopped." for an abort reason, a
+ *   short reason notice otherwise.
+ */
+import { hashId } from "../log.js";
+import { renderChunks } from "./render.js";
+import { resolveTargets } from "../jobs.js";
+/** The pinned notice for a textless answer (Review Focus 4). */
+export const NO_TEXT_REPLY = "(no text reply)";
+/** The pinned abort notice (spec §8.6: "An abort from /stop produces Stopped."). */
+export const STOPPED = "Stopped.";
+/**
+ * The settled-run handler: enqueue finals (or the empty-answer notice)
+ * for every live bound chat, and the unanswered notice for the origin
+ * chat. Never throws (the event bus's bounded handler owns isolation,
+ * but a ledger failure must not lose the rest of the fan-out).
+ */
+export async function onRunSettled(event, deps) {
+    try {
+        await run(event, deps);
+    }
+    catch (error) {
+        // A fan-out failure is logged loud: the entries that landed stay
+        // queued (the ledger is the source of truth), the lost ones log
+        // their conversation (§8.6: nothing is dropped silently).
+        deps.log.error(`settled fan-out failed (conversation ${String(event.conversationId)})`, error);
+    }
+}
+/** The body (isolated from the catch so a partial fan-out still logs). */
+async function run(event, deps) {
+    const conversationId = event.conversationId;
+    if (event.outcome.status === "answered") {
+        await fanOutAnswer(event, deps, conversationId);
+        await deliverJobAnswer(event, deps, conversationId);
+        return;
+    }
+    if (originKeyOf(deps, event) !== undefined) {
+        deps.streams.abandon(conversationId);
+    }
+    await notifyOrigin(event, deps);
+}
+/** The answered fan-out: every live bound key, access-checked. */
+async function fanOutAnswer(event, deps, conversationId) {
+    const keys = deps.bindings.keysOf(conversationId);
+    // The answer's visible text: text blocks joined (thinking/tool calls
+    // are never shown — §8.6).
+    const text = answerText(event);
+    // The origin-chat streaming hand-off runs ONCE per conversation,
+    // before the fan-out and even when the binding disappeared (the watch
+    // still needs releasing). Only the origin gets its chunks here.
+    const origin = originKeyOf(deps, event);
+    const originChannel = origin === undefined ? undefined : deps.channelOf(origin.channel);
+    const originBinding = origin === undefined ? undefined : deps.bindings.get(origin.bindingKey);
+    const originChunks = originChannel === undefined || originBinding === undefined || originBinding.dead === true || text === ""
+        ? []
+        : renderChunks(text, originChannel.capabilities, originChannel.format);
+    // Foreign settles (webui/jobs) still fan out finals, but must not tear
+    // down the gateway-originated run's live preview.
+    const streamed = origin === undefined
+        ? false
+        : await deps.streams.finalize(conversationId, originChunks);
+    if (keys.length === 0)
+        return;
+    for (const key of keys) {
+        const binding = deps.bindings.get(key);
+        if (binding === undefined || binding.dead === true)
+            continue;
+        // A channel config that is ABSENT or {failed} is a CONFIG problem,
+        // not a revoked binding: the binding is KEPT (a config typo must
+        // never silently delete chats) and the fan-out skips with a log.
+        const channel = channelOfFor(deps, key);
+        if (channel === undefined) {
+            deps.log.warn(`settled: no channel adapter for binding "${hashId(key)}" — skipped, binding kept`);
+            deps.log.debug(`settled: no channel adapter for binding "${key}" — skipped, binding kept`);
+            continue;
+        }
+        const config = await deps.configOf(key.split(":")[0] ?? "");
+        if (config === undefined) {
+            deps.log.warn(`settled: channel config unavailable for binding "${hashId(key)}" — skipped, binding kept`);
+            deps.log.debug(`settled: channel config unavailable for binding "${key}" — skipped, binding kept`);
+            continue;
+        }
+        // M7: the access re-check. DM bindings resolve their user through
+        // the SAME allowlist-then-link resolution admission ran; group
+        // bindings use the config's owner. A FAILED CHECK (a present config
+        // whose user is unresolvable, or access "none") unbinds, logs, skips.
+        const meta = await deps.host.conversations.meta(conversationId);
+        // A removed or malformed group row pauses that group; neither revokes
+        // the binding. This matches inbound admission and preserves continuity
+        // if the operator restores or repairs the row. Only a valid row whose
+        // owner is genuinely unresolvable reaches the unbind path below.
+        const group = binding.chat.chatType === "dm"
+            ? undefined
+            : config.groups.find((entry) => entry.chat === binding.chat.chatId);
+        if (binding.chat.chatType !== "dm" &&
+            (group === undefined || "failed" in group)) {
+            deps.log.warn(`settled: group config absent or invalid for binding "${hashId(key)}" — skipped, binding kept`);
+            deps.log.debug(`settled: group config absent or invalid for binding "${key}" — skipped, binding kept`);
+            continue;
+        }
+        const user = await bindingUser(deps, config, key, binding.chat);
+        if (user === undefined || meta === undefined) {
+            await unbindAndLog(deps, conversationId, key, "user unresolvable");
+            continue;
+        }
+        const access = await deps.host.access.accessOf({ user }, { owner: meta.owner, sharing: meta.sharing });
+        if (access === "none") {
+            await unbindAndLog(deps, conversationId, key, `access revoked for user "${user}"`);
+            continue;
+        }
+        const chunks = text === "" ? [NO_TEXT_REPLY] : renderChunks(text, channel.capabilities, channel.format);
+        // The stream owns the ORIGIN chat (the chat the run streamed to):
+        // that key is skipped; every other key still enqueues.
+        if (streamed && key === origin?.bindingKey) {
+            continue;
+        }
+        for (let index = 0; index < chunks.length; index++) {
+            await deps.ledger.enqueue({
+                channel: channel.id,
+                bindingKey: key,
+                chat: binding.chat,
+                kind: text === "" ? "notice" : "final",
+                message: { chat: binding.chat, text: chunks[index] },
+                // The tag is chunk-indexed: a multi-chunk final's entries are
+                // distinct rows (a replayed settle re-dedupes the whole set).
+                tag: `final:${conversationId}:${String(event.outcome.answerEntryId)}:${key}:${index}`,
+            });
+        }
+    }
+}
+/**
+ * A new-conversation job's FIRST answered settle: resolve the meta's
+ * targets and enqueue one headed answer per target. The job-tag prefix
+ * makes this one-shot even when later runs carry different answers.
+ */
+async function deliverJobAnswer(event, deps, conversationId) {
+    if (deps.ledger.list().some((entry) => entry.tag?.startsWith(`job:${conversationId}:`) === true))
+        return;
+    const meta = deps.readMeta === undefined
+        ? await deps.host.conversations.meta(conversationId)
+        : await deps.readMeta(conversationId);
+    if (meta?.jobId === undefined || meta.deliver === undefined)
+        return;
+    const owner = meta.owner;
+    if (owner === undefined) {
+        deps.log.warn(`job delivery rejected (conversation ${conversationId}): no owner`);
+        return;
+    }
+    const targets = await resolveTargets(deps, owner, meta.deliver);
+    for (const rejected of targets.rejected) {
+        deps.log.warn(`job delivery rejected (conversation ${conversationId}, target "${rejected.target}"): ${rejected.reason}`);
+    }
+    const text = answerText(event);
+    const body = text === "" ? NO_TEXT_REPLY : text;
+    const name = meta.name ?? meta.autoName ?? `Conversation ${conversationId}`;
+    for (const target of targets.resolved) {
+        const channel = deps.channelOf(target.channel);
+        if (channel === undefined) {
+            deps.log.warn(`job delivery skipped: no channel "${target.channel}"`);
+            continue;
+        }
+        const chunks = renderChunks(`Job ${name}\n${body}`, channel.capabilities, channel.format);
+        for (let index = 0; index < chunks.length; index++) {
+            await deps.ledger.enqueue({
+                channel: target.channel,
+                chat: target.chat,
+                kind: "final",
+                message: { chat: target.chat, text: chunks[index] },
+                // The target suffix distinguishes simultaneous targets; the
+                // chunk index distinguishes rows of a split answer.
+                tag: `job:${conversationId}:${target.channel}:${target.chat.chatId}:${index}`,
+            });
+        }
+    }
+}
+/** The unanswered notice: the origin chat only. */
+async function notifyOrigin(event, deps) {
+    const origin = originKeyOf(deps, event);
+    if (origin === undefined) {
+        // A run the engine never admitted (webui-started, a job): no chat
+        // to notify — the webui shows the failure itself.
+        return;
+    }
+    const binding = deps.bindings.get(origin.bindingKey);
+    if (binding === undefined || binding.dead === true)
+        return;
+    const channel = deps.channelOf(origin.channel);
+    if (channel === undefined) {
+        deps.log.warn(`settled: no channel "${origin.channel}" for the unanswered notice`);
+        return;
+    }
+    const text = event.outcome.reason === "aborted"
+        ? STOPPED
+        : `Could not answer: ${event.outcome.reason}`;
+    await deps.ledger.enqueue({
+        channel: origin.channel,
+        bindingKey: origin.bindingKey,
+        chat: binding.chat,
+        kind: "notice",
+        message: { chat: binding.chat, text },
+        // Tagged: a replayed settle re-dedupes (the same rule the finals
+        // carry).
+        tag: `notice:${String(event.conversationId)}:${origin.bindingKey}`,
+    });
+}
+/**
+ * The origin record of the event's run: the LAST input's record (the
+ * run's final submission — an album's batch shares one record per
+ * submit). Undefined when the engine never admitted the run.
+ */
+function originKeyOf(deps, event) {
+    for (const id of [...event.inputs].reverse()) {
+        const origin = deps.origins.get(id);
+        if (origin !== undefined)
+            return origin;
+    }
+    return undefined;
+}
+/** The binding's user: the DM's resolved user (allowlist then link —
+ *  the SAME resolution the admission ran), the group owner for a group (M7).
+ *  The config is the CALLER's (the fan-out already verified it present). */
+async function bindingUser(deps, config, key, chat) {
+    const channel = key.split(":")[0] ?? "";
+    if (chat.chatType === "dm") {
+        // A DM binding's chat id IS the platform sender id: the admission's
+        // own resolution (allowlist first, then the stored link) — the
+        // allowlist mapping outlives the link.
+        return (await deps.identities.userFor(config, channel, chat.chatId))?.user;
+    }
+    // A group binding's user is the configured OWNER (spec §8.2: the
+    // group's owner is who the run acts for).
+    const group = config.groups.find((entry) => entry.chat === chat.chatId && !("failed" in entry));
+    return group === undefined || "failed" in group ? undefined : group.owner;
+}
+/** The channel adapter for a binding key's channel segment. */
+function channelOfFor(deps, key) {
+    const channel = key.split(":")[0];
+    return deps.channelOf(channel);
+}
+/** Unbind + log (the M7 revoked-access path). */
+async function unbindAndLog(deps, conversationId, key, reason) {
+    await deps.bindings.unbind(key);
+    deps.log.info(`settled: unbound "${hashId(key)}" from conversation ${String(conversationId)} (${reason})`);
+    deps.log.debug(`settled: unbound "${key}" from conversation ${String(conversationId)} (${reason})`);
+}
+/** The answer's visible text (text blocks joined). */
+function answerText(event) {
+    return event.outcome.answer.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+}

package/dist/outbound/stream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Origin-chat streaming (spec §8.6): live frames ride the conversation
+ * watch, never the durable ledger. The first send waits for 20 visible
+ * characters; later edits are prefix-stable and rate-limited. Final
+ * chunks come from runSettled, not from the last preview frame.
+ */
+import type { ChannelContribution, ChatRef, SigrunHost } from "@sigrun/sigrun/extension";
+import type { ChannelConfig } from "../config.js";
+import type { EngineLog } from "../log.js";
+import type { Streams } from "./settled.js";
+export interface StreamOrigin {
+    readonly channel: string;
+    readonly bindingKey: string;
+    readonly chat: ChatRef;
+}
+export interface StreamRegistryDeps {
+    readonly host: SigrunHost;
+    readonly channelOf: (id: string) => ChannelContribution | undefined;
+    readonly configOf: (id: string) => Promise<ChannelConfig | undefined>;
+    readonly log: EngineLog;
+    readonly now?: () => number;
+    readonly setTimer?: (fn: () => void, ms: number) => () => void;
+}
+export declare class StreamRegistry implements Streams {
+    private readonly deps;
+    private readonly now;
+    private readonly setTimer;
+    private readonly active;
+    private readonly openings;
+    constructor(deps: StreamRegistryDeps);
+    open(conversationId: number, origin: StreamOrigin): Promise<boolean>;
+    finalize(conversationId: number, chunks: string[]): Promise<boolean>;
+    abandonAll(): void;
+    abandon(conversationId: number): void;
+    private startTyping;
+    private preview;
+    private edit;
+}

package/dist/outbound/stream.js

@@ -0,0 +1,205 @@
+/**
+ * Origin-chat streaming (spec §8.6): live frames ride the conversation
+ * watch, never the durable ledger. The first send waits for 20 visible
+ * characters; later edits are prefix-stable and rate-limited. Final
+ * chunks come from runSettled, not from the last preview frame.
+ */
+import { liveGenerationText } from "@sigrun/shared/live";
+import { stripMarkdown } from "./markdown.js";
+const FIRST_SEND_VISIBLE_CHARS = 20;
+export class StreamRegistry {
+    deps;
+    now;
+    setTimer;
+    active = new Map();
+    openings = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => {
+            const timer = setTimeout(fn, ms);
+            return () => clearTimeout(timer);
+        });
+    }
+    async open(conversationId, origin) {
+        // One preview per conversation: a second admission is final-only;
+        // abandoning here would freeze the owning run's streamed partial.
+        if (this.active.has(conversationId) || this.openings.has(conversationId))
+            return false;
+        const opening = {};
+        this.openings.set(conversationId, opening);
+        try {
+            const channel = this.deps.channelOf(origin.channel);
+            const config = await this.deps.configOf(origin.channel);
+            if (channel === undefined || config === undefined || !config.stream) {
+                this.openings.delete(conversationId);
+                return false;
+            }
+            if (channel.capabilities.edit !== undefined && channel.edit === undefined) {
+                this.openings.delete(conversationId);
+                this.deps.log.error(`stream: channel "${channel.id}" declares edit capabilities without edit()`);
+                return false;
+            }
+            // Abandon/reopen while the config read was awaiting invalidates this
+            // open; without the generation check it could orphan a fresh watch.
+            if (this.openings.get(conversationId) !== opening)
+                return false;
+            let listener;
+            const releaseWatch = await this.deps.host.conversations.watch(conversationId, (view) => listener?.(view));
+            if (this.openings.get(conversationId) !== opening) {
+                await releaseWatch();
+                return false;
+            }
+            this.openings.delete(conversationId);
+            const state = {
+                conversationId,
+                origin,
+                channel,
+                releaseWatch,
+                closed: false,
+                failed: false,
+                lastDeliveryAt: Number.NEGATIVE_INFINITY,
+                operations: Promise.resolve(),
+            };
+            listener = (view) => {
+                if (state.closed || state.failed)
+                    return;
+                const text = liveGenerationText(view);
+                state.operations = state.operations
+                    .then(async () => this.preview(state, text))
+                    .catch((error) => {
+                    state.failed = true;
+                    this.deps.log.error("stream preview failed", error);
+                });
+            };
+            this.active.set(conversationId, state);
+            if (channel.capabilities.edit === undefined)
+                this.startTyping(state);
+            return true;
+        }
+        catch (error) {
+            // A rejected config/watch attempt owns no active stream; release
+            // its slot so a later admission can retry instead of staying final-only.
+            if (this.openings.get(conversationId) === opening) {
+                this.openings.delete(conversationId);
+            }
+            throw error;
+        }
+    }
+    async finalize(conversationId, chunks) {
+        const state = this.active.get(conversationId);
+        if (state === undefined)
+            return false;
+        this.active.delete(conversationId);
+        state.closed = true;
+        state.cancelEdit?.();
+        state.cancelTyping?.();
+        await state.releaseWatch();
+        await state.operations;
+        if (state.failed || state.message === undefined || chunks.length === 0)
+            return false;
+        try {
+            // At-least-once: a failed tail send re-delivers all chunks fresh,
+            // the cost of the ledger fallback (chunk 1 may duplicate).
+            await this.edit(state, chunks[0]);
+            for (const chunk of chunks.slice(1)) {
+                await state.channel.send({ chat: state.origin.chat, text: chunk });
+            }
+            return true;
+        }
+        catch (error) {
+            this.deps.log.error("stream final delivery failed", error);
+            return false;
+        }
+    }
+    abandonAll() {
+        for (const conversationId of [
+            ...this.active.keys(),
+            ...this.openings.keys(),
+        ])
+            this.abandon(conversationId);
+    }
+    abandon(conversationId) {
+        const state = this.active.get(conversationId);
+        if (state === undefined) {
+            // Before activation, the opening itself is the only ownership
+            // handle; deleting it invalidates that pending preview.
+            this.openings.delete(conversationId);
+            return;
+        }
+        this.active.delete(conversationId);
+        state.closed = true;
+        state.cancelEdit?.();
+        state.cancelTyping?.();
+        void state.releaseWatch().catch((error) => {
+            this.deps.log.error("stream watch release failed", error);
+        });
+    }
+    startTyping(state) {
+        const typing = state.channel.typing;
+        const interval = state.channel.capabilities.typing?.intervalMs;
+        if (typing === undefined || interval === undefined)
+            return;
+        const pulse = () => {
+            if (state.closed)
+                return;
+            void typing.call(state.channel, state.origin.chat).catch((error) => {
+                this.deps.log.error("stream typing failed", error);
+            });
+            if (!state.closed)
+                state.cancelTyping = this.setTimer(pulse, interval);
+        };
+        state.cancelTyping = this.setTimer(pulse, interval);
+    }
+    async preview(state, text) {
+        // Raw cumulative text preserves prefix-stability; re-formatting is
+        // reserved for the authoritative final through renderChunks.
+        if (state.closed || state.failed || state.channel.capabilities.edit === undefined)
+            return;
+        if (stripMarkdown(text).trim().length < FIRST_SEND_VISIBLE_CHARS)
+            return;
+        if (state.lastSent !== undefined && !text.startsWith(state.lastSent))
+            return;
+        if (state.message === undefined) {
+            const receipt = await state.channel.send({ chat: state.origin.chat, text });
+            const messageId = receipt.messageIds[0];
+            if (messageId === undefined)
+                throw new Error("stream send returned no message id");
+            state.message = { chat: state.origin.chat, messageId };
+            state.lastSent = text;
+            state.lastDeliveryAt = this.now();
+            return;
+        }
+        if (text === state.lastSent)
+            return;
+        const wait = Math.max(0, state.channel.capabilities.edit.minIntervalMs - (this.now() - state.lastDeliveryAt));
+        if (wait > 0) {
+            state.pendingText = text;
+            if (state.cancelEdit === undefined) {
+                state.cancelEdit = this.setTimer(() => {
+                    state.cancelEdit = undefined;
+                    const pending = state.pendingText;
+                    state.pendingText = undefined;
+                    if (pending !== undefined && !state.closed && !state.failed) {
+                        state.operations = state.operations
+                            .then(async () => this.preview(state, pending))
+                            .catch((error) => {
+                            state.failed = true;
+                            this.deps.log.error("stream preview failed", error);
+                        });
+                    }
+                }, wait);
+            }
+            return;
+        }
+        await this.edit(state, text);
+        state.lastSent = text;
+        state.lastDeliveryAt = this.now();
+    }
+    async edit(state, text) {
+        if (state.message === undefined || state.channel.edit === undefined) {
+            throw new Error("stream edit requires a streamed message and adapter edit()");
+        }
+        await state.channel.edit(state.message, { chat: state.origin.chat, text });
+    }
+}

package/dist/section.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The bound-chat prompt section (spec §8.10). It describes only the
+ * first live binding, keeping its text static per binding for prompt-cache
+ * stability; additional bindings collapse to the pinned count suffix.
+ */
+import { type PromptSection } from "@earendil-works/pi-durable";
+import type { ChannelContribution, SigrunHost } from "@sigrun/sigrun/extension";
+import type { BindingStore } from "./state/bindings.js";
+import type { GatewayConfig } from "./config.js";
+export interface ChannelSectionDeps {
+    readonly host: SigrunHost;
+    readonly bindings: BindingStore;
+    channelOf(channel: string): ChannelContribution | undefined;
+    readConfig(): Promise<GatewayConfig>;
+}
+export declare function createChannelSection(deps: ChannelSectionDeps): PromptSection;

package/dist/section.js

@@ -0,0 +1,55 @@
+/**
+ * The bound-chat prompt section (spec §8.10). It describes only the
+ * first live binding, keeping its text static per binding for prompt-cache
+ * stability; additional bindings collapse to the pinned count suffix.
+ */
+import { section } from "@earendil-works/pi-durable";
+export function createChannelSection(deps) {
+    return section("gateway-channel", async (input) => {
+        const keys = deps.bindings.keysOf(input.conversationId).filter((key) => deps.bindings.get(key)?.dead !== true);
+        const first = keys[0];
+        if (first === undefined)
+            return undefined;
+        const binding = deps.bindings.get(first);
+        if (binding === undefined)
+            return undefined;
+        const channelId = first.split(":", 1)[0];
+        if (channelId === undefined)
+            return undefined;
+        const channel = deps.channelOf(channelId);
+        if (channel === undefined)
+            return undefined;
+        const config = await deps.readConfig();
+        const block = config.channels[channelId];
+        const group = block === undefined || "failed" in block
+            ? undefined
+            : findGroup(block.groups, binding.chat);
+        const title = binding.chat.title;
+        const chatLabel = binding.chat.chatType === "dm"
+            ? "direct message"
+            : `group "${title ?? binding.chat.chatId}"`;
+        const hint = channel.capabilities.promptHint;
+        const lines = [
+            `This conversation is connected to ${channel.label} (${chatLabel}).${hint === undefined ? "" : ` ${hint}`}`,
+        ];
+        if (binding.chat.chatType !== "dm") {
+            const owner = group === undefined
+                ? (await deps.host.conversations.meta(input.conversationId)).owner
+                : group.owner;
+            if (owner !== undefined) {
+                const ownerName = (await deps.host.users.get(owner))?.name ?? owner;
+                lines.push(`Messages are prefixed with the sender's name. You act for ${ownerName}; senders other than ${ownerName} are not the account owner.`);
+            }
+            if (group?.members === "anyone") {
+                lines.push("Anyone in the group can message you.");
+            }
+        }
+        let rendered = lines.join("\n");
+        if (keys.length > 1)
+            rendered += ` (also connected to ${keys.length - 1} more)`;
+        return rendered;
+    });
+}
+function findGroup(groups, chat) {
+    return groups.find((group) => !("failed" in group) && group.chat === chat.chatId);
+}

package/dist/session-meta.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The core session-meta document token, re-declared structurally from
+ * the shared wire type. Standalone doc tokens compare by kind/scope;
+ * declaring it here avoids a runtime import of core's server modules.
+ * Core-contract follow-up: version drift here silently reads job meta as absent.
+ */
+import type { SessionMeta } from "@sigrun/shared/views";
+export declare const SessionMetaDoc: import("@earendil-works/pi-durable").ConversationDocToken<SessionMeta>;

package/dist/session-meta.js

@@ -0,0 +1,21 @@
+/**
+ * The core session-meta document token, re-declared structurally from
+ * the shared wire type. Standalone doc tokens compare by kind/scope;
+ * declaring it here avoids a runtime import of core's server modules.
+ * Core-contract follow-up: version drift here silently reads job meta as absent.
+ */
+import { defineDoc } from "@earendil-works/pi-durable";
+export const SessionMetaDoc = defineDoc({
+    kind: "sigrun.session-meta",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "current",
+    initial: () => ({
+        pinned: false,
+        tagged: [],
+        archived: false,
+        draft: { text: "", attachments: [] },
+        source: "user",
+    }),
+});

package/dist/state/bindings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The binding store (spec §8.3): one row per chat, key → the
+ * conversation the chat is bound to. Persisted at
+ * `<stateDir>/gateway/bindings.json` through {@link JsonFile} (0600,
+ * atomic, serialized updates).
+ *
+ * `account` is always `default` in v1 (the multi-account slot the key
+ * reserves so keys never need migrating); a thread rides its own key
+ * segment. `previous` records every conversation the chat was bound to
+ * before the current one (`/new` and rebinds append) — the outbound
+ * side never reads it today, but `/status` (Task 7) shows it and the
+ * array is the honest history a rebind loses otherwise.
+ */
+import type { ChatRef } from "@sigrun/sigrun/extension";
+/** One live binding: the chat → conversation edge. */
+export interface Binding {
+    readonly conversationId: number;
+    readonly chat: ChatRef;
+    /** Clock ms when the CURRENT conversation was bound. */
+    readonly boundAt: number;
+    /** Earlier conversation ids this chat was bound to, oldest first. */
+    readonly previous: readonly number[];
+    /** Set when delivery classified the chat gone (`chat_gone`). */
+    readonly dead?: boolean;
+}
+/** The binding key (§8.3): `<channel>:default:<chatType>:<chatId>[:threadId]`. */
+export declare function bindingKey(channel: string, chat: ChatRef): string;
+/**
+ * The chat → conversation bindings, one instance per engine. `bind` is
+ * the only mutator that grows `previous`; every method persists through
+ * the serialized JsonFile queue, so concurrent receives on the same
+ * chat never lose a rebind.
+ */
+export declare class BindingStore {
+    private readonly file;
+    /** The write-side clock (tests inject a fake; default real). */
+    private readonly now;
+    constructor(path: string, opts?: {
+        readonly now?: () => number;
+    });
+    /** The live binding for `key`, or undefined when unbound. */
+    get(key: string): Binding | undefined;
+    /** One file read's binding rows, keyed for target authorization. */
+    entries(): Readonly<Record<string, Binding>>;
+    /** Every live key bound to `conversationId` (the delivery fan-out read). */
+    keysOf(conversationId: number): readonly string[];
+    /** Bind `key` to `conversationId`, recording any prior binding in `previous`. */
+    bind(key: string, conversationId: number, chat: ChatRef): Promise<void>;
+    /** Remove the binding entirely (the access-revoked path). */
+    unbind(key: string): Promise<void>;
+    /** Mark the binding dead (`chat_gone` delivery): kept, never delivered to. */
+    markDead(key: string): Promise<void>;
+    /** Clear the dead flag (a new inbound event proves the chat alive). */
+    clearDead(key: string): Promise<void>;
+}