@happyvertical/smrt-commerce 0.56.2 → 0.57.0

package/agents/invoice-calculations.md

@@ -1,56 +1,31 @@
-# General invoice calculations
-
-`@happyvertical/smrt-commerce/invoices` is a Svelte-free entry usable by server handlers and browsers. `calculateInvoiceLine`, `calculateInvoiceDraft`, and `resolveInvoiceLineDraft` share exact decimal arithmetic. The UI consumes these helpers for previews; preview results confer no authority.
-
-This guide describes the standalone, legacy-compatible invoice editor helpers.
-For tenant `moneyModel: 'v2'` document arithmetic, persisted tax components, and
-issued snapshots, use the [commercial money model](money-model.md) and [money
-calculator](money-calculator.md) instead.
-
-Drafts retain unparsed text. Quantity accepts nonnegative decimals with at most six fractional digits and must round-trip through the model numeric representation. Prices and flat discounts accept only whole currency minor units expressed in major-unit text. Currency uses the shared explicit ISO minor-unit table; unknown codes and codes without a minor unit are rejected. Servers must authorize their supported currency set. No exchange conversion occurs. Rates are percentages from 0 through 100 with at most six fractional digits. `discountType` is `flat` or `percent`; `taxMode` is `inherit` or `override`. An override of `0` is zero tax; an empty override is invalid. Inherited lines ignore their dormant override string.
-
-Calculation order is quantity × price rounded half up to minor units, discount rounded half up and subtracted, then tax on the discounted subtotal rounded half up. Flat discounts cannot exceed gross. Numeric model quantities and rates use their canonical decimal representation (including supported exponent notation), never a `toFixed` expansion of binary approximation. No floating-point multiplication or epsilon comparison determines money. Unsafe individual or aggregate results are rejected; invalid lines produce errors without monetary totals. Header validation requires customer, real issue/due dates with due date not before issue date, valid currency shape/default rate, at least one line, and unique nonblank row keys.
-
-`resolveInvoiceLineDraft` returns the existing model's resolved integer-minor price, flat discount, fractional quantity, effective fractional tax rate, and calculated amount. It verifies exact agreement with model arithmetic. `InvoiceLineItem.applyEditorDraft()` retains the editing modes alongside resolved fields; `getEditorDraft(authorizedContext)` restores them only while current authority and fields agree. See [invoice quantity storage](invoice-quantity.md) for the required existing-database migration. `calculateInvoiceMinorLine` is the currency-independent model helper: it permits existing negative-price credit lines, retains their historical ties toward positive infinity, and rejects invalid quantities/rates or unsafe/fractional money.
-
-Trailing zeroes do not make an exact amount invalid: `100.00` JPY is 100 minor units, while `100.01` JPY is rejected. Parsing never rewrites the draft text.
-
-## Server responsibilities
-
-Parse native form values into the typed draft (never pass unvalidated arbitrary JSON as the typed object), enforce request/row limits, authorize customer and source references in the active tenant, and validate edits against invoice lifecycle state. Replace inherited rate/currency policy with server-authorized context, call the shared validator/resolver, and save resolved rows and invoice within the application's transaction/retry contract. Ignore any client-supplied calculated amount. For these legacy-compatible helpers, default tax remains externally determined; this module is not a tax determination service. V2 tax-code resolution and stored tax facts are defined by the [commercial money model](money-model.md). Caller-owned extension allocations, budget availability and approval evidence require their own server validation and are not part of line pricing.
-
-Changing currency changes the precision and denomination of the entered values, not their numeric text. The UI must not silently convert entered amounts or rewrite invalid drafts. Reopening or changing authorized tax context requires fresh server validation.
-
-
-## Explicit tax rounding scope
-
-The `roundingScope: 'invoice'` option below is the standalone editor's
-legacy-compatible aggregate calculation. It is distinct from v2's
-`roundingScope: 'document'`, which allocates rounded tax into persisted
-document tax facts; see the [money calculator](money-calculator.md).
-
-`calculateInvoiceDraft(values, { roundingScope: 'invoice' })` and the shared
-`InvoiceEditor` / `InvoiceLineEditor` `roundingScope` prop accept `line` or
-`invoice`. Omission preserves per-line rounding. The server chooses this option
-from its authorized policy, and supplies it again when rendering rejected forms
-or reopening retained drafts; it is not a client authority field.
-
-Invoice scope groups numerically equal effective percentages, including textual
-variants such as `5` and `5.000000`, and rounds each rate group once through
-`calculateCostBillingTax`. Different rates remain independent components; explicit
-zero overrides remain exempt. Quantity and discount rounding are unchanged. Two
-10-minor lines at 5% therefore have tax 1 in invoice scope and 2 in line scope.
-This is an additive single-rate-per-line editor, not a tax determination or
-compound-tax solver. Invalid scope is a validation error. Drafts still reject
-negative quantities/prices; the signed model calculator is unchanged.
-
-`lineResults` and `resolveInvoiceLineDraft` remain standalone per-line
-calculations, useful for validation and existing line-mode model storage. They
-are **not allocations** of invoice-rounded tax: their tax/total fields may not
-sum to the aggregate. In invoice mode the UI displays each line's subtotal and
-an explanation, with tax and total shown only at invoice level. Persist the
-aggregate with the authorized scope and retained draft when using invoice
-rounding; do not reconstruct it by summing standalone resolved line totals.
-No persistence schema or `InvoiceLineItem` tax behavior is changed by this
-legacy-compatible adapter API. V2 persistence and issued tax snapshots are
-defined by the [commercial money model](money-model.md).
+# Invoice line calculation helper
+
+`@happyvertical/smrt-commerce/invoices` is a Svelte-free entry for server
+handlers and browsers. It exports `calculateInvoiceMinorLine`,
+`MoneyValidationError` and the `MoneyValidationCode` type.
+
+Document arithmetic, tax-code resolution, persisted tax components and issued
+snapshots belong to the [commercial money model](money-model.md) and the
+[money calculator](money-calculator.md). The invoice editor previews with
+`calculateMoneyEditorDraft`; see [the invoice editor](invoice-preparation.md).
+
+`calculateInvoiceMinorLine({ quantity, unitPrice, discount, taxRate })`
+calculates one stored line in integer minor units, independent of currency. It
+returns `grossMinor`, `discountMinor`, `subtotalMinor`, `taxMinor` and
+`totalMinor`, and it runs the same money calculator the documents use:
+
+- `quantity` is nonnegative, with at most six fractional digits;
+- `unitPrice` is a signed safe integer, so credit lines may be negative;
+- `discount` is a flat signed safe integer that carries the gross sign;
+- `taxRate` is an already-resolved fraction in [0, 1], with at most eight
+  fractional digits. It is an input to this helper only; it never determines
+  tax on a stored invoice line, whose tax comes from its tax codes.
+
+Rounding follows the money calculator, so a negative credit line rounds
+symmetrically with its positive counterpart. Numeric quantities and rates use
+their canonical decimal form, including exponent notation, and never a
+`toFixed` expansion. Invalid quantities or rates, fractional or unsafe money,
+and a discount with the wrong sign throw `RangeError` before persistence.
+
+The [invoice quantity migration](invoice-quantity.md) uses this helper to
+check that every stored quantity round-trips exactly.

