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

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

@@ -46,7 +46,33 @@
  * `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.
+ *
+ * ## A REQUIRED eraser (AGL-3080)
+ *
+ * Isolation is right for a share whose failure leaves the workspace's data
+ * gone and only a provider-side courtesy undone. It is wrong for a share the
+ * erasure PROMISES: a public record naming the erased organization, a payout
+ * identifier on a world-readable document. A plugin holding such a record
+ * declares `"requiredOrgEraser": true` in `plugins.config.json`, compiled into
+ * {@link PLUGIN_REQUIRED_ORG_ERASERS} so no registration can opt out of it, and:
+ *
+ * - an erasure REFUSES to start while a required eraser is not registered —
+ *   a boot that failed to declare it must not produce a "complete" erasure
+ *   with the record still standing;
+ * - a required eraser that throws still lets every other eraser run, and then
+ *   fails the erasure's `plugins` step, which the cron retries.
+ *
+ * ## Plugin collections keyed by the organization (AGL-3080)
+ *
+ * A plugin's TOP-LEVEL collection whose documents carry the organization's id
+ * in a field is invisible to the erasure's path deletes. The plugin declares
+ * it (`orgKeyedCollections`, compiled into {@link PLUGIN_ORG_KEYED_COLLECTIONS})
+ * and the erasure sweeps it by that field in every process, with or without
+ * the plugin loaded — a deletion that must not depend on which bundles an
+ * erasing process happened to load, so it is data rather than an eraser.
  */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS } from "./first-party-plugins.generated.js";
+export { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS };
 const registrations = [];
 /**
  * Registers a plugin's workspace eraser. Owner = the loader's marker inside a
@@ -72,9 +98,20 @@ const registrations = [];
 /**
  * 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) {
+ * threw.
+ *
+ * Throws in exactly two cases, both about a REQUIRED eraser (`required`,
+ * the compiled {@link PLUGIN_REQUIRED_ORG_ERASERS} unless a spec passes its
+ * own): before running anything, when one is not registered; and after
+ * running every eraser, when one threw.
+ */ export async function runPluginOrgErasers(request, required = PLUGIN_REQUIRED_ORG_ERASERS) {
+    const registered = new Set(registrations.map((entry)=>entry.pluginId));
+    const missing = required.filter((pluginId)=>!registered.has(pluginId));
+    if (missing.length) {
+        throw new Error(`[plugins] erasing org ${request.orgId} refused: ${missing.join(', ')} ` + 'declared a required org eraser and none is registered in this process');
+    }
     const reports = {};
+    const failedRequired = [];
     for (const { pluginId, eraser } of [
         ...registrations
     ]){
@@ -86,8 +123,12 @@ const registrations = [];
         } catch (error) {
             reports[pluginId] = null;
             console.error(`[plugins] ${pluginId} failed to erase org ${request.orgId}`, error);
+            if (required.includes(pluginId)) failedRequired.push(pluginId);
         }
     }
+    if (failedRequired.length) {
+        throw new Error(`[plugins] erasing org ${request.orgId} incomplete: the required eraser of ` + `${failedRequired.join(', ')} failed`);
+    }
     return reports;
 }
 /** The plugins with a workspace eraser, in the order they run. */ export function listPluginOrgErasers() {
@@ -96,5 +137,23 @@ const registrations = [];
 /** Test seam: forget every eraser. */ export function resetPluginOrgErasersForTests() {
     registrations.length = 0;
 }
+/**
+ * Test seam: a no-op eraser for every REQUIRED plugin that has none, so a
+ * spec about the erasure's own sweeps can run it without loading a plugin
+ * (core and the data layer may not import one). A spec about a required
+ * plugin's share registers the real one through the app's manifest instead.
+ */ export function standInRequiredOrgErasersForTests() {
+    const registered = new Set(registrations.map((entry)=>entry.pluginId));
+    for (const pluginId of PLUGIN_REQUIRED_ORG_ERASERS){
+        if (!registered.has(pluginId)) {
+            registrations.push({
+                pluginId,
+                eraser: async ()=>({
+                        standIn: true
+                    })
+            });
+        }
+    }
+}
 
 //# sourceMappingURL=plugin-org-erasure.js.map

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

@@ -1 +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"}
+{"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 * ## A REQUIRED eraser (AGL-3080)\n *\n * Isolation is right for a share whose failure leaves the workspace's data\n * gone and only a provider-side courtesy undone. It is wrong for a share the\n * erasure PROMISES: a public record naming the erased organization, a payout\n * identifier on a world-readable document. A plugin holding such a record\n * declares `\"requiredOrgEraser\": true` in `plugins.config.json`, compiled into\n * {@link PLUGIN_REQUIRED_ORG_ERASERS} so no registration can opt out of it, and:\n *\n * - an erasure REFUSES to start while a required eraser is not registered —\n *   a boot that failed to declare it must not produce a \"complete\" erasure\n *   with the record still standing;\n * - a required eraser that throws still lets every other eraser run, and then\n *   fails the erasure's `plugins` step, which the cron retries.\n *\n * ## Plugin collections keyed by the organization (AGL-3080)\n *\n * A plugin's TOP-LEVEL collection whose documents carry the organization's id\n * in a field is invisible to the erasure's path deletes. The plugin declares\n * it (`orgKeyedCollections`, compiled into {@link PLUGIN_ORG_KEYED_COLLECTIONS})\n * and the erasure sweeps it by that field in every process, with or without\n * the plugin loaded — a deletion that must not depend on which bundles an\n * erasing process happened to load, so it is data rather than an eraser.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  PLUGIN_ORG_KEYED_COLLECTIONS,\n  PLUGIN_REQUIRED_ORG_ERASERS,\n} from './first-party-plugins.generated'\n\nexport { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS }\n\n/**\n * A plugin's top-level collection whose documents name an organization in a\n * field, declared by that plugin. See the module note.\n */\nexport interface PluginOrgKeyedCollection {\n  /** The plugin that declared it. */\n  pluginId: string\n  /** The top-level collection. */\n  name: string\n  /** The field naming the organization a document belongs to. */\n  orgField: string\n}\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.\n *\n * Throws in exactly two cases, both about a REQUIRED eraser (`required`,\n * the compiled {@link PLUGIN_REQUIRED_ORG_ERASERS} unless a spec passes its\n * own): before running anything, when one is not registered; and after\n * running every eraser, when one threw.\n */\nexport async function runPluginOrgErasers(\n  request: PluginOrgErasureRequest,\n  required: readonly string[] = PLUGIN_REQUIRED_ORG_ERASERS,\n): Promise<Record<string, PluginOrgErasureReport | null>> {\n  const registered = new Set(registrations.map((entry) => entry.pluginId))\n  const missing = required.filter((pluginId) => !registered.has(pluginId))\n  if (missing.length) {\n    throw new Error(\n      `[plugins] erasing org ${request.orgId} refused: ${missing.join(', ')} ` +\n        'declared a required org eraser and none is registered in this process',\n    )\n  }\n  const reports: Record<string, PluginOrgErasureReport | null> = {}\n  const failedRequired: string[] = []\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      if (required.includes(pluginId)) failedRequired.push(pluginId)\n    }\n  }\n  if (failedRequired.length) {\n    throw new Error(\n      `[plugins] erasing org ${request.orgId} incomplete: the required eraser of ` +\n        `${failedRequired.join(', ')} failed`,\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\n/**\n * Test seam: a no-op eraser for every REQUIRED plugin that has none, so a\n * spec about the erasure's own sweeps can run it without loading a plugin\n * (core and the data layer may not import one). A spec about a required\n * plugin's share registers the real one through the app's manifest instead.\n */\nexport function standInRequiredOrgErasersForTests(): void {\n  const registered = new Set(registrations.map((entry) => entry.pluginId))\n  for (const pluginId of PLUGIN_REQUIRED_ORG_ERASERS) {\n    if (!registered.has(pluginId)) {\n      registrations.push({ pluginId, eraser: async () => ({ standIn: true }) })\n    }\n  }\n}\n"],"names":["getRegisteringPluginId","PLUGIN_ORG_KEYED_COLLECTIONS","PLUGIN_REQUIRED_ORG_ERASERS","registrations","registerPluginOrgEraser","eraser","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginOrgErasers","request","required","registered","Set","map","missing","filter","has","length","orgId","join","reports","failedRequired","dryRun","error","console","includes","listPluginOrgErasers","resetPluginOrgErasersForTests","standInRequiredOrgErasersForTests","standIn"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,4BAA4B,EAC5BC,2BAA2B,QACtB,qCAAiC;AAExC,SAASD,4BAA4B,EAAEC,2BAA2B,GAAE;AA0CpE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,wBACdC,MAAuB,EACvBC,OAA+B;QAEbN,MAAAA;IAAlB,MAAMO,WAAW,EAACP,QAAAA,0BAAAA,oCAAAA,0BAA4BM,2BAAAA,QAASC,QAAQ,YAA7CP,OAAiD,IAAIQ,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;;;;;;;;;CASC,GACD,OAAO,eAAeS,oBACpBC,OAAgC,EAChCC,WAA8Bd,2BAA2B;IAEzD,MAAMe,aAAa,IAAIC,IAAIf,cAAcgB,GAAG,CAAC,CAACP,QAAUA,MAAML,QAAQ;IACtE,MAAMa,UAAUJ,SAASK,MAAM,CAAC,CAACd,WAAa,CAACU,WAAWK,GAAG,CAACf;IAC9D,IAAIa,QAAQG,MAAM,EAAE;QAClB,MAAM,IAAId,MACR,CAAC,sBAAsB,EAAEM,QAAQS,KAAK,CAAC,UAAU,EAAEJ,QAAQK,IAAI,CAAC,MAAM,CAAC,CAAC,GACtE;IAEN;IACA,MAAMC,UAAyD,CAAC;IAChE,MAAMC,iBAA2B,EAAE;IACnC,KAAK,MAAM,EAAEpB,QAAQ,EAAEF,MAAM,EAAE,IAAI;WAAIF;KAAc,CAAE;QACrD,IAAI;YACFuB,OAAO,CAACnB,SAAS,GAAG,MAAMF,OAAO;gBAAEmB,OAAOT,QAAQS,KAAK;gBAAEI,QAAQb,QAAQa,MAAM;YAAC;QAClF,EAAE,OAAOC,OAAO;YACdH,OAAO,CAACnB,SAAS,GAAG;YACpBuB,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEtB,SAAS,qBAAqB,EAAEQ,QAAQS,KAAK,EAAE,EAAEK;YAC5E,IAAIb,SAASe,QAAQ,CAACxB,WAAWoB,eAAed,IAAI,CAACN;QACvD;IACF;IACA,IAAIoB,eAAeJ,MAAM,EAAE;QACzB,MAAM,IAAId,MACR,CAAC,sBAAsB,EAAEM,QAAQS,KAAK,CAAC,oCAAoC,CAAC,GAC1E,GAAGG,eAAeF,IAAI,CAAC,MAAM,OAAO,CAAC;IAE3C;IACA,OAAOC;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASM;IACd,OAAO7B,cAAcgB,GAAG,CAAC,CAACP,QAAUA,MAAML,QAAQ;AACpD;AAEA,oCAAoC,GACpC,OAAO,SAAS0B;IACd9B,cAAcoB,MAAM,GAAG;AACzB;AAEA;;;;;CAKC,GACD,OAAO,SAASW;IACd,MAAMjB,aAAa,IAAIC,IAAIf,cAAcgB,GAAG,CAAC,CAACP,QAAUA,MAAML,QAAQ;IACtE,KAAK,MAAMA,YAAYL,4BAA6B;QAClD,IAAI,CAACe,WAAWK,GAAG,CAACf,WAAW;YAC7BJ,cAAcU,IAAI,CAAC;gBAAEN;gBAAUF,QAAQ,UAAa,CAAA;wBAAE8B,SAAS;oBAAK,CAAA;YAAG;QACzE;IACF;AACF"}

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

@@ -0,0 +1,123 @@
+/**
+ * @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 EACH PLAN INCLUDES OF A PLUGIN'S OWN KEYS (AGL-3080).
+ *
+ * `plugin-entitlement-keys` gives a plugin the TYPE of a key it owns, by
+ * augmentation, so `OrgEntitlements` and `OrgFeatureFlags` carry the key
+ * without core naming it. That leaves the VALUE: what Free, Starter and every
+ * other plan include of it. A key that only a plugin's type declares still
+ * needs a figure in every row of `PLAN_ENTITLEMENTS`, and core writing the
+ * figure is core naming the key.
+ *
+ * So the owning plugin declares the figure per plan, beside the reasoning
+ * that sized it, and core composes it into the plan table. A plan row in
+ * `PLAN_ENTITLEMENTS` still answers every key the platform sells, at the same
+ * number — `/pricing`, the plan comparison, the pricing-table generator and
+ * every quota gate read the composed table and cannot tell the difference.
+ *
+ * ## Compiled, never registered
+ *
+ * The readers include the published pricing tables, which a generator builds
+ * from `PLAN_ENTITLEMENTS` with no plugin loaded, and the customer's plan
+ * comparison, which renders before any plugin surface does. A registry one of
+ * them had not filled would publish a plan without the band — a missing row on
+ * the price list, or a quota gate reading nothing — with nothing red. So a
+ * first-party plugin names a function under `register.planEntitlements` in
+ * `plugins.config.json`; `tools/scripts/generate-plugin-manifests.mjs` loads
+ * `${package}/plan-entitlements`, calls it, validates the answer and compiles
+ * it into `first-party-plugins.generated.ts` as data. There is no runtime
+ * registrar, for the reason `plugin-org-capacity` gives: a registrar nothing
+ * can safely call is worse than none.
+ *
+ * ## What a missing figure means
+ *
+ * A declaration names every plan: the generated rows are typed
+ * `Record<OrgPlan, …>`, so a plan left out does not compile. A key nobody
+ * declares is absent from the table, and each reader answers absence in the
+ * closed direction — a quota reads as nothing included, a feature as off.
+ * `planQuotaOf` below is that reading, and it never answers "unlimited" or
+ * "free" for a key that has no figure.
+ *
+ * ## One key, one owner, and never one of core's
+ *
+ * The generator refuses a key two plugins declare. A key the platform's own
+ * rows already carry is refused by `plan-entitlements.spec.ts` rather than
+ * here, because the generator cannot read core's rows without loading the
+ * module that imports this one; the composition keeps core's figure either
+ * way, so a collision can shadow nothing a customer is charged.
+ */
+import type { OrgPlan } from '../foundation';
+/** A numeric entitlement a plugin owns: a band, a daily pace, a take rate. */
+export interface PluginPlanQuotaDeclaration {
+    /** The stored key, exactly as `OrgEntitlements` and an override spell it. */
+    key: string;
+    /** What a staff page calls it. */
+    label: string;
+    /**
+     * What each plan includes. `Infinity` is `UNLIMITED`; every other value is
+     * a finite, non-negative number.
+     */
+    byPlan: Readonly<Record<OrgPlan, number>>;
+    /**
+     * A PRICE rather than a cap — a percentage of a sale — so an uncapped plan
+     * comp must never lift it (`PRICE_ENTITLEMENT_KEYS`).
+     */
+    price?: boolean;
+}
+/** A boolean gate a plugin owns. */
+export interface PluginPlanFeatureDeclaration {
+    /** The stored key, exactly as `OrgFeatureFlags` and an override spell it. */
+    key: string;
+    label: string;
+    byPlan: Readonly<Record<OrgPlan, boolean>>;
+}
+/** What a plugin's `planEntitlements` function answers. */
+export interface PluginPlanEntitlementsDeclaration {
+    quotas?: readonly PluginPlanQuotaDeclaration[];
+    features?: readonly PluginPlanFeatureDeclaration[];
+}
+/** A quota declaration with the plugin that made it. */
+export type ResolvedPluginPlanQuota = PluginPlanQuotaDeclaration & {
+    pluginId: string;
+};
+/** A feature declaration with the plugin that made it. */
+export type ResolvedPluginPlanFeature = PluginPlanFeatureDeclaration & {
+    pluginId: string;
+};
+/** Every declared quota, in catalog order. */
+export declare function pluginPlanQuotas(): readonly ResolvedPluginPlanQuota[];
+/** Every declared feature, in catalog order. */
+export declare function pluginPlanFeatures(): readonly ResolvedPluginPlanFeature[];
+/** The plugin that declared a quota or feature key, or `null`. */
+export declare function pluginPlanEntitlementOwner(key: string): string | null;
+/** The declared quotas' figures for one plan, keyed by the stored key. */
+export declare function pluginPlanQuotaRow(plan: OrgPlan): Record<string, number>;
+/** The declared features' answers for one plan, keyed by the stored key. */
+export declare function pluginPlanFeatureRow(plan: OrgPlan): Record<string, boolean>;
+/**
+ * A resolved quota read by its key — the reading core uses for a key a plugin
+ * owns, since core compiles without the plugin's type augmentation.
+ *
+ * ⚑ ABSENT IS NOTHING INCLUDED. A key no plugin declares, or a value that is
+ * not a number, reads as `0`: every gate that compares usage against it
+ * refuses, and every meter drawn from it shows full. That is the same
+ * direction `plugin-org-capacity` answers an unknown capacity in. Reading
+ * absence as `UNLIMITED` would be a plan giving away what nobody declared it
+ * sells.
+ */
+export declare function planQuotaOf(entitlements: object, key: string): number;

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

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHAT EACH PLAN INCLUDES OF A PLUGIN'S OWN KEYS (AGL-3080).
+ *
+ * `plugin-entitlement-keys` gives a plugin the TYPE of a key it owns, by
+ * augmentation, so `OrgEntitlements` and `OrgFeatureFlags` carry the key
+ * without core naming it. That leaves the VALUE: what Free, Starter and every
+ * other plan include of it. A key that only a plugin's type declares still
+ * needs a figure in every row of `PLAN_ENTITLEMENTS`, and core writing the
+ * figure is core naming the key.
+ *
+ * So the owning plugin declares the figure per plan, beside the reasoning
+ * that sized it, and core composes it into the plan table. A plan row in
+ * `PLAN_ENTITLEMENTS` still answers every key the platform sells, at the same
+ * number — `/pricing`, the plan comparison, the pricing-table generator and
+ * every quota gate read the composed table and cannot tell the difference.
+ *
+ * ## Compiled, never registered
+ *
+ * The readers include the published pricing tables, which a generator builds
+ * from `PLAN_ENTITLEMENTS` with no plugin loaded, and the customer's plan
+ * comparison, which renders before any plugin surface does. A registry one of
+ * them had not filled would publish a plan without the band — a missing row on
+ * the price list, or a quota gate reading nothing — with nothing red. So a
+ * first-party plugin names a function under `register.planEntitlements` in
+ * `plugins.config.json`; `tools/scripts/generate-plugin-manifests.mjs` loads
+ * `${package}/plan-entitlements`, calls it, validates the answer and compiles
+ * it into `first-party-plugins.generated.ts` as data. There is no runtime
+ * registrar, for the reason `plugin-org-capacity` gives: a registrar nothing
+ * can safely call is worse than none.
+ *
+ * ## What a missing figure means
+ *
+ * A declaration names every plan: the generated rows are typed
+ * `Record<OrgPlan, …>`, so a plan left out does not compile. A key nobody
+ * declares is absent from the table, and each reader answers absence in the
+ * closed direction — a quota reads as nothing included, a feature as off.
+ * `planQuotaOf` below is that reading, and it never answers "unlimited" or
+ * "free" for a key that has no figure.
+ *
+ * ## One key, one owner, and never one of core's
+ *
+ * The generator refuses a key two plugins declare. A key the platform's own
+ * rows already carry is refused by `plan-entitlements.spec.ts` rather than
+ * here, because the generator cannot read core's rows without loading the
+ * module that imports this one; the composition keeps core's figure either
+ * way, so a collision can shadow nothing a customer is charged.
+ */ import { PLUGIN_PLAN_FEATURES_DECLARED, PLUGIN_PLAN_QUOTAS_DECLARED } from "./first-party-plugins.generated.js";
+/** Every declared quota, in catalog order. */ export function pluginPlanQuotas() {
+    return PLUGIN_PLAN_QUOTAS_DECLARED;
+}
+/** Every declared feature, in catalog order. */ export function pluginPlanFeatures() {
+    return PLUGIN_PLAN_FEATURES_DECLARED;
+}
+/** The plugin that declared a quota or feature key, or `null`. */ export function pluginPlanEntitlementOwner(key) {
+    var _ref, _ref1;
+    var _PLUGIN_PLAN_QUOTAS_DECLARED_find, _PLUGIN_PLAN_FEATURES_DECLARED_find;
+    return (_ref = (_ref1 = (_PLUGIN_PLAN_QUOTAS_DECLARED_find = PLUGIN_PLAN_QUOTAS_DECLARED.find((one)=>one.key === key)) == null ? void 0 : _PLUGIN_PLAN_QUOTAS_DECLARED_find.pluginId) != null ? _ref1 : (_PLUGIN_PLAN_FEATURES_DECLARED_find = PLUGIN_PLAN_FEATURES_DECLARED.find((one)=>one.key === key)) == null ? void 0 : _PLUGIN_PLAN_FEATURES_DECLARED_find.pluginId) != null ? _ref : null;
+}
+/** The declared quotas' figures for one plan, keyed by the stored key. */ export function pluginPlanQuotaRow(plan) {
+    return Object.fromEntries(PLUGIN_PLAN_QUOTAS_DECLARED.map((one)=>[
+            one.key,
+            one.byPlan[plan]
+        ]));
+}
+/** The declared features' answers for one plan, keyed by the stored key. */ export function pluginPlanFeatureRow(plan) {
+    return Object.fromEntries(PLUGIN_PLAN_FEATURES_DECLARED.map((one)=>[
+            one.key,
+            one.byPlan[plan]
+        ]));
+}
+/**
+ * A resolved quota read by its key — the reading core uses for a key a plugin
+ * owns, since core compiles without the plugin's type augmentation.
+ *
+ * ⚑ ABSENT IS NOTHING INCLUDED. A key no plugin declares, or a value that is
+ * not a number, reads as `0`: every gate that compares usage against it
+ * refuses, and every meter drawn from it shows full. That is the same
+ * direction `plugin-org-capacity` answers an unknown capacity in. Reading
+ * absence as `UNLIMITED` would be a plan giving away what nobody declared it
+ * sells.
+ */ export function planQuotaOf(entitlements, key) {
+    const value = entitlements[key];
+    return typeof value === 'number' && !Number.isNaN(value) ? value : 0;
+}
+
+//# sourceMappingURL=plugin-plan-entitlements.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-plan-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 * WHAT EACH PLAN INCLUDES OF A PLUGIN'S OWN KEYS (AGL-3080).\n *\n * `plugin-entitlement-keys` gives a plugin the TYPE of a key it owns, by\n * augmentation, so `OrgEntitlements` and `OrgFeatureFlags` carry the key\n * without core naming it. That leaves the VALUE: what Free, Starter and every\n * other plan include of it. A key that only a plugin's type declares still\n * needs a figure in every row of `PLAN_ENTITLEMENTS`, and core writing the\n * figure is core naming the key.\n *\n * So the owning plugin declares the figure per plan, beside the reasoning\n * that sized it, and core composes it into the plan table. A plan row in\n * `PLAN_ENTITLEMENTS` still answers every key the platform sells, at the same\n * number — `/pricing`, the plan comparison, the pricing-table generator and\n * every quota gate read the composed table and cannot tell the difference.\n *\n * ## Compiled, never registered\n *\n * The readers include the published pricing tables, which a generator builds\n * from `PLAN_ENTITLEMENTS` with no plugin loaded, and the customer's plan\n * comparison, which renders before any plugin surface does. A registry one of\n * them had not filled would publish a plan without the band — a missing row on\n * the price list, or a quota gate reading nothing — with nothing red. So a\n * first-party plugin names a function under `register.planEntitlements` in\n * `plugins.config.json`; `tools/scripts/generate-plugin-manifests.mjs` loads\n * `${package}/plan-entitlements`, calls it, validates the answer and compiles\n * it into `first-party-plugins.generated.ts` as data. There is no runtime\n * registrar, for the reason `plugin-org-capacity` gives: a registrar nothing\n * can safely call is worse than none.\n *\n * ## What a missing figure means\n *\n * A declaration names every plan: the generated rows are typed\n * `Record<OrgPlan, …>`, so a plan left out does not compile. A key nobody\n * declares is absent from the table, and each reader answers absence in the\n * closed direction — a quota reads as nothing included, a feature as off.\n * `planQuotaOf` below is that reading, and it never answers \"unlimited\" or\n * \"free\" for a key that has no figure.\n *\n * ## One key, one owner, and never one of core's\n *\n * The generator refuses a key two plugins declare. A key the platform's own\n * rows already carry is refused by `plan-entitlements.spec.ts` rather than\n * here, because the generator cannot read core's rows without loading the\n * module that imports this one; the composition keeps core's figure either\n * way, so a collision can shadow nothing a customer is charged.\n */\n\nimport type { OrgPlan } from '../foundation'\nimport {\n  PLUGIN_PLAN_FEATURES_DECLARED,\n  PLUGIN_PLAN_QUOTAS_DECLARED,\n} from './first-party-plugins.generated'\n\n/** A numeric entitlement a plugin owns: a band, a daily pace, a take rate. */\nexport interface PluginPlanQuotaDeclaration {\n  /** The stored key, exactly as `OrgEntitlements` and an override spell it. */\n  key: string\n  /** What a staff page calls it. */\n  label: string\n  /**\n   * What each plan includes. `Infinity` is `UNLIMITED`; every other value is\n   * a finite, non-negative number.\n   */\n  byPlan: Readonly<Record<OrgPlan, number>>\n  /**\n   * A PRICE rather than a cap — a percentage of a sale — so an uncapped plan\n   * comp must never lift it (`PRICE_ENTITLEMENT_KEYS`).\n   */\n  price?: boolean\n}\n\n/** A boolean gate a plugin owns. */\nexport interface PluginPlanFeatureDeclaration {\n  /** The stored key, exactly as `OrgFeatureFlags` and an override spell it. */\n  key: string\n  label: string\n  byPlan: Readonly<Record<OrgPlan, boolean>>\n}\n\n/** What a plugin's `planEntitlements` function answers. */\nexport interface PluginPlanEntitlementsDeclaration {\n  quotas?: readonly PluginPlanQuotaDeclaration[]\n  features?: readonly PluginPlanFeatureDeclaration[]\n}\n\n/** A quota declaration with the plugin that made it. */\nexport type ResolvedPluginPlanQuota = PluginPlanQuotaDeclaration & {\n  pluginId: string\n}\n\n/** A feature declaration with the plugin that made it. */\nexport type ResolvedPluginPlanFeature = PluginPlanFeatureDeclaration & {\n  pluginId: string\n}\n\n/** Every declared quota, in catalog order. */\nexport function pluginPlanQuotas(): readonly ResolvedPluginPlanQuota[] {\n  return PLUGIN_PLAN_QUOTAS_DECLARED\n}\n\n/** Every declared feature, in catalog order. */\nexport function pluginPlanFeatures(): readonly ResolvedPluginPlanFeature[] {\n  return PLUGIN_PLAN_FEATURES_DECLARED\n}\n\n/** The plugin that declared a quota or feature key, or `null`. */\nexport function pluginPlanEntitlementOwner(key: string): string | null {\n  return (\n    PLUGIN_PLAN_QUOTAS_DECLARED.find((one) => one.key === key)?.pluginId ??\n    PLUGIN_PLAN_FEATURES_DECLARED.find((one) => one.key === key)?.pluginId ??\n    null\n  )\n}\n\n/** The declared quotas' figures for one plan, keyed by the stored key. */\nexport function pluginPlanQuotaRow(plan: OrgPlan): Record<string, number> {\n  return Object.fromEntries(\n    PLUGIN_PLAN_QUOTAS_DECLARED.map((one) => [one.key, one.byPlan[plan]]),\n  )\n}\n\n/** The declared features' answers for one plan, keyed by the stored key. */\nexport function pluginPlanFeatureRow(plan: OrgPlan): Record<string, boolean> {\n  return Object.fromEntries(\n    PLUGIN_PLAN_FEATURES_DECLARED.map((one) => [one.key, one.byPlan[plan]]),\n  )\n}\n\n/**\n * A resolved quota read by its key — the reading core uses for a key a plugin\n * owns, since core compiles without the plugin's type augmentation.\n *\n * ⚑ ABSENT IS NOTHING INCLUDED. A key no plugin declares, or a value that is\n * not a number, reads as `0`: every gate that compares usage against it\n * refuses, and every meter drawn from it shows full. That is the same\n * direction `plugin-org-capacity` answers an unknown capacity in. Reading\n * absence as `UNLIMITED` would be a plan giving away what nobody declared it\n * sells.\n */\nexport function planQuotaOf(entitlements: object, key: string): number {\n  const value = (entitlements as Record<string, unknown>)[key]\n  return typeof value === 'number' && !Number.isNaN(value) ? value : 0\n}\n"],"names":["PLUGIN_PLAN_FEATURES_DECLARED","PLUGIN_PLAN_QUOTAS_DECLARED","pluginPlanQuotas","pluginPlanFeatures","pluginPlanEntitlementOwner","key","find","one","pluginId","pluginPlanQuotaRow","plan","Object","fromEntries","map","byPlan","pluginPlanFeatureRow","planQuotaOf","entitlements","value","Number","isNaN"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GAGD,SACEA,6BAA6B,EAC7BC,2BAA2B,QACtB,qCAAiC;AA4CxC,4CAA4C,GAC5C,OAAO,SAASC;IACd,OAAOD;AACT;AAEA,8CAA8C,GAC9C,OAAO,SAASE;IACd,OAAOH;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASI,2BAA2BC,GAAW;QAElDJ;QAAAA,mCACAD;IAFF,QACEC,iBAAAA,oCAAAA,4BAA4BK,IAAI,CAAC,CAACC,MAAQA,IAAIF,GAAG,KAAKA,yBAAtDJ,kCAA4DO,QAAQ,qBACpER,sCAAAA,8BAA8BM,IAAI,CAAC,CAACC,MAAQA,IAAIF,GAAG,KAAKA,yBAAxDL,oCAA8DQ,QAAQ,YADtEP,OAEA;AAEJ;AAEA,wEAAwE,GACxE,OAAO,SAASQ,mBAAmBC,IAAa;IAC9C,OAAOC,OAAOC,WAAW,CACvBX,4BAA4BY,GAAG,CAAC,CAACN,MAAQ;YAACA,IAAIF,GAAG;YAAEE,IAAIO,MAAM,CAACJ,KAAK;SAAC;AAExE;AAEA,0EAA0E,GAC1E,OAAO,SAASK,qBAAqBL,IAAa;IAChD,OAAOC,OAAOC,WAAW,CACvBZ,8BAA8Ba,GAAG,CAAC,CAACN,MAAQ;YAACA,IAAIF,GAAG;YAAEE,IAAIO,MAAM,CAACJ,KAAK;SAAC;AAE1E;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASM,YAAYC,YAAoB,EAAEZ,GAAW;IAC3D,MAAMa,QAAQ,AAACD,YAAwC,CAACZ,IAAI;IAC5D,OAAO,OAAOa,UAAU,YAAY,CAACC,OAAOC,KAAK,CAACF,SAASA,QAAQ;AACrE"}

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-index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 records, listed and read for ANOTHER plugin (AGL-3080).
+ *
+ * A plugin that works over records it does not own — an AI job enriching a
+ * site's products, a composer binding the products an email names — used to
+ * read the owner's Firestore collection itself: the path, the field names,
+ * what "deleted" looks like. That is a plugin's storage reached around the
+ * plugin, invisible to `check:lib-boundaries` because a collection name is
+ * not an import, and it breaks the day the owner changes a field.
+ *
+ * So the owner publishes an INDEX for each record kind it keeps: `list` names
+ * the live records of a scope, `get` reads one — each as an id, a name and the
+ * FACTS the owner chooses to share, in a shape its registration documents.
+ * The reader never learns where the records are stored or what a deleted one
+ * looks like; the owner answers only live records.
+ *
+ * Its siblings: `plugin-record-cards` (how one record LOOKS, for a campaign
+ * sender) and `plugin-record-facts` (what a record SAYS, for a summary);
+ * `plugin-resource-drafts` is the WRITE side. This is the side that finds and
+ * reads records to work on.
+ *
+ * ## Not registered is an answer
+ *
+ * No index for a kind means no plugin keeps it in this process — 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. Registered from the
+ * owner's server declarations, so every server process that boots the
+ * declarations has it.
+ *
+ * ## One index per kind
+ *
+ * A second plugin registering an index for a kind another plugin already
+ * keeps is refused, naming both, and the incumbent keeps serving.
+ */
+/** One record, as its owner shares it. */
+export interface PluginIndexedRecord {
+    id: string;
+    /** What a person calls it. Never empty: the owner leaves an unnamed record out. */
+    name: string;
+    /** What else the owner shares, in the shape its registration documents. */
+    facts: Readonly<Record<string, unknown>>;
+}
+/** Which records a reader asks about. */
+export interface PluginRecordIndexScope {
+    /** The organization the records belong to, where the kind is org-scoped. */
+    orgId?: string | null;
+    /** The site the records belong to, where the kind is site-scoped. */
+    hostId?: string | null;
+}
+export interface PluginRecordIndex {
+    /**
+     * The live records of the scope, at most `limit`, in the owner's order.
+     * `truncated` says the scope holds more than were answered.
+     */
+    list(request: PluginRecordIndexScope & {
+        limit: number;
+    }): Promise<{
+        records: PluginIndexedRecord[];
+        truncated: boolean;
+    }>;
+    /** One live record, or `null` — gone, deleted, or not the scope's. */
+    get(request: PluginRecordIndexScope & {
+        id: string;
+    }): Promise<PluginIndexedRecord | null>;
+}
+export declare const PLUGIN_RECORD_INDEXES: import("./plugin-services").PluginServiceContract<PluginRecordIndex>;
+/**
+ * Publishes the index 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 keeps throws naming both.
+ */
+export declare function registerPluginRecordIndex(kind: string, index: PluginRecordIndex, options?: {
+    pluginId?: string;
+}): void;
+/** The index for a kind, with the plugin that keeps it, or `null` when none does here. */
+export declare function pluginRecordIndex(kind: string): {
+    pluginId: string;
+    index: PluginRecordIndex;
+} | null;