@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/install-presets.js

@@ -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.
+ */ let mapper;
+export function registerPluginInstallPresetMapper(fn) {
+    mapper = fn;
+}
+let presetsMapper;
+export function registerPluginInstallPresetsMapper(fn) {
+    presetsMapper = fn;
+}
+/**
+ * Every drawer preset an install contributes. Falls back to the singular
+ * mapper so a surface that registered only that keeps working unchanged.
+ */ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function pluginInstallToPresets(install) {
+    if (presetsMapper) return presetsMapper(install);
+    const single = pluginInstallToPreset(install);
+    return single ? [
+        single
+    ] : [];
+}
+/** Maps an install doc to a drawer preset; null until a mapper registers. */ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function pluginInstallToPreset(install) {
+    return mapper ? mapper(install) : null;
+}
+let knownInstalls;
+/**
+ * Bumped on every publish so consumers can depend on "the set changed"
+ * (AGL-1030). The install set arrives from a live Firestore subscription and
+ * can land AFTER the element panel has built its fields — installing a plugin
+ * in another tab, or simply a slow first read — and without a change signal
+ * the picker would sit on "No plugins installed for this site" until remount.
+ */ let knownInstallsVersion = 0;
+const knownInstallListeners = new Set();
+/** Called by the console when the install set changes; undefined to forget. */ export function setKnownPluginInstalls(installs) {
+    knownInstalls = installs ? new Map(installs.map((install)=>[
+            install.listingId,
+            install
+        ])) : undefined;
+    knownInstallsVersion += 1;
+    for (const listener of knownInstallListeners)listener();
+}
+/** `useSyncExternalStore` pair for the element panel's plugin picker. */ export function subscribeKnownPluginInstalls(listener) {
+    knownInstallListeners.add(listener);
+    return ()=>{
+        knownInstallListeners.delete(listener);
+    };
+}
+export function getKnownPluginInstallsVersion() {
+    return knownInstallsVersion;
+}
+/** True once a surface has published its install set — see the note above. */ export function hasKnownPluginInstalls() {
+    return knownInstalls !== undefined;
+}
+export function getKnownPluginInstall(listingId) {
+    return listingId ? knownInstalls == null ? void 0 : knownInstalls.get(listingId) : undefined;
+}
+/**
+ * The installed set, for the element panel's plugin picker (AGL-1030).
+ *
+ * Sorted by name so the options do not reshuffle when an install document
+ * happens to come back in a different order.
+ */ export function getKnownPluginInstalls() {
+    var _ref;
+    return [
+        ...(_ref = knownInstalls == null ? void 0 : knownInstalls.values()) != null ? _ref : []
+    ].sort((a, b)=>{
+        var _a_displayName, _b_displayName;
+        return ((_a_displayName = a.displayName) != null ? _a_displayName : a.listingId).localeCompare((_b_displayName = b.displayName) != null ? _b_displayName : b.listingId);
+    });
+}
+
+//# sourceMappingURL=install-presets.js.map

