@aglyn/aglyn 1.0.0-beta.161 → 1.0.0-beta.163

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

@@ -0,0 +1,102 @@
+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.
+ */ /**
+ * A plugin's share of taking a CONTAINER away (AGL-3254).
+ *
+ * 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
+ * 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
+ * does not know — registers a detacher here, and the removal runs every
+ * detacher with the container's id, the membership field it is held in,
+ * the site and the org, so the plugin can clear its own records.
+ *
+ * Detachers run BEFORE the container is deleted, for the reason the owner's
+ * own passes do: a run that stops between them leaves records already out
+ * of the container, which every surface draws correctly, while deleting
+ * first would leave a plugin's record naming an id nothing can resolve. A
+ * detacher that reports `remaining` holds the deletion, exactly as the
+ * owner's own pass does when the container is on more records than one
+ * request can clear.
+ *
+ * Detachers run in registration order and are ISOLATED: a throw is logged
+ * against its plugin, recorded as `null`, and does not stop the next one.
+ * The owner reads a `null` as "this plugin's records may still name the
+ * container" and refuses to remove it, which is the direction a failure
+ * here has to fall.
+ *
+ * Registered from a plugin's declarations — `consoleServerDeclarations`,
+ * since a container is removed from the console — so the detacher is in
+ * place in a process that never loaded the plugin's API surface. The core
+ * never imports a plugin; this is how a removal one plugin performs reaches
+ * another plugin's records.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const registrations = [];
+/**
+ * Registers a plugin's membership detacher. Owner = the loader's marker
+ * inside a register fn, else `options.pluginId`; a detacher with neither
+ * throws. One detacher per plugin: registering again replaces the plugin's
+ * earlier detacher in place, so a module evaluated twice does not run twice.
+ */ export function registerPluginMembershipDetacher(detacher, options) {
+    var _ref, _getRegisteringPluginId;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error('a plugin membership detacher was registered with no owner: pass ' + '{ pluginId } when registering outside a plugin register fn');
+    }
+    const index = registrations.findIndex((entry)=>entry.pluginId === pluginId);
+    if (index >= 0) registrations[index] = {
+        pluginId,
+        detacher
+    };
+    else registrations.push({
+        pluginId,
+        detacher
+    });
+}
+/**
+ * Runs every detacher, in registration order, and answers each plugin's
+ * report by plugin id: the detacher's own report, or `null` for one that
+ * threw. Never throws.
+ */ export async function runPluginMembershipDetachers(request) {
+    const reports = {};
+    for (const { pluginId, detacher } of [
+        ...registrations
+    ]){
+        try {
+            var _ref;
+            const report = await detacher(_extends({}, request));
+            reports[pluginId] = {
+                detached: Math.max(0, Math.floor(Number((_ref = report == null ? void 0 : report.detached) != null ? _ref : 0)) || 0),
+                remaining: (report == null ? void 0 : report.remaining) === true
+            };
+        } catch (error) {
+            reports[pluginId] = null;
+            console.error(`[plugins] ${pluginId} failed to detach ${request.field} ${request.id} on host ${request.hostId}`, error);
+        }
+    }
+    return reports;
+}
+/** The plugins with a detacher in place, in registration order. Only for specs and the guards. */ export function listPluginMembershipDetachers() {
+    return registrations.map((entry)=>entry.pluginId);
+}
+/** Test seam: forget every detacher. */ export function resetPluginMembershipDetachersForTests() {
+    registrations.length = 0;
+}
+
+//# sourceMappingURL=plugin-membership-detach.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,85 @@
+/**
+ * @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 { EmailState } from '../app-utils/email-state';
+/**
+ * The verdict on an address, written onto the records that carry it
+ * (AGL-3245).
+ *
+ * The senders keep their lists — the platform's suppression list, a site's
+ * suppressions, an organization's do-not-contact list — and those are what
+ * a send consults. The record a person reads is the record system's: a
+ * lead, a contact, whatever the plugin that keeps the workspace's records
+ * calls them. A sender must not write that plugin's documents itself, nor
+ * import it; so the record system registers a WRITER here, and a sender
+ * that filed a verdict on a list says so through it.
+ *
+ * The writer finds every record the address is — the plugin knows its own
+ * storage and its own index — and stamps `emailState` on each, keeping the
+ * stronger verdict (`nextEmailState`). A single-implementation contract: a
+ * workspace keeps one record system.
+ *
+ * ## The caller proves who is asking
+ *
+ * Like the timeline seam, the registry authenticates nobody. The caller
+ * decides, in its own terms and before it asks, that the verdict is the
+ * workspace's to write: an address it sent to, a list it wrote.
+ */
+export interface PluginRecordEmailStateRequest {
+    /** The organization whose records are stamped. */
+    orgId?: string;
+    /**
+     * Or the site the send left from, when the caller knows only that — a
+     * campaign webhook, an unsubscribe link. The writer reads the
+     * organization off it.
+     */
+    hostId?: string;
+    email: string;
+    state: EmailState;
+    /** Write the state whatever the record holds — a release. */
+    force?: boolean;
+}
+export interface PluginRecordEmailStateReport {
+    /** Records whose state moved. */
+    records: number;
+}
+export interface PluginRecordEmailStateWriter {
+    /** Never throws: a list is the control, the stamp is what a person reads. */
+    stamp(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport>;
+}
+export declare const PLUGIN_RECORD_EMAIL_STATE: import("./plugin-services").PluginServiceContract<PluginRecordEmailStateWriter>;
+/**
+ * Registers the workspace's record email-state writer. The owner is the
+ * loader's marker when a register fn is running, else `options.pluginId`;
+ * with neither the registration throws, and a second plugin's writer is
+ * refused naming both — the incumbent keeps serving.
+ */
+export declare function registerPluginRecordEmailStateWriter(writer: PluginRecordEmailStateWriter, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginRecordEmailStateWriter {
+    /** The plugin that keeps the records. */
+    pluginId: string;
+    writer: PluginRecordEmailStateWriter;
+}
+/** The writer, with its owner, or `null` when no plugin keeps records here. */
+export declare function pluginRecordEmailStateWriter(): ResolvedPluginRecordEmailStateWriter | null;
+/**
+ * Stamps the verdict through whichever plugin keeps the records, or answers
+ * `null` when none does. Never throws: every caller is a sender for whom
+ * the stamp is a courtesy beside the list it already wrote.
+ */
+export declare function stampRecordEmailState(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport | null>;

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

@@ -0,0 +1,53 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_RECORD_EMAIL_STATE = definePluginServiceContract('core.record-email-state', {
+    multiple: false
+});
+/**
+ * Registers the workspace's record email-state writer. The owner is the
+ * loader's marker when a register fn is running, else `options.pluginId`;
+ * with neither the registration throws, and a second plugin's writer is
+ * refused naming both — the incumbent keeps serving.
+ */ export function registerPluginRecordEmailStateWriter(writer, options) {
+    registerPluginService(PLUGIN_RECORD_EMAIL_STATE, writer, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The writer, with its owner, or `null` when no plugin keeps records here. */ export function pluginRecordEmailStateWriter() {
+    const entry = resolvePluginServices(PLUGIN_RECORD_EMAIL_STATE)[0];
+    return entry ? {
+        pluginId: entry.pluginId,
+        writer: entry.impl
+    } : null;
+}
+/**
+ * Stamps the verdict through whichever plugin keeps the records, or answers
+ * `null` when none does. Never throws: every caller is a sender for whom
+ * the stamp is a courtesy beside the list it already wrote.
+ */ export async function stampRecordEmailState(request) {
+    const resolved = pluginRecordEmailStateWriter();
+    if (!resolved) return null;
+    try {
+        return await resolved.writer.stamp(request);
+    } catch (error) {
+        console.error('[record-email-state] the record system could not stamp the address', error);
+        return null;
+    }
+}
+
+//# sourceMappingURL=plugin-record-email-state.js.map

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

@@ -0,0 +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\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;AAmD1B,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"}

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

@@ -131,9 +131,31 @@ export type PluginRecordWrite = {
     /** Customer-safe: a caller may show or log it as it stands. */
     error: string;
 };
+/**
+ * What became of an email a plugin filed (AGL-3245): the receiving server
+ * bounced it, or the recipient reported it. Addressed by the `Message-ID`
+ * the send was filed under, so the verdict lands on the send's own entry
+ * and the record reads Sent, then Bounced.
+ */
+export interface PluginRecordDeliveryRequest {
+    orgId: string;
+    /** The `Message-ID` header of the send, angle brackets included. */
+    messageId: string;
+    state: 'bounced' | 'complained';
+    /** When it happened, epoch ms. */
+    atMs: number;
+    /** What the server said, scrubbed of the address; the owner bounds it. */
+    detail?: string | null;
+}
 export interface PluginRecordTimelineWriter {
     logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>;
     createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>;
+    /**
+     * Marks a filed email bounced or reported (AGL-3245). Optional: a record
+     * system that keeps no delivery state answers nothing, and the caller's
+     * entry stands as filed.
+     */
+    recordEmailDelivery?(request: PluginRecordDeliveryRequest): Promise<PluginRecordWrite>;
 }
 export declare const PLUGIN_RECORD_TIMELINE: import("./plugin-services").PluginServiceContract<PluginRecordTimelineWriter>;
 /**

package/src/lib/plugin-manager/plugin-record-timeline.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-timeline.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * An entry one plugin files on a record another plugin keeps (AGL-2981).\n *\n * A person, a company and a deal are records of the workspace's record\n * system, and what happened with them — an email sent, a reply received, a\n * call to make — belongs on their timeline, whichever plugin it happened in.\n * A plugin that sends mail or books a meeting must not write the record\n * system's documents itself: it would restate the owner's rules — where an\n * entry lives, who may see it, how a copy of the same email is told apart,\n * how many entries a record may carry — and drift from them the day the\n * owner changes one. Nor may it import the owner, which the package map\n * forbids.\n *\n * So the record system registers a WRITER here, from its server surfaces,\n * and a caller asks for it. Every rule stays the owner's:\n *\n *  - the entry is stamped with the scope a record made on the site would\n *    carry, so it is visible to exactly who sees the record;\n *  - an EMAIL is filed once per `Message-ID`, under the id the owner files a\n *    copy of the same message by through any other door — a copy the rep\n *    forwarded to a capture address is the same entry, not a second one;\n *  - any other entry, and every task, is filed once per the caller's own\n *    `dedupeKey`, so a caller that runs again finds what it wrote rather\n *    than writing it twice;\n *  - a record whose log is full, or a workspace whose plan carries no record\n *    system, is refused — answered, never thrown.\n *\n * A single-implementation contract: a workspace keeps one record system.\n *\n * ## The caller proves who is asking\n *\n * Like `plugin-resource-drafts`, the registry authenticates nobody. The\n * caller decides, in its own terms and before it asks, that the entry is\n * the workspace's to write — that the record is one it acted on, for the\n * member it acted for.\n */\n\n/** The record an entry is filed on: any of the four, as the owner links them. */\nexport interface PluginRecordLink {\n  contactId?: string\n  companyId?: string\n  dealId?: string\n  /**\n   * A lead not yet converted (AGL-3234) — the record system's own id for\n   * it, addressed under `hostId`. A sequence's emails and tasks land on the\n   * lead's page while the person is one, and follow the lead to the contact\n   * it becomes.\n   */\n  leadId?: string\n}\n\n/** Where an entry is filed, and by which plugin. */\nexport interface PluginRecordEntryContext {\n  orgId: string\n  /** The site whose scope the entry carries: as if a member made it there. */\n  hostId: string\n  link: PluginRecordLink\n  /** The plugin filing it, recorded on the entry. */\n  sourcePluginId: string\n}\n\n/** What an activity is, in the record system's own words. */\nexport type PluginRecordActivityKind = 'email' | 'call' | 'meeting' | 'note' | 'other'\n\n/** The message an `email` activity is about. */\nexport interface PluginRecordEmail {\n  /** `outbound` for one the workspace wrote; `inbound` for one written to it. */\n  direction: 'outbound' | 'inbound'\n  subject: string\n  /** The address on the message's From. */\n  from: string\n  /** The address it was written to, when one is worth showing. */\n  to: string | null\n  /** The `Message-ID` header, angle brackets included: what files it once. */\n  messageId: string\n  /** The `Message-ID` it answered, when it answered one. */\n  inReplyTo?: string | null\n}\n\nexport interface PluginRecordActivityRequest extends PluginRecordEntryContext {\n  kind: PluginRecordActivityKind\n  /** When it happened, epoch ms. */\n  atMs: number\n  /** Plain text: an email's excerpt, a note's words. The owner bounds it. */\n  body: string\n  /** The member it is by, or `''` for none. */\n  byUid: string\n  byName?: string | null\n  /** Required for an `email`, and read only for one. */\n  email?: PluginRecordEmail | null\n  /** Required for every kind but `email`: the caller's id for this entry. */\n  dedupeKey?: string | null\n}\n\n/** What a task is, in the record system's own words. */\nexport type PluginRecordTaskKind = 'call' | 'email' | 'meeting' | 'todo'\n\nexport interface PluginRecordTaskRequest extends PluginRecordEntryContext {\n  /** The caller's id for this task: the same key never makes a second task. */\n  dedupeKey: string\n  title: string\n  notes?: string | null\n  kind: PluginRecordTaskKind\n  /** When it is due, epoch ms. */\n  dueAtMs: number\n  /** The member it is for, or `''` for nobody. */\n  assigneeUid: string\n  /** The member who made it happen, or `''` when nobody did. */\n  createdByUid: string\n}\n\n/**\n * The owner's answer. `created: false` is the entry a previous write — or a\n * copy through another door — already filed, under the same `id`.\n */\nexport type PluginRecordWrite =\n  | { ok: true; id: string; created: boolean }\n  | {\n      ok: false\n      status: 400 | 403 | 404 | 409\n      /** Customer-safe: a caller may show or log it as it stands. */\n      error: string\n    }\n\nexport interface PluginRecordTimelineWriter {\n  logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>\n  createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>\n}\n\nexport const PLUGIN_RECORD_TIMELINE = definePluginServiceContract<PluginRecordTimelineWriter>(\n  'core.record-timeline',\n  { multiple: false },\n)\n\n/**\n * Registers the workspace's record timeline writer. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`; with neither\n * the registration throws, and a second plugin's writer is refused naming\n * both — the incumbent keeps serving.\n */\nexport function registerPluginRecordTimelineWriter(\n  writer: PluginRecordTimelineWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_TIMELINE, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginRecordTimelineWriter {\n  /** The plugin that keeps the records. */\n  pluginId: string\n  writer: PluginRecordTimelineWriter\n}\n\n/** The writer, with its owner, or `null` when no plugin keeps records here. */\nexport function pluginRecordTimelineWriter(): ResolvedPluginRecordTimelineWriter | null {\n  const entry = resolvePluginServices(PLUGIN_RECORD_TIMELINE)[0]\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_TIMELINE","multiple","registerPluginRecordTimelineWriter","writer","options","pluginId","pluginRecordTimelineWriter","entry","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAmI1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,mCACdC,MAAkC,EAClCC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,QAAQ,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,uBAAuB,CAAC,EAAE;IAC9D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,QAAQI,MAAMC,IAAI;IAAC,IAAI;AACpE"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-timeline.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * An entry one plugin files on a record another plugin keeps (AGL-2981).\n *\n * A person, a company and a deal are records of the workspace's record\n * system, and what happened with them — an email sent, a reply received, a\n * call to make — belongs on their timeline, whichever plugin it happened in.\n * A plugin that sends mail or books a meeting must not write the record\n * system's documents itself: it would restate the owner's rules — where an\n * entry lives, who may see it, how a copy of the same email is told apart,\n * how many entries a record may carry — and drift from them the day the\n * owner changes one. Nor may it import the owner, which the package map\n * forbids.\n *\n * So the record system registers a WRITER here, from its server surfaces,\n * and a caller asks for it. Every rule stays the owner's:\n *\n *  - the entry is stamped with the scope a record made on the site would\n *    carry, so it is visible to exactly who sees the record;\n *  - an EMAIL is filed once per `Message-ID`, under the id the owner files a\n *    copy of the same message by through any other door — a copy the rep\n *    forwarded to a capture address is the same entry, not a second one;\n *  - any other entry, and every task, is filed once per the caller's own\n *    `dedupeKey`, so a caller that runs again finds what it wrote rather\n *    than writing it twice;\n *  - a record whose log is full, or a workspace whose plan carries no record\n *    system, is refused — answered, never thrown.\n *\n * A single-implementation contract: a workspace keeps one record system.\n *\n * ## The caller proves who is asking\n *\n * Like `plugin-resource-drafts`, the registry authenticates nobody. The\n * caller decides, in its own terms and before it asks, that the entry is\n * the workspace's to write — that the record is one it acted on, for the\n * member it acted for.\n */\n\n/** The record an entry is filed on: any of the four, as the owner links them. */\nexport interface PluginRecordLink {\n  contactId?: string\n  companyId?: string\n  dealId?: string\n  /**\n   * A lead not yet converted (AGL-3234) — the record system's own id for\n   * it, addressed under `hostId`. A sequence's emails and tasks land on the\n   * lead's page while the person is one, and follow the lead to the contact\n   * it becomes.\n   */\n  leadId?: string\n}\n\n/** Where an entry is filed, and by which plugin. */\nexport interface PluginRecordEntryContext {\n  orgId: string\n  /** The site whose scope the entry carries: as if a member made it there. */\n  hostId: string\n  link: PluginRecordLink\n  /** The plugin filing it, recorded on the entry. */\n  sourcePluginId: string\n}\n\n/** What an activity is, in the record system's own words. */\nexport type PluginRecordActivityKind = 'email' | 'call' | 'meeting' | 'note' | 'other'\n\n/** The message an `email` activity is about. */\nexport interface PluginRecordEmail {\n  /** `outbound` for one the workspace wrote; `inbound` for one written to it. */\n  direction: 'outbound' | 'inbound'\n  subject: string\n  /** The address on the message's From. */\n  from: string\n  /** The address it was written to, when one is worth showing. */\n  to: string | null\n  /** The `Message-ID` header, angle brackets included: what files it once. */\n  messageId: string\n  /** The `Message-ID` it answered, when it answered one. */\n  inReplyTo?: string | null\n}\n\nexport interface PluginRecordActivityRequest extends PluginRecordEntryContext {\n  kind: PluginRecordActivityKind\n  /** When it happened, epoch ms. */\n  atMs: number\n  /** Plain text: an email's excerpt, a note's words. The owner bounds it. */\n  body: string\n  /** The member it is by, or `''` for none. */\n  byUid: string\n  byName?: string | null\n  /** Required for an `email`, and read only for one. */\n  email?: PluginRecordEmail | null\n  /** Required for every kind but `email`: the caller's id for this entry. */\n  dedupeKey?: string | null\n}\n\n/** What a task is, in the record system's own words. */\nexport type PluginRecordTaskKind = 'call' | 'email' | 'meeting' | 'todo'\n\nexport interface PluginRecordTaskRequest extends PluginRecordEntryContext {\n  /** The caller's id for this task: the same key never makes a second task. */\n  dedupeKey: string\n  title: string\n  notes?: string | null\n  kind: PluginRecordTaskKind\n  /** When it is due, epoch ms. */\n  dueAtMs: number\n  /** The member it is for, or `''` for nobody. */\n  assigneeUid: string\n  /** The member who made it happen, or `''` when nobody did. */\n  createdByUid: string\n}\n\n/**\n * The owner's answer. `created: false` is the entry a previous write — or a\n * copy through another door — already filed, under the same `id`.\n */\nexport type PluginRecordWrite =\n  | { ok: true; id: string; created: boolean }\n  | {\n      ok: false\n      status: 400 | 403 | 404 | 409\n      /** Customer-safe: a caller may show or log it as it stands. */\n      error: string\n    }\n\n/**\n * What became of an email a plugin filed (AGL-3245): the receiving server\n * bounced it, or the recipient reported it. Addressed by the `Message-ID`\n * the send was filed under, so the verdict lands on the send's own entry\n * and the record reads Sent, then Bounced.\n */\nexport interface PluginRecordDeliveryRequest {\n  orgId: string\n  /** The `Message-ID` header of the send, angle brackets included. */\n  messageId: string\n  state: 'bounced' | 'complained'\n  /** When it happened, epoch ms. */\n  atMs: number\n  /** What the server said, scrubbed of the address; the owner bounds it. */\n  detail?: string | null\n}\n\nexport interface PluginRecordTimelineWriter {\n  logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>\n  createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>\n  /**\n   * Marks a filed email bounced or reported (AGL-3245). Optional: a record\n   * system that keeps no delivery state answers nothing, and the caller's\n   * entry stands as filed.\n   */\n  recordEmailDelivery?(request: PluginRecordDeliveryRequest): Promise<PluginRecordWrite>\n}\n\nexport const PLUGIN_RECORD_TIMELINE = definePluginServiceContract<PluginRecordTimelineWriter>(\n  'core.record-timeline',\n  { multiple: false },\n)\n\n/**\n * Registers the workspace's record timeline writer. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`; with neither\n * the registration throws, and a second plugin's writer is refused naming\n * both — the incumbent keeps serving.\n */\nexport function registerPluginRecordTimelineWriter(\n  writer: PluginRecordTimelineWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_TIMELINE, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginRecordTimelineWriter {\n  /** The plugin that keeps the records. */\n  pluginId: string\n  writer: PluginRecordTimelineWriter\n}\n\n/** The writer, with its owner, or `null` when no plugin keeps records here. */\nexport function pluginRecordTimelineWriter(): ResolvedPluginRecordTimelineWriter | null {\n  const entry = resolvePluginServices(PLUGIN_RECORD_TIMELINE)[0]\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_TIMELINE","multiple","registerPluginRecordTimelineWriter","writer","options","pluginId","pluginRecordTimelineWriter","entry","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA0J1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,mCACdC,MAAkC,EAClCC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,QAAQ,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,uBAAuB,CAAC,EAAE;IAC9D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,QAAQI,MAAMC,IAAI;IAAC,IAAI;AACpE"}