@aglyn/aglyn 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/plugin-manager/plugin-domain-events.js

@@ -0,0 +1,148 @@
+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";
+const EVENT_NAME = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9_]*)+$/;
+/**
+ * A token for one event name: lower-case words joined by dots, the first
+ * naming what the event is about (`order.paid`, `return.requested`).
+ */ export function definePluginDomainEvent(id) {
+    const name = String(id != null ? id : '').trim();
+    if (!EVENT_NAME.test(name)) {
+        throw new Error(`plugin event name "${id}" must be dotted lower-case words, e.g. "order.paid"`);
+    }
+    return {
+        id: name
+    };
+}
+const REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-domain-events');
+const globalScope = globalThis;
+function registry() {
+    if (!globalScope[REGISTRY_KEY]) {
+        globalScope[REGISTRY_KEY] = {
+            declarations: new Map(),
+            subscriptions: new Map()
+        };
+    }
+    return globalScope[REGISTRY_KEY];
+}
+const nameOf = (event)=>typeof event === 'string' ? event : event.id;
+function ownerOf(kind, name, options) {
+    var _ref, _getRegisteringPluginId;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`plugin event "${name}" ${kind} with no owner: pass { pluginId } outside a plugin register fn`);
+    }
+    return pluginId;
+}
+/**
+ * Declares the events a plugin raises. One plugin owns a name: a second
+ * plugin declaring it throws, so two plugins cannot raise one event with two
+ * payloads. The owner declaring again replaces its entry.
+ */ export function declarePluginDomainEvents(declarations, options) {
+    for (const declaration of declarations){
+        var _declaration_payloadKeys;
+        const name = nameOf(declaration.event);
+        if (!EVENT_NAME.test(name)) {
+            throw new Error(`plugin event name "${name}" must be dotted lower-case words`);
+        }
+        const pluginId = ownerOf('declared', name, options);
+        const existing = registry().declarations.get(name);
+        if (existing && existing.pluginId !== pluginId) {
+            throw new Error(`plugin event "${name}" is already declared by "${existing.pluginId}"; "${pluginId}" cannot declare it too`);
+        }
+        registry().declarations.set(name, {
+            pluginId,
+            event: name,
+            label: declaration.label,
+            description: declaration.description,
+            payloadKeys: [
+                ...(_declaration_payloadKeys = declaration.payloadKeys) != null ? _declaration_payloadKeys : []
+            ]
+        });
+    }
+}
+/** Every declared event, sorted by name. */ export function listPluginDomainEvents() {
+    return [
+        ...registry().declarations.values()
+    ].sort((a, b)=>a.event.localeCompare(b.event));
+}
+/** The declaration of one event, or `null` when no plugin declares it. */ export function pluginDomainEventDeclaration(event) {
+    var _registry_declarations_get;
+    return (_registry_declarations_get = registry().declarations.get(event)) != null ? _registry_declarations_get : null;
+}
+/**
+ * Subscribes to an event. A subscriber subscribing again to the same event
+ * replaces its earlier handler, so a module evaluated twice delivers once.
+ *
+ * The subscriber is named by plugin id, or `pluginId:name` when a plugin
+ * subscribes more than one handler to an event (its webhooks and its
+ * workflow triggers, say) — and that name is what the outbox records as
+ * delivered, so it must be stable.
+ */ export function subscribePluginDomainEvent(event, handler, options) {
+    var _registry_subscriptions_get;
+    const name = nameOf(event);
+    const owner = ownerOf('subscribed', name, options);
+    const pluginId = (options == null ? void 0 : options.name) ? `${owner}:${options.name}` : owner;
+    const list = ((_registry_subscriptions_get = registry().subscriptions.get(name)) != null ? _registry_subscriptions_get : []).filter((entry)=>entry.pluginId !== pluginId);
+    list.push({
+        pluginId,
+        handler: handler
+    });
+    registry().subscriptions.set(name, list);
+}
+/** The plugins subscribed to an event, in subscription order. */ export function listPluginDomainEventSubscribers(event) {
+    var _registry_subscriptions_get;
+    return ((_registry_subscriptions_get = registry().subscriptions.get(event)) != null ? _registry_subscriptions_get : []).map((entry)=>entry.pluginId);
+}
+/**
+ * Hands an envelope to every subscriber not in `skip`, one after another. A
+ * throw is caught and reported and does not stop the others. The outbox
+ * drain calls this; a raiser never does.
+ */ export async function deliverPluginDomainEvent(envelope, options = {}) {
+    var _registry_subscriptions_get;
+    const result = {
+        delivered: [],
+        failed: []
+    };
+    for (const { pluginId, handler } of (_registry_subscriptions_get = registry().subscriptions.get(envelope.event)) != null ? _registry_subscriptions_get : []){
+        var _options_skip;
+        if ((_options_skip = options.skip) == null ? void 0 : _options_skip.has(pluginId)) continue;
+        try {
+            var _ref;
+            var _options_attempts;
+            await handler(_extends({}, envelope, {
+                attempt: ((_ref = (_options_attempts = options.attempts) == null ? void 0 : _options_attempts[pluginId]) != null ? _ref : 0) + 1
+            }));
+            result.delivered.push(pluginId);
+        } catch (error) {
+            var _ref1;
+            const message = String((_ref1 = error == null ? void 0 : error.message) != null ? _ref1 : error).slice(0, 500);
+            result.failed.push({
+                pluginId,
+                error: message
+            });
+            console.error(`[plugin-events] ${pluginId} failed on ${envelope.event} ${envelope.id}`, error);
+        }
+    }
+    return result;
+}
+/** Test seam: forget every declaration and subscription. */ export function resetPluginDomainEventsForTests() {
+    registry().declarations.clear();
+    registry().subscriptions.clear();
+}
+
+//# sourceMappingURL=plugin-domain-events.js.map

