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

package/dist/catalog/scope-sync.js

@@ -7,8 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { getQueueToken, OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
-import { Inject, Injectable } from "@nestjs/common";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { ApiError } from "../errors.js";
 import { ExtensionLifecycle } from "../extensions/lifecycle.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
@@ -17,12 +16,13 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { LockService } from "../infra/lock/lock.service.js";
-import { runJob } from "../infra/queue/run-job.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { connectorTemplatesOn, templateIdOfPath } from "./component-state.js";
 import { isUsable } from "./ownership.js";
 import { PluginInstaller } from "./plugin-install.js";
 import { wantedOn } from "./scope.js";
+import { oweScopeItem, PLUGIN_SCOPE_QUEUE, SCOPE_BACKSTOP_DELAY, SCOPE_BACKSTOP_DELAY_MS, SCOPE_ITEM_JOB, SCOPE_ORG_JOB, scopeOrgJobId, scopeRetryJobId, } from "./scope-jobs.js";
 import { ScopeNoLongerWanted, ScopeStillWanted } from "./scope-state.js";
 /**
  * The plugin scope sync (plugin and component management spec §5, phase 1): converges every org
@@ -46,30 +46,18 @@ import { ScopeNoLongerWanted, ScopeStillWanted } from "./scope-state.js";
  * super admin's inbox, until a later sync of the pair does not fail) and not retried until the next
  * enqueue. An error outside those steps (a read, the failure write itself) ends the attempt without
  * touching the pair's row, so an older failure stays open.
- * Every worker start enqueues every live item once ({@link PluginScopeSync.enqueueAll}), which
- * also catches a lost enqueue.
  *
  * Jobs (queue {@link PLUGIN_SCOPE_QUEUE}): one per item and scope version
  * (`scope-item-<itemId>-<scope_version>`, every org), one per org (`scope-org-<orgId>`, every item,
- * enqueued after the org is created). Both are removed when done, so the next enqueue with the same
+ * owed by the org's creation). Both are owed in the outbox by the transaction that changes what
+ * they converge to (transactional outbox spec §8.1), so none is lost; a migration that changes a
+ * scope inserts its outbox rows itself. A confirmation (import, permissions, org upload) owes the
+ * immediate item job after its deploy and, in its commit, a backstop `scope-item-backstop` due
+ * five minutes later (ruling R24) that waits, retrying, for the extension to be enabled. Both are removed when done, so the next add with the same
  * id is not swallowed. Pairs of one org are serialized across replicas by a Redis lock per org; the
  * installer's org row lock and its one-live-install rule are the backstop.
  */
-/** The scope sync queue (no `:` in the name). */
-export const PLUGIN_SCOPE_QUEUE = "cap-kernel-plugin-scope";
-/** The job converging one item in every org. */
-export const SCOPE_ITEM_JOB = "scope-item";
-/** The job converging every item in one org. */
-export const SCOPE_ORG_JOB = "scope-org";
-/** One item job per scope version (no `:`: item ids are UUIDs). */
-export const scopeItemJobId = (itemId, version) => `scope-item-${itemId}-${version}`;
-/** One org job at a time per org. */
-export const scopeOrgJobId = (orgId) => `scope-org-${orgId}`;
-/**
- * The delayed retry `n` of an item job whose extension this replica had not loaded yet (ruling
- * P3-38); deterministic, so replicas deferring the same item add it once.
- */
-export const scopeRetryJobId = (itemId, version, n) => `scope-item-${itemId}-${version}-r${n}`;
+export { PLUGIN_SCOPE_QUEUE, SCOPE_BACKSTOP_DELAY, SCOPE_BACKSTOP_DELAY_MS, SCOPE_BACKSTOP_JOB, SCOPE_ITEM_JOB, SCOPE_ORG_JOB, scopeBackstopJobId, scopeItemJobId, scopeOrgJobId, scopeRetryJobId, } from "./scope-jobs.js";
 /** How many delayed retries an item job gets while its extension is not loaded here (P3-38). */
 export const SCOPE_LOAD_RETRIES = 6;
 /** The delay of each such retry. */
@@ -98,19 +86,6 @@ export async function reconcileWithin(lifecycle, reason, ms, log) {
             clearTimeout(timer);
     }
 }
