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

package/dist/catalog/platform-import-update.js

@@ -0,0 +1,116 @@
+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 { ApiError } from "../errors.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater, } from "./plugin-upgrade.js";
+const notInstalled = (name) => new ApiError("plugin.upgrade_target_invalid", `Plugin ${name} is not a platform plugin of this deployment yet; install it with the import review instead`, [{ reason: "not_installed" }]);
+/**
+ * The platform's update of an installed plugin to a version staged for import (the one wizard of
+ * the admin plugin pages, maintainer decision 2026-11-13): the import review (prepared as any
+ * import, `PluginImport.prepare`) and the platform update preview of the staged version
+ * ({@link preview}: `PlatformPluginUpdater.previewStaged`, the target read from the staging) are
+ * confirmed together ({@link confirm} with the review's `reviewHash` and the preview's `diffHash`).
+ * Nothing is written before that confirm: cancelling the wizard leaves only the staging row, which
+ * expires like any staged import.
+ *
+ * The confirm holds the item's update lock (`PlatformPluginUpdater.withItemLock`, one per item
+ * across replicas: another update -> 409 `plugin.install_in_progress`), recomputes the preview
+ * (another `diffHash` -> 409 `plugin.upgrade_stale`, nothing written), commits the import without
+ * deploying its extension (the permission snapshot is written as the review approved it), then
+ * runs the platform update, which moves the extension with its own rollback and writes the
+ * components in one transaction. When that update fails, the platform stays on its version, the
+ * extension where it was and its previous approval is put back; the imported version stays in the
+ * catalog (its 版本 tab, and 更新到 retries the update with the plain update preview): 409
+ * `plugin.imported_not_updated` says so, with the cause in the details. No in-process state.
+ */
+let PlatformImportUpdate = class PlatformImportUpdate {
+    pluginImport;
+    updater;
+    log;
+    constructor(pluginImport, updater, log) {
+        this.pluginImport = pluginImport;
+        this.updater = updater;
+        this.log = log;
+    }
+    /**
+     * The platform update the staged version would apply (writes nothing). The staging must be a
+     * platform staging (else 404 `plugin.staging_not_found`) of a new version of a live
+     * platform-owned plugin (else 409 `plugin.upgrade_target_invalid`, reason `not_installed`); the
+     * updater's refusals apply as for any update preview. `needsApproval` is false: the confirm
+     * approves the permissions the review shows.
+     */
+    async preview(stagingId) {
+        const st = await this.target(stagingId);
+        return this.previewOf(st);
+    }
+    /** Confirms the import and the update together (see the class comment). */
+    async confirm(actor, stagingId, input, opts = {}) {
+        const st = await this.target(stagingId);
+        return this.updater.withItemLock(st.itemId, async () => {
+            const preview = await this.previewOf(st);
+            if (preview.diffHash !== input.diffHash) {
+                throw new ApiError("plugin.upgrade_stale", `What updating plugin ${preview.name} to ${st.version} does changed since the preview; preview it again`);
+            }
+            // The review hash is checked by the import's confirm (409 plugin.review_stale, nothing
+            // written)
+            const imported = await this.pluginImport.confirm(actor, stagingId, { reviewHash: input.reviewHash, deploy: false }, opts);
+            try {
+                const update = await this.updater.updateHeld(actor, st.itemId, { version: st.version, diffHash: input.diffHash }, opts);
+                return { item: await this.pluginImport.view(st.itemId), update };
+            }
+            catch (e) {
+                let restored = imported.approval === undefined;
+                if (imported.approval !== undefined) {
+                    try {
+                        restored = await this.pluginImport.restoreApproval(actor, imported.approval, opts);
+                    }
+                    catch (err) {
+                        this.log.error("cannot restore an extension's approval after a failed update", {
+                            itemId: st.itemId,
+                            err,
+                        });
+                    }
+                }
+                const cause = e instanceof ApiError ? e : undefined;
+                throw new ApiError("plugin.imported_not_updated", `Version ${st.version} of plugin ${preview.name} was imported, but updating the platform to it failed (${cause?.code ?? "internal"}); the platform stays on ${preview.from ?? "(none)"}. Update to ${st.version} from the plugin's page to retry`, [
+                    {
+                        version: st.version,
+                        from: preview.from,
+                        code: cause?.code ?? "internal",
+                        ...(cause !== undefined && { message: cause.message }),
+                        ...(cause?.details !== undefined && { causeDetails: cause.details }),
+                        approvalRestored: restored,
+                    },
+                ]);
+            }
+        });
+    }
+    /** The staged target, which must be a new version of a live platform-owned plugin. */
+    async target(stagingId) {
+        const st = await this.pluginImport.stagedTarget(stagingId);
+        if (!st.existing) {
+            throw notInstalled((await this.pluginImport.staged(stagingId)).review.name);
+        }
+        return st;
+    }
+    async previewOf(st) {
+        const p = await this.updater.previewStaged(st.itemId, st.version, st.target);
+        return p.extension === null ? p : { ...p, extension: { ...p.extension, needsApproval: false } };
+    }
+};
+PlatformImportUpdate = __decorate([
+    Injectable(),
+    __param(0, Inject(PluginImport)),
+    __param(1, Inject(PlatformPluginUpdater)),
+    __param(2, Inject(KERNEL_LOGGER))
+], PlatformImportUpdate);
+export { PlatformImportUpdate };