package/src/lib/plugin-manager/plugin-domain-events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-domain-events.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'\n\n/**\n * Events a PLUGIN raises for other plugins (AGL-3611).\n *\n * `plugin-events.ts` carries the platform's own facts — a seat add-on, a paid\n * invoice — with payloads core declares. This is the same idea for facts\n * that belong to a plugin: one plugin declares an event and its payload,\n * raises it when the thing happens, and any other plugin subscribes by the\n * event's name without importing the plugin that raises it. Core names\n * nothing a plugin raises.\n *\n * DELIVERY IS RELIABLE, NOT FIRE-AND-FORGET. Raising an event writes an\n * outbox document (`plugin-event-outbox.ts` in the admin data lib), in the\n * same transaction as the write it reports where the raiser has one, and a\n * scheduled drain hands it to each subscriber in turn. A subscriber that\n * throws is retried with backoff, alone: the ones that already took the\n * event are not called again. Delivery is AT LEAST ONCE, so every envelope\n * carries `id`, stable across retries, for a subscriber to dedupe on.\n *\n * TYPED BY TOKEN. `definePluginDomainEvent<Payload>(name)` gives the raiser\n * and a subscriber the same payload type; a subscriber in another plugin\n * restates the shape it reads and defines its own token under the same\n * name, as a widget restates a zone's props.\n *\n * The registry lives on `globalThis` (AGL-3412): subscriptions register from\n * the plugins' server declarations at boot, in a module graph the routes and\n * the job runner do not share.\n */\n\n/** A typed handle on one event name. */\nexport interface PluginDomainEvent<Payload> {\n  readonly id: string\n  /** Type-level only: the payload the event carries. */\n  readonly __payload?: Payload\n}\n\n/** The payload an event token carries. */\nexport type PluginDomainEventPayload<Event> = Event extends PluginDomainEvent<infer Payload>\n  ? Payload\n  : never\n\nconst EVENT_NAME = /^[a-z][a-zA-Z0-9]*(\\.[a-z][a-zA-Z0-9_]*)+$/\n\n/**\n * A token for one event name: lower-case words joined by dots, the first\n * naming what the event is about (`order.paid`, `return.requested`).\n */\nexport function definePluginDomainEvent<Payload>(id: string): PluginDomainEvent<Payload> {\n  const name = String(id ?? '').trim()\n  if (!EVENT_NAME.test(name)) {\n    throw new Error(`plugin event name \"${id}\" must be dotted lower-case words, e.g. \"order.paid\"`)\n  }\n  return { id: name }\n}\n\n/** How a plugin describes an event it raises, for pickers and the docs. */\nexport interface PluginDomainEventDeclaration {\n  event: PluginDomainEvent<unknown> | string\n  /** \"Order paid\". */\n  label: string\n  /** One sentence: when it is raised. */\n  description: string\n  /** The top-level payload keys, for a person writing a subscriber. */\n  payloadKeys?: readonly string[]\n}\n\n/** A declared event, with the plugin that raises it. */\nexport interface DeclaredPluginDomainEvent {\n  pluginId: string\n  event: string\n  label: string\n  description: string\n  payloadKeys: readonly string[]\n}\n\n/** What a subscriber is handed. */\nexport interface PluginDomainEventEnvelope<Payload = unknown> {\n  /** Stable across retries: the idempotency key for a subscriber. */\n  id: string\n  event: string\n  /** The site the event happened on. */\n  hostId: string\n  /** The site's org, when the raiser knew it. */\n  orgId: string | null\n  /** When the fact happened, not when it was delivered. */\n  occurredAtMs: number\n  /** 1 on the first delivery to this subscriber, then 2, 3, … */\n  attempt: number\n  payload: Payload\n}\n\nexport type PluginDomainEventHandler<Payload = unknown> = (\n  envelope: PluginDomainEventEnvelope<Payload>,\n) => void | Promise<void>\n\ninterface Subscription {\n  pluginId: string\n  handler: PluginDomainEventHandler<unknown>\n}\n\ninterface Registry {\n  declarations: Map<string, DeclaredPluginDomainEvent>\n  subscriptions: Map<string, Subscription[]>\n}\n\nconst REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-domain-events')\nconst globalScope = globalThis as typeof globalThis & { [REGISTRY_KEY]?: Registry }\n\nfunction registry(): Registry {\n  if (!globalScope[REGISTRY_KEY]) {\n    globalScope[REGISTRY_KEY] = { declarations: new Map(), subscriptions: new Map() }\n  }\n  return globalScope[REGISTRY_KEY] as Registry\n}\n\nconst nameOf = (event: PluginDomainEvent<unknown> | string): string =>\n  typeof event === 'string' ? event : event.id\n\nfunction ownerOf(kind: string, name: string, options?: { pluginId?: string }): string {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      `plugin event \"${name}\" ${kind} with no owner: pass { pluginId } outside a plugin register fn`,\n    )\n  }\n  return pluginId\n}\n\n/**\n * Declares the events a plugin raises. One plugin owns a name: a second\n * plugin declaring it throws, so two plugins cannot raise one event with two\n * payloads. The owner declaring again replaces its entry.\n */\nexport function declarePluginDomainEvents(\n  declarations: readonly PluginDomainEventDeclaration[],\n  options?: { pluginId?: string },\n): void {\n  for (const declaration of declarations) {\n    const name = nameOf(declaration.event)\n    if (!EVENT_NAME.test(name)) {\n      throw new Error(`plugin event name \"${name}\" must be dotted lower-case words`)\n    }\n    const pluginId = ownerOf('declared', name, options)\n    const existing = registry().declarations.get(name)\n    if (existing && existing.pluginId !== pluginId) {\n      throw new Error(\n        `plugin event \"${name}\" is already declared by \"${existing.pluginId}\"; \"${pluginId}\" cannot declare it too`,\n      )\n    }\n    registry().declarations.set(name, {\n      pluginId,\n      event: name,\n      label: declaration.label,\n      description: declaration.description,\n      payloadKeys: [...(declaration.payloadKeys ?? [])],\n    })\n  }\n}\n\n/** Every declared event, sorted by name. */\nexport function listPluginDomainEvents(): DeclaredPluginDomainEvent[] {\n  return [...registry().declarations.values()].sort((a, b) => a.event.localeCompare(b.event))\n}\n\n/** The declaration of one event, or `null` when no plugin declares it. */\nexport function pluginDomainEventDeclaration(event: string): DeclaredPluginDomainEvent | null {\n  return registry().declarations.get(event) ?? null\n}\n\n/**\n * Subscribes to an event. A subscriber subscribing again to the same event\n * replaces its earlier handler, so a module evaluated twice delivers once.\n *\n * The subscriber is named by plugin id, or `pluginId:name` when a plugin\n * subscribes more than one handler to an event (its webhooks and its\n * workflow triggers, say) — and that name is what the outbox records as\n * delivered, so it must be stable.\n */\nexport function subscribePluginDomainEvent<Payload>(\n  event: PluginDomainEvent<Payload> | string,\n  handler: PluginDomainEventHandler<Payload>,\n  options?: { pluginId?: string; name?: string },\n): void {\n  const name = nameOf(event as PluginDomainEvent<unknown> | string)\n  const owner = ownerOf('subscribed', name, options)\n  const pluginId = options?.name ? `${owner}:${options.name}` : owner\n  const list = (registry().subscriptions.get(name) ?? []).filter((entry) => entry.pluginId !== pluginId)\n  list.push({ pluginId, handler: handler as PluginDomainEventHandler<unknown> })\n  registry().subscriptions.set(name, list)\n}\n\n/** The plugins subscribed to an event, in subscription order. */\nexport function listPluginDomainEventSubscribers(event: string): string[] {\n  return (registry().subscriptions.get(event) ?? []).map((entry) => entry.pluginId)\n}\n\n/** What one delivery pass came to. */\nexport interface PluginDomainEventDeliveryResult {\n  /** Subscribers that took the event on this pass. */\n  delivered: string[]\n  /** Subscribers that threw, with what they said. */\n  failed: Array<{ pluginId: string; error: string }>\n}\n\n/**\n * Hands an envelope to every subscriber not in `skip`, one after another. A\n * throw is caught and reported and does not stop the others. The outbox\n * drain calls this; a raiser never does.\n */\nexport async function deliverPluginDomainEvent(\n  envelope: Omit<PluginDomainEventEnvelope, 'attempt'>,\n  options: { skip?: ReadonlySet<string>; attempts?: Readonly<Record<string, number>> } = {},\n): Promise<PluginDomainEventDeliveryResult> {\n  const result: PluginDomainEventDeliveryResult = { delivered: [], failed: [] }\n  for (const { pluginId, handler } of registry().subscriptions.get(envelope.event) ?? []) {\n    if (options.skip?.has(pluginId)) continue\n    try {\n      await handler({ ...envelope, attempt: (options.attempts?.[pluginId] ?? 0) + 1 })\n      result.delivered.push(pluginId)\n    } catch (error) {\n      const message = String((error as Error)?.message ?? error).slice(0, 500)\n      result.failed.push({ pluginId, error: message })\n      console.error(`[plugin-events] ${pluginId} failed on ${envelope.event} ${envelope.id}`, error)\n    }\n  }\n  return result\n}\n\n/** Test seam: forget every declaration and subscription. */\nexport function resetPluginDomainEventsForTests(): void {\n  registry().declarations.clear()\n  registry().subscriptions.clear()\n}\n"],"names":["getRegisteringPluginId","EVENT_NAME","definePluginDomainEvent","id","name","String","trim","test","Error","REGISTRY_KEY","Symbol","for","globalScope","globalThis","registry","declarations","Map","subscriptions","nameOf","event","ownerOf","kind","options","pluginId","declarePluginDomainEvents","declaration","existing","get","set","label","description","payloadKeys","listPluginDomainEvents","values","sort","a","b","localeCompare","pluginDomainEventDeclaration","subscribePluginDomainEvent","handler","owner","list","filter","entry","push","listPluginDomainEventSubscribers","map","deliverPluginDomainEvent","envelope","result","delivered","failed","skip","has","attempt","attempts","error","message","slice","console","resetPluginDomainEventsForTests","clear"],"mappings":"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"}

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

@@ -24,6 +24,10 @@
  * billing-webhook hooks are the precedent for one vendor's events; this is
  * the same shape for the platform's own.
  *
+ * Events a PLUGIN raises for other plugins — an order paid, a return
+ * refunded — are `plugin-domain-events.ts` (AGL-3611): declared by the plugin,
+ * delivered through an outbox, at least once.
+ *
  * Handlers run sequentially and are ISOLATED: a plugin that throws is
  * logged and the next one runs, because these are consequences of a write
  * that has already happened — an activity row, a notification — and a
@@ -129,6 +133,53 @@ export interface PluginEventPayloads {
             data: Readonly<Record<string, unknown>>;
         }>;
     };
