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

package/dist/index.d.ts

@@ -70,6 +70,7 @@ export { ROUTE_SCHEMAS, type RouteSchemas } from "./platform/route-schemas.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export type { AgentLoop, LoopContext, LoopOutcome } from "./runtime/loop.js";
 export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
+export { type OrphanCandidate, queuedRunsWithoutJob } from "./runtime/run-orphan-check.job.js";
 export { runJobId } from "./runtime/run-queue.js";
 export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, type SandboxUseInfo, } from "./sandbox/sandbox.service.js";

package/dist/index.js

@@ -68,6 +68,7 @@ export { PlatformOperations } from "./platform/registry.js";
 export { ROUTE_SCHEMAS } from "./platform/route-schemas.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
+export { queuedRunsWithoutJob } from "./runtime/run-orphan-check.job.js";
 export { runJobId } from "./runtime/run-queue.js";
 export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, } from "./sandbox/sandbox.service.js";

package/dist/infra/cli/kernel-cli.module.js

@@ -21,6 +21,7 @@ import { KernelEventsModule } from "../events/kernel-events.js";
 import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "../lock/lock.module.js";
 import { LoggingModule } from "../logging/logging.module.js";
+import { OutboxModule } from "../outbox/outbox.module.js";
 import { QueueModule } from "../queue/queue.module.js";
 import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
 /** How long the CLI's Redis connection may take before a command fails (a publish only warns). */
