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

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

@@ -181,9 +181,61 @@ export interface PluginRecordDeliveryRequest {
     /** What the server said, scrubbed of the address; the owner bounds it. */
     detail?: string | null;
 }
+/**
+ * An email a plugin is about to send to a person (AGL-3080), offered to the
+ * record system BEFORE it goes so the entry it files can follow the
+ * message's delivery: the record system answers with the provider tags the
+ * message has to carry for the delivery webhook to find the entry, and with
+ * how to file it once the provider has accepted it.
+ *
+ * Only a message addressed to the person `link` names — the person an
+ * automation's event is about — earns an entry: an alert routed to the
+ * merchant's own inbox would put that inbox on a customer's history.
+ */
+export interface PluginRecordEmailPrepareRequest {
+    orgId: string;
+    /** The site the message goes out as: the entry carries its scope. */
+    hostId: string;
+    /** The address the message is sent to, raw. */
+    to: string;
+    /** The person the sender means: by id where it holds one, else by address. */
+    link: Pick<PluginRecordLink, 'contactId' | 'email'>;
+    /**
+     * The organization's billing document, when the caller already read it —
+     * the record system's plan gate and scope read it; absent, the owner reads
+     * it itself.
+     */
+    org?: unknown;
+}
+/** The message as it was sent, for the entry the record system files. */
+export interface PluginRecordEmailSent {
+    subject: string;
+    body: string;
+    to: string;
+    /** When it was accepted, epoch ms; now when absent. */
+    atMs?: number;
+    /** The sender's own id for what sent it — an automation's id. */
+    sourceRef: string;
+}
+/** What the record system answered a prepared email with. */
+export interface PluginRecordPreparedEmail {
+    /** Provider tags the message must carry for its delivery to reach the entry. */
+    tags: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+    /** Files the entry, once the provider accepted the message. Never throws. */
+    file(sent: PluginRecordEmailSent): Promise<void>;
+}
 export interface PluginRecordTimelineWriter {
     logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>;
     createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>;
+    /**
+     * Prepares the entry an email to a person will earn (AGL-3080). Optional:
+     * a record system that files no sent mail answers nothing. `null` for a
+     * message that earns no entry. Never throws.
+     */
+    prepareEmail?(request: PluginRecordEmailPrepareRequest): Promise<PluginRecordPreparedEmail | null>;
     /**
      * Marks a filed email bounced or reported (AGL-3245). Optional: a record
      * system that keeps no delivery state answers nothing, and the caller's
@@ -208,3 +260,11 @@ export interface ResolvedPluginRecordTimelineWriter {
 }
 /** The writer, with its owner, or `null` when no plugin keeps records here. */
 export declare function pluginRecordTimelineWriter(): ResolvedPluginRecordTimelineWriter | null;
+/**
+ * Asks whichever plugin keeps records to prepare the entry an email to a
+ * person will earn, or answers `null` when none does, the one that does
+ * files no sent mail, or this message earns no entry. Never throws: the
+ * entry is bookkeeping beside a send, and a lookup that failed must not
+ * become a message that never left.
+ */
+export declare function preparePluginRecordEmail(request: PluginRecordEmailPrepareRequest): Promise<PluginRecordPreparedEmail | null>;

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

@@ -35,5 +35,21 @@ export const PLUGIN_RECORD_TIMELINE = definePluginServiceContract('core.record-t
         writer: entry.impl
     } : null;
 }
