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

package/src/lib/plugin-manager/plugin-site-export.js

@@ -0,0 +1,40 @@
+/**
+ * @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_HOST_COLLECTIONS_DECLARED } from "./first-party-plugins.generated.js";
+import { hostResourcePlatformCap } from "./plugin-host-resources.js";
+/** Every collection a plugin declares for the site backup, in config order. */ export function listPluginSiteExportCollections() {
+    const out = [];
+    for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED){
+        var _resource_platformCap;
+        const { siteExport, resource } = row;
+        if (!siteExport || !resource) continue;
+        out.push({
+            pluginId: row.pluginId,
+            collection: row.name,
+            limit: siteExport.limit,
+            fields: siteExport.fields,
+            label: resource.label,
+            count: resource.quotaKey ? {
+                quotaKey: resource.quotaKey
+            } : {
+                max: hostResourcePlatformCap((_resource_platformCap = resource.platformCap) != null ? _resource_platformCap : '')
+            }
+        });
+    }
+    return out;
+}
+
+//# sourceMappingURL=plugin-site-export.js.map

package/src/lib/plugin-manager/plugin-site-export.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-export.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_HOST_COLLECTIONS_DECLARED } from './first-party-plugins.generated'\nimport { hostResourcePlatformCap } from './plugin-host-resources'\n\n/**\n * A plugin's host collection in the platform's whole-site backup (AGL-3080).\n *\n * `/api/hosts/export` writes one JSON bundle of everything designable on a\n * site and `/api/hosts/import` restores it (AGL-163). The platform's own\n * documents — screens, layouts, components, authors, content collections,\n * media — are the routes' to carry. A plugin whose site documents belong in\n * a backup declares so beside the collection, in the `hostCollections` block\n * of `plugins.config.json` (a host collection's `siteExport`), and both\n * routes walk the declarations: the export reads up to `limit` live documents\n * into the bundle under the collection's own name, and the restore writes each\n * one back through `fields` and counts the result against the collection's\n * declared `resource`.\n *\n * ## `fields` is the round trip, not the create\n *\n * A restore writes with `merge: false`, so the list is every key a live\n * document carries — which can be narrower than what a create admits, and is\n * often wider — and a key left off is ERASED from every restored document\n * (AGL-1382). Nothing the restore stamps (`createdAt`, `updatedAt`,\n * `deletedAt`) or scopes (`visibleTo`) is on it; the generator refuses them.\n *\n * ## Compiled, and counted\n *\n * A backup that silently lacks a collection is worse than a failed one: the\n * file looks whole until the day it is restored. So the declarations are\n * compiled, present the moment this module is imported, and a runtime\n * `registerPluginHostCollections` carrying a `siteExport` throws. A restore\n * creates documents with the Admin SDK, past the rules, so the generator also\n * refuses a `siteExport` on a collection with no `resource`: the resource's\n * plan counter or flat platform cap is what the restore is met against.\n *\n * Reached by its own subpath, never the barrel: its readers are the two\n * console routes.\n */\nexport interface PluginHostCollectionSiteExport {\n  /** The most live documents one bundle carries; a restore writes no more. */\n  limit: number\n  /** The keys a restore writes back. Anything else a bundle carries is dropped. */\n  fields: readonly string[]\n}\n\n/** What a restore of a declared collection is counted against. */\nexport type PluginSiteExportCount =\n  /** A plan counter, an `OrgEntitlements` key core resolves. */\n  | { quotaKey: string }\n  /**\n   * A flat platform cap, resolved from the name the resource declares, or\n   * `null` for a name core does not hold — which a restore refuses.\n   */\n  | { max: number | null }\n\n/** A declared collection with the plugin that made it and its count. */\nexport interface ResolvedPluginSiteExportCollection extends PluginHostCollectionSiteExport {\n  pluginId: string\n  /** The subcollection under `hosts/{hostId}`, and its key in the bundle. */\n  collection: string\n  /** Plural, for a restore's refusal: \"this backup holds 40 {label}\". */\n  label: string\n  count: PluginSiteExportCount\n}\n\n/** Every collection a plugin declares for the site backup, in config order. */\nexport function listPluginSiteExportCollections(): ResolvedPluginSiteExportCollection[] {\n  const out: ResolvedPluginSiteExportCollection[] = []\n  for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED) {\n    const { siteExport, resource } = row\n    if (!siteExport || !resource) continue\n    out.push({\n      pluginId: row.pluginId,\n      collection: row.name,\n      limit: siteExport.limit,\n      fields: siteExport.fields,\n      label: resource.label,\n      count: resource.quotaKey\n        ? { quotaKey: resource.quotaKey }\n        : { max: hostResourcePlatformCap(resource.platformCap ?? '') },\n    })\n  }\n  return out\n}\n"],"names":["PLUGIN_HOST_COLLECTIONS_DECLARED","hostResourcePlatformCap","listPluginSiteExportCollections","out","row","resource","siteExport","push","pluginId","collection","name","limit","fields","label","count","quotaKey","max","platformCap"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gCAAgC,QAAQ,qCAAiC;AAClF,SAASC,uBAAuB,QAAQ,6BAAyB;AAgEjE,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,MAA4C,EAAE;IACpD,KAAK,MAAMC,OAAOJ,iCAAkC;YAWbK;QAVrC,MAAM,EAAEC,UAAU,EAAED,QAAQ,EAAE,GAAGD;QACjC,IAAI,CAACE,cAAc,CAACD,UAAU;QAC9BF,IAAII,IAAI,CAAC;YACPC,UAAUJ,IAAII,QAAQ;YACtBC,YAAYL,IAAIM,IAAI;YACpBC,OAAOL,WAAWK,KAAK;YACvBC,QAAQN,WAAWM,MAAM;YACzBC,OAAOR,SAASQ,KAAK;YACrBC,OAAOT,SAASU,QAAQ,GACpB;gBAAEA,UAAUV,SAASU,QAAQ;YAAC,IAC9B;gBAAEC,KAAKf,yBAAwBI,wBAAAA,SAASY,WAAW,YAApBZ,wBAAwB;YAAI;QACjE;IACF;IACA,OAAOF;AACT"}