package/agents/invoice-preparation.md

@@ -1,86 +1,75 @@
-# General invoice editor and allocation extensions
+# Invoice editor and allocation fields
 
-Import `InvoiceEditor`, `InvoiceLineEditor`, `InvoiceAllocationFields`, `InvoiceReview`
-and their Props types from `@happyvertical/smrt-commerce/svelte`. `InvoiceEditor`
-is the general invoice form; `InvoiceLineEditor` and `InvoiceAllocationFields`
-render fields only and never nest a form. The interactive Commerce invoice preview
-shows general line items with an optional allocation extension.
+Import `InvoiceEditor`, `InvoiceAllocationFields`, `InvoiceReview` and their
+Props types from `@happyvertical/smrt-commerce/svelte`. `InvoiceEditor` is the
+invoice form. It renders `MoneyInvoiceEditor` (also exported) and uses the
+commercial money model, the only invoice money model. Line tax
+comes from tax codes, never from a typed rate. See the
+[commercial money model](money-model.md) and the
+[money calculator](money-calculator.md).
 
-`InvoiceDraftValues` contains customerId, issuedOn, dueOn, currency, paymentTerms,
-taxRate and ordered lines. Each `InvoiceLineDraft` contains caller key, description,
-sku, fractional quantity, unitPrice, discountType, discountValue, taxMode and
-taxRate. Editable values are lossless strings, including invalid submitted input.
-Unit price and flat discount are currency-unit text; percentage values use `5`
-for five percent. `discountType` is `flat` or `percent`; `taxMode` is `inherit` or
-`override`. Explicit override `0` means zero tax; it never means inherit. Unknown
-modes remain representable for rejected submissions. Dates remain text so invalid
-values survive action failures. Customer options are caller-authorized projections;
-unknown retained IDs remain visible. Currency uses the shared CurrencySelect.
+`InvoiceEditorProps` requires `action` and `money: MoneyEditorProps`. Optional
+props are `method` (default `post`), `canEdit`, `pending`, `hiddenFields`,
+`intentField` (default `intent`), `saveIntent` (default `save`), `saveLabel`
+and `onsubmit`. `money` carries:
 