+    /**
+     * A site's email was opened, or a link in it clicked (AGL-3605): the
+     * delivery events one webhook delivery recorded for a send tagged with the
+     * site, the FIRST of each type per message only — the delivery log decides
+     * which those are, so a replay or a reader opening one email six times is
+     * one event. Raised by the plugin whose webhook reads the provider, after
+     * the log has recorded them; a subscriber that counts engagement of its own
+     * reads it here rather than subscribing to the provider.
+     */
+    'host.email.engaged': {
+        hostId: string;
+        events: ReadonlyArray<{
+            /** The recipient, lowercased. */
+            to: string;
+            /** `opened` or `clicked`. */
+            type: string;
+            /** When it happened, epoch ms. */
+            at: number;
+            firstOfType: boolean;
+        }>;
+    };
+    /**
+     * A custom domain was connected to a site and the hosting provider accepted
+     * it (AGL-3629). Raised once the claim is written, so `domain` is the site's
+     * `cname` and no other site's. The site may still be awaiting a certificate
+     * or a DNS change; a plugin that needs the domain registered somewhere — a
+     * payment provider, a search console — does that now rather than waiting
+     * for traffic.
+     */
+    'host.domain.attached': {
+        orgId: string | null;
+        hostId: string;
+        domain: string;
+    };
+    /**
+     * A domain stopped serving a site (AGL-3629): its custom domain was
+     * disconnected, or the site was deleted — which releases its platform
+     * subdomain too, raised as a second event with that name. A plugin undoes
+     * whatever it registered for the name, and must check the name is not
+     * still served by ANOTHER site first (a `www.` twin, a reused subdomain).
+     */
+    'host.domain.released': {
+        orgId: string | null;
+        hostId: string;
+        domain: string;
+        reason: 'detached' | 'site-deleted';
+    };
     /** One permission key moved on a subject of the org. */
     'org.permissions.changed': {
         orgId: string;

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

@@ -23,6 +23,10 @@
  * billing-webhook hooks are the precedent for one vendor's events; this is
  * the same shape for the platform's own.
  *
+ * Events a PLUGIN raises for other plugins — an order paid, a return
+ * refunded — are `plugin-domain-events.ts` (AGL-3611): declared by the plugin,
+ * delivered through an outbox, at least once.
+ *
  * Handlers run sequentially and are ISOLATED: a plugin that throws is
  * logged and the next one runs, because these are consequences of a write
  * that has already happened — an activity row, a notification — and a

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-events.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 * Platform events a plugin listens to (AGL-2939, AGL-2940).\n *\n * Core raises a small number of facts about the workspace that a plugin\n * may care about — a seat add-on was bought or dropped, a permission key\n * moved on a member, a role or a site — and a plugin subscribes from its\n * declarations rather than core calling the plugin's own writer. The\n * billing-webhook hooks are the precedent for one vendor's events; this is\n * the same shape for the platform's own.\n *\n * Handlers run sequentially and are ISOLATED: a plugin that throws is\n * logged and the next one runs, because these are consequences of a write\n * that has already happened — an activity row, a notification — and a\n * failure in one must not undo or hide the write for the customer.\n */\n\nimport type { OrgSeatAddons } from '../foundation'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** Who did it, as the activity logs record an actor. */\nexport interface PluginEventActor {\n  uid: string | null\n  email: string | null\n}\n\n/** The payload each platform event carries. */\nexport interface PluginEventPayloads {\n  /** An org's purchased seat add-ons were written (a purchase, a removal, a webhook mirror). */\n  'org.seatAddons.changed': {\n    orgId: string\n    actor: PluginEventActor\n    before: OrgSeatAddons | null | undefined\n    after: OrgSeatAddons | null | undefined\n  }\n  /**\n   * The workspace's Stripe invoice was paid, in full, by a real charge.\n   *\n   * Raised from the platform billing webhook once the invoice has resolved\n   * to a workspace, so a plugin that bills its own usage learns the outcome\n   * of the invoice it asked for without subscribing to Stripe itself. The\n   * invoice's own `metadata` travels with it, unread by core: a plugin that\n   * stamped `pluginId` on the invoice it created recognizes its own by it,\n   * and every other handler ignores the event.\n   *\n   * `paidOutOfBand` is Stripe's own flag for an invoice marked paid without\n   * a charge. A plugin counting payment history must not count one: it is a\n   * staff action, not evidence that money moved.\n   */\n  'billing.invoice.paid': {\n    orgId: string\n    invoiceId: string\n    amountPaidCents: number\n    currency: string\n    paidOutOfBand: boolean\n    metadata: Readonly<Record<string, string>>\n  }\n  /** A charge attempt on the workspace's invoice failed or needs action. */\n  'billing.invoice.failed': {\n    orgId: string\n    invoiceId: string\n    amountDueCents: number\n    metadata: Readonly<Record<string, string>>\n  }\n  /**\n   * An invoice was closed without being paid — voided, or written off as\n   * uncollectible.\n   *\n   * ONE event for both Stripe events because they are one fact to a plugin:\n   * this invoice will never be paid and nothing more is owed on it. A\n   * handler that must tell them apart reads `reason`; one that only needs\n   * to stop waiting does not.\n   */\n  'billing.invoice.closed': {\n    orgId: string\n    invoiceId: string\n    reason: 'voided' | 'uncollectible'\n    metadata: Readonly<Record<string, string>>\n  }\n  /** A cardholder disputed a charge of the workspace's. */\n  'billing.dispute.opened': {\n    orgId: string\n    chargeId: string\n    invoiceId: string | null\n    amountCents: number\n  }\n  /**\n   * The workspace's default payment method changed, or its type did.\n   *\n   * `defaultType` is Stripe's own type string (`card`, `us_bank_account`,\n   * `link`, …), or `null` when the customer has no default. Core states the\n   * fact and takes no view: which types a plugin will extend credit against\n   * is the plugin's decision, not the platform's.\n   */\n  'billing.paymentMethod.changed': {\n    orgId: string\n    defaultType: string | null\n  }\n  /**\n   * Records were REMOVED from a collection, by a path that is not the\n   * owning plugin's own (AGL-3330): a deletion through the public API, a\n   * person's erasure.\n   *\n   * Raised after the delete has landed, with each removed document's data\n   * as it stood, so a plugin that keeps a figure over those rows — a counter\n   * no increment can take back — can recount what they fed. Core names the\n   * collection and takes no view of what it holds.\n   *\n   * `hostIds` are the sites the records were on: the one site for a site's\n   * collection, every site of the organization for an organization row.\n   */\n  'host.records.removed': {\n    orgId: string | null\n    hostIds: readonly string[]\n    collection: string\n    records: ReadonlyArray<{ id: string; data: Readonly<Record<string, unknown>> }>\n  }\n  /** One permission key moved on a subject of the org. */\n  'org.permissions.changed': {\n    orgId: string\n    actor: PluginEventActor\n    subject: {\n      type: 'org' | 'role' | 'member' | 'host'\n      id?: string | null\n      name?: string | null\n    }\n    permission: string\n    granted: boolean\n  }\n}\n\nexport type PluginEventName = keyof PluginEventPayloads\n\nexport type PluginEventHandler<E extends PluginEventName> = (\n  payload: PluginEventPayloads[E],\n) => void | Promise<void>\n\ninterface Registration {\n  pluginId: string\n  handler: PluginEventHandler<PluginEventName>\n}\n\nconst handlers = new Map<PluginEventName, Registration[]>()\n\n/**\n * Subscribes to an event. Owner = the loader's marker inside a register fn,\n * else `options.pluginId`; a subscription with neither throws. A plugin\n * re-subscribing replaces its earlier handler for that event, so a module\n * evaluated twice does not write two rows.\n */\nexport function registerPluginEventHandler<E extends PluginEventName>(\n  event: E,\n  handler: PluginEventHandler<E>,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      `plugin event \"${event}\" subscribed with no owner: pass { pluginId } ` +\n        'when subscribing outside a plugin register fn',\n    )\n  }\n  const list = (handlers.get(event) ?? []).filter((entry) => entry.pluginId !== pluginId)\n  list.push({ pluginId, handler: handler as PluginEventHandler<PluginEventName> })\n  handlers.set(event, list)\n}\n\n/**\n * Raises an event. Every handler runs, in subscription order; a throw is\n * logged with the plugin's id and does not stop the others.\n */\nexport async function runPluginEventHandlers<E extends PluginEventName>(\n  event: E,\n  payload: PluginEventPayloads[E],\n): Promise<{ handled: number; failed: string[] }> {\n  let handled = 0\n  const failed: string[] = []\n  for (const { pluginId, handler } of handlers.get(event) ?? []) {\n    try {\n      await handler(payload)\n      handled += 1\n    } catch (error) {\n      failed.push(pluginId)\n      console.error(`[plugins] ${pluginId} failed on event ${event}`, error)\n    }\n  }\n  return { handled, failed }\n}\n\n/** The plugins subscribed to an event, for diagnostics. */\nexport function listPluginEventHandlers(event: PluginEventName): string[] {\n  return (handlers.get(event) ?? []).map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every subscription. */\nexport function resetPluginEventHandlersForTests(): void {\n  handlers.clear()\n}\n"],"names":["getRegisteringPluginId","handlers","Map","registerPluginEventHandler","event","handler","options","pluginId","trim","Error","list","get","filter","entry","push","set","runPluginEventHandlers","payload","handled","failed","error","console","listPluginEventHandlers","map","resetPluginEventHandlersForTests","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;CAcC,GAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AA4HxE,MAAMC,WAAW,IAAIC;AAErB;;;;;CAKC,GACD,OAAO,SAASC,2BACdC,KAAQ,EACRC,OAA8B,EAC9BC,OAA+B;QAEbN,MAAAA,yBAOJC;IAPd,MAAMM,WAAW,EAACP,QAAAA,0BAAAA,oCAAAA,0BAA4BM,2BAAAA,QAASC,QAAQ,YAA7CP,OAAiD,IAAIQ,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,CAAC,cAAc,EAAEL,MAAM,8CAA8C,CAAC,GACpE;IAEN;IACA,MAAMM,OAAO,EAACT,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,EAAEW,MAAM,CAAC,CAACC,QAAUA,MAAMN,QAAQ,KAAKA;IAC9EG,KAAKI,IAAI,CAAC;QAAEP;QAAUF,SAASA;IAA+C;IAC9EJ,SAASc,GAAG,CAACX,OAAOM;AACtB;AAEA;;;CAGC,GACD,OAAO,eAAeM,uBACpBZ,KAAQ,EACRa,OAA+B;QAIKhB;IAFpC,IAAIiB,UAAU;IACd,MAAMC,SAAmB,EAAE;IAC3B,KAAK,MAAM,EAAEZ,QAAQ,EAAEF,OAAO,EAAE,KAAIJ,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,CAAE;QAC7D,IAAI;YACF,MAAMI,QAAQY;YACdC,WAAW;QACb,EAAE,OAAOE,OAAO;YACdD,OAAOL,IAAI,CAACP;YACZc,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEb,SAAS,iBAAiB,EAAEH,OAAO,EAAEgB;QAClE;IACF;IACA,OAAO;QAAEF;QAASC;IAAO;AAC3B;AAEA,yDAAyD,GACzD,OAAO,SAASG,wBAAwBlB,KAAsB;QACpDH;IAAR,OAAO,EAACA,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,EAAEsB,GAAG,CAAC,CAACV,QAAUA,MAAMN,QAAQ;AAClE;AAEA,0CAA0C,GAC1C,OAAO,SAASiB;IACdvB,SAASwB,KAAK;AAChB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-events.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 * Platform events a plugin listens to (AGL-2939, AGL-2940).\n *\n * Core raises a small number of facts about the workspace that a plugin\n * may care about — a seat add-on was bought or dropped, a permission key\n * moved on a member, a role or a site — and a plugin subscribes from its\n * declarations rather than core calling the plugin's own writer. The\n * billing-webhook hooks are the precedent for one vendor's events; this is\n * the same shape for the platform's own.\n *\n * Events a PLUGIN raises for other plugins — an order paid, a return\n * refunded — are `plugin-domain-events.ts` (AGL-3611): declared by the plugin,\n * delivered through an outbox, at least once.\n *\n * Handlers run sequentially and are ISOLATED: a plugin that throws is\n * logged and the next one runs, because these are consequences of a write\n * that has already happened — an activity row, a notification — and a\n * failure in one must not undo or hide the write for the customer.\n */\n\nimport type { OrgSeatAddons } from '../foundation'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** Who did it, as the activity logs record an actor. */\nexport interface PluginEventActor {\n  uid: string | null\n  email: string | null\n}\n\n/** The payload each platform event carries. */\nexport interface PluginEventPayloads {\n  /** An org's purchased seat add-ons were written (a purchase, a removal, a webhook mirror). */\n  'org.seatAddons.changed': {\n    orgId: string\n    actor: PluginEventActor\n    before: OrgSeatAddons | null | undefined\n    after: OrgSeatAddons | null | undefined\n  }\n  /**\n   * The workspace's Stripe invoice was paid, in full, by a real charge.\n   *\n   * Raised from the platform billing webhook once the invoice has resolved\n   * to a workspace, so a plugin that bills its own usage learns the outcome\n   * of the invoice it asked for without subscribing to Stripe itself. The\n   * invoice's own `metadata` travels with it, unread by core: a plugin that\n   * stamped `pluginId` on the invoice it created recognizes its own by it,\n   * and every other handler ignores the event.\n   *\n   * `paidOutOfBand` is Stripe's own flag for an invoice marked paid without\n   * a charge. A plugin counting payment history must not count one: it is a\n   * staff action, not evidence that money moved.\n   */\n  'billing.invoice.paid': {\n    orgId: string\n    invoiceId: string\n    amountPaidCents: number\n    currency: string\n    paidOutOfBand: boolean\n    metadata: Readonly<Record<string, string>>\n  }\n  /** A charge attempt on the workspace's invoice failed or needs action. */\n  'billing.invoice.failed': {\n    orgId: string\n    invoiceId: string\n    amountDueCents: number\n    metadata: Readonly<Record<string, string>>\n  }\n  /**\n   * An invoice was closed without being paid — voided, or written off as\n   * uncollectible.\n   *\n   * ONE event for both Stripe events because they are one fact to a plugin:\n   * this invoice will never be paid and nothing more is owed on it. A\n   * handler that must tell them apart reads `reason`; one that only needs\n   * to stop waiting does not.\n   */\n  'billing.invoice.closed': {\n    orgId: string\n    invoiceId: string\n    reason: 'voided' | 'uncollectible'\n    metadata: Readonly<Record<string, string>>\n  }\n  /** A cardholder disputed a charge of the workspace's. */\n  'billing.dispute.opened': {\n    orgId: string\n    chargeId: string\n    invoiceId: string | null\n    amountCents: number\n  }\n  /**\n   * The workspace's default payment method changed, or its type did.\n   *\n   * `defaultType` is Stripe's own type string (`card`, `us_bank_account`,\n   * `link`, …), or `null` when the customer has no default. Core states the\n   * fact and takes no view: which types a plugin will extend credit against\n   * is the plugin's decision, not the platform's.\n   */\n  'billing.paymentMethod.changed': {\n    orgId: string\n    defaultType: string | null\n  }\n  /**\n   * Records were REMOVED from a collection, by a path that is not the\n   * owning plugin's own (AGL-3330): a deletion through the public API, a\n   * person's erasure.\n   *\n   * Raised after the delete has landed, with each removed document's data\n   * as it stood, so a plugin that keeps a figure over those rows — a counter\n   * no increment can take back — can recount what they fed. Core names the\n   * collection and takes no view of what it holds.\n   *\n   * `hostIds` are the sites the records were on: the one site for a site's\n   * collection, every site of the organization for an organization row.\n   */\n  'host.records.removed': {\n    orgId: string | null\n    hostIds: readonly string[]\n    collection: string\n    records: ReadonlyArray<{ id: string; data: Readonly<Record<string, unknown>> }>\n  }\n  /**\n   * A site's email was opened, or a link in it clicked (AGL-3605): the\n   * delivery events one webhook delivery recorded for a send tagged with the\n   * site, the FIRST of each type per message only — the delivery log decides\n   * which those are, so a replay or a reader opening one email six times is\n   * one event. Raised by the plugin whose webhook reads the provider, after\n   * the log has recorded them; a subscriber that counts engagement of its own\n   * reads it here rather than subscribing to the provider.\n   */\n  'host.email.engaged': {\n    hostId: string\n    events: ReadonlyArray<{\n      /** The recipient, lowercased. */\n      to: string\n      /** `opened` or `clicked`. */\n      type: string\n      /** When it happened, epoch ms. */\n      at: number\n      firstOfType: boolean\n    }>\n  }\n  /**\n   * A custom domain was connected to a site and the hosting provider accepted\n   * it (AGL-3629). Raised once the claim is written, so `domain` is the site's\n   * `cname` and no other site's. The site may still be awaiting a certificate\n   * or a DNS change; a plugin that needs the domain registered somewhere — a\n   * payment provider, a search console — does that now rather than waiting\n   * for traffic.\n   */\n  'host.domain.attached': {\n    orgId: string | null\n    hostId: string\n    domain: string\n  }\n  /**\n   * A domain stopped serving a site (AGL-3629): its custom domain was\n   * disconnected, or the site was deleted — which releases its platform\n   * subdomain too, raised as a second event with that name. A plugin undoes\n   * whatever it registered for the name, and must check the name is not\n   * still served by ANOTHER site first (a `www.` twin, a reused subdomain).\n   */\n  'host.domain.released': {\n    orgId: string | null\n    hostId: string\n    domain: string\n    reason: 'detached' | 'site-deleted'\n  }\n  /** One permission key moved on a subject of the org. */\n  'org.permissions.changed': {\n    orgId: string\n    actor: PluginEventActor\n    subject: {\n      type: 'org' | 'role' | 'member' | 'host'\n      id?: string | null\n      name?: string | null\n    }\n    permission: string\n    granted: boolean\n  }\n}\n\nexport type PluginEventName = keyof PluginEventPayloads\n\nexport type PluginEventHandler<E extends PluginEventName> = (\n  payload: PluginEventPayloads[E],\n) => void | Promise<void>\n\ninterface Registration {\n  pluginId: string\n  handler: PluginEventHandler<PluginEventName>\n}\n\nconst handlers = new Map<PluginEventName, Registration[]>()\n\n/**\n * Subscribes to an event. Owner = the loader's marker inside a register fn,\n * else `options.pluginId`; a subscription with neither throws. A plugin\n * re-subscribing replaces its earlier handler for that event, so a module\n * evaluated twice does not write two rows.\n */\nexport function registerPluginEventHandler<E extends PluginEventName>(\n  event: E,\n  handler: PluginEventHandler<E>,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      `plugin event \"${event}\" subscribed with no owner: pass { pluginId } ` +\n        'when subscribing outside a plugin register fn',\n    )\n  }\n  const list = (handlers.get(event) ?? []).filter((entry) => entry.pluginId !== pluginId)\n  list.push({ pluginId, handler: handler as PluginEventHandler<PluginEventName> })\n  handlers.set(event, list)\n}\n\n/**\n * Raises an event. Every handler runs, in subscription order; a throw is\n * logged with the plugin's id and does not stop the others.\n */\nexport async function runPluginEventHandlers<E extends PluginEventName>(\n  event: E,\n  payload: PluginEventPayloads[E],\n): Promise<{ handled: number; failed: string[] }> {\n  let handled = 0\n  const failed: string[] = []\n  for (const { pluginId, handler } of handlers.get(event) ?? []) {\n    try {\n      await handler(payload)\n      handled += 1\n    } catch (error) {\n      failed.push(pluginId)\n      console.error(`[plugins] ${pluginId} failed on event ${event}`, error)\n    }\n  }\n  return { handled, failed }\n}\n\n/** The plugins subscribed to an event, for diagnostics. */\nexport function listPluginEventHandlers(event: PluginEventName): string[] {\n  return (handlers.get(event) ?? []).map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every subscription. */\nexport function resetPluginEventHandlersForTests(): void {\n  handlers.clear()\n}\n"],"names":["getRegisteringPluginId","handlers","Map","registerPluginEventHandler","event","handler","options","pluginId","trim","Error","list","get","filter","entry","push","set","runPluginEventHandlers","payload","handled","failed","error","console","listPluginEventHandlers","map","resetPluginEventHandlersForTests","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;CAkBC,GAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AA2KxE,MAAMC,WAAW,IAAIC;AAErB;;;;;CAKC,GACD,OAAO,SAASC,2BACdC,KAAQ,EACRC,OAA8B,EAC9BC,OAA+B;QAEbN,MAAAA,yBAOJC;IAPd,MAAMM,WAAW,EAACP,QAAAA,0BAAAA,oCAAAA,0BAA4BM,2BAAAA,QAASC,QAAQ,YAA7CP,OAAiD,IAAIQ,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,CAAC,cAAc,EAAEL,MAAM,8CAA8C,CAAC,GACpE;IAEN;IACA,MAAMM,OAAO,EAACT,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,EAAEW,MAAM,CAAC,CAACC,QAAUA,MAAMN,QAAQ,KAAKA;IAC9EG,KAAKI,IAAI,CAAC;QAAEP;QAAUF,SAASA;IAA+C;IAC9EJ,SAASc,GAAG,CAACX,OAAOM;AACtB;AAEA;;;CAGC,GACD,OAAO,eAAeM,uBACpBZ,KAAQ,EACRa,OAA+B;QAIKhB;IAFpC,IAAIiB,UAAU;IACd,MAAMC,SAAmB,EAAE;IAC3B,KAAK,MAAM,EAAEZ,QAAQ,EAAEF,OAAO,EAAE,KAAIJ,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,CAAE;QAC7D,IAAI;YACF,MAAMI,QAAQY;YACdC,WAAW;QACb,EAAE,OAAOE,OAAO;YACdD,OAAOL,IAAI,CAACP;YACZc,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEb,SAAS,iBAAiB,EAAEH,OAAO,EAAEgB;QAClE;IACF;IACA,OAAO;QAAEF;QAASC;IAAO;AAC3B;AAEA,yDAAyD,GACzD,OAAO,SAASG,wBAAwBlB,KAAsB;QACpDH;IAAR,OAAO,EAACA,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,EAAEsB,GAAG,CAAC,CAACV,QAAUA,MAAMN,QAAQ;AAClE;AAEA,0CAA0C,GAC1C,OAAO,SAASiB;IACdvB,SAASwB,KAAK;AAChB"}

package/src/lib/plugin-manager/plugin-fulfillment-providers.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @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.
+ */
+/**
+ * Outside parties that fulfill a seller's lines (AGL-3634): a fulfillment
+ * network that picks and packs from its own warehouses, a print-on-demand or
+ * dropship supplier that makes and sends the goods itself.
+ *
+ * Each one takes some of a record's lines away from the merchant's own
+ * packing table. Whoever else ships that record — a label buyer, another
+ * provider, the merchant by hand — must know which units are already spoken
+ * for, or the customer gets two parcels and the merchant pays twice. The
+ * provider plugins never import one another and never import the seller, so
+ * each registers a {@link PluginFulfillmentProvider} here and answers one
+ * question: which units of this record do you hold that have not shipped?
+ *
+ * A HOLD IS ONLY WHAT HAS NOT SHIPPED. Once the provider ships, it writes the
+ * shipment onto the record through `core.shipment-records`, the record's own
+ * unshipped count drops, and the hold drops with it. A canceled or failed
+ * hand-off is no hold: the units are the merchant's again.
+ *
+ * A provider that cannot answer is reported by name in `unanswered` rather
+ * than read as holding nothing, so a caller deciding whether to ship can say
+ * why it is waiting instead of shipping a parcel that may already be on its
+ * way from somewhere else.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-fulfillment-providers`); it is not in
+ * the barrel.
+ */
+/** Units of one line a provider has taken and not yet shipped. */
+export interface PluginFulfillmentHold {
+    /** The provider's id, unique across plugins: `shipbob`, `printful`. */
+    providerId: string;
+    /** What a person calls it. */
+    providerLabel: string;
+    /** The line's position on the record, as `core.shipment-records` names it. */
+    lineIndex: number;
+    /** Units of the line the provider holds that have not shipped. */
+    quantity: number;
+    /**
+     * `pending` — taken and not yet accepted by the provider (queued, or being
+     * sent); `accepted` — the provider has it and is fulfilling it.
+     */
+    state: 'pending' | 'accepted';
+    /** The provider's own reference for the hand-off, for a person to look it up there. */
+    reference?: string;
+}
+export interface PluginFulfillmentProvider {
+    /** Stable and unique across plugins; a plugin may register several. */
+    id: string;
+    label: string;
+    /** The units of one record this provider holds; empty when none. */
+    holds(hostId: string, recordId: string): Promise<PluginFulfillmentHold[]>;
+}
+/**
+ * Registers a provider. A plugin registers each of its providers under the
+ * provider's id, and registering the same id again replaces it.
+ */
+export declare function registerPluginFulfillmentProvider(provider: PluginFulfillmentProvider, options?: {
+    pluginId?: string;
+}): void;
+/** Every registered provider, with the plugin that registered it. */
+export declare function listPluginFulfillmentProviders(): Array<{
+    pluginId: string;
+    id: string;
+    label: string;
+}>;
+/** What every provider holds of one record. */
+export interface PluginFulfillmentHolds {
+    holds: PluginFulfillmentHold[];
+    /** Providers that threw: they may hold units nobody can see. */
+    unanswered: Array<{
+        providerId: string;
+        providerLabel: string;
+    }>;
+}
+/**
+ * Asks every provider — or every provider but those of `exceptPluginId`, so
+ * a provider deciding what it may take does not count itself — what it holds
+ * of one record. Each is isolated: one that throws is logged and named in
+ * `unanswered`, and the rest still answer. A hold of no units is dropped.
+ */
+export declare function pluginFulfillmentHolds(hostId: string, recordId: string, options?: {
+    exceptPluginId?: string;
+}): Promise<PluginFulfillmentHolds>;
+/** Units held per line, summed across providers. */
+export declare function heldQuantitiesByLine(holds: readonly PluginFulfillmentHold[]): Map<number, number>;

package/src/lib/plugin-manager/plugin-fulfillment-providers.js

@@ -0,0 +1,83 @@
+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";
+const PLUGIN_FULFILLMENT_PROVIDERS = definePluginServiceContract('core.fulfillment-providers', {
+    multiple: true
+});
+/**
+ * Registers a provider. A plugin registers each of its providers under the
+ * provider's id, and registering the same id again replaces it.
+ */ export function registerPluginFulfillmentProvider(provider, options) {
+    var _ref, _getRegisteringPluginId;
+    const id = String((_ref = provider == null ? void 0 : provider.id) != null ? _ref : '').trim();
+    if (!id) throw new Error('a fulfillment provider needs an id');
+    const pluginId = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId;
+    registerPluginService(PLUGIN_FULFILLMENT_PROVIDERS, provider, _extends({
+        key: id
+    }, pluginId ? {
+        pluginId
+    } : {}));
+}
+/** Every registered provider, with the plugin that registered it. */ export function listPluginFulfillmentProviders() {
+    return resolvePluginServices(PLUGIN_FULFILLMENT_PROVIDERS).map((entry)=>({
+            pluginId: entry.pluginId,
+            id: entry.impl.id,
+            label: entry.impl.label
+        }));
+}
+/**
+ * Asks every provider — or every provider but those of `exceptPluginId`, so
+ * a provider deciding what it may take does not count itself — what it holds
+ * of one record. Each is isolated: one that throws is logged and named in
+ * `unanswered`, and the rest still answer. A hold of no units is dropped.
+ */ export async function pluginFulfillmentHolds(hostId, recordId, options) {
+    const result = {
+        holds: [],
+        unanswered: []
+    };
+    const entries = resolvePluginServices(PLUGIN_FULFILLMENT_PROVIDERS).filter((entry)=>!(options == null ? void 0 : options.exceptPluginId) || entry.pluginId !== options.exceptPluginId);
+    await Promise.all(entries.map(async (entry)=>{
+        try {
+            const holds = await entry.impl.holds(hostId, recordId);
+            for (const hold of holds != null ? holds : []){
+                const quantity = Math.floor(Number(hold == null ? void 0 : hold.quantity));
+                const lineIndex = Math.floor(Number(hold == null ? void 0 : hold.lineIndex));
+                if (!(quantity > 0) || !(lineIndex >= 0)) continue;
+                result.holds.push(_extends({}, hold, {
+                    quantity,
+                    lineIndex
+                }));
+            }
+        } catch (error) {
+            console.error(`[fulfillment-providers] "${entry.impl.id}" of "${entry.pluginId}" failed for ${hostId}/${recordId}`, error);
+            result.unanswered.push({
+                providerId: entry.impl.id,
+                providerLabel: entry.impl.label
+            });
+        }
+    }));
+    return result;
+}
+/** Units held per line, summed across providers. */ export function heldQuantitiesByLine(holds) {
+    var _held_get;
+    const held = new Map();
+    for (const hold of holds)held.set(hold.lineIndex, ((_held_get = held.get(hold.lineIndex)) != null ? _held_get : 0) + hold.quantity);
+    return held;
+}
+
+//# sourceMappingURL=plugin-fulfillment-providers.js.map

package/src/lib/plugin-manager/plugin-fulfillment-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-fulfillment-providers.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 * Outside parties that fulfill a seller's lines (AGL-3634): a fulfillment\n * network that picks and packs from its own warehouses, a print-on-demand or\n * dropship supplier that makes and sends the goods itself.\n *\n * Each one takes some of a record's lines away from the merchant's own\n * packing table. Whoever else ships that record — a label buyer, another\n * provider, the merchant by hand — must know which units are already spoken\n * for, or the customer gets two parcels and the merchant pays twice. The\n * provider plugins never import one another and never import the seller, so\n * each registers a {@link PluginFulfillmentProvider} here and answers one\n * question: which units of this record do you hold that have not shipped?\n *\n * A HOLD IS ONLY WHAT HAS NOT SHIPPED. Once the provider ships, it writes the\n * shipment onto the record through `core.shipment-records`, the record's own\n * unshipped count drops, and the hold drops with it. A canceled or failed\n * hand-off is no hold: the units are the merchant's again.\n *\n * A provider that cannot answer is reported by name in `unanswered` rather\n * than read as holding nothing, so a caller deciding whether to ship can say\n * why it is waiting instead of shipping a parcel that may already be on its\n * way from somewhere else.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-fulfillment-providers`); it is not in\n * the barrel.\n */\n\n/** Units of one line a provider has taken and not yet shipped. */\nexport interface PluginFulfillmentHold {\n  /** The provider's id, unique across plugins: `shipbob`, `printful`. */\n  providerId: string\n  /** What a person calls it. */\n  providerLabel: string\n  /** The line's position on the record, as `core.shipment-records` names it. */\n  lineIndex: number\n  /** Units of the line the provider holds that have not shipped. */\n  quantity: number\n  /**\n   * `pending` — taken and not yet accepted by the provider (queued, or being\n   * sent); `accepted` — the provider has it and is fulfilling it.\n   */\n  state: 'pending' | 'accepted'\n  /** The provider's own reference for the hand-off, for a person to look it up there. */\n  reference?: string\n}\n\nexport interface PluginFulfillmentProvider {\n  /** Stable and unique across plugins; a plugin may register several. */\n  id: string\n  label: string\n  /** The units of one record this provider holds; empty when none. */\n  holds(hostId: string, recordId: string): Promise<PluginFulfillmentHold[]>\n}\n\nconst PLUGIN_FULFILLMENT_PROVIDERS = definePluginServiceContract<PluginFulfillmentProvider>(\n  'core.fulfillment-providers',\n  { multiple: true },\n)\n\n/**\n * Registers a provider. A plugin registers each of its providers under the\n * provider's id, and registering the same id again replaces it.\n */\nexport function registerPluginFulfillmentProvider(\n  provider: PluginFulfillmentProvider,\n  options?: { pluginId?: string },\n): void {\n  const id = String(provider?.id ?? '').trim()\n  if (!id) throw new Error('a fulfillment provider needs an id')\n  const pluginId = getRegisteringPluginId() ?? options?.pluginId\n  registerPluginService(PLUGIN_FULFILLMENT_PROVIDERS, provider, {\n    key: id,\n    ...(pluginId ? { pluginId } : {}),\n  })\n}\n\n/** Every registered provider, with the plugin that registered it. */\nexport function listPluginFulfillmentProviders(): Array<{ pluginId: string; id: string; label: string }> {\n  return resolvePluginServices(PLUGIN_FULFILLMENT_PROVIDERS).map((entry) => ({\n    pluginId: entry.pluginId,\n    id: entry.impl.id,\n    label: entry.impl.label,\n  }))\n}\n\n/** What every provider holds of one record. */\nexport interface PluginFulfillmentHolds {\n  holds: PluginFulfillmentHold[]\n  /** Providers that threw: they may hold units nobody can see. */\n  unanswered: Array<{ providerId: string; providerLabel: string }>\n}\n\n/**\n * Asks every provider — or every provider but those of `exceptPluginId`, so\n * a provider deciding what it may take does not count itself — what it holds\n * of one record. Each is isolated: one that throws is logged and named in\n * `unanswered`, and the rest still answer. A hold of no units is dropped.\n */\nexport async function pluginFulfillmentHolds(\n  hostId: string,\n  recordId: string,\n  options?: { exceptPluginId?: string },\n): Promise<PluginFulfillmentHolds> {\n  const result: PluginFulfillmentHolds = { holds: [], unanswered: [] }\n  const entries = resolvePluginServices(PLUGIN_FULFILLMENT_PROVIDERS).filter(\n    (entry) => !options?.exceptPluginId || entry.pluginId !== options.exceptPluginId,\n  )\n  await Promise.all(\n    entries.map(async (entry) => {\n      try {\n        const holds = await entry.impl.holds(hostId, recordId)\n        for (const hold of holds ?? []) {\n          const quantity = Math.floor(Number(hold?.quantity))\n          const lineIndex = Math.floor(Number(hold?.lineIndex))\n          if (!(quantity > 0) || !(lineIndex >= 0)) continue\n          result.holds.push({ ...hold, quantity, lineIndex })\n        }\n      } catch (error) {\n        console.error(\n          `[fulfillment-providers] \"${entry.impl.id}\" of \"${entry.pluginId}\" failed for ${hostId}/${recordId}`,\n          error,\n        )\n        result.unanswered.push({ providerId: entry.impl.id, providerLabel: entry.impl.label })\n      }\n    }),\n  )\n  return result\n}\n\n/** Units held per line, summed across providers. */\nexport function heldQuantitiesByLine(holds: readonly PluginFulfillmentHold[]): Map<number, number> {\n  const held = new Map<number, number>()\n  for (const hold of holds) held.set(hold.lineIndex, (held.get(hold.lineIndex) ?? 0) + hold.quantity)\n  return held\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_FULFILLMENT_PROVIDERS","multiple","registerPluginFulfillmentProvider","provider","options","id","String","trim","Error","pluginId","key","listPluginFulfillmentProviders","map","entry","impl","label","pluginFulfillmentHolds","hostId","recordId","result","holds","unanswered","entries","filter","exceptPluginId","Promise","all","hold","quantity","Math","floor","Number","lineIndex","push","error","console","providerId","providerLabel","heldQuantitiesByLine","held","Map","set","get"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyD1B,MAAMC,+BAA+BH,4BACnC,8BACA;IAAEI,UAAU;AAAK;AAGnB;;;CAGC,GACD,OAAO,SAASC,kCACdC,QAAmC,EACnCC,OAA+B;cAIdR;IAFjB,MAAMS,KAAKC,eAAOH,4BAAAA,SAAUE,EAAE,mBAAI,IAAIE,IAAI;IAC1C,IAAI,CAACF,IAAI,MAAM,IAAIG,MAAM;IACzB,MAAMC,YAAWb,0BAAAA,oCAAAA,0BAA4BQ,2BAAAA,QAASK,QAAQ;IAC9DX,sBAAsBE,8BAA8BG,UAAU;QAC5DO,KAAKL;OACDI,WAAW;QAAEA;IAAS,IAAI,CAAC;AAEnC;AAEA,mEAAmE,GACnE,OAAO,SAASE;IACd,OAAOZ,sBAAsBC,8BAA8BY,GAAG,CAAC,CAACC,QAAW,CAAA;YACzEJ,UAAUI,MAAMJ,QAAQ;YACxBJ,IAAIQ,MAAMC,IAAI,CAACT,EAAE;YACjBU,OAAOF,MAAMC,IAAI,CAACC,KAAK;QACzB,CAAA;AACF;AASA;;;;;CAKC,GACD,OAAO,eAAeC,uBACpBC,MAAc,EACdC,QAAgB,EAChBd,OAAqC;IAErC,MAAMe,SAAiC;QAAEC,OAAO,EAAE;QAAEC,YAAY,EAAE;IAAC;IACnE,MAAMC,UAAUvB,sBAAsBC,8BAA8BuB,MAAM,CACxE,CAACV,QAAU,EAACT,2BAAAA,QAASoB,cAAc,KAAIX,MAAMJ,QAAQ,KAAKL,QAAQoB,cAAc;IAElF,MAAMC,QAAQC,GAAG,CACfJ,QAAQV,GAAG,CAAC,OAAOC;QACjB,IAAI;YACF,MAAMO,QAAQ,MAAMP,MAAMC,IAAI,CAACM,KAAK,CAACH,QAAQC;YAC7C,KAAK,MAAMS,QAAQP,gBAAAA,QAAS,EAAE,CAAE;gBAC9B,MAAMQ,WAAWC,KAAKC,KAAK,CAACC,OAAOJ,wBAAAA,KAAMC,QAAQ;gBACjD,MAAMI,YAAYH,KAAKC,KAAK,CAACC,OAAOJ,wBAAAA,KAAMK,SAAS;gBACnD,IAAI,CAAEJ,CAAAA,WAAW,CAAA,KAAM,CAAEI,CAAAA,aAAa,CAAA,GAAI;gBAC1Cb,OAAOC,KAAK,CAACa,IAAI,CAAC,aAAKN;oBAAMC;oBAAUI;;YACzC;QACF,EAAE,OAAOE,OAAO;YACdC,QAAQD,KAAK,CACX,CAAC,yBAAyB,EAAErB,MAAMC,IAAI,CAACT,EAAE,CAAC,MAAM,EAAEQ,MAAMJ,QAAQ,CAAC,aAAa,EAAEQ,OAAO,CAAC,EAAEC,UAAU,EACpGgB;YAEFf,OAAOE,UAAU,CAACY,IAAI,CAAC;gBAAEG,YAAYvB,MAAMC,IAAI,CAACT,EAAE;gBAAEgC,eAAexB,MAAMC,IAAI,CAACC,KAAK;YAAC;QACtF;IACF;IAEF,OAAOI;AACT;AAEA,kDAAkD,GAClD,OAAO,SAASmB,qBAAqBlB,KAAuC;QAEtBmB;IADpD,MAAMA,OAAO,IAAIC;IACjB,KAAK,MAAMb,QAAQP,MAAOmB,KAAKE,GAAG,CAACd,KAAKK,SAAS,EAAE,EAACO,YAAAA,KAAKG,GAAG,CAACf,KAAKK,SAAS,aAAvBO,YAA4B,KAAKZ,KAAKC,QAAQ;IAClG,OAAOW;AACT"}

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

