@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-org-erasure.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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.
+ */
+/** What an eraser is asked to erase. */
+export interface PluginOrgErasureRequest {
+    /** The workspace being erased. */
+    orgId: string;
+    /**
+     * A plan, not an erasure: count, touch no provider, write nothing. The
+     * erasure's own sweeps honor the same flag.
+     */
+    dryRun: boolean;
+}
+/**
+ * What an eraser reports for the erasure's audit record: counts and flags,
+ * never the erased content, because the record outlives the data by design.
+ * A `null` field is a figure the eraser could not measure, which is not zero.
+ */
+export type PluginOrgErasureReport = Readonly<Record<string, number | boolean | null>>;
+export type PluginOrgEraser = (request: PluginOrgErasureRequest) => Promise<PluginOrgErasureReport>;
+/**
+ * Registers a plugin's workspace eraser. Owner = the loader's marker inside a
+ * register fn, else `options.pluginId`; an eraser with neither throws. One
+ * eraser per plugin: registering again replaces the plugin's earlier eraser
+ * in place, so a module evaluated twice does not erase twice.
+ */
+export declare function registerPluginOrgEraser(eraser: PluginOrgEraser, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * Runs every eraser, in registration order, and answers each plugin's
+ * report by plugin id: the eraser's own report, or `null` for one that
+ * threw. Never throws.
+ */
+export declare function runPluginOrgErasers(request: PluginOrgErasureRequest): Promise<Record<string, PluginOrgErasureReport | null>>;
+/** The plugins with a workspace eraser, in the order they run. */
+export declare function listPluginOrgErasers(): string[];
+/** Test seam: forget every eraser. */
+export declare function resetPluginOrgErasersForTests(): void;

package/src/lib/plugin-manager/plugin-org-erasure.js

@@ -0,0 +1,100 @@
+/**
+ * @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.
+ */ /**
+ * A plugin's share of a workspace erasure (AGL-2978).
+ *
+ * The workspace erasure destroys what the platform holds for an
+ * organization: its document tree, its sites, and the top-level records
+ * keyed to it by a field. A plugin that holds something those deletes cannot
+ * finish on their own registers an eraser here — a grant at a provider that
+ * only the plugin can revoke, or a record outside every path and field the
+ * erasure sweeps — and the erasure runs every eraser with the organization's
+ * id.
+ *
+ * Erasers run BEFORE the erasure deletes anything of its own. The
+ * organization, its roster and every record the erasure is about to sweep
+ * still exist when an eraser runs, so an eraser that has to act through a
+ * record — open a stored grant to revoke it — finds the record there. What
+ * the erasure deletes on its own stays its to delete: an eraser adds to the
+ * erasure, and the erasure does not wait on one to finish its own sweeps.
+ *
+ * Erasers run in registration order and are ISOLATED: a throw is logged
+ * against its plugin, recorded as `null`, and does not stop the next one or
+ * the erasure. An erasure runs against a legal clock, and one plugin's
+ * outage must not keep every other plugin's data, or the workspace, past it.
+ * The `null` is how the erasure's audit record says that plugin's share may
+ * not be done, which a report of zero would hide.
+ *
+ * A DRY RUN is handed to every eraser, which must then touch no provider and
+ * write nothing: it counts what it would do. A plan that reached a vendor
+ * would be an erasure that happened without anybody deciding it should.
+ *
+ * Registered from a plugin's declarations — `serverDeclarations`, or
+ * `consoleServerDeclarations` for an eraser that opens a credential only the
+ * console holds — so the eraser is in place in a server process that never
+ * loaded the plugin's API surface.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const registrations = [];
+/**
+ * Registers a plugin's workspace eraser. Owner = the loader's marker inside a
+ * register fn, else `options.pluginId`; an eraser with neither throws. One
+ * eraser per plugin: registering again replaces the plugin's earlier eraser
+ * in place, so a module evaluated twice does not erase twice.
+ */ export function registerPluginOrgEraser(eraser, 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('a plugin org eraser was registered with no owner: pass { pluginId } ' + 'when registering outside a plugin register fn');
+    }
+    const index = registrations.findIndex((entry)=>entry.pluginId === pluginId);
+    if (index >= 0) registrations[index] = {
+        pluginId,
+        eraser
+    };
+    else registrations.push({
+        pluginId,
+        eraser
+    });
+}
+/**
+ * Runs every eraser, in registration order, and answers each plugin's
+ * report by plugin id: the eraser's own report, or `null` for one that
+ * threw. Never throws.
+ */ export async function runPluginOrgErasers(request) {
+    const reports = {};
+    for (const { pluginId, eraser } of [
+        ...registrations
+    ]){
+        try {
+            reports[pluginId] = await eraser({
+                orgId: request.orgId,
+                dryRun: request.dryRun
+            });
+        } catch (error) {
+            reports[pluginId] = null;
+            console.error(`[plugins] ${pluginId} failed to erase org ${request.orgId}`, error);
+        }
+    }
+    return reports;
+}
+/** The plugins with a workspace eraser, in the order they run. */ export function listPluginOrgErasers() {
+    return registrations.map((entry)=>entry.pluginId);
+}
+/** Test seam: forget every eraser. */ export function resetPluginOrgErasersForTests() {
+    registrations.length = 0;
+}
+
+//# sourceMappingURL=plugin-org-erasure.js.map