-See [server calculation and persistence semantics](invoice-calculations.md).
+- `mode: 'v2'` (a fixed discriminator);
+- `draft`: currency, `lineAmountType` (`exclusive`, `inclusive` or `none`),
+  `roundingScope` (`line` or `document`) and ordered `lines`;
+- `taxCodes`: the authorized tax-code choices, each with its components;
+- optionally `frozen`, `status`, `kind` (`invoice` or `credit_note`), `stored`,
+  `onCreateCreditNote`, `customerTaxExempt`, `sellerTaxRegistrations`,
+  `partyTaxId`, `showNetSubtotal` and `names`.
 
-`InvoiceLineEditor` also recalculates when used independently: it retains a local
-draft copy and calls optional `onchange(line)` with each edit. It never mutates
-the supplied line. Replacing the line prop applies caller/server response values.
-
-The UI invokes the exact, Svelte-free `calculateInvoiceDraft` and
-`calculateInvoiceLine` helpers for previews. The shared public calculation entry
-is `@happyvertical/smrt-commerce/invoices`. Valid totals use safe integer minor
-units, with exact decimal arithmetic and explicit currency precision. Invalid
-drafts show an unavailable-total message rather than plausible numbers. The
-calculator uses Commerce's explicit exponent table and its existing two-digit
-fallback for other uppercase three-letter codes; the server must authorize its
-supported currencies. Calculated values are never submitted as authority.
-The server revalidates customer/SKU, prices, quantity, discounts, tax policy,
-permissions and calculated totals. Header taxRate is a draft preview default,
-not a new persisted Invoice tax field; replace it with authorized tax context
-on the server. Client edits never establish approval or allocate inventory.
+Each `MoneyEditorLineDraft` holds id, description, quantity, unitPrice,
+`discountType` (`none`, `percent` or `amount`), discountValue (a nonnegative
+magnitude; the calculator applies the line sign), `taxMode` (`inherit` or
+`override`), `taxCodeId`, and the resolver's `inheritedTaxCodeId` and
+`inheritedTaxCodeSource` (`product`, `customer`, `app`, `exempt-customer` or
+`none`). Values are lossless strings, so input the server rejected comes back
+unchanged. Choosing a tax code sets `taxMode` to `override`. Clearing it goes
+back to the inherited code, and the editor shows that code's source.
 
 ```svelte
-<InvoiceEditor action="?/save" values={form?.values ?? data.values}
-  customers={data.authorizedCustomers} errors={form?.errors}
-  message={form?.message} canEdit={data.mayEdit}
-  hiddenFields={[{ name: 'requestId', value: form?.requestId ?? data.requestId }]}>
-  {#snippet children(current)}
-  <InvoiceAllocationFields currency={current.currency}
-    allocations={form?.allocations ?? data.allocations}
-    sources={data.authorizedSources} mayReadSources={data.mayReadSources}
-    canEdit={data.mayEdit} />
-  {/snippet}
-</InvoiceEditor>
+<InvoiceEditor action="?/save" money={form?.money ?? data.money}
+  canEdit={data.mayEdit}
+  hiddenFields={[{ name: 'requestId', value: form?.requestId ?? data.requestId }]} />
 ```
 
-Native header names default to customerId, issuedOn, dueOn, currency,
-paymentTerms, invoiceTaxRate. Repeated line names are lineKey, lineDescription,
-lineSku, lineQuantity, lineUnitPrice, lineDiscountType, lineDiscountValue,
-lineTaxMode and lineTaxRate, in displayed order. `fields` and `lineFields` adapt
-names. Caller `errors` use header names or `lineKey.fieldName` keys. Repeated
-hidden fields retain exact values. Avoid collisions with the component's names.
+Native field names default to `lineAmountType`, `roundingScope`, then repeated
+`lineId`, `lineDescription`, `lineQuantity`, `lineUnitPrice`,
+`lineDiscountType`, `lineDiscountValue`, `lineTaxMode` and `lineTaxCodeId`, in
+displayed order. Use `money.names` to rename them. `moneyEditorFieldNames`
+exports the defaults, and `moneyEditorSubmission(draft)` returns the typed
+shape those controls represent. Hidden fields are submitted exactly as given,
+including repeated names. The default transport is a native POST, which also
+works without JavaScript. `onsubmit` can enhance it.
+
+`calculateMoneyEditorDraft(draft, taxCodes)` is the editor's only calculation:
+the pure money calculator, run on the retained text. The preview gives no
+authority. The server resolves tax codes (line override, else product, else
+customer, else the tenant default), recomputes `taxAmount` and the totals, and
+ignores any client total. Invalid input shows the calculator's message instead
+of a total.
 
