@capybara-hq/kernel 0.1.0-rc.22 → 0.1.0-rc.24

package/dist/infra/outbox/outbox.dispatcher.js

@@ -0,0 +1,310 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { sql } from "kysely";
+import { KernelDb } from "../database/kernel-db.js";
+import { TransactionHost } from "../database/transaction-host.js";
+import { Transactional } from "../database/transactional.decorator.js";
+import { QUEUE_JOB_DEFAULTS } from "../queue/queue.module.js";
+import { KERNEL_QUEUES } from "../queue/queue-names.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+import { outboxJobOptions } from "./registry.js";
+/**
+ * Retry schedule of a row whose add failed (spec §3.4): the next attempt waits
+ * `min(capMs, baseMs * 2^attempts)`, and the row is dead (kept, never retried) at `maxAttempts`.
+ */
+export const OUTBOX_BACKOFF = { baseMs: 1000, capMs: 300_000, maxAttempts: 20 };
+/**
+ * How long the queue adds of one claim pass may take in all: the claim transaction holds its rows'
+ * locks and a pool connection for at most about this long.
+ */
+export const OUTBOX_REDIS_TIMEOUT_MS = 2000;
+/**
+ * Most fast-path passes running at once in one process; more are skipped and left to the relay,
+ * so a slow Redis cannot take the whole pool (a local resource bound, no shared state).
+ */
+export const OUTBOX_FAST_PATH_CONCURRENCY = 4;
+/**
+ * Test seam (`KernelOverride`): returns true to make the adds to the given queue fail (a Redis
+ * outage) without calling Redis. The kernel never provides it; the dispatcher defaults to "never
+ * fails".
+ */
+export const OUTBOX_DISPATCH_FAILS = Symbol("OUTBOX_DISPATCH_FAILS");
+/** Longest `last_error` kept on a row. */
+const MAX_ERROR_LENGTH = 2000;
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+const NOT_READY = Symbol("NOT_READY");
+/**
+ * Whether the queue's Redis connection is ready now, without waiting: the backend's client
+ * promise only settles once connected, so a pending one counts as not ready.
+ */
+async function connectionReady(queue) {
+    try {
+        // an already settled client promise wins the race (its callback is queued first)
+        const client = await Promise.race([queue.getBackend().client, Promise.resolve(NOT_READY)]);
+        return client !== NOT_READY && client.status === "ready";
+    }
+    catch {
+        return false;
+    }
+}
+/** Rejects when `p` takes longer than `ms`; a late rejection of `p` is swallowed. */
+async function withTimeout(p, ms, what) {
+    p.catch(() => { });
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms} ms`)), ms);
+    });
+    try {
+        return await Promise.race([p, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Delivers outbox rows to BullMQ (transactional outbox spec §3.3, §3.4). A pass claims rows
+ * `FOR UPDATE SKIP LOCKED` (so concurrent passes never take the same row), adds their jobs per
+ * queue with `addBulk` (the queue defaults overlaid by the registry's options of the job name, the
+ * row's job id, a future `run_at` as the remaining `delay`), and deletes
+ * the delivered rows in the same short transaction. A crash after the add and before the commit
+ * leaves the rows; the next pass adds again and BullMQ ignores the existing job id. A queue whose
+ * add fails keeps its rows, and a second short update records the attempt with exponential
+ * backoff, setting `dead_at` at the last one.
+ *
+ * The fast path never queues behind an outage: it skips the pass (the relay delivers the rows) when
+ * a queue's Redis connection is not ready or {@link OUTBOX_FAST_PATH_CONCURRENCY} passes already
+ * run. Within a pass, the first failed queue fails the queues after it without trying them.
+ *
+ * The queue handles are the instances the queues' owner modules registered (one per queue, no
+ * connection of the outbox's own), resolved by token at use time. A queue whose owner this
+ * process's roles do not load is not reachable here: no pass claims its rows, which stay for a
+ * process that has it.
+ */
+let OutboxDispatcher = class OutboxDispatcher {
+    txHost;
+    db;
+    log;
+    moduleRef;
+    dispatchFails;
+    /** The owners' queue instances resolved so far (a per-process handle cache). */
+    queues = new Map();
+    /** Fast-path passes running in this process (bounded by OUTBOX_FAST_PATH_CONCURRENCY). */
+    fastPaths = 0;
+    constructor(txHost, db, log, moduleRef, dispatchFails = () => false) {
+        this.txHost = txHost;
+        this.db = db;
+        this.log = log;
+        this.moduleRef = moduleRef;
+        this.dispatchFails = dispatchFails;
+    }
+    /** The queue instance its owner module registered, or undefined when no loaded module has it. */
+    queue(name) {
+        const known = this.queues.get(name);
+        if (known)
+            return known;
+        let queue;
+        try {
+            queue = this.moduleRef.get(getQueueToken(name), { strict: false });
+        }
+        catch {
+            return undefined;
+        }
+        if (queue)
+            this.queues.set(name, queue);
+        return queue;
+    }
+    /** The kernel queues this process can add to, with their handles. */
+    reachable() {
+        const found = [];
+        for (const name of KERNEL_QUEUES) {
+            const queue = this.queue(name);
+            if (queue)
+                found.push([name, queue]);
+        }
+        return found;
+    }
+    /**
+     * The fast path: delivers the given rows (a committed transaction's own) right away. Never
+     * throws: whatever it does not deliver stays for the relay, and a failure is logged.
+     */
+    async dispatchOwn(ids) {
+        if (ids.length === 0)
+            return;
+        if (this.fastPaths >= OUTBOX_FAST_PATH_CONCURRENCY) {
+            this.log.debug("outbox fast path busy; the relay delivers the rows", { rows: ids.length });
+            return;
+        }
+        this.fastPaths++;
+        try {
+            if (!(await this.redisReady())) {
+                this.log.debug("outbox fast path: Redis not ready; the relay delivers the rows", {
+                    rows: ids.length,
+                });
+                return;
+            }
+            await this.dispatch({ ids });
+        }
+        catch (e) {
+            this.log.error("outbox fast path failed; the relay delivers the rows", {
+                rows: ids.length,
+                error: errMsg(e),
+            });
+        }
+        finally {
+            this.fastPaths--;
+        }
+    }
+    /**
+     * Every reachable queue's connection is ready (they reach the same Redis; the fast path does not
+     * read its rows' queues before claiming them).
+     */
+    async redisReady() {
+        const ready = await Promise.all(this.reachable().map(([, q]) => connectionReady(q)));
+        return ready.every(Boolean);
+    }
+    /**
+     * The relay: delivers up to `limit` due rows (not dead, `next_attempt_at` reached), oldest
+     * first.
+     */
+    dispatchDue(limit) {
+        return this.dispatch({ limit });
+    }
+    async dispatch(claim) {
+        const { sent, failed } = await this.claimAndSend(claim);
+        let dead = 0;
+        for (const group of failed)
+            dead += await this.recordFailure(group);
+        return { sent, failed: failed.reduce((n, g) => n + g.ids.length, 0), dead };
+    }
+    /**
+     * One claim transaction: locks the rows (skipping rows another pass holds), adds their jobs and
+     * deletes the delivered rows. The only Redis calls made while a PG transaction is open in the
+     * kernel (spec §3.3): the locks held are outbox rows only, and the pass's adds together are
+     * bounded by {@link OUTBOX_REDIS_TIMEOUT_MS}.
+     */
+    async claimAndSend(claim) {
+        const queues = new Map(this.reachable());
+        if (queues.size === 0)
+            return { sent: 0, failed: [] };
+        // rows of a queue this process cannot reach are left for a process that can
+        let query = this.db
+            .selectFrom("outbox")
+            .select(["id", "queue", "job_name", "job_id", "data", "run_at"])
+            .where("dead_at", "is", null)
+            .where("queue", "in", [...queues.keys()]);
+        query =
+            "ids" in claim
+                ? query.where("id", "in", [...claim.ids])
+                : query.where("next_attempt_at", "<=", sql `now()`).limit(claim.limit);
+        const rows = await query.orderBy("id").forUpdate().skipLocked().execute();
+        if (rows.length === 0)
+            return { sent: 0, failed: [] };
+        const byQueue = new Map();
+        for (const row of rows) {
+            const group = byQueue.get(row.queue);
+            if (group)
+                group.push(row);
+            else
+                byQueue.set(row.queue, [row]);
+        }
+        const now = Date.now();
+        const deadline = now + OUTBOX_REDIS_TIMEOUT_MS;
+        const delivered = [];
+        const failed = [];
+        // after the first failure the queues left are failed without a try: Redis is likely down
+        let firstError;
+        for (const [name, group] of byQueue) {
+            const ids = group.map((r) => r.id);
+            if (firstError !== undefined) {
+                failed.push({
+                    ids,
+                    error: `not tried after an earlier queue failed: ${firstError}`.slice(0, MAX_ERROR_LENGTH),
+                });
+                continue;
+            }
+            try {
+                if (this.dispatchFails(name))
+                    throw new Error("outbox dispatch failure (test seam)");
+                const queue = queues.get(name);
+                if (!queue)
+                    throw new Error(`"${name}" is not a kernel queue`);
+                const left = deadline - Date.now();
+                if (left <= 0)
+                    throw new Error(`no time left of the pass's ${OUTBOX_REDIS_TIMEOUT_MS} ms`);
+                await withTimeout(queue.addBulk(group.map((r) => ({
+                    name: r.job_name,
+                    data: r.data,
+                    opts: {
+                        ...QUEUE_JOB_DEFAULTS,
+                        ...outboxJobOptions(r.job_name),
+                        jobId: r.job_id,
+                        delay: r.run_at ? Math.max(0, r.run_at.getTime() - now) : 0,
+                    },
+                }))), left, `addBulk to ${name}`);
+                delivered.push(...ids);
+            }
+            catch (e) {
+                firstError = errMsg(e);
+                failed.push({ ids, error: firstError.slice(0, MAX_ERROR_LENGTH) });
+            }
+        }
+        if (delivered.length > 0)
+            await this.db.deleteFrom("outbox").where("id", "in", delivered).execute();
+        return { sent: delivered.length, failed };
+    }
+    /**
+     * Records a failed add on its rows (after the claim transaction, so the attempt is kept whatever
+     * that transaction did): one more attempt, the error, the next attempt by {@link OUTBOX_BACKOFF},
+     * and `dead_at` at the last attempt. Returns how many rows it made dead.
+     */
+    async recordFailure(group) {
+        const { baseMs, capMs, maxAttempts } = OUTBOX_BACKOFF;
+        // the right-hand sides read the row before the update: the first failure waits baseMs
+        const backoffMs = sql `least(${capMs}::float8, ${baseMs}::float8 * power(2, attempts))`;
+        const updated = await this.db
+            .updateTable("outbox")
+            .set({
+            attempts: sql `attempts + 1`,
+            last_error: group.error,
+            next_attempt_at: sql `now() + ${backoffMs} * interval '1 millisecond'`,
+            dead_at: sql `case when attempts + 1 >= ${maxAttempts}::int then now() end`,
+        })
+            .where("id", "in", group.ids)
+            .where("dead_at", "is", null)
+            .returning(["dead_at"])
+            .execute();
+        const dead = updated.filter((r) => r.dead_at !== null).length;
+        this.log.warn("outbox delivery failed; retrying with backoff", {
+            rows: group.ids.length,
+            dead,
+            error: group.error,
+        });
+        if (dead > 0) {
+            this.log.error("outbox rows dead after the last attempt", { rows: dead, error: group.error });
+        }
+        return dead;
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], OutboxDispatcher.prototype, "claimAndSend", null);
+OutboxDispatcher = __decorate([
+    Injectable(),
+    __param(0, Inject(TransactionHost)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(ModuleRef)),
+    __param(4, Optional()),
+    __param(4, Inject(OUTBOX_DISPATCH_FAILS))
+], OutboxDispatcher);
+export { OutboxDispatcher };