package/src/lib/plugin-manager/plugin-sitemap-sections.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @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 child sitemap a plugin's documents fill, declared by that plugin
+ * (AGL-3080).
+ *
+ * The tenant's `/sitemap.xml` is an index over one child per section (AGL-2520):
+ * the site's pages, its content collections and its authors are the platform's
+ * and are built by the route itself. A plugin that serves pages of its own — a
+ * product at `/products/{slug}` — had its section written into that route by
+ * hand: the collection, the filter, the store setting that switches it on, the
+ * address and the date field were all core's knowledge of one plugin's model.
+ *
+ * So the plugin declares the section, and the route builds every declared one
+ * the same way: counted for the index, paged by document id for the child.
+ *
+ * ## Compiled, because the reader is a published page's
+ *
+ * The sitemap is what a search engine is told the site holds. A section
+ * registered at runtime would be missing from any process that had not loaded
+ * the plugin, and a crawler reads a missing section as pages that no longer
+ * exist — the products drop out of the index silently, on a live site. So
+ * sections are compiled from `plugins.config.json` by
+ * `tools/scripts/generate-plugin-manifests.mjs`, present the moment this
+ * module is imported, and there is no registrar.
+ *
+ * ## What a declaration can say
+ *
+ * Only what a sitemap needs and a query can express: one equality filter, the
+ * setting that must be set for the pages to render at all, the address with
+ * `{slug}` in it, a field that drops a row (a soft delete), and the date
+ * fields to try in order. A row without a slug addresses nothing and is left
+ * out. Anything richer belongs to the plugin's own page, not to its sitemap.
+ *
+ * Reached by its own subpath, never the barrel.
+ */
+export interface PluginSitemapSectionDeclaration {
+    /** The section's path segment: `/sitemaps/{section}/{page}.xml`. */
+    section: string;
+    /** The subcollection under `hosts/{hostId}` whose documents are the pages. */
+    collection: string;
+    /** The one equality a document must meet to be a page. */
+    where?: {
+        field: string;
+        equals: string | number | boolean;
+    };
+    /**
+     * A `collection/doc` under the host and a field on it that must be set for
+     * the section to exist: the template the pages render through. Unset, the
+     * section is left out rather than listing addresses that 404.
+     */
+    enabledBy?: {
+        doc: string;
+        field: string;
+    };
+    /** The page's site path, with `{slug}` standing for the document's slug. */
+    path: string;
+    /** The field holding the slug; `slug` when absent. */
+    slugField?: string;
+    /** A field whose truthy value leaves the row out, for a soft delete the filter cannot see. */
+    skipWhen?: string;
+    /** The fields a row's `lastmod` is read from, first present wins. */
+    lastmod?: readonly string[];
+}
+/** A declaration with the plugin that made it. */
+export type ResolvedPluginSitemapSection = PluginSitemapSectionDeclaration & {
+    pluginId: string;
+};
+/** Every declared section, in config order — the order the index lists them. */
+export declare function listPluginSitemapSections(): readonly ResolvedPluginSitemapSection[];
+/** One declared section by its name, or `null`. */
+export declare function pluginSitemapSection(section: string): ResolvedPluginSitemapSection | null;
+/** The site path of one row, or `null` for a row with no slug. */
+export declare function pluginSitemapSectionPath(declaration: PluginSitemapSectionDeclaration, slug: unknown): string | null;