-Default submitter `intent` values are `save`, `addLine` and `removeLine:<key>`;
-`saveIntent`, `addIntent`, `removePrefix` and `fields.intent` adapt the contract.
-Save is first so implicit Enter cannot remove/add a row. Structural actions
-use formnovalidate, preserving every submitted draft string and request token.
-The caller returns updated rows for add/remove; it must not persist or rotate
-request identity simply because the user added a line. The default transport
-is native POST, including without JavaScript. With JavaScript, input changes
-update exact previews without mutating the supplied values object. `onsubmit`
-may enhance transport; caller-owned retryStatus/pending controls submission.
+A frozen document (`frozen: true`) renders only `stored`, the server's issued
+snapshot. It never recalculates and disables every field. If `stored` is
+missing, the editor reports that. A frozen invoice shows a credit-note action,
+enabled only when the host supplies `onCreateCreditNote`. A credit note never
+offers one.
 
-Allocation fields remain optional application-specific composition. Each row
-has key, sourceId, currency-unit amount, optional remove and field errors.
-`mayReadSources=false` hides supplied labels/balances and renders references.
-Retained unavailable sources remain postable for server reconciliation. Native
-names remain sourceId/allocationAmount and checked zero-based removeRow;
-`fields` maps these, and addIntent defaults to addAllocation. Availability,
-reservations, budget policy and approval are caller/server concerns. The
-extension must receive the same canEdit/pending capability as its owner.
+`InvoiceAllocationFields` renders source-allocation rows without a form of its
+own; put it in a caller-owned native form. Each row has key, sourceId, a
+currency-unit amount, optional remove, and field errors.
+`mayReadSources=false` hides supplied labels and balances and renders
+references instead. Unavailable sources that were retained stay postable, so
+the server can reconcile them. Native names stay sourceId, allocationAmount
+and the checked zero-based removeRow. `fields` renames them, and `addIntent`
+defaults to `addAllocation`. Availability, reservations, budget policy and
+approval belong to the caller and server.
 
-`review` is a caller-supplied snapshot; edits do not infer status changes.
-Read-only disables fields and hides mutation buttons. On rejected, denied or
-uncertain actions, return every original string, stable row key, errors and
-caller request/tenant/fingerprint identity. No component generates request keys.
+`InvoiceReview` presents a review snapshot that the caller supplies. Edits
+never infer a status change. No component generates request keys.
 
 Focused validation: Commerce `vitest.invoices.config.ts`,
-`e2e/invoices/playwright.config.ts`, `typecheck`, and `build`; consolidated
-release gates and calculator/model checks remain separate owning validations.
+`e2e/invoices/playwright.config.ts`, `typecheck` and `build`.

package/agents/invoice-quantity.md

@@ -1,22 +1,11 @@
-# Invoice quantity persistence and editor recovery
+# Invoice quantity persistence
 
 InvoiceLineItem accepts nonnegative decimal quantities with at most six decimal
 places. The `1.0` default declares a floating-point quantity column. Unit price,
-flat discount, and calculated amount remain safe integer minor units. Save always
-validates resolved fields and recalculates amount; a supplied amount is never
-trusted. Gross quantity × price and then tax on discounted gross round to minor
-units, with ties toward positive infinity (including existing negative-price
-credit lines). Tax is a resolved fraction in [0, 1], with eight decimal places.
-Accounting export retains an explicit zero rate instead of omitting it.
-
-`applyEditorDraft(draft, authorizedContext)` resolves the shared invoice draft
-helper into description/SKU/quantity/price/flat discount/tax and stores cloned
-`invoiceEditorStateJson` TEXT, accessed through a guarded typed `invoiceEditorState` getter/setter. It does not save.
-`getEditorDraft(authorizedContext)` returns a clone only when currency, inherited
-tax authority, and all source fields still agree. Otherwise it returns null so the
-caller can reconstruct a flat-discount/explicit-tax editor from resolved fields.
-Normal save clears stale editor state and never derives money from metadata.
-All other object metadata, authorization, and transaction ownership are unchanged.
+discount and amount stay safe integer minor units. Every save goes through the
+invoice money aggregate, which recomputes the line and ignores
+any supplied amount. Tax comes from the line's resolved tax code, never from a
+stored rate. See the [commercial money model](money-model.md).
 
 ## Existing integer columns
 
@@ -34,11 +23,10 @@ SQLite uses the public core table-rebuild planner to change the declaration to
 REAL while preserving existing columns, constraints, indexes, and triggers. If
 incoming foreign keys make that rebuild unsafe, the migration throws with the
 planner reason and rolls back; it does not disable constraints or lose children.
-Resolve that maintenance condition before deploying fractional writers. The same
-transaction adds the nullable TEXT `invoice_editor_state_json` column with an empty
-string default on every engine. This column is required for updated model saves.
-An existing floating quantity column still receives the missing state column.
-No schema mutation runs implicitly during runtime initialization or model save.
+Resolve that maintenance condition before deploying fractional writers. The
+migration no longer adds an editor-state column. An `invoice_editor_state_json`
+column that an earlier version added is left in place and unused. No schema
+mutation runs implicitly during runtime initialization or model save.
 
 The actual DuckDB quantity/storage migration is tested. Complete Commerce model
 persistence on DuckDB is currently unsupported because its hard foreign keys use