-/** The item job of a scope version (what {@link PluginScopeSync.enqueueItem} adds). */
-export function scopeItemJob(itemId, version) {
-    return {
-        name: SCOPE_ITEM_JOB,
-        data: { kind: "item", itemId },
-        opts: {
-            jobId: scopeItemJobId(itemId, version),
-            attempts: 1,
-            removeOnComplete: true,
-            removeOnFail: true,
-        },
-    };
-}
 /** How long one org's pairs wait for each other (an install can take a while). */
 const ORG_LOCK_TTL_MS = 60_000;
 const ORG_LOCK_WAIT_MS = 10 * 60_000;
@@ -119,62 +94,67 @@ export const PLUGIN_SCOPE_CONCURRENCY = 2;
 const LIVE = ["installing", "installed", "upgrading"];
 let PluginScopeSync = class PluginScopeSync {
     kdb;
-    queue;
+    outbox;
     installer;
     registry;
     lifecycle;
     locks;
     log;
     txHost;
-    constructor(kdb, queue, installer, registry, 
+    backstopDelayMs;
+    constructor(kdb, outbox, installer, registry, 
     /** This replica's reconcile, awaited (bounded) before deferring an install (P3-38). */
-    lifecycle, locks, log, txHost) {
+    lifecycle, locks, log, txHost, 
+    /** The backstop's delay (a test seam; default {@link SCOPE_BACKSTOP_DELAY_MS}). */
+    backstopDelayMs = SCOPE_BACKSTOP_DELAY_MS) {
         this.kdb = kdb;
-        this.queue = queue;
+        this.outbox = outbox;
         this.installer = installer;
         this.registry = registry;
         this.lifecycle = lifecycle;
         this.locks = locks;
         this.log = log;
         this.txHost = txHost;
+        this.backstopDelayMs = backstopDelayMs;
     }
     get db() {
         return this.kdb.db;
     }
-    /** Enqueues the sync of an item in every org, once per scope version. Call after the commit. */
+    /**
+     * Owes the sync of an item in every org, once per scope version (the version read in the
+     * caller's transaction, so after its own bump), in the transaction that changes the scope.
+     */
     async enqueueItem(itemId) {
-        const row = await this.db
-            .selectFrom("catalog_items")
-            .select("scope_version")
-            .where("id", "=", itemId)
-            .executeTakeFirst();
-        if (!row)
-            return;
-        const job = scopeItemJob(itemId, row.scope_version);
-        await this.queue.add(job.name, job.data, job.opts);
+        await oweScopeItem(this.outbox, this.db, itemId);
     }
     /**
-     * Enqueues the sync of every live, not builtin item (a worker start): retries what failed or was
-     * never enqueued (a lost `afterCommit` enqueue, a migrated scope). The job ids are the items'
-     * scope versions, so replicas starting together add each one once.
+     * Owes the delayed backstop of the item's sync (ruling R24) in the transaction in context: a
+     * confirmation owes it before (or with) its deploy, so a crash before its post-deploy add still
+     * converges the orgs.
      */
-    async enqueueAll() {
-        const items = await this.db
-            .selectFrom("catalog_items")
-            .select("id")
-            .where("deleted_at", "is", null)
-            .where("builtin", "=", false)
-            .orderBy("id")
-            .execute();
-        for (const i of items)
-            await this.enqueueItem(i.id);
+    async enqueueBackstop(itemId) {
+        await oweScopeItem(this.outbox, this.db, itemId, {
+            backstop: true,
+            backstopDelayMs: this.backstopDelayMs,
+        });
     }
-    /** Enqueues the sync of every item in an org (a new org). Call after the commit. */
+    /** Owes the sync of every item in an org, in the transaction that creates the org. */
     async enqueueOrg(orgId) {
-        await this.queue.add(SCOPE_ORG_JOB, { kind: "org", orgId }, { jobId: scopeOrgJobId(orgId), attempts: 1, removeOnComplete: true, removeOnFail: true });
+        await this.outbox.add({
+            queue: PLUGIN_SCOPE_QUEUE,
+            name: SCOPE_ORG_JOB,
+            jobId: scopeOrgJobId(orgId),
+            data: { kind: "org", orgId },
+            orgId,
+        });
     }
-    /** One job: every org of an item, or every item of an org; `signal` stops between pairs. */
+    /**
+     * One job: every org of an item, or every item of an org; `signal` stops between pairs. A
+     * backstop job first checks the item's extension is deployed ({@link assertDeployed}).
+     */
     async process(data, signal) {
+        if (data.kind === "item" && data.backstop === true)
+            await this.assertDeployed(data.itemId);
         const pairs = data.kind === "item"
             ? (await this.db
                 .selectFrom("orgs")
@@ -214,7 +194,55 @@ let PluginScopeSync = class PluginScopeSync {
             }
         }
     }
-    /** The delayed retry `n` of an item job (deterministic id, P3-38). */
+    /**
+     * A backstop job (ruling R24) runs only once the item's extension is loaded here or enabled on
+     * the deployment; otherwise it throws, so BullMQ retries it with its backoff (bounded by its
+     * attempts) and no pair records a `catalog.not_deployed` failure that nothing would retry. An item without an
+     * extension, or one no longer live (deleted, disabled, still waiting, builtin), passes: its pairs
+     * converge (or change nothing) as for an immediate job.
+     */
+    async assertDeployed(itemId) {
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select([
+            "builtin",
+            "disabled",
+            "deleted_at",
+            "awaiting_confirmation",
+            "latest_version",
+            "platform_synced_version",
+        ])
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        if (!item || item.builtin || !isUsable(item))
+            return;
+        const version = item.platform_synced_version ?? item.latest_version;
+        const v = await this.db
+            .selectFrom("catalog_item_versions")
+            .select("manifest")
+            .where("item_id", "=", itemId)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        const m = v?.manifest;
+        if (!m?.extension)
+            return;
+        // loaded here (a config-declared extension has no install record), or enabled on the
+        // deployment (a replica that has not loaded it yet defers as P3-38 says)
+        if (this.registry.manifests().some((x) => x.name === m.name))
+            return;
+        const install = await this.db
+            .selectFrom("extension_installs")
+            .select("desired_state")
+            .where("name", "=", m.name)
+            .executeTakeFirst();
+        if (install?.desired_state === "enabled")
+            return;
+        throw new Error(`the extension ${m.name} of catalog item ${itemId} is not enabled on the deployment yet; the scope sync backstop is retried`);
+    }
+    /**
+     * Owes the delayed retry `n` of an item job (deterministic id, P3-38) in a transaction of its
+     * own: the job's own follow-up, delivered by the relay once due.
+     */
     async enqueueRetry(itemId, n) {
         const row = await this.db
             .selectFrom("catalog_items")
@@ -223,12 +251,12 @@ let PluginScopeSync = class PluginScopeSync {
             .executeTakeFirst();
         if (!row)
             return;
-        await this.queue.add(SCOPE_ITEM_JOB, { kind: "item", itemId, retry: n }, {
+        await this.outbox.add({
+            queue: PLUGIN_SCOPE_QUEUE,
+            name: SCOPE_ITEM_JOB,
             jobId: scopeRetryJobId(itemId, row.scope_version, n),
-            delay: SCOPE_LOAD_RETRY_DELAY_MS,
-            attempts: 1,
-            removeOnComplete: true,
-            removeOnFail: true,
+            data: { kind: "item", itemId, retry: n },
+            runAt: new Date(Date.now() + SCOPE_LOAD_RETRY_DELAY_MS),
         });
     }
     /**
@@ -509,68 +537,32 @@ let PluginScopeSync = class PluginScopeSync {
             .execute();
     }
 };
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginScopeSync.prototype, "enqueueItem", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginScopeSync.prototype, "enqueueBackstop", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginScopeSync.prototype, "enqueueOrg", null);
+__decorate([
+    Transactional()
+], PluginScopeSync.prototype, "enqueueRetry", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], PluginScopeSync.prototype, "recordFailure", null);
 PluginScopeSync = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(getQueueToken(PLUGIN_SCOPE_QUEUE))),
+    __param(1, Inject(OutboxService)),
     __param(2, Inject(PluginInstaller)),
     __param(3, Inject(ExtensionRegistry)),
     __param(4, Inject(ExtensionLifecycle)),
     __param(5, Inject(LockService)),
     __param(6, Inject(KERNEL_LOGGER)),
-    __param(7, Inject(TransactionHost))
+    __param(7, Inject(TransactionHost)),
+    __param(8, Optional()),
+    __param(8, Inject(SCOPE_BACKSTOP_DELAY))
 ], PluginScopeSync);
 export { PluginScopeSync };
-/** The consumer of {@link PLUGIN_SCOPE_QUEUE}: {@link PluginScopeSync}. */
-let PluginScopeSyncProcessor = class PluginScopeSyncProcessor extends WorkerHost {
-    sync;
-    log;
-    stopping = new AbortController();
-    constructor(sync, log) {
-        super();
-        this.sync = sync;
-        this.log = log;
-    }
-    process(job) {
-        return runJob(PLUGIN_SCOPE_QUEUE, job, () => this.sync.process(job.data, this.stopping.signal));
-    }
-    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
-    start() {
-        void this.worker.run().catch((err) => this.error(err));
-    }
-    /**
-     * Enqueues every live item's sync once (the worker role, after the start gate opened), in the
-     * background; a failure is only logged (the next worker start, or the next change, enqueues).
-     */
-    resync() {
-        void this.sync
-            .enqueueAll()
-            .catch((err) => this.log.error("plugin scope resync failed", { err }));
-    }
-    /** Stops between pairs and closes the worker. */
-    async close() {
-        this.stopping.abort();
-        await this.worker.close();
-    }
-    failed(job, err) {
-        this.log.error("plugin scope job failed", { name: job?.name, jobId: job?.id, err });
-    }
-    error(err) {
-        this.log.error("plugin scope worker error", { err });
-    }
-};
-__decorate([
-    OnWorkerEvent("failed")
-], PluginScopeSyncProcessor.prototype, "failed", null);
-__decorate([
-    OnWorkerEvent("error")
-], PluginScopeSyncProcessor.prototype, "error", null);
-PluginScopeSyncProcessor = __decorate([
-    Injectable(),
-    __param(0, Inject(PluginScopeSync)),
-    __param(1, Inject(KERNEL_LOGGER))
-], PluginScopeSyncProcessor);
-export { PluginScopeSyncProcessor };

package/dist/channels/channels.module.d.ts

@@ -1,6 +1,6 @@
 import { WorkerHost } from "@nestjs/bullmq";
 import { type DynamicModule } from "@nestjs/common";
-import type { Job, Worker } from "bullmq";
+import { type Job, type Worker } from "bullmq";
 import type { KernelConfig } from "../config/schema.js";
 import { type ProcessorWorkerOptions } from "../infra/queue/configured-processor.js";
 import { type ChannelJobData } from "./jobs.js";
@@ -14,7 +14,10 @@ import { ChannelOutbound } from "./outbound.js";
  */
 export declare class ChannelsModule {
 }
-/** The consumer of `cap-kernel-channels` (deliveries and inbound jobs): {@link ChannelOutbound}. */
+/**
+ * The consumer of `cap-kernel-channels`: deliveries (`DELIVER_JOB`, owed through the outbox or
+ * hinted) and inbound jobs (`INBOUND_JOB`), both handled by {@link ChannelOutbound}.
+ */
 export declare class ChannelsProcessor extends WorkerHost<Worker<ChannelJobData>> {
     private readonly outbound;
     constructor(outbound: ChannelOutbound);

package/dist/channels/channels.module.js

@@ -10,6 +10,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 var ChannelWorkersModule_1;
 import { OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
 import { Inject, Injectable, Module } from "@nestjs/common";
+import { UnrecoverableError } from "bullmq";
 import { ConversationsModule } from "../conversations/conversations.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
 import { DevicesModule } from "../devices/devices.module.js";
@@ -25,7 +26,7 @@ import { SchedulesModule } from "../schedules/schedules.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
-import { CHANNEL_QUEUE_NAME, ChannelJobs } from "./jobs.js";
+import { CHANNEL_QUEUE_NAME, ChannelJobs, DELIVER_JOB, INBOUND_JOB, } from "./jobs.js";
 import { ChannelOutbound, deliverBackoff } from "./outbound.js";
 import { AnonymousGuestLock, AnonymousGuests } from "./threads.js";
 /** The channel queue's registration (its producer here; the admin health reads its counts). */
@@ -74,7 +75,10 @@ ChannelsModule = __decorate([
     })
 ], ChannelsModule);
 export { ChannelsModule };
-/** The consumer of `cap-kernel-channels` (deliveries and inbound jobs): {@link ChannelOutbound}. */
+/**
+ * The consumer of `cap-kernel-channels`: deliveries (`DELIVER_JOB`, owed through the outbox or
+ * hinted) and inbound jobs (`INBOUND_JOB`), both handled by {@link ChannelOutbound}.
+ */
 let ChannelsProcessor = class ChannelsProcessor extends WorkerHost {
     outbound;
     constructor(outbound) {
@@ -82,6 +86,9 @@ let ChannelsProcessor = class ChannelsProcessor extends WorkerHost {
         this.outbound = outbound;
     }
     process(job, token) {
+        if (job.name !== DELIVER_JOB && job.name !== INBOUND_JOB) {
+            return Promise.reject(new UnrecoverableError(`unknown channel job "${job.name}"`));
+        }
         return runJob(CHANNEL_QUEUE_NAME, job, () => this.outbound.process(job, token));
     }
     failed(job, err) {

package/dist/channels/deliver-job.d.ts

@@ -0,0 +1,25 @@
+import type { OutboxService } from "../infra/outbox/outbox.service.js";
+/**
+ * The channel delivery job as the outbox owes it (transactional outbox spec §8.1): a leaf module
+ * with no BullMQ and no Nest class, so the event log can owe it without importing the channels
+ * domain. `jobs.ts` (the producer) re-exports these names.
+ */
+/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+export declare const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
+/** 投递任务名。 */
+export declare const DELIVER_JOB = "deliver";
+/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+export declare const deliverJobId: (conversationId: string, seq: number) => string;
+export interface DeliverJobData {
+    conversationId: string;
+}
+/**
+ * Owes the conversation's delivery job for the log position `seq` in the transaction in context:
+ * the caller knows the conversation has a channel target. Shares the job id of
+ * `ChannelJobs.enqueue`, so a hint for the same position is deduped by BullMQ.
+ */
+export declare function oweDelivery(outbox: Pick<OutboxService, "add">, d: {
+    conversationId: string;
+    orgId: string;
+    seq: number;
+}): Promise<boolean>;

package/dist/channels/deliver-job.js

@@ -0,0 +1,25 @@
+/**
+ * The channel delivery job as the outbox owes it (transactional outbox spec §8.1): a leaf module
+ * with no BullMQ and no Nest class, so the event log can owe it without importing the channels
+ * domain. `jobs.ts` (the producer) re-exports these names.
+ */
+/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+export const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
+/** 投递任务名。 */
+export const DELIVER_JOB = "deliver";
+/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+export const deliverJobId = (conversationId, seq) => `deliver-${conversationId}-${seq}`;
+/**
+ * Owes the conversation's delivery job for the log position `seq` in the transaction in context:
+ * the caller knows the conversation has a channel target. Shares the job id of
+ * `ChannelJobs.enqueue`, so a hint for the same position is deduped by BullMQ.
+ */
+export function oweDelivery(outbox, d) {
+    return outbox.add({
+        queue: CHANNEL_QUEUE_NAME,
+        name: DELIVER_JOB,
+        jobId: deliverJobId(d.conversationId, d.seq),
+        data: { conversationId: d.conversationId },
+        orgId: d.orgId,
+    });
+}

package/dist/channels/inbound.d.ts

@@ -72,7 +72,7 @@ export declare class ChannelInbound {
     /** 通讯录同步的投递（按 (组织, 插件) 每分钟去重的维护队列任务）。 */
     directorySync: Pick<DirectorySync, "enqueue">, 
     /** The channel queue: inbound jobs (`onEvent` only dedupes and enqueues) and deliveries. */
-    jobs: Pick<ChannelJobs, "enqueue" | "enqueueInbound">, 
+    jobs: Pick<ChannelJobs, "enqueue" | "enqueueInbound" | "bind">, 
     /** 卡片操作：审批决定与提问回答（授权由这两个服务按点击者映射到的账号判定）。 */
     approvals: Pick<ApprovalsService, "decide">, questions: Pick<QuestionsService, "answer">, guests: Pick<AnonymousGuests, "ensure">, devices: Pick<DevicesService, "list" | "imDefault" | "setImDefault">, log: Pick<Logger, "warn" | "info">);
     /**

package/dist/channels/inbound.js

@@ -11,6 +11,7 @@ import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { imSenderContext, recipientLocale, } from "../conversations/message-context.js";
+import { channelSource } from "../conversations/source.js";
 import { DevicesService } from "../devices/devices.service.js";
 import { DEFAULT_DEVICE_ALIASES, deviceLabel } from "../devices/label.js";
 import { ApiError } from "../errors.js";
@@ -227,8 +228,7 @@ let ChannelInbound = class ChannelInbound {
             try {
                 // bound to the person's IM default device, else their default (environments spec
                 // §4.2 item 8); an anonymous sender's stays unbound (no sandbox)
-                created = (await this.conversations.create(row.orgId, accountId, row.agentId, { im: true }))
-                    .id;
+                created = (await this.conversations.create(row.orgId, accountId, row.agentId, { im: true }, { source: channelSource(e.target.chatType) })).id;
             }
             catch (err) {
                 if (err instanceof ApiError && err.code === "agent.not_found") {
@@ -277,21 +277,8 @@ let ChannelInbound = class ChannelInbound {
             }
             throw err;
         }
-        await db
-            .insertInto("channel_deliveries")
-            .values({
-            conversation_id: conversationId,
-            connection_id: connectionId,
-            target: JSON.stringify(replyTarget),
-            last_seq: seq,
-        })
-            .onConflict((oc) => oc.column("conversation_id").doUpdateSet({
-            connection_id: connectionId,
-            target: JSON.stringify(replyTarget),
-            updated_at: new Date(),
-        }))
-            .execute();
-        await this.jobs.enqueue(conversationId);
+        // the reply target and its delivery, owed in one transaction (transactional outbox spec §8.1)
+        await this.jobs.bind(row.orgId, conversationId, connectionId, replyTarget, seq);
     }
     /**
      * Direct-message `/device` (environments spec §4.2 item 8): lists the person's usable devices,

package/dist/channels/jobs.d.ts

@@ -1,14 +1,12 @@
-import type { InboundEvent, Logger } from "@capybara-hq/plugin-sdk";
+import type { ChannelTarget, InboundEvent, Logger } from "@capybara-hq/plugin-sdk";
 import { type OnApplicationShutdown } from "@nestjs/common";
 import type { Queue } from "bullmq";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
-/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
-export declare const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
-/** 投递任务名。 */
-export declare const DELIVER_JOB = "deliver";
-/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
-export declare const deliverJobId: (conversationId: string, seq: number) => string;
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import { type DeliverJobData } from "./deliver-job.js";
+export { CHANNEL_QUEUE_NAME, DELIVER_JOB, type DeliverJobData, deliverJobId, oweDelivery, } from "./deliver-job.js";
 /**
  * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
  * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
@@ -20,10 +18,7 @@ export declare const followUpJobId: (conversationId: string, seq: number) => str
  */
 export declare function idempotencyKey(raw: string): string;
 /** 可重试失败（限流、5xx、网络、超时）的总尝试次数。 */
-export declare const DELIVER_ATTEMPTS = 8;
-export interface DeliverJobData {
-    conversationId: string;
-}
+export declare const DELIVER_ATTEMPTS: 8;
 /** 入站任务（Ruling A21）：插件 `onEvent` 收到的事件，原样排进队列由 worker 处理。 */
 export interface InboundJobData {
     connectionId: string;
@@ -37,7 +32,7 @@ export declare const INBOUND_JOB = "inbound";
  * 用户发来的消息不能排在它们后面。
  */
 export declare const INBOUND_PRIORITY = 1;
-export declare const DELIVER_PRIORITY = 10;
+export declare const DELIVER_PRIORITY: 10;
 /** 入站任务的总尝试次数（处理失败由 BullMQ 指数退避重试：1s、2s、4s、8s）。 */
 export declare const INBOUND_ATTEMPTS = 5;
 /**
@@ -49,24 +44,39 @@ export declare const inboundJobId: (connectionId: string, messageId: string) =>
  * The producer side of the channel queue `cap-kernel-channels` (any role): delivery jobs for a
  * conversation with an IM target, inbound jobs (Ruling A21), and the catch-up of a connection that
  * can deliver again. Its consumer is {@link ChannelOutbound} through the `@Processor` of the worker
- * role. Delivery jobs follow the kernel's domain events (spec §3b): every published log advance
- * (`conversation.event-appended`), a run starting here (`run.started`), a stopped wait
- * (`run.wait-stopped`), a decided approval and an answered question (their cards change). Each is
- * lost-tolerant: the next append enqueues again, and a finished delivery job re-checks the log.
+ * role. A delivery is owed (transactional outbox spec §8.1): every event append of a conversation
+ * with a channel target adds its deliver job to the outbox in the append's transaction (a reply, an
+ * approval decision, a question answer, a wait stop all append), and {@link bind} owes the first
+ * one with the target. The direct {@link enqueue} is left for hints and catch-ups: a run starting
+ * here (`run.started`, so its streaming drafts start at once), a finished delivery job's re-check,
+ * a card click's thread and a connection that can deliver again.
  */
 export declare class ChannelJobs implements OnApplicationShutdown {
     private readonly db;
     private readonly queue;
     private readonly log;
+    private readonly outbox;
+    readonly txHost: TransactionHost;
     /** Stopped (the stop's channel-outbound phase): enqueues do nothing, inbound enqueues throw. */
     private closed;
     private readonly unsubscribe;
-    constructor(db: KernelDb, queue: Queue<ChannelJobData>, events: Pick<KernelEvents, "on">, log: Pick<Logger, "warn" | "error">);
+    constructor(db: KernelDb, queue: Queue<ChannelJobData>, events: Pick<KernelEvents, "on">, log: Pick<Logger, "warn" | "error">, outbox: Pick<OutboxService, "add">, txHost: TransactionHost);
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
     onApplicationShutdown(): void;
+    /**
+     * Makes `target` (on `connectionId`) the conversation's delivery target and owes its delivery
+     * from the current log position, in one transaction. A new target starts delivering after
+     * `seq` (the message that bound it); a known one keeps its progress. The conversation row is
+     * locked first, as an append locks it: an append either committed before (its events are below
+     * the owed position) or reads the target (and owes its own job).
+     */
+    bind(orgId: string, conversationId: string, connectionId: string, target: ChannelTarget, seq: number): Promise<void>;
     /** 会话有 IM 投递目标时排一个出站任务，不等入队完成；失败只记日志。 */
     private enqueueSoon;
-    /** 会话有 IM 投递目标时投递一个出站任务（同一日志位置重复调用只排一个）；已关闭时什么都不做。 */
+    /**
+     * A hint (not owed work, see the class): a delivery job for a conversation with an IM target (one
+     * per log position; `followUp` gets a fresh id); does nothing once closed.
+     */
     enqueue(conversationId: string, opts?: {
         followUp?: boolean;
     }): Promise<void>;