@happyvertical/smrt-commerce 0.56.2 → 0.57.0

package/AGENTS.md

@@ -12,7 +12,7 @@ E-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, pay
 - **LicenseSale**: industry-neutral licensing primitive. Carries an *immutable* rights snapshot (`rightsMedium`, `rightsDistributionScope`, `rightsExclusivity`, `rightsDuration`, `rightsTerritory`, `rightsSublicensing`, `rightsDerivatives` — typed `Meta<T>` fields), licensee identity (`licenseeEmail`, optional `licenseeLegalEntity` / `licenseeJurisdiction`), and a signed-PDF reference (`pdfUrl`, `pdfHash`, optional `onChainHashRegistryRef`). Once saved at `ContractStatus.ACCEPTED`, the rights snapshot is frozen — mutating any of the seven rights fields and re-saving throws. The only legal transition out of ACCEPTED is `revoke()` (moves to CANCELLED without touching rights). Useful for stock media, music licensing, code-asset marketplaces, license keys, anywhere rights are sold for a fee.
 - **ContractLineItem**: items on contracts.
 - **Invoice**: status machine `DRAFT → SENT → VIEWED → PARTIAL → PAID` (also OVERDUE, CANCELLED, WRITTEN_OFF). `recognizeRevenue()` creates balanced AR journal entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable).
-- **InvoiceLineItem**: fractional-quantity line items with safe minor-unit validation/recalculation on save; editor-mode recovery and existing-column migration are documented in [invoice quantity persistence](agents/invoice-quantity.md).
+- **InvoiceLineItem**: fractional-quantity line items with safe minor-unit validation/recalculation on save; the existing-column migration is documented in [invoice quantity persistence](agents/invoice-quantity.md).
 - **Payment** / **PaymentAllocation**: tracks payments against invoices (status: see Gotchas). Carries optional backend-adapter fields for PaymentBackend-routed flows: `backendId` (rail adapter id — `base-usdc`, `btc`, `stripe`, distinct from `externalProvider` which names an accounting sync destination), `backendTxRef` (chain tx hash or gateway settlement id), `nativeAmount` / `nativeCurrency` (what actually arrived), `usdAtQuote` / `usdAtConfirmation` (drift accounting for volatile-currency rails). `Payment.usdDrift()` returns the confirmation - quote delta, or `0` when either side is unset.
 - **PaymentInstrument**: reusable saved payment method ("card on file"). Stores only provider references and non-sensitive display metadata (`providerCustomerId`, `providerPaymentMethodId`, brand / last4 / expiry), never raw card data. `isDefault` is domain-managed, not API-writable: `PaymentInstrumentCollection.setDefaultForCustomer(customerId, instrumentId)` validates the target and clears the customer's other defaults (one per customer).
 - **PaymentIntent**: short-lived pre-payment commitment with multi-option semantics. Locks a USD price for a fixed window (default 15 minutes) and lists one or more `PaymentOption`s describing different rails (`backendId`, `currency`, `payTo`, `nativeAmount`, optional `chain` / `memo` / `x402Capable` / `expiresAt`). First option to receive payment wins; the others are implicitly retired. State machine `awaiting_payment → paid → (issued | retired)` plus `expired` and `cancelled`. Mutate via dedicated `markPaid` / `markIssued` / `expire` / `cancel` / `retire` helpers — direct status assignment bypasses the invariant checks. Idempotency: see the natural-key Gotcha.
@@ -34,11 +34,16 @@ language for end users and update them when a recipe's fields change. See
 See [payment allocation integrity](agents/payment-allocations.md) for atomic splits,
 retry identity, parent corrections and supported dialects.
 See [tax codes](agents/tax-codes.md) for tenant-owned rate components, default codes,
-and legacy-rate migration.
-See [document money persistence](agents/document-money.md) for the per-tenant
-legacy/v2 gate, atomic aggregate writes, issued snapshots, and frozen fields.
+and the standard codes every tenant gets.
+See [document money persistence](agents/document-money.md) for the one money
+model: tax-code resolution, atomic aggregate writes, issued snapshots, and
+frozen fields. Every Invoice and Contract money write needs a tenant. Host
+bootstrap is `ensureCommerceTenant(db, tenantId, { cookbook })`, which returns
+`{ tenantId }`. Money data written by an earlier version is refused with
+`COMMERCE_DATA_NEEDS_UPGRADE` until `smrt db:upgrade-commerce-money` converts
+it; see [money data upgrade](agents/money-upgrade.md).
 See [Contract money persistence](agents/contract-money.md) for the Contract
-aggregate, purchase recoverability, and migration-only materialization boundary.
+aggregate and purchase recoverability.
 
 ## Ledger Integration
 
@@ -128,8 +133,14 @@ for usage.
   `WRITTEN_OFF` (a later payment, by card or on a rail (#3188), is recorded
   and reinstates the payer; the status stays, so "paid in full" for a
   written-off invoice is read from its allocations).
-- **`Invoice.providerTaxAmount`** is added to line-item tax; it is
-  server-managed (not API-writable). `toAccountingInput()` emits major units.
+- **Billing invoices are money-model invoices.** The provider taxes them
+  (`providerTaxAmount`, server-managed, not API-writable, added to line tax),
+  so every billing line is an explicit `taxMode: 'override'` to the seller's
+  `out-of-scope` code. Charges are written before credits so the running
+  subtotal never goes negative, and provider tax is written in the save that
+  issues the invoice. Revenue posting is idempotent. `ledger.bookCurrency` is
+  required (ISO 4217, validated by `BillingRuntime`) and must equal the
+  billing currency. `toAccountingInput({ mapping })` emits major units.
 - **Payment rails (#3138).** A runtime has one issuing `provider` and any
   number of `paymentProviders` (unique names, one inbox namespace each; a
   provider with `capabilities.issuesInvoices === false` can never issue).
@@ -167,11 +178,13 @@ for usage.
 ## Gotchas
 
 - **Optional tenancy**: all models `@TenantScoped({ mode: 'optional' })` + nullable tenantId
-- **Money units and arithmetic**: money fields use signed integer minor units; rates and quantities remain decimal where their contracts require them. Exact rounding, tax-code resolution, legacy adapters, safe-integer validation, and journal units are defined in the [commercial money model](agents/money-model.md) and [money calculator](agents/money-calculator.md). Do not reintroduce floating-point tolerances on money paths.
-- **Tenant money migration**: the [tenant line-amount migration](agents/line-amount-migration.md) is authoritative for preflight, the durable journal, tenant barrier, marker activation, issued snapshots, verification, and checksum-guarded rollback. It is distinct from the compatibility behavior described in [document money](agents/document-money.md).
-- **Asset-native amounts stay outside line migration**: `Payment.nativeAmount` and `PaymentIntent.paymentOptions[].nativeAmount` are per-asset values identified by `nativeCurrency`; normalize each asset to its own minor unit before any type conversion, and never apply the commerce ×100 line-money rescale to them.
+- **Money units and arithmetic**: money fields use signed integer minor units; rates and quantities remain decimal where their contracts require them. Exact rounding, tax-code resolution, safe-integer validation, and journal units are defined in the [commercial money model](agents/money-model.md) and [money calculator](agents/money-calculator.md). Do not reintroduce floating-point tolerances on money paths.
+- **Money documents need a tenant**: models are optionally tenant-scoped, but every Invoice and Contract money write requires one (`MoneyValidationError` `INVALID_MONEY_INPUT`, `Commerce money documents require a tenant`).
+- **Earlier-version money data is refused**: never add a read or conversion path for it. Detection and the one-shot upgrade are in [money data upgrade](agents/money-upgrade.md).
+- **Book currency is required**: `recognizeRevenue()` and `cancelWithRevenueReversal()` take a required `bookCurrency`, which must equal the invoice currency.
+- **Asset-native amounts stay outside line rescales**: `Payment.nativeAmount` and `PaymentIntent.paymentOptions[].nativeAmount` are per-asset values identified by `nativeCurrency`; normalize each asset to its own minor unit before any type conversion, and never apply the commerce ×100 line-money rescale to them.
 - **Invoice controls payment status**: not the Payment model — use `Invoice.updatePaymentStatus()`
-- **Tax rate is external**: no tax rate field on Invoice — rate must be calculated externally
+- **Tax comes from tax codes**: the server resolves each line's code and computes line tax and header totals; client totals and a line's stored `taxRate` are never inputs
 - **Profile linking**: separate `ProfileCollection.create()` needed to fetch actual Profile object
 - **PaymentIntent natural key**: `conflictColumns: ['tenant_id', 'offering_ref', 'licensee_email', 'idempotency_key']` — a retried `create` with the same tuple upserts the existing row. Use `PaymentIntentCollection.getOrCreateByIdempotencyKey()` to branch on `{ intent, created }`. Empty natural-key inputs (e.g. blank `idempotencyKey`) disable dedup by design.
 - **Payout state-machine guards**: `markSent` requires a non-empty `backendTxRef`; `markConfirmed` only valid from `SENT`; `markFailed` only valid from `PENDING` / `SENT` (a confirmed payout can't fail — that path is a refund). `resetFromFailed()` is the dedicated escape hatch from `FAILED` back to `PENDING` after an operator fixes the underlying problem; it clears `backendTxRef` so the next attempt picks up a fresh one.

package/README.md

@@ -11,70 +11,80 @@ pnpm add @happyvertical/smrt-commerce
 ## Usage
 
 ```typescript
+import { withTenant } from '@happyvertical/smrt-tenancy';
 import {
-  Customer, CustomerCollection,
-  Order, ContractCollection,
-  Invoice, InvoiceCollection,
-  Payment, PaymentCollection,
-  ContractStatus, InvoiceStatus, PaymentMethod
+  CustomerCollection,
+  ContractCollection,
+  InvoiceCollection,
+  InvoiceLineItemCollection,
+  PaymentCollection,
+  PaymentMethod,
+  ensureCommerceTenant,
 } from '@happyvertical/smrt-commerce';
 
-// Create a customer linked to a profile
-const customers = await CustomerCollection.create({ db });
-const customer = await customers.create({
-  profileId: 'profile-uuid',
-  creditLimit: 1000000, // $10,000.00 — money is integer minor units
-  paymentTerms: 'Net 30',
-});
-await customer.save();
-
-// Create an order (STI contract type)
-const contracts = await ContractCollection.create({ db });
-const order = await contracts.create({
-  _meta_type: 'Order',
-  customerId: customer.id,
-  subtotal: 100000, // $1,000.00
-  taxAmount: 5000, // $50.00
-  totalAmount: 105000, // $1,050.00
-  currency: 'CAD',
-});
-await order.save();
-
-// Create an invoice for the order
-const invoices = await InvoiceCollection.create({ db });
-const invoiceNumber = await invoices.generateInvoiceNumber();
-const invoice = await invoices.create({
-  customerId: customer.id,
-  contractId: order.id,
-  invoiceNumber,
-  subtotal: 100000, // $1,000.00
-  taxAmount: 5000, // $50.00
-  totalAmount: 105000, // $1,050.00
-});
-await invoice.save();
-
-// Recognize revenue (creates balanced journal in smrt-ledgers)
-await invoice.recognizeRevenue({
-  arAccountId: 'ar-account-id',
-  revenueAccountId: 'revenue-account-id',
-  taxAccountId: 'tax-account-id',
-});
-
-// Record a payment
-const payments = await PaymentCollection.create({ db });
-const payment = await payments.create({
-  contractId: order.id,
-  customerId: customer.id,
-  amount: 105000,
-  method: PaymentMethod.CREDIT_CARD,
-});
-await payment.save();
-
-// Record payment with ledger integration
-await payment.recordPayment({
-  ledgerId: 'ledger-id',
-  receivablesAccountId: 'ar-account-id',
-  cashAccountId: 'bank-account-id',
+// Once per tenant, after the host creates it: tax settings and standard codes.
+await ensureCommerceTenant(db, tenantId);
+
+// Money documents (invoices, contracts, and their lines) belong to a tenant.
+await withTenant({ tenantId }, async () => {
+  // Create a customer linked to a profile
+  const customers = await CustomerCollection.create({ db });
+  const customer = await customers.create({
+    profileId: 'profile-uuid',
+    creditLimit: 1000000, // $10,000.00 — money is integer minor units
+    paymentTerms: 'Net 30',
+  });
+
+  // Create an order (STI contract type)
+  const contracts = await ContractCollection.create({ db });
+  const order = await contracts.create({
+    _meta_type: 'Order',
+    customerId: customer.id,
+    currency: 'CAD',
+  });
+
+  // Create an invoice. The server resolves each line's tax code and computes
+  // line tax and the header totals; header amounts are never inputs.
+  const invoices = await InvoiceCollection.create({ db });
+  const invoice = await invoices.create({
+    customerId: customer.id,
+    contractId: order.id,
+    invoiceNumber: await invoices.generateInvoiceNumber(),
+    currency: 'CAD',
+  });
+  const lines = await InvoiceLineItemCollection.create({ db });
+  await lines.create({
+    invoiceId: invoice.id,
+    description: 'Consulting',
+    quantity: 10,
+    unitPrice: 10000, // $100.00
+  });
+
+  // Issuing freezes the money snapshot; then recognize revenue (creates a
+  // balanced journal in smrt-ledgers from the frozen facts).
+  const issued = await invoices.get({ id: invoice.id }, { cache: false });
+  issued.markSent();
+  await issued.save();
+  await issued.recognizeRevenue({
+    arAccountId: 'ar-account-id',
+    revenueAccountId: 'revenue-account-id',
+    taxAccountId: 'tax-account-id',
+    bookCurrency: 'CAD', // must equal the invoice currency
+  });
+
+  // Record a payment with ledger integration
+  const payments = await PaymentCollection.create({ db });
+  const payment = await payments.create({
+    contractId: order.id,
+    customerId: customer.id,
+    amount: issued.totalAmount,
+    method: PaymentMethod.CREDIT_CARD,
+  });
+  await payment.recordPayment({
+    ledgerId: 'ledger-id',
+    receivablesAccountId: 'ar-account-id',
+    cashAccountId: 'bank-account-id',
+  });
 });
 ```
 
@@ -104,7 +114,7 @@ const totals = calculateMoneyDocument({
 ```
 
 `resolveLineTaxCode()` resolves caller-loaded codes without I/O, and the
-Svelte `InvoiceEditor` opts into the v2 money controls through its `money`
+Svelte `InvoiceEditor` renders the money controls from its required `money`
 prop. Frozen editor documents render a supplied stored snapshot without
 recalculation. See the [commerce money calculator guide](../../docs/content/commerce-money.md)
 for pricing modes, rounding, input and result types, the native-form editor
@@ -119,40 +129,68 @@ one settings row per tenant supplies sales/purchase defaults, amount mode,
 rounding scope, and labelled registration numbers. A referenced component rate
 is immutable: archive it and create a replacement for a rate change.
 
-`ensureTenantTaxCodes(db, tenantId)` idempotently creates the baseline
-non-taxable codes. `applyTaxCodeExamplePack(db, tenantId)` installs illustrative
+`ensureTenantTaxCodes(db, tenantId)` idempotently creates the standard
+non-taxable codes, `exempt`, `zero-rated`, and `out-of-scope`
+(`STANDARD_TAX_CODES`). `applyTaxCodeExamplePack(db, tenantId)` installs illustrative
 regional examples for review, and `applyCommerceCookbookSettings(db, tenantId,
 cookbook)` explicitly materializes a validated cookbook's defaults after schema
 setup and authentication establish the tenant. See the [commerce money
 calculator guide](../../docs/content/commerce-money.md#tenant-tax-catalogue) for
 the supported kinds, seed behavior, and cookbook rate units.
 
-### Persisted Invoice v2
+### Persisted Invoice money
 
-The public `Invoice` and `InvoiceLineItem` save paths use the server-owned
-`TaxSettings.moneyModel` gate. Missing settings and `legacy` preserve the
-existing behavior; `migrating` rejects Invoice money writes; `v2` atomically
-recalculates the draft Invoice aggregate from its lines and current tax inputs.
-The marker is not writable through generated surfaces or ordinary saves of
-an existing settings row.
+Commerce has one money model. Tax codes resolve each line's tax: the line's
+override, else `exempt` for an exempt customer, else the product's code, the
+customer's code, then the tenant default. The server computes line
+`taxAmount` and the header totals and ignores any client total. Every Invoice
+and Contract money write needs a tenant; without one it fails with
+`MoneyValidationError` `INVALID_MONEY_INPUT`.
+`ensureCommerceTenant(db, tenantId, { cookbook })` is the one bootstrap call a
+host makes after creating a tenant. It seeds the tenant's tax settings, the
+standard codes, and the cookbook's defaults, and returns `{ tenantId }`.
 
 Issuing an Invoice (leaving `DRAFT`) or assigning `arJournalId` freezes its
 money snapshot. Header and line money changes then fail with `FROZEN_DOCUMENT`,
 while later lifecycle and payment updates retain the snapshot. Provider tax
 stays separate in `providerTaxAmount` and contributes to the Invoice headers
-without creating an application tax code. In v2,
+without creating an application tax code.
 `InvoiceLineItemCollection.getTotalForInvoice()` sums line amounts for
-compatibility; use persisted `Invoice.totalAmount` for the amount due. The
+compatibility; use persisted `Invoice.totalAmount` for the amount due.
+`recognizeRevenue()` and `cancelWithRevenueReversal()` require a `bookCurrency`
+equal to the invoice currency, and `toAccountingInput({ mapping })` requires
+explicit QuickBooks realm mapping. The
 [commerce money calculator guide](../../docs/content/commerce-money.md#persisted-invoice-money)
-and [document-money contract](agents/document-money.md) cover persisted Invoice-v2
+and [document-money contract](agents/document-money.md) cover persisted Invoice
 semantics, credits, refunds, and posting. The materialized Invoice tax-report
 descriptor and tenant-safe drilldown are documented in
-[tax-summary contract](agents/tax-summary.md). Tenant migration commands,
-Contract money persistence, PurchaseContract tax contributors, and the
-materialized tax-summary host and drilldown are available. Applications opt in
-by registering `createTaxSummaryMaterializedReportHost()` in their server-only
-report-host registry; the route binds the authenticated tenant and read
-permission. See the tax-summary contract for registration and migration details.
+[tax-summary contract](agents/tax-summary.md). Contract money persistence,
+PurchaseContract tax contributors, and the materialized tax-summary host and
+drilldown are available. Applications opt in by registering
+`createTaxSummaryMaterializedReportHost()` in their server-only report-host
+registry; the route binds the authenticated tenant and read permission. See the
+tax-summary contract for registration details.
+
+### Upgrading money data from an earlier version
+
+Commerce refuses money data written by an earlier version with
+`COMMERCE_DATA_NEEDS_UPGRADE` instead of reading it. That is a schema that
+still has the earlier money columns or the `commerce_money_migration_documents` table,
+an invoice or contract without a tenant, or a tenant with invoices or contracts but no tax settings row or with
+documents in the earlier format. `smrt db:status`
+reports it, so `smrt app doctor` reports `migration-required`. Run the normal
+schema migration, then upgrade once:
+
+```sh
+smrt db:upgrade-commerce-money --check   # report only
+smrt db:upgrade-commerce-money           # every tenant
+```
+
+Each tenant converts in its own transaction. Stored rates become tax codes,
+issued documents keep every stored total, and drafts are recomputed. The
+earlier columns are dropped once no tenant needs the upgrade. See
+[money data upgrade](agents/money-upgrade.md) and the
+[CLI guide](../cli/agents/commerce-money-upgrade.md).
 
 ## API
 
@@ -318,6 +356,7 @@ const billing = await BillingRuntime.create({
   provider: createStripeBillingProvider({ stripe, webhookSecret }),
   billingRelationships, // smrt-tenancy BillingRelationshipService
   ledger: {
+    bookCurrency: 'USD', // ISO 4217; must equal the billing currency
     arAccountId,
     revenueAccountId,
     taxAccountId,
@@ -465,7 +504,13 @@ const evaluator = await SpendingPolicyEvaluator.create({
   upgrade (`<subscriptionId>:<periodStart>`, number 0) count as billed
   coverage, so nothing is billed again after it.
 - **Tax** comes from the provider (Stripe Tax) using the account customer's
-  `defaultBillingAddress`; the invoice records it as `providerTaxAmount`.
+  `defaultBillingAddress`; the invoice records it as `providerTaxAmount` in the
+  save that issues it. Billing invoices are ordinary money-model invoices in
+  the seller's tenant; period close seeds its standard codes if needed. Every
+  billing line is an explicit override to the seller's `out-of-scope` code, so
+  the seller's default code never taxes it a second time. Charges are written
+  before credits, so the running subtotal never goes negative. Revenue posting
+  uses `ledger.bookCurrency` and is idempotent.
 - **Events** are verified, stored in smrt-jobs' durable delivery inbox, and
   applied against current provider state: paid invoices record a payment and
   allocation; failures and overdue notices mark the payer `past_due` and its
@@ -751,14 +796,17 @@ The same models carry `@field({ ui: { widget } })` hints in the manifest:
 
 ## Invoice preparation UI
 
-`InvoiceLineEditor` and `InvoiceEditor` from `@happyvertical/smrt-commerce/svelte`
-provide editable descriptions/SKUs, fractional quantities, unit prices, flat or
-percentage discounts, explicit or inherited tax, customer, dates, currency and
-terms. Calculated previews use the same exact minor-unit arithmetic exported
-for server handlers from `@happyvertical/smrt-commerce/invoices`.
-`InvoiceAllocationFields` and `InvoiceReview` extend this foundation with
-caller-owned sources and approvals. See [the editor contract](agents/invoice-preparation.md),
-[calculation rules](agents/invoice-calculations.md), and the required
+`InvoiceEditor` from `@happyvertical/smrt-commerce/svelte` is the invoice form,
+built on the commercial money model, v2, which is the only invoice money model.
+It requires a `money` prop (`MoneyEditorProps`): a lossless draft with
+descriptions, fractional quantities, unit prices, percentage or amount
+discounts and a tax code per line (inherited or overridden), plus the
+authorized tax codes. Its previews run the same exact calculator the server
+uses, and the server re-resolves tax codes and recomputes every stored amount.
+An issued document renders only its frozen stored snapshot.
+`InvoiceAllocationFields` and `InvoiceReview` add caller-owned sources and
+approvals. See [the editor contract](agents/invoice-preparation.md), the
+[line calculation helper](agents/invoice-calculations.md), and the
 [existing-database storage migration](agents/invoice-quantity.md).
 
 ## Exact cost billing

package/agents/accounting-snapshot-mapper.md

@@ -4,9 +4,9 @@
 snapshot. `src/invoice-accounting-sync.ts` is the owning persistence and
 provider boundary. It re-reads the issued Invoice, InvoiceLineItem and
 DocumentTax rows and verifies their shared `moneySnapshotId` before calling the
-pure mapper. `Invoice.toAccountingInput()` keeps its legacy behavior for legacy
-tenants; a money-v2 tenant must supply explicit QuickBooks realm mapping and is
-routed through the frozen boundary.
+pure mapper. `Invoice.toAccountingInput({ mapping })` always requires explicit
+QuickBooks realm mapping and is routed through the frozen boundary; calling it
+without options throws `INVALID_MONEY_INPUT`.
 
 The released `@happyvertical/accounting` 0.103.7 path accepts frozen invoices
 and positive credit memos. Commerce sends persisted pre-discount unit price,

package/agents/commercial-ui.md

@@ -36,8 +36,8 @@ Do not mix currencies in totals or infer an unknown allocation as zero.
 
 The original invoice display DTOs in `src/svelte/types.ts` and their components
 accept decimal major-unit amounts. Preserve that published behavior. Applications
-adapting model amounts into those legacy components must explicitly convert units;
-do not pass a model's integer amount directly or silently change a legacy prop's
+adapting model amounts into those major-unit components must explicitly convert
+units; do not pass a model's integer amount directly or silently change a prop's
 meaning. New editor DTOs are separate contracts.
 
 Approved or otherwise retained invoice facts use the explicit `retained` display

package/agents/contract-money.md

@@ -2,9 +2,10 @@
 
 Contract money runs through `contract-money.ts`. A tenant operation enters
 `withTenantMoneyRuntime` before it locks and reloads its Contract and sibling
-lines on the scoped executor. The legacy barrier variants retain the old line
-calculation; only active v2 tenants resolve tax codes and replace the Contract
-aggregate plus `DocumentTax` rows in the same transaction.
+lines on the scoped executor, resolves tax codes, and replaces the Contract
+aggregate plus `DocumentTax` rows in the same transaction. Every Contract money
+write needs a tenant, and a tenant whose data needs the upgrade is refused (see
+[money data upgrade](money-upgrade.md)).
 
 Draft Contract line writes recompute every sibling. `subtotal` is tax-exclusive
 net after discount, `taxAmount` is the component total, and `totalAmount` is
@@ -13,12 +14,8 @@ component says so. A Contract leaving draft snapshots registrations, party tax
 identity, per-line component amounts, and `moneySnapshotId`; later money edits
 are refused with `FROZEN_DOCUMENT`.
 
-`materializeContractMoneySnapshot` is migration-only. Its caller supplies the
-already transaction-bound migration owner executor; it verifies that owner,
-locks/reloads the Contract, and never starts a runtime transaction.
-
-`SupplierQuote` uses purchase defaults and recoverability, including during
-legacy-to-v2 migration. Non-draft quotes freeze just like other Contracts, but
-quote snapshots (including custom descendants) are excluded by their hydrated
-STI subtype, not the mutable `contractType` scalar, from report candidates and
-purchase tax facts. Awarding requires a separate PurchaseOrder.
+`SupplierQuote` uses purchase defaults and recoverability. Non-draft quotes
+freeze just like other Contracts, but quote snapshots (including custom
+descendants) are excluded by their hydrated STI subtype, not the mutable
+`contractType` scalar, from report candidates and purchase tax facts. Awarding
+requires a separate PurchaseOrder.

package/agents/cost-billing.md

@@ -3,13 +3,10 @@
 `@happyvertical/smrt-commerce/cost-billing` is an independent, transport-neutral
 entry point without model, server or Svelte dependencies. It does not persist,
 post, authorize, select a currency/jurisdiction, or implement credit-note lifecycle.
-Legacy Invoice calculations and editor defaults are unchanged by this entry
-point. In particular,
-`calculateInvoiceMinorLine` retains negative ties toward positive infinity; the
-new opt-in helpers use symmetric half-away-from-zero ties. Positive-only invoice
-editor validation remains distinct from these generic signed calculations. The
+It does not change Invoice calculations or the invoice editor; both use the
+commerce money calculator, whose ties also round half away from zero. The
 `roundingScope: 'invoice'` behavior in this guide is a standalone cost-billing
-convention; v2 document arithmetic uses `roundingScope: 'document'` and stores
+convention; document arithmetic uses `roundingScope: 'document'` and stores
 allocated tax facts. See the [commercial money model](money-model.md) and
 [money calculator](money-calculator.md).
 

package/agents/customer-vendor-ui.md

@@ -179,8 +179,7 @@ money-v2 fields (#4011): line `taxAmount`, `discountTotal` on Invoice and
 Contract, `Invoice.creditedAmount`, and `DocumentTax` `taxableMinor` /
 `taxMinor` / `recoverableMinor`; the test asserts every integer named
 `*Amount`, `*Total`, `*Minor` or `subtotal` on those models (and Contract's
-STI subtypes) is hinted. `legacyAmount` is `@internal` migration-rollback
-state, not a user-facing amount, and stays unhinted. Payout and Payment's
+STI subtypes) is hinted. Payout and Payment's
 native/USD drift amounts are not hinted: their currency is a payout rail or
 fixed USD, not the record's `currency`. The line-item FKs
 (`ContractLineItem.contractId`, `InvoiceLineItem.invoiceId`,

package/agents/document-money.md

@@ -1,28 +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, customer exemption (unless
-the line overrides), 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.
+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
@@ -69,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.
 
@@ -91,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.
@@ -103,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),
@@ -118,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.