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

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

@@ -0,0 +1,51 @@
+/**
+ * @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_INDEXES = definePluginServiceContract('core.record-index', {
+    multiple: true
+});
+/**
+ * Publishes the index for one record kind. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A kind another plugin keeps throws naming both.
+ */ export function registerPluginRecordIndex(kind, index, options) {
+    var _ref, _getRegisteringPluginId;
+    const key = kind.trim();
+    if (!key) throw new Error('a record index 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 index for "${key}" was registered with no owner`);
+    }
+    const incumbent = resolvePluginServices(PLUGIN_RECORD_INDEXES).find((entry)=>entry.key === key);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`record kind "${key}" is already indexed by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_RECORD_INDEXES, index, {
+        pluginId,
+        key
+    });
+}
+/** The index for a kind, with the plugin that keeps it, or `null` when none does here. */ export function pluginRecordIndex(kind) {
+    const key = kind.trim();
+    const entry = resolvePluginServices(PLUGIN_RECORD_INDEXES).find((one)=>one.key === key);
+    return entry ? {
+        pluginId: entry.pluginId,
+        index: entry.impl
+    } : null;
+}
+
+//# sourceMappingURL=plugin-record-index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-index.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 {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * A plugin's records, listed and read for ANOTHER plugin (AGL-3080).\n *\n * A plugin that works over records it does not own — an AI job enriching a\n * site's products, a composer binding the products an email names — used to\n * read the owner's Firestore collection itself: the path, the field names,\n * what \"deleted\" looks like. That is a plugin's storage reached around the\n * plugin, invisible to `check:lib-boundaries` because a collection name is\n * not an import, and it breaks the day the owner changes a field.\n *\n * So the owner publishes an INDEX for each record kind it keeps: `list` names\n * the live records of a scope, `get` reads one — each as an id, a name and the\n * FACTS the owner chooses to share, in a shape its registration documents.\n * The reader never learns where the records are stored or what a deleted one\n * looks like; the owner answers only live records.\n *\n * Its siblings: `plugin-record-cards` (how one record LOOKS, for a campaign\n * sender) and `plugin-record-facts` (what a record SAYS, for a summary);\n * `plugin-resource-drafts` is the WRITE side. This is the side that finds and\n * reads records to work on.\n *\n * ## Not registered is an answer\n *\n * No index for a kind means no plugin keeps it in this process — 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. Registered from the\n * owner's server declarations, so every server process that boots the\n * declarations has it.\n *\n * ## One index per kind\n *\n * A second plugin registering an index for a kind another plugin already\n * keeps is refused, naming both, and the incumbent keeps serving.\n */\n\n/** One record, as its owner shares it. */\nexport interface PluginIndexedRecord {\n  id: string\n  /** What a person calls it. Never empty: the owner leaves an unnamed record out. */\n  name: string\n  /** What else the owner shares, in the shape its registration documents. */\n  facts: Readonly<Record<string, unknown>>\n}\n\n/** Which records a reader asks about. */\nexport interface PluginRecordIndexScope {\n  /** The organization the records belong to, where the kind is org-scoped. */\n  orgId?: string | null\n  /** The site the records belong to, where the kind is site-scoped. */\n  hostId?: string | null\n}\n\nexport interface PluginRecordIndex {\n  /**\n   * The live records of the scope, at most `limit`, in the owner's order.\n   * `truncated` says the scope holds more than were answered.\n   */\n  list(\n    request: PluginRecordIndexScope & { limit: number },\n  ): Promise<{ records: PluginIndexedRecord[]; truncated: boolean }>\n  /** One live record, or `null` — gone, deleted, or not the scope's. */\n  get(request: PluginRecordIndexScope & { id: string }): Promise<PluginIndexedRecord | null>\n}\n\nexport const PLUGIN_RECORD_INDEXES = definePluginServiceContract<PluginRecordIndex>(\n  'core.record-index',\n  { multiple: true },\n)\n\n/**\n * Publishes the index for one record kind. The owner is the loader's marker\n * when a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A kind another plugin keeps throws naming both.\n */\nexport function registerPluginRecordIndex(\n  kind: string,\n  index: PluginRecordIndex,\n  options?: { pluginId?: string },\n): void {\n  const key = kind.trim()\n  if (!key) throw new Error('a record index needs a record kind')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(`the record index for \"${key}\" was registered with no owner`)\n  }\n  const incumbent = resolvePluginServices(PLUGIN_RECORD_INDEXES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `record kind \"${key}\" is already indexed by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RECORD_INDEXES, index, { pluginId, key })\n}\n\n/** The index for a kind, with the plugin that keeps it, or `null` when none does here. */\nexport function pluginRecordIndex(\n  kind: string,\n): { pluginId: string; index: PluginRecordIndex } | null {\n  const key = kind.trim()\n  const entry = resolvePluginServices(PLUGIN_RECORD_INDEXES).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, index: entry.impl } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_INDEXES","multiple","registerPluginRecordIndex","kind","index","options","key","trim","Error","pluginId","incumbent","find","entry","pluginRecordIndex","one","impl"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAkE1B,OAAO,MAAMC,wBAAwBH,4BACnC,qBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,0BACdC,IAAY,EACZC,KAAwB,EACxBC,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,sBAAsB,EAAEF,IAAI,8BAA8B,CAAC;IAC9E;IACA,MAAMI,YAAYX,sBAAsBC,uBAAuBW,IAAI,CACjE,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaA,UAAUD,QAAQ,KAAKA,UAAU;QAChD,MAAM,IAAID,MACR,CAAC,aAAa,EAAEF,IAAI,yBAAyB,EAAEI,UAAUD,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAE/F;IACAX,sBAAsBE,uBAAuBI,OAAO;QAAEK;QAAUH;IAAI;AACtE;AAEA,wFAAwF,GACxF,OAAO,SAASO,kBACdV,IAAY;IAEZ,MAAMG,MAAMH,KAAKI,IAAI;IACrB,MAAMK,QAAQb,sBAAsBC,uBAAuBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACrF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,OAAOQ,MAAMG,IAAI;IAAC,IAAI;AACnE"}

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

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

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-record-written.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 record changed": the one signal every server writer of an org record
+ * already gives (AGL-3336).
+ *
+ * The capture doors, the conversion, the merge, an automation's step, the
+ * record system's own routes — each of them, after it writes a record under
+ * `orgs/{orgId}/{collection}`, restamps the fields that record's list
+ * queries (`restampCrmListFieldsAt`). That restamp is the only place all of
+ * them pass, so it is where a plugin that needs to act on the record AFTER
+ * any write — re-evaluating the sharing rules that match it, say — is told.
+ * A listener registered here is the alternative to editing every writer.
+ *
+ * ## What a listener may do
+ *
+ * Read the record and write it again, in its own transaction. It must not
+ * call back into the restamp, which is what would loop; the restamp
+ * notifies after its own write, once. A listener that throws is logged and
+ * the next one still runs: the write it is told about already landed.
+ */
+/**
+ * A written record, by its path: the listener opens its own reference, so
+ * core names no database SDK.
+ */
+export interface PluginRecordWrittenEvent {
+    /** `orgs/{orgId}/{collection}/{id}`. */
+    path: string;
+    /** The collection's name under the org. */
+    collection: string;
+}
+export type PluginRecordWrittenListener = (event: PluginRecordWrittenEvent) => Promise<void>;
+export declare const PLUGIN_RECORD_WRITTEN: import("./plugin-services").PluginServiceContract<PluginRecordWrittenListener>;
+/**
+ * Registers a listener. The owner is the loader's marker when a register fn
+ * is running, else `options.pluginId`; registering twice under one key
+ * replaces in place.
+ */
+export declare function registerPluginRecordWrittenListener(listener: PluginRecordWrittenListener, options?: {
+    pluginId?: string;
+    key?: string;
+}): void;
+/** Tells every listener. Never throws. */
+export declare function notifyPluginRecordWritten(event: PluginRecordWrittenEvent): Promise<void>;

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

@@ -0,0 +1,42 @@
+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_RECORD_WRITTEN = definePluginServiceContract('core.record-written', {
+    multiple: true
+});
+/**
+ * Registers a listener. The owner is the loader's marker when a register fn
+ * is running, else `options.pluginId`; registering twice under one key
+ * replaces in place.
+ */ export function registerPluginRecordWrittenListener(listener, options) {
+    registerPluginService(PLUGIN_RECORD_WRITTEN, listener, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, (options == null ? void 0 : options.key) ? {
+        key: options.key
+    } : {}));
+}
+/** Tells every listener. Never throws. */ export async function notifyPluginRecordWritten(event) {
+    for (const entry of resolvePluginServices(PLUGIN_RECORD_WRITTEN)){
+        try {
+            await entry.impl(event);
+        } catch (error) {
+            console.error(`[record-written] ${entry.pluginId} failed on ${event.path}`, error);
+        }
+    }
+}
+
+//# sourceMappingURL=plugin-record-written.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-written.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 record changed\": the one signal every server writer of an org record\n * already gives (AGL-3336).\n *\n * The capture doors, the conversion, the merge, an automation's step, the\n * record system's own routes — each of them, after it writes a record under\n * `orgs/{orgId}/{collection}`, restamps the fields that record's list\n * queries (`restampCrmListFieldsAt`). That restamp is the only place all of\n * them pass, so it is where a plugin that needs to act on the record AFTER\n * any write — re-evaluating the sharing rules that match it, say — is told.\n * A listener registered here is the alternative to editing every writer.\n *\n * ## What a listener may do\n *\n * Read the record and write it again, in its own transaction. It must not\n * call back into the restamp, which is what would loop; the restamp\n * notifies after its own write, once. A listener that throws is logged and\n * the next one still runs: the write it is told about already landed.\n */\n\n/**\n * A written record, by its path: the listener opens its own reference, so\n * core names no database SDK.\n */\nexport interface PluginRecordWrittenEvent {\n  /** `orgs/{orgId}/{collection}/{id}`. */\n  path: string\n  /** The collection's name under the org. */\n  collection: string\n}\n\nexport type PluginRecordWrittenListener = (event: PluginRecordWrittenEvent) => Promise<void>\n\nexport const PLUGIN_RECORD_WRITTEN = definePluginServiceContract<PluginRecordWrittenListener>(\n  'core.record-written',\n  { multiple: true },\n)\n\n/**\n * Registers a listener. The owner is the loader's marker when a register fn\n * is running, else `options.pluginId`; registering twice under one key\n * replaces in place.\n */\nexport function registerPluginRecordWrittenListener(\n  listener: PluginRecordWrittenListener,\n  options?: { pluginId?: string; key?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_WRITTEN, listener, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    ...(options?.key ? { key: options.key } : {}),\n  })\n}\n\n/** Tells every listener. Never throws. */\nexport async function notifyPluginRecordWritten(event: PluginRecordWrittenEvent): Promise<void> {\n  for (const entry of resolvePluginServices(PLUGIN_RECORD_WRITTEN)) {\n    try {\n      await entry.impl(event)\n    } catch (error) {\n      console.error(\n        `[record-written] ${entry.pluginId} failed on ${event.path}`,\n        error,\n      )\n    }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_WRITTEN","multiple","registerPluginRecordWrittenListener","listener","options","pluginId","key","notifyPluginRecordWritten","event","entry","impl","error","console","path"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAmC1B,OAAO,MAAMC,wBAAwBH,4BACnC,uBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,oCACdC,QAAqC,EACrCC,OAA6C;IAE7CN,sBAAsBE,uBAAuBG,UAAU,aACjDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC,GACtDD,CAAAA,2BAAAA,QAASE,GAAG,IAAG;QAAEA,KAAKF,QAAQE,GAAG;IAAC,IAAI,CAAC;AAE/C;AAEA,wCAAwC,GACxC,OAAO,eAAeC,0BAA0BC,KAA+B;IAC7E,KAAK,MAAMC,SAASV,sBAAsBC,uBAAwB;QAChE,IAAI;YACF,MAAMS,MAAMC,IAAI,CAACF;QACnB,EAAE,OAAOG,OAAO;YACdC,QAAQD,KAAK,CACX,CAAC,iBAAiB,EAAEF,MAAMJ,QAAQ,CAAC,WAAW,EAAEG,MAAMK,IAAI,EAAE,EAC5DF;QAEJ;IACF;AACF"}