package/agents/minor-unit-migration.md

@@ -1,8 +1,8 @@
-# Legacy major-unit to minor-unit migration
+# Major-unit to minor-unit migration
 
-This guide covers the existing numeric-column rescale only. It is not the
-Invoice-v2 tenant money-model migration: it does not change `TaxSettings`,
-calculate tax, create snapshots, or activate v2.
+This guide covers the numeric-column rescale only. It is not the
+[money data upgrade](money-upgrade.md): it does not change `TaxSettings`,
+calculate tax, or create snapshots.
 
 `preflightCommerceMoneyMinorUnits(db)` reports whether known commerce columns
 still contain major units, rows that would round, and values outside JavaScript

package/agents/money-calculator.md

@@ -35,11 +35,10 @@ codes include `TAX_CODE_DUPLICATE_COMPONENT`,
 shared input, discount, percent, compound, state, scope, safety, freeze, and
 currency codes exported as `MoneyValidationCode`.
 
-The existing invoice functions in `src/svelte/invoices/calculations.ts` remain
-compatibility adapters for the legacy single-component exclusive model until the
-tenant migration gate enables persisted money-v2 fields. In particular,
-`calculateInvoiceMinorLine(input)` defaults to the legacy negative-tie rule for
-existing model saves. Migration-aware callers explicitly pass
-`{ moneyModel: 'v2' }`; there is no process-global mode. V2 callers pass the
-stored signed discount through unchanged; editor magnitude normalization happens
-before constructing that stored input.
+`calculateInvoiceMinorLine(input)` in `src/svelte/invoices/calculations.ts`
+(also exported from `@happyvertical/smrt-commerce/invoices`) runs one line
+through this calculator with a single-component code built from its resolved
+fraction. It takes no options. Its discount is signed minor units and passes
+through unchanged, and its ties round half away from zero for negative
+lines too. Editor magnitude normalization happens before constructing that
+input. See [invoice line calculation](invoice-calculations.md).

package/agents/money-model.md

@@ -5,9 +5,9 @@ shapes, validation codes, and worked calculator examples live in the
 [calculator guide](money-calculator.md) and
 [package documentation](../../../docs/content/commerce-money.md). Money values
 are signed safe-integer minor units; calculator tax percentages are exact text,
-so `'5'` means 5%. The retained `InvoiceLineItem.taxRate` and
-`ContractLineItem.taxRate` fields are different legacy persisted fractions:
-`0.05` means 5%.
+so `'5'` means 5%. The `InvoiceLineItem.taxRate` and
+`ContractLineItem.taxRate` fields are server-derived fractions of the resolved
+components (`0.05` means 5%); they are never tax inputs.
 
 ## Calculation contract
 
@@ -39,10 +39,10 @@ catalogue, seeds, registrations, and cookbook boundary are documented in
 
 ## Stored Invoice facts
 
-`TaxSettings.moneyModel` selects the Invoice write behavior. `legacy` keeps the
-compatibility path; `migrating` rejects money writes; `v2` resolves a draft's
-current settings once and atomically writes the header, line snapshots, and
-`DocumentTax` rows. The detailed persistence, freeze, preview, credit-note, and
+There is one money model. Saving a draft resolves its current tax settings
+once and atomically writes the header, line snapshots, and `DocumentTax` rows.
+Every money document needs a tenant, and data written by an earlier version is
+refused until it is upgraded ([money data upgrade](money-upgrade.md)). The detailed persistence, freeze, preview, credit-note, and
 refund contracts are in [document money](document-money.md).
 
 Once an Invoice leaves `DRAFT`, or receives an AR journal, its money snapshot
@@ -55,7 +55,7 @@ not invent a taxable component.
 
 A credit note is an `Invoice` with `kind: 'credit_note'`. It stores positive
 amounts; posting, reporting, and accounting adapters apply that direction once.
-Issued-credit capacity and refunds are stable Invoice-v2 behavior. A refund is
+Issued-credit capacity and refunds are stable Invoice behavior. A refund is
 a positive `Payment` of kind `refund`, allocated only to a credit note. See
 [document money](document-money.md) before presenting either balance as an
 ordinary incoming payment.
@@ -63,15 +63,13 @@ ordinary incoming payment.
 ## Invoice MCP `get` projection
 
 The standard Invoice MCP `get` tool uses `serializeInvoiceMcpGet`. For a