package/src/lib/plugin-manager/plugin-org-erasure.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-org-erasure.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 * A plugin's share of a workspace erasure (AGL-2978).\n *\n * The workspace erasure destroys what the platform holds for an\n * organization: its document tree, its sites, and the top-level records\n * keyed to it by a field. A plugin that holds something those deletes cannot\n * finish on their own registers an eraser here — a grant at a provider that\n * only the plugin can revoke, or a record outside every path and field the\n * erasure sweeps — and the erasure runs every eraser with the organization's\n * id.\n *\n * Erasers run BEFORE the erasure deletes anything of its own. The\n * organization, its roster and every record the erasure is about to sweep\n * still exist when an eraser runs, so an eraser that has to act through a\n * record — open a stored grant to revoke it — finds the record there. What\n * the erasure deletes on its own stays its to delete: an eraser adds to the\n * erasure, and the erasure does not wait on one to finish its own sweeps.\n *\n * Erasers run in registration order and are ISOLATED: a throw is logged\n * against its plugin, recorded as `null`, and does not stop the next one or\n * the erasure. An erasure runs against a legal clock, and one plugin's\n * outage must not keep every other plugin's data, or the workspace, past it.\n * The `null` is how the erasure's audit record says that plugin's share may\n * not be done, which a report of zero would hide.\n *\n * A DRY RUN is handed to every eraser, which must then touch no provider and\n * write nothing: it counts what it would do. A plan that reached a vendor\n * would be an erasure that happened without anybody deciding it should.\n *\n * Registered from a plugin's declarations — `serverDeclarations`, or\n * `consoleServerDeclarations` for an eraser that opens a credential only the\n * console holds — so the eraser is in place in a server process that never\n * loaded the plugin's API surface.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** What an eraser is asked to erase. */\nexport interface PluginOrgErasureRequest {\n  /** The workspace being erased. */\n  orgId: string\n  /**\n   * A plan, not an erasure: count, touch no provider, write nothing. The\n   * erasure's own sweeps honor the same flag.\n   */\n  dryRun: boolean\n}\n\n/**\n * What an eraser reports for the erasure's audit record: counts and flags,\n * never the erased content, because the record outlives the data by design.\n * A `null` field is a figure the eraser could not measure, which is not zero.\n */\nexport type PluginOrgErasureReport = Readonly<Record<string, number | boolean | null>>\n\nexport type PluginOrgEraser = (\n  request: PluginOrgErasureRequest,\n) => Promise<PluginOrgErasureReport>\n\ninterface Registration {\n  pluginId: string\n  eraser: PluginOrgEraser\n}\n\nconst registrations: Registration[] = []\n\n/**\n * Registers a plugin's workspace eraser. Owner = the loader's marker inside a\n * register fn, else `options.pluginId`; an eraser with neither throws. One\n * eraser per plugin: registering again replaces the plugin's earlier eraser\n * in place, so a module evaluated twice does not erase twice.\n */\nexport function registerPluginOrgEraser(\n  eraser: PluginOrgEraser,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin org eraser was registered with no owner: pass { pluginId } ' +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const index = registrations.findIndex((entry) => entry.pluginId === pluginId)\n  if (index >= 0) registrations[index] = { pluginId, eraser }\n  else registrations.push({ pluginId, eraser })\n}\n\n/**\n * Runs every eraser, in registration order, and answers each plugin's\n * report by plugin id: the eraser's own report, or `null` for one that\n * threw. Never throws.\n */\nexport async function runPluginOrgErasers(\n  request: PluginOrgErasureRequest,\n): Promise<Record<string, PluginOrgErasureReport | null>> {\n  const reports: Record<string, PluginOrgErasureReport | null> = {}\n  for (const { pluginId, eraser } of [...registrations]) {\n    try {\n      reports[pluginId] = await eraser({ orgId: request.orgId, dryRun: request.dryRun })\n    } catch (error) {\n      reports[pluginId] = null\n      console.error(`[plugins] ${pluginId} failed to erase org ${request.orgId}`, error)\n    }\n  }\n  return reports\n}\n\n/** The plugins with a workspace eraser, in the order they run. */\nexport function listPluginOrgErasers(): string[] {\n  return registrations.map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every eraser. */\nexport function resetPluginOrgErasersForTests(): void {\n  registrations.length = 0\n}\n"],"names":["getRegisteringPluginId","registrations","registerPluginOrgEraser","eraser","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginOrgErasers","request","reports","orgId","dryRun","error","console","listPluginOrgErasers","map","resetPluginOrgErasersForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AA6BxE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,wBACdC,MAAuB,EACvBC,OAA+B;QAEbJ,MAAAA;IAAlB,MAAMK,WAAW,EAACL,QAAAA,0BAAAA,oCAAAA,0BAA4BI,2BAAAA,QAASC,QAAQ,YAA7CL,OAAiD,IAAIM,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,yEACE;IAEN;IACA,MAAMC,QAAQP,cAAcQ,SAAS,CAAC,CAACC,QAAUA,MAAML,QAAQ,KAAKA;IACpE,IAAIG,SAAS,GAAGP,aAAa,CAACO,MAAM,GAAG;QAAEH;QAAUF;IAAO;SACrDF,cAAcU,IAAI,CAAC;QAAEN;QAAUF;IAAO;AAC7C;AAEA;;;;CAIC,GACD,OAAO,eAAeS,oBACpBC,OAAgC;IAEhC,MAAMC,UAAyD,CAAC;IAChE,KAAK,MAAM,EAAET,QAAQ,EAAEF,MAAM,EAAE,IAAI;WAAIF;KAAc,CAAE;QACrD,IAAI;YACFa,OAAO,CAACT,SAAS,GAAG,MAAMF,OAAO;gBAAEY,OAAOF,QAAQE,KAAK;gBAAEC,QAAQH,QAAQG,MAAM;YAAC;QAClF,EAAE,OAAOC,OAAO;YACdH,OAAO,CAACT,SAAS,GAAG;YACpBa,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEZ,SAAS,qBAAqB,EAAEQ,QAAQE,KAAK,EAAE,EAAEE;QAC9E;IACF;IACA,OAAOH;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASK;IACd,OAAOlB,cAAcmB,GAAG,CAAC,CAACV,QAAUA,MAAML,QAAQ;AACpD;AAEA,oCAAoC,GACpC,OAAO,SAASgB;IACdpB,cAAcqB,MAAM,GAAG;AACzB"}

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

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Plugin-declared permissions (AGL-435, Strapi RBAC-actions parity): a
+ * plugin contributes NAMED permission keys with per-role-tier defaults.
+ * `resolveRolePermissions` spreads them into every resolved set (custom
+ * roles override key-by-key exactly like built-in keys), so
+ * `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).
+ */
+export interface PluginPermission {
+    /** Stable key ('managePos') — persisted in custom role docs. */
+    key: string;
+    pluginId: string;
+    label: string;
+    description?: string;
+    /** Verdict per built-in role tier when a role doesn't name the key. */
+    defaults: {
+        admin: boolean;
+        editor: boolean;
+        viewer: boolean;
+    };
+}
+/**
+ * Idempotent per key FOR ITS OWNER — the declaring plugin may re-register
+ * (hot reload, a second surface, a repeated init) and its entry is replaced.
+ *
+ * A key already declared by a DIFFERENT plugin is refused (AGL-2484). This
+ * map keyed on `permission.key` alone, so a later registration could redeclare
+ * someone else's key with its own tier defaults — and these defaults are not
+ * cosmetic: `managePos` is enforced server-side in
+ * `libs/plugins/commerce/src/lib/server/pos-order.ts`, so moving
+ * `defaults.viewer` to `true` hands a viewer the register. Reaching this
+ * needs `PLUGIN_REMOTE_SERVER=enabled` (off by default), realm trust and a
+ * signature; the registry closing its own door is the cheap part of that
+ * stack.
+ *
+ * Per KEY, not per batch: a bundle that collides on one key still gets the
+ * keys that are genuinely its own.
+ */
+export declare function registerPluginPermissions(permissions: readonly PluginPermission[]): void;
+export declare function listPluginPermissions(): PluginPermission[];
+/**
+ * The registered keys alone (AGL-2474). `resolveRolePermissions` needs the
+ * grantable key SPACE, not the tier verdicts: it used to iterate
+ * `ORG_ROLE_PERMISSION_KEYS` — the legacy six — when applying overrides and
+ * custom roles, so a plugin-declared key materialised into the resolved map
+ * and could then only ever hold its tier default. Read live rather than
+ * snapshotted: registration happens at plugin module scope, which can run
+ * after any module-level constant here has already been evaluated.
+ */
+export declare function listPluginPermissionKeys(): string[];
+/** Tier defaults for every registered plugin permission. */
+export declare function pluginPermissionDefaults(tier: 'admin' | 'editor' | 'viewer'): Record<string, boolean>;

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

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Plugin-declared permissions (AGL-435, Strapi RBAC-actions parity): a
+ * plugin contributes NAMED permission keys with per-role-tier defaults.
+ * `resolveRolePermissions` spreads them into every resolved set (custom
+ * roles override key-by-key exactly like built-in keys), so
+ * `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();
+/**
+ * Idempotent per key FOR ITS OWNER — the declaring plugin may re-register
+ * (hot reload, a second surface, a repeated init) and its entry is replaced.
+ *
+ * A key already declared by a DIFFERENT plugin is refused (AGL-2484). This
+ * map keyed on `permission.key` alone, so a later registration could redeclare
+ * someone else's key with its own tier defaults — and these defaults are not
+ * cosmetic: `managePos` is enforced server-side in
+ * `libs/plugins/commerce/src/lib/server/pos-order.ts`, so moving
+ * `defaults.viewer` to `true` hands a viewer the register. Reaching this
+ * needs `PLUGIN_REMOTE_SERVER=enabled` (off by default), realm trust and a
+ * signature; the registry closing its own door is the cheap part of that
+ * stack.
+ *
+ * Per KEY, not per batch: a bundle that collides on one key still gets the
+ * keys that are genuinely its own.
+ */ export function registerPluginPermissions(permissions) {
+    for (const permission of permissions){
+        const incumbent = pluginPermissions.get(permission.key);
+        if (incumbent !== undefined && incumbent.pluginId !== permission.pluginId) {
+            console.error(`[plugins] refused permission key "${permission.key}" to ` + `"${permission.pluginId}": already declared by ` + `"${incumbent.pluginId}"`);
+            continue;
+        }
+        pluginPermissions.set(permission.key, permission);
+    }
+}
+export function listPluginPermissions() {
+    return [
+        ...pluginPermissions.values()
+    ];
+}
+/**
+ * The registered keys alone (AGL-2474). `resolveRolePermissions` needs the
+ * grantable key SPACE, not the tier verdicts: it used to iterate
+ * `ORG_ROLE_PERMISSION_KEYS` — the legacy six — when applying overrides and
+ * custom roles, so a plugin-declared key materialised into the resolved map
+ * and could then only ever hold its tier default. Read live rather than
+ * snapshotted: registration happens at plugin module scope, which can run
+ * after any module-level constant here has already been evaluated.
+ */ export function listPluginPermissionKeys() {
+    return [
+        ...pluginPermissions.keys()
+    ];
+}
+/** Tier defaults for every registered plugin permission. */ export function pluginPermissionDefaults(tier) {
+    const defaults = {};
+    for (const permission of pluginPermissions.values()){
+        defaults[permission.key] = permission.defaults[tier];
+    }
+    return defaults;
+}
+
+//# sourceMappingURL=plugin-permissions.js.map

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

@@ -0,0 +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 * 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}\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","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;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASC,0BACdC,WAAwC;IAExC,KAAK,MAAMC,cAAcD,YAAa;QACpC,MAAME,YAAYL,kBAAkBM,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;QACAT,kBAAkBY,GAAG,CAACR,WAAWG,GAAG,EAAEH;IACxC;AACF;AAEA,OAAO,SAASS;IACd,OAAO;WAAIb,kBAAkBc,MAAM;KAAG;AACxC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC;IACd,OAAO;WAAIf,kBAAkBgB,IAAI;KAAG;AACtC;AAEA,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,IAAmC;IAEnC,MAAMC,WAAoC,CAAC;IAC3C,KAAK,MAAMf,cAAcJ,kBAAkBc,MAAM,GAAI;QACnDK,QAAQ,CAACf,WAAWG,GAAG,CAAC,GAAGH,WAAWe,QAAQ,CAACD,KAAK;IACtD;IACA,OAAOC;AACT"}