package/dist/infra/outbox/outbox.module.d.ts

@@ -0,0 +1,24 @@
+import { OutboxDispatcher } from "./outbox.dispatcher.js";
+import { type OutboxFastPath } from "./outbox.service.js";
+/**
+ * Test seam (`KernelOverride`): receives each detached fast-path pass, so a test can await what a
+ * request started after its commit (the kernel never provides it).
+ */
+export declare const OUTBOX_FAST_PATH_SETTLED: unique symbol;
+/**
+ * The fast path (spec §3.3): starts the dispatcher on a committed transaction's rows and returns
+ * at once, so the commit's caller never waits on Redis (R9). `dispatchOwn` never throws; what it
+ * does not deliver stays for the relay.
+ */
+export declare const outboxFastPath: (dispatcher: Pick<OutboxDispatcher, "dispatchOwn">, settled?: (pass: Promise<void>) => void) => OutboxFastPath;
+/**
+ * Global: `OutboxService` (owed work written in the caller's transaction, transactional outbox
+ * spec §3.2), the `OutboxDispatcher` that delivers the rows (the relay drives it too) and the fast
+ * path `add` hands each committed transaction's rows to.
+ *
+ * It registers no queue: the dispatcher adds through the instances the queues' owner modules
+ * registered (one instance and connection per queue, as everywhere in the kernel), resolved at use
+ * time, and leaves the rows of a queue whose owner this process does not load to one that does.
+ */
+export declare class OutboxModule {
+}

