@addozhang/dsh-discord 0.1.0

package/lib/state/fail-closed.js

@@ -0,0 +1,57 @@
+/**
+ * Fail-closed integrity gate over a binding store (design.md §10). Storage
+ * records are validated against the strict zod schema on every access:
+ * malformed or NEWER-format records make the key read as corrupt, and every
+ * Discord-triggered write refuses — the record is never replaced, repaired,
+ * or emptied by the adapter. Backend durability failures surface as plain
+ * values so callers can retry or alert without a crash crossing the dispatch
+ * loop.
+ */
+export function createFailClosedBindingStore(inner, schema, raw) {
+    function diagnose(key) {
+        const record = raw.get(key);
+        if (record === undefined || record === null)
+            return { state: 'missing' };
+        const parsed = schema.safeParse(record);
+        if (parsed.success)
+            return { state: 'ok' };
+        return {
+            state: 'corrupt',
+            issues: parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`),
+        };
+    }
+    function guard(key) {
+        return diagnose(key).state === 'corrupt' ? 'state-corrupt' : undefined;
+    }
+    async function durable(operation) {
+        try {
+            return await operation();
+        }
+        catch (cause) {
+            return { ok: false, error: 'durable-write-failed', cause };
+        }
+    }
+    return {
+        get(key) {
+            // Read-path integrity: a corrupt or newer-format record never reaches
+            // the business layer typed as a validated V. Callers that need the
+            // reason ask `diagnose(key)` explicitly.
+            if (guard(key) === 'state-corrupt')
+                return undefined;
+            return inner.get(key);
+        },
+        diagnose,
+        async bind(key, record, options) {
+            if (guard(key) === 'state-corrupt')
+                return { ok: false, error: 'state-corrupt' };
+            const result = await durable(() => inner.bind(key, record, options));
+            return result;
+        },
+        async release(key, options) {
+            if (guard(key) === 'state-corrupt')
+                return { ok: false, error: 'state-corrupt' };
+            const result = await durable(() => inner.release(key, options));
+            return result;
+        },
+    };
+}

package/lib/state/intents.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Inbound intent records (design.md §10). The stable Discord message identity
+ * plus the normalized payload hash are claimed atomically before any DSH
+ * call, so every later delivery of the same message either reuses the record
+ * (same-ID/same-hash) or fails closed (same-ID/different-hash — a tampered or
+ * ambiguous replay). Unknown outcomes are recorded and retained, never
+ * silently rewritten.
+ */
+/** SHA-256 over the canonical JSON of the normalized payload. */
+export declare function hashPayload(payload: unknown): Promise<string>;
+export type IntentState = 'claimed' | 'succeeded' | 'failed' | 'unknown';
+export interface InboundIntentRecord {
+    contentHash: string;
+    state: IntentState;
+    claimedAtMs: number;
+    resolvedAtMs?: number | undefined;
+    /** Correlation: the Discord thread created for this source message. */
+    threadId?: string | undefined;
+}
+export interface ClaimRequest {
+    messageId: string;
+    contentHash: string;
+    claimedAtMs: number;
+    /** Test/diagnostic hook run inside the serialized claim slot. */
+    beforeClaim?: () => Promise<void> | void;
+}
+export type ClaimOutcome = {
+    outcome: 'claimed';
+} | {
+    outcome: 'duplicate';
+    record: InboundIntentRecord;
+} | {
+    outcome: 'conflict';
+    record: InboundIntentRecord;
+};
+export type ResolveOutcome = 'succeeded' | 'failed' | 'unknown';
+/** Minimal durable face (the domain's KvTable provides it). */
+export interface IntentTable {
+    get(messageId: string): InboundIntentRecord | undefined;
+    put(messageId: string, record: InboundIntentRecord): Promise<void>;
+}
+export interface IntentStore {
+    get(messageId: string): InboundIntentRecord | undefined;
+    claim(request: ClaimRequest): Promise<ClaimOutcome>;
+    resolve(messageId: string, outcome: ResolveOutcome, atMs: number): Promise<void>;
+    /** Record the correlation thread for this intent, serialized. */
+    annotate(messageId: string, correlation: {
+        threadId: string;
+    }): Promise<void>;
+}
+export declare function createIntentStore(table: IntentTable): IntentStore;

package/lib/state/intents.js

@@ -0,0 +1,73 @@
+/**
+ * Inbound intent records (design.md §10). The stable Discord message identity
+ * plus the normalized payload hash are claimed atomically before any DSH
+ * call, so every later delivery of the same message either reuses the record
+ * (same-ID/same-hash) or fails closed (same-ID/different-hash — a tampered or
+ * ambiguous replay). Unknown outcomes are recorded and retained, never
+ * silently rewritten.
+ */
+import { createHash } from 'node:crypto';
+/** Canonical JSON: recursively sorted keys, so hash equality is structural. */
+function stableValue(value) {
+    if (Array.isArray(value))
+        return `[${value.map(item => stableValue(item)).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableValue(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** SHA-256 over the canonical JSON of the normalized payload. */
+export function hashPayload(payload) {
+    return Promise.resolve(createHash('sha256').update(stableValue(payload)).digest('hex'));
+}
+const noBeforeClaim = () => { };
+export function createIntentStore(table) {
+    const chains = new Map();
+    function enqueue(messageId, op) {
+        const tail = chains.get(messageId) ?? Promise.resolve();
+        const run = tail.then(op, op);
+        chains.set(messageId, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    return {
+        get: messageId => table.get(messageId),
+        claim(request) {
+            return enqueue(request.messageId, async () => {
+                const hook = request.beforeClaim ?? noBeforeClaim;
+                await Promise.resolve().then(hook);
+                const existing = table.get(request.messageId);
+                if (existing !== undefined) {
+                    // Same identity, different content: refuse rather than guess.
+                    if (existing.contentHash !== request.contentHash) {
+                        return { outcome: 'conflict', record: existing };
+                    }
+                    return { outcome: 'duplicate', record: existing };
+                }
+                const record = {
+                    contentHash: request.contentHash,
+                    state: 'claimed',
+                    claimedAtMs: request.claimedAtMs,
+                };
+                await table.put(request.messageId, record);
+                return { outcome: 'claimed' };
+            });
+        },
+        resolve(messageId, outcome, atMs) {
+            return enqueue(messageId, async () => {
+                const existing = table.get(messageId);
+                if (existing === undefined)
+                    return;
+                await table.put(messageId, { ...existing, state: outcome, resolvedAtMs: atMs });
+            });
+        },
+        annotate(messageId, correlation) {
+            return enqueue(messageId, async () => {
+                const existing = table.get(messageId);
+                if (existing === undefined)
+                    return;
+                await table.put(messageId, { ...existing, threadId: correlation.threadId });
+            });
+        },
+    };
+}

package/lib/state/records.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Binding record schemas, validated by zod at the durable boundary. The
+ * schemas are strict: unknown fields reject, so state written by a newer
+ * format fails closed instead of silently half-decoding.
+ */
+import { z } from 'zod';
+/** One channel-to-workspace binding; `revision` fences stale writes (6.2). */
+export declare const ChannelBindingRecord: z.ZodObject<{
+    workspaceId: z.ZodString;
+    revision: z.ZodNumber;
+    boundBy: z.ZodString;
+    boundAtMs: z.ZodNumber;
+}, z.core.$strict>;
+export type ChannelBinding = z.infer<typeof ChannelBindingRecord>;
+/** One inbound intent record; the durable at-most-once claim (design §10). */
+export declare const InboundIntentRecordSchema: z.ZodObject<{
+    contentHash: z.ZodString;
+    state: z.ZodEnum<{
+        claimed: "claimed";
+        unknown: "unknown";
+        succeeded: "succeeded";
+        failed: "failed";
+    }>;
+    claimedAtMs: z.ZodNumber;
+    resolvedAtMs: z.ZodOptional<z.ZodNumber>;
+    threadId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type InboundIntentRecordSchema = z.infer<typeof InboundIntentRecordSchema>;
+/** One thread-to-session writable binding; `revision` fences stale writes. */
+export declare const ThreadBindingRecord: z.ZodObject<{
+    sessionId: z.ZodString;
+    workspaceId: z.ZodString;
+    revision: z.ZodNumber;
+    createdBy: z.ZodString;
+    createdAtMs: z.ZodNumber;
+}, z.core.$strict>;
+export type ThreadBinding = z.infer<typeof ThreadBindingRecord>;

package/lib/state/records.js

@@ -0,0 +1,30 @@
+/**
+ * Binding record schemas, validated by zod at the durable boundary. The
+ * schemas are strict: unknown fields reject, so state written by a newer
+ * format fails closed instead of silently half-decoding.
+ */
+import { z } from 'zod';
+/** One channel-to-workspace binding; `revision` fences stale writes (6.2). */
+export const ChannelBindingRecord = z.strictObject({
+    workspaceId: z.string().min(1),
+    revision: z.number().int().min(1),
+    /** Discord user id that performed the bind. */
+    boundBy: z.string().min(1),
+    boundAtMs: z.number().int().min(0),
+});
+/** One inbound intent record; the durable at-most-once claim (design §10). */
+export const InboundIntentRecordSchema = z.strictObject({
+    contentHash: z.string().min(1),
+    state: z.enum(['claimed', 'succeeded', 'failed', 'unknown']),
+    claimedAtMs: z.number().int().min(0),
+    resolvedAtMs: z.number().int().min(0).optional(),
+    threadId: z.string().min(1).optional(),
+});
+/** One thread-to-session writable binding; `revision` fences stale writes. */
+export const ThreadBindingRecord = z.strictObject({
+    sessionId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    revision: z.number().int().min(1),
+    createdBy: z.string().min(1),
+    createdAtMs: z.number().int().min(0),
+});

package/lib/state/retention.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Bounded retention and Guild forget (design.md §10). Completed intents and
+ * deliveries default to 30-day retention; resolved interactions to 7 days;
+ * no configured window may drop below the 7-day floor. Unresolved records —
+ * claimed prompts and unknown outcomes — never expire on a timer: they wait
+ * for explicit user resolution or a Guild forget. Active channel/thread
+ * bindings are ownership, not history, and no retention rule touches them.
+ * A Guild forget plans the removal of only that guild's adapter records;
+ * DSH workspaces and sessions are structurally out of reach.
+ */
+import type { InboundIntentRecord } from './intents.js';
+/** The retention floor: no configured window may go below 7 days. */
+export declare const MINIMUM_RETENTION_MS: number;
+/** Default retention for completed (succeeded/failed) intents and deliveries. */
+export declare const DEFAULT_COMPLETED_RETENTION_MS: number;
+/** Default retention for resolved interactions. */
+export declare const DEFAULT_INTERACTION_RETENTION_MS: number;
+export interface RetentionPolicy {
+    completedRetentionMs?: number | undefined;
+    interactionRetentionMs?: number | undefined;
+}
+export interface NormalizedRetentionPolicy {
+    completedRetentionMs: number;
+    interactionRetentionMs: number;
+}
+/** Clamp a policy into the legal range, applying defaults. */
+export declare function normalizeRetentionPolicy(policy: RetentionPolicy): NormalizedRetentionPolicy;
+/** Resolved-intent record shape (subset) the sweep reasons about. */
+export interface SweepableIntent {
+    state: InboundIntentRecord['state'];
+    resolvedAtMs?: number | undefined;
+}
+export interface SweepableInteraction {
+    resolvedAtMs: number;
+}
+export interface SweepInput {
+    intents: ReadonlyArray<[string, SweepableIntent]>;
+    resolvedInteractions: ReadonlyArray<[string, SweepableInteraction]>;
+}
+export interface SweepOptions {
+    nowMs: number;
+    policy?: RetentionPolicy | undefined;
+}
+export interface SweepPlan {
+    intentKeys: string[];
+    interactionKeys: string[];
+}
+/**
+ * Plan one retention sweep. Only terminal, resolved records age out:
+ * `claimed` and `unknown` intents are retained indefinitely (unknown until
+ * explicit user resolution), regardless of age.
+ */
+export declare function sweepExpired(input: SweepInput, options: SweepOptions): SweepPlan;
+export interface ForgetPlanInput {
+    guildId: string;
+    channelBindingKeys: readonly string[];
+    threadBindingKeys: readonly string[];
+}
+export interface ForgetPlan {
+    channelKeys: string[];
+    threadKeys: string[];
+    /**
+     * Always empty: intent keys are message-scoped, so forget planning cannot
+     * sweep them by guild — deliberate, to keep DSH-side data structurally
+     * unreachable from a Discord-initiated forget.
+     */
+    intentKeys: string[];
+}
+/**
+ * Plan one Guild forget: parse every binding key and keep only those whose
+ * guild matches. Removal execution (deletes) stays with the caller, which
+ * holds the open domain tables.
+ */
+export declare function guildKeysToForget(input: ForgetPlanInput): ForgetPlan;

package/lib/state/retention.js

@@ -0,0 +1,68 @@
+/**
+ * Bounded retention and Guild forget (design.md §10). Completed intents and
+ * deliveries default to 30-day retention; resolved interactions to 7 days;
+ * no configured window may drop below the 7-day floor. Unresolved records —
+ * claimed prompts and unknown outcomes — never expire on a timer: they wait
+ * for explicit user resolution or a Guild forget. Active channel/thread
+ * bindings are ownership, not history, and no retention rule touches them.
+ * A Guild forget plans the removal of only that guild's adapter records;
+ * DSH workspaces and sessions are structurally out of reach.
+ */
+const DAY = 24 * 60 * 60_000;
+/** The retention floor: no configured window may go below 7 days. */
+export const MINIMUM_RETENTION_MS = 7 * DAY;
+/** Default retention for completed (succeeded/failed) intents and deliveries. */
+export const DEFAULT_COMPLETED_RETENTION_MS = 30 * DAY;
+/** Default retention for resolved interactions. */
+export const DEFAULT_INTERACTION_RETENTION_MS = 7 * DAY;
+/** Clamp a policy into the legal range, applying defaults. */
+export function normalizeRetentionPolicy(policy) {
+    const clamp = (value, fallback) => value === undefined || !Number.isFinite(value)
+        ? fallback
+        : Math.max(value, MINIMUM_RETENTION_MS);
+    return {
+        completedRetentionMs: clamp(policy.completedRetentionMs, DEFAULT_COMPLETED_RETENTION_MS),
+        interactionRetentionMs: clamp(policy.interactionRetentionMs, DEFAULT_INTERACTION_RETENTION_MS),
+    };
+}
+/**
+ * Plan one retention sweep. Only terminal, resolved records age out:
+ * `claimed` and `unknown` intents are retained indefinitely (unknown until
+ * explicit user resolution), regardless of age.
+ */
+export function sweepExpired(input, options) {
+    const policy = normalizeRetentionPolicy(options.policy ?? {});
+    const intentKeys = input.intents
+        .filter(([, record]) => {
+        if (record.state !== 'succeeded' && record.state !== 'failed')
+            return false;
+        const resolvedAtMs = record.resolvedAtMs;
+        if (resolvedAtMs === undefined)
+            return false;
+        return options.nowMs - resolvedAtMs >= policy.completedRetentionMs;
+    })
+        .map(([key]) => key);
+    const interactionKeys = input.resolvedInteractions
+        .filter(([, record]) => options.nowMs - record.resolvedAtMs >= policy.interactionRetentionMs)
+        .map(([key]) => key);
+    return { intentKeys, interactionKeys };
+}
+/**
+ * Plan one Guild forget: parse every binding key and keep only those whose
+ * guild matches. Removal execution (deletes) stays with the caller, which
+ * holds the open domain tables.
+ */
+export function guildKeysToForget(input) {
+    const parse = (key) => {
+        const segments = key.split(':');
+        if (segments.length !== 6)
+            return undefined;
+        const guildId = segments[3];
+        return guildId === input.guildId ? key : undefined;
+    };
+    return {
+        channelKeys: input.channelBindingKeys.filter(key => parse(key) !== undefined),
+        threadKeys: input.threadBindingKeys.filter(key => parse(key) !== undefined),
+        intentKeys: [],
+    };
+}

package/lib/state/session-owners.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The unique logical owner record for writable Session bindings (design.md
+ * §6, §10). One record per session id — the record itself IS the ownership,
+ * so uniqueness falls out of the key. Claims serialize per session; a second
+ * writable thread conflicts without any implicit takeover, the owning thread
+ * re-claiming is idempotent (crash/recovery), and only the owner can release.
+ */
+export interface SessionOwnerRecord {
+    threadId: string;
+    guildId: string;
+    claimedAtMs: number;
+}
+export interface SessionOwnerTable {
+    get(sessionId: string): SessionOwnerRecord | undefined;
+    put(sessionId: string, record: SessionOwnerRecord): Promise<void>;
+    delete(sessionId: string): Promise<boolean>;
+}
+export interface ClaimOwnershipRequest {
+    sessionId: string;
+    threadId: string;
+    guildId: string;
+    claimedAtMs: number;
+    /** Test/diagnostic hook run inside the serialized claim slot. */
+    beforeClaim?: () => Promise<void> | void;
+}
+export type ClaimOwnershipOutcome = {
+    outcome: 'claimed';
+    record: SessionOwnerRecord;
+} | {
+    outcome: 'duplicate';
+    record: SessionOwnerRecord;
+} | {
+    outcome: 'conflict';
+    record: SessionOwnerRecord;
+};
+export type ReleaseOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    error: 'not-owner';
+};
+export interface SessionOwnerStore {
+    get(sessionId: string): SessionOwnerRecord | undefined;
+    claim(request: ClaimOwnershipRequest): Promise<ClaimOwnershipOutcome>;
+    release(request: {
+        sessionId: string;
+        threadId: string;
+    }): Promise<ReleaseOutcome>;
+}
+export declare function createSessionOwnerStore(table: SessionOwnerTable): SessionOwnerStore;

package/lib/state/session-owners.js

@@ -0,0 +1,50 @@
+/**
+ * The unique logical owner record for writable Session bindings (design.md
+ * §6, §10). One record per session id — the record itself IS the ownership,
+ * so uniqueness falls out of the key. Claims serialize per session; a second
+ * writable thread conflicts without any implicit takeover, the owning thread
+ * re-claiming is idempotent (crash/recovery), and only the owner can release.
+ */
+const noBeforeClaim = () => { };
+export function createSessionOwnerStore(table) {
+    const chains = new Map();
+    function enqueue(sessionId, op) {
+        const tail = chains.get(sessionId) ?? Promise.resolve();
+        const run = tail.then(op, op);
+        chains.set(sessionId, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    return {
+        get: sessionId => table.get(sessionId),
+        claim(request) {
+            return enqueue(request.sessionId, async () => {
+                const hook = request.beforeClaim ?? noBeforeClaim;
+                await Promise.resolve().then(hook);
+                const existing = table.get(request.sessionId);
+                if (existing !== undefined) {
+                    const record = existing;
+                    return existing.threadId === request.threadId
+                        ? { outcome: 'duplicate', record }
+                        : { outcome: 'conflict', record };
+                }
+                const record = {
+                    threadId: request.threadId,
+                    guildId: request.guildId,
+                    claimedAtMs: request.claimedAtMs,
+                };
+                await table.put(request.sessionId, record);
+                return { outcome: 'claimed', record };
+            });
+        },
+        release(request) {
+            return enqueue(request.sessionId, async () => {
+                const existing = table.get(request.sessionId);
+                if (existing === undefined || existing.threadId !== request.threadId) {
+                    return { ok: false, error: 'not-owner' };
+                }
+                await table.delete(request.sessionId);
+                return { ok: true };
+            });
+        },
+    };
+}

package/lib/stream/finalizer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The answer finalizer (design.md §8, task 11.10). The final answer lands as
+ * ONE edited head message; overflow continues as ordered follow-up messages.
+ * Every piece is sent exactly once: the finalizer records progress as it
+ * goes, duplicate finalize calls skip without touching Discord, a failed
+ * continuation halts at that index (recovery belongs to reconciliation, not
+ * blind resend), and a rate-limited head edit is retried in place — bounded,
+ * so a port that keeps reporting rate-limit cannot spin forever.
+ */
+export interface AnswerDeliveryPort {
+    editHead(request: {
+        messageId: string;
+        content: string;
+    }): Promise<{
+        outcome: 'completed';
+    } | {
+        outcome: 'rate-limited';
+        retryAfterMs: number;
+    } | {
+        outcome: 'failed';
+    }>;
+    sendContinuation(request: {
+        index: number;
+        content: string;
+    }): Promise<{
+        outcome: 'completed';
+    } | {
+        outcome: 'failed';
+    }>;
+}
+export type FinalizeResult = {
+    outcome: 'finalized';
+    editedHead: boolean;
+    continuations: number;
+} | {
+    outcome: 'partial';
+    editedHead: boolean;
+    continuations: number;
+} | {
+    outcome: 'skipped';
+    reason: 'already-finalized';
+};
+export interface AnswerFinalizer {
+    finalize(fullText: string): Promise<FinalizeResult>;
+}
+export declare function createAnswerFinalizer(deps: {
+    delivery: AnswerDeliveryPort;
+    headMessageId: string;
+}): AnswerFinalizer;

package/lib/stream/finalizer.js

@@ -0,0 +1,67 @@
+/**
+ * The answer finalizer (design.md §8, task 11.10). The final answer lands as
+ * ONE edited head message; overflow continues as ordered follow-up messages.
+ * Every piece is sent exactly once: the finalizer records progress as it
+ * goes, duplicate finalize calls skip without touching Discord, a failed
+ * continuation halts at that index (recovery belongs to reconciliation, not
+ * blind resend), and a rate-limited head edit is retried in place — bounded,
+ * so a port that keeps reporting rate-limit cannot spin forever.
+ */
+import { splitMarkdownAware } from './markdown.js';
+import { DISCORD_MESSAGE_LIMIT } from './splitter.js';
+/** Head-edit retry budget when the port reports rate-limit backoff. */
+const MAX_HEAD_EDIT_RETRIES = 10;
+export function createAnswerFinalizer(deps) {
+    let finalized = false;
+    return {
+        async finalize(fullText) {
+            if (finalized)
+                return { outcome: 'skipped', reason: 'already-finalized' };
+            // Fence-aware: a long answer never splits a ``` code block across
+            // messages; each continuation renders as well-formed Markdown alone.
+            const chunks = splitMarkdownAware(fullText, DISCORD_MESSAGE_LIMIT);
+            if (chunks.length === 0) {
+                finalized = true;
+                return { outcome: 'finalized', editedHead: false, continuations: 0 };
+            }
+            // Head: edit until the port completes; a rate-limited port backs off
+            // here, within a bounded budget so the loop cannot spin forever.
+            let editedHead = false;
+            let rateLimitedAttempts = 0;
+            for (;;) {
+                const edited = await deps.delivery.editHead({ messageId: deps.headMessageId, content: chunks[0] ?? '' });
+                if (edited.outcome === 'completed') {
+                    editedHead = true;
+                    break;
+                }
+                if (edited.outcome === 'rate-limited') {
+                    rateLimitedAttempts += 1;
+                    if (rateLimitedAttempts > MAX_HEAD_EDIT_RETRIES) {
+                        finalized = true;
+                        return { outcome: 'partial', editedHead: false, continuations: 0 };
+                    }
+                    await new Promise(resolve => { setTimeout(resolve, edited.retryAfterMs); });
+                    continue;
+                }
+                // Hard failure: nothing was mutated on Discord.
+                finalized = true;
+                return { outcome: 'partial', editedHead: false, continuations: 0 };
+            }
+            // Continuations: ordered, exactly once, halting at the first failure.
+            let sent = 0;
+            for (let index = 1; index < chunks.length; index += 1) {
+                const content = chunks[index];
+                if (content === undefined)
+                    break;
+                const sentOutcome = await deps.delivery.sendContinuation({ index, content });
+                if (sentOutcome.outcome !== 'completed') {
+                    finalized = true;
+                    return { outcome: 'partial', editedHead, continuations: sent };
+                }
+                sent += 1;
+            }
+            finalized = true;
+            return { outcome: 'finalized', editedHead, continuations: sent };
+        },
+    };
+}

package/lib/stream/icons.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The adapter's fixed iconography table (stream-renderer "Fixed
+ * adapter-owned iconography"). This module is the ONLY source of icons:
+ * tool rows carry one category icon each (never a run-state mark — state
+ * flips would cost one message edit per tool transition), and notices use
+ * kind-fixed prefixes. Icons are never derived from model output, tool
+ * output, or Host presentation views; sanitized text labels stay unchanged
+ * beside them, and assistant answer text carries no icon prefix.
+ */
+/** The category icon for a sanitized tool label (generic fallback included). */
+export declare function toolCategoryIcon(label: string): string;
+/** The notice kinds the adapter renders, with their fixed prefixes. */
+export type NoticeKind = 'failure' | 'guidance' | 'stop' | 'steer' | 'queued';
+/** The fixed prefix for a notice kind. */
+export declare function noticeIcon(kind: NoticeKind): string;

package/lib/stream/icons.js

@@ -0,0 +1,36 @@
+/**
+ * The adapter's fixed iconography table (stream-renderer "Fixed
+ * adapter-owned iconography"). This module is the ONLY source of icons:
+ * tool rows carry one category icon each (never a run-state mark — state
+ * flips would cost one message edit per tool transition), and notices use
+ * kind-fixed prefixes. Icons are never derived from model output, tool
+ * output, or Host presentation views; sanitized text labels stay unchanged
+ * beside them, and assistant answer text carries no icon prefix.
+ */
+/** Category icon by the sanitized label's first word (the label allowlist). */
+const TOOL_CATEGORY_ICONS = {
+    Shell: '💻',
+    Read: '📖',
+    Write: '✍️',
+    Edit: '✏️',
+    Search: '🔍',
+    Find: '🗂️',
+    Web: '🌐',
+};
+const GENERIC_CATEGORY_ICON = '🧩';
+/** The category icon for a sanitized tool label (generic fallback included). */
+export function toolCategoryIcon(label) {
+    const firstWord = label.split(' ')[0] ?? '';
+    return TOOL_CATEGORY_ICONS[firstWord] ?? GENERIC_CATEGORY_ICON;
+}
+const NOTICE_ICONS = {
+    failure: '⚠️',
+    guidance: '💡',
+    stop: '🛑',
+    steer: '↪️',
+    queued: '⏳',
+};
+/** The fixed prefix for a notice kind. */
+export function noticeIcon(kind) {
+    return NOTICE_ICONS[kind];
+}