@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,147 @@
+/**
+ * @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.
+ */
+/**
+ * An entry one plugin files on a record another plugin keeps (AGL-2981).
+ *
+ * A person, a company and a deal are records of the workspace's record
+ * system, and what happened with them — an email sent, a reply received, a
+ * call to make — belongs on their timeline, whichever plugin it happened in.
+ * A plugin that sends mail or books a meeting must not write the record
+ * system's documents itself: it would restate the owner's rules — where an
+ * entry lives, who may see it, how a copy of the same email is told apart,
+ * how many entries a record may carry — and drift from them the day the
+ * owner changes one. Nor may it import the owner, which the package map
+ * forbids.
+ *
+ * So the record system registers a WRITER here, from its server surfaces,
+ * and a caller asks for it. Every rule stays the owner's:
+ *
+ *  - the entry is stamped with the scope a record made on the site would
+ *    carry, so it is visible to exactly who sees the record;
+ *  - an EMAIL is filed once per `Message-ID`, under the id the owner files a
+ *    copy of the same message by through any other door — a copy the rep
+ *    forwarded to a capture address is the same entry, not a second one;
+ *  - any other entry, and every task, is filed once per the caller's own
+ *    `dedupeKey`, so a caller that runs again finds what it wrote rather
+ *    than writing it twice;
+ *  - a record whose log is full, or a workspace whose plan carries no record
+ *    system, is refused — answered, never thrown.
+ *
+ * A single-implementation contract: a workspace keeps one record system.
+ *
+ * ## The caller proves who is asking
+ *
+ * Like `plugin-resource-drafts`, the registry authenticates nobody. The
+ * caller decides, in its own terms and before it asks, that the entry is
+ * the workspace's to write — that the record is one it acted on, for the
+ * member it acted for.
+ */
+/** The record an entry is filed on: any of the three, as the owner links them. */
+export interface PluginRecordLink {
+    contactId?: string;
+    companyId?: string;
+    dealId?: string;
+}
+/** Where an entry is filed, and by which plugin. */
+export interface PluginRecordEntryContext {
+    orgId: string;
+    /** The site whose scope the entry carries: as if a member made it there. */
+    hostId: string;
+    link: PluginRecordLink;
+    /** The plugin filing it, recorded on the entry. */
+    sourcePluginId: string;
+}
+/** What an activity is, in the record system's own words. */
+export type PluginRecordActivityKind = 'email' | 'call' | 'meeting' | 'note' | 'other';
+/** The message an `email` activity is about. */
+export interface PluginRecordEmail {
+    /** `outbound` for one the workspace wrote; `inbound` for one written to it. */
+    direction: 'outbound' | 'inbound';
+    subject: string;
+    /** The address on the message's From. */
+    from: string;
+    /** The address it was written to, when one is worth showing. */
+    to: string | null;
+    /** The `Message-ID` header, angle brackets included: what files it once. */
+    messageId: string;
+    /** The `Message-ID` it answered, when it answered one. */
+    inReplyTo?: string | null;
+}
+export interface PluginRecordActivityRequest extends PluginRecordEntryContext {
+    kind: PluginRecordActivityKind;
+    /** When it happened, epoch ms. */
+    atMs: number;
+    /** Plain text: an email's excerpt, a note's words. The owner bounds it. */
+    body: string;
+    /** The member it is by, or `''` for none. */
+    byUid: string;
+    byName?: string | null;
+    /** Required for an `email`, and read only for one. */
+    email?: PluginRecordEmail | null;
+    /** Required for every kind but `email`: the caller's id for this entry. */
+    dedupeKey?: string | null;
+}
+/** What a task is, in the record system's own words. */
+export type PluginRecordTaskKind = 'call' | 'email' | 'meeting' | 'todo';
+export interface PluginRecordTaskRequest extends PluginRecordEntryContext {
+    /** The caller's id for this task: the same key never makes a second task. */
+    dedupeKey: string;
+    title: string;
+    notes?: string | null;
+    kind: PluginRecordTaskKind;
+    /** When it is due, epoch ms. */
+    dueAtMs: number;
+    /** The member it is for, or `''` for nobody. */
+    assigneeUid: string;
+    /** The member who made it happen, or `''` when nobody did. */
+    createdByUid: string;
+}
+/**
+ * The owner's answer. `created: false` is the entry a previous write — or a
+ * copy through another door — already filed, under the same `id`.
+ */
+export type PluginRecordWrite = {
+    ok: true;
+    id: string;
+    created: boolean;
+} | {
+    ok: false;
+    status: 400 | 403 | 404 | 409;
+    /** Customer-safe: a caller may show or log it as it stands. */
+    error: string;
+};
+export interface PluginRecordTimelineWriter {
+    logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>;
+    createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>;
+}
+export declare const PLUGIN_RECORD_TIMELINE: import("./plugin-services").PluginServiceContract<PluginRecordTimelineWriter>;
+/**
+ * Registers the workspace's record timeline writer. 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 registerPluginRecordTimelineWriter(writer: PluginRecordTimelineWriter, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginRecordTimelineWriter {
+    /** The plugin that keeps the records. */
+    pluginId: string;
+    writer: PluginRecordTimelineWriter;
+}
+/** The writer, with its owner, or `null` when no plugin keeps records here. */
+export declare function pluginRecordTimelineWriter(): ResolvedPluginRecordTimelineWriter | null;

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

