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

package/dist/catalog/scope-sync.d.ts

@@ -1,13 +1,12 @@
-import { WorkerHost } from "@nestjs/bullmq";
-import type { Job, Queue, Worker } from "bullmq";
 import { ExtensionLifecycle } from "../extensions/lifecycle.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { LockService } from "../infra/lock/lock.service.js";
-import type { OneJob } from "../infra/queue/add-job-once.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { PluginInstaller } from "./plugin-install.js";
+import { type ScopeJob } from "./scope-jobs.js";
 /**
  * The plugin scope sync (plugin and component management spec §5, phase 1): converges every org
  * to each platform plugin's scope. In phase 1 "on in an org" is the org's plugin install, so for
@@ -30,55 +29,29 @@ import { PluginInstaller } from "./plugin-install.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 declare const PLUGIN_SCOPE_QUEUE = "cap-kernel-plugin-scope";
-/** The job converging one item in every org. */
-export declare const SCOPE_ITEM_JOB = "scope-item";
-/** The job converging every item in one org. */
-export declare const SCOPE_ORG_JOB = "scope-org";
-/** One item job per scope version (no `:`: item ids are UUIDs). */
-export declare const scopeItemJobId: (itemId: string, version: number) => string;
-/** One org job at a time per org. */
-export declare const scopeOrgJobId: (orgId: string) => string;
-/**
- * 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 declare const scopeRetryJobId: (itemId: string, version: number, n: number) => string;
+export { PLUGIN_SCOPE_QUEUE, SCOPE_BACKSTOP_DELAY, SCOPE_BACKSTOP_DELAY_MS, SCOPE_BACKSTOP_JOB, SCOPE_ITEM_JOB, SCOPE_ORG_JOB, type ScopeJob, 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 declare const SCOPE_LOAD_RETRIES = 6;
 /** The delay of each such retry. */
 export declare const SCOPE_LOAD_RETRY_DELAY_MS = 5000;
 /** How long a pair waits for this replica's reconcile before deferring (P3-38). */
 export declare const SCOPE_RECONCILE_WAIT_MS = 10000;
-/**
- * The job's data. `retry`: the item job's delayed retry number (P3-38); at
- * {@link SCOPE_LOAD_RETRIES} an extension still not loaded is a failure as before.
- */
-export type ScopeJob = {
-    kind: "item";
-    itemId: string;
-    retry?: number;
-} | {
-    kind: "org";
-    orgId: string;
-};
 /**
  * Awaits this replica's extension reconcile for at most `ms` (a slower one carries on in the
  * background); a failure only warns.
  */
 export declare function reconcileWithin(lifecycle: Pick<ExtensionLifecycle, "reconcile">, reason: string, ms: number, log: Pick<KernelLogger, "warn">): Promise<void>;
-/** The item job of a scope version (what {@link PluginScopeSync.enqueueItem} adds). */
-export declare function scopeItemJob(itemId: string, version: number): OneJob<ScopeJob>;
 /**
  * What a sync of one (item, org) did. `deferred`: the plugin's extension is enabled on the
  * deployment but not loaded on this replica yet (P3-38); the item job retries later.
@@ -88,7 +61,7 @@ export type ScopeSyncResult = "installed" | "removed" | "needs_config" | "unchan
 export declare const PLUGIN_SCOPE_CONCURRENCY = 2;
 export declare class PluginScopeSync {
     private readonly kdb;
-    private readonly queue;
+    private readonly outbox;
     private readonly installer;
     private readonly registry;
     /** This replica's reconcile, awaited (bounded) before deferring an install (P3-38). */
@@ -96,23 +69,44 @@ export declare class PluginScopeSync {
     private readonly locks;
     private readonly log;
     readonly txHost: TransactionHost;
-    constructor(kdb: KernelDb, queue: Queue<ScopeJob>, installer: PluginInstaller, registry: ExtensionRegistry, 
+    /** The backstop's delay (a test seam; default {@link SCOPE_BACKSTOP_DELAY_MS}). */
+    private readonly backstopDelayMs;
+    constructor(kdb: KernelDb, outbox: Pick<OutboxService, "add">, installer: PluginInstaller, registry: ExtensionRegistry, 
     /** This replica's reconcile, awaited (bounded) before deferring an install (P3-38). */
-    lifecycle: ExtensionLifecycle, locks: LockService, log: KernelLogger, txHost: TransactionHost);
+    lifecycle: ExtensionLifecycle, locks: LockService, log: KernelLogger, txHost: TransactionHost, 
+    /** The backstop's delay (a test seam; default {@link SCOPE_BACKSTOP_DELAY_MS}). */
+    backstopDelayMs?: number);
     private get 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.
+     */
     enqueueItem(itemId: string): Promise<void>;
     /**
-     * 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.
      */
-    enqueueAll(): Promise<void>;
-    /** Enqueues the sync of every item in an org (a new org). Call after the commit. */
+    enqueueBackstop(itemId: string): Promise<void>;
+    /** Owes the sync of every item in an org, in the transaction that creates the org. */
     enqueueOrg(orgId: string): Promise<void>;
-    /** 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}).
+     */
     process(data: ScopeJob, signal?: AbortSignal): Promise<void>;
-    /** 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.
+     */
+    private assertDeployed;
+    /**
+     * 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.
+     */
     private enqueueRetry;
     /**
      * Whether the install of the item's `version` may go ahead on this replica (P3-38): its
@@ -155,22 +149,3 @@ export declare class PluginScopeSync {
     private failed;
     private recordFailure;
 }
-/** The consumer of {@link PLUGIN_SCOPE_QUEUE}: {@link PluginScopeSync}. */
-export declare class PluginScopeSyncProcessor extends WorkerHost<Worker<ScopeJob>> {
-    private readonly sync;
-    private readonly log;
-    private readonly stopping;
-    constructor(sync: PluginScopeSync, log: Pick<KernelLogger, "error">);
-    process(job: Job<ScopeJob>): Promise<void>;
-    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
-    start(): void;
-    /**
-     * 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;
-    /** Stops between pairs and closes the worker. */
-    close(): Promise<void>;
-    failed(job: Job<ScopeJob> | undefined, err: Error): void;
-    error(err: Error): void;
-}

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/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") {

package/dist/channels/threads.d.ts

@@ -21,9 +21,10 @@ export declare class AnonymousGuests {
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, guestLock: AnonymousGuestLock, txHost: TransactionHost);
     /**
-     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
-     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
-     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     * The org's one anonymous guest account id, created on first use (`accounts.status = active`, no
+     * way to sign in, org role guest). Every call makes sure the membership exists (a removed guest
+     * is added back on its next use). Concurrent first creations across replicas are serialized by
+     * {@link AnonymousGuestLock}: one account.
      */
     ensure(orgId: string): Promise<string>;
 }