package/dist/infra/outbox/outbox.module.js

@@ -0,0 +1,50 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Global, Module } from "@nestjs/common";
+import { OutboxDispatcher } from "./outbox.dispatcher.js";
+import { OUTBOX_FAST_PATH, OutboxService } from "./outbox.service.js";
+/**
+ * Test seam (`KernelOverride`): receives each detached fast-path pass, so a test can await what a
+ * request started after its commit (the kernel never provides it).
+ */
+export const OUTBOX_FAST_PATH_SETTLED = Symbol("OUTBOX_FAST_PATH_SETTLED");
+/**
+ * The fast path (spec §3.3): starts the dispatcher on a committed transaction's rows and returns
+ * at once, so the commit's caller never waits on Redis (R9). `dispatchOwn` never throws; what it
+ * does not deliver stays for the relay.
+ */
+export const outboxFastPath = (dispatcher, settled) => async (ids) => {
+    const pass = dispatcher.dispatchOwn(ids);
+    settled?.(pass);
+};
+/**
+ * Global: `OutboxService` (owed work written in the caller's transaction, transactional outbox
+ * spec §3.2), the `OutboxDispatcher` that delivers the rows (the relay drives it too) and the fast
+ * path `add` hands each committed transaction's rows to.
+ *
+ * It registers no queue: the dispatcher adds through the instances the queues' owner modules
+ * registered (one instance and connection per queue, as everywhere in the kernel), resolved at use
+ * time, and leaves the rows of a queue whose owner this process does not load to one that does.
+ */
+let OutboxModule = class OutboxModule {
+};
+OutboxModule = __decorate([
+    Global(),
+    Module({
+        providers: [
+            OutboxService,
+            OutboxDispatcher,
+            {
+                provide: OUTBOX_FAST_PATH,
+                inject: [OutboxDispatcher, { token: OUTBOX_FAST_PATH_SETTLED, optional: true }],
+                useFactory: (dispatcher, settled) => outboxFastPath(dispatcher, settled ?? undefined),
+            },
+        ],
+        exports: [OutboxService, OutboxDispatcher, OUTBOX_FAST_PATH],
+    })
+], OutboxModule);
+export { OutboxModule };

