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

package/dist/catalog/plugin-import.js

@@ -9,8 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { createHash, randomUUID } from "node:crypto";
 import { appearanceIssues, PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
-import { getQueueToken } from "@nestjs/bullmq";
-import { Inject, Injectable } from "@nestjs/common";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
 import { ClientBuilds } from "../client/client-builds.service.js";
@@ -35,10 +34,10 @@ import { afterCommit } from "../infra/database/after-commit.js";
 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 { OutboxService } from "../infra/outbox/outbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { packPackageTgz } from "../packages/tgz.js";
-import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { checkSkillFiles, SkillArchiveError } from "../skills/package.js";
 import { StorageService } from "../storage/storage.service.js";
 import { canonicalJson } from "../tools/canonical-json.js";
@@ -52,15 +51,13 @@ import { item as reportItem, sortItems, } from "./claude/report.js";
 import { isClaudePluginTree, translateClaudePlugin } from "./claude/translate.js";
 import { CatalogItemLock } from "./locks.js";
 import { assertNameFree, assertPackageFree, assertShareable, packageOwner, releaseExtensionClaim, shareGate, usableBy, } from "./ownership.js";
-import { PlatformComponents } from "./platform-components.js";
-import { PLATFORM_MIGRATION_JOB } from "./platform-migration.js";
+import { PlanStale, PlatformComponents } from "./platform-components.js";
 import { PluginPackageError, readPluginFiles, readPluginPackage, themeApiError, } from "./plugin-package.js";
 import { hasImportRequests, importRequestOf, resolveImportRequests } from "./request-rules.js";
 import { assertNameNotReserved } from "./reserved-names.js";
+import { oweScopeItem, SCOPE_BACKSTOP_DELAY, SCOPE_BACKSTOP_DELAY_MS } from "./scope-jobs.js";
 import { addScopeOrg } from "./scope-orgs.js";
 import { maxSatisfying, satisfiesRange } from "./versions.js";
-/** How long after a failed post-import platform sync the migration job runs for the item. */
-export const PLATFORM_SYNC_RETRY_MS = 60_000;
 /**
  * Platform import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
  * it contains (an extension, skills, connector templates, dependencies), confirmed once.
@@ -86,8 +83,10 @@ export const PLATFORM_SYNC_RETRY_MS = 60_000;
  * snapshot when it is installed or upgraded by this import (source web, audit
  * `extension.permissions_approved` carrying the plugin), and creates the item (with the scope the
  * admin chose, default `optional`) or adds the version (`manifest` = the normalized plugin.json,
- * `extension_sha256`, the files under the staging prefix). After the commit the plugin's own
- * extension is installed on the deployment and enabled (`ExtensionAdminOps.install` + `enable`;
+ * `extension_sha256`, the files under the staging prefix); an item's first usable version also
+ * gets its platform component rows there (their files copied before, keyed by content: a failure
+ * leaves nothing a retry copies again; no job heals an item later). After the commit the plugin's
+ * own extension is installed on the deployment and enabled (`ExtensionAdminOps.install` + `enable`;
  * each replica reconciles, no restart); a failure is returned, not thrown, and an upgrade that was
  * not installed gets its old snapshot back.
  *
@@ -164,8 +163,9 @@ let PluginImport = class PluginImport {
     log;
     txHost;
     platform;
-    maintenance;
     clientBuilds;
+    outbox;
+    backstopDelayMs;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -183,12 +183,14 @@ let PluginImport = class PluginImport {
     blobs, 
     /** Config-declared names, loaded connectors and extension versions (the extension registry). */
     registry, log, txHost, 
-    /** The platform rows of a new item's components, written after the confirm's commit. */
+    /** The platform rows of a new item's components, written in the confirm's transaction. */
     platform, 
-    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    maintenance, 
     /** The client build of a dropped org upload's package is deleted with it. */
-    clientBuilds) {
+    clientBuilds, 
+    /** The scope sync's backstop, owed by the confirm's commit (ruling R24). */
+    outbox, 
+    /** The backstop's delay (a test seam; default `SCOPE_BACKSTOP_DELAY_MS`). */
+    backstopDelayMs = SCOPE_BACKSTOP_DELAY_MS) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.orgLock = orgLock;
@@ -204,8 +206,9 @@ let PluginImport = class PluginImport {
         this.log = log;
         this.txHost = txHost;
         this.platform = platform;
-        this.maintenance = maintenance;
         this.clientBuilds = clientBuilds;
+        this.outbox = outbox;
+        this.backstopDelayMs = backstopDelayMs;
         this.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -734,11 +737,16 @@ let PluginImport = class PluginImport {
         const stored = reviewed && reviewed.action !== "keep" && owner === undefined
             ? await this.readStored(reviewed.sha256)
             : undefined;
+        // The platform components of the item's first usable version: planned and their files copied
+        // (keyed by content) before the transaction, their rows written in it
+        const prepared = staged.retry === true || (owner !== undefined && reviewed !== undefined)
+            ? undefined
+            : await this.prepareFirstVersion(staged, row.object_prefix, owner);
         const committed = await this.commit(actor, { stagingId, review, staged, src, manifest, objectPrefix: row.object_prefix }, {
             scope,
             orgs: [...new Set(orgs ?? [])].sort(),
             ...(owner !== undefined && { owner, shareable: input.shareable ?? false }),
-        }, stored, opts);
+        }, stored, opts, prepared);
         const { now } = committed;
         if (committed.pending) {
             // Waits for the super admin (P3-10): no platform components, nothing deployed
@@ -750,11 +758,6 @@ let PluginImport = class PluginImport {
                 firstVersion: false,
             };
         }