package/src/lib/plugin-manager/plugin-sitemap-sections.js

@@ -0,0 +1,29 @@
+/**
+ * @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_SITEMAP_SECTIONS_DECLARED } from "./first-party-plugins.generated.js";
+/** Every declared section, in config order — the order the index lists them. */ export function listPluginSitemapSections() {
+    return PLUGIN_SITEMAP_SECTIONS_DECLARED;
+}
+/** One declared section by its name, or `null`. */ export function pluginSitemapSection(section) {
+    var _PLUGIN_SITEMAP_SECTIONS_DECLARED_find;
+    return (_PLUGIN_SITEMAP_SECTIONS_DECLARED_find = PLUGIN_SITEMAP_SECTIONS_DECLARED.find((one)=>one.section === section)) != null ? _PLUGIN_SITEMAP_SECTIONS_DECLARED_find : null;
+}
+/** The site path of one row, or `null` for a row with no slug. */ export function pluginSitemapSectionPath(declaration, slug) {
+    if (typeof slug !== 'string' || !slug) return null;
+    return declaration.path.replace('{slug}', slug);
+}
+
+//# sourceMappingURL=plugin-sitemap-sections.js.map

package/src/lib/plugin-manager/plugin-sitemap-sections.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-sitemap-sections.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_SITEMAP_SECTIONS_DECLARED } from './first-party-plugins.generated'\n\n/**\n * A child sitemap a plugin's documents fill, declared by that plugin\n * (AGL-3080).\n *\n * The tenant's `/sitemap.xml` is an index over one child per section (AGL-2520):\n * the site's pages, its content collections and its authors are the platform's\n * and are built by the route itself. A plugin that serves pages of its own — a\n * product at `/products/{slug}` — had its section written into that route by\n * hand: the collection, the filter, the store setting that switches it on, the\n * address and the date field were all core's knowledge of one plugin's model.\n *\n * So the plugin declares the section, and the route builds every declared one\n * the same way: counted for the index, paged by document id for the child.\n *\n * ## Compiled, because the reader is a published page's\n *\n * The sitemap is what a search engine is told the site holds. A section\n * registered at runtime would be missing from any process that had not loaded\n * the plugin, and a crawler reads a missing section as pages that no longer\n * exist — the products drop out of the index silently, on a live site. So\n * sections are compiled from `plugins.config.json` by\n * `tools/scripts/generate-plugin-manifests.mjs`, present the moment this\n * module is imported, and there is no registrar.\n *\n * ## What a declaration can say\n *\n * Only what a sitemap needs and a query can express: one equality filter, the\n * setting that must be set for the pages to render at all, the address with\n * `{slug}` in it, a field that drops a row (a soft delete), and the date\n * fields to try in order. A row without a slug addresses nothing and is left\n * out. Anything richer belongs to the plugin's own page, not to its sitemap.\n *\n * Reached by its own subpath, never the barrel.\n */\nexport interface PluginSitemapSectionDeclaration {\n  /** The section's path segment: `/sitemaps/{section}/{page}.xml`. */\n  section: string\n  /** The subcollection under `hosts/{hostId}` whose documents are the pages. */\n  collection: string\n  /** The one equality a document must meet to be a page. */\n  where?: { field: string; equals: string | number | boolean }\n  /**\n   * A `collection/doc` under the host and a field on it that must be set for\n   * the section to exist: the template the pages render through. Unset, the\n   * section is left out rather than listing addresses that 404.\n   */\n  enabledBy?: { doc: string; field: string }\n  /** The page's site path, with `{slug}` standing for the document's slug. */\n  path: string\n  /** The field holding the slug; `slug` when absent. */\n  slugField?: string\n  /** A field whose truthy value leaves the row out, for a soft delete the filter cannot see. */\n  skipWhen?: string\n  /** The fields a row's `lastmod` is read from, first present wins. */\n  lastmod?: readonly string[]\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginSitemapSection = PluginSitemapSectionDeclaration & {\n  pluginId: string\n}\n\n/** Every declared section, in config order — the order the index lists them. */\nexport function listPluginSitemapSections(): readonly ResolvedPluginSitemapSection[] {\n  return PLUGIN_SITEMAP_SECTIONS_DECLARED\n}\n\n/** One declared section by its name, or `null`. */\nexport function pluginSitemapSection(\n  section: string,\n): ResolvedPluginSitemapSection | null {\n  return PLUGIN_SITEMAP_SECTIONS_DECLARED.find((one) => one.section === section) ?? null\n}\n\n/** The site path of one row, or `null` for a row with no slug. */\nexport function pluginSitemapSectionPath(\n  declaration: PluginSitemapSectionDeclaration,\n  slug: unknown,\n): string | null {\n  if (typeof slug !== 'string' || !slug) return null\n  return declaration.path.replace('{slug}', slug)\n}\n"],"names":["PLUGIN_SITEMAP_SECTIONS_DECLARED","listPluginSitemapSections","pluginSitemapSection","section","find","one","pluginSitemapSectionPath","declaration","slug","path","replace"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gCAAgC,QAAQ,qCAAiC;AAgElF,8EAA8E,GAC9E,OAAO,SAASC;IACd,OAAOD;AACT;AAEA,iDAAiD,GACjD,OAAO,SAASE,qBACdC,OAAe;QAERH;IAAP,QAAOA,yCAAAA,iCAAiCI,IAAI,CAAC,CAACC,MAAQA,IAAIF,OAAO,KAAKA,oBAA/DH,yCAA2E;AACpF;AAEA,gEAAgE,GAChE,OAAO,SAASM,yBACdC,WAA4C,EAC5CC,IAAa;IAEb,IAAI,OAAOA,SAAS,YAAY,CAACA,MAAM,OAAO;IAC9C,OAAOD,YAAYE,IAAI,CAACC,OAAO,CAAC,UAAUF;AAC5C"}

