@addozhang/dsh-discord 0.1.0

package/lib/settings.js

@@ -0,0 +1,102 @@
+import { installSettingsSection } from '@deepseek-ai/dsh-settings';
+import z from '@deepseek-ai/schemastery';
+import { DISCORD_SETTINGS_NAMESPACE } from './settings-namespace.js';
+export { DISCORD_SETTINGS_NAMESPACE } from './settings-namespace.js';
+export const THREAD_AUTO_ARCHIVE_OPTIONS = [60, 1440, 4320, 10080];
+export const DEFAULT_DISCORD_SETTINGS = Object.freeze({
+    enabled: false,
+    allowedGuildIds: [],
+    memberUserIds: [],
+    memberRoleIds: [],
+    administratorUserIds: [],
+    administratorRoleIds: [],
+    deniedUserIds: [],
+    deniedRoleIds: [],
+    hostOperatorUserIds: [],
+    defaultVerbosity: 'essential-tools',
+    language: 'auto',
+    streamUpdateIntervalMs: 800,
+    typingIntervalMs: 7_000,
+    approvalTimeoutMs: 10 * 60_000,
+    questionTimeoutMs: 30 * 60_000,
+    threadAutoArchiveMinutes: 1440,
+});
+const discordIdList = z.array(z.string()).default([]);
+export const DiscordSettingsSchema = z.object({
+    enabled: z.boolean().default(false),
+    allowedGuildIds: discordIdList,
+    memberUserIds: discordIdList,
+    memberRoleIds: discordIdList,
+    administratorUserIds: discordIdList,
+    administratorRoleIds: discordIdList,
+    deniedUserIds: discordIdList,
+    deniedRoleIds: discordIdList,
+    hostOperatorUserIds: discordIdList,
+    defaultVerbosity: z.union(['text-only', 'essential-tools', 'full-tools'])
+        .default('essential-tools'),
+    language: z.union(['auto', 'zh', 'en']).default('auto'),
+    threadAutoArchiveMinutes: z.union([60, 1440, 4320, 10080])
+        .default(1440),
+    streamUpdateIntervalMs: z.number().step(1).min(250).max(10_000).default(800),
+    typingIntervalMs: z.number().step(1).min(1_000).max(30_000).default(7_000),
+    approvalTimeoutMs: z.number().step(1).min(30_000).max(86_400_000).default(600_000),
+    questionTimeoutMs: z.number().step(1).min(30_000).max(86_400_000).default(1_800_000),
+});
+const DISCORD_SNOWFLAKE = /^\d{17,20}$/u;
+const ID_FIELDS = [
+    'allowedGuildIds',
+    'memberUserIds',
+    'memberRoleIds',
+    'administratorUserIds',
+    'administratorRoleIds',
+    'deniedUserIds',
+    'deniedRoleIds',
+    'hostOperatorUserIds',
+];
+function normalizeIds(values) {
+    return [...new Set(values.map(value => value.trim()))];
+}
+export function normalizeDiscordSettings(input) {
+    const result = { ...input };
+    for (const field of ID_FIELDS) {
+        result[field] = normalizeIds(input[field]);
+    }
+    return result;
+}
+export function validateDiscordSettings(input) {
+    for (const field of ID_FIELDS) {
+        if (input[field].some(value => !DISCORD_SNOWFLAKE.test(value.trim()))) {
+            throw new TypeError(`${field} must contain Discord snowflake IDs`);
+        }
+    }
+    if (!Number.isSafeInteger(input.streamUpdateIntervalMs)
+        || input.streamUpdateIntervalMs < 250
+        || input.streamUpdateIntervalMs > 10_000) {
+        throw new TypeError('streamUpdateIntervalMs must be between 250 and 10000');
+    }
+    if (!Number.isSafeInteger(input.typingIntervalMs)
+        || input.typingIntervalMs < 1_000
+        || input.typingIntervalMs > 30_000) {
+        throw new TypeError('typingIntervalMs must be between 1000 and 30000');
+    }
+    for (const field of ['approvalTimeoutMs', 'questionTimeoutMs']) {
+        if (!Number.isSafeInteger(input[field]) || input[field] < 30_000 || input[field] > 86_400_000) {
+            throw new TypeError(`${field} must be between 30000 and 86400000`);
+        }
+    }
+    if (!THREAD_AUTO_ARCHIVE_OPTIONS.includes(input.threadAutoArchiveMinutes)) {
+        throw new TypeError('threadAutoArchiveMinutes must be one of 60, 1440, 4320, 10080');
+    }
+}
+export function installDiscordSettings(ctx, entry, onChange) {
+    let source = () => entry;
+    installSettingsSection(ctx, DISCORD_SETTINGS_NAMESPACE, DiscordSettingsSchema, entry, {
+        validate: value => { validateDiscordSettings(normalizeDiscordSettings(value)); },
+        setSource: current => {
+            source = () => normalizeDiscordSettings(current());
+        },
+        onChange: () => {
+            onChange(source());
+        },
+    });
+}