package/dist/infra/outbox/outbox.relay.d.ts

@@ -0,0 +1,31 @@
+import type { KernelLogger } from "../../log.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { LockService } from "../lock/lock.service.js";
+import { OutboxDispatcher } from "./outbox.dispatcher.js";
+/** The relay's `@LockedInterval` job name (its run lock key is the default `cron:outbox-relay`). */
+export declare const OUTBOX_RELAY_JOB = "outbox-relay";
+/** The relay's period: a fixed constant, not a config field. */
+export declare const OUTBOX_RELAY_PERIOD_MS = 2000;
+/** Rows one claim pass of the relay takes. */
+export declare const OUTBOX_RELAY_BATCH = 500;
+/** Most claim passes in one tick; what is left waits for the next tick. */
+export declare const OUTBOX_RELAY_MAX_ROUNDS = 10;
+/**
+ * The outbox relay (transactional outbox spec §3.3), on the worker role only: once per tick across
+ * replicas it delivers the due rows the fast path did not (a failed or skipped pass, a process that
+ * died after the commit, a retry whose backoff ran out). A tick runs passes of
+ * {@link OUTBOX_RELAY_BATCH} rows until one handles fewer (the backlog is drained) or
+ * {@link OUTBOX_RELAY_MAX_ROUNDS} have run. It also stops early when the run is aborted, and after
+ * a pass that delivered nothing but failed rows (Redis trouble: the next tick tries again, rather
+ * than spinning more passes that each hold a pool connection).
+ */
+export declare class OutboxRelay {
+    private readonly dispatcher;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(dispatcher: Pick<OutboxDispatcher, "dispatchDue">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    relay(signal?: AbortSignal): Promise<void>;
+    /** One tick's passes (the body of {@link relay}); returns the rows delivered. */
+    relayOnce(signal?: AbortSignal): Promise<number>;
+}

package/dist/infra/outbox/outbox.relay.js

@@ -0,0 +1,76 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { LockService } from "../lock/lock.service.js";
+import { LockedInterval } from "../schedule/locked-interval.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+import { OutboxDispatcher } from "./outbox.dispatcher.js";
+/** The relay's `@LockedInterval` job name (its run lock key is the default `cron:outbox-relay`). */
+export const OUTBOX_RELAY_JOB = "outbox-relay";
+/** The relay's period: a fixed constant, not a config field. */
+export const OUTBOX_RELAY_PERIOD_MS = 2000;
+/** Rows one claim pass of the relay takes. */
+export const OUTBOX_RELAY_BATCH = 500;
+/** Most claim passes in one tick; what is left waits for the next tick. */
+export const OUTBOX_RELAY_MAX_ROUNDS = 10;
+/**
+ * The outbox relay (transactional outbox spec §3.3), on the worker role only: once per tick across
+ * replicas it delivers the due rows the fast path did not (a failed or skipped pass, a process that
+ * died after the commit, a retry whose backoff ran out). A tick runs passes of
+ * {@link OUTBOX_RELAY_BATCH} rows until one handles fewer (the backlog is drained) or
+ * {@link OUTBOX_RELAY_MAX_ROUNDS} have run. It also stops early when the run is aborted, and after
+ * a pass that delivered nothing but failed rows (Redis trouble: the next tick tries again, rather
+ * than spinning more passes that each hold a pool connection).
+ */
+let OutboxRelay = class OutboxRelay {
+    dispatcher;
+    config;
+    lockService;
+    log;
+    constructor(dispatcher, config, lockService, log) {
+        this.dispatcher = dispatcher;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async relay(signal) {
+        await this.relayOnce(signal);
+    }
+    /** One tick's passes (the body of {@link relay}); returns the rows delivered. */
+    async relayOnce(signal) {
+        let sent = 0;
+        for (let round = 0; round < OUTBOX_RELAY_MAX_ROUNDS; round++) {
+            if (signal?.aborted)
+                break;
+            const r = await this.dispatcher.dispatchDue(OUTBOX_RELAY_BATCH);
+            sent += r.sent;
+            // rows handled: `dead` is a part of `failed`, not counted again
+            if (r.sent + r.failed < OUTBOX_RELAY_BATCH)
+                break;
+            if (r.sent === 0 && r.failed > 0)
+                break;
+        }
+        if (sent > 0)
+            this.log.debug("outbox relay delivered rows", { rows: sent });
+        return sent;
+    }
+};
+__decorate([
+    LockedInterval(OUTBOX_RELAY_JOB, () => OUTBOX_RELAY_PERIOD_MS)
+], OutboxRelay.prototype, "relay", null);
+OutboxRelay = __decorate([
+    Injectable(),
+    __param(0, Inject(OutboxDispatcher)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(LockService)),
+    __param(3, Inject(KERNEL_LOGGER))
+], OutboxRelay);
+export { OutboxRelay };

package/dist/infra/outbox/outbox.service.d.ts

@@ -0,0 +1,51 @@
+import type { KernelLogger } from "../../log.js";
+import { KernelDb } from "../database/kernel-db.js";
+import { TransactionHost } from "../database/transaction-host.js";
+import type { KernelQueueName } from "../queue/queue-names.js";
+import type { OutboxJobName } from "./registry.js";
+/** A BullMQ job owed by the caller's transaction (transactional outbox spec §5). */
+export interface OutboxJob<T> {
+    /** One of the kernel queues. */
+    queue: KernelQueueName;
+    /** A registered job name ({@link OutboxJobName}). */
+    name: OutboxJobName;
+    /** Deterministic, no `:`; one pending (not dead) row per (queue, jobId). */
+    jobId: string;
+    /** JSON data: stored as jsonb, so what JSON cannot carry (undefined, Date objects) is lost. */
+    data: T;
+    /** Delay target: delivered as a BullMQ `delay` computed at dispatch. */
+    runAt?: Date;
+    /** The org the work belongs to (its deletion removes the pending row); absent for platform work. */
+    orgId?: string;
+}
+/** Delivers the given outbox rows right after their transaction committed (the fast path, §3.3). */
+export type OutboxFastPath = (ids: readonly string[]) => Promise<void>;
+/** The fast path `add` hands each committed transaction's rows to (`OutboxModule` provides it). */
+export declare const OUTBOX_FAST_PATH: unique symbol;
+/**
+ * Test seam (`KernelOverride`): `true` makes a reused job id with different data throw instead of
+ * logging an error (spec §4, designer's call: "throws in tests, logs in production").
+ */
+export declare const OUTBOX_STRICT_CONFLICTS: unique symbol;
+/**
+ * Writes owed work as a row in the caller's transaction (spec §3.2): the row commits or rolls back
+ * with the business write, and after the commit the fast path delivers it when it is due now (a
+ * row with a future `runAt` waits for the relay, spec §3.3).
+ */
+export declare class OutboxService {
+    readonly txHost: TransactionHost;
+    private readonly db;
+    private readonly log;
+    private readonly fastPath;
+    private readonly strictConflicts;
+    constructor(txHost: TransactionHost, db: KernelDb, log: KernelLogger, fastPath: OutboxFastPath, strictConflicts?: boolean);
+    /**
+     * Adds the job to the outbox in the transaction in context (throws outside one). Returns true when
+     * it inserted a row, false when the same (queue, jobId) is already owed (a no-op; a dead row is
+     * not owed). A conflict whose stored data differs is a bug in the job id: it throws under strict
+     * conflicts, else logs an error. Undefined data is stored as JSON null.
+     */
+    add<T>(job: OutboxJob<T>): Promise<boolean>;
+    /** Collects `id` for its transaction; the first id registers the transaction's one hint. */
+    private deliverAfterCommit;
+}

package/dist/infra/outbox/outbox.service.js

@@ -0,0 +1,131 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { isDeepStrictEqual } from "node:util";
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { afterCommit } from "../database/after-commit.js";
+import { KernelDb } from "../database/kernel-db.js";
+import { currentStore, TransactionHost } from "../database/transaction-host.js";
+import { Transactional } from "../database/transactional.decorator.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+/** The fast path `add` hands each committed transaction's rows to (`OutboxModule` provides it). */
+export const OUTBOX_FAST_PATH = Symbol("OUTBOX_FAST_PATH");
+/**
+ * Test seam (`KernelOverride`): `true` makes a reused job id with different data throw instead of
+ * logging an error (spec §4, designer's call: "throws in tests, logs in production").
+ */
+export const OUTBOX_STRICT_CONFLICTS = Symbol("OUTBOX_STRICT_CONFLICTS");
+/**
+ * The ids each open transaction inserted, keyed by its transaction store: lives only as long as
+ * that transaction (a WeakMap entry, no state shared across requests).
+ */
+const pendingIds = new WeakMap();
+/**
+ * Writes owed work as a row in the caller's transaction (spec §3.2): the row commits or rolls back
+ * with the business write, and after the commit the fast path delivers it when it is due now (a
+ * row with a future `runAt` waits for the relay, spec §3.3).
+ */
+let OutboxService = class OutboxService {
+    txHost;
+    db;
+    log;
+    fastPath;
+    strictConflicts;
+    constructor(txHost, db, log, fastPath, strictConflicts = false) {
+        this.txHost = txHost;
+        this.db = db;
+        this.log = log;
+        this.fastPath = fastPath;
+        this.strictConflicts = strictConflicts;
+    }
+    /**
+     * Adds the job to the outbox in the transaction in context (throws outside one). Returns true when
+     * it inserted a row, false when the same (queue, jobId) is already owed (a no-op; a dead row is
+     * not owed). A conflict whose stored data differs is a bug in the job id: it throws under strict
+     * conflicts, else logs an error. Undefined data is stored as JSON null.
+     */
+    async add(job) {
+        if (job.jobId.includes(":")) {
+            throw new Error(`outbox job id "${job.jobId}" must not contain ":" (BullMQ uses it as its key separator); ` +
+                'join the id\'s parts with "-" instead');
+        }
+        const json = JSON.stringify(job.data ?? null);
+        const row = await this.db
+            .insertInto("outbox")
+            .values({
+            queue: job.queue,
+            job_name: job.name,
+            job_id: job.jobId,
+            data: json,
+            run_at: job.runAt ?? null,
+            org_id: job.orgId ?? null,
+        })
+            .onConflict((oc) => oc.columns(["queue", "job_id"]).where("dead_at", "is", null).doNothing())
+            .returning("id")
+            .executeTakeFirst();
+        if (row) {
+            // only a job due now goes through the fast path (ruling R20): a delayed one (a backstop, a
+            // timeout) is claimed by the relay within its next tick and added with its remaining delay,
+            // so the commit's caller spends no claim transaction on work due in seconds or hours
+            if (job.runAt === undefined || job.runAt.getTime() <= Date.now()) {
+                this.deliverAfterCommit(row.id);
+            }
+            return true;
+        }
+        const stored = await this.db
+            .selectFrom("outbox")
+            .select(["job_name", "data"])
+            .where("queue", "=", job.queue)
+            .where("job_id", "=", job.jobId)
+            .where("dead_at", "is", null)
+            .executeTakeFirst();
+        // no row: the owed one was delivered (and deleted) since the conflict; BullMQ dedupes the id
+        if (stored && !isDeepStrictEqual(stored.data, JSON.parse(json))) {
+            const msg = "outbox job id reused with different data";
+            const fields = {
+                queue: job.queue,
+                jobId: job.jobId,
+                job: job.name,
+                owedJob: stored.job_name,
+            };
+            if (this.strictConflicts)
+                throw new Error(`${msg}: ${JSON.stringify(fields)}`);
+            this.log.error(msg, fields);
+        }
+        return false;
+    }
+    /** Collects `id` for its transaction; the first id registers the transaction's one hint. */
+    deliverAfterCommit(id) {
+        // `mandatory` guarantees a live store here
+        const store = currentStore();
+        if (!store)
+            throw new Error("outbox: no transaction in context");
+        const ids = pendingIds.get(store);
+        if (ids) {
+            ids.push(id);
+            return;
+        }
+        const first = [id];
+        pendingIds.set(store, first);
+        afterCommit(() => this.fastPath(first));
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], OutboxService.prototype, "add", null);
+OutboxService = __decorate([
+    Injectable(),
+    __param(0, Inject(TransactionHost)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(OUTBOX_FAST_PATH)),
+    __param(4, Optional()),
+    __param(4, Inject(OUTBOX_STRICT_CONFLICTS))
+], OutboxService);
+export { OutboxService };