@aglyn/aglyn 1.0.0-beta.270 → 1.0.0-beta.271

package/src/lib/plugin-manager/plugin-ai-capabilities.d.ts

@@ -114,6 +114,17 @@ export interface PluginAiCapabilityDraftContext {
         id: string;
     }>>;
 }
+/** One field a capability asks a person to fill (AGL-3978). */
+export interface PluginAiCapabilityInputField {
+    /** The item's argument the answer is written to. */
+    arg: string;
+    /** The field's label, naming the provider: "Meta pixel ID". */
+    label: string;
+    /** What an answer looks like, as a person reads it: "8–20 digits". */
+    shape: string;
+    /** What an answer is held to; no flags. */
+    pattern: RegExp;
+}
 export interface PluginAiCapability {
     /** The operation's name in a plan, stable across releases: `page`, `note`. */
     op: string;
@@ -167,6 +178,14 @@ export interface PluginAiCapability {
      * be built.
      */
     missingInput?(item: PluginAiCapabilityItem): string | null;
+    /**
+     * The fields that ask what `missingInput` asks (AGL-3978), one per id the
+     * item needs, each naming its provider and held to the pattern the
+     * operation holds it to. Pure. With fields, a build that needs them waits
+     * in `needs_input` for the person to fill them and goes on from there;
+     * without, it ends with the question. Absent: no item asks.
+     */
+    inputFields?(item: PluginAiCapabilityItem): readonly PluginAiCapabilityInputField[];
     /** Operations an item of this one may depend on. */
     dependsOnOps?: readonly string[];
     degrade: PluginAiCapabilityDegrade;

package/src/lib/plugin-manager/plugin-ai-capabilities.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-ai-capabilities.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 * What an AI build can make, contributed by the plugin that owns each thing\n * (AGL-3616).\n *\n * A build turns one request — \"a few pages, a contact form and a way to book\n * me\" — into a plan of ITEMS, each an operation (`op`) with arguments, and\n * runs them in dependency order. The AI plugin plans and meters the build;\n * it does not know what a plugin's resource is, and the package map forbids\n * it importing that plugin. So every operation is a CAPABILITY the owner\n * registers from its server entry, and the build asks for one by `op`:\n *\n *  - the planner offers the model only the operations registered here, in\n *    the owner's own words (`noun`, `intents`, `argsSchema`);\n *  - admission removes an item whose capability this site, plan or member\n *    cannot use (`feature`, `permission`, `quota`, `freeAllowed`), with a\n *    sentence, so the rest of the plan still runs;\n *  - the item is executed one of two ways: `runnerKind` hands it to an\n *    existing AI job runner (the AI plugin's own operations), and\n *    `draftResource` hands its content to the owner's writer on\n *    `plugin-resource-drafts`, which checks it, meets the allowance and\n *    writes a draft that nothing publishes.\n *\n * An operation lights up the moment its owner registers it; nothing in the\n * AI plugin names it. Register by CALLING `registerPluginAiCapability` from a\n * function the server entry runs — a top-level side effect is dropped by a\n * bundler that sees no import of its result.\n *\n * Server-only: import this file by its own path, never from the barrel that\n * every published page loads.\n *\n * ## One capability per operation\n *\n * An operation has one owner. A second plugin registering an `op` another\n * plugin already owns is refused, naming both, and the incumbent keeps\n * serving; the same plugin registering again replaces its own.\n */\n\n/** A value an item's arguments may hold: scalars and lists of strings only. */\nexport type PluginAiCapabilityArgValue = string | number | boolean | readonly string[]\n\n/** An item's arguments, in the shape its capability's `argsSchema` declares. */\nexport type PluginAiCapabilityArgs = Readonly<Record<string, PluginAiCapabilityArgValue>>\n\n/**\n * One argument, as a JSON Schema property the model fills in directly. The\n * subset is deliberately small: a flat object of scalars and string lists is\n * what a planner can be held to, and what `pluginAiCapabilityArgsProblems`\n * checks without a schema library.\n */\nexport interface PluginAiCapabilityArgProperty {\n  type: 'string' | 'integer' | 'number' | 'boolean' | 'array'\n  /** Read by the model: what the value means and how to choose it. */\n  description: string\n  /** For `string`: the allowed values. */\n  enum?: readonly string[]\n  /** For `integer`/`number`. */\n  minimum?: number\n  maximum?: number\n  /** For `string`, and each item of an `array`. */\n  maxLength?: number\n  /** For `array`: always a list of strings. */\n  items?: { type: 'string'; enum?: readonly string[]; maxLength?: number }\n  maxItems?: number\n}\n\n/** A flat JSON Schema object: no nesting, no extra keys. */\nexport interface PluginAiCapabilityArgsSchema {\n  type: 'object'\n  properties: Readonly<Record<string, PluginAiCapabilityArgProperty>>\n  required?: readonly string[]\n  additionalProperties: false\n}\n\n/** How the items that depend on a failed item of this capability behave. */\nexport type PluginAiCapabilityDegrade =\n  /** Dependents are built without it (a page loses the block that used it). */\n  | 'omit'\n  /** Dependents use something that already exists in its place (a site's own layout). */\n  | 'fallback'\n\n/** One planned item, as a capability sees it. */\nexport interface PluginAiCapabilityItem {\n  /** The item's name in the plan, unique within it; other items cite it as `new:<name>`. */\n  name: string\n  args: PluginAiCapabilityArgs\n  /** Why the planner says the request needs it, where it said. */\n  why?: string\n}\n\n/** What a capability's `draftContent` is told beside the item. */\nexport interface PluginAiCapabilityDraftContext {\n  hostId: string\n  /**\n   * The drafts written for the items this one depends on, keyed by the\n   * reference the plan used (`new:<name>`), each with its operation and the\n   * id its own writer or runner gave it. A dependency that did not succeed is\n   * absent.\n   */\n  dependencies: Readonly<Record<string, { op: string; id: string }>>\n}\n\nexport interface PluginAiCapability {\n  /** The operation's name in a plan, stable across releases: `page`, `note`. */\n  op: string\n  /** What one is called in a sentence a person reads: \"contact form\". */\n  noun: string\n  /** Where a person finds the draft afterwards: \"Notes → Drafts\". */\n  where: string\n  /**\n   * What a person might ask for that this makes, as short phrases the chat's\n   * instructions list. True of the shipped product: never a promise the\n   * writer cannot keep.\n   */\n  intents: readonly string[]\n  /** The item's arguments, which the planner fills in. */\n  argsSchema: PluginAiCapabilityArgsSchema\n  /** How many items of this operation one plan may hold. */\n  maxPerPlan: number\n  /** Whether a workspace on the free plan may have one made. */\n  freeAllowed: boolean\n  /** The entitlement a workspace needs, checked with the platform's entitlement read. */\n  feature?: string\n  /** The site permission the member needs. */\n  permission?: string\n  /** The allowance one counts against, which the owner's writer meets. */\n  quota?: string\n  /**\n   * The resource whose writer on `plugin-resource-drafts` makes the draft.\n   * Exactly one of this and `runnerKind` is set.\n   */\n  draftResource?: string\n  /**\n   * The AI job kind whose runner makes it — the AI plugin's own operations.\n   * Exactly one of this and `draftResource` is set.\n   */\n  runnerKind?: string\n  /**\n   * The writer's write takes effect at once, because the resource has no\n   * draft state (a redirect rule, AGL-3745; a CRM pipeline or custom field,\n   * AGL-3746), so the job reports the item as live in `where` rather than as\n   * a draft. Absent: the writer writes a draft.\n   */\n  live?: boolean\n  /** The most this item can cost, in AI credits; a draft written without a model costs 0. */\n  estimateCredits(args: PluginAiCapabilityArgs): number\n  /**\n   * The question to ask the person when an item leaves out something only\n   * they can give — an account id the planner must never make up — or\n   * `null` when the item can be built. Pure. A plan holding such an item is\n   * not kept: the build asks this instead of building nothing, or building\n   * it from a made-up value. Absent: every item that passes its schema can\n   * be built.\n   */\n  missingInput?(item: PluginAiCapabilityItem): string | null\n  /** Operations an item of this one may depend on. */\n  dependsOnOps?: readonly string[]\n  degrade: PluginAiCapabilityDegrade\n  /**\n   * Blocks a page places when it uses an item of this operation (the block\n   * names the page palette knows). When the item fails, a dependent page is\n   * built without them, and says so.\n   */\n  pageBlocks?: readonly string[]\n  /**\n   * The writer's content for an item, from its arguments and its built\n   * dependencies. Pure. Absent means the arguments ARE the content.\n   */\n  draftContent?(\n    item: PluginAiCapabilityItem,\n    context: PluginAiCapabilityDraftContext,\n  ): Readonly<Record<string, unknown>>\n}\n\nexport const PLUGIN_AI_CAPABILITIES = definePluginServiceContract<PluginAiCapability>(\n  'core.ai-capabilities',\n  { multiple: true },\n)\n\nconst OP_PATTERN = /^[a-z][a-z0-9-]{0,39}$/\n\n/** Why a capability cannot be registered, or `null`. */\nexport function pluginAiCapabilityProblem(capability: PluginAiCapability): string | null {\n  if (!OP_PATTERN.test(capability.op)) {\n    return `ai capability op \"${capability.op}\" must be lowercase letters, digits and dashes`\n  }\n  const executors = [capability.draftResource, capability.runnerKind].filter(\n    (one) => typeof one === 'string' && one.trim(),\n  )\n  if (executors.length !== 1) {\n    return `ai capability \"${capability.op}\" needs exactly one of draftResource and runnerKind`\n  }\n  if (!Number.isInteger(capability.maxPerPlan) || capability.maxPerPlan < 1) {\n    return `ai capability \"${capability.op}\" needs a maxPerPlan of at least 1`\n  }\n  if (capability.argsSchema?.type !== 'object' || capability.argsSchema.additionalProperties !== false) {\n    return `ai capability \"${capability.op}\" needs a flat object argsSchema with additionalProperties: false`\n  }\n  for (const required of capability.argsSchema.required ?? []) {\n    if (!(required in capability.argsSchema.properties)) {\n      return `ai capability \"${capability.op}\" requires \"${required}\", which its schema does not declare`\n    }\n  }\n  if (!capability.noun.trim() || !capability.where.trim()) {\n    return `ai capability \"${capability.op}\" needs a noun and a where`\n  }\n  return null\n}\n\n/**\n * Registers what a plugin's AI builds can make. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`. An `op`\n * another plugin owns throws naming both; a malformed capability throws.\n */\nexport function registerPluginAiCapability(\n  capability: PluginAiCapability,\n  options?: { pluginId?: string },\n): void {\n  const problem = pluginAiCapabilityProblem(capability)\n  if (problem) throw new Error(problem)\n  const key = capability.op\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `ai capability \"${key}\" is already registered by \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_AI_CAPABILITIES, capability, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginAiCapability {\n  /** The plugin that owns the operation. */\n  pluginId: string\n  capability: PluginAiCapability\n}\n\n/** Every registered capability with its owner, in registration order. */\nexport function pluginAiCapabilities(): ResolvedPluginAiCapability[] {\n  return resolvePluginServices(PLUGIN_AI_CAPABILITIES).map((entry) => ({\n    pluginId: entry.pluginId,\n    capability: entry.impl,\n  }))\n}\n\n/** The capability for an operation, with its owner, or `null` when nothing registered it. */\nexport function pluginAiCapability(op: string): ResolvedPluginAiCapability | null {\n  const key = op.trim()\n  const entry = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, capability: entry.impl } : null\n}\n\n/**\n * What is wrong with an item's arguments against its schema; empty when\n * nothing is. Pure, and the same answer on both sides of the seam: the\n * planner holds the model to it, and an owner may hold its content to it.\n */\nexport function pluginAiCapabilityArgsProblems(\n  schema: PluginAiCapabilityArgsSchema,\n  args: Readonly<Record<string, unknown>>,\n): string[] {\n  const problems: string[] = []\n  for (const name of schema.required ?? []) {\n    const value = args[name]\n    if (value === undefined || value === null || value === '') problems.push(`\"${name}\" is required`)\n  }\n  for (const [name, value] of Object.entries(args)) {\n    const property = schema.properties[name]\n    if (!property) {\n      problems.push(`\"${name}\" is not an argument`)\n      continue\n    }\n    if (value === undefined || value === null) continue\n    switch (property.type) {\n      case 'string':\n        if (typeof value !== 'string') problems.push(`\"${name}\" must be text`)\n        else {\n          if (property.enum && !property.enum.includes(value)) {\n            problems.push(`\"${name}\" must be one of ${property.enum.join(', ')}`)\n          }\n          if (property.maxLength !== undefined && value.length > property.maxLength) {\n            problems.push(`\"${name}\" must be at most ${property.maxLength} characters`)\n          }\n        }\n        break\n      case 'integer':\n      case 'number':\n        if (\n          typeof value !== 'number' ||\n          !Number.isFinite(value) ||\n          (property.type === 'integer' && !Number.isInteger(value))\n        ) {\n          problems.push(`\"${name}\" must be ${property.type === 'integer' ? 'a whole number' : 'a number'}`)\n        } else {\n          if (property.minimum !== undefined && value < property.minimum) {\n            problems.push(`\"${name}\" must be at least ${property.minimum}`)\n          }\n          if (property.maximum !== undefined && value > property.maximum) {\n            problems.push(`\"${name}\" must be at most ${property.maximum}`)\n          }\n        }\n        break\n      case 'boolean':\n        if (typeof value !== 'boolean') problems.push(`\"${name}\" must be true or false`)\n        break\n      case 'array':\n        if (!Array.isArray(value) || value.some((one) => typeof one !== 'string')) {\n          problems.push(`\"${name}\" must be a list of text`)\n        } else {\n          if (property.maxItems !== undefined && value.length > property.maxItems) {\n            problems.push(`\"${name}\" must hold at most ${property.maxItems}`)\n          }\n          const items = property.items\n          for (const one of value as string[]) {\n            if (items?.enum && !items.enum.includes(one)) {\n              problems.push(`\"${name}\" holds \"${one}\", which is not one of ${items.enum.join(', ')}`)\n              break\n            }\n            if (items?.maxLength !== undefined && one.length > items.maxLength) {\n              problems.push(`\"${name}\" holds an entry longer than ${items.maxLength} characters`)\n              break\n            }\n          }\n        }\n        break\n    }\n  }\n  return problems\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_AI_CAPABILITIES","multiple","OP_PATTERN","pluginAiCapabilityProblem","capability","test","op","executors","draftResource","runnerKind","filter","one","trim","length","Number","isInteger","maxPerPlan","argsSchema","type","additionalProperties","required","properties","noun","where","registerPluginAiCapability","options","problem","Error","key","pluginId","incumbent","find","entry","pluginAiCapabilities","map","impl","pluginAiCapability","pluginAiCapabilityArgsProblems","schema","args","problems","name","value","undefined","push","Object","entries","property","enum","includes","join","maxLength","isFinite","minimum","maximum","Array","isArray","some","maxItems","items"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-ai-capabilities.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 * What an AI build can make, contributed by the plugin that owns each thing\n * (AGL-3616).\n *\n * A build turns one request — \"a few pages, a contact form and a way to book\n * me\" — into a plan of ITEMS, each an operation (`op`) with arguments, and\n * runs them in dependency order. The AI plugin plans and meters the build;\n * it does not know what a plugin's resource is, and the package map forbids\n * it importing that plugin. So every operation is a CAPABILITY the owner\n * registers from its server entry, and the build asks for one by `op`:\n *\n *  - the planner offers the model only the operations registered here, in\n *    the owner's own words (`noun`, `intents`, `argsSchema`);\n *  - admission removes an item whose capability this site, plan or member\n *    cannot use (`feature`, `permission`, `quota`, `freeAllowed`), with a\n *    sentence, so the rest of the plan still runs;\n *  - the item is executed one of two ways: `runnerKind` hands it to an\n *    existing AI job runner (the AI plugin's own operations), and\n *    `draftResource` hands its content to the owner's writer on\n *    `plugin-resource-drafts`, which checks it, meets the allowance and\n *    writes a draft that nothing publishes.\n *\n * An operation lights up the moment its owner registers it; nothing in the\n * AI plugin names it. Register by CALLING `registerPluginAiCapability` from a\n * function the server entry runs — a top-level side effect is dropped by a\n * bundler that sees no import of its result.\n *\n * Server-only: import this file by its own path, never from the barrel that\n * every published page loads.\n *\n * ## One capability per operation\n *\n * An operation has one owner. A second plugin registering an `op` another\n * plugin already owns is refused, naming both, and the incumbent keeps\n * serving; the same plugin registering again replaces its own.\n */\n\n/** A value an item's arguments may hold: scalars and lists of strings only. */\nexport type PluginAiCapabilityArgValue = string | number | boolean | readonly string[]\n\n/** An item's arguments, in the shape its capability's `argsSchema` declares. */\nexport type PluginAiCapabilityArgs = Readonly<Record<string, PluginAiCapabilityArgValue>>\n\n/**\n * One argument, as a JSON Schema property the model fills in directly. The\n * subset is deliberately small: a flat object of scalars and string lists is\n * what a planner can be held to, and what `pluginAiCapabilityArgsProblems`\n * checks without a schema library.\n */\nexport interface PluginAiCapabilityArgProperty {\n  type: 'string' | 'integer' | 'number' | 'boolean' | 'array'\n  /** Read by the model: what the value means and how to choose it. */\n  description: string\n  /** For `string`: the allowed values. */\n  enum?: readonly string[]\n  /** For `integer`/`number`. */\n  minimum?: number\n  maximum?: number\n  /** For `string`, and each item of an `array`. */\n  maxLength?: number\n  /** For `array`: always a list of strings. */\n  items?: { type: 'string'; enum?: readonly string[]; maxLength?: number }\n  maxItems?: number\n}\n\n/** A flat JSON Schema object: no nesting, no extra keys. */\nexport interface PluginAiCapabilityArgsSchema {\n  type: 'object'\n  properties: Readonly<Record<string, PluginAiCapabilityArgProperty>>\n  required?: readonly string[]\n  additionalProperties: false\n}\n\n/** How the items that depend on a failed item of this capability behave. */\nexport type PluginAiCapabilityDegrade =\n  /** Dependents are built without it (a page loses the block that used it). */\n  | 'omit'\n  /** Dependents use something that already exists in its place (a site's own layout). */\n  | 'fallback'\n\n/** One planned item, as a capability sees it. */\nexport interface PluginAiCapabilityItem {\n  /** The item's name in the plan, unique within it; other items cite it as `new:<name>`. */\n  name: string\n  args: PluginAiCapabilityArgs\n  /** Why the planner says the request needs it, where it said. */\n  why?: string\n}\n\n/** What a capability's `draftContent` is told beside the item. */\nexport interface PluginAiCapabilityDraftContext {\n  hostId: string\n  /**\n   * The drafts written for the items this one depends on, keyed by the\n   * reference the plan used (`new:<name>`), each with its operation and the\n   * id its own writer or runner gave it. A dependency that did not succeed is\n   * absent.\n   */\n  dependencies: Readonly<Record<string, { op: string; id: string }>>\n}\n\n/** One field a capability asks a person to fill (AGL-3978). */\nexport interface PluginAiCapabilityInputField {\n  /** The item's argument the answer is written to. */\n  arg: string\n  /** The field's label, naming the provider: \"Meta pixel ID\". */\n  label: string\n  /** What an answer looks like, as a person reads it: \"8–20 digits\". */\n  shape: string\n  /** What an answer is held to; no flags. */\n  pattern: RegExp\n}\n\nexport interface PluginAiCapability {\n  /** The operation's name in a plan, stable across releases: `page`, `note`. */\n  op: string\n  /** What one is called in a sentence a person reads: \"contact form\". */\n  noun: string\n  /** Where a person finds the draft afterwards: \"Notes → Drafts\". */\n  where: string\n  /**\n   * What a person might ask for that this makes, as short phrases the chat's\n   * instructions list. True of the shipped product: never a promise the\n   * writer cannot keep.\n   */\n  intents: readonly string[]\n  /** The item's arguments, which the planner fills in. */\n  argsSchema: PluginAiCapabilityArgsSchema\n  /** How many items of this operation one plan may hold. */\n  maxPerPlan: number\n  /** Whether a workspace on the free plan may have one made. */\n  freeAllowed: boolean\n  /** The entitlement a workspace needs, checked with the platform's entitlement read. */\n  feature?: string\n  /** The site permission the member needs. */\n  permission?: string\n  /** The allowance one counts against, which the owner's writer meets. */\n  quota?: string\n  /**\n   * The resource whose writer on `plugin-resource-drafts` makes the draft.\n   * Exactly one of this and `runnerKind` is set.\n   */\n  draftResource?: string\n  /**\n   * The AI job kind whose runner makes it — the AI plugin's own operations.\n   * Exactly one of this and `draftResource` is set.\n   */\n  runnerKind?: string\n  /**\n   * The writer's write takes effect at once, because the resource has no\n   * draft state (a redirect rule, AGL-3745; a CRM pipeline or custom field,\n   * AGL-3746), so the job reports the item as live in `where` rather than as\n   * a draft. Absent: the writer writes a draft.\n   */\n  live?: boolean\n  /** The most this item can cost, in AI credits; a draft written without a model costs 0. */\n  estimateCredits(args: PluginAiCapabilityArgs): number\n  /**\n   * The question to ask the person when an item leaves out something only\n   * they can give — an account id the planner must never make up — or\n   * `null` when the item can be built. Pure. A plan holding such an item is\n   * not kept: the build asks this instead of building nothing, or building\n   * it from a made-up value. Absent: every item that passes its schema can\n   * be built.\n   */\n  missingInput?(item: PluginAiCapabilityItem): string | null\n  /**\n   * The fields that ask what `missingInput` asks (AGL-3978), one per id the\n   * item needs, each naming its provider and held to the pattern the\n   * operation holds it to. Pure. With fields, a build that needs them waits\n   * in `needs_input` for the person to fill them and goes on from there;\n   * without, it ends with the question. Absent: no item asks.\n   */\n  inputFields?(item: PluginAiCapabilityItem): readonly PluginAiCapabilityInputField[]\n  /** Operations an item of this one may depend on. */\n  dependsOnOps?: readonly string[]\n  degrade: PluginAiCapabilityDegrade\n  /**\n   * Blocks a page places when it uses an item of this operation (the block\n   * names the page palette knows). When the item fails, a dependent page is\n   * built without them, and says so.\n   */\n  pageBlocks?: readonly string[]\n  /**\n   * The writer's content for an item, from its arguments and its built\n   * dependencies. Pure. Absent means the arguments ARE the content.\n   */\n  draftContent?(\n    item: PluginAiCapabilityItem,\n    context: PluginAiCapabilityDraftContext,\n  ): Readonly<Record<string, unknown>>\n}\n\nexport const PLUGIN_AI_CAPABILITIES = definePluginServiceContract<PluginAiCapability>(\n  'core.ai-capabilities',\n  { multiple: true },\n)\n\nconst OP_PATTERN = /^[a-z][a-z0-9-]{0,39}$/\n\n/** Why a capability cannot be registered, or `null`. */\nexport function pluginAiCapabilityProblem(capability: PluginAiCapability): string | null {\n  if (!OP_PATTERN.test(capability.op)) {\n    return `ai capability op \"${capability.op}\" must be lowercase letters, digits and dashes`\n  }\n  const executors = [capability.draftResource, capability.runnerKind].filter(\n    (one) => typeof one === 'string' && one.trim(),\n  )\n  if (executors.length !== 1) {\n    return `ai capability \"${capability.op}\" needs exactly one of draftResource and runnerKind`\n  }\n  if (!Number.isInteger(capability.maxPerPlan) || capability.maxPerPlan < 1) {\n    return `ai capability \"${capability.op}\" needs a maxPerPlan of at least 1`\n  }\n  if (capability.argsSchema?.type !== 'object' || capability.argsSchema.additionalProperties !== false) {\n    return `ai capability \"${capability.op}\" needs a flat object argsSchema with additionalProperties: false`\n  }\n  for (const required of capability.argsSchema.required ?? []) {\n    if (!(required in capability.argsSchema.properties)) {\n      return `ai capability \"${capability.op}\" requires \"${required}\", which its schema does not declare`\n    }\n  }\n  if (!capability.noun.trim() || !capability.where.trim()) {\n    return `ai capability \"${capability.op}\" needs a noun and a where`\n  }\n  return null\n}\n\n/**\n * Registers what a plugin's AI builds can make. The owner is the loader's\n * marker when a register fn is running, else `options.pluginId`. An `op`\n * another plugin owns throws naming both; a malformed capability throws.\n */\nexport function registerPluginAiCapability(\n  capability: PluginAiCapability,\n  options?: { pluginId?: string },\n): void {\n  const problem = pluginAiCapabilityProblem(capability)\n  if (problem) throw new Error(problem)\n  const key = capability.op\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  const incumbent = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && pluginId && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `ai capability \"${key}\" is already registered by \"${incumbent.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_AI_CAPABILITIES, capability, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    key,\n  })\n}\n\nexport interface ResolvedPluginAiCapability {\n  /** The plugin that owns the operation. */\n  pluginId: string\n  capability: PluginAiCapability\n}\n\n/** Every registered capability with its owner, in registration order. */\nexport function pluginAiCapabilities(): ResolvedPluginAiCapability[] {\n  return resolvePluginServices(PLUGIN_AI_CAPABILITIES).map((entry) => ({\n    pluginId: entry.pluginId,\n    capability: entry.impl,\n  }))\n}\n\n/** The capability for an operation, with its owner, or `null` when nothing registered it. */\nexport function pluginAiCapability(op: string): ResolvedPluginAiCapability | null {\n  const key = op.trim()\n  const entry = resolvePluginServices(PLUGIN_AI_CAPABILITIES).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, capability: entry.impl } : null\n}\n\n/**\n * What is wrong with an item's arguments against its schema; empty when\n * nothing is. Pure, and the same answer on both sides of the seam: the\n * planner holds the model to it, and an owner may hold its content to it.\n */\nexport function pluginAiCapabilityArgsProblems(\n  schema: PluginAiCapabilityArgsSchema,\n  args: Readonly<Record<string, unknown>>,\n): string[] {\n  const problems: string[] = []\n  for (const name of schema.required ?? []) {\n    const value = args[name]\n    if (value === undefined || value === null || value === '') problems.push(`\"${name}\" is required`)\n  }\n  for (const [name, value] of Object.entries(args)) {\n    const property = schema.properties[name]\n    if (!property) {\n      problems.push(`\"${name}\" is not an argument`)\n      continue\n    }\n    if (value === undefined || value === null) continue\n    switch (property.type) {\n      case 'string':\n        if (typeof value !== 'string') problems.push(`\"${name}\" must be text`)\n        else {\n          if (property.enum && !property.enum.includes(value)) {\n            problems.push(`\"${name}\" must be one of ${property.enum.join(', ')}`)\n          }\n          if (property.maxLength !== undefined && value.length > property.maxLength) {\n            problems.push(`\"${name}\" must be at most ${property.maxLength} characters`)\n          }\n        }\n        break\n      case 'integer':\n      case 'number':\n        if (\n          typeof value !== 'number' ||\n          !Number.isFinite(value) ||\n          (property.type === 'integer' && !Number.isInteger(value))\n        ) {\n          problems.push(`\"${name}\" must be ${property.type === 'integer' ? 'a whole number' : 'a number'}`)\n        } else {\n          if (property.minimum !== undefined && value < property.minimum) {\n            problems.push(`\"${name}\" must be at least ${property.minimum}`)\n          }\n          if (property.maximum !== undefined && value > property.maximum) {\n            problems.push(`\"${name}\" must be at most ${property.maximum}`)\n          }\n        }\n        break\n      case 'boolean':\n        if (typeof value !== 'boolean') problems.push(`\"${name}\" must be true or false`)\n        break\n      case 'array':\n        if (!Array.isArray(value) || value.some((one) => typeof one !== 'string')) {\n          problems.push(`\"${name}\" must be a list of text`)\n        } else {\n          if (property.maxItems !== undefined && value.length > property.maxItems) {\n            problems.push(`\"${name}\" must hold at most ${property.maxItems}`)\n          }\n          const items = property.items\n          for (const one of value as string[]) {\n            if (items?.enum && !items.enum.includes(one)) {\n              problems.push(`\"${name}\" holds \"${one}\", which is not one of ${items.enum.join(', ')}`)\n              break\n            }\n            if (items?.maxLength !== undefined && one.length > items.maxLength) {\n              problems.push(`\"${name}\" holds an entry longer than ${items.maxLength} characters`)\n              break\n            }\n          }\n        }\n        break\n    }\n  }\n  return problems\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_AI_CAPABILITIES","multiple","OP_PATTERN","pluginAiCapabilityProblem","capability","test","op","executors","draftResource","runnerKind","filter","one","trim","length","Number","isInteger","maxPerPlan","argsSchema","type","additionalProperties","required","properties","noun","where","registerPluginAiCapability","options","problem","Error","key","pluginId","incumbent","find","entry","pluginAiCapabilities","map","impl","pluginAiCapability","pluginAiCapabilityArgsProblems","schema","args","problems","name","value","undefined","push","Object","entries","property","enum","includes","join","maxLength","isFinite","minimum","maximum","Array","isArray","some","maxItems","items"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-domain-search.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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.
+ */
+/**
+ * Searching for a domain name to register, as core asks for it (AGL-3958).
+ *
+ * The one-screen build for a client has a Domain step: staff type what the
+ * owner wants, see what is free with its first-year and renewal price side by
+ * side, and record the pick on the bundle link, so the owner buys it on their
+ * own phone after subscribing. Which registrar answers, and what it charges,
+ * is the domains plugin's; core asks through this slot and never imports it.
+ *
+ * One implementation, registered from the provider plugin's
+ * `consoleServerDeclarations`: the only caller is a staff console route. A
+ * deployment with no provider, or one whose provider has no registrar
+ * configured, offers no search at all, and the step shows only "use the
+ * free address" and "I have a domain".
+ *
+ * Search only. Nothing here buys, holds or reserves a name.
+ */
+/** One name a search found. */
+export interface PluginDomainSearchResult {
+    /** The full name, lower case: `example.com`. */
+    name: string;
+    /** Whether the name can be registered now. */
+    available: boolean;
+    /** What the first year costs, in US dollars, as the owner will be charged. */
+    firstYearUsd: number;
+    /** What each year after costs, in US dollars. Shown beside the first year, always. */
+    renewalUsd: number;
+    /** A registry premium name, priced above the TLD's list price. */
+    premium?: boolean;
+}
+export interface PluginDomainSearch {
+    /**
+     * Names for a query: the exact name when the query is one, and close
+     * alternatives. `null` when the provider has no registrar configured in
+     * this deployment, so there is nothing to search with. May throw; the
+     * caller reports a failed search, never a partial one.
+     */
+    search(query: string): Promise<PluginDomainSearchResult[] | null>;
+}
+export declare const PLUGIN_DOMAIN_SEARCH: import("./plugin-services").PluginServiceContract<PluginDomainSearch>;
+/**
+ * Fills the slot. The owner is the loader's marker when a register fn is
+ * running, else `options.pluginId`; a second plugin's implementation is
+ * refused naming both.
+ */
+export declare function registerPluginDomainSearch(impl: PluginDomainSearch, options?: {
+    pluginId?: string;
+}): void;
+/** Whether a plugin offers domain search in this process: the step's "show the search?" */
+export declare function domainSearchRegistered(): boolean;
+/** What a caller learns from a search. */
+export type DomainSearchOutcome = {
+    status: 'ok';
+    results: PluginDomainSearchResult[];
+}
+/** No plugin offers search, or its registrar is not configured here. */
+ | {
+    status: 'unavailable';
+}
+/** The provider threw. Logged. */
+ | {
+    status: 'failed';
+};
+/** Searches through whichever plugin offers it. Never throws. */
+export declare function searchDomains(query: string): Promise<DomainSearchOutcome>;

package/src/lib/plugin-manager/plugin-domain-search.js

@@ -0,0 +1,63 @@
+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_DOMAIN_SEARCH = definePluginServiceContract('core.domain-search', {
+    multiple: false
+});
+/**
+ * Fills the slot. The owner is the loader's marker when a register fn is
+ * running, else `options.pluginId`; a second plugin's implementation is
+ * refused naming both.
+ */ export function registerPluginDomainSearch(impl, options) {
+    registerPluginService(PLUGIN_DOMAIN_SEARCH, impl, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** Whether a plugin offers domain search in this process: the step's "show the search?" */ export function domainSearchRegistered() {
+    return resolvePluginServices(PLUGIN_DOMAIN_SEARCH).length > 0;
+}
+/** Keeps a provider's answer to names and prices that can be shown as they are. */ function usable(result) {
+    const price = (value)=>typeof value === 'number' && Number.isFinite(value) && value >= 0;
+    return typeof (result == null ? void 0 : result.name) === 'string' && result.name.length > 0 && typeof result.available === 'boolean' && price(result.firstYearUsd) && price(result.renewalUsd);
+}
+/** Searches through whichever plugin offers it. Never throws. */ export async function searchDomains(query) {
+    var _resolvePluginServices_;
+    const impl = (_resolvePluginServices_ = resolvePluginServices(PLUGIN_DOMAIN_SEARCH)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+    if (!impl) return {
+        status: 'unavailable'
+    };
+    try {
+        const results = await impl.search(query);
+        if (results === null) return {
+            status: 'unavailable'
+        };
+        return {
+            status: 'ok',
+            results: (Array.isArray(results) ? results : []).filter(usable).map((result)=>_extends({}, result, {
+                    name: result.name.toLowerCase()
+                }))
+        };
+    } catch (error) {
+        // The query is a business name a prospect said aloud: not logged.
+        console.error('[domain-search] the provider failed a search', error);
+        return {
+            status: 'failed'
+        };
+    }
+}
+
+//# sourceMappingURL=plugin-domain-search.js.map

package/src/lib/plugin-manager/plugin-domain-search.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-domain-search.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 * Searching for a domain name to register, as core asks for it (AGL-3958).\n *\n * The one-screen build for a client has a Domain step: staff type what the\n * owner wants, see what is free with its first-year and renewal price side by\n * side, and record the pick on the bundle link, so the owner buys it on their\n * own phone after subscribing. Which registrar answers, and what it charges,\n * is the domains plugin's; core asks through this slot and never imports it.\n *\n * One implementation, registered from the provider plugin's\n * `consoleServerDeclarations`: the only caller is a staff console route. A\n * deployment with no provider, or one whose provider has no registrar\n * configured, offers no search at all, and the step shows only \"use the\n * free address\" and \"I have a domain\".\n *\n * Search only. Nothing here buys, holds or reserves a name.\n */\n\n/** One name a search found. */\nexport interface PluginDomainSearchResult {\n  /** The full name, lower case: `example.com`. */\n  name: string\n  /** Whether the name can be registered now. */\n  available: boolean\n  /** What the first year costs, in US dollars, as the owner will be charged. */\n  firstYearUsd: number\n  /** What each year after costs, in US dollars. Shown beside the first year, always. */\n  renewalUsd: number\n  /** A registry premium name, priced above the TLD's list price. */\n  premium?: boolean\n}\n\nexport interface PluginDomainSearch {\n  /**\n   * Names for a query: the exact name when the query is one, and close\n   * alternatives. `null` when the provider has no registrar configured in\n   * this deployment, so there is nothing to search with. May throw; the\n   * caller reports a failed search, never a partial one.\n   */\n  search(query: string): Promise<PluginDomainSearchResult[] | null>\n}\n\nexport const PLUGIN_DOMAIN_SEARCH = definePluginServiceContract<PluginDomainSearch>(\n  'core.domain-search',\n  { multiple: false },\n)\n\n/**\n * Fills the slot. The owner is the loader's marker when a register fn is\n * running, else `options.pluginId`; a second plugin's implementation is\n * refused naming both.\n */\nexport function registerPluginDomainSearch(\n  impl: PluginDomainSearch,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_DOMAIN_SEARCH, impl, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** Whether a plugin offers domain search in this process: the step's \"show the search?\" */\nexport function domainSearchRegistered(): boolean {\n  return resolvePluginServices(PLUGIN_DOMAIN_SEARCH).length > 0\n}\n\n/** What a caller learns from a search. */\nexport type DomainSearchOutcome =\n  | { status: 'ok'; results: PluginDomainSearchResult[] }\n  /** No plugin offers search, or its registrar is not configured here. */\n  | { status: 'unavailable' }\n  /** The provider threw. Logged. */\n  | { status: 'failed' }\n\n/** Keeps a provider's answer to names and prices that can be shown as they are. */\nfunction usable(result: PluginDomainSearchResult): boolean {\n  const price = (value: unknown) => typeof value === 'number' && Number.isFinite(value) && value >= 0\n  return (\n    typeof result?.name === 'string' &&\n    result.name.length > 0 &&\n    typeof result.available === 'boolean' &&\n    price(result.firstYearUsd) &&\n    price(result.renewalUsd)\n  )\n}\n\n/** Searches through whichever plugin offers it. Never throws. */\nexport async function searchDomains(query: string): Promise<DomainSearchOutcome> {\n  const impl = resolvePluginServices(PLUGIN_DOMAIN_SEARCH)[0]?.impl\n  if (!impl) return { status: 'unavailable' }\n  try {\n    const results = await impl.search(query)\n    if (results === null) return { status: 'unavailable' }\n    return {\n      status: 'ok',\n      results: (Array.isArray(results) ? results : [])\n        .filter(usable)\n        .map((result) => ({ ...result, name: result.name.toLowerCase() })),\n    }\n  } catch (error) {\n    // The query is a business name a prospect said aloud: not logged.\n    console.error('[domain-search] the provider failed a search', error)\n    return { status: 'failed' }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_DOMAIN_SEARCH","multiple","registerPluginDomainSearch","impl","options","pluginId","domainSearchRegistered","length","usable","result","price","value","Number","isFinite","name","available","firstYearUsd","renewalUsd","searchDomains","query","status","results","search","Array","isArray","filter","map","toLowerCase","error","console"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA4C1B,OAAO,MAAMC,uBAAuBH,4BAClC,sBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;CAIC,GACD,OAAO,SAASC,2BACdC,IAAwB,EACxBC,OAA+B;IAE/BN,sBAAsBE,sBAAsBG,MAAM,aAC5CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yFAAyF,GACzF,OAAO,SAASC;IACd,OAAOP,sBAAsBC,sBAAsBO,MAAM,GAAG;AAC9D;AAUA,iFAAiF,GACjF,SAASC,OAAOC,MAAgC;IAC9C,MAAMC,QAAQ,CAACC,QAAmB,OAAOA,UAAU,YAAYC,OAAOC,QAAQ,CAACF,UAAUA,SAAS;IAClG,OACE,QAAOF,0BAAAA,OAAQK,IAAI,MAAK,YACxBL,OAAOK,IAAI,CAACP,MAAM,GAAG,KACrB,OAAOE,OAAOM,SAAS,KAAK,aAC5BL,MAAMD,OAAOO,YAAY,KACzBN,MAAMD,OAAOQ,UAAU;AAE3B;AAEA,+DAA+D,GAC/D,OAAO,eAAeC,cAAcC,KAAa;QAClCpB;IAAb,MAAMI,QAAOJ,0BAAAA,sBAAsBC,qBAAqB,CAAC,EAAE,qBAA9CD,wBAAgDI,IAAI;IACjE,IAAI,CAACA,MAAM,OAAO;QAAEiB,QAAQ;IAAc;IAC1C,IAAI;QACF,MAAMC,UAAU,MAAMlB,KAAKmB,MAAM,CAACH;QAClC,IAAIE,YAAY,MAAM,OAAO;YAAED,QAAQ;QAAc;QACrD,OAAO;YACLA,QAAQ;YACRC,SAAS,AAACE,CAAAA,MAAMC,OAAO,CAACH,WAAWA,UAAU,EAAE,AAAD,EAC3CI,MAAM,CAACjB,QACPkB,GAAG,CAAC,CAACjB,SAAY,aAAKA;oBAAQK,MAAML,OAAOK,IAAI,CAACa,WAAW;;QAChE;IACF,EAAE,OAAOC,OAAO;QACd,kEAAkE;QAClEC,QAAQD,KAAK,CAAC,gDAAgDA;QAC9D,OAAO;YAAER,QAAQ;QAAS;IAC5B;AACF"}

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

@@ -45,7 +45,7 @@
  * gave, and a list that followed it would put the staff lockdown checklist
  * in a different order per session.
  */
-import type { HostAccessRole, OrgPlan, OrgRole } from '../foundation';
+import type { AglynOrgBilling, HostAccessRole, OrgPlan, OrgRole } from '../foundation';
 import { type PluginPermission } from './plugin-permissions';
 export interface PluginSeatAddonDeclaration {
     /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */
@@ -58,17 +58,35 @@ export interface PluginSeatAddonDeclaration {
      */
     maxUnits?: number;
     /**
-     * The quota each unit widens, per plan: the resolved entitlement named by
-     * `key` gains `perUnitByPlan[plan] × units`. A plan the add-on is not sold
-     * on declares 0.
+     * The quota each unit widens: the resolved entitlement named by `key`
+     * gains `perUnit(org, plan) × units` when the figure depends on WHAT was
+     * bought (the Aglyn AI tier, AGL-3965), else `perUnitByPlan[plan] × units`.
+     * A plan the add-on is not sold on answers 0.
      */
     quota?: {
         key: string;
-        perUnitByPlan: Readonly<Record<OrgPlan, number>>;
+        perUnitByPlan?: Readonly<Record<OrgPlan, number>>;
+        /**
+         * The per-unit figure read off the org itself. `org` is the billing
+         * document as `resolveOrgEntitlements` received it and `plan` its
+         * effective plan.
+         */
+        perUnit?: (org: Readonly<Partial<AglynOrgBilling>>, plan: OrgPlan) => number;
     };
     /** Feature flags a purchased unit switches on. */
     features?: readonly string[];
+    /**
+     * Whether a plan sells the add-on, when `perUnitByPlan` cannot say so
+     * (a `perUnit` quota, AGL-3965). Absent: sold where `perUnitByPlan` names
+     * a figure above zero, or everywhere for an add-on with no quota.
+     */
+    soldOn?: (plan: OrgPlan) => boolean;
 }
+/**
+ * Whether a plan sells a declared seat add-on: its own `soldOn`, else a
+ * `perUnitByPlan` figure above zero for the plan, else (no quota) yes.
+ */
+export declare function pluginSeatAddonSoldOn(addon: PluginSeatAddonDeclaration, plan: OrgPlan): boolean;
 export interface PluginFeatureDeclaration {
     /** The `OrgFeatureFlags` key. */
     key: string;

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

@@ -47,6 +47,16 @@
 var _globalScope, _REGISTRY_KEY, _;
 import { FIRST_PARTY_PLUGINS } from "./enabled-plugins.js";
 import { registerPluginPermissions } from "./plugin-permissions.js";
+/**
+ * Whether a plan sells a declared seat add-on: its own `soldOn`, else a
+ * `perUnitByPlan` figure above zero for the plan, else (no quota) yes.
+ */ export function pluginSeatAddonSoldOn(addon, plan) {
+    var _ref;
+    var _addon_quota_perUnitByPlan;
+    if (addon.soldOn) return addon.soldOn(plan);
+    if (!addon.quota) return true;
+    return ((_ref = (_addon_quota_perUnitByPlan = addon.quota.perUnitByPlan) == null ? void 0 : _addon_quota_perUnitByPlan[plan]) != null ? _ref : 0) > 0;
+}
 /**
  * The registrations and their listeners, held on `globalThis` rather than in
  * module `const`s (AGL-3596), as the custom field registry and the

package/src/lib/plugin-manager/plugin-entitlements.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-entitlements.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 * Plugin-declared billing and access keys (AGL-2940).\n *\n * A plugin that sells something, gates something, or can be switched off in\n * an incident declares the KEYS here — a seat add-on, a feature flag, a\n * lockdown lever, a permission — and the core catalogs that used to be\n * edited for each one read the declarations instead:\n *\n * - `plan-entitlements` folds every registered seat add-on into\n *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)\n *   and answers a registered feature's plan defaults;\n * - `lockdown` lists a registered lever on the staff page, carries its label,\n *   its staff-bypass rule and its visitor notice, and maps the API paths it\n *   names onto it for the plugin dispatcher;\n * - `plugin-permissions` receives the permissions with the owner filled in;\n * - `org-permissions` folds every declared catalog key into the org\n *   permission catalog — the role editor, custom roles, per-member overrides\n *   and the rules stamp — and `host-permissions` decides the keys that\n *   declare host-role defaults for a site collaborator, per site.\n *\n * The NUMBERS stay where they are checked. A seat add-on's price is a row in\n * `PLAN_PRICING`, read by the Stripe wiring and reconciled by\n * `check-pricing-drift`; a declaration names the quota it widens and by how\n * much per plan, and nothing here restates a price.\n *\n * Registration order is deterministic: the catalog order of\n * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules\n * load in parallel, so the order they REGISTER in is whatever the network\n * gave, and a list that followed it would put the staff lockdown checklist\n * in a different order per session.\n */\n\nimport type { HostAccessRole, OrgPlan, OrgRole } from '../foundation'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\nimport {\n  registerPluginPermissions,\n  type PluginPermission,\n} from './plugin-permissions'\n\nexport interface PluginSeatAddonDeclaration {\n  /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */\n  key: string\n  label: string\n  /**\n   * How many purchased units count. `1` for an org-wide add-on that is\n   * bought once, where a doubled webhook item or a hand edit above one is\n   * still one purchase; absent to count the stored quantity.\n   */\n  maxUnits?: number\n  /**\n   * The quota each unit widens, per plan: the resolved entitlement named by\n   * `key` gains `perUnitByPlan[plan] × units`. A plan the add-on is not sold\n   * on declares 0.\n   */\n  quota?: {\n    key: string\n    perUnitByPlan: Readonly<Record<OrgPlan, number>>\n  }\n  /** Feature flags a purchased unit switches on. */\n  features?: readonly string[]\n}\n\nexport interface PluginFeatureDeclaration {\n  /** The `OrgFeatureFlags` key. */\n  key: string\n  label: string\n  /**\n   * The plan defaults, when the key is not one the plan tables already\n   * carry. Absent means the plan tables decide, which is the case for every\n   * key that predates this registry.\n   */\n  defaultByPlan?: Readonly<Partial<Record<OrgPlan, boolean>>>\n}\n\nexport interface PluginLockdownFeatureDeclaration {\n  /** The lever's wire identity (`ai-generate`). */\n  key: string\n  /** The staff checklist's label. */\n  label: string\n  /**\n   * What the lever is called in the customer's mail when staff pull it for\n   * their workspace (`media uploads`, `AI generation`). A noun phrase that\n   * reads right mid-sentence (\"our team paused media uploads\") and after a\n   * colon, so lowercase unless it starts with a name or an acronym. The\n   * staff `label` never reaches a customer.\n   */\n  customerName: string\n  /**\n   * Whether a verified staff claim passes the lock. Granted where a staff\n   * action aids incident response — one real call proves a provider is back\n   * — and withheld where the staff action would BE the incident.\n   */\n  staffBypass: boolean\n  /**\n   * What a visitor reads while the lever is pulled: what is paused AND what\n   * still works. The expected-back window is appended by the notice builder.\n   */\n  notice: { title: string; body: string }\n  /**\n   * Plugin API paths the lever gates at the dispatcher: exact paths, and\n   * prefixes matched on a segment boundary (`ai/generate` also gates\n   * `ai/generate/section`, never `ai/generated-report`).\n   */\n  apiPaths?: { exact?: readonly string[]; prefixes?: readonly string[] }\n}\n\n/**\n * A key a plugin adds to the org permission CATALOG (AGL-2984): the granular\n * map custom roles and per-member overrides are stored in, that\n * `resolveOrgPermissions` layers and the rules stamp carries, and that the\n * role editor lists. A declared key is stored, layered and resolved exactly\n * like a core key; the declaration supplies what a core key's catalog entry\n * and role table supply.\n */\nexport interface PluginOrgPermissionDeclaration {\n  /** The dotted key a custom role and a per-member override store (`reviews.reply`). */\n  key: string\n  /** The role editor's line for the key, and the word a refusal names. */\n  label: string\n  /** What the key opens, under the label in the role editor. */\n  description: string\n  /** Each org role's verdict when no custom role or per-member override sets the key. */\n  roleDefaults: Readonly<Record<OrgRole, boolean>>\n  /**\n   * Each HOST role's verdict, for a key a site collaborator holds per site.\n   *\n   * A collaborator's membership carries no org standing to refine — it\n   * exists only to carry access to named sites — so a key with this field is\n   * decided for them on the site a request names: the host role they hold\n   * there, refined by the per-site toggle on their member document. A key\n   * without it is never held by a collaborator.\n   */\n  hostRoleDefaults?: Readonly<Record<HostAccessRole, boolean>>\n}\n\nexport interface PluginEntitlementRegistration {\n  pluginId: string\n  seatAddons?: readonly PluginSeatAddonDeclaration[]\n  features?: readonly PluginFeatureDeclaration[]\n  lockdownFeatures?: readonly PluginLockdownFeatureDeclaration[]\n  /** Per-tier keys a plugin's own pages read (`registerPluginPermissions`). */\n  permissions?: readonly Omit<PluginPermission, 'pluginId'>[]\n  /** Keys added to the org permission catalog — see {@link PluginOrgPermissionDeclaration}. */\n  orgPermissions?: readonly PluginOrgPermissionDeclaration[]\n}\n\n/**\n * The registrations and their listeners, held on `globalThis` rather than in\n * module `const`s (AGL-3596), as the custom field registry and the\n * declarations repair hook are (AGL-3412).\n *\n * An app registers the plugins' declarations from `instrumentation.ts`, which\n * Next compiles into a different module graph from the routes. A module-scoped\n * map was filled in the instrumentation's copy and read empty in a route's, so\n * a core route that never loaded a plugin knew none of its keys: the site\n * create door asked for `ai.generate`, read `undefined` from a catalog that\n * had never heard of it, and every guided AI start was born with the starter.\n * One map per process, under a `Symbol.for` key, is the same map in every\n * copy.\n */\nconst REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-entitlements')\n\ninterface PluginEntitlementsRegistry {\n  registrations: Map<string, PluginEntitlementRegistration>\n  /**\n   * Readers of the registrations that keep a derived view in step with them —\n   * every copy of the org permission catalog rebuilds itself on every\n   * registration and reset, because a plugin's declarations can register\n   * after a module that imported the catalog was evaluated, and in another\n   * module graph's copy of this file.\n   */\n  listeners: Set<() => void>\n}\n\nconst globalScope = globalThis as typeof globalThis & {\n  [REGISTRY_KEY]?: PluginEntitlementsRegistry\n}\n\nconst registry: PluginEntitlementsRegistry = (globalScope[REGISTRY_KEY] ??= {\n  registrations: new Map(),\n  listeners: new Set(),\n})\n\nconst registrations = registry.registrations\nconst listeners = registry.listeners\n\n/** Calls `listener` after every registration and reset; answers the unsubscribe. */\nexport function subscribePluginEntitlements(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\nfunction notifyListeners(): void {\n  for (const listener of [...listeners]) listener()\n}\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\nfunction orderedRegistrations(): PluginEntitlementRegistration[] {\n  return [...registrations.values()].sort(\n    (a, b) =>\n      catalogRank(a.pluginId) - catalogRank(b.pluginId) ||\n      a.pluginId.localeCompare(b.pluginId),\n  )\n}\n\nfunction refuseStolenKeys(\n  pluginId: string,\n  kind: 'seat add-on' | 'lockdown feature' | 'org permission',\n  keys: readonly string[],\n  ownerOf: (key: string) => string | undefined,\n): void {\n  for (const key of keys) {\n    const owner = ownerOf(key)\n    if (owner && owner !== pluginId) {\n      throw new Error(\n        `${kind} \"${key}\" is already declared by \"${owner}\"; refused \"${pluginId}\"`,\n      )\n    }\n  }\n}\n\n/**\n * Idempotent per plugin — re-registration replaces that plugin's\n * declarations. A seat add-on, lockdown or catalog permission key another\n * plugin already owns refuses the whole registration: one key, one owner,\n * or the two declarations disagree about what the key means.\n */\nexport function registerPluginEntitlements(\n  registration: PluginEntitlementRegistration,\n): void {\n  const pluginId = registration.pluginId.trim()\n  if (!pluginId) throw new Error('plugin entitlements need a pluginId')\n  refuseStolenKeys(\n    pluginId,\n    'seat add-on',\n    (registration.seatAddons ?? []).map((entry) => entry.key),\n    (key) => pluginSeatAddonOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'lockdown feature',\n    (registration.lockdownFeatures ?? []).map((entry) => entry.key),\n    (key) => pluginLockdownFeatureOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'org permission',\n    (registration.orgPermissions ?? []).map((entry) => entry.key),\n    (key) => pluginOrgPermissionOwner(key),\n  )\n  registrations.set(pluginId, { ...registration, pluginId })\n  if (registration.permissions?.length) {\n    registerPluginPermissions(\n      registration.permissions.map((permission) => ({ ...permission, pluginId })),\n    )\n  }\n  notifyListeners()\n}\n\nfunction pluginSeatAddonOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.seatAddons?.some((addon) => addon.key === key)) return entry.pluginId\n  }\n  return undefined\n}\n\nfunction pluginLockdownFeatureOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.lockdownFeatures?.some((feature) => feature.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\nfunction pluginOrgPermissionOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.orgPermissions?.some((permission) => permission.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\n/** Every declared catalog permission, in catalog order, with the plugin that declared it. */\nexport function listPluginOrgPermissions(): Array<\n  PluginOrgPermissionDeclaration & { pluginId: string }\n> {\n  return orderedRegistrations().flatMap((entry) =>\n    (entry.orgPermissions ?? []).map((permission) => ({\n      ...permission,\n      pluginId: entry.pluginId,\n    })),\n  )\n}\n\n/** Every declared seat add-on, in catalog order. */\nexport function listPluginSeatAddons(): PluginSeatAddonDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.seatAddons ?? [])])\n}\n\n/** One declared seat add-on by its `seatAddons` key. */\nexport function pluginSeatAddon(key: string): PluginSeatAddonDeclaration | undefined {\n  return listPluginSeatAddons().find((entry) => entry.key === key)\n}\n\n/** Every declared feature, in catalog order. */\nexport function listPluginFeatures(): PluginFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.features ?? [])])\n}\n\n/** Every declared lockdown lever, in catalog order. */\nexport function listPluginLockdownFeatures(): PluginLockdownFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [\n    ...(entry.lockdownFeatures ?? []),\n  ])\n}\n\n/** One declared lockdown lever by key. */\nexport function pluginLockdownFeature(\n  key: string,\n): PluginLockdownFeatureDeclaration | undefined {\n  return listPluginLockdownFeatures().find((entry) => entry.key === key)\n}\n\n/** The plugin that declared a lockdown lever, for attribution. */\nexport function pluginIdForLockdownFeature(key: string): string | undefined {\n  return pluginLockdownFeatureOwner(key)\n}\n\n/** Every registration, in catalog order. */\nexport function listPluginEntitlementRegistrations(): PluginEntitlementRegistration[] {\n  return orderedRegistrations()\n}\n\n/**\n * Test seam: forget every registration. The per-tier permissions stay\n * registered; the catalog permissions go with their registrations.\n */\nexport function resetPluginEntitlementsForTests(): void {\n  registrations.clear()\n  notifyListeners()\n}\n"],"names":["globalScope","REGISTRY_KEY","FIRST_PARTY_PLUGINS","registerPluginPermissions","Symbol","for","globalThis","registry","registrations","Map","listeners","Set","subscribePluginEntitlements","listener","add","delete","notifyListeners","CATALOG_ORDER","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","orderedRegistrations","values","sort","a","b","localeCompare","refuseStolenKeys","kind","keys","ownerOf","key","owner","Error","registerPluginEntitlements","registration","trim","seatAddons","entry","pluginSeatAddonOwner","lockdownFeatures","pluginLockdownFeatureOwner","orgPermissions","pluginOrgPermissionOwner","set","permissions","length","permission","some","addon","undefined","feature","listPluginOrgPermissions","flatMap","listPluginSeatAddons","pluginSeatAddon","find","listPluginFeatures","features","listPluginLockdownFeatures","pluginLockdownFeature","pluginIdForLockdownFeature","listPluginEntitlementRegistrations","resetPluginEntitlementsForTests","clear"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-entitlements.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 * Plugin-declared billing and access keys (AGL-2940).\n *\n * A plugin that sells something, gates something, or can be switched off in\n * an incident declares the KEYS here — a seat add-on, a feature flag, a\n * lockdown lever, a permission — and the core catalogs that used to be\n * edited for each one read the declarations instead:\n *\n * - `plan-entitlements` folds every registered seat add-on into\n *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)\n *   and answers a registered feature's plan defaults;\n * - `lockdown` lists a registered lever on the staff page, carries its label,\n *   its staff-bypass rule and its visitor notice, and maps the API paths it\n *   names onto it for the plugin dispatcher;\n * - `plugin-permissions` receives the permissions with the owner filled in;\n * - `org-permissions` folds every declared catalog key into the org\n *   permission catalog — the role editor, custom roles, per-member overrides\n *   and the rules stamp — and `host-permissions` decides the keys that\n *   declare host-role defaults for a site collaborator, per site.\n *\n * The NUMBERS stay where they are checked. A seat add-on's price is a row in\n * `PLAN_PRICING`, read by the Stripe wiring and reconciled by\n * `check-pricing-drift`; a declaration names the quota it widens and by how\n * much per plan, and nothing here restates a price.\n *\n * Registration order is deterministic: the catalog order of\n * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules\n * load in parallel, so the order they REGISTER in is whatever the network\n * gave, and a list that followed it would put the staff lockdown checklist\n * in a different order per session.\n */\n\nimport type { AglynOrgBilling, HostAccessRole, OrgPlan, OrgRole } from '../foundation'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\nimport {\n  registerPluginPermissions,\n  type PluginPermission,\n} from './plugin-permissions'\n\nexport interface PluginSeatAddonDeclaration {\n  /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */\n  key: string\n  label: string\n  /**\n   * How many purchased units count. `1` for an org-wide add-on that is\n   * bought once, where a doubled webhook item or a hand edit above one is\n   * still one purchase; absent to count the stored quantity.\n   */\n  maxUnits?: number\n  /**\n   * The quota each unit widens: the resolved entitlement named by `key`\n   * gains `perUnit(org, plan) × units` when the figure depends on WHAT was\n   * bought (the Aglyn AI tier, AGL-3965), else `perUnitByPlan[plan] × units`.\n   * A plan the add-on is not sold on answers 0.\n   */\n  quota?: {\n    key: string\n    perUnitByPlan?: Readonly<Record<OrgPlan, number>>\n    /**\n     * The per-unit figure read off the org itself. `org` is the billing\n     * document as `resolveOrgEntitlements` received it and `plan` its\n     * effective plan.\n     */\n    perUnit?: (org: Readonly<Partial<AglynOrgBilling>>, plan: OrgPlan) => number\n  }\n  /** Feature flags a purchased unit switches on. */\n  features?: readonly string[]\n  /**\n   * Whether a plan sells the add-on, when `perUnitByPlan` cannot say so\n   * (a `perUnit` quota, AGL-3965). Absent: sold where `perUnitByPlan` names\n   * a figure above zero, or everywhere for an add-on with no quota.\n   */\n  soldOn?: (plan: OrgPlan) => boolean\n}\n\n/**\n * Whether a plan sells a declared seat add-on: its own `soldOn`, else a\n * `perUnitByPlan` figure above zero for the plan, else (no quota) yes.\n */\nexport function pluginSeatAddonSoldOn(\n  addon: PluginSeatAddonDeclaration,\n  plan: OrgPlan,\n): boolean {\n  if (addon.soldOn) return addon.soldOn(plan)\n  if (!addon.quota) return true\n  return (addon.quota.perUnitByPlan?.[plan] ?? 0) > 0\n}\n\nexport interface PluginFeatureDeclaration {\n  /** The `OrgFeatureFlags` key. */\n  key: string\n  label: string\n  /**\n   * The plan defaults, when the key is not one the plan tables already\n   * carry. Absent means the plan tables decide, which is the case for every\n   * key that predates this registry.\n   */\n  defaultByPlan?: Readonly<Partial<Record<OrgPlan, boolean>>>\n}\n\nexport interface PluginLockdownFeatureDeclaration {\n  /** The lever's wire identity (`ai-generate`). */\n  key: string\n  /** The staff checklist's label. */\n  label: string\n  /**\n   * What the lever is called in the customer's mail when staff pull it for\n   * their workspace (`media uploads`, `AI generation`). A noun phrase that\n   * reads right mid-sentence (\"our team paused media uploads\") and after a\n   * colon, so lowercase unless it starts with a name or an acronym. The\n   * staff `label` never reaches a customer.\n   */\n  customerName: string\n  /**\n   * Whether a verified staff claim passes the lock. Granted where a staff\n   * action aids incident response — one real call proves a provider is back\n   * — and withheld where the staff action would BE the incident.\n   */\n  staffBypass: boolean\n  /**\n   * What a visitor reads while the lever is pulled: what is paused AND what\n   * still works. The expected-back window is appended by the notice builder.\n   */\n  notice: { title: string; body: string }\n  /**\n   * Plugin API paths the lever gates at the dispatcher: exact paths, and\n   * prefixes matched on a segment boundary (`ai/generate` also gates\n   * `ai/generate/section`, never `ai/generated-report`).\n   */\n  apiPaths?: { exact?: readonly string[]; prefixes?: readonly string[] }\n}\n\n/**\n * A key a plugin adds to the org permission CATALOG (AGL-2984): the granular\n * map custom roles and per-member overrides are stored in, that\n * `resolveOrgPermissions` layers and the rules stamp carries, and that the\n * role editor lists. A declared key is stored, layered and resolved exactly\n * like a core key; the declaration supplies what a core key's catalog entry\n * and role table supply.\n */\nexport interface PluginOrgPermissionDeclaration {\n  /** The dotted key a custom role and a per-member override store (`reviews.reply`). */\n  key: string\n  /** The role editor's line for the key, and the word a refusal names. */\n  label: string\n  /** What the key opens, under the label in the role editor. */\n  description: string\n  /** Each org role's verdict when no custom role or per-member override sets the key. */\n  roleDefaults: Readonly<Record<OrgRole, boolean>>\n  /**\n   * Each HOST role's verdict, for a key a site collaborator holds per site.\n   *\n   * A collaborator's membership carries no org standing to refine — it\n   * exists only to carry access to named sites — so a key with this field is\n   * decided for them on the site a request names: the host role they hold\n   * there, refined by the per-site toggle on their member document. A key\n   * without it is never held by a collaborator.\n   */\n  hostRoleDefaults?: Readonly<Record<HostAccessRole, boolean>>\n}\n\nexport interface PluginEntitlementRegistration {\n  pluginId: string\n  seatAddons?: readonly PluginSeatAddonDeclaration[]\n  features?: readonly PluginFeatureDeclaration[]\n  lockdownFeatures?: readonly PluginLockdownFeatureDeclaration[]\n  /** Per-tier keys a plugin's own pages read (`registerPluginPermissions`). */\n  permissions?: readonly Omit<PluginPermission, 'pluginId'>[]\n  /** Keys added to the org permission catalog — see {@link PluginOrgPermissionDeclaration}. */\n  orgPermissions?: readonly PluginOrgPermissionDeclaration[]\n}\n\n/**\n * The registrations and their listeners, held on `globalThis` rather than in\n * module `const`s (AGL-3596), as the custom field registry and the\n * declarations repair hook are (AGL-3412).\n *\n * An app registers the plugins' declarations from `instrumentation.ts`, which\n * Next compiles into a different module graph from the routes. A module-scoped\n * map was filled in the instrumentation's copy and read empty in a route's, so\n * a core route that never loaded a plugin knew none of its keys: the site\n * create door asked for `ai.generate`, read `undefined` from a catalog that\n * had never heard of it, and every guided AI start was born with the starter.\n * One map per process, under a `Symbol.for` key, is the same map in every\n * copy.\n */\nconst REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-entitlements')\n\ninterface PluginEntitlementsRegistry {\n  registrations: Map<string, PluginEntitlementRegistration>\n  /**\n   * Readers of the registrations that keep a derived view in step with them —\n   * every copy of the org permission catalog rebuilds itself on every\n   * registration and reset, because a plugin's declarations can register\n   * after a module that imported the catalog was evaluated, and in another\n   * module graph's copy of this file.\n   */\n  listeners: Set<() => void>\n}\n\nconst globalScope = globalThis as typeof globalThis & {\n  [REGISTRY_KEY]?: PluginEntitlementsRegistry\n}\n\nconst registry: PluginEntitlementsRegistry = (globalScope[REGISTRY_KEY] ??= {\n  registrations: new Map(),\n  listeners: new Set(),\n})\n\nconst registrations = registry.registrations\nconst listeners = registry.listeners\n\n/** Calls `listener` after every registration and reset; answers the unsubscribe. */\nexport function subscribePluginEntitlements(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\nfunction notifyListeners(): void {\n  for (const listener of [...listeners]) listener()\n}\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\nfunction orderedRegistrations(): PluginEntitlementRegistration[] {\n  return [...registrations.values()].sort(\n    (a, b) =>\n      catalogRank(a.pluginId) - catalogRank(b.pluginId) ||\n      a.pluginId.localeCompare(b.pluginId),\n  )\n}\n\nfunction refuseStolenKeys(\n  pluginId: string,\n  kind: 'seat add-on' | 'lockdown feature' | 'org permission',\n  keys: readonly string[],\n  ownerOf: (key: string) => string | undefined,\n): void {\n  for (const key of keys) {\n    const owner = ownerOf(key)\n    if (owner && owner !== pluginId) {\n      throw new Error(\n        `${kind} \"${key}\" is already declared by \"${owner}\"; refused \"${pluginId}\"`,\n      )\n    }\n  }\n}\n\n/**\n * Idempotent per plugin — re-registration replaces that plugin's\n * declarations. A seat add-on, lockdown or catalog permission key another\n * plugin already owns refuses the whole registration: one key, one owner,\n * or the two declarations disagree about what the key means.\n */\nexport function registerPluginEntitlements(\n  registration: PluginEntitlementRegistration,\n): void {\n  const pluginId = registration.pluginId.trim()\n  if (!pluginId) throw new Error('plugin entitlements need a pluginId')\n  refuseStolenKeys(\n    pluginId,\n    'seat add-on',\n    (registration.seatAddons ?? []).map((entry) => entry.key),\n    (key) => pluginSeatAddonOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'lockdown feature',\n    (registration.lockdownFeatures ?? []).map((entry) => entry.key),\n    (key) => pluginLockdownFeatureOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'org permission',\n    (registration.orgPermissions ?? []).map((entry) => entry.key),\n    (key) => pluginOrgPermissionOwner(key),\n  )\n  registrations.set(pluginId, { ...registration, pluginId })\n  if (registration.permissions?.length) {\n    registerPluginPermissions(\n      registration.permissions.map((permission) => ({ ...permission, pluginId })),\n    )\n  }\n  notifyListeners()\n}\n\nfunction pluginSeatAddonOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.seatAddons?.some((addon) => addon.key === key)) return entry.pluginId\n  }\n  return undefined\n}\n\nfunction pluginLockdownFeatureOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.lockdownFeatures?.some((feature) => feature.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\nfunction pluginOrgPermissionOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.orgPermissions?.some((permission) => permission.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\n/** Every declared catalog permission, in catalog order, with the plugin that declared it. */\nexport function listPluginOrgPermissions(): Array<\n  PluginOrgPermissionDeclaration & { pluginId: string }\n> {\n  return orderedRegistrations().flatMap((entry) =>\n    (entry.orgPermissions ?? []).map((permission) => ({\n      ...permission,\n      pluginId: entry.pluginId,\n    })),\n  )\n}\n\n/** Every declared seat add-on, in catalog order. */\nexport function listPluginSeatAddons(): PluginSeatAddonDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.seatAddons ?? [])])\n}\n\n/** One declared seat add-on by its `seatAddons` key. */\nexport function pluginSeatAddon(key: string): PluginSeatAddonDeclaration | undefined {\n  return listPluginSeatAddons().find((entry) => entry.key === key)\n}\n\n/** Every declared feature, in catalog order. */\nexport function listPluginFeatures(): PluginFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.features ?? [])])\n}\n\n/** Every declared lockdown lever, in catalog order. */\nexport function listPluginLockdownFeatures(): PluginLockdownFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [\n    ...(entry.lockdownFeatures ?? []),\n  ])\n}\n\n/** One declared lockdown lever by key. */\nexport function pluginLockdownFeature(\n  key: string,\n): PluginLockdownFeatureDeclaration | undefined {\n  return listPluginLockdownFeatures().find((entry) => entry.key === key)\n}\n\n/** The plugin that declared a lockdown lever, for attribution. */\nexport function pluginIdForLockdownFeature(key: string): string | undefined {\n  return pluginLockdownFeatureOwner(key)\n}\n\n/** Every registration, in catalog order. */\nexport function listPluginEntitlementRegistrations(): PluginEntitlementRegistration[] {\n  return orderedRegistrations()\n}\n\n/**\n * Test seam: forget every registration. The per-tier permissions stay\n * registered; the catalog permissions go with their registrations.\n */\nexport function resetPluginEntitlementsForTests(): void {\n  registrations.clear()\n  notifyListeners()\n}\n"],"names":["globalScope","REGISTRY_KEY","FIRST_PARTY_PLUGINS","registerPluginPermissions","pluginSeatAddonSoldOn","addon","plan","soldOn","quota","perUnitByPlan","Symbol","for","globalThis","registry","registrations","Map","listeners","Set","subscribePluginEntitlements","listener","add","delete","notifyListeners","CATALOG_ORDER","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","orderedRegistrations","values","sort","a","b","localeCompare","refuseStolenKeys","kind","keys","ownerOf","key","owner","Error","registerPluginEntitlements","registration","trim","seatAddons","entry","pluginSeatAddonOwner","lockdownFeatures","pluginLockdownFeatureOwner","orgPermissions","pluginOrgPermissionOwner","set","permissions","length","permission","some","undefined","feature","listPluginOrgPermissions","flatMap","listPluginSeatAddons","pluginSeatAddon","find","listPluginFeatures","features","listPluginLockdownFeatures","pluginLockdownFeature","pluginIdForLockdownFeature","listPluginEntitlementRegistrations","resetPluginEntitlementsForTests","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC;IA8K6CA,cAAYC,eAAZD;AA3K9C,SAASE,mBAAmB,QAAQ,uBAAmB;AACvD,SACEC,yBAAyB,QAEpB,0BAAsB;AAsC7B;;;CAGC,GACD,OAAO,SAASC,sBACdC,KAAiC,EACjCC,IAAa;;QAILD;IAFR,IAAIA,MAAME,MAAM,EAAE,OAAOF,MAAME,MAAM,CAACD;IACtC,IAAI,CAACD,MAAMG,KAAK,EAAE,OAAO;IACzB,OAAO,UAACH,6BAAAA,MAAMG,KAAK,CAACC,aAAa,qBAAzBJ,0BAA2B,CAACC,KAAK,mBAAI,KAAK;AACpD;AAsFA;;;;;;;;;;;;;CAaC,GACD,MAAML,eAAeS,OAAOC,GAAG,CAAC;AAchC,MAAMX,cAAcY;AAIpB,MAAMC,YAAwCb,IAAAA,CAAAA,eAAAA,YAAW,CAACC,gBAAAA,aAAa,YAAzBD,IAAAA,YAAW,CAACC,cAAa,GAAK;IAC1Ea,eAAe,IAAIC;IACnBC,WAAW,IAAIC;AACjB;AAEA,MAAMH,gBAAgBD,SAASC,aAAa;AAC5C,MAAME,YAAYH,SAASG,SAAS;AAEpC,kFAAkF,GAClF,OAAO,SAASE,4BAA4BC,QAAoB;IAC9DH,UAAUI,GAAG,CAACD;IACd,OAAO;QACLH,UAAUK,MAAM,CAACF;IACnB;AACF;AAEA,SAASG;IACP,KAAK,MAAMH,YAAY;WAAIH;KAAU,CAAEG;AACzC;AAEA,MAAMI,gBAAgB,IAAIR,IACxBb,oBAAoBsB,GAAG,CAAC,CAACC,QAAQC,QAAU;QAACD,OAAOE,EAAE;QAAED;KAAM;AAG/D,SAASE,YAAYC,QAAgB;QAC5BN;IAAP,QAAOA,qBAAAA,cAAcO,GAAG,CAACD,qBAAlBN,qBAA+BQ,OAAOC,gBAAgB;AAC/D;AAEA,SAASC;IACP,OAAO;WAAInB,cAAcoB,MAAM;KAAG,CAACC,IAAI,CACrC,CAACC,GAAGC,IACFT,YAAYQ,EAAEP,QAAQ,IAAID,YAAYS,EAAER,QAAQ,KAChDO,EAAEP,QAAQ,CAACS,aAAa,CAACD,EAAER,QAAQ;AAEzC;AAEA,SAASU,iBACPV,QAAgB,EAChBW,IAA2D,EAC3DC,IAAuB,EACvBC,OAA4C;IAE5C,KAAK,MAAMC,OAAOF,KAAM;QACtB,MAAMG,QAAQF,QAAQC;QACtB,IAAIC,SAASA,UAAUf,UAAU;YAC/B,MAAM,IAAIgB,MACR,GAAGL,KAAK,EAAE,EAAEG,IAAI,0BAA0B,EAAEC,MAAM,YAAY,EAAEf,SAAS,CAAC,CAAC;QAE/E;IACF;AACF;AAEA;;;;;CAKC,GACD,OAAO,SAASiB,2BACdC,YAA2C;QAOxCA,0BAMAA,gCAMAA;QAICA;IArBJ,MAAMlB,WAAWkB,aAAalB,QAAQ,CAACmB,IAAI;IAC3C,IAAI,CAACnB,UAAU,MAAM,IAAIgB,MAAM;IAC/BN,iBACEV,UACA,eACA,EAACkB,2BAAAA,aAAaE,UAAU,YAAvBF,2BAA2B,EAAE,EAAEvB,GAAG,CAAC,CAAC0B,QAAUA,MAAMP,GAAG,GACxD,CAACA,MAAQQ,qBAAqBR;IAEhCJ,iBACEV,UACA,oBACA,EAACkB,iCAAAA,aAAaK,gBAAgB,YAA7BL,iCAAiC,EAAE,EAAEvB,GAAG,CAAC,CAAC0B,QAAUA,MAAMP,GAAG,GAC9D,CAACA,MAAQU,2BAA2BV;IAEtCJ,iBACEV,UACA,kBACA,EAACkB,+BAAAA,aAAaO,cAAc,YAA3BP,+BAA+B,EAAE,EAAEvB,GAAG,CAAC,CAAC0B,QAAUA,MAAMP,GAAG,GAC5D,CAACA,MAAQY,yBAAyBZ;IAEpC7B,cAAc0C,GAAG,CAAC3B,UAAU,aAAKkB;QAAclB;;IAC/C,KAAIkB,4BAAAA,aAAaU,WAAW,qBAAxBV,0BAA0BW,MAAM,EAAE;QACpCvD,0BACE4C,aAAaU,WAAW,CAACjC,GAAG,CAAC,CAACmC,aAAgB,aAAKA;gBAAY9B;;IAEnE;IACAP;AACF;AAEA,SAAS6B,qBAAqBR,GAAW;IACvC,KAAK,MAAMO,SAASpC,cAAcoB,MAAM,GAAI;YACtCgB;QAAJ,KAAIA,oBAAAA,MAAMD,UAAU,qBAAhBC,kBAAkBU,IAAI,CAAC,CAACvD,QAAUA,MAAMsC,GAAG,KAAKA,MAAM,OAAOO,MAAMrB,QAAQ;IACjF;IACA,OAAOgC;AACT;AAEA,SAASR,2BAA2BV,GAAW;IAC7C,KAAK,MAAMO,SAASpC,cAAcoB,MAAM,GAAI;YACtCgB;QAAJ,KAAIA,0BAAAA,MAAME,gBAAgB,qBAAtBF,wBAAwBU,IAAI,CAAC,CAACE,UAAYA,QAAQnB,GAAG,KAAKA,MAAM;YAClE,OAAOO,MAAMrB,QAAQ;QACvB;IACF;IACA,OAAOgC;AACT;AAEA,SAASN,yBAAyBZ,GAAW;IAC3C,KAAK,MAAMO,SAASpC,cAAcoB,MAAM,GAAI;YACtCgB;QAAJ,KAAIA,wBAAAA,MAAMI,cAAc,qBAApBJ,sBAAsBU,IAAI,CAAC,CAACD,aAAeA,WAAWhB,GAAG,KAAKA,MAAM;YACtE,OAAOO,MAAMrB,QAAQ;QACvB;IACF;IACA,OAAOgC;AACT;AAEA,2FAA2F,GAC3F,OAAO,SAASE;IAGd,OAAO9B,uBAAuB+B,OAAO,CAAC,CAACd;YACpCA;eAAD,EAACA,wBAAAA,MAAMI,cAAc,YAApBJ,wBAAwB,EAAE,EAAE1B,GAAG,CAAC,CAACmC,aAAgB,aAC7CA;gBACH9B,UAAUqB,MAAMrB,QAAQ;;;AAG9B;AAEA,kDAAkD,GAClD,OAAO,SAASoC;IACd,OAAOhC,uBAAuB+B,OAAO,CAAC,CAACd;YAAeA;eAAL;gBAAKA,oBAAAA,MAAMD,UAAU,YAAhBC,oBAAoB,EAAE;SAAE;;AAChF;AAEA,sDAAsD,GACtD,OAAO,SAASgB,gBAAgBvB,GAAW;IACzC,OAAOsB,uBAAuBE,IAAI,CAAC,CAACjB,QAAUA,MAAMP,GAAG,KAAKA;AAC9D;AAEA,8CAA8C,GAC9C,OAAO,SAASyB;IACd,OAAOnC,uBAAuB+B,OAAO,CAAC,CAACd;YAAeA;eAAL;gBAAKA,kBAAAA,MAAMmB,QAAQ,YAAdnB,kBAAkB,EAAE;SAAE;;AAC9E;AAEA,qDAAqD,GACrD,OAAO,SAASoB;IACd,OAAOrC,uBAAuB+B,OAAO,CAAC,CAACd;YACjCA;eAD2C;gBAC3CA,0BAAAA,MAAME,gBAAgB,YAAtBF,0BAA0B,EAAE;SACjC;;AACH;AAEA,wCAAwC,GACxC,OAAO,SAASqB,sBACd5B,GAAW;IAEX,OAAO2B,6BAA6BH,IAAI,CAAC,CAACjB,QAAUA,MAAMP,GAAG,KAAKA;AACpE;AAEA,gEAAgE,GAChE,OAAO,SAAS6B,2BAA2B7B,GAAW;IACpD,OAAOU,2BAA2BV;AACpC;AAEA,0CAA0C,GAC1C,OAAO,SAAS8B;IACd,OAAOxC;AACT;AAEA;;;CAGC,GACD,OAAO,SAASyC;IACd5D,cAAc6D,KAAK;IACnBrD;AACF"}

