@happyvertical/smrt-commerce 0.56.1 → 0.57.0

package/agents/document-money.md

@@ -1,27 +1,51 @@
 # Document money persistence
 
-Tenant money behavior is selected by the server-owned `TaxSettings.moneyModel`
-marker. Missing settings and `legacy` preserve the existing line-save behavior.
-`migrating` is a persisted maintenance guard: invoice money writes fail until
-the owning migration restores `legacy` or activates `v2`. Generated surfaces
-cannot write either the marker or its owner token.
+Commerce has one money model. Tax codes resolve each line's tax, the server
+computes line `taxAmount` and the header totals, and issuing a document freezes
+it with a money snapshot. Every Invoice and Contract money write needs a
+tenant; a tenantless write fails with `MoneyValidationError`
+`INVALID_MONEY_INPUT` (`Commerce money documents require a tenant`).
+
+### Tenant settings and bootstrap (#4009)
+
+Each tenant has one `TaxSettings` row. It is created once, wherever the first
+caller reaches it: `getOrCreateForTenant`, the cookbook path, a generated
+create, or the runtime barrier ahead of a tenant's first document. Creation
+runs in one transaction under a tenant advisory lock on PostgreSQL (the
+embedded write queue elsewhere), re-reads before inserting, and inserts the
+deterministic settings id, so racing first writers converge on one row.
+
+`ensureCommerceTenant(db, tenantId, { cookbook? })` is the one host bootstrap
+call after tenant creation. It seeds the settings row, the standard tax codes
+(`exempt`, `zero-rated`, `out-of-scope`), and the cookbook's commerce tax
+settings when one is given. It returns `{ tenantId }` and is idempotent;
+re-running it with a cookbook re-applies the cookbook defaults.
+
+Money data written by an earlier version is refused, never read. A schema with
+the earlier version's money columns or table, or an Invoice or Contract row
+without a tenant, refuses the whole database. A tenant with Invoice or Contract
+rows but no settings row, or with old-format documents (an issued document
+without a money snapshot, or a line with neither a tax code nor a component
+snapshot), is refused on its own. All fail with `COMMERCE_DATA_NEEDS_UPGRADE`
+and name `smrt db:upgrade-commerce-money`.
+See [money data upgrade](money-upgrade.md). Rows written with raw SQL bypass
+the model and are not recalculated.
 
 Every Invoice/InvoiceLineItem get, list, preview, mutation, posting, and
-accounting-sync phase acquires the same tenant settings row before document
-rows. The barrier is held through the owning transaction, so migration cannot
-start between the marker check and a money read/write. Nested coordinators
-reuse an explicitly registered transaction executor; adapter shape is never
-used as transaction proof. When the settings table exists, the first legacy
-runtime boundary materializes the deterministic legacy row solely as this
-durable serialization point. Older schemas without the table remain legacy
-and runtime never creates schema.
-
-In `v2`, saving an invoice line locks and reloads its parent on the caller's
+accounting-sync phase checks for old-format data, then acquires the tenant
+settings row before document rows. The lock is held through the owning
+transaction. Nested coordinators reuse an explicitly registered transaction
+executor; adapter shape is never used as transaction proof. Runtime code never
+creates schema.
+
+Saving an invoice line locks and reloads its parent on the caller's
 transaction, reloads every sibling, resolves current tax defaults, calculates
 the document once, and writes line snapshots, `DocumentTax`, and header totals
-atomically. Tax resolution order is line override, product, customer, then app
-default. Product reads use the products package's collection on that same
-transaction executor; tenant-owned and catalog-global products are accepted.
+atomically. Tax resolution order is line override, customer exemption (unless
+the line overrides), product, customer code, then the tenant default; `none`
+mode uses the tenant's `out-of-scope` code. Product reads use the products
+package's collection on that same transaction executor; tenant-owned and
+catalog-global products are accepted.
 
 The first transition away from `DRAFT`, or setting `arJournalId`, freezes the
 money document. The invoice and every line receive the same stable