@@ -0,0 +1,39 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_RECORD_TIMELINE = definePluginServiceContract('core.record-timeline', {
+    multiple: false
+});
+/**
+ * Registers the workspace's record timeline writer. 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 registerPluginRecordTimelineWriter(writer, options) {
+    registerPluginService(PLUGIN_RECORD_TIMELINE, writer, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The writer, with its owner, or `null` when no plugin keeps records here. */ export function pluginRecordTimelineWriter() {
+    const entry = resolvePluginServices(PLUGIN_RECORD_TIMELINE)[0];
+    return entry ? {
+        pluginId: entry.pluginId,
+        writer: entry.impl
+    } : null;
+}
+
+//# sourceMappingURL=plugin-record-timeline.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-timeline.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * An entry one plugin files on a record another plugin keeps (AGL-2981).\n *\n * A person, a company and a deal are records of the workspace's record\n * system, and what happened with them — an email sent, a reply received, a\n * call to make — belongs on their timeline, whichever plugin it happened in.\n * A plugin that sends mail or books a meeting must not write the record\n * system's documents itself: it would restate the owner's rules — where an\n * entry lives, who may see it, how a copy of the same email is told apart,\n * how many entries a record may carry — and drift from them the day the\n * owner changes one. Nor may it import the owner, which the package map\n * forbids.\n *\n * So the record system registers a WRITER here, from its server surfaces,\n * and a caller asks for it. Every rule stays the owner's:\n *\n *  - the entry is stamped with the scope a record made on the site would\n *    carry, so it is visible to exactly who sees the record;\n *  - an EMAIL is filed once per `Message-ID`, under the id the owner files a\n *    copy of the same message by through any other door — a copy the rep\n *    forwarded to a capture address is the same entry, not a second one;\n *  - any other entry, and every task, is filed once per the caller's own\n *    `dedupeKey`, so a caller that runs again finds what it wrote rather\n *    than writing it twice;\n *  - a record whose log is full, or a workspace whose plan carries no record\n *    system, is refused — answered, never thrown.\n *\n * A single-implementation contract: a workspace keeps one record system.\n *\n * ## The caller proves who is asking\n *\n * Like `plugin-resource-drafts`, the registry authenticates nobody. The\n * caller decides, in its own terms and before it asks, that the entry is\n * the workspace's to write — that the record is one it acted on, for the\n * member it acted for.\n */\n\n/** The record an entry is filed on: any of the three, as the owner links them. */\nexport interface PluginRecordLink {\n  contactId?: string\n  companyId?: string\n  dealId?: string\n}\n\n/** Where an entry is filed, and by which plugin. */\nexport interface PluginRecordEntryContext {\n  orgId: string\n  /** The site whose scope the entry carries: as if a member made it there. */\n  hostId: string\n  link: PluginRecordLink\n  /** The plugin filing it, recorded on the entry. */\n  sourcePluginId: string\n}\n\n/** What an activity is, in the record system's own words. */\nexport type PluginRecordActivityKind = 'email' | 'call' | 'meeting' | 'note' | 'other'\n\n/** The message an `email` activity is about. */\nexport interface PluginRecordEmail {\n  /** `outbound` for one the workspace wrote; `inbound` for one written to it. */\n  direction: 'outbound' | 'inbound'\n  subject: string\n  /** The address on the message's From. */\n  from: string\n  /** The address it was written to, when one is worth showing. */\n  to: string | null\n  /** The `Message-ID` header, angle brackets included: what files it once. */\n  messageId: string\n  /** The `Message-ID` it answered, when it answered one. */\n  inReplyTo?: string | null\n}\n\nexport interface PluginRecordActivityRequest extends PluginRecordEntryContext {\n  kind: PluginRecordActivityKind\n  /** When it happened, epoch ms. */\n  atMs: number\n  /** Plain text: an email's excerpt, a note's words. The owner bounds it. */\n  body: string\n  /** The member it is by, or `''` for none. */\n  byUid: string\n  byName?: string | null\n  /** Required for an `email`, and read only for one. */\n  email?: PluginRecordEmail | null\n  /** Required for every kind but `email`: the caller's id for this entry. */\n  dedupeKey?: string | null\n}\n\n/** What a task is, in the record system's own words. */\nexport type PluginRecordTaskKind = 'call' | 'email' | 'meeting' | 'todo'\n\nexport interface PluginRecordTaskRequest extends PluginRecordEntryContext {\n  /** The caller's id for this task: the same key never makes a second task. */\n  dedupeKey: string\n  title: string\n  notes?: string | null\n  kind: PluginRecordTaskKind\n  /** When it is due, epoch ms. */\n  dueAtMs: number\n  /** The member it is for, or `''` for nobody. */\n  assigneeUid: string\n  /** The member who made it happen, or `''` when nobody did. */\n  createdByUid: string\n}\n\n/**\n * The owner's answer. `created: false` is the entry a previous write — or a\n * copy through another door — already filed, under the same `id`.\n */\nexport type PluginRecordWrite =\n  | { ok: true; id: string; created: boolean }\n  | {\n      ok: false\n      status: 400 | 403 | 404 | 409\n      /** Customer-safe: a caller may show or log it as it stands. */\n      error: string\n    }\n\nexport interface PluginRecordTimelineWriter {\n  logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite>\n  createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite>\n}\n\nexport const PLUGIN_RECORD_TIMELINE = definePluginServiceContract<PluginRecordTimelineWriter>(\n  'core.record-timeline',\n  { multiple: false },\n)\n\n/**\n * Registers the workspace's record timeline writer. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`; with neither\n * the registration throws, and a second plugin's writer is refused naming\n * both — the incumbent keeps serving.\n */\nexport function registerPluginRecordTimelineWriter(\n  writer: PluginRecordTimelineWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_TIMELINE, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginRecordTimelineWriter {\n  /** The plugin that keeps the records. */\n  pluginId: string\n  writer: PluginRecordTimelineWriter\n}\n\n/** The writer, with its owner, or `null` when no plugin keeps records here. */\nexport function pluginRecordTimelineWriter(): ResolvedPluginRecordTimelineWriter | null {\n  const entry = resolvePluginServices(PLUGIN_RECORD_TIMELINE)[0]\n  return entry ? { pluginId: entry.pluginId, writer: entry.impl } : null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_TIMELINE","multiple","registerPluginRecordTimelineWriter","writer","options","pluginId","pluginRecordTimelineWriter","entry","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA4H1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,mCACdC,MAAkC,EAClCC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,QAAQ,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,uBAAuB,CAAC,EAAE;IAC9D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,QAAQI,MAAMC,IAAI;IAAC,IAAI;AACpE"}

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

