@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-host-collections.js

@@ -0,0 +1,116 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_HOST_COLLECTIONS = definePluginServiceContract('core.host-collections', {
+    multiple: true
+});
+/**
+ * Declares the host subcollections the registering plugin owns. The owner is
+ * the loader's marker when a register fn is running, else `options.pluginId`;
+ * with neither the registration throws. A collection another plugin declared
+ * throws naming both, and nothing in the same call is registered — a
+ * declaration is one plugin's statement about its own storage, so half of it
+ * landing would be worse than none.
+ */ export function registerPluginHostCollections(collections, options) {
+    var _ref, _getRegisteringPluginId;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    const prepared = collections.map((declaration)=>{
+        var _ref;
+        var _declaration_name, _declaration_mediaScanReason;
+        const name = (_ref = (_declaration_name = declaration.name) == null ? void 0 : _declaration_name.trim()) != null ? _ref : '';
+        if (!name) throw new Error('a host collection needs a name');
+        if (declaration.mediaScan === 'none' && !((_declaration_mediaScanReason = declaration.mediaScanReason) == null ? void 0 : _declaration_mediaScanReason.trim())) {
+            throw new Error(`host collection "${name}" is not scanned for media and says no ` + 'reason: mediaScanReason has to name what scanning would cost, or ' + 'what it would get wrong');
+        }
+        const incumbent = resolvePluginServices(PLUGIN_HOST_COLLECTIONS).find((entry)=>entry.key === name);
+        if (incumbent && pluginId && incumbent.pluginId !== pluginId) {
+            throw new Error(`host collection "${name}" is already declared by ` + `"${incumbent.pluginId}"; refused "${pluginId}"`);
+        }
+        return _extends({}, declaration, {
+            name
+        });
+    });
+    for (const declaration of prepared){
+        registerPluginService(PLUGIN_HOST_COLLECTIONS, declaration, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+            pluginId: options.pluginId
+        } : {}, {
+            key: declaration.name
+        }));
+    }
+}
+/** Every declared collection, with its owner, in registration order. */ export function listPluginHostCollections() {
+    return resolvePluginServices(PLUGIN_HOST_COLLECTIONS).map((entry)=>_extends({}, entry.impl, {
+            pluginId: entry.pluginId
+        }));
+}
+/** One declared collection by name, with its owner, or `null`. */ export function pluginHostCollection(name) {
+    const key = name.trim();
+    const entry = resolvePluginServices(PLUGIN_HOST_COLLECTIONS).find((one)=>one.key === key);
+    return entry ? _extends({}, entry.impl, {
+        pluginId: entry.pluginId
+    }) : null;
+}
+/** The plugin that owns a collection, or `undefined` when none declares it. */ export function pluginIdForHostCollection(name) {
+    var _pluginHostCollection;
+    return (_pluginHostCollection = pluginHostCollection(name)) == null ? void 0 : _pluginHostCollection.pluginId;
+}
+/**
+ * The console hub slug a reference row for this collection links to, or
+ * `undefined` when the owner routes none.
+ */ export function pluginHostCollectionRouteSlug(name) {
+    var _pluginHostCollection;
+    return (_pluginHostCollection = pluginHostCollection(name)) == null ? void 0 : _pluginHostCollection.routeSlug;
+}
+/**
+ * The declared collections the media scan reads generically — the list the
+ * scan walks, in place of one core keeps by hand.
+ */ export function pluginHostCollectionsScannedGenerically() {
+    return listPluginHostCollections().filter((one)=>{
+        var _one_mediaScan;
+        return ((_one_mediaScan = one.mediaScan) != null ? _one_mediaScan : 'generic') === 'generic';
+    }).map((one)=>one.name);
+}
+/** The declared collections the scan does not read, with the reason given. */ export function pluginHostCollectionsExcludedFromMediaScan() {
+    return listPluginHostCollections().filter((one)=>one.mediaScan === 'none').map((one)=>{
+        var _one_mediaScanReason;
+        return {
+            name: one.name,
+            reason: (_one_mediaScanReason = one.mediaScanReason) != null ? _one_mediaScanReason : '',
+            pluginId: one.pluginId
+        };
+    });
+}
+/** The declared collections whose documents the site's artifact counters total. */ export function pluginHostArtifactCollections() {
+    return listPluginHostCollections().filter((one)=>one.artifact === true).map((one)=>one.name);
+}
+/**
+ * What to call one of a collection's documents in a reference row: the
+ * declared label, else derived from the name — `productCategories` reads as
+ * "Product category". Singularized with the two rules English spells
+ * consistently enough to automate; anything else keeps its name, which is a
+ * cosmetic miss rather than a coverage one.
+ */ export function pluginHostCollectionLabel(name) {
+    var _pluginHostCollection_label, _pluginHostCollection;
+    const declared = (_pluginHostCollection = pluginHostCollection(name)) == null ? void 0 : (_pluginHostCollection_label = _pluginHostCollection.label) == null ? void 0 : _pluginHostCollection_label.trim();
+    if (declared) return declared;
+    const singular = /ies$/.test(name) ? name.replace(/ies$/, 'y') : /(ss|s)$/.test(name) ? name.replace(/s$/, '') : name;
+    const spaced = singular.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+//# sourceMappingURL=plugin-host-collections.js.map

package/src/lib/plugin-manager/plugin-host-collections.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-host-collections.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * The host subcollections a plugin owns, declared by that plugin (AGL-3124).\n *\n * A first-party plugin writes ordinary documents under `hosts/{hostId}` with\n * the ordinary SDKs, and several core surfaces have to know which plugin owns\n * which of them: the media-usage scan decides what to read before an author\n * deletes an asset, a reference row deep-links to the console page that shows\n * one, and the artifact counters total what a site holds.\n *\n * Core answered all three by listing the collections and switching over plugin\n * ids — `services` and `resources` are bookings', `campaigns` and `experiments`\n * are marketing's, `functions`, `variables` and `actions` are logic's — which\n * is the platform holding a map of its plugins' storage. Every entry is also a\n * thing that can silently fall out of step: a plugin that ships a new\n * collection is invisible to all three until somebody remembers the list.\n *\n * So the plugin declares what it owns, once, and the three readers ask.\n *\n * ## What a declaration says, and what it deliberately does not\n *\n * A declaration names the collection, how the media scan should treat it, the\n * console slug a reference row links to, and whether a document in it is an\n * ARTIFACT the site's counters total beside screens and layouts. It does NOT\n * name fields: the scan flattens a document generically on purpose, and a\n * field list here would be the same staleness trap one level down.\n *\n * The media default is inherited from the scan's own rule and is the whole\n * reason that rule survives this move: **a collection is scanned unless its\n * declaration says why it is not.** A plugin that ships a media-bearing\n * collection is covered the day it lands rather than the day somebody\n * remembers it, and `mediaScan: 'none'` without a reason is refused — \"it\n * probably has no images in it\" is the guess the scan's design exists to\n * avoid making.\n *\n * ## One collection, one owner\n *\n * Two plugins writing one collection under one site would be two schemas in\n * one place, and the scan, the deep link and the counters would each pick a\n * winner by registration order. So a collection another plugin declared is\n * refused naming both, and the incumbent keeps it; the same plugin declaring\n * again replaces its own.\n *\n * Reached by its own subpath rather than through `plugin-manager/index.ts`:\n * the readers are the media scan, the console counters and the reference\n * rows, none of which a published page renders.\n */\n\n/** How the media-usage scan reads a collection. */\nexport type PluginHostCollectionMediaScan =\n  /** Flattened and searched generically, with no per-collection decoder. */\n  | 'generic'\n  /** Read by a pass that knows its shape, the way screens and layouts are. */\n  | 'own'\n  /** Not read; {@link PluginHostCollectionDeclaration.mediaScanReason} says why. */\n  | 'none'\n\nexport interface PluginHostCollectionDeclaration {\n  /** The subcollection under `hosts/{hostId}`, spelled as Firestore holds it. */\n  name: string\n  /**\n   * What one of its documents is called in a reference row. Derived from the\n   * collection name when absent, so a new collection reads correctly without\n   * a second list to keep in step.\n   */\n  label?: string\n  /** Default `generic` — see this module's note on why the default is to scan. */\n  mediaScan?: PluginHostCollectionMediaScan\n  /**\n   * Why the scan does not read it. Required with `mediaScan: 'none'`, and it\n   * has to answer what scanning would COST or what it would get WRONG.\n   */\n  mediaScanReason?: string\n  /**\n   * The `[pluginSlug]` segment of the plugin's console hub, for a reference\n   * row's deep link. Optional on purpose: a row with no destination still\n   * renders as text, which is better than the row not existing.\n   */\n  routeSlug?: string\n  /**\n   * Whether a document here is a live ARTIFACT — something the site's own\n   * counters total beside its screens, layouts, components and templates.\n   */\n  artifact?: boolean\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginHostCollection = PluginHostCollectionDeclaration & {\n  pluginId: string\n}\n\nexport const PLUGIN_HOST_COLLECTIONS =\n  definePluginServiceContract<PluginHostCollectionDeclaration>(\n    'core.host-collections',\n    { multiple: true },\n  )\n\n/**\n * Declares the host subcollections the registering plugin owns. The owner is\n * the loader's marker when a register fn is running, else `options.pluginId`;\n * with neither the registration throws. A collection another plugin declared\n * throws naming both, and nothing in the same call is registered — a\n * declaration is one plugin's statement about its own storage, so half of it\n * landing would be worse than none.\n */\nexport function registerPluginHostCollections(\n  collections: readonly PluginHostCollectionDeclaration[],\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const prepared = collections.map((declaration) => {\n    const name = declaration.name?.trim() ?? ''\n    if (!name) throw new Error('a host collection needs a name')\n    if (declaration.mediaScan === 'none' && !declaration.mediaScanReason?.trim()) {\n      throw new Error(\n        `host collection \"${name}\" is not scanned for media and says no ` +\n          'reason: mediaScanReason has to name what scanning would cost, or ' +\n          'what it would get wrong',\n      )\n    }\n    const incumbent = resolvePluginServices(PLUGIN_HOST_COLLECTIONS).find(\n      (entry) => entry.key === name,\n    )\n    if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n      throw new Error(\n        `host collection \"${name}\" is already declared by ` +\n          `\"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n      )\n    }\n    return { ...declaration, name }\n  })\n  for (const declaration of prepared) {\n    registerPluginService(PLUGIN_HOST_COLLECTIONS, declaration, {\n      ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n      key: declaration.name,\n    })\n  }\n}\n\n/** Every declared collection, with its owner, in registration order. */\nexport function listPluginHostCollections(): ResolvedPluginHostCollection[] {\n  return resolvePluginServices(PLUGIN_HOST_COLLECTIONS).map((entry) => ({\n    ...entry.impl,\n    pluginId: entry.pluginId,\n  }))\n}\n\n/** One declared collection by name, with its owner, or `null`. */\nexport function pluginHostCollection(\n  name: string,\n): ResolvedPluginHostCollection | null {\n  const key = name.trim()\n  const entry = resolvePluginServices(PLUGIN_HOST_COLLECTIONS).find(\n    (one) => one.key === key,\n  )\n  return entry ? { ...entry.impl, pluginId: entry.pluginId } : null\n}\n\n/** The plugin that owns a collection, or `undefined` when none declares it. */\nexport function pluginIdForHostCollection(name: string): string | undefined {\n  return pluginHostCollection(name)?.pluginId\n}\n\n/**\n * The console hub slug a reference row for this collection links to, or\n * `undefined` when the owner routes none.\n */\nexport function pluginHostCollectionRouteSlug(\n  name: string,\n): string | undefined {\n  return pluginHostCollection(name)?.routeSlug\n}\n\n/**\n * The declared collections the media scan reads generically — the list the\n * scan walks, in place of one core keeps by hand.\n */\nexport function pluginHostCollectionsScannedGenerically(): string[] {\n  return listPluginHostCollections()\n    .filter((one) => (one.mediaScan ?? 'generic') === 'generic')\n    .map((one) => one.name)\n}\n\n/** The declared collections the scan does not read, with the reason given. */\nexport function pluginHostCollectionsExcludedFromMediaScan(): Array<{\n  name: string\n  reason: string\n  pluginId: string\n}> {\n  return listPluginHostCollections()\n    .filter((one) => one.mediaScan === 'none')\n    .map((one) => ({\n      name: one.name,\n      reason: one.mediaScanReason ?? '',\n      pluginId: one.pluginId,\n    }))\n}\n\n/** The declared collections whose documents the site's artifact counters total. */\nexport function pluginHostArtifactCollections(): string[] {\n  return listPluginHostCollections()\n    .filter((one) => one.artifact === true)\n    .map((one) => one.name)\n}\n\n/**\n * What to call one of a collection's documents in a reference row: the\n * declared label, else derived from the name — `productCategories` reads as\n * \"Product category\". Singularized with the two rules English spells\n * consistently enough to automate; anything else keeps its name, which is a\n * cosmetic miss rather than a coverage one.\n */\nexport function pluginHostCollectionLabel(name: string): string {\n  const declared = pluginHostCollection(name)?.label?.trim()\n  if (declared) return declared\n  const singular = /ies$/.test(name)\n    ? name.replace(/ies$/, 'y')\n    : /(ss|s)$/.test(name)\n      ? name.replace(/s$/, '')\n      : name\n  const spaced = singular.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase()\n  return spaced.charAt(0).toUpperCase() + spaced.slice(1)\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_HOST_COLLECTIONS","multiple","registerPluginHostCollections","collections","options","pluginId","trim","prepared","map","declaration","name","Error","mediaScan","mediaScanReason","incumbent","find","entry","key","listPluginHostCollections","impl","pluginHostCollection","one","pluginIdForHostCollection","pluginHostCollectionRouteSlug","routeSlug","pluginHostCollectionsScannedGenerically","filter","pluginHostCollectionsExcludedFromMediaScan","reason","pluginHostArtifactCollections","artifact","pluginHostCollectionLabel","declared","label","singular","test","replace","spaced","toLowerCase","charAt","toUpperCase","slice"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-jobs.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Plugin scheduled jobs (AGL-435, Strapi cron parity): `/server` entries
+ * register named jobs with an interval; a guarded platform runner route
+ * (`/api/plugins/run-jobs`, secret header, invoked by the deployment's
+ * scheduler) executes the due ones. The REGISTRY is pure — due-ness and
+ * last-run persistence belong to the runner, so core stays storage-free.
+ * Handlers must be idempotent and bounded (they share the API process).
+ */
+/**
+ * The one question a beat asks before touching a host: is a lock active that
+ * forbids this write? Resolved by the host app, never by core.
+ */
+export type PluginJobHostLockedResolver = (hostId: string) => Promise<boolean> | boolean;
+/**
+ * Registers the platform's per-host lockdown verdict for background work,
+ * from a place that may import the admin data lib — on this platform,
+ * `apps/tenant/utils/plugin-job-lockdown.ts`, loaded for its side effect by
+ * the runner route beside the core job registrations.
+ *
+ * Idempotent and last-registration-wins, unlike `registerOrderFulfilmentService`
+ * next door: that one holds a capability with a plugin OWNER, where a second
+ * claimant is a misconfiguration. This is infrastructure the deployment
+ * supplies exactly once, and a process that loads the module twice must not
+ * throw on the second pass.
+ */
+export declare function registerPluginJobHostLockdown(resolver: PluginJobHostLockedResolver): void;
+/** Has the deployment wired a verdict? Reported by the runner route. */
+export declare function hasPluginJobHostLockdown(): boolean;
+/** Test seam: forget the registration. */
+export declare function resetPluginJobHostLockdownForTests(): void;
+/**
+ * The gate handed to a `per-host` job. One method, so there is exactly one
+ * thing to call and one thing for the coverage guard to look for:
+ *
+ *   if (await gate.isLocked(hostId)) continue
+ *
+ * SKIPPED, NOT DROPPED is the caller's obligation and the reason this
+ * answers a question rather than performing the skip: `continue` leaves the
+ * row exactly as it was, so the work lands on the next beat after the lift.
+ * A gate that swallowed the row — stamping it done, deleting it, advancing a
+ * cursor past it — would turn a pause into a cancellation, which is what
+ * `publish-schedule-job.ts` argued at length and what every job here copies.
+ */
+export interface PluginJobHostGate {
+    isLocked(hostId: string): Promise<boolean>;
+}
+/**
+ * The gate as the runner builds it. Exported because the MANUAL doors —
+ * `commerce/process-abandoned`, `bookings/reminders` and the other
+ * `x-cron-secret` entry points that still exist for ops — call the same scan
+ * functions and must ask the same question. A forced pass is still a pass.
+ *
+ * NO resolver registered answers "not locked", loudly and once. That is the
+ * fail-open direction on purpose: a deployment that has not wired a carrier
+ * (a self-host, a test process) must not have every background job welded
+ * shut by infrastructure it never asked for. The loss is real and is why
+ * `hasPluginJobHostLockdown` is reported by the runner route rather than
+ * left to be inferred from nothing happening.
+ */
+export declare function pluginJobHostGate(): PluginJobHostGate;
+/** Test seam: let the "warned once" latch be re-armed. */
+export declare function resetPluginJobLockdownWarningForTests(): void;
+/**
+ * What a job touches, and therefore what the runner owes it. REQUIRED on
+ * every registration — the point of the field is that a new job cannot
+ * compile without its author answering.
+ */
+export type PluginJobLockdown = 
+/**
+ * The job acts FOR HOSTS. The runner injects a {@link PluginJobHostGate}
+ * and the handler must ask it for every host it is about to touch.
+ */
+{
+    scope: 'per-host';
+}
+/**
+ * The job touches nothing a lock could be about. `reason` is the argument,
+ * and `lockdown-tenant-api-coverage.spec.ts` holds the set by name so a new
+ * one has to be argued rather than declared.
+ */
+ | {
+    scope: 'platform';
+    reason: string;
+};
+export interface PluginJob {
+    pluginId: string;
+    /** Stable job name, unique within the plugin ('expire-stale-holds'). */
+    name: string;
+    intervalMinutes: number;
+    description?: string;
+    /** See {@link PluginJobLockdown}. Required, deliberately. */
+    lockdown: PluginJobLockdown;
+    handler: (gate: PluginJobHostGate) => Promise<void> | void;
+}
+export declare const pluginJobKey: (job: Pick<PluginJob, "pluginId" | "name">) => string;
+/** Idempotent per pluginId:name. */
+export declare function registerPluginJob(job: PluginJob): void;
+export declare function listPluginJobs(): PluginJob[];
+export interface PluginJobResult {
+    key: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Runs the jobs `due` selects (default: all), sequentially with error
+ * isolation — one broken job never blocks the rest.
+ *
+ * Every handler is handed a {@link PluginJobHostGate} (AGL-2495). It is a
+ * parameter rather than something the handler imports so that the runner
+ * stays the single place the verdict comes from: swap what
+ * `registerPluginJobHostLockdown` holds and every job on the beat changes
+ * behaviour together, including one written next month.
+ */
+export declare function runPluginJobs(due?: (job: PluginJob) => boolean): Promise<PluginJobResult[]>;

package/src/lib/plugin-manager/plugin-jobs.js

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Plugin scheduled jobs (AGL-435, Strapi cron parity): `/server` entries
+ * register named jobs with an interval; a guarded platform runner route
+ * (`/api/plugins/run-jobs`, secret header, invoked by the deployment's
+ * scheduler) executes the due ones. The REGISTRY is pure — due-ness and
+ * last-run persistence belong to the runner, so core stays storage-free.
+ * Handlers must be idempotent and bounded (they share the API process).
+ */ /*==========================================
+ * THE LOCKDOWN GATE FOR BACKGROUND WORK (AGL-2495, from the AGL-1621 drill).
+ *
+ * A job runs on PLATFORM credentials, from a secret-gated route, with no
+ * visitor, no session and no org — so none of the gates that cover the
+ * visitor-facing write paths are anywhere near it. That is exactly the shape
+ * the drill found in `publish-schedule-job.ts`: a scheduled publish firing on
+ * a locked host. The commerce and bookings beats are the sharper version of
+ * the same thing, because they touch orders, stock and money for a host that
+ * may be suspended for abuse, non-payment or a legal takedown.
+ *
+ * ## Why the gate lives HERE and not at the six call sites
+ *
+ * Six call-site edits close six holes and guarantee the seventh is forgotten.
+ * Gating in the job contract means the seventh job is covered the day it is
+ * written: `lockdown` below is REQUIRED, so a new `registerPluginJob({…})`
+ * does not compile until its author has answered "what does this touch".
+ *
+ * (The nx boundary is NOT why. `libs/plugins/*` CAN import
+ * `@aglyn/tenant-data-admin` — it carries `scope:data` and `scope:aglyn`,
+ * both on the `aglyn:addons` allowlist, and 196 files in `libs/plugins`
+ * already do. The AGL-2495 sweep recorded the opposite as its reason for
+ * deferring; it was wrong about the constraint and right about the design.)
+ *
+ * ## Why core cannot just call `getSiteLockdown` itself
+ *
+ * `@aglyn/tenant-data-admin` imports `@aglyn/aglyn/server`, so a core import
+ * of it is a project CYCLE. Hence the same registry shape the platform uses
+ * for every other app↔core edge (`registerOrderFulfilmentService`,
+ * `registerBillingWebhookHandler`, `registerSitePageResolver`): the host app
+ * registers the resolver from a place that may import the admin lib, and core
+ * looks it up. Nothing is imported statically in either direction and a
+ * self-host build with a different carrier registers its own.
+ *
+ * ## Fail-open is INHERITED, not re-decided
+ *
+ * The gate asks whatever the app registered — on the tenant that is
+ * `getSiteLockdown`, which owns the fail-open/fail-closed decision (and the
+ * takedown-class ratchet on top of it). This module deliberately holds no
+ * parallel notion of what a lock is: it has one question and no opinion.
+ *=========================================*/ /**
+ * The one question a beat asks before touching a host: is a lock active that
+ * forbids this write? Resolved by the host app, never by core.
+ */ let hostLockedResolver = null;
+/**
+ * Registers the platform's per-host lockdown verdict for background work,
+ * from a place that may import the admin data lib — on this platform,
+ * `apps/tenant/utils/plugin-job-lockdown.ts`, loaded for its side effect by
+ * the runner route beside the core job registrations.
+ *
+ * Idempotent and last-registration-wins, unlike `registerOrderFulfilmentService`
+ * next door: that one holds a capability with a plugin OWNER, where a second
+ * claimant is a misconfiguration. This is infrastructure the deployment
+ * supplies exactly once, and a process that loads the module twice must not
+ * throw on the second pass.
+ */ export function registerPluginJobHostLockdown(resolver) {
+    hostLockedResolver = resolver;
+}
+/** Has the deployment wired a verdict? Reported by the runner route. */ export function hasPluginJobHostLockdown() {
+    return hostLockedResolver !== null;
+}
+/** Test seam: forget the registration. */ export function resetPluginJobHostLockdownForTests() {
+    hostLockedResolver = null;
+}
+/**
+ * The gate as the runner builds it. Exported because the MANUAL doors —
+ * `commerce/process-abandoned`, `bookings/reminders` and the other
+ * `x-cron-secret` entry points that still exist for ops — call the same scan
+ * functions and must ask the same question. A forced pass is still a pass.
+ *
+ * NO resolver registered answers "not locked", loudly and once. That is the
+ * fail-open direction on purpose: a deployment that has not wired a carrier
+ * (a self-host, a test process) must not have every background job welded
+ * shut by infrastructure it never asked for. The loss is real and is why
+ * `hasPluginJobHostLockdown` is reported by the runner route rather than
+ * left to be inferred from nothing happening.
+ */ export function pluginJobHostGate() {
+    return {
+        isLocked: async (hostId)=>{
+            if (!hostId) return false;
+            if (!hostLockedResolver) {
+                warnMissingResolver();
+                return false;
+            }
+            return await hostLockedResolver(hostId) === true;
+        }
+    };
+}
+let warnedMissingResolver = false;
+function warnMissingResolver() {
+    if (warnedMissingResolver) return;
+    warnedMissingResolver = true;
+    console.error('[plugin-jobs] no host lockdown resolver is registered — background ' + 'jobs are running UNGATED. Register one with ' + 'registerPluginJobHostLockdown() from the app that owns the runner.');
+}
+/** Test seam: let the "warned once" latch be re-armed. */ export function resetPluginJobLockdownWarningForTests() {
+    warnedMissingResolver = false;
+}
+const jobs = new Map();
+export const pluginJobKey = (job)=>`${job.pluginId}:${job.name}`;
+/** Idempotent per pluginId:name. */ export function registerPluginJob(job) {
+    jobs.set(pluginJobKey(job), job);
+}
+export function listPluginJobs() {
+    return [
+        ...jobs.values()
+    ];
+}
+/**
+ * The gate a `platform`-scoped job gets: one that REFUSES to answer.
+ *
+ * A declaration of `platform` scope is a claim that there is no host to ask
+ * about. If such a job asks anyway, the claim is false and the registration
+ * is the thing that needs fixing — so the runner surfaces it as that job's
+ * own failure (isolated, like every other job error) instead of quietly
+ * answering "not locked" and letting a mislabelled job mutate a locked site.
+ *
+ * This is the one place the contract is enforced at RUNTIME rather than by
+ * the type or by the guard, and it is enforceable precisely because asking
+ * is the only way to get an answer.
+ */ function refusingGate(key) {
+    return {
+        isLocked: async (hostId)=>{
+            throw new Error(`plugin job ${key} declared lockdown scope 'platform' but asked ` + `about host "${hostId}". Declare { scope: 'per-host' } instead.`);
+        }
+    };
+}
+/**
+ * Runs the jobs `due` selects (default: all), sequentially with error
+ * isolation — one broken job never blocks the rest.
+ *
+ * Every handler is handed a {@link PluginJobHostGate} (AGL-2495). It is a
+ * parameter rather than something the handler imports so that the runner
+ * stays the single place the verdict comes from: swap what
+ * `registerPluginJobHostLockdown` holds and every job on the beat changes
+ * behaviour together, including one written next month.
+ */ export async function runPluginJobs(due) {
+    const results = [];
+    for (const job of jobs.values()){
+        if (due && !due(job)) continue;
+        const key = pluginJobKey(job);
+        try {
+            var _job_lockdown;
+            await job.handler(((_job_lockdown = job.lockdown) == null ? void 0 : _job_lockdown.scope) === 'platform' ? refusingGate(key) : pluginJobHostGate());
+            results.push({
+                key,
+                ok: true
+            });
+        } catch (error) {
+            console.error(`plugin job ${key} failed:`, error);
+            results.push({
+                key,
+                ok: false,
+                error: String(error)
+            });
+        }
+    }
+    return results;
+}
+
+//# sourceMappingURL=plugin-jobs.js.map

package/src/lib/plugin-manager/plugin-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-jobs.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Plugin scheduled jobs (AGL-435, Strapi cron parity): `/server` entries\n * register named jobs with an interval; a guarded platform runner route\n * (`/api/plugins/run-jobs`, secret header, invoked by the deployment's\n * scheduler) executes the due ones. The REGISTRY is pure — due-ness and\n * last-run persistence belong to the runner, so core stays storage-free.\n * Handlers must be idempotent and bounded (they share the API process).\n */\n\n/*==========================================\n * THE LOCKDOWN GATE FOR BACKGROUND WORK (AGL-2495, from the AGL-1621 drill).\n *\n * A job runs on PLATFORM credentials, from a secret-gated route, with no\n * visitor, no session and no org — so none of the gates that cover the\n * visitor-facing write paths are anywhere near it. That is exactly the shape\n * the drill found in `publish-schedule-job.ts`: a scheduled publish firing on\n * a locked host. The commerce and bookings beats are the sharper version of\n * the same thing, because they touch orders, stock and money for a host that\n * may be suspended for abuse, non-payment or a legal takedown.\n *\n * ## Why the gate lives HERE and not at the six call sites\n *\n * Six call-site edits close six holes and guarantee the seventh is forgotten.\n * Gating in the job contract means the seventh job is covered the day it is\n * written: `lockdown` below is REQUIRED, so a new `registerPluginJob({…})`\n * does not compile until its author has answered \"what does this touch\".\n *\n * (The nx boundary is NOT why. `libs/plugins/*` CAN import\n * `@aglyn/tenant-data-admin` — it carries `scope:data` and `scope:aglyn`,\n * both on the `aglyn:addons` allowlist, and 196 files in `libs/plugins`\n * already do. The AGL-2495 sweep recorded the opposite as its reason for\n * deferring; it was wrong about the constraint and right about the design.)\n *\n * ## Why core cannot just call `getSiteLockdown` itself\n *\n * `@aglyn/tenant-data-admin` imports `@aglyn/aglyn/server`, so a core import\n * of it is a project CYCLE. Hence the same registry shape the platform uses\n * for every other app↔core edge (`registerOrderFulfilmentService`,\n * `registerBillingWebhookHandler`, `registerSitePageResolver`): the host app\n * registers the resolver from a place that may import the admin lib, and core\n * looks it up. Nothing is imported statically in either direction and a\n * self-host build with a different carrier registers its own.\n *\n * ## Fail-open is INHERITED, not re-decided\n *\n * The gate asks whatever the app registered — on the tenant that is\n * `getSiteLockdown`, which owns the fail-open/fail-closed decision (and the\n * takedown-class ratchet on top of it). This module deliberately holds no\n * parallel notion of what a lock is: it has one question and no opinion.\n *=========================================*/\n\n/**\n * The one question a beat asks before touching a host: is a lock active that\n * forbids this write? Resolved by the host app, never by core.\n */\nexport type PluginJobHostLockedResolver = (\n  hostId: string,\n) => Promise<boolean> | boolean\n\nlet hostLockedResolver: PluginJobHostLockedResolver | null = null\n\n/**\n * Registers the platform's per-host lockdown verdict for background work,\n * from a place that may import the admin data lib — on this platform,\n * `apps/tenant/utils/plugin-job-lockdown.ts`, loaded for its side effect by\n * the runner route beside the core job registrations.\n *\n * Idempotent and last-registration-wins, unlike `registerOrderFulfilmentService`\n * next door: that one holds a capability with a plugin OWNER, where a second\n * claimant is a misconfiguration. This is infrastructure the deployment\n * supplies exactly once, and a process that loads the module twice must not\n * throw on the second pass.\n */\nexport function registerPluginJobHostLockdown(\n  resolver: PluginJobHostLockedResolver,\n): void {\n  hostLockedResolver = resolver\n}\n\n/** Has the deployment wired a verdict? Reported by the runner route. */\nexport function hasPluginJobHostLockdown(): boolean {\n  return hostLockedResolver !== null\n}\n\n/** Test seam: forget the registration. */\nexport function resetPluginJobHostLockdownForTests(): void {\n  hostLockedResolver = null\n}\n\n/**\n * The gate handed to a `per-host` job. One method, so there is exactly one\n * thing to call and one thing for the coverage guard to look for:\n *\n *   if (await gate.isLocked(hostId)) continue\n *\n * SKIPPED, NOT DROPPED is the caller's obligation and the reason this\n * answers a question rather than performing the skip: `continue` leaves the\n * row exactly as it was, so the work lands on the next beat after the lift.\n * A gate that swallowed the row — stamping it done, deleting it, advancing a\n * cursor past it — would turn a pause into a cancellation, which is what\n * `publish-schedule-job.ts` argued at length and what every job here copies.\n */\nexport interface PluginJobHostGate {\n  isLocked(hostId: string): Promise<boolean>\n}\n\n/**\n * The gate as the runner builds it. Exported because the MANUAL doors —\n * `commerce/process-abandoned`, `bookings/reminders` and the other\n * `x-cron-secret` entry points that still exist for ops — call the same scan\n * functions and must ask the same question. A forced pass is still a pass.\n *\n * NO resolver registered answers \"not locked\", loudly and once. That is the\n * fail-open direction on purpose: a deployment that has not wired a carrier\n * (a self-host, a test process) must not have every background job welded\n * shut by infrastructure it never asked for. The loss is real and is why\n * `hasPluginJobHostLockdown` is reported by the runner route rather than\n * left to be inferred from nothing happening.\n */\nexport function pluginJobHostGate(): PluginJobHostGate {\n  return {\n    isLocked: async (hostId: string) => {\n      if (!hostId) return false\n      if (!hostLockedResolver) {\n        warnMissingResolver()\n        return false\n      }\n      return (await hostLockedResolver(hostId)) === true\n    },\n  }\n}\n\nlet warnedMissingResolver = false\nfunction warnMissingResolver(): void {\n  if (warnedMissingResolver) return\n  warnedMissingResolver = true\n  console.error(\n    '[plugin-jobs] no host lockdown resolver is registered — background ' +\n      'jobs are running UNGATED. Register one with ' +\n      'registerPluginJobHostLockdown() from the app that owns the runner.',\n  )\n}\n\n/** Test seam: let the \"warned once\" latch be re-armed. */\nexport function resetPluginJobLockdownWarningForTests(): void {\n  warnedMissingResolver = false\n}\n\n/**\n * What a job touches, and therefore what the runner owes it. REQUIRED on\n * every registration — the point of the field is that a new job cannot\n * compile without its author answering.\n */\nexport type PluginJobLockdown =\n  /**\n   * The job acts FOR HOSTS. The runner injects a {@link PluginJobHostGate}\n   * and the handler must ask it for every host it is about to touch.\n   */\n  | { scope: 'per-host' }\n  /**\n   * The job touches nothing a lock could be about. `reason` is the argument,\n   * and `lockdown-tenant-api-coverage.spec.ts` holds the set by name so a new\n   * one has to be argued rather than declared.\n   */\n  | { scope: 'platform'; reason: string }\n\nexport interface PluginJob {\n  pluginId: string\n  /** Stable job name, unique within the plugin ('expire-stale-holds'). */\n  name: string\n  intervalMinutes: number\n  description?: string\n  /** See {@link PluginJobLockdown}. Required, deliberately. */\n  lockdown: PluginJobLockdown\n  handler: (gate: PluginJobHostGate) => Promise<void> | void\n}\n\nconst jobs = new Map<string, PluginJob>()\n\nexport const pluginJobKey = (job: Pick<PluginJob, 'pluginId' | 'name'>) =>\n  `${job.pluginId}:${job.name}`\n\n/** Idempotent per pluginId:name. */\nexport function registerPluginJob(job: PluginJob): void {\n  jobs.set(pluginJobKey(job), job)\n}\n\nexport function listPluginJobs(): PluginJob[] {\n  return [...jobs.values()]\n}\n\nexport interface PluginJobResult {\n  key: string\n  ok: boolean\n  error?: string\n}\n\n/**\n * The gate a `platform`-scoped job gets: one that REFUSES to answer.\n *\n * A declaration of `platform` scope is a claim that there is no host to ask\n * about. If such a job asks anyway, the claim is false and the registration\n * is the thing that needs fixing — so the runner surfaces it as that job's\n * own failure (isolated, like every other job error) instead of quietly\n * answering \"not locked\" and letting a mislabelled job mutate a locked site.\n *\n * This is the one place the contract is enforced at RUNTIME rather than by\n * the type or by the guard, and it is enforceable precisely because asking\n * is the only way to get an answer.\n */\nfunction refusingGate(key: string): PluginJobHostGate {\n  return {\n    isLocked: async (hostId: string) => {\n      throw new Error(\n        `plugin job ${key} declared lockdown scope 'platform' but asked ` +\n          `about host \"${hostId}\". Declare { scope: 'per-host' } instead.`,\n      )\n    },\n  }\n}\n\n/**\n * Runs the jobs `due` selects (default: all), sequentially with error\n * isolation — one broken job never blocks the rest.\n *\n * Every handler is handed a {@link PluginJobHostGate} (AGL-2495). It is a\n * parameter rather than something the handler imports so that the runner\n * stays the single place the verdict comes from: swap what\n * `registerPluginJobHostLockdown` holds and every job on the beat changes\n * behaviour together, including one written next month.\n */\nexport async function runPluginJobs(\n  due?: (job: PluginJob) => boolean,\n): Promise<PluginJobResult[]> {\n  const results: PluginJobResult[] = []\n  for (const job of jobs.values()) {\n    if (due && !due(job)) continue\n    const key = pluginJobKey(job)\n    try {\n      await job.handler(\n        job.lockdown?.scope === 'platform'\n          ? refusingGate(key)\n          : pluginJobHostGate(),\n      )\n      results.push({ key, ok: true })\n    } catch (error) {\n      console.error(`plugin job ${key} failed:`, error)\n      results.push({ key, ok: false, error: String(error) })\n    }\n  }\n  return results\n}\n"],"names":["hostLockedResolver","registerPluginJobHostLockdown","resolver","hasPluginJobHostLockdown","resetPluginJobHostLockdownForTests","pluginJobHostGate","isLocked","hostId","warnMissingResolver","warnedMissingResolver","console","error","resetPluginJobLockdownWarningForTests","jobs","Map","pluginJobKey","job","pluginId","name","registerPluginJob","set","listPluginJobs","values","refusingGate","key","Error","runPluginJobs","due","results","handler","lockdown","scope","push","ok","String"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;CAOC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAwC2C,GAE3C;;;CAGC,GAKD,IAAIA,qBAAyD;AAE7D;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,8BACdC,QAAqC;IAErCF,qBAAqBE;AACvB;AAEA,sEAAsE,GACtE,OAAO,SAASC;IACd,OAAOH,uBAAuB;AAChC;AAEA,wCAAwC,GACxC,OAAO,SAASI;IACdJ,qBAAqB;AACvB;AAmBA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASK;IACd,OAAO;QACLC,UAAU,OAAOC;YACf,IAAI,CAACA,QAAQ,OAAO;YACpB,IAAI,CAACP,oBAAoB;gBACvBQ;gBACA,OAAO;YACT;YACA,OAAO,AAAC,MAAMR,mBAAmBO,YAAa;QAChD;IACF;AACF;AAEA,IAAIE,wBAAwB;AAC5B,SAASD;IACP,IAAIC,uBAAuB;IAC3BA,wBAAwB;IACxBC,QAAQC,KAAK,CACX,wEACE,iDACA;AAEN;AAEA,wDAAwD,GACxD,OAAO,SAASC;IACdH,wBAAwB;AAC1B;AA+BA,MAAMI,OAAO,IAAIC;AAEjB,OAAO,MAAMC,eAAe,CAACC,MAC3B,GAAGA,IAAIC,QAAQ,CAAC,CAAC,EAAED,IAAIE,IAAI,EAAE,CAAA;AAE/B,kCAAkC,GAClC,OAAO,SAASC,kBAAkBH,GAAc;IAC9CH,KAAKO,GAAG,CAACL,aAAaC,MAAMA;AAC9B;AAEA,OAAO,SAASK;IACd,OAAO;WAAIR,KAAKS,MAAM;KAAG;AAC3B;AAQA;;;;;;;;;;;;CAYC,GACD,SAASC,aAAaC,GAAW;IAC/B,OAAO;QACLlB,UAAU,OAAOC;YACf,MAAM,IAAIkB,MACR,CAAC,WAAW,EAAED,IAAI,8CAA8C,CAAC,GAC/D,CAAC,YAAY,EAAEjB,OAAO,yCAAyC,CAAC;QAEtE;IACF;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,eAAemB,cACpBC,GAAiC;IAEjC,MAAMC,UAA6B,EAAE;IACrC,KAAK,MAAMZ,OAAOH,KAAKS,MAAM,GAAI;QAC/B,IAAIK,OAAO,CAACA,IAAIX,MAAM;QACtB,MAAMQ,MAAMT,aAAaC;QACzB,IAAI;gBAEAA;YADF,MAAMA,IAAIa,OAAO,CACfb,EAAAA,gBAAAA,IAAIc,QAAQ,qBAAZd,cAAce,KAAK,MAAK,aACpBR,aAAaC,OACbnB;YAENuB,QAAQI,IAAI,CAAC;gBAAER;gBAAKS,IAAI;YAAK;QAC/B,EAAE,OAAOtB,OAAO;YACdD,QAAQC,KAAK,CAAC,CAAC,WAAW,EAAEa,IAAI,QAAQ,CAAC,EAAEb;YAC3CiB,QAAQI,IAAI,CAAC;gBAAER;gBAAKS,IAAI;gBAAOtB,OAAOuB,OAAOvB;YAAO;QACtD;IACF;IACA,OAAOiB;AACT"}

package/src/lib/plugin-manager/plugin-loader.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Dynamic plugin activation (AGL-417). Apps never import @aglyn/plugins-*;
+ * they hand this loader a GENERATED manifest of `() => import(...)` thunks
+ * (see tools/scripts/generate-plugin-manifests.mjs) and activate plugins at
+ * runtime from `org.enabledPlugins` (AGL-416). Loading is cached per
+ * entry+surface and registration per entry+surface+use, and `ensure` returns
+ * a stable promise per (ids, surfaces, use) so React `use()` can suspend on
+ * it during SSR — the canvas never renders before its components are
+ * registered (the blank-canvas invariant, AGL-52).
+ */
+export interface PluginLoadEntry {
+    /** Stable plugin id — matches FIRST_PARTY_PLUGINS / org.enabledPlugins. */
+    id: string;
+    /** Loaded regardless of the org switchboard (base components). */
+    alwaysOn?: boolean;
+    /** `/api/<prefix>/...` paths this plugin's handlers own (server gate). */
+    apiPrefixes?: string[];
+    /** surface → exported register-fn name on the loaded module. */
+    register: Partial<Record<string, string>>;
+    load: () => Promise<Record<string, unknown>>;
+    /**
+     * The module a surface loads from, when it is not `load`'s (AGL-3116).
+     *
+     * A package entry imported with `import()` is a namespace the loader reads
+     * by name, so the bundler keeps every export it has: a site surface loaded
+     * from the package root carried the console registrar, its nav objects and
+     * its lazy pages onto every published page that used the plugin. A surface
+     * with a module of its own carries only what that module exports.
+     */
+    loads?: Partial<Record<string, () => Promise<Record<string, unknown>>>>;
+    /**
+     * What this plugin declares it contributes, and where (AGL-3142).
+     *
+     * The loader never reads it: `ensure` is told which plugins to activate and
+     * activates them. It rides on the entry because the manifest is the one list
+     * of plugins an app holds, and an app that loads by presence has to answer
+     * "which of these belongs on this screen" before it names any ids — from
+     * data, not by running a plugin, which is the cost being avoided.
+     *
+     * Written into a manifest whose app reads it and left off the others: the
+     * published page decides presence from the nodes it places, so the tenant
+     * manifest would carry a declaration nothing there consults.
+     */
+    contributes?: PluginContributions;
+}
+export type PluginLoadManifest = readonly PluginLoadEntry[];
+export interface PluginLoader {
+    /**
+     * Loads + registers the given plugins' surfaces. `ids` may include unknown
+     * ids (marketplace realm plugins — ignored here); manifest entries marked
+     * alwaysOn activate regardless of `ids`.
+     *
+     * `use` is what the surface actually uses (AGL-3141), carried unchanged to
+     * every register function: the page computes it, the loader carries it, a
+     * plugin reads it or ignores it. Omitting it asks for everything, which is
+     * what a surface that cannot narrow must do.
+     *
+     * A surface registers once per plugin per use context. A second page that
+     * places a component the first did not still reaches the plugin, so the
+     * element it added has a component to render (AGL-52); one whose use is
+     * already covered costs nothing.
+     */
+    ensure(ids: readonly string[], surfaces: readonly string[], use?: PluginUse): Promise<void>;
+    /** Every manifest plugin, for `ensureAll` semantics (server dispatchers). */
+    ensureAll(surfaces: readonly string[]): Promise<void>;
+    /** The plugin owning an api path ('bookings/slots' → 'bookings'). */
+    pluginIdForApiPath(path: string): string | undefined;
+}
+import type { PluginContributions, PluginUse } from './plugin-contributions';
+export declare function createPluginLoader(manifest: PluginLoadManifest): PluginLoader;