@happyvertical/smrt-commerce 0.53.4 → 0.53.6

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**: line items on invoices.
+- **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).
 - **Payment** / **PaymentAllocation**: tracks payments against invoices. Status controlled by `Invoice.updatePaymentStatus()`, not Payment model. 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. Use `PaymentInstrumentCollection.setDefaultForCustomer()` to change the default so the single-default-per-customer invariant is enforced; generated create/update routes cannot write `isDefault` directly.
 - **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 via natural key `(tenant_id, offering_ref, licensee_email, idempotency_key)` and `PaymentIntentCollection.getOrCreateByIdempotencyKey()`.
@@ -146,8 +146,8 @@ for usage.
 
 - **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 an integer count.
-- **Rounding happens where a rate meets money, and nowhere else**: `InvoiceLineItem.getTaxAmount()` and `ContractLineItem.calculateAmount()` `Math.round()` the fractional product to whole minor units. 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.)
+- **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.
@@ -161,3 +161,19 @@ for usage.
 - **PaymentInstrument defaults**: `isDefault` is domain-managed, not API-writable. Call `setDefaultForCustomer(customerId, instrumentId)` so the target is validated and the customer's other instruments are cleared.
 - **LicenseSale immutability**: rights snapshot freezes on save-with-status-ACCEPTED. The captured snapshot lives in a module-scoped `WeakMap<LicenseSale, string>` so it doesn't interact with the schema or round-trip through `_meta_data`. Drafts (status != ACCEPTED) remain mutable. To "change" an issued license: `revoke()` it, then issue a new `LicenseSale` row.
 - **Vendor.payoutAddresses normalization**: the constructor accepts either a `Record<string, string>` or a pre-serialized JSON string. `initialize()` re-normalizes after the framework's option-override pass; `save()` re-normalizes defensively against direct field assignment. Non-string values inside the input map are silently dropped to preserve the typed invariant downstream.
+
+## Commercial UI
+
+See [commercial UI composition](agents/commercial-ui.md) for native form recovery, amount compatibility and backend ownership. Package-owned guides under `agents/` ship with the package.
+
+## Quote and estimate UI
+
+`src/svelte/quote-types.ts` separates unparsed draft strings from explicit
+minor-unit revision DTOs. Native row submitters, caller-owned retry identity and
+extension conventions are documented in [agents/quote-ui.md](agents/quote-ui.md).
+
+## Purchasing UI
+
+`PurchaseOrderEditor` preserves allocation IDs and explicit zeroes, including
+retained reduction rows; the server validates review fingerprints before recording.
+See [agents/purchasing-ui.md](agents/purchasing-ui.md) for caller responsibilities.

package/README.md

@@ -1,6 +1,6 @@
 # @happyvertical/smrt-commerce
 
-Commerce models for the s-m-r-t framework. Covers customers, vendors, contracts (5 STI types), invoices with ledger integration, payments, and fulfillment tracking.
+Commerce models for the s-m-r-t framework. Covers customers, vendors, contracts (9 STI types), invoices with ledger integration, payments, and fulfillment tracking.
 
 ## Installation
 
@@ -514,3 +514,31 @@ known limits.
 
 See [`AGENTS.md`](./AGENTS.md) for package architecture, invariants, validation,
 and contributor guidance.
+
+## Pricing version UI
+
+`PricingVersionSummary` and `PricingVersionDecision` compose the quote revision
+contract without adding a pricing ledger. Compare versions using
+`QuoteRevisionComparison`; the application owns every decision and native form
+action. See [pricing version presentation](agents/pricing-versions.md).
+
+## Commercial UI composition
+
+Customer addresses and vendor/quote currencies use the shared localized code
+selectors while preserving native field names and rejected raw drafts. See
+[commercial UI contracts and backend boundaries](agents/commercial-ui.md) for
+native forms, recovery, amount units and consumer adoption, plus the focused
+[customer/vendor](agents/customer-vendor-ui.md) and
+[quotation](agents/quote-ui.md) contracts for selector restrictions.
+
+## 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
+[existing-database storage migration](agents/invoice-quantity.md).

package/agents/commercial-ui.md

