@happyvertical/smrt-commerce 0.57.2 → 0.57.4

package/AGENTS.md

@@ -31,6 +31,8 @@ recipes show carry `@field({ description })` text; keep both in plain
 language for end users and update them when a recipe's fields change. See
 [core recipes](../core/agents/recipes.md).
 
+See [historical issued sales](agents/historical-sales.md) for exact original source
+money, immutable source children and combined historical/live customer funds.
 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,
@@ -215,3 +217,18 @@ See [agents/purchasing-ui.md](agents/purchasing-ui.md) for caller responsibiliti
 
 Pure signed cost billing and explicit tax rounding are available through the
 independent `cost-billing` subpath; see [contract](agents/cost-billing.md).
+
+See [contract billing schedules](agents/contract-billing-schedules.md) for exact
+approved milestone capacity, immutable amendments and atomic canonical invoice issue.
+
+## Customer funds (#4079)
+
+See [customer advances](agents/customer-funds.md) for explicitly configured
+unapplied-AR/deposit-liability receipts, conserved application/refund capacity,
+real liability reclassification, final-invoice attestation and mutation guards.
+Use the public commands; `Payment.customerFundsJson` is command-owned.
+
+See [observed purchase prices](agents/observed-purchase-prices.md) for incomplete
+original supplier prices, explicit unknown totals and reviewed completion.
+See [received sales agreement money](agents/received-sales-contract-money.md) for
+exact complete source Order/Agreement evidence without synthetic lines or tax recognition.

package/README.md

@@ -323,6 +323,10 @@ and retry only if it is still pending. An already completed payment retains the
 owner: if it rolls back after settlement returns, reload the payment before retry.
 These guarantees cover new postings, not orphaned journals written by older
 versions. The returned journal uses the caller's database executor.
+Both payment and refund journal lines retain the payment's explicit currency and
+exact amount; posting does not convert currencies or fall back to USD. When
+reporting accounts that contain different currencies, use the public
+`listPostedMovements` currency filter rather than combining their amounts.
 
 ### Cross-Package References
 
