@gobing-ai/ts-db 0.4.63 → 0.4.65

package/dist/embedded-migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-migrations.d.ts","sourceRoot":"","sources":["../src/embedded-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,iBAAiB,EA+BjD,CAAC"}
+{"version":3,"file":"embedded-migrations.d.ts","sourceRoot":"","sources":["../src/embedded-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,iBAAiB,EAoCjD,CAAC"}

package/dist/embedded-migrations.js

@@ -38,4 +38,9 @@ export const embeddedMigrations = [
         sql: 'ALTER TABLE `queue_jobs` ADD `timeout_ms` integer;\nALTER TABLE `queue_jobs` ADD `timeout_unlimited` integer DEFAULT 0 NOT NULL;\nALTER TABLE `queue_jobs` ADD `attempt_token` text;\nALTER TABLE `queue_jobs` ADD `lease_expires_at` integer;',
         hash: 'f6a4eaf11eee838f424515e57eca3a46539260bb2fb5b0b112870ca5ed38d040',
     },
+    {
+        tag: '0014_inbox_messages_request_key',
+        sql: 'ALTER TABLE `inbox_messages` ADD `request_key` text;\nCREATE UNIQUE INDEX `idx_inbox_messages_request_key` ON `inbox_messages` (`request_key`) WHERE `request_key` IS NOT NULL;\n',
+        hash: '7277e79f8339975b29565e7b33e04f0dbd50995b99b82048fd83079757334f71',
+    },
 ];

package/dist/inbox-message-dao.d.ts

@@ -36,12 +36,20 @@ export interface FailedMessageDetail {
     error: string;
     timestamp: number;
 }
+/** Payload for a `message.requeued` event (one per row returned by `release`). */
+export interface RequeuedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    timestamp: number;
+}
 /** Typed event map for inbox message lifecycle transitions. */
 export type InboxMessageEvents = {
     'message.enqueued': (detail: EnqueuedMessageDetail) => void;
     'message.injected': (detail: InjectedMessageDetail) => void;
     'message.delivered': (detail: DeliveredMessageDetail) => void;
     'message.failed': (detail: FailedMessageDetail) => void;
+    'message.requeued': (detail: RequeuedMessageDetail) => void;
 };
 /**
  * Zero-dependency structural event sink.
@@ -56,6 +64,15 @@ export interface InboxMessageDaoOptions {
     /** Optional structural event sink for message lifecycle observability. */
     events?: InboxMessageEventSink;
 }
+/**
+ * Thrown by `InboxMessageDao.enqueueIdempotent` when a request key is re-used for a
+ * *different* payload (different `body` or `to_id`). Never a silent overwrite.
+ */
+export declare class RequestKeyConflictError extends Error {
+    readonly requestKey: string;
+    readonly existingId: string;
+    constructor(requestKey: string, existingId: string);
+}
 /**
  * DAO for durable inter-agent inbox messages.
  */
@@ -63,11 +80,34 @@ export declare class InboxMessageDao extends EntityDao<typeof inboxMessages, typ
     private readonly events?;
     constructor(adapter: DbAdapter, options?: InboxMessageDaoOptions);
     enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string>;
+    /**
+     * Insert-first idempotent enqueue (task 0832): the caller-supplied request key
+     * is the arbiter, enforced by the partial unique index
+     * `idx_inbox_messages_request_key` (request_key IS NOT NULL) — no read-then-write
+     * window exists, so two concurrent submissions of one key cannot both insert.
+     *
+     * Same key + same body + same to_id → replay: returns the original row's id with
+     * `replayed: true` and emits nothing. Same key + different payload → throws
+     * `RequestKeyConflictError`. Emits `message.enqueued` only on a fresh insert.
+     */
+    enqueueIdempotent(fromId: string | null, toId: string, body: string, requestKey: string, inReplyTo?: string): Promise<{
+        id: string;
+        replayed: boolean;
+    }>;
     drainPending(toId: string, options?: {
         limit?: number;
     }): Promise<InboxMessage[]>;
     markDelivered(msgId: string): Promise<void>;
     markFailed(msgId: string, error: string): Promise<void>;