package/src/lib/plugin-manager/plugin-person-erasure.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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.
+ */
+/** Who is being erased, and from which workspace. */
+export interface PluginPersonErasureRequest {
+    /** The workspace the person is erased from. */
+    orgId: string;
+    /** The person's address, normalized. */
+    email: string;
+    /**
+     * `personKey(email)`: how every suppression list, and any list a plugin
+     * keeps in the same way, names the person without their address.
+     */
+    key: string;
+    /** The contact documents the erasure is about to delete, by id. */
+    contactIds: readonly string[];
+    /** A plan, not an erasure: count, write nothing. */
+    dryRun: boolean;
+}
+/**
+ * What an eraser reports for the erasure's audit record: counts and flags,
+ * never the erased content. A `null` field is a figure the eraser could not
+ * measure, which is not zero.
+ */
+export type PluginPersonErasureReport = Readonly<Record<string, number | boolean | null>>;
+export type PluginPersonEraser = (request: PluginPersonErasureRequest) => Promise<PluginPersonErasureReport>;
+/**
+ * Registers a plugin's person eraser. Owner = the loader's marker inside a
+ * register fn, else `options.pluginId`; an eraser with neither throws. One
+ * eraser per plugin: registering again replaces the plugin's earlier eraser
+ * in place, so a module evaluated twice does not erase twice.
+ */
+export declare function registerPluginPersonEraser(eraser: PluginPersonEraser, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * Runs every eraser, in registration order, and answers each plugin's
+ * report by plugin id: the eraser's own report, or `null` for one that
+ * threw. Never throws.
+ */
+export declare function runPluginPersonErasers(request: PluginPersonErasureRequest): Promise<Record<string, PluginPersonErasureReport | null>>;
+/** The plugins with a person eraser, in the order they run. */
+export declare function listPluginPersonErasers(): string[];
+/** Test seam: forget every eraser. */
+export declare function resetPluginPersonErasersForTests(): void;

package/src/lib/plugin-manager/plugin-person-erasure.js

@@ -0,0 +1,109 @@
+/**
+ * @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.
+ */ /**
+ * A plugin's share of a PERSON erasure (AGL-2981).
+ *
+ * The person erasure removes one person from one workspace — a contact the
+ * workspace kept, not an account: the contact document, what the CRM files
+ * beside it, the leads, list memberships and delivery log under the
+ * address, and the person's identity on orders and bookings. A plugin that
+ * keeps records about such a person where none of those sweeps reach — a
+ * collection under the organization keyed by the contact or by the address
+ * — registers an eraser here, and the erasure runs every eraser with the
+ * person's address, its key and the contacts it is about to delete.
+ *
+ * Erasers run AFTER the erasure has closed the door and BEFORE it deletes
+ * the contacts: every site's suppression row is already written, so nothing
+ * a plugin sends can reach the person while its eraser runs, and the contact
+ * documents still exist for an eraser that has to read one.
+ *
+ * The two halves of the rule that holds everywhere else in the erasure hold
+ * here too. A record ABOUT the person goes. A record that the person asked
+ * not to be contacted — keyed by `personKey`, the hash every suppression
+ * list is keyed by, and holding no address — is KEPT, because the promise
+ * it records has to outlive the person's data; an eraser strips from it
+ * anything that could identify the person again.
+ *
+ * Erasers run in registration order and are ISOLATED: a throw is logged
+ * against its plugin, recorded as `null`, and does not stop the next one or
+ * the erasure. The `null` is how the erasure's audit record says that
+ * plugin's share may remain, which a report of zero would hide.
+ *
+ * A DRY RUN is handed to every eraser, which must then write nothing: it
+ * counts what it would do.
+ *
+ * Registered from a plugin's declarations — `serverDeclarations`, or
+ * `consoleServerDeclarations` for a plugin whose server code runs only in
+ * the console — so the eraser is in place in a process that never loaded
+ * the plugin's API surface.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const registrations = [];
+/**
+ * Registers a plugin's person eraser. Owner = the loader's marker inside a
+ * register fn, else `options.pluginId`; an eraser with neither throws. One
+ * eraser per plugin: registering again replaces the plugin's earlier eraser
+ * in place, so a module evaluated twice does not erase twice.
+ */ export function registerPluginPersonEraser(eraser, 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('a plugin person eraser was registered with no owner: pass { pluginId } ' + 'when registering outside a plugin register fn');
+    }
+    const index = registrations.findIndex((entry)=>entry.pluginId === pluginId);
+    if (index >= 0) registrations[index] = {
+        pluginId,
+        eraser
+    };
+    else registrations.push({
+        pluginId,
+        eraser
+    });
+}
+/**
+ * Runs every eraser, in registration order, and answers each plugin's
+ * report by plugin id: the eraser's own report, or `null` for one that
+ * threw. Never throws.
+ */ export async function runPluginPersonErasers(request) {
+    const reports = {};
+    for (const { pluginId, eraser } of [
+        ...registrations
+    ]){
+        try {
+            reports[pluginId] = await eraser({
+                orgId: request.orgId,
+                email: request.email,
+                key: request.key,
+                contactIds: [
+                    ...request.contactIds
+                ],
+                dryRun: request.dryRun
+            });
+        } catch (error) {
+            reports[pluginId] = null;
+            // The org, never the address: this line outlives the erasure.
+            console.error(`[plugins] ${pluginId} failed to erase a person in org ${request.orgId}`, error);
+        }
+    }
+    return reports;
+}
+/** The plugins with a person eraser, in the order they run. */ export function listPluginPersonErasers() {
+    return registrations.map((entry)=>entry.pluginId);
+}
+/** Test seam: forget every eraser. */ export function resetPluginPersonErasersForTests() {
+    registrations.length = 0;
+}
+
+//# sourceMappingURL=plugin-person-erasure.js.map

