@chidchanun/bcp 0.2.10 → 0.2.12

package/packages/server/src/events.ts

@@ -0,0 +1,1416 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+import type {
+    BcpDatabase,
+    DatabaseDriver,
+    TransactionDatabase,
+} from "../../client/src/database.js";
+import type {
+    BackgroundJobQueue,
+} from "./jobs.js";
+
+export type OutboxEventState =
+    | "pending"
+    | "processing"
+    | "published"
+    | "failed";
+
+export interface OutboxEventRecord<TPayload = unknown> {
+    id: string;
+    type: string;
+    payload: TPayload;
+    metadata: Record<string, unknown>;
+    state: OutboxEventState;
+    attempts: number;
+    maxAttempts: number;
+    createdAt: number;
+    availableAt: number;
+    processingAt?: number;
+    publishedAt?: number;
+    failedAt?: number;
+    error?: string;
+    correlationId?: string;
+    causationId?: string;
+    aggregateId?: string;
+    leaseOwner?: string;
+    leaseUntil?: number;
+}
+
+export interface PublishOutboxEventOptions {
+    id?: string;
+    metadata?: Record<string, unknown>;
+    correlationId?: string;
+    causationId?: string;
+    aggregateId?: string;
+    delayMs?: number;
+    maxAttempts?: number;
+}
+
+export interface ClaimOutboxEventsOptions {
+    ownerId: string;
+    leaseMs: number;
+    limit?: number;
+}
+
+export interface FailOutboxEventOptions {
+    ownerId: string;
+    error: string;
+    failedAt: number;
+    retryAt?: number;
+}
+
+export interface CleanupOutboxOptions {
+    before: number;
+}
+
+export interface OutboxStats {
+    total: number;
+    pending: number;
+    processing: number;
+    published: number;
+    failed: number;
+}
+
+export interface OutboxStore {
+    append<TPayload = unknown>(
+        transaction: TransactionDatabase,
+        event: OutboxEventRecord<TPayload>
+    ): Promise<void>;
+    claimDue(
+        now: number,
+        options: ClaimOutboxEventsOptions
+    ): Promise<OutboxEventRecord[]>;
+    markPublished(
+        id: string,
+        publishedAt: number,
+        ownerId: string
+    ): Promise<boolean>;
+    markFailed(
+        id: string,
+        options: FailOutboxEventOptions
+    ): Promise<boolean>;
+    recoverStale(
+        now: number,
+        limit?: number
+    ): Promise<number>;
+    get<TPayload = unknown>(
+        id: string
+    ): Promise<OutboxEventRecord<TPayload> | null>;
+    list(): Promise<OutboxEventRecord[]>;
+    cleanup(
+        options: CleanupOutboxOptions
+    ): Promise<number>;
+    stats(): Promise<OutboxStats>;
+    close?(): Promise<void>;
+}
+
+export interface MemoryOutboxStore
+extends OutboxStore {
+    clear(): void;
+}
+
+export interface TransactionalOutboxOptions {
+    store: OutboxStore;
+    now?: () => number;
+    idFactory?: () => string;
+    defaultMaxAttempts?: number;
+}
+
+export interface TransactionalOutbox {
+    readonly store: OutboxStore;
+    publish<TPayload = unknown>(
+        transaction: TransactionDatabase,
+        type: string,
+        payload: TPayload,
+        options?: PublishOutboxEventOptions
+    ): Promise<OutboxEventRecord<TPayload>>;
+}
+
+export interface OutboxEventHandlerContext<TPayload = unknown> {
+    event: Readonly<OutboxEventRecord<TPayload>>;
+    payload: TPayload;
+}
+
+export type OutboxEventHandler<TPayload = unknown> = (
+    context: OutboxEventHandlerContext<TPayload>
+) => unknown | Promise<unknown>;
+
+export interface EventBus {
+    on<TPayload = unknown>(
+        type: string,
+        handler: OutboxEventHandler<TPayload>
+    ): () => void;
+    emit(
+        event: OutboxEventRecord
+    ): Promise<void>;
+    clear(): void;
+}
+
+export type OutboxRetryDelay =
+    | number
+    | ((attempt: number) => number);
+
+export interface OutboxDispatcherOptions {
+    store: OutboxStore;
+    queue?: BackgroundJobQueue;
+    publish?: (
+        event: OutboxEventRecord
+    ) => unknown | Promise<unknown>;
+    eventBus?: EventBus;
+    ownerId?: string;
+    leaseMs?: number;
+    batchSize?: number;
+    pollIntervalMs?: number;
+    retryDelayMs?: OutboxRetryDelay;
+    queueNamePrefix?: string;
+    now?: () => number;
+    onError?: (
+        error: unknown,
+        event?: OutboxEventRecord
+    ) => void | Promise<void>;
+}
+
+export interface OutboxDispatcherRunner {
+    readonly running: boolean;
+    stop(): Promise<void>;
+}
+
+export interface OutboxDispatcher {
+    readonly store: OutboxStore;
+    readonly ownerId: string;
+    dispatchBatch(): Promise<number>;
+    recoverStale(limit?: number): Promise<number>;
+    start(): OutboxDispatcherRunner;
+    close(): Promise<void>;
+}
+
+export interface SqlOutboxStoreOptions {
+    database: Pick<
+        BcpDatabase,
+        "query" | "execute" | "transaction"
+    >;
+    driver: DatabaseDriver;
+    tableName?: string;
+}
+
+export interface SqlOutboxStore
+extends OutboxStore {
+    readonly driver: DatabaseDriver;
+    readonly tableName: string;
+}
+
+export function createMemoryOutboxStore():
+MemoryOutboxStore {
+    const events =
+        new Map<string, OutboxEventRecord>();
+
+    return {
+        async append(_transaction, event) {
+            if (events.has(event.id)) {
+                throw new Error(
+                    `BCP Events: outbox event id "${event.id}" already exists.`
+                );
+            }
+            events.set(
+                event.id,
+                cloneEvent(event)
+            );
+        },
+
+        async claimDue(now, options) {
+            const ownerId =
+                normalizeText(
+                    options.ownerId,
+                    "dispatcher owner id"
+                );
+            const leaseMs =
+                positiveInteger(
+                    options.leaseMs,
+                    "leaseMs"
+                );
+            const limit =
+                positiveInteger(
+                    options.limit ?? 100,
+                    "batch limit"
+                );
+
+            recoverMemoryStale(
+                events,
+                now,
+                Number.MAX_SAFE_INTEGER
+            );
+
+            const due =
+                Array.from(events.values())
+                    .filter(event =>
+                        event.state === "pending" &&
+                        event.availableAt <= now &&
+                        event.attempts < event.maxAttempts
+                    )
+                    .sort(compareEvents)
+                    .slice(0, limit);
+
+            for (const event of due) {
+                event.state = "processing";
+                event.attempts += 1;
+                event.processingAt = now;
+                event.leaseOwner = ownerId;
+                event.leaseUntil = now + leaseMs;
+                event.error = undefined;
+            }
+
+            return due.map(cloneEvent);
+        },
+
+        async markPublished(id, publishedAt, ownerId) {
+            const event = events.get(id);
+            if (
+                !event ||
+                event.state !== "processing" ||
+                event.leaseOwner !== ownerId
+            ) {
+                return false;
+            }
+            event.state = "published";
+            event.publishedAt = publishedAt;
+            event.failedAt = undefined;
+            event.error = undefined;
+            clearLease(event);
+            return true;
+        },
+
+        async markFailed(id, options) {
+            const event = events.get(id);
+            if (
+                !event ||
+                event.state !== "processing" ||
+                event.leaseOwner !== options.ownerId
+            ) {
+                return false;
+            }
+
+            event.error = options.error;
+            clearLease(event);
+
+            if (
+                options.retryAt !== undefined &&
+                event.attempts < event.maxAttempts
+            ) {
+                event.state = "pending";
+                event.availableAt = options.retryAt;
+                event.processingAt = undefined;
+                return true;
+            }
+
+            event.state = "failed";
+            event.failedAt = options.failedAt;
+            return true;
+        },
+
+        async recoverStale(now, limit = 100) {
+            return recoverMemoryStale(
+                events,
+                now,
+                positiveInteger(limit, "recovery limit")
+            );
+        },
+
+        async get(id) {
+            const event = events.get(id);
+            return event
+                ? cloneEvent(event) as OutboxEventRecord<any>
+                : null;
+        },
+
+        async list() {
+            return Array.from(events.values())
+                .map(cloneEvent)
+                .sort(compareEvents);
+        },
+
+        async cleanup(options) {
+            finiteNumber(
+                options.before,
+                "cleanup before"
+            );
+            let removed = 0;
+            for (const [id, event] of events) {
+                const terminalAt =
+                    event.publishedAt ??
+                    event.failedAt;
+                if (
+                    (event.state === "published" || event.state === "failed") &&
+                    terminalAt !== undefined &&
+                    terminalAt <= options.before
+                ) {
+                    events.delete(id);
+                    removed += 1;
+                }
+            }
+            return removed;
+        },
+
+        async stats() {
+            return calculateStats(
+                Array.from(events.values())
+            );
+        },
+
+        clear() {
+            events.clear();
+        },
+    };
+}
+
+export function createTransactionalOutbox(
+    options: TransactionalOutboxOptions
+): TransactionalOutbox {
+    if (!options?.store) {
+        throw new TypeError(
+            "BCP Events: transactional outbox requires a store."
+        );
+    }
+
+    const store = options.store;
+    const now = options.now ?? Date.now;
+    const idFactory = options.idFactory ?? randomUUID;
+    const defaultMaxAttempts =
+        positiveInteger(
+            options.defaultMaxAttempts ?? 5,
+            "defaultMaxAttempts"
+        );
+
+    return {
+        store,
+
+        async publish(
+            transaction,
+            rawType,
+            payload,
+            publishOptions = {}
+        ) {
+            assertTransaction(transaction);
+            const type =
+                normalizeText(
+                    rawType,
+                    "event type"
+                );
+            const createdAt = now();
+            const delayMs =
+                nonNegativeNumber(
+                    publishOptions.delayMs ?? 0,
+                    "delayMs"
+                );
+            const event:
+                OutboxEventRecord<typeof payload> = {
+                id: normalizeText(
+                    publishOptions.id ?? idFactory(),
+                    "event id"
+                ),
+                type,
+                payload,
+                metadata: {
+                    ...(publishOptions.metadata ?? {}),
+                },
+                state: "pending",
+                attempts: 0,
+                maxAttempts: positiveInteger(
+                    publishOptions.maxAttempts ?? defaultMaxAttempts,
+                    "maxAttempts"
+                ),
+                createdAt,
+                availableAt: createdAt + delayMs,
+                correlationId:
+                    optionalText(
+                        publishOptions.correlationId
+                    ),
+                causationId:
+                    optionalText(
+                        publishOptions.causationId
+                    ),
+                aggregateId:
+                    optionalText(
+                        publishOptions.aggregateId
+                    ),
+            };
+
+            await store.append(
+                transaction,
+                event
+            );
+
+            return cloneEvent(event);
+        },
+    };
+}
+
+export function createEventBus(): EventBus {
+    const handlers =
+        new Map<
+            string,
+            Set<OutboxEventHandler<any>>
+        >();
+
+    return {
+        on(type, handler) {
+            const normalizedType =
+                normalizeText(type, "event type");
+            if (typeof handler !== "function") {
+                throw new TypeError(
+                    "BCP Events: event handler must be a function."
+                );
+            }
+            let group = handlers.get(normalizedType);
+            if (!group) {
+                group = new Set();
+                handlers.set(normalizedType, group);
+            }
+            group.add(handler);
+            return () => {
+                group?.delete(handler);
+                if (group?.size === 0) {
+                    handlers.delete(normalizedType);
+                }
+            };
+        },
+
+        async emit(event) {
+            const group = handlers.get(event.type);
+            if (!group || group.size === 0) {
+                return;
+            }
+            for (const handler of group) {
+                await handler({
+                    event: cloneEvent(event),
+                    payload: event.payload,
+                });
+            }
+        },
+
+        clear() {
+            handlers.clear();
+        },
+    };
+}
+
+export function createOutboxDispatcher(
+    options: OutboxDispatcherOptions
+): OutboxDispatcher {
+    if (!options?.store) {
+        throw new TypeError(
+            "BCP Events: dispatcher requires an outbox store."
+        );
+    }
+    if (
+        !options.queue &&
+        !options.publish &&
+        !options.eventBus
+    ) {
+        throw new TypeError(
+            "BCP Events: dispatcher requires queue, publish or eventBus delivery."
+        );
+    }
+
+    const store = options.store;
+    const queue = options.queue;
+    const eventBus = options.eventBus;
+    const publish = options.publish;
+    const ownerId =
+        normalizeText(
+            options.ownerId ??
+            `outbox-${randomUUID()}`,
+            "dispatcher owner id"
+        );
+    const leaseMs =
+        positiveInteger(
+            options.leaseMs ?? 30_000,
+            "leaseMs"
+        );
+    const batchSize =
+        positiveInteger(
+            options.batchSize ?? 100,
+            "batchSize"
+        );
+    const pollIntervalMs =
+        nonNegativeNumber(
+            options.pollIntervalMs ?? 1_000,
+            "pollIntervalMs"
+        );
+    const retryDelay =
+        options.retryDelayMs ??
+        ((attempt: number) =>
+            Math.min(
+                60_000,
+                1_000 * Math.pow(2, Math.max(0, attempt - 1))
+            ));
+    const queueNamePrefix =
+        String(
+            options.queueNamePrefix ?? "event."
+        );
+    const now = options.now ?? Date.now;
+    const runners =
+        new Set<OutboxDispatcherRunner>();
+
+    const dispatcher: OutboxDispatcher = {
+        store,
+        ownerId,
+
+        async dispatchBatch() {
+            await store.recoverStale(
+                now(),
+                batchSize
+            );
+            const events =
+                await store.claimDue(
+                    now(),
+                    {
+                        ownerId,
+                        leaseMs,
+                        limit: batchSize,
+                    }
+                );
+
+            let publishedCount = 0;
+
+            for (const event of events) {
+                try {
+                    if (queue) {
+                        await queue.enqueue(
+                            `${queueNamePrefix}${event.type}`,
+                            createEventEnvelope(event),
+                            {
+                                id: `outbox:${event.id}`,
+                                maxAttempts: 1,
+                            }
+                        );
+                    }
+                    if (eventBus) {
+                        await eventBus.emit(event);
+                    }
+                    if (publish) {
+                        await publish(event);
+                    }
+
+                    const marked =
+                        await store.markPublished(
+                            event.id,
+                            now(),
+                            ownerId
+                        );
+                    if (marked) {
+                        publishedCount += 1;
+                    }
+                } catch (error) {
+                    const failedAt = now();
+                    const retryAt =
+                        event.attempts < event.maxAttempts
+                            ? failedAt + resolveRetryDelay(
+                                retryDelay,
+                                event.attempts
+                            )
+                            : undefined;
+                    await store.markFailed(
+                        event.id,
+                        {
+                            ownerId,
+                            error: formatError(error),
+                            failedAt,
+                            retryAt,
+                        }
+                    );
+                    if (options.onError) {
+                        await options.onError(
+                            error,
+                            cloneEvent(event)
+                        );
+                    }
+                }
+            }
+
+            return publishedCount;
+        },
+
+        recoverStale(limit = batchSize) {
+            return store.recoverStale(
+                now(),
+                positiveInteger(
+                    limit,
+                    "recovery limit"
+                )
+            );
+        },
+
+        start() {
+            let running = true;
+            let stopPromise: Promise<void> | null = null;
+            const controller = new AbortController();
+            const loop = async () => {
+                while (
+                    running &&
+                    !controller.signal.aborted
+                ) {
+                    try {
+                        await dispatcher.dispatchBatch();
+                    } catch (error) {
+                        if (options.onError) {
+                            await options.onError(error);
+                        }
+                    }
+                    if (
+                        running &&
+                        !controller.signal.aborted
+                    ) {
+                        await sleep(
+                            pollIntervalMs,
+                            controller.signal
+                        );
+                    }
+                }
+            };
+            const loopPromise = loop();
+
+            const runner: OutboxDispatcherRunner = {
+                get running() {
+                    return running;
+                },
+                stop() {
+                    if (!stopPromise) {
+                        running = false;
+                        controller.abort();
+                        stopPromise =
+                            loopPromise.catch(error => {
+                                if (!isAbortError(error)) {
+                                    throw error;
+                                }
+                            }).then(() => {
+                                runners.delete(runner);
+                            });
+                    }
+                    return stopPromise;
+                },
+            };
+            runners.add(runner);
+            return runner;
+        },
+
+        async close() {
+            await Promise.all(
+                Array.from(
+                    runners,
+                    runner => runner.stop()
+                )
+            );
+            await store.close?.();
+        },
+    };
+
+    return dispatcher;
+}
+
+export function createSqlOutboxStore(
+    options: SqlOutboxStoreOptions
+): SqlOutboxStore {
+    if (!options?.database) {
+        throw new TypeError(
+            "BCP Events: SQL outbox store requires a database."
+        );
+    }
+    const database = options.database;
+    const driver = normalizeDriver(options.driver);
+    const tableName =
+        normalizeIdentifier(
+            options.tableName ?? "bcp_outbox_events"
+        );
+
+    return {
+        driver,
+        tableName,
+
+        async append(transaction, event) {
+            assertTransaction(transaction);
+            const values = [
+                event.id,
+                event.type,
+                JSON.stringify(event.payload),
+                JSON.stringify(event.metadata),
+                event.state,
+                event.attempts,
+                event.maxAttempts,
+                event.createdAt,
+                event.availableAt,
+                event.correlationId ?? null,
+                event.causationId ?? null,
+                event.aggregateId ?? null,
+            ];
+            await transaction.execute(
+                `INSERT INTO ${tableName} (` +
+                "id, event_type, payload_json, metadata_json, state, attempts, max_attempts, created_at, available_at, correlation_id, causation_id, aggregate_id" +
+                `) VALUES (${placeholders(driver, values.length)})`,
+                values
+            );
+        },
+
+        async claimDue(now, claimOptions) {
+            const ownerId =
+                normalizeText(
+                    claimOptions.ownerId,
+                    "dispatcher owner id"
+                );
+            const leaseMs =
+                positiveInteger(
+                    claimOptions.leaseMs,
+                    "leaseMs"
+                );
+            const limit =
+                positiveInteger(
+                    claimOptions.limit ?? 100,
+                    "batch limit"
+                );
+
+            return database.transaction(
+                async transaction => {
+                    await recoverSqlStale(
+                        transaction,
+                        driver,
+                        tableName,
+                        now
+                    );
+
+                    const candidates =
+                        await transaction.query<Record<string, unknown>[]>(
+                            `SELECT * FROM ${tableName} ` +
+                            "WHERE state = " + bind(driver, 1) +
+                            " AND available_at <= " + bind(driver, 2) +
+                            " AND attempts < max_attempts " +
+                            "ORDER BY available_at ASC, created_at ASC, id ASC " +
+                            `LIMIT ${limit}` +
+                            (driver === "sqlite"
+                                ? ""
+                                : " FOR UPDATE SKIP LOCKED"),
+                            ["pending", now]
+                        );
+
+                    const claimed:
+                        OutboxEventRecord[] = [];
+                    for (const row of candidates) {
+                        const id = String(row.id ?? "");
+                        if (!id) {
+                            continue;
+                        }
+                        const updateValues = [
+                            "processing",
+                            now,
+                            ownerId,
+                            now + leaseMs,
+                            id,
+                            "pending",
+                        ];
+                        await transaction.execute(
+                            `UPDATE ${tableName} SET ` +
+                            `state = ${bind(driver, 1)}, ` +
+                            `attempts = attempts + 1, ` +
+                            `processing_at = ${bind(driver, 2)}, ` +
+                            `lease_owner = ${bind(driver, 3)}, ` +
+                            `lease_until = ${bind(driver, 4)}, error_text = NULL ` +
+                            `WHERE id = ${bind(driver, 5)} AND state = ${bind(driver, 6)}`,
+                            updateValues
+                        );
+                        const rows =
+                            await transaction.query<Record<string, unknown>[]>(
+                                `SELECT * FROM ${tableName} WHERE id = ${bind(driver, 1)} AND state = ${bind(driver, 2)} AND lease_owner = ${bind(driver, 3)}`,
+                                [id, "processing", ownerId]
+                            );
+                        if (rows[0]) {
+                            claimed.push(
+                                rowToEvent(rows[0])
+                            );
+                        }
+                    }
+                    return claimed;
+                }
+            );
+        },
+
+        async markPublished(id, publishedAt, ownerId) {
+            return conditionalUpdate(
+                database,
+                driver,
+                tableName,
+                id,
+                ownerId,
+                `state = ${bind(driver, 1)}, published_at = ${bind(driver, 2)}, error_text = NULL, lease_owner = NULL, lease_until = NULL`,
+                ["published", publishedAt]
+            );
+        },
+
+        async markFailed(id, failOptions) {
+            const retry =
+                failOptions.retryAt !== undefined;
+            const setClause = retry
+                ? `state = ${bind(driver, 1)}, available_at = ${bind(driver, 2)}, processing_at = NULL, error_text = ${bind(driver, 3)}, lease_owner = NULL, lease_until = NULL`
+                : `state = ${bind(driver, 1)}, failed_at = ${bind(driver, 2)}, error_text = ${bind(driver, 3)}, lease_owner = NULL, lease_until = NULL`;
+            const values = retry
+                ? ["pending", failOptions.retryAt, failOptions.error]
+                : ["failed", failOptions.failedAt, failOptions.error];
+            return conditionalUpdate(
+                database,
+                driver,
+                tableName,
+                id,
+                failOptions.ownerId,
+                setClause,
+                values
+            );
+        },
+
+        async recoverStale(now, limit = 100) {
+            const normalizedLimit =
+                positiveInteger(limit, "recovery limit");
+            return database.transaction(
+                async transaction => {
+                    const rows =
+                        await transaction.query<Record<string, unknown>[]>(
+                            `SELECT id FROM ${tableName} WHERE state = ${bind(driver, 1)} AND lease_until IS NOT NULL AND lease_until <= ${bind(driver, 2)} ORDER BY lease_until ASC, id ASC LIMIT ${normalizedLimit}`,
+                            ["processing", now]
+                        );
+                    for (const row of rows) {
+                        const id = String(row.id ?? "");
+                        if (!id) {
+                            continue;
+                        }
+                        await transaction.execute(
+                            `UPDATE ${tableName} SET state = ${bind(driver, 1)}, processing_at = NULL, lease_owner = NULL, lease_until = NULL WHERE id = ${bind(driver, 2)} AND state = ${bind(driver, 3)} AND lease_until <= ${bind(driver, 4)}`,
+                            ["pending", id, "processing", now]
+                        );
+                    }
+                    return rows.length;
+                }
+            );
+        },
+
+        async get(id) {
+            const rows =
+                await database.query<Record<string, unknown>[]>(
+                    `SELECT * FROM ${tableName} WHERE id = ${bind(driver, 1)}`,
+                    [id]
+                );
+            return rows[0]
+                ? rowToEvent(rows[0]) as OutboxEventRecord<any>
+                : null;
+        },
+
+        async list() {
+            const rows =
+                await database.query<Record<string, unknown>[]>(
+                    `SELECT * FROM ${tableName} ORDER BY created_at ASC, id ASC`
+                );
+            return rows.map(rowToEvent);
+        },
+
+        async cleanup(cleanupOptions) {
+            finiteNumber(
+                cleanupOptions.before,
+                "cleanup before"
+            );
+            const rows =
+                await database.query<Record<string, unknown>[]>(
+                    `SELECT id FROM ${tableName} WHERE ` +
+                    `(state = ${bind(driver, 1)} AND published_at <= ${bind(driver, 2)}) OR ` +
+                    `(state = ${bind(driver, 3)} AND failed_at <= ${bind(driver, 4)})`,
+                    [
+                        "published",
+                        cleanupOptions.before,
+                        "failed",
+                        cleanupOptions.before,
+                    ]
+                );
+            await database.execute(
+                `DELETE FROM ${tableName} WHERE ` +
+                `(state = ${bind(driver, 1)} AND published_at <= ${bind(driver, 2)}) OR ` +
+                `(state = ${bind(driver, 3)} AND failed_at <= ${bind(driver, 4)})`,
+                [
+                    "published",
+                    cleanupOptions.before,
+                    "failed",
+                    cleanupOptions.before,
+                ]
+            );
+            return rows.length;
+        },
+
+        async stats() {
+            const rows =
+                await database.query<Array<{
+                    state: string;
+                    count: number | string;
+                }>>(
+                    `SELECT state, COUNT(*) AS count FROM ${tableName} GROUP BY state`
+                );
+            const stats: OutboxStats = {
+                total: 0,
+                pending: 0,
+                processing: 0,
+                published: 0,
+                failed: 0,
+            };
+            for (const row of rows) {
+                const count = Number(row.count ?? 0);
+                if (
+                    row.state === "pending" ||
+                    row.state === "processing" ||
+                    row.state === "published" ||
+                    row.state === "failed"
+                ) {
+                    stats[row.state] += count;
+                    stats.total += count;
+                }
+            }
+            return stats;
+        },
+    };
+}
+
+export function createOutboxMigrationSql(
+    driver: DatabaseDriver,
+    tableName = "bcp_outbox_events"
+): string {
+    const normalizedDriver =
+        normalizeDriver(driver);
+    const table =
+        normalizeIdentifier(tableName);
+
+    if (normalizedDriver === "mysql") {
+        return `CREATE TABLE IF NOT EXISTS ${table} (\n` +
+            "  id VARCHAR(191) PRIMARY KEY,\n" +
+            "  event_type VARCHAR(191) NOT NULL,\n" +
+            "  payload_json LONGTEXT NOT NULL,\n" +
+            "  metadata_json LONGTEXT NOT NULL,\n" +
+            "  state VARCHAR(32) NOT NULL,\n" +
+            "  attempts INT NOT NULL DEFAULT 0,\n" +
+            "  max_attempts INT NOT NULL,\n" +
+            "  created_at BIGINT NOT NULL,\n" +
+            "  available_at BIGINT NOT NULL,\n" +
+            "  processing_at BIGINT NULL,\n" +
+            "  published_at BIGINT NULL,\n" +
+            "  failed_at BIGINT NULL,\n" +
+            "  error_text TEXT NULL,\n" +
+            "  correlation_id VARCHAR(191) NULL,\n" +
+            "  causation_id VARCHAR(191) NULL,\n" +
+            "  aggregate_id VARCHAR(191) NULL,\n" +
+            "  lease_owner VARCHAR(191) NULL,\n" +
+            "  lease_until BIGINT NULL,\n" +
+            "  INDEX idx_bcp_outbox_due (state, available_at),\n" +
+            "  INDEX idx_bcp_outbox_lease (state, lease_until)\n" +
+            ") ENGINE=InnoDB;";
+    }
+
+    const idType =
+        normalizedDriver === "postgresql"
+            ? "VARCHAR(191)"
+            : "TEXT";
+    const textType =
+        normalizedDriver === "postgresql"
+            ? "TEXT"
+            : "TEXT";
+    return `CREATE TABLE IF NOT EXISTS ${table} (\n` +
+        `  id ${idType} PRIMARY KEY,\n` +
+        `  event_type ${idType} NOT NULL,\n` +
+        `  payload_json ${textType} NOT NULL,\n` +
+        `  metadata_json ${textType} NOT NULL,\n` +
+        `  state ${idType} NOT NULL,\n` +
+        "  attempts INTEGER NOT NULL DEFAULT 0,\n" +
+        "  max_attempts INTEGER NOT NULL,\n" +
+        "  created_at BIGINT NOT NULL,\n" +
+        "  available_at BIGINT NOT NULL,\n" +
+        "  processing_at BIGINT NULL,\n" +
+        "  published_at BIGINT NULL,\n" +
+        "  failed_at BIGINT NULL,\n" +
+        `  error_text ${textType} NULL,\n` +
+        `  correlation_id ${idType} NULL,\n` +
+        `  causation_id ${idType} NULL,\n` +
+        `  aggregate_id ${idType} NULL,\n` +
+        `  lease_owner ${idType} NULL,\n` +
+        "  lease_until BIGINT NULL\n" +
+        ");\n" +
+        `CREATE INDEX IF NOT EXISTS idx_bcp_outbox_due ON ${table} (state, available_at);\n` +
+        `CREATE INDEX IF NOT EXISTS idx_bcp_outbox_lease ON ${table} (state, lease_until);`;
+}
+
+function createEventEnvelope(
+    event: OutboxEventRecord
+): Record<string, unknown> {
+    return {
+        eventId: event.id,
+        type: event.type,
+        payload: event.payload,
+        metadata: event.metadata,
+        correlationId: event.correlationId,
+        causationId: event.causationId,
+        aggregateId: event.aggregateId,
+        createdAt: event.createdAt,
+    };
+}
+
+function recoverMemoryStale(
+    events: Map<string, OutboxEventRecord>,
+    now: number,
+    limit: number
+): number {
+    const stale =
+        Array.from(events.values())
+            .filter(event =>
+                event.state === "processing" &&
+                event.leaseUntil !== undefined &&
+                event.leaseUntil <= now
+            )
+            .sort((left, right) =>
+                (left.leaseUntil ?? 0) - (right.leaseUntil ?? 0) ||
+                left.id.localeCompare(right.id)
+            )
+            .slice(0, limit);
+    for (const event of stale) {
+        event.state = "pending";
+        event.processingAt = undefined;
+        clearLease(event);
+    }
+    return stale.length;
+}
+
+async function recoverSqlStale(
+    transaction: TransactionDatabase,
+    driver: DatabaseDriver,
+    tableName: string,
+    now: number
+): Promise<void> {
+    await transaction.execute(
+        `UPDATE ${tableName} SET state = ${bind(driver, 1)}, processing_at = NULL, lease_owner = NULL, lease_until = NULL ` +
+        `WHERE state = ${bind(driver, 2)} AND lease_until IS NOT NULL AND lease_until <= ${bind(driver, 3)}`,
+        ["pending", "processing", now]
+    );
+}
+
+async function conditionalUpdate(
+    database: Pick<BcpDatabase, "query" | "execute">,
+    driver: DatabaseDriver,
+    tableName: string,
+    id: string,
+    ownerId: string,
+    setClause: string,
+    setValues: unknown[]
+): Promise<boolean> {
+    const idIndex = setValues.length + 1;
+    const stateIndex = idIndex + 1;
+    const ownerIndex = idIndex + 2;
+    await database.execute(
+        `UPDATE ${tableName} SET ${setClause} ` +
+        `WHERE id = ${bind(driver, idIndex)} AND state = ${bind(driver, stateIndex)} AND lease_owner = ${bind(driver, ownerIndex)}`,
+        [...setValues, id, "processing", ownerId]
+    );
+    const rows =
+        await database.query<Record<string, unknown>[]>(
+            `SELECT state, lease_owner FROM ${tableName} WHERE id = ${bind(driver, 1)}`,
+            [id]
+        );
+    const row = rows[0];
+    return Boolean(
+        row &&
+        row.lease_owner !== ownerId &&
+        row.state !== "processing"
+    );
+}
+
+function rowToEvent(
+    row: Record<string, unknown>
+): OutboxEventRecord {
+    return {
+        id: String(row.id ?? ""),
+        type: String(row.event_type ?? ""),
+        payload: parseJson(row.payload_json),
+        metadata: parseMetadata(row.metadata_json),
+        state: normalizeState(row.state),
+        attempts: Number(row.attempts ?? 0),
+        maxAttempts: Number(row.max_attempts ?? 1),
+        createdAt: Number(row.created_at ?? 0),
+        availableAt: Number(row.available_at ?? 0),
+        processingAt: optionalNumber(row.processing_at),
+        publishedAt: optionalNumber(row.published_at),
+        failedAt: optionalNumber(row.failed_at),
+        error: optionalText(row.error_text),
+        correlationId: optionalText(row.correlation_id),
+        causationId: optionalText(row.causation_id),
+        aggregateId: optionalText(row.aggregate_id),
+        leaseOwner: optionalText(row.lease_owner),
+        leaseUntil: optionalNumber(row.lease_until),
+    };
+}
+
+function calculateStats(
+    events: OutboxEventRecord[]
+): OutboxStats {
+    const stats: OutboxStats = {
+        total: events.length,
+        pending: 0,
+        processing: 0,
+        published: 0,
+        failed: 0,
+    };
+    for (const event of events) {
+        stats[event.state] += 1;
+    }
+    return stats;
+}
+
+function compareEvents(
+    left: OutboxEventRecord,
+    right: OutboxEventRecord
+): number {
+    return left.availableAt - right.availableAt ||
+        left.createdAt - right.createdAt ||
+        left.id.localeCompare(right.id);
+}
+
+function clearLease(
+    event: OutboxEventRecord
+): void {
+    event.leaseOwner = undefined;
+    event.leaseUntil = undefined;
+}
+
+function cloneEvent<TPayload>(
+    event: OutboxEventRecord<TPayload>
+): OutboxEventRecord<TPayload> {
+    return {
+        ...event,
+        metadata: {
+            ...event.metadata,
+        },
+    };
+}
+
+function normalizeState(
+    value: unknown
+): OutboxEventState {
+    if (
+        value === "pending" ||
+        value === "processing" ||
+        value === "published" ||
+        value === "failed"
+    ) {
+        return value;
+    }
+    throw new Error(
+        `BCP Events: invalid outbox state "${String(value)}".`
+    );
+}
+
+function normalizeDriver(
+    driver: DatabaseDriver
+): DatabaseDriver {
+    if (
+        driver === "mysql" ||
+        driver === "postgresql" ||
+        driver === "sqlite"
+    ) {
+        return driver;
+    }
+    throw new TypeError(
+        `BCP Events: unsupported database driver "${String(driver)}".`
+    );
+}
+
+function normalizeIdentifier(
+    value: string
+): string {
+    const identifier =
+        String(value ?? "").trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+        throw new TypeError(
+            "BCP Events: table name must be a simple SQL identifier."
+        );
+    }
+    return identifier;
+}
+
+function placeholders(
+    driver: DatabaseDriver,
+    count: number
+): string {
+    return Array.from(
+        { length: count },
+        (_, index) => bind(driver, index + 1)
+    ).join(", ");
+}
+
+function bind(
+    driver: DatabaseDriver,
+    index: number
+): string {
+    return driver === "postgresql"
+        ? `$${index}`
+        : "?";
+}
+
+function assertTransaction(
+    transaction: TransactionDatabase
+): void {
+    if (
+        !transaction ||
+        typeof transaction.query !== "function" ||
+        typeof transaction.execute !== "function"
+    ) {
+        throw new TypeError(
+            "BCP Events: publish requires a BCP transaction database."
+        );
+    }
+}
+
+function normalizeText(
+    value: unknown,
+    field: string
+): string {
+    const text = String(value ?? "").trim();
+    if (!text) {
+        throw new TypeError(
+            `BCP Events: ${field} must be a non-empty string.`
+        );
+    }
+    return text;
+}
+
+function optionalText(
+    value: unknown
+): string | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const text = String(value).trim();
+    return text || undefined;
+}
+
+function optionalNumber(
+    value: unknown
+): number | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const number = Number(value);
+    return Number.isFinite(number)
+        ? number
+        : undefined;
+}
+
+function positiveInteger(
+    value: number,
+    field: string
+): number {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new TypeError(
+            `BCP Events: ${field} must be a positive integer.`
+        );
+    }
+    return value;
+}
+
+function nonNegativeNumber(
+    value: number,
+    field: string
+): number {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError(
+            `BCP Events: ${field} must be a non-negative finite number.`
+        );
+    }
+    return Math.floor(value);
+}
+
+function finiteNumber(
+    value: number,
+    field: string
+): number {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(
+            `BCP Events: ${field} must be a finite number.`
+        );
+    }
+    return value;
+}
+
+function resolveRetryDelay(
+    retryDelay: OutboxRetryDelay,
+    attempt: number
+): number {
+    const delay =
+        typeof retryDelay === "function"
+            ? retryDelay(attempt)
+            : retryDelay;
+    return nonNegativeNumber(
+        delay,
+        "retry delay"
+    );
+}
+
+function parseJson(
+    value: unknown
+): unknown {
+    if (typeof value !== "string") {
+        return value;
+    }
+    return JSON.parse(value);
+}
+
+function parseMetadata(
+    value: unknown
+): Record<string, unknown> {
+    const parsed = parseJson(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed as Record<string, unknown>
+        : {};
+}
+
+function formatError(
+    error: unknown
+): string {
+    if (error instanceof Error) {
+        return error.message || error.name;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    try {
+        return JSON.stringify(error) ?? String(error);
+    } catch {
+        return String(error);
+    }
+}
+
+function sleep(
+    delayMs: number,
+    signal: AbortSignal
+): Promise<void> {
+    if (delayMs === 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, delayMs);
+        const abort = () => {
+            clearTimeout(timer);
+            const error = new Error("Outbox dispatcher stopped.");
+            error.name = "AbortError";
+            reject(error);
+        };
+        if (signal.aborted) {
+            abort();
+            return;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+
+function isAbortError(
+    error: unknown
+): boolean {
+    return error instanceof Error &&
+        error.name === "AbortError";
+}