@@ -68,18 +92,17 @@ draft overlay through the owning resolver/calculator without writes and rejects
 frozen documents. A supplied line id must name a stored line exactly once; omit
 the id for a new preview-only line. `getInvoiceMoneyFacts({ db, tenantId,
 invoiceId })` reads the authoritative stored header, lines, `moneySnapshotId`,
-and `DocumentTax` rows without recalculation. Both facades require an active
-`v2` tenant and fail closed while migration is in progress, so legacy or
-partially migrated amounts are never presented as money-v2 facts.
+and `DocumentTax` rows without recalculation. Both facades take the tenant
+settings lock and refuse a tenant whose data needs the upgrade.
 
 ### Record-screen composition
 
 `loadInvoiceRecordScreenData({ db, tenantId, invoiceId })` is the commerce
 server adapter for a generic invoice record page. A caller must already have
 that exact active tenant; the adapter never switches principals based on its
-argument. It holds the shared v2 money read barrier while it reads the stored
-header, lines, `DocumentTax`, and related credit-note summaries, so a migration
-cannot mix a stale header with a different snapshot of those rows. Its totals
+argument. It holds the tenant money lock while it reads the stored header,
+lines, `DocumentTax`, and related credit-note summaries, so it never mixes a
+stale header with a different snapshot of those rows. Its totals
 are a direct projection of persisted minor-unit values and component snapshots;
 it does not resolve a code or recalculate tax.
 
@@ -90,9 +113,10 @@ may expose `onCreateCreditNote` only with a server-derived
 `canCreateCreditNote` authorization result. The wrapper hides the action for
 credit-note records and never treats a client callback as authorization.
 
-`InvoiceLineItem.amount` is tax-exclusive net money in `v2`.
-`taxAmount` is separate, while `legacyAmount` is reserved for rollback during
-the compatibility migration. `taxCodeId` and component identity may be null for
+`InvoiceLineItem.amount` is the post-discount amount in the document's
+`lineAmountType`: tax-exclusive net for `exclusive`, tax-inclusive for
+`inclusive`. `taxAmount` is separate. `taxRate` is derived by the server from
+the resolved components (`0.05` means 5%); it is never an input. `taxCodeId` and component identity may be null for
 a genuine unassigned zero-tax line. Optional `productId` and
 `revenueAccountId` are nullable UUID references so PostgreSQL never receives an
 empty-string sentinel.
@@ -102,7 +126,7 @@ labels, percentage, liability account, taxable minor units, and tax minor
 units. Provider tax remains the invoice header's `providerTaxAmount`; commerce
 does not invent a tax code or component for provider-owned tax.
 
-Revenue recognition for `v2` reads only the frozen invoice, lines, and
+Revenue recognition reads only the frozen invoice, lines, and
 `DocumentTax` rows. It groups each line's stored net by its snapshotted revenue
 account (falling back to the caller's revenue account), groups component tax by
 the snapshotted liability account (falling back to the caller's tax account),
@@ -117,10 +141,14 @@ the invoice parent lock and transaction, so retries converge. Account IDs from
 frozen snapshots are still authorization checked: every used account must be
 active and owned by the invoice tenant.
 
-A posted `v2` invoice cannot move directly to `CANCELLED`. Call
+A posted invoice cannot move directly to `CANCELLED`. Call
 `cancelWithRevenueReversal({ bookCurrency })`; it reads the original posted
 journal, posts one deterministic journal with every debit and credit reversed,
 and stores `arReversalJournalId` with the status transition atomically. The
 original journal remains posted. Failed link or reversal writes roll back the
-entire operation, and retry returns the same reversal. Legacy tenants keep the
-existing recognition and cancellation behavior.
+entire operation, and retry returns the same reversal.
+
+Billing period close writes ordinary money-model invoices. The payment provider
+taxes them, so each billing line is an explicit override to the seller's
+`out-of-scope` code, and the provider's tax is stored in `providerTaxAmount`
+in the save that issues the invoice.

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.