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

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

@@ -0,0 +1,75 @@
+/**
+ * @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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_RECORD_LISTS = definePluginServiceContract('core.record-lists', {
+    multiple: true
+});
+/**
+ * Publishes the list source for one record kind. The owner is the loader's
+ * marker when a register fn is running, else `options.pluginId`; with neither
+ * the registration throws. A kind another plugin lists throws naming both.
+ */ export function registerPluginRecordListSource(kind, source, options) {
+    var _ref, _getRegisteringPluginId;
+    const key = kind.trim();
+    if (!key) throw new Error('a record list source needs a record kind');
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`the record list source for "${key}" was registered with no owner`);
+    }
+    const incumbent = resolvePluginServices(PLUGIN_RECORD_LISTS).find((entry)=>entry.key === key);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`record kind "${key}" is already listed by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_RECORD_LISTS, source, {
+        pluginId,
+        key
+    });
+}
+/** The list source for a kind, with the plugin that keeps it, or `null` when none does here. */ export function pluginRecordListSource(kind) {
+    const key = kind.trim();
+    const entry = resolvePluginServices(PLUGIN_RECORD_LISTS).find((one)=>one.key === key);
+    return entry ? {
+        pluginId: entry.pluginId,
+        source: entry.impl
+    } : null;
+}
+/**
+ * The query a reader listens to for a kind's records — with the console's own
+ * collection listener, so it is bounded, retried and reported like every
+ * other list — or `null` when no plugin keeps the kind here or the scope has
+ * none.
+ */ export function pluginRecordListQuery(kind, firestore, request) {
+    var _ref;
+    var _pluginRecordListSource;
+    return (_ref = (_pluginRecordListSource = pluginRecordListSource(kind)) == null ? void 0 : _pluginRecordListSource.source.query(firestore, request)) != null ? _ref : null;
+}
+/**
+ * The documents a reader's listener answered for `kind`, as their owner
+ * shares them: each row's id is read from `idField` (the listener's), and a
+ * row the owner leaves out (deleted, unnamed) is not answered. None where no
+ * plugin keeps the kind here.
+ */ export function pluginRecordsFromRows(kind, rows, idField = '$id') {
+    var _pluginRecordListSource;
+    const source = (_pluginRecordListSource = pluginRecordListSource(kind)) == null ? void 0 : _pluginRecordListSource.source;
+    if (!source) return [];
+    return (rows != null ? rows : []).map((row)=>{
+        var _row_idField;
+        return source.record(String((_row_idField = row[idField]) != null ? _row_idField : ''), row);
+    }).filter((record)=>record !== null);
+}
+
+//# sourceMappingURL=plugin-record-lists.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-lists.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 { DocumentData, Firestore, Query } from 'firebase/firestore'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport type { PluginIndexedRecord } from './plugin-record-index'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * A plugin's records, LISTED in the console for another plugin's picker or\n * check (AGL-3080) — the browser's half of `plugin-record-index`.\n *\n * A plugin that offers records it does not own — an automation step picking\n * a dataset, a reference check confirming a workflow still exists, a deal\n * picking a product — used to query the owner's collection from the browser\n * itself: the path, the filter the owner's security rules require, the field\n * a name is in, what a deleted one looks like. Each breaks the day the owner\n * changes one, and none is visible to `check:lib-boundaries`.\n *\n * So the owner publishes a LIST SOURCE for each record kind it keeps: the\n * query the signed-in member's read of a scope is proved by, and how one\n * stored document reads as a record — an id, a name and the facts the owner\n * chooses to share, in the shape its registration documents, the same shape\n * its server index answers. The reader runs the query with its own listener\n * (`pluginRecordListQuery`) and reads the rows back through the owner\n * (`pluginRecordsFromRows`), and never learns where the records are stored.\n *\n * ## Not registered is an answer\n *\n * No source for a kind means no plugin keeps it in this console — the owner is\n * not installed or not loaded. A reader treats that as \"none here\" and says\n * so, rather than reaching for the collection itself.\n *\n * ## One source per kind\n *\n * A second plugin registering a source for a kind another plugin already\n * keeps is refused, naming both, and the incumbent keeps serving.\n */\n\n/** Which records a reader lists. */\nexport interface PluginRecordListRequest {\n  /** The organization the records belong to, where the kind is org-scoped. */\n  orgId?: string | null\n  /**\n   * The site the records are listed for. An org-scoped kind narrows to what\n   * the site may use; `null` lists the organization's own view, which only an\n   * organization-wide reader may hold.\n   */\n  hostId?: string | null\n  /** What a person typed, matched the owner's way; absent lists the scope. */\n  search?: string | null\n  /**\n   * The signed-in member's own scope tokens, where they are not\n   * organization-wide and no site is named: an org-scoped kind narrows to\n   * what they may see, which is the filter the security rules require of\n   * them. Absent for an organization-wide reader; a named site's narrowing\n   * wins over it, and a site's own kind has no use for it.\n   */\n  memberScope?: readonly string[] | null\n  /**\n   * Only the records installed from this listing — the `listingId` of their\n   * install stamp (`app-utils/artifact-provenance.ts`), matched wherever the\n   * owner keeps it. A kind that is never installed answers none.\n   */\n  installedFrom?: string | null\n  /** The most documents the query may answer — a reader asks one past its window to learn it was cut. */\n  limit: number\n}\n\nexport interface PluginRecordListSource {\n  /**\n   * The query the signed-in member's read of the scope is proved by, at most\n   * `limit` documents, or `null` for a scope the kind has none in (a site-only\n   * kind asked at the organization, a search with nothing to match).\n   */\n  query(firestore: Firestore, request: PluginRecordListRequest): Query<DocumentData> | null\n  /** One stored document as the owner shares it, or `null` to leave it out (deleted, unnamed). */\n  record(id: string, data: Readonly<Record<string, unknown>>): PluginIndexedRecord | null\n}\n\nexport const PLUGIN_RECORD_LISTS = definePluginServiceContract<PluginRecordListSource>(\n  'core.record-lists',\n  { multiple: true },\n)\n\n/**\n * Publishes the list source for one record kind. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`; with neither\n * the registration throws. A kind another plugin lists throws naming both.\n */\nexport function registerPluginRecordListSource(\n  kind: string,\n  source: PluginRecordListSource,\n  options?: { pluginId?: string },\n): void {\n  const key = kind.trim()\n  if (!key) throw new Error('a record list source needs a record kind')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(`the record list source for \"${key}\" was registered with no owner`)\n  }\n  const incumbent = resolvePluginServices(PLUGIN_RECORD_LISTS).find((entry) => entry.key === key)\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `record kind \"${key}\" is already listed by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RECORD_LISTS, source, { pluginId, key })\n}\n\n/** The list source for a kind, with the plugin that keeps it, or `null` when none does here. */\nexport function pluginRecordListSource(\n  kind: string,\n): { pluginId: string; source: PluginRecordListSource } | null {\n  const key = kind.trim()\n  const entry = resolvePluginServices(PLUGIN_RECORD_LISTS).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, source: entry.impl } : null\n}\n\n/**\n * The query a reader listens to for a kind's records — with the console's own\n * collection listener, so it is bounded, retried and reported like every\n * other list — or `null` when no plugin keeps the kind here or the scope has\n * none.\n */\nexport function pluginRecordListQuery(\n  kind: string,\n  firestore: Firestore,\n  request: PluginRecordListRequest,\n): Query<DocumentData> | null {\n  return pluginRecordListSource(kind)?.source.query(firestore, request) ?? null\n}\n\n/**\n * The documents a reader's listener answered for `kind`, as their owner\n * shares them: each row's id is read from `idField` (the listener's), and a\n * row the owner leaves out (deleted, unnamed) is not answered. None where no\n * plugin keeps the kind here.\n */\nexport function pluginRecordsFromRows(\n  kind: string,\n  rows: ReadonlyArray<Readonly<Record<string, unknown>>> | null | undefined,\n  idField = '$id',\n): PluginIndexedRecord[] {\n  const source = pluginRecordListSource(kind)?.source\n  if (!source) return []\n  return (rows ?? [])\n    .map((row) => source.record(String(row[idField] ?? ''), row))\n    .filter((record): record is PluginIndexedRecord => record !== null)\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_LISTS","multiple","registerPluginRecordListSource","kind","source","options","key","trim","Error","pluginId","incumbent","find","entry","pluginRecordListSource","one","impl","pluginRecordListQuery","firestore","request","query","pluginRecordsFromRows","rows","idField","map","row","record","String","filter"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AAExE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA0E1B,OAAO,MAAMC,sBAAsBH,4BACjC,qBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,+BACdC,IAAY,EACZC,MAA8B,EAC9BC,OAA+B;QAIbT,MAAAA;IAFlB,MAAMU,MAAMH,KAAKI,IAAI;IACrB,IAAI,CAACD,KAAK,MAAM,IAAIE,MAAM;IAC1B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASI,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,IAAI,CAACE,UAAU;QACb,MAAM,IAAID,MAAM,CAAC,4BAA4B,EAAEF,IAAI,8BAA8B,CAAC;IACpF;IACA,MAAMI,YAAYX,sBAAsBC,qBAAqBW,IAAI,CAAC,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAC3F,IAAII,aAAaA,UAAUD,QAAQ,KAAKA,UAAU;QAChD,MAAM,IAAID,MACR,CAAC,aAAa,EAAEF,IAAI,wBAAwB,EAAEI,UAAUD,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAE9F;IACAX,sBAAsBE,qBAAqBI,QAAQ;QAAEK;QAAUH;IAAI;AACrE;AAEA,8FAA8F,GAC9F,OAAO,SAASO,uBACdV,IAAY;IAEZ,MAAMG,MAAMH,KAAKI,IAAI;IACrB,MAAMK,QAAQb,sBAAsBC,qBAAqBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACnF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,QAAQQ,MAAMG,IAAI;IAAC,IAAI;AACpE;AAEA;;;;;CAKC,GACD,OAAO,SAASC,sBACdb,IAAY,EACZc,SAAoB,EACpBC,OAAgC;;QAEzBL;IAAP,gBAAOA,0BAAAA,uBAAuBV,0BAAvBU,wBAA8BT,MAAM,CAACe,KAAK,CAACF,WAAWC,2BAAY;AAC3E;AAEA;;;;;CAKC,GACD,OAAO,SAASE,sBACdjB,IAAY,EACZkB,IAAyE,EACzEC,UAAU,KAAK;QAEAT;IAAf,MAAMT,UAASS,0BAAAA,uBAAuBV,0BAAvBU,wBAA8BT,MAAM;IACnD,IAAI,CAACA,QAAQ,OAAO,EAAE;IACtB,OAAO,CAACiB,eAAAA,OAAQ,EAAE,EACfE,GAAG,CAAC,CAACC;YAA6BA;eAArBpB,OAAOqB,MAAM,CAACC,QAAOF,eAAAA,GAAG,CAACF,QAAQ,YAAZE,eAAgB,KAAKA;OACvDG,MAAM,CAAC,CAACF,SAA0CA,WAAW;AAClE"}

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

@@ -17,9 +17,10 @@
 /**
  * An entry one plugin files on a record another plugin keeps (AGL-2981).
  *
- * A person, a company and a deal are records of the workspace's record
- * system, and what happened with them — an email sent, a reply received, a
- * call to make — belongs on their timeline, whichever plugin it happened in.
+ * A person and the company they work for are records of the workspace's
+ * record system, and what happened with them — an email sent, a reply
+ * received, a call to make — belongs on their timeline, whichever plugin it
+ * happened in.
  * A plugin that sends mail or books a meeting must not write the record
  * system's documents itself: it would restate the owner's rules — where an
  * entry lives, who may see it, how a copy of the same email is told apart,
@@ -39,7 +40,11 @@
  *    `dedupeKey`, so a caller that runs again finds what it wrote rather
  *    than writing it twice;
  *  - a record whose log is full, or a workspace whose plan carries no record
- *    system, is refused — answered, never thrown.
+ *    system, is refused — answered, never thrown;
+ *  - a caller that knows a record only as the owner handed it over — a kind
+ *    and an id carried on a link — or knows only the person's address is
+ *    answered with the record the owner finds for it, on that site, or
+ *    refused with a 404 when it finds none.
  *
  * A single-implementation contract: a workspace keeps one record system.
  *
@@ -50,11 +55,19 @@
  * the workspace's to write — that the record is one it acted on, for the
  * member it acted for.
  */
-/** The record an entry is filed on: any of the four, as the owner links them. */
+/**
+ * The record an entry is filed on: the person (a contact, or a lead not yet
+ * one) and the company they work for, as the owner links them — or, from a
+ * caller that holds no id of the owner's, how to find the record.
+ *
+ * The ids win where given, and are filed on as named. Otherwise `record`,
+ * then `email`: the owner looks the record up as the entry's site sees it,
+ * links whatever it groups that record under itself, and refuses the entry
+ * with a 404 when it finds nothing.
+ */
 export interface PluginRecordLink {
     contactId?: string;
     companyId?: string;
-    dealId?: string;
     /**
      * A lead not yet converted (AGL-3234) — the record system's own id for
      * it, addressed under `hostId`. A sequence's emails and tasks land on the
@@ -62,6 +75,23 @@ export interface PluginRecordLink {
      * it becomes.
      */
     leadId?: string;
+    /**
+     * A record the owner handed the caller, by its kind and id in the owner's
+     * own words, and carried back unread (AGL-2660): the record a booking link
+     * was dropped from, through the zone the owner drew it in. A kind the
+     * owner does not keep, or a record the site cannot see, is passed over for
+     * `email` rather than refused.
+     */
+    record?: {
+        kind: string;
+        id: string;
+    } | null;
+    /**
+     * The person at this address, as the entry's site knows them: what the
+     * entry lands on when nothing above names a record the owner finds — a
+     * booking taken off the widget cold.
+     */
+    email?: string | null;
 }
 /** Where an entry is filed, and by which plugin. */
 export interface PluginRecordEntryContext {
@@ -112,8 +142,12 @@ export interface PluginRecordTaskRequest extends PluginRecordEntryContext {
     kind: PluginRecordTaskKind;
     /** When it is due, epoch ms. */
     dueAtMs: number;
-    /** The member it is for, or `''` for nobody. */
-    assigneeUid: string;
+    /**
+     * The member it is for, `''` for nobody, or `null` for whoever holds the
+     * record it lands on — the caller that found the record by `record` or
+     * `email` does not know who that is.
+     */
+    assigneeUid: string | null;
     /** The member who made it happen, or `''` when nobody did. */
     createdByUid: string;
 }

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\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"}
+{"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"}

package/src/lib/plugin-manager/plugin-server-steps.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @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 SERVER STEP ANOTHER PLUGIN RUNS (AGL-3080).
+ *
+ * An interaction's steps are the platform's client steps plus whatever steps
+ * the plugins add (`site-interactions.ts`), and every step that is not a
+ * client step is the server's to run. The plugin that runs a server run — the
+ * automation engine — knows its own steps. A step that acts on ANOTHER
+ * plugin's records is that plugin's: writing a dataset row is the data
+ * plugin's, moving a contact's stage is the CRM's. The engine used to carry
+ * each of those writes itself, which made it the keeper of every plugin's
+ * storage.
+ *
+ * So the plugin that owns a step REGISTERS ITS EXECUTOR here, by step type,
+ * and the engine hands it the step when a run reaches one. The engine keeps
+ * what every step shares — the step's guard, the run's order, its history,
+ * the nesting cap — and the executor does the step's one write. Neither
+ * imports the other: both meet at this module, which names no plugin, so a
+ * marketplace plugin adds a step the same way a first-party one does.
+ *
+ * ## Declared, then registered — and an absent executor is refused
+ *
+ * The executor is registered from the owning plugin's `serverDeclarations`
+ * entry, which every app runs at boot. An empty registry must not read as an
+ * answer: a step whose executor never registered would otherwise fall through
+ * the engine as a step nobody runs, and a run history would say the record
+ * was written when it was not.
+ *
+ * So a first-party plugin also DECLARES the steps it runs, under
+ * `serverSteps` in `plugins.config.json`, compiled into core. The three cases
+ * are kept apart:
+ *
+ * - registered — the executor runs the step, declared or not (a marketplace
+ *   plugin's steps are registered and never compiled);
+ * - declared and NOT registered — the boot failed. The app's declarations
+ *   step is run again ({@link runPluginDeclarationsRepair}); if the executor
+ *   is still missing, {@link pluginServerStepExecutor} THROWS
+ *   {@link ServerStepUnavailableError}, which the engine records as the
+ *   step's failure;
+ * - neither — no plugin runs the type, and the caller answers `null` as it
+ *   would for any step it does not know.
+ *
+ * A type the engine runs itself never reaches this registry, so a
+ * registration cannot replace one of the engine's own steps.
+ *
+ * Reached by path, never through a barrel: only server code asks.
+ */
+/** The automation a step belongs to, as its history and its records name it. */
+export interface ServerStepRunRef {
+    /** Which kind of automation is running — the engine's own vocabulary. */
+    kind: string;
+    /** The automation's document id. */
+    id: string;
+    /** Its name at the time of the run. */
+    name: string;
+}
+/** One step, handed to the plugin that runs it. */
+export interface ServerStepRequest {
+    /** The site the run is on. Every write is scoped to what this site may see. */
+    hostId: string;
+    /**
+     * The owning organization's billing document, already read by the gate
+     * that admitted the run, and its id beside it — so an executor gating on
+     * the plan or counting against a cap pays no second read. Null when the
+     * site has no resolvable organization, which every gate reads as Free.
+     */
+    org: unknown;
+    orgId: string | null;
+    /** The automation whose step this is. */
+    run: ServerStepRunRef;
+    /** The event the run is answering. */
+    event: string;
+    /** The event's payload: the values a step reads. */
+    payload: Record<string, unknown>;
+    /** The step exactly as it is stored. */
+    step: {
+        type: string;
+        [field: string]: unknown;
+    };
+}
+/**
+ * What one step did.
+ *
+ * Nothing set is a step that did its work. `error` is a step that did not —
+ * the run records it and goes on to the next step, so an executor answers a
+ * refusal rather than throwing one; a throw is read the same way.
+ */
+export interface ServerStepAnswer {
+    /** Why nothing was written, when nothing was — a line of the run history. */
+    error?: string;
+    /** The one fact worth carrying into the run summary: a record's name, a status. */
+    detail?: string;
+    /**
+     * An event this step's write earned, for the ENGINE to raise. Not raised
+     * by the executor: an automation whose step causes the event it listens
+     * for would otherwise run until a meter stopped it, and only the engine
+     * holds the nesting cap that stops it first.
+     */
+    emit?: {
+        event: string;
+        payload: Record<string, unknown>;
+    };
+}
+/** Runs one step of the types it was registered for. */
+export type ServerStepExecutor = (request: ServerStepRequest) => Promise<ServerStepAnswer>;
+/** The compiled declaration: which plugin runs which step type. */
+export interface ServerStepDeclaration {
+    pluginId: string;
+    /** The stored step `type`. */
+    type: string;
+}
+/** Every server step a first-party plugin declares, in `plugins.config.json` order. */
+export declare function declaredServerSteps(): readonly ServerStepDeclaration[];
+/** The declaration of this step type, or `null` for one no plugin declares. */
+export declare function declaredServerStep(type: string): ServerStepDeclaration | null;
+/** A registered executor, with the plugin it belongs to. */
+export interface RegisteredServerStepExecutor {
+    pluginId: string;
+    run: ServerStepExecutor;
+}
+/**
+ * Registers the executor of one or more step types. Returns the unregister,
+ * which removes each type only while this executor still holds it.
+ *
+ * The owner is the plugin whose register fn is running, or the `pluginId`
+ * passed for a boot declaration, where the loader's marker is not set. A
+ * registration with neither is refused; so is a type another plugin declares
+ * or already holds, because two executors for one step would each write the
+ * other's records. The same plugin registering again replaces its own (a
+ * second surface, a repeated boot). Nothing is registered unless every type
+ * is accepted.
+ */
+export declare function registerServerStepExecutor(types: readonly string[], run: ServerStepExecutor, options?: {
+    pluginId?: string;
+}): () => void;
+/** The executor registered for a step type, with its owner, or `null`. Never repairs. */
+export declare function registeredServerStepExecutor(type: string): RegisteredServerStepExecutor | null;
+/** Only for specs: forgets every registered executor. */
+export declare function resetServerStepExecutorsForTests(): void;
+/**
+ * The declared step's executor was not registered, even after the app's
+ * declarations step ran again. Its message is the step's line in the run
+ * history, so it says what happened in the words a site owner reads.
+ */
+export declare class ServerStepUnavailableError extends Error {
+    readonly declaration: ServerStepDeclaration;
+    constructor(declaration: ServerStepDeclaration);
+}
+/**
+ * The executor for a step type, for a run that has reached one. See the
+ * module note for the three cases: registered answers it, declared but
+ * missing throws after the repair has had its turn, and neither answers
+ * `null`.
+ */
+export declare function pluginServerStepExecutor(type: string): Promise<RegisteredServerStepExecutor | null>;

package/src/lib/plugin-manager/plugin-server-steps.js

@@ -0,0 +1,116 @@
+var _globalScope_EXECUTORS_KEY;
+/**
+ * @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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { PLUGIN_SERVER_STEPS_DECLARED } from "./first-party-plugins.generated.js";
+import { runPluginDeclarationsRepair } from "./plugin-declarations-repair.js";
+/** Every server step a first-party plugin declares, in `plugins.config.json` order. */ export function declaredServerSteps() {
+    return PLUGIN_SERVER_STEPS_DECLARED;
+}
+/** The declaration of this step type, or `null` for one no plugin declares. */ export function declaredServerStep(type) {
+    var _PLUGIN_SERVER_STEPS_DECLARED_find;
+    return (_PLUGIN_SERVER_STEPS_DECLARED_find = PLUGIN_SERVER_STEPS_DECLARED.find((declaration)=>declaration.type === type)) != null ? _PLUGIN_SERVER_STEPS_DECLARED_find : null;
+}
+/**
+ * One table per process, on `globalThis` (AGL-3412): the app registers from
+ * `instrumentation.ts`, which Next compiles apart from the routes that run
+ * steps, and a module-scoped map would be filled in one copy and read empty
+ * in the other.
+ */ const EXECUTORS_KEY = Symbol.for('@aglyn/aglyn:server-step-executors');
+const globalScope = globalThis;
+const executors = (_globalScope_EXECUTORS_KEY = globalScope[EXECUTORS_KEY]) != null ? _globalScope_EXECUTORS_KEY : globalScope[EXECUTORS_KEY] = new Map();
+const PLAIN_TYPE = /^[a-z][A-Za-z0-9]*$/;
+/**
+ * Registers the executor of one or more step types. Returns the unregister,
+ * which removes each type only while this executor still holds it.
+ *
+ * The owner is the plugin whose register fn is running, or the `pluginId`
+ * passed for a boot declaration, where the loader's marker is not set. A
+ * registration with neither is refused; so is a type another plugin declares
+ * or already holds, because two executors for one step would each write the
+ * other's records. The same plugin registering again replaces its own (a
+ * second surface, a repeated boot). Nothing is registered unless every type
+ * is accepted.
+ */ export function registerServerStepExecutor(types, run, 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 server step executor was registered with no owner: pass { pluginId } ' + 'when registering outside a plugin register fn');
+    }
+    const list = [
+        ...new Set(types.map((type)=>type.trim()))
+    ];
+    if (!list.length) throw new Error(`"${pluginId}" registered a server step executor for no step type`);
+    for (const type of list){
+        if (!PLAIN_TYPE.test(type)) {
+            throw new Error(`"${pluginId}" registered a server step executor for "${type}", which is not a plain step type`);
+        }
+        const declared = declaredServerStep(type);
+        if (declared && declared.pluginId !== pluginId) {
+            throw new Error(`server step "${type}" is declared by "${declared.pluginId}"; refused an executor from "${pluginId}"`);
+        }
+        const held = executors.get(type);
+        if (held && held.pluginId !== pluginId) {
+            throw new Error(`server step "${type}" already has an executor from "${held.pluginId}"; refused "${pluginId}"`);
+        }
+    }
+    const entry = {
+        pluginId,
+        run
+    };
+    for (const type of list)executors.set(type, entry);
+    return ()=>{
+        for (const type of list)if (executors.get(type) === entry) executors.delete(type);
+    };
+}
+/** The executor registered for a step type, with its owner, or `null`. Never repairs. */ export function registeredServerStepExecutor(type) {
+    var _executors_get;
+    return (_executors_get = executors.get(type)) != null ? _executors_get : null;
+}
+/** Only for specs: forgets every registered executor. */ export function resetServerStepExecutorsForTests() {
+    executors.clear();
+}
+/**
+ * The declared step's executor was not registered, even after the app's
+ * declarations step ran again. Its message is the step's line in the run
+ * history, so it says what happened in the words a site owner reads.
+ */ export class ServerStepUnavailableError extends Error {
+    constructor(declaration){
+        super(`the "${declaration.type}" step did not run: the plugin that runs it ` + `("${declaration.pluginId}") is not loaded on this server`), this.declaration = declaration;
+        this.name = 'ServerStepUnavailableError';
+    }
+}
+/**
+ * The executor for a step type, for a run that has reached one. See the
+ * module note for the three cases: registered answers it, declared but
+ * missing throws after the repair has had its turn, and neither answers
+ * `null`.
+ */ export async function pluginServerStepExecutor(type) {
+    const registered = executors.get(type);
+    if (registered) return registered;
+    const declared = declaredServerStep(type);
+    if (!declared) return null;
+    try {
+        await runPluginDeclarationsRepair();
+    } catch (error) {
+        console.error('[server-steps] the declarations repair failed', error);
+    }
+    const repaired = executors.get(type);
+    if (!repaired) throw new ServerStepUnavailableError(declared);
+    return repaired;
+}
+
+//# sourceMappingURL=plugin-server-steps.js.map

package/src/lib/plugin-manager/plugin-server-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-server-steps.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 { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport { PLUGIN_SERVER_STEPS_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * A SERVER STEP ANOTHER PLUGIN RUNS (AGL-3080).\n *\n * An interaction's steps are the platform's client steps plus whatever steps\n * the plugins add (`site-interactions.ts`), and every step that is not a\n * client step is the server's to run. The plugin that runs a server run — the\n * automation engine — knows its own steps. A step that acts on ANOTHER\n * plugin's records is that plugin's: writing a dataset row is the data\n * plugin's, moving a contact's stage is the CRM's. The engine used to carry\n * each of those writes itself, which made it the keeper of every plugin's\n * storage.\n *\n * So the plugin that owns a step REGISTERS ITS EXECUTOR here, by step type,\n * and the engine hands it the step when a run reaches one. The engine keeps\n * what every step shares — the step's guard, the run's order, its history,\n * the nesting cap — and the executor does the step's one write. Neither\n * imports the other: both meet at this module, which names no plugin, so a\n * marketplace plugin adds a step the same way a first-party one does.\n *\n * ## Declared, then registered — and an absent executor is refused\n *\n * The executor is registered from the owning plugin's `serverDeclarations`\n * entry, which every app runs at boot. An empty registry must not read as an\n * answer: a step whose executor never registered would otherwise fall through\n * the engine as a step nobody runs, and a run history would say the record\n * was written when it was not.\n *\n * So a first-party plugin also DECLARES the steps it runs, under\n * `serverSteps` in `plugins.config.json`, compiled into core. The three cases\n * are kept apart:\n *\n * - registered — the executor runs the step, declared or not (a marketplace\n *   plugin's steps are registered and never compiled);\n * - declared and NOT registered — the boot failed. The app's declarations\n *   step is run again ({@link runPluginDeclarationsRepair}); if the executor\n *   is still missing, {@link pluginServerStepExecutor} THROWS\n *   {@link ServerStepUnavailableError}, which the engine records as the\n *   step's failure;\n * - neither — no plugin runs the type, and the caller answers `null` as it\n *   would for any step it does not know.\n *\n * A type the engine runs itself never reaches this registry, so a\n * registration cannot replace one of the engine's own steps.\n *\n * Reached by path, never through a barrel: only server code asks.\n */\n\n/** The automation a step belongs to, as its history and its records name it. */\nexport interface ServerStepRunRef {\n  /** Which kind of automation is running — the engine's own vocabulary. */\n  kind: string\n  /** The automation's document id. */\n  id: string\n  /** Its name at the time of the run. */\n  name: string\n}\n\n/** One step, handed to the plugin that runs it. */\nexport interface ServerStepRequest {\n  /** The site the run is on. Every write is scoped to what this site may see. */\n  hostId: string\n  /**\n   * The owning organization's billing document, already read by the gate\n   * that admitted the run, and its id beside it — so an executor gating on\n   * the plan or counting against a cap pays no second read. Null when the\n   * site has no resolvable organization, which every gate reads as Free.\n   */\n  org: unknown\n  orgId: string | null\n  /** The automation whose step this is. */\n  run: ServerStepRunRef\n  /** The event the run is answering. */\n  event: string\n  /** The event's payload: the values a step reads. */\n  payload: Record<string, unknown>\n  /** The step exactly as it is stored. */\n  step: { type: string; [field: string]: unknown }\n}\n\n/**\n * What one step did.\n *\n * Nothing set is a step that did its work. `error` is a step that did not —\n * the run records it and goes on to the next step, so an executor answers a\n * refusal rather than throwing one; a throw is read the same way.\n */\nexport interface ServerStepAnswer {\n  /** Why nothing was written, when nothing was — a line of the run history. */\n  error?: string\n  /** The one fact worth carrying into the run summary: a record's name, a status. */\n  detail?: string\n  /**\n   * An event this step's write earned, for the ENGINE to raise. Not raised\n   * by the executor: an automation whose step causes the event it listens\n   * for would otherwise run until a meter stopped it, and only the engine\n   * holds the nesting cap that stops it first.\n   */\n  emit?: { event: string; payload: Record<string, unknown> }\n}\n\n/** Runs one step of the types it was registered for. */\nexport type ServerStepExecutor = (request: ServerStepRequest) => Promise<ServerStepAnswer>\n\n/** The compiled declaration: which plugin runs which step type. */\nexport interface ServerStepDeclaration {\n  pluginId: string\n  /** The stored step `type`. */\n  type: string\n}\n\n/** Every server step a first-party plugin declares, in `plugins.config.json` order. */\nexport function declaredServerSteps(): readonly ServerStepDeclaration[] {\n  return PLUGIN_SERVER_STEPS_DECLARED\n}\n\n/** The declaration of this step type, or `null` for one no plugin declares. */\nexport function declaredServerStep(type: string): ServerStepDeclaration | null {\n  return PLUGIN_SERVER_STEPS_DECLARED.find((declaration) => declaration.type === type) ?? null\n}\n\n/** A registered executor, with the plugin it belongs to. */\nexport interface RegisteredServerStepExecutor {\n  pluginId: string\n  run: ServerStepExecutor\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): the app registers from\n * `instrumentation.ts`, which Next compiles apart from the routes that run\n * steps, and a module-scoped map would be filled in one copy and read empty\n * in the other.\n */\nconst EXECUTORS_KEY = Symbol.for('@aglyn/aglyn:server-step-executors')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [EXECUTORS_KEY]?: Map<string, RegisteredServerStepExecutor>\n}\n\nconst executors: Map<string, RegisteredServerStepExecutor> =\n  globalScope[EXECUTORS_KEY] ?? (globalScope[EXECUTORS_KEY] = new Map())\n\nconst PLAIN_TYPE = /^[a-z][A-Za-z0-9]*$/\n\n/**\n * Registers the executor of one or more step types. Returns the unregister,\n * which removes each type only while this executor still holds it.\n *\n * The owner is the plugin whose register fn is running, or the `pluginId`\n * passed for a boot declaration, where the loader's marker is not set. A\n * registration with neither is refused; so is a type another plugin declares\n * or already holds, because two executors for one step would each write the\n * other's records. The same plugin registering again replaces its own (a\n * second surface, a repeated boot). Nothing is registered unless every type\n * is accepted.\n */\nexport function registerServerStepExecutor(\n  types: readonly string[],\n  run: ServerStepExecutor,\n  options?: { pluginId?: string },\n): () => void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a server step executor was registered with no owner: pass { pluginId } ' +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const list = [...new Set(types.map((type) => type.trim()))]\n  if (!list.length) throw new Error(`\"${pluginId}\" registered a server step executor for no step type`)\n  for (const type of list) {\n    if (!PLAIN_TYPE.test(type)) {\n      throw new Error(`\"${pluginId}\" registered a server step executor for \"${type}\", which is not a plain step type`)\n    }\n    const declared = declaredServerStep(type)\n    if (declared && declared.pluginId !== pluginId) {\n      throw new Error(\n        `server step \"${type}\" is declared by \"${declared.pluginId}\"; refused an executor from \"${pluginId}\"`,\n      )\n    }\n    const held = executors.get(type)\n    if (held && held.pluginId !== pluginId) {\n      throw new Error(\n        `server step \"${type}\" already has an executor from \"${held.pluginId}\"; refused \"${pluginId}\"`,\n      )\n    }\n  }\n  const entry: RegisteredServerStepExecutor = { pluginId, run }\n  for (const type of list) executors.set(type, entry)\n  return () => {\n    for (const type of list) if (executors.get(type) === entry) executors.delete(type)\n  }\n}\n\n/** The executor registered for a step type, with its owner, or `null`. Never repairs. */\nexport function registeredServerStepExecutor(type: string): RegisteredServerStepExecutor | null {\n  return executors.get(type) ?? null\n}\n\n/** Only for specs: forgets every registered executor. */\nexport function resetServerStepExecutorsForTests(): void {\n  executors.clear()\n}\n\n/**\n * The declared step's executor was not registered, even after the app's\n * declarations step ran again. Its message is the step's line in the run\n * history, so it says what happened in the words a site owner reads.\n */\nexport class ServerStepUnavailableError extends Error {\n  constructor(readonly declaration: ServerStepDeclaration) {\n    super(\n      `the \"${declaration.type}\" step did not run: the plugin that runs it ` +\n        `(\"${declaration.pluginId}\") is not loaded on this server`,\n    )\n    this.name = 'ServerStepUnavailableError'\n  }\n}\n\n/**\n * The executor for a step type, for a run that has reached one. See the\n * module note for the three cases: registered answers it, declared but\n * missing throws after the repair has had its turn, and neither answers\n * `null`.\n */\nexport async function pluginServerStepExecutor(\n  type: string,\n): Promise<RegisteredServerStepExecutor | null> {\n  const registered = executors.get(type)\n  if (registered) return registered\n  const declared = declaredServerStep(type)\n  if (!declared) return null\n  try {\n    await runPluginDeclarationsRepair()\n  } catch (error) {\n    console.error('[server-steps] the declarations repair failed', error)\n  }\n  const repaired = executors.get(type)\n  if (!repaired) throw new ServerStepUnavailableError(declared)\n  return repaired\n}\n"],"names":["globalScope","getRegisteringPluginId","PLUGIN_SERVER_STEPS_DECLARED","runPluginDeclarationsRepair","declaredServerSteps","declaredServerStep","type","find","declaration","EXECUTORS_KEY","Symbol","for","globalThis","executors","Map","PLAIN_TYPE","registerServerStepExecutor","types","run","options","pluginId","trim","Error","list","Set","map","length","test","declared","held","get","entry","set","delete","registeredServerStepExecutor","resetServerStepExecutorsForTests","clear","ServerStepUnavailableError","name","pluginServerStepExecutor","registered","error","console","repaired"],"mappings":"IAgKEA;AAhKF;;;;;;;;;;;;;;;CAeC,GAED,SAASC,sBAAsB,QAAQ,qCAAiC;AACxE,SAASC,4BAA4B,QAAQ,qCAAiC;AAC9E,SAASC,2BAA2B,QAAQ,kCAA8B;AAgH1E,qFAAqF,GACrF,OAAO,SAASC;IACd,OAAOF;AACT;AAEA,6EAA6E,GAC7E,OAAO,SAASG,mBAAmBC,IAAY;QACtCJ;IAAP,QAAOA,qCAAAA,6BAA6BK,IAAI,CAAC,CAACC,cAAgBA,YAAYF,IAAI,KAAKA,iBAAxEJ,qCAAiF;AAC1F;AAQA;;;;;CAKC,GACD,MAAMO,gBAAgBC,OAAOC,GAAG,CAAC;AAEjC,MAAMX,cAAcY;AAIpB,MAAMC,aACJb,6BAAAA,WAAW,CAACS,cAAc,YAA1BT,6BAA+BA,WAAW,CAACS,cAAc,GAAG,IAAIK;AAElE,MAAMC,aAAa;AAEnB;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,2BACdC,KAAwB,EACxBC,GAAuB,EACvBC,OAA+B;QAEblB,MAAAA;IAAlB,MAAMmB,WAAW,EAACnB,QAAAA,0BAAAA,oCAAAA,0BAA4BkB,2BAAAA,QAASC,QAAQ,YAA7CnB,OAAiD,IAAIoB,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,4EACE;IAEN;IACA,MAAMC,OAAO;WAAI,IAAIC,IAAIP,MAAMQ,GAAG,CAAC,CAACnB,OAASA,KAAKe,IAAI;KAAK;IAC3D,IAAI,CAACE,KAAKG,MAAM,EAAE,MAAM,IAAIJ,MAAM,CAAC,CAAC,EAAEF,SAAS,oDAAoD,CAAC;IACpG,KAAK,MAAMd,QAAQiB,KAAM;QACvB,IAAI,CAACR,WAAWY,IAAI,CAACrB,OAAO;YAC1B,MAAM,IAAIgB,MAAM,CAAC,CAAC,EAAEF,SAAS,yCAAyC,EAAEd,KAAK,iCAAiC,CAAC;QACjH;QACA,MAAMsB,WAAWvB,mBAAmBC;QACpC,IAAIsB,YAAYA,SAASR,QAAQ,KAAKA,UAAU;YAC9C,MAAM,IAAIE,MACR,CAAC,aAAa,EAAEhB,KAAK,kBAAkB,EAAEsB,SAASR,QAAQ,CAAC,6BAA6B,EAAEA,SAAS,CAAC,CAAC;QAEzG;QACA,MAAMS,OAAOhB,UAAUiB,GAAG,CAACxB;QAC3B,IAAIuB,QAAQA,KAAKT,QAAQ,KAAKA,UAAU;YACtC,MAAM,IAAIE,MACR,CAAC,aAAa,EAAEhB,KAAK,gCAAgC,EAAEuB,KAAKT,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;QAElG;IACF;IACA,MAAMW,QAAsC;QAAEX;QAAUF;IAAI;IAC5D,KAAK,MAAMZ,QAAQiB,KAAMV,UAAUmB,GAAG,CAAC1B,MAAMyB;IAC7C,OAAO;QACL,KAAK,MAAMzB,QAAQiB,KAAM,IAAIV,UAAUiB,GAAG,CAACxB,UAAUyB,OAAOlB,UAAUoB,MAAM,CAAC3B;IAC/E;AACF;AAEA,uFAAuF,GACvF,OAAO,SAAS4B,6BAA6B5B,IAAY;QAChDO;IAAP,QAAOA,iBAAAA,UAAUiB,GAAG,CAACxB,iBAAdO,iBAAuB;AAChC;AAEA,uDAAuD,GACvD,OAAO,SAASsB;IACdtB,UAAUuB,KAAK;AACjB;AAEA;;;;CAIC,GACD,OAAO,MAAMC,mCAAmCf;IAC9C,YAAY,AAASd,WAAkC,CAAE;QACvD,KAAK,CACH,CAAC,KAAK,EAAEA,YAAYF,IAAI,CAAC,4CAA4C,CAAC,GACpE,CAAC,EAAE,EAAEE,YAAYY,QAAQ,CAAC,+BAA+B,CAAC,QAH3CZ,cAAAA;QAKnB,IAAI,CAAC8B,IAAI,GAAG;IACd;AACF;AAEA;;;;;CAKC,GACD,OAAO,eAAeC,yBACpBjC,IAAY;IAEZ,MAAMkC,aAAa3B,UAAUiB,GAAG,CAACxB;IACjC,IAAIkC,YAAY,OAAOA;IACvB,MAAMZ,WAAWvB,mBAAmBC;IACpC,IAAI,CAACsB,UAAU,OAAO;IACtB,IAAI;QACF,MAAMzB;IACR,EAAE,OAAOsC,OAAO;QACdC,QAAQD,KAAK,CAAC,iDAAiDA;IACjE;IACA,MAAME,WAAW9B,UAAUiB,GAAG,CAACxB;IAC/B,IAAI,CAACqC,UAAU,MAAM,IAAIN,2BAA2BT;IACpD,OAAOe;AACT"}