-legacy tenant, or when tenant settings are absent, it returns the ordinary
-public Invoice projection and omits the `money` alias. For a v2 tenant, the
-optional `money` value is the stored `InvoiceMoneyFacts` projection: its
-header, line snapshots, and `DocumentTax` facts are read from the issued
-snapshot and are never recalculated.
-
-A tenant in the `migrating` gate refuses this read with the stable
-`FROZEN_DOCUMENT` code and the public message `Tenant money migration is in
-progress`. If the caller's `PublicJsonOptions` hide any Invoice,
+tenant invoice, the optional `money` value is the stored `InvoiceMoneyFacts`
+projection: its header, line snapshots, and `DocumentTax` facts are read from
+the stored snapshot and are never recalculated. An invoice without an id or
+tenant returns the ordinary public Invoice projection.
+
+A tenant whose data needs the upgrade refuses this read with
+`COMMERCE_DATA_NEEDS_UPGRADE`. If the caller's `PublicJsonOptions` hide any Invoice,
 `InvoiceLineItem`, or `DocumentTax` field needed by the money projection, the
 serializer returns the base Invoice and omits the entire `money` alias. It does
 not expose restricted values through a partial plain-object alias.
@@ -84,7 +82,7 @@ serializers](../../core/agents/generators.md#mcp-get-serializers).
 ## Reporting and integrations
 
 The materialized `TaxSummaryReport` and its public descriptor/drilldown bridge
-read stored Invoice `DocumentTax` facts under the tenant v2 gate. See
+read stored Invoice `DocumentTax` facts under the tenant money lock. See
 [tax summary aggregation](tax-summary.md). Commerce exports
 `createTaxSummaryMaterializedReportHost()` for an application-owned,
 server-only host; register that host in the app's fixed report-host registry to
@@ -104,10 +102,8 @@ mapper](accounting-snapshot-mapper.md).
 
 ## Deliberate boundaries
 
-The tenant migration and rollback contract is documented in
-[tenant line-amount migration](line-amount-migration.md).
-The marker is a maintenance gate, not a customer-controlled setting. Contract
-money persistence remains a separate aggregate contract; production report
+Upgrading data written by an earlier version is documented in
+[money data upgrade](money-upgrade.md). Contract money persistence remains a separate aggregate contract; production report
 hosting is an application opt-in over the public host described above. The
 model also does not provide currency conversion, cash-basis/deposit accounting,
 partial recoverability, period locking, or compound tax.

package/agents/money-upgrade.md