@@ -110,6 +111,10 @@ let KernelCliModule = KernelCliModule_1 = class KernelCliModule {
                 ConfigModule.forRoot(config, opts.env !== undefined ? { env: opts.env } : {}),
                 GracefulShutdownModule,
                 DatabaseModule.forRoot(),
+                // owed jobs a command's domain writes carry (an extension's embed call owes its usage
+                // report); delivered by the fast path when the command's context has the queue, else by a
+                // worker's relay
+                OutboxModule,
                 // QueueModule's root gives the queues a command's modules register (the catalog's scope
                 // sync and maintenance queues) the configured Redis; without it BullMQ would connect to
                 // its default 127.0.0.1:6379

package/dist/infra/events/kernel-events.d.ts

@@ -23,8 +23,9 @@ export interface KernelEventMap {
     };
     /**
      * A person decided a tool call approval (after the commit, exactly once: only the decision that
-     * changed it from pending). The run's waits resume it and its IM delivery is enqueued; a lost
-     * event is re-derived by the wait sweep (runs waiting on a decided approval are resumed).
+     * changed it from pending). The decision's transaction resumed the run and, for a conversation
+     * with a channel target, owed the IM delivery that updates the card (with its `approval_decided`
+     * append); the event itself is only the decision's announcement.
      */
     "approval.decided": {
         id: string;
@@ -36,8 +37,7 @@ export interface KernelEventMap {
     };
     /**
      * A person answered a tool call's input request, or skipped it with a message (after the commit,
-     * exactly once). Same
-     * consumers and the same re-derivation as `approval.decided`.
+     * exactly once). The same transaction contract as `approval.decided`.
      */
     "question.answered": {
         id: string;
@@ -47,38 +47,20 @@ export interface KernelEventMap {
         /** `skipped`: the run's starter sent a message instead (reply-while-question spec §6.3). */
         outcome: "answered" | "skipped";
     };
-    /**
-     * EventAppended: a conversation's event log advanced to `toSeq` (after the commit, from
-     * `EventLog.notify`, right after the bus publish). The channel outbound delivery enqueues a job
-     * for a conversation with an IM target; a lost event is re-derived by the next append's (and the
-     * finished delivery job re-checks the log for content it has not delivered).
-     */
-    "conversation.event-appended": {
-        conversationId: string;
-        toSeq: number;
-    };
     /**
      * A run started executing on this replica (its first start, a resume, or a takeover after a
      * stall), after it took the conversation lock and an org quota slot. The channel outbound
-     * enqueues the conversation's IM delivery; a lost event is re-derived by the run's next append.
+     * enqueues the conversation's IM delivery at once (a hint: the run's appends owe it, transactional
+     * outbox spec §8.1).
      */
     "run.started": {
         conversationId: string;
         runId: string;
     };
     /**
-     * A stop of a run waiting on a person was handled (`RunControl.abortWaiting`, whether or not it
-     * still waited): its approval and question cards change, so the channel outbound enqueues the
-     * conversation's IM delivery (re-derived by the next append when lost).
-     */
-    "run.wait-stopped": {
-        conversationId: string;
-        runId: string;
-    };
-    /**
-     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active fork
-     * sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event is
-     * repaired by the wait sweep (fork children of finished runs).
+     * The `run-orphan-check` failed an orphaned run (after the commit): the waits stop its active
+     * fork sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event
+     * is repaired by the `stop-tree` job the run's terminal transaction owed.
      */
     "run.orphaned": {
         runId: string;
@@ -99,14 +81,6 @@ export interface KernelEventMap {
     "background_task.finished": {
         conversationId: string;
     };
-    /**
-     * An extension's `ctx.models.embed` call wrote a `model_usage` row (after the commit, spec B
-     * §5.4). The usage reporter enqueues its `usage.report` delivery; a lost event is re-derived by
-     * the usage sweep (rows whose `reported_at` is still null).
-     */
-    "model_usage.recorded": {
-        id: string;
-    };
 }
 type Handler<K extends keyof KernelEventMap> = (payload: KernelEventMap[K]) => Promise<void> | void;
 /** Typed in-process event emitter; handlers run in order, a failing one is logged and skipped. */

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

@@ -0,0 +1,6 @@
+/**
+ * The outbox relay (`@LockedInterval`), imported only by `WorkerModule`. Its dispatcher comes from
+ * the global `OutboxModule`, which every role has (the fast path runs everywhere).
+ */
+export declare class OutboxRelayModule {
+}

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

@@ -0,0 +1,18 @@
+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 { Module } from "@nestjs/common";
+import { OutboxRelay } from "./outbox.relay.js";
+/**
+ * The outbox relay (`@LockedInterval`), imported only by `WorkerModule`. Its dispatcher comes from
+ * the global `OutboxModule`, which every role has (the fast path runs everywhere).
+ */
+let OutboxRelayModule = class OutboxRelayModule {
+};
+OutboxRelayModule = __decorate([
+    Module({ providers: [OutboxRelay] })
+], OutboxRelayModule);
+export { OutboxRelayModule };

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

@@ -0,0 +1,103 @@
+import { ModuleRef } from "@nestjs/core";
+import type { Queue } from "bullmq";
+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";
+/**
+ * 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 declare const OUTBOX_BACKOFF: {
+    readonly baseMs: 1000;
+    readonly capMs: 300000;
+    readonly 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 declare 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 declare 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 declare const OUTBOX_DISPATCH_FAILS: unique symbol;
+/** What one pass did: rows delivered, rows whose add failed, and of those the rows now dead. */
+export interface DispatchResult {
+    sent: number;
+    failed: number;
+    dead: number;
+}
+/** The queue handle the dispatcher uses: adds, and the connection's state. */
+export type OutboxQueue = Pick<Queue, "addBulk" | "getBackend">;
+/**
+ * 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.
+ */
+export declare class OutboxDispatcher {
+    readonly txHost: TransactionHost;
+    private readonly db;
+    private readonly log;
+    private readonly moduleRef;
+    private readonly dispatchFails;
+    /** The owners' queue instances resolved so far (a per-process handle cache). */
+    private readonly queues;
+    /** Fast-path passes running in this process (bounded by OUTBOX_FAST_PATH_CONCURRENCY). */
+    private fastPaths;
+    constructor(txHost: TransactionHost, db: KernelDb, log: KernelLogger, moduleRef: Pick<ModuleRef, "get">, dispatchFails?: (queue: KernelQueueName) => boolean);
+    /** The queue instance its owner module registered, or undefined when no loaded module has it. */
+    private queue;
+    /** The kernel queues this process can add to, with their handles. */
+    private reachable;
+    /**
+     * 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.
+     */
+    dispatchOwn(ids: readonly string[]): Promise<void>;
+    /**
+     * Every reachable queue's connection is ready (they reach the same Redis; the fast path does not
+     * read its rows' queues before claiming them).
+     */
+    private redisReady;
+    /**
+     * The relay: delivers up to `limit` due rows (not dead, `next_attempt_at` reached), oldest
+     * first.
+     */
+    dispatchDue(limit: number): Promise<DispatchResult>;
+    private dispatch;
+    /**
+     * 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}.
+     */
+    private claimAndSend;
+    /**
+     * 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.
+     */
+    private recordFailure;
+}

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 };