+    /**
+     * Release claimed (`injected`) messages back to `queued` so a drain whose
+     * invocation never started stays redeliverable. Only rows currently in
+     * `status = 'injected'` are touched — a `queued` or `delivered` row is
+     * left alone, so double-release is a no-op. `injectAttempts` and
+     * `injectError` are left untouched: the claim counter IS the budget.
+     * Emits one `message.requeued` event per released row.
+     */
+    release(msgIds: string[]): Promise<number>;
     inbox(toId: string, limit?: number, offset?: number): Promise<InboxMessage[]>;
     countPending(toId: string): Promise<number>;
     getById(id: string): Promise<InboxMessage | undefined>;

package/dist/inbox-message-dao.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-message-dao.d.ts","sourceRoot":"","sources":["../src/inbox-message-dao.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inbox-message-dao.d.ts","sourceRoot":"","sources":["../src/inbox-message-dao.ts"],"names":[],"mappings":"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"}

package/dist/inbox-message-dao.js

@@ -1,4 +1,4 @@
-import { sql } from 'drizzle-orm';
+import { and, eq, inArray, sql } from 'drizzle-orm';
 import { EntityDao } from './entity-dao.js';
 import { inboxMessages } from './schema/inbox-messages.js';
 function isPromiseLike(value) {
@@ -6,6 +6,27 @@ function isPromiseLike(value) {
         (typeof value === 'object' || typeof value === 'function') &&
         typeof value.then === 'function');
 }
+/**
+ * Thrown by `InboxMessageDao.enqueueIdempotent` when a request key is re-used for a
+ * *different* payload (different `body` or `to_id`). Never a silent overwrite.
+ */
+export class RequestKeyConflictError extends Error {
+    requestKey;
+    existingId;
+    constructor(requestKey, existingId) {
+        super(`Request key conflict: key is already bound to another payload` +
+            (existingId ? ` (existing message id: ${existingId})` : ''));
+        this.name = 'RequestKeyConflictError';
+        this.requestKey = requestKey;
+        this.existingId = existingId;
+    }
+}
+/** True when the error is SQLite's unique violation on the request-key partial index. */
+function isRequestKeyUniqueViolation(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return (msg.includes('UNIQUE constraint failed') &&
+        (msg.includes('idx_inbox_messages_request_key') || msg.includes('inbox_messages.request_key')));
+}
 // ---------------------------------------------------------------------------
 // DAO
 // ---------------------------------------------------------------------------
@@ -41,6 +62,54 @@ export class InboxMessageDao extends EntityDao {
         });
         return id;
     }
+    /**
+     * Insert-first idempotent enqueue (task 0832): the caller-supplied request key
+     * is the arbiter, enforced by the partial unique index
+     * `idx_inbox_messages_request_key` (request_key IS NOT NULL) — no read-then-write
+     * window exists, so two concurrent submissions of one key cannot both insert.
+     *
+     * Same key + same body + same to_id → replay: returns the original row's id with
+     * `replayed: true` and emits nothing. Same key + different payload → throws
+     * `RequestKeyConflictError`. Emits `message.enqueued` only on a fresh insert.
+     */
+    async enqueueIdempotent(fromId, toId, body, requestKey, inReplyTo) {
+        const id = crypto.randomUUID();
+        const now = this.now();
+        try {
+            await this.create({
+                id,
+                fromId,
+                toId,
+                body,
+                status: 'queued',
+                injectAttempts: 0,
+                requestKey,
+                createdAt: now,
+                updatedAt: now,
+                ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+            });
+        }
+        catch (error) {
+            if (isRequestKeyUniqueViolation(error)) {
+                // The constraint won the race (or the row already existed): fetch the
+                // winner and decide replay vs conflict by comparing the payload.
+                const existing = await this.findBy(inboxMessages.requestKey, requestKey);
+                if (existing && existing.body === body && existing.toId === toId) {
+                    return { id: existing.id, replayed: true };
+                }
+                throw new RequestKeyConflictError(requestKey, existing?.id ?? '');
+            }
+            throw error;
+        }
+        this.emitEvent('message.enqueued', {
+            id,
+            fromId,
+            toId,
+            ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+            timestamp: now,
+        });
+        return { id, replayed: false };
+    }
     async drainPending(toId, options) {
         // A backed-up inbox is claimed in pages of at most `limit` (default 100) so one
         // recipient's queue cannot be monopolised by a single drain (task 0060 F10).
@@ -109,6 +178,33 @@ export class InboxMessageDao extends EntityDao {
             });
         }
     }