@@ -0,0 +1,92 @@
+# Money data upgrade
+
+Commerce has one money model. It does not read money data written by an
+earlier version, and it does not convert that data on the fly. It refuses it
+and names the upgrade command. The operator steps are in the CLI guide,
+[commerce money upgrade command](../../cli/agents/commerce-money-upgrade.md).
+
+## Detection
+
+`src/upgrade/detect.ts` owns detection. Four shapes count as old data:
+
+- **Old schema.** The database still has `tax_settings.money_model`,
+  `tax_settings.money_migration_id`, `*_line_items.legacy_amount`, or the
+  `commerce_money_migration_documents` table. This refuses the whole database.
+- **Documents without a tenant.** An Invoice or Contract row, header or line,
+  with no tenant. The current model writes none, and the upgrade cannot convert
+  one: assign it to a tenant or delete it. This refuses the whole database and
+  keeps the old schema in place until it is resolved.
+- **Tenant without settings.** A tenant has Invoice or Contract rows but no
+  `tax_settings` row. This refuses that tenant only.
+- **Old-format documents.** An issued Invoice or Contract without a money
+  snapshot, or a line with neither a tax code nor a component snapshot. The
+  current model never writes either, so these stay detectable after `db:migrate --drop-columns`
+  removed the old columns. This refuses that tenant only.
+
+`assertCommerceMoneySchemaCurrent(db)` checks the schema.
+`assertTenantMoneyCurrent(db, tenantId)` checks the schema, then the tenant.
+On PostgreSQL every cross-tenant scan runs on a connection of its own (opened
+from the database URL), in a transaction that raises `smrt.system_context`,
+so the caller's connection and row policies are never touched; concurrent
+checks for one database and tenant share a single scan. Both cache a passing
+result per database (keyed by its connection URL, so
+request executors share it) and tenant, so the check runs once per process.
+Invoice, Contract and line models also run the check from `initialize()` on
+every row hydrated from the database, which covers unscoped reads and every
+collection class, including generated STI subtype collections. A
+tenantless collection read still checks the schema, and a tenant's first
+`TaxSettings` row is refused while that tenant holds old documents. Every runtime money read and write, the money MCP tools, the tax
+summary, and `ensureCommerceTenant()` call them first.
+
+A refusal is a `CommerceDataNeedsUpgradeError` with `code`
+`COMMERCE_DATA_NEEDS_UPGRADE`. Its message ends with the command, for example
+`Run smrt db:upgrade-commerce-money --tenant-id <id> to upgrade it.`
+`commerceMoneyUpgradeCommand(tenantId?)` builds that command text.
+
+`findCommerceMoneyUpgradeNeeds(db)` scans the whole database. It is
+operator-only: it ignores the caller's row permissions, so never wire it into
+a principal-facing surface. It returns `oldSchema`, `tenantlessDocuments`
+(rows to assign or delete) and each tenant that needs the upgrade, with a
+reason (`legacy-marker`, `interrupted-migration`, `missing-settings`, or
+`old-format-documents`).
+`smrt db:status` uses it to report the `commerce-money-upgrade` error
+precondition, so `smrt app doctor` reports `migration-required`.
+
+## Upgrade
+
+`upgradeCommerceMoney(db, { tenantId? })` in `src/upgrade/money-v2.ts` is the
+one-shot conversion behind `smrt db:upgrade-commerce-money`. Run the normal
+schema migration first. Each tenant converts in its own transaction:
+
+1. Its tax settings row and standard codes are seeded.
+2. Each stored fractional rate maps to a code. A zero rate becomes `exempt`
+   for an exempt customer, otherwise `out-of-scope`. Any other rate becomes a
+   one-component `rate-<percent>` code, created once.
+3. Issued documents are backfilled from their stored values: line net, line
+   tax, tax-code snapshot, `DocumentTax` rows, and a money snapshot. No stored
+   total changes.
+4. Drafts are recomputed through the runtime from their prices. Only
+   old-format lines (no tax code and no component snapshot) are mapped; a
+   draft header keeps its amount type and rounding. The result lists each
+   draft whose total changed.
+
+An issued document whose stored lines do not add up exactly to its stored
+header fails its tenant. So do an invalid stored rate, an invoice posted under
+the earlier version (its revenue journal carries that version's provenance,
+which current posting and reversal refuse; void it and clear the link, or reset
+the data), an existing `rate-<percent>` code or component that does not
+mean exactly that rate, and an edited standard `exempt` or `out-of-scope`
+code. Nothing in that tenant changes, and the result lists
+each failing document. A tenant whose earlier
+migration never finished also fails; roll it back with the version that started
+it, or reset its data. Converted tenants are skipped on a rerun.
+
+Once no tenant needs the upgrade, the old columns and table are dropped. The
+upgrade leaves no mode flag. Read `failures` and `remaining` on the result; the
+CLI exits nonzero on either. New `rate-<percent>` components have no liability
+account and are listed in `componentsWithoutLiabilityAccount`; posting falls
+back to the caller's `taxAccountId` until one is assigned.
+
+The runtime never imports `money-v2.ts`. Delete the `upgrade/` directory, the
+CLI command, and the detection call sites together once no supported version
+can have written old-format data.

package/agents/revenue-journal.md

@@ -13,8 +13,8 @@ debit receivables and credit revenue/tax; signed credits naturally swap sides, a
 For inclusive documents, stored line net is `amountMinor - taxMinor`; for exclusive
 and no-tax pricing it is `amountMinor`. Revenue is grouped by each line's stored
 account, falling back to the caller's revenue account. Component tax uses the
-stored liability account and falls back to `taxAccountId`. A `legacy-*` code that
-needs this fallback returns a structured warning. Provider tax is posted once as
+stored liability account and falls back to `taxAccountId`. The result has only
+`entries`; there are no warnings. Provider tax is posted once as
 its own entry to `taxAccountId`. Zero-tax and null-component reporting rows do not
 produce entries.
 

package/agents/tax-codes.md

@@ -4,23 +4,22 @@
 change a rate, archive the old component, create a replacement and update the
 editable `TaxCode.components` list. Never edit a used component's percent.
 
-Every tenant seeds `exempt`, `zero-rated`, `out-of-scope`, and
-`legacy-unreconciled`. Those kinds have no components because they report
-differently. A legacy zero rate means out-of-scope unless the linked customer
-was explicitly exempt; malformed or out-of-range legacy rates stay visible
-through `legacy-unreconciled` and the mapping report.
+Every tenant seeds `exempt`, `zero-rated`, and `out-of-scope`
+(`STANDARD_TAX_CODES`, seeded by `ensureTenantTaxCodes(db, tenantId)` in
+`src/tax/standard-codes.ts`). Those kinds have no components because they
+report differently. They are reserved: billing lines and zero rates rely on
+them never carrying tax, so `ensureTenantTaxCodes` (and through it the
+bootstrap, billing period close and the upgrade) refuses a standard code
+whose kind or components were changed. `TaxCodeCollection.findByCode(code, tenantId?)` finds a
+code by its tenant-unique `code`, optionally for an explicit tenant.
+The [money data upgrade](money-upgrade.md) adds a one-component
+`rate-<percent>` code for each nonzero rate it finds in earlier-version data.
 
 `TaxSettings` owns tenant defaults, tax registrations, default line amount type
 and rounding scope. Cookbook policies adapt the portable settings document;