package/dist/channels/threads.js

@@ -55,9 +55,10 @@ let AnonymousGuests = class AnonymousGuests {
         this.txHost = txHost;
     }
     /**
-     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
-     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
-     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     * The org's one anonymous guest account id, created on first use (`accounts.status = active`, no
+     * way to sign in, org role guest). Every call makes sure the membership exists (a removed guest
+     * is added back on its next use). Concurrent first creations across replicas are serialized by
+     * {@link AnonymousGuestLock}: one account.
      */
     async ensure(orgId) {
         await this.guestLock.lock(orgId);

package/dist/conversations/conversations.controller.js

@@ -190,7 +190,9 @@ let ConversationsController = class ConversationsController {
         const pick = body.deviceId === undefined ? {} : { deviceId: body.deviceId };
         if (body.message === undefined) {
             return {
-                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick),
+                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick, {
+                    source: "web",
+                }),
             };
         }
         const m = body.message;
@@ -204,7 +206,7 @@ let ConversationsController = class ConversationsController {
             ...(m.skill !== undefined && { skill: m.skill }),
             ...(m.timeZone !== undefined && { timeZone: m.timeZone }),
             ...(m.locale !== undefined && { locale: m.locale }),
-        }, pick);
+        }, pick, { source: "web" });
         reply.status(out.created ? 201 : 200);
         return { conversation: out.conversation, event: out.event, events: out.events };
     }

package/dist/conversations/conversations.service.d.ts

@@ -1,3 +1,4 @@
+import type { ConversationSource } from "@capybara-hq/plugin-sdk";
 import { AgentLookup } from "../agents/agent-lookup.js";
 import type { ModelRef } from "../agents/definition.js";
 import type { AgentAvatar } from "../agents/profile.js";
@@ -146,6 +147,8 @@ export interface RunControl {
      * 否则返回 false。
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
+    /** Ends a run still `queued` in PG before a worker started it (`RunQueue.abortQueued`): true. */
+    abortQueued(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
     /**
      * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
      * 运行已不是 waiting（例如刚被续跑）→ false。
@@ -228,6 +231,14 @@ export interface InternalMessageOptions {
     schedule?: ScheduleMarker;
     timeZoneOverride?: string;
 }
+/** Options of a conversation created by a kernel caller (never an HTTP body). */
+export interface NewConversationOptions {
+    /**
+     * Where it comes from (memory plugin spec §6.2), fixed at creation. Required: a channel or group
+     * conversation that fell back to `web` would be offered what only the web and DMs may see.
+     */
+    source: ConversationSource;
+}
 /**
  * 会话：只有所有者可见；每次访问都实时复核 agent 对所有者仍可用（spec 3.6 R5），
  * 不可用时会话也按不存在处理（`conversation.not_found`）。
@@ -280,9 +291,10 @@ export declare class ConversationsService {
      * Creates an empty conversation bound to its device (`pick`, see
      * {@link ConversationDevices.forNew}); an agent the account cannot use →
      * `agent.not_found`, a device it may not use → `device.not_found` /
-     * `device.unavailable`, and nothing is created.
+     * `device.unavailable`, and nothing is created. `opts.source` records where the conversation
+     * comes from.
      */
-    create(orgId: string, accountId: string, agentId: string, pick?: NewConversationDevice): Promise<ConversationView>;
+    create(orgId: string, accountId: string, agentId: string, pick: NewConversationDevice | undefined, opts: NewConversationOptions): Promise<ConversationView>;
     /**
      * Creates a conversation together with its first message (UI refresh B, create on first send):
      * the conversation row and the `user_message` are written in one transaction, keyed by the
@@ -291,12 +303,12 @@ export declare class ConversationsService {
      * `agent.not_found` and nothing is written. Queues a run afterwards, like `postUserMessage`.
      * `events` are every event the create wrote, in seq order from seq 1 (a `model_switched` before
      * the message when the send switched), so a client can seed the new conversation's log whole.
-     * `internal` (kernel callers only): a scheduled task's marker, which also sets
-     * `conversations.scheduled_task_id`, and its zone override.
+     * `internal`: the conversation's source and, for kernel callers only, a scheduled task's marker,
+     * which also sets `conversations.scheduled_task_id`, and its zone override.
      */
     createWithMessage(orgId: string, accountId: string, agentId: string, input: UserMessageInput & {
         clientMessageId: string;
-    }, pick?: NewConversationDevice, internal?: InternalMessageOptions): Promise<{
+    }, pick: NewConversationDevice | undefined, internal: InternalMessageOptions & NewConversationOptions): Promise<{
         conversation: ConversationView;
         event: ConversationEvent;
         events: ConversationEvent[];