@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/plugin-manager/plugin-tax-return-sources.js

@@ -0,0 +1,191 @@
+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.
+ */ /**
+ * THE SALES A PLUGIN MADE THROUGH THE PLATFORM, ON THE OPERATOR'S RETURN
+ * (AGL-3080).
+ *
+ * The operator — whoever runs this deployment — files a sales tax return for
+ * the sales it FACILITATED, not only for its own. Its own subscription
+ * invoices are platform billing and the return sums them itself. A plugin
+ * that sells through the platform's account — a storefront checkout whose tax
+ * Stripe computes against the operator's registrations, a marketplace charge
+ * whose tax stays platform-side — holds records the return cannot read
+ * without knowing that plugin's storage, and a classification of them the
+ * return has no business restating.
+ *
+ * So the division is: the FILING is the platform's — the period, the
+ * jurisdiction and registration, the verdict, the working-papers export and
+ * the Texas Webfile lines. What a plugin sold, how each of its rows
+ * classifies and who is liable for it, and the words a preparer reads about
+ * it, are the plugin's. A source answers one period with a
+ * {@link TaxReturnSourceAnswer}: its findings, its lines for the filing
+ * figures, its tables and figures for the screen, its blocks for the export,
+ * and its own summary and rows carried whole for the audit.
+ *
+ * ## ⛔ AN UNREAD SOURCE REFUSES, IT NEVER READS AS ZERO
+ *
+ * Decided before anything else, because this is a legal filing. A source
+ * that answered nothing is indistinguishable, on a total, from a source that
+ * sold nothing — and a return signed on that total understates what the
+ * operator collected and holds. So:
+ *
+ * - **Declared and not registered** — every plugin whose sales belong on the
+ *   return says so with `"taxReturnSource": true` in `plugins.config.json`,
+ *   compiled into {@link PLUGIN_TAX_RETURN_SOURCES}. A declared plugin that
+ *   registered no source in this process answers `outcome: 'refused'`. A
+ *   runtime registry alone could not say this: an empty registry looks
+ *   exactly like a deployment where nothing sells.
+ * - **Threw, or answered a malformed section** — `outcome: 'refused'`, with
+ *   the sentence the return prints.
+ * - **Truncated, or holding rows no period can reach** — answered, and the
+ *   platform raises each as a BLOCKING finding itself; a source cannot word
+ *   its way out of either.
+ *
+ * The return turns every refusal into a blocking "do not file from this"
+ * finding. {@link readTaxReturnSources} never throws and never drops a
+ * declared source.
+ *
+ * The reader is the staff tax-return route, which awaits `ensureAll` on the
+ * `consoleApi` surface before it asks, so a runtime registry is filled before
+ * the question; the compiled declaration is what makes a MISSING
+ * registration a refusal rather than an absence.
+ *
+ * ⚑ The discriminant is a string: this repo compiles with
+ * `strictNullChecks: false`, under which a boolean-literal union does not
+ * narrow (see `plugin-artifact-inventory.ts`).
+ */ import { PLUGIN_TAX_RETURN_SOURCES } from "./first-party-plugins.generated.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export { PLUGIN_TAX_RETURN_SOURCES };
+/** Every source answers; one per plugin. */ export const TAX_RETURN_SOURCES = definePluginServiceContract('core.tax-return-sources', {
+    multiple: true
+});
+/**
+ * Installs a plugin's source. Owner = the loader's marker inside a register
+ * fn, else `options.pluginId`. Registering again replaces the plugin's
+ * earlier source, so a module evaluated twice does not answer twice.
+ */ export function registerTaxReturnSource(source, options) {
+    if (typeof (source == null ? void 0 : source.read) !== 'function') {
+        throw new Error('a tax return source needs a read function');
+    }
+    registerPluginService(TAX_RETURN_SOURCES, source, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The plugins with a registered source, in the order they answer. */ export function listTaxReturnSources() {
+    return resolvePluginServices(TAX_RETURN_SOURCES).map((entry)=>entry.pluginId);
+}
+const isText = (value)=>typeof value === 'string' && value.trim().length > 0;
+const isCount = (value)=>typeof value === 'number' && Number.isFinite(value) && value >= 0;
+/**
+ * What is wrong with an answer, or null when it can be printed.
+ *
+ * Checked because the answer crosses a package boundary into a legal
+ * document: a finding with a NaN count sums to NaN and the verdict reads
+ * clean, and a missing array is a section that silently shows nothing.
+ */ function malformed(answer) {
+    if (!answer || typeof answer !== 'object') return 'no section';
+    if (!isText(answer.id) || !isText(answer.name) || !isText(answer.title)) {
+        return 'a section with no id, name or title';
+    }
+    if (typeof answer.truncated !== 'boolean') return 'no truncation flag';
+    if (!isCount(answer.undatedRows)) return 'no count of undated rows';
+    for (const key of [
+        'findings',
+        'filingLines',
+        'tables',
+        'figures',
+        'exports',
+        'rows'
+    ]){
+        if (!Array.isArray(answer[key])) return `no ${key}`;
+    }
+    const badFinding = answer.findings.find((finding)=>!isText(finding == null ? void 0 : finding.id) || finding.severity !== 'blocking' && finding.severity !== 'review' || !isCount(finding.count));
+    if (badFinding) return 'a finding with no id, severity or count';
+    return null;
+}
+/**
+ * Every source's answer for one period — declared sources first, in the
+ * compiled order, then any other registered source in registration order.
+ *
+ * NEVER THROWS and never drops a declared source: a declared plugin with no
+ * registration, a source that threw, and a malformed or duplicate answer
+ * each come back as `outcome: 'refused'` with the sentence the return prints.
+ * `declared` is the compiled {@link PLUGIN_TAX_RETURN_SOURCES} unless a spec
+ * passes its own.
+ */ export async function readTaxReturnSources(request, declared = PLUGIN_TAX_RETURN_SOURCES) {
+    const registered = resolvePluginServices(TAX_RETURN_SOURCES);
+    const order = [
+        ...declared,
+        ...registered.map((entry)=>entry.pluginId).filter((pluginId)=>!declared.includes(pluginId))
+    ].filter((pluginId, index, all)=>all.indexOf(pluginId) === index);
+    const answers = await Promise.all(order.map(async (pluginId)=>{
+        var _registered_find;
+        const source = (_registered_find = registered.find((entry)=>entry.pluginId === pluginId)) == null ? void 0 : _registered_find.impl;
+        if (!source) {
+            console.error(`[tax-return] "${pluginId}" declares a tax return source and none is ` + 'registered in this process; its sales cannot be read.');
+            return {
+                outcome: 'refused',
+                pluginId,
+                id: pluginId,
+                reason: `The “${pluginId}” plugin sells through the platform and registered ` + 'nothing to read its sales with.'
+            };
+        }
+        try {
+            const answer = await source.read(request);
+            const problem = malformed(answer);
+            if (problem) {
+                return {
+                    outcome: 'refused',
+                    pluginId,
+                    id: pluginId,
+                    reason: `The “${pluginId}” plugin answered ${problem}.`
+                };
+            }
+            return _extends({}, answer, {
+                outcome: 'answered',
+                pluginId
+            });
+        } catch (error) {
+            console.error(`[tax-return] "${pluginId}" failed to read its sales`, error);
+            return {
+                outcome: 'refused',
+                pluginId,
+                id: pluginId,
+                reason: `The “${pluginId}” plugin could not read its sales for this period.`
+            };
+        }
+    }));
+    // Two sources under one id would print two cards and one set of findings
+    // under the same key, and a finding that names the wrong source's rows is
+    // worse than none. The later one is refused, visibly.
+    const seen = new Set();
+    return answers.map((section)=>{
+        if (section.outcome !== 'answered') return section;
+        if (!seen.has(section.id)) {
+            seen.add(section.id);
+            return section;
+        }
+        return {
+            outcome: 'refused',
+            pluginId: section.pluginId,
+            id: section.pluginId,
+            reason: `The “${section.pluginId}” plugin answered as “${section.id}”, which ` + 'another source already is.'
+        };
+    });
+}
+
+//# sourceMappingURL=plugin-tax-return-sources.js.map

package/src/lib/plugin-manager/plugin-tax-return-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-tax-return-sources.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 * THE SALES A PLUGIN MADE THROUGH THE PLATFORM, ON THE OPERATOR'S RETURN\n * (AGL-3080).\n *\n * The operator — whoever runs this deployment — files a sales tax return for\n * the sales it FACILITATED, not only for its own. Its own subscription\n * invoices are platform billing and the return sums them itself. A plugin\n * that sells through the platform's account — a storefront checkout whose tax\n * Stripe computes against the operator's registrations, a marketplace charge\n * whose tax stays platform-side — holds records the return cannot read\n * without knowing that plugin's storage, and a classification of them the\n * return has no business restating.\n *\n * So the division is: the FILING is the platform's — the period, the\n * jurisdiction and registration, the verdict, the working-papers export and\n * the Texas Webfile lines. What a plugin sold, how each of its rows\n * classifies and who is liable for it, and the words a preparer reads about\n * it, are the plugin's. A source answers one period with a\n * {@link TaxReturnSourceAnswer}: its findings, its lines for the filing\n * figures, its tables and figures for the screen, its blocks for the export,\n * and its own summary and rows carried whole for the audit.\n *\n * ## ⛔ AN UNREAD SOURCE REFUSES, IT NEVER READS AS ZERO\n *\n * Decided before anything else, because this is a legal filing. A source\n * that answered nothing is indistinguishable, on a total, from a source that\n * sold nothing — and a return signed on that total understates what the\n * operator collected and holds. So:\n *\n * - **Declared and not registered** — every plugin whose sales belong on the\n *   return says so with `\"taxReturnSource\": true` in `plugins.config.json`,\n *   compiled into {@link PLUGIN_TAX_RETURN_SOURCES}. A declared plugin that\n *   registered no source in this process answers `outcome: 'refused'`. A\n *   runtime registry alone could not say this: an empty registry looks\n *   exactly like a deployment where nothing sells.\n * - **Threw, or answered a malformed section** — `outcome: 'refused'`, with\n *   the sentence the return prints.\n * - **Truncated, or holding rows no period can reach** — answered, and the\n *   platform raises each as a BLOCKING finding itself; a source cannot word\n *   its way out of either.\n *\n * The return turns every refusal into a blocking \"do not file from this\"\n * finding. {@link readTaxReturnSources} never throws and never drops a\n * declared source.\n *\n * The reader is the staff tax-return route, which awaits `ensureAll` on the\n * `consoleApi` surface before it asks, so a runtime registry is filled before\n * the question; the compiled declaration is what makes a MISSING\n * registration a refusal rather than an absence.\n *\n * ⚑ The discriminant is a string: this repo compiles with\n * `strictNullChecks: false`, under which a boolean-literal union does not\n * narrow (see `plugin-artifact-inventory.ts`).\n */\n\nimport { PLUGIN_TAX_RETURN_SOURCES } from './first-party-plugins.generated'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\nexport { PLUGIN_TAX_RETURN_SOURCES }\n\n/** Which exporter the filing jurisdiction gets. */\nexport type TaxReturnFilingForm = 'tx-webfile' | 'breakdown'\n\n/**\n * The jurisdiction the operator files in, as the platform resolved it from\n * its own configuration. A source words its lines and findings for THIS\n * jurisdiction and never assumes one.\n */\nexport interface TaxReturnFiling {\n  /** The bucket key: `US-TX`, `US-CA`, `GB`. */\n  code: string\n  /** How a sentence names it: `Texas`, or the code itself. */\n  label: string\n  /** Which exporter the filing lines are for. */\n  form: TaxReturnFilingForm\n  /** How a sentence names the filing figures: `Items 1–3`, `the breakdown`. */\n  figuresName: string\n}\n\n/** What the return asks every source, once per period. */\nexport interface TaxReturnSourceRequest {\n  /** `2026-Q3` or `2026-09`, echoed for the record. */\n  period: string\n  /** Half-open UTC bounds of the period. */\n  start: Date\n  end: Date\n  filing: TaxReturnFiling\n  /**\n   * The most documents the operator will read for one source. Past it the\n   * answer is `truncated`, and a truncated source blocks the return: the\n   * ceiling is the operator's policy, so a source is TOLD it.\n   */\n  rowCap: number\n}\n\nexport type TaxReturnFindingSeverity = 'blocking' | 'review'\n\n/**\n * One finding, in the words a preparer reads. `blocking` means the return\n * must not be filed until it is resolved; `review` means a figure is\n * qualified. A zero count is not raised.\n */\nexport interface TaxReturnFinding {\n  /** Stable, and unique on the return. */\n  id: string\n  severity: TaxReturnFindingSeverity\n  /** Rows, or cents where the label says so. */\n  count: number\n  label: string\n  /** What it means for the return, and what to do — not a restatement. */\n  detail: string\n}\n\n/** A line printed beneath the platform's own filing figures. */\nexport interface TaxReturnFilingLine {\n  /** The form's item number where the figure maps to one, else `—`. */\n  item: string\n  label: string\n  /** Dollars, or null when the figure is not computed. */\n  dollars: string | null\n  note: string\n}\n\n/** One cell of a source's table on the screen. */\nexport interface TaxReturnSectionCell {\n  text: string\n  /** A second, quieter line under the text. */\n  caption?: string\n  /**\n   * A short tag beside the text. `attention` marks the figure that needs a\n   * decision; `neutral` qualifies one.\n   */\n  tag?: { label: string; tone: 'attention' | 'neutral' }\n  /** The figure a reader must not miss. */\n  strong?: boolean\n}\n\nexport interface TaxReturnSectionColumn {\n  label: string\n  /** Right-aligned. */\n  numeric?: boolean\n  /** Money: set in a fixed-width face so columns of cents line up. */\n  money?: boolean\n}\n\n/** A table on the source's card. */\nexport interface TaxReturnSectionTable {\n  /** A subheading above the table; the first table sits under the card's own. */\n  heading?: string\n  /** A sentence between the heading and the table. */\n  description?: string\n  columns: TaxReturnSectionColumn[]\n  rows: Array<{ key: string; cells: TaxReturnSectionCell[] }>\n  /** What the table says when it has no rows. */\n  empty: string\n  /** A caption under the table. */\n  footnote?: string\n}\n\n/** One label/value line of a source's figures. */\nexport interface TaxReturnSectionFigure {\n  label: string\n  value: string\n  note: string\n}\n\n/**\n * One block of the working-papers export, as the CSV's own rows.\n *\n * `jurisdictions` places it beside the operator's own sales by jurisdiction,\n * before the working papers; `sections` places it after them, where each\n * source's figures sit. The platform separates blocks with a blank row.\n */\nexport interface TaxReturnExportBlock {\n  placement: 'jurisdictions' | 'sections'\n  rows: string[][]\n}\n\n/** What a source answers for one period. */\nexport interface TaxReturnSourceAnswer {\n  /** Stable key for the source's findings and its card, unique on the return. */\n  id: string\n  /** The noun for its rows: `Storefront`, `Marketplace`. */\n  name: string\n  /** The card's heading. */\n  title: string\n  /** The card's help, as a documentation excerpt. */\n  help: string\n  /** The paragraph under the heading. */\n  intro: string\n  /** Documents past the request's `rowCap` were not read. */\n  truncated: boolean\n  /** Rows no period query can reach — in this return and every other. */\n  undatedRows: number\n  /** The source's own findings. Truncation and undated rows are raised by the platform. */\n  findings: TaxReturnFinding[]\n  /** Lines beneath the filing figures, for the request's `filing.form`. */\n  filingLines: TaxReturnFilingLine[]\n  tables: TaxReturnSectionTable[]\n  figures: TaxReturnSectionFigure[]\n  exports: TaxReturnExportBlock[]\n  /** The source's own figures, carried whole for the audit. */\n  summary: unknown\n  /** The rows behind them, as the source projects them for the working papers. */\n  rows: unknown[]\n}\n\n/** One source on the return: its answer, or why there is none. */\nexport type TaxReturnSection =\n  | ({ outcome: 'answered'; pluginId: string } & TaxReturnSourceAnswer)\n  | {\n      outcome: 'refused'\n      pluginId: string\n      /** The plugin id: a refused source never said what it calls itself. */\n      id: string\n      /** Why nothing from this source is on the return, as the return prints it. */\n      reason: string\n    }\n\nexport interface TaxReturnSource {\n  /**\n   * This plugin's sales for one period. May throw: the return refuses the\n   * source rather than read a throw as nothing sold.\n   */\n  read(request: TaxReturnSourceRequest): Promise<TaxReturnSourceAnswer>\n}\n\n/** Every source answers; one per plugin. */\nexport const TAX_RETURN_SOURCES = definePluginServiceContract<TaxReturnSource>(\n  'core.tax-return-sources',\n  { multiple: true },\n)\n\n/**\n * Installs a plugin's source. Owner = the loader's marker inside a register\n * fn, else `options.pluginId`. Registering again replaces the plugin's\n * earlier source, so a module evaluated twice does not answer twice.\n */\nexport function registerTaxReturnSource(\n  source: TaxReturnSource,\n  options?: { pluginId?: string },\n): void {\n  if (typeof source?.read !== 'function') {\n    throw new Error('a tax return source needs a read function')\n  }\n  registerPluginService(TAX_RETURN_SOURCES, source, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The plugins with a registered source, in the order they answer. */\nexport function listTaxReturnSources(): string[] {\n  return resolvePluginServices(TAX_RETURN_SOURCES).map((entry) => entry.pluginId)\n}\n\nconst isText = (value: unknown): value is string =>\n  typeof value === 'string' && value.trim().length > 0\n\nconst isCount = (value: unknown): boolean =>\n  typeof value === 'number' && Number.isFinite(value) && value >= 0\n\n/**\n * What is wrong with an answer, or null when it can be printed.\n *\n * Checked because the answer crosses a package boundary into a legal\n * document: a finding with a NaN count sums to NaN and the verdict reads\n * clean, and a missing array is a section that silently shows nothing.\n */\nfunction malformed(answer: TaxReturnSourceAnswer): string | null {\n  if (!answer || typeof answer !== 'object') return 'no section'\n  if (!isText(answer.id) || !isText(answer.name) || !isText(answer.title)) {\n    return 'a section with no id, name or title'\n  }\n  if (typeof answer.truncated !== 'boolean') return 'no truncation flag'\n  if (!isCount(answer.undatedRows)) return 'no count of undated rows'\n  for (const key of ['findings', 'filingLines', 'tables', 'figures', 'exports', 'rows'] as const) {\n    if (!Array.isArray(answer[key])) return `no ${key}`\n  }\n  const badFinding = answer.findings.find(\n    (finding) =>\n      !isText(finding?.id) ||\n      (finding.severity !== 'blocking' && finding.severity !== 'review') ||\n      !isCount(finding.count),\n  )\n  if (badFinding) return 'a finding with no id, severity or count'\n  return null\n}\n\n/**\n * Every source's answer for one period — declared sources first, in the\n * compiled order, then any other registered source in registration order.\n *\n * NEVER THROWS and never drops a declared source: a declared plugin with no\n * registration, a source that threw, and a malformed or duplicate answer\n * each come back as `outcome: 'refused'` with the sentence the return prints.\n * `declared` is the compiled {@link PLUGIN_TAX_RETURN_SOURCES} unless a spec\n * passes its own.\n */\nexport async function readTaxReturnSources(\n  request: TaxReturnSourceRequest,\n  declared: readonly string[] = PLUGIN_TAX_RETURN_SOURCES,\n): Promise<TaxReturnSection[]> {\n  const registered = resolvePluginServices(TAX_RETURN_SOURCES)\n  const order = [\n    ...declared,\n    ...registered\n      .map((entry) => entry.pluginId)\n      .filter((pluginId) => !declared.includes(pluginId)),\n  ].filter((pluginId, index, all) => all.indexOf(pluginId) === index)\n\n  const answers = await Promise.all(\n    order.map(async (pluginId): Promise<TaxReturnSection> => {\n      const source = registered.find((entry) => entry.pluginId === pluginId)?.impl\n      if (!source) {\n        console.error(\n          `[tax-return] \"${pluginId}\" declares a tax return source and none is ` +\n            'registered in this process; its sales cannot be read.',\n        )\n        return {\n          outcome: 'refused',\n          pluginId,\n          id: pluginId,\n          reason:\n            `The “${pluginId}” plugin sells through the platform and registered ` +\n            'nothing to read its sales with.',\n        }\n      }\n      try {\n        const answer = await source.read(request)\n        const problem = malformed(answer)\n        if (problem) {\n          return {\n            outcome: 'refused',\n            pluginId,\n            id: pluginId,\n            reason: `The “${pluginId}” plugin answered ${problem}.`,\n          }\n        }\n        return { ...answer, outcome: 'answered', pluginId }\n      } catch (error) {\n        console.error(`[tax-return] \"${pluginId}\" failed to read its sales`, error)\n        return {\n          outcome: 'refused',\n          pluginId,\n          id: pluginId,\n          reason: `The “${pluginId}” plugin could not read its sales for this period.`,\n        }\n      }\n    }),\n  )\n\n  // Two sources under one id would print two cards and one set of findings\n  // under the same key, and a finding that names the wrong source's rows is\n  // worse than none. The later one is refused, visibly.\n  const seen = new Set<string>()\n  return answers.map((section) => {\n    if (section.outcome !== 'answered') return section\n    if (!seen.has(section.id)) {\n      seen.add(section.id)\n      return section\n    }\n    return {\n      outcome: 'refused',\n      pluginId: section.pluginId,\n      id: section.pluginId,\n      reason:\n        `The “${section.pluginId}” plugin answered as “${section.id}”, which ` +\n        'another source already is.',\n    }\n  })\n}\n"],"names":["PLUGIN_TAX_RETURN_SOURCES","definePluginServiceContract","registerPluginService","resolvePluginServices","TAX_RETURN_SOURCES","multiple","registerTaxReturnSource","source","options","read","Error","pluginId","listTaxReturnSources","map","entry","isText","value","trim","length","isCount","Number","isFinite","malformed","answer","id","name","title","truncated","undatedRows","key","Array","isArray","badFinding","findings","find","finding","severity","count","readTaxReturnSources","request","declared","registered","order","filter","includes","index","all","indexOf","answers","Promise","impl","console","error","outcome","reason","problem","seen","Set","section","has","add"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-template-sources.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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 { PLUGIN_TEMPLATE_SOURCES } from './first-party-plugins.generated';
+/**
+ * Where a site's template came from, by its stored `source.type` (AGL-666,
+ * AGL-3080).
+ *
+ * The stamp is server-managed, which is what lets a site's library show it as
+ * a trust signal. Two values are the platform's own: {@link
+ * AUTHORED_TEMPLATE_SOURCE}, a template saved on the site, and {@link
+ * STARTER_TEMPLATE_SOURCE}, a first-party starter copied in when it was used
+ * or edited. Every other value is stamped by a plugin that INSTALLS templates
+ * into a site's library, and that plugin declares it as `templateSource` in
+ * `plugins.config.json`: the value its install route writes, the badge the
+ * library shows, and the sentence explaining the badge.
+ *
+ * ## Compiled, never registered
+ *
+ * The readers ask before any plugin code has loaded, and one of them asks
+ * Firestore by value: the template gallery's own shelf holds a site's saved
+ * AND installed templates, as a `source.type in [...]` clause. A runtime
+ * registry the page had not filled yet would leave every installed template
+ * off that shelf with nothing to say it was missing, so the declaration is
+ * data the generator compiles.
+ *
+ * ## A type no plugin declares
+ *
+ * A template installed by a plugin this build no longer carries keeps its
+ * stamp, and the stamp still says a server installed it. It reads as
+ * installed ({@link installedTemplateSource} answers `null`, and the
+ * library's badge says "Installed") rather than as something the site
+ * authored.
+ */
+export interface PluginTemplateSource {
+    /** The plugin that declared it. */
+    pluginId: string;
+    /** The `source.type` the plugin's install route stamps. */
+    type: string;
+    /** The library's badge: the name of where the template came from. */
+    label: string;
+    /** One sentence saying where the template came from, for the badge's hint. */
+    description: string;
+}
+/** A template saved on the site itself — and one written before `source`. */
+export declare const AUTHORED_TEMPLATE_SOURCE = "authored";
+/** A first-party starter, copied into the library when it was used or edited. */
+export declare const STARTER_TEMPLATE_SOURCE = "starter";
+export { PLUGIN_TEMPLATE_SOURCES };
+/** Every `source.type` a plugin in this build stamps on a template it installs. */
+export declare const INSTALLED_TEMPLATE_SOURCE_TYPES: readonly string[];
+/**
+ * The declaration behind a template's `source.type`, or `null` for the
+ * platform's own two values, a missing stamp, and a stamp no plugin in this
+ * build declares.
+ */
+export declare function installedTemplateSource(type: unknown): PluginTemplateSource | null;
+/**
+ * Whether a template was installed rather than saved here or started from a
+ * starter: any stamp but the platform's own two, declared or not.
+ */
+export declare function isInstalledTemplateSource(type: unknown): boolean;

package/src/lib/plugin-manager/plugin-template-sources.js

@@ -0,0 +1,37 @@
+/**
+ * @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 { PLUGIN_TEMPLATE_SOURCES } from "./first-party-plugins.generated.js";
+/** A template saved on the site itself — and one written before `source`. */ export const AUTHORED_TEMPLATE_SOURCE = 'authored';
+/** A first-party starter, copied into the library when it was used or edited. */ export const STARTER_TEMPLATE_SOURCE = 'starter';
+export { PLUGIN_TEMPLATE_SOURCES };
+/** Every `source.type` a plugin in this build stamps on a template it installs. */ export const INSTALLED_TEMPLATE_SOURCE_TYPES = PLUGIN_TEMPLATE_SOURCES.map((source)=>source.type);
+/**
+ * The declaration behind a template's `source.type`, or `null` for the
+ * platform's own two values, a missing stamp, and a stamp no plugin in this
+ * build declares.
+ */ export function installedTemplateSource(type) {
+    var _PLUGIN_TEMPLATE_SOURCES_find;
+    if (typeof type !== 'string') return null;
+    return (_PLUGIN_TEMPLATE_SOURCES_find = PLUGIN_TEMPLATE_SOURCES.find((source)=>source.type === type)) != null ? _PLUGIN_TEMPLATE_SOURCES_find : null;
+}
+/**
+ * Whether a template was installed rather than saved here or started from a
+ * starter: any stamp but the platform's own two, declared or not.
+ */ export function isInstalledTemplateSource(type) {
+    return typeof type === 'string' && type !== '' && type !== AUTHORED_TEMPLATE_SOURCE && type !== STARTER_TEMPLATE_SOURCE;
+}
+
+//# sourceMappingURL=plugin-template-sources.js.map

package/src/lib/plugin-manager/plugin-template-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-template-sources.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 { PLUGIN_TEMPLATE_SOURCES } from './first-party-plugins.generated'\n\n/**\n * Where a site's template came from, by its stored `source.type` (AGL-666,\n * AGL-3080).\n *\n * The stamp is server-managed, which is what lets a site's library show it as\n * a trust signal. Two values are the platform's own: {@link\n * AUTHORED_TEMPLATE_SOURCE}, a template saved on the site, and {@link\n * STARTER_TEMPLATE_SOURCE}, a first-party starter copied in when it was used\n * or edited. Every other value is stamped by a plugin that INSTALLS templates\n * into a site's library, and that plugin declares it as `templateSource` in\n * `plugins.config.json`: the value its install route writes, the badge the\n * library shows, and the sentence explaining the badge.\n *\n * ## Compiled, never registered\n *\n * The readers ask before any plugin code has loaded, and one of them asks\n * Firestore by value: the template gallery's own shelf holds a site's saved\n * AND installed templates, as a `source.type in [...]` clause. A runtime\n * registry the page had not filled yet would leave every installed template\n * off that shelf with nothing to say it was missing, so the declaration is\n * data the generator compiles.\n *\n * ## A type no plugin declares\n *\n * A template installed by a plugin this build no longer carries keeps its\n * stamp, and the stamp still says a server installed it. It reads as\n * installed ({@link installedTemplateSource} answers `null`, and the\n * library's badge says \"Installed\") rather than as something the site\n * authored.\n */\nexport interface PluginTemplateSource {\n  /** The plugin that declared it. */\n  pluginId: string\n  /** The `source.type` the plugin's install route stamps. */\n  type: string\n  /** The library's badge: the name of where the template came from. */\n  label: string\n  /** One sentence saying where the template came from, for the badge's hint. */\n  description: string\n}\n\n/** A template saved on the site itself — and one written before `source`. */\nexport const AUTHORED_TEMPLATE_SOURCE = 'authored'\n\n/** A first-party starter, copied into the library when it was used or edited. */\nexport const STARTER_TEMPLATE_SOURCE = 'starter'\n\nexport { PLUGIN_TEMPLATE_SOURCES }\n\n/** Every `source.type` a plugin in this build stamps on a template it installs. */\nexport const INSTALLED_TEMPLATE_SOURCE_TYPES: readonly string[] =\n  PLUGIN_TEMPLATE_SOURCES.map((source) => source.type)\n\n/**\n * The declaration behind a template's `source.type`, or `null` for the\n * platform's own two values, a missing stamp, and a stamp no plugin in this\n * build declares.\n */\nexport function installedTemplateSource(\n  type: unknown,\n): PluginTemplateSource | null {\n  if (typeof type !== 'string') return null\n  return PLUGIN_TEMPLATE_SOURCES.find((source) => source.type === type) ?? null\n}\n\n/**\n * Whether a template was installed rather than saved here or started from a\n * starter: any stamp but the platform's own two, declared or not.\n */\nexport function isInstalledTemplateSource(type: unknown): boolean {\n  return (\n    typeof type === 'string' &&\n    type !== '' &&\n    type !== AUTHORED_TEMPLATE_SOURCE &&\n    type !== STARTER_TEMPLATE_SOURCE\n  )\n}\n"],"names":["PLUGIN_TEMPLATE_SOURCES","AUTHORED_TEMPLATE_SOURCE","STARTER_TEMPLATE_SOURCE","INSTALLED_TEMPLATE_SOURCE_TYPES","map","source","type","installedTemplateSource","find","isInstalledTemplateSource"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,QAAQ,qCAAiC;AA2CzE,2EAA2E,GAC3E,OAAO,MAAMC,2BAA2B,WAAU;AAElD,+EAA+E,GAC/E,OAAO,MAAMC,0BAA0B,UAAS;AAEhD,SAASF,uBAAuB,GAAE;AAElC,iFAAiF,GACjF,OAAO,MAAMG,kCACXH,wBAAwBI,GAAG,CAAC,CAACC,SAAWA,OAAOC,IAAI,EAAC;AAEtD;;;;CAIC,GACD,OAAO,SAASC,wBACdD,IAAa;QAGNN;IADP,IAAI,OAAOM,SAAS,UAAU,OAAO;IACrC,QAAON,gCAAAA,wBAAwBQ,IAAI,CAAC,CAACH,SAAWA,OAAOC,IAAI,KAAKA,iBAAzDN,gCAAkE;AAC3E;AAEA;;;CAGC,GACD,OAAO,SAASS,0BAA0BH,IAAa;IACrD,OACE,OAAOA,SAAS,YAChBA,SAAS,MACTA,SAASL,4BACTK,SAASJ;AAEb"}

package/src/lib/plugin-manager/plugin-usage-axes.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** A meter a plugin contributes to the platform's cost model. */
+export interface PluginCostAxisDeclaration {
+    /** The breakdown key every staff reader shows it under. */
+    id: string;
+    /** Where it sorts among the cost model's axes; core's own are multiples of 10. */
+    order: number;
+    /** Rollup fields summed for the axis. */
+    fields: readonly string[];
+    /**
+     * Read only when every one of `fields` is absent from a rollup — the
+     * narrower field an older rollup recorded the same meter under.
+     */
+    fallbackFields?: readonly string[];
+    /**
+     * Rollup fields recorded beside the meter so its sum is legible, forwarded
+     * by `orgCogsInputFrom` and never priced.
+     */
+    recordedFields?: readonly string[];
+    /**
+     * The `ORG_COGS_UNIT_RATES_USD` key pricing one unit. Absent when the
+     * fields are already dollars, which then enter the model at ×1.
+     */
+    rate?: string;
+    /**
+     * The month's LIVE reading, when the rollup's figure is a snapshot a meter
+     * keeps adding to: `orgs/{orgId}/{collection}/{month}`, the first of
+     * `fields` that is a positive number. It replaces the axis's first rollup
+     * field wherever a reader fetches it.
+     */
+    live?: {
+        collection: string;
+        fields: readonly string[];
+    };
+}
+/** A band a plugin contributes to the utilization table. */
+export interface PluginUsageBandDeclaration {
+    /** The band's key, and the column the staff table shows it under. */
+    id: string;
+    label: string;
+    order: number;
+    /** Rollup fields summed for what the org used. */
+    fields: readonly string[];
+    fallbackFields?: readonly string[];
+    /** The resolved entitlement holding what the plan includes. */
+    entitlement: string;
+    /** The entitlement is per SITE and the org-wide band is it × `hostLimit`. */
+    perHost?: boolean;
+    /**
+     * The band is sold in a unit of cost and the rollup records dollars: what
+     * was used is `ceil(dollars / unitCostUsd)`, rounded UP so spend already
+     * made never reads as less of the band.
+     */
+    unitCostUsd?: number;
+}
+export type ResolvedPluginCostAxis = PluginCostAxisDeclaration & {
+    pluginId: string;
+};
+export type ResolvedPluginUsageBand = PluginUsageBandDeclaration & {
+    pluginId: string;
+};
+/** What a plugin's `usageAxes` function answers. */
+export interface PluginUsageAxesDeclaration {
+    costAxes?: readonly PluginCostAxisDeclaration[];
+    bands?: readonly PluginUsageBandDeclaration[];
+}
+export declare function pluginCostAxes(): readonly ResolvedPluginCostAxis[];
+export declare function pluginUsageBands(): readonly ResolvedPluginUsageBand[];
+/**
+ * What a rollup recorded for a declared meter: `fields` summed, or
+ * `fallbackFields` summed when the rollup carries none of `fields` at all.
+ *
+ * "Carries none" is `null` or absent, never zero. A rollup that measured
+ * zero has answered, and must not fall back to a figure recorded under an
+ * older, narrower basis.
+ */
+export declare function declaredMeterReading(source: Readonly<Record<string, unknown>> | null | undefined, declared: {
+    fields: readonly string[];
+    fallbackFields?: readonly string[];
+}): number;
+/**
+ * The live reading a cost axis names: the first of its `live.fields` that is
+ * a positive number on the month's document, or `undefined` when none is.
+ * `undefined` is "keep the rollup's snapshot", never zero.
+ */
+export declare function liveMeterReading(document: {
+    get(field: string): unknown;
+} | null | undefined, live: {
+    fields: readonly string[];
+}): number | undefined;
+/** Every rollup field the declared cost axes read or record, in order. */
+export declare function pluginCostAxisFields(): string[];

package/src/lib/plugin-manager/plugin-usage-axes.js

@@ -0,0 +1,107 @@
+/**
+ * @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.
+ */ /**
+ * WHAT A PLUGIN'S USAGE COSTS, AND HOW MUCH OF ITS BAND IT SPENT (AGL-3080).
+ *
+ * The platform keeps one cost model (`orgMonthlyCogsUsd`) and one
+ * utilization table (`margin-utilization.ts`), and both read the monthly
+ * usage rollup. Several of the rollup's meters are a plugin's: the AI
+ * plugin's provider spend, the CRM's records, the forms plugin's
+ * submissions, the workflows plugin's runs. Core used to name each of them —
+ * its rollup field, the unit rate that prices it, the band it is measured
+ * against — so a plugin that metered something new could not reach the
+ * discount guardrail without a core edit, and core could not be taken
+ * without the plugins it named.
+ *
+ * So a plugin declares its meters, and core composes them:
+ *
+ *  - a COST AXIS names the rollup fields a meter is recorded under and the
+ *    `ORG_COGS_UNIT_RATES_USD` key that prices one unit, or no key when the
+ *    field is already dollars. `orgMonthlyCogsUsd` prices it beside core's
+ *    own axes, and `orgCogsInputFrom` forwards its fields.
+ *  - a BAND names the rollup fields that measure it and the entitlement that
+ *    says what the plan includes. The utilization table reads it beside
+ *    core's own bands.
+ *
+ * ## What core keeps
+ *
+ * The MONEY. Every unit rate stays in `ORG_COGS_UNIT_RATES_USD`, beside the
+ * billed table it is reconciled against, and every included figure stays in
+ * `PLAN_ENTITLEMENTS`. A declaration names fields and keys; it carries no
+ * price. The one number a declaration may carry is a band's unit cost, where
+ * the band is sold in a unit OF cost (a credit is a fixed quantity of
+ * dollars), and that number is the plugin's own definition of its unit.
+ *
+ * ## Compiled, never registered
+ *
+ * The cost model's readers include the staff org page, which prices a rollup
+ * in the browser, and the discount guardrail, whose every wrong answer is in
+ * the approving direction: a cost axis a registry had not filled would price
+ * at nothing and approve a discount the margin cannot carry. So these are
+ * compiled from each plugin's `usage-axes` declaration by the manifest
+ * generator, like the plan figures, and a rate key core does not have is an
+ * error rather than a zero.
+ */ import { PLUGIN_USAGE_BANDS_DECLARED, PLUGIN_COST_AXES_DECLARED } from "./first-party-plugins.generated.js";
+export function pluginCostAxes() {
+    return PLUGIN_COST_AXES_DECLARED;
+}
+export function pluginUsageBands() {
+    return PLUGIN_USAGE_BANDS_DECLARED;
+}
+/** A positive finite number, or 0 — the reading every meter is priced from. */ function meterValue(value) {
+    const parsed = Number(value != null ? value : 0);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+/**
+ * What a rollup recorded for a declared meter: `fields` summed, or
+ * `fallbackFields` summed when the rollup carries none of `fields` at all.
+ *
+ * "Carries none" is `null` or absent, never zero. A rollup that measured
+ * zero has answered, and must not fall back to a figure recorded under an
+ * older, narrower basis.
+ */ export function declaredMeterReading(source, declared) {
+    var _declared_fallbackFields;
+    const present = declared.fields.some((field)=>(source == null ? void 0 : source[field]) != null);
+    const fields = !present && ((_declared_fallbackFields = declared.fallbackFields) == null ? void 0 : _declared_fallbackFields.length) ? declared.fallbackFields : declared.fields;
+    return fields.reduce((sum, field)=>sum + meterValue(source == null ? void 0 : source[field]), 0);
+}
+/**
+ * The live reading a cost axis names: the first of its `live.fields` that is
+ * a positive number on the month's document, or `undefined` when none is.
+ * `undefined` is "keep the rollup's snapshot", never zero.
+ */ export function liveMeterReading(document, live) {
+    for (const field of live.fields){
+        const value = meterValue(document == null ? void 0 : document.get(field));
+        if (value > 0) return value;
+    }
+    return undefined;
+}
+/** Every rollup field the declared cost axes read or record, in order. */ export function pluginCostAxisFields() {
+    const fields = [];
+    for (const axis of PLUGIN_COST_AXES_DECLARED){
+        var _axis_fallbackFields, _axis_recordedFields;
+        for (const field of [
+            ...axis.fields,
+            ...(_axis_fallbackFields = axis.fallbackFields) != null ? _axis_fallbackFields : [],
+            ...(_axis_recordedFields = axis.recordedFields) != null ? _axis_recordedFields : []
+        ]){
+            if (!fields.includes(field)) fields.push(field);
+        }
+    }
+    return fields;
+}
+
+//# sourceMappingURL=plugin-usage-axes.js.map

package/src/lib/plugin-manager/plugin-usage-axes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-usage-axes.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 * WHAT A PLUGIN'S USAGE COSTS, AND HOW MUCH OF ITS BAND IT SPENT (AGL-3080).\n *\n * The platform keeps one cost model (`orgMonthlyCogsUsd`) and one\n * utilization table (`margin-utilization.ts`), and both read the monthly\n * usage rollup. Several of the rollup's meters are a plugin's: the AI\n * plugin's provider spend, the CRM's records, the forms plugin's\n * submissions, the workflows plugin's runs. Core used to name each of them —\n * its rollup field, the unit rate that prices it, the band it is measured\n * against — so a plugin that metered something new could not reach the\n * discount guardrail without a core edit, and core could not be taken\n * without the plugins it named.\n *\n * So a plugin declares its meters, and core composes them:\n *\n *  - a COST AXIS names the rollup fields a meter is recorded under and the\n *    `ORG_COGS_UNIT_RATES_USD` key that prices one unit, or no key when the\n *    field is already dollars. `orgMonthlyCogsUsd` prices it beside core's\n *    own axes, and `orgCogsInputFrom` forwards its fields.\n *  - a BAND names the rollup fields that measure it and the entitlement that\n *    says what the plan includes. The utilization table reads it beside\n *    core's own bands.\n *\n * ## What core keeps\n *\n * The MONEY. Every unit rate stays in `ORG_COGS_UNIT_RATES_USD`, beside the\n * billed table it is reconciled against, and every included figure stays in\n * `PLAN_ENTITLEMENTS`. A declaration names fields and keys; it carries no\n * price. The one number a declaration may carry is a band's unit cost, where\n * the band is sold in a unit OF cost (a credit is a fixed quantity of\n * dollars), and that number is the plugin's own definition of its unit.\n *\n * ## Compiled, never registered\n *\n * The cost model's readers include the staff org page, which prices a rollup\n * in the browser, and the discount guardrail, whose every wrong answer is in\n * the approving direction: a cost axis a registry had not filled would price\n * at nothing and approve a discount the margin cannot carry. So these are\n * compiled from each plugin's `usage-axes` declaration by the manifest\n * generator, like the plan figures, and a rate key core does not have is an\n * error rather than a zero.\n */\n\nimport {\n  PLUGIN_USAGE_BANDS_DECLARED,\n  PLUGIN_COST_AXES_DECLARED,\n} from './first-party-plugins.generated'\n\n/** A meter a plugin contributes to the platform's cost model. */\nexport interface PluginCostAxisDeclaration {\n  /** The breakdown key every staff reader shows it under. */\n  id: string\n  /** Where it sorts among the cost model's axes; core's own are multiples of 10. */\n  order: number\n  /** Rollup fields summed for the axis. */\n  fields: readonly string[]\n  /**\n   * Read only when every one of `fields` is absent from a rollup — the\n   * narrower field an older rollup recorded the same meter under.\n   */\n  fallbackFields?: readonly string[]\n  /**\n   * Rollup fields recorded beside the meter so its sum is legible, forwarded\n   * by `orgCogsInputFrom` and never priced.\n   */\n  recordedFields?: readonly string[]\n  /**\n   * The `ORG_COGS_UNIT_RATES_USD` key pricing one unit. Absent when the\n   * fields are already dollars, which then enter the model at ×1.\n   */\n  rate?: string\n  /**\n   * The month's LIVE reading, when the rollup's figure is a snapshot a meter\n   * keeps adding to: `orgs/{orgId}/{collection}/{month}`, the first of\n   * `fields` that is a positive number. It replaces the axis's first rollup\n   * field wherever a reader fetches it.\n   */\n  live?: { collection: string; fields: readonly string[] }\n}\n\n/** A band a plugin contributes to the utilization table. */\nexport interface PluginUsageBandDeclaration {\n  /** The band's key, and the column the staff table shows it under. */\n  id: string\n  label: string\n  order: number\n  /** Rollup fields summed for what the org used. */\n  fields: readonly string[]\n  fallbackFields?: readonly string[]\n  /** The resolved entitlement holding what the plan includes. */\n  entitlement: string\n  /** The entitlement is per SITE and the org-wide band is it × `hostLimit`. */\n  perHost?: boolean\n  /**\n   * The band is sold in a unit of cost and the rollup records dollars: what\n   * was used is `ceil(dollars / unitCostUsd)`, rounded UP so spend already\n   * made never reads as less of the band.\n   */\n  unitCostUsd?: number\n}\n\nexport type ResolvedPluginCostAxis = PluginCostAxisDeclaration & { pluginId: string }\nexport type ResolvedPluginUsageBand = PluginUsageBandDeclaration & { pluginId: string }\n\n/** What a plugin's `usageAxes` function answers. */\nexport interface PluginUsageAxesDeclaration {\n  costAxes?: readonly PluginCostAxisDeclaration[]\n  bands?: readonly PluginUsageBandDeclaration[]\n}\n\nexport function pluginCostAxes(): readonly ResolvedPluginCostAxis[] {\n  return PLUGIN_COST_AXES_DECLARED\n}\n\nexport function pluginUsageBands(): readonly ResolvedPluginUsageBand[] {\n  return PLUGIN_USAGE_BANDS_DECLARED\n}\n\n/** A positive finite number, or 0 — the reading every meter is priced from. */\nfunction meterValue(value: unknown): number {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\n/**\n * What a rollup recorded for a declared meter: `fields` summed, or\n * `fallbackFields` summed when the rollup carries none of `fields` at all.\n *\n * \"Carries none\" is `null` or absent, never zero. A rollup that measured\n * zero has answered, and must not fall back to a figure recorded under an\n * older, narrower basis.\n */\nexport function declaredMeterReading(\n  source: Readonly<Record<string, unknown>> | null | undefined,\n  declared: {\n    fields: readonly string[]\n    fallbackFields?: readonly string[]\n  },\n): number {\n  const present = declared.fields.some((field) => source?.[field] != null)\n  const fields =\n    !present && declared.fallbackFields?.length\n      ? declared.fallbackFields\n      : declared.fields\n  return fields.reduce((sum, field) => sum + meterValue(source?.[field]), 0)\n}\n\n/**\n * The live reading a cost axis names: the first of its `live.fields` that is\n * a positive number on the month's document, or `undefined` when none is.\n * `undefined` is \"keep the rollup's snapshot\", never zero.\n */\nexport function liveMeterReading(\n  document: { get(field: string): unknown } | null | undefined,\n  live: { fields: readonly string[] },\n): number | undefined {\n  for (const field of live.fields) {\n    const value = meterValue(document?.get(field))\n    if (value > 0) return value\n  }\n  return undefined\n}\n\n/** Every rollup field the declared cost axes read or record, in order. */\nexport function pluginCostAxisFields(): string[] {\n  const fields: string[] = []\n  for (const axis of PLUGIN_COST_AXES_DECLARED) {\n    for (const field of [\n      ...axis.fields,\n      ...(axis.fallbackFields ?? []),\n      ...(axis.recordedFields ?? []),\n    ]) {\n      if (!fields.includes(field)) fields.push(field)\n    }\n  }\n  return fields\n}\n"],"names":["PLUGIN_USAGE_BANDS_DECLARED","PLUGIN_COST_AXES_DECLARED","pluginCostAxes","pluginUsageBands","meterValue","value","parsed","Number","isFinite","declaredMeterReading","source","declared","present","fields","some","field","fallbackFields","length","reduce","sum","liveMeterReading","document","live","get","undefined","pluginCostAxisFields","axis","recordedFields","includes","push"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GAED,SACEA,2BAA2B,EAC3BC,yBAAyB,QACpB,qCAAiC;AAgExC,OAAO,SAASC;IACd,OAAOD;AACT;AAEA,OAAO,SAASE;IACd,OAAOH;AACT;AAEA,6EAA6E,GAC7E,SAASI,WAAWC,KAAc;IAChC,MAAMC,SAASC,OAAOF,gBAAAA,QAAS;IAC/B,OAAOE,OAAOC,QAAQ,CAACF,WAAWA,SAAS,IAAIA,SAAS;AAC1D;AAEA;;;;;;;CAOC,GACD,OAAO,SAASG,qBACdC,MAA4D,EAC5DC,QAGC;QAIaA;IAFd,MAAMC,UAAUD,SAASE,MAAM,CAACC,IAAI,CAAC,CAACC,QAAUL,CAAAA,0BAAAA,MAAQ,CAACK,MAAM,KAAI;IACnE,MAAMF,SACJ,CAACD,aAAWD,2BAAAA,SAASK,cAAc,qBAAvBL,yBAAyBM,MAAM,IACvCN,SAASK,cAAc,GACvBL,SAASE,MAAM;IACrB,OAAOA,OAAOK,MAAM,CAAC,CAACC,KAAKJ,QAAUI,MAAMf,WAAWM,0BAAAA,MAAQ,CAACK,MAAM,GAAG;AAC1E;AAEA;;;;CAIC,GACD,OAAO,SAASK,iBACdC,QAA4D,EAC5DC,IAAmC;IAEnC,KAAK,MAAMP,SAASO,KAAKT,MAAM,CAAE;QAC/B,MAAMR,QAAQD,WAAWiB,4BAAAA,SAAUE,GAAG,CAACR;QACvC,IAAIV,QAAQ,GAAG,OAAOA;IACxB;IACA,OAAOmB;AACT;AAEA,wEAAwE,GACxE,OAAO,SAASC;IACd,MAAMZ,SAAmB,EAAE;IAC3B,KAAK,MAAMa,QAAQzB,0BAA2B;YAGtCyB,sBACAA;QAHN,KAAK,MAAMX,SAAS;eACfW,KAAKb,MAAM;gBACVa,uBAAAA,KAAKV,cAAc,YAAnBU,uBAAuB,EAAE;gBACzBA,uBAAAA,KAAKC,cAAc,YAAnBD,uBAAuB,EAAE;SAC9B,CAAE;YACD,IAAI,CAACb,OAAOe,QAAQ,CAACb,QAAQF,OAAOgB,IAAI,CAACd;QAC3C;IACF;IACA,OAAOF;AACT"}

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

@@ -21,10 +21,9 @@
  * a slot id has always been an open string, so a plugin could already host a
  * zone of its own. What it could not do is say what that zone HANDS a widget.
  * The props had to be a type, the type had to be somewhere both sides import,
- * and "somewhere both sides import" was read as the core — which is how
- * `plugin-manager/commerce-zone-props.ts` and `plugin-manager/record-zone-props.ts`
- * came to spell out the commerce catalog and the record vocabulary of two
- * named plugins inside the platform.
+ * and "somewhere both sides import" was read as the core — which is how a
+ * named plugin's catalog or record vocabulary comes to be spelled out inside
+ * the platform.
  *
  * So the declaration moves to the plugin. A plugin defines a token for its
  * zone with {@link definePluginZone}, carrying the props type on the token,
@@ -36,7 +35,7 @@
  *
  * A zone token is `{ id }` and nothing else: `__props` is a phantom field that
  * never holds a value, so the props type is carried at the type level and
- * erased. That is the same trick the two type-only modules above use, and it
+ * erased. That is the same trick a type-only props module uses, and it
  * is load-bearing rather than tidy — AGL-3082 measured the zone catalog on the
  * published page's static graph, and a declaration that put a plugin's prop
  * SHAPES there would have made every published page carry the console's