-        // A new item's skills, agent templates and connector templates become platform components
-        // (plugin scope phase 2); a new version of an existing item leaves them to the platform
-        // 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),
@@ -780,12 +783,31 @@ let PluginImport = class PluginImport {
         };
     }
     /**
-     * Writes the platform components of an item's first usable version after a commit made
-     * elsewhere (the super admin's confirmation of an org upload, `CatalogScopeService`); a failure
-     * is logged and retried by the migration job (see {@link syncPlatform}).
+     * The platform components of the staged version when its confirm will most likely make it the
+     * item's first usable version ({@link commit} decides under its locks): no live item of the name
+     * yet, or an org upload replacing its own first upload still awaiting confirmation. Planned from
+     * the staged content and their files copied, outside any transaction; otherwise undefined.
      */
-    async writePlatformComponents(itemId, version) {
-        await this.syncPlatform(itemId, version);
+    async prepareFirstVersion(staged, objectPrefix, owner) {
+        const live = await this.db
+            .selectFrom("catalog_items")
+            .select(["id", "awaiting_confirmation", "owner_org_id"])
+            .where("name", "=", staged.manifest.name)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const first = live === undefined ||
+            (owner !== undefined && live.awaiting_confirmation && live.owner_org_id === owner.orgId);
+        if (!first)
+            return undefined;
+        return this.platform.prepareImport({
+            itemId: live?.id ?? staged.itemId,
+            plugin: staged.manifest.name,
+            version: staged.version,
+            manifest: staged.manifest,
+            objectPrefix,
+            files: staged.files,
+            sourceFormat: staged.sourceFormat ?? "capybara",
+        });
     }
     /**
      * The confirm's transaction: the staging row consumed, the extension's action recomputed under
@@ -800,8 +822,15 @@ let PluginImport = class PluginImport {
      * upload without an extension for an item whose first version still waits (plan Task 6) replaces
      * that upload and applies at once: the item stops waiting and the claim is released (nothing
      * was installed under it).
+     *
+     * The item's first usable version (a new item not waiting, or an awaiting first upload replaced)
+     * writes the platform rows of its skills, agent templates, connector templates and themes
+     * (plugin scope phase 2) from `prepared` (their files copied before the transaction, keyed by
+     * content): a failure rolls the whole confirm back, and a retry copies nothing again. A plan made
+     * for another item or version, or a component changed since it -> `plugin.review_stale`. A new
+     * version of an existing item leaves them to the platform update.
      */
-    async commit(actor, c, scope, stored, opts) {
+    async commit(actor, c, scope, stored, opts, prepared) {
         const { stagingId, review, staged, src, manifest } = c;
         const reviewed = review.extension;
         const stale = () => reviewStale(review);
@@ -1034,61 +1063,44 @@ let PluginImport = class PluginImport {
             await markVersionApplied(t, itemId, staged.version);
             await releaseExtensionClaim(t, m.name, existing.package_name);
         }
+        const firstVersion = (created && !pending) || replacedAwaiting;
+        if (firstVersion) {
+            if (prepared?.plan.itemId !== itemId || prepared.plan.version !== staged.version) {
+                throw stale();
+            }
+            try {
+                await this.platform.applySyncIn(prepared);
+            }
+            catch (e) {
+                if (e instanceof PlanStale)
+                    throw stale();
+                throw e;
+            }
+        }
+        // The commit owes the scope sync's backstop (ruling R24) when the item's scope turns it on by
+        // itself: the caller owes the immediate sync after the deploy, which a crash may lose
+        if (!pending) {
+            const item = await t
+                .selectFrom("catalog_items")
+                .select("scope")
+                .where("id", "=", itemId)
+                .executeTakeFirstOrThrow();
+            if (item.scope !== "optional") {
+                await oweScopeItem(this.outbox, t, itemId, {
+                    backstop: true,
+                    backstopDelayMs: this.backstopDelayMs,
+                });
+            }
+        }
         return {
             itemId,
             created,
-            firstVersion: (created && !pending) || replacedAwaiting,
+            firstVersion,
             pending,
             now,
             previous,
         };
     }
-    /**
-     * The platform components of a new item. The item is committed already, so a failure is logged
-     * and not thrown (like a failed deploy, the import itself succeeded); a run of the platform
-     * components migration job (which writes what is missing) is enqueued on `cap-kernel-maintenance`
-     * after {@link PLATFORM_SYNC_RETRY_MS}, one per item (deterministic job id). If that run fails
-     * too, its `itemsFailed` shows in the super admin's inbox; the daily run and every worker start
-     * try again.
-     */
-    async syncPlatform(itemId, version) {
-        try {
-            await this.platform.syncFromVersion(itemId, version, { initial: true });
-        }
-        catch (err) {
-            // Removed meanwhile (an org deletion racing a confirmation, P3-20): nothing to write
-            const live = await this.db
-                .selectFrom("catalog_items")
-                .select("id")
-                .where("id", "=", itemId)
-                .where("deleted_at", "is", null)
-                .executeTakeFirst();
-            if (live === undefined) {
-                this.log.info("catalog item removed before its platform components were written", {
-                    itemId,
-                    version,
-                });
-                return;
-            }
-            this.log.error("writing the platform components of a new catalog item failed", {
-                itemId,
-                version,
-                err,
-            });
-            try {
-                await this.maintenance.add(PLATFORM_MIGRATION_JOB, {}, {
-                    jobId: `${PLATFORM_MIGRATION_JOB}-retry-${itemId}`,
-                    delay: PLATFORM_SYNC_RETRY_MS,
-                    attempts: 1,
-                    removeOnComplete: true,
-                    removeOnFail: { age: 86_400 },
-                });
-            }
-            catch (e) {
-                this.log.warn("cannot enqueue the platform components migration", { itemId, err: e });
-            }
-        }
-    }
     /**
      * Writes the extension's permission snapshot for the version being imported (source web; cli
      * without an actor; bootstrap for the bootstrap step), after
@@ -1727,8 +1739,10 @@ PluginImport = __decorate([
     __param(13, Inject(KERNEL_LOGGER)),
     __param(14, Inject(TransactionHost)),
     __param(15, Inject(PlatformComponents)),
-    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
-    __param(17, Inject(ClientBuilds))
+    __param(16, Inject(ClientBuilds)),
+    __param(17, Inject(OutboxService)),
+    __param(18, Optional()),
+    __param(18, Inject(SCOPE_BACKSTOP_DELAY))
 ], PluginImport);
 export { PluginImport };
 /**

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

@@ -178,14 +178,14 @@ export type UpdateTarget = VersionRow;
  *   the extension first (`ExtensionAdminOps.install`, enabled when the update installs it; added
  *   permissions wait for the admin's approval as for any extension upgrade), then one transaction
  *   under the item name's lock that recomputes the diff (`plugin.upgrade_stale` on a difference)
- *   and writes the platform versions (`PlatformComponents.syncFromVersion`, which records
+ *   and writes the platform versions (`PlatformComponents.applySyncIn`, which records
  *   `platform_synced_version`), the removals (a component no agent uses is soft-deleted, so
  *   unpinned linked copies go with it; pinned copies keep their own version; a removed connector
  *   template leaves its connectors as the orgs' own), clears the pins of linked copies, fans
  *   changed templates out to every connector made from them (`applyTemplateIn`, under each org's
  *   row lock, credentials cleared only for a changed credential shape), moves every org install to the version and audits
- *   `plugin.platform_updated`; the scope sync of the item and its dependencies is enqueued after
- *   the commit (orgs get new dependencies by rule 9). A failure rolls the transaction back and
+ *   `plugin.platform_updated`; the scope sync of the item and its dependencies is owed in that
+ *   transaction (orgs get new dependencies by rule 9). A failure rolls the transaction back and
  *   puts the extension back where it was (audit `plugin.platform_update_failed`, 502
  *   `plugin.upgrade_failed`); files copied to `deployment/platform/` stay unreferenced.
  * Storage is never read or written inside the transaction: the target's contents (and the
@@ -363,7 +363,7 @@ export declare class PlatformPluginUpdater {
     /**
      * Other platform plugins depending on this one must accept the target (their platform version's
      * dependency range); returns the catalog items of the target's own dependencies (their scope
-     * sync is enqueued after the update: rule 9).
+     * sync is owed with the update: rule 9).
      */
     private checkDependents;
     /** The plugin's live platform components with their current versions. */

package/dist/catalog/plugin-upgrade.js

@@ -26,7 +26,6 @@ import { audit } from "../identity/audit.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
 import { addOrgNotice, itemDisplayName, notifySharedUpdate } from "../inbox/org-notices.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
-import { afterCommit } from "../infra/database/after-commit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
@@ -105,14 +104,14 @@ const filesDigest = (row) => skillFilesDigest(row.files.map((f) => ({ path: f.pa
  *   the extension first (`ExtensionAdminOps.install`, enabled when the update installs it; added
  *   permissions wait for the admin's approval as for any extension upgrade), then one transaction
  *   under the item name's lock that recomputes the diff (`plugin.upgrade_stale` on a difference)
- *   and writes the platform versions (`PlatformComponents.syncFromVersion`, which records
+ *   and writes the platform versions (`PlatformComponents.applySyncIn`, which records
  *   `platform_synced_version`), the removals (a component no agent uses is soft-deleted, so
  *   unpinned linked copies go with it; pinned copies keep their own version; a removed connector
  *   template leaves its connectors as the orgs' own), clears the pins of linked copies, fans
  *   changed templates out to every connector made from them (`applyTemplateIn`, under each org's
  *   row lock, credentials cleared only for a changed credential shape), moves every org install to the version and audits
- *   `plugin.platform_updated`; the scope sync of the item and its dependencies is enqueued after
- *   the commit (orgs get new dependencies by rule 9). A failure rolls the transaction back and
+ *   `plugin.platform_updated`; the scope sync of the item and its dependencies is owed in that
+ *   transaction (orgs get new dependencies by rule 9). A failure rolls the transaction back and
  *   puts the extension back where it was (audit `plugin.platform_update_failed`, 502
  *   `plugin.upgrade_failed`); files copied to `deployment/platform/` stay unreferenced.
  * Storage is never read or written inside the transaction: the target's contents (and the
@@ -669,20 +668,9 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
                 ...opts.auditDetail,
             },
         });
-        const enqueue = [itemId, ...diff.dependencies];
-        afterCommit(async () => {
-            for (const id of enqueue) {
-                try {
-                    await this.sync.enqueueItem(id);
-                }
-                catch (err) {
-                    this.log.warn("enqueueing the scope sync after a platform update failed", {
-                        itemId: id,
-                        err,
-                    });
-                }
-            }
-        });
+        // The scope sync of the item and its dependencies is owed with the update (outbox spec §8.1)
+        for (const id of [itemId, ...diff.dependencies])
+            await this.sync.enqueueItem(id);
         return diff;
     }
     /**
@@ -1340,7 +1328,7 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
     /**
      * Other platform plugins depending on this one must accept the target (their platform version's
      * dependency range); returns the catalog items of the target's own dependencies (their scope
-     * sync is enqueued after the update: rule 9).
+     * sync is owed with the update: rule 9).
      */
     async checkDependents(name, to) {
         const rows = await this.db

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

@@ -0,0 +1,59 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { OutboxService } from "../infra/outbox/outbox.service.js";
+/**
+ * The plugin scope sync's jobs as the outbox owes them (transactional outbox spec §8.1): a leaf
+ * module (type imports only), so the import confirm (`PluginImport`, below the scope service) and
+ * the CLI owe them without the sync. `scope-sync.ts` (the consumer side) re-exports these names.
+ */
+/** 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";
+/**
+ * The delayed backstop of an item job owed by a confirmation's commit (ruling R24): it converges
+ * the item as {@link SCOPE_ITEM_JOB} does once the extension is deployed, and fails (BullMQ
+ * retries it with its backoff) while the extension is not enabled on the deployment yet.
+ */
+export declare const SCOPE_BACKSTOP_JOB = "scope-item-backstop";
+/** How long after the confirmation's commit the backstop runs (the deploy has finished by then). */
+export declare const SCOPE_BACKSTOP_DELAY_MS: number;
+/**
+ * Optional provider (a test seam): the backstop's delay (ms) instead of
+ * {@link SCOPE_BACKSTOP_DELAY_MS}, so a long test file never has a backstop fire in a later test.
+ */
+export declare const SCOPE_BACKSTOP_DELAY: unique symbol;
+/** One item job per scope version (no `:`: item ids are UUIDs). */
+export declare const scopeItemJobId: (itemId: string, version: number) => string;
+/** The backstop of the item job of a scope version (distinct from the immediate one). */
+export declare const scopeBackstopJobId: (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;
+/**
+ * The job's data. `retry`: the item job's delayed retry number (P3-38). `backstop`: a
+ * {@link SCOPE_BACKSTOP_JOB}.
+ */
+export type ScopeJob = {
+    kind: "item";
+    itemId: string;
+    retry?: number;
+    backstop?: true;
+} | {
+    kind: "org";
+    orgId: string;
+};
+/**
+ * Owes the item's scope sync in the transaction in context, once per scope version (read in that
+ * transaction, so after its own bump); `backstop` owes the delayed backstop instead, due
+ * `backstopDelayMs` later (default {@link SCOPE_BACKSTOP_DELAY_MS}). A missing item owes nothing.
+ */
+export declare function oweScopeItem(outbox: Pick<OutboxService, "add">, db: KernelSchemaDb, itemId: string, opts?: {
+    backstop?: boolean;
+    backstopDelayMs?: number;
+}): Promise<void>;

package/dist/catalog/scope-jobs.js

@@ -0,0 +1,65 @@
+/**
+ * The plugin scope sync's jobs as the outbox owes them (transactional outbox spec §8.1): a leaf
+ * module (type imports only), so the import confirm (`PluginImport`, below the scope service) and
+ * the CLI owe them without the sync. `scope-sync.ts` (the consumer side) re-exports these names.
+ */
+/** 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";
+/**
+ * The delayed backstop of an item job owed by a confirmation's commit (ruling R24): it converges
+ * the item as {@link SCOPE_ITEM_JOB} does once the extension is deployed, and fails (BullMQ
+ * retries it with its backoff) while the extension is not enabled on the deployment yet.
+ */
+export const SCOPE_BACKSTOP_JOB = "scope-item-backstop";
+/** How long after the confirmation's commit the backstop runs (the deploy has finished by then). */
+export const SCOPE_BACKSTOP_DELAY_MS = 5 * 60_000;
+/**
+ * Optional provider (a test seam): the backstop's delay (ms) instead of
+ * {@link SCOPE_BACKSTOP_DELAY_MS}, so a long test file never has a backstop fire in a later test.
+ */
+export const SCOPE_BACKSTOP_DELAY = Symbol("SCOPE_BACKSTOP_DELAY");
+/** One item job per scope version (no `:`: item ids are UUIDs). */
+export const scopeItemJobId = (itemId, version) => `scope-item-${itemId}-${version}`;
+/** The backstop of the item job of a scope version (distinct from the immediate one). */
+export const scopeBackstopJobId = (itemId, version) => `${scopeItemJobId(itemId, version)}-backstop`;
+/** 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}`;
+/**
+ * Owes the item's scope sync in the transaction in context, once per scope version (read in that
+ * transaction, so after its own bump); `backstop` owes the delayed backstop instead, due
+ * `backstopDelayMs` later (default {@link SCOPE_BACKSTOP_DELAY_MS}). A missing item owes nothing.
+ */
+export async function oweScopeItem(outbox, db, itemId, opts = {}) {
+    const row = await db
+        .selectFrom("catalog_items")
+        .select("scope_version")
+        .where("id", "=", itemId)
+        .executeTakeFirst();
+    if (!row)
+        return;
+    if (opts.backstop === true) {
+        await outbox.add({
+            queue: PLUGIN_SCOPE_QUEUE,
+            name: SCOPE_BACKSTOP_JOB,
+            jobId: scopeBackstopJobId(itemId, row.scope_version),
+            data: { kind: "item", itemId, backstop: true },
+            runAt: new Date(Date.now() + (opts.backstopDelayMs ?? SCOPE_BACKSTOP_DELAY_MS)),
+        });
+        return;
+    }
+    await outbox.add({
+        queue: PLUGIN_SCOPE_QUEUE,
+        name: SCOPE_ITEM_JOB,
+        jobId: scopeItemJobId(itemId, row.scope_version),
+        data: { kind: "item", itemId },
+    });
+}

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

@@ -1,3 +1,25 @@
+import { WorkerHost } from "@nestjs/bullmq";
+import type { Job, Worker } from "bullmq";
+import type { KernelLogger } from "../log.js";
+import { PluginScopeSync, type ScopeJob } from "./scope-sync.js";
+/**
+ * The consumer of {@link PLUGIN_SCOPE_QUEUE}: {@link PluginScopeSync} runs the `scope-item`,
+ * `scope-item-backstop` and `scope-org` jobs the outbox delivers (any other name fails the job; a
+ * backstop whose extension is not deployed yet throws, so BullMQ retries it).
+ */
+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;
+    /** Stops between pairs and closes the worker. */
+    close(): Promise<void>;
+    failed(job: Job<ScopeJob> | undefined, err: Error): void;
+    error(err: Error): void;
+}
 /**
  * The plugin scope queue's consumer: {@link PluginScopeSyncProcessor}. Imported only by the worker
  * role (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by

package/dist/catalog/scope-sync-workers.js

@@ -4,10 +4,66 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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;
 };
-import { Module } from "@nestjs/common";
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
 import { configuredProcessor } from "../infra/queue/configured-processor.js";
+import { runJob } from "../infra/queue/run-job.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { CatalogModule } from "./catalog.module.js";
-import { PLUGIN_SCOPE_CONCURRENCY, PLUGIN_SCOPE_QUEUE, PluginScopeSyncProcessor, } from "./scope-sync.js";
+import { PLUGIN_SCOPE_CONCURRENCY, PLUGIN_SCOPE_QUEUE, PluginScopeSync, SCOPE_BACKSTOP_JOB, SCOPE_ITEM_JOB, SCOPE_ORG_JOB, } from "./scope-sync.js";
+/**
+ * The consumer of {@link PLUGIN_SCOPE_QUEUE}: {@link PluginScopeSync} runs the `scope-item`,
+ * `scope-item-backstop` and `scope-org` jobs the outbox delivers (any other name fails the job; a
+ * backstop whose extension is not deployed yet throws, so BullMQ retries it).
+ */
+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, () => {
+            if (![SCOPE_ITEM_JOB, SCOPE_BACKSTOP_JOB, SCOPE_ORG_JOB].includes(job.name)) {
+                throw new Error(`unknown plugin scope job ${job.name}`);
+            }
+            return 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));
+    }
+    /** 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 };
 /**
  * The plugin scope queue's consumer: {@link PluginScopeSyncProcessor}. Imported only by the worker
  * role (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by