package/src/lib/plugin-manager/plugin-person-erasure.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-person-erasure.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 * A plugin's share of a PERSON erasure (AGL-2981).\n *\n * The person erasure removes one person from one workspace — a contact the\n * workspace kept, not an account: the contact document, what the CRM files\n * beside it, the leads, list memberships and delivery log under the\n * address, and the person's identity on orders and bookings. A plugin that\n * keeps records about such a person where none of those sweeps reach — a\n * collection under the organization keyed by the contact or by the address\n * — registers an eraser here, and the erasure runs every eraser with the\n * person's address, its key and the contacts it is about to delete.\n *\n * Erasers run AFTER the erasure has closed the door and BEFORE it deletes\n * the contacts: every site's suppression row is already written, so nothing\n * a plugin sends can reach the person while its eraser runs, and the contact\n * documents still exist for an eraser that has to read one.\n *\n * The two halves of the rule that holds everywhere else in the erasure hold\n * here too. A record ABOUT the person goes. A record that the person asked\n * not to be contacted — keyed by `personKey`, the hash every suppression\n * list is keyed by, and holding no address — is KEPT, because the promise\n * it records has to outlive the person's data; an eraser strips from it\n * anything that could identify the person again.\n *\n * Erasers run in registration order and are ISOLATED: a throw is logged\n * against its plugin, recorded as `null`, and does not stop the next one or\n * the erasure. The `null` is how the erasure's audit record says that\n * plugin's share may remain, which a report of zero would hide.\n *\n * A DRY RUN is handed to every eraser, which must then write nothing: it\n * counts what it would do.\n *\n * Registered from a plugin's declarations — `serverDeclarations`, or\n * `consoleServerDeclarations` for a plugin whose server code runs only in\n * the console — so the eraser is in place in a process that never loaded\n * the plugin's API surface.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** Who is being erased, and from which workspace. */\nexport interface PluginPersonErasureRequest {\n  /** The workspace the person is erased from. */\n  orgId: string\n  /** The person's address, normalized. */\n  email: string\n  /**\n   * `personKey(email)`: how every suppression list, and any list a plugin\n   * keeps in the same way, names the person without their address.\n   */\n  key: string\n  /** The contact documents the erasure is about to delete, by id. */\n  contactIds: readonly string[]\n  /** A plan, not an erasure: count, write nothing. */\n  dryRun: boolean\n}\n\n/**\n * What an eraser reports for the erasure's audit record: counts and flags,\n * never the erased content. A `null` field is a figure the eraser could not\n * measure, which is not zero.\n */\nexport type PluginPersonErasureReport = Readonly<Record<string, number | boolean | null>>\n\nexport type PluginPersonEraser = (\n  request: PluginPersonErasureRequest,\n) => Promise<PluginPersonErasureReport>\n\ninterface Registration {\n  pluginId: string\n  eraser: PluginPersonEraser\n}\n\nconst registrations: Registration[] = []\n\n/**\n * Registers a plugin's person eraser. Owner = the loader's marker inside a\n * register fn, else `options.pluginId`; an eraser with neither throws. One\n * eraser per plugin: registering again replaces the plugin's earlier eraser\n * in place, so a module evaluated twice does not erase twice.\n */\nexport function registerPluginPersonEraser(\n  eraser: PluginPersonEraser,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin person eraser was registered with no owner: pass { pluginId } ' +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const index = registrations.findIndex((entry) => entry.pluginId === pluginId)\n  if (index >= 0) registrations[index] = { pluginId, eraser }\n  else registrations.push({ pluginId, eraser })\n}\n\n/**\n * Runs every eraser, in registration order, and answers each plugin's\n * report by plugin id: the eraser's own report, or `null` for one that\n * threw. Never throws.\n */\nexport async function runPluginPersonErasers(\n  request: PluginPersonErasureRequest,\n): Promise<Record<string, PluginPersonErasureReport | null>> {\n  const reports: Record<string, PluginPersonErasureReport | null> = {}\n  for (const { pluginId, eraser } of [...registrations]) {\n    try {\n      reports[pluginId] = await eraser({\n        orgId: request.orgId,\n        email: request.email,\n        key: request.key,\n        contactIds: [...request.contactIds],\n        dryRun: request.dryRun,\n      })\n    } catch (error) {\n      reports[pluginId] = null\n      // The org, never the address: this line outlives the erasure.\n      console.error(`[plugins] ${pluginId} failed to erase a person in org ${request.orgId}`, error)\n    }\n  }\n  return reports\n}\n\n/** The plugins with a person eraser, in the order they run. */\nexport function listPluginPersonErasers(): string[] {\n  return registrations.map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every eraser. */\nexport function resetPluginPersonErasersForTests(): void {\n  registrations.length = 0\n}\n"],"names":["getRegisteringPluginId","registrations","registerPluginPersonEraser","eraser","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginPersonErasers","request","reports","orgId","email","key","contactIds","dryRun","error","console","listPluginPersonErasers","map","resetPluginPersonErasersForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AAmCxE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,2BACdC,MAA0B,EAC1BC,OAA+B;QAEbJ,MAAAA;IAAlB,MAAMK,WAAW,EAACL,QAAAA,0BAAAA,oCAAAA,0BAA4BI,2BAAAA,QAASC,QAAQ,YAA7CL,OAAiD,IAAIM,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,4EACE;IAEN;IACA,MAAMC,QAAQP,cAAcQ,SAAS,CAAC,CAACC,QAAUA,MAAML,QAAQ,KAAKA;IACpE,IAAIG,SAAS,GAAGP,aAAa,CAACO,MAAM,GAAG;QAAEH;QAAUF;IAAO;SACrDF,cAAcU,IAAI,CAAC;QAAEN;QAAUF;IAAO;AAC7C;AAEA;;;;CAIC,GACD,OAAO,eAAeS,uBACpBC,OAAmC;IAEnC,MAAMC,UAA4D,CAAC;IACnE,KAAK,MAAM,EAAET,QAAQ,EAAEF,MAAM,EAAE,IAAI;WAAIF;KAAc,CAAE;QACrD,IAAI;YACFa,OAAO,CAACT,SAAS,GAAG,MAAMF,OAAO;gBAC/BY,OAAOF,QAAQE,KAAK;gBACpBC,OAAOH,QAAQG,KAAK;gBACpBC,KAAKJ,QAAQI,GAAG;gBAChBC,YAAY;uBAAIL,QAAQK,UAAU;iBAAC;gBACnCC,QAAQN,QAAQM,MAAM;YACxB;QACF,EAAE,OAAOC,OAAO;YACdN,OAAO,CAACT,SAAS,GAAG;YACpB,8DAA8D;YAC9DgB,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEf,SAAS,iCAAiC,EAAEQ,QAAQE,KAAK,EAAE,EAAEK;QAC1F;IACF;IACA,OAAON;AACT;AAEA,6DAA6D,GAC7D,OAAO,SAASQ;IACd,OAAOrB,cAAcsB,GAAG,CAAC,CAACb,QAAUA,MAAML,QAAQ;AACpD;AAEA,oCAAoC,GACpC,OAAO,SAASmB;IACdvB,cAAcwB,MAAM,GAAG;AACzB"}

package/src/lib/plugin-manager/plugin-record-cards.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @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.
+ */
+/**
+ * How a plugin's record presents as a card, published by the plugin that owns
+ * it (AGL-3080).
+ *
+ * A surface that is not the record's own sometimes has to DRAW it rather than
+ * link to it: a designed email that features a product, a picker that lists
+ * what another plugin keeps. Doing that by reading the owner's collection and
+ * importing the owner's model is two couplings at once — to where the record
+ * is stored and to what its fields mean — and the second is the one that goes
+ * wrong quietly, because a price rule that changes in the owner is still
+ * computed the old way everywhere it was copied.
+ *
+ * So the owner answers the fourth question about a record kind. The facts
+ * reader says what a member may know about it, the timeline what happened on
+ * it, the route where a person reads it; this says what it looks like in one
+ * line and one image. It is keyed by the same RECORD KIND as those three, so
+ * a plugin that owns `product` registers them together.
+ *
+ * ## What a card is
+ *
+ * A title, an optional caption already worded for a reader (a price, a date, a
+ * status — the owner decides, and formats it), an optional image, and an
+ * optional `path` on the published site. Nothing here is the owner's model:
+ * no field a caller could compute on, which is what keeps the rule in one
+ * place.
+ *
+ * ## Server-side, and unauthenticated on purpose
+ *
+ * A reader runs with the Admin SDK for a caller that has already decided the
+ * read is the workspace's to make — a send the merchant started, a job the
+ * platform scheduled. That is a different question from `plugin-record-facts`,
+ * which answers ONE member and applies their permissions, and the two are
+ * separate contracts so neither borrows the other's trust.
+ *
+ * Both apps load every plugin's server entry before any plugin handler runs
+ * (`ensureAll`), so a reader registered from a server registrar is present
+ * wherever a handler asks. `null` still has two meanings a caller must treat
+ * alike — no plugin publishes the kind, or the record is not there — and both
+ * mean the same thing to it: there is nothing to draw.
+ *
+ * ## One kind, one owner
+ *
+ * A second plugin publishing a card for a kind another already publishes is
+ * refused naming both, and the incumbent keeps serving; the owner registering
+ * again replaces its own.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-record-cards`); it is not in the barrel.
+ */
+export interface PluginRecordCardRequest {
+    hostId: string;
+    /** The record's document id. */
+    id: string;
+}
+export interface PluginRecordCard {
+    title: string;
+    /** One short line the owner has already worded for a reader. */
+    caption?: string;
+    imageUrl?: string;
+    /** Where the record is read on the published site, site-relative. */
+    path?: string;
+}
+export interface PluginRecordCardReader {
+    /** `null` when the record does not exist. */
+    read(request: PluginRecordCardRequest): Promise<PluginRecordCard | null>;
+}
+export interface ResolvedPluginRecordCardReader {
+    pluginId: string;
+    reader: PluginRecordCardReader;
+}
+export declare const PLUGIN_RECORD_CARDS: import("./plugin-services").PluginServiceContract<PluginRecordCardReader>;
+export declare function registerPluginRecordCardReader(kind: string, reader: PluginRecordCardReader, options?: {
+    pluginId?: string;
+}): void;
+/** The reader for a kind with its owner, or `null` when none publishes it. */
+export declare function pluginRecordCardReader(kind: string): ResolvedPluginRecordCardReader | null;
+/** One record's card; `null` when no plugin publishes the kind or it is gone. */
+export declare function readPluginRecordCard(kind: string, request: PluginRecordCardRequest): Promise<PluginRecordCard | null>;
+/** Every published kind with its owner. */
+export declare function listPluginRecordCardKinds(): Array<{
+    kind: string;
+    pluginId: string;
+}>;