@addozhang/dsh-discord 0.1.0

package/lib/dsh/api-proxy-face.d.ts

@@ -0,0 +1,253 @@
+/**
+ * The typed face over the Host's in-process `ctx.apiProxy` service
+ * (ApiProxyService, the transport-agnostic gateway's direct implementation).
+ * Its domain methods speak the narrow RPC signature: `RpcRequest<P>` in,
+ * `RpcResponse<T>` out, business errors on `result.ok === false` — they never
+ * throw for business outcomes. Two guarantees are added here:
+ *
+ * 1. Boundedness — a Host that never answers must not wedge an interaction
+ *    handler (or a Discord ephemeral) forever; every call races a timeout and
+ *    resolves to an unobservable outcome instead.
+ * 2. Observability — every terminal outcome is reported through the injected
+ *    log sink, so a silent-void call can never again be misread as a hang.
+ */
+import type { ProjectListPort } from '../features/project-list.js';
+import type { WorkspaceResolver } from '../features/project-bind.js';
+/** The workspace rows the catalog port needs (subset of WorkspaceView). */
+export interface WorkspaceCatalogEntry {
+    workspaceId: string;
+    title: string;
+    /** Canonical directory; present in Host responses, rendered only to proven administrators. */
+    path?: string | undefined;
+}
+/** The narrow slice of ApiProxy this module speaks. */
+export interface DshApiProxyFace {
+    workspace: {
+        list(request: RpcRequestShape<Record<string, never>>): Promise<RpcResponseShape<{
+            items: WorkspaceCatalogEntry[];
+        }>>;
+    };
+    sessions: {
+        prompt(request: RpcRequestShape<{
+            sessionId: string;
+            mode: 'queue' | 'steer';
+            content: Array<{
+                type: 'text';
+                text: string;
+            }>;
+        }>): Promise<RpcResponseShape<{
+            accepted: true;
+        }>>;
+        create(request: RpcRequestShape<{
+            workspaceId?: string;
+            sessionId?: string;
+            agentPreset?: string;
+        }>): Promise<RpcResponseShape<{
+            sessionId: string;
+        }>>;
+        cancel(request: RpcRequestShape<{
+            sessionId: string;
+        }>): Promise<RpcResponseShape<{
+            accepted: true;
+        }>>;
+        updateQueue(request: RpcRequestShape<{
+            sessionId: string;
+            itemId: string;
+            action: {
+                kind: 'remove';
+            };
+        }>): Promise<RpcResponseShape<{
+            accepted: true;
+        }>>;
+        list(request: RpcRequestShape<{
+            cursor?: string;
+        }>): Promise<RpcResponseShape<{
+            items: Array<{
+                sessionId: string;
+            }>;
+        }>>;
+    };
+}
+/** Signature-layer narrow request form (RpcId brand erased at this seam). */
+export interface RpcRequestShape<P> {
+    rpcId: string;
+    payload: P;
+}
+/** Signature-layer narrow response form with the business ok/error result. */
+export interface RpcResponseShape<T> {
+    rpcId: string;
+    result: {
+        ok: true;
+        value: T;
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+}
+/** Raised when the Host did not answer within the bounded window. */
+export declare class RpcTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/** Race one apiProxy promise against a bounded window. */
+export declare function withRpcTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+/** Diagnostic sink shared by both faces. */
+export type ApiProxyLog = (event: string, detail?: unknown) => void;
+export interface ApiProxyFaceOptions {
+    timeoutMs?: number;
+    log?: ApiProxyLog;
+}
+/**
+ * The bind flow's catalog verifier: resolves an opaque `ws:` reference
+ * against the live workspace list. A well-formed reference the catalog no
+ * longer knows — and any malformed one — resolve `stale` (fail-closed, no
+ * write can follow); a Host error is `failed`; a timeout is `unknown`.
+ */
+export declare function createWorkspaceResolver(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): WorkspaceResolver;
+/**
+ * The `/project list` catalog port satisfied by the in-process apiProxy.
+ * Outcomes follow the port contract: a definitive Host error is `failed`
+ * (sanitized before Discord), while a timeout or unreadable body is
+ * `unknown` — delivery was not observed, so no retry is implied.
+ */
+export declare function createWorkspaceCatalogPort(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): ProjectListPort;
+export type WorkspaceDetailOutcome = {
+    outcome: 'found';
+    workspace: {
+        id: string;
+        title: string;
+        path: string | undefined;
+    };
+} | {
+    outcome: 'stale';
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Read one Workspace's full view (title plus canonical path). The path is
+ * for the administrator-only ephemeral info response — the disclosure
+ * policy owns whether it ever renders; this face only carries it in memory.
+ */
+export declare function readWorkspaceDetail(dsh: DshApiProxyFace, reference: string, options?: ApiProxyFaceOptions): Promise<WorkspaceDetailOutcome>;
+export type PromptOutcome = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Submit one prompt turn through the in-process apiProxy. A definitive Host
+ * error is a rejection carrying the sanitized code; a timeout is `unknown` —
+ * the turn may or may not have been admitted, so callers must not resubmit.
+ * `options.rpcId` pins the adapter-owned stable request id, which the Host
+ * records on the durable `user/message` (`source.rpcId`) for reconciliation.
+ */
+export declare function promptSession(dsh: DshApiProxyFace, request: {
+    sessionId: string;
+    prompt: string;
+}, options?: ApiProxyFaceOptions & {
+    rpcId?: string;
+}): Promise<PromptOutcome>;
+/**
+ * Steer the session's active turn: `session.prompt` with `mode: 'steer'`,
+ * carrying the same stable request-id discipline as the queue path.
+ */
+export declare function steerSession(dsh: DshApiProxyFace, request: {
+    sessionId: string;
+    prompt: string;
+}, options?: ApiProxyFaceOptions & {
+    rpcId?: string;
+}): Promise<PromptOutcome>;
+export type CreateSessionOutcome = {
+    outcome: 'completed';
+    sessionId: string;
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/**
+ * Create one DSH Session against a preallocated id (design.md §10): DSH
+ * adopts the same session id idempotently, so an uncertain response never
+ * forks a second Session. Same outcome discipline as the prompt path.
+ */
+export declare function createSessionViaProxy(dsh: DshApiProxyFace, request: {
+    sessionId: string;
+    workspaceId: string;
+}, options?: ApiProxyFaceOptions): Promise<CreateSessionOutcome>;
+/** The durable Session-id baseline reconciliation reconciles against. */
+export type SessionIdListOutcome = {
+    outcome: 'completed';
+    ids: string[];
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+/** List durable Session ids (`session.list`, v1 returns everything). */
+export declare function listSessionIds(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): Promise<SessionIdListOutcome>;
+export type CancelOutcome = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/** Cancel the session's active turn (`session.cancel`); DSH preserves the pending inbox. */
+export declare function cancelSessionViaProxy(dsh: DshApiProxyFace, request: {
+    sessionId: string;
+}, options?: ApiProxyFaceOptions): Promise<CancelOutcome>;
+export type QueueRemoveOutcome = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/** Remove one pending inbox item (`session.updateQueue`, action remove). */
+export declare function removeQueueItemViaProxy(dsh: DshApiProxyFace, request: {
+    sessionId: string;
+    itemId: string;
+}, options?: ApiProxyFaceOptions): Promise<QueueRemoveOutcome>;
+/** The carrier verdict apiProxy.respond resolves with (RpcReceipt). */
+export type RespondReceipt = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: 'not-pending' | 'bad-response';
+} | {
+    accepted: unknown;
+};
+export type RespondOutcome = {
+    outcome: 'confirmed';
+} | {
+    outcome: 'rejected';
+    reason: string;
+} | {
+    outcome: 'unknown';
+};
+/**
+ * The respond face for answerable server-requests (approvals, questions).
+ * Builds the full ClientResponse envelope — {type: 'client-response',
+ * rpcId, result: {ok: true, value}} is the wire contract; posting the bare
+ * payload is silently ignored by the Host (rpcId never resolves) — and
+ * maps the RpcReceipt onto the port outcome. Like every call in this module
+ * it is bounded (a Host that never resolves the receipt must not wedge an
+ * interaction handler or an expiry sweep forever) and never throws: a Host
+ * rejection or timeout resolves to `unknown` — the response may or may not
+ * have landed, and the callers park the ask `unresolved` on exactly that.
+ */
+export declare function createClientRespondPort(dsh: {
+    respond(message: unknown): Promise<unknown>;
+}, options?: ApiProxyFaceOptions): {
+    respond(rpcId: string, value: unknown): Promise<RespondOutcome>;
+};

package/lib/dsh/api-proxy-face.js

@@ -0,0 +1,370 @@
+/**
+ * The typed face over the Host's in-process `ctx.apiProxy` service
+ * (ApiProxyService, the transport-agnostic gateway's direct implementation).
+ * Its domain methods speak the narrow RPC signature: `RpcRequest<P>` in,
+ * `RpcResponse<T>` out, business errors on `result.ok === false` — they never
+ * throw for business outcomes. Two guarantees are added here:
+ *
+ * 1. Boundedness — a Host that never answers must not wedge an interaction
+ *    handler (or a Discord ephemeral) forever; every call races a timeout and
+ *    resolves to an unobservable outcome instead.
+ * 2. Observability — every terminal outcome is reported through the injected
+ *    log sink, so a silent-void call can never again be misread as a hang.
+ */
+import { parseWorkspaceReference } from '../policy/disclosure.js';
+/** Raised when the Host did not answer within the bounded window. */
+export class RpcTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`dsh apiProxy call did not answer within ${String(timeoutMs)}ms`);
+        this.name = 'RpcTimeoutError';
+    }
+}
+/** Race one apiProxy promise against a bounded window. */
+export function withRpcTimeout(promise, timeoutMs) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => { reject(new RpcTimeoutError(timeoutMs)); }, timeoutMs);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+}
+/** Default bounded window for unary catalog reads (local, no model work). */
+const CATALOG_TIMEOUT_MS = 5_000;
+/** Default bounded window for prompt admission (the Host may enqueue). */
+const PROMPT_TIMEOUT_MS = 30_000;
+/** Mint a request envelope the way every client shape does. */
+function mintRequest(payload, rpcId) {
+    return { rpcId: rpcId ?? crypto.randomUUID(), payload };
+}
+/**
+ * The bind flow's catalog verifier: resolves an opaque `ws:` reference
+ * against the live workspace list. A well-formed reference the catalog no
+ * longer knows — and any malformed one — resolve `stale` (fail-closed, no
+ * write can follow); a Host error is `failed`; a timeout is `unknown`.
+ */
+export function createWorkspaceResolver(dsh, options = {}) {
+    const port = createWorkspaceCatalogPort(dsh, options);
+    return {
+        async resolve(reference) {
+            const catalog = await port.listWorkspaces();
+            if (catalog.outcome !== 'completed') {
+                return catalog.outcome === 'unknown' ? { outcome: 'unknown' } : { outcome: 'failed' };
+            }
+            const id = parseWorkspaceReference(reference);
+            const found = id === undefined
+                ? undefined
+                : catalog.workspaces.find(workspace => workspace.id === id);
+            return found === undefined
+                ? { outcome: 'stale' }
+                : { outcome: 'found', workspace: { id: found.id, title: found.title } };
+        },
+    };
+}
+/**
+ * The `/project list` catalog port satisfied by the in-process apiProxy.
+ * Outcomes follow the port contract: a definitive Host error is `failed`
+ * (sanitized before Discord), while a timeout or unreadable body is
+ * `unknown` — delivery was not observed, so no retry is implied.
+ */
+export function createWorkspaceCatalogPort(dsh, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
+    const log = options.log;
+    return {
+        async listWorkspaces() {
+            let response;
+            try {
+                response = await withRpcTimeout(dsh.workspace.list(mintRequest({})), timeoutMs);
+            }
+            catch (cause) {
+                if (cause instanceof RpcTimeoutError) {
+                    log?.('discord_workspace_list_timeout', { timeoutMs });
+                    return { outcome: 'unknown' };
+                }
+                log?.('discord_workspace_list_threw', { cause: String(cause) });
+                return { outcome: 'failed' };
+            }
+            // A malformed envelope is a definitive, sanitized failure: the Host
+            // answered, so a retry is safe and semantics stay observable-free.
+            const result = response?.result;
+            if (result === undefined) {
+                log?.('discord_workspace_list_malformed');
+                return { outcome: 'failed' };
+            }
+            if (result.ok) {
+                const items = Array.isArray(result.value.items)
+                    ? result.value.items
+                    : [];
+                return {
+                    outcome: 'completed',
+                    workspaces: items.map(workspace => ({
+                        id: workspace.workspaceId,
+                        title: workspace.title,
+                    })),
+                };
+            }
+            log?.('discord_workspace_list_rejected', {
+                code: result.error.code,
+                message: result.error.message,
+            });
+            return { outcome: 'failed' };
+        },
+    };
+}
+/**
+ * Read one Workspace's full view (title plus canonical path). The path is
+ * for the administrator-only ephemeral info response — the disclosure
+ * policy owns whether it ever renders; this face only carries it in memory.
+ */
+export async function readWorkspaceDetail(dsh, reference, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
+    const log = options.log;
+    let response;
+    try {
+        response = await withRpcTimeout(dsh.workspace.list(mintRequest({})), timeoutMs);
+    }
+    catch (cause) {
+        if (cause instanceof RpcTimeoutError) {
+            log?.('discord_workspace_detail_timeout', { timeoutMs });
+            return { outcome: 'unknown' };
+        }
+        log?.('discord_workspace_detail_threw', { cause: String(cause) });
+        return { outcome: 'failed' };
+    }
+    const result = response?.result;
+    if (result === undefined) {
+        log?.('discord_workspace_detail_malformed');
+        return { outcome: 'failed' };
+    }
+    if (!result.ok) {
+        log?.('discord_workspace_detail_rejected', { code: result.error.code });
+        return { outcome: 'failed' };
+    }
+    const id = parseWorkspaceReference(reference) ?? (reference === '' ? undefined : reference);
+    const found = Array.isArray(result.value.items)
+        ? result.value.items.find(workspace => workspace.workspaceId === id)
+        : undefined;
+    if (found === undefined)
+        return { outcome: 'stale' };
+    return {
+        outcome: 'found',
+        workspace: {
+            id: found.workspaceId,
+            title: found.title,
+            path: typeof found.path === 'string' ? found.path : undefined,
+        },
+    };
+}
+/**
+ * Submit one prompt turn through the in-process apiProxy. A definitive Host
+ * error is a rejection carrying the sanitized code; a timeout is `unknown` —
+ * the turn may or may not have been admitted, so callers must not resubmit.
+ * `options.rpcId` pins the adapter-owned stable request id, which the Host
+ * records on the durable `user/message` (`source.rpcId`) for reconciliation.
+ */
+export async function promptSession(dsh, request, options = {}) {
+    return submitPromptTurn(dsh, { ...request, mode: 'queue' }, options);
+}
+/**
+ * Steer the session's active turn: `session.prompt` with `mode: 'steer'`,
+ * carrying the same stable request-id discipline as the queue path.
+ */
+export async function steerSession(dsh, request, options = {}) {
+    return submitPromptTurn(dsh, { ...request, mode: 'steer' }, options);
+}
+async function submitPromptTurn(dsh, request, options) {
+    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
+    const log = options.log;
+    let response;
+    try {
+        response = await withRpcTimeout(dsh.sessions.prompt(mintRequest({
+            sessionId: request.sessionId,
+            mode: request.mode,
+            content: [{ type: 'text', text: request.prompt }],
+        }, options.rpcId)), timeoutMs);
+    }
+    catch (cause) {
+        if (cause instanceof RpcTimeoutError) {
+            log?.('discord_prompt_submit_timeout', { timeoutMs, sessionId: request.sessionId });
+            return { outcome: 'unknown' };
+        }
+        log?.('discord_prompt_submit_threw', { cause: String(cause), sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    const result = response?.result;
+    if (result === undefined) {
+        // An unreadable body leaves admission unobservable: the turn MAY have
+        // been admitted, so the at-most-once discipline forbids resubmission.
+        log?.('discord_prompt_submit_malformed', { sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    if (result.ok) {
+        // The wire schema pins accepted to literal true; the Host's own zod
+        // parse enforces it before this seam ever sees the body.
+        return { outcome: 'accepted' };
+    }
+    log?.('discord_prompt_submit_rejected', {
+        code: result.error.code,
+        sessionId: request.sessionId,
+    });
+    return { outcome: 'rejected', reason: result.error.code };
+}
+/**
+ * Create one DSH Session against a preallocated id (design.md §10): DSH
+ * adopts the same session id idempotently, so an uncertain response never
+ * forks a second Session. Same outcome discipline as the prompt path.
+ */
+export async function createSessionViaProxy(dsh, request, options = {}) {
+    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
+    const log = options.log;
+    let response;
+    try {
+        response = await withRpcTimeout(dsh.sessions.create(mintRequest({
+            workspaceId: request.workspaceId,
+            sessionId: request.sessionId,
+        })), timeoutMs);
+    }
+    catch (cause) {
+        if (cause instanceof RpcTimeoutError) {
+            log?.('discord_session_create_timeout', { timeoutMs, sessionId: request.sessionId });
+            return { outcome: 'unknown' };
+        }
+        log?.('discord_session_create_threw', { cause: String(cause), sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    const result = response?.result;
+    if (result === undefined) {
+        log?.('discord_session_create_malformed', { sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    if (result.ok) {
+        return { outcome: 'completed', sessionId: result.value.sessionId };
+    }
+    log?.('discord_session_create_rejected', { code: result.error.code, sessionId: request.sessionId });
+    return { outcome: 'rejected', reason: result.error.code };
+}
+/** List durable Session ids (`session.list`, v1 returns everything). */
+export async function listSessionIds(dsh, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
+    const log = options.log;
+    let response;
+    try {
+        response = await withRpcTimeout(dsh.sessions.list(mintRequest({})), timeoutMs);
+    }
+    catch (cause) {
+        if (cause instanceof RpcTimeoutError) {
+            log?.('discord_session_list_timeout', { timeoutMs });
+            return { outcome: 'unknown' };
+        }
+        log?.('discord_session_list_threw', { cause: String(cause) });
+        return { outcome: 'unknown' };
+    }
+    const result = response?.result;
+    if (result === undefined) {
+        log?.('discord_session_list_malformed');
+        return { outcome: 'failed' };
+    }
+    if (result.ok) {
+        return { outcome: 'completed', ids: Array.isArray(result.value.items) ? result.value.items.map(item => item.sessionId) : [] };
+    }
+    log?.('discord_session_list_rejected', { code: result.error.code });
+    return { outcome: 'failed' };
+}
+/** Cancel the session's active turn (`session.cancel`); DSH preserves the pending inbox. */
+export async function cancelSessionViaProxy(dsh, request, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
+    const log = options.log;
+    let response;
+    try {
+        response = await withRpcTimeout(dsh.sessions.cancel(mintRequest({ sessionId: request.sessionId })), timeoutMs);
+    }
+    catch (cause) {
+        if (cause instanceof RpcTimeoutError) {
+            log?.('discord_session_cancel_timeout', { timeoutMs, sessionId: request.sessionId });
+            return { outcome: 'unknown' };
+        }
+        log?.('discord_session_cancel_threw', { cause: String(cause), sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    const result = response?.result;
+    if (result === undefined) {
+        log?.('discord_session_cancel_malformed', { sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    if (result.ok)
+        return { outcome: 'accepted' };
+    log?.('discord_session_cancel_rejected', { code: result.error.code, sessionId: request.sessionId });
+    return { outcome: 'rejected', reason: result.error.code };
+}
+/** Remove one pending inbox item (`session.updateQueue`, action remove). */
+export async function removeQueueItemViaProxy(dsh, request, options = {}) {
+    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
+    const log = options.log;
+    let response;
+    try {
+        response = await withRpcTimeout(dsh.sessions.updateQueue(mintRequest({
+            sessionId: request.sessionId,
+            itemId: request.itemId,
+            action: { kind: 'remove' },
+        })), timeoutMs);
+    }
+    catch (cause) {
+        if (cause instanceof RpcTimeoutError) {
+            log?.('discord_queue_remove_timeout', { timeoutMs, sessionId: request.sessionId });
+            return { outcome: 'unknown' };
+        }
+        log?.('discord_queue_remove_threw', { cause: String(cause), sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    const result = response?.result;
+    if (result === undefined) {
+        log?.('discord_queue_remove_malformed', { sessionId: request.sessionId });
+        return { outcome: 'unknown' };
+    }
+    if (result.ok)
+        return { outcome: 'accepted' };
+    log?.('discord_queue_remove_rejected', { code: result.error.code, sessionId: request.sessionId });
+    return { outcome: 'rejected', reason: result.error.code };
+}
+/**
+ * The respond face for answerable server-requests (approvals, questions).
+ * Builds the full ClientResponse envelope — {type: 'client-response',
+ * rpcId, result: {ok: true, value}} is the wire contract; posting the bare
+ * payload is silently ignored by the Host (rpcId never resolves) — and
+ * maps the RpcReceipt onto the port outcome. Like every call in this module
+ * it is bounded (a Host that never resolves the receipt must not wedge an
+ * interaction handler or an expiry sweep forever) and never throws: a Host
+ * rejection or timeout resolves to `unknown` — the response may or may not
+ * have landed, and the callers park the ask `unresolved` on exactly that.
+ */
+export function createClientRespondPort(dsh, options = {}) {
+    const log = options.log;
+    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
+    return {
+        async respond(rpcId, value) {
+            let receipt;
+            try {
+                const response = await withRpcTimeout(dsh.respond({
+                    type: 'client-response',
+                    rpcId,
+                    result: { ok: true, value },
+                }), timeoutMs);
+                receipt = response;
+            }
+            catch (cause) {
+                const reason = cause instanceof RpcTimeoutError ? 'discord_client_respond_timeout' : 'discord_client_respond_threw';
+                log?.(reason, { rpcId, ...(cause instanceof RpcTimeoutError ? { timeoutMs } : { cause: String(cause) }) });
+                return { outcome: 'unknown' };
+            }
+            const table = receipt;
+            log?.('discord_client_respond_receipt', { rpcId, receipt: table ?? null });
+            if (table?.accepted === true)
+                return { outcome: 'confirmed' };
+            if (table?.accepted === false) {
+                return { outcome: 'rejected', reason: typeof table.reason === 'string' ? table.reason : 'respond-refused' };
+            }
+            return { outcome: 'unknown' };
+        },
+    };
+}