package/src/lib/plugin-manager/install-presets.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/install-presets.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 type { PluginCapabilities } from '../app-utils/plugin-manifest'\nimport type { PresetSchema } from '../types/nodes'\n\n/**\n * Install→preset mapping seam (AGL-419): the besigner drawer shows a\n * preset per installed marketplace plugin, but the preset shape (component\n * id, drawer category, icon) belongs to the mui plugin — so the mapper is\n * REGISTERED by plugins-mui and the console consumes it through core,\n * never importing the plugin.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type PluginInstallPresetMapper = (install: any) => PresetSchema | null\n\nlet mapper: PluginInstallPresetMapper | undefined\n\nexport function registerPluginInstallPresetMapper(\n  fn: PluginInstallPresetMapper,\n): void {\n  mapper = fn\n}\n\n/**\n * Many presets per install (AGL-1031): the generic Plugin element, plus one\n * per element the pinned version DECLARES.\n *\n * A separate seam rather than a widened return type on the singular one — the\n * singular mapper is the AGL-419 contract and several call sites still want\n * exactly one preset. Registering the plural is what turns declared elements\n * into palette entries; without it a plugin's elements simply do not appear,\n * which is the correct behaviour for a host that predates the declaration.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type PluginInstallPresetsMapper = (install: any) => PresetSchema[]\n\nlet presetsMapper: PluginInstallPresetsMapper | undefined\n\nexport function registerPluginInstallPresetsMapper(\n  fn: PluginInstallPresetsMapper,\n): void {\n  presetsMapper = fn\n}\n\n/**\n * Every drawer preset an install contributes. Falls back to the singular\n * mapper so a surface that registered only that keeps working unchanged.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function pluginInstallToPresets(install: any): PresetSchema[] {\n  if (presetsMapper) return presetsMapper(install)\n  const single = pluginInstallToPreset(install)\n  return single ? [single] : []\n}\n\n/** Maps an install doc to a drawer preset; null until a mapper registers. */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function pluginInstallToPreset(install: any): PresetSchema | null {\n  return mapper ? mapper(install) : null\n}\n\n/**\n * What the EDITOR knows about installed plugins (AGL-1029).\n *\n * The Plugin element used to read \"not installed on this site\" off the absence\n * of `version`/`sha256` — fields the tenant compose pass injects and the canvas\n * never has. So it asserted an install fact it had never checked, and said it\n * about every plugin, installed or not.\n *\n * The surface that DOES know is the console, which already reads the installs\n * to build drawer presets. It publishes them here, through the same seam the\n * mapper uses, so the element can name the plugin and only claim \"not\n * installed\" when it has a list to be absent from.\n *\n * Empty is meaningfully different from \"not installed\": on the tenant nothing\n * populates this, so the element must fall back to a neutral statement rather\n * than reading emptiness as absence.\n */\nexport interface KnownPluginInstall {\n  listingId: string\n  displayName?: string\n  /** 'org' when the pin covers every site in the workspace. */\n  scope?: 'org' | 'host'\n  /**\n   * The pinned manifest's capabilities (AGL-1049).\n   *\n   * Carried so the attributes panel can render a plugin's declared settings as\n   * real fields instead of a JSON textarea. The install document already holds\n   * the whole manifest — only the part the editor needs is published here, so\n   * the canvas cannot come to depend on anything the bridge does not honour.\n   */\n  capabilities?: PluginCapabilities\n}\n\nlet knownInstalls: Map<string, KnownPluginInstall> | undefined\n/**\n * Bumped on every publish so consumers can depend on \"the set changed\"\n * (AGL-1030). The install set arrives from a live Firestore subscription and\n * can land AFTER the element panel has built its fields — installing a plugin\n * in another tab, or simply a slow first read — and without a change signal\n * the picker would sit on \"No plugins installed for this site\" until remount.\n */\nlet knownInstallsVersion = 0\nconst knownInstallListeners = new Set<() => void>()\n\n/** Called by the console when the install set changes; undefined to forget. */\nexport function setKnownPluginInstalls(\n  installs: readonly KnownPluginInstall[] | undefined,\n): void {\n  knownInstalls = installs\n    ? new Map(installs.map((install) => [install.listingId, install]))\n    : undefined\n  knownInstallsVersion += 1\n  for (const listener of knownInstallListeners) listener()\n}\n\n/** `useSyncExternalStore` pair for the element panel's plugin picker. */\nexport function subscribeKnownPluginInstalls(listener: () => void): () => void {\n  knownInstallListeners.add(listener)\n  return () => {\n    knownInstallListeners.delete(listener)\n  }\n}\n\nexport function getKnownPluginInstallsVersion(): number {\n  return knownInstallsVersion\n}\n\n/** True once a surface has published its install set — see the note above. */\nexport function hasKnownPluginInstalls(): boolean {\n  return knownInstalls !== undefined\n}\n\nexport function getKnownPluginInstall(\n  listingId: string | undefined,\n): KnownPluginInstall | undefined {\n  return listingId ? knownInstalls?.get(listingId) : undefined\n}\n\n/**\n * The installed set, for the element panel's plugin picker (AGL-1030).\n *\n * Sorted by name so the options do not reshuffle when an install document\n * happens to come back in a different order.\n */\nexport function getKnownPluginInstalls(): readonly KnownPluginInstall[] {\n  return [...(knownInstalls?.values() ?? [])].sort((a, b) =>\n    (a.displayName ?? a.listingId).localeCompare(b.displayName ?? b.listingId),\n  )\n}\n"],"names":["mapper","registerPluginInstallPresetMapper","fn","presetsMapper","registerPluginInstallPresetsMapper","pluginInstallToPresets","install","single","pluginInstallToPreset","knownInstalls","knownInstallsVersion","knownInstallListeners","Set","setKnownPluginInstalls","installs","Map","map","listingId","undefined","listener","subscribeKnownPluginInstalls","add","delete","getKnownPluginInstallsVersion","hasKnownPluginInstalls","getKnownPluginInstall","get","getKnownPluginInstalls","values","sort","a","b","displayName","localeCompare"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAeD,IAAIA;AAEJ,OAAO,SAASC,kCACdC,EAA6B;IAE7BF,SAASE;AACX;AAeA,IAAIC;AAEJ,OAAO,SAASC,mCACdF,EAA8B;IAE9BC,gBAAgBD;AAClB;AAEA;;;CAGC,GACD,8DAA8D;AAC9D,OAAO,SAASG,uBAAuBC,OAAY;IACjD,IAAIH,eAAe,OAAOA,cAAcG;IACxC,MAAMC,SAASC,sBAAsBF;IACrC,OAAOC,SAAS;QAACA;KAAO,GAAG,EAAE;AAC/B;AAEA,2EAA2E,GAC3E,8DAA8D;AAC9D,OAAO,SAASC,sBAAsBF,OAAY;IAChD,OAAON,SAASA,OAAOM,WAAW;AACpC;AAmCA,IAAIG;AACJ;;;;;;CAMC,GACD,IAAIC,uBAAuB;AAC3B,MAAMC,wBAAwB,IAAIC;AAElC,6EAA6E,GAC7E,OAAO,SAASC,uBACdC,QAAmD;IAEnDL,gBAAgBK,WACZ,IAAIC,IAAID,SAASE,GAAG,CAAC,CAACV,UAAY;YAACA,QAAQW,SAAS;YAAEX;SAAQ,KAC9DY;IACJR,wBAAwB;IACxB,KAAK,MAAMS,YAAYR,sBAAuBQ;AAChD;AAEA,uEAAuE,GACvE,OAAO,SAASC,6BAA6BD,QAAoB;IAC/DR,sBAAsBU,GAAG,CAACF;IAC1B,OAAO;QACLR,sBAAsBW,MAAM,CAACH;IAC/B;AACF;AAEA,OAAO,SAASI;IACd,OAAOb;AACT;AAEA,4EAA4E,GAC5E,OAAO,SAASc;IACd,OAAOf,kBAAkBS;AAC3B;AAEA,OAAO,SAASO,sBACdR,SAA6B;IAE7B,OAAOA,YAAYR,iCAAAA,cAAeiB,GAAG,CAACT,aAAaC;AACrD;AAEA;;;;;CAKC,GACD,OAAO,SAASS;;IACd,OAAO;mBAAKlB,iCAAAA,cAAemB,MAAM,qBAAM,EAAE;KAAE,CAACC,IAAI,CAAC,CAACC,GAAGC;YAClDD,gBAA4CC;eAA7C,EAACD,iBAAAA,EAAEE,WAAW,YAAbF,iBAAiBA,EAAEb,SAAS,EAAEgB,aAAa,EAACF,iBAAAA,EAAEC,WAAW,YAAbD,iBAAiBA,EAAEd,SAAS;;AAE7E"}

