@aglyn/aglyn 1.0.0-beta.182 → 1.0.0-beta.184

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

@@ -1 +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"}
+{"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 type { ReusableComponentTree } from '../app-utils/compose-reusable-components'\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\n/** What a check is told beside the content. */\nexport interface PluginDraftCheckContext {\n  hostId: string\n  /**\n   * The site's published reusable components the content places, keyed by id\n   * — what `loadReferencedComponents` reads (AGL-3287).\n   *\n   * `check` does no I/O, so a caller whose content may place a component loads\n   * the definitions first and hands them in; a writer whose resource renders\n   * placed components composes them before judging, so what passes is what\n   * would render. Absent means none were loaded, and the content is judged as\n   * written.\n   */\n  components?: Readonly<Record<string, ReusableComponentTree | undefined>>\n}\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: PluginDraftCheckContext,\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;AAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyH1B,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"}