package/dist/catalog/plugin-import.d.ts

@@ -8,6 +8,7 @@ import { ExtensionBlobs } from "../extensions/blobs.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
 import { PluginApproveLock, PluginInstallLock } from "../extensions/locks.js";
 import { ExtensionPackageError } from "../extensions/package.js";
+import { type PermissionSet } from "../extensions/permission-set.js";
 import { type PackageWarning, type PermissionGroup, type PermissionItem } from "../extensions/permission-view.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import type { SingleProviderBlock } from "../extensions/single-provider.js";
@@ -317,6 +318,18 @@ export interface PluginConfirmResult {
      * extension (applied at once, plan Task 6).
      */
     firstVersion: boolean;
+    /**
+     * A confirm with `deploy: false` that approved the extension's permissions (its snapshot
+     * written): what {@link PluginImport.restoreApproval} needs to put the previous approval back
+     * when the step that was to deploy it fails. Never sent over HTTP (the route always deploys).
+     */
+    approval?: HeldApproval;
+}
+/** The approval a confirm without its deploy wrote (see {@link PluginConfirmResult.approval}). */
+export interface HeldApproval {
+    review: PluginReview;
+    extension: PluginReviewExtension;
+    previous: PreviousSnapshot | null;
 }
 /** What prepare checks besides the package itself (npm and marketplace imports). */
 export interface PluginPrepareExpect {
@@ -338,6 +351,14 @@ export interface ReviewProvenance {
     provenance: ProvenanceResult;
     warning?: "repository_mismatch";
 }
+/** The snapshot overwritten at confirm (restored when deploying an upgrade fails). */
+export interface PreviousSnapshot {
+    version: string;
+    permissions: PermissionSet;
+    approvedBy: string | null;
+    approvedAt: Date;
+    source: "auto" | "web" | "cli" | "bootstrap";
+}
 /** What an org's staged upload targets (see {@link PluginImport.stagedTarget}). */
 export interface StagedTarget {
     itemId: string;
@@ -521,8 +542,10 @@ export declare class PluginImport {
      * whether the item exists (a new version of the org's own plugin) or the version is imported
      * already (F4), and the target as the platform updater reads it: the staged manifest and files,
      * or the imported version's for a retry. Another org's staging -> 404 `plugin.staging_not_found`.
+     * Without `owner`: a platform staging, and `existing` means a live platform-owned item (the
+     * platform's import and update, `PlatformImportUpdate`).
      */
-    stagedTarget(stagingId: string, owner: ImportOwner): Promise<StagedTarget>;
+    stagedTarget(stagingId: string, owner?: ImportOwner): Promise<StagedTarget>;
     /** The catalog item's view (as a confirm returns it). */
     view(itemId: string): Promise<CatalogItemView>;
     /**
@@ -553,6 +576,13 @@ export declare class PluginImport {
         orgs?: string[];
         /** An org upload's new item: shared with other orgs by its owner (default false, P3-16). */
         shareable?: boolean;
+        /**
+         * Deploy the extension after the commit (default true). false (the platform's import and
+         * update, `PlatformImportUpdate`) leaves the deployment to the platform update that follows,
+         * which moves the extension with its own rollback; the approval written is returned in
+         * `approval`.
+         */
+        deploy?: boolean;
     }, opts?: ActorOpts & {
         owner?: ImportOwner;
     }): Promise<PluginConfirmResult>;
@@ -603,6 +633,11 @@ export declare class PluginImport {
      * admin (the package is already in the package store) with the sha256 from the result.
      */
     private deploy;
+    /**
+     * Puts back the approval a confirm with `deploy: false` wrote, after the step that was to deploy
+     * the extension failed (see {@link restoreSnapshot}; false when someone changed it meanwhile).
+     */
+    restoreApproval(actor: string | null, held: HeldApproval, opts?: ActorOpts): Promise<boolean>;
     /**
      * Restores the snapshot overwritten at confirm (deletes it when there was none before), audits
      * `extension.permissions_restored`. Compare-and-write (row locked): restores only while the

package/dist/catalog/plugin-import.js

@@ -610,6 +610,8 @@ let PluginImport = class PluginImport {
      * whether the item exists (a new version of the org's own plugin) or the version is imported
      * already (F4), and the target as the platform updater reads it: the staged manifest and files,
      * or the imported version's for a retry. Another org's staging -> 404 `plugin.staging_not_found`.
+     * Without `owner`: a platform staging, and `existing` means a live platform-owned item (the
+     * platform's import and update, `PlatformImportUpdate`).
      */
     async stagedTarget(stagingId, owner) {
         if (!UUID_RE.test(stagingId))
@@ -630,7 +632,7 @@ let PluginImport = class PluginImport {
             .select(["id", "awaiting_confirmation"])
             .where("id", "=", staged.itemId)
             .where("deleted_at", "is", null)
-            .where("owner_org_id", "=", owner.orgId)
+            .where((eb) => owner === undefined ? eb("owner_org_id", "is", null) : eb("owner_org_id", "=", owner.orgId))
             .executeTakeFirst();
         const imported = staged.retry === true
             ? await this.db
@@ -753,6 +755,19 @@ let PluginImport = class PluginImport {
         // update. After the commit: it copies files in object storage
         if (committed.firstVersion)
             await this.syncPlatform(committed.itemId, staged.version);
+        if (input.deploy === false) {
+            return {
+                item: await this.itemView(committed.itemId),
+                created: committed.created,
+                deploy: null,
+                pending: false,
+                firstVersion: committed.firstVersion,
+                ...(now &&
+                    committed.previous !== undefined && {
+                    approval: { review, extension: now, previous: committed.previous },
+                }),
+            };
+        }
         const deploy = now && now.action !== "keep"
             ? await this.deploy(actor, review, committed.itemId, now, committed.previous, opts, input.enable ?? true)
             : null;
@@ -1184,6 +1199,13 @@ let PluginImport = class PluginImport {
             return { ...base, result: "failed", ...failure(e) };
         }
     }
+    /**
+     * Puts back the approval a confirm with `deploy: false` wrote, after the step that was to deploy
+     * the extension failed (see {@link restoreSnapshot}; false when someone changed it meanwhile).
+     */
+    async restoreApproval(actor, held, opts = {}) {
+        return this.restoreSnapshot(actor, held.review, held.extension, held.previous, opts);
+    }
     /**
      * Restores the snapshot overwritten at confirm (deletes it when there was none before), audits
      * `extension.permissions_restored`. Compare-and-write (row locked): restores only while the

package/dist/catalog/plugin-upgrade.d.ts

@@ -230,6 +230,13 @@ export declare class PlatformPluginUpdater {
     private get db();
     /** The update preview (see the class comment); writes nothing. */
     preview(itemId: string, version: string): Promise<PlatformUpdatePreview>;
+    /**
+     * The update preview of a version staged for import, not imported yet (the platform's import and
+     * update, `PlatformImportUpdate`): the same diff as {@link preview}, with the target read from the
+     * staging (`target`, whose files are where the import's version row will point), so the
+     * `diffHash` is the one {@link updateHeld} recomputes after the import. Writes nothing.
+     */
+    previewStaged(itemId: string, version: string, target: UpdateTarget): Promise<PlatformUpdatePreview>;
     /** The preview of a diff with the template guides it changes. */
     private withGuideChanges;
     /**
@@ -292,6 +299,17 @@ export declare class PlatformPluginUpdater {
      * upload runs every step under it (ruling P3-35).
      */
     withItemLock<T>(itemId: string, f: () => Promise<T>): Promise<T>;
+    /**
+     * {@link update} for a caller already holding the item's update lock ({@link withItemLock}):
+     * the platform's import and update runs its import and this update under one hold.
+     */
+    updateHeld(actor: string, itemId: string, input: {
+        version: string;
+        diffHash: string;
+    }, opts?: {
+        actorTokenId?: string;
+        auditDetail?: Record<string, unknown>;
+    }): Promise<PlatformUpdateResult>;
     /**
      * Runs an update confirmed with the preview's `diffHash` (see the class comment). A version an
      * org upload waits with, or an item whose first version waits, -> 409 `catalog.item_pending`

package/dist/catalog/plugin-upgrade.js

@@ -176,6 +176,18 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
     async preview(itemId, version) {
         return this.withGuideChanges(await this.diff(itemId, version));
     }
+    /**
+     * The update preview of a version staged for import, not imported yet (the platform's import and
+     * update, `PlatformImportUpdate`): the same diff as {@link preview}, with the target read from the
+     * staging (`target`, whose files are where the import's version row will point), so the
+     * `diffHash` is the one {@link updateHeld} recomputes after the import. Writes nothing.
+     */
+    async previewStaged(itemId, version, target) {
+        if (target.version !== version) {
+            throw new Error(`internal: previewStaged got the staged target of version ${target.version} for version ${version}`);
+        }
+        return this.withGuideChanges(await this.diff(itemId, version, { target }));
+    }
     /** The preview of a diff with the template guides it changes. */
     async withGuideChanges(d) {
         return {
@@ -335,6 +347,13 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
             throw itemNotFound();
         return this.locked(itemId, f);
     }
+    /**
+     * {@link update} for a caller already holding the item's update lock ({@link withItemLock}):
+     * the platform's import and update runs its import and this update under one hold.
+     */
+    async updateHeld(actor, itemId, input, opts = {}) {
+        return this.updateLocked(actor, itemId, input, opts);
+    }
     /**
      * Runs an update confirmed with the preview's `diffHash` (see the class comment). A version an
      * org upload waits with, or an item whose first version waits, -> 409 `catalog.item_pending`

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

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