@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-console-crons.js

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * A plugin's own scheduled jobs, run by the CONSOLE (AGL-2981).
+ *
+ * The platform already has a beat for work that belongs on the tenant — the
+ * job runner behind `pluginJobsBeat` — and it is the wrong place for a job
+ * that holds a credential only the console may hold: a provider key, a
+ * sealed grant to a person's mailbox. Those jobs have to run in the console,
+ * and until now the only way to get one there was a console route of its own
+ * and a literal in the scheduler's route list, which is a plugin's route in
+ * the platform's code.
+ *
+ * So a plugin DECLARES a console job here instead, and the platform runs
+ * every declared job from one route, `/api/admin/plugin-crons`, which the
+ * Cloud Scheduler job that drives the console's fifteen-minute sweeps posts
+ * like any other of its routes. A plugin that adds a job adds a declaration;
+ * the scheduler, its firewall rule and its deploy are unchanged.
+ *
+ * ## One schedule
+ *
+ * Every declared job runs on that tick: {@link PLUGIN_CONSOLE_CRON_SCHEDULE}.
+ * A job that has nothing to do returns at once. A job that needs a slower
+ * cadence keeps its own "last ran" mark and skips; one that needs a faster
+ * one is not a job for this runner.
+ *
+ * ## Watched like every other job
+ *
+ * Each job has its own row on `/api/health/crons` —
+ * {@link pluginConsoleCronScheduledJobs} — and the runner stamps that row's
+ * `platformCronBeats` mark when it invokes the job, BEFORE the work, the rule
+ * every console cron follows: the mark answers "is this job still being
+ * scheduled", and a job that throws was still scheduled. A job that stops
+ * being run — its plugin unregistered it, the route stopped being posted —
+ * goes red on the board within its grace.
+ *
+ * ## Isolated, and bounded
+ *
+ * Jobs run concurrently, each in its own try: a throw is logged against its
+ * plugin and reported as `null`, and never stops another job. Each is handed
+ * a deadline, and a job that starts no new unit of work after it lets the
+ * route answer before its caller gives up.
+ *
+ * Declared from a plugin's `consoleServerDeclarations` — the console's boot
+ * registrations — with the job's body imported lazily, so boot pays for the
+ * declaration and the tick pays for the work.
+ */ import { SCHEDULED_JOBS } from "../app-utils/health-report.js";
+import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+/** The console route that runs every declared job, as the scheduler posts it. */ export const PLUGIN_CONSOLE_CRONS_ROUTE = '/api/admin/plugin-crons';
+/** The runner's own row on `/api/health/crons`: is the route being posted at all. */ export const PLUGIN_CONSOLE_CRONS_JOB_ID = 'plugin-console-crons';
+/**
+ * The tick every declared job runs on, five-field UTC: the console's
+ * fifteen-minute sweep (`CONSOLE_FAST_CRON_SCHEDULE` in `cloud/functions`).
+ */ export const PLUGIN_CONSOLE_CRON_SCHEDULE = '*/15 * * * *';
+/** How late a declared job may be before its row goes red: three missed ticks. */ export const PLUGIN_CONSOLE_CRON_GRACE_MINUTES = 45;
+const registrations = [];
+/** A job id as a beat document and a health row can carry it. */ const JOB_ID = /^[a-z][a-z0-9-]*$/;
+/** Job ids the platform's own inventory holds. */ const PLATFORM_JOB_IDS = new Set([
+    ...SCHEDULED_JOBS.map((job)=>job.id),
+    PLUGIN_CONSOLE_CRONS_JOB_ID
+]);
+/**
+ * Declares a plugin's console job. Owner = the loader's marker inside a
+ * register fn, else `options.pluginId`; a job with neither throws, as does
+ * an id that is not the plugin's own (`<pluginId>-…`), one the platform's
+ * inventory holds, one another plugin declared, and a job with no label or
+ * no consequence. The same plugin declaring the same id again replaces its
+ * job in place.
+ */ export function registerPluginConsoleCron(job, options) {
+    var _ref, _getRegisteringPluginId, _ref1, _job_label, _job_drives;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error('a plugin console job was registered with no owner: pass { pluginId } ' + 'when registering outside a plugin register fn');
+    }
+    const id = String((_ref1 = job == null ? void 0 : job.id) != null ? _ref1 : '').trim();
+    if (!JOB_ID.test(id) || !id.startsWith(`${pluginId}-`) || id === `${pluginId}-`) {
+        throw new Error(`plugin console job "${id}" from "${pluginId}" needs an id of its own: ` + `"${pluginId}-" and a lowercase name`);
+    }
+    if (PLATFORM_JOB_IDS.has(id)) {
+        throw new Error(`plugin console job "${id}" is a platform job's id; refused "${pluginId}"`);
+    }
+    const incumbent = registrations.find((entry)=>entry.id === id);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`plugin console job "${id}" is already declared by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    const label = String((_job_label = job.label) != null ? _job_label : '').trim();
+    const drives = String((_job_drives = job.drives) != null ? _job_drives : '').trim();
+    if (!label || !drives || typeof job.run !== 'function') {
+        throw new Error(`plugin console job "${id}" needs a label, what it drives, and a run function`);
+    }
+    const registration = {
+        pluginId,
+        id,
+        label,
+        drives,
+        run: job.run
+    };
+    const index = registrations.findIndex((entry)=>entry.id === id);
+    if (index >= 0) registrations[index] = registration;
+    else registrations.push(registration);
+}
+/** Every declared job, in declaration order, without its body. */ export function listPluginConsoleCrons() {
+    return registrations.map(({ pluginId, id, label, drives })=>({
+            pluginId,
+            id,
+            label,
+            drives
+        }));
+}
+/**
+ * The declared jobs as rows of the scheduled-job inventory, for
+ * `/api/health/crons` to judge beside the platform's own.
+ */ export function pluginConsoleCronScheduledJobs() {
+    return registrations.map((entry)=>({
+            id: entry.id,
+            label: entry.label,
+            cron: PLUGIN_CONSOLE_CRON_SCHEDULE,
+            runner: 'cloud-scheduler',
+            target: `consoleFastCrons → console ${PLUGIN_CONSOLE_CRONS_ROUTE} (${entry.pluginId})`,
+            graceMinutes: PLUGIN_CONSOLE_CRON_GRACE_MINUTES,
+            drives: entry.drives
+        }));
+}
+/**
+ * Runs the declared jobs — every one, or the ones named — concurrently,
+ * each after its beat. Answers each job's report by id, or `null` for one
+ * that threw. Never throws.
+ */ export async function runPluginConsoleCrons(options) {
+    var _options_jobIds;
+    const wanted = ((_options_jobIds = options.jobIds) == null ? void 0 : _options_jobIds.length) ? new Set(options.jobIds) : null;
+    const jobs = [
+        ...registrations
+    ].filter((entry)=>!wanted || wanted.has(entry.id));
+    const settled = await Promise.all(jobs.map(async (job)=>{
+        try {
+            await options.beat(job.id, options.nowMs);
+        } catch (unused) {
+        // A beat that cannot be written must not take down the job it
+        // describes; a write that keeps failing reads as a silent job.
+        }
+        try {
+            return [
+                job.id,
+                await job.run({
+                    nowMs: options.nowMs,
+                    deadlineMs: options.deadlineMs
+                })
+            ];
+        } catch (error) {
+            console.error(`[plugins] ${job.pluginId} console job ${job.id} failed`, error);
+            return [
+                job.id,
+                null
+            ];
+        }
+    }));
+    // Declaration order, whichever job finished first.
+    return Object.fromEntries(settled);
+}
+/** Test seam: forget every declared job. */ export function resetPluginConsoleCronsForTests() {
+    registrations.length = 0;
+}
+
+//# sourceMappingURL=plugin-console-crons.js.map

package/src/lib/plugin-manager/plugin-console-crons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-console-crons.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A plugin's own scheduled jobs, run by the CONSOLE (AGL-2981).\n *\n * The platform already has a beat for work that belongs on the tenant — the\n * job runner behind `pluginJobsBeat` — and it is the wrong place for a job\n * that holds a credential only the console may hold: a provider key, a\n * sealed grant to a person's mailbox. Those jobs have to run in the console,\n * and until now the only way to get one there was a console route of its own\n * and a literal in the scheduler's route list, which is a plugin's route in\n * the platform's code.\n *\n * So a plugin DECLARES a console job here instead, and the platform runs\n * every declared job from one route, `/api/admin/plugin-crons`, which the\n * Cloud Scheduler job that drives the console's fifteen-minute sweeps posts\n * like any other of its routes. A plugin that adds a job adds a declaration;\n * the scheduler, its firewall rule and its deploy are unchanged.\n *\n * ## One schedule\n *\n * Every declared job runs on that tick: {@link PLUGIN_CONSOLE_CRON_SCHEDULE}.\n * A job that has nothing to do returns at once. A job that needs a slower\n * cadence keeps its own \"last ran\" mark and skips; one that needs a faster\n * one is not a job for this runner.\n *\n * ## Watched like every other job\n *\n * Each job has its own row on `/api/health/crons` —\n * {@link pluginConsoleCronScheduledJobs} — and the runner stamps that row's\n * `platformCronBeats` mark when it invokes the job, BEFORE the work, the rule\n * every console cron follows: the mark answers \"is this job still being\n * scheduled\", and a job that throws was still scheduled. A job that stops\n * being run — its plugin unregistered it, the route stopped being posted —\n * goes red on the board within its grace.\n *\n * ## Isolated, and bounded\n *\n * Jobs run concurrently, each in its own try: a throw is logged against its\n * plugin and reported as `null`, and never stops another job. Each is handed\n * a deadline, and a job that starts no new unit of work after it lets the\n * route answer before its caller gives up.\n *\n * Declared from a plugin's `consoleServerDeclarations` — the console's boot\n * registrations — with the job's body imported lazily, so boot pays for the\n * declaration and the tick pays for the work.\n */\n\nimport { SCHEDULED_JOBS, type ScheduledJob } from '../app-utils/health-report'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** The console route that runs every declared job, as the scheduler posts it. */\nexport const PLUGIN_CONSOLE_CRONS_ROUTE = '/api/admin/plugin-crons'\n\n/** The runner's own row on `/api/health/crons`: is the route being posted at all. */\nexport const PLUGIN_CONSOLE_CRONS_JOB_ID = 'plugin-console-crons'\n\n/**\n * The tick every declared job runs on, five-field UTC: the console's\n * fifteen-minute sweep (`CONSOLE_FAST_CRON_SCHEDULE` in `cloud/functions`).\n */\nexport const PLUGIN_CONSOLE_CRON_SCHEDULE = '*/15 * * * *'\n\n/** How late a declared job may be before its row goes red: three missed ticks. */\nexport const PLUGIN_CONSOLE_CRON_GRACE_MINUTES = 45\n\n/** What one run of a job is handed. */\nexport interface PluginConsoleCronContext {\n  /** When the tick began, epoch ms. */\n  nowMs: number\n  /** Start no new unit of work after this, epoch ms. */\n  deadlineMs: number\n}\n\n/** What a job reports for the tick's answer and log: counts, flags, a word — never content. */\nexport type PluginConsoleCronReport = Readonly<Record<string, number | boolean | string | null>>\n\nexport interface PluginConsoleCronJob {\n  /**\n   * The job's id: its `platformCronBeats` document and its health row.\n   * Starts with the plugin's own id — `acme-mail-sync` for `acme-mail` — so\n   * two plugins' jobs, and a plugin's job and the platform's, never share one.\n   */\n  id: string\n  /** What the health board calls it. */\n  label: string\n  /** What stops happening when it stops, in a sentence the board renders. */\n  drives: string\n  run(context: PluginConsoleCronContext): Promise<PluginConsoleCronReport>\n}\n\n/** A declared job, without its body. */\nexport interface PluginConsoleCronDeclaration {\n  pluginId: string\n  id: string\n  label: string\n  drives: string\n}\n\ninterface Registration extends PluginConsoleCronDeclaration {\n  run: PluginConsoleCronJob['run']\n}\n\nconst registrations: Registration[] = []\n\n/** A job id as a beat document and a health row can carry it. */\nconst JOB_ID = /^[a-z][a-z0-9-]*$/\n\n/** Job ids the platform's own inventory holds. */\nconst PLATFORM_JOB_IDS = new Set([...SCHEDULED_JOBS.map((job) => job.id), PLUGIN_CONSOLE_CRONS_JOB_ID])\n\n/**\n * Declares a plugin's console job. Owner = the loader's marker inside a\n * register fn, else `options.pluginId`; a job with neither throws, as does\n * an id that is not the plugin's own (`<pluginId>-…`), one the platform's\n * inventory holds, one another plugin declared, and a job with no label or\n * no consequence. The same plugin declaring the same id again replaces its\n * job in place.\n */\nexport function registerPluginConsoleCron(\n  job: PluginConsoleCronJob,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin console job was registered with no owner: pass { pluginId } ' +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const id = String(job?.id ?? '').trim()\n  if (!JOB_ID.test(id) || !id.startsWith(`${pluginId}-`) || id === `${pluginId}-`) {\n    throw new Error(\n      `plugin console job \"${id}\" from \"${pluginId}\" needs an id of its own: ` +\n        `\"${pluginId}-\" and a lowercase name`,\n    )\n  }\n  if (PLATFORM_JOB_IDS.has(id)) {\n    throw new Error(`plugin console job \"${id}\" is a platform job's id; refused \"${pluginId}\"`)\n  }\n  const incumbent = registrations.find((entry) => entry.id === id)\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `plugin console job \"${id}\" is already declared by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  const label = String(job.label ?? '').trim()\n  const drives = String(job.drives ?? '').trim()\n  if (!label || !drives || typeof job.run !== 'function') {\n    throw new Error(`plugin console job \"${id}\" needs a label, what it drives, and a run function`)\n  }\n  const registration: Registration = { pluginId, id, label, drives, run: job.run }\n  const index = registrations.findIndex((entry) => entry.id === id)\n  if (index >= 0) registrations[index] = registration\n  else registrations.push(registration)\n}\n\n/** Every declared job, in declaration order, without its body. */\nexport function listPluginConsoleCrons(): PluginConsoleCronDeclaration[] {\n  return registrations.map(({ pluginId, id, label, drives }) => ({ pluginId, id, label, drives }))\n}\n\n/**\n * The declared jobs as rows of the scheduled-job inventory, for\n * `/api/health/crons` to judge beside the platform's own.\n */\nexport function pluginConsoleCronScheduledJobs(): ScheduledJob[] {\n  return registrations.map((entry) => ({\n    id: entry.id,\n    label: entry.label,\n    cron: PLUGIN_CONSOLE_CRON_SCHEDULE,\n    runner: 'cloud-scheduler',\n    target: `consoleFastCrons → console ${PLUGIN_CONSOLE_CRONS_ROUTE} (${entry.pluginId})`,\n    graceMinutes: PLUGIN_CONSOLE_CRON_GRACE_MINUTES,\n    drives: entry.drives,\n  }))\n}\n\nexport interface RunPluginConsoleCronsOptions {\n  nowMs: number\n  deadlineMs: number\n  /** Only these jobs, by id — a manual re-run of one. Absent runs every job. */\n  jobIds?: readonly string[] | null\n  /**\n   * Stamps a job's `platformCronBeats` mark. Must not throw; the runner\n   * awaits it before the job starts.\n   */\n  beat(jobId: string, nowMs: number): Promise<unknown>\n}\n\n/**\n * Runs the declared jobs — every one, or the ones named — concurrently,\n * each after its beat. Answers each job's report by id, or `null` for one\n * that threw. Never throws.\n */\nexport async function runPluginConsoleCrons(\n  options: RunPluginConsoleCronsOptions,\n): Promise<Record<string, PluginConsoleCronReport | null>> {\n  const wanted = options.jobIds?.length ? new Set(options.jobIds) : null\n  const jobs = [...registrations].filter((entry) => !wanted || wanted.has(entry.id))\n  const settled = await Promise.all(\n    jobs.map(async (job): Promise<[string, PluginConsoleCronReport | null]> => {\n      try {\n        await options.beat(job.id, options.nowMs)\n      } catch {\n        // A beat that cannot be written must not take down the job it\n        // describes; a write that keeps failing reads as a silent job.\n      }\n      try {\n        return [job.id, await job.run({ nowMs: options.nowMs, deadlineMs: options.deadlineMs })]\n      } catch (error) {\n        console.error(`[plugins] ${job.pluginId} console job ${job.id} failed`, error)\n        return [job.id, null]\n      }\n    }),\n  )\n  // Declaration order, whichever job finished first.\n  return Object.fromEntries(settled)\n}\n\n/** Test seam: forget every declared job. */\nexport function resetPluginConsoleCronsForTests(): void {\n  registrations.length = 0\n}\n"],"names":["SCHEDULED_JOBS","getRegisteringPluginId","PLUGIN_CONSOLE_CRONS_ROUTE","PLUGIN_CONSOLE_CRONS_JOB_ID","PLUGIN_CONSOLE_CRON_SCHEDULE","PLUGIN_CONSOLE_CRON_GRACE_MINUTES","registrations","JOB_ID","PLATFORM_JOB_IDS","Set","map","job","id","registerPluginConsoleCron","options","pluginId","trim","Error","String","test","startsWith","has","incumbent","find","entry","label","drives","run","registration","index","findIndex","push","listPluginConsoleCrons","pluginConsoleCronScheduledJobs","cron","runner","target","graceMinutes","runPluginConsoleCrons","wanted","jobIds","length","jobs","filter","settled","Promise","all","beat","nowMs","deadlineMs","error","console","Object","fromEntries","resetPluginConsoleCronsForTests"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-contact-capture.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @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 person met on a site, handed to whichever plugin keeps people (AGL-3124).
+ *
+ * Four silos capture the same thing and none of them is the record system: a
+ * form submission, a site member signing up, an order, a booking. Each holds
+ * an address, a name and the fact that something happened, and each wants the
+ * workspace's person record to know. Today each one imports the writer, which
+ * makes the highest-fan-in edge in the repo — thirty files in one plugin alone
+ * — and makes the record system's plugin something a storefront cannot take a
+ * payment without.
+ *
+ * So the silo stops importing and starts DECLARING: it registers the capture
+ * door it owns, and hands a capture to this seam. The plugin that keeps people
+ * registers the writer and does every part of the work that is a record
+ * system's to do:
+ *
+ *  - normalizing and keying the address, and deciding whether this is a new
+ *    person or a visit from one the workspace already holds;
+ *  - the audience band, the erasure rows, and every other refusal — answered,
+ *    never thrown, so a capture that is refused never costs the silo the order
+ *    or the submission it was recording;
+ *  - what a stage, an owner, a company and a tag mean, and what the arrival
+ *    of a new person sets off.
+ *
+ * The silo decides none of that. It reports what it saw.
+ *
+ * ## Why the profile is opaque
+ *
+ * `profile` is the owner's own field names with scalar values, not a core
+ * type. A person's record shape belongs to the plugin that models it, and a
+ * typed core shape would be that model spelled in the platform again — which
+ * is the defect this seam exists to retire, not a smaller version of it. A key
+ * the owner does not document is the owner's to ignore.
+ *
+ * `source` is the silo's own word for its door, and it is declared rather than
+ * enumerated here for the same reason: core listing `form`, `member`, `order`
+ * and `booking` would be core holding the plugin set again. A silo registers
+ * its source with {@link registerPluginContactSource}, which is what lets a
+ * timeline label an entry and a link point back at the thing that captured the
+ * person, without the platform knowing what any of them are.
+ *
+ * ## One writer; many silos
+ *
+ * A workspace keeps one set of people, so the writer is a slot: a second
+ * plugin's writer is refused naming both, and the incumbent keeps serving. A
+ * SOURCE is per silo and there are many, but one source word has one owner —
+ * two plugins claiming `order` would make the label and the link ambiguous at
+ * the point they are read.
+ *
+ * ## The caller proves who is asking
+ *
+ * Like `plugin-record-timeline`, the registry authenticates nobody. A silo has
+ * already decided, in its own terms and before it asks, that the capture is
+ * the workspace's to record — that the submission was accepted, that the order
+ * was paid.
+ *
+ * Server-side: reached by its own subpath, never through
+ * `plugin-manager/index.ts`.
+ */
+/** The person, as the capturing silo saw them. */
+export interface PluginContactIdentity {
+    /**
+     * The address they gave. Raw: the owner normalizes and keys on it, and a
+     * silo that normalized first would be keeping a second copy of that rule.
+     */
+    email: unknown;
+    name?: string | null;
+}
+/** What happened, in the capturing silo's own words. */
+export interface PluginContactInteraction {
+    /** The silo's declared source word — see {@link registerPluginContactSource}. */
+    source: string;
+    /** When it happened, epoch ms; the owner uses now when absent. */
+    atMs?: number;
+    /**
+     * The document it happened on, in the silo's terms
+     * (`formSubmissions/{id}`, `orders/{id}`), so a timeline entry can point
+     * back at it. Absent where the door leaves nothing to open.
+     */
+    refId?: string | null;
+    /** One line a person reads on the timeline. */
+    summary?: string | null;
+}
+export interface PluginContactCaptureRequest {
+    orgId: string;
+    /** The site the person was met on: the brand whose form or checkout it was. */
+    hostId: string;
+    identity: PluginContactIdentity;
+    interaction: PluginContactInteraction;
+    /**
+     * An explicit marketing opt-in the capture surface carried, recorded against
+     * `hostId`. Absent is not consent, and filing a capture under a campaign is
+     * not consent either.
+     */
+    marketingConsent?: boolean;
+    /** Tags the silo puts on this capture; the owner adds, never replaces. */
+    tags?: readonly string[];
+    /** The campaigns the capture SURFACE is filed under — the merchant's own act. */
+    campaignIds?: readonly string[];
+    /** Money the capture was worth, in cents, where the silo took some. */
+    purchaseCents?: number;
+    /** The currency {@link purchaseCents} is in, lowercase, when the silo knows. */
+    purchaseCurrency?: string;
+    /**
+     * The earliest stage this capture describes, in the OWNER's words. A floor
+     * and not a value: the owner fills an empty stage and advances an earlier
+     * one, and never moves anybody back, so a repeat customer filling in a
+     * contact form is still a customer.
+     */
+    lifecycleFloor?: string;
+    /**
+     * Profile fields the silo knows, keyed by the owner's own field names.
+     * Only the keys given are written, so a silo that knows the phone number
+     * does not blank a title somebody typed.
+     */
+    profile?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The owner's answer. `created: false` is a visit by somebody the workspace
+ * already held, which is an interaction and not a new person.
+ *
+ * A refusal is RETURNED. Every one of these silos has already done the thing
+ * it was recording, so a throw here would cost an accepted submission or a
+ * paid order for a record it could not keep.
+ */
+export type PluginContactCaptured = {
+    ok: true;
+    contactId: string;
+    created: boolean;
+} | {
+    ok: false;
+    /**
+     * `invalid-email`: nothing usable to key a person on. `band`: the
+     * workspace is at the audience it may hold. `erased`: the workspace
+     * erased this person and a capture must not quietly rebuild them.
+     * `error`: the owner failed, and said so rather than silently.
+     */
+    reason: 'invalid-email' | 'band' | 'erased' | 'error';
+    /** Customer-safe: a caller may show or log it as it stands. */
+    error: string;
+};
+export interface PluginContactCaptureWriter {
+    /** Records one capture; a refusal is returned, never thrown. */
+    capture(request: PluginContactCaptureRequest): Promise<PluginContactCaptured>;
+}
+/** A capture door a silo owns. */
+export interface PluginContactSourceDeclaration {
+    /** The silo's word for the door, as its captures carry it. */
+    source: string;
+    /** What a timeline entry from this door says: `Form submission`. */
+    label: string;
+    /**
+     * What a link from that entry says when there is something to open —
+     * `Open submission`. Absent where the door leaves nothing to open, which
+     * is the honest answer for an import or a by-hand add.
+     */
+    openLabel?: string;
+    /**
+     * The record kind the silo's own document is, for
+     * `plugin-record-routes` to address it with. Absent where the door has no
+     * record of its own to open.
+     */
+    recordKind?: string;
+}
+/** A source declaration with the silo that made it. */
+export type ResolvedPluginContactSource = PluginContactSourceDeclaration & {
+    pluginId: string;
+};
+export declare const PLUGIN_CONTACT_CAPTURE: import("./plugin-services").PluginServiceContract<PluginContactCaptureWriter>;
+export declare const PLUGIN_CONTACT_SOURCES: import("./plugin-services").PluginServiceContract<PluginContactSourceDeclaration>;
+/**
+ * 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 writer is refused naming both —
+ * the incumbent keeps serving.
+ */
+export declare function registerPluginContactCaptureWriter(writer: PluginContactCaptureWriter, options?: {
+    pluginId?: string;
+}): void;
+/** Declares a capture door. One source word has one owner. */
+export declare function registerPluginContactSource(declaration: PluginContactSourceDeclaration, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginContactCaptureWriter {
+    /** The plugin that keeps people. */
+    pluginId: string;
+    writer: PluginContactCaptureWriter;
+}
+/** The writer with its owner, or `null` when no plugin keeps people here. */
+export declare function pluginContactCaptureWriter(): ResolvedPluginContactCaptureWriter | null;
+/**
+ * Hands one capture to the plugin that keeps people, or answers `null` when
+ * no plugin does.
+ *
+ * `null` and a refusal are different answers and a silo treats them
+ * differently: `null` is a workspace with no record system, where there is
+ * nothing to record and nothing has gone wrong; a refusal is a record system
+ * that considered this person and declined.
+ */
+export declare function capturePluginContact(request: PluginContactCaptureRequest): Promise<PluginContactCaptured | null>;
+/** Every declared capture door, with its silo, in registration order. */
+export declare function listPluginContactSources(): ResolvedPluginContactSource[];
+/** One declared capture door by its source word, or `null`. */
+export declare function pluginContactSource(source: string): ResolvedPluginContactSource | null;

package/src/lib/plugin-manager/plugin-contact-capture.js

@@ -0,0 +1,89 @@
+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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_CONTACT_CAPTURE = definePluginServiceContract('core.contact-capture', {
+    multiple: false
+});
+export const PLUGIN_CONTACT_SOURCES = definePluginServiceContract('core.contact-capture-sources', {
+    multiple: true
+});
+/**
+ * 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 writer is refused naming both —
+ * the incumbent keeps serving.
+ */ export function registerPluginContactCaptureWriter(writer, options) {
+    registerPluginService(PLUGIN_CONTACT_CAPTURE, writer, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** Declares a capture door. One source word has one owner. */ export function registerPluginContactSource(declaration, options) {
+    var _ref, _ref1, _getRegisteringPluginId;
+    var _declaration_source, _declaration_label;
+    const key = (_ref = (_declaration_source = declaration.source) == null ? void 0 : _declaration_source.trim()) != null ? _ref : '';
+    if (!key) throw new Error('a contact capture source needs a source word');
+    if (!((_declaration_label = declaration.label) == null ? void 0 : _declaration_label.trim())) {
+        throw new Error(`contact capture source "${key}" needs a label`);
+    }
+    const pluginId = ((_ref1 = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref1 : '').trim();
+    const incumbent = resolvePluginServices(PLUGIN_CONTACT_SOURCES).find((entry)=>entry.key === key);
+    if (incumbent && pluginId && incumbent.pluginId !== pluginId) {
+        throw new Error(`contact capture source "${key}" is already declared by ` + `"${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_CONTACT_SOURCES, _extends({}, declaration, {
+        source: key
+    }), _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, {
+        key
+    }));
+}
+/** The writer with its owner, or `null` when no plugin keeps people here. */ export function pluginContactCaptureWriter() {
+    const entry = resolvePluginServices(PLUGIN_CONTACT_CAPTURE)[0];
+    return entry ? {
+        pluginId: entry.pluginId,
+        writer: entry.impl
+    } : null;
+}
+/**
+ * Hands one capture to the plugin that keeps people, or answers `null` when
+ * no plugin does.
+ *
+ * `null` and a refusal are different answers and a silo treats them
+ * differently: `null` is a workspace with no record system, where there is
+ * nothing to record and nothing has gone wrong; a refusal is a record system
+ * that considered this person and declined.
+ */ export async function capturePluginContact(request) {
+    const found = pluginContactCaptureWriter();
+    if (!found) return null;
+    return found.writer.capture(request);
+}
+/** Every declared capture door, with its silo, in registration order. */ export function listPluginContactSources() {
+    return resolvePluginServices(PLUGIN_CONTACT_SOURCES).map((entry)=>_extends({}, entry.impl, {
+            pluginId: entry.pluginId
+        }));
+}
+/** One declared capture door by its source word, or `null`. */ export function pluginContactSource(source) {
+    const key = source.trim();
+    const entry = resolvePluginServices(PLUGIN_CONTACT_SOURCES).find((one)=>one.key === key);
+    return entry ? _extends({}, entry.impl, {
+        pluginId: entry.pluginId
+    }) : null;
+}
+
+//# sourceMappingURL=plugin-contact-capture.js.map

package/src/lib/plugin-manager/plugin-contact-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-contact-capture.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 person met on a site, handed to whichever plugin keeps people (AGL-3124).\n *\n * Four silos capture the same thing and none of them is the record system: a\n * form submission, a site member signing up, an order, a booking. Each holds\n * an address, a name and the fact that something happened, and each wants the\n * workspace's person record to know. Today each one imports the writer, which\n * makes the highest-fan-in edge in the repo — thirty files in one plugin alone\n * — and makes the record system's plugin something a storefront cannot take a\n * payment without.\n *\n * So the silo stops importing and starts DECLARING: it registers the capture\n * door it owns, and hands a capture to this seam. The plugin that keeps people\n * registers the writer and does every part of the work that is a record\n * system's to do:\n *\n *  - normalizing and keying the address, and deciding whether this is a new\n *    person or a visit from one the workspace already holds;\n *  - the audience band, the erasure rows, and every other refusal — answered,\n *    never thrown, so a capture that is refused never costs the silo the order\n *    or the submission it was recording;\n *  - what a stage, an owner, a company and a tag mean, and what the arrival\n *    of a new person sets off.\n *\n * The silo decides none of that. It reports what it saw.\n *\n * ## Why the profile is opaque\n *\n * `profile` is the owner's own field names with scalar values, not a core\n * type. A person's record shape belongs to the plugin that models it, and a\n * typed core shape would be that model spelled in the platform again — which\n * is the defect this seam exists to retire, not a smaller version of it. A key\n * the owner does not document is the owner's to ignore.\n *\n * `source` is the silo's own word for its door, and it is declared rather than\n * enumerated here for the same reason: core listing `form`, `member`, `order`\n * and `booking` would be core holding the plugin set again. A silo registers\n * its source with {@link registerPluginContactSource}, which is what lets a\n * timeline label an entry and a link point back at the thing that captured the\n * person, without the platform knowing what any of them are.\n *\n * ## One writer; many silos\n *\n * A workspace keeps one set of people, so the writer is a slot: a second\n * plugin's writer is refused naming both, and the incumbent keeps serving. A\n * SOURCE is per silo and there are many, but one source word has one owner —\n * two plugins claiming `order` would make the label and the link ambiguous at\n * the point they are read.\n *\n * ## The caller proves who is asking\n *\n * Like `plugin-record-timeline`, the registry authenticates nobody. A silo has\n * already decided, in its own terms and before it asks, that the capture is\n * the workspace's to record — that the submission was accepted, that the order\n * was paid.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\n/** The person, as the capturing silo saw them. */\nexport interface PluginContactIdentity {\n  /**\n   * The address they gave. Raw: the owner normalizes and keys on it, and a\n   * silo that normalized first would be keeping a second copy of that rule.\n   */\n  email: unknown\n  name?: string | null\n}\n\n/** What happened, in the capturing silo's own words. */\nexport interface PluginContactInteraction {\n  /** The silo's declared source word — see {@link registerPluginContactSource}. */\n  source: string\n  /** When it happened, epoch ms; the owner uses now when absent. */\n  atMs?: number\n  /**\n   * The document it happened on, in the silo's terms\n   * (`formSubmissions/{id}`, `orders/{id}`), so a timeline entry can point\n   * back at it. Absent where the door leaves nothing to open.\n   */\n  refId?: string | null\n  /** One line a person reads on the timeline. */\n  summary?: string | null\n}\n\nexport interface PluginContactCaptureRequest {\n  orgId: string\n  /** The site the person was met on: the brand whose form or checkout it was. */\n  hostId: string\n  identity: PluginContactIdentity\n  interaction: PluginContactInteraction\n  /**\n   * An explicit marketing opt-in the capture surface carried, recorded against\n   * `hostId`. Absent is not consent, and filing a capture under a campaign is\n   * not consent either.\n   */\n  marketingConsent?: boolean\n  /** Tags the silo puts on this capture; the owner adds, never replaces. */\n  tags?: readonly string[]\n  /** The campaigns the capture SURFACE is filed under — the merchant's own act. */\n  campaignIds?: readonly string[]\n  /** Money the capture was worth, in cents, where the silo took some. */\n  purchaseCents?: number\n  /** The currency {@link purchaseCents} is in, lowercase, when the silo knows. */\n  purchaseCurrency?: string\n  /**\n   * The earliest stage this capture describes, in the OWNER's words. A floor\n   * and not a value: the owner fills an empty stage and advances an earlier\n   * one, and never moves anybody back, so a repeat customer filling in a\n   * contact form is still a customer.\n   */\n  lifecycleFloor?: string\n  /**\n   * Profile fields the silo knows, keyed by the owner's own field names.\n   * Only the keys given are written, so a silo that knows the phone number\n   * does not blank a title somebody typed.\n   */\n  profile?: Readonly<Record<string, unknown>>\n}\n\n/**\n * The owner's answer. `created: false` is a visit by somebody the workspace\n * already held, which is an interaction and not a new person.\n *\n * A refusal is RETURNED. Every one of these silos has already done the thing\n * it was recording, so a throw here would cost an accepted submission or a\n * paid order for a record it could not keep.\n */\nexport type PluginContactCaptured =\n  | { ok: true; contactId: string; created: boolean }\n  | {\n      ok: false\n      /**\n       * `invalid-email`: nothing usable to key a person on. `band`: the\n       * workspace is at the audience it may hold. `erased`: the workspace\n       * erased this person and a capture must not quietly rebuild them.\n       * `error`: the owner failed, and said so rather than silently.\n       */\n      reason: 'invalid-email' | 'band' | 'erased' | 'error'\n      /** Customer-safe: a caller may show or log it as it stands. */\n      error: string\n    }\n\nexport interface PluginContactCaptureWriter {\n  /** Records one capture; a refusal is returned, never thrown. */\n  capture(\n    request: PluginContactCaptureRequest,\n  ): Promise<PluginContactCaptured>\n}\n\n/** A capture door a silo owns. */\nexport interface PluginContactSourceDeclaration {\n  /** The silo's word for the door, as its captures carry it. */\n  source: string\n  /** What a timeline entry from this door says: `Form submission`. */\n  label: string\n  /**\n   * What a link from that entry says when there is something to open —\n   * `Open submission`. Absent where the door leaves nothing to open, which\n   * is the honest answer for an import or a by-hand add.\n   */\n  openLabel?: string\n  /**\n   * The record kind the silo's own document is, for\n   * `plugin-record-routes` to address it with. Absent where the door has no\n   * record of its own to open.\n   */\n  recordKind?: string\n}\n\n/** A source declaration with the silo that made it. */\nexport type ResolvedPluginContactSource = PluginContactSourceDeclaration & {\n  pluginId: string\n}\n\nexport const PLUGIN_CONTACT_CAPTURE =\n  definePluginServiceContract<PluginContactCaptureWriter>(\n    'core.contact-capture',\n    { multiple: false },\n  )\n\nexport const PLUGIN_CONTACT_SOURCES =\n  definePluginServiceContract<PluginContactSourceDeclaration>(\n    'core.contact-capture-sources',\n    { multiple: true },\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 writer is refused naming both —\n * the incumbent keeps serving.\n */\nexport function registerPluginContactCaptureWriter(\n  writer: PluginContactCaptureWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_CONTACT_CAPTURE, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** Declares a capture door. One source word has one owner. */\nexport function registerPluginContactSource(\n  declaration: PluginContactSourceDeclaration,\n  options?: { pluginId?: string },\n): void {\n  const key = declaration.source?.trim() ?? ''\n  if (!key) throw new Error('a contact capture source needs a source word')\n  if (!declaration.label?.trim()) {\n    throw new Error(`contact capture source \"${key}\" needs a label`)\n  }\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_CONTACT_SOURCES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `contact capture source \"${key}\" is already declared by ` +\n        `\"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(\n    PLUGIN_CONTACT_SOURCES,\n    { ...declaration, source: key },\n    {\n      ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n      key,\n    },\n  )\n}\n\nexport interface ResolvedPluginContactCaptureWriter {\n  /** The plugin that keeps people. */\n  pluginId: string\n  writer: PluginContactCaptureWriter\n}\n\n/** The writer with its owner, or `null` when no plugin keeps people here. */\nexport function pluginContactCaptureWriter(): ResolvedPluginContactCaptureWriter | null {\n  const entry = resolvePluginServices(PLUGIN_CONTACT_CAPTURE)[0]\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n\n/**\n * Hands one capture to the plugin that keeps people, or answers `null` when\n * no plugin does.\n *\n * `null` and a refusal are different answers and a silo treats them\n * differently: `null` is a workspace with no record system, where there is\n * nothing to record and nothing has gone wrong; a refusal is a record system\n * that considered this person and declined.\n */\nexport async function capturePluginContact(\n  request: PluginContactCaptureRequest,\n): Promise<PluginContactCaptured | null> {\n  const found = pluginContactCaptureWriter()\n  if (!found) return null\n  return found.writer.capture(request)\n}\n\n/** Every declared capture door, with its silo, in registration order. */\nexport function listPluginContactSources(): ResolvedPluginContactSource[] {\n  return resolvePluginServices(PLUGIN_CONTACT_SOURCES).map((entry) => ({\n    ...entry.impl,\n    pluginId: entry.pluginId,\n  }))\n}\n\n/** One declared capture door by its source word, or `null`. */\nexport function pluginContactSource(\n  source: string,\n): ResolvedPluginContactSource | null {\n  const key = source.trim()\n  const entry = resolvePluginServices(PLUGIN_CONTACT_SOURCES).find(\n    (one) => one.key === key,\n  )\n  return entry ? { ...entry.impl, pluginId: entry.pluginId } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_CONTACT_CAPTURE","multiple","PLUGIN_CONTACT_SOURCES","registerPluginContactCaptureWriter","writer","options","pluginId","registerPluginContactSource","declaration","key","source","trim","Error","label","incumbent","find","entry","pluginContactCaptureWriter","impl","capturePluginContact","request","found","capture","listPluginContactSources","map","pluginContactSource","one"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAkL1B,OAAO,MAAMC,yBACXH,4BACE,wBACA;IAAEI,UAAU;AAAM,GACnB;AAEH,OAAO,MAAMC,yBACXL,4BACE,gCACA;IAAEI,UAAU;AAAK,GAClB;AAEH;;;;;CAKC,GACD,OAAO,SAASE,mCACdC,MAAkC,EAClCC,OAA+B;IAE/BP,sBAAsBE,wBAAwBI,QAAQ,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,4DAA4D,GAC5D,OAAO,SAASC,4BACdC,WAA2C,EAC3CH,OAA+B;cAObT,OAAAA;QALNY,qBAEPA;IAFL,MAAMC,eAAMD,sBAAAA,YAAYE,MAAM,qBAAlBF,oBAAoBG,IAAI,qBAAM;IAC1C,IAAI,CAACF,KAAK,MAAM,IAAIG,MAAM;IAC1B,IAAI,GAACJ,qBAAAA,YAAYK,KAAK,qBAAjBL,mBAAmBG,IAAI,KAAI;QAC9B,MAAM,IAAIC,MAAM,CAAC,wBAAwB,EAAEH,IAAI,eAAe,CAAC;IACjE;IACA,MAAMH,WAAW,EAACV,SAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASC,QAAQ,YAA7CV,QAAiD,IAAIe,IAAI;IAC3E,MAAMG,YAAYf,sBAAsBG,wBAAwBa,IAAI,CAClE,CAACC,QAAUA,MAAMP,GAAG,KAAKA;IAE3B,IAAIK,aAAaR,YAAYQ,UAAUR,QAAQ,KAAKA,UAAU;QAC5D,MAAM,IAAIM,MACR,CAAC,wBAAwB,EAAEH,IAAI,yBAAyB,CAAC,GACvD,CAAC,CAAC,EAAEK,UAAUR,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAEtD;IACAR,sBACEI,wBACA,aAAKM;QAAaE,QAAQD;QAC1B,aACMJ,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;QAC1DG;;AAGN;AAQA,2EAA2E,GAC3E,OAAO,SAASQ;IACd,MAAMD,QAAQjB,sBAAsBC,uBAAuB,CAAC,EAAE;IAC9D,OAAOgB,QAAQ;QAAEV,UAAUU,MAAMV,QAAQ;QAAEF,QAAQY,MAAME,IAAI;IAAC,IAAI;AACpE;AAEA;;;;;;;;CAQC,GACD,OAAO,eAAeC,qBACpBC,OAAoC;IAEpC,MAAMC,QAAQJ;IACd,IAAI,CAACI,OAAO,OAAO;IACnB,OAAOA,MAAMjB,MAAM,CAACkB,OAAO,CAACF;AAC9B;AAEA,uEAAuE,GACvE,OAAO,SAASG;IACd,OAAOxB,sBAAsBG,wBAAwBsB,GAAG,CAAC,CAACR,QAAW,aAChEA,MAAME,IAAI;YACbZ,UAAUU,MAAMV,QAAQ;;AAE5B;AAEA,6DAA6D,GAC7D,OAAO,SAASmB,oBACdf,MAAc;IAEd,MAAMD,MAAMC,OAAOC,IAAI;IACvB,MAAMK,QAAQjB,sBAAsBG,wBAAwBa,IAAI,CAC9D,CAACW,MAAQA,IAAIjB,GAAG,KAAKA;IAEvB,OAAOO,QAAQ,aAAKA,MAAME,IAAI;QAAEZ,UAAUU,MAAMV,QAAQ;SAAK;AAC/D"}