package/lib/startup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The adapter's fail-loud startup boundary. Cordis `inject` delays activation
+ * until the named services exist but says nothing about contract shape, and a
+ * silently half-mounted Discord plugin is a security liability. This module
+ * probes every required DSH Host service in one pass and refuses activation
+ * with a single actionable diagnostic naming every gap.
+ */
+/** The exact Host service roster the adapter requires (design decision 1). */
+export declare const REQUIRED_HOST_SERVICES: readonly ["apiProxy", "credentials", "settings", "storageDomain", "connection"];
+export type HostServiceName = (typeof REQUIRED_HOST_SERVICES)[number];
+/**
+ * Validate every required Host capability through `resolveService`, which
+ * returns the service value or `undefined` when absent. Throws one aggregated
+ * `TypeError` naming every missing service and every missing contract member.
+ */
+export declare function validateHostCapabilities(resolveService: (name: HostServiceName) => unknown): void;

package/lib/startup.js

@@ -0,0 +1,60 @@
+/**
+ * The adapter's fail-loud startup boundary. Cordis `inject` delays activation
+ * until the named services exist but says nothing about contract shape, and a
+ * silently half-mounted Discord plugin is a security liability. This module
+ * probes every required DSH Host service in one pass and refuses activation
+ * with a single actionable diagnostic naming every gap.
+ */
+/** The exact Host service roster the adapter requires (design decision 1). */
+export const REQUIRED_HOST_SERVICES = [
+    'apiProxy',
+    'credentials',
+    'settings',
+    'storageDomain',
+    'connection',
+];
+/**
+ * Minimum contract members per service, confirmed against the installed DSH
+ * `0.1.1-rc.2` types. A service lacking any member means a version drift the
+ * exact peer pin should have prevented; refuse rather than probe at runtime.
+ */
+const REQUIRED_CONTRACT_MEMBERS = {
+    apiProxy: ['sessions', 'workspace', 'events', 'host'],
+    credentials: ['resolve', 'describe', 'set', 'unset'],
+    settings: ['register'],
+    storageDomain: ['open'],
+    connection: ['rpc'],
+};
+/** Actionable remediation hint appended to every activation failure. */
+const REMEDIATION = 'install @addozhang/dsh-discord into a dsh web profile providing the pinned DSH 0.1.1-rc.2 contracts';
+function missingMembers(service, required) {
+    if (service === undefined || service === null)
+        return [...required];
+    return required.filter(member => typeof service[member] === 'undefined');
+}
+/**
+ * Validate every required Host capability through `resolveService`, which
+ * returns the service value or `undefined` when absent. Throws one aggregated
+ * `TypeError` naming every missing service and every missing contract member.
+ */
+export function validateHostCapabilities(resolveService) {
+    const missing = [];
+    const incompatible = [];
+    for (const name of REQUIRED_HOST_SERVICES) {
+        const service = resolveService(name);
+        if (service === undefined || service === null) {
+            missing.push(name);
+            continue;
+        }
+        const gaps = missingMembers(service, REQUIRED_CONTRACT_MEMBERS[name]);
+        if (gaps.length > 0)
+            incompatible.push(`${name} lacks ${gaps.map(member => `'${member}'`).join(', ')}`);
+    }
+    const parts = [
+        missing.length > 0 ? `missing DSH host service(s) ${missing.map(name => `'${name}'`).join(', ')}` : undefined,
+        incompatible.length > 0 ? `incompatible service(s): ${incompatible.join('; ')}` : undefined,
+    ].filter(Boolean);
+    if (parts.length > 0) {
+        throw new TypeError(`dsh-discord cannot activate (${parts.join('; ')}). ${REMEDIATION}`);
+    }
+}