package/src/lib/plugin-manager/plugin-tax-profile.d.ts

@@ -24,11 +24,18 @@
  * Importing the owner's model instead is how two money paths end up with two
  * rounding rules, and the second is found by an accountant.
  *
- * ## Pure, synchronous, and unauthenticated
+ * ## Where the rate is kept, and the arithmetic over it
  *
- * Both questions are arithmetic over values the caller already holds: a rate
- * off the settings it read, a charge in cents, a settled payment object.
- * Nothing is read and nobody is asked who they are.
+ * The merchant's rates are the owner's settings, stored where the owner keeps
+ * them, so a caller asks for one — {@link PluginTaxProfile.flatRate}, the
+ * contract's one read, by site and by the kind of charge — and never reads
+ * the owner's documents itself. A plugin that knew where another plugin kept
+ * a merchant's tax settings would charge untaxed, and record it as untaxed,
+ * the day those settings moved.
+ *
+ * The other two questions are pure and synchronous arithmetic over values the
+ * caller already holds: the rate it was handed, a charge in cents, a settled
+ * payment object. Nobody is asked who they are.
  *
  * ## No profile is a refusal, never a zero
  *
@@ -59,6 +66,15 @@ export interface PluginResolvedFlatTax {
     pct: number;
 }
 export interface PluginTaxProfile {
+    /**
+     * The merchant's flat rate for one kind of charge on a site, as the owner
+     * stores it — to be handed to {@link PluginTaxProfile.flatTax} as read. `charge` names what
+     * is being sold in the owner's words for its rates (`service` for an
+     * appointment). A site that set none, or a kind the owner keeps no rate
+     * for, answers `undefined`, which `flatTax` prices at zero. Server-side:
+     * the owner reads its own settings document.
+     */
+    flatRate(hostId: string, charge: string): Promise<unknown>;
     /**
      * Tax, EXCLUSIVE, for a flat merchant rate on one charged amount. `rate` is
      * the merchant's stored setting, passed as read: the owner decides what a

package/src/lib/plugin-manager/plugin-tax-profile.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-tax-profile.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 * The tenant's tax rule, answered by the one plugin that owns it (AGL-3080).\n *\n * More than one plugin takes money — a storefront sells goods, a calendar\n * sells appointments — and a merchant has ONE tax profile. The plugin that\n * keeps it works out what a flat rate adds to a charge and which regime a\n * settled payment was taxed under; any other plugin that charges asks here.\n * Importing the owner's model instead is how two money paths end up with two\n * rounding rules, and the second is found by an accountant.\n *\n * ## Pure, synchronous, and unauthenticated\n *\n * Both questions are arithmetic over values the caller already holds: a rate\n * off the settings it read, a charge in cents, a settled payment object.\n * Nothing is read and nobody is asked who they are.\n *\n * ## No profile is a refusal, never a zero\n *\n * {@link pluginTaxProfile} THROWS when no plugin registered one. Every other\n * seam here answers `null` for \"nobody home\", and this one must not: a caller\n * that read `null` as \"no tax\" would charge a customer an untaxed total and\n * record it as untaxed, silently, and the merchant would owe the difference.\n * A refused sale is seen the same day.\n *\n * It cannot happen in a working build. Both apps load every plugin's server\n * entry before a plugin handler, a cron or the billing webhook runs\n * (`ensureAll`), so the owner's registration is in place wherever a charge is\n * priced; `tax-profile-is-registered.spec.ts` in each app holds that.\n *\n * ## One owner\n *\n * A workspace has one tax profile, so the contract is a slot: a second\n * plugin's profile is refused naming both and the incumbent keeps serving.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-tax-profile`); it is not in the barrel.\n */\n\n/** What a flat rate adds to one charge. All zero and empty when it adds nothing. */\nexport interface PluginResolvedFlatTax {\n  taxCents: number\n  /** What the line is called on the receipt. */\n  label: string\n  pct: number\n}\n\nexport interface PluginTaxProfile {\n  /**\n   * Tax, EXCLUSIVE, for a flat merchant rate on one charged amount. `rate` is\n   * the merchant's stored setting, passed as read: the owner decides what a\n   * usable rate is, and an absent, zero, negative or out-of-range one answers\n   * zero rather than throwing.\n   */\n  flatTax(\n    rate: unknown,\n    chargeCents: number,\n    fallbackLabel: string,\n  ): PluginResolvedFlatTax\n  /**\n   * Which regime a settled payment was taxed under, as the owner records it.\n   * `manualTaxCents` is the tax this caller added as a line of its own, which\n   * the payment processor reports as no tax at all.\n   */\n  taxModeOf(settledPayment: unknown, manualTaxCents?: number): string\n}\n\nexport const PLUGIN_TAX_PROFILE = definePluginServiceContract<PluginTaxProfile>(\n  'core.tax-profile',\n  { multiple: false },\n)\n\n/** Registers the plugin that owns the tenant's tax rule. */\nexport function registerPluginTaxProfile(\n  profile: PluginTaxProfile,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_TAX_PROFILE, profile, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The owner, or `null` — for a caller that only wants to know who it is. */\nexport function pluginTaxProfileOwner(): string | null {\n  return resolvePluginServices(PLUGIN_TAX_PROFILE)[0]?.pluginId ?? null\n}\n\n/** The tax rule. THROWS when no plugin registered one; see the module note. */\nexport function pluginTaxProfile(): PluginTaxProfile {\n  const entry = resolvePluginServices(PLUGIN_TAX_PROFILE)[0]\n  if (!entry) {\n    throw new Error(\n      'no plugin registered a tax profile, so this charge cannot be priced: ' +\n        'refusing rather than charging it untaxed',\n    )\n  }\n  return entry.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_TAX_PROFILE","multiple","registerPluginTaxProfile","profile","options","pluginId","pluginTaxProfileOwner","pluginTaxProfile","entry","Error","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAoE1B,OAAO,MAAMC,qBAAqBH,4BAChC,oBACA;IAAEI,UAAU;AAAM,GACnB;AAED,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,OAAyB,EACzBC,OAA+B;IAE/BN,sBAAsBE,oBAAoBG,SAAS,aAC7CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,2EAA2E,GAC3E,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,mBAAmB,CAAC,EAAE,qBAA5CD,wBAA8CM,QAAQ,mBAAI;AACnE;AAEA,6EAA6E,GAC7E,OAAO,SAASE;IACd,MAAMC,QAAQT,sBAAsBC,mBAAmB,CAAC,EAAE;IAC1D,IAAI,CAACQ,OAAO;QACV,MAAM,IAAIC,MACR,0EACE;IAEN;IACA,OAAOD,MAAME,IAAI;AACnB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-tax-profile.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 * The tenant's tax rule, answered by the one plugin that owns it (AGL-3080).\n *\n * More than one plugin takes money — a storefront sells goods, a calendar\n * sells appointments — and a merchant has ONE tax profile. The plugin that\n * keeps it works out what a flat rate adds to a charge and which regime a\n * settled payment was taxed under; any other plugin that charges asks here.\n * Importing the owner's model instead is how two money paths end up with two\n * rounding rules, and the second is found by an accountant.\n *\n * ## Where the rate is kept, and the arithmetic over it\n *\n * The merchant's rates are the owner's settings, stored where the owner keeps\n * them, so a caller asks for one — {@link PluginTaxProfile.flatRate}, the\n * contract's one read, by site and by the kind of charge — and never reads\n * the owner's documents itself. A plugin that knew where another plugin kept\n * a merchant's tax settings would charge untaxed, and record it as untaxed,\n * the day those settings moved.\n *\n * The other two questions are pure and synchronous arithmetic over values the\n * caller already holds: the rate it was handed, a charge in cents, a settled\n * payment object. Nobody is asked who they are.\n *\n * ## No profile is a refusal, never a zero\n *\n * {@link pluginTaxProfile} THROWS when no plugin registered one. Every other\n * seam here answers `null` for \"nobody home\", and this one must not: a caller\n * that read `null` as \"no tax\" would charge a customer an untaxed total and\n * record it as untaxed, silently, and the merchant would owe the difference.\n * A refused sale is seen the same day.\n *\n * It cannot happen in a working build. Both apps load every plugin's server\n * entry before a plugin handler, a cron or the billing webhook runs\n * (`ensureAll`), so the owner's registration is in place wherever a charge is\n * priced; `tax-profile-is-registered.spec.ts` in each app holds that.\n *\n * ## One owner\n *\n * A workspace has one tax profile, so the contract is a slot: a second\n * plugin's profile is refused naming both and the incumbent keeps serving.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-tax-profile`); it is not in the barrel.\n */\n\n/** What a flat rate adds to one charge. All zero and empty when it adds nothing. */\nexport interface PluginResolvedFlatTax {\n  taxCents: number\n  /** What the line is called on the receipt. */\n  label: string\n  pct: number\n}\n\nexport interface PluginTaxProfile {\n  /**\n   * The merchant's flat rate for one kind of charge on a site, as the owner\n   * stores it — to be handed to {@link PluginTaxProfile.flatTax} as read. `charge` names what\n   * is being sold in the owner's words for its rates (`service` for an\n   * appointment). A site that set none, or a kind the owner keeps no rate\n   * for, answers `undefined`, which `flatTax` prices at zero. Server-side:\n   * the owner reads its own settings document.\n   */\n  flatRate(hostId: string, charge: string): Promise<unknown>\n  /**\n   * Tax, EXCLUSIVE, for a flat merchant rate on one charged amount. `rate` is\n   * the merchant's stored setting, passed as read: the owner decides what a\n   * usable rate is, and an absent, zero, negative or out-of-range one answers\n   * zero rather than throwing.\n   */\n  flatTax(\n    rate: unknown,\n    chargeCents: number,\n    fallbackLabel: string,\n  ): PluginResolvedFlatTax\n  /**\n   * Which regime a settled payment was taxed under, as the owner records it.\n   * `manualTaxCents` is the tax this caller added as a line of its own, which\n   * the payment processor reports as no tax at all.\n   */\n  taxModeOf(settledPayment: unknown, manualTaxCents?: number): string\n}\n\nexport const PLUGIN_TAX_PROFILE = definePluginServiceContract<PluginTaxProfile>(\n  'core.tax-profile',\n  { multiple: false },\n)\n\n/** Registers the plugin that owns the tenant's tax rule. */\nexport function registerPluginTaxProfile(\n  profile: PluginTaxProfile,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_TAX_PROFILE, profile, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The owner, or `null` — for a caller that only wants to know who it is. */\nexport function pluginTaxProfileOwner(): string | null {\n  return resolvePluginServices(PLUGIN_TAX_PROFILE)[0]?.pluginId ?? null\n}\n\n/** The tax rule. THROWS when no plugin registered one; see the module note. */\nexport function pluginTaxProfile(): PluginTaxProfile {\n  const entry = resolvePluginServices(PLUGIN_TAX_PROFILE)[0]\n  if (!entry) {\n    throw new Error(\n      'no plugin registered a tax profile, so this charge cannot be priced: ' +\n        'refusing rather than charging it untaxed',\n    )\n  }\n  return entry.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_TAX_PROFILE","multiple","registerPluginTaxProfile","profile","options","pluginId","pluginTaxProfileOwner","pluginTaxProfile","entry","Error","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAoF1B,OAAO,MAAMC,qBAAqBH,4BAChC,oBACA;IAAEI,UAAU;AAAM,GACnB;AAED,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,OAAyB,EACzBC,OAA+B;IAE/BN,sBAAsBE,oBAAoBG,SAAS,aAC7CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,2EAA2E,GAC3E,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,mBAAmB,CAAC,EAAE,qBAA5CD,wBAA8CM,QAAQ,mBAAI;AACnE;AAEA,6EAA6E,GAC7E,OAAO,SAASE;IACd,MAAMC,QAAQT,sBAAsBC,mBAAmB,CAAC,EAAE;IAC1D,IAAI,CAACQ,OAAO;QACV,MAAM,IAAIC,MACR,0EACE;IAEN;IACA,OAAOD,MAAME,IAAI;AACnB"}

package/src/lib/plugin-manager/plugin-tax-return-sources.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @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';
+export { PLUGIN_TAX_RETURN_SOURCES };
+/** Which exporter the filing jurisdiction gets. */
+export type TaxReturnFilingForm = 'tx-webfile' | 'breakdown';
+/**
+ * The jurisdiction the operator files in, as the platform resolved it from
+ * its own configuration. A source words its lines and findings for THIS
+ * jurisdiction and never assumes one.
+ */
+export interface TaxReturnFiling {
+    /** The bucket key: `US-TX`, `US-CA`, `GB`. */
+    code: string;
+    /** How a sentence names it: `Texas`, or the code itself. */
+    label: string;
+    /** Which exporter the filing lines are for. */
+    form: TaxReturnFilingForm;
+    /** How a sentence names the filing figures: `Items 1–3`, `the breakdown`. */
+    figuresName: string;
+}
+/** What the return asks every source, once per period. */
+export interface TaxReturnSourceRequest {
+    /** `2026-Q3` or `2026-09`, echoed for the record. */
+    period: string;
+    /** Half-open UTC bounds of the period. */
+    start: Date;
+    end: Date;
+    filing: TaxReturnFiling;
+    /**
+     * The most documents the operator will read for one source. Past it the
+     * answer is `truncated`, and a truncated source blocks the return: the
+     * ceiling is the operator's policy, so a source is TOLD it.
+     */
+    rowCap: number;
+}
+export type TaxReturnFindingSeverity = 'blocking' | 'review';
+/**
+ * One finding, in the words a preparer reads. `blocking` means the return
+ * must not be filed until it is resolved; `review` means a figure is
+ * qualified. A zero count is not raised.
+ */
+export interface TaxReturnFinding {
+    /** Stable, and unique on the return. */
+    id: string;
+    severity: TaxReturnFindingSeverity;
+    /** Rows, or cents where the label says so. */
+    count: number;
+    label: string;
+    /** What it means for the return, and what to do — not a restatement. */
+    detail: string;
+}
+/** A line printed beneath the platform's own filing figures. */
+export interface TaxReturnFilingLine {
+    /** The form's item number where the figure maps to one, else `—`. */
+    item: string;
+    label: string;
+    /** Dollars, or null when the figure is not computed. */
+    dollars: string | null;
+    note: string;
+}
+/** One cell of a source's table on the screen. */
+export interface TaxReturnSectionCell {
+    text: string;
+    /** A second, quieter line under the text. */
+    caption?: string;
+    /**
+     * A short tag beside the text. `attention` marks the figure that needs a
+     * decision; `neutral` qualifies one.
+     */
+    tag?: {
+        label: string;
+        tone: 'attention' | 'neutral';
+    };
+    /** The figure a reader must not miss. */
+    strong?: boolean;
+}
+export interface TaxReturnSectionColumn {
+    label: string;
+    /** Right-aligned. */
+    numeric?: boolean;
+    /** Money: set in a fixed-width face so columns of cents line up. */
+    money?: boolean;
+}
+/** A table on the source's card. */
+export interface TaxReturnSectionTable {
+    /** A subheading above the table; the first table sits under the card's own. */
+    heading?: string;
+    /** A sentence between the heading and the table. */
+    description?: string;
+    columns: TaxReturnSectionColumn[];
+    rows: Array<{
+        key: string;
+        cells: TaxReturnSectionCell[];
+    }>;
+    /** What the table says when it has no rows. */
+    empty: string;
+    /** A caption under the table. */
+    footnote?: string;
+}
+/** One label/value line of a source's figures. */
+export interface TaxReturnSectionFigure {
+    label: string;
+    value: string;
+    note: string;
+}
+/**
+ * One block of the working-papers export, as the CSV's own rows.
+ *
+ * `jurisdictions` places it beside the operator's own sales by jurisdiction,
+ * before the working papers; `sections` places it after them, where each
+ * source's figures sit. The platform separates blocks with a blank row.
+ */
+export interface TaxReturnExportBlock {
+    placement: 'jurisdictions' | 'sections';
+    rows: string[][];
+}
+/** What a source answers for one period. */
+export interface TaxReturnSourceAnswer {
+    /** Stable key for the source's findings and its card, unique on the return. */
+    id: string;
+    /** The noun for its rows: `Storefront`, `Marketplace`. */
+    name: string;
+    /** The card's heading. */
+    title: string;
+    /** The card's help, as a documentation excerpt. */
+    help: string;
+    /** The paragraph under the heading. */
+    intro: string;
+    /** Documents past the request's `rowCap` were not read. */
+    truncated: boolean;
+    /** Rows no period query can reach — in this return and every other. */
+    undatedRows: number;
+    /** The source's own findings. Truncation and undated rows are raised by the platform. */
+    findings: TaxReturnFinding[];
+    /** Lines beneath the filing figures, for the request's `filing.form`. */
+    filingLines: TaxReturnFilingLine[];
+    tables: TaxReturnSectionTable[];
+    figures: TaxReturnSectionFigure[];
+    exports: TaxReturnExportBlock[];
+    /** The source's own figures, carried whole for the audit. */
+    summary: unknown;
+    /** The rows behind them, as the source projects them for the working papers. */
+    rows: unknown[];
+}
+/** One source on the return: its answer, or why there is none. */
+export type TaxReturnSection = ({
+    outcome: 'answered';
+    pluginId: string;
+} & TaxReturnSourceAnswer) | {
+    outcome: 'refused';
+    pluginId: string;
+    /** The plugin id: a refused source never said what it calls itself. */
+    id: string;
+    /** Why nothing from this source is on the return, as the return prints it. */
+    reason: string;
+};
+export interface TaxReturnSource {
+    /**
+     * This plugin's sales for one period. May throw: the return refuses the
+     * source rather than read a throw as nothing sold.
+     */
+    read(request: TaxReturnSourceRequest): Promise<TaxReturnSourceAnswer>;
+}
+/** Every source answers; one per plugin. */
+export declare const TAX_RETURN_SOURCES: import("./plugin-services").PluginServiceContract<TaxReturnSource>;
+/**
+ * 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 declare function registerTaxReturnSource(source: TaxReturnSource, options?: {
+    pluginId?: string;
+}): void;
+/** The plugins with a registered source, in the order they answer. */
+export declare function listTaxReturnSources(): string[];
+/**
+ * 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 declare function readTaxReturnSources(request: TaxReturnSourceRequest, declared?: readonly string[]): Promise<TaxReturnSection[]>;