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

package/src/lib/plugin-manager/plugin-person-records.d.ts

@@ -0,0 +1,275 @@
+/**
+ * @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.
+ */
+/**
+ * THE PEOPLE A WORKSPACE KEEPS, asked for by the plugins that do not keep
+ * them (AGL-3080).
+ *
+ * `plugin-contact-capture` is how a silo hands somebody it MET to the plugin
+ * that keeps people. This is the other half: a plugin that has an address, or
+ * a record the owner handed it, and needs the person behind it.
+ *
+ *  - a flow email asking whether the person agreed to marketing mail;
+ *  - a campaign filling in the name a merge tag reads;
+ *  - a refund taking money back off what a customer is worth;
+ *  - an automation filing somebody under a campaign;
+ *  - a sales sequence reading the people a rep enrolls.
+ *
+ * Each of those used to open the owner's collection itself — its path, its
+ * address index, which site may see which document — and broke the day the
+ * owner changed one. None of it is visible to `check:lib-boundaries`, because
+ * a collection name is not an import.
+ *
+ * So the plugin that keeps people registers ONE service here, and every rule
+ * stays the owner's: how an address is keyed, what an alternate address a
+ * merge folded in still answers to, which site may see which record, and what
+ * a refund or a filing writes.
+ *
+ * ## What a record is
+ *
+ * A {@link PluginPersonRecord} is a kind and an id in the owner's own words —
+ * the words `plugin-record-routes` addresses the record by — the person's
+ * primary address, and the record as the owner stores it. The fields the
+ * PLATFORM defines on a person record (the consent basis
+ * `marketing-consent.ts` reads, the `emailState` verdict, the `visibleTo`
+ * scope) are read off it with the platform's own readers; anything else is
+ * the owner's and is documented with its registration.
+ *
+ * ## Not registered is an answer
+ *
+ * Every reader answers `null` when no plugin keeps people in this process,
+ * which is a workspace with no record system and is not "nobody found". A
+ * caller treats the two differently: a send with no record system has no
+ * basis to read, which is not the same as a person who declined.
+ *
+ * A single-implementation contract: a workspace keeps one set of people, so
+ * a second plugin's service is refused naming both and the incumbent keeps
+ * serving. Registered from the owner's server declarations, so it is in place
+ * in a process that never loaded the owner's API surface.
+ *
+ * ## The caller proves who is asking
+ *
+ * Like the capture and timeline seams, the registry authenticates nobody. A
+ * caller decides in its own terms, before it asks, that the read or the write
+ * is the workspace's to make.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`.
+ */
+/** A person record, by the owner's word for its kind and its id. */
+export interface PluginPersonRecordRef {
+    /** The owner's word for the record — the kind `plugin-record-routes` addresses it by. */
+    kind: string;
+    id: string;
+}
+/** One person record, as the plugin that keeps people shares it. */
+export interface PluginPersonRecord extends PluginPersonRecordRef {
+    /** The record's primary address, normalized, or `null` when it holds none. */
+    email: string | null;
+    /**
+     * The record as the owner stores it. The platform's own fields on it are
+     * read with the platform's readers; the rest is the owner's, documented
+     * with its registration.
+     */
+    data: Readonly<Record<string, unknown>>;
+}
+/** Who to find by address, and where. */
+export interface PluginPersonFindRequest {
+    /**
+     * The organization whose people are searched. A caller that knows only the
+     * site names `hostId` instead, and the owner reads the organization off it.
+     */
+    orgId?: string | null;
+    /** The site asking. Required with {@link onlyVisibleToSite}. */
+    hostId?: string | null;
+    /** Raw: the owner normalizes it, alternate addresses included. */
+    email: unknown;
+    /**
+     * Answer only a record `hostId` may see. A record the address names but the
+     * site cannot see is `null`, never a reason to look further — one address
+     * names one person.
+     */
+    onlyVisibleToSite?: boolean;
+    /**
+     * Look at every kind of record the owner keeps a person as, in the owner's
+     * order, instead of only the one a known person is held as. A send deciding
+     * whether it may mail somebody asks for this: a person not yet qualified is
+     * still a person whose answer counts.
+     */
+    anyKind?: boolean;
+}
+/** Records to read, by the refs the owner handed out. */
+export interface PluginPersonReadRequest {
+    orgId: string;
+    records: readonly PluginPersonRecordRef[];
+}
+/**
+ * File a person under containers (`plugin-containers.ts`) — the merchant's
+ * own act, through an automation step or an enrollment. Filing is not
+ * consent.
+ */
+export interface PluginPersonFileRequest {
+    /** The site filing them: the person is filed under the containers as this site holds them. */
+    hostId: string;
+    orgId?: string | null;
+    record: PluginPersonRecordRef;
+    /** The container kind, as `plugin-containers.ts` declares it. */
+    containerKind: string;
+    ids: readonly string[];
+}
+/**
+ * Money handed back to a person a silo took it from: a refund, or a dispute
+ * lost. The owner records it beside what the person is worth; it never
+ * creates a person to hold it.
+ */
+export interface PluginPersonRefundRequest {
+    /** The site the money was taken on. */
+    hostId: string;
+    /** The buyer's address as the sale recorded it. Raw: the owner normalizes it. */
+    email: unknown;
+    /** Cents reversed by THIS refund, never the sale's total. */
+    amountCents: number;
+    /** The silo's own document the money went back on — what a timeline entry points at. */
+    refId: string;
+    /** True only for the refund that moved the sale into fully refunded. */
+    closedTheSale: boolean;
+    /** `chargeback` for a dispute lost; a refund otherwise. */
+    reason?: 'refund' | 'chargeback';
+}
+/**
+ * What became of a refund. `recorded`; `no-email` for a sale that never
+ * named its buyer; `no-person` for an address the workspace holds nobody at;
+ * `gone` for a person removed between the sale and the refund.
+ */
+export type PluginPersonRefundOutcome = 'recorded' | 'no-email' | 'no-person' | 'gone';
+/**
+ * The people a saved selection the owner keeps names — a saved view of one of
+ * its lists — taken for one site, as the people a sequence or a send works
+ * through.
+ */
+export interface PluginPersonViewRequest {
+    orgId: string;
+    /** The site the people are taken for: only records it holds are answered. */
+    hostId: string;
+    /** The view, by the id the owner's record list handed out (`plugin-record-lists`). */
+    viewId: string;
+    /** The member asking: a view they may not list does not exist for them. */
+    viewerUid: string;
+    /** The most people answered. */
+    limit: number;
+}
+export type PluginPersonViewPeople = {
+    ok: true;
+    people: PluginPersonRecordRef[];
+    /** How many the view selects, as far as the owner read it. */
+    total: number;
+    /** The view selects more than `limit`, or more than the owner read. */
+    truncated: boolean;
+} | {
+    ok: false;
+    /**
+     * `not-found`: no such view, or not this member's to list.
+     * `not-people`: a view of something that is not people.
+     * `unsupported`: the view narrows by something the owner cannot apply
+     * outside its own list, so taking it would select more people than the
+     * view shows; `unsupported` names what, in the owner's words.
+     */
+    reason: 'not-found' | 'not-people' | 'unsupported';
+    unsupported?: string[];
+};
+/** Records to ask about, by the refs the owner handed out. */
+export interface PluginPersonWroteInRequest {
+    orgId: string;
+    records: readonly PluginPersonRecordRef[];
+}
+export interface PluginPersonRecords {
+    /** The person an address belongs to, or `null`. A read; may throw, and the caller decides which way a failure falls. */
+    find(request: PluginPersonFindRequest): Promise<PluginPersonRecord | null>;
+    /** The records named, in the order asked; `null` for one that is gone. */
+    read(request: PluginPersonReadRequest): Promise<Array<PluginPersonRecord | null>>;
+    /**
+     * Files the person under the containers. Optional: an owner that keeps no
+     * containers answers nothing. `filed: false` is a record the owner could
+     * not find for the site.
+     */
+    fileUnder?(request: PluginPersonFileRequest): Promise<{
+        filed: boolean;
+    }>;
+    /** Records money handed back. Optional. Never throws: the money has already moved. */
+    recordRefund?(request: PluginPersonRefundRequest): Promise<PluginPersonRefundOutcome>;
+    /** The people a saved view selects for a site. Optional: an owner that keeps no views answers nothing. */
+    peopleInView?(request: PluginPersonViewRequest): Promise<PluginPersonViewPeople>;
+    /**
+     * Whether each person has ever written to the workspace — an email they
+     * sent, on their record — in the order asked; `null` for one the owner
+     * could not answer. Optional.
+     */
+    wroteIn?(request: PluginPersonWroteInRequest): Promise<Array<boolean | null>>;
+}
+export declare const PLUGIN_PERSON_RECORDS: import("./plugin-services").PluginServiceContract<PluginPersonRecords>;
+/**
+ * Registers the plugin that keeps people. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws, and a second plugin's service is refused naming both —
+ * the incumbent keeps serving.
+ */
+export declare function registerPluginPersonRecords(records: PluginPersonRecords, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginPersonRecords {
+    /** The plugin that keeps people. */
+    pluginId: string;
+    records: PluginPersonRecords;
+}
+/** The service with its owner, or `null` when no plugin keeps people here. */
+export declare function pluginPersonRecords(): ResolvedPluginPersonRecords | null;
+/**
+ * The person an address belongs to, or `null` — for nobody found, and for a
+ * workspace no plugin keeps people for. A failed read is the owner's to
+ * throw and the caller's to decide which way it falls.
+ */
+export declare function findPluginPerson(request: PluginPersonFindRequest): Promise<PluginPersonRecord | null>;
+/**
+ * The records named, in the order asked, `null` for each that is gone — or
+ * `null` whole when no plugin keeps people here, which is not "all gone".
+ */
+export declare function readPluginPeople(request: PluginPersonReadRequest): Promise<Array<PluginPersonRecord | null> | null>;
+/**
+ * Files the person under the containers through whichever plugin keeps
+ * people, or answers `null` when none does or the one that does keeps no
+ * containers. A failed write throws, as the caller's own write would have.
+ */
+export declare function filePluginPersonUnder(request: PluginPersonFileRequest): Promise<{
+    filed: boolean;
+} | null>;
+/**
+ * Hands a refund to whichever plugin keeps people, or answers `null` when
+ * none does. Never throws: every caller has already moved the money and
+ * recorded it on its own document, and a person's figure is derived from it.
+ */
+export declare function recordPluginPersonRefund(request: PluginPersonRefundRequest): Promise<PluginPersonRefundOutcome | null>;
+/**
+ * The people a saved view selects for a site, or `null` when no plugin keeps
+ * people here or the one that does keeps no views. A failed read throws.
+ */
+export declare function pluginPeopleInView(request: PluginPersonViewRequest): Promise<PluginPersonViewPeople | null>;
+/**
+ * Whether each person has ever written to the workspace, in the order asked
+ * — `null` for each the owner could not answer, and `null` whole when no
+ * plugin keeps people here or the one that does cannot say. Never throws: a
+ * caller reads an unknown as unknown.
+ */
+export declare function pluginPeopleWroteIn(request: PluginPersonWroteInRequest): Promise<Array<boolean | null> | null>;

package/src/lib/plugin-manager/plugin-person-records.js

@@ -0,0 +1,107 @@
+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_PERSON_RECORDS = definePluginServiceContract('core.person-records', {
+    multiple: false
+});
+/**
+ * Registers the plugin that keeps people. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws, and a second plugin's service is refused naming both —
+ * the incumbent keeps serving.
+ */ export function registerPluginPersonRecords(records, options) {
+    registerPluginService(PLUGIN_PERSON_RECORDS, records, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The service with its owner, or `null` when no plugin keeps people here. */ export function pluginPersonRecords() {
+    const entry = resolvePluginServices(PLUGIN_PERSON_RECORDS)[0];
+    return entry ? {
+        pluginId: entry.pluginId,
+        records: entry.impl
+    } : null;
+}
+/**
+ * The person an address belongs to, or `null` — for nobody found, and for a
+ * workspace no plugin keeps people for. A failed read is the owner's to
+ * throw and the caller's to decide which way it falls.
+ */ export async function findPluginPerson(request) {
+    const resolved = pluginPersonRecords();
+    if (!resolved) return null;
+    return await resolved.records.find(request);
+}
+/**
+ * The records named, in the order asked, `null` for each that is gone — or
+ * `null` whole when no plugin keeps people here, which is not "all gone".
+ */ export async function readPluginPeople(request) {
+    const resolved = pluginPersonRecords();
+    if (!resolved) return null;
+    if (!request.records.length) return [];
+    return await resolved.records.read(request);
+}
+/**
+ * Files the person under the containers through whichever plugin keeps
+ * people, or answers `null` when none does or the one that does keeps no
+ * containers. A failed write throws, as the caller's own write would have.
+ */ export async function filePluginPersonUnder(request) {
+    const resolved = pluginPersonRecords();
+    if (!(resolved == null ? void 0 : resolved.records.fileUnder)) return null;
+    if (!request.ids.length) return {
+        filed: false
+    };
+    return await resolved.records.fileUnder(request);
+}
+/**
+ * Hands a refund to whichever plugin keeps people, or answers `null` when
+ * none does. Never throws: every caller has already moved the money and
+ * recorded it on its own document, and a person's figure is derived from it.
+ */ export async function recordPluginPersonRefund(request) {
+    const resolved = pluginPersonRecords();
+    if (!(resolved == null ? void 0 : resolved.records.recordRefund)) return null;
+    try {
+        return await resolved.records.recordRefund(request);
+    } catch (error) {
+        console.error('[person-records] the record system could not record a refund', error);
+        return null;
+    }
+}
+/**
+ * The people a saved view selects for a site, or `null` when no plugin keeps
+ * people here or the one that does keeps no views. A failed read throws.
+ */ export async function pluginPeopleInView(request) {
+    const resolved = pluginPersonRecords();
+    if (!(resolved == null ? void 0 : resolved.records.peopleInView)) return null;
+    return await resolved.records.peopleInView(request);
+}
+/**
+ * Whether each person has ever written to the workspace, in the order asked
+ * — `null` for each the owner could not answer, and `null` whole when no
+ * plugin keeps people here or the one that does cannot say. Never throws: a
+ * caller reads an unknown as unknown.
+ */ export async function pluginPeopleWroteIn(request) {
+    const resolved = pluginPersonRecords();
+    if (!(resolved == null ? void 0 : resolved.records.wroteIn)) return null;
+    if (!request.records.length) return [];
+    try {
+        return await resolved.records.wroteIn(request);
+    } catch (error) {
+        console.error('[person-records] the record system could not say who wrote in', error);
+        return null;
+    }
+}
+
+//# sourceMappingURL=plugin-person-records.js.map

package/src/lib/plugin-manager/plugin-person-records.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-person-records.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 * THE PEOPLE A WORKSPACE KEEPS, asked for by the plugins that do not keep\n * them (AGL-3080).\n *\n * `plugin-contact-capture` is how a silo hands somebody it MET to the plugin\n * that keeps people. This is the other half: a plugin that has an address, or\n * a record the owner handed it, and needs the person behind it.\n *\n *  - a flow email asking whether the person agreed to marketing mail;\n *  - a campaign filling in the name a merge tag reads;\n *  - a refund taking money back off what a customer is worth;\n *  - an automation filing somebody under a campaign;\n *  - a sales sequence reading the people a rep enrolls.\n *\n * Each of those used to open the owner's collection itself — its path, its\n * address index, which site may see which document — and broke the day the\n * owner changed one. None of it is visible to `check:lib-boundaries`, because\n * a collection name is not an import.\n *\n * So the plugin that keeps people registers ONE service here, and every rule\n * stays the owner's: how an address is keyed, what an alternate address a\n * merge folded in still answers to, which site may see which record, and what\n * a refund or a filing writes.\n *\n * ## What a record is\n *\n * A {@link PluginPersonRecord} is a kind and an id in the owner's own words —\n * the words `plugin-record-routes` addresses the record by — the person's\n * primary address, and the record as the owner stores it. The fields the\n * PLATFORM defines on a person record (the consent basis\n * `marketing-consent.ts` reads, the `emailState` verdict, the `visibleTo`\n * scope) are read off it with the platform's own readers; anything else is\n * the owner's and is documented with its registration.\n *\n * ## Not registered is an answer\n *\n * Every reader answers `null` when no plugin keeps people in this process,\n * which is a workspace with no record system and is not \"nobody found\". A\n * caller treats the two differently: a send with no record system has no\n * basis to read, which is not the same as a person who declined.\n *\n * A single-implementation contract: a workspace keeps one set of people, so\n * a second plugin's service is refused naming both and the incumbent keeps\n * serving. Registered from the owner's server declarations, so it is in place\n * in a process that never loaded the owner's API surface.\n *\n * ## The caller proves who is asking\n *\n * Like the capture and timeline seams, the registry authenticates nobody. A\n * caller decides in its own terms, before it asks, that the read or the write\n * is the workspace's to make.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\n/** A person record, by the owner's word for its kind and its id. */\nexport interface PluginPersonRecordRef {\n  /** The owner's word for the record — the kind `plugin-record-routes` addresses it by. */\n  kind: string\n  id: string\n}\n\n/** One person record, as the plugin that keeps people shares it. */\nexport interface PluginPersonRecord extends PluginPersonRecordRef {\n  /** The record's primary address, normalized, or `null` when it holds none. */\n  email: string | null\n  /**\n   * The record as the owner stores it. The platform's own fields on it are\n   * read with the platform's readers; the rest is the owner's, documented\n   * with its registration.\n   */\n  data: Readonly<Record<string, unknown>>\n}\n\n/** Who to find by address, and where. */\nexport interface PluginPersonFindRequest {\n  /**\n   * The organization whose people are searched. A caller that knows only the\n   * site names `hostId` instead, and the owner reads the organization off it.\n   */\n  orgId?: string | null\n  /** The site asking. Required with {@link onlyVisibleToSite}. */\n  hostId?: string | null\n  /** Raw: the owner normalizes it, alternate addresses included. */\n  email: unknown\n  /**\n   * Answer only a record `hostId` may see. A record the address names but the\n   * site cannot see is `null`, never a reason to look further — one address\n   * names one person.\n   */\n  onlyVisibleToSite?: boolean\n  /**\n   * Look at every kind of record the owner keeps a person as, in the owner's\n   * order, instead of only the one a known person is held as. A send deciding\n   * whether it may mail somebody asks for this: a person not yet qualified is\n   * still a person whose answer counts.\n   */\n  anyKind?: boolean\n}\n\n/** Records to read, by the refs the owner handed out. */\nexport interface PluginPersonReadRequest {\n  orgId: string\n  records: readonly PluginPersonRecordRef[]\n}\n\n/**\n * File a person under containers (`plugin-containers.ts`) — the merchant's\n * own act, through an automation step or an enrollment. Filing is not\n * consent.\n */\nexport interface PluginPersonFileRequest {\n  /** The site filing them: the person is filed under the containers as this site holds them. */\n  hostId: string\n  orgId?: string | null\n  record: PluginPersonRecordRef\n  /** The container kind, as `plugin-containers.ts` declares it. */\n  containerKind: string\n  ids: readonly string[]\n}\n\n/**\n * Money handed back to a person a silo took it from: a refund, or a dispute\n * lost. The owner records it beside what the person is worth; it never\n * creates a person to hold it.\n */\nexport interface PluginPersonRefundRequest {\n  /** The site the money was taken on. */\n  hostId: string\n  /** The buyer's address as the sale recorded it. Raw: the owner normalizes it. */\n  email: unknown\n  /** Cents reversed by THIS refund, never the sale's total. */\n  amountCents: number\n  /** The silo's own document the money went back on — what a timeline entry points at. */\n  refId: string\n  /** True only for the refund that moved the sale into fully refunded. */\n  closedTheSale: boolean\n  /** `chargeback` for a dispute lost; a refund otherwise. */\n  reason?: 'refund' | 'chargeback'\n}\n\n/**\n * What became of a refund. `recorded`; `no-email` for a sale that never\n * named its buyer; `no-person` for an address the workspace holds nobody at;\n * `gone` for a person removed between the sale and the refund.\n */\nexport type PluginPersonRefundOutcome = 'recorded' | 'no-email' | 'no-person' | 'gone'\n\n/**\n * The people a saved selection the owner keeps names — a saved view of one of\n * its lists — taken for one site, as the people a sequence or a send works\n * through.\n */\nexport interface PluginPersonViewRequest {\n  orgId: string\n  /** The site the people are taken for: only records it holds are answered. */\n  hostId: string\n  /** The view, by the id the owner's record list handed out (`plugin-record-lists`). */\n  viewId: string\n  /** The member asking: a view they may not list does not exist for them. */\n  viewerUid: string\n  /** The most people answered. */\n  limit: number\n}\n\nexport type PluginPersonViewPeople =\n  | {\n      ok: true\n      people: PluginPersonRecordRef[]\n      /** How many the view selects, as far as the owner read it. */\n      total: number\n      /** The view selects more than `limit`, or more than the owner read. */\n      truncated: boolean\n    }\n  | {\n      ok: false\n      /**\n       * `not-found`: no such view, or not this member's to list.\n       * `not-people`: a view of something that is not people.\n       * `unsupported`: the view narrows by something the owner cannot apply\n       * outside its own list, so taking it would select more people than the\n       * view shows; `unsupported` names what, in the owner's words.\n       */\n      reason: 'not-found' | 'not-people' | 'unsupported'\n      unsupported?: string[]\n    }\n\n/** Records to ask about, by the refs the owner handed out. */\nexport interface PluginPersonWroteInRequest {\n  orgId: string\n  records: readonly PluginPersonRecordRef[]\n}\n\nexport interface PluginPersonRecords {\n  /** The person an address belongs to, or `null`. A read; may throw, and the caller decides which way a failure falls. */\n  find(request: PluginPersonFindRequest): Promise<PluginPersonRecord | null>\n  /** The records named, in the order asked; `null` for one that is gone. */\n  read(request: PluginPersonReadRequest): Promise<Array<PluginPersonRecord | null>>\n  /**\n   * Files the person under the containers. Optional: an owner that keeps no\n   * containers answers nothing. `filed: false` is a record the owner could\n   * not find for the site.\n   */\n  fileUnder?(request: PluginPersonFileRequest): Promise<{ filed: boolean }>\n  /** Records money handed back. Optional. Never throws: the money has already moved. */\n  recordRefund?(request: PluginPersonRefundRequest): Promise<PluginPersonRefundOutcome>\n  /** The people a saved view selects for a site. Optional: an owner that keeps no views answers nothing. */\n  peopleInView?(request: PluginPersonViewRequest): Promise<PluginPersonViewPeople>\n  /**\n   * Whether each person has ever written to the workspace — an email they\n   * sent, on their record — in the order asked; `null` for one the owner\n   * could not answer. Optional.\n   */\n  wroteIn?(request: PluginPersonWroteInRequest): Promise<Array<boolean | null>>\n}\n\nexport const PLUGIN_PERSON_RECORDS = definePluginServiceContract<PluginPersonRecords>(\n  'core.person-records',\n  { multiple: false },\n)\n\n/**\n * Registers the plugin that keeps people. The owner is the loader's marker\n * when a register fn is running, else `options.pluginId`; with neither the\n * registration throws, and a second plugin's service is refused naming both —\n * the incumbent keeps serving.\n */\nexport function registerPluginPersonRecords(\n  records: PluginPersonRecords,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PERSON_RECORDS, records, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginPersonRecords {\n  /** The plugin that keeps people. */\n  pluginId: string\n  records: PluginPersonRecords\n}\n\n/** The service with its owner, or `null` when no plugin keeps people here. */\nexport function pluginPersonRecords(): ResolvedPluginPersonRecords | null {\n  const entry = resolvePluginServices(PLUGIN_PERSON_RECORDS)[0]\n  return entry ? { pluginId: entry.pluginId, records: entry.impl } : null\n}\n\n/**\n * The person an address belongs to, or `null` — for nobody found, and for a\n * workspace no plugin keeps people for. A failed read is the owner's to\n * throw and the caller's to decide which way it falls.\n */\nexport async function findPluginPerson(\n  request: PluginPersonFindRequest,\n): Promise<PluginPersonRecord | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved) return null\n  return await resolved.records.find(request)\n}\n\n/**\n * The records named, in the order asked, `null` for each that is gone — or\n * `null` whole when no plugin keeps people here, which is not \"all gone\".\n */\nexport async function readPluginPeople(\n  request: PluginPersonReadRequest,\n): Promise<Array<PluginPersonRecord | null> | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved) return null\n  if (!request.records.length) return []\n  return await resolved.records.read(request)\n}\n\n/**\n * Files the person under the containers through whichever plugin keeps\n * people, or answers `null` when none does or the one that does keeps no\n * containers. A failed write throws, as the caller's own write would have.\n */\nexport async function filePluginPersonUnder(\n  request: PluginPersonFileRequest,\n): Promise<{ filed: boolean } | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.fileUnder) return null\n  if (!request.ids.length) return { filed: false }\n  return await resolved.records.fileUnder(request)\n}\n\n/**\n * Hands a refund to whichever plugin keeps people, or answers `null` when\n * none does. Never throws: every caller has already moved the money and\n * recorded it on its own document, and a person's figure is derived from it.\n */\nexport async function recordPluginPersonRefund(\n  request: PluginPersonRefundRequest,\n): Promise<PluginPersonRefundOutcome | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.recordRefund) return null\n  try {\n    return await resolved.records.recordRefund(request)\n  } catch (error) {\n    console.error('[person-records] the record system could not record a refund', error)\n    return null\n  }\n}\n\n/**\n * The people a saved view selects for a site, or `null` when no plugin keeps\n * people here or the one that does keeps no views. A failed read throws.\n */\nexport async function pluginPeopleInView(\n  request: PluginPersonViewRequest,\n): Promise<PluginPersonViewPeople | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.peopleInView) return null\n  return await resolved.records.peopleInView(request)\n}\n\n/**\n * Whether each person has ever written to the workspace, in the order asked\n * — `null` for each the owner could not answer, and `null` whole when no\n * plugin keeps people here or the one that does cannot say. Never throws: a\n * caller reads an unknown as unknown.\n */\nexport async function pluginPeopleWroteIn(\n  request: PluginPersonWroteInRequest,\n): Promise<Array<boolean | null> | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.wroteIn) return null\n  if (!request.records.length) return []\n  try {\n    return await resolved.records.wroteIn(request)\n  } catch (error) {\n    console.error('[person-records] the record system could not say who wrote in', error)\n    return null\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PERSON_RECORDS","multiple","registerPluginPersonRecords","records","options","pluginId","pluginPersonRecords","entry","impl","findPluginPerson","request","resolved","find","readPluginPeople","length","read","filePluginPersonUnder","fileUnder","ids","filed","recordPluginPersonRefund","recordRefund","error","console","pluginPeopleInView","peopleInView","pluginPeopleWroteIn","wroteIn"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2N1B,OAAO,MAAMC,wBAAwBH,4BACnC,uBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,4BACdC,OAA4B,EAC5BC,OAA+B;IAE/BN,sBAAsBE,uBAAuBG,SAAS,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,4EAA4E,GAC5E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,sBAAsB,CAAC,EAAE;IAC7D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,SAASI,MAAMC,IAAI;IAAC,IAAI;AACrE;AAEA;;;;CAIC,GACD,OAAO,eAAeC,iBACpBC,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,OAAO,MAAMA,SAASR,OAAO,CAACS,IAAI,CAACF;AACrC;AAEA;;;CAGC,GACD,OAAO,eAAeG,iBACpBH,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,IAAI,CAACD,QAAQP,OAAO,CAACW,MAAM,EAAE,OAAO,EAAE;IACtC,OAAO,MAAMH,SAASR,OAAO,CAACY,IAAI,CAACL;AACrC;AAEA;;;;CAIC,GACD,OAAO,eAAeM,sBACpBN,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACc,SAAS,GAAE,OAAO;IACzC,IAAI,CAACP,QAAQQ,GAAG,CAACJ,MAAM,EAAE,OAAO;QAAEK,OAAO;IAAM;IAC/C,OAAO,MAAMR,SAASR,OAAO,CAACc,SAAS,CAACP;AAC1C;AAEA;;;;CAIC,GACD,OAAO,eAAeU,yBACpBV,OAAkC;IAElC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACkB,YAAY,GAAE,OAAO;IAC5C,IAAI;QACF,OAAO,MAAMV,SAASR,OAAO,CAACkB,YAAY,CAACX;IAC7C,EAAE,OAAOY,OAAO;QACdC,QAAQD,KAAK,CAAC,gEAAgEA;QAC9E,OAAO;IACT;AACF;AAEA;;;CAGC,GACD,OAAO,eAAeE,mBACpBd,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACsB,YAAY,GAAE,OAAO;IAC5C,OAAO,MAAMd,SAASR,OAAO,CAACsB,YAAY,CAACf;AAC7C;AAEA;;;;;CAKC,GACD,OAAO,eAAegB,oBACpBhB,OAAmC;IAEnC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACwB,OAAO,GAAE,OAAO;IACvC,IAAI,CAACjB,QAAQP,OAAO,CAACW,MAAM,EAAE,OAAO,EAAE;IACtC,IAAI;QACF,OAAO,MAAMH,SAASR,OAAO,CAACwB,OAAO,CAACjB;IACxC,EAAE,OAAOY,OAAO;QACdC,QAAQD,KAAK,CAAC,iEAAiEA;QAC/E,OAAO;IACT;AACF"}

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

@@ -0,0 +1,76 @@
+/**
+ * @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';
+/**
+ * How many of a plugin's records one site produced, COUNTED in the console
+ * for another plugin's figure (AGL-3080) — the count's half of
+ * `plugin-record-lists`.
+ *
+ * A plugin that reports a share of another plugin's records — a campaign's
+ * conversions out of every form submission, booking, lead or contact the site
+ * holds — used to count the owner's collection from the browser itself: the
+ * path, which ones a site may be credited with, the filter the owner's
+ * security rules require. Each breaks the day the owner changes one.
+ *
+ * So the owner publishes a COUNT SOURCE for each record kind it keeps: the
+ * query whose aggregate count is how many records of the kind one site
+ * produced, provable by the signed-in member's read. The reader runs its own
+ * aggregation over it (`getCountFromServer`) and never learns where the
+ * records are stored. Which records a site "produced" is the owner's to say:
+ * a site's own submissions, the leads it captured, or — for a kind the
+ * organization holds once for all its sites — every one, which the reader
+ * must then present as a total across sites.
+ *
+ * ## Not registered is an answer
+ *
+ * No source for a kind means no plugin keeps it in this console. A reader
+ * withholds the figure rather than counting the collection itself.
+ *
+ * One source per kind; a second plugin claiming a kind another counts is
+ * refused, naming both.
+ */
+/** Which site's records a reader counts. */
+export interface PluginRecordCountRequest {
+    hostId: string;
+    /** The site's organization, where the kind is held by the organization. */
+    orgId?: string | null;
+}
+export interface PluginRecordCountSource {
+    /**
+     * The query whose count is how many records of the kind the site
+     * produced, or `null` where the site has none to count (an organization
+     * not yet resolved).
+     */
+    query(firestore: Firestore, request: PluginRecordCountRequest): Query<DocumentData> | null;
+    /**
+     * Whether the count is the ORGANIZATION's, shared by every site in it,
+     * rather than this site's alone — a reader dividing a site's figure by it
+     * must say the total crosses sites.
+     */
+    crossesSites?: boolean;
+}
+export declare const PLUGIN_RECORD_COUNTS: import("./plugin-services").PluginServiceContract<PluginRecordCountSource>;
+/**
+ * Publishes the count 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 counts throws naming both.
+ */
+export declare function registerPluginRecordCountSource(kind: string, source: PluginRecordCountSource, options?: {
+    pluginId?: string;
+}): void;
+/** The count source for a kind, or `null` when no plugin counts it here. */
+export declare function pluginRecordCountSource(kind: string): PluginRecordCountSource | null;

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

@@ -0,0 +1,49 @@
+/**
+ * @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_COUNTS = definePluginServiceContract('core.record-counts', {
+    multiple: true
+});
+/**
+ * Publishes the count 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 counts throws naming both.
+ */ export function registerPluginRecordCountSource(kind, source, options) {
+    var _ref, _getRegisteringPluginId;
+    const key = kind.trim();
+    if (!key) throw new Error('a record count 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 count source for "${key}" was registered with no owner`);
+    }
+    const incumbent = resolvePluginServices(PLUGIN_RECORD_COUNTS).find((entry)=>entry.key === key);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`record kind "${key}" is already counted by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_RECORD_COUNTS, source, {
+        pluginId,
+        key
+    });
+}
+/** The count source for a kind, or `null` when no plugin counts it here. */ export function pluginRecordCountSource(kind) {
+    var _ref;
+    var _resolvePluginServices_find;
+    const key = kind.trim();
+    return (_ref = (_resolvePluginServices_find = resolvePluginServices(PLUGIN_RECORD_COUNTS).find((one)=>one.key === key)) == null ? void 0 : _resolvePluginServices_find.impl) != null ? _ref : null;
+}
+
+//# sourceMappingURL=plugin-record-counts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-counts.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 {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * How many of a plugin's records one site produced, COUNTED in the console\n * for another plugin's figure (AGL-3080) — the count's half of\n * `plugin-record-lists`.\n *\n * A plugin that reports a share of another plugin's records — a campaign's\n * conversions out of every form submission, booking, lead or contact the site\n * holds — used to count the owner's collection from the browser itself: the\n * path, which ones a site may be credited with, the filter the owner's\n * security rules require. Each breaks the day the owner changes one.\n *\n * So the owner publishes a COUNT SOURCE for each record kind it keeps: the\n * query whose aggregate count is how many records of the kind one site\n * produced, provable by the signed-in member's read. The reader runs its own\n * aggregation over it (`getCountFromServer`) and never learns where the\n * records are stored. Which records a site \"produced\" is the owner's to say:\n * a site's own submissions, the leads it captured, or — for a kind the\n * organization holds once for all its sites — every one, which the reader\n * must then present as a total across sites.\n *\n * ## Not registered is an answer\n *\n * No source for a kind means no plugin keeps it in this console. A reader\n * withholds the figure rather than counting the collection itself.\n *\n * One source per kind; a second plugin claiming a kind another counts is\n * refused, naming both.\n */\n\n/** Which site's records a reader counts. */\nexport interface PluginRecordCountRequest {\n  hostId: string\n  /** The site's organization, where the kind is held by the organization. */\n  orgId?: string | null\n}\n\nexport interface PluginRecordCountSource {\n  /**\n   * The query whose count is how many records of the kind the site\n   * produced, or `null` where the site has none to count (an organization\n   * not yet resolved).\n   */\n  query(firestore: Firestore, request: PluginRecordCountRequest): Query<DocumentData> | null\n  /**\n   * Whether the count is the ORGANIZATION's, shared by every site in it,\n   * rather than this site's alone — a reader dividing a site's figure by it\n   * must say the total crosses sites.\n   */\n  crossesSites?: boolean\n}\n\nexport const PLUGIN_RECORD_COUNTS = definePluginServiceContract<PluginRecordCountSource>(\n  'core.record-counts',\n  { multiple: true },\n)\n\n/**\n * Publishes the count 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 counts throws naming both.\n */\nexport function registerPluginRecordCountSource(\n  kind: string,\n  source: PluginRecordCountSource,\n  options?: { pluginId?: string },\n): void {\n  const key = kind.trim()\n  if (!key) throw new Error('a record count source needs a record kind')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(`the record count source for \"${key}\" was registered with no owner`)\n  }\n  const incumbent = resolvePluginServices(PLUGIN_RECORD_COUNTS).find((entry) => entry.key === key)\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `record kind \"${key}\" is already counted by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RECORD_COUNTS, source, { pluginId, key })\n}\n\n/** The count source for a kind, or `null` when no plugin counts it here. */\nexport function pluginRecordCountSource(kind: string): PluginRecordCountSource | null {\n  const key = kind.trim()\n  return resolvePluginServices(PLUGIN_RECORD_COUNTS).find((one) => one.key === key)?.impl ?? null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_COUNTS","multiple","registerPluginRecordCountSource","kind","source","options","key","trim","Error","pluginId","incumbent","find","entry","pluginRecordCountSource","one","impl"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAqD1B,OAAO,MAAMC,uBAAuBH,4BAClC,sBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,gCACdC,IAAY,EACZC,MAA+B,EAC/BC,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,6BAA6B,EAAEF,IAAI,8BAA8B,CAAC;IACrF;IACA,MAAMI,YAAYX,sBAAsBC,sBAAsBW,IAAI,CAAC,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAC5F,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,sBAAsBI,QAAQ;QAAEK;QAAUH;IAAI;AACtE;AAEA,0EAA0E,GAC1E,OAAO,SAASO,wBAAwBV,IAAY;;QAE3CJ;IADP,MAAMO,MAAMH,KAAKI,IAAI;IACrB,gBAAOR,8BAAAA,sBAAsBC,sBAAsBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA,yBAAtEP,4BAA4EgB,IAAI,mBAAI;AAC7F"}

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

@@ -104,6 +104,20 @@ export interface PluginRecordEmailReachRequest {
     /** The addresses delivered to, as the send addressed them. */
     emails: readonly string[];
 }
+/**
+ * The people who wrote back to mail the workspace sent them (AGL-3080), so
+ * the record system can say a person is engaged — a lead nobody had worked is
+ * being worked now. Only a real reply: an opt-out answered with "remove me"
+ * is a refusal, filed through the suppression lists, and is not handed here.
+ */
+export interface PluginRecordEmailReplyRequest {
+    /** The organization whose records the reply is about. */
+    orgId: string;
+    /** The site the mail went out as; only records it holds are moved. */
+    hostId: string;
+    /** The addresses that wrote back, as the mail addressed them. */
+    emails: readonly string[];
+}
 export interface PluginRecordEmailStateWriter {
     /** Never throws: a list is the control, the stamp is what a person reads. */
     stamp(request: PluginRecordEmailStateRequest): Promise<PluginRecordEmailStateReport>;
@@ -120,6 +134,11 @@ export interface PluginRecordEmailStateWriter {
      * already gone.
      */
     reached?(request: PluginRecordEmailReachRequest): Promise<PluginRecordEmailStateReport>;
+    /**
+     * Notes that these people replied. Optional: a record system with no stage
+     * for it answers nothing. Never throws: the reply has already arrived.
+     */
+    replied?(request: PluginRecordEmailReplyRequest): Promise<PluginRecordEmailStateReport>;
 }
 export declare const PLUGIN_RECORD_EMAIL_STATE: import("./plugin-services").PluginServiceContract<PluginRecordEmailStateWriter>;
 /**
@@ -159,3 +178,10 @@ export declare function stampRecordEmailEngagement(request: PluginRecordEmailEng
  * send has already delivered, and its bookkeeping must not fail it.
  */
 export declare function stampRecordEmailReach(request: PluginRecordEmailReachRequest): Promise<PluginRecordEmailStateReport | null>;
+/**
+ * Hands the addresses that wrote back to whichever plugin keeps the records
+ * (AGL-3080). Answers `null` when no plugin keeps records, or the one that
+ * does keeps no such stage. Never throws: the reply is already filed, and its
+ * bookkeeping must not fail the sync that read it.
+ */
+export declare function stampRecordEmailReply(request: PluginRecordEmailReplyRequest): Promise<PluginRecordEmailStateReport | null>;

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

@@ -81,5 +81,21 @@ export const PLUGIN_RECORD_EMAIL_STATE = definePluginServiceContract('core.recor
         return null;
     }
 }
+/**
+ * Hands the addresses that wrote back to whichever plugin keeps the records
+ * (AGL-3080). Answers `null` when no plugin keeps records, or the one that
+ * does keeps no such stage. Never throws: the reply is already filed, and its
+ * bookkeeping must not fail the sync that read it.
+ */ export async function stampRecordEmailReply(request) {
+    if (!request.emails.length) return null;
+    const resolved = pluginRecordEmailStateWriter();
+    if (!(resolved == null ? void 0 : resolved.writer.replied)) return null;
+    try {
+        return await resolved.writer.replied(request);
+    } catch (error) {
+        console.error('[record-email-state] the record system could not note a reply', error);
+        return null;
+    }
+}
 
 //# sourceMappingURL=plugin-record-email-state.js.map