package/src/lib/plugin-manager/plugin-site-beacons.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @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 own beacons, posted to the platform's site collector.
+ *
+ * A published page has one place to report what visitors did — the
+ * collector behind `sendAnalyticsBeacon` — and that endpoint owns what every
+ * beacon owes before anything is counted: the host must exist, a platform,
+ * org or site lockdown refuses it silently, and the per-address rate limit
+ * applies. What a plugin's site runtime reports beyond a pageview (an
+ * announcement bar seen, a popup dismissed) is the plugin's to count, in its
+ * own documents.
+ *
+ * So the plugin registers a beacon by the body FIELD that marks it as its
+ * own, and the collector hands a beacon carrying that field to the plugin
+ * after its own gates, then answers 204 without counting a pageview. The
+ * field is the beacon's whole claim: one owner per field, refused naming
+ * both, and the incumbent keeps serving.
+ *
+ * Registered from the plugin's `serverDeclarations`, so every server process
+ * has it from boot; keep the registration light and import the counting
+ * code on the first beacon.
+ */
+/** What the collector hands the owner, after the host and lockdown gates. */
+export interface PluginSiteBeaconRequest {
+    hostId: string;
+    /** The collector's day bucket, `YYYY-MM-DD` in UTC. */
+    day: string;
+    /**
+     * When the site's analytics document for {@link day} expires: the
+     * platform's retention. An owner that writes into that document stamps it,
+     * so a document created by its beacons alone is still swept.
+     */
+    dayExpiresAt: Date;
+    /** The beacon as the browser sent it. Untrusted: validate every field read. */
+    body: Readonly<Record<string, unknown>>;
+}
+export interface PluginSiteBeacon {
+    /** The body field whose non-empty string marks a beacon as this plugin's. */
+    field: string;
+    /** Counts one beacon. A throw is logged by the collector, never surfaced. */
+    count(request: PluginSiteBeaconRequest): Promise<void>;
+}
+export declare const PLUGIN_SITE_BEACONS: import("./plugin-services").PluginServiceContract<PluginSiteBeacon>;
+/**
+ * Registers a beacon. The owner is the loader's marker inside a register fn,
+ * else `options.pluginId`; with neither the registration throws. A field
+ * another plugin claims throws naming both.
+ */
+export declare function registerPluginSiteBeacon(beacon: PluginSiteBeacon, options?: {
+    pluginId?: string;
+}): void;
+/** The owner of a beacon body, or `null` when no registered field marks it. */
+export declare function pluginSiteBeaconFor(body: Readonly<Record<string, unknown>>): {
+    pluginId: string;
+    beacon: PluginSiteBeacon;
+} | null;