@voltro/plugin-billing 0.86.0 → 0.87.0

package/README.md

@@ -27,7 +27,435 @@ Checkout and portal URL routes recheck current authentication and their declared
 manager guard after provider IO, before releasing the private URL. A refusal does
 not undo or replay an already created external session.
 
+Checkout creation reserves an active tenant operation in the Billing store,
+retains its request/customer/deadline identity and reuses the provider key across
+invocations. DataStore-backed applications retain that journal across restarts;
+memory stores retain only process state. Providers return exact session receipts
+and provider-clock lookup evidence. A missing mirror or host timestamp cannot
+release an uncertain operation. Custom adapters and stores must adopt the
+registered migration review; sales and provider setup are not activated by it.
+
+Account closure first reserves an immutable account fence in `BillingStores.closures`,
+blocking new checkout/change/resume/portal actions. After tenant-only final usage,
+each subscription receives one retained provider-clock deadline and request identity.
+Stripe retries reuse that deadline and SDK key, including after process replacement.
+Native factories and `billingTables()` include the close journal; custom stores and
+providers must adopt `BillingCloseStore`, `prepareSubscriptionClose` and the required
+`closeOperation` for account-close cancellations. Keep these financial tombstones;
+memory stores remain process-local. Pending/unknown results keep deletion pending.
+In-flight provider actions, late usage and final invoice/payment settlement still
+require lifecycle coordination; a canceled subscription is not a settlement receipt.
+
+The account journal seals normal meter dispatch after the initial final flush.
+Later billable usage is retained, blocks successful closure and needs financial
+reconciliation. Global flushes skip sealed accounts; meter retries recheck the
+seal. Custom close stores must implement monotonic `sealUsage`. In-flight writes,
+provider aggregation receipts and late-usage invoice adjustments remain required.
+
+Trusted server callers with a durable occurrence identity can use
+`reportUsageEvent({ tenantId, entitlementKey, quantity, occurredAt, idempotencyKey })`.
+The native usage store atomically commits the receipt and original-UTC-month counter;
+matching replays do not count again, changed payloads are refused. Memory receipts
+remain local. Custom UsageStore implementations need atomic `recordEvent`, and
+custom schemas need `billingUsageEventsTable`. Native recording owns one root-store
+transaction; do not nest application transactions or provider effects inside it.
+Historical-month pending counters are retained for financial reconciliation rather
+than flushed into the current month. Provider adjustments/settlement remain separate.
+
+Checkout rows retain `slot: 'active'` while live, then use their immutable row id
+for history. `(tenantId, slot)` is the non-null conflict/uniqueness key, independent
+of nullable UNIQUE semantics. Custom stores preserve slot/state together; native
+memory reads return validated copies. Existing custom/prototype receipts require
+verified inventory/slot mapping before index changes; do not discard unknown rows.
+
+Usage retention only expires unused counters (`used = 0` and
+`reportedToProvider = 0`). Counters with consumption remain financial anchors,
+including after provider dispatch; age does not establish financial settlement.
+
 ## License
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+
+## Detailed invoice evidence
+
+`BillingService.invoiceSnapshot(tenantId, providerInvoiceId)` performs a fresh,
+customer-bound read through the optional `BillingProvider.fetchInvoiceSnapshot`
+capability. Stripe reads every line page and rejects drafts, inconsistent headers,
+duplicate cursors, malformed values or more than 10,000 lines. Exact decimal
+quantities remain strings; unknown origins remain null. The service rechecks the
+current customer link after the provider read. Adapters without the capability
+fail explicitly. This server method still requires application authorization.
+
+The result is an observation, not persisted payment or license authority. It
+does not finalize/pay an invoice or change entitlements. Native ingestion and
+subscription/price/payment qualification must precede paid-through decisions.
+
+## Native invoice reconciliation
+
+`BillingService.reconcileInvoice(tenantId, providerInvoiceId)` reads the native
+revision, obtains a complete customer-bound provider snapshot, conditionally
+persists it and reads it back. Invoice events use this path. Missing customer
+links/capability or uncertain persistence fail explicitly for webhook retry.
+A lost compare repeats BOTH reads, with bounded contention retries. Provider
+calls stay outside database transactions. Applications still authorize callers.
+
+`InvoiceStore` replaces event-payload upsert with get(binding),
+complete(binding, expectedOrNull, snapshot) for exact InvoiceObservation records.
+The unbounded native listByTenant method is removed. `_voltro_billing_invoice_observations` has immutable
+ownership and a non-null unique provider/invoice digest. Retained invoice-event
+history is never promoted. Apply declared schema, quiesce old writers and update
+custom schema/store assemblies before cutover. The mock needs independent
+setInvoiceSnapshot state; an event does not create provider evidence.
+
+This persists observations, not payment receipts or license authority. Original
+event callbacks remain historical notifications. Current subscription/price/
+settlement qualification and native recovery still require separate validation.
+
+## Invoice trigger ownership
+
+`BillingProvider.normalizeEvent` returns `BillingProviderEvent`. Its invoice
+variants carry exact providerCustomerId/providerInvoiceId, without tenantId.
+Stripe ignores invoice and subscription metadata for this attribution. Missing
+customer identity fails rather than acknowledging the event as unhandled.
+
+`BillingService.applyEvent` resolves the unique native customer link, checks the
+configured account/mode and retained customer ownership, reconciles complete invoice evidence,
+and returns the tenant-resolved `BillingEvent` for onEvent. Missing, foreign or
+ambiguous links fail; invoice triggers never create links. Custom providers and
+service implementations must adopt both input and result contracts. Customer custody includes retained retired customers in the exact provider account/mode. Full invoice-history catch-up remains separate.
+
+## Durable delivery and bounded catch-up
+
+Live webhook and recovered events share one input-bound Framework receipt in
+`_voltro_idempotency`, scoped by provider, plugin instance, observed account ID and mode. Complete after
+reconciliation and callbacks; failed attempts release only their captured running
+claim. Completed replay lasts 24 hours; retention can preserve rows longer. Native
+Schema registration is required. Standalone webhook mounts keep process memory
+unless `receipts: { scope, store }` supplies a shared IdempotencyStore.
+
+Callbacks are at-least-once, including after expired claims, unknown commits and
+receipt expiry. The optional delivery context provides provider/providerEventId/
+receiptScope for business idempotency; it is absent on direct checkpoint/operator
+corrections. Neither receipt ownership nor invoice observations establish payment
+or license authority. A lease cannot stop an old executor's physical effects.
+
+Provider listUndeliveredEvents now accepts cursor/limit and returns an explicit
+page of exact normalized events plus nextCursor. Stripe reads at most 100 per page;
+a pass visits at most 10 pages. Continuations, busy/failed events or failed reads
+schedule a retry after 60 seconds. Fully processed exhausted history leaves no
+recovery timer. Rejected events remain pending without preventing other event/page
+work. Shutdown cancels pending retry and drains active recovery before returning.
+Current customer discovery cannot replace another native binding or create a
+missing link for a closed tenant. Historical custody is retained; migration, account cutover and recovery acceptance remain required.
+
+The mount-local duplicate cache is isolated per mount by default. A successful
+HTTP acknowledgement from older code is not an undelivered provider event. Review
+that retained history separately; failed-delivery catch-up cannot recover invoices
+that older code already acknowledged without recording complete evidence.
+
+## Account and customer observations
+
+BillingProvider.fetchAccountIdentity and fetchCustomerSnapshot are optional
+read-only capabilities, implemented by Stripe and the mock. Custody consumers
+must refuse unsupported providers rather than infer identity from a key prefix,
+metadata, adapter name or an unqualified native row.
+
+Stripe reads accounts.retrieve(null), balance.retrieve() and the account again.
+It captures the returned account ID and the balance livemode flag. Customer reads
+require an explicitly expected account/mode; mismatch fails before reading the
+customer. The SDK response must name the exact customer, with matching livemode
+for an undeleted Customer. Account/mode is checked again after the customer response.
+Only an actual DeletedCustomer response records deleted:true; resource_missing,
+authorization failures and network failures remain errors. These calls require
+credentials permitting the corresponding SDK reads.
+
+Snapshots copy primitive inputs before asynchronous calls and return independent
+Date values. observedAt is local diagnostic time, not provider-clock evidence.
+The SDK client must remain bound to one immutable credential/request context.
+These are bounded multi-request observations, not an atomic provider transaction,
+a settled payment or license authority; native customer custody is stored separately. General
+sandbox namespace/cutover and real account/mode matrix acceptance remain required.
+No existing customer row is automatically adopted or backfilled by these readers.
+
+The mock owns a fresh nonsecret account ID per instance by default; accountId
+provides an explicit stable fixture identity. Its mode is always test. Independent
+setCustomerSnapshot state or ensureCustomer creates customer observations; invoice
+or webhook payloads never manufacture them. Seed account/customer state explicitly
+for recovery fixtures. Deleted customers are retained as observations; a later
+ensureCustomer creates a different customer ID rather than reviving the old one.
+
+
+## Durable customer custody and account namespaces
+
+Every tenant's financial namespace is pinned in `_voltro_billing_customer_accounts`
+before first checkout, closure or usage mutation. It records provider, observed
+account ID and mode. A different configured account/mode fails; no implicit
+account switch, expiry or automatic adoption is supported.
+
+`CustomerStore.bind` requires a positive, undeleted `fetchCustomerSnapshot`.
+`_voltro_billing_customer_custody` uniquely binds each provider/account/mode/customer
+to one tenant, and permits one current customer per tenant. Repeated binding of
+that exact owner is idempotent. `retire` requires positive provider deletion and
+keeps ownership permanently; later invoice observations use the retained owner,
+never invoice metadata or a new current customer's identity. Discovery cannot
+reactivate a retired customer. A new current link is refused while the tenant
+still has live native subscriptions requiring reconciliation.
+
+`fetchSubscriptionSnapshot` supplies direct customer-qualified observations,
+including canceled subscriptions. Stripe and mock implement it; custom providers
+must supply it for missing-list and retired-customer reconciliation. A null/404
+or omission from a live list does not prove cancellation. Retired reconciliation
+only mirrors positively canceled subscriptions of the retained customer; it
+never restores plan grants, meter prices or the current customer slot. Provider
+observations and native writes are not one transaction; concurrency, restart and
+dialect acceptance remain required.
+
+The current invoice table is `_voltro_billing_account_invoices`, whose identity
+includes provider account and mode. Both earlier invoice tables and the earlier
+customer table remain declared and intact. Apply `billingTables()` before the
+updated code serves requests. Stop old writers before cutover. Existing financial
+rows without a pinned namespace fail explicitly and require reviewed ownership
+migration; this release supplies no automatic migration or namespace-switch tool.
+Custom `CustomerStore` implementations must adopt `accountForTenant`,
+`assertAccount`, `reserveAccount`, `bind`, `retire` and scoped lookup/list methods;
+`upsert` and `removeByTenant` are removed.
+
+Webhook signature verification also retrieves the exact event through the SDK,
+checks account/mode and signed immutable event content, then uses an account-bound
+version-2 delivery receipt. SDK credentials must permit event retrieval. Older
+receipts are retained but never promoted across namespace versions. Callbacks
+remain at-least-once. These records establish custody/observations, not settled
+payment, financial completeness, sandbox namespace identity or license authority.
+
+
+## Retained-custody inventory
+
+`inspectBillingCustody(rootStore, { tenantId, pageSize?, maxRowsPerTable? })` is a
+trusted server/operator read utility, not an RPC or an adoption API. Authorize the
+operator and tenant first; invoke outside an existing transaction. Mandatory
+integrity reads cover the explicit tenant's original/current billing tables,
+including deletion/expiry states. Two complete bounded keyset sweeps run in one
+native transaction; changed content, query failures, duplicate IDs, foreign tenant
+rows and unsupported evidence fail rather than produce partial review output.
+
+The review-only result contains content/table/row SHA-256 digests, row IDs and
+existing provider identifiers, without raw financial payloads. Date values become
+ISO strings; unsafe numeric/non-JSON values fail rather than lose identity. Default
+page size is 200 (1–500), default per-table bound 5,000 (1–50,000); encoded limits
+are 4 MiB per row and 64 MiB per sweep. The digest excludes diagnostic observedAt.
+
+Equal read sweeps do not prove a writer barrier, schema readiness, complete
+restoration, provider state, original account ownership or settled financial
+history. Global receipts, provider history and application Cloud records remain
+separate inputs. No account/custody write occurs. The explicit original-evidence,
+approval/apply, adoption and account/environment cutover workflow is still required.
+
+
+## Account-bound invoice history pages
+
+`BillingProvider.listInvoiceHistory` is an optional read capability implemented by
+Stripe and mock. Inputs are `{ account, providerCustomerId, cursor?, limit? }`.
+Limit defaults to100 and must be an integer1–100. Each cursor retains account ID,
+mode, exact customer and afterInvoiceId. Wrong scope or malformed/repeated page
+identities fail; there is no fallback to the bounded listInvoices preview.
+
+Stripe reads account/mode before and after the page, verifies an incoming cursor's
+invoice belongs to that customer, and uses official SDK invoice pagination with
+no delivery-success or invoice-status filter. Paid, open, void, uncollectible and
+draft references are included. The page exposes invoices plus explicit nextCursor,
+account/customer and local observedAt. IDs, status, customer/mode, created dates,
+minor-unit amounts, currency and nullable HTTPS provider links are validated.
+Future unknown statuses fail explicitly. Omitted hosted/PDF links become null;
+missing identity/status never becomes an invented ID or unknown status.
+
+Server code can call `BillingService.invoiceHistory(tenantId, customerId, options)`
+for a positively owned current or retained customer. The service checks account
+and immutable native custody around the provider read. Authorize the caller first;
+no new public RPC is installed. Custom service implementations must add this
+method or fail explicitly. `reconcileInvoice` now publicly accepts an optional
+third exact customer ID for retained-owner observations; never ignore that identity
+in custom implementations.
+
+`listInvoices` and service.invoices remain recent previews (20 by default for
+built-in providers), not complete history or lifetime totals. Stripe and mock use
+the same validated page reader for those previews. The mock requires independent
+`setInvoiceHistory` state with original createdAt; setInvoiceSnapshot and webhook
+payloads do not create history or customer ownership. Seed all three independently
+when a fixture claims each plane.
+
+A page is a reference list, not complete invoice/line evidence or settled payment.
+A null nextCursor exhausts this traversal; pages are not an atomic provider snapshot
+or proof that future/late invoices cannot appear. Persist walk progress and every
+failed/pending reference before advancing, revisit drafts and new head entries,
+and reconcile finalized invoices with complete snapshots. That durable backfill,
+previous-successful-ACK recovery, full financial qualification and native/provider/
+restart/replica/browser/start acceptance remain required and are not completed by
+this read-only capability.
+
+
+### Durable invoice-history page admission
+
+`dataStoreInvoiceHistoryJournal(rootStore)` provides `begin(owner)`, `read(owner)`,
+`commitPage(expectedWalk, page)`, `restart(expectedWalk)` and
+`references(owner, { afterReferenceId?, limit? })`. The owner must already be an
+actual current or retained `CustomerRecord` in the same native namespace.
+No row is adopted from an event, metadata, old acknowledgement or current SDK
+credentials. Obtain account/customer-confirmed pages through `invoiceHistory`
+outside the native transaction; journal admission does not contact providers.
+
+A page and every invoice reference commit in one root-store transaction before
+cursor advancement. Native uniqueness, root locking, expected revision and
+readback protect the page boundary; a stale checkpoint returns null without
+writes. Repeated cursors or cross-page invoice IDs in one round refuse the
+whole page. Restart retains every prior page/reference and monotonically
+orders new pages, including new-head scans. Discovery keeps drafts and all
+supported invoice statuses without creating invoice observations, payments,
+licenses or settlement claims.
+
+`billingTables()` includes `billingInvoiceHistoryWalksTable`,
+`billingInvoiceHistoryPagesTable` and `billingInvoiceHistoryReferencesTable`.
+Custom schemas must include them too. The retained-custody roster includes all
+17 tables. Missing roots are not recreated over orphan receipts. Bounds and
+native aggregate counts reject missing pages/references; returned references
+are checked against their complete page and digest. These integrity reads
+inspect retained native indexes and counts; their cost grows with history and
+still needs real-dialect performance/recovery validation.
+
+`exhausted` only records the end of provider enumeration. A reference page's
+watermark and null next cursor describe its captured native read, not a global
+or financial completion receipt. Automatic scan scheduling and due-queue enumeration are still to be
+connected. Per-reference processing and durable results are described below. No existing `BillingService` method is promoted to automatic
+backfill by this primitive.
+
+After a stale `commitPage` result, discard the offered page and reread both the
+native checkpoint and the provider page for that exact cursor. Never relabel a
+captured page with a newer checkpoint or a restarted head.
+
+
+### Process a retained invoice reference
+
+`BillingService.processInvoiceHistoryReference(tenantId, customerId, referenceId)`
+verifies actual retained customer custody and the exact journal reference,
+then reads/reconciles the complete invoice through the existing provider path.
+The caller still authorizes access. This is a server method, not a new RPC or
+HTTP route. The reconciliation phase has a five-minute Effect timeout; timeout
+or interruption does not prove a dispatched SDK/database action stopped.
+
+`BillingStores` now requires `historyJournal` and `historyWork`. Use the same
+root as `customers`, `invoices` and Framework idempotency. `memoryStores()`
+uses these native adapters together on one actual InMemoryDataStore, including
+standard Framework receipt metadata. Custom schema assemblies must include
+`billingInvoiceHistoryWorkTable` and the standard `_voltro_idempotency` table;
+`billingTables()` includes the work table and retained-custody inventory now
+contains 17 tenant tables. Do not compose unrelated Memory ports for this flow.
+
+Work has durable queued/working/retry/deferred/observed state, logical attempt
+and execution counters, next-attempt time and an actual native observation
+ID/version. Framework claims and their standard heartbeat own the running
+execution. Completing that exact claim and the business acknowledgement share
+one native transaction; a reclaimed executor cannot publish a result. A
+completed receipt without its matching native work never manufactures an
+observation: a later attempt must reread the provider. Work results survive
+receipt expiry. Fresh reads/reconciliation may run more than once.
+
+Open invoices remain deferred; drafts and unconfirmed/error/timeout reads
+remain retryable after one minute. An observed work result is not payment,
+settlement, original-price or historical-license coverage. Reusing an observed
+result checks its actual native invoice ID/version and status; missing or
+rewound evidence queues a fresh attempt. Automatic discovery/due scheduling,
+startup/replica orchestration and full financial qualification are not part of it.
+
+
+### Bounded invoice work selection
+
+`historyWork.pending(owner, lane, now, { limit, cursor })` reads at most 100
+entries from an actual owned walk (25 by default). Use the independent
+`unprepared`, `ready` and `working` lanes: new references, due queued/retry/deferred
+work, and claimed executions whose stored retry time has arrived. Selection
+never acquires a claim. Dispatch still calls `processInvoiceHistoryReference`,
+which independently checks the current Framework receipt and native custody.
+An entry in `working` can still have a renewed live claim and return busy.
+
+Cursors belong to their retained walk and lane. Continue each lane separately;
+revisit its head in later passes so newly inserted work is included. A null
+cursor ends this bounded read, not invoice enumeration, pending work, payment
+or historical financial coverage. Unprepared selection uses a native
+anti-subquery instead of loading every old reference. Selected references are
+validated in one batch against their complete retained pages, sharing the
+journal's actual native integrity checks. Total retained-history/index cost
+still needs native performance measurement.
+
+This server store primitive does not start a worker. Automatic retained-customer
+inventory, due-queue dispatch, durable orchestration cursors, new-head rounds
+and startup/replica/shutdown integration remain required. Custom
+`InvoiceHistoryWorkStore` implementations must provide `pending`; a fabricated
+empty page is not a recovery implementation.
+
+
+### Current and retained customer inventory
+
+`customers.inventory(scope, { afterCustodyId, limit })` reads actual current
+and retired custody records in one exact provider account and mode. It does
+not change `customers.list(scope)`, which continues to list current customers.
+Pages default to 25 records and allow at most 100, with stable custody-ID
+continuation. A retained cursor stays usable when its customer is retired.
+Unknown or differently scoped cursors refuse; every returned record is checked
+against its independent native tenant/account intent and custody identity.
+Unqualified legacy customer rows refuse inventory rather than disappear behind
+an apparently empty current-account result.
+
+A null continuation only ends this account-bound read. Later passes must revisit
+the head for newly inserted IDs. It neither adopts an original account namespace
+nor establishes complete invoice/payment/license coverage. Inventory requires
+root server visibility, not a tenant-filtered request store. The standard custody
+table includes `byBillingCustomerCustodyInventory` for provider/account/mode/ID
+ordering; use normal reviewed schema migration. Existing rows need no rewritten
+ownership, and this index does not migrate unqualified historical data.
+
+Custom `CustomerStore` ports must provide `inventory` including retained retired
+ownership. `memoryCustomerStore()`, `memoryStores()` and `dataStoreStores(root)`
+share the native implementation. Automatic durable traversal, invoice dispatch
+and startup/replica/shutdown orchestration are still required; native dialect,
+concurrency/restore and growing-history performance remain unproven.
+
+
+### Durable bounded history passes
+
+`BillingService.reconcileInvoiceHistory()` connects native account/customer
+inventory, page admission and reference work in one bounded server pass: one
+current or retained customer, at most one provider page of 100 entries, and one
+entry from each independent unprepared/ready/working lane. Account and lane
+continuations live in `historyProgress` over the same native root. A fresh
+service and fresh adapters resume those positions. Positions use native
+revision CAS and validate retained customer/walk/cursor identity; they neither
+own work execution nor qualify financial completion. Actual work still uses
+Framework claims and fresh owned reconciliation. Unchanged traversal positions
+retain their native revision and update time; an idle pass is not a heartbeat
+write.
+
+A customer-specific failure remains unconfirmed and does not starve the other
+customers. Each lane revisits its head after reaching its current end. The
+pass has a two-minute Effect timeout; interruption stops the reference
+heartbeat, but does not prove an already dispatched SDK/database operation
+stopped. Invoice reads/writes remain bound to their captured store; a rebind
+detected during provider observation refuses acknowledgement before writing
+the replacement root.
+
+`BillingStores` requires `historyProgress`. Standard `billingTables()` adds
+`billingInvoiceHistoryScanAccountsTable` and `billingInvoiceHistoryDispatchTable`.
+The dispatch table joins the 17 tenant-addressable custody tables; the scan
+account table is global account-scoped traversal metadata and needs separate
+inventory alongside other global receipts. Both progress tables are
+destination-local during logical transfer. Default shared Memory and SQL stores
+use the same native adapters. Custom ports must persist actual progress and
+validate its pointers, not return fabricated completed/empty positions.
+
+This is a server service method, with no new HTTP/RPC/inspect entry point. It
+does not start an automatic lifecycle worker or restart exhausted enumeration
+at new heads. Startup/replica/shutdown scheduling, fresh new-head admission
+with bounded retained-receipt growth, original namespace adoption and full
+financial qualification remain required. Idle/advanced/contended results and
+counts describe a bounded pass only. Native rollback/isolation/restore,
+performance, provider/browser and normal development/compiled-start acceptance
+remain unproven.