package/src/lib/plugin-manager/media-delivery-provider.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @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.
+ */
+/**
+ * Media delivery through a provider outside this platform (AGL-2824).
+ *
+ * The media CDN serves every byte through a function, which is the right
+ * shape for images the edge can hold and the wrong one for video: a video
+ * is served `private` (AGL-1515), so every play pulls the whole file through
+ * the function and its transfer is billed twice over. A delivery provider is
+ * an object store with its own edge in front. The platform keeps every access
+ * decision and hands a caller a short-lived signed URL on the provider's
+ * host; the provider checks that URL and serves the bytes.
+ *
+ * Core defines the contract and never names a provider. A plugin registers
+ * the one implementation from its `serverDeclarations` entry, so the
+ * provider is registered in both apps before the first request, and core
+ * asks for it by capability:
+ *
+ *  - `store` — the provider can hold copies: `putObject`, `deleteObject`,
+ *    `deleteObjectsWithPrefix`. Only a process that writes copies needs the
+ *    credentials behind it.
+ *  - `deliver` — the provider can mint a delivery URL: `deliveryUrl`. Every
+ *    process that answers a media request needs it.
+ *
+ * A provider that is registered and not configured for a capability answers
+ * as absent for it, so a deployment with no provider settings behaves exactly
+ * as one without the plugin.
+ *
+ * ## What the platform keeps
+ *
+ * The media document stays the record of an asset, and the platform's own
+ * bucket keeps the bytes; a provider holds COPIES, keyed by the content hash
+ * they were made from (`media-delivery.ts` in `tenant-data-admin` owns the
+ * key grammar and the copy record). Nothing here authorizes a caller: every
+ * access decision is made before core asks the provider for a URL.
+ */
+/** What a provider must be configured for before core relies on it. */
+export type MediaDeliveryCapability = 'store' | 'deliver';
+/** The bytes of one copy. A stream is read once, start to end. */
+export type MediaDeliveryBody = ReadableStream<Uint8Array> | Uint8Array;
+export interface MediaDeliveryPutRequest {
+    /** The object key, from core's key grammar. */
+    key: string;
+    body: MediaDeliveryBody;
+    /** Exact byte length of `body`; the provider sends it as-is. */
+    contentLength: number;
+    /** The type the provider should serve the object as. */
+    contentType: string;
+}
+/**
+ * What a delivery URL carries about the request it was minted for, so a
+ * provider can attribute delivered bytes to an organization later. None of it
+ * authorizes anything: the URL is bound to its key, and the platform decided
+ * who may have it before minting.
+ */
+export interface MediaDeliveryClaims {
+    /** The CDN scope segment the asset was requested under. */
+    scope: string;
+    mediaId: string;
+    /** The owning organization, or null when it could not be resolved. */
+    orgId: string | null;
+    /** The site the delivery is for, or null for an org-wide request. */
+    hostId: string | null;
+}
+export interface MediaDeliveryUrlRequest {
+    key: string;
+    /** When the URL stops working. The provider may refuse a longer lifetime. */
+    expiresAtMs: number;
+    claims: MediaDeliveryClaims;
+}
+export interface MediaDeliveryProvider {
+    /** Whether this deployment has the settings `capability` needs. */
+    isConfigured(capability: MediaDeliveryCapability): boolean;
+    /** Stores one object under `key`, replacing any object already there. */
+    putObject(request: MediaDeliveryPutRequest): Promise<void>;
+    /** Removes `key`. Resolves when the key is absent, whether or not it existed. */
+    deleteObject(key: string): Promise<void>;
+    /**
+     * Removes every object whose key starts with `prefix`, and answers how
+     * many it removed. An erasure calls it with a scope's whole prefix.
+     */
+    deleteObjectsWithPrefix(prefix: string): Promise<number>;
+    /** A URL on the provider's host that serves `key` until `expiresAtMs`. */
+    deliveryUrl(request: MediaDeliveryUrlRequest): Promise<string>;
+}
+/**
+ * The slot one plugin holds. A second plugin registering a provider is a
+ * conflict, not a list: two providers would each hold half the copies, and
+ * a URL minted by one would name an object the other stores.
+ */
+export declare const MEDIA_DELIVERY_PROVIDER: import("./plugin-services").PluginServiceContract<MediaDeliveryProvider>;
+/**
+ * Registers the platform's delivery provider. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`. The same
+ * plugin registering again replaces its provider; a different plugin throws
+ * naming both.
+ */
+export declare function registerMediaDeliveryProvider(provider: MediaDeliveryProvider, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * The registered provider when it is configured for `capability`, else
+ * `null`. Synchronous and free of I/O, so a hot path can ask it first and pay
+ * nothing when no provider is set up.
+ *
+ * A provider whose configuration check throws answers as unconfigured: a
+ * delivery provider is an optimization over serving the bytes directly, and
+ * its failure must leave that path standing.
+ */
+export declare function mediaDeliveryProvider(capability: MediaDeliveryCapability): MediaDeliveryProvider | null;

package/src/lib/plugin-manager/media-delivery-provider.js

@@ -0,0 +1,53 @@
+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 { definePluginServiceContract, registerPluginService, resolvePluginService } from "./plugin-services.js";
+/**
+ * The slot one plugin holds. A second plugin registering a provider is a
+ * conflict, not a list: two providers would each hold half the copies, and
+ * a URL minted by one would name an object the other stores.
+ */ export const MEDIA_DELIVERY_PROVIDER = definePluginServiceContract('core.media-delivery', {
+    multiple: false
+});
+/**
+ * Registers the platform's delivery provider. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`. The same
+ * plugin registering again replaces its provider; a different plugin throws
+ * naming both.
+ */ export function registerMediaDeliveryProvider(provider, options) {
+    registerPluginService(MEDIA_DELIVERY_PROVIDER, provider, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/**
+ * The registered provider when it is configured for `capability`, else
+ * `null`. Synchronous and free of I/O, so a hot path can ask it first and pay
+ * nothing when no provider is set up.
+ *
+ * A provider whose configuration check throws answers as unconfigured: a
+ * delivery provider is an optimization over serving the bytes directly, and
+ * its failure must leave that path standing.
+ */ export function mediaDeliveryProvider(capability) {
+    const provider = resolvePluginService(MEDIA_DELIVERY_PROVIDER);
+    if (!provider) return null;
+    try {
+        return provider.isConfigured(capability) ? provider : null;
+    } catch (unused) {
+        return null;
+    }
+}
+
+//# sourceMappingURL=media-delivery-provider.js.map

package/src/lib/plugin-manager/media-delivery-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/media-delivery-provider.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 {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\n\n/**\n * Media delivery through a provider outside this platform (AGL-2824).\n *\n * The media CDN serves every byte through a function, which is the right\n * shape for images the edge can hold and the wrong one for video: a video\n * is served `private` (AGL-1515), so every play pulls the whole file through\n * the function and its transfer is billed twice over. A delivery provider is\n * an object store with its own edge in front. The platform keeps every access\n * decision and hands a caller a short-lived signed URL on the provider's\n * host; the provider checks that URL and serves the bytes.\n *\n * Core defines the contract and never names a provider. A plugin registers\n * the one implementation from its `serverDeclarations` entry, so the\n * provider is registered in both apps before the first request, and core\n * asks for it by capability:\n *\n *  - `store` — the provider can hold copies: `putObject`, `deleteObject`,\n *    `deleteObjectsWithPrefix`. Only a process that writes copies needs the\n *    credentials behind it.\n *  - `deliver` — the provider can mint a delivery URL: `deliveryUrl`. Every\n *    process that answers a media request needs it.\n *\n * A provider that is registered and not configured for a capability answers\n * as absent for it, so a deployment with no provider settings behaves exactly\n * as one without the plugin.\n *\n * ## What the platform keeps\n *\n * The media document stays the record of an asset, and the platform's own\n * bucket keeps the bytes; a provider holds COPIES, keyed by the content hash\n * they were made from (`media-delivery.ts` in `tenant-data-admin` owns the\n * key grammar and the copy record). Nothing here authorizes a caller: every\n * access decision is made before core asks the provider for a URL.\n */\n\n/** What a provider must be configured for before core relies on it. */\nexport type MediaDeliveryCapability = 'store' | 'deliver'\n\n/** The bytes of one copy. A stream is read once, start to end. */\nexport type MediaDeliveryBody = ReadableStream<Uint8Array> | Uint8Array\n\nexport interface MediaDeliveryPutRequest {\n  /** The object key, from core's key grammar. */\n  key: string\n  body: MediaDeliveryBody\n  /** Exact byte length of `body`; the provider sends it as-is. */\n  contentLength: number\n  /** The type the provider should serve the object as. */\n  contentType: string\n}\n\n/**\n * What a delivery URL carries about the request it was minted for, so a\n * provider can attribute delivered bytes to an organization later. None of it\n * authorizes anything: the URL is bound to its key, and the platform decided\n * who may have it before minting.\n */\nexport interface MediaDeliveryClaims {\n  /** The CDN scope segment the asset was requested under. */\n  scope: string\n  mediaId: string\n  /** The owning organization, or null when it could not be resolved. */\n  orgId: string | null\n  /** The site the delivery is for, or null for an org-wide request. */\n  hostId: string | null\n}\n\nexport interface MediaDeliveryUrlRequest {\n  key: string\n  /** When the URL stops working. The provider may refuse a longer lifetime. */\n  expiresAtMs: number\n  claims: MediaDeliveryClaims\n}\n\nexport interface MediaDeliveryProvider {\n  /** Whether this deployment has the settings `capability` needs. */\n  isConfigured(capability: MediaDeliveryCapability): boolean\n  /** Stores one object under `key`, replacing any object already there. */\n  putObject(request: MediaDeliveryPutRequest): Promise<void>\n  /** Removes `key`. Resolves when the key is absent, whether or not it existed. */\n  deleteObject(key: string): Promise<void>\n  /**\n   * Removes every object whose key starts with `prefix`, and answers how\n   * many it removed. An erasure calls it with a scope's whole prefix.\n   */\n  deleteObjectsWithPrefix(prefix: string): Promise<number>\n  /** A URL on the provider's host that serves `key` until `expiresAtMs`. */\n  deliveryUrl(request: MediaDeliveryUrlRequest): Promise<string>\n}\n\n/**\n * The slot one plugin holds. A second plugin registering a provider is a\n * conflict, not a list: two providers would each hold half the copies, and\n * a URL minted by one would name an object the other stores.\n */\nexport const MEDIA_DELIVERY_PROVIDER =\n  definePluginServiceContract<MediaDeliveryProvider>('core.media-delivery', {\n    multiple: false,\n  })\n\n/**\n * Registers the platform's delivery provider. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`. The same\n * plugin registering again replaces its provider; a different plugin throws\n * naming both.\n */\nexport function registerMediaDeliveryProvider(\n  provider: MediaDeliveryProvider,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(MEDIA_DELIVERY_PROVIDER, provider, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/**\n * The registered provider when it is configured for `capability`, else\n * `null`. Synchronous and free of I/O, so a hot path can ask it first and pay\n * nothing when no provider is set up.\n *\n * A provider whose configuration check throws answers as unconfigured: a\n * delivery provider is an optimization over serving the bytes directly, and\n * its failure must leave that path standing.\n */\nexport function mediaDeliveryProvider(\n  capability: MediaDeliveryCapability,\n): MediaDeliveryProvider | null {\n  const provider = resolvePluginService(MEDIA_DELIVERY_PROVIDER)\n  if (!provider) return null\n  try {\n    return provider.isConfigured(capability) ? provider : null\n  } catch {\n    return null\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","MEDIA_DELIVERY_PROVIDER","multiple","registerMediaDeliveryProvider","provider","options","pluginId","mediaDeliveryProvider","capability","isConfigured"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AA4F1B;;;;CAIC,GACD,OAAO,MAAMC,0BACXH,4BAAmD,uBAAuB;IACxEI,UAAU;AACZ,GAAE;AAEJ;;;;;CAKC,GACD,OAAO,SAASC,8BACdC,QAA+B,EAC/BC,OAA+B;IAE/BN,sBAAsBE,yBAAyBG,UAAU,aACnDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC,sBACdC,UAAmC;IAEnC,MAAMJ,WAAWJ,qBAAqBC;IACtC,IAAI,CAACG,UAAU,OAAO;IACtB,IAAI;QACF,OAAOA,SAASK,YAAY,CAACD,cAAcJ,WAAW;IACxD,EAAE,eAAM;QACN,OAAO;IACT;AACF"}

package/src/lib/plugin-manager/order-fulfilment.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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.
+ */
+/**
+ * The order-fulfilment capability (AGL-2461) — how a HOST APP records a
+ * shipment without importing the plugin that owns order semantics.
+ *
+ * ## Why this registry exists at all
+ *
+ * `eslint.config.mjs`'s `scope:app` → `notDependOnLibsWithTags:['aglyn:addons']`
+ * rule means `apps/console` may not import `@aglyn/plugins-commerce`, so the
+ * customer REST API could not reach `ORDER_TRANSITIONS`, `canTransitionOrder`,
+ * `liftLegacyOrder` or `appendOrderEvent` — and therefore could not record a
+ * shipment at all. The rule is not a preference: the app must stay runnable
+ * with any plugin absent, which is the whole plugin platform (AGL-417/419).
+ *
+ * The tempting escape is a second copy of the transition table inside `/v1`.
+ * That is the wrong one, and much worse than the projection drift `orderView`
+ * already tolerates: two transition tables drifting means **the API writes an
+ * order status the console forbids** — `paid → delivered` skipping fulfilment,
+ * or a write onto a `refunded` order — which is precisely the class of bug
+ * AGL-1818/AGL-1819 were opened to close.
+ *
+ * So the edge runs the way every other app↔plugin edge on this platform runs:
+ * the plugin registers an implementation into a core registry from its
+ * `/server` entry, and the app looks it up. Same shape as
+ * `registerBillingWebhookHandler`, `registerSitePageResolver` and
+ * `registerPluginJob`. Nothing is imported statically in either direction, the
+ * app compiles and boots with commerce absent, and there is exactly ONE
+ * implementation of the transition rule — the plugin's.
+ *
+ * ## THE REGISTRY CARRIES NO AUTHORIZATION. READ THIS BEFORE CALLING.
+ *
+ * `recordShipment` is a PRE-AUTHORIZED domain operation. It answers "may this
+ * order move to this status" (the transition rule, re-asked inside the write)
+ * and nothing whatsoever about "may this caller touch this order". It does not
+ * know who is asking — deliberately, because its two callers authenticate
+ * completely differently: the console's `commerce/fulfill-order` route
+ * verifies a Firebase ID token and reads `memberRoles[uid]`, while a `/v1`
+ * API key is an ORG credential with no uid at all.
+ *
+ * Every caller MUST therefore have already established, in its own terms:
+ *
+ * 1. **who the caller is** (session, or key), and
+ * 2. **that the caller's org owns `hostId`** — the org-scoping check, without
+ *    which this becomes a cross-tenant write primitive addressable by any
+ *    authenticated caller who can guess a host id, and
+ * 3. **that the plugin owning this service is switched on for that site**
+ *    (`isHostPluginEnabled`) — the registry is process-global and populated by
+ *    `ensureAll`, so a registered service says nothing about one org's
+ *    configuration.
+ *
+ * A single implementation is held, not a list: this is a capability with an
+ * owner, not a fan-out hook. Two plugins claiming order fulfilment is a
+ * misconfiguration, and last-registration-wins would resolve it silently, so
+ * {@link registerOrderFulfilmentService} refuses the second registration
+ * loudly instead.
+ */
+/**
+ * The two fulfilment-side transitions, and ONLY those.
+ *
+ * `cancelled` releases stock under its own transaction and `refunded` moves
+ * money under another, so neither belongs to a capability whose contract is
+ * "a forward status flip plus a timeline entry, no stock moved, no money
+ * moved". Widening this union is how a caller gets a door around the
+ * specifics those routes exist to enforce — the type is the door being shut.
+ */
+export type OrderFulfilmentTarget = 'fulfilled' | 'delivered';
+export interface RecordShipmentRequest {
+    /** Site that owns the order. The CALLER has already proven ownership. */
+    hostId: string;
+    orderId: string;
+    to: OrderFulfilmentTarget;
+    /** Free text, e.g. `'UPS'`. Implementations bound the length. */
+    carrier?: string;
+    trackingNumber?: string;
+}
+/**
+ * What happened, as a domain fact rather than an HTTP status — each caller
+ * maps it into its own error vocabulary (the console route into its JSON
+ * shape, `/v1` into the published error envelope), because those two
+ * vocabularies are contracts with different audiences and neither may leak
+ * into the other.
+ *
+ * `already` is a SUCCESS and is distinct from `recorded` on purpose: a retried
+ * request finds the order in the target status and returns without writing, so
+ * a lost response can never append a second copy of the same shipment. A
+ * caller that folded the two together would still be correct about the state
+ * and would lose the only signal that says "this was your retry".
+ */
+export type RecordShipmentOutcome = {
+    outcome: 'recorded';
+} | {
+    outcome: 'already';
+} | {
+    outcome: 'no_such_order';
+}
+/** The transition rule refused. `from` is the status that refused it. */
+ | {
+    outcome: 'blocked';
+    from: string;
+};
+export interface OrderFulfilmentService {
+    /**
+     * The plugin that owns this capability. Callers gate on THIS — never on a
+     * hard-coded `'commerce'` — which is what keeps the app free of any name
+     * from the addon layer.
+     */
+    pluginId: string;
+    recordShipment(request: RecordShipmentRequest): Promise<RecordShipmentOutcome>;
+}
+/**
+ * Registers the platform's order-fulfilment implementation, from a plugin's
+ * `/server` entry. Idempotent for the SAME plugin (the loader guarantees one
+ * activation per plugin+surface, but a re-registration must not be an error in
+ * a process that loads a surface twice); a DIFFERENT plugin claiming the
+ * capability throws, because silently overwriting it would hand order writes
+ * to whichever module happened to load last.
+ */
+export declare function registerOrderFulfilmentService(next: OrderFulfilmentService): void;
+/**
+ * The registered service, or `null` when no loaded plugin provides one — a
+ * deployment with commerce switched off, or a self-host build without it.
+ * `null` is an ordinary answer, never an error: callers turn it into "this
+ * endpoint does not exist here", which is the truth.
+ */
+export declare function getOrderFulfilmentService(): OrderFulfilmentService | null;
+/** Test seam: forget the registration. */
+export declare function resetOrderFulfilmentServiceForTests(): void;

package/src/lib/plugin-manager/order-fulfilment.js

@@ -0,0 +1,104 @@
+/**
+ * @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.
+ */ /**
+ * The order-fulfilment capability (AGL-2461) — how a HOST APP records a
+ * shipment without importing the plugin that owns order semantics.
+ *
+ * ## Why this registry exists at all
+ *
+ * `eslint.config.mjs`'s `scope:app` → `notDependOnLibsWithTags:['aglyn:addons']`
+ * rule means `apps/console` may not import `@aglyn/plugins-commerce`, so the
+ * customer REST API could not reach `ORDER_TRANSITIONS`, `canTransitionOrder`,
+ * `liftLegacyOrder` or `appendOrderEvent` — and therefore could not record a
+ * shipment at all. The rule is not a preference: the app must stay runnable
+ * with any plugin absent, which is the whole plugin platform (AGL-417/419).
+ *
+ * The tempting escape is a second copy of the transition table inside `/v1`.
+ * That is the wrong one, and much worse than the projection drift `orderView`
+ * already tolerates: two transition tables drifting means **the API writes an
+ * order status the console forbids** — `paid → delivered` skipping fulfilment,
+ * or a write onto a `refunded` order — which is precisely the class of bug
+ * AGL-1818/AGL-1819 were opened to close.
+ *
+ * So the edge runs the way every other app↔plugin edge on this platform runs:
+ * the plugin registers an implementation into a core registry from its
+ * `/server` entry, and the app looks it up. Same shape as
+ * `registerBillingWebhookHandler`, `registerSitePageResolver` and
+ * `registerPluginJob`. Nothing is imported statically in either direction, the
+ * app compiles and boots with commerce absent, and there is exactly ONE
+ * implementation of the transition rule — the plugin's.
+ *
+ * ## THE REGISTRY CARRIES NO AUTHORIZATION. READ THIS BEFORE CALLING.
+ *
+ * `recordShipment` is a PRE-AUTHORIZED domain operation. It answers "may this
+ * order move to this status" (the transition rule, re-asked inside the write)
+ * and nothing whatsoever about "may this caller touch this order". It does not
+ * know who is asking — deliberately, because its two callers authenticate
+ * completely differently: the console's `commerce/fulfill-order` route
+ * verifies a Firebase ID token and reads `memberRoles[uid]`, while a `/v1`
+ * API key is an ORG credential with no uid at all.
+ *
+ * Every caller MUST therefore have already established, in its own terms:
+ *
+ * 1. **who the caller is** (session, or key), and
+ * 2. **that the caller's org owns `hostId`** — the org-scoping check, without
+ *    which this becomes a cross-tenant write primitive addressable by any
+ *    authenticated caller who can guess a host id, and
+ * 3. **that the plugin owning this service is switched on for that site**
+ *    (`isHostPluginEnabled`) — the registry is process-global and populated by
+ *    `ensureAll`, so a registered service says nothing about one org's
+ *    configuration.
+ *
+ * A single implementation is held, not a list: this is a capability with an
+ * owner, not a fan-out hook. Two plugins claiming order fulfilment is a
+ * misconfiguration, and last-registration-wins would resolve it silently, so
+ * {@link registerOrderFulfilmentService} refuses the second registration
+ * loudly instead.
+ */ /**
+ * The two fulfilment-side transitions, and ONLY those.
+ *
+ * `cancelled` releases stock under its own transaction and `refunded` moves
+ * money under another, so neither belongs to a capability whose contract is
+ * "a forward status flip plus a timeline entry, no stock moved, no money
+ * moved". Widening this union is how a caller gets a door around the
+ * specifics those routes exist to enforce — the type is the door being shut.
+ */ let service = null;
+/**
+ * Registers the platform's order-fulfilment implementation, from a plugin's
+ * `/server` entry. Idempotent for the SAME plugin (the loader guarantees one
+ * activation per plugin+surface, but a re-registration must not be an error in
+ * a process that loads a surface twice); a DIFFERENT plugin claiming the
+ * capability throws, because silently overwriting it would hand order writes
+ * to whichever module happened to load last.
+ */ export function registerOrderFulfilmentService(next) {
+    if (service && service.pluginId !== next.pluginId) {
+        throw new Error(`Order fulfilment is already provided by "${service.pluginId}"; ` + `"${next.pluginId}" cannot also claim it`);
+    }
+    service = next;
+}
+/**
+ * The registered service, or `null` when no loaded plugin provides one — a
+ * deployment with commerce switched off, or a self-host build without it.
+ * `null` is an ordinary answer, never an error: callers turn it into "this
+ * endpoint does not exist here", which is the truth.
+ */ export function getOrderFulfilmentService() {
+    return service;
+}
+/** Test seam: forget the registration. */ export function resetOrderFulfilmentServiceForTests() {
+    service = null;
+}
+
+//# sourceMappingURL=order-fulfilment.js.map

package/src/lib/plugin-manager/order-fulfilment.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/order-fulfilment.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 * The order-fulfilment capability (AGL-2461) — how a HOST APP records a\n * shipment without importing the plugin that owns order semantics.\n *\n * ## Why this registry exists at all\n *\n * `eslint.config.mjs`'s `scope:app` → `notDependOnLibsWithTags:['aglyn:addons']`\n * rule means `apps/console` may not import `@aglyn/plugins-commerce`, so the\n * customer REST API could not reach `ORDER_TRANSITIONS`, `canTransitionOrder`,\n * `liftLegacyOrder` or `appendOrderEvent` — and therefore could not record a\n * shipment at all. The rule is not a preference: the app must stay runnable\n * with any plugin absent, which is the whole plugin platform (AGL-417/419).\n *\n * The tempting escape is a second copy of the transition table inside `/v1`.\n * That is the wrong one, and much worse than the projection drift `orderView`\n * already tolerates: two transition tables drifting means **the API writes an\n * order status the console forbids** — `paid → delivered` skipping fulfilment,\n * or a write onto a `refunded` order — which is precisely the class of bug\n * AGL-1818/AGL-1819 were opened to close.\n *\n * So the edge runs the way every other app↔plugin edge on this platform runs:\n * the plugin registers an implementation into a core registry from its\n * `/server` entry, and the app looks it up. Same shape as\n * `registerBillingWebhookHandler`, `registerSitePageResolver` and\n * `registerPluginJob`. Nothing is imported statically in either direction, the\n * app compiles and boots with commerce absent, and there is exactly ONE\n * implementation of the transition rule — the plugin's.\n *\n * ## THE REGISTRY CARRIES NO AUTHORIZATION. READ THIS BEFORE CALLING.\n *\n * `recordShipment` is a PRE-AUTHORIZED domain operation. It answers \"may this\n * order move to this status\" (the transition rule, re-asked inside the write)\n * and nothing whatsoever about \"may this caller touch this order\". It does not\n * know who is asking — deliberately, because its two callers authenticate\n * completely differently: the console's `commerce/fulfill-order` route\n * verifies a Firebase ID token and reads `memberRoles[uid]`, while a `/v1`\n * API key is an ORG credential with no uid at all.\n *\n * Every caller MUST therefore have already established, in its own terms:\n *\n * 1. **who the caller is** (session, or key), and\n * 2. **that the caller's org owns `hostId`** — the org-scoping check, without\n *    which this becomes a cross-tenant write primitive addressable by any\n *    authenticated caller who can guess a host id, and\n * 3. **that the plugin owning this service is switched on for that site**\n *    (`isHostPluginEnabled`) — the registry is process-global and populated by\n *    `ensureAll`, so a registered service says nothing about one org's\n *    configuration.\n *\n * A single implementation is held, not a list: this is a capability with an\n * owner, not a fan-out hook. Two plugins claiming order fulfilment is a\n * misconfiguration, and last-registration-wins would resolve it silently, so\n * {@link registerOrderFulfilmentService} refuses the second registration\n * loudly instead.\n */\n\n/**\n * The two fulfilment-side transitions, and ONLY those.\n *\n * `cancelled` releases stock under its own transaction and `refunded` moves\n * money under another, so neither belongs to a capability whose contract is\n * \"a forward status flip plus a timeline entry, no stock moved, no money\n * moved\". Widening this union is how a caller gets a door around the\n * specifics those routes exist to enforce — the type is the door being shut.\n */\nexport type OrderFulfilmentTarget = 'fulfilled' | 'delivered'\n\nexport interface RecordShipmentRequest {\n  /** Site that owns the order. The CALLER has already proven ownership. */\n  hostId: string\n  orderId: string\n  to: OrderFulfilmentTarget\n  /** Free text, e.g. `'UPS'`. Implementations bound the length. */\n  carrier?: string\n  trackingNumber?: string\n}\n\n/**\n * What happened, as a domain fact rather than an HTTP status — each caller\n * maps it into its own error vocabulary (the console route into its JSON\n * shape, `/v1` into the published error envelope), because those two\n * vocabularies are contracts with different audiences and neither may leak\n * into the other.\n *\n * `already` is a SUCCESS and is distinct from `recorded` on purpose: a retried\n * request finds the order in the target status and returns without writing, so\n * a lost response can never append a second copy of the same shipment. A\n * caller that folded the two together would still be correct about the state\n * and would lose the only signal that says \"this was your retry\".\n */\nexport type RecordShipmentOutcome =\n  | { outcome: 'recorded' }\n  | { outcome: 'already' }\n  | { outcome: 'no_such_order' }\n  /** The transition rule refused. `from` is the status that refused it. */\n  | { outcome: 'blocked'; from: string }\n\nexport interface OrderFulfilmentService {\n  /**\n   * The plugin that owns this capability. Callers gate on THIS — never on a\n   * hard-coded `'commerce'` — which is what keeps the app free of any name\n   * from the addon layer.\n   */\n  pluginId: string\n  recordShipment(request: RecordShipmentRequest): Promise<RecordShipmentOutcome>\n}\n\nlet service: OrderFulfilmentService | null = null\n\n/**\n * Registers the platform's order-fulfilment implementation, from a plugin's\n * `/server` entry. Idempotent for the SAME plugin (the loader guarantees one\n * activation per plugin+surface, but a re-registration must not be an error in\n * a process that loads a surface twice); a DIFFERENT plugin claiming the\n * capability throws, because silently overwriting it would hand order writes\n * to whichever module happened to load last.\n */\nexport function registerOrderFulfilmentService(\n  next: OrderFulfilmentService,\n): void {\n  if (service && service.pluginId !== next.pluginId) {\n    throw new Error(\n      `Order fulfilment is already provided by \"${service.pluginId}\"; ` +\n        `\"${next.pluginId}\" cannot also claim it`,\n    )\n  }\n  service = next\n}\n\n/**\n * The registered service, or `null` when no loaded plugin provides one — a\n * deployment with commerce switched off, or a self-host build without it.\n * `null` is an ordinary answer, never an error: callers turn it into \"this\n * endpoint does not exist here\", which is the truth.\n */\nexport function getOrderFulfilmentService(): OrderFulfilmentService | null {\n  return service\n}\n\n/** Test seam: forget the registration. */\nexport function resetOrderFulfilmentServiceForTests(): void {\n  service = null\n}\n"],"names":["service","registerOrderFulfilmentService","next","pluginId","Error","getOrderFulfilmentService","resetOrderFulfilmentServiceForTests"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDC,GAED;;;;;;;;CAQC,GA2CD,IAAIA,UAAyC;AAE7C;;;;;;;CAOC,GACD,OAAO,SAASC,+BACdC,IAA4B;IAE5B,IAAIF,WAAWA,QAAQG,QAAQ,KAAKD,KAAKC,QAAQ,EAAE;QACjD,MAAM,IAAIC,MACR,CAAC,yCAAyC,EAAEJ,QAAQG,QAAQ,CAAC,GAAG,CAAC,GAC/D,CAAC,CAAC,EAAED,KAAKC,QAAQ,CAAC,sBAAsB,CAAC;IAE/C;IACAH,UAAUE;AACZ;AAEA;;;;;CAKC,GACD,OAAO,SAASG;IACd,OAAOL;AACT;AAEA,wCAAwC,GACxC,OAAO,SAASM;IACdN,UAAU;AACZ"}