@@ -0,0 +1,137 @@
+/**
+ * @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.
+ */
+/**
+ * Drafts one plugin writes for another (AGL-2912).
+ *
+ * A resource belongs to the plugin that models it: the document's shape, the
+ * allowance a create counts against, who may create one, and what makes one
+ * well-formed. A different plugin that produces such a resource — an importer
+ * turning a file into pages, a generator turning a brief into an email, a
+ * migration bringing campaigns over from another tool — must not write the
+ * document itself, because it would restate the owner's rules and drift from
+ * them the day the owner changes one. Nor may it import the owner, which the
+ * package map forbids.
+ *
+ * So the owner registers a WRITER for the resource from its server surfaces,
+ * and a caller asks for one by resource name. Every rule stays the owner's:
+ *
+ *  - `refusal` answers, before the caller spends anything, whether this
+ *    member may create one on this site now: their role, the site's room;
+ *  - `check` answers, synchronously and without I/O, whether content is
+ *    well-formed, so a caller can hold what it produces to the owner's rules
+ *    before it keeps it;
+ *  - `read` reports the draft already written under an id, so a caller that
+ *    runs again finds its draft rather than making a second;
+ *  - `write` makes the draft, meets the allowance inside its own write, and
+ *    never publishes, schedules or sends anything.
+ *
+ * Built on the typed service registry (`plugin-services`): one contract, every
+ * writer registered under its resource name as the service's key.
+ *
+ * ## The registry carries no authorization of the CALLER
+ *
+ * Like `order-fulfilment`, a writer is a pre-authorized operation. It applies
+ * the owner's rules to the member the draft is for, and knows nothing about
+ * whether the caller may act for that member. A caller establishes, in its
+ * own terms and before it asks: who is asking, that the org owns the site,
+ * and that the owning plugin is switched on for that site.
+ *
+ * ## One writer per resource
+ *
+ * A resource has one owner. A second plugin registering a writer for a
+ * resource another plugin already writes is refused, naming both, and the
+ * incumbent keeps serving; the same plugin registering again — from its second
+ * server surface, or on a hot reload — replaces its own.
+ */
+/** Who a draft is for, on which site, and when. */
+export interface PluginDraftContext {
+    orgId: string;
+    hostId: string;
+    /** The member the draft is made for: the owner applies its rules to them and records them as the author. */
+    uid: string;
+    /** The org document the caller already read, for the owner's entitlement and allowance reads. */
+    org: Readonly<Record<string, unknown>> | null;
+    now: Date;
+}
+/** Why a draft cannot be made. */
+export interface PluginDraftRefusal {
+    status: 400 | 403 | 404 | 409;
+    /** Customer-safe: a caller shows it as it stands. */
+    error: string;
+}
+/** A draft that exists. */
+export interface PluginDraftRecord {
+    id: string;
+    name: string;
+    /** The version the draft opens on, where the resource has versions. */
+    versionId: string | null;
+    /** What the owner reports about the draft beyond its identity, in the shape its writer documents. */
+    facts: Readonly<Record<string, unknown>>;
+}
+export interface PluginDraftRequest extends PluginDraftContext {
+    /** The draft's id, chosen by the caller: one per act, so a write asked again finds its draft. */
+    id: string;
+    /** The name asked for; the owner may number it to keep it unique. */
+    name: string;
+    /** The resource's content, in the shape the owner's writer documents and validates. */
+    content: Readonly<Record<string, unknown>>;
+}
+export type PluginDraftCheck = {
+    ok: true;
+    facts: Readonly<Record<string, unknown>>;
+} | {
+    ok: false;
+    problems: string[];
+};
+export type PluginDraftWrite = (PluginDraftRecord & {
+    ok: true;
+    replayed: boolean;
+}) | (PluginDraftRefusal & {
+    ok: false;
+});
+export interface PluginResourceDraftWriter {
+    /** Whether this member may create one on this site now; `null` admits. */
+    refusal(context: PluginDraftContext): Promise<PluginDraftRefusal | null>;
+    /** Whether content is well-formed, with what the owner derived from it. Pure. */
+    check(content: Readonly<Record<string, unknown>>, context: {
+        hostId: string;
+    }): PluginDraftCheck;
+    /** The draft written under `id`, or `null`. */
+    read(context: {
+        hostId: string;
+        id: string;
+    }): Promise<PluginDraftRecord | null>;
+    /** Makes the draft; a refusal is returned, never thrown. */
+    write(request: PluginDraftRequest): Promise<PluginDraftWrite>;
+}
+export declare const PLUGIN_RESOURCE_DRAFTS: import("./plugin-services").PluginServiceContract<PluginResourceDraftWriter>;
+/**
+ * Registers the writer for a resource. The owner is the loader's marker when
+ * a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A writer for a resource another plugin writes throws
+ * naming both.
+ */
+export declare function registerPluginResourceDraftWriter(resource: string, writer: PluginResourceDraftWriter, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginDraftWriter {
+    /** The plugin that owns the resource. */
+    pluginId: string;
+    writer: PluginResourceDraftWriter;
+}
+/** The writer for a resource, with its owner, or `null` when no plugin writes it. */
+export declare function pluginResourceDraftWriter(resource: string): ResolvedPluginDraftWriter | null;

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

@@ -0,0 +1,51 @@
+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_RESOURCE_DRAFTS = definePluginServiceContract('core.resource-drafts', {
+    multiple: true
+});
+/**
+ * Registers the writer for a resource. The owner is the loader's marker when
+ * a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A writer for a resource another plugin writes throws
+ * naming both.
+ */ export function registerPluginResourceDraftWriter(resource, writer, options) {
+    var _ref, _getRegisteringPluginId;
+    const key = resource.trim();
+    if (!key) throw new Error('a resource draft writer needs a resource name');
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    const incumbent = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find((entry)=>entry.key === key);
+    if (incumbent && pluginId && incumbent.pluginId !== pluginId) {
+        throw new Error(`resource "${key}" already has a draft writer from "${incumbent.pluginId}"; ` + `refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_RESOURCE_DRAFTS, writer, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, {
+        key
+    }));
+}
+/** The writer for a resource, with its owner, or `null` when no plugin writes it. */ export function pluginResourceDraftWriter(resource) {
+    const key = resource.trim();
+    const entry = resolvePluginServices(PLUGIN_RESOURCE_DRAFTS).find((one)=>one.key === key);
+    return entry ? {
+        pluginId: entry.pluginId,
+        writer: entry.impl
+    } : null;
+}
+
+//# sourceMappingURL=plugin-resource-drafts.js.map

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

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

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

@@ -0,0 +1,94 @@
+/**
+ * @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 contract token. `T` is the implementation type and is carried at the
+ * type level only; `__type` never holds a value.
+ */
+export interface PluginServiceContract<T> {
+    readonly id: string;
+    /**
+     * Whether more than one plugin may register against the contract. A
+     * single-implementation contract (`false`) is a slot — an AI provider
+     * routing table, a payment processor — where a second registration from a
+     * different plugin is a conflict, not a list. A multiple contract is a set
+     * every implementation joins.
+     */
+    readonly multiple: boolean;
+    readonly __type?: T;
+}
+export interface PluginServiceRegistration<T> {
+    contractId: string;
+    pluginId: string;
+    /**
+     * Which of a plugin's implementations this is, on a multiple contract
+     * where one plugin registers several (two provider adapters from one
+     * plugin). Absent when the plugin registers one.
+     */
+    key?: string;
+    impl: T;
+    /** Higher resolves first among several implementations; default 0. */
+    priority: number;
+}
+/**
+ * Declares a contract. Idempotent by id for the same `multiple` setting, so
+ * a hot reload or a second surface re-evaluating the declaring module gets
+ * the token back; declaring the same id with a DIFFERENT setting is a
+ * programming error and throws, because two plugins would then disagree
+ * about whether the seam is a slot or a set.
+ */
+export declare function definePluginServiceContract<T>(id: string, options: {
+    multiple: boolean;
+}): PluginServiceContract<T>;
+/**
+ * Registers an implementation. The owner is the loader's marker when a
+ * register fn is running, else `options.pluginId`; a registration with
+ * neither throws.
+ *
+ * Re-registration by the SAME plugin under the same `key` replaces its
+ * previous entry (hot reload, a second surface, a repeated init); a plugin
+ * registering several implementations on a multiple contract tells them
+ * apart with `key`. On a single-implementation contract a registration
+ * from a DIFFERENT plugin throws naming both, and the incumbent keeps
+ * serving.
+ */
+export declare function registerPluginService<T>(contract: PluginServiceContract<T>, impl: T, options?: {
+    pluginId?: string;
+    priority?: number;
+    key?: string;
+}): void;
+/**
+ * Every implementation of a contract, highest priority first and
+ * registration order within a priority. Empty when nothing registered.
+ */
+export declare function resolvePluginServices<T>(contract: PluginServiceContract<T>): PluginServiceRegistration<T>[];
+/**
+ * The one implementation of a single contract — or, on a multiple
+ * contract, the highest-priority one — or `undefined`.
+ */
+export declare function resolvePluginService<T>(contract: PluginServiceContract<T>): T | undefined;
+/** Whether any plugin has registered against the contract. */
+export declare function hasPluginService<T>(contract: PluginServiceContract<T>): boolean;
+/** Every declared contract id, for diagnostics. */
+export declare function listPluginServiceContracts(): string[];
+/**
+ * Drops a plugin's registrations across every contract — what the loader's
+ * reverse (a bundle unloading) would call, and what a spec calls to give
+ * one fake plugin back its slot.
+ */
+export declare function unregisterPluginServices(pluginId: string): void;
+/** Test seam: forget every registration; contracts stay defined. */
+export declare function resetPluginServicesForTests(): void;

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

@@ -0,0 +1,153 @@
+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.
+ */ /**
+ * Typed plugin service registry (AGL-2940).
+ *
+ * A plugin that wants OTHER plugins to extend it — a provider behind a
+ * contract, a tool a generator can call, a generator kind — declares a
+ * contract token here, and any plugin (first-party or marketplace) registers
+ * an implementation against the token. The declaring plugin resolves the
+ * implementations when it needs them and never imports the plugin that
+ * supplied one, so the dependency runs only from an adopter to a contract.
+ *
+ * `registerBillingWebhookHandler` and `registerSiteRuntime` are the
+ * precedent: one registry per extension seam, filled at registration time,
+ * read lazily. What those cannot do is carry a TYPE for the thing registered
+ * beyond their one shape, and each new seam meant a new module in core. A
+ * contract token carries the implementation type with it, so a seam another
+ * plugin invents needs no core edit at all.
+ *
+ * Attribution follows every other registry: the owner is the plugin whose
+ * register fn is running (`setRegisteringPluginId`), or the `pluginId` the
+ * caller names for a registration made at module scope, where the loader's
+ * marker is not yet set. An implementation with no owner is refused —
+ * ownership is what lets a duplicate single-service registration name both
+ * claimants rather than silently taking the later one.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const contracts = new Map();
+const registrations = new Map();
+/**
+ * Declares a contract. Idempotent by id for the same `multiple` setting, so
+ * a hot reload or a second surface re-evaluating the declaring module gets
+ * the token back; declaring the same id with a DIFFERENT setting is a
+ * programming error and throws, because two plugins would then disagree
+ * about whether the seam is a slot or a set.
+ */ export function definePluginServiceContract(id, options) {
+    const key = id.trim();
+    if (!key) throw new Error('a plugin service contract needs an id');
+    const existing = contracts.get(key);
+    if (existing) {
+        if (existing.multiple !== options.multiple) {
+            throw new Error(`plugin service contract "${key}" is already defined with ` + `multiple=${existing.multiple}; cannot redefine it with ` + `multiple=${options.multiple}`);
+        }
+        return existing;
+    }
+    const contract = {
+        id: key,
+        multiple: options.multiple
+    };
+    contracts.set(key, contract);
+    return contract;
+}
+function requireContract(contract) {
+    const known = contracts.get(contract.id);
+    if (!known) {
+        throw new Error(`plugin service contract "${contract.id}" is not defined; call ` + 'definePluginServiceContract before registering against it');
+    }
+    return known;
+}
+/**
+ * Registers an implementation. The owner is the loader's marker when a
+ * register fn is running, else `options.pluginId`; a registration with
+ * neither throws.
+ *
+ * Re-registration by the SAME plugin under the same `key` replaces its
+ * previous entry (hot reload, a second surface, a repeated init); a plugin
+ * registering several implementations on a multiple contract tells them
+ * apart with `key`. On a single-implementation contract a registration
+ * from a DIFFERENT plugin throws naming both, and the incumbent keeps
+ * serving.
+ */ export function registerPluginService(contract, impl, options) {
+    var _ref, _getRegisteringPluginId, _registrations_get, _ref1;
+    var _options_key;
+    const known = requireContract(contract);
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`plugin service "${known.id}" registered with no owner: pass ` + '{ pluginId } when registering outside a plugin register fn');
+    }
+    const key = (options == null ? void 0 : (_options_key = options.key) == null ? void 0 : _options_key.trim()) || undefined;
+    const list = (_registrations_get = registrations.get(known.id)) != null ? _registrations_get : [];
+    const foreign = list.find((entry)=>entry.pluginId !== pluginId);
+    if (!known.multiple && foreign) {
+        throw new Error(`plugin service "${known.id}" is a single-implementation contract ` + `already registered by "${foreign.pluginId}"; refused "${pluginId}"`);
+    }
+    const kept = list.filter((entry)=>{
+        var _entry_key;
+        return !(entry.pluginId === pluginId && ((_entry_key = entry.key) != null ? _entry_key : null) === (key != null ? key : null));
+    });
+    kept.push(_extends({
+        contractId: known.id,
+        pluginId
+    }, key ? {
+        key
+    } : {}, {
+        impl,
+        priority: (_ref1 = options == null ? void 0 : options.priority) != null ? _ref1 : 0
+    }));
+    registrations.set(known.id, kept);
+}
+/**
+ * Every implementation of a contract, highest priority first and
+ * registration order within a priority. Empty when nothing registered.
+ */ export function resolvePluginServices(contract) {
+    var _registrations_get;
+    const known = requireContract(contract);
+    const list = (_registrations_get = registrations.get(known.id)) != null ? _registrations_get : [];
+    return [
+        ...list
+    ].sort((a, b)=>b.priority - a.priority);
+}
+/**
+ * The one implementation of a single contract — or, on a multiple
+ * contract, the highest-priority one — or `undefined`.
+ */ export function resolvePluginService(contract) {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(contract)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+/** Whether any plugin has registered against the contract. */ export function hasPluginService(contract) {
+    var _registrations_get;
+    return ((_registrations_get = registrations.get(requireContract(contract).id)) != null ? _registrations_get : []).length > 0;
+}
+/** Every declared contract id, for diagnostics. */ export function listPluginServiceContracts() {
+    return [
+        ...contracts.keys()
+    ];
+}
+/**
+ * Drops a plugin's registrations across every contract — what the loader's
+ * reverse (a bundle unloading) would call, and what a spec calls to give
+ * one fake plugin back its slot.
+ */ export function unregisterPluginServices(pluginId) {
+    for (const [id, list] of registrations){
+        registrations.set(id, list.filter((entry)=>entry.pluginId !== pluginId));
+    }
+}
+/** Test seam: forget every registration; contracts stay defined. */ export function resetPluginServicesForTests() {
+    registrations.clear();
+}
+
+//# sourceMappingURL=plugin-services.js.map