@addozhang/dsh-discord 0.1.0

package/lib/features/question-store.js

@@ -0,0 +1,186 @@
+/**
+ * Pending question records and answer drafts (design.md §8, task 14.1). One
+ * record binds the ownership facts — Session, Discord Thread, owning
+ * adapter-submitted request ID, the answerable question rpcId, originating
+ * user — plus the full question list and one draft answer per question. DSH
+ * answers an ask() as a whole batch or not at all, so drafts may accumulate
+ * but never submit until every question is answered and valid.
+ *
+ * Bounds are Discord's component limits, enforced at open as fail-closed
+ * values: a batch the adapter cannot render is refused rather than silently
+ * truncated. Records are process-local by design — a Host restart invalidates
+ * pending questions, which reconciliation (15.7) treats as unresolved.
+ */
+/** Discord action rows per message — one select each. */
+export const MAX_QUESTIONS_PER_BATCH = 5;
+/** Discord string-select option bound. */
+export const MAX_OPTIONS_PER_QUESTION = 25;
+/** Discord select option label bound (characters). */
+export const MAX_LABEL_LENGTH = 100;
+/** The adapter's own custom-text bound (inside Discord's 4000). */
+export const MAX_CUSTOM_LENGTH = 1000;
+/** Validate one draft answer against its question (pure; also used by routing). */
+export function validateDraftAnswer(question, draft) {
+    if (question === undefined || draft.id !== question.id)
+        return { ok: false, error: 'unknown-question' };
+    const labels = new Set((question.options ?? []).map(option => option.label));
+    if (!draft.selected.every(label => labels.has(label)))
+        return { ok: false, error: 'invalid-label' };
+    if (!question.multiSelect && draft.selected.length > 1)
+        return { ok: false, error: 'invalid-label' };
+    if (draft.custom !== undefined && draft.custom.length > MAX_CUSTOM_LENGTH) {
+        return { ok: false, error: 'custom-too-long' };
+    }
+    return { ok: true };
+}
+/** A batch is complete exactly when every question carries a draft. */
+export function isCompleteDraft(questions, drafts) {
+    return questions.every(question => drafts.has(question.id));
+}
+/** Encode the complete draft into the DSH answer batch (pure). */
+export function encodeAnswer(questions, drafts) {
+    return {
+        answers: questions.map((question) => {
+            const draft = drafts.get(question.id);
+            const selected = draft?.selected ?? [];
+            return {
+                id: question.id,
+                selected,
+                ...(draft?.custom === undefined ? {} : { custom: draft.custom }),
+            };
+        }),
+    };
+}
+function toRecord(entry) {
+    return {
+        ...entry.batch,
+        state: entry.state,
+        ...(entry.resolvedOutcome === undefined ? {} : { resolvedOutcome: entry.resolvedOutcome }),
+        ...(entry.resolvedBy === undefined ? {} : { resolvedBy: entry.resolvedBy }),
+        ...(entry.expiredCancel === undefined ? {} : { expiredCancel: entry.expiredCancel }),
+        draft: questionId => entry.drafts.get(questionId),
+        drafts: () => [...entry.batch.questions.flatMap(question => {
+                const draft = entry.drafts.get(question.id);
+                return draft === undefined ? [] : [draft];
+            })],
+    };
+}
+export function createQuestionStore() {
+    const entries = new Map();
+    const chains = new Map();
+    function entry(rpcId) {
+        return entries.get(rpcId);
+    }
+    /** Per-key serialization: operations on one batch never interleave. */
+    function serialized(rpcId, op) {
+        const tail = chains.get(rpcId) ?? Promise.resolve();
+        const run = tail.then(op, op);
+        chains.set(rpcId, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    function mutate(rpcId, change) {
+        return serialized(rpcId, () => {
+            const found = entries.get(rpcId);
+            if (found === undefined)
+                return;
+            change(found);
+        });
+    }
+    return {
+        get(rpcId) {
+            const found = entry(rpcId);
+            return found === undefined ? undefined : toRecord(found);
+        },
+        open(candidate) {
+            const existing = entries.get(candidate.questionRpcId);
+            if (existing !== undefined)
+                return { ok: true };
+            if (candidate.questions.length > MAX_QUESTIONS_PER_BATCH)
+                return { ok: false, error: 'too-many-questions' };
+            for (const question of candidate.questions) {
+                const options = question.options ?? [];
+                if (options.length === 0)
+                    return { ok: false, error: 'options-required' };
+                if (options.length > MAX_OPTIONS_PER_QUESTION)
+                    return { ok: false, error: 'too-many-options' };
+                if (options.some(option => option.label.length > MAX_LABEL_LENGTH)) {
+                    return { ok: false, error: 'option-label-too-long' };
+                }
+            }
+            entries.set(candidate.questionRpcId, {
+                batch: candidate,
+                state: 'pending',
+                drafts: new Map(),
+            });
+            return { ok: true };
+        },
+        setDraft(rpcId, draft) {
+            const found = entry(rpcId);
+            if (found === undefined)
+                return { ok: false, error: 'unknown-question' };
+            const question = found.batch.questions.find(item => item.id === draft.id);
+            const verdict = validateDraftAnswer(question, draft);
+            if (!verdict.ok)
+                return verdict;
+            found.drafts.set(draft.id, draft);
+            return { ok: true, complete: isCompleteDraft(found.batch.questions, found.drafts) };
+        },
+        takeDrafts(rpcId) {
+            const found = entry(rpcId);
+            if (found === undefined)
+                return [];
+            return found.batch.questions.flatMap(question => {
+                const draft = found.drafts.get(question.id);
+                return draft === undefined ? [] : [draft];
+            });
+        },
+        encodeSubmitted(rpcId) {
+            const found = entry(rpcId);
+            if (found === undefined)
+                return { answers: [] };
+            return encodeAnswer(found.batch.questions, found.drafts);
+        },
+        claim(rpcId) {
+            return serialized(rpcId, () => {
+                const found = entries.get(rpcId);
+                if (found === undefined)
+                    return { outcome: 'unknown' };
+                const claimable = found.state === 'pending' || found.state === 'unresolved';
+                if (!claimable)
+                    return { outcome: 'not-claimable', record: toRecord(found) };
+                found.state = 'submitting';
+                return { outcome: 'claimed', record: toRecord(found) };
+            });
+        },
+        markResolved(rpcId, outcome, by, _atMs) {
+            return mutate(rpcId, (found) => {
+                // First resolution wins: a remote frame arriving after the user's own
+                // recorded answer retires controls elsewhere, never rewrites history.
+                if (found.state === 'resolved')
+                    return;
+                found.state = 'resolved';
+                found.resolvedOutcome = outcome;
+                found.resolvedBy = by;
+            });
+        },
+        markUnresolved(rpcId, _atMs) {
+            return mutate(rpcId, (found) => {
+                found.state = 'unresolved';
+            });
+        },
+        listPendingExpired(atMs) {
+            const expired = [];
+            for (const entry of entries.values()) {
+                if (entry.state === 'pending' && atMs >= entry.batch.expiresAtMs)
+                    expired.push(toRecord(entry));
+            }
+            return expired;
+        },
+        markExpired(rpcId, cancel, _atMs) {
+            return mutate(rpcId, (found) => {
+                found.state = 'expired';
+                found.expiredCancel = cancel;
+            });
+        },
+    };
+}

package/lib/features/question-view.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Question control rendering (design.md §8, task 14.1). One pending ask()
+ * batch renders as one string select per question — Discord's min/max values
+ * carry the multi-select semantics — plus a Submit button when the five-row
+ * budget allows (a full batch auto-submits when its last answer lands). Every
+ * custom_id is an opaque registry key: rpc ids, question ids, session, and
+ * labels never ride the Discord wire. Option values are the host's own
+ * labels, validated against the batch before any answer is recorded.
+ */
+import type { ComponentRegistry } from '../discord/components.js';
+import { DISCORD_SUPPRESS_NOTIFICATIONS_FLAG } from '../policy/disclosure.js';
+import { type QuestionBatch } from './question-store.js';
+/** Discord interactive-component ids (action row = 1, button = 2, string select = 3). */
+declare const ACTION_ROW = 1;
+declare const BUTTON = 2;
+declare const STRING_SELECT = 3;
+declare const BUTTON_STYLE_PRIMARY = 1;
+/** The reserved select value that routes a question to the custom-text modal. */
+export declare const CUSTOM_ANSWER_VALUE = "__custom__";
+export interface QuestionViewInput {
+    registry: ComponentRegistry;
+    batch: QuestionBatch;
+}
+export interface QuestionSelectComponent {
+    type: typeof STRING_SELECT;
+    custom_id: string;
+    options: Array<{
+        label: string;
+        value: string;
+        description?: string | undefined;
+    }>;
+    min_values: number;
+    max_values: number;
+    placeholder?: string | undefined;
+}
+export interface QuestionButtonComponent {
+    type: typeof BUTTON;
+    style: typeof BUTTON_STYLE_PRIMARY;
+    label: string;
+    custom_id: string;
+}
+export interface QuestionRow {
+    type: typeof ACTION_ROW;
+    components: Array<QuestionSelectComponent | QuestionButtonComponent>;
+}
+export interface QuestionViewPayload {
+    content: string;
+    flags: typeof DISCORD_SUPPRESS_NOTIFICATIONS_FLAG;
+    components: QuestionRow[];
+}
+/**
+ * Render one pending question batch. Selects carry a trailing "Other…"
+ * option (value `__custom__`) whose selection opens the custom-text modal —
+ * see question-routing's modal flow. Registry contexts expose
+ * `{ questionRpcId, action: 'select' | 'submit', questionId?, expiresAtMs }`.
+ */
+export declare function renderQuestionControls(input: QuestionViewInput): QuestionViewPayload;
+export {};

package/lib/features/question-view.js

@@ -0,0 +1,81 @@
+/**
+ * Question control rendering (design.md §8, task 14.1). One pending ask()
+ * batch renders as one string select per question — Discord's min/max values
+ * carry the multi-select semantics — plus a Submit button when the five-row
+ * budget allows (a full batch auto-submits when its last answer lands). Every
+ * custom_id is an opaque registry key: rpc ids, question ids, session, and
+ * labels never ride the Discord wire. Option values are the host's own
+ * labels, validated against the batch before any answer is recorded.
+ */
+import { DISCORD_SUPPRESS_NOTIFICATIONS_FLAG } from '../policy/disclosure.js';
+import { suppressMentionSyntax } from '../policy/suppress.js';
+import { MAX_CUSTOM_LENGTH, MAX_LABEL_LENGTH, } from './question-store.js';
+/** Discord interactive-component ids (action row = 1, button = 2, string select = 3). */
+const ACTION_ROW = 1;
+const BUTTON = 2;
+const STRING_SELECT = 3;
+const BUTTON_STYLE_PRIMARY = 1;
+/** The reserved select value that routes a question to the custom-text modal. */
+export const CUSTOM_ANSWER_VALUE = '__custom__';
+function boundedQuestionText(text) {
+    const neutralized = suppressMentionSyntax(text);
+    return neutralized.length <= MAX_LABEL_LENGTH ? neutralized : `${neutralized.slice(0, MAX_LABEL_LENGTH)}…`;
+}
+function selectFor(registry, batch, question) {
+    const options = (question.options ?? []).map(option => ({
+        label: option.label,
+        value: option.label,
+        ...(option.description === undefined ? {} : { description: option.description }),
+    }));
+    const customLabel = `Other — tell us in your own words`;
+    options.push({ label: customLabel, value: CUSTOM_ANSWER_VALUE });
+    return {
+        type: STRING_SELECT,
+        custom_id: registry.register({
+            questionRpcId: batch.questionRpcId,
+            action: 'select',
+            questionId: question.id,
+            expiresAtMs: batch.expiresAtMs,
+        }),
+        options,
+        min_values: 1,
+        max_values: question.multiSelect ? Math.min(options.length, 25) : 1,
+        ...(question.header === undefined ? {} : { placeholder: boundedQuestionText(question.header) }),
+    };
+}
+/**
+ * Render one pending question batch. Selects carry a trailing "Other…"
+ * option (value `__custom__`) whose selection opens the custom-text modal —
+ * see question-routing's modal flow. Registry contexts expose
+ * `{ questionRpcId, action: 'select' | 'submit', questionId?, expiresAtMs }`.
+ */
+export function renderQuestionControls(input) {
+    const { registry, batch } = input;
+    const rows = batch.questions.map(question => ({
+        type: ACTION_ROW,
+        components: [selectFor(registry, batch, question)],
+    }));
+    if (batch.questions.length < 5) {
+        rows.push({
+            type: ACTION_ROW,
+            components: [{
+                    type: BUTTON,
+                    style: BUTTON_STYLE_PRIMARY,
+                    label: 'Submit answers',
+                    custom_id: registry.register({
+                        questionRpcId: batch.questionRpcId,
+                        action: 'submit',
+                        expiresAtMs: batch.expiresAtMs,
+                    }),
+                }],
+        });
+    }
+    const header = batch.questions.length === 1
+        ? boundedQuestionText(batch.questions[0]?.question ?? 'Questions')
+        : `${String(batch.questions.length)} questions need answers`;
+    return {
+        content: `${header} (answers stay editable until you submit; custom text up to ${String(MAX_CUSTOM_LENGTH)} characters)`,
+        flags: DISCORD_SUPPRESS_NOTIFICATIONS_FLAG,
+        components: rows,
+    };
+}

package/lib/features/queue-control.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `/queue list` and `/queue remove <item>` (design.md §13, task 8.6). The
+ * list renders the session's pending inbox in queue order with stable
+ * positions; removal targets exactly one item. Every DSH outcome maps to a
+ * value, and unknown removal outcomes stay unknown — reconciliation, not
+ * optimism, decides whether the item is really gone.
+ */
+export interface DshQueuePort {
+    snapshot(request: {
+        sessionId: string;
+    }): Promise<{
+        outcome: 'completed';
+        items: Array<{
+            itemId: string;
+            summary: string;
+            requestedBy: string;
+        }>;
+    } | {
+        outcome: 'rejected';
+        reason: string;
+    } | {
+        outcome: 'unknown';
+    }>;
+    remove(request: {
+        sessionId: string;
+        itemId: string;
+    }): Promise<{
+        outcome: 'completed';
+        removed: boolean;
+    } | {
+        outcome: 'rejected';
+        reason: string;
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+export type QueueListView = {
+    outcome: 'ok';
+    items: Array<{
+        itemId: string;
+        position: number;
+        summary: string;
+    }>;
+} | {
+    outcome: 'failed';
+    reason: 'queue-unavailable' | 'queue-unknown';
+};
+export declare function listQueue(queue: DshQueuePort, request: {
+    sessionId: string;
+}): Promise<QueueListView>;
+export type QueueRemoveResult = {
+    outcome: 'removed';
+} | {
+    outcome: 'not-found';
+} | {
+    outcome: 'failed';
+} | {
+    outcome: 'unknown';
+};
+export declare function removeQueueItem(queue: DshQueuePort, request: {
+    sessionId: string;
+    itemId: string;
+}): Promise<QueueRemoveResult>;

package/lib/features/queue-control.js

@@ -0,0 +1,31 @@
+/**
+ * `/queue list` and `/queue remove <item>` (design.md §13, task 8.6). The
+ * list renders the session's pending inbox in queue order with stable
+ * positions; removal targets exactly one item. Every DSH outcome maps to a
+ * value, and unknown removal outcomes stay unknown — reconciliation, not
+ * optimism, decides whether the item is really gone.
+ */
+export async function listQueue(queue, request) {
+    const snapshot = await queue.snapshot({ sessionId: request.sessionId });
+    if (snapshot.outcome === 'rejected')
+        return { outcome: 'failed', reason: 'queue-unavailable' };
+    if (snapshot.outcome === 'unknown')
+        return { outcome: 'failed', reason: 'queue-unknown' };
+    return {
+        outcome: 'ok',
+        items: snapshot.items.map((item, index) => ({
+            itemId: item.itemId,
+            position: index + 1,
+            summary: item.summary,
+        })),
+    };
+}
+export async function removeQueueItem(queue, request) {
+    const removed = await queue.remove({ sessionId: request.sessionId, itemId: request.itemId });
+    if (removed.outcome === 'completed') {
+        return removed.removed ? { outcome: 'removed' } : { outcome: 'not-found' };
+    }
+    if (removed.outcome === 'unknown')
+        return { outcome: 'unknown' };
+    return { outcome: 'failed' };
+}

package/lib/features/reconcile-bindings.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Binding reconciliation (design.md §11 steps 1–2, 8–9; task 15.1/15.2). At
+ * startup every persisted mapping is checked against the DSH Workspace and
+ * Session baseline and the Discord channel surface. Retirement ever removes
+ * only the adapter's own record — Host Workspaces and Sessions are never
+ * deleted by the adapter — and a mapping the adapter cannot verify right now
+ * stays in a blocked state for a later sweep instead of being guessed away.
+ */
+import type { ChannelBinding, ThreadBinding } from '../state/records.js';
+/** The DSH baseline the adapter reconciles against (workspace.list / session list). */
+export interface DshBaseline {
+    workspaces: ReadonlyArray<{
+        workspaceId: string;
+        title: string;
+        path: string;
+    }>;
+    sessionIds: ReadonlySet<string> | readonly string[];
+}
+/** Discord channel reachability as observed through the REST surface. */
+export type DiscordChannelStatus = 'ok' | 'missing' | 'unknown';
+export interface DiscordChannelFacts {
+    channels: Readonly<Record<string, DiscordChannelStatus>>;
+}
+export type ChannelBindingAction = {
+    channelId: string;
+    action: 'keep';
+} | {
+    channelId: string;
+    action: 'keep-blocked';
+    reason: 'discord-unverified';
+} | {
+    channelId: string;
+    action: 'retire';
+    reason: 'workspace-missing' | 'discord-deleted';
+} | {
+    channelId: string;
+    action: 'update-metadata';
+    metadata: {
+        title: string;
+        path: string;
+    };
+};
+export type ThreadBindingAction = {
+    threadId: string;
+    action: 'keep';
+} | {
+    threadId: string;
+    action: 'keep-blocked';
+    reason: 'discord-unverified';
+} | {
+    threadId: string;
+    action: 'retire';
+    reason: 'workspace-missing' | 'session-missing' | 'discord-deleted';
+};
+export interface BindingReconciliationInput {
+    channelBindings: ReadonlyArray<ChannelBinding & {
+        channelId: string;
+    }>;
+    threadBindings: ReadonlyArray<ThreadBinding & {
+        threadId: string;
+    }>;
+    baseline: DshBaseline;
+    discord: DiscordChannelFacts;
+    /** The adapter's cached Workspace labels; a mismatch plans a refresh. */
+    cachedWorkspaceMetadata?: Readonly<Record<string, {
+        title: string;
+        path: string;
+    }>> | undefined;
+}
+export interface BindingReconciliationPlan {
+    channelActions: ChannelBindingAction[];
+    threadActions: ThreadBindingAction[];
+}
+/** Plan one reconciliation pass. Pure: callers decide how actions are applied. */
+export declare function planBindingReconciliation(input: BindingReconciliationInput): BindingReconciliationPlan;

package/lib/features/reconcile-bindings.js

@@ -0,0 +1,54 @@
+/**
+ * Binding reconciliation (design.md §11 steps 1–2, 8–9; task 15.1/15.2). At
+ * startup every persisted mapping is checked against the DSH Workspace and
+ * Session baseline and the Discord channel surface. Retirement ever removes
+ * only the adapter's own record — Host Workspaces and Sessions are never
+ * deleted by the adapter — and a mapping the adapter cannot verify right now
+ * stays in a blocked state for a later sweep instead of being guessed away.
+ */
+function workspaceSet(baseline) {
+    return new Map(baseline.workspaces.map(workspace => [workspace.workspaceId, { title: workspace.title, path: workspace.path }]));
+}
+function sessionSet(baseline) {
+    return new Set(baseline.sessionIds);
+}
+/** Plan one reconciliation pass. Pure: callers decide how actions are applied. */
+export function planBindingReconciliation(input) {
+    const workspaces = workspaceSet(input.baseline);
+    const sessions = sessionSet(input.baseline);
+    const channelActions = input.channelBindings.map((binding) => {
+        const workspace = workspaces.get(binding.workspaceId);
+        if (workspace === undefined) {
+            return { channelId: binding.channelId, action: 'retire', reason: 'workspace-missing' };
+        }
+        const status = input.discord.channels[binding.channelId];
+        if (status === 'missing') {
+            return { channelId: binding.channelId, action: 'retire', reason: 'discord-deleted' };
+        }
+        if (status === 'unknown') {
+            return { channelId: binding.channelId, action: 'keep-blocked', reason: 'discord-unverified' };
+        }
+        const cached = input.cachedWorkspaceMetadata?.[binding.workspaceId];
+        if (cached !== undefined && (cached.title !== workspace.title || cached.path !== workspace.path)) {
+            return { channelId: binding.channelId, action: 'update-metadata', metadata: workspace };
+        }
+        return { channelId: binding.channelId, action: 'keep' };
+    });
+    const threadActions = input.threadBindings.map((binding) => {
+        if (!workspaces.has(binding.workspaceId)) {
+            return { threadId: binding.threadId, action: 'retire', reason: 'workspace-missing' };
+        }
+        if (!sessions.has(binding.sessionId)) {
+            return { threadId: binding.threadId, action: 'retire', reason: 'session-missing' };
+        }
+        const status = input.discord.channels[binding.threadId];
+        if (status === 'missing') {
+            return { threadId: binding.threadId, action: 'retire', reason: 'discord-deleted' };
+        }
+        if (status === 'unknown') {
+            return { threadId: binding.threadId, action: 'keep-blocked', reason: 'discord-unverified' };
+        }
+        return { threadId: binding.threadId, action: 'keep' };
+    });
+    return { channelActions, threadActions };
+}

package/lib/features/reconcile-deliveries.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Discord delivery reconciliation (design.md §11 step 7, task 15.6). An
+ * outbound delivery parked in an unknown state is resolved by evidence: one
+ * bounded GET against Discord — present proves delivery, a confirmed 404
+ * proves failure — and an unreachable probe leaves the record unknown for a
+ * later sweep. The reconciliation deps carry no send face: recovery never
+ * resends, it only settles what already happened.
+ */
+export interface DeliveryLookupInput {
+    deliveryId: string;
+    channelId: string;
+    messageId: string;
+}
+export interface DeliveryReconcileDeps {
+    resolve(deliveryId: string, outcome: 'succeeded' | 'failed' | 'unknown', atMs: number): Promise<void>;
+    messageProbe(channelId: string, messageId: string): Promise<'present' | 'missing' | 'unknown'>;
+    nowMs: () => number;
+}
+export interface DeliveryReconcileInput {
+    deliveries: readonly DeliveryLookupInput[];
+    /** Bound per sweep; leftovers wait for the next one. */
+    maxLookups: number;
+}
+export interface DeliveryReconcileResult {
+    delivered: string[];
+    failed: string[];
+    unresolved: string[];
+}
+export declare function reconcileDeliveries(deps: DeliveryReconcileDeps, input: DeliveryReconcileInput): Promise<DeliveryReconcileResult>;

package/lib/features/reconcile-deliveries.js

@@ -0,0 +1,28 @@
+/**
+ * Discord delivery reconciliation (design.md §11 step 7, task 15.6). An
+ * outbound delivery parked in an unknown state is resolved by evidence: one
+ * bounded GET against Discord — present proves delivery, a confirmed 404
+ * proves failure — and an unreachable probe leaves the record unknown for a
+ * later sweep. The reconciliation deps carry no send face: recovery never
+ * resends, it only settles what already happened.
+ */
+export async function reconcileDeliveries(deps, input) {
+    const delivered = [];
+    const failed = [];
+    const unresolved = [];
+    for (const record of input.deliveries.slice(0, input.maxLookups)) {
+        const probe = await deps.messageProbe(record.channelId, record.messageId);
+        if (probe === 'present') {
+            await deps.resolve(record.deliveryId, 'succeeded', deps.nowMs());
+            delivered.push(record.deliveryId);
+            continue;
+        }
+        if (probe === 'missing') {
+            await deps.resolve(record.deliveryId, 'failed', deps.nowMs());
+            failed.push(record.deliveryId);
+            continue;
+        }
+        unresolved.push(record.deliveryId);
+    }
+    return { delivered, failed, unresolved };
+}

package/lib/features/reconcile-events.d.ts

@@ -0,0 +1,49 @@
+/**
+ * History replay after reconnect (design.md §11 steps 4–7, tasks 15.3/15.4).
+ * Because DSH 0.1.1-rc.2 ignores `events.mux.since`, durable history reads —
+ * not the live stream — are the recovery source. Per active session the
+ * replay walks bounded history pages, folds events past the committed
+ * watermark oldest-first, skips events whose live delivery is already known,
+ * and advances the watermark strictly after the delivery bookkeeping for that
+ * event resolves. The page budget bounds recovery work; hitting it yields an
+ * explicitly incomplete result rather than an unbounded fetch loop.
+ */
+export interface HistoryEvent {
+    seq: number;
+    id: string;
+}
+/** One history page: events ascending within the page, newest page first. */
+export interface HistoryPage {
+    events: HistoryEvent[];
+    hasMore: boolean;
+}
+export interface EventHistoryPort {
+    /** `beforeSeq === undefined` reads the newest page; older pages chain down. */
+    history(sessionId: string, beforeSeq: number | undefined): Promise<HistoryPage>;
+}
+export interface ReplayDeliverPort {
+    /** Deliver one missed event; the return is the delivery bookkeeping. */
+    deliver(event: HistoryEvent): Promise<'recorded' | 'duplicate'>;
+}
+export interface ReplayWatermarkStore {
+    watermark(sessionId: string): number | undefined;
+    commit(sessionId: string, seq: number): Promise<void>;
+}
+export interface ReplayDeps {
+    historyPort: EventHistoryPort;
+    deliver: ReplayDeliverPort;
+    watermarkStore: ReplayWatermarkStore;
+}
+export interface ReplayInput {
+    sessionId: string;
+    /** Ids already delivered live across the reconnect gap. */
+    liveSeen?: ReadonlySet<string> | undefined;
+    /** Page budget; recovery reports incomplete past this instead of looping. */
+    maxPages?: number | undefined;
+}
+export interface ReplayResult {
+    delivered: string[];
+    committedThrough?: number | undefined;
+    incomplete: boolean;
+}
+export declare function replayHistory(deps: ReplayDeps, input: ReplayInput): Promise<ReplayResult>;