package/src/lib/plugin-manager/purchase-gate-preclearance.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** The gates a preclearance may waive. One today. */
+export type PurchaseGate = 'domain-payment-history';
+export interface PurchaseGatePreclearanceInput {
+    /** The workspace the purchase is for. */
+    orgId: string;
+    gate: PurchaseGate;
+}
+export interface PurchaseGatePreclearance {
+    /**
+     * A live, unused waiver for this workspace and gate, or null. Reads only:
+     * asking does not spend it.
+     */
+    check(input: PurchaseGatePreclearanceInput): Promise<{
+        preclearanceId: string;
+    } | null>;
+    /**
+     * Spend the waiver: true exactly once per id, in a transaction that marks it
+     * used only if nothing has. False for an id this implementation does not
+     * hold, one already spent, or one that expired.
+     */
+    consume(preclearanceId: string): Promise<boolean>;
+}
+/**
+ * A set: more than one surface may mint a waiver (a bundle link today), and
+ * the gate asks each in turn.
+ */
+export declare const PURCHASE_GATE_PRECLEARANCE: import("./plugin-services").PluginServiceContract<PurchaseGatePreclearance>;
+/** Installs an implementation. The console registers the bundle links at boot. */
+export declare function registerPurchaseGatePreclearance(impl: PurchaseGatePreclearance, options?: {
+    pluginId?: string;
+    key?: string;
+}): void;
+/**
+ * The first live waiver any implementation holds for the workspace and gate,
+ * or null. Never throws; an implementation that throws is skipped and
+ * logged, so it can only ever cost a waiver, never grant one.
+ */
+export declare function checkPurchaseGatePreclearance(input: PurchaseGatePreclearanceInput): Promise<{
+    preclearanceId: string;
+} | null>;
+/**
+ * Spend a waiver. True only when an implementation marked it used just now.
+ * Never throws: a failure answers false, which refuses the purchase.
+ */
+export declare function consumePurchaseGatePreclearance(preclearanceId: string): Promise<boolean>;