-they do not replace persisted tax settings. The per-tenant migration marker is
-owned by the money-snapshot migration. Ordinary saves and generated creates
-cannot change it: a new instance whose tenant natural key would upsert over a
-`migrating` or `v2` row is refused rather than resetting that tenant to legacy.
-The ordinary save transaction locks and re-reads the tenant marker before its
-natural-key upsert, serializing that check with migration claim and activation.
-If the tenant has no marker to lock, its first ordinary save is insert-only: a
-concurrent migration that creates the marker wins and the stale save is refused
-instead of adopting and overwriting the migration-owned row.
+they do not replace persisted tax settings. There is one settings row per
+tenant, created once under a tenant lock (see
+[document money](document-money.md#tenant-settings-and-bootstrap-4009)).
 
 `applyCommerceCookbookSettings(db, tenantId, cookbook)` is the explicit
 server-side activation boundary for core's portable `taxRate`, inclusion, and
@@ -34,6 +33,10 @@ import cookbook from './smrt.cookbook.json' with { type: 'json' };
 await applyCommerceCookbookSettings(db, session.tenantId, cookbook);
 ```
 
+`ensureCommerceTenant(db, tenantId, { cookbook })` wraps this call with the
+settings row and standard code seed; prefer it for a newly created tenant
+(#4009).
+
 `smrt cookbook apply` writes project files and does not have a database or
 tenant, so it deliberately performs no storage writes. Activation creates or
 reuses a component and default tax code, then updates tenant `TaxSettings` in

package/agents/tax-summary.md

@@ -32,8 +32,9 @@ movement to every component.
 ## Materialized document report path
 
 `TaxSummaryReport` is a tenant-scoped, manual materialized report. Its owner,
-`TaxSummaryReportCollection.refreshTaxSummary()`, refuses tenants whose
-`TaxSettings.moneyModel` is not `v2`: legacy and migrating documents are not a
+`TaxSummaryReportCollection.refreshTaxSummary()`, requires a tenant and refuses
+one whose money data needs the upgrade (`COMMERCE_DATA_NEEDS_UPGRADE`, see
+[money data upgrade](money-upgrade.md)): earlier-version documents are not a
 complete stored-tax source. The caller injects the public Expense and Journal
 source adapters because commerce cannot depend on expenses; omitting either
 adapter is a refusal, never a zero-ITC fallback.
@@ -68,13 +69,14 @@ matching `DocumentTax.documentType` pairs: `invoice`/`invoice` or
 `credit_note`/`credit_note`. Credit rows retain positive stored values and pass
 through the aggregation's single credit sign step.
 
-Refresh holds the tenant `TaxSettings` parent lock through the v2 gate, all
-source reads, aggregation, and replacement. Every source-adapter call receives
+Refresh holds the tenant `TaxSettings` parent lock through the upgrade check,
+all source reads, aggregation, and replacement. Every source-adapter call receives
 the same transaction-bound database executor. Replacement rows use a stable
 UUID derived from tenant, period, currency, row kind, and dimension, so retry
 and concurrent same-period refreshes converge to one row set. Materialized
-`list`, `get`, `count`, and Invoice drilldowns all recheck the tenant's marker;
-`legacy` and `migrating` refuse even existing report rows.
+`list`, `get`, `count`, and Invoice drilldowns all require a tenant context and
+recheck it; a tenant that needs the upgrade is refused even for existing report
+rows.
 
 Each document drilldown fact carries its printed invoice number or Contract
 reference, tenant-scoped customer/vendor party id, issue date, stored taxable

package/dist/billing/period-close.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"period-close.d.ts","sourceRoot":"","sources":["../../src/billing/period-close.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,WAAW,EAAE,IAAI,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,iDAAiD;IACjD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,OAAO,GACP,MAAM,GACN,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,WAAW,EAAE,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;gBAAzB,MAAM,EAAE,iBAAiB;CAW/C;AAmDD,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,GAAG,OAAa,GAAG,aAAa,CAQrE;AAkCD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,MAAM,CAAC,EACxD,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAsED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,KAAK,GAAE,gBAAqB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAwE5B"}
+{"version":3,"file":"period-close.d.ts","sourceRoot":"","sources":["../../src/billing/period-close.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,WAAW,EAAE,IAAI,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,iDAAiD;IACjD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,OAAO,GACP,MAAM,GACN,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,WAAW,EAAE,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;gBAAzB,MAAM,EAAE,iBAAiB;CAW/C;AAmDD,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,GAAG,OAAa,GAAG,aAAa,CAQrE;AAkCD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,MAAM,CAAC,EACxD,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAsED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,KAAK,GAAE,gBAAqB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAwE5B"}