@gobing-ai/ts-db 0.4.7 → 0.4.9

package/README.md

@@ -286,6 +286,44 @@ const history = await inbox.inbox('coder', 20);
 const queued = await inbox.countPending('coder');
 ```
 
+
+#### Structural event sink
+
+`InboxMessageDao` accepts an optional `InboxMessageEventSink` via the second constructor
+argument. The DAO depends only on the structural port (`InboxMessageEventSink` is a plain
+interface); it does **not** import `@gobing-ai/ts-infra` or `EventBus`. This follows the
+`ProcessEventSink` pattern from ADR-013.
+
+```ts
+import { type BusLifecycleEvents, EventBus } from '@gobing-ai/ts-infra';
+import { InboxMessageDao, type InboxMessageEvents } from '@gobing-ai/ts-db/inbox';
+
+// Pass an EventBus directly as the structural sink — no adapter class needed.
+const lifecycleBus = new EventBus<BusLifecycleEvents>();
+const events = new EventBus<InboxMessageEvents>({ lifecycleBus });
+const inbox = new InboxMessageDao(adapter, { events });
+events.on('message.enqueued', (detail) => {
+    console.log(`message ${detail.id} from ${detail.fromId ?? 'operator'} to ${detail.toId}`);
+});
+```
+
+**Events emitted** (after the corresponding database mutation succeeds):
+
+|Event|Trigger|Key payload fields|
+|---|---|---|
+|`message.enqueued`|`enqueue` succeeds|`id`, `fromId`, `toId`, `inReplyTo?`|
+|`message.injected`|`drainPending` returns rows|`id`, `toId`, `inReplyTo?`, `injectAttempts`|
+|`message.delivered`|`markDelivered` succeeds|`id`, `toId`, `deliveredAt`|
+|`message.failed`|`markFailed` succeeds|`id`, `toId`, `error`|
+
+Omitting the sink preserves the existing contract — no no-op object is allocated and no
+event infrastructure is required.
+
+Event delivery is best-effort and never changes the result of an already-committed mutation:
+the DAO does not await observers and contains synchronous throws or rejected thenables. Lifecycle
+observers can persist event payloads, so message bodies are deliberately excluded. The required
+`message.failed.error` field may be persisted; callers must pass a pre-redacted error string.
+
 The `inbox_messages` table is additive and included in embedded migrations. It stores `from_id`,
 `to_id`, `body`, `status`, optional reply linkage, delivery timestamp, injection attempts, and the
 last injection error. The indexed access path is `(to_id, status)` for efficient pending drains.

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

@@ -3,11 +3,65 @@ import { EntityDao } from './entity-dao';
 import { inboxMessages } from './schema/inbox-messages';
 /** Row type inferred from the inbox_messages Drizzle schema. */
 export type InboxMessage = typeof inboxMessages.$inferSelect;
+/** Payload for a `message.enqueued` event. */
+export interface EnqueuedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    inReplyTo?: string;
+    timestamp: number;
+}
+/** Payload for a `message.injected` event (one per row returned by `drainPending`). */
+export interface InjectedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    inReplyTo?: string | null;
+    injectAttempts: number;
+    timestamp: number;
+}
+/** Payload for a `message.delivered` event. */
+export interface DeliveredMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    deliveredAt: number;
+    timestamp: number;
+}
+/** Payload for a `message.failed` event. */
+export interface FailedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    error: 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;
+};
+/**
+ * Zero-dependency structural event sink.
+ * `EventBus<InboxMessageEvents>` is structurally compatible — pass it as
+ * `{ events: eventBus }` in `InboxMessageDaoOptions`.
+ */
+export interface InboxMessageEventSink {
+    emit<K extends keyof InboxMessageEvents>(event: K, ...args: Parameters<InboxMessageEvents[K]>): void;
+}
+/** Options bag for `InboxMessageDao`. */
+export interface InboxMessageDaoOptions {
+    /** Optional structural event sink for message lifecycle observability. */
+    events?: InboxMessageEventSink;
+}
 /**
  * DAO for durable inter-agent inbox messages.
  */
 export declare class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inboxMessages.id> {
-    constructor(adapter: DbAdapter);
+    private readonly events?;
+    constructor(adapter: DbAdapter, options?: InboxMessageDaoOptions);
     enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string>;
     drainPending(toId: string): Promise<InboxMessage[]>;
     markDelivered(msgId: string): Promise<void>;
@@ -15,5 +69,7 @@ export declare class InboxMessageDao extends EntityDao<typeof inboxMessages, typ
     inbox(toId: string, limit?: number, offset?: number): Promise<InboxMessage[]>;
     countPending(toId: string): Promise<number>;
     getById(id: string): Promise<InboxMessage | undefined>;
+    /** Event delivery is observational: sink failures never change a committed DAO result. */
+    private emitEvent;
 }
 //# sourceMappingURL=inbox-message-dao.d.ts.map

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":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAE7D;;GAEG;AACH,qBAAa,eAAgB,SAAQ,SAAS,CAAC,OAAO,aAAa,EAAE,OAAO,aAAa,CAAC,EAAE,CAAC;gBAC7E,OAAO,EAAE,SAAS;IAIxB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc/F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwBnD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAS7E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS3C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CAG/D"}
+{"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,15 +1,26 @@
 import { sql } from 'drizzle-orm';
 import { EntityDao } from './entity-dao.js';
 import { inboxMessages } from './schema/inbox-messages.js';
+function isPromiseLike(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+// ---------------------------------------------------------------------------
+// DAO
+// ---------------------------------------------------------------------------
 /**
  * DAO for durable inter-agent inbox messages.
  */
 export class InboxMessageDao extends EntityDao {
-    constructor(adapter) {
+    events;
+    constructor(adapter, options = {}) {
         super(adapter, inboxMessages, [inboxMessages.id], 'inbox_messages');
+        this.events = options.events;
     }
     async enqueue(fromId, toId, body, inReplyTo) {
         const id = crypto.randomUUID();
+        const now = this.now();
         await this.create({
             id,
             fromId,
@@ -17,13 +28,22 @@ export class InboxMessageDao extends EntityDao {
             body,
             status: 'queued',
             injectAttempts: 0,
+            createdAt: now,
+            updatedAt: now,
+            ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+        });
+        this.emitEvent('message.enqueued', {
+            id,
+            fromId,
+            toId,
             ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+            timestamp: now,
         });
         return id;
     }
     async drainPending(toId) {
         const now = this.now();
-        const rows = await this.db
+        const rows = (await this.db
             .update(inboxMessages)
             .set({
             status: 'injected',
@@ -38,20 +58,49 @@ export class InboxMessageDao extends EntityDao {
                     ORDER BY created_at
                 )
                 AND ${inboxMessages.status} = 'queued'`)
