@addozhang/dsh-discord 0.1.0

package/lib/compose.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The adapter composition root (review C1). Assembles the runtime the
+ * module-level features could not wire themselves into: bot token → Gateway
+ * → authorized ingress → business router → Discord REST / DSH apiProxy,
+ * plus the settings-card status feed. Everything injected is a port;
+ * everything started here is torn down by the returned disposer.
+ *
+ * Fail-closed by construction: without a resolvable bot token nothing
+ * connects, and the status reports exactly that instead of pretending.
+ */
+import { type GatewaySocketFactory } from './gateway/gateway.js';
+import type { AccessDecision, PolicyTable } from './policy/authorization.js';
+import type { NormalizedInboundEvent } from './gateway/ingress.js';
+import { type ComponentRegistry } from './discord/components.js';
+import type { AdapterStatusTracker } from './features/adapter-status.js';
+import type { ApprovalStore } from './features/approval-store.js';
+import type { QuestionStore } from './features/question-store.js';
+/** Discord Gateway wss endpoint (Milestone 1: fixed v10 surface). */
+export declare const GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json";
+/**
+ * The session mainline (src/features/session-mainline.ts): the orchestrator
+ * behind both message paths — bound-channel mentions create thread/session,
+ * adapter-owned thread messages queue continuations.
+ */
+export interface SessionMainlinePort {
+    admitMention(request: {
+        applicationId: string;
+        guildId: string;
+        channelId: string;
+        messageId: string;
+        authorId: string;
+        workspaceId: string;
+        prompt: string;
+    }): Promise<{
+        outcome: 'admitted';
+        threadId: string;
+        sessionId: string;
+    } | {
+        outcome: 'thread-conflict';
+    } | {
+        outcome: 'thread-failed';
+    } | {
+        outcome: 'session-rejected';
+    } | {
+        outcome: 'session-unknown';
+    } | {
+        outcome: 'prompt-rejected';
+    } | {
+        outcome: 'prompt-unknown';
+    }>;
+    continueInThread(request: {
+        applicationId: string;
+        guildId: string;
+        threadId: string;
+        sessionId: string;
+        messageId: string;
+        prompt: string;
+    }): Promise<{
+        outcome: 'queued';
+    } | {
+        outcome: 'already-submitted';
+    } | {
+        outcome: 'conflict';
+    } | {
+        outcome: 'rejected';
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+export interface BindingsProbe {
+    /** Workspace id bound to the channel, when one exists. */
+    workspaceForChannel(guildId: string, channelId: string): string | undefined;
+    /** Session id owning the thread (writable binding), when one exists. */
+    sessionForThread(guildId: string, threadId: string): string | undefined;
+}
+export interface CompositionDeps {
+    tokenProvider: () => Promise<string | undefined>;
+    socketFactory: GatewaySocketFactory;
+    policy: () => PolicyTable;
+    /** Resolves the bot's own user id (Discord GET /users/@me) before start. */
+    selfUserIdProvider: () => Promise<string>;
+    /** Gateway intent bitmask (Milestone 1 fixed set). */
+    intents: number;
+    /**
+     * Gateway endpoint override (twin-E2E seam): defaults to the production
+     * wss URL. Must expose the real Gateway wire protocol, not a fake.
+     */
+    gatewayUrl?: string;
+    /** Live accessor for the adapter's Discord application id (binding keys). */
+    applicationId: () => string;
+    mainline: SessionMainlinePort;
+    bindings: BindingsProbe;
+    approvals: ApprovalStore;
+    questions: QuestionStore;
+    status: AdapterStatusTracker;
+    /**
+     * Interaction (commands/components/modals) routing, wired by the Host
+     * composition where the typed apiProxy respond face lives.
+     */
+    routeInteraction?: (event: NormalizedInboundEvent, interactionToken?: string) => void | Promise<void>;
+    /**
+     * Public (non-ephemeral — ordinary messages have no ephemeral channel)
+     * bind affordance for an authorized mention in an unbound channel
+     * (session-control spec, "New task in an unbound channel"). Absent, the
+     * mention is ignored as before.
+     */
+    unboundNotice?: (request: {
+        guildId: string;
+        channelId: string;
+        actorId: string;
+        audience: 'administrator' | 'member';
+    }) => void | Promise<void>;
+    /** Idempotently ensure the category + control channel exist in a guild. */
+    ensureGuildChannels?: (guildId: string) => Promise<void>;
+    /**
+     * Runs once per READY after channel provisioning: the reconciliation
+     * sweep's trigger (startup mapping verification precedes accepting
+     * writes for those mappings — reconciliation spec).
+     */
+    onReady?: () => void | Promise<void>;
+    /** Allowlist snapshot used to provision channels on READY. */
+    allowedGuildIds?: readonly string[] | undefined;
+    /**
+     * Registry override so the composition root shares ONE registry instance
+     * across the runtime and every feature handler (question controls,
+     * approval buttons, bind confirms).
+     */
+    registry?: ComponentRegistry;
+    logger?: {
+        warn(event: string, detail?: unknown): void;
+    };
+}
+export interface DiscordAdapterRuntime {
+    registry: ComponentRegistry;
+    approvals: ApprovalStore;
+    questions: QuestionStore;
+    started: boolean;
+    /** Why the runtime did not start (no token ⇒ fail-closed offline). */
+    startError?: 'missing-token' | undefined;
+    /**
+     * Re-run the start chain after a late credential write (the card's
+     * Connect button). Idempotent: an already-running gateway is replaced.
+     */
+    connect(): void;
+    /**
+     * Operator-initiated offline. The credential stays stored; the start chain
+     * is blocked until the next connect().
+     */
+    disconnect(): void;
+    dispose(): void;
+}
+/** Business routing over one normalized, already-authorized event. */
+export declare function routeEvent(deps: CompositionDeps, event: NormalizedInboundEvent, decision: AccessDecision): void;
+/**
+ * Start the composed adapter runtime. The returned runtime is live after the
+ * token resolves; `started` flips once the Gateway has been spawned.
+ */
+export declare function startDiscordAdapter(deps: CompositionDeps): DiscordAdapterRuntime;

package/lib/compose.js

@@ -0,0 +1,227 @@
+/**
+ * The adapter composition root (review C1). Assembles the runtime the
+ * module-level features could not wire themselves into: bot token → Gateway
+ * → authorized ingress → business router → Discord REST / DSH apiProxy,
+ * plus the settings-card status feed. Everything injected is a port;
+ * everything started here is torn down by the returned disposer.
+ *
+ * Fail-closed by construction: without a resolvable bot token nothing
+ * connects, and the status reports exactly that instead of pretending.
+ */
+import { startGateway } from './gateway/gateway.js';
+import { createAuthorizedIngress } from './policy/guard.js';
+import { planUnboundMention } from './features/unbound-mention.js';
+import { createComponentRegistry } from './discord/components.js';
+/** Discord Gateway wss endpoint (Milestone 1: fixed v10 surface). */
+export const GATEWAY_URL = 'wss://gateway.discord.gg/?v=10&encoding=json';
+/** Business routing over one normalized, already-authorized event. */
+export function routeEvent(deps, event, decision) {
+    if (event.kind === 'message') {
+        const prompt = event.content.trim();
+        // Adapter-owned thread: ordinary continuation, no mention required.
+        const sessionId = deps.bindings.sessionForThread(event.guildId, event.channelId);
+        if (sessionId !== undefined) {
+            if (prompt === '')
+                return;
+            const request = {
+                applicationId: deps.applicationId(),
+                guildId: event.guildId,
+                threadId: event.channelId,
+                sessionId,
+                messageId: event.messageId,
+                prompt,
+            };
+            void deps.mainline.continueInThread(request)
+                .then((result) => {
+                if (result.outcome === 'rejected' || result.outcome === 'unknown') {
+                    deps.logger?.warn('discord_continuation_not_queued', { ...result, messageId: event.messageId });
+                }
+            })
+                .catch((cause) => {
+                deps.logger?.warn('discord_continuation_failed', { messageId: event.messageId, cause: String(cause) });
+            });
+            return;
+        }
+        // Mention-gated prompt flow: bindings decide admit vs ignore.
+        const workspaceId = deps.bindings.workspaceForChannel(event.guildId, event.channelId);
+        if (!event.mentionedBot)
+            return;
+        if (workspaceId === undefined) {
+            // Unbound channel: one public bind affordance for authorized members,
+            // silent for everyone the guard already refused (spec-as-written,
+            // task 16.5). No DSH call ever follows.
+            const plan = planUnboundMention({ decision, isBound: false });
+            if (plan.outcome === 'bind-affordance') {
+                void Promise.resolve(deps.unboundNotice?.({
+                    guildId: event.guildId,
+                    channelId: event.channelId,
+                    actorId: event.authorId,
+                    audience: plan.audience,
+                })).catch((cause) => {
+                    deps.logger?.warn('discord_unbound_notice_failed', { cause: String(cause) });
+                });
+            }
+            return;
+        }
+        if (prompt === '')
+            return;
+        void deps.mainline.admitMention({
+            applicationId: deps.applicationId(),
+            guildId: event.guildId,
+            channelId: event.channelId,
+            messageId: event.messageId,
+            authorId: event.authorId,
+            workspaceId,
+            prompt,
+        })
+            .then((result) => {
+            if (result.outcome !== 'admitted') {
+                deps.logger?.warn('discord_mention_not_admitted', { result, messageId: event.messageId });
+            }
+        })
+            .catch((cause) => {
+            deps.logger?.warn('discord_mention_admit_failed', { messageId: event.messageId, cause: String(cause) });
+        });
+        return;
+    }
+    // Interactions are dispatched ONLY from handleDispatch (which owns the
+    // interaction token); no token-less forwarding here (double-call bug).
+}
+/**
+ * Start the composed adapter runtime. The returned runtime is live after the
+ * token resolves; `started` flips once the Gateway has been spawned.
+ */
+export function startDiscordAdapter(deps) {
+    const registry = deps.registry ?? createComponentRegistry();
+    const status = deps.status;
+    let gateway;
+    let started = false;
+    let startError;
+    let ingress;
+    // provisioning style: one category + one control channel per
+    // allowed guild, created idempotently on the first READY.
+    const provisioned = new Set();
+    function handleDispatch(dispatch) {
+        if (dispatch.t === 'READY')
+            status.setGateway('connected');
+        const accepted = ingress?.accept(dispatch);
+        if (accepted?.accepted === false && (dispatch.t === 'INTERACTION_CREATE' || dispatch.t === 'MESSAGE_CREATE')) {
+            // A user-driven dispatch that dies at the gate must not vanish: from
+            // the user's side the click "does nothing", so the gate reason is on
+            // the record. Unrelated dispatch noise stays unlogged.
+            deps.logger?.warn('discord_dispatch_rejected', { type: dispatch.t, reason: accepted.reason });
+        }
+        if (accepted?.accepted === true && accepted.event !== undefined && accepted.event.kind === 'interaction') {
+            const d = dispatch.d;
+            const token = typeof d?.['token'] === 'string' ? d['token'] : undefined;
+            void Promise.resolve(deps.routeInteraction?.(accepted.event, token)).catch((cause) => {
+                console.error('[dsh-discord] interaction handler failed:', cause);
+            });
+        }
+        if (dispatch.t === 'READY' && deps.ensureGuildChannels !== undefined) {
+            for (const guildId of deps.allowedGuildIds ?? []) {
+                if (provisioned.has(guildId))
+                    continue;
+                provisioned.add(guildId);
+                deps.ensureGuildChannels(guildId).catch((cause) => {
+                    deps.logger?.warn('discord_channel_provision_failed', { guildId, cause: String(cause) });
+                });
+            }
+        }
+        if (dispatch.t === 'READY' && deps.onReady !== undefined) {
+            void Promise.resolve(deps.onReady()).catch((cause) => {
+                deps.logger?.warn('discord_ready_reconcile_failed', String(cause));
+            });
+        }
+    }
+    /** Set while the operator explicitly disconnected; blocks auto start. */
+    let stoppedByUser = false;
+    /**
+     * Start-chain generation. Bumped by connect()/disconnect() so an in-flight
+     * chain (suspended at its token/identity awaits) dies quietly instead of
+     * spawning a second, unownable gateway after the operator acted.
+     */
+    let startSeq = 0;
+    async function runStartChain() {
+        const seq = ++startSeq;
+        const stale = () => stoppedByUser || seq !== startSeq;
+        if (stale())
+            return;
+        const token = await deps.tokenProvider();
+        if (stale())
+            return;
+        if (token === undefined || token === '') {
+            started = false;
+            startError = 'missing-token';
+            status.setCredential({ configured: false });
+            status.setGateway('disconnected');
+            return;
+        }
+        status.setCredential({ configured: true });
+        const selfUserId = await deps.selfUserIdProvider();
+        if (stale())
+            return;
+        ingress = createAuthorizedIngress({
+            selfUserId,
+            policy: deps.policy,
+            onEvent: (event, decision) => { routeEvent(deps, event, decision); },
+        });
+        gateway = startGateway({
+            url: deps.gatewayUrl ?? GATEWAY_URL,
+            tokenProvider: () => deps.tokenProvider().then((value) => {
+                if (value === undefined)
+                    throw new TypeError('discord bot token unavailable');
+                return value;
+            }),
+            intents: deps.intents,
+            socketFactory: deps.socketFactory,
+            onDispatch: handleDispatch,
+            onTerminalClose: (code) => {
+                status.setGateway({ kind: 'terminal-close', code });
+            },
+            onBackoffScheduled: () => {
+                status.setGateway('connecting');
+            },
+        });
+        started = true;
+        status.setGateway('connecting');
+    }
+    void runStartChain().catch((cause) => {
+        deps.logger?.warn('discord_adapter_start_failed', String(cause));
+        status.setGateway('disconnected');
+    });
+    return {
+        registry,
+        approvals: deps.approvals,
+        questions: deps.questions,
+        get started() { return started; },
+        get startError() { return startError; },
+        connect() {
+            stoppedByUser = false;
+            startError = undefined;
+            startSeq += 1;
+            gateway?.dispose();
+            gateway = undefined;
+            started = false;
+            void runStartChain().catch((cause) => {
+                deps.logger?.warn('discord_adapter_connect_failed', String(cause));
+                status.setGateway('disconnected');
+            });
+        },
+        disconnect() {
+            // Operator-initiated offline: the credential stays in the store so the
+            // next Connect (possibly with a replaced token) needs no re-entry.
+            stoppedByUser = true;
+            startSeq += 1;
+            gateway?.dispose();
+            gateway = undefined;
+            started = false;
+            startError = undefined;
+            status.setGateway('disconnected');
+        },
+        dispose() {
+            startSeq += 1;
+            gateway?.dispose();
+        },
+    };
+}

package/lib/credential.d.ts

@@ -0,0 +1,20 @@
+export declare const DISCORD_BOT_TOKEN_REF: import("@deepseek-ai/dsh-credentials").CredentialRef;
+export interface DiscordCredentialProvider {
+    describe(ref: typeof DISCORD_BOT_TOKEN_REF): Promise<{
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+    }>;
+    resolve(ref: typeof DISCORD_BOT_TOKEN_REF): Promise<{
+        value: string;
+        source: string;
+    } | undefined>;
+    /** Durably store the secret in the provider-managed writable source. */
+    set(ref: typeof DISCORD_BOT_TOKEN_REF, value: string): Promise<void>;
+}
+export declare function describeDiscordCredential(provider: Pick<DiscordCredentialProvider, 'describe' | 'resolve'>): Promise<{
+    configured: boolean;
+    source?: string;
+    writable: boolean;
+}>;
+export declare function resolveDiscordBotToken(provider: Pick<DiscordCredentialProvider, 'resolve'>): Promise<string | undefined>;

package/lib/credential.js

@@ -0,0 +1,24 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+export const DISCORD_BOT_TOKEN_REF = credentialRef('DSH_DISCORD_BOT_TOKEN');
+export async function describeDiscordCredential(provider) {
+    const result = await provider.describe(DISCORD_BOT_TOKEN_REF);
+    if (result.configured) {
+        return {
+            configured: true,
+            ...(result.source === undefined ? {} : { source: result.source }),
+            writable: result.writable,
+        };
+    }
+    // The Host's describe() does not report env-sourced values, while the
+    // gateway's resolve() accepts them. Resolve is what connectivity actually
+    // uses, so probe it before claiming the credential is absent — otherwise
+    // the card shows "not configured" on a connected adapter.
+    const resolved = await provider.resolve(DISCORD_BOT_TOKEN_REF).catch(() => undefined);
+    if (resolved !== undefined) {
+        return { configured: true, source: resolved.source, writable: false };
+    }
+    return { configured: false, writable: result.writable };
+}
+export async function resolveDiscordBotToken(provider) {
+    return (await provider.resolve(DISCORD_BOT_TOKEN_REF))?.value;
+}

package/lib/discord/commands.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The Milestone 1 Discord command contract (design.md §13). One declarative
+ * table feeds both the adapter's own routing metadata and the Discord
+ * registration payload, so the wire shape cannot drift from the contract:
+ * nine fixed commands, guild-only, ephemeral responses, no Discord-level
+ * permission gates (adapter RBAC decides at interaction time, deny-first).
+ */
+/** A command argument as the contract table declares it. */
+export interface CommandArgument {
+    name: string;
+    required: boolean;
+    /**
+     * Discord sends a type-4 autocomplete interaction while the user types;
+     * the adapter answers with live choices (live-candidates pattern).
+     */
+    autocomplete?: boolean;
+}
+/** A subcommand of a top-level command. */
+export interface CommandSubcommand {
+    name: string;
+    options?: CommandArgument[];
+}
+/** One fixed top-level command. */
+export interface AdapterCommand {
+    name: string;
+    description: string;
+    subcommands?: CommandSubcommand[];
+    /** Direct options for leaf commands (no subcommands). */
+    options?: CommandArgument[];
+    /** Milestone 1: guild-only; DMs are unsupported. */
+    guildOnly: true;
+    /** Milestone 1: every response is ephemeral. */
+    responseVisibility: 'ephemeral';
+}
+/** The complete Milestone 1 command set, in registration order. */
+export declare const MILESTONE_ONE_COMMANDS: readonly AdapterCommand[];
+/**
+ * Build the bulk-overwrite registration payload for
+ * `PUT /applications/{application.id}/commands`.
+ * `default_member_permissions: '0'` keeps every command visible: the
+ * adapter's own deny-first RBAC authorizes at interaction time, because
+ * Discord roles cannot express Workspace-administrator or Host-operator
+ * authority.
+ */
+export declare function buildCommandRegistrations(): Array<Record<string, unknown>>;

package/lib/discord/commands.js

@@ -0,0 +1,87 @@
+/**
+ * The Milestone 1 Discord command contract (design.md §13). One declarative
+ * table feeds both the adapter's own routing metadata and the Discord
+ * registration payload, so the wire shape cannot drift from the contract:
+ * nine fixed commands, guild-only, ephemeral responses, no Discord-level
+ * permission gates (adapter RBAC decides at interaction time, deny-first).
+ */
+function leaf(name, description, options) {
+    return { name, description, ...(options === undefined ? {} : { options }), guildOnly: true, responseVisibility: 'ephemeral' };
+}
+function grouped(name, description, subcommands) {
+    return { name, description, subcommands, guildOnly: true, responseVisibility: 'ephemeral' };
+}
+/** The complete Milestone 1 command set, in registration order. */
+export const MILESTONE_ONE_COMMANDS = [
+    grouped('project', 'Bind this channel to a DSH workspace', [
+        { name: 'list', options: [{ name: 'query', required: false, autocomplete: true }] },
+        { name: 'bind', options: [{ name: 'workspace', required: true, autocomplete: true }] },
+        { name: 'info' },
+    ]),
+    grouped('queue', 'Inspect the session inbox queue', [
+        { name: 'list' },
+        { name: 'remove', options: [{ name: 'item', required: true }] },
+    ]),
+    leaf('steer', 'Steer the running turn of this thread', [{ name: 'prompt', required: true }]),
+    leaf('stop', 'Cancel the running turn of this thread'),
+    grouped('model', 'Show or select the session model', [
+        { name: 'show' },
+        { name: 'select', options: [{ name: 'model', required: true }, { name: 'reasoning', required: false }] },
+    ]),
+    grouped('preset', 'Show, select, or reset this channel\'s agent preset', [
+        { name: 'show' },
+        { name: 'select', options: [{ name: 'preset', required: true }] },
+        { name: 'reset' },
+    ]),
+    grouped('skill', 'Run a DSH skill through the session queue', [
+        { name: 'run', options: [{ name: 'skill', required: true }, { name: 'input', required: false }] },
+    ]),
+    grouped('host', 'Show the connected DSH host status', [
+        { name: 'status' },
+    ]),
+    grouped('guild', 'Guild-scoped adapter operations', [
+        { name: 'forget' },
+    ]),
+];
+const DISCORD_APPLICATION_COMMAND = 1;
+const DISCORD_SUBCOMMAND = 1;
+const DISCORD_STRING_OPTION = 3;
+/** 0 = interaction context "guild" (Telegram-style contexts list; no DMs). */
+const DISCORD_GUILD_CONTEXT = 0;
+function argumentToWire(option) {
+    return {
+        type: DISCORD_STRING_OPTION,
+        name: option.name,
+        description: option.name,
+        required: option.required,
+        ...(option.autocomplete === true ? { autocomplete: true } : {}),
+    };
+}
+/**
+ * Build the bulk-overwrite registration payload for
+ * `PUT /applications/{application.id}/commands`.
+ * `default_member_permissions: '0'` keeps every command visible: the
+ * adapter's own deny-first RBAC authorizes at interaction time, because
+ * Discord roles cannot express Workspace-administrator or Host-operator
+ * authority.
+ */
+export function buildCommandRegistrations() {
+    return MILESTONE_ONE_COMMANDS.map((command) => {
+        const options = command.subcommands !== undefined
+            ? command.subcommands.map(sub => ({
+                type: DISCORD_SUBCOMMAND,
+                name: sub.name,
+                description: `${command.name} ${sub.name}`,
+                ...(sub.options === undefined ? {} : { options: sub.options.map(argumentToWire) }),
+            }))
+            : command.options?.map(argumentToWire);
+        return {
+            type: DISCORD_APPLICATION_COMMAND,
+            name: command.name,
+            description: command.description,
+            contexts: [DISCORD_GUILD_CONTEXT],
+            default_member_permissions: '0',
+            ...(options === undefined || options.length === 0 ? {} : { options }),
+        };
+    });
+}

package/lib/discord/components.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Opaque component-id correlation for Discord components and modals. The
+ * custom_id Discord echoes back carries none of the adapter's DSH identifiers
+ * — only a registry key — so session, approval, question, and request data
+ * never appear on the Discord wire. Resolution returns the exact pending
+ * context idempotently until its expiry; actor and business validation stay
+ * with the callers, who own what they register.
+ */
+/** Arbitrary JSON-safe correlation context. */
+export type ComponentContext = Record<string, unknown>;
+export interface RegistryOptions {
+    /** Injectable opaque-id source for deterministic tests. */
+    idFactory?: () => string;
+    /** custom_id prefix; Discord allows 100 characters total. */
+    prefix?: string;
+}
+export type ComponentResolution = {
+    found: true;
+    context: ComponentContext;
+} | {
+    found: false;
+};
+/** The registry face shared by renderers (register) and click routing (resolve). */
+export type ComponentRegistry = ReturnType<typeof createComponentRegistry>;
+export declare function createComponentRegistry(options?: RegistryOptions): {
+    register(context: ComponentContext): string;
+    resolve(customId: string, atMs: number): ComponentResolution;
+    purgeExpired(atMs: number): number;
+};

package/lib/discord/components.js

@@ -0,0 +1,57 @@
+/**
+ * Opaque component-id correlation for Discord components and modals. The
+ * custom_id Discord echoes back carries none of the adapter's DSH identifiers
+ * — only a registry key — so session, approval, question, and request data
+ * never appear on the Discord wire. Resolution returns the exact pending
+ * context idempotently until its expiry; actor and business validation stay
+ * with the callers, who own what they register.
+ */
+const DEFAULT_PREFIX = 'dc';
+const DISCORD_CUSTOM_ID_MAX = 100;
+export function createComponentRegistry(options = {}) {
+    const prefix = options.prefix ?? DEFAULT_PREFIX;
+    const nextId = options.idFactory ?? (() => {
+        // UnGuessable by default: custom_ids are bearer tokens for interaction
+        // routing, so the fallback must not be enumerable. Web crypto is global
+        // in Node 22+ and every browser target.
+        return globalThis.crypto.randomUUID();
+    });
+    const entries = new Map();
+    function register(context) {
+        let customId = `${prefix}:${nextId()}`;
+        while (entries.has(customId))
+            customId = `${prefix}:${nextId()}`;
+        if (customId.length > DISCORD_CUSTOM_ID_MAX) {
+            throw new TypeError(`custom_id exceeds Discord's ${String(DISCORD_CUSTOM_ID_MAX)}-character limit`);
+        }
+        const expiresAtMs = context['expiresAtMs'];
+        if (typeof expiresAtMs !== 'number' || !Number.isFinite(expiresAtMs)) {
+            throw new TypeError('component context requires a numeric expiresAtMs');
+        }
+        entries.set(customId, { context, expiresAtMs });
+        return customId;
+    }
+    function resolve(customId, atMs) {
+        const entry = entries.get(customId);
+        if (entry === undefined)
+            return { found: false };
+        if (atMs >= entry.expiresAtMs) {
+            // Lazy expiry: the first observation past the deadline retires the
+            // entry, so a stale clock can never resurrect a consumed control.
+            entries.delete(customId);
+            return { found: false };
+        }
+        return { found: true, context: entry.context };
+    }
+    function purgeExpired(atMs) {
+        let purged = 0;
+        for (const [customId, entry] of entries) {
+            if (atMs >= entry.expiresAtMs) {
+                entries.delete(customId);
+                purged += 1;
+            }
+        }
+        return purged;
+    }
+    return { register, resolve, purgeExpired };
+}

package/lib/discord/delivery.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Per-route delivery queues with nonce delivery identity. Writes to one
+ * Discord route (a channel, an interaction token) serialize FIFO so edits can
+ * never reorder terminal output; distinct routes proceed concurrently. A
+ * nonce identifies one in-process delivery claim and cannot be reused while
+ * known, which turns a double-send race into a loud local failure instead of
+ * duplicate Discord output.
+ */
+/** A unique in-process delivery identity; the durable layer binds it to intent records. */
+export interface DeliveryIdentity {
+    nonce: string;
+}
+export interface RouteQueues {
+    /**
+     * Run `op` serialized after every unsettled op previously enqueued on the
+     * same route. Rejects when `identity.nonce` collides with an op that has
+     * not settled yet.
+     */
+    enqueue<T>(route: string, op: () => Promise<T>, identity: DeliveryIdentity): Promise<T>;
+}
+export declare function createRouteQueues(): RouteQueues;