@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/plugin-manager/plugin-subscription-topics.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-subscription-topics.generated.ts"],"sourcesContent":["/**\n * GENERATED FILE — do not edit. Regenerate with:\n *   node tools/scripts/generate-plugin-manifests.mjs\n *\n * The subscription topics plugins declare (AGL-3080): each plugin's\n * `subscriptionTopics` block in plugins.config.json, in preference-page\n * order. Core's `app-utils/subscription-topics.ts` reads them as the\n * built-in floor of every org's topic catalog; core names no stream.\n */\n\nimport type { DeclaredSubscriptionTopic } from '../app-utils/subscription-topics'\n\nexport const PLUGIN_SUBSCRIPTION_TOPICS_DECLARED: readonly DeclaredSubscriptionTopic[] = [\n  {\n    \"pluginId\": \"marketing\",\n    \"id\": \"marketing\",\n    \"name\": \"Promotions and offers\",\n    \"description\": \"Sales, discounts and seasonal campaigns.\",\n    \"order\": 10,\n    \"default\": true\n  },\n  {\n    \"pluginId\": \"commerce\",\n    \"id\": \"newsletter\",\n    \"name\": \"Newsletter\",\n    \"description\": \"Regular news and stories from us.\",\n    \"order\": 20\n  },\n  {\n    \"pluginId\": \"commerce\",\n    \"id\": \"product-updates\",\n    \"name\": \"Product updates\",\n    \"description\": \"New products, restocks and changes to what we offer.\",\n    \"order\": 30\n  },\n  {\n    \"pluginId\": \"outreach\",\n    \"id\": \"sales\",\n    \"name\": \"Sales outreach\",\n    \"description\": \"Messages from a person here about working together.\",\n    \"order\": 40\n  }\n]\n"],"names":["PLUGIN_SUBSCRIPTION_TOPICS_DECLARED"],"mappings":"AAAA;;;;;;;;CAQC,GAID,OAAO,MAAMA,sCAA4E;IACvF;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;QACT,WAAW;IACb;IACA;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;IACX;IACA;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;IACX;IACA;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;IACX;CACD,CAAA"}

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[]>;

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;