package/src/lib/plugin-manager/purchase-gate-preclearance.js

@@ -0,0 +1,102 @@
+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.
+ */ /**
+ * WHO MAY WAIVE A PURCHASE GATE, ONCE (AGL-3955).
+ *
+ * A plugin that sells something can hold a purchase behind a gate the
+ * workspace has to earn: the domains plugin refuses to register a name until
+ * the workspace has a paid platform invoice at least 72 hours old. Core owns
+ * the one thing that can stand in for that history: a staff member who met
+ * the owner in person and minted a single-use bundle link for that one
+ * workspace, accountable for it in `adminAudit`.
+ *
+ * The plugin cannot read core's bundle-link records (a plugin never imports
+ * core's storage, and never another plugin), so the waiver is a contract
+ * here. The plugin asks `check` while deciding whether the gate refuses, and
+ * calls `consume` after it has taken its own hold and before it charges: a
+ * `false` from `consume` refuses the purchase, so one preclearance buys
+ * exactly one thing.
+ *
+ * Only the named gate is waived. Every other refusal the plugin makes (a
+ * brand lookalike, its per-workspace caps) stands, and an implementation has
+ * no say in them.
+ *
+ * ## FAILS CLOSED
+ *
+ * {@link checkPurchaseGatePreclearance} answers null on any error and when
+ * nothing is registered, and {@link consumePurchaseGatePreclearance} answers
+ * false: a waiver that cannot be confirmed is no waiver, and the gate keeps
+ * refusing.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+/**
+ * A set: more than one surface may mint a waiver (a bundle link today), and
+ * the gate asks each in turn.
+ */ export const PURCHASE_GATE_PRECLEARANCE = definePluginServiceContract('core.purchase-gate-preclearance', {
+    multiple: true
+});
+/** Installs an implementation. The console registers the bundle links at boot. */ export function registerPurchaseGatePreclearance(impl, options) {
+    if (typeof (impl == null ? void 0 : impl.check) !== 'function' || typeof (impl == null ? void 0 : impl.consume) !== 'function') {
+        throw new Error('a purchase gate preclearance needs check and consume functions');
+    }
+    registerPluginService(PURCHASE_GATE_PRECLEARANCE, impl, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, (options == null ? void 0 : options.key) ? {
+        key: options.key
+    } : {}));
+}
+/**
+ * The first live waiver any implementation holds for the workspace and gate,
+ * or null. Never throws; an implementation that throws is skipped and
+ * logged, so it can only ever cost a waiver, never grant one.
+ */ export async function checkPurchaseGatePreclearance(input) {
+    var _ref;
+    const orgId = String((_ref = input == null ? void 0 : input.orgId) != null ? _ref : '').trim();
+    if (!orgId || (input == null ? void 0 : input.gate) !== 'domain-payment-history') return null;
+    for (const registration of resolvePluginServices(PURCHASE_GATE_PRECLEARANCE)){
+        try {
+            var _ref1;
+            const found = await registration.impl.check({
+                orgId,
+                gate: input.gate
+            });
+            const preclearanceId = String((_ref1 = found == null ? void 0 : found.preclearanceId) != null ? _ref1 : '').trim();
+            if (preclearanceId) return {
+                preclearanceId
+            };
+        } catch (error) {
+            console.error(`[purchase-gate-preclearance] check failed in "${registration.pluginId}"`, error);
+        }
+    }
+    return null;
+}
+/**
+ * Spend a waiver. True only when an implementation marked it used just now.
+ * Never throws: a failure answers false, which refuses the purchase.
+ */ export async function consumePurchaseGatePreclearance(preclearanceId) {
+    const id = String(preclearanceId != null ? preclearanceId : '').trim();
+    if (!id) return false;
+    for (const registration of resolvePluginServices(PURCHASE_GATE_PRECLEARANCE)){
+        try {
+            if (await registration.impl.consume(id) === true) return true;
+        } catch (error) {
+            console.error(`[purchase-gate-preclearance] consume failed in "${registration.pluginId}"`, error);
+        }
+    }
+    return false;
+}
+
+//# sourceMappingURL=purchase-gate-preclearance.js.map