@@ -21,7 +21,24 @@
  * `ConsolePluginPageProps.permissions` and API-side resolution carry them
  * with zero app changes. Register at module scope from both the client
  * barrel and the /server entry (the AGL-428 pattern).
- */ const pluginPermissions = new Map();
+ */ var _globalScope_REGISTRY_KEY;
+/*
+ * One registry per process, keyed on `globalThis` under `Symbol.for`, like
+ * `plugin-services.ts`. Next compiles the boot file and the route handlers
+ * apart, so each can hold its own copy of this module: with the map at module
+ * scope, a plugin's keys registered by one copy were absent from the copy
+ * `resolveOrgPermissions` read, an absent key reads as refused, and the
+ * register's `managePos` gate answered 403 to the site's own owner.
+ */ const REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-permissions');
+const globalScope = globalThis;
+const tables = (_globalScope_REGISTRY_KEY = globalScope[REGISTRY_KEY]) != null ? _globalScope_REGISTRY_KEY : globalScope[REGISTRY_KEY] = {
+    permissions: new Map(),
+    listeners: new Set(),
+    version: {
+        value: 0
+    }
+};
+const pluginPermissions = tables.permissions;
 /*
  * Whoever resolved a permission map before a plugin registered holds a map
  * without that plugin's keys, and a key that is absent reads as refused
@@ -31,8 +48,7 @@
  * they hold by default until the next full render. So registration is
  * observable, the way `subscribePluginEntitlements` makes the org catalog's
  * registrations observable, and the provider re-reads on every change.
- */ let registrationVersion = 0;
-const listeners = new Set();
+ */ const listeners = tables.listeners;
 /** Calls `listener` after every registration; answers the unsubscribe. */ export function subscribePluginPermissions(listener) {
     listeners.add(listener);
     return ()=>{
@@ -43,10 +59,10 @@ const listeners = new Set();
  * A number that changes whenever the registry does — the snapshot for a
  * `useSyncExternalStore` over `subscribePluginPermissions`.
  */ export function pluginPermissionsVersion() {
-    return registrationVersion;
+    return tables.version.value;
 }
 function notifyListeners() {
-    registrationVersion += 1;
+    tables.version.value += 1;
     for (const listener of [
         ...listeners
     ])listener();

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-permissions.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-declared permissions (AGL-435, Strapi RBAC-actions parity): a\n * plugin contributes NAMED permission keys with per-role-tier defaults.\n * `resolveRolePermissions` spreads them into every resolved set (custom\n * roles override key-by-key exactly like built-in keys), so\n * `ConsolePluginPageProps.permissions` and API-side resolution carry them\n * with zero app changes. Register at module scope from both the client\n * barrel and the /server entry (the AGL-428 pattern).\n */\n\nexport interface PluginPermission {\n  /** Stable key ('managePos') — persisted in custom role docs. */\n  key: string\n  pluginId: string\n  label: string\n  description?: string\n  /** Verdict per built-in role tier when a role doesn't name the key. */\n  defaults: { admin: boolean; editor: boolean; viewer: boolean }\n}\n\nconst pluginPermissions = new Map<string, PluginPermission>()\n\n/*\n * Whoever resolved a permission map before a plugin registered holds a map\n * without that plugin's keys, and a key that is absent reads as refused\n * (AGL-3228). The console's permission provider resolved its map when the\n * member document arrived; on a cold load of a plugin's deep link the\n * plugin's chunk can register AFTER that, so the owner was refused a surface\n * they hold by default until the next full render. So registration is\n * observable, the way `subscribePluginEntitlements` makes the org catalog's\n * registrations observable, and the provider re-reads on every change.\n */\nlet registrationVersion = 0\nconst listeners = new Set<() => void>()\n\n/** Calls `listener` after every registration; answers the unsubscribe. */\nexport function subscribePluginPermissions(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * A number that changes whenever the registry does — the snapshot for a\n * `useSyncExternalStore` over `subscribePluginPermissions`.\n */\nexport function pluginPermissionsVersion(): number {\n  return registrationVersion\n}\n\nfunction notifyListeners(): void {\n  registrationVersion += 1\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Idempotent per key FOR ITS OWNER — the declaring plugin may re-register\n * (hot reload, a second surface, a repeated init) and its entry is replaced.\n *\n * A key already declared by a DIFFERENT plugin is refused (AGL-2484). This\n * map keyed on `permission.key` alone, so a later registration could redeclare\n * someone else's key with its own tier defaults — and these defaults are not\n * cosmetic: `managePos` is enforced server-side in\n * `libs/plugins/commerce/src/lib/server/pos-order.ts`, so moving\n * `defaults.viewer` to `true` hands a viewer the register. Reaching this\n * needs `PLUGIN_REMOTE_SERVER=enabled` (off by default), realm trust and a\n * signature; the registry closing its own door is the cheap part of that\n * stack.\n *\n * Per KEY, not per batch: a bundle that collides on one key still gets the\n * keys that are genuinely its own.\n */\nexport function registerPluginPermissions(\n  permissions: readonly PluginPermission[],\n): void {\n  for (const permission of permissions) {\n    const incumbent = pluginPermissions.get(permission.key)\n    if (incumbent !== undefined && incumbent.pluginId !== permission.pluginId) {\n      console.error(\n        `[plugins] refused permission key \"${permission.key}\" to ` +\n          `\"${permission.pluginId}\": already declared by ` +\n          `\"${incumbent.pluginId}\"`,\n      )\n      continue\n    }\n    pluginPermissions.set(permission.key, permission)\n  }\n  notifyListeners()\n}\n\nexport function listPluginPermissions(): PluginPermission[] {\n  return [...pluginPermissions.values()]\n}\n\n/**\n * The registered keys alone (AGL-2474). `resolveRolePermissions` needs the\n * grantable key SPACE, not the tier verdicts: it used to iterate\n * `ORG_ROLE_PERMISSION_KEYS` — the legacy six — when applying overrides and\n * custom roles, so a plugin-declared key materialised into the resolved map\n * and could then only ever hold its tier default. Read live rather than\n * snapshotted: registration happens at plugin module scope, which can run\n * after any module-level constant here has already been evaluated.\n */\nexport function listPluginPermissionKeys(): string[] {\n  return [...pluginPermissions.keys()]\n}\n\n/** Tier defaults for every registered plugin permission. */\nexport function pluginPermissionDefaults(\n  tier: 'admin' | 'editor' | 'viewer',\n): Record<string, boolean> {\n  const defaults: Record<string, boolean> = {}\n  for (const permission of pluginPermissions.values()) {\n    defaults[permission.key] = permission.defaults[tier]\n  }\n  return defaults\n}\n"],"names":["pluginPermissions","Map","registrationVersion","listeners","Set","subscribePluginPermissions","listener","add","delete","pluginPermissionsVersion","notifyListeners","registerPluginPermissions","permissions","permission","incumbent","get","key","undefined","pluginId","console","error","set","listPluginPermissions","values","listPluginPermissionKeys","keys","pluginPermissionDefaults","tier","defaults"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,GAYD,MAAMA,oBAAoB,IAAIC;AAE9B;;;;;;;;;CASC,GACD,IAAIC,sBAAsB;AAC1B,MAAMC,YAAY,IAAIC;AAEtB,wEAAwE,GACxE,OAAO,SAASC,2BAA2BC,QAAoB;IAC7DH,UAAUI,GAAG,CAACD;IACd,OAAO;QACLH,UAAUK,MAAM,CAACF;IACnB;AACF;AAEA;;;CAGC,GACD,OAAO,SAASG;IACd,OAAOP;AACT;AAEA,SAASQ;IACPR,uBAAuB;IACvB,KAAK,MAAMI,YAAY;WAAIH;KAAU,CAAEG;AACzC;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASK,0BACdC,WAAwC;IAExC,KAAK,MAAMC,cAAcD,YAAa;QACpC,MAAME,YAAYd,kBAAkBe,GAAG,CAACF,WAAWG,GAAG;QACtD,IAAIF,cAAcG,aAAaH,UAAUI,QAAQ,KAAKL,WAAWK,QAAQ,EAAE;YACzEC,QAAQC,KAAK,CACX,CAAC,kCAAkC,EAAEP,WAAWG,GAAG,CAAC,KAAK,CAAC,GACxD,CAAC,CAAC,EAAEH,WAAWK,QAAQ,CAAC,uBAAuB,CAAC,GAChD,CAAC,CAAC,EAAEJ,UAAUI,QAAQ,CAAC,CAAC,CAAC;YAE7B;QACF;QACAlB,kBAAkBqB,GAAG,CAACR,WAAWG,GAAG,EAAEH;IACxC;IACAH;AACF;AAEA,OAAO,SAASY;IACd,OAAO;WAAItB,kBAAkBuB,MAAM;KAAG;AACxC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC;IACd,OAAO;WAAIxB,kBAAkByB,IAAI;KAAG;AACtC;AAEA,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,IAAmC;IAEnC,MAAMC,WAAoC,CAAC;IAC3C,KAAK,MAAMf,cAAcb,kBAAkBuB,MAAM,GAAI;QACnDK,QAAQ,CAACf,WAAWG,GAAG,CAAC,GAAGH,WAAWe,QAAQ,CAACD,KAAK;IACtD;IACA,OAAOC;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-permissions.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-declared permissions (AGL-435, Strapi RBAC-actions parity): a\n * plugin contributes NAMED permission keys with per-role-tier defaults.\n * `resolveRolePermissions` spreads them into every resolved set (custom\n * roles override key-by-key exactly like built-in keys), so\n * `ConsolePluginPageProps.permissions` and API-side resolution carry them\n * with zero app changes. Register at module scope from both the client\n * barrel and the /server entry (the AGL-428 pattern).\n */\n\nexport interface PluginPermission {\n  /** Stable key ('managePos') — persisted in custom role docs. */\n  key: string\n  pluginId: string\n  label: string\n  description?: string\n  /** Verdict per built-in role tier when a role doesn't name the key. */\n  defaults: { admin: boolean; editor: boolean; viewer: boolean }\n}\n\n/*\n * One registry per process, keyed on `globalThis` under `Symbol.for`, like\n * `plugin-services.ts`. Next compiles the boot file and the route handlers\n * apart, so each can hold its own copy of this module: with the map at module\n * scope, a plugin's keys registered by one copy were absent from the copy\n * `resolveOrgPermissions` read, an absent key reads as refused, and the\n * register's `managePos` gate answered 403 to the site's own owner.\n */\nconst REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-permissions')\n\ninterface PluginPermissionTables {\n  permissions: Map<string, PluginPermission>\n  listeners: Set<() => void>\n  version: { value: number }\n}\n\nconst globalScope = globalThis as typeof globalThis & {\n  [REGISTRY_KEY]?: PluginPermissionTables\n}\n\nconst tables: PluginPermissionTables =\n  globalScope[REGISTRY_KEY] ??\n  (globalScope[REGISTRY_KEY] = {\n    permissions: new Map(),\n    listeners: new Set(),\n    version: { value: 0 },\n  })\nconst pluginPermissions = tables.permissions\n\n/*\n * Whoever resolved a permission map before a plugin registered holds a map\n * without that plugin's keys, and a key that is absent reads as refused\n * (AGL-3228). The console's permission provider resolved its map when the\n * member document arrived; on a cold load of a plugin's deep link the\n * plugin's chunk can register AFTER that, so the owner was refused a surface\n * they hold by default until the next full render. So registration is\n * observable, the way `subscribePluginEntitlements` makes the org catalog's\n * registrations observable, and the provider re-reads on every change.\n */\nconst listeners = tables.listeners\n\n/** Calls `listener` after every registration; answers the unsubscribe. */\nexport function subscribePluginPermissions(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * A number that changes whenever the registry does — the snapshot for a\n * `useSyncExternalStore` over `subscribePluginPermissions`.\n */\nexport function pluginPermissionsVersion(): number {\n  return tables.version.value\n}\n\nfunction notifyListeners(): void {\n  tables.version.value += 1\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Idempotent per key FOR ITS OWNER — the declaring plugin may re-register\n * (hot reload, a second surface, a repeated init) and its entry is replaced.\n *\n * A key already declared by a DIFFERENT plugin is refused (AGL-2484). This\n * map keyed on `permission.key` alone, so a later registration could redeclare\n * someone else's key with its own tier defaults — and these defaults are not\n * cosmetic: `managePos` is enforced server-side in\n * `libs/plugins/commerce/src/lib/server/pos-order.ts`, so moving\n * `defaults.viewer` to `true` hands a viewer the register. Reaching this\n * needs `PLUGIN_REMOTE_SERVER=enabled` (off by default), realm trust and a\n * signature; the registry closing its own door is the cheap part of that\n * stack.\n *\n * Per KEY, not per batch: a bundle that collides on one key still gets the\n * keys that are genuinely its own.\n */\nexport function registerPluginPermissions(\n  permissions: readonly PluginPermission[],\n): void {\n  for (const permission of permissions) {\n    const incumbent = pluginPermissions.get(permission.key)\n    if (incumbent !== undefined && incumbent.pluginId !== permission.pluginId) {\n      console.error(\n        `[plugins] refused permission key \"${permission.key}\" to ` +\n          `\"${permission.pluginId}\": already declared by ` +\n          `\"${incumbent.pluginId}\"`,\n      )\n      continue\n    }\n    pluginPermissions.set(permission.key, permission)\n  }\n  notifyListeners()\n}\n\nexport function listPluginPermissions(): PluginPermission[] {\n  return [...pluginPermissions.values()]\n}\n\n/**\n * The registered keys alone (AGL-2474). `resolveRolePermissions` needs the\n * grantable key SPACE, not the tier verdicts: it used to iterate\n * `ORG_ROLE_PERMISSION_KEYS` — the legacy six — when applying overrides and\n * custom roles, so a plugin-declared key materialised into the resolved map\n * and could then only ever hold its tier default. Read live rather than\n * snapshotted: registration happens at plugin module scope, which can run\n * after any module-level constant here has already been evaluated.\n */\nexport function listPluginPermissionKeys(): string[] {\n  return [...pluginPermissions.keys()]\n}\n\n/** Tier defaults for every registered plugin permission. */\nexport function pluginPermissionDefaults(\n  tier: 'admin' | 'editor' | 'viewer',\n): Record<string, boolean> {\n  const defaults: Record<string, boolean> = {}\n  for (const permission of pluginPermissions.values()) {\n    defaults[permission.key] = permission.defaults[tier]\n  }\n  return defaults\n}\n"],"names":["globalScope","REGISTRY_KEY","Symbol","for","globalThis","tables","permissions","Map","listeners","Set","version","value","pluginPermissions","subscribePluginPermissions","listener","add","delete","pluginPermissionsVersion","notifyListeners","registerPluginPermissions","permission","incumbent","get","key","undefined","pluginId","console","error","set","listPluginPermissions","values","listPluginPermissionKeys","keys","pluginPermissionDefaults","tier","defaults"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,OAiCCA;AArBF;;;;;;;CAOC,GACD,MAAMC,eAAeC,OAAOC,GAAG,CAAC;AAQhC,MAAMH,cAAcI;AAIpB,MAAMC,UACJL,4BAAAA,WAAW,CAACC,aAAa,YAAzBD,4BACCA,WAAW,CAACC,aAAa,GAAG;IAC3BK,aAAa,IAAIC;IACjBC,WAAW,IAAIC;IACfC,SAAS;QAAEC,OAAO;IAAE;AACtB;AACF,MAAMC,oBAAoBP,OAAOC,WAAW;AAE5C;;;;;;;;;CASC,GACD,MAAME,YAAYH,OAAOG,SAAS;AAElC,wEAAwE,GACxE,OAAO,SAASK,2BAA2BC,QAAoB;IAC7DN,UAAUO,GAAG,CAACD;IACd,OAAO;QACLN,UAAUQ,MAAM,CAACF;IACnB;AACF;AAEA;;;CAGC,GACD,OAAO,SAASG;IACd,OAAOZ,OAAOK,OAAO,CAACC,KAAK;AAC7B;AAEA,SAASO;IACPb,OAAOK,OAAO,CAACC,KAAK,IAAI;IACxB,KAAK,MAAMG,YAAY;WAAIN;KAAU,CAAEM;AACzC;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASK,0BACdb,WAAwC;IAExC,KAAK,MAAMc,cAAcd,YAAa;QACpC,MAAMe,YAAYT,kBAAkBU,GAAG,CAACF,WAAWG,GAAG;QACtD,IAAIF,cAAcG,aAAaH,UAAUI,QAAQ,KAAKL,WAAWK,QAAQ,EAAE;YACzEC,QAAQC,KAAK,CACX,CAAC,kCAAkC,EAAEP,WAAWG,GAAG,CAAC,KAAK,CAAC,GACxD,CAAC,CAAC,EAAEH,WAAWK,QAAQ,CAAC,uBAAuB,CAAC,GAChD,CAAC,CAAC,EAAEJ,UAAUI,QAAQ,CAAC,CAAC,CAAC;YAE7B;QACF;QACAb,kBAAkBgB,GAAG,CAACR,WAAWG,GAAG,EAAEH;IACxC;IACAF;AACF;AAEA,OAAO,SAASW;IACd,OAAO;WAAIjB,kBAAkBkB,MAAM;KAAG;AACxC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC;IACd,OAAO;WAAInB,kBAAkBoB,IAAI;KAAG;AACtC;AAEA,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,IAAmC;IAEnC,MAAMC,WAAoC,CAAC;IAC3C,KAAK,MAAMf,cAAcR,kBAAkBkB,MAAM,GAAI;QACnDK,QAAQ,CAACf,WAAWG,GAAG,CAAC,GAAGH,WAAWe,QAAQ,CAACD,KAAK;IACtD;IACA,OAAOC;AACT"}