@@ -827,3 +831,129 @@ native POST of vendor, reference, notes, expected date and ship-to fields. Pass
 allocations and totals unchanged. `PurchaseOrder` stores `expectedDate` and
 `shipTo` in existing STI metadata. See [the purchasing contract](agents/purchasing-ui.md#purchase-order-header)
 for validation, retained values and transport details.
+
+### Invoice retention and release
+
+`configureInvoiceRetention` freezes an explicit retained minor-unit amount on an
+unpaid draft. Supply tenant, invoice, currency, expected invoice revision,
+request identity, actor, reason, evidence reference, and versioned host policy.
+The supported `creditPolicy: 'retained-first'` is an explicit caller choice:
+issued credits reduce unreleased retention first, then current payable. Hosts
+must choose and authorize their regional policy; Commerce supplies no legal
+percentage or release date default. Configuration cannot be overwritten; replace
+an unissued draft to change the original agreement.
+
+`releaseInvoiceRetention` appends evidence under the invoice's transaction lock.
+It cannot release more than the currently retained remainder. Exact request
+replays are safe; changed payloads or stale revisions fail. Both commands retain
+caller transaction affinity. Original gross, tax, line snapshots and approved
+configuration stay unchanged. Credits and credit cancellation derive remaining
+retention without rewriting release history.
+
+`invoice.getPayableFacts()` separates `grossBalanceMinor`,
+`retainedRemainingMinor`, `currentlyDueMinor`, and `allocationCapMinor`. The
+allocation API enforces the current cap. `getAmountDue()` returns current due;
+`getBalance()` remains the signed gross balance. An invoice with paid current
+due and unreleased retention is not fully paid or overdue. Display gross and
+current payable separately; pass explicit current due and remaining holdback to
+the exact retained invoice UI props rather than treating gross as payable.
+Stored money facts include `payable` for retained invoices; MCP projection honors
+field visibility for every source of the payable alias.
+
+Provider-controlled imports/automatic collection cannot acquire retention.
+Accounting export refuses unreleased retention until the provider has an
+explicit payable representation; it never silently requests collection of
+gross. Fully released invoices use the existing gross accounting contract.
+
+## Retained invoice accounting
+
+`loadRetainedInvoiceAccountingSnapshot` supplies a read-only frozen document for
+reviewing item/tax mapping before posting; `toRetainedInvoiceAccountingInput`
+validates that reviewed mapping against those frozen lines. Both preserve tenant and caller executor
+scope and performs no provider operation. Generic accounting snapshot/export still
+refuses unreleased retention. A supplied host-managed release due date may precede
+the release date: preserving original past-due terms makes the released amount
+immediately overdue rather than silently extending payment terms.
+
+`loadRetainedCreditAccountingSnapshot` and `toRetainedCreditAccountingInput`
+provide the equivalent review path for an issued calculated credit. The caller
+supplies both original invoice and credit IDs; the owning API verifies tenant,
+customer, currency and exact original lineage, then retains the existing frozen
+reader's issue and provider-realm checks. Generic retained-credit export remains
+blocked. Review never creates a credit adjustment or contacts a provider.
+
+The public `syncRetainedInvoiceToAccounting`, `releaseRetainedInvoiceToAccounting`,
+`syncRetainedCreditToAccounting`, and `syncRetainedRefundToAccounting` commands
+implement an explicit QuickBooks accrual reclassification contract. They require
+SDK `receivableTransfers` from the published SDK0.104.1 cohort
+(happyvertical/sdk#1414 / #1415; absent from SDK0.104.0).
+They are available from the Commerce root and `/invoices` entry points.
+
+The tenant must review/version the realm, environment, customer, AR account,
+retained-asset account and optional bank account mapping. Supported choices are
+`accrual`, `invoice-tax-point` and `host-managed` release due dates. Verified home
+currency only; no inferred FX, tax timing, recovery percentage or release date.
+Hosts authorize actors before these server commands and provide an active tenant.
+
+For gross10500/retained1000, the original approved invoice remains10500. A
+withholding journal debits retained assets and credits customer AR1000; a
+zero-cash application links that credit to the original invoice. A partial release
+creates the opposite journal and an explicitly dated host collection obligation.
+The original invoice and its tax snapshot are unchanged. Provider collections and
+provider tax overrides are unsupported for this contract.
+
+Initial export requires an issued, unpaid, uncredited, unreleased host-owned
+invoice with no prior provider identity. Historical source-owned invoices require
+a separate reconciled ownership contract and are rejected: importing history must
+not duplicate its original journal. Existing local retention commands continue to
+reject provider-controlled releases; use the provider release command instead.
+
+Retained-first credits cancel the applicable retained asset through a release
+journal, apply the exported credit memo to that journal, and apply any due portion
+to the original invoice. Unapplied credit remains available for a refund. Refund
+sync requires an already completed local refund Payment, its cash journal and one
+exact source-credit allocation. It records the cash journal and applies the
+existing credit; it performs no bank action and makes no settlement-certification
+claim. That source payment/allocation becomes immutable. Provider-managed invoice
+voids/write-offs, credit cancellation/reallocation and refund deletion are rejected
+rather than silently erasing remote postings. Corrective reversal contracts are
+not implemented by these commands.
+
+### Recovery and concurrency
+
+Each external write has persisted request bytes/hash, attempt owner, status and
+validated readback. Confirmed earlier steps survive a later failure. Unknown or
+interrupted steps block new operations; `reconcileRetainedAccountingStep` requires
+the observed request/attempt, a known remote ID for exact provider readback, or
+explicit authoritative absence evidence. An interrupted in-flight owner must be
+proven stopped. Reconciliation evidence and previous attempts remain recorded.
+`reconcileRetainedBaseInvoice` wraps the existing frozen invoice recovery contract.
+`reconcileRetainedCreditAccounting` resolves the reserved credit-memo creation step. Ordinary credit export is blocked for provider-retained sources.
+
+The descriptor hash is not remote idempotency. The SDK uses documented QuickBooks
+request-ID duplicate handling; never create a new request identity merely because
+a response was lost. Exact local replays reuse confirmed steps. Competing commands
+serialize under the tenant/source invoice locks, and releases check an observed
+invoice revision. Source credits cannot change during an unfinished retention
+operation. Commands reject caller-owned Commerce money transactions because a
+provider write cannot be rolled back with local SQL.
+
+`readRetainedInvoiceAccountingState` exposes the persisted operation/readback
+history. Canonical `Invoice.getPayableFacts()` remains the source of local gross,
+retained, released, credited and currently due amounts. Provider invoice
+`TotalAmt - Balance` includes noncash applications and must never be labeled cash
+received. SDK readback separates noncash applications, recorded cash journals and
+unverified bank settlement.
+
+Validation uses native SQLite/PostgreSQL persistence with mocked public provider
+operations, plus the SDK's exact request/readback fixtures. No live provider call
+or sandbox certification has been performed. Primary contract evidence and
+provider-field limits are documented in the SDK Accounting README.
+
+### Incomplete supplier price evidence
+
+Use `recordPurchasePriceObservation`, `readPurchasePriceObservation`, and
+`completePurchasePriceObservation` for source quotes/orders that lack complete
+net/tax/gross facts. Unknown totals remain null and no calculated or reportable
+Contract exists until explicit reviewed completion. See
+[observed purchase prices](agents/observed-purchase-prices.md).

package/agents/accounting-snapshot-mapper.md

@@ -109,3 +109,14 @@ 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.
+
+## Compound tax configuration
+
+`FrozenQuickBooksTaxMapping.lines[lineId].taxComponents` may retain the
+caller-verified ordered realm TaxCode configuration as `{taxRateRef, compound}`
+entries. Compound frozen lines require that exact sequence and their stored
+`taxableMinor` bases. The mapper projects `compound` and `taxableAmount` into the
+public accounting SDK without changing statutory percentages or declared taxes.
+Missing/mismatched configuration fails explicitly. Hosts own tenant-scoped review
+and provenance of the existing realm code's applicability/order; a taxCodeRef
+string alone is insufficient evidence. Use the SDK release containing sdk#1412.

package/agents/contract-billing-schedules.md

@@ -0,0 +1,67 @@
+# Contract milestone billing (#4074)
+
+Use the public Commerce `approveContractBillingSchedule`,
+`issueContractMilestoneInvoice`, `getContractBillingSchedule` and
+`allocateContractMilestones` exports for fixed-value milestone billing. These
+commands own monetary capacity. The host owns construction scope, estimated cost,
+approval permissions, signed evidence, regional policy and UI.
+
+Start with an accepted, frozen customer `Order` or `Agreement`. The first schedule
+requires `amendmentMinor: 0`, `expectedRevision: 0`, currency, explicit `basis:
+'net' | 'gross'`, `approvalEvidenceRef`, `taxPolicyEvidenceRef` and exact milestone
+`{ key, label, amountMinor }` entries. Their sum must equal the original Contract
+subtotal for net basis or totalAmount for gross basis. There is no editable
+schedule override of the accepted Contract value.
+
+Each amendment supplies the current expected revision, a new request identity,
+an explicit signed `amendmentMinor`, approval evidence and the complete next
+schedule. Its ceiling is derived from the original frozen value plus all approved
+amendments. Currency/basis cannot change. Already issued milestone keys, labels
+and amounts must remain unchanged. Prior revisions and original Contract money
+remain immutable. Unissued milestones can be rescheduled through an explicitly
+approved revision. Net capacity is not a gross ceiling: each invoice's tax must
+also be explicitly approved under the versioned policy.
+
+`allocateContractMilestones(totalMinor, weights)` accepts positive integer
+relative weights. All nonfinal shares truncate exact rational arithmetic; the
+final entry receives the exact remainder. For example 100 with weights [1,1,1]
+returns [33,33,34]. Zero amounts are allowed; negative/unsafe money and nonpositive
+weights reject. The helper chooses no tax policy or commercial percentages.
+
+Prepare a normal canonical draft Invoice and real line items through the public
+Commerce collections. Draft preparation consumes no capacity; an unissued draft may be cancelled
+without a claim. Then call:
+
+```ts
+const claim = await issueContractMilestoneInvoice({
+  db, tenantId, contractId, requestId: 'issue:start:v1',
+  revision: 1, milestoneKey: 'start', invoiceId,
+  approvedMoney: { netMinor: 4000, taxMinor: 200, grossMinor: 4200 },
+  invoiceApprovalEvidenceRef: 'approved-invoice:123',
+});
+```
+
+The command checks same tenant/customer/currency/Contract, derives current line
+money, verifies the exact approved net/tax/gross and schedule amount, freezes the
+invoice and records the claim atomically. Tax-policy evidence is a host-owned
+reviewed version reference, not an instruction to infer tax rates. Preserve the
+approval's policy and original evidence in the host. Ordinary issue against a
+scheduled Contract is refused, including direct creation in a non-draft state.
+Existing issued contract invoices prevent adopting a schedule retroactively.
+
+The explicit capacity policy is `issued-consumed`: cancellation, credits,
+write-offs, payments, retention and refunds never reopen a claimed milestone.
+Credits correct the canonical receivable and settlement continues through existing
+Payment/PaymentAllocation facilities. Unapplied payments remain the deposit cash
+authority. A replacement billing entitlement requires an explicit approved
+amendment; this API does not infer that a credit authorizes re-billing. Applications
+must explain that policy rather than present a hidden re-bill action. Issued
+claims remain readable after later amendments and cancellations.
+
+Every mutation requires the active tenant context and uses the tenant money
+serialization barrier on the exact parent transaction executor. Identical request
+replay returns the original evidence; a changed payload, stale revision or second
+claim rejects. A parent rollback reverses both invoice issue and schedule claim.
+A detached read DTO cannot modify persisted state. Ordinary Contract writes and
+deletes cannot erase schedule history. Host authorization precedes these commands;
+none is exposed as an unauthenticated generated mutation.

package/agents/contract-money.md

@@ -19,3 +19,84 @@ 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.
+
+## Received supplier monetary evidence
+
+`recordReceivedPurchaseMoney({ db, tenantId, contractId, requestId, evidenceRef,
+facts, sourceQuote? })` records declared money on an existing empty draft
+`SupplierQuote` or `PurchaseOrder`. Authorize the human in the host first and
+call inside its active tenant context. The command locks tenant settings and
+the document on its transaction executor; an outer transaction can include
+creation of the quote/order. It returns a `ReceivedPurchaseMoneySnapshot`;
+`getReceivedPurchaseMoney(contract)` returns that validated snapshot or `null`
+for calculated documents. The public command is not an unguarded MCP action.
+
+```ts
+await recordReceivedPurchaseMoney({
+  db, tenantId, contractId: quote.id, requestId: 'received-revision-1',
+  evidenceRef: 'supplier-document:revision-1',
+  facts: {
+    currency: 'CAD', netMinor: 10000, taxMinor: 537, grossMinor: 10537,
+    taxComponents: null,
+    detail: { kind: 'header-only' },
+  },
+});
+// Reload after the command; stale instances cannot overwrite its authority.
+const received = await contracts.get({ id: quote.id }, { cache: false });
+received.status = ContractStatus.ACCEPTED;
+await received.save();
+```
+
+This sets `moneyAuthority='received'`; aggregate headers retain exactly
+10000/537/10537 without guessing a tax rate. The default `calculated` mode and
+its line/tax-code calculator are unchanged. Received facts become immutable
+when recorded. Exact retries return the original snapshot even after acceptance;
+changed requests need a new document revision. Direct authority/evidence writes,
+header edits, calculated lines, party/type changes and deleting received history
+are rejected. Acceptance sets the normal `moneySnapshotId` without recalculating
+source amounts. A stable application quote identity may reference a distinct
+canonical `SupplierQuote` for each immutable revision.
+
+`detail` must explicitly be `header-only` or `lines`. The latter supplies complete
+source `netMinor`, `taxMinor`, `grossMinor` per uniquely keyed line with exact
+aggregate reconciliation. Optional `quantityText`/`unitRateText` retain original
+decimal text, never drive recomputation. When source lines are incomplete, retain
+them in the referenced source evidence and use header-only monetary facts; do
+not invent `ContractLineItem` quantities, tax lines, or allocations.
+
+`taxComponents:null` means unknown decomposition. `[]` means known zero tax,
+which requires `taxMinor:0`, but does not classify that zero as exempt/zero-rated.
+Each supplied component retains its source key, label, amount, explicit
+`classification` (`taxable`, `zero-rated`, `exempt`, `out-of-scope`, or `null`)
+and `recoverableMinor` (including explicit zero or unknown `null`). Optional
+`taxCodeId`, `taxComponentId` and `taxableMinor` remain unknown when omitted. Values are exact
+safe nonnegative minor units; sums use integer arithmetic. No recoverability,
+rate, taxable basis or classification is inferred from a label or amount.
+
+An order can include
+`sourceQuote:{contractId,relationship:'copy'|'negotiated'}`. The quote must be
+accepted, frozen, received, and match tenant/vendor/currency. `copy` requires
+identical facts. `negotiated` requires separately supplied approved monetary
+facts and a separate evidence reference; it never prorates a quote. The command
+records lineage but does not manufacture acceptance or financial approvals.
+
+Received SupplierQuotes remain excluded from incurred purchase-tax reporting.
+PurchaseOrders retain their existing report eligibility. For a received order,
+public document report facts project explicit source amounts without creating
+calculated `DocumentTax` rows or fictitious rates. Each report component must
+have an explicit classification, tenant-owned tax code, taxable basis, recoverable amount and, for
+`taxable`, a tenant-owned `taxComponentId`. Missing facts raise
+`ReceivedPurchaseTaxClassificationRequired` with code
+`RECEIVED_PURCHASE_TAX_CLASSIFICATION_REQUIRED` and the affected order ID. This
+blocks only a report whose tenant/date/currency window includes that order;
+recording, accepting and awarding unknown-classification evidence remains valid.
+Existing calculated PO reporting is unchanged. Correct classification through an
+explicit reviewed replacement revision and cancellation of the superseded
+report-eligible order, preserving its history; never rewrite frozen evidence or
+silently omit the unknown order from a report.
+
+The two added Contract fields use the normal generated schema/migration flow;
+apply the generated migration before using the new public command on an existing
+database. Native SQLite/PostgreSQL acceptance is in
+`received-purchase-money.test.ts` / `received-purchase-money.optional.test.ts`.
+DuckDB retains the existing unsupported native Contract foreign-key boundary.

package/agents/customer-funds.md

@@ -0,0 +1,96 @@
+# Customer advances and unallocated cash
+
+The public `recordCustomerFunds`, `allocateCustomerFunds`, `refundCustomerFunds`,
+`reverseCustomerFundsAllocation` and `getCustomerFundsFacts` commands reuse
+Payment, PaymentAllocation and smrt-ledgers journals. They do not create invoice
+revenue, issue credit notes, transmit money to a bank or call a provider.
+Applications authorize each command and supply human/source evidence.
+
+A receipt requires an explicit immutable policy version:
+
+- `mode`: `unapplied-ar` or `deposit-liability`.
+- `taxTiming: 'invoice-tax-point'`: the caller has explicitly reviewed that tax
+  belongs on the eventual invoice. This is the only supported timing. The API
+  does not assume that every jurisdiction treats deposits as untaxed; other
+  timing policies are rejected and need a separate supported accounting model.
+- `releaseEligibility`: `any-issued-invoice` or `final-invoice-only`.
+- Distinct cash and receivables asset accounts, plus a liability account only
+  for liability mode. Every account must be active in the same tenant chart.
+
+Ledgers currently has no separate Ledger entity or currency-restricted Account
+field. The ledger boundary is its tenant-owned chart; currency is explicit on
+this receipt and every journal entry. The legacy `RecordPaymentOptions.ledgerId`
+is unused by existing Payment settlement. These commands neither pretend it
+validates an independent ledger nor invent account metadata conventions.
+
+| Operation | Unapplied AR | Deposit liability |
+| --- | --- | --- |
+| Receipt | DR cash / CR AR | DR cash / CR customer liability |
+| Application | Existing settlement allocation | DR customer liability / CR AR |
+| Unallocated refund | DR AR / CR cash | DR customer liability / CR cash |
+| Application reversal | Reverse settlement allocation | DR AR / CR customer liability |
+
+All amounts are positive safe integer minor units. Available capacity is exactly
+`received - active applications - settled source-linked refunds`. A refund is a
+positive outgoing Payment with immutable source-receipt lineage; it is not an
+invoice credit refund. Reversal retains the original application and appends an
+inverse operation and journal, removing only the active settlement row. An issued
+invoice credit or credit refund blocks application reversal so previously spent
+cash cannot become refundable a second time. Resolve that invoice correction
+through its own authority first.
+
+Each request carries `effectiveOn` (calendar date), `evidenceRef`, `actorId` and a
+stable `requestId`. Effective dates are distinct from recording timestamps and
+must be chronological within a receipt's movements. Receipt/refund `paidAt` and
+journal dates use the explicitly supplied effective date. Exact replays return
+current conserved facts; changing the request payload fails. Refund/application
+races serialize on the tenant money boundary and receipt revision. Caller-owned
+transactions include the payment, journals, allocation, status and audit evidence.
+
+Application requires a matching issued invoice, customer, currency, optional
+sales contract and actual `moneySnapshotId`. `release` also names the frozen
+receipt policy version and the host's immutable invoice-approval evidence. Under
+final-only policy, the host must verify and attest `kind: 'final-invoice'` from
+that frozen approval. This is an application authorization responsibility, not a
+user-supplied checkbox or inference from invoice numbering. The generic library
+checks the attestation shape and exact canonical monetary snapshot; it does not
+know construction milestone/finality rules.
+
+`Payment.customerFundsJson` is command-owned. Ordinary saves, deletes,
+PaymentAllocation create/update/delete, collection allocation helpers, payment
+intent settlement and supplier payouts cannot repurpose managed advances or
+bypass required journal entries. Managed refunds cannot be allocated to invoice
+credits. `getUnallocatedFromPayment` subtracts managed refunds and requires the
+persisted receipt amount. Direct SQL and administrative ledger mutations remain
+outside this domain authority; facts refuse missing/voided journal evidence.
+
+```ts
+await withTenant({ tenantId }, async () => {
+  const received = await recordCustomerFunds({
+    db, tenantId, customerId, currency: 'CAD', amountMinor: 10000,
+    method: PaymentMethod.BANK_TRANSFER, requestId: receiptRequestId,
+    effectiveOn: '2026-10-01', evidenceRef: bankReceiptRef, actorId,
+    policy: {
+      version: reviewedPolicyVersion, mode: 'deposit-liability',
+      taxTiming: 'invoice-tax-point', releaseEligibility: 'final-invoice-only',
+      cashAccountId, receivablesAccountId, liabilityAccountId,
+    },
+  });
+  await allocateCustomerFunds({
+    db, tenantId, paymentId: received.paymentId, invoiceId, amountMinor: 8000,
+    requestId: applicationRequestId, effectiveOn: '2026-10-10',
+    evidenceRef: applicationEvidenceRef, actorId,
+    release: {
+      kind: 'final-invoice', invoiceSnapshotId,
+      approvalEvidenceRef: frozenFinalInvoiceApprovalRef,
+      policyVersion: reviewedPolicyVersion,
+    },
+  });
+});
+```
+
+Native `customer-funds.test.ts` and `customer-funds.optional.test.ts` prove exact
+journals, both modes, direct-path protections, dates, finality evidence,
+conservation, invoice-credit interaction, retries, caller rollback and a real
+PostgreSQL post-journal write fault plus refund/application race. Run PostgreSQL
+through the standard managed database wrapper; never use an application's schema.

package/agents/historical-sales.md

@@ -0,0 +1,132 @@
+# Historical issued sales and original customer funds (#4081)
+
+Historical intake is a separate source authority, not a new sale, send, or cash
+posting. Hosts must authorize the reviewer/importer, preserve original evidence,
+and call these public commands with the explicit active tenant. All writes use
+one caller-affine transaction and the existing tenant money serialization lock.
+
+`recordHistoricalSalesMoney({ db, tenantId, invoiceId, requestId, evidenceRef,
+review, source, facts, creditedSource? })` adopts an empty draft Invoice. Supply
+original integer minor-unit net/tax/gross, explicit signed-versus-magnitude
+polarity, original issue calendar date/time zone, and a nullable unknown due date.
+Normal calculated Invoice construction still defaults its due date as before.
+Historical invoices expose `moneyAuthority: 'historical'` and a frozen source
+snapshot. They create no InvoiceLineItems, fake quantities/rates, delivery event,
+AR/revenue journal, or provider invoice.
+
+A `detail: { kind: 'lines', lines }` source creates immutable
+`HistoricalSalesLine` children. The returned `{ snapshot, lines }` binds every
+source key to a concrete `lineId`; use these IDs for consumer crosswalks.
+Unknown line tax, gross, quantity and rate remain null. Signed real adjustment
+lines retain their source values. The line net sum and every fully known other
+sum must exactly equal its corresponding original header.
+
+Historical credits specify the exact original invoice/money snapshot and
+optional concrete original child IDs. Independent net, tax and gross capacity
+checks never prorate a header. `getHistoricalSalesMoney` and
+`readHistoricalSalesLines` validate immutable retained authority.
+`getInvoiceMoneyFacts` includes the historical source projection. Exact header
+reports remain available through `listHistoricalSalesHeaderFacts` even when tax
+classification is unknown. Breakdown-dependent tax reports require explicit
+reviewed component identities, taxable and net bases and classification; they
+never infer a percentage from the source amount or borrow today's rate.
+
+Optional original `source.retention` records exact retained cents, an explicit
+retained-first credit policy, source actors/evidence and original calendar-dated
+releases. This contract represents retention configured at original issue; its
+original effective date must equal the issue calendar date. A later retention
+configuration requires its own supported source event contract. Derived retention
+events retain actual `recordedAt` and separate
+`effectiveOn`; as-of original cash eligibility uses the original dates. Ordinary
+current retention configuration/release commands keep their existing behavior.
+Original credit/release sequencing rejects a release whose retained-first
+capacity was already consumed; same-day ordering must be explicitly reviewed.
+Release payment terms remain the original invoice due date, including an
+explicitly unknown date. No jurisdiction terms are invented.
+
+`recordHistoricalCustomerFunds` retains original receipt/refund evidence and
+explicit original deposit/release policy without creating a Payment or journal.
+Original accounting ownership and journal references are evidence, not authority
+to create duplicate original cash. Refunds identify either conserved unapplied
+funds or one exact issued credit. Their headers immediately reserve refund
+capacity, even before their original allocation row is imported.
+
+`recordHistoricalCustomerAllocation` records exact source allocation identities.
+Receipt applications affect the shared invoice paid balance once. Same-original
+credit allocation rows and refund allocation rows audit their already-recorded
+economic effects and do not reduce balances again. Cross-invoice transferable
+credits are not represented by this contract. Same-day cash/credit chronology
+requires explicit reviewed ordering; earlier original cash remains preserved
+when a later credit creates owed/refundable overpayment. Original cash dates
+remain separate from current balances and import timestamps.
+
+`getHistoricalCustomerFundsPosition` returns exact received/allocated/refunded/
+available minor units. `applyHistoricalCustomerFunds` and
+`refundHistoricalCustomerFunds` perform NEW movements against remaining original
+funds using explicit current active same-tenant accounts and the pinned original
+policy terms. Applications use the existing liability-to-AR reclassification;
+refunds use the existing journal-backed Payment command and retain the historical
+receipt ID. Original receipts are never forged into completed Payments. Shared
+live/historical paid/refund capacity prevents a second allocation or refund.
+
+Stable source namespace/key identities replay exact facts across import runs
+without replacing the original importer or evidence. Changed facts/policy or
+source-version reuse conflicts. Ordinary/generated model writes and deletion
+cannot mutate these immutable records. Provider synchronization and new revenue
+recognition reject historical authority until an explicit supported historical
+accounting representation is supplied; exact original money is still readable.
+
+Focused evidence covers source/header immutability, concrete children, original
+cash/credit/refund chronology, conservation, CAD journals for new movements,
+caller rollback and isolated PostgreSQL execution. Consumer historical adapters
+must still map every source table and prove full-cohort reconciliation; adopting
+these public facts alone is not full reference-import acceptance.
+
+Current explicitly dated retention releases append after the immutable original
+release prefix. Both remain readable without changing original dates or source
+authority; replay binds the explicit date and caller rollback restores the
+complete release history. Provider releases retain their effective date in the
+canonical retention history as well as provider evidence. Shared SQLite and
+PostgreSQL retention suites verify reload, exact retry, original-prefix tamper
+refusal, and transactional rollback.
+
+Historical cash allocations are validated as dated payment prefixes, independent
+of source import order. Backdated insertion rechecks later application dates;
+ordinary public allocations retain their canonical allocatedAt chronology.
+Same-day credit ordering remains explicit. Later credits alone do not
+retroactively invalidate cash received before their issue date.
+
+Current `releaseInvoiceRetention` commands retain optional `sameDayCreditOrder`
+in their immutable evidence, alongside the effective calendar date. An exact
+retry must preserve that ordering; changing or removing it is a changed request.
+A later original credit import on the release date uses the retained ordering:
+`release-before-credit` releases first, while `credit-before-release` applies
+the retained-first credit before checking remaining release capacity. Missing
+ordering remains ambiguous and is refused rather than inferred from record time.
+### Bounded historical report scope
+
+Historical header and tax reports apply the explicit tenant, historical money
+authority, inclusive issue-date period, optional currency, and non-draft/non-cancelled
+status predicates in the collection query before enforcing the 100,000-document
+scope limit. Unrelated archived invoices do not consume a smaller report's limit;
+more than 100,000 matching documents is refused rather than truncated.
+
+Regression design (#4063, PR #4101 comment 4300513731):
+
+| Invariant / trigger | Positive / refusal | Actor and executor | Runtime / evidence |
+| --- | --- | --- | --- |
+| Small matching period in a large tenant archive | Query-boundary fixture returns the single matching row only when all predicates precede the limit; matching scope above the cap still refuses | Explicit tenant and caller database; reads only | Focused Vitest; sparse overflow result avoids creating an archive |
+| Native collection scope | Exact inclusive boundaries, optional currency, historical authority and tenant isolation; draft/cancelled excluded | Active tenant, native test database | Focused SQLite and isolated PostgreSQL public historical-money + report proof |
+
+No persistence behavior changes; rollback/retry and external-provider edges are
+not applicable to this read-only query correction. The coordinator owns broader
+cohort validation and exact-head review under the resumed four-comment batch.
+
+Evidence on Node26/pnpm11.25.0: the focused archive-query regression failed against
+78f3ac856 (two failures, one pass), then passed after this query fix. The standard
+`node scripts/run-with-ci-postgres.mjs -- pnpm --filter @happyvertical/smrt-commerce exec vitest run src/__tests__/historical-sales-report-scope.test.ts src/__tests__/historical-sales-report-scope-native.test.ts`
+proof passed all five cases in9.80seconds, including actual SQLite and isolated
+PostgreSQL scope/tenant checks. No100,000-row fixture, production writes or schema
+changes were needed. Full logs remain external at the2026-10-16 MVP session's
+`nonfinancial-import/scoped-sales-regression-base.log`, `scoped-sales-focused.log`
+and `scoped-sales-postgres.log`. Native token usage was unavailable.

package/agents/money-calculator.md

@@ -42,3 +42,39 @@ fraction. It takes no options. Its discount is signed minor units and passes
 through unchanged, and its ties round half away from zero for negative
 lines too. Editor magnitude normalization happens before constructing that
 input. See [invoice line calculation](invoice-calculations.md).
+
+## Ordered compound taxes
+
+`TaxComponentInput.compound: true` uses every preceding component in the same
+ordered tax code. Different applicable line/category subsets use different codes;
+no missing predecessor is invented. Exclusive and explicit-net credit inputs use
+prior rounded taxes at line scope or prior allocated taxes at document scope.
+Shared components retain one rate. Contradictory dependency orders across codes
+fail with `TAX_COMPONENT_DEPENDENCY_CYCLE`.
+
+Inclusive extraction computes exact ordered rational factors, then rounds or
+allocates the extracted component taxes. Net is the gross-minus-tax residual.
+This is not a promise that an inclusive extraction reverses an exclusive rounded
+calculation penny-for-penny. Signed reversals use the same symmetric rules.
+
+Compound result components and frozen line snapshots carry `compound: true` and
+`taxableMinor`. Component tax rows preserve this actual basis, with `netMinor`
+separate so kind/revenue summaries do not include tax-on-tax as net revenue.
+Historical additive snapshots omit these optional fields. Credits reconstruct the
+frozen ordered components; a final credit consumes the remaining frozen bases and
+taxes. The compatibility line `taxRate` is the observed effective tax/net ratio
+for compound lines, not a flattened statutory rate; never use it to reconstruct
+a document. Use component snapshots and canonical minor-unit totals.
+
+`DocumentTax.netMinor` is a nullable generated-schema field. Additive records use
+null and retain their previous reporting shape. Upgrade schemas before projecting
+reports. Received purchase components may declare a taxable basis above net;
+when that occurs their explicit `netMinor` is required for report classification.
+Recording evidence remains allowed without that classification.
+
+Compound accounting synchronization uses the public SDK ordered snapshot contract
+([SDK #1412](https://github.com/happyvertical/sdk/issues/1412)). The mapper preserves
+original rates, exact taxable bases and caller-verified realm TaxCode ordering.
+Missing or mismatched reviewed mapping still raises `ACCOUNTING_SYNC_UNSUPPORTED`.
+It never substitutes a flattened rate. Deployment requires the SDK release that
+contains this public contract; the prior additive-only SDK cannot accept it.

package/agents/money-model.md

@@ -27,7 +27,7 @@ line-ID code-unit order breaking ties. It leaves no document residual. Across
 `n` small lines, the two scopes can differ by up to `ceil(n / 2)` minor units
 per component. Store the chosen scope; do not silently substitute a later
 setting. `MoneyValidationError.code` is the public branch point for invalid
-money, discounts, tax-code state and scope, unsupported compound tax, frozen
+money, discounts, tax-code state and scope, contradictory compound dependencies, frozen
 records, and unsafe values.
 
 Tax-code resolution is pure once the caller has loaded authorized codes. It
@@ -105,5 +105,8 @@ mapper](accounting-snapshot-mapper.md).
 Upgrading data written by an earlier version is documented in
 [money data upgrade](money-upgrade.md). Contract money persistence remains a separate aggregate contract; production report
 hosting is an application opt-in over the public host described above. The
-model also does not provide currency conversion, cash-basis/deposit accounting,
-partial recoverability, period locking, or compound tax.
+model also does not provide currency conversion or general cash-basis accounting,
+partial recoverability or period locking. Ordered compound taxes are supported as
+documented in [money calculator](money-calculator.md). Explicit invoice-tax-point
+customer deposits and unallocated cash are provided by the separate
+[customer-funds authority](customer-funds.md), not by invoice pricing.