-            .returning();
+            .returning());
+        for (const row of rows) {
+            this.emitEvent('message.injected', {
+                id: row.id,
+                fromId: row.fromId,
+                toId: row.toId,
+                inReplyTo: row.inReplyTo,
+                injectAttempts: row.injectAttempts,
+                timestamp: now,
+            });
+        }
         return rows;
     }
     async markDelivered(msgId) {
-        await this.update(msgId, {
+        const now = this.now();
+        const updated = await this.update(msgId, {
             status: 'delivered',
-            deliveredAt: this.now(),
+            deliveredAt: now,
         });
+        if (updated) {
+            this.emitEvent('message.delivered', {
+                id: updated.id,
+                fromId: updated.fromId,
+                toId: updated.toId,
+                deliveredAt: now,
+                timestamp: now,
+            });
+        }
     }
     async markFailed(msgId, error) {
-        await this.update(msgId, {
+        const updated = await this.update(msgId, {
             status: 'failed',
             injectError: error,
         });
+        if (updated) {
+            this.emitEvent('message.failed', {
+                id: updated.id,
+                fromId: updated.fromId,
+                toId: updated.toId,
+                error,
+                timestamp: updated.updatedAt,
+            });
+        }
     }
     async inbox(toId, limit, offset) {
         return this.list({
@@ -72,4 +121,20 @@ export class InboxMessageDao extends EntityDao {
     async getById(id) {
         return this.findBy(inboxMessages.id, id);
     }
+    /** Event delivery is observational: sink failures never change a committed DAO result. */
+    emitEvent(event, ...args) {
+        if (!this.events)
+            return;
+        try {
+            const pending = this.events.emit(event, ...args);
+            if (isPromiseLike(pending)) {
+                void Promise.resolve(pending).catch(() => {
+                    // A rejected observer must not turn a committed mutation into an apparent failure.
+                });
+            }
+        }
+        catch {
+            // A throwing observer must not turn a committed mutation into an apparent failure.
+        }
+    }
 }

package/dist/inbox.d.ts

@@ -1,3 +1,3 @@
-export { type InboxMessage, InboxMessageDao } from './inbox-message-dao';
+export { type DeliveredMessageDetail, type EnqueuedMessageDetail, type FailedMessageDetail, type InboxMessage, InboxMessageDao, type InboxMessageDaoOptions, type InboxMessageEventSink, type InboxMessageEvents, type InjectedMessageDetail, } from './inbox-message-dao';
 export { inboxMessages } from './schema/inbox-messages';
 //# sourceMappingURL=inbox.d.ts.map

package/dist/inbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../src/inbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../src/inbox.ts"],"names":[],"mappings":"AAAA,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,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/inbox.js

@@ -1,2 +1,2 @@
-export { InboxMessageDao } from './inbox-message-dao.js';
+export { InboxMessageDao, } from './inbox-message-dao.js';
 export { inboxMessages } from './schema/inbox-messages.js';

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { D1Adapter } from './adapters/d1';
 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 InboxMessage, InboxMessageDao } from './inbox-message-dao';
+export { type DeliveredMessageDetail, type EnqueuedMessageDetail, type FailedMessageDetail, type InboxMessage, InboxMessageDao, type InboxMessageDaoOptions, type InboxMessageEventSink, type InboxMessageEvents, type InjectedMessageDetail, } 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,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,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,EAAE,KAAK,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,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,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,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"}

package/dist/index.js

@@ -3,7 +3,7 @@ export { D1Adapter } from './adapters/d1.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, } 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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-db",
-    "version": "0.4.7",
+    "version": "0.4.9",
     "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",
@@ -66,8 +66,8 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-db-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-runtime": "^0.4.7",
-        "@gobing-ai/ts-utils": "^0.4.7"
+        "@gobing-ai/ts-runtime": "^0.4.9",
+        "@gobing-ai/ts-utils": "^0.4.9"
     },
     "peerDependencies": {
         "drizzle-orm": ">=0.38.0",

package/src/inbox-message-dao.ts

@@ -7,16 +7,96 @@ import { inboxMessages } from './schema/inbox-messages';
 /** Row type inferred from the inbox_messages Drizzle schema. */
 export type InboxMessage = typeof inboxMessages.$inferSelect;
 
+// ---------------------------------------------------------------------------
+// Event types (structural port — no ts-infra dependency, per ADR-013 pattern)
+// ---------------------------------------------------------------------------
+
+/** Payload for a `message.enqueued` event. */
+export interface EnqueuedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    inReplyTo?: string;
+    timestamp: number;
+}
+
+/** Payload for a `message.injected` event (one per row returned by `drainPending`). */
+export interface InjectedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    inReplyTo?: string | null;
+    injectAttempts: number;
+    timestamp: number;
+}
+
+/** Payload for a `message.delivered` event. */
+export interface DeliveredMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    deliveredAt: number;
+    timestamp: number;
+}
+
+/** Payload for a `message.failed` event. */
+export interface FailedMessageDetail {
+    id: string;
+    fromId: string | null;
+    toId: string;
+    error: 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;
+};
+
+/**
+ * Zero-dependency structural event sink.
+ * `EventBus<InboxMessageEvents>` is structurally compatible — pass it as
+ * `{ events: eventBus }` in `InboxMessageDaoOptions`.
+ */
+export interface InboxMessageEventSink {
+    emit<K extends keyof InboxMessageEvents>(event: K, ...args: Parameters<InboxMessageEvents[K]>): void;
+}
+
+/** Options bag for `InboxMessageDao`. */
+export interface InboxMessageDaoOptions {
+    /** Optional structural event sink for message lifecycle observability. */
+    events?: InboxMessageEventSink;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+    return (
+        value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof (value as { then?: unknown }).then === 'function'
+    );
+}
+
+// ---------------------------------------------------------------------------
+// DAO
+// ---------------------------------------------------------------------------
+
 /**
  * DAO for durable inter-agent inbox messages.
  */
 export class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inboxMessages.id> {
-    constructor(adapter: DbAdapter) {
+    private readonly events?: InboxMessageEventSink;
+
+    constructor(adapter: DbAdapter, options: InboxMessageDaoOptions = {}) {
         super(adapter, inboxMessages, [inboxMessages.id], 'inbox_messages');
+        this.events = options.events;
     }
 
     async enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string> {
         const id = crypto.randomUUID();
+        const now = this.now();
         await this.create({
             id,
             fromId,
@@ -24,14 +104,23 @@ export class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inbo
             body,
             status: 'queued',
             injectAttempts: 0,
+            createdAt: now,
+            updatedAt: now,
             ...(inReplyTo !== undefined ? { inReplyTo } : {}),
         });
+        this.emitEvent('message.enqueued', {
+            id,
+            fromId,
+            toId,
+            ...(inReplyTo !== undefined ? { inReplyTo } : {}),
+            timestamp: now,
+        });
         return id;
     }
 
     async drainPending(toId: string): Promise<InboxMessage[]> {
         const now = this.now();
-        const rows = await (this.db as UpdateReturningDb)
+        const rows = (await (this.db as UpdateReturningDb)
             .update(inboxMessages)
             .set({
                 status: 'injected',
@@ -48,23 +137,53 @@ export class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inbo
                 )
                 AND ${inboxMessages.status} = 'queued'`,
             )
-            .returning();
+            .returning()) as InboxMessage[];
+
+        for (const row of rows) {
+            this.emitEvent('message.injected', {
+                id: row.id,
+                fromId: row.fromId,
+                toId: row.toId,
+                inReplyTo: row.inReplyTo,
+                injectAttempts: row.injectAttempts,
+                timestamp: now,
+            });
+        }
 
         return rows as InboxMessage[];
     }
 
     async markDelivered(msgId: string): Promise<void> {
-        await this.update(msgId, {
+        const now = this.now();
+        const updated = await this.update(msgId, {
             status: 'delivered',
-            deliveredAt: this.now(),
+            deliveredAt: now,
         });
+        if (updated) {
+            this.emitEvent('message.delivered', {
+                id: updated.id,
+                fromId: updated.fromId,
+                toId: updated.toId,
+                deliveredAt: now,
+                timestamp: now,
+            });
+        }
     }
 
     async markFailed(msgId: string, error: string): Promise<void> {
-        await this.update(msgId, {
+        const updated = await this.update(msgId, {
             status: 'failed',
             injectError: error,
         });
+        if (updated) {
+            this.emitEvent('message.failed', {
+                id: updated.id,
+                fromId: updated.fromId,
+                toId: updated.toId,
+                error,
+                timestamp: updated.updatedAt,
+            });
+        }
     }
 
     async inbox(toId: string, limit?: number, offset?: number): Promise<InboxMessage[]> {
@@ -88,4 +207,19 @@ export class InboxMessageDao extends EntityDao<typeof inboxMessages, typeof inbo
     async getById(id: string): Promise<InboxMessage | undefined> {
         return this.findBy(inboxMessages.id, id);
     }
+
+    /** Event delivery is observational: sink failures never change a committed DAO result. */
+    private emitEvent<K extends keyof InboxMessageEvents>(event: K, ...args: Parameters<InboxMessageEvents[K]>): void {
+        if (!this.events) return;
+        try {
+            const pending = this.events.emit(event, ...args) as unknown;
+            if (isPromiseLike(pending)) {
+                void Promise.resolve(pending).catch(() => {
+                    // A rejected observer must not turn a committed mutation into an apparent failure.
+                });
+            }
+        } catch {
+            // A throwing observer must not turn a committed mutation into an apparent failure.
+        }
+    }
 }

package/src/inbox.ts

@@ -1,2 +1,12 @@
-export { type InboxMessage, InboxMessageDao } from './inbox-message-dao';
+export {
+    type DeliveredMessageDetail,
+    type EnqueuedMessageDetail,
+    type FailedMessageDetail,
+    type InboxMessage,
+    InboxMessageDao,
+    type InboxMessageDaoOptions,
+    type InboxMessageEventSink,
+    type InboxMessageEvents,
+    type InjectedMessageDetail,
+} from './inbox-message-dao';
 export { inboxMessages } from './schema/inbox-messages';

package/src/index.ts

@@ -14,7 +14,17 @@ export {
     type PKValue,
     type SoftDeletableTable,
 } from './entity-dao';
-export { type InboxMessage, InboxMessageDao } from './inbox-message-dao';
+export {
+    type DeliveredMessageDetail,
+    type EnqueuedMessageDetail,
+    type FailedMessageDetail,
+    type InboxMessage,
+    InboxMessageDao,
+    type InboxMessageDaoOptions,
+    type InboxMessageEventSink,
+    type InboxMessageEvents,
+    type InjectedMessageDetail,
+} from './inbox-message-dao';
 export { applyMigrations, type MigrationLogger, type MigrationOptions } from './migrate';
 export {
     type ColRef,