package/lib/state/bindings.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Revision-fenced bindings over one durable record each (design.md §10).
+ * The store serializes claims per key with a process-local chain, then
+ * re-checks the fence at the write slot — so an async writer that snapshotted
+ * an older revision always loses to the live writer, and a failed claim never
+ * partially mutates the record. Channel and thread bindings share this one
+ * mechanism; only their record shapes differ.
+ */
+import type { ChannelBinding, ThreadBinding } from './records.js';
+/** Minimal durable face the store needs (the domain's KvTable provides it). */
+export interface BindingTable<V> {
+    get(key: string): V | undefined;
+    put(key: string, value: V): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+export type BindOutcome<V> = {
+    ok: true;
+    binding: V;
+} | {
+    ok: false;
+    error: 'already-bound' | 'stale-revision' | 'not-bound';
+};
+export interface BindOptions {
+    /** Fence: the caller's observed revision; undefined only for a fresh bind. */
+    expectedRevision?: number | undefined;
+    /** Test/diagnostic hook run at the claim slot before the durable write. */
+    beforeWrite?: () => Promise<void> | void;
+}
+export interface BindingStore<V extends {
+    revision: number;
+}> {
+    get(key: string): V | undefined;
+    bind(key: string, record: Omit<V, 'revision'>, options?: BindOptions): Promise<BindOutcome<V>>;
+    release(key: string, options: {
+        expectedRevision: number;
+    }): Promise<BindOutcome<V>>;
+    /** Run one operation serialized behind this key's claim chain. */
+    withKey<T>(key: string, op: () => Promise<T>): Promise<T>;
+}
+export declare function createBindingStore<V extends {
+    revision: number;
+}>(table: BindingTable<V>): BindingStore<V>;
+/** Convenience alias for the channel-binding table's store. */
+export type ChannelBindingStore = BindingStore<ChannelBinding>;
+/** Convenience alias for the thread-binding table's store. */
+export type ThreadBindingStore = BindingStore<ThreadBinding>;

package/lib/state/bindings.js

@@ -0,0 +1,55 @@
+/**
+ * Revision-fenced bindings over one durable record each (design.md §10).
+ * The store serializes claims per key with a process-local chain, then
+ * re-checks the fence at the write slot — so an async writer that snapshotted
+ * an older revision always loses to the live writer, and a failed claim never
+ * partially mutates the record. Channel and thread bindings share this one
+ * mechanism; only their record shapes differ.
+ */
+const noBeforeWrite = () => { };
+export function createBindingStore(table) {
+    const chains = new Map();
+    function enqueue(key, op) {
+        const tail = chains.get(key) ?? Promise.resolve();
+        const run = tail.then(op, op);
+        // A failed claim never poisons later claims on the same key.
+        chains.set(key, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    async function bindAtSlot(key, record, options) {
+        const hook = options.beforeWrite ?? noBeforeWrite;
+        await Promise.resolve().then(hook);
+        const current = table.get(key);
+        if (options.expectedRevision === undefined) {
+            if (current !== undefined)
+                return { ok: false, error: 'already-bound' };
+            const binding = { ...record, revision: 1 };
+            await table.put(key, binding);
+            return { ok: true, binding };
+        }
+        if (current === undefined || current.revision !== options.expectedRevision) {
+            return { ok: false, error: 'stale-revision' };
+        }
+        const binding = { ...record, revision: options.expectedRevision + 1 };
+        await table.put(key, binding);
+        return { ok: true, binding };
+    }
+    return {
+        get: key => table.get(key),
+        bind(key, record, options = {}) {
+            return enqueue(key, () => bindAtSlot(key, record, options));
+        },
+        release(key, { expectedRevision }) {
+            return enqueue(key, async () => {
+                const current = table.get(key);
+                if (current === undefined)
+                    return { ok: false, error: 'not-bound' };
+                if (current.revision !== expectedRevision)
+                    return { ok: false, error: 'stale-revision' };
+                await table.delete(key);
+                return { ok: true, binding: current };
+            });
+        },
+        withKey: (key, op) => enqueue(key, op),
+    };
+}

package/lib/state/channel-bindings.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Channel→Workspace binding service: the composition of the versioned
+ * key codec, the revision-fenced binding store, and guild-scoped listing.
+ * Keys carry the full ownership scope (application+guild+channel), so
+ * bindings are independent across channels and guilds by construction, and
+ * a guild-scoped scan parses keys instead of guessing with prefixes.
+ */
+import type { ChannelBinding } from './records.js';
+import { type ChannelBindingScope } from './domain.js';
+import type { BindingStore, BindOutcome } from './bindings.js';
+export interface GuildBindingEntry {
+    scope: ChannelBindingScope;
+    binding: ChannelBinding;
+}
+export interface ChannelBindingService {
+    keyFor(scope: ChannelBindingScope): string;
+    resolve(scope: ChannelBindingScope): ChannelBinding | undefined;
+    bind(scope: ChannelBindingScope, request: {
+        workspaceId: string;
+        actorId: string;
+        nowMs: number;
+    }, options?: {
+        expectedRevision?: number | undefined;
+        beforeWrite?: () => Promise<void> | void;
+    }): Promise<BindOutcome<ChannelBinding>>;
+    release(scope: ChannelBindingScope, options: {
+        expectedRevision: number;
+    }): Promise<BindOutcome<ChannelBinding>>;
+    /** All bindings inside one guild (parsed keys, not prefix guesses). */
+    listForGuild(guildId: string): GuildBindingEntry[];
+}
+export declare function createChannelBindingService(deps: {
+    store: BindingStore<ChannelBinding>;
+    applicationId: string;
+    /** Raw key access for guild scans; the domain's table provides it. */
+    listKeys?: () => Iterable<string>;
+}): ChannelBindingService;

package/lib/state/channel-bindings.js

@@ -0,0 +1,43 @@
+/**
+ * The Channel→Workspace binding service: the composition of the versioned
+ * key codec, the revision-fenced binding store, and guild-scoped listing.
+ * Keys carry the full ownership scope (application+guild+channel), so
+ * bindings are independent across channels and guilds by construction, and
+ * a guild-scoped scan parses keys instead of guessing with prefixes.
+ */
+import { channelBindingKey, parseChannelBindingKey } from './domain.js';
+export function createChannelBindingService(deps) {
+    const { store, applicationId, listKeys } = deps;
+    function keyFor(scope) {
+        return channelBindingKey(scope);
+    }
+    return {
+        keyFor,
+        resolve: scope => store.get(keyFor(scope)),
+        bind(scope, request, options = {}) {
+            return store.bind(keyFor(scope), {
+                workspaceId: request.workspaceId,
+                boundBy: request.actorId,
+                boundAtMs: request.nowMs,
+            }, {
+                ...(options.expectedRevision === undefined ? {} : { expectedRevision: options.expectedRevision }),
+                ...(options.beforeWrite === undefined ? {} : { beforeWrite: options.beforeWrite }),
+            });
+        },
+        release: (scope, options) => store.release(keyFor(scope), options),
+        listForGuild(guildId) {
+            if (listKeys === undefined)
+                return [];
+            const entries = [];
+            for (const key of listKeys()) {
+                const scope = parseChannelBindingKey(key);
+                if (scope === undefined || scope.applicationId !== applicationId || scope.guildId !== guildId)
+                    continue;
+                const binding = store.get(key);
+                if (binding !== undefined)
+                    entries.push({ scope, binding });
+            }
+            return entries;
+        },
+    };
+}

package/lib/state/domain.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The adapter's versioned DSH storage domain. Keys compose the logical
+ * ownership scopes — application, guild, then channel or thread — as
+ * parseable strings, so guild-scoped reconciliation and forget derive their
+ * scan space from parsed parts. The spec is declared once with
+ * `defineDomain`, which fails loud at module load on any naming or version
+ * misconfiguration.
+ */
+/**
+ * Storage-legal domain name (`UNIT_NAME_RE` allows only lowercase, digits,
+ * and underscores) and the current format version; a medium stamped with a
+ * different version rejects at open, which is exactly the fail-closed
+ * behavior the adapter wants across upgrades.
+ */
+export declare const DISCORD_DOMAIN_NAME = "dsh_discord";
+export declare const DISCORD_DOMAIN_VERSION = 1;
+export declare const CHANNEL_BINDINGS_TABLE = "channel_bindings";
+export declare const THREAD_BINDINGS_TABLE = "thread_bindings";
+export declare const INTENTS_TABLE = "inbound_intents";
+/** Scope of one project-channel binding. */
+export interface ChannelBindingScope {
+    applicationId: string;
+    guildId: string;
+    channelId: string;
+}
+/** Scope of one session-thread binding. */
+export interface ThreadBindingScope {
+    applicationId: string;
+    guildId: string;
+    threadId: string;
+}
+/** Build the channel-binding key for one guild channel. */
+export declare function channelBindingKey(scope: ChannelBindingScope): string;
+/** Parse a channel-binding key; `undefined` when the key is another family. */
+export declare function parseChannelBindingKey(key: string): ChannelBindingScope | undefined;
+/** Build the thread-binding key for one guild thread. */
+export declare function threadBindingKey(scope: ThreadBindingScope): string;
+/** Parse a thread-binding key; `undefined` when the key is another family. */
+export declare function parseThreadBindingKey(key: string): ThreadBindingScope | undefined;
+/** The domain declaration: identity, format version, and record layout. */
+export declare const discordDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        channel_bindings: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<"channel", {
+            workspaceId: string;
+            revision: number;
+            boundBy: string;
+            boundAtMs: number;
+        }>;
+        thread_bindings: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<"thread", {
+            sessionId: string;
+            workspaceId: string;
+            revision: number;
+            createdBy: string;
+            createdAtMs: number;
+        }>;
+        inbound_intents: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<"intent", {
+            contentHash: string;
+            state: "claimed" | "unknown" | "succeeded" | "failed";
+            claimedAtMs: number;
+            resolvedAtMs?: number | undefined;
+            threadId?: string | undefined;
+        }>;
+    };
+};
+/** Minimal facility face the opener needs (the real DomainFacility matches). */
+export interface DomainFacilityLike {
+    open(spec: typeof discordDomainSpec): Promise<{
+        name: string;
+        close(): Promise<void>;
+    }>;
+}
+/**
+ * Open the adapter's domain through the Host's domain facility. The caller
+ * owns the returned handle — close it from the plugin's cancellation root so
+ * shutdown drains queued writes before the unit releases.
+ */
+export declare function openDiscordDomain(facility: DomainFacilityLike): Promise<{
+    name: string;
+    close(): Promise<void>;
+}>;

package/lib/state/domain.js

@@ -0,0 +1,86 @@
+/**
+ * The adapter's versioned DSH storage domain. Keys compose the logical
+ * ownership scopes — application, guild, then channel or thread — as
+ * parseable strings, so guild-scoped reconciliation and forget derive their
+ * scan space from parsed parts. The spec is declared once with
+ * `defineDomain`, which fails loud at module load on any naming or version
+ * misconfiguration.
+ */
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { ChannelBindingRecord, InboundIntentRecordSchema, ThreadBindingRecord } from './records.js';
+/**
+ * Storage-legal domain name (`UNIT_NAME_RE` allows only lowercase, digits,
+ * and underscores) and the current format version; a medium stamped with a
+ * different version rejects at open, which is exactly the fail-closed
+ * behavior the adapter wants across upgrades.
+ */
+export const DISCORD_DOMAIN_NAME = 'dsh_discord';
+export const DISCORD_DOMAIN_VERSION = 1;
+export const CHANNEL_BINDINGS_TABLE = 'channel_bindings';
+export const THREAD_BINDINGS_TABLE = 'thread_bindings';
+export const INTENTS_TABLE = 'inbound_intents';
+const ID_SEGMENT = /^[^:\s]+$/;
+function composeKey(parts) {
+    return parts.join(':');
+}
+function parseSegments(key, family) {
+    const segments = key.split(':');
+    if (segments.length !== 6)
+        return undefined;
+    const [familyPrefix, applicationId, guildLiteral, guildId, leaf, leafId] = segments;
+    if (familyPrefix !== 'app' || guildLiteral !== 'guild')
+        return undefined;
+    if (leaf !== family)
+        return undefined;
+    for (const id of [applicationId, guildId, leafId]) {
+        if (id === undefined || id === '' || !ID_SEGMENT.test(id))
+            return undefined;
+    }
+    return segments;
+}
+/** Build the channel-binding key for one guild channel. */
+export function channelBindingKey(scope) {
+    return composeKey(['app', scope.applicationId, 'guild', scope.guildId, 'channel', scope.channelId]);
+}
+/** Parse a channel-binding key; `undefined` when the key is another family. */
+export function parseChannelBindingKey(key) {
+    const segments = parseSegments(key, 'channel');
+    const applicationId = segments?.[1];
+    const guildId = segments?.[3];
+    const channelId = segments?.[5];
+    if (applicationId === undefined || guildId === undefined || channelId === undefined)
+        return undefined;
+    return { applicationId, guildId, channelId };
+}
+/** Build the thread-binding key for one guild thread. */
+export function threadBindingKey(scope) {
+    return composeKey(['app', scope.applicationId, 'guild', scope.guildId, 'thread', scope.threadId]);
+}
+/** Parse a thread-binding key; `undefined` when the key is another family. */
+export function parseThreadBindingKey(key) {
+    const segments = parseSegments(key, 'thread');
+    const applicationId = segments?.[1];
+    const guildId = segments?.[3];
+    const threadId = segments?.[5];
+    if (applicationId === undefined || guildId === undefined || threadId === undefined)
+        return undefined;
+    return { applicationId, guildId, threadId };
+}
+/** The domain declaration: identity, format version, and record layout. */
+export const discordDomainSpec = defineDomain({
+    name: DISCORD_DOMAIN_NAME,
+    version: DISCORD_DOMAIN_VERSION,
+    tables: {
+        [CHANNEL_BINDINGS_TABLE]: domainTable(ChannelBindingRecord),
+        [THREAD_BINDINGS_TABLE]: domainTable(ThreadBindingRecord),
+        [INTENTS_TABLE]: domainTable(InboundIntentRecordSchema),
+    },
+});
+/**
+ * Open the adapter's domain through the Host's domain facility. The caller
+ * owns the returned handle — close it from the plugin's cancellation root so
+ * shutdown drains queued writes before the unit releases.
+ */
+export async function openDiscordDomain(facility) {
+    return facility.open(discordDomainSpec);
+}

package/lib/state/effect-machine.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The external-effect state machine shared by Discord deliveries and DSH
+ * submissions (design.md §10):
+ *
+ *   planned → executing → succeeded
+ *                       → failed
+ *                       → unknown-needs-user-resolution
+ *
+ * Effects must be marked executing before they can finish, and every
+ * terminal state — including the unknown one — is final: recovery always
+ * issues a NEW intent instead of rewriting a settled record. All decisions
+ * are pure values; callers decide how to persist the record.
+ */
+/** The five effect states, in authority order. */
+export declare const DELIVERY_STATES: readonly ["planned", "executing", "succeeded", "failed", "unknown-needs-user-resolution"];
+export type EffectState = (typeof DELIVERY_STATES)[number];
+/** Whether the edge `from → to` exists in the transition table. */
+export declare function canTransition(from: EffectState, to: EffectState): boolean;
+/** Terminal states can never transition again; recovery means a new intent. */
+export declare function isTerminal(state: EffectState): boolean;
+export interface EffectRecord {
+    state: EffectState;
+}
+export type TransitionResult = {
+    ok: true;
+    state: EffectState;
+} | {
+    ok: false;
+    error: 'invalid-transition';
+    from: EffectState;
+    to: EffectState;
+};
+export interface EffectMachine {
+    create(): EffectRecord;
+    transition(record: EffectRecord, to: EffectState): TransitionResult;
+}
+export declare function createStateMachine(): EffectMachine;

package/lib/state/effect-machine.js

@@ -0,0 +1,52 @@
+/**
+ * The external-effect state machine shared by Discord deliveries and DSH
+ * submissions (design.md §10):
+ *
+ *   planned → executing → succeeded
+ *                       → failed
+ *                       → unknown-needs-user-resolution
+ *
+ * Effects must be marked executing before they can finish, and every
+ * terminal state — including the unknown one — is final: recovery always
+ * issues a NEW intent instead of rewriting a settled record. All decisions
+ * are pure values; callers decide how to persist the record.
+ */
+/** The five effect states, in authority order. */
+export const DELIVERY_STATES = [
+    'planned',
+    'executing',
+    'succeeded',
+    'failed',
+    'unknown-needs-user-resolution',
+];
+const TERMINAL = new Set([
+    'succeeded',
+    'failed',
+    'unknown-needs-user-resolution',
+]);
+const VALID_EDGES = new Map([
+    ['planned', ['executing']],
+    ['executing', ['succeeded', 'failed', 'unknown-needs-user-resolution']],
+    ['succeeded', []],
+    ['failed', []],
+    ['unknown-needs-user-resolution', []],
+]);
+/** Whether the edge `from → to` exists in the transition table. */
+export function canTransition(from, to) {
+    return VALID_EDGES.get(from)?.includes(to) === true;
+}
+/** Terminal states can never transition again; recovery means a new intent. */
+export function isTerminal(state) {
+    return TERMINAL.has(state);
+}
+export function createStateMachine() {
+    return {
+        create: () => ({ state: 'planned' }),
+        transition(record, to) {
+            if (!canTransition(record.state, to)) {
+                return { ok: false, error: 'invalid-transition', from: record.state, to };
+            }
+            return { ok: true, state: to };
+        },
+    };
+}

package/lib/state/fail-closed.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+import type { ZodType } from 'zod';
+import type { BindOptions, BindingStore, BindOutcome } from './bindings.js';
+export interface RawRecordAccess {
+    /** Raw (unvalidated) record access for integrity diagnosis. */
+    get(key: string): unknown;
+}
+export type Diagnosis = {
+    state: 'missing';
+} | {
+    state: 'ok';
+} | {
+    state: 'corrupt';
+    issues: string[];
+};
+export type FailClosedOutcome<V> = BindOutcome<V> | {
+    ok: false;
+    error: 'state-corrupt';
+} | {
+    ok: false;
+    error: 'durable-write-failed';
+    cause: unknown;
+};
+export interface FailClosedBindingStore<V extends {
+    revision: number;
+}> {
+    get(key: string): V | undefined;
+    diagnose(key: string): Diagnosis;
+    bind(key: string, record: Omit<V, 'revision'>, options?: BindOptions): Promise<FailClosedOutcome<V>>;
+    release(key: string, options: {
+        expectedRevision: number;
+    }): Promise<FailClosedOutcome<V>>;
+}
+export declare function createFailClosedBindingStore<V extends {
+    revision: number;
+}>(inner: BindingStore<V>, schema: ZodType<V>, raw: RawRecordAccess): FailClosedBindingStore<V>;