@happyvertical/smrt-commerce 0.56.1 → 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

@@ -1,6 +1,6 @@
 # @happyvertical/smrt-commerce
 
-Commerce models for the s-m-r-t framework. Covers customers, vendors, contracts (9 STI types), invoices with ledger integration, payments, and fulfillment tracking.
+Commerce models for the s-m-r-t framework. Covers customers, vendors, contracts (10 STI types), invoices with ledger integration, payments, and fulfillment tracking.
 
 ## Installation
 
@@ -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,54 +129,99 @@ 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
 
 ### Models
 
+#### Supplier quotations
+
+`SupplierQuote` extends `PurchaseContract`, requires `vendorId`, and has
+`ContractType.SUPPLIER_QUOTE`. Create it through `PurchaseContractCollection`
+(or `ContractCollection`) with `_meta_type:
+'@happyvertical/smrt-commerce:SupplierQuote'`. It inherits `expiryDate`,
+`reference`, `notes`, and `terms`; it has no customer relationship. Purchase
+branch reads include quotes and sales branch reads exclude them.
+
+Keep received quote revisions and shared quote identity in your application.
+Awarding a quote creates a separate `PurchaseOrder`; accepting or saving a
+quote never converts its identity into an order. Quotes use purchase-side
+money calculation and frozen snapshots, but never contribute incurred purchase
+tax to reports, regardless of status. Existing Estimate and PurchaseOrder
+report eligibility is unchanged.
+
 #### 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
+The existing 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.
+`WholesaleOrder` require a customer on save. `PurchaseOrder` and `SupplierQuote`
+require a vendor.
 `Cart`, `LicenseSale`, and `ProductionOrder` retain optional parties on their side.
 
 Before upgrading existing data, run the read-only
@@ -203,6 +258,7 @@ This preflight never edits rows; an operator chooses the data correction.
 | `Order` | Customer purchase order |
 | `Lease` | Rental or lease agreement |
 | `Agreement` | Service or maintenance agreement |
+| `SupplierQuote` | Quotation received from a vendor; distinct from an awarded purchase order |
 | `PurchaseOrder` | Order sent to a vendor/supplier |
 | `ContractLineItem` | Line item within a contract |
 | `Invoice` | Billing document with status lifecycle and ledger integration |
@@ -230,7 +286,7 @@ replay, parent revision refresh and compatibility requirements.
 
 | Export | Values |
 |--------|--------|
-| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `purchase_order`, `wholesale_order`, `production_order`, `cart`, `license_sale` |
+| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `supplier_quote`, `purchase_order`, `wholesale_order`, `production_order`, `cart`, `license_sale` |
 | `ContractStatus` | `draft`, `sent`, `accepted`, `declined`, `completed`, `cancelled` |
 | `CustomerStatus` | `active`, `inactive`, `suspended` |
 | `VendorStatus` | `active`, `inactive`, `suspended` |
@@ -300,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,
@@ -447,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
@@ -733,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,6 +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. 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

@@ -174,7 +174,12 @@ vitest.selects.config.ts` (also part of `pnpm test:ui`).
 Minor-unit amounts on Contract, Invoice, their line items, Payment,
 PaymentAllocation, `Customer.creditLimit` and `Vendor.minimumOrderAmount`
 carry `ui: { format: 'money' }` (#3718; `widget: 'currency'` stays the
-currency-code picker on the text `currency` field). Payout and Payment's
+currency-code picker on the text `currency` field). That includes the
+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. 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`,