+    /**
+     * Release claimed (`injected`) messages back to `queued` so a drain whose
+     * invocation never started stays redeliverable. Only rows currently in
+     * `status = 'injected'` are touched — a `queued` or `delivered` row is
+     * left alone, so double-release is a no-op. `injectAttempts` and
+     * `injectError` are left untouched: the claim counter IS the budget.
+     * Emits one `message.requeued` event per released row.
+     */
+    async release(msgIds) {
+        if (msgIds.length === 0)
+            return 0;
+        const now = this.now();
+        const rows = (await this.db
+            .update(inboxMessages)
+            .set({ status: 'queued', updatedAt: now })
+            .where(and(inArray(inboxMessages.id, msgIds), eq(inboxMessages.status, 'injected')))
+            .returning());
+        for (const row of rows) {
+            this.emitEvent('message.requeued', {
+                id: row.id,
+                fromId: row.fromId,
+                toId: row.toId,
+                timestamp: now,
+            });
+        }
+        return rows.length;
+    }
     async inbox(toId, limit, offset) {
         return this.list({
             where: { col: inboxMessages.toId, op: 'eq', value: toId },

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type DbBatchOp,
 export { BaseDao, type TxHandle } from './base-dao';
 export { type EmbeddedMigration, embeddedMigrations } from './embedded-migrations';
 export { type CursorListSpec, type DaoValidator, EntityDao, type EntityDaoOptions, type EntityListSpec, type EntityTable, type PKColumn, type PKValue, type SoftDeletableTable, } from './entity-dao';
-export { type DeliveredMessageDetail, type EnqueuedMessageDetail, type FailedMessageDetail, type InboxMessage, InboxMessageDao, type InboxMessageDaoOptions, type InboxMessageEventSink, type InboxMessageEvents, type InjectedMessageDetail, } from './inbox-message-dao';
+export { type DeliveredMessageDetail, type EnqueuedMessageDetail, type FailedMessageDetail, type InboxMessage, InboxMessageDao, type InboxMessageDaoOptions, type InboxMessageEventSink, type InboxMessageEvents, type InjectedMessageDetail, RequestKeyConflictError, } from './inbox-message-dao';
 export { applyMigrations, type MigrationLogger, type MigrationOptions } from './migrate';
 export { type ColRef, type ComparisonOp, compileOrderBy, compilePredicate, type ListSpec, type OrderTerm, type Predicate, } from './query-spec';
 export { QueueJobDao, type QueueJobRecord, type QueueStats } from './queue-job-dao';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACnH,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EACH,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpF,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACnH,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,uBAAuB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EACH,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpF,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@ export { createDbAdapter } from './adapter.js';
 export { BaseDao } from './base-dao.js';
 export { embeddedMigrations } from './embedded-migrations.js';
 export { EntityDao, } from './entity-dao.js';
-export { InboxMessageDao, } from './inbox-message-dao.js';
+export { InboxMessageDao, RequestKeyConflictError, } from './inbox-message-dao.js';
 export { applyMigrations } from './migrate.js';
 export { compileOrderBy, compilePredicate, } from './query-spec.js';
 export { QueueJobDao } from './queue-job-dao.js';

package/dist/schema/inbox-messages.d.ts

@@ -206,6 +206,25 @@ export declare const inboxMessages: import("drizzle-orm/sqlite-core").SQLiteTabl
         }, {}, {
             length: number | undefined;
         }>;
+        requestKey: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "request_key";
+            tableName: "inbox_messages";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;

package/dist/schema/inbox-messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-messages.d.ts","sourceRoot":"","sources":["../../src/schema/inbox-messages.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBzB,CAAC"}
+{"version":3,"file":"inbox-messages.d.ts","sourceRoot":"","sources":["../../src/schema/inbox-messages.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBzB,CAAC"}

package/dist/schema/inbox-messages.js

@@ -14,4 +14,5 @@ export const inboxMessages = sqliteTable('inbox_messages', {
     deliveredAt: integer('delivered_at'),
     injectAttempts: integer('inject_attempts').notNull().default(0),
     injectError: text('inject_error'),
+    requestKey: text('request_key'),
 }, (table) => [index('idx_inbox_messages_to_status').on(table.toId, table.status)]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-db",
-    "version": "0.4.63",
+    "version": "0.4.65",
     "description": "@gobing-ai/ts-db — a drizzle-free database facade: typed DAOs over Bun SQLite / Cloudflare D1, a small predicate query spec, single-source-of-truth tables, and migrations. Drizzle stays an internal detail.",
     "keywords": [
         "typescript",

package/src/embedded-migrations.ts

@@ -46,4 +46,9 @@ export const embeddedMigrations: EmbeddedMigration[] = [
         sql: 'ALTER TABLE `queue_jobs` ADD `timeout_ms` integer;\nALTER TABLE `queue_jobs` ADD `timeout_unlimited` integer DEFAULT 0 NOT NULL;\nALTER TABLE `queue_jobs` ADD `attempt_token` text;\nALTER TABLE `queue_jobs` ADD `lease_expires_at` integer;',
         hash: 'f6a4eaf11eee838f424515e57eca3a46539260bb2fb5b0b112870ca5ed38d040',
     },
+    {
+        tag: '0014_inbox_messages_request_key',
+        sql: 'ALTER TABLE `inbox_messages` ADD `request_key` text;\nCREATE UNIQUE INDEX `idx_inbox_messages_request_key` ON `inbox_messages` (`request_key`) WHERE `request_key` IS NOT NULL;\n',
+        hash: '7277e79f8339975b29565e7b33e04f0dbd50995b99b82048fd83079757334f71',
+    },
 ];

package/src/inbox-message-dao.ts

@@ -1,4 +1,4 @@
-import { sql } from 'drizzle-orm';
+import { and, eq, inArray, sql } from 'drizzle-orm';
 import type { DbAdapter } from './adapter';
 import type { UpdateReturningDb } from './drizzle-builders';
 import { EntityDao } from './entity-dao';
@@ -48,12 +48,21 @@ export interface FailedMessageDetail {
     timestamp: number;
 }
 
+/** Payload for a `message.requeued` event (one per row returned by `release`). */
+export interface RequeuedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    timestamp: number;
+}
+
 /** Typed event map for inbox message lifecycle transitions. */
 export type InboxMessageEvents = {
     'message.enqueued': (detail: EnqueuedMessageDetail) => void;
     'message.injected': (detail: InjectedMessageDetail) => void;
     'message.delivered': (detail: DeliveredMessageDetail) => void;
     'message.failed': (detail: FailedMessageDetail) => void;
+    'message.requeued': (detail: RequeuedMessageDetail) => void;
 };
 
 /**
@@ -79,6 +88,34 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
     );
 }
 
+/**
+ * Thrown by `InboxMessageDao.enqueueIdempotent` when a request key is re-used for a
+ * *different* payload (different `body` or `to_id`). Never a silent overwrite.
+ */
+export class RequestKeyConflictError extends Error {
+    readonly requestKey: string;
+    readonly existingId: string;
+
+    constructor(requestKey: string, existingId: string) {
+        super(
+            `Request key conflict: key is already bound to another payload` +
+                (existingId ? ` (existing message id: ${existingId})` : ''),
+        );
+        this.name = 'RequestKeyConflictError';
+        this.requestKey = requestKey;
+        this.existingId = existingId;
+    }
+}
+
+/** True when the error is SQLite's unique violation on the request-key partial index. */
+function isRequestKeyUniqueViolation(error: unknown): boolean {
+    const msg = error instanceof Error ? error.message : String(error);
+    return (
+        msg.includes('UNIQUE constraint failed') &&
+        (msg.includes('idx_inbox_messages_request_key') || msg.includes('inbox_messages.request_key'))
+    );
+}
+
 // ---------------------------------------------------------------------------
 // DAO
 // ---------------------------------------------------------------------------
@@ -118,6 +155,60 @@ export class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inbo
         return id;
     }
 
+    /**
+     * Insert-first idempotent enqueue (task 0832): the caller-supplied request key
+     * is the arbiter, enforced by the partial unique index
+     * `idx_inbox_messages_request_key` (request_key IS NOT NULL) — no read-then-write
+     * window exists, so two concurrent submissions of one key cannot both insert.
+     *
+     * Same key + same body + same to_id → replay: returns the original row's id with
+     * `replayed: true` and emits nothing. Same key + different payload → throws
+     * `RequestKeyConflictError`. Emits `message.enqueued` only on a fresh insert.
+     */
+    async enqueueIdempotent(
+        fromId: string | null,
+        toId: string,
+        body: string,
+        requestKey: string,
+        inReplyTo?: string,
+    ): Promise<{ id: string; replayed: boolean }> {
+        const id = crypto.randomUUID();
+        const now = this.now();
+        try {
+            await this.create({
+                id,
+                fromId,
+                toId,
+                body,
+                status: 'queued',
+                injectAttempts: 0,
+                requestKey,
+                createdAt: now,
+                updatedAt: now,
+                ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+            });
+        } catch (error) {
+            if (isRequestKeyUniqueViolation(error)) {
+                // The constraint won the race (or the row already existed): fetch the
+                // winner and decide replay vs conflict by comparing the payload.
+                const existing = await this.findBy(inboxMessages.requestKey, requestKey);
+                if (existing && existing.body === body && existing.toId === toId) {
+                    return { id: existing.id, replayed: true };
+                }
+                throw new RequestKeyConflictError(requestKey, existing?.id ?? '');
+            }
+            throw error;
+        }
+        this.emitEvent('message.enqueued', {
+            id,
+            fromId,
+            toId,
+            ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+            timestamp: now,
+        });
+        return { id, replayed: false };
+    }
+
     async drainPending(toId: string, options?: { limit?: number }): Promise<InboxMessage[]> {
         // A backed-up inbox is claimed in pages of at most `limit` (default 100) so one
         // recipient's queue cannot be monopolised by a single drain (task 0060 F10).
@@ -193,6 +284,35 @@ export class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inbo
         }
     }
 
+    /**
+     * Release claimed (`injected`) messages back to `queued` so a drain whose
+     * invocation never started stays redeliverable. Only rows currently in
+     * `status = 'injected'` are touched — a `queued` or `delivered` row is
+     * left alone, so double-release is a no-op. `injectAttempts` and
+     * `injectError` are left untouched: the claim counter IS the budget.
+     * Emits one `message.requeued` event per released row.
+     */
+    async release(msgIds: string[]): Promise<number> {
+        if (msgIds.length === 0) return 0;
+        const now = this.now();
+        const rows = (await (this.db as UpdateReturningDb)
+            .update(inboxMessages)
+            .set({ status: 'queued', updatedAt: now })
+            .where(and(inArray(inboxMessages.id, msgIds), eq(inboxMessages.status, 'injected')))
+            .returning()) as InboxMessage[];
+
+        for (const row of rows) {
+            this.emitEvent('message.requeued', {
+                id: row.id,
+                fromId: row.fromId,
+                toId: row.toId,
+                timestamp: now,
+            });
+        }
+
+        return rows.length;
+    }
+
     async inbox(toId: string, limit?: number, offset?: number): Promise<InboxMessage[]> {
         return this.list({
             where: { col: inboxMessages.toId, op: 'eq', value: toId },

package/src/index.ts

@@ -23,6 +23,7 @@ export {
     type InboxMessageEventSink,
     type InboxMessageEvents,
     type InjectedMessageDetail,
+    RequestKeyConflictError,
 } from './inbox-message-dao';
 export { applyMigrations, type MigrationLogger, type MigrationOptions } from './migrate';
 export {

package/src/schema/inbox-messages.ts

@@ -17,6 +17,7 @@ export const inboxMessages = sqliteTable(
         deliveredAt: integer('delivered_at'),
         injectAttempts: integer('inject_attempts').notNull().default(0),
         injectError: text('inject_error'),
+        requestKey: text('request_key'),
     },
     (table) => [index('idx_inbox_messages_to_status').on(table.toId, table.status)],
 );