@@ -0,0 +1,78 @@
+# Commercial UI composition
+
+The commercial UI release is tracked in [#3423](https://github.com/happyvertical/smrt/issues/3423).
+Components compose the provider-free controls in `@happyvertical/smrt-ui/forms`
+and visual controls in `@happyvertical/smrt-ui`. They do not require SvelteKit,
+a database, or the top-level `smrt-svelte` integration package.
+
+## Native forms and recovery
+
+The application owns action URLs, HTTP methods, submitter names/values, field
+names, request identity, tenant context and returned validation errors. Native
+forms use the base `Form` with `preventDefault={false}`. Enhancement is optional;
+a handler that takes over submission is responsible for preventing navigation.
+
+A failed action returns the submitted strings, including invalid amounts and
+repeated fields, alongside errors. Components must not reconstruct these values
+from saved models or generate a replacement request token. Unknown commit outcomes
+retain the same identity and payload until the application resolves the result.
+File inputs cannot be repopulated after navigation: explain that the file must be
+selected again and retain the caller's recovery identity.
+
+The existing [form retry contract](../../../docs/content/form-retry.md) provides
+optional browser enhancement. It does not replace server-side tenant/actor checks
+or idempotency. Permission props control presentation only; applications must
+supply already-authorized data and reauthorize every submitted action.
+
+## Amounts and public compatibility
+
+New commercial editors use explicitly documented integer minor-unit amounts.
+Editable values remain strings until the owning server validates them; blank,
+invalid and zero are distinct. Currency and its display precision are explicit.
+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
+meaning. New editor DTOs are separate contracts.
+
+## Domain boundaries
+
+Customer and Vendor reference Profiles identity data. A consumer's Client record
+is not automatically a Commerce Customer; UI adoption performs no identity merge
+or persistence migration. Domain-specific contact fields, trades, project/package
+allocations and approval policies enter through typed adapters and extension slots.
+
+Quote/estimate preparation, customer acceptance, vendor award, expense review and
+invoice approval are separate decisions. A UI status or selection must never
+implicitly perform another transition. The server supplies current decision and
+source availability, including restricted-reader presentation.
+
+## Backend capability assessment
+
+Assessment baseline: SMRT `98c872be4` and reviewed DomaCraft epic-138
+`b03b322f75fbfdcb9193b18e73d3ec818ef18811`.
+
+| Responsibility | Existing capability | Release decision |
+| --- | --- | --- |
+| Commitment versus actual | `ExpenseCollection.commitmentPosition()` sums reviewed, non-duplicate expenses in the commitment currency, optionally per line. | Reuse Expenses; keep DomaCraft award lineage and package-cap constraints in its adapter. |
+| Receipt identity and duplicate review | `ExpenseReceiptCollection` owns receipt joins and duplicate detection; `Expense` owns guarded review transitions. | Reuse these contracts. Private upload authorization, draft capacity and storage compensation stay in application composition. |
+| Idempotent submission and uncertain outcomes | Core `runOnce()` and UI `createFormRetry()` provide shared server/browser primitives. | Preserve the caller's request identity. Do not replace DomaCraft's transaction-bound financial submission logic without proving equivalent transaction and recovery semantics. |
+| Invoice source reservations | DomaCraft `finance.ts` reserves its own cost allocations under project transaction locks; Commerce Invoice has no equivalent source-allocation contract. | Keep the reservation service local: extracting it changes a published financial contract and requires an agreed cross-domain source model. UI accepts supplied source availability. |
+| Source-change approval invalidation | DomaCraft `withdrawInvoiceApprovalForSource()` and invoice fingerprint checks bind project policy, actor decisions and retained sources. | Keep this policy local. Shared presentation renders server-supplied approval state and cannot authorize execution. |
+
+No generic backend redesign is required by these UI slices. A future extraction
+needs evidence that a contract works beyond the application-specific project and
+policy model; UI reuse alone does not establish that requirement.
+
+## Validation and consumer adoption
+
+Each slice covers its public exports, SSR/native payload, retained errors,
+read-only and empty states, keyboard operation and a 390px viewport. The release
+also validates the complete touched packages and integrated workbench. A browser
+viewport test does not establish physical-device camera behavior.
+
+DomaCraft adopts a published release through normal dependency admission. Its
+native financial, authorization, tenant and uncertain-outcome tests remain required;
+shared component tests do not establish those server-side properties.

package/agents/customer-vendor-ui.md

@@ -0,0 +1,76 @@
+# Customer and vendor UI
+
+Import the provider-free surfaces from `@happyvertical/smrt-commerce/svelte`:
+
+```svelte
+<script lang="ts">
+  import {
+    CustomerDirectory,
+    CustomerDetail,
+    CustomerForm,
+    VendorDirectory,
+    VendorDetail,
+    VendorForm,
+    type CustomerDisplayData,
+  } from '@happyvertical/smrt-commerce/svelte';
+
+  let { data, form } = $props();
+</script>
+
+<CustomerForm
+  mode="edit"
+  values={form?.values ?? data.values}
+  errors={form?.errors}
+  transport={{
+    action: '?/update',
+    method: 'post',
+    hiddenFields: {
+      requestId: form?.values.requestId ?? data.requestId,
+      expectedTenantId: data.tenantId,
+    },
+  }}
+  labels={{ singular: 'Client', plural: 'Clients' }}
+  cancelHref={`/clients/${data.customer.id}`}
+/>
+```
+
+The caller owns action URLs, server authorization, tenancy checks, request tokens, persistence, and retry behavior. Capability props only decide whether an affordance is rendered. The components never create a Profile, Customer, Vendor, or contact relationship and never generate request tokens.
+
+`CustomerDisplayData.creditLimitMinor` and `VendorDisplayData.minimumOrderMinor` are integer currency minor units. Detail components convert them only for display and accept an explicit `minorUnitExponent`. Form values deliberately use retained strings such as `1250.00`; the server validates and converts those major-unit strings to the model's integer minor units.
+
+`VendorFormValues.leadTimeDays` is also retained text. The control supplies a numeric keyboard hint without browser number-input sanitization, and the server must parse and validate the submitted non-negative integer.
+
+Forms use the provider-free `Form`, `Input`, `Select`, `Textarea`, and `Checkbox` controls from `@happyvertical/smrt-ui/forms`. They default to native `POST` submission through `preventDefault={false}`. `transport.hiddenFields`, `transport.intentName`, and the field-name maps let an application preserve its existing payload contract. Repeatable contact rows submit repeated field names in DOM order. Add and remove controls are native submitters, so they work without JavaScript; the server returns the revised rows and retained values.
+
+Customer shipping and billing addresses use the shared `CountrySelect` and
+`ProvinceSelect`. The native names remain `shippingCountry`, `shippingState`,
+`billingCountry`, and `billingState` unless `fieldNames` overrides them. Changing
+country changes the region control without clearing its current string; CA and US
+render localized subdivision choices, while unsupported countries render an
+editable text field. Unknown values remain selectable/postable after a failed
+submission. Use `countryOptions` or `provinceOptions` only when the caller must
+restrict the choices. `VendorForm` has no structured address fields in its public
+DTO and does not invent them.
+
+Vendor currency uses the shared `CurrencySelect`. The raw retained string remains
+the native `currency` payload, including unknown values returned after validation.
+Use `currencyOptions` for caller-authorized restrictions; omitted options use the
+shared currency catalog. Selector labels follow the active smrt-ui i18n locale.
+
+The forms place a non-focusable default save submitter before contact row actions so Enter in a text field cannot accidentally add or remove a contact. This remains in place when the `actions` snippet customizes the visible action bar; set `transport.saveIntent` to the custom save intent.
+
+Use the `extension` snippets for application fields such as construction roles and trades. Keep those fields and their policy in the application:
+
+```svelte
+<VendorForm values={data.values} transport={{ action: '?/save' }}>
+  {#snippet extension(values)}
+    <ConstructionVendorFields roles={values.roles} trades={values.trades} />
+  {/snippet}
+</VendorForm>
+```
+
+Directory entries carry caller-owned detail links and pagination links. Detail edit links and form submit buttons appear only when their capability props allow them; the server must still authorize every request.
+
+The registry keys are `customer-directory`, `customer-detail`, `customer-form`, `vendor-directory`, `vendor-detail`, `vendor-form`, and `party-contact-fields`. Interactive examples are published by `@happyvertical/smrt-commerce/playground` and ship in the next generated Commerce package release. DomaCraft can replace its local routes incrementally by adapting its existing server DTOs and payload names; no identity or database migration is required.
+
+The form playground previews handle save, add-contact, and remove-contact intents in memory. They deliberately return a simulated validation error on save so retained values and retry behavior can be inspected without a backend.

package/agents/invoice-calculations.md

@@ -0,0 +1,17 @@
+# General invoice calculations
+
+`@happyvertical/smrt-commerce/invoices` is a Svelte-free entry usable by server handlers and browsers. `calculateInvoiceLine`, `calculateInvoiceDraft`, and `resolveInvoiceLineDraft` share exact decimal arithmetic. The UI consumes these helpers for previews; preview results confer no authority.
+
+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 Commerce billing's explicit ISO exponent table (0/3/4 exceptions; other uppercase three-letter codes use 2); servers must authorize their supported currency set. No exchange conversion occurs. Rates are percentages from 0 through 100 with at most six fractional digits. `discountType` is `flat` or `percent`; `taxMode` is `inherit` or `override`. An override of `0` is zero tax; an empty override is invalid. Inherited lines ignore their dormant override string.
+
+Calculation order is quantity × price rounded half up to minor units, discount rounded half up and subtracted, then tax on the discounted subtotal rounded half up. Flat discounts cannot exceed gross. Numeric model quantities and rates use their canonical decimal representation (including supported exponent notation), never a `toFixed` expansion of binary approximation. No floating-point multiplication or epsilon comparison determines money. Unsafe individual or aggregate results are rejected; invalid lines produce errors without monetary totals. Header validation requires customer, real issue/due dates with due date not before issue date, valid currency shape/default rate, at least one line, and unique nonblank row keys.
+
+`resolveInvoiceLineDraft` returns the existing model's resolved integer-minor price, flat discount, fractional quantity, effective fractional tax rate, and calculated amount. It verifies exact agreement with model arithmetic. `InvoiceLineItem.applyEditorDraft()` retains the editing modes alongside resolved fields; `getEditorDraft(authorizedContext)` restores them only while current authority and fields agree. See [invoice quantity storage](invoice-quantity.md) for the required existing-database migration. `calculateInvoiceMinorLine` is the currency-independent model helper: it permits existing negative-price credit lines, retains their historical ties toward positive infinity, and rejects invalid quantities/rates or unsafe/fractional money.
+
+Trailing zeroes do not make an exact amount invalid: `100.00` JPY is 100 minor units, while `100.01` JPY is rejected. Parsing never rewrites the draft text.
+
+## Server responsibilities
+
+Parse native form values into the typed draft (never pass unvalidated arbitrary JSON as the typed object), enforce request/row limits, authorize customer and source references in the active tenant, and validate edits against invoice lifecycle state. Replace inherited rate/currency policy with server-authorized context, call the shared validator/resolver, and save resolved rows and invoice within the application's transaction/retry contract. Ignore any client-supplied calculated amount. 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.
+
+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.

package/agents/invoice-preparation.md

@@ -0,0 +1,86 @@
+# General invoice editor and allocation extensions
+
+Import `InvoiceEditor`, `InvoiceLineEditor`, `InvoiceAllocationFields`, `InvoiceReview`
+and their Props types from `@happyvertical/smrt-commerce/svelte`. `InvoiceEditor`
+is the general invoice form; `InvoiceLineEditor` and `InvoiceAllocationFields`
+render fields only and never nest a form. The interactive Commerce invoice preview
+shows general line items with an optional allocation extension.
+
+`InvoiceDraftValues` contains customerId, issuedOn, dueOn, currency, paymentTerms,
+taxRate and ordered lines. Each `InvoiceLineDraft` contains caller key, description,
+sku, fractional quantity, unitPrice, discountType, discountValue, taxMode and
+taxRate. Editable values are lossless strings, including invalid submitted input.
+Unit price and flat discount are currency-unit text; percentage values use `5`
+for five percent. `discountType` is `flat` or `percent`; `taxMode` is `inherit` or
+`override`. Explicit override `0` means zero tax; it never means inherit. Unknown
+modes remain representable for rejected submissions. Dates remain text so invalid
+values survive action failures. Customer options are caller-authorized projections;
+unknown retained IDs remain visible. Currency uses the shared CurrencySelect.
+
+See [server calculation and persistence semantics](invoice-calculations.md).
+
+`InvoiceLineEditor` also recalculates when used independently: it retains a local
+draft copy and calls optional `onchange(line)` with each edit. It never mutates
+the supplied line. Replacing the line prop applies caller/server response values.
+
+The UI invokes the exact, Svelte-free `calculateInvoiceDraft` and
+`calculateInvoiceLine` helpers for previews. The shared public calculation entry
+is `@happyvertical/smrt-commerce/invoices`. Valid totals use safe integer minor
+units, with exact decimal arithmetic and explicit currency precision. Invalid
+drafts show an unavailable-total message rather than plausible numbers. The
+calculator uses Commerce's explicit exponent table and its existing two-digit
+fallback for other uppercase three-letter codes; the server must authorize its
+supported currencies. Calculated values are never submitted as authority.
+The server revalidates customer/SKU, prices, quantity, discounts, tax policy,
+permissions and calculated totals. Header taxRate is a draft preview default,
+not a new persisted Invoice tax field; replace it with authorized tax context
+on the server. Client edits never establish approval or allocate inventory.
+
+```svelte
+<InvoiceEditor action="?/save" values={form?.values ?? data.values}
+  customers={data.authorizedCustomers} errors={form?.errors}
+  message={form?.message} canEdit={data.mayEdit}
+  hiddenFields={[{ name: 'requestId', value: form?.requestId ?? data.requestId }]}>
+  {#snippet children(current)}
+  <InvoiceAllocationFields currency={current.currency}
+    allocations={form?.allocations ?? data.allocations}
+    sources={data.authorizedSources} mayReadSources={data.mayReadSources}
+    canEdit={data.mayEdit} />
+  {/snippet}
+</InvoiceEditor>
+```
+
+Native header names default to customerId, issuedOn, dueOn, currency,
+paymentTerms, invoiceTaxRate. Repeated line names are lineKey, lineDescription,
+lineSku, lineQuantity, lineUnitPrice, lineDiscountType, lineDiscountValue,
+lineTaxMode and lineTaxRate, in displayed order. `fields` and `lineFields` adapt
+names. Caller `errors` use header names or `lineKey.fieldName` keys. Repeated
+hidden fields retain exact values. Avoid collisions with the component's names.
+
+Default submitter `intent` values are `save`, `addLine` and `removeLine:<key>`;
+`saveIntent`, `addIntent`, `removePrefix` and `fields.intent` adapt the contract.
+Save is first so implicit Enter cannot remove/add a row. Structural actions
+use formnovalidate, preserving every submitted draft string and request token.
+The caller returns updated rows for add/remove; it must not persist or rotate
+request identity simply because the user added a line. The default transport
+is native POST, including without JavaScript. With JavaScript, input changes
+update exact previews without mutating the supplied values object. `onsubmit`
+may enhance transport; caller-owned retryStatus/pending controls submission.
+
+Allocation fields remain optional application-specific composition. Each row
+has key, sourceId, currency-unit amount, optional remove and field errors.
+`mayReadSources=false` hides supplied labels/balances and renders references.
+Retained unavailable sources remain postable for server reconciliation. Native
+names remain sourceId/allocationAmount and checked zero-based removeRow;
+`fields` maps these, and addIntent defaults to addAllocation. Availability,
+reservations, budget policy and approval are caller/server concerns. The
+extension must receive the same canEdit/pending capability as its owner.
+
+`review` is a caller-supplied snapshot; edits do not infer status changes.
+Read-only disables fields and hides mutation buttons. On rejected, denied or
+uncertain actions, return every original string, stable row key, errors and
+caller request/tenant/fingerprint identity. No component generates request keys.
+
+Focused validation: Commerce `vitest.invoices.config.ts`,
+`e2e/invoices/playwright.config.ts`, `typecheck`, and `build`; consolidated
+release gates and calculator/model checks remain separate owning validations.

package/agents/invoice-quantity.md

@@ -0,0 +1,46 @@
+# Invoice quantity persistence and editor recovery
+
+InvoiceLineItem accepts nonnegative decimal quantities with at most six decimal
+places. The `1.0` default declares a floating-point quantity column. Unit price,
+flat discount, and calculated amount remain safe integer minor units. Save always
+validates resolved fields and recalculates amount; a supplied amount is never
+trusted. Gross quantity × price and then tax on discounted gross round to minor
+units, with ties toward positive infinity (including existing negative-price
+credit lines). Tax is a resolved fraction in [0, 1], with eight decimal places.
+Accounting export retains an explicit zero rate instead of omitting it.
+
+`applyEditorDraft(draft, authorizedContext)` resolves the shared invoice draft
+helper into description/SKU/quantity/price/flat discount/tax and stores cloned
+`invoiceEditorStateJson` TEXT, accessed through a guarded typed `invoiceEditorState` getter/setter. It does not save.
+`getEditorDraft(authorizedContext)` returns a clone only when currency, inherited
+tax authority, and all source fields still agree. Otherwise it returns null so the
+caller can reconstruct a flat-discount/explicit-tax editor from resolved fields.
+Normal save clears stale editor state and never derives money from metadata.
+All other object metadata, authorization, and transaction ownership are unchanged.
+
+## Existing integer columns
+
+Run a backup and pause invoice writers for this explicit migration. With a root
+database handle and its known engine (`sqlite`, `postgres`, or `duckdb`), call
+`preflightInvoiceEditorStorage(db, engine)`, resolve every reported invalid row,
+then `migrateInvoiceEditorStorage(db, engine)`. The preflight rejects negative,
+nonfinite, unsafe, excess-precision, and numerically non-roundtripping quantities.
+The migration uses a transaction (and a PostgreSQL writer lock) and never rescales
+or rounds stored values. PostgreSQL widens INTEGER/BIGINT to DOUBLE PRECISION;
+DuckDB widens to DOUBLE. Repeating it leaves an already widened declaration alone.
+An absent table is reported as absent and is never marked migrated.
+
+SQLite uses the public core table-rebuild planner to change the declaration to
+REAL while preserving existing columns, constraints, indexes, and triggers. If
+incoming foreign keys make that rebuild unsafe, the migration throws with the
+planner reason and rolls back; it does not disable constraints or lose children.
+Resolve that maintenance condition before deploying fractional writers. The same
+transaction adds the nullable TEXT `invoice_editor_state_json` column with an empty
+string default on every engine. This column is required for updated model saves.
+An existing floating quantity column still receives the missing state column.
+No schema mutation runs implicitly during runtime initialization or model save.
+
+The actual DuckDB quantity/storage migration is tested. Complete Commerce model
+persistence on DuckDB is currently unsupported because its hard foreign keys use
+ON UPDATE CASCADE, which DuckDB cannot preserve; the schema builder refuses that
+contract. SQLite and PostgreSQL exercise complete save/reload model behavior.

package/agents/pricing-versions.md

@@ -0,0 +1,28 @@
+# Pricing version presentation
+
+Import `PricingVersionSummary`, `PricingVersionDecision` and
+`QuoteRevisionComparison` from `@happyvertical/smrt-commerce/svelte`.
+`PricingVersionData` extends `QuoteRevision`: use the same explicit document kind,
+counterparty, currency, minor-unit scale and integer total. Optional `sources`
+retain authorized source labels, amounts and explanations in that currency.
+Compare versions with `QuoteRevisionComparison`; no second comparison algorithm
+or pricing ledger is introduced.
+
+`PricingVersionDecision` accepts an immutable `version`, native POST `action`,
+explicit `actions` (label/name/value and optional formAction/disabled), ordered
+`hiddenFields`, and retained `reason`/`error`. Pass every server-required version,
+fingerprint, request and tenant field through `hiddenFields`; displaying a version
+never creates or replaces those identities. Repeated hidden names remain repeated
+form entries. `reasonName` adapts to existing endpoints and `children` composes
+additional native fields. Native submission is the default; `onsubmit` can opt
+into enhancement. `readOnly` removes mutation controls; `busy` disables actions.
+Neither prop replaces authorization or server-side fingerprint checks.
+
+Applications must return current version/action availability with failed-action
+values and preserve the same request identity after an uncertain outcome. A
+source-change conflict requires fresh server review; this component never
+approves, awards work, accepts a budget, or changes a saved status on its own.
+
+The Commerce workbench pricing example composes comparison and decision controls
+and demonstrates value retention on a rejected preview action. Its actions are
+explicitly demonstrations and perform no financial writes.

package/agents/purchasing-ui.md

@@ -0,0 +1,82 @@
+# Purchasing and award presentation
+
+Public `@happyvertical/smrt-commerce/svelte` exports `PurchaseSourceSelector`,
+`PurchaseOrderEditor`, their Props and `Purchase*` DTOs. Registry slots are
+`purchase-source-selector` and `purchase-order-editor`. Interactive playground
+entries cover ordinary amendment and explicit retained-allocation reduction.
+
+These components use public Commerce PurchaseOrder/Contract as their owning
+financial domain without adding a backend command, ledger or fixed approval
+policy. The caller decides instrument options, source availability, allocation
+labels, prior commitments, reviewed actuals, floors/ceilings and exact source
+identity. Construction work packages, accepted budgets, contractor entitlement
+and vendor award policy stay in the consumer. Capability/disabled props only
+control presentation. Every POST needs authoritative server authorization.
+
+`PurchaseSourceSelector` uses a native GET to the supplied action with `name`
+(default `source`) and optional hidden search/context fields. It never writes an
+award. Disabled sources remain visible with caller notices; unknown saved IDs
+remain visible as unavailable. Keep source selection outside a reduction form;
+the server must reject a downward amendment under an ordinary amendment mode
+and enforce the retained source/instrument during reductions.
+
+`PurchaseOrderEditor` receives `operation` (`create`, `amend`, `reduce`), a
+retained `source`, `currency`, explicit `minorUnitDigits`, raw `values`,
+`instruments`, native POST `action`, and caller-owned `hiddenFields`. Supply
+source ID, currency, predecessor, tenant and retry IDs in those hidden fields
+under the exact names your endpoint expects. `names` adapts all built-in fields.
+`labels` adapts approval language; `extensions` and `attachments` compose domain
+fields and authorized Assets evidence without fetching bytes in this component.
+`formAttributes` supports native encoding/ID and caller-owned form-retry Svelte
+attachments; `onsubmit` supports caller transport enhancement. Tokens are never
+minted or rotated here. See the shared [form/action contract](commercial-ui.md)
+and repository `docs/content/form-retry.md`.
+
+All editable money is **raw major-unit text**, including malformed values and
+empty unknown amounts. The caller parses against the exact currency contract;
+there is no UI floating-point calculation or implicit blank-to-zero conversion.
+Saved/source/review numbers are safe integer minor units formatted by the
+shared quotation helper. `sourceMinor: null` renders Unknown. Displayed bounds
+are guidance; the server validates floors, ceilings and source eligibility.
+
+Every allocation posts its stable `id` and amount, even when zero. Mark every
+predecessor allocation `retained: true`. A `reduce` form requires those amounts
+explicitly and never offers their removal. Supplying fewer predecessor rows is
+not safe: the server must compare the complete ID set and reject omissions.
+Optional `rowActions` uses native formnovalidate add/remove POSTs carrying all
+current fields; the caller re-renders unchanged rejected strings and IDs.
+New-row IDs belong to the caller. Row editing never records a commitment.
+
+Pressing Enter in an input activates review or record, preserving draft rows.
+Explicit add/remove actions remain available without JavaScript.
+Default submitter `intent` values are `review`, `record`, `edit`, all configurable.
+Only a caller-produced `review` snapshot or a retained `retryFingerprint` exposes
+explicit confirmation. `review.fingerprint` posts under `reviewFingerprint` by
+default. After an uncertain outcome, re-render the exact submitted values,
+request identity and fingerprint; never fabricate a new intent/token. Confirmation
+is an unchecked required checkbox on native renders and when a new review
+fingerprint arrives in a hydrated form. Its value defaults to
+`yes`. The server must bind fingerprint to all submitted values and authority,
+reject changed/stale review data, and replay identical committed retries.
+Rendering a review snapshot or selecting a source never accepts/records anything.
+
+Validation: `pnpm --filter @happyvertical/smrt-commerce exec vitest run --config
+vitest.purchasing.config.ts`, owning build/typecheck/pack checks, and the shared
+quote native/hydrated browser harness with `QUOTE_BROWSER_EXTENSION` pointing at
+`packages/commerce/test-support/purchasing-browser-extension.mjs`. Full repository
+CI/E2E is consolidated at the #3423 release boundary by owner instruction.
+
+Invalid or unsafe display amounts/scales render localized unavailable text.
+Strict money helpers continue to reject malformed data; presentation recovery
+does not validate or authorize submitted money.
+
+The `attachments` snippet renders outside the editor form so an Assets
+`AttachmentPanel`/`AttachmentUpload` keeps its own multipart action and request
+identity. The attachment region remains disabled while the editor is read-only
+or busy. Use `extensions` only for controls belonging to the editor submission;
+never place another form there.
+
+Composition regression: run the quote SSR lane, then the maintained quote browser
+host with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/quote-attachments-browser.mjs`.
+It submits actual Assets upload bytes and the separate editor action with and
+without JavaScript at 390px.

package/agents/quote-ui.md

@@ -0,0 +1,82 @@
+# Quotation and estimate presentation
+
+Import `QuoteEditor`, `QuoteRevisionHistory`, `QuoteRevisionComparison` and their
+Props/DTOs from `@happyvertical/smrt-commerce/svelte`. Registry slots are
+`quote-editor`, `quote-revision-history`, and `quote-revision-comparison`.
+Commerce playground has interactive vendor quotation and customer estimate demos.
+
+`kind: 'vendor-quotation'` means received supplier evidence;
+`kind: 'customer-estimate'` means pricing proposed to a customer. Neither widget
+selects pricing, accepts budgets, awards work, sends messages or mutates a model.
+Adapt public Commerce Estimate/Contract fields (`currency`, `totalAmount`,
+`status`, `customerId`/`vendorId`) to these presentation DTOs;
+construction package allocation and approval policy remain caller extensions.
+Client records need not become Commerce Customers.
+
+`QuoteRevision.total.amountMinor` is a safe integer or null (unknown), with an
+explicit `minorUnitDigits` from the owning currency/asset contract. No locale
+inference, monetary rounding or unknown-as-zero comparison occurs. Different
+kinds/currencies/scales cannot produce a delta. Existing invoice `LineItem`
+major-unit props retain their established contract. Form money values are raw
+**major-unit strings**: the caller validates and converts before saving; invalid
+strings remain visible after failed actions. Dates likewise remain text to avoid
+native date inputs silently clearing rejected server values.
+
+Supply `values`, authorized `counterparties`, `action`, optional `method`,
+`hiddenFields` (name/value pairs), `errors` and `message`. `names` maps payload
+names to an existing endpoint. `labels.counterparty = 'Client'` supports local
+terminology. `extensions` composes pricing-source/allocation fields;
+`attachments` composes private Assets controls without loading bytes here.
+`QuoteRevisionHistory.evidence(revision)` composes authorized document links.
+All fixed component text uses the shared i18n catalog; data/status/date labels
+come from the caller.
+
+Currency uses the shared `CurrencySelect`, localized by the active smrt-ui i18n
+context. Its native name still comes from `names.currency`, and rejected or
+unknown raw strings remain selected for a corrected submission. Pass
+`currencyOptions` only when the caller must restrict the catalog.
+
+Rows submit repeated `lineId`, `lineDescription`, `lineQuantity`, `lineUnitRate`.
+Default submitter `intent` is `save`, `addLine`, or `removeLine:<stable-id>`;
+override via `intents`. Add/remove are ordinary `formnovalidate` POSTs, including
+all current strings and hidden tokens even without JavaScript. The action must
+read all repeated fields, preserve row IDs, and re-render them; add/remove are
+form-edit operations, not financial writes. Never treat an add-row POST as a save.
+
+The editor does not generate or rotate submission tokens. Caller-owned
+`@happyvertical/smrt-ui/form-retry` can be attached via `formAttributes` using
+Svelte's `createAttachmentKey()` and `retry.attach`; caller transport enhancement
+may use `onsubmit`. Use the same server-owned hidden identity when retrying an
+uncertain commit. Never blindly reset after a response. The caller must preserve
+hidden tenant/request/predecessor values, validate authorization on every action,
+and enforce idempotency transactionally. See `docs/content/form-retry.md`.
+`readonly`/`busy` only disable the presented fields; these props are not security.
+
+Validation: `pnpm --filter @happyvertical/smrt-commerce exec vitest run --config vitest.quotes.config.ts`,
+`node packages/commerce/test-support/quote-browser.mjs`, package typecheck/build.
+The browser harness executes actual SSR POST recovery with JavaScript disabled
+and hydrated demo interactions at 390px. Full release CI/E2E runs at #3423's
+consolidated release boundary by explicit owner instruction.
+
+On NixOS, the browser lane accepts the repository-standard
+`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/run/current-system/sw/bin/chromium`.
+Set `QUOTE_EVIDENCE_DIR` and `CI_TEST_TMPDIR` to an owned evidence directory outside
+`/tmp`. Other commercial tests may reuse its host via
+`QUOTE_BROWSER_EXTENSION=/absolute/fixture.mjs`: export `handleRequest(req, res,
+{vite, render, css, requests})` returning true when handled, and
+`run({browser, baseUrl, evidence, requests})` for additional assertions.
+
+Invalid or unsafe display amounts/scales render localized unavailable text.
+Strict money helpers continue to reject malformed data; presentation recovery
+does not validate or authorize submitted money.
+
+The `attachments` snippet renders outside the editor form so an Assets
+`AttachmentPanel`/`AttachmentUpload` keeps its own multipart action and request
+identity. The attachment region remains disabled while the editor is read-only
+or busy. Use `extensions` only for controls belonging to the editor submission;
+never place another form there.
+
+Composition regression: run the quote SSR lane, then the maintained quote browser
+host with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/quote-attachments-browser.mjs`.
+It submits actual Assets upload bytes and the separate editor action with and
+without JavaScript at 390px.

package/dist/billing/units.d.ts

@@ -6,13 +6,7 @@
  * representation itself, so the only conversion this package performs is the
  * ISO 4217 one: minor units ÷ 10^exponent.
  */
-/** Upper-case, validate, and return an ISO 4217-shaped currency code. */
-export declare function normalizeCurrency(currency: string): string;
-/**
- * The ISO 4217 minor-unit exponent of a currency (2 for USD and RSD, 0 for
- * JPY, 3 for IQD). Any code not listed as 0, 3, or 4 is 2.
- */
-export declare function currencyMinorUnitExponent(currency: string): number;
+export { currencyMinorUnitExponent, normalizeCurrency, } from '../svelte/invoices/currency.js';
 /** Integer minor units → major units (`1999` USD → `19.99`). */
 export declare function minorToMajorUnits(amount: number, currency: string): number;
 /**

package/dist/billing/units.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/billing/units.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAuCD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY1E;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAetE;AAKD,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,SAAc,GAAG,MAAM,CAKzE;AAED,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1C;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE/D"}
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/billing/units.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AAExC,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY1E;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAetE;AAKD,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,SAAc,GAAG,MAAM,CAKzE;AAED,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1C;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE/D"}