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

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,244 @@
+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 "run-stop": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "stopping a finished 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: {
+                readonly age: number;
+                readonly count: 1000;
+            };
+        };
+    };
+    readonly "sandbox-destroy-for": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "destroying a destroyed device is a no-op";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 30000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: 100;
+        };
+    };
+    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;
+        };
+    };
+    readonly "scope-item": {
+        readonly queue: "cap-kernel-plugin-scope";
+        readonly idempotent: "the sync converges each (item, org) from the scope, switches and installs it reads under the org's lock, and the installer re-checks under the org row lock, so a second run changes nothing";
+        readonly processedIn: "packages/kernel/src/catalog/scope-sync-workers.ts";
+        readonly opts: {
+            readonly attempts: 1;
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "scope-item-backstop": {
+        readonly queue: "cap-kernel-plugin-scope";
+        readonly idempotent: "the sync converges each (item, org) from what it reads, as a scope-item job does, so a run after the immediate job changes nothing";
+        readonly processedIn: "packages/kernel/src/catalog/scope-sync-workers.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 60000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "scope-org": {
+        readonly queue: "cap-kernel-plugin-scope";
+        readonly idempotent: "the sync converges each (item, org) of the org from what it reads, so a second run changes nothing";
+        readonly processedIn: "packages/kernel/src/catalog/scope-sync-workers.ts";
+        readonly opts: {
+            readonly attempts: 1;
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "owned-plugin-cleanup": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "the cleanup takes the extension out only while no live item uses it, and a missing install or a released claim changes nothing";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 3;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "sched-fire": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "a fire acts only on a pending task run, under its row lock; a retried start reuses what the first one made";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 3;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 2000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "sched-settle": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "a check acts only on a task run still pending (claimed for the claimed check, unclaimed for the unfired one), under the task and run row locks, so a run claimed, started, ended or skipped since is left as it is";
+        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 lifecycle: {
+        readonly queue: "cap-kernel-lifecycle";
+        readonly idempotent: "lifecycle handlers must be idempotent (the SDK contract): they delete what the plugin holds for the removed member, agent or org, and deleting it again is a no-op";
+        readonly processedIn: "packages/kernel/src/extensions/lifecycle-hooks.ts";
+        readonly opts: {
+            readonly attempts: 15;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 2000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: {
+                readonly age: number;
+                readonly count: 1000;
+            };
+        };
+    };
+};
+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,234 @@
+/**
+ * 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,
+        },
+    },
+    // `orgs/offboarding.ts` RUN_STOP_JOB: owed by the offboard transaction for each of the departed
+    // member's active runs in the org, under `runStopJobId` (spec §8.1)
+    "run-stop": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "stopping a finished run is a no-op",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // retried while PG or Redis is briefly unavailable; removed once done; a job that failed every
+        // attempt is kept a week (no sweep stops the run after it: the failure must stay visible)
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: { age: 7 * 86_400, count: 1_000 },
+        },
+    },
+    // `sandbox/jobs.ts` SANDBOX_DESTROY_FOR_JOB: owed by the transaction that soft-deletes a device
+    // (its deletion, offboarding), under `deviceDestroyJobId` (spec §8.1)
+    "sandbox-destroy-for": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "destroying a destroyed device is a no-op",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // the options the direct enqueue had: retried while the provider is down
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 30_000 },
+            removeOnComplete: true,
+            removeOnFail: 100,
+        },
+    },
+    // `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,
+        },
+    },
+    // `catalog/scope-sync.ts` SCOPE_ITEM_JOB: owed by every transaction that changes an item's
+    // scope, disabled flag, list, owner or platform version, under `scopeItemJobId` (one per scope
+    // version), and by a sync deferred on a replica that had not loaded the extension yet, under
+    // `scopeRetryJobId` with `runAt` (spec §8.1)
+    "scope-item": {
+        queue: "cap-kernel-plugin-scope",
+        idempotent: "the sync converges each (item, org) from the scope, switches and installs it reads under the org's lock, and the installer re-checks under the org row lock, so a second run changes nothing",
+        processedIn: "packages/kernel/src/catalog/scope-sync-workers.ts",
+        // one attempt (a pair's failure is recorded, not retried); removed once done, so the next
+        // add of the same id is not swallowed
+        opts: { attempts: 1, removeOnComplete: true, removeOnFail: true },
+    },
+    // `catalog/scope-jobs.ts` SCOPE_BACKSTOP_JOB: owed by a confirmation's commit (an import, a
+    // permissions confirm, an org upload's first version) with `runAt` 5 min on, under
+    // `scopeBackstopJobId`, so a crash before the post-deploy add still converges (ruling R24)
+    "scope-item-backstop": {
+        queue: "cap-kernel-plugin-scope",
+        idempotent: "the sync converges each (item, org) from what it reads, as a scope-item job does, so a run after the immediate job changes nothing",
+        processedIn: "packages/kernel/src/catalog/scope-sync-workers.ts",
+        // retried while the item's extension is not enabled on the deployment yet (the job throws):
+        // 1, 2, 4, 8 min; removed once done
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 60_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `catalog/scope-sync.ts` SCOPE_ORG_JOB: owed by an org's creation, under `scopeOrgJobId`
+    "scope-org": {
+        queue: "cap-kernel-plugin-scope",
+        idempotent: "the sync converges each (item, org) of the org from what it reads, so a second run changes nothing",
+        processedIn: "packages/kernel/src/catalog/scope-sync-workers.ts",
+        opts: { attempts: 1, removeOnComplete: true, removeOnFail: true },
+    },
+    // `catalog/job-ids.ts` OWNED_PLUGIN_CLEANUP_JOB: owed by the removal of an org-owned plugin
+    // (and by a confirmation that took out the extension of an item removed meanwhile), under
+    // `ownedPluginCleanupJobId` (spec §8.1)
+    "owned-plugin-cleanup": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "the cleanup takes the extension out only while no live item uses it, and a missing install or a released claim changes nothing",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // a few retries while PG is briefly unavailable; removed once done
+        opts: {
+            attempts: 3,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `schedules/job-ids.ts` SCHED_FIRE_JOB: owed by the transaction that writes a pending task run
+    // (the scan's tick, a person's "run now"), under `schedFireJobId` (spec §8.1)
+    "sched-fire": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "a fire acts only on a pending task run, under its row lock; a retried start reuses what the first one made",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // a few retries while PG is briefly unavailable; removed once done
+        opts: {
+            attempts: 3,
+            backoff: { type: "exponential", delay: 2_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `schedules/job-ids.ts` SCHED_SETTLE_JOB: the claimed check, owed by the fire job's claim (the
+    // transaction that writes `fired_at`) with `runAt` 10 min on, under `schedSettleJobId` (a run
+    // still in flight owes the next check an hour on); the unfired check, owed with the task run
+    // (scan tick, "run now") under `schedSettleUnfiredJobId` (ruling R26)
+    "sched-settle": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "a check acts only on a task run still pending (claimed for the claimed check, unclaimed for the unfired one), under the task and run row locks, so a run claimed, started, ended or skipped since is left as it is",
+        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,
+        },
+    },
+    // `extensions/lifecycle-hooks.ts` LIFECYCLE_JOB: owed by the transaction that removes a member,
+    // deletes an agent or deletes an org, once per subscribing plugin, under `lifecycleJobId`
+    // (memory plugin spec §6.3)
+    lifecycle: {
+        queue: "cap-kernel-lifecycle",
+        idempotent: "lifecycle handlers must be idempotent (the SDK contract): they delete what the plugin holds for the removed member, agent or org, and deleting it again is a no-op",
+        processedIn: "packages/kernel/src/extensions/lifecycle-hooks.ts",
+        // retried while the plugin is not loaded on the replica that took the job (a rolling deploy)
+        // or its handler fails: 15 attempts from 2 s, doubling (about 18 h in all); removed once done;
+        // a job that failed every attempt is kept a week (the failure must stay visible)
+        opts: {
+            attempts: 15,
+            backoff: { type: "exponential", delay: 2_000 },
+            removeOnComplete: true,
+            removeOnFail: { age: 7 * 86_400, count: 1_000 },
+        },
+    },
+};
+/** 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", "cap-kernel-lifecycle"];
+export type KernelQueueName = (typeof KERNEL_QUEUES)[number];

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

@@ -0,0 +1,17 @@
+/**
+ * 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",
+    "cap-kernel-lifecycle",
+];

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`