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

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

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

@@ -0,0 +1,120 @@
+import type { JobsOptions } from "bullmq";
+import type { KernelQueueName } from "../queue/queue-names.js";
+/** What the registry says about one job name added through the outbox (spec §3.5, §5). */
+export interface OutboxJobSpec {
+    /** The kernel queue the job is added to, or the queues when one job name serves several. */
+    queue: KernelQueueName | readonly KernelQueueName[];
+    /** One sentence: why a duplicate delivery of this job is harmless (state check, key, id). */
+    idempotent: string;
+    /** Repo-relative path of the file whose `@Processor` handles the job. */
+    processedIn: string;
+    /**
+     * BullMQ options the dispatcher adds the job with over the queue defaults
+     * (`QUEUE_JOB_DEFAULTS`); the job id and the delay always come from the row.
+     */
+    opts?: Pick<JobsOptions, "attempts" | "backoff" | "priority" | "removeOnComplete" | "removeOnFail">;
+}
+/**
+ * Every job name added through the outbox. The task that introduces a job name adds its entry; a
+ * name without one does not type-check as an `OutboxJobName` (`add` does not check it at runtime).
+ */
+export declare const OUTBOX_JOBS: {
+    readonly run: {
+        readonly queue: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs"];
+        readonly idempotent: "the run worker starts only a run in `queued` state for this job's runId; a finished run's job only repeats the idempotent post-run ensureRun, a waiting run's does nothing";
+        readonly processedIn: "packages/kernel/src/runtime/run-processors.ts";
+        readonly opts: {
+            readonly attempts: 1;
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "ensure-run": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "ensureRun decides from the conversation's state; with nothing unconsumed it is a no-op";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "wait-timeout": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "a timeout acts only on a still-pending wait (a row lock and status check) and a resume starts only a waiting run with nothing else pending";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "stop-tree": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "stopping a stopped run is a no-op";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "deliver-to-parent": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "the delivery's idempotency key is the child run id";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "usage-report": {
+        readonly queue: "cap-kernel-usage-report";
+        readonly idempotent: "handlers are idempotent by eventId (the event's `<conversationId>/<seq>` or the model_usage row id), and the job's `pending` list keeps a retry from reaching plugins already served";
+        readonly processedIn: "packages/kernel/src/runtime/run-processors.ts";
+        readonly opts: {
+            readonly attempts: 6;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 2000;
+            };
+            readonly removeOnComplete: {
+                readonly age: number;
+                readonly count: 100000;
+            };
+            readonly removeOnFail: {
+                readonly age: number;
+                readonly count: 100000;
+            };
+        };
+    };
+    readonly deliver: {
+        readonly queue: "cap-kernel-channels";
+        readonly idempotent: "a delivery resumes from the conversation's delivered seq under a per-conversation lock and sends with idempotency keys, so a second job sends nothing twice";
+        readonly processedIn: "packages/kernel/src/channels/channels.module.ts";
+        readonly opts: {
+            readonly attempts: 8;
+            readonly backoff: {
+                readonly type: "deliver";
+            };
+            readonly priority: 10;
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+};
+export type OutboxJobName = keyof typeof OUTBOX_JOBS;
+/** The registry's BullMQ options of a job name (none for a name it does not list). */
+export declare function outboxJobOptions(name: string): OutboxJobSpec["opts"];

package/dist/infra/outbox/registry.js

@@ -0,0 +1,108 @@
+/**
+ * Every job name added through the outbox. The task that introduces a job name adds its entry; a
+ * name without one does not type-check as an `OutboxJobName` (`add` does not check it at runtime).
+ */
+export const OUTBOX_JOBS = {
+    // `runtime/run-jobs.ts` RUN_JOB: one name on both run queues (a sub-agent's runs go to the
+    // sub-agent queue), under the job ids `runJobId` builds and, for a waiting run's resume
+    // (`RunResume.resumeIn`), `resumeJobId`
+    run: {
+        queue: ["cap-kernel-runs", "cap-kernel-subagent-runs"],
+        idempotent: "the run worker starts only a run in `queued` state for this job's runId; a finished run's job only repeats the idempotent post-run ensureRun, a waiting run's does nothing",
+        processedIn: "packages/kernel/src/runtime/run-processors.ts",
+        // one attempt (the run's own paths handle failures); removed once done, so the next run of the
+        // same trigger can take the id again (the post-run ensureRun, R34)
+        opts: { attempts: 1, removeOnComplete: true, removeOnFail: true },
+    },
+    // `runtime/run-jobs.ts` ENSURE_RUN_JOB: the ensure-run backstop owed with every message, queue
+    // change, background task finish, sub-agent delivery and run end (spec §6), under the job ids
+    // `ensureRunJobId` builds
+    "ensure-run": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "ensureRun decides from the conversation's state; with nothing unconsumed it is a no-op",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // removed once done (the queue defaults keep finished jobs), so a later write under the same
+        // seq (a queue change writes no event of its own) owes a job that is not deduped away
+        opts: { removeOnComplete: true, removeOnFail: true },
+    },
+    // `runtime/waits.ts` WAIT_TIMEOUT_JOB: owed with the suspend that sets a run `waiting`, under
+    // `waitTimeoutJobId`, with `runAt` = the wait's deadline (spec §6 "Resumes and timeouts")
+    "wait-timeout": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "a timeout acts only on a still-pending wait (a row lock and status check) and a resume starts only a waiting run with nothing else pending",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // retried while PG is briefly unavailable; removed once done
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `runtime/subagents/tree-jobs.ts` STOP_TREE_JOB: owed by a run's terminal transaction that
+    // leaves an active fork child (or a person-stopped sub-agent's descendants), under
+    // `stopChildrenJobId`, and by a root's delete, under `stopDeletedTreeJobId` (spec §6)
+    "stop-tree": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "stopping a stopped run is a no-op",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // retried while PG is briefly unavailable; removed once done
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `runtime/subagents/tree-jobs.ts` DELIVER_TO_PARENT_JOB: owed by a sub-agent run's terminal
+    // transaction, under `deliverToParentJobId` (spec §6)
+    "deliver-to-parent": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "the delivery's idempotency key is the child run id",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `runtime/usage-report-jobs.ts` USAGE_REPORT_JOB: owed with the usage it reports (a `usage`
+    // event or a `model_usage` row) while some plugin subscribes, under `usageReportJobId` /
+    // `modelUsageJobId` (spec §8.1)
+    "usage-report": {
+        queue: "cap-kernel-usage-report",
+        idempotent: "handlers are idempotent by eventId (the event's `<conversationId>/<seq>` or the model_usage row id), and the job's `pending` list keeps a retry from reaching plugins already served",
+        processedIn: "packages/kernel/src/runtime/run-processors.ts",
+        // first attempt plus 5 retries, 2 s doubling (F11); finished jobs kept a day so a re-add of the
+        // same id (a crash between the add and the row's delete) dedupes; failed ones a week; both
+        // capped by count (I-2: a long outage of a billing endpoint cannot grow Redis)
+        opts: {
+            attempts: 6,
+            backoff: { type: "exponential", delay: 2_000 },
+            removeOnComplete: { age: 24 * 3600, count: 100_000 },
+            removeOnFail: { age: 7 * 86_400, count: 100_000 },
+        },
+    },
+    // `channels/deliver-job.ts` DELIVER_JOB: owed by every event append of a conversation with a
+    // channel target (a reply, an approval decision, a question answer, a wait stop) and by binding
+    // a conversation to its target, under `deliverJobId` (spec §8.1)
+    deliver: {
+        queue: "cap-kernel-channels",
+        idempotent: "a delivery resumes from the conversation's delivered seq under a per-conversation lock and sends with idempotency keys, so a second job sends nothing twice",
+        processedIn: "packages/kernel/src/channels/channels.module.ts",
+        // the platform's retry-after, else exponential (the processor's `deliver` backoff strategy);
+        // behind inbound jobs; removed once done, so a later append's id is never deduped away
+        opts: {
+            attempts: 8,
+            backoff: { type: "deliver" },
+            priority: 10,
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+};
+/** The registry's BullMQ options of a job name (none for a name it does not list). */
+export function outboxJobOptions(name) {
+    return OUTBOX_JOBS[name]?.opts;
+}

package/dist/infra/queue/queue-names.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The kernel's own BullMQ queues, spelled as literals so infra code (the outbox registry and
+ * dispatcher) names a queue without importing feature modules. `KERNEL_QUEUE_NAMES`
+ * (admin/health.service.ts) lists the same names from the feature constants;
+ * test/infra/queue-names.test.ts keeps the two equal.
+ */
+export declare const KERNEL_QUEUES: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs", "cap-kernel-channels", "cap-kernel-maintenance", "cap-kernel-plugin-scope", "cap-kernel-titles", "cap-kernel-usage-report", "cap-kernel-evals"];
+export type KernelQueueName = (typeof KERNEL_QUEUES)[number];

package/dist/infra/queue/queue-names.js

@@ -0,0 +1,16 @@
+/**
+ * The kernel's own BullMQ queues, spelled as literals so infra code (the outbox registry and
+ * dispatcher) names a queue without importing feature modules. `KERNEL_QUEUE_NAMES`
+ * (admin/health.service.ts) lists the same names from the feature constants;
+ * test/infra/queue-names.test.ts keeps the two equal.
+ */
+export const KERNEL_QUEUES = [
+    "cap-kernel-runs",
+    "cap-kernel-subagent-runs",
+    "cap-kernel-channels",
+    "cap-kernel-maintenance",
+    "cap-kernel-plugin-scope",
+    "cap-kernel-titles",
+    "cap-kernel-usage-report",
+    "cap-kernel-evals",
+];

package/dist/kernel.module.js

@@ -25,6 +25,7 @@ import { databaseCheck, HEALTH_CHECKS, redisCheck } from "./infra/health/health.
 import { GracefulShutdownModule } from "./infra/lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "./infra/lock/lock.module.js";
 import { LoggingModule } from "./infra/logging/logging.module.js";
+import { OutboxModule } from "./infra/outbox/outbox.module.js";
 import { PresenceModule } from "./infra/presence/presence.module.js";
 import { QueueModule } from "./infra/queue/queue.module.js";
 import { RedisModule } from "./infra/redis/redis.module.js";
@@ -95,6 +96,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 ConfigModule.forRoot(config, options.env !== undefined ? { env: options.env } : {}),
                 GracefulShutdownModule,
                 DatabaseModule.forRoot(),
+                // owed jobs written in the caller's transaction (transactional outbox spec §3.2)
+                OutboxModule,
                 RedisModule,
                 LockModule,
                 CacheModule,

package/dist/local-devices/device-policy.service.d.ts

@@ -53,6 +53,10 @@ export declare class DevicePolicyService {
         features: DeviceFeature[];
         policy: DeviceLocalPolicySummary | null;
     } | null>;
+    /** Adds `op` to the machine's pending ops, dropping the expired ones. */
+    private notePending;
+    /** Removes the pending op `opId` from the machine's row. */
+    private dropPending;
     /**
      * Keeps the policy the machine wrote on its row and audits the change (`confirmed`); with no
      * policy (the answer never came) only audits the attempt, unconfirmed. The detail's `isolation`