+/**
+ * Asks whichever plugin keeps records to prepare the entry an email to a
+ * person will earn, or answers `null` when none does, the one that does
+ * files no sent mail, or this message earns no entry. Never throws: the
+ * entry is bookkeeping beside a send, and a lookup that failed must not
+ * become a message that never left.
+ */ export async function preparePluginRecordEmail(request) {
+    const resolved = pluginRecordTimelineWriter();
+    if (!(resolved == null ? void 0 : resolved.writer.prepareEmail)) return null;
+    try {
+        return await resolved.writer.prepareEmail(request);
+    } catch (error) {
+        console.error('[record-timeline] the record system could not prepare an email entry', error);
+        return null;
+    }
+}
 
 //# sourceMappingURL=plugin-record-timeline.js.map

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 and the company they work for are records of the workspace's\n * record system, and what happened with them — an email sent, a reply\n * received, a call to make — belongs on their timeline, whichever plugin it\n * 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 *  - a caller that knows a record only as the owner handed it over — a kind\n *    and an id carried on a link — or knows only the person's address is\n *    answered with the record the owner finds for it, on that site, or\n *    refused with a 404 when it finds none.\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/**\n * The record an entry is filed on: the person (a contact, or a lead not yet\n * one) and the company they work for, as the owner links them — or, from a\n * caller that holds no id of the owner's, how to find the record.\n *\n * The ids win where given, and are filed on as named. Otherwise `record`,\n * then `email`: the owner looks the record up as the entry's site sees it,\n * links whatever it groups that record under itself, and refuses the entry\n * with a 404 when it finds nothing.\n */\nexport interface PluginRecordLink {\n  contactId?: string\n  companyId?: 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   * A record the owner handed the caller, by its kind and id in the owner's\n   * own words, and carried back unread (AGL-2660): the record a booking link\n   * was dropped from, through the zone the owner drew it in. A kind the\n   * owner does not keep, or a record the site cannot see, is passed over for\n   * `email` rather than refused.\n   */\n  record?: { kind: string; id: string } | null\n  /**\n   * The person at this address, as the entry's site knows them: what the\n   * entry lands on when nothing above names a record the owner finds — a\n   * booking taken off the widget cold.\n   */\n  email?: string | null\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  /**\n   * The member it is for, `''` for nobody, or `null` for whoever holds the\n   * record it lands on — the caller that found the record by `record` or\n   * `email` does not know who that is.\n   */\n  assigneeUid: string | null\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;AAyL1B,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 and the company they work for are records of the workspace's\n * record system, and what happened with them — an email sent, a reply\n * received, a call to make — belongs on their timeline, whichever plugin it\n * 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 *  - a caller that knows a record only as the owner handed it over — a kind\n *    and an id carried on a link — or knows only the person's address is\n *    answered with the record the owner finds for it, on that site, or\n *    refused with a 404 when it finds none.\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/**\n * The record an entry is filed on: the person (a contact, or a lead not yet\n * one) and the company they work for, as the owner links them — or, from a\n * caller that holds no id of the owner's, how to find the record.\n *\n * The ids win where given, and are filed on as named. Otherwise `record`,\n * then `email`: the owner looks the record up as the entry's site sees it,\n * links whatever it groups that record under itself, and refuses the entry\n * with a 404 when it finds nothing.\n */\nexport interface PluginRecordLink {\n  contactId?: string\n  companyId?: 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   * A record the owner handed the caller, by its kind and id in the owner's\n   * own words, and carried back unread (AGL-2660): the record a booking link\n   * was dropped from, through the zone the owner drew it in. A kind the\n   * owner does not keep, or a record the site cannot see, is passed over for\n   * `email` rather than refused.\n   */\n  record?: { kind: string; id: string } | null\n  /**\n   * The person at this address, as the entry's site knows them: what the\n   * entry lands on when nothing above names a record the owner finds — a\n   * booking taken off the widget cold.\n   */\n  email?: string | null\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  /**\n   * The member it is for, `''` for nobody, or `null` for whoever holds the\n   * record it lands on — the caller that found the record by `record` or\n   * `email` does not know who that is.\n   */\n  assigneeUid: string | null\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\n/**\n * An email a plugin is about to send to a person (AGL-3080), offered to the\n * record system BEFORE it goes so the entry it files can follow the\n * message's delivery: the record system answers with the provider tags the\n * message has to carry for the delivery webhook to find the entry, and with\n * how to file it once the provider has accepted it.\n *\n * Only a message addressed to the person `link` names — the person an\n * automation's event is about — earns an entry: an alert routed to the\n * merchant's own inbox would put that inbox on a customer's history.\n */\nexport interface PluginRecordEmailPrepareRequest {\n  orgId: string\n  /** The site the message goes out as: the entry carries its scope. */\n  hostId: string\n  /** The address the message is sent to, raw. */\n  to: string\n  /** The person the sender means: by id where it holds one, else by address. */\n  link: Pick<PluginRecordLink, 'contactId' | 'email'>\n  /**\n   * The organization's billing document, when the caller already read it —\n   * the record system's plan gate and scope read it; absent, the owner reads\n   * it itself.\n   */\n  org?: unknown\n}\n\n/** The message as it was sent, for the entry the record system files. */\nexport interface PluginRecordEmailSent {\n  subject: string\n  body: string\n  to: string\n  /** When it was accepted, epoch ms; now when absent. */\n  atMs?: number\n  /** The sender's own id for what sent it — an automation's id. */\n  sourceRef: string\n}\n\n/** What the record system answered a prepared email with. */\nexport interface PluginRecordPreparedEmail {\n  /** Provider tags the message must carry for its delivery to reach the entry. */\n  tags: ReadonlyArray<{ name: string; value: string }>\n  /** Files the entry, once the provider accepted the message. Never throws. */\n  file(sent: PluginRecordEmailSent): Promise<void>\n}\n\nexport interface PluginRecordTimelineWriter {\n  logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>\n  createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>\n  /**\n   * Prepares the entry an email to a person will earn (AGL-3080). Optional:\n   * a record system that files no sent mail answers nothing. `null` for a\n   * message that earns no entry. Never throws.\n   */\n  prepareEmail?(request: PluginRecordEmailPrepareRequest): Promise<PluginRecordPreparedEmail | null>\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\n/**\n * Asks whichever plugin keeps records to prepare the entry an email to a\n * person will earn, or answers `null` when none does, the one that does\n * files no sent mail, or this message earns no entry. Never throws: the\n * entry is bookkeeping beside a send, and a lookup that failed must not\n * become a message that never left.\n */\nexport async function preparePluginRecordEmail(\n  request: PluginRecordEmailPrepareRequest,\n): Promise<PluginRecordPreparedEmail | null> {\n  const resolved = pluginRecordTimelineWriter()\n  if (!resolved?.writer.prepareEmail) return null\n  try {\n    return await resolved.writer.prepareEmail(request)\n  } catch (error) {\n    console.error('[record-timeline] the record system could not prepare an email entry', error)\n    return null\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_TIMELINE","multiple","registerPluginRecordTimelineWriter","writer","options","pluginId","pluginRecordTimelineWriter","entry","impl","preparePluginRecordEmail","request","resolved","prepareEmail","error","console"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA6O1B,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;AAEA;;;;;;CAMC,GACD,OAAO,eAAeC,yBACpBC,OAAwC;IAExC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,MAAM,CAACS,YAAY,GAAE,OAAO;IAC3C,IAAI;QACF,OAAO,MAAMD,SAASR,MAAM,CAACS,YAAY,CAACF;IAC5C,EAAE,OAAOG,OAAO;QACdC,QAAQD,KAAK,CAAC,wEAAwEA;QACtF,OAAO;IACT;AACF"}

package/src/lib/plugin-manager/plugin-resource-drafts.d.ts

@@ -45,11 +45,11 @@ import type { ReusableComponentTree } from '../app-utils/compose-reusable-compon
  *
  * ## The registry carries no authorization of the CALLER
  *
- * Like `order-fulfilment`, a writer is a pre-authorized operation. It applies
- * the owner's rules to the member the draft is for, and knows nothing about
- * whether the caller may act for that member. A caller establishes, in its
- * own terms and before it asks: who is asking, that the org owns the site,
- * and that the owning plugin is switched on for that site.
+ * A writer is a pre-authorized operation. It applies the owner's rules to the
+ * member the draft is for, and knows nothing about whether the caller may act
+ * for that member. A caller establishes, in its own terms and before it asks:
+ * who is asking, that the org owns the site, and that the owning plugin is
+ * switched on for that site.
  *
  * ## One writer per resource
  *

package/src/lib/plugin-manager/plugin-resource-drafts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-resource-drafts.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 { ReusableComponentTree } from '../app-utils/compose-reusable-components'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * Drafts one plugin writes for another (AGL-2912).\n *\n * A resource belongs to the plugin that models it: the document's shape, the\n * allowance a create counts against, who may create one, and what makes one\n * well-formed. A different plugin that produces such a resource — an importer\n * turning a file into pages, a generator turning a brief into an email, a\n * migration bringing campaigns over from another tool — must not write the\n * document itself, because it would restate the owner's rules and drift from\n * them the day the owner changes one. Nor may it import the owner, which the\n * package map forbids.\n *\n * So the owner registers a WRITER for the resource from its server surfaces,\n * and a caller asks for one by resource name. Every rule stays the owner's:\n *\n *  - `refusal` answers, before the caller spends anything, whether this\n *    member may create one on this site now: their role, the site's room;\n *  - `check` answers, synchronously and without I/O, whether content is\n *    well-formed, so a caller can hold what it produces to the owner's rules\n *    before it keeps it;\n *  - `read` reports the draft already written under an id, so a caller that\n *    runs again finds its draft rather than making a second;\n *  - `write` makes the draft, meets the allowance inside its own write, and\n *    never publishes, schedules or sends anything.\n *\n * Built on the typed service registry (`plugin-services`): one contract, every\n * writer registered under its resource name as the service's key.\n *\n * ## The registry carries no authorization of the CALLER\n *\n * Like `order-fulfilment`, a writer is a pre-authorized operation. It applies\n * the owner's rules to the member the draft is for, and knows nothing about\n * whether the caller may act for that member. A caller establishes, in its\n * own terms and before it asks: who is asking, that the org owns the site,\n * and that the owning plugin is switched on for that site.\n *\n * ## One writer per resource\n *\n * A resource has one owner. A second plugin registering a writer for a\n * resource another plugin already writes is refused, naming both, and the\n * incumbent keeps serving; the same plugin registering again — from its second\n * server surface, or on a hot reload — replaces its own.\n */\n\n/** Who a draft is for, on which site, and when. */\nexport interface PluginDraftContext {\n  orgId: string\n  hostId: string\n  /** The member the draft is made for: the owner applies its rules to them and records them as the author. */\n  uid: string\n  /** The org document the caller already read, for the owner's entitlement and allowance reads. */\n  org: Readonly<Record<string, unknown>> | null\n  now: Date\n}\n\n/** Why a draft cannot be made. */\nexport interface PluginDraftRefusal {\n  status: 400 | 403 | 404 | 409\n  /** Customer-safe: a caller shows it as it stands. */\n  error: string\n}\n\n/** A draft that exists. */\nexport interface PluginDraftRecord {\n  id: string\n  name: string\n  /** The version the draft opens on, where the resource has versions. */\n  versionId: string | null\n  /** What the owner reports about the draft beyond its identity, in the shape its writer documents. */\n  facts: Readonly<Record<string, unknown>>\n}\n\nexport interface PluginDraftRequest extends PluginDraftContext {\n  /** The draft's id, chosen by the caller: one per act, so a write asked again finds its draft. */\n  id: string\n  /** The name asked for; the owner may number it to keep it unique. */\n  name: string\n  /** The resource's content, in the shape the owner's writer documents and validates. */\n  content: Readonly<Record<string, unknown>>\n}\n\nexport type PluginDraftCheck =\n  | { ok: true; facts: Readonly<Record<string, unknown>> }\n  | { ok: false; problems: string[] }\n\n/** What a check is told beside the content. */\nexport interface PluginDraftCheckContext {\n  hostId: string\n  /**\n   * The site's published reusable components the content places, keyed by id\n   * — what `loadReferencedComponents` reads (AGL-3287).\n   *\n   * `check` does no I/O, so a caller whose content may place a component loads\n   * the definitions first and hands them in; a writer whose resource renders\n   * placed components composes them before judging, so what passes is what\n   * would render. Absent means none were loaded, and the content is judged as\n   * written.\n   */\n  components?: Readonly<Record<string, ReusableComponentTree | undefined>>\n}\n\nexport type PluginDraftWrite =\n  | (PluginDraftRecord & { ok: true; replayed: boolean })\n  | (PluginDraftRefusal & { ok: false })\n\nexport interface PluginResourceDraftWriter {\n  /** Whether this member may create one on this site now; `null` admits. */\n  refusal(context: PluginDraftContext): Promise<PluginDraftRefusal | null>\n  /** Whether content is well-formed, with what the owner derived from it. Pure. */\n  check(\n    content: Readonly<Record<string, unknown>>,\n    context: PluginDraftCheckContext,\n  ): PluginDraftCheck\n  /** The draft written under `id`, or `null`. */\n  read(context: { hostId: string; id: string }): Promise<PluginDraftRecord | null>\n  /** Makes the draft; a refusal is returned, never thrown. */\n  write(request: PluginDraftRequest): Promise<PluginDraftWrite>\n}\n\nexport const PLUGIN_RESOURCE_DRAFTS =\n  definePluginServiceContract<PluginResourceDraftWriter>('core.resource-drafts', {\n    multiple: true,\n  })\n\n/**\n * Registers the writer for a resource. The owner is the loader's marker when\n * a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A writer for a resource another plugin writes throws\n * naming both.\n */\nexport function registerPluginResourceDraftWriter(\n  resource: string,\n  writer: PluginResourceDraftWriter,\n  options?: { pluginId?: string },\n): void {\n  const key = resource.trim()\n  if (!key) throw new Error('a resource draft writer needs a resource name')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `resource \"${key}\" already has a draft writer from \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RESOURCE_DRAFTS, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginDraftWriter {\n  /** The plugin that owns the resource. */\n  pluginId: string\n  writer: PluginResourceDraftWriter\n}\n\n/** The writer for a resource, with its owner, or `null` when no plugin writes it. */\nexport function pluginResourceDraftWriter(resource: string): ResolvedPluginDraftWriter | null {\n  const key = resource.trim()\n  const entry = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RESOURCE_DRAFTS","multiple","registerPluginResourceDraftWriter","resource","writer","options","key","trim","Error","pluginId","incumbent","find","entry","pluginResourceDraftWriter","one","impl"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyH1B,OAAO,MAAMC,yBACXH,4BAAuD,wBAAwB;IAC7EI,UAAU;AACZ,GAAE;AAEJ;;;;;CAKC,GACD,OAAO,SAASC,kCACdC,QAAgB,EAChBC,MAAiC,EACjCC,OAA+B;QAIbT,MAAAA;IAFlB,MAAMU,MAAMH,SAASI,IAAI;IACzB,IAAI,CAACD,KAAK,MAAM,IAAIE,MAAM;IAC1B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASI,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,MAAMG,YAAYX,sBAAsBC,wBAAwBW,IAAI,CAClE,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaD,YAAYC,UAAUD,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAID,MACR,CAAC,UAAU,EAAEF,IAAI,mCAAmC,EAAEI,UAAUD,QAAQ,CAAC,GAAG,CAAC,GAC3E,CAAC,SAAS,EAAEA,SAAS,CAAC,CAAC;IAE7B;IACAX,sBAAsBE,wBAAwBI,QAAQ,aAChDC,CAAAA,2BAAAA,QAASI,QAAQ,IAAG;QAAEA,UAAUJ,QAAQI,QAAQ;IAAC,IAAI,CAAC;QAC1DH;;AAEJ;AAQA,mFAAmF,GACnF,OAAO,SAASO,0BAA0BV,QAAgB;IACxD,MAAMG,MAAMH,SAASI,IAAI;IACzB,MAAMK,QAAQb,sBAAsBC,wBAAwBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACtF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,QAAQQ,MAAMG,IAAI;IAAC,IAAI;AACpE"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-resource-drafts.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 { ReusableComponentTree } from '../app-utils/compose-reusable-components'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * Drafts one plugin writes for another (AGL-2912).\n *\n * A resource belongs to the plugin that models it: the document's shape, the\n * allowance a create counts against, who may create one, and what makes one\n * well-formed. A different plugin that produces such a resource — an importer\n * turning a file into pages, a generator turning a brief into an email, a\n * migration bringing campaigns over from another tool — must not write the\n * document itself, because it would restate the owner's rules and drift from\n * them the day the owner changes one. Nor may it import the owner, which the\n * package map forbids.\n *\n * So the owner registers a WRITER for the resource from its server surfaces,\n * and a caller asks for one by resource name. Every rule stays the owner's:\n *\n *  - `refusal` answers, before the caller spends anything, whether this\n *    member may create one on this site now: their role, the site's room;\n *  - `check` answers, synchronously and without I/O, whether content is\n *    well-formed, so a caller can hold what it produces to the owner's rules\n *    before it keeps it;\n *  - `read` reports the draft already written under an id, so a caller that\n *    runs again finds its draft rather than making a second;\n *  - `write` makes the draft, meets the allowance inside its own write, and\n *    never publishes, schedules or sends anything.\n *\n * Built on the typed service registry (`plugin-services`): one contract, every\n * writer registered under its resource name as the service's key.\n *\n * ## The registry carries no authorization of the CALLER\n *\n * A writer is a pre-authorized operation. It applies the owner's rules to the\n * member the draft is for, and knows nothing about whether the caller may act\n * for that member. A caller establishes, in its own terms and before it asks:\n * who is asking, that the org owns the site, and that the owning plugin is\n * switched on for that site.\n *\n * ## One writer per resource\n *\n * A resource has one owner. A second plugin registering a writer for a\n * resource another plugin already writes is refused, naming both, and the\n * incumbent keeps serving; the same plugin registering again — from its second\n * server surface, or on a hot reload — replaces its own.\n */\n\n/** Who a draft is for, on which site, and when. */\nexport interface PluginDraftContext {\n  orgId: string\n  hostId: string\n  /** The member the draft is made for: the owner applies its rules to them and records them as the author. */\n  uid: string\n  /** The org document the caller already read, for the owner's entitlement and allowance reads. */\n  org: Readonly<Record<string, unknown>> | null\n  now: Date\n}\n\n/** Why a draft cannot be made. */\nexport interface PluginDraftRefusal {\n  status: 400 | 403 | 404 | 409\n  /** Customer-safe: a caller shows it as it stands. */\n  error: string\n}\n\n/** A draft that exists. */\nexport interface PluginDraftRecord {\n  id: string\n  name: string\n  /** The version the draft opens on, where the resource has versions. */\n  versionId: string | null\n  /** What the owner reports about the draft beyond its identity, in the shape its writer documents. */\n  facts: Readonly<Record<string, unknown>>\n}\n\nexport interface PluginDraftRequest extends PluginDraftContext {\n  /** The draft's id, chosen by the caller: one per act, so a write asked again finds its draft. */\n  id: string\n  /** The name asked for; the owner may number it to keep it unique. */\n  name: string\n  /** The resource's content, in the shape the owner's writer documents and validates. */\n  content: Readonly<Record<string, unknown>>\n}\n\nexport type PluginDraftCheck =\n  | { ok: true; facts: Readonly<Record<string, unknown>> }\n  | { ok: false; problems: string[] }\n\n/** What a check is told beside the content. */\nexport interface PluginDraftCheckContext {\n  hostId: string\n  /**\n   * The site's published reusable components the content places, keyed by id\n   * — what `loadReferencedComponents` reads (AGL-3287).\n   *\n   * `check` does no I/O, so a caller whose content may place a component loads\n   * the definitions first and hands them in; a writer whose resource renders\n   * placed components composes them before judging, so what passes is what\n   * would render. Absent means none were loaded, and the content is judged as\n   * written.\n   */\n  components?: Readonly<Record<string, ReusableComponentTree | undefined>>\n}\n\nexport type PluginDraftWrite =\n  | (PluginDraftRecord & { ok: true; replayed: boolean })\n  | (PluginDraftRefusal & { ok: false })\n\nexport interface PluginResourceDraftWriter {\n  /** Whether this member may create one on this site now; `null` admits. */\n  refusal(context: PluginDraftContext): Promise<PluginDraftRefusal | null>\n  /** Whether content is well-formed, with what the owner derived from it. Pure. */\n  check(\n    content: Readonly<Record<string, unknown>>,\n    context: PluginDraftCheckContext,\n  ): PluginDraftCheck\n  /** The draft written under `id`, or `null`. */\n  read(context: { hostId: string; id: string }): Promise<PluginDraftRecord | null>\n  /** Makes the draft; a refusal is returned, never thrown. */\n  write(request: PluginDraftRequest): Promise<PluginDraftWrite>\n}\n\nexport const PLUGIN_RESOURCE_DRAFTS =\n  definePluginServiceContract<PluginResourceDraftWriter>('core.resource-drafts', {\n    multiple: true,\n  })\n\n/**\n * Registers the writer for a resource. The owner is the loader's marker when\n * a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A writer for a resource another plugin writes throws\n * naming both.\n */\nexport function registerPluginResourceDraftWriter(\n  resource: string,\n  writer: PluginResourceDraftWriter,\n  options?: { pluginId?: string },\n): void {\n  const key = resource.trim()\n  if (!key) throw new Error('a resource draft writer needs a resource name')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `resource \"${key}\" already has a draft writer from \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RESOURCE_DRAFTS, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginDraftWriter {\n  /** The plugin that owns the resource. */\n  pluginId: string\n  writer: PluginResourceDraftWriter\n}\n\n/** The writer for a resource, with its owner, or `null` when no plugin writes it. */\nexport function pluginResourceDraftWriter(resource: string): ResolvedPluginDraftWriter | null {\n  const key = resource.trim()\n  const entry = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RESOURCE_DRAFTS","multiple","registerPluginResourceDraftWriter","resource","writer","options","key","trim","Error","pluginId","incumbent","find","entry","pluginResourceDraftWriter","one","impl"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyH1B,OAAO,MAAMC,yBACXH,4BAAuD,wBAAwB;IAC7EI,UAAU;AACZ,GAAE;AAEJ;;;;;CAKC,GACD,OAAO,SAASC,kCACdC,QAAgB,EAChBC,MAAiC,EACjCC,OAA+B;QAIbT,MAAAA;IAFlB,MAAMU,MAAMH,SAASI,IAAI;IACzB,IAAI,CAACD,KAAK,MAAM,IAAIE,MAAM;IAC1B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASI,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,MAAMG,YAAYX,sBAAsBC,wBAAwBW,IAAI,CAClE,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaD,YAAYC,UAAUD,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAID,MACR,CAAC,UAAU,EAAEF,IAAI,mCAAmC,EAAEI,UAAUD,QAAQ,CAAC,GAAG,CAAC,GAC3E,CAAC,SAAS,EAAEA,SAAS,CAAC,CAAC;IAE7B;IACAX,sBAAsBE,wBAAwBI,QAAQ,aAChDC,CAAAA,2BAAAA,QAASI,QAAQ,IAAG;QAAEA,UAAUJ,QAAQI,QAAQ;IAAC,IAAI,CAAC;QAC1DH;;AAEJ;AAQA,mFAAmF,GACnF,OAAO,SAASO,0BAA0BV,QAAgB;IACxD,MAAMG,MAAMH,SAASI,IAAI;IACzB,MAAMK,QAAQb,sBAAsBC,wBAAwBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACtF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,QAAQQ,MAAMG,IAAI;IAAC,IAAI;AACpE"}

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

@@ -0,0 +1,64 @@
+/**
+ * @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 { PluginRevocation } from '../app-utils/plugin-manifest';
+/**
+ * The platform's kill switch, read by a plugin that is not the one that keeps
+ * it (AGL-3080).
+ *
+ * An artifact installed from a distribution channel — an email design, a
+ * component, a plugin — carries the listing it came from on its install
+ * stamp (`app-utils/artifact-provenance.ts`). When the platform pulls that
+ * listing, or one of its versions, the revocation (`PluginRevocation`, the
+ * platform's own shape) is what every reader consults: the loader before it
+ * runs a bundle, the send path before it mails a design that was installed
+ * rather than written. The revocations are KEPT by the plugin that runs the
+ * distribution channel, and a reader that is not that plugin asks through
+ * this slot rather than reading its storage.
+ *
+ * ## Absent, and failed, are different answers
+ *
+ * No reader registered means nothing in this process distributes artifacts,
+ * so nothing here could have been installed from a listing and there is
+ * nothing to revoke: {@link readListingRevocation} answers `null` — after
+ * running the app's boot step once, because a boot whose declarations
+ * failed looks the same from here, and a kill switch that silently stopped
+ * answering is the one failure it may not have. A reader
+ * that FAILS throws through to the caller, which decides — a send that cannot
+ * learn whether its design was pulled refuses rather than mails it, the
+ * direction the read had before it was a seam.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`.
+ */
+export interface PluginRevocationReader {
+    /** The listing's revocation, or `null` when it was never revoked. */
+    revocation(listingId: string): Promise<PluginRevocation | null>;
+}
+export declare const PLUGIN_REVOCATIONS: import("./plugin-services").PluginServiceContract<PluginRevocationReader>;
+/**
+ * Registers the plugin that keeps the revocations. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`; a second
+ * plugin's reader is refused naming both.
+ */
+export declare function registerPluginRevocationReader(reader: PluginRevocationReader, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * A listing's revocation: `null` when it has none, or when nothing in this
+ * process keeps revocations. Throws what a failing reader throws.
+ */
+export declare function readListingRevocation(listingId: string): Promise<PluginRevocation | null>;

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

@@ -0,0 +1,47 @@
+/**
+ * @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 { runPluginDeclarationsRepair } from "./plugin-declarations-repair.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginService } from "./plugin-services.js";
+export const PLUGIN_REVOCATIONS = definePluginServiceContract('core.revocations', {
+    multiple: false
+});
+/**
+ * Registers the plugin that keeps the revocations. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`; a second
+ * plugin's reader is refused naming both.
+ */ export function registerPluginRevocationReader(reader, options) {
+    registerPluginService(PLUGIN_REVOCATIONS, reader, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/**
+ * A listing's revocation: `null` when it has none, or when nothing in this
+ * process keeps revocations. Throws what a failing reader throws.
+ */ export async function readListingRevocation(listingId) {
+    const id = String(listingId != null ? listingId : '').trim();
+    if (!id) return null;
+    let reader = resolvePluginService(PLUGIN_REVOCATIONS);
+    if (!reader) {
+        await runPluginDeclarationsRepair().catch((error)=>{
+            console.error('[revocations] plugin declarations failed', error);
+        });
+        reader = resolvePluginService(PLUGIN_REVOCATIONS);
+    }
+    return reader ? reader.revocation(id) : null;
+}
+
+//# sourceMappingURL=plugin-revocations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-revocations.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 { PluginRevocation } from '../app-utils/plugin-manifest'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\n\n/**\n * The platform's kill switch, read by a plugin that is not the one that keeps\n * it (AGL-3080).\n *\n * An artifact installed from a distribution channel — an email design, a\n * component, a plugin — carries the listing it came from on its install\n * stamp (`app-utils/artifact-provenance.ts`). When the platform pulls that\n * listing, or one of its versions, the revocation (`PluginRevocation`, the\n * platform's own shape) is what every reader consults: the loader before it\n * runs a bundle, the send path before it mails a design that was installed\n * rather than written. The revocations are KEPT by the plugin that runs the\n * distribution channel, and a reader that is not that plugin asks through\n * this slot rather than reading its storage.\n *\n * ## Absent, and failed, are different answers\n *\n * No reader registered means nothing in this process distributes artifacts,\n * so nothing here could have been installed from a listing and there is\n * nothing to revoke: {@link readListingRevocation} answers `null` — after\n * running the app's boot step once, because a boot whose declarations\n * failed looks the same from here, and a kill switch that silently stopped\n * answering is the one failure it may not have. A reader\n * that FAILS throws through to the caller, which decides — a send that cannot\n * learn whether its design was pulled refuses rather than mails it, the\n * direction the read had before it was a seam.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\nexport interface PluginRevocationReader {\n  /** The listing's revocation, or `null` when it was never revoked. */\n  revocation(listingId: string): Promise<PluginRevocation | null>\n}\n\nexport const PLUGIN_REVOCATIONS = definePluginServiceContract<PluginRevocationReader>(\n  'core.revocations',\n  { multiple: false },\n)\n\n/**\n * Registers the plugin that keeps the revocations. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`; a second\n * plugin's reader is refused naming both.\n */\nexport function registerPluginRevocationReader(\n  reader: PluginRevocationReader,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_REVOCATIONS, reader, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/**\n * A listing's revocation: `null` when it has none, or when nothing in this\n * process keeps revocations. Throws what a failing reader throws.\n */\nexport async function readListingRevocation(listingId: string): Promise<PluginRevocation | null> {\n  const id = String(listingId ?? '').trim()\n  if (!id) return null\n  let reader = resolvePluginService(PLUGIN_REVOCATIONS)\n  if (!reader) {\n    await runPluginDeclarationsRepair().catch((error: unknown) => {\n      console.error('[revocations] plugin declarations failed', error)\n    })\n    reader = resolvePluginService(PLUGIN_REVOCATIONS)\n  }\n  return reader ? reader.revocation(id) : null\n}\n"],"names":["runPluginDeclarationsRepair","definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_REVOCATIONS","multiple","registerPluginRevocationReader","reader","options","pluginId","readListingRevocation","listingId","id","String","trim","catch","error","console","revocation"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,2BAA2B,QAAQ,kCAA8B;AAC1E,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAqC1B,OAAO,MAAMC,qBAAqBH,4BAChC,oBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;CAIC,GACD,OAAO,SAASC,+BACdC,MAA8B,EAC9BC,OAA+B;IAE/BN,sBAAsBE,oBAAoBG,QAAQ,aAC5CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA;;;CAGC,GACD,OAAO,eAAeC,sBAAsBC,SAAiB;IAC3D,MAAMC,KAAKC,OAAOF,oBAAAA,YAAa,IAAIG,IAAI;IACvC,IAAI,CAACF,IAAI,OAAO;IAChB,IAAIL,SAASJ,qBAAqBC;IAClC,IAAI,CAACG,QAAQ;QACX,MAAMP,8BAA8Be,KAAK,CAAC,CAACC;YACzCC,QAAQD,KAAK,CAAC,4CAA4CA;QAC5D;QACAT,SAASJ,qBAAqBC;IAChC;IACA,OAAOG,SAASA,OAAOW,UAAU,CAACN,MAAM;AAC1C"}

package/src/lib/plugin-manager/plugin-send-tallies.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A bulk send's own figures, moved by a door that is not its sender
+ * (AGL-3080).
+ *
+ * A message a bulk send carried names the send — its id is signed into the
+ * unsubscribe link and tagged on the message — and the plugin that serves
+ * the site's unsubscribe page learns that a recipient left. That plugin is
+ * not the sender: the send, and the figures its report reads, are the
+ * plugin's that sent it. So the door reports what happened and the sender
+ * counts it, without either importing the other.
+ *
+ * A MULTIPLE contract: several plugins may send in bulk, and the door does
+ * not know which one a send id is. Each tally answers whether the send was
+ * its own and counted; the first that answers yes ends the ask.
+ *
+ * ## The caller proves what happened
+ *
+ * The registry authenticates nobody. A door counts only what it has already
+ * written: an unsubscribe is counted once, when its suppression was created,
+ * never on a second click of the same link.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`.
+ */
+/** A send, as a link or a message tag names it. */
+export interface PluginSendTallyRequest {
+    /** The site whose mail it was. */
+    hostId: string;
+    /** The send's id, as signed into the link. */
+    sendId: string;
+}
+export interface PluginSendTally {
+    /**
+     * One more recipient left from this send's mail. Answers whether the send
+     * is this plugin's and was counted; a send it does not keep is `false`.
+     */
+    unsubscribed(request: PluginSendTallyRequest): Promise<boolean>;
+}
+export declare const PLUGIN_SEND_TALLIES: import("./plugin-services").PluginServiceContract<PluginSendTally>;
+/**
+ * Registers a sender's tally. The owner is the loader's marker when a
+ * register fn is running, else `options.pluginId`; registering again under
+ * the same plugin replaces in place.
+ */
+export declare function registerPluginSendTally(tally: PluginSendTally, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * Tells the sender of a send that a recipient left. Never throws: the door's
+ * own write — the suppression — has landed, and a figure must never be able
+ * to cost it. Answers whether any sender counted it.
+ */
+export declare function tallySendUnsubscribe(request: PluginSendTallyRequest): Promise<boolean>;

package/src/lib/plugin-manager/plugin-send-tallies.js

@@ -0,0 +1,45 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_SEND_TALLIES = definePluginServiceContract('core.send-tallies', {
+    multiple: true
+});
+/**
+ * Registers a sender's tally. The owner is the loader's marker when a
+ * register fn is running, else `options.pluginId`; registering again under
+ * the same plugin replaces in place.
+ */ export function registerPluginSendTally(tally, options) {
+    registerPluginService(PLUGIN_SEND_TALLIES, tally, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/**
+ * Tells the sender of a send that a recipient left. Never throws: the door's
+ * own write — the suppression — has landed, and a figure must never be able
+ * to cost it. Answers whether any sender counted it.
+ */ export async function tallySendUnsubscribe(request) {
+    for (const entry of resolvePluginServices(PLUGIN_SEND_TALLIES)){
+        try {
+            if (await entry.impl.unsubscribed(request)) return true;
+        } catch (error) {
+            console.error(`[send-tallies] ${entry.pluginId} failed on ${request.hostId}`, error);
+        }
+    }
+    return false;
+}
+
+//# sourceMappingURL=plugin-send-tallies.js.map

package/src/lib/plugin-manager/plugin-send-tallies.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-send-tallies.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 * A bulk send's own figures, moved by a door that is not its sender\n * (AGL-3080).\n *\n * A message a bulk send carried names the send — its id is signed into the\n * unsubscribe link and tagged on the message — and the plugin that serves\n * the site's unsubscribe page learns that a recipient left. That plugin is\n * not the sender: the send, and the figures its report reads, are the\n * plugin's that sent it. So the door reports what happened and the sender\n * counts it, without either importing the other.\n *\n * A MULTIPLE contract: several plugins may send in bulk, and the door does\n * not know which one a send id is. Each tally answers whether the send was\n * its own and counted; the first that answers yes ends the ask.\n *\n * ## The caller proves what happened\n *\n * The registry authenticates nobody. A door counts only what it has already\n * written: an unsubscribe is counted once, when its suppression was created,\n * never on a second click of the same link.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\n/** A send, as a link or a message tag names it. */\nexport interface PluginSendTallyRequest {\n  /** The site whose mail it was. */\n  hostId: string\n  /** The send's id, as signed into the link. */\n  sendId: string\n}\n\nexport interface PluginSendTally {\n  /**\n   * One more recipient left from this send's mail. Answers whether the send\n   * is this plugin's and was counted; a send it does not keep is `false`.\n   */\n  unsubscribed(request: PluginSendTallyRequest): Promise<boolean>\n}\n\nexport const PLUGIN_SEND_TALLIES = definePluginServiceContract<PluginSendTally>(\n  'core.send-tallies',\n  { multiple: true },\n)\n\n/**\n * Registers a sender's tally. The owner is the loader's marker when a\n * register fn is running, else `options.pluginId`; registering again under\n * the same plugin replaces in place.\n */\nexport function registerPluginSendTally(\n  tally: PluginSendTally,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_SEND_TALLIES, tally, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/**\n * Tells the sender of a send that a recipient left. Never throws: the door's\n * own write — the suppression — has landed, and a figure must never be able\n * to cost it. Answers whether any sender counted it.\n */\nexport async function tallySendUnsubscribe(request: PluginSendTallyRequest): Promise<boolean> {\n  for (const entry of resolvePluginServices(PLUGIN_SEND_TALLIES)) {\n    try {\n      if (await entry.impl.unsubscribed(request)) return true\n    } catch (error) {\n      console.error(`[send-tallies] ${entry.pluginId} failed on ${request.hostId}`, error)\n    }\n  }\n  return false\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_SEND_TALLIES","multiple","registerPluginSendTally","tally","options","pluginId","tallySendUnsubscribe","request","entry","impl","unsubscribed","error","console","hostId"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2C1B,OAAO,MAAMC,sBAAsBH,4BACjC,qBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,wBACdC,KAAsB,EACtBC,OAA+B;IAE/BN,sBAAsBE,qBAAqBG,OAAO,aAC5CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA;;;;CAIC,GACD,OAAO,eAAeC,qBAAqBC,OAA+B;IACxE,KAAK,MAAMC,SAAST,sBAAsBC,qBAAsB;QAC9D,IAAI;YACF,IAAI,MAAMQ,MAAMC,IAAI,CAACC,YAAY,CAACH,UAAU,OAAO;QACrD,EAAE,OAAOI,OAAO;YACdC,QAAQD,KAAK,CAAC,CAAC,eAAe,EAAEH,MAAMH,QAAQ,CAAC,WAAW,EAAEE,QAAQM,MAAM,EAAE,EAAEF;QAChF;IACF;IACA,OAAO;AACT"}