@happyvertical/smrt-commerce 0.55.24 → 0.56.1

package/AGENTS.md

@@ -5,7 +5,7 @@ E-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, pay
 ## Models
 
 - **Customer** / **Vendor**: linked to Profile via string ID (not FK). `contacts` (JSON) is written via [`savePartyContacts()`](agents/customer-vendor-ui.md#contact-rows-3501). Customer has creditLimit, paymentTerms, customerType (DTC / WHOLESALE / RETAIL). Vendor has leadTimeDays, minimumOrder, and `payoutAddresses: Record<string, string>` — a flat map from payout-rail-qualified currency code (`USDC-base`, `BTC`, `USD-stripe`, ...) to destination string (EVM address, BTC address, Stripe Connect account id, IBAN). Use `getPayoutAddress(currency)` for a `Map.get`-style lookup; missing entries return `undefined` (caller decides skip-vs-error).
-- **Contract** (STI base → Estimate, Order, Lease, Agreement, PurchaseOrder, WholesaleOrder, ProductionOrder, Cart, LicenseSale): 9 contract types sharing one table. Carries `channelId` (open-ended string — `dtc-web`, `wholesale-b2b`, `pos-store-N`, etc.) so the same model serves DTC checkout, B2B portals, and POS.
+- **Contract**: concrete STI base. Abstract **SalesContract** owns `customerId`; **PurchaseContract** owns `vendorId`. `channelId` is open-ended. Before upgrade, run `preflightCommercePartyLinks(db)` and repair linked base rows, stray parties, and wrong-branch links. See [README](README.md).
 - **WholesaleOrder**: B2B order. Conventional pairing — customer has `customerType: 'wholesale'`, NET-30/60 terms, delivered via wholesale-portal channel.
 - **ProductionOrder**: manufacturing equivalent of a PurchaseOrder — commission your factory to make finished goods. Consumes raw materials per BOM (`@happyvertical/smrt-manufacturing`) and produces SKU stock (`@happyvertical/smrt-inventory`).
 - **Cart**: transient order-in-progress. Same shape as Order; the application promotes the row from `_meta_type: Cart` to `_meta_type: Order` at checkout instead of copying data between tables.
@@ -33,6 +33,12 @@ 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.
+See [Contract money persistence](agents/contract-money.md) for the Contract
+aggregate, purchase recoverability, and migration-only materialization boundary.
 
 ## Ledger Integration
 
@@ -150,6 +156,7 @@ for usage.
 ## Cross-Package References
 
 - `customerId` → `@foreignKey('Customer')` (hard reference within package)
+- `vendorId` → `@foreignKey('Vendor')` on PurchaseContract only
 - `profileId` → plain string to smrt-profiles
 - `arJournalId`, `revenueJournalId` → plain string to smrt-ledgers
 - `skuId` (on `PaymentIntent`, `LicenseSale`) → plain string to smrt-products
@@ -160,14 +167,9 @@ for usage.
 ## Gotchas
 
 - **Optional tenancy**: all models `@TenantScoped({ mode: 'optional' })` + nullable tenantId
-- **Currency is integer minor units** (cents, satoshis) — `$19.99` is `1999`, like affiliates. Money is exact, so money fields initialize `= 0`, never `= 0.0`: the integer literal is what maps them to INTEGER columns (BIGINT on fresh PostgreSQL/DuckDB databases). Writing a fractional major-unit value is the bug — the model rejects it via `assertIntegerMinorUnits` on `Invoice`/`Payment`/`PaymentAllocation`/`Payout`/`Contract` before the database sees it, because PostgreSQL would reject it with `22P02` while SQLite's affinity silently stores it. `pnpm --filter @happyvertical/smrt-commerce test:postgres` is the lane that holds the line (#2361, #2401, #2373).
-- **Rates are the opposite**: `InvoiceLineItem.taxRate` and `ContractLineItem.taxRate` are inherently fractional and must initialize `= 0.0`. INTEGER would truncate every rate to 0. `ContractLineItem.quantity` is decimal for the same reason (contracts price fractional hours/weight/bandwidth); `InvoiceLineItem.quantity` is also decimal (six fractional places); existing integer columns require the explicit [quantity migration](agents/invoice-quantity.md).
-- **Rounding happens where a rate meets money, and nowhere else**: `InvoiceLineItem` uses exact shared invoice arithmetic to round fractional quantity × price and then tax to minor units; `ContractLineItem.calculateAmount()` uses `Math.round()` for tax. Everything downstream is exact integer arithmetic, which is why **there are no `EPSILON` tolerances left on any money path** (#2401). `Invoice`, `PaymentAllocation`, `Payout` and `PaymentIntent` compare with `===` / `>` / `>=`. Do not reintroduce a tolerance: against integers it forgives a real one-cent discrepancy rather than float fuzz. (`FulfillmentLineItem`'s quantity epsilon is unrelated — quantities are genuinely decimal there.)
-- **Migrating an existing database to minor units**: `preflightCommerceMoneyMinorUnits(db)` reports, per column, whether it still holds major units and which rows would be rounded or exceed JavaScript's safe-integer range; `migrateCommerceMoneyToMinorUnits(db)` converts them. Both are exported from the package root. The rescale is idempotent via a `_smrt_backfills` marker, changes the column type in place on PostgreSQL/DuckDB (`ALTER … TYPE BIGINT USING round(col * 100)`), and on SQLite rescales values only — SQLite cannot alter a declared type in place, so those columns come back in `declaredTypeChangePending` and need the table-rebuild path (#2370).
-- **`Payment.nativeAmount` is NOT in that migration, and must not be.** Its minor unit is a property of the *row's asset*: satoshis on a BTC rail (×1e8), cents on a fiat or stablecoin rail (×1e2), in one column discriminated only by `nativeCurrency`. A blanket ×100 turns 0.00713 BTC into `1` instead of `713000` sats, and a round 0.01 BTC even passes the preflight's integrality check while being wrong by six orders of magnitude. Convert it in two deliberate steps — normalise each row to its own asset's minor units while the column is still floating-point, then `rescaleMoneyColumnsToMinorUnits(db, COMMERCE_NATIVE_UNIT_COLUMNS, { scale: 1, … })` for the type change. `COMMERCE_NATIVE_UNIT_COLUMNS` is exported with a worked example; step one is deliberately the deployment's to write, because only it knows which `nativeCurrency` values it has used.
-- **`PaymentIntent.paymentOptions[].nativeAmount` has the same per-asset problem inside a JSON column and is likewise not migrated.** An intent's price lock defaults to 15 minutes, so the supported answer is to let open intents expire and be re-quoted: an unconverted option fails the exact `!==` reconciliation against the payment that arrives, which is a loud failure rather than a silently mis-scaled quote.
-- **Range and existing deployments**: fresh PostgreSQL/DuckDB INTEGER columns are BIGINT, and the runtime rejects values outside JavaScript's safe-integer range rather than rounding them. Existing PostgreSQL `int4` columns do not self-repair; widen them through the explicit migration tracked in #2424.
-- **Journals posted from commerce carry minor units**: `Payment.recordPayment()` and `Invoice.recognizeRevenue()` write `amount` / `totalAmount` straight into smrt-ledgers entries. smrt-ledgers is unit-agnostic (its `BALANCE_EPSILON` only checks debits === credits), and integer entries balance exactly, so this is strictly tighter than the major-unit journals commerce used to post.
+- **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.
 - **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
 - **Profile linking**: separate `ProfileCollection.create()` needed to fetch actual Profile object

package/README.md

@@ -78,15 +78,127 @@ await payment.recordPayment({
 });
 ```
 
+## Commercial money calculator
+
+The public `/money` entry is a pure calculator for line amounts, discounts,
+component tax, document rounding, and totals. It consumes and returns integer
+minor-unit money values; tax and discount percentages are exact text (`'5'`
+means 5%). It does not persist or load documents.
+
+```ts
+import { calculateMoneyDocument } from '@happyvertical/smrt-commerce/money';
+
+const totals = calculateMoneyDocument({
+  currency: 'CAD',
+  lineAmountType: 'exclusive',
+  roundingScope: 'line',
+  lines: [{
+    id: 'consulting', quantity: 1, unitPrice: 10000,
+    discount: { kind: 'none' },
+    taxCode: {
+      id: 'gst', kind: 'taxable',
+      components: [{ taxComponentId: 'gst', percent: '5', compound: false }],
+    },
+  }],
+});
+```
+
+`resolveLineTaxCode()` resolves caller-loaded codes without I/O, and the
+Svelte `InvoiceEditor` opts into the v2 money controls through its `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
+contract, and the boundaries this package does not define.
+
+### Tenant tax catalogue and defaults
+
+The package root also exports tenant-scoped `TaxComponent`, `TaxCode`, and
+`TaxSettings` models and their collections. Components hold exact percentage
+rates and optional liability accounts; codes combine compatible components; the
+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
+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
+
+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.
+
+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,
+`InvoiceLineItemCollection.getTotalForInvoice()` sums line amounts for
+compatibility; use persisted `Invoice.totalAmount` for the amount due. 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
+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.
+
 ## API
 
 ### Models
 
+#### Upgrading contract parties (#3898)
+
+`Contract` no longer declares `customerId` or `vendorId`. Narrow a contract to
+`SalesContract` to read `customerId`, or to `PurchaseContract` to read `vendorId`.
+The nine leaf qualified names and the `contracts` table stay the same; a
+`db:migrate --dry-run` against a v0.55.19 schema reports no DDL changes on
+SQLite or PostgreSQL. Sales leaves no longer accept `vendorId`; purchase leaves
+no longer accept `customerId`. `Order`, `Estimate`, `Agreement`, `Lease`, and
+`WholesaleOrder` require a customer on save. `PurchaseOrder` requires a vendor.
+`Cart`, `LicenseSale`, and `ProductionOrder` retain optional parties on their side.
+
+Before upgrading existing data, run the read-only
+`preflightCommercePartyLinks(db)` and inspect its stray party links, missing
+required parties, base-typed rows, discriminator mismatches, and invalid
+document references. Its `unqualifiedDiscriminatorRows` lists legacy simple
+`_meta_type` values such as `Order` and `PurchaseOrder`; retype them to the
+qualified class name before upgrading, since branch collections cannot read
+them. The report checks invoice, payment, fulfillment, ad group,
+and expense links when those tables exist. A linked base-typed or wrong-branch
+contract blocks the next save of its document even when the link is unchanged.
+Registered custom descendants of either contract branch are accepted in link
+checks; load those model classes before running the preflight.
+Tenant-owned documents linked to global or other-tenant contracts are also
+reported because the save-time lookup is tenant-scoped. Retype the contract to
+the correct leaf, assign it to the document's tenant, or repair the link before
+deployment. The deprecated `ContractCollection` party finders now return the
+appropriate branch
+only, so retype legacy base rows with party links before relying on those
+finders. Clear stray party columns and fill required parties before deploying
+writers that save affected rows. Missing required parties remain readable but
+fail their next save. Regenerate cached manifests, planner catalogs, and
+generated screens after upgrading.
+This preflight never edits rows; an operator chooses the data correction.
+
 | Export | Description |
 |--------|------------|
 | `Customer` | Customer record with creditLimit, paymentTerms, tax exemption, addresses, contacts |
 | `Vendor` | Vendor/supplier with leadTimeDays, minimumOrderAmount, currency, contacts |
 | `Contract` | STI base class for all commercial agreements |
+| `SalesContract` | Abstract customer-side Contract branch; owns `customerId` |
+| `PurchaseContract` | Abstract supplier-side Contract branch; owns `vendorId` |
 | `Estimate` | Quote or proposal sent to a customer |
 | `Order` | Customer purchase order |
 | `Lease` | Rental or lease agreement |
@@ -105,7 +217,7 @@ await payment.recordPayment({
 
 ### Collections
 
-`CustomerCollection`, `VendorCollection`, `ContractCollection`, `InvoiceCollection`, `InvoiceLineItemCollection`, `PaymentCollection`, `PaymentAllocationCollection`, `FulfillmentCollection`
+`CustomerCollection`, `VendorCollection`, `ContractCollection`, `SalesContractCollection`, `PurchaseContractCollection`, `InvoiceCollection`, `InvoiceLineItemCollection`, `PaymentCollection`, `PaymentAllocationCollection`, `FulfillmentCollection`
 
 `PaymentAllocationCollection.allocatePayment()` splits a payment across invoices
 in one transaction using stable allocation IDs for retries. Direct allocation
@@ -118,7 +230,7 @@ replay, parent revision refresh and compatibility requirements.
 
 | Export | Values |
 |--------|--------|
-| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `purchase_order` |
+| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `purchase_order`, `wholesale_order`, `production_order`, `cart`, `license_sale` |
 | `ContractStatus` | `draft`, `sent`, `accepted`, `declined`, `completed`, `cancelled` |
 | `CustomerStatus` | `active`, `inactive`, `suspended` |
 | `VendorStatus` | `active`, `inactive`, `suspended` |

package/agents/accounting-snapshot-mapper.md

@@ -0,0 +1,111 @@
+# Frozen commerce snapshot → accounting SDK mapper
+
+`src/accounting-snapshot.ts` is the pure adapter for an approved commerce money
+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.
+
+The released `@happyvertical/accounting` 0.103.7 path accepts frozen invoices
+and positive credit memos. Commerce sends persisted pre-discount unit price,
+line discount, net amount, allocated tax, and inclusive gross amount through
+the SDK's public input types. It never sends a numeric `taxRate`; every taxable
+line has explicit Item, TaxCode, and component TaxRate references. Exempt and
+out-of-scope lines carry no fabricated components. No dependency override or
+private SDK import is used.
+
+The caller supplies persisted document and line facts: document mode and
+rounding scope, integer-minor header totals, line pre-discount unit price and
+discount, post-discount net amount, and each component's ID, exact percent text,
+and allocated minor tax amount. The mapper converts only ISO 4217 minor units
+to major units. It never calculates a discount, tax, rate, or allocation. For
+an inclusive line, `taxInclusiveAmount` is the exact sum of the persisted net
+and persisted tax facts, so the SDK can serialize QBO `TaxInclusiveAmt`.
+
+`FrozenQuickBooksTaxMapping` is tenant/realm configuration and must supply an
+Item.Id and TaxCode.Id for every line plus a TaxRate.Id for every stored
+component. The mapper refuses missing mappings and never derives a provider ID
+from a tax-code name, percent, or component identifier. It also refuses a
+nonzero `providerTaxMinor`: header-only provider tax has no frozen component or
+rate reference and cannot safely become a QBO tax line.
+
+The mapper checks only snapshot identities before any provider I/O: each line's
+component sum equals its stored tax, lines sum to header net/tax, and header net
+plus tax equals total. `taxRoundingScope` is retained as frozen provenance; no
+rounding is repeated. Currency exponents come from the shared ISO map, so JPY
+and KWD retain their exact stored values.
+
+Credit memos use positive input values and require `creditedInvoiceExternalId`.
+Their provider direction is the SDK's `CreditMemo` operation. The owning sync
+boundary calls the public `requireCreditMemoOperations()` capability guard
+before persisting an in-flight owner, prepares and persists the SDK's
+`quickbooksCreditMemoRequest`, then records the returned external ID. The
+source invoice must have a reconciled QuickBooks identity in the same realm and
+environment. The adapter never auto-applies a credit memo to its invoice.
+
+## Sync identity and recovery
+
+`syncFrozenInvoiceToAccounting()` derives a QuickBooks request identity from
+the provider, realm, environment, document id, and immutable
+`moneySnapshotId`. The SDK forwards the persisted `requestId` as QuickBooks'
+`requestid` parameter and validates the payload hash. Commerce persists an
+`in_flight` owner before provider I/O, so a competing call is refused instead
+of issuing a second create. A successful call persists the external id and a
+`synced` state; another call for the same identity returns `unchanged` without
+provider I/O. A different realm, environment, provider, or snapshot never
+shares that no-op.
+
+The database transaction and provider request are separate phases. Commerce
+does not claim they are atomic. If the provider outcome or the post-write local
+commit is uncertain, the stored state requires reconciliation and refuses a
+blind retry. A provider rejection known not to have committed may be retried
+with the same prepared request. `readFrozenAccountingSyncState()` exposes the
+request descriptor needed by an operator-owned reconciliation workflow.
+
+Recovery is an explicit application flow rather than a database repair:
+
+1. Load the invoice and call `readFrozenAccountingSyncState()`.
+2. Use its realm, environment, `requestId`, and payload hash to query the
+   configured QuickBooks realm. An absence result does not establish that an
+   active request has stopped. For `in_flight`, first terminate or otherwise
+   positively establish that the original process/request owner cannot finish.
+3. Call `reconcileFrozenInvoiceAccountingSync()` with that same request ID,
+   attempt ID, and mapping. Report `found` with the provider document ID and
+   observed timestamp, or report `absent` only after QuickBooks authoritatively
+   confirms no create.
+4. A `found` result records the sync and makes later calls no-ops. An `absent`
+   result returns `ready`; the next sync reuses the identical prepared request.
+
+The reconciliation API accepts both `unknown` and interrupted `in_flight`
+records so a process crash after the remote write cannot wedge the invoice.
+It rejects a changed snapshot, request, realm, environment, or mapping. It does
+not perform the remote lookup itself. A normal caller cannot reconcile an
+`in_flight` record; the trusted server caller must pass
+`confirmInterruptedOwnerStopped: true` after establishing quiescence. That flag
+is an explicit operational assertion, not a lease inferred from time or from a
+provider lookup. `unknown` records already have no live local owner and do not
+require it.
+
+## Deployment and capability boundary
+
+`Invoice.accountingSyncStateJson` is a sensitive, server-owned persistence
+field. It is excluded from public serialization and from the shared generated
+REST, MCP/Chat, and CLI writable allowlist. Deployments must apply the normal
+generated schema migration that adds `accounting_sync_state_json` before using
+this sync API. Runtime code never creates or alters schema.
+
+Signed adjustment lines remain a known acceptance gap. The commerce money model
+can persist signed adjustments inside a positive document, but the accounting
+SDK has no reviewed signed-line representation. The owning sync boundary
+therefore rejects them before state or provider mutation. Header-only provider
+tax is also refused because it has no persisted component identity or realm tax
+rate mapping. Inclusive documents, discounted lines, exempt lines, and positive
+credit memos use the released public SDK contract.
+
+The mapper's A/B fixtures are the commerce calculator's actual CAD goldens:
+example A is tax-exclusive and example B is tax-inclusive. Both cover line and
+document allocation; example B's document scope preserves line 3's allocated
+GST cent. Focused sync tests inspect the exact public SDK request inputs and
+persisted create descriptors without performing a provider network write.

package/agents/contract-money.md

@@ -0,0 +1,18 @@
+# Contract money persistence
+
+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.
+
+Draft Contract line writes recompute every sibling. `subtotal` is tax-exclusive
+net after discount, `taxAmount` is the component total, and `totalAmount` is
+their exact sum. Purchase component tax is recoverable only when the frozen
+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.

package/agents/cost-billing.md

@@ -3,10 +3,15 @@
 `@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.
-Existing Invoice calculations and editor defaults are unchanged. In particular,
+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.
+editor validation remains distinct from these generic signed calculations. The
+`roundingScope: 'invoice'` behavior in this guide is a standalone cost-billing
+convention; v2 document arithmetic uses `roundingScope: 'document'` and stores
+allocated tax facts. See the [commercial money model](money-model.md) and
+[money calculator](money-calculator.md).
 
 Call `resolveCostMarkup(overrides)` with caller-approved precedence, most specific
 first. Each item has `source`, optional `policy` and `version`, and optional

package/agents/document-money.md

@@ -0,0 +1,126 @@
+# 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.
+
+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
+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.
+
+The first transition away from `DRAFT`, or setting `arJournalId`, freezes the
+money document. The invoice and every line receive the same stable
+`moneySnapshotId`. Later payment and lifecycle saves keep that identity.
+That persisted snapshot identity remains the freeze authority if payment
+allocation changes move the lifecycle status back to `DRAFT`; it does not turn
+an issued document back into an editable money draft.
+Frozen fields include party/customer identity, currency, issue and due dates,
+document amount/rounding settings, seller and party tax snapshots, line
+description/SKU/product, quantity/pricing/discount modes, tax code and component
+snapshots, source period, revenue account, and sort order. Header and child
+money edits, child moves, additions, and deletions then fail with
+`FROZEN_DOCUMENT`; status, payment, reminder, and delivery metadata continue
+through their existing lifecycle guards.
+
+Credit notes reuse `Invoice` with `kind: 'credit_note'` and a frozen
+`creditedInvoiceId`; their `DocumentTax.documentType` is `credit_note`. Stored
+header amounts remain positive and posting/report direction comes from `kind`.
+A targeted credit line carries `creditedLineId` plus a server-derived frozen
+calculation basis. The credit document inherits and re-enforces its source
+`lineAmountType` and `taxRoundingScope`; later tenant defaults cannot reinterpret
+the frozen unit price or tax allocation. Quantity credits reuse the source price
+and allocate its frozen flat or percentage discount from cumulative credited
+quantity; this prevents repeated rounding from exceeding the source discount,
+and the final quantity receives its exact remaining discount. Amount credits use
+an explicit tax-exclusive magnitude and restore the source line sign. A quantity
+request is also bounded by tax-exclusive value already consumed through amount
+credits, so mixing the two bases cannot exceed the source line. Tax components,
+labels, rates, and accounts come from the issued source snapshot. When a request
+exhausts every remaining original line, the final line also receives the exact
+remaining document/component residual.
+Free-form goodwill lines require an explicit tax code and do not consume source
+line capacity.
+
+Issued credit notes reduce the source `getBalance()` and update its
+server-managed `creditedAmount` under the same locks. Refunds are positive
+`Payment` rows with `kind: 'refund'`, allocated only to credit notes; their
+available amount is the unapplied issued credit after source settlement and
+prior settled refunds. Incoming payments debit cash and credit receivables;
+refund journals reverse those sides.
+
+`previewInvoiceMoney({ db, tenantId, invoiceId, draft })` applies a proposed
+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.
+
+### 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
+are a direct projection of persisted minor-unit values and component snapshots;
+it does not resolve a code or recalculate tax.
+
+`InvoiceRecordScreen` from `@happyvertical/smrt-commerce/svelte` composes that
+projection with `RecordScreen.lineItemStoredTotals`, the released generic
+line-items widget contract. A host passes its own generic screen wiring and
+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
+a genuine unassigned zero-tax line. Optional `productId` and
+`revenueAccountId` are nullable UUID references so PostgreSQL never receives an
+empty-string sentinel.
+
+`DocumentTax` is derived and read-only. Its rows snapshot the code/component
+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
+`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),
+and posts provider tax to the fallback once. Non-taxable zero rows do not post.
+Every entry is an exact non-negative debit or credit in the invoice currency.
+The caller must supply its authoritative `bookCurrency`; commerce rejects a
+missing, unsupported, or different currency because ledgers has no book model.
+
+The revenue journal identity derives from the tenant, invoice, and stable
+`moneySnapshotId`. Creation, posting, and the invoice's `arJournalId` link share
+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
+`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.

package/agents/invoice-calculations.md

@@ -2,6 +2,11 @@
 
 `@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.
@@ -12,13 +17,18 @@ Trailing zeroes do not make an exact amount invalid: `100.00` JPY is 100 minor u
 
 ## 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. Default tax remains externally determined; this module is not a tax determination service. Caller-owned extension allocations, budget availability and approval evidence require their own server validation and are not part of line pricing.
+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
@@ -41,4 +51,6 @@ 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 API.
+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).

package/agents/line-amount-migration.md

@@ -0,0 +1,50 @@
+# Tenant line-amount migration
+
+The operational CLI entrypoints are documented in
+`@happyvertical/smrt-cli/agents/commerce-money-migration.md`. A CLI migration
+chooses and prints its owner UUID before the tenant is claimed, so a failure
+after the claim can be resumed with the exact same `--migration-id`; a
+different owner is rejected.
+
+`preflightCommerceLineAmounts(db, { tenantId?, out? })` is read-only. It does
+not create `TaxSettings`. Review its structured report (and optional explicit
+`jsonPath`/`csvPath`) before migration. `UNRECONCILED`, orphan or cross-tenant
+lines, missing tenancy, an ambiguous base Contract direction, and an
+`in_flight`/`unknown` accounting sync block the tenant before any marker or
+document mutation. Draft total changes also require `acceptDraftChanges`.
+
+`migrateCommerceLineAmounts(db, { tenantId, acceptDraftChanges?, migrationId? })`
+claims the tenant marker, maps legacy rates, and processes each document under
+the shared tenant barrier. A sensitive internal
+`MoneyMigrationDocument` record commits its checksummed pre-image before the
+document transaction. The applied transaction stores a checksummed post-image;
+an exact retry skips it, while any mismatch fails closed. Runtime reads and
+writes remain blocked until every issued document verifies and the marker is
+written `v2` last.
+
+Issued migration preserves every previously stored header field, timestamp,
+revision and journal link. The only header writes are the additive v2 snapshot
+columns `discount_total`, `line_amount_type`, `tax_rounding_scope`,
+`seller_tax_registrations_json`, `party_tax_id`, and `money_snapshot_id`.
+Issued legacy snapshots always record `line_amount_type=exclusive` and
+`tax_rounding_scope=line`, which describe the historical storage contract;
+current tenant defaults apply only when calculating new v2 drafts.
+Drafts are recomputed through the owning aggregate after their legacy rate is
+promoted to an explicit code override. When a tenant has both exempt and
+ordinary zero-rate history, migration selects the durable code from each
+document's linked customer: exempt customers remain `exempt`; other zero-rate
+documents remain `out-of-scope`.
+
+`rollbackCommerceLineAmounts(db, { tenantId, migrationId })` claims the tenant
+barrier and validates journal existence plus every current post-image in one
+transaction. Every current tenant invoice and contract must have a matching
+journal entry; an unjournaled header was created under v2 and makes rollback
+unsafe, so rollback refuses before changing the marker or document. Any other
+refusal before restoration begins also rolls the claim back, so the tenant
+remains on v2 and ordinary runtime reads stay available. Once restoration
+begins, each document commits separately under the same owner; an interruption
+leaves the marker in `migrating`, and retrying that owner skips durable
+`rolled_back` journal entries. Exact pre-images restore the header, lines,
+taxes, timestamps and revisions, then the marker returns to `legacy`.
+The journal is installed by normal schema migration and retained through the
+rollback window. Runtime code never creates its table.

package/agents/minor-unit-migration.md

@@ -0,0 +1,20 @@
+# Legacy 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.
+
+`preflightCommerceMoneyMinorUnits(db)` reports whether known commerce columns
+still contain major units, rows that would round, and values outside JavaScript
+safe-integer range. After reviewing its report, run
+`migrateCommerceMoneyToMinorUnits(db)`. The migration is idempotent through its
+`_smrt_backfills` marker. PostgreSQL and DuckDB change columns to `BIGINT` and
+rescale values; SQLite rescales values but reports its required declared-type
+table rebuild as `declaredTypeChangePending`.
+
+`Payment.nativeAmount` and `PaymentIntent.paymentOptions[].nativeAmount` are
+excluded. Their units depend on the row currency or asset (for example BTC
+satoshis), so a blanket ×100 is wrong. First normalize each value to its own
+asset's minor unit, then use `rescaleMoneyColumnsToMinorUnits()` with scale 1
+for `Payment.nativeAmount`. Let open payment intents expire and be re-quoted;
+their JSON options have no safe blanket conversion.