@aglyn/aglyn 1.0.0-beta.219 → 1.0.0-beta.220

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

@@ -0,0 +1,68 @@
+/**
+ * @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.
+ */
+/**
+ * CONTAINER KINDS: the documents other records are FILED UNDER, declared by
+ * the plugin that keeps them.
+ *
+ * A container is a document other records join by naming its id in a
+ * membership array on their OWN documents — a form, a screen, a lead or a
+ * contact filed under a campaign. `app-utils/container-membership.ts` says
+ * why the edge lives on the member, and holds the helpers every member's
+ * writer and reader share.
+ *
+ * The plugin that keeps a kind declares it in the `containers` block of
+ * `plugins.config.json`, compiled into `plugin-containers.generated.ts`, so
+ * no surface that files a record has to know which plugin that is or where
+ * the containers are stored:
+ *
+ *  - `kind` names the membership field: a member holds its containers in
+ *    `<kind>Ids` (`containerMembershipField`). The name is the contract,
+ *    which is what lets a record page in one plugin file itself under a kind
+ *    another plugin keeps without importing it.
+ *  - `orgCollection` is where the containers are stored, under the
+ *    organization (`orgs/{orgId}/{orgCollection}`), one of the owner's own
+ *    declared org collections. A container is placed on sites by the core's
+ *    scope field (`visibleTo`) and retired by `deletedAt`, like every other
+ *    org record a site hub lists.
+ *  - `label` / `pluralLabel` / `ownerLabel` are what a picker calls one, several,
+ *    and the plugin a merchant creates one in.
+ *
+ * Compiled rather than registered: the readers include a form submission
+ * that loads no plugin, and a registry that request had not filled would
+ * read every record as filed under nothing.
+ */
+/** One container kind, as its plugin declares it. */
+export interface PluginContainerKind {
+    /** The plugin that keeps the containers. */
+    pluginId: string;
+    /** The kind, lowerCamelCase; its members hold it in `<kind>Ids`. */
+    kind: string;
+    /** What one container is called. */
+    label: string;
+    /** What several are called. */
+    pluralLabel: string;
+    /** The owner's catalog label: where a merchant creates one. */
+    ownerLabel: string;
+    /** The org collection the containers are stored in. */
+    orgCollection: string;
+    /** The field a container's name is stored in. */
+    nameField: string;
+}
+/** Every declared container kind, in catalog order. */
+export declare function listPluginContainerKinds(): PluginContainerKind[];
+/** One declared kind, or `null` when no plugin keeps it. */
+export declare function pluginContainerKind(kind: string): PluginContainerKind | null;

package/src/lib/plugin-manager/plugin-containers.generated.d.ts

@@ -0,0 +1,10 @@
+/**
+ * GENERATED FILE — do not edit. Regenerate with:
+ *   node tools/scripts/generate-plugin-manifests.mjs
+ *
+ * The container kinds plugins declare (AGL-3080): each plugin's
+ * `containers` block in plugins.config.json. Core's `plugin-containers.ts`
+ * reads them; core names no kind.
+ */
+import type { PluginContainerKind } from './plugin-containers';
+export declare const PLUGIN_CONTAINER_KINDS_DECLARED: readonly PluginContainerKind[];

package/src/lib/plugin-manager/plugin-containers.generated.js

@@ -0,0 +1,20 @@
+/**
+ * GENERATED FILE — do not edit. Regenerate with:
+ *   node tools/scripts/generate-plugin-manifests.mjs
+ *
+ * The container kinds plugins declare (AGL-3080): each plugin's
+ * `containers` block in plugins.config.json. Core's `plugin-containers.ts`
+ * reads them; core names no kind.
+ */ export const PLUGIN_CONTAINER_KINDS_DECLARED = [
+    {
+        "pluginId": "marketing",
+        "kind": "campaign",
+        "label": "Campaign",
+        "pluralLabel": "Campaigns",
+        "ownerLabel": "Marketing",
+        "orgCollection": "emailCampaigns",
+        "nameField": "name"
+    }
+];
+
+//# sourceMappingURL=plugin-containers.generated.js.map

package/src/lib/plugin-manager/plugin-containers.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-containers.generated.ts"],"sourcesContent":["/**\n * GENERATED FILE — do not edit. Regenerate with:\n *   node tools/scripts/generate-plugin-manifests.mjs\n *\n * The container kinds plugins declare (AGL-3080): each plugin's\n * `containers` block in plugins.config.json. Core's `plugin-containers.ts`\n * reads them; core names no kind.\n */\n\nimport type { PluginContainerKind } from './plugin-containers'\n\nexport const PLUGIN_CONTAINER_KINDS_DECLARED: readonly PluginContainerKind[] = [\n  {\n    \"pluginId\": \"marketing\",\n    \"kind\": \"campaign\",\n    \"label\": \"Campaign\",\n    \"pluralLabel\": \"Campaigns\",\n    \"ownerLabel\": \"Marketing\",\n    \"orgCollection\": \"emailCampaigns\",\n    \"nameField\": \"name\"\n  }\n]\n"],"names":["PLUGIN_CONTAINER_KINDS_DECLARED"],"mappings":"AAAA;;;;;;;CAOC,GAID,OAAO,MAAMA,kCAAkE;IAC7E;QACE,YAAY;QACZ,QAAQ;QACR,SAAS;QACT,eAAe;QACf,cAAc;QACd,iBAAiB;QACjB,aAAa;IACf;CACD,CAAA"}

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

@@ -0,0 +1,27 @@
+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 { PLUGIN_CONTAINER_KINDS_DECLARED } from "./plugin-containers.generated.js";
+/** Every declared container kind, in catalog order. */ export function listPluginContainerKinds() {
+    return PLUGIN_CONTAINER_KINDS_DECLARED.map((row)=>_extends({}, row));
+}
+/** One declared kind, or `null` when no plugin keeps it. */ export function pluginContainerKind(kind) {
+    const key = String(kind != null ? kind : '').trim();
+    const row = PLUGIN_CONTAINER_KINDS_DECLARED.find((one)=>one.kind === key);
+    return row ? _extends({}, row) : null;
+}
+
+//# sourceMappingURL=plugin-containers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-containers.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 { PLUGIN_CONTAINER_KINDS_DECLARED } from './plugin-containers.generated'\n\n/**\n * CONTAINER KINDS: the documents other records are FILED UNDER, declared by\n * the plugin that keeps them.\n *\n * A container is a document other records join by naming its id in a\n * membership array on their OWN documents — a form, a screen, a lead or a\n * contact filed under a campaign. `app-utils/container-membership.ts` says\n * why the edge lives on the member, and holds the helpers every member's\n * writer and reader share.\n *\n * The plugin that keeps a kind declares it in the `containers` block of\n * `plugins.config.json`, compiled into `plugin-containers.generated.ts`, so\n * no surface that files a record has to know which plugin that is or where\n * the containers are stored:\n *\n *  - `kind` names the membership field: a member holds its containers in\n *    `<kind>Ids` (`containerMembershipField`). The name is the contract,\n *    which is what lets a record page in one plugin file itself under a kind\n *    another plugin keeps without importing it.\n *  - `orgCollection` is where the containers are stored, under the\n *    organization (`orgs/{orgId}/{orgCollection}`), one of the owner's own\n *    declared org collections. A container is placed on sites by the core's\n *    scope field (`visibleTo`) and retired by `deletedAt`, like every other\n *    org record a site hub lists.\n *  - `label` / `pluralLabel` / `ownerLabel` are what a picker calls one, several,\n *    and the plugin a merchant creates one in.\n *\n * Compiled rather than registered: the readers include a form submission\n * that loads no plugin, and a registry that request had not filled would\n * read every record as filed under nothing.\n */\n\n/** One container kind, as its plugin declares it. */\nexport interface PluginContainerKind {\n  /** The plugin that keeps the containers. */\n  pluginId: string\n  /** The kind, lowerCamelCase; its members hold it in `<kind>Ids`. */\n  kind: string\n  /** What one container is called. */\n  label: string\n  /** What several are called. */\n  pluralLabel: string\n  /** The owner's catalog label: where a merchant creates one. */\n  ownerLabel: string\n  /** The org collection the containers are stored in. */\n  orgCollection: string\n  /** The field a container's name is stored in. */\n  nameField: string\n}\n\n/** Every declared container kind, in catalog order. */\nexport function listPluginContainerKinds(): PluginContainerKind[] {\n  return PLUGIN_CONTAINER_KINDS_DECLARED.map((row) => ({ ...row }))\n}\n\n/** One declared kind, or `null` when no plugin keeps it. */\nexport function pluginContainerKind(kind: string): PluginContainerKind | null {\n  const key = String(kind ?? '').trim()\n  const row = PLUGIN_CONTAINER_KINDS_DECLARED.find((one) => one.kind === key)\n  return row ? { ...row } : null\n}\n"],"names":["PLUGIN_CONTAINER_KINDS_DECLARED","listPluginContainerKinds","map","row","pluginContainerKind","kind","key","String","trim","find","one"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,+BAA+B,QAAQ,mCAA+B;AAoD/E,qDAAqD,GACrD,OAAO,SAASC;IACd,OAAOD,gCAAgCE,GAAG,CAAC,CAACC,MAAS,aAAKA;AAC5D;AAEA,0DAA0D,GAC1D,OAAO,SAASC,oBAAoBC,IAAY;IAC9C,MAAMC,MAAMC,OAAOF,eAAAA,OAAQ,IAAIG,IAAI;IACnC,MAAML,MAAMH,gCAAgCS,IAAI,CAAC,CAACC,MAAQA,IAAIL,IAAI,KAAKC;IACvE,OAAOH,MAAM,aAAKA,OAAQ;AAC5B"}

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

@@ -85,6 +85,14 @@ export interface PluginLockdownFeatureDeclaration {
     key: string;
     /** The staff checklist's label. */
     label: string;
+    /**
+     * What the lever is called in the customer's mail when staff pull it for
+     * their workspace (`media uploads`, `AI generation`). A noun phrase that
+     * reads right mid-sentence ("our team paused media uploads") and after a
+     * colon, so lowercase unless it starts with a name or an acronym. The
+     * staff `label` never reaches a customer.
+     */
+    customerName: string;
     /**
      * Whether a verified staff claim passes the lock. Granted where a staff
      * action aids incident response — one real call proves a provider is back

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-entitlements.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 billing and access keys (AGL-2940).\n *\n * A plugin that sells something, gates something, or can be switched off in\n * an incident declares the KEYS here — a seat add-on, a feature flag, a\n * lockdown lever, a permission — and the core catalogs that used to be\n * edited for each one read the declarations instead:\n *\n * - `plan-entitlements` folds every registered seat add-on into\n *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)\n *   and answers a registered feature's plan defaults;\n * - `lockdown` lists a registered lever on the staff page, carries its label,\n *   its staff-bypass rule and its visitor notice, and maps the API paths it\n *   names onto it for the plugin dispatcher;\n * - `plugin-permissions` receives the permissions with the owner filled in;\n * - `org-permissions` folds every declared catalog key into the org\n *   permission catalog — the role editor, custom roles, per-member overrides\n *   and the rules stamp — and `host-permissions` decides the keys that\n *   declare host-role defaults for a site collaborator, per site.\n *\n * The NUMBERS stay where they are checked. A seat add-on's price is a row in\n * `PLAN_PRICING`, read by the Stripe wiring and reconciled by\n * `check-pricing-drift`; a declaration names the quota it widens and by how\n * much per plan, and nothing here restates a price.\n *\n * Registration order is deterministic: the catalog order of\n * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules\n * load in parallel, so the order they REGISTER in is whatever the network\n * gave, and a list that followed it would put the staff lockdown checklist\n * in a different order per session.\n */\n\nimport type { HostAccessRole, OrgPlan, OrgRole } from '../foundation'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\nimport {\n  registerPluginPermissions,\n  type PluginPermission,\n} from './plugin-permissions'\n\nexport interface PluginSeatAddonDeclaration {\n  /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */\n  key: string\n  label: string\n  /**\n   * How many purchased units count. `1` for an org-wide add-on that is\n   * bought once, where a doubled webhook item or a hand edit above one is\n   * still one purchase; absent to count the stored quantity.\n   */\n  maxUnits?: number\n  /**\n   * The quota each unit widens, per plan: the resolved entitlement named by\n   * `key` gains `perUnitByPlan[plan] × units`. A plan the add-on is not sold\n   * on declares 0.\n   */\n  quota?: {\n    key: string\n    perUnitByPlan: Readonly<Record<OrgPlan, number>>\n  }\n  /** Feature flags a purchased unit switches on. */\n  features?: readonly string[]\n}\n\nexport interface PluginFeatureDeclaration {\n  /** The `OrgFeatureFlags` key. */\n  key: string\n  label: string\n  /**\n   * The plan defaults, when the key is not one the plan tables already\n   * carry. Absent means the plan tables decide, which is the case for every\n   * key that predates this registry.\n   */\n  defaultByPlan?: Readonly<Partial<Record<OrgPlan, boolean>>>\n}\n\nexport interface PluginLockdownFeatureDeclaration {\n  /** The lever's wire identity (`ai-generate`). */\n  key: string\n  /** The staff checklist's label. */\n  label: string\n  /**\n   * Whether a verified staff claim passes the lock. Granted where a staff\n   * action aids incident response — one real call proves a provider is back\n   * — and withheld where the staff action would BE the incident.\n   */\n  staffBypass: boolean\n  /**\n   * What a visitor reads while the lever is pulled: what is paused AND what\n   * still works. The expected-back window is appended by the notice builder.\n   */\n  notice: { title: string; body: string }\n  /**\n   * Plugin API paths the lever gates at the dispatcher: exact paths, and\n   * prefixes matched on a segment boundary (`ai/generate` also gates\n   * `ai/generate/section`, never `ai/generated-report`).\n   */\n  apiPaths?: { exact?: readonly string[]; prefixes?: readonly string[] }\n}\n\n/**\n * A key a plugin adds to the org permission CATALOG (AGL-2984): the granular\n * map custom roles and per-member overrides are stored in, that\n * `resolveOrgPermissions` layers and the rules stamp carries, and that the\n * role editor lists. A declared key is stored, layered and resolved exactly\n * like a core key; the declaration supplies what a core key's catalog entry\n * and role table supply.\n */\nexport interface PluginOrgPermissionDeclaration {\n  /** The dotted key a custom role and a per-member override store (`reviews.reply`). */\n  key: string\n  /** The role editor's line for the key, and the word a refusal names. */\n  label: string\n  /** What the key opens, under the label in the role editor. */\n  description: string\n  /** Each org role's verdict when no custom role or per-member override sets the key. */\n  roleDefaults: Readonly<Record<OrgRole, boolean>>\n  /**\n   * Each HOST role's verdict, for a key a site collaborator holds per site.\n   *\n   * A collaborator's membership carries no org standing to refine — it\n   * exists only to carry access to named sites — so a key with this field is\n   * decided for them on the site a request names: the host role they hold\n   * there, refined by the per-site toggle on their member document. A key\n   * without it is never held by a collaborator.\n   */\n  hostRoleDefaults?: Readonly<Record<HostAccessRole, boolean>>\n}\n\nexport interface PluginEntitlementRegistration {\n  pluginId: string\n  seatAddons?: readonly PluginSeatAddonDeclaration[]\n  features?: readonly PluginFeatureDeclaration[]\n  lockdownFeatures?: readonly PluginLockdownFeatureDeclaration[]\n  /** Per-tier keys a plugin's own pages read (`registerPluginPermissions`). */\n  permissions?: readonly Omit<PluginPermission, 'pluginId'>[]\n  /** Keys added to the org permission catalog — see {@link PluginOrgPermissionDeclaration}. */\n  orgPermissions?: readonly PluginOrgPermissionDeclaration[]\n}\n\nconst registrations = new Map<string, PluginEntitlementRegistration>()\n\n/**\n * Readers of the registrations that keep a derived view in step with them —\n * the org permission catalog rebuilds itself on every registration and\n * reset, because a plugin's declarations can register after a module that\n * imported the catalog was evaluated.\n */\nconst listeners = new Set<() => void>()\n\n/** Calls `listener` after every registration and reset; answers the unsubscribe. */\nexport function subscribePluginEntitlements(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\nfunction notifyListeners(): void {\n  for (const listener of [...listeners]) listener()\n}\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\nfunction orderedRegistrations(): PluginEntitlementRegistration[] {\n  return [...registrations.values()].sort(\n    (a, b) =>\n      catalogRank(a.pluginId) - catalogRank(b.pluginId) ||\n      a.pluginId.localeCompare(b.pluginId),\n  )\n}\n\nfunction refuseStolenKeys(\n  pluginId: string,\n  kind: 'seat add-on' | 'lockdown feature' | 'org permission',\n  keys: readonly string[],\n  ownerOf: (key: string) => string | undefined,\n): void {\n  for (const key of keys) {\n    const owner = ownerOf(key)\n    if (owner && owner !== pluginId) {\n      throw new Error(\n        `${kind} \"${key}\" is already declared by \"${owner}\"; refused \"${pluginId}\"`,\n      )\n    }\n  }\n}\n\n/**\n * Idempotent per plugin — re-registration replaces that plugin's\n * declarations. A seat add-on, lockdown or catalog permission key another\n * plugin already owns refuses the whole registration: one key, one owner,\n * or the two declarations disagree about what the key means.\n */\nexport function registerPluginEntitlements(\n  registration: PluginEntitlementRegistration,\n): void {\n  const pluginId = registration.pluginId.trim()\n  if (!pluginId) throw new Error('plugin entitlements need a pluginId')\n  refuseStolenKeys(\n    pluginId,\n    'seat add-on',\n    (registration.seatAddons ?? []).map((entry) => entry.key),\n    (key) => pluginSeatAddonOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'lockdown feature',\n    (registration.lockdownFeatures ?? []).map((entry) => entry.key),\n    (key) => pluginLockdownFeatureOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'org permission',\n    (registration.orgPermissions ?? []).map((entry) => entry.key),\n    (key) => pluginOrgPermissionOwner(key),\n  )\n  registrations.set(pluginId, { ...registration, pluginId })\n  if (registration.permissions?.length) {\n    registerPluginPermissions(\n      registration.permissions.map((permission) => ({ ...permission, pluginId })),\n    )\n  }\n  notifyListeners()\n}\n\nfunction pluginSeatAddonOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.seatAddons?.some((addon) => addon.key === key)) return entry.pluginId\n  }\n  return undefined\n}\n\nfunction pluginLockdownFeatureOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.lockdownFeatures?.some((feature) => feature.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\nfunction pluginOrgPermissionOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.orgPermissions?.some((permission) => permission.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\n/** Every declared catalog permission, in catalog order, with the plugin that declared it. */\nexport function listPluginOrgPermissions(): Array<\n  PluginOrgPermissionDeclaration & { pluginId: string }\n> {\n  return orderedRegistrations().flatMap((entry) =>\n    (entry.orgPermissions ?? []).map((permission) => ({\n      ...permission,\n      pluginId: entry.pluginId,\n    })),\n  )\n}\n\n/** Every declared seat add-on, in catalog order. */\nexport function listPluginSeatAddons(): PluginSeatAddonDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.seatAddons ?? [])])\n}\n\n/** One declared seat add-on by its `seatAddons` key. */\nexport function pluginSeatAddon(key: string): PluginSeatAddonDeclaration | undefined {\n  return listPluginSeatAddons().find((entry) => entry.key === key)\n}\n\n/** Every declared feature, in catalog order. */\nexport function listPluginFeatures(): PluginFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.features ?? [])])\n}\n\n/** Every declared lockdown lever, in catalog order. */\nexport function listPluginLockdownFeatures(): PluginLockdownFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [\n    ...(entry.lockdownFeatures ?? []),\n  ])\n}\n\n/** One declared lockdown lever by key. */\nexport function pluginLockdownFeature(\n  key: string,\n): PluginLockdownFeatureDeclaration | undefined {\n  return listPluginLockdownFeatures().find((entry) => entry.key === key)\n}\n\n/** The plugin that declared a lockdown lever, for attribution. */\nexport function pluginIdForLockdownFeature(key: string): string | undefined {\n  return pluginLockdownFeatureOwner(key)\n}\n\n/** Every registration, in catalog order. */\nexport function listPluginEntitlementRegistrations(): PluginEntitlementRegistration[] {\n  return orderedRegistrations()\n}\n\n/**\n * Test seam: forget every registration. The per-tier permissions stay\n * registered; the catalog permissions go with their registrations.\n */\nexport function resetPluginEntitlementsForTests(): void {\n  registrations.clear()\n  notifyListeners()\n}\n"],"names":["FIRST_PARTY_PLUGINS","registerPluginPermissions","registrations","Map","listeners","Set","subscribePluginEntitlements","listener","add","delete","notifyListeners","CATALOG_ORDER","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","orderedRegistrations","values","sort","a","b","localeCompare","refuseStolenKeys","kind","keys","ownerOf","key","owner","Error","registerPluginEntitlements","registration","trim","seatAddons","entry","pluginSeatAddonOwner","lockdownFeatures","pluginLockdownFeatureOwner","orgPermissions","pluginOrgPermissionOwner","set","permissions","length","permission","some","addon","undefined","feature","listPluginOrgPermissions","flatMap","listPluginSeatAddons","pluginSeatAddon","find","listPluginFeatures","features","listPluginLockdownFeatures","pluginLockdownFeature","pluginIdForLockdownFeature","listPluginEntitlementRegistrations","resetPluginEntitlementsForTests","clear"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-entitlements.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 billing and access keys (AGL-2940).\n *\n * A plugin that sells something, gates something, or can be switched off in\n * an incident declares the KEYS here — a seat add-on, a feature flag, a\n * lockdown lever, a permission — and the core catalogs that used to be\n * edited for each one read the declarations instead:\n *\n * - `plan-entitlements` folds every registered seat add-on into\n *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)\n *   and answers a registered feature's plan defaults;\n * - `lockdown` lists a registered lever on the staff page, carries its label,\n *   its staff-bypass rule and its visitor notice, and maps the API paths it\n *   names onto it for the plugin dispatcher;\n * - `plugin-permissions` receives the permissions with the owner filled in;\n * - `org-permissions` folds every declared catalog key into the org\n *   permission catalog — the role editor, custom roles, per-member overrides\n *   and the rules stamp — and `host-permissions` decides the keys that\n *   declare host-role defaults for a site collaborator, per site.\n *\n * The NUMBERS stay where they are checked. A seat add-on's price is a row in\n * `PLAN_PRICING`, read by the Stripe wiring and reconciled by\n * `check-pricing-drift`; a declaration names the quota it widens and by how\n * much per plan, and nothing here restates a price.\n *\n * Registration order is deterministic: the catalog order of\n * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules\n * load in parallel, so the order they REGISTER in is whatever the network\n * gave, and a list that followed it would put the staff lockdown checklist\n * in a different order per session.\n */\n\nimport type { HostAccessRole, OrgPlan, OrgRole } from '../foundation'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\nimport {\n  registerPluginPermissions,\n  type PluginPermission,\n} from './plugin-permissions'\n\nexport interface PluginSeatAddonDeclaration {\n  /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */\n  key: string\n  label: string\n  /**\n   * How many purchased units count. `1` for an org-wide add-on that is\n   * bought once, where a doubled webhook item or a hand edit above one is\n   * still one purchase; absent to count the stored quantity.\n   */\n  maxUnits?: number\n  /**\n   * The quota each unit widens, per plan: the resolved entitlement named by\n   * `key` gains `perUnitByPlan[plan] × units`. A plan the add-on is not sold\n   * on declares 0.\n   */\n  quota?: {\n    key: string\n    perUnitByPlan: Readonly<Record<OrgPlan, number>>\n  }\n  /** Feature flags a purchased unit switches on. */\n  features?: readonly string[]\n}\n\nexport interface PluginFeatureDeclaration {\n  /** The `OrgFeatureFlags` key. */\n  key: string\n  label: string\n  /**\n   * The plan defaults, when the key is not one the plan tables already\n   * carry. Absent means the plan tables decide, which is the case for every\n   * key that predates this registry.\n   */\n  defaultByPlan?: Readonly<Partial<Record<OrgPlan, boolean>>>\n}\n\nexport interface PluginLockdownFeatureDeclaration {\n  /** The lever's wire identity (`ai-generate`). */\n  key: string\n  /** The staff checklist's label. */\n  label: string\n  /**\n   * What the lever is called in the customer's mail when staff pull it for\n   * their workspace (`media uploads`, `AI generation`). A noun phrase that\n   * reads right mid-sentence (\"our team paused media uploads\") and after a\n   * colon, so lowercase unless it starts with a name or an acronym. The\n   * staff `label` never reaches a customer.\n   */\n  customerName: string\n  /**\n   * Whether a verified staff claim passes the lock. Granted where a staff\n   * action aids incident response — one real call proves a provider is back\n   * — and withheld where the staff action would BE the incident.\n   */\n  staffBypass: boolean\n  /**\n   * What a visitor reads while the lever is pulled: what is paused AND what\n   * still works. The expected-back window is appended by the notice builder.\n   */\n  notice: { title: string; body: string }\n  /**\n   * Plugin API paths the lever gates at the dispatcher: exact paths, and\n   * prefixes matched on a segment boundary (`ai/generate` also gates\n   * `ai/generate/section`, never `ai/generated-report`).\n   */\n  apiPaths?: { exact?: readonly string[]; prefixes?: readonly string[] }\n}\n\n/**\n * A key a plugin adds to the org permission CATALOG (AGL-2984): the granular\n * map custom roles and per-member overrides are stored in, that\n * `resolveOrgPermissions` layers and the rules stamp carries, and that the\n * role editor lists. A declared key is stored, layered and resolved exactly\n * like a core key; the declaration supplies what a core key's catalog entry\n * and role table supply.\n */\nexport interface PluginOrgPermissionDeclaration {\n  /** The dotted key a custom role and a per-member override store (`reviews.reply`). */\n  key: string\n  /** The role editor's line for the key, and the word a refusal names. */\n  label: string\n  /** What the key opens, under the label in the role editor. */\n  description: string\n  /** Each org role's verdict when no custom role or per-member override sets the key. */\n  roleDefaults: Readonly<Record<OrgRole, boolean>>\n  /**\n   * Each HOST role's verdict, for a key a site collaborator holds per site.\n   *\n   * A collaborator's membership carries no org standing to refine — it\n   * exists only to carry access to named sites — so a key with this field is\n   * decided for them on the site a request names: the host role they hold\n   * there, refined by the per-site toggle on their member document. A key\n   * without it is never held by a collaborator.\n   */\n  hostRoleDefaults?: Readonly<Record<HostAccessRole, boolean>>\n}\n\nexport interface PluginEntitlementRegistration {\n  pluginId: string\n  seatAddons?: readonly PluginSeatAddonDeclaration[]\n  features?: readonly PluginFeatureDeclaration[]\n  lockdownFeatures?: readonly PluginLockdownFeatureDeclaration[]\n  /** Per-tier keys a plugin's own pages read (`registerPluginPermissions`). */\n  permissions?: readonly Omit<PluginPermission, 'pluginId'>[]\n  /** Keys added to the org permission catalog — see {@link PluginOrgPermissionDeclaration}. */\n  orgPermissions?: readonly PluginOrgPermissionDeclaration[]\n}\n\nconst registrations = new Map<string, PluginEntitlementRegistration>()\n\n/**\n * Readers of the registrations that keep a derived view in step with them —\n * the org permission catalog rebuilds itself on every registration and\n * reset, because a plugin's declarations can register after a module that\n * imported the catalog was evaluated.\n */\nconst listeners = new Set<() => void>()\n\n/** Calls `listener` after every registration and reset; answers the unsubscribe. */\nexport function subscribePluginEntitlements(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\nfunction notifyListeners(): void {\n  for (const listener of [...listeners]) listener()\n}\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\nfunction orderedRegistrations(): PluginEntitlementRegistration[] {\n  return [...registrations.values()].sort(\n    (a, b) =>\n      catalogRank(a.pluginId) - catalogRank(b.pluginId) ||\n      a.pluginId.localeCompare(b.pluginId),\n  )\n}\n\nfunction refuseStolenKeys(\n  pluginId: string,\n  kind: 'seat add-on' | 'lockdown feature' | 'org permission',\n  keys: readonly string[],\n  ownerOf: (key: string) => string | undefined,\n): void {\n  for (const key of keys) {\n    const owner = ownerOf(key)\n    if (owner && owner !== pluginId) {\n      throw new Error(\n        `${kind} \"${key}\" is already declared by \"${owner}\"; refused \"${pluginId}\"`,\n      )\n    }\n  }\n}\n\n/**\n * Idempotent per plugin — re-registration replaces that plugin's\n * declarations. A seat add-on, lockdown or catalog permission key another\n * plugin already owns refuses the whole registration: one key, one owner,\n * or the two declarations disagree about what the key means.\n */\nexport function registerPluginEntitlements(\n  registration: PluginEntitlementRegistration,\n): void {\n  const pluginId = registration.pluginId.trim()\n  if (!pluginId) throw new Error('plugin entitlements need a pluginId')\n  refuseStolenKeys(\n    pluginId,\n    'seat add-on',\n    (registration.seatAddons ?? []).map((entry) => entry.key),\n    (key) => pluginSeatAddonOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'lockdown feature',\n    (registration.lockdownFeatures ?? []).map((entry) => entry.key),\n    (key) => pluginLockdownFeatureOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'org permission',\n    (registration.orgPermissions ?? []).map((entry) => entry.key),\n    (key) => pluginOrgPermissionOwner(key),\n  )\n  registrations.set(pluginId, { ...registration, pluginId })\n  if (registration.permissions?.length) {\n    registerPluginPermissions(\n      registration.permissions.map((permission) => ({ ...permission, pluginId })),\n    )\n  }\n  notifyListeners()\n}\n\nfunction pluginSeatAddonOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.seatAddons?.some((addon) => addon.key === key)) return entry.pluginId\n  }\n  return undefined\n}\n\nfunction pluginLockdownFeatureOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.lockdownFeatures?.some((feature) => feature.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\nfunction pluginOrgPermissionOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.orgPermissions?.some((permission) => permission.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\n/** Every declared catalog permission, in catalog order, with the plugin that declared it. */\nexport function listPluginOrgPermissions(): Array<\n  PluginOrgPermissionDeclaration & { pluginId: string }\n> {\n  return orderedRegistrations().flatMap((entry) =>\n    (entry.orgPermissions ?? []).map((permission) => ({\n      ...permission,\n      pluginId: entry.pluginId,\n    })),\n  )\n}\n\n/** Every declared seat add-on, in catalog order. */\nexport function listPluginSeatAddons(): PluginSeatAddonDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.seatAddons ?? [])])\n}\n\n/** One declared seat add-on by its `seatAddons` key. */\nexport function pluginSeatAddon(key: string): PluginSeatAddonDeclaration | undefined {\n  return listPluginSeatAddons().find((entry) => entry.key === key)\n}\n\n/** Every declared feature, in catalog order. */\nexport function listPluginFeatures(): PluginFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.features ?? [])])\n}\n\n/** Every declared lockdown lever, in catalog order. */\nexport function listPluginLockdownFeatures(): PluginLockdownFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [\n    ...(entry.lockdownFeatures ?? []),\n  ])\n}\n\n/** One declared lockdown lever by key. */\nexport function pluginLockdownFeature(\n  key: string,\n): PluginLockdownFeatureDeclaration | undefined {\n  return listPluginLockdownFeatures().find((entry) => entry.key === key)\n}\n\n/** The plugin that declared a lockdown lever, for attribution. */\nexport function pluginIdForLockdownFeature(key: string): string | undefined {\n  return pluginLockdownFeatureOwner(key)\n}\n\n/** Every registration, in catalog order. */\nexport function listPluginEntitlementRegistrations(): PluginEntitlementRegistration[] {\n  return orderedRegistrations()\n}\n\n/**\n * Test seam: forget every registration. The per-tier permissions stay\n * registered; the catalog permissions go with their registrations.\n */\nexport function resetPluginEntitlementsForTests(): void {\n  registrations.clear()\n  notifyListeners()\n}\n"],"names":["FIRST_PARTY_PLUGINS","registerPluginPermissions","registrations","Map","listeners","Set","subscribePluginEntitlements","listener","add","delete","notifyListeners","CATALOG_ORDER","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","orderedRegistrations","values","sort","a","b","localeCompare","refuseStolenKeys","kind","keys","ownerOf","key","owner","Error","registerPluginEntitlements","registration","trim","seatAddons","entry","pluginSeatAddonOwner","lockdownFeatures","pluginLockdownFeatureOwner","orgPermissions","pluginOrgPermissionOwner","set","permissions","length","permission","some","addon","undefined","feature","listPluginOrgPermissions","flatMap","listPluginSeatAddons","pluginSeatAddon","find","listPluginFeatures","features","listPluginLockdownFeatures","pluginLockdownFeature","pluginIdForLockdownFeature","listPluginEntitlementRegistrations","resetPluginEntitlementsForTests","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC;AAGD,SAASA,mBAAmB,QAAQ,uBAAmB;AACvD,SACEC,yBAAyB,QAEpB,0BAAsB;AA6G7B,MAAMC,gBAAgB,IAAIC;AAE1B;;;;;CAKC,GACD,MAAMC,YAAY,IAAIC;AAEtB,kFAAkF,GAClF,OAAO,SAASC,4BAA4BC,QAAoB;IAC9DH,UAAUI,GAAG,CAACD;IACd,OAAO;QACLH,UAAUK,MAAM,CAACF;IACnB;AACF;AAEA,SAASG;IACP,KAAK,MAAMH,YAAY;WAAIH;KAAU,CAAEG;AACzC;AAEA,MAAMI,gBAAgB,IAAIR,IACxBH,oBAAoBY,GAAG,CAAC,CAACC,QAAQC,QAAU;QAACD,OAAOE,EAAE;QAAED;KAAM;AAG/D,SAASE,YAAYC,QAAgB;QAC5BN;IAAP,QAAOA,qBAAAA,cAAcO,GAAG,CAACD,qBAAlBN,qBAA+BQ,OAAOC,gBAAgB;AAC/D;AAEA,SAASC;IACP,OAAO;WAAInB,cAAcoB,MAAM;KAAG,CAACC,IAAI,CACrC,CAACC,GAAGC,IACFT,YAAYQ,EAAEP,QAAQ,IAAID,YAAYS,EAAER,QAAQ,KAChDO,EAAEP,QAAQ,CAACS,aAAa,CAACD,EAAER,QAAQ;AAEzC;AAEA,SAASU,iBACPV,QAAgB,EAChBW,IAA2D,EAC3DC,IAAuB,EACvBC,OAA4C;IAE5C,KAAK,MAAMC,OAAOF,KAAM;QACtB,MAAMG,QAAQF,QAAQC;QACtB,IAAIC,SAASA,UAAUf,UAAU;YAC/B,MAAM,IAAIgB,MACR,GAAGL,KAAK,EAAE,EAAEG,IAAI,0BAA0B,EAAEC,MAAM,YAAY,EAAEf,SAAS,CAAC,CAAC;QAE/E;IACF;AACF;AAEA;;;;;CAKC,GACD,OAAO,SAASiB,2BACdC,YAA2C;QAOxCA,0BAMAA,gCAMAA;QAICA;IArBJ,MAAMlB,WAAWkB,aAAalB,QAAQ,CAACmB,IAAI;IAC3C,IAAI,CAACnB,UAAU,MAAM,IAAIgB,MAAM;IAC/BN,iBACEV,UACA,eACA,EAACkB,2BAAAA,aAAaE,UAAU,YAAvBF,2BAA2B,EAAE,EAAEvB,GAAG,CAAC,CAAC0B,QAAUA,MAAMP,GAAG,GACxD,CAACA,MAAQQ,qBAAqBR;IAEhCJ,iBACEV,UACA,oBACA,EAACkB,iCAAAA,aAAaK,gBAAgB,YAA7BL,iCAAiC,EAAE,EAAEvB,GAAG,CAAC,CAAC0B,QAAUA,MAAMP,GAAG,GAC9D,CAACA,MAAQU,2BAA2BV;IAEtCJ,iBACEV,UACA,kBACA,EAACkB,+BAAAA,aAAaO,cAAc,YAA3BP,+BAA+B,EAAE,EAAEvB,GAAG,CAAC,CAAC0B,QAAUA,MAAMP,GAAG,GAC5D,CAACA,MAAQY,yBAAyBZ;IAEpC7B,cAAc0C,GAAG,CAAC3B,UAAU,aAAKkB;QAAclB;;IAC/C,KAAIkB,4BAAAA,aAAaU,WAAW,qBAAxBV,0BAA0BW,MAAM,EAAE;QACpC7C,0BACEkC,aAAaU,WAAW,CAACjC,GAAG,CAAC,CAACmC,aAAgB,aAAKA;gBAAY9B;;IAEnE;IACAP;AACF;AAEA,SAAS6B,qBAAqBR,GAAW;IACvC,KAAK,MAAMO,SAASpC,cAAcoB,MAAM,GAAI;YACtCgB;QAAJ,KAAIA,oBAAAA,MAAMD,UAAU,qBAAhBC,kBAAkBU,IAAI,CAAC,CAACC,QAAUA,MAAMlB,GAAG,KAAKA,MAAM,OAAOO,MAAMrB,QAAQ;IACjF;IACA,OAAOiC;AACT;AAEA,SAAST,2BAA2BV,GAAW;IAC7C,KAAK,MAAMO,SAASpC,cAAcoB,MAAM,GAAI;YACtCgB;QAAJ,KAAIA,0BAAAA,MAAME,gBAAgB,qBAAtBF,wBAAwBU,IAAI,CAAC,CAACG,UAAYA,QAAQpB,GAAG,KAAKA,MAAM;YAClE,OAAOO,MAAMrB,QAAQ;QACvB;IACF;IACA,OAAOiC;AACT;AAEA,SAASP,yBAAyBZ,GAAW;IAC3C,KAAK,MAAMO,SAASpC,cAAcoB,MAAM,GAAI;YACtCgB;QAAJ,KAAIA,wBAAAA,MAAMI,cAAc,qBAApBJ,sBAAsBU,IAAI,CAAC,CAACD,aAAeA,WAAWhB,GAAG,KAAKA,MAAM;YACtE,OAAOO,MAAMrB,QAAQ;QACvB;IACF;IACA,OAAOiC;AACT;AAEA,2FAA2F,GAC3F,OAAO,SAASE;IAGd,OAAO/B,uBAAuBgC,OAAO,CAAC,CAACf;YACpCA;eAAD,EAACA,wBAAAA,MAAMI,cAAc,YAApBJ,wBAAwB,EAAE,EAAE1B,GAAG,CAAC,CAACmC,aAAgB,aAC7CA;gBACH9B,UAAUqB,MAAMrB,QAAQ;;;AAG9B;AAEA,kDAAkD,GAClD,OAAO,SAASqC;IACd,OAAOjC,uBAAuBgC,OAAO,CAAC,CAACf;YAAeA;eAAL;gBAAKA,oBAAAA,MAAMD,UAAU,YAAhBC,oBAAoB,EAAE;SAAE;;AAChF;AAEA,sDAAsD,GACtD,OAAO,SAASiB,gBAAgBxB,GAAW;IACzC,OAAOuB,uBAAuBE,IAAI,CAAC,CAAClB,QAAUA,MAAMP,GAAG,KAAKA;AAC9D;AAEA,8CAA8C,GAC9C,OAAO,SAAS0B;IACd,OAAOpC,uBAAuBgC,OAAO,CAAC,CAACf;YAAeA;eAAL;gBAAKA,kBAAAA,MAAMoB,QAAQ,YAAdpB,kBAAkB,EAAE;SAAE;;AAC9E;AAEA,qDAAqD,GACrD,OAAO,SAASqB;IACd,OAAOtC,uBAAuBgC,OAAO,CAAC,CAACf;YACjCA;eAD2C;gBAC3CA,0BAAAA,MAAME,gBAAgB,YAAtBF,0BAA0B,EAAE;SACjC;;AACH;AAEA,wCAAwC,GACxC,OAAO,SAASsB,sBACd7B,GAAW;IAEX,OAAO4B,6BAA6BH,IAAI,CAAC,CAAClB,QAAUA,MAAMP,GAAG,KAAKA;AACpE;AAEA,gEAAgE,GAChE,OAAO,SAAS8B,2BAA2B9B,GAAW;IACpD,OAAOU,2BAA2BV;AACpC;AAEA,0CAA0C,GAC1C,OAAO,SAAS+B;IACd,OAAOzC;AACT;AAEA;;;CAGC,GACD,OAAO,SAAS0C;IACd7D,cAAc8D,KAAK;IACnBtD;AACF"}

package/src/lib/plugin-manager/plugin-membership-detach.js

@@ -19,7 +19,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  *
  * A container — a campaign is the first — is a document other records join
  * by naming it in a membership array on their OWN documents
- * (`app-utils/campaign-membership.ts` says why the edge lives on the
+ * (`app-utils/container-membership.ts` says why the edge lives on the
  * member). When the container is removed, its owner clears the id off every
  * member it can name. A plugin that keeps members of its own where that
  * walk does not reach — records under the org, in collections the owner

package/src/lib/plugin-manager/plugin-membership-detach.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-membership-detach.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 taking a CONTAINER away (AGL-3254).\n *\n * A container — a campaign is the first — is a document other records join\n * by naming it in a membership array on their OWN documents\n * (`app-utils/campaign-membership.ts` says why the edge lives on the\n * member). When the container is removed, its owner clears the id off every\n * member it can name. A plugin that keeps members of its own where that\n * walk does not reach — records under the org, in collections the owner\n * does not know — registers a detacher here, and the removal runs every\n * detacher with the container's id, the membership field it is held in,\n * the site and the org, so the plugin can clear its own records.\n *\n * Detachers run BEFORE the container is deleted, for the reason the owner's\n * own passes do: a run that stops between them leaves records already out\n * of the container, which every surface draws correctly, while deleting\n * first would leave a plugin's record naming an id nothing can resolve. A\n * detacher that reports `remaining` holds the deletion, exactly as the\n * owner's own pass does when the container is on more records than one\n * request can clear.\n *\n * Detachers 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.\n * The owner reads a `null` as \"this plugin's records may still name the\n * container\" and refuses to remove it, which is the direction a failure\n * here has to fall.\n *\n * Registered from a plugin's declarations — `consoleServerDeclarations`,\n * since a container is removed from the console — so the detacher is in\n * place in a process that never loaded the plugin's API surface. The core\n * never imports a plugin; this is how a removal one plugin performs reaches\n * another plugin's records.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** The container being removed, and where its members may be. */\nexport interface PluginMembershipDetachRequest {\n  /** The site the container belongs to. */\n  hostId: string\n  /** The site's organization, or `''` for a site with no org behind it. */\n  orgId: string\n  /** The membership field a member holds the container's id in. */\n  field: string\n  /** The container's document id — what the field names. */\n  id: string\n}\n\n/**\n * What a detacher reports: how many of its records it took the container\n * off, and whether any were left for a second run. Counts, never content.\n */\nexport interface PluginMembershipDetachReport {\n  detached: number\n  remaining: boolean\n}\n\nexport type PluginMembershipDetacher = (\n  request: PluginMembershipDetachRequest,\n) => Promise<PluginMembershipDetachReport>\n\ninterface Registration {\n  pluginId: string\n  detacher: PluginMembershipDetacher\n}\n\nconst registrations: Registration[] = []\n\n/**\n * Registers a plugin's membership detacher. Owner = the loader's marker\n * inside a register fn, else `options.pluginId`; a detacher with neither\n * throws. One detacher per plugin: registering again replaces the plugin's\n * earlier detacher in place, so a module evaluated twice does not run twice.\n */\nexport function registerPluginMembershipDetacher(\n  detacher: PluginMembershipDetacher,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin membership detacher was registered with no owner: pass ' +\n        '{ pluginId } 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, detacher }\n  else registrations.push({ pluginId, detacher })\n}\n\n/**\n * Runs every detacher, in registration order, and answers each plugin's\n * report by plugin id: the detacher's own report, or `null` for one that\n * threw. Never throws.\n */\nexport async function runPluginMembershipDetachers(\n  request: PluginMembershipDetachRequest,\n): Promise<Record<string, PluginMembershipDetachReport | null>> {\n  const reports: Record<string, PluginMembershipDetachReport | null> = {}\n  for (const { pluginId, detacher } of [...registrations]) {\n    try {\n      const report = await detacher({ ...request })\n      reports[pluginId] = {\n        detached: Math.max(0, Math.floor(Number(report?.detached ?? 0)) || 0),\n        remaining: report?.remaining === true,\n      }\n    } catch (error) {\n      reports[pluginId] = null\n      console.error(\n        `[plugins] ${pluginId} failed to detach ${request.field} ${request.id} on host ${request.hostId}`,\n        error,\n      )\n    }\n  }\n  return reports\n}\n\n/** The plugins with a detacher in place, in registration order. Only for specs and the guards. */\nexport function listPluginMembershipDetachers(): string[] {\n  return registrations.map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every detacher. */\nexport function resetPluginMembershipDetachersForTests(): void {\n  registrations.length = 0\n}\n"],"names":["getRegisteringPluginId","registrations","registerPluginMembershipDetacher","detacher","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginMembershipDetachers","request","reports","report","detached","Math","max","floor","Number","remaining","error","console","field","id","hostId","listPluginMembershipDetachers","map","resetPluginMembershipDetachersForTests","length"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AAgCxE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,iCACdC,QAAkC,EAClCC,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,qEACE;IAEN;IACA,MAAMC,QAAQP,cAAcQ,SAAS,CAAC,CAACC,QAAUA,MAAML,QAAQ,KAAKA;IACpE,IAAIG,SAAS,GAAGP,aAAa,CAACO,MAAM,GAAG;QAAEH;QAAUF;IAAS;SACvDF,cAAcU,IAAI,CAAC;QAAEN;QAAUF;IAAS;AAC/C;AAEA;;;;CAIC,GACD,OAAO,eAAeS,6BACpBC,OAAsC;IAEtC,MAAMC,UAA+D,CAAC;IACtE,KAAK,MAAM,EAAET,QAAQ,EAAEF,QAAQ,EAAE,IAAI;WAAIF;KAAc,CAAE;QACvD,IAAI;;YACF,MAAMc,SAAS,MAAMZ,SAAS,aAAKU;YACnCC,OAAO,CAACT,SAAS,GAAG;gBAClBW,UAAUC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,KAAK,CAACC,eAAOL,0BAAAA,OAAQC,QAAQ,mBAAI,OAAO;gBACnEK,WAAWN,CAAAA,0BAAAA,OAAQM,SAAS,MAAK;YACnC;QACF,EAAE,OAAOC,OAAO;YACdR,OAAO,CAACT,SAAS,GAAG;YACpBkB,QAAQD,KAAK,CACX,CAAC,UAAU,EAAEjB,SAAS,kBAAkB,EAAEQ,QAAQW,KAAK,CAAC,CAAC,EAAEX,QAAQY,EAAE,CAAC,SAAS,EAAEZ,QAAQa,MAAM,EAAE,EACjGJ;QAEJ;IACF;IACA,OAAOR;AACT;AAEA,gGAAgG,GAChG,OAAO,SAASa;IACd,OAAO1B,cAAc2B,GAAG,CAAC,CAAClB,QAAUA,MAAML,QAAQ;AACpD;AAEA,sCAAsC,GACtC,OAAO,SAASwB;IACd5B,cAAc6B,MAAM,GAAG;AACzB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-membership-detach.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 taking a CONTAINER away (AGL-3254).\n *\n * A container — a campaign is the first — is a document other records join\n * by naming it in a membership array on their OWN documents\n * (`app-utils/container-membership.ts` says why the edge lives on the\n * member). When the container is removed, its owner clears the id off every\n * member it can name. A plugin that keeps members of its own where that\n * walk does not reach — records under the org, in collections the owner\n * does not know — registers a detacher here, and the removal runs every\n * detacher with the container's id, the membership field it is held in,\n * the site and the org, so the plugin can clear its own records.\n *\n * Detachers run BEFORE the container is deleted, for the reason the owner's\n * own passes do: a run that stops between them leaves records already out\n * of the container, which every surface draws correctly, while deleting\n * first would leave a plugin's record naming an id nothing can resolve. A\n * detacher that reports `remaining` holds the deletion, exactly as the\n * owner's own pass does when the container is on more records than one\n * request can clear.\n *\n * Detachers 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.\n * The owner reads a `null` as \"this plugin's records may still name the\n * container\" and refuses to remove it, which is the direction a failure\n * here has to fall.\n *\n * Registered from a plugin's declarations — `consoleServerDeclarations`,\n * since a container is removed from the console — so the detacher is in\n * place in a process that never loaded the plugin's API surface. The core\n * never imports a plugin; this is how a removal one plugin performs reaches\n * another plugin's records.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** The container being removed, and where its members may be. */\nexport interface PluginMembershipDetachRequest {\n  /** The site the container belongs to. */\n  hostId: string\n  /** The site's organization, or `''` for a site with no org behind it. */\n  orgId: string\n  /** The membership field a member holds the container's id in. */\n  field: string\n  /** The container's document id — what the field names. */\n  id: string\n}\n\n/**\n * What a detacher reports: how many of its records it took the container\n * off, and whether any were left for a second run. Counts, never content.\n */\nexport interface PluginMembershipDetachReport {\n  detached: number\n  remaining: boolean\n}\n\nexport type PluginMembershipDetacher = (\n  request: PluginMembershipDetachRequest,\n) => Promise<PluginMembershipDetachReport>\n\ninterface Registration {\n  pluginId: string\n  detacher: PluginMembershipDetacher\n}\n\nconst registrations: Registration[] = []\n\n/**\n * Registers a plugin's membership detacher. Owner = the loader's marker\n * inside a register fn, else `options.pluginId`; a detacher with neither\n * throws. One detacher per plugin: registering again replaces the plugin's\n * earlier detacher in place, so a module evaluated twice does not run twice.\n */\nexport function registerPluginMembershipDetacher(\n  detacher: PluginMembershipDetacher,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin membership detacher was registered with no owner: pass ' +\n        '{ pluginId } 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, detacher }\n  else registrations.push({ pluginId, detacher })\n}\n\n/**\n * Runs every detacher, in registration order, and answers each plugin's\n * report by plugin id: the detacher's own report, or `null` for one that\n * threw. Never throws.\n */\nexport async function runPluginMembershipDetachers(\n  request: PluginMembershipDetachRequest,\n): Promise<Record<string, PluginMembershipDetachReport | null>> {\n  const reports: Record<string, PluginMembershipDetachReport | null> = {}\n  for (const { pluginId, detacher } of [...registrations]) {\n    try {\n      const report = await detacher({ ...request })\n      reports[pluginId] = {\n        detached: Math.max(0, Math.floor(Number(report?.detached ?? 0)) || 0),\n        remaining: report?.remaining === true,\n      }\n    } catch (error) {\n      reports[pluginId] = null\n      console.error(\n        `[plugins] ${pluginId} failed to detach ${request.field} ${request.id} on host ${request.hostId}`,\n        error,\n      )\n    }\n  }\n  return reports\n}\n\n/** The plugins with a detacher in place, in registration order. Only for specs and the guards. */\nexport function listPluginMembershipDetachers(): string[] {\n  return registrations.map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every detacher. */\nexport function resetPluginMembershipDetachersForTests(): void {\n  registrations.length = 0\n}\n"],"names":["getRegisteringPluginId","registrations","registerPluginMembershipDetacher","detacher","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginMembershipDetachers","request","reports","report","detached","Math","max","floor","Number","remaining","error","console","field","id","hostId","listPluginMembershipDetachers","map","resetPluginMembershipDetachersForTests","length"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AAgCxE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,iCACdC,QAAkC,EAClCC,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,qEACE;IAEN;IACA,MAAMC,QAAQP,cAAcQ,SAAS,CAAC,CAACC,QAAUA,MAAML,QAAQ,KAAKA;IACpE,IAAIG,SAAS,GAAGP,aAAa,CAACO,MAAM,GAAG;QAAEH;QAAUF;IAAS;SACvDF,cAAcU,IAAI,CAAC;QAAEN;QAAUF;IAAS;AAC/C;AAEA;;;;CAIC,GACD,OAAO,eAAeS,6BACpBC,OAAsC;IAEtC,MAAMC,UAA+D,CAAC;IACtE,KAAK,MAAM,EAAET,QAAQ,EAAEF,QAAQ,EAAE,IAAI;WAAIF;KAAc,CAAE;QACvD,IAAI;;YACF,MAAMc,SAAS,MAAMZ,SAAS,aAAKU;YACnCC,OAAO,CAACT,SAAS,GAAG;gBAClBW,UAAUC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,KAAK,CAACC,eAAOL,0BAAAA,OAAQC,QAAQ,mBAAI,OAAO;gBACnEK,WAAWN,CAAAA,0BAAAA,OAAQM,SAAS,MAAK;YACnC;QACF,EAAE,OAAOC,OAAO;YACdR,OAAO,CAACT,SAAS,GAAG;YACpBkB,QAAQD,KAAK,CACX,CAAC,UAAU,EAAEjB,SAAS,kBAAkB,EAAEQ,QAAQW,KAAK,CAAC,CAAC,EAAEX,QAAQY,EAAE,CAAC,SAAS,EAAEZ,QAAQa,MAAM,EAAE,EACjGJ;QAEJ;IACF;IACA,OAAOR;AACT;AAEA,gGAAgG,GAChG,OAAO,SAASa;IACd,OAAO1B,cAAc2B,GAAG,CAAC,CAAClB,QAAUA,MAAML,QAAQ;AACpD;AAEA,sCAAsC,GACtC,OAAO,SAASwB;IACd5B,cAAc6B,MAAM,GAAG;AACzB"}

package/src/lib/plugin-manager/plugin-record-email-state.d.ts

@@ -63,9 +63,63 @@ export interface PluginRecordEmailStateReport {
     /** Records whose state moved. */
     records: number;
 }
+/**
+ * One delivery event a send's webhook recorded, as the delivery log
+ * answered it: who it is about, what happened, when, and whether it is the
+ * first event of its type for its message.
+ */
+export interface PluginRecordEmailEvent {
+    /** The recipient, lowercased. */
+    to: string;
+    /** `opened`, `clicked`, `delivered`, `bounced`, … */
+    type: string;
+    /** When it happened, epoch ms. */
+    at: number;
+    /** No event of this type had been recorded against this message before. */
+    firstOfType: boolean;
+}
+/**
+ * The events one webhook delivery recorded for a send from a site — what
+ * the record system reads a person's engagement off (AGL-2616).
+ */
+export interface PluginRecordEmailEngagementRequest {
+    /**
+     * The site the send went out from: the `hostId` tag the send stamped,
+     * which is the only tenant identity a delivery event carries.
+     */
+    hostId: string;
+    events: readonly PluginRecordEmailEvent[];
+}
+/**
+ * The people a marketing send was delivered to (AGL-3446), so the record
+ * system can say automated email is reaching them — a lead's Nurturing
+ * stage. Only what was actually accepted for delivery: a refused or
+ * deferred address reached nobody.
+ */
+export interface PluginRecordEmailReachRequest {
+    /** The organization whose records the send reached. */
+    orgId: string;
+    /** The site the send went out as; only records it holds are moved. */
+    hostId: string;
+    /** The addresses delivered to, as the send addressed them. */
+    emails: readonly string[];
+}
 export interface PluginRecordEmailStateWriter {
     /** Never throws: a list is the control, the stamp is what a person reads. */
     stamp(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport>;
+    /**
+     * Stamps when each person these events name last engaged with a send from
+     * the site, on the records the site may see. Optional: a record system
+     * that keeps no engagement answers nothing. Never throws, for the reason
+     * `stamp` does not: the webhook's acknowledgement must not depend on it.
+     */
+    engaged?(request: PluginRecordEmailEngagementRequest): Promise<PluginRecordEmailStateReport>;
+    /**
+     * Notes that a marketing send reached these people. Optional: a record
+     * system with no stage for it answers nothing. Never throws: the mail has
+     * already gone.
+     */
+    reached?(request: PluginRecordEmailReachRequest): Promise<PluginRecordEmailStateReport>;
 }
 export declare const PLUGIN_RECORD_EMAIL_STATE: import("./plugin-services").PluginServiceContract<PluginRecordEmailStateWriter>;
 /**
@@ -90,3 +144,18 @@ export declare function pluginRecordEmailStateWriter(): ResolvedPluginRecordEmai
  * the stamp is a courtesy beside the list it already wrote.
  */
 export declare function stampRecordEmailState(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport | null>;
+/**
+ * Hands a send's delivery events to whichever plugin keeps the records, so
+ * it can stamp the people who engaged (AGL-2616). Answers `null` when no
+ * plugin keeps records, or the one that does keeps no engagement. Never
+ * throws: the caller is a webhook whose acknowledgement must not hang on a
+ * courtesy stamp.
+ */
+export declare function stampRecordEmailEngagement(request: PluginRecordEmailEngagementRequest): Promise<PluginRecordEmailStateReport | null>;
+/**
+ * Hands the addresses a marketing send was delivered to to whichever plugin
+ * keeps the records (AGL-3446). Answers `null` when no plugin keeps
+ * records, or the one that does keeps no such stage. Never throws: the
+ * send has already delivered, and its bookkeeping must not fail it.
+ */
+export declare function stampRecordEmailReach(request: PluginRecordEmailReachRequest): Promise<PluginRecordEmailStateReport | null>;

package/src/lib/plugin-manager/plugin-record-email-state.js

@@ -49,5 +49,37 @@ export const PLUGIN_RECORD_EMAIL_STATE = definePluginServiceContract('core.recor
         return null;
     }
 }
+/**
+ * Hands a send's delivery events to whichever plugin keeps the records, so
+ * it can stamp the people who engaged (AGL-2616). Answers `null` when no
+ * plugin keeps records, or the one that does keeps no engagement. Never
+ * throws: the caller is a webhook whose acknowledgement must not hang on a
+ * courtesy stamp.
+ */ export async function stampRecordEmailEngagement(request) {
+    const resolved = pluginRecordEmailStateWriter();
+    if (!(resolved == null ? void 0 : resolved.writer.engaged)) return null;
+    try {
+        return await resolved.writer.engaged(request);
+    } catch (error) {
+        console.error('[record-email-state] the record system could not stamp an engagement', error);
+        return null;
+    }
+}
+/**
+ * Hands the addresses a marketing send was delivered to to whichever plugin
+ * keeps the records (AGL-3446). Answers `null` when no plugin keeps
+ * records, or the one that does keeps no such stage. Never throws: the
+ * send has already delivered, and its bookkeeping must not fail it.
+ */ export async function stampRecordEmailReach(request) {
+    if (!request.emails.length) return null;
+    const resolved = pluginRecordEmailStateWriter();
+    if (!(resolved == null ? void 0 : resolved.writer.reached)) return null;
+    try {
+        return await resolved.writer.reached(request);
+    } catch (error) {
+        console.error('[record-email-state] the record system could not note a delivered send', error);
+        return null;
+    }
+}
 
 //# sourceMappingURL=plugin-record-email-state.js.map

package/src/lib/plugin-manager/plugin-record-email-state.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-email-state.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 { EmailState } from '../app-utils/email-state'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * The verdict on an address, written onto the records that carry it\n * (AGL-3245).\n *\n * The senders keep their lists — the platform's suppression list, a site's\n * suppressions, an organization's do-not-contact list — and those are what\n * a send consults. The record a person reads is the record system's: a\n * lead, a contact, whatever the plugin that keeps the workspace's records\n * calls them. A sender must not write that plugin's documents itself, nor\n * import it; so the record system registers a WRITER here, and a sender\n * that filed a verdict on a list says so through it.\n *\n * The writer finds every record the address is — the plugin knows its own\n * storage and its own index — and stamps `emailState` on each, keeping the\n * stronger verdict (`nextEmailState`). A single-implementation contract: a\n * workspace keeps one record system.\n *\n * ## The caller proves who is asking\n *\n * Like the timeline seam, the registry authenticates nobody. The caller\n * decides, in its own terms and before it asks, that the verdict is the\n * workspace's to write: an address it sent to, a list it wrote.\n */\n\nexport interface PluginRecordEmailStateRequest {\n  /** The organization whose records are stamped. */\n  orgId?: string\n  /**\n   * Or the site the send left from, when the caller knows only that — a\n   * campaign webhook, an unsubscribe link. The writer reads the\n   * organization off it.\n   */\n  hostId?: string\n  email: string\n  state: EmailState\n  /** Write the state whatever the record holds — a release. */\n  force?: boolean\n  /**\n   * Take the verdict back instead of writing it: a record whose standing\n   * state has `state.status` loses it, and any other record is left alone.\n   * The deliverability check's way back from `undeliverable` once the\n   * domain takes mail (AGL-3328); it never clears a verdict it did not give.\n   */\n  withdraw?: boolean\n}\n\nexport interface PluginRecordEmailStateReport {\n  /** Records whose state moved. */\n  records: number\n}\n\nexport interface PluginRecordEmailStateWriter {\n  /** Never throws: a list is the control, the stamp is what a person reads. */\n  stamp(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport>\n}\n\nexport const PLUGIN_RECORD_EMAIL_STATE = definePluginServiceContract<PluginRecordEmailStateWriter>(\n  'core.record-email-state',\n  { multiple: false },\n)\n\n/**\n * Registers the workspace's record email-state writer. The owner is the\n * loader's marker when a register fn is running, else `options.pluginId`;\n * with neither the registration throws, and a second plugin's writer is\n * refused naming both — the incumbent keeps serving.\n */\nexport function registerPluginRecordEmailStateWriter(\n  writer: PluginRecordEmailStateWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_EMAIL_STATE, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginRecordEmailStateWriter {\n  /** The plugin that keeps the records. */\n  pluginId: string\n  writer: PluginRecordEmailStateWriter\n}\n\n/** The writer, with its owner, or `null` when no plugin keeps records here. */\nexport function pluginRecordEmailStateWriter(): ResolvedPluginRecordEmailStateWriter | null {\n  const entry = resolvePluginServices(PLUGIN_RECORD_EMAIL_STATE)[0]\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n\n/**\n * Stamps the verdict through whichever plugin keeps the records, or answers\n * `null` when none does. Never throws: every caller is a sender for whom\n * the stamp is a courtesy beside the list it already wrote.\n */\nexport async function stampRecordEmailState(\n  request: PluginRecordEmailStateRequest,\n): Promise<PluginRecordEmailStateReport | null> {\n  const resolved = pluginRecordEmailStateWriter()\n  if (!resolved) return null\n  try {\n    return await resolved.writer.stamp(request)\n  } catch (error) {\n    console.error('[record-email-state] the record system could not stamp the address', error)\n    return null\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_EMAIL_STATE","multiple","registerPluginRecordEmailStateWriter","writer","options","pluginId","pluginRecordEmailStateWriter","entry","impl","stampRecordEmailState","request","resolved","stamp","error","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA0D1B,OAAO,MAAMC,4BAA4BH,4BACvC,2BACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,qCACdC,MAAoC,EACpCC,OAA+B;IAE/BN,sBAAsBE,2BAA2BG,QAAQ,aACnDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,0BAA0B,CAAC,EAAE;IACjE,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,QAAQI,MAAMC,IAAI;IAAC,IAAI;AACpE;AAEA;;;;CAIC,GACD,OAAO,eAAeC,sBACpBC,OAAsC;IAEtC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,IAAI;QACF,OAAO,MAAMA,SAASR,MAAM,CAACS,KAAK,CAACF;IACrC,EAAE,OAAOG,OAAO;QACdC,QAAQD,KAAK,CAAC,sEAAsEA;QACpF,OAAO;IACT;AACF"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-email-state.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 { EmailState } from '../app-utils/email-state'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * The verdict on an address, written onto the records that carry it\n * (AGL-3245).\n *\n * The senders keep their lists — the platform's suppression list, a site's\n * suppressions, an organization's do-not-contact list — and those are what\n * a send consults. The record a person reads is the record system's: a\n * lead, a contact, whatever the plugin that keeps the workspace's records\n * calls them. A sender must not write that plugin's documents itself, nor\n * import it; so the record system registers a WRITER here, and a sender\n * that filed a verdict on a list says so through it.\n *\n * The writer finds every record the address is — the plugin knows its own\n * storage and its own index — and stamps `emailState` on each, keeping the\n * stronger verdict (`nextEmailState`). A single-implementation contract: a\n * workspace keeps one record system.\n *\n * ## The caller proves who is asking\n *\n * Like the timeline seam, the registry authenticates nobody. The caller\n * decides, in its own terms and before it asks, that the verdict is the\n * workspace's to write: an address it sent to, a list it wrote.\n */\n\nexport interface PluginRecordEmailStateRequest {\n  /** The organization whose records are stamped. */\n  orgId?: string\n  /**\n   * Or the site the send left from, when the caller knows only that — a\n   * campaign webhook, an unsubscribe link. The writer reads the\n   * organization off it.\n   */\n  hostId?: string\n  email: string\n  state: EmailState\n  /** Write the state whatever the record holds — a release. */\n  force?: boolean\n  /**\n   * Take the verdict back instead of writing it: a record whose standing\n   * state has `state.status` loses it, and any other record is left alone.\n   * The deliverability check's way back from `undeliverable` once the\n   * domain takes mail (AGL-3328); it never clears a verdict it did not give.\n   */\n  withdraw?: boolean\n}\n\nexport interface PluginRecordEmailStateReport {\n  /** Records whose state moved. */\n  records: number\n}\n\n/**\n * One delivery event a send's webhook recorded, as the delivery log\n * answered it: who it is about, what happened, when, and whether it is the\n * first event of its type for its message.\n */\nexport interface PluginRecordEmailEvent {\n  /** The recipient, lowercased. */\n  to: string\n  /** `opened`, `clicked`, `delivered`, `bounced`, … */\n  type: string\n  /** When it happened, epoch ms. */\n  at: number\n  /** No event of this type had been recorded against this message before. */\n  firstOfType: boolean\n}\n\n/**\n * The events one webhook delivery recorded for a send from a site — what\n * the record system reads a person's engagement off (AGL-2616).\n */\nexport interface PluginRecordEmailEngagementRequest {\n  /**\n   * The site the send went out from: the `hostId` tag the send stamped,\n   * which is the only tenant identity a delivery event carries.\n   */\n  hostId: string\n  events: readonly PluginRecordEmailEvent[]\n}\n\n/**\n * The people a marketing send was delivered to (AGL-3446), so the record\n * system can say automated email is reaching them — a lead's Nurturing\n * stage. Only what was actually accepted for delivery: a refused or\n * deferred address reached nobody.\n */\nexport interface PluginRecordEmailReachRequest {\n  /** The organization whose records the send reached. */\n  orgId: string\n  /** The site the send went out as; only records it holds are moved. */\n  hostId: string\n  /** The addresses delivered to, as the send addressed them. */\n  emails: readonly string[]\n}\n\nexport interface PluginRecordEmailStateWriter {\n  /** Never throws: a list is the control, the stamp is what a person reads. */\n  stamp(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport>\n  /**\n   * Stamps when each person these events name last engaged with a send from\n   * the site, on the records the site may see. Optional: a record system\n   * that keeps no engagement answers nothing. Never throws, for the reason\n   * `stamp` does not: the webhook's acknowledgement must not depend on it.\n   */\n  engaged?(request: PluginRecordEmailEngagementRequest): Promise<PluginRecordEmailStateReport>\n  /**\n   * Notes that a marketing send reached these people. Optional: a record\n   * system with no stage for it answers nothing. Never throws: the mail has\n   * already gone.\n   */\n  reached?(request: PluginRecordEmailReachRequest): Promise<PluginRecordEmailStateReport>\n}\n\nexport const PLUGIN_RECORD_EMAIL_STATE = definePluginServiceContract<PluginRecordEmailStateWriter>(\n  'core.record-email-state',\n  { multiple: false },\n)\n\n/**\n * Registers the workspace's record email-state writer. The owner is the\n * loader's marker when a register fn is running, else `options.pluginId`;\n * with neither the registration throws, and a second plugin's writer is\n * refused naming both — the incumbent keeps serving.\n */\nexport function registerPluginRecordEmailStateWriter(\n  writer: PluginRecordEmailStateWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_EMAIL_STATE, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginRecordEmailStateWriter {\n  /** The plugin that keeps the records. */\n  pluginId: string\n  writer: PluginRecordEmailStateWriter\n}\n\n/** The writer, with its owner, or `null` when no plugin keeps records here. */\nexport function pluginRecordEmailStateWriter(): ResolvedPluginRecordEmailStateWriter | null {\n  const entry = resolvePluginServices(PLUGIN_RECORD_EMAIL_STATE)[0]\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n\n/**\n * Stamps the verdict through whichever plugin keeps the records, or answers\n * `null` when none does. Never throws: every caller is a sender for whom\n * the stamp is a courtesy beside the list it already wrote.\n */\nexport async function stampRecordEmailState(\n  request: PluginRecordEmailStateRequest,\n): Promise<PluginRecordEmailStateReport | null> {\n  const resolved = pluginRecordEmailStateWriter()\n  if (!resolved) return null\n  try {\n    return await resolved.writer.stamp(request)\n  } catch (error) {\n    console.error('[record-email-state] the record system could not stamp the address', error)\n    return null\n  }\n}\n\n/**\n * Hands a send's delivery events to whichever plugin keeps the records, so\n * it can stamp the people who engaged (AGL-2616). Answers `null` when no\n * plugin keeps records, or the one that does keeps no engagement. Never\n * throws: the caller is a webhook whose acknowledgement must not hang on a\n * courtesy stamp.\n */\nexport async function stampRecordEmailEngagement(\n  request: PluginRecordEmailEngagementRequest,\n): Promise<PluginRecordEmailStateReport | null> {\n  const resolved = pluginRecordEmailStateWriter()\n  if (!resolved?.writer.engaged) return null\n  try {\n    return await resolved.writer.engaged(request)\n  } catch (error) {\n    console.error('[record-email-state] the record system could not stamp an engagement', error)\n    return null\n  }\n}\n\n/**\n * Hands the addresses a marketing send was delivered to to whichever plugin\n * keeps the records (AGL-3446). Answers `null` when no plugin keeps\n * records, or the one that does keeps no such stage. Never throws: the\n * send has already delivered, and its bookkeeping must not fail it.\n */\nexport async function stampRecordEmailReach(\n  request: PluginRecordEmailReachRequest,\n): Promise<PluginRecordEmailStateReport | null> {\n  if (!request.emails.length) return null\n  const resolved = pluginRecordEmailStateWriter()\n  if (!resolved?.writer.reached) return null\n  try {\n    return await resolved.writer.reached(request)\n  } catch (error) {\n    console.error('[record-email-state] the record system could not note a delivered send', error)\n    return null\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_EMAIL_STATE","multiple","registerPluginRecordEmailStateWriter","writer","options","pluginId","pluginRecordEmailStateWriter","entry","impl","stampRecordEmailState","request","resolved","stamp","error","console","stampRecordEmailEngagement","engaged","stampRecordEmailReach","emails","length","reached"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAmH1B,OAAO,MAAMC,4BAA4BH,4BACvC,2BACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,qCACdC,MAAoC,EACpCC,OAA+B;IAE/BN,sBAAsBE,2BAA2BG,QAAQ,aACnDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,0BAA0B,CAAC,EAAE;IACjE,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,QAAQI,MAAMC,IAAI;IAAC,IAAI;AACpE;AAEA;;;;CAIC,GACD,OAAO,eAAeC,sBACpBC,OAAsC;IAEtC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,IAAI;QACF,OAAO,MAAMA,SAASR,MAAM,CAACS,KAAK,CAACF;IACrC,EAAE,OAAOG,OAAO;QACdC,QAAQD,KAAK,CAAC,sEAAsEA;QACpF,OAAO;IACT;AACF;AAEA;;;;;;CAMC,GACD,OAAO,eAAeE,2BACpBL,OAA2C;IAE3C,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,MAAM,CAACa,OAAO,GAAE,OAAO;IACtC,IAAI;QACF,OAAO,MAAML,SAASR,MAAM,CAACa,OAAO,CAACN;IACvC,EAAE,OAAOG,OAAO;QACdC,QAAQD,KAAK,CAAC,wEAAwEA;QACtF,OAAO;IACT;AACF;AAEA;;;;;CAKC,GACD,OAAO,eAAeI,sBACpBP,OAAsC;IAEtC,IAAI,CAACA,QAAQQ,MAAM,CAACC,MAAM,EAAE,OAAO;IACnC,MAAMR,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,MAAM,CAACiB,OAAO,GAAE,OAAO;IACtC,IAAI;QACF,OAAO,MAAMT,SAASR,MAAM,CAACiB,OAAO,CAACV;IACvC,EAAE,OAAOG,OAAO;QACdC,QAAQD,KAAK,CAAC,0EAA0EA;QACxF,OAAO;IACT;AACF"}

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

@@ -0,0 +1,115 @@
+/**
+ * @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 type { DocumentData, Firestore, Query } from 'firebase/firestore';
+import type { PluginIndexedRecord } from './plugin-record-index';
+/**
+ * A plugin's records, LISTED in the console for another plugin's picker or
+ * check (AGL-3080) — the browser's half of `plugin-record-index`.
+ *
+ * A plugin that offers records it does not own — an automation step picking
+ * a dataset, a reference check confirming a workflow still exists, a deal
+ * picking a product — used to query the owner's collection from the browser
+ * itself: the path, the filter the owner's security rules require, the field
+ * a name is in, what a deleted one looks like. Each breaks the day the owner
+ * changes one, and none is visible to `check:lib-boundaries`.
+ *
+ * So the owner publishes a LIST SOURCE for each record kind it keeps: the
+ * query the signed-in member's read of a scope is proved by, and how one
+ * stored document reads as a record — an id, a name and the facts the owner
+ * chooses to share, in the shape its registration documents, the same shape
+ * its server index answers. The reader runs the query with its own listener
+ * (`pluginRecordListQuery`) and reads the rows back through the owner
+ * (`pluginRecordsFromRows`), and never learns where the records are stored.
+ *
+ * ## Not registered is an answer
+ *
+ * No source for a kind means no plugin keeps it in this console — the owner is
+ * not installed or not loaded. A reader treats that as "none here" and says
+ * so, rather than reaching for the collection itself.
+ *
+ * ## One source per kind
+ *
+ * A second plugin registering a source for a kind another plugin already
+ * keeps is refused, naming both, and the incumbent keeps serving.
+ */
+/** Which records a reader lists. */
+export interface PluginRecordListRequest {
+    /** The organization the records belong to, where the kind is org-scoped. */
+    orgId?: string | null;
+    /**
+     * The site the records are listed for. An org-scoped kind narrows to what
+     * the site may use; `null` lists the organization's own view, which only an
+     * organization-wide reader may hold.
+     */
+    hostId?: string | null;
+    /** What a person typed, matched the owner's way; absent lists the scope. */
+    search?: string | null;
+    /**
+     * The signed-in member's own scope tokens, where they are not
+     * organization-wide and no site is named: an org-scoped kind narrows to
+     * what they may see, which is the filter the security rules require of
+     * them. Absent for an organization-wide reader; a named site's narrowing
+     * wins over it, and a site's own kind has no use for it.
+     */
+    memberScope?: readonly string[] | null;
+    /**
+     * Only the records installed from this listing — the `listingId` of their
+     * install stamp (`app-utils/artifact-provenance.ts`), matched wherever the
+     * owner keeps it. A kind that is never installed answers none.
+     */
+    installedFrom?: string | null;
+    /** The most documents the query may answer — a reader asks one past its window to learn it was cut. */
+    limit: number;
+}
+export interface PluginRecordListSource {
+    /**
+     * The query the signed-in member's read of the scope is proved by, at most
+     * `limit` documents, or `null` for a scope the kind has none in (a site-only
+     * kind asked at the organization, a search with nothing to match).
+     */
+    query(firestore: Firestore, request: PluginRecordListRequest): Query<DocumentData> | null;
+    /** One stored document as the owner shares it, or `null` to leave it out (deleted, unnamed). */
+    record(id: string, data: Readonly<Record<string, unknown>>): PluginIndexedRecord | null;
+}
+export declare const PLUGIN_RECORD_LISTS: import("./plugin-services").PluginServiceContract<PluginRecordListSource>;
+/**
+ * Publishes the list source for one record kind. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`; with neither
+ * the registration throws. A kind another plugin lists throws naming both.
+ */
+export declare function registerPluginRecordListSource(kind: string, source: PluginRecordListSource, options?: {
+    pluginId?: string;
+}): void;
+/** The list source for a kind, with the plugin that keeps it, or `null` when none does here. */
+export declare function pluginRecordListSource(kind: string): {
+    pluginId: string;
+    source: PluginRecordListSource;
+} | null;
+/**
+ * The query a reader listens to for a kind's records — with the console's own
+ * collection listener, so it is bounded, retried and reported like every
+ * other list — or `null` when no plugin keeps the kind here or the scope has
+ * none.
+ */
+export declare function pluginRecordListQuery(kind: string, firestore: Firestore, request: PluginRecordListRequest): Query<DocumentData> | null;
+/**
+ * The documents a reader's listener answered for `kind`, as their owner
+ * shares them: each row's id is read from `idField` (the listener's), and a
+ * row the owner leaves out (deleted, unnamed) is not answered. None where no
+ * plugin keeps the kind here.
+ */
+export declare function pluginRecordsFromRows(kind: string, rows: ReadonlyArray<Readonly<Record<string, unknown>>> | null | undefined, idField?: string): PluginIndexedRecord[];