@voltro/plugin-billing 0.85.0 → 0.87.0

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { default as default_2 } from 'stripe';
 import { Effect } from 'effect';
+import { IdempotencyClaim } from '@voltro/protocol';
+import { IdempotencyStore } from '@voltro/protocol';
 import { IncomingRequest } from '@voltro/plugin-webhooks';
 import { IncomingResponse } from '@voltro/plugin-webhooks';
 import { IncomingWebhookDescriptor } from '@voltro/plugin-webhooks';
@@ -26,16 +28,45 @@ export declare const assertBillingProductionReady: (input: {
     readonly redirectOrigins: ReadonlyArray<string> | undefined;
 }) => void;
 
+export declare const BILLING_CHECKOUT_OPERATIONS_TABLE = "_voltro_billing_checkout_operations";
+
+export declare const BILLING_CLOSE_OPERATIONS_TABLE = "_voltro_billing_close_operations";
+
+/** Tenant-addressable native inputs, including retained tables. Global delivery
+ * receipts, provider history and the application's own records need separate
+ * inventory; this roster does not assert their absence or financial completion. */
+export declare const BILLING_CUSTODY_INVENTORY_TABLES: ReadonlyArray<string>;
+
+export declare const BILLING_CUSTOMER_ACCOUNTS_TABLE = "_voltro_billing_customer_accounts";
+
+export declare const BILLING_CUSTOMER_CUSTODY_TABLE = "_voltro_billing_customer_custody";
+
 export declare const BILLING_CUSTOMERS_TABLE = "_voltro_billing_customers";
 
 export declare const BILLING_DUNNING_NOTICES_TABLE = "_voltro_billing_dunning_notices";
 
 export declare const BILLING_FLUSH_CLAIMS_TABLE = "_voltro_billing_flush_claims";
 
+export declare const BILLING_INVOICE_HISTORY_DISPATCH_TABLE = "_voltro_billing_invoice_history_dispatch";
+
+export declare const BILLING_INVOICE_HISTORY_PAGES_TABLE = "_voltro_billing_invoice_history_pages";
+
+export declare const BILLING_INVOICE_HISTORY_REFERENCES_TABLE = "_voltro_billing_invoice_history_references";
+
+export declare const BILLING_INVOICE_HISTORY_SCAN_ACCOUNTS_TABLE = "_voltro_billing_invoice_history_scan_accounts";
+
+export declare const BILLING_INVOICE_HISTORY_WALKS_TABLE = "_voltro_billing_invoice_history_walks";
+
+export declare const BILLING_INVOICE_HISTORY_WORK_TABLE = "_voltro_billing_invoice_history_work";
+
+export declare const BILLING_INVOICE_OBSERVATIONS_TABLE = "_voltro_billing_account_invoices";
+
 export declare const BILLING_INVOICES_TABLE = "_voltro_billing_invoices";
 
 export declare const BILLING_SUBSCRIPTIONS_TABLE = "_voltro_billing_subscriptions";
 
+export declare const BILLING_USAGE_EVENTS_TABLE = "_voltro_billing_usage_events";
+
 export declare const BILLING_USAGE_TABLE = "_voltro_billing_usage";
 
 /** The webhook id + the path the doc + plugin mount at. */
@@ -51,6 +82,35 @@ export declare const BILLING_WEBHOOK_PATH = "/billing/webhook";
  */
 export declare type BillingAction = 'checkout' | 'change' | 'resume' | 'portal' | 'cancel';
 
+export declare const billingCheckoutOperationsTable: BillingTable;
+
+export declare interface BillingCloseOperation {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly provider: string;
+    readonly scope: string;
+    readonly providerSubscriptionId: string | null;
+    readonly cancelAt: Date | null;
+    readonly createdAt: Date;
+    readonly usageSealed: number;
+}
+
+export declare const billingCloseOperationsTable: BillingTable;
+
+export declare interface BillingCloseStore {
+    readonly sealUsage: (tenantId: string) => Effect.Effect<BillingCloseOperation, BillingError>;
+    readonly getAccount: (tenantId: string) => Effect.Effect<BillingCloseOperation | null, BillingError>;
+    readonly reserveAccount: (tenantId: string, provider: string, createdAt: Date) => Effect.Effect<BillingCloseOperation, BillingError>;
+    readonly getSubscription: (tenantId: string, providerSubscriptionId: string) => Effect.Effect<BillingCloseOperation | null, BillingError>;
+    readonly reserveSubscription: (input: {
+        readonly tenantId: string;
+        readonly provider: string;
+        readonly providerSubscriptionId: string;
+        readonly cancelAt: Date;
+        readonly createdAt: Date;
+    }) => Effect.Effect<BillingCloseOperation, BillingError>;
+}
+
 /**
  * The shape every handler executor receives carries the resolved subject
  * under `ctx.request.subject` (mirrors `@voltro/plugin-rbac`'s
@@ -62,9 +122,55 @@ export declare interface BillingContext {
     };
 }
 
+export declare interface BillingCustodyInventory {
+    readonly format: 'voltro.billing-custody-inventory.v1';
+    readonly tenantId: string;
+    readonly digest: string;
+    readonly tables: ReadonlyArray<BillingCustodyInventoryTable>;
+    /** Diagnostic local time, excluded from the content digest. */
+    readonly observedAt: Date;
+    /** Two equal native read sweeps are observations, not a writer-stop proof,
+     * an atomic provider snapshot, an approval or original account authority. */
+    readonly purpose: 'review-only';
+}
+
+export declare interface BillingCustodyInventoryOptions {
+    readonly tenantId: string;
+    /** Defaults to 200; bounded to 1..500. */
+    readonly pageSize?: number;
+    /** Defaults to 5,000; bounded to 1..50,000 per table. Exceeding this limit
+     * fails the whole inventory rather than returning a truncated manifest. */
+    readonly maxRowsPerTable?: number;
+}
+
+export declare interface BillingCustodyInventoryRow {
+    readonly id: string;
+    /** Hash of every returned native field, not just the displayed references. */
+    readonly digest: string;
+    /** Existing native identifiers only; never a proposed customer/tenant mapping. */
+    readonly references: Readonly<Record<string, string>>;
+}
+
+export declare interface BillingCustodyInventoryTable {
+    readonly tableName: string;
+    readonly rowCount: number;
+    readonly digest: string;
+    readonly rows: ReadonlyArray<BillingCustodyInventoryRow>;
+}
+
+export declare const billingCustomerAccountsTable: BillingTable;
+
+export declare const billingCustomerCustodyTable: BillingTable;
+
 /** tenant ↔ provider customer link. */
 export declare const billingCustomersTable: BillingTable;
 
+/** Optional native receipt binding for standalone webhook mounts. */
+export declare interface BillingDeliveryReceipts {
+    readonly scope: string;
+    readonly store: () => IdempotencyStore;
+}
+
 /**
  * The sent-notice ledger. One row per `(tenant, episode, step)` — and the
  * UNIQUE over exactly those three is the send gate, not a report: a notice is
@@ -103,7 +209,7 @@ declare const BillingError_base: Schema.Class<BillingError, Schema.TaggedStruct<
 }>, YieldableError>;
 
 /**
- * The normalized event union a `BillingProvider.normalizeEvent` produces
+ * The tenant-resolved event union dispatched after `BillingService.applyEvent` accepts an event
  * from a verified, decoded provider webhook payload. `BillingService`
  * applies these to the DB rows — switching provider swaps the adapter;
  * the service + rows + entitlement engine are unchanged.
@@ -156,15 +262,51 @@ export declare type BillingEvent = {
     readonly occurredAt: Date | null;
 };
 
+/** Per-event side effect, run AFTER the row is updated. */
+export declare interface BillingEventDeliveryContext extends ProviderAccountIdentity {
+    readonly provider: string;
+    readonly providerEventId: string;
+    readonly receiptScope: string;
+}
+
 /** The event tag union — handy for `onEvent` keys. */
 export declare type BillingEventTag = BillingEvent['_tag'];
 
 /** One row per flush window — `windowKey` UNIQUE makes the INSERT the gate. */
 export declare const billingFlushClaimsTable: TableLike;
 
-/** Invoice history (money as integer minor units). */
+export declare const billingInvoiceHistoryDispatchTable: BillingTable;
+
+export declare const billingInvoiceHistoryPagesTable: BillingTable;
+
+export declare const billingInvoiceHistoryReferencesTable: BillingTable;
+
+export declare const billingInvoiceHistoryScanAccountsTable: BillingTable;
+
+export declare const billingInvoiceHistoryWalksTable: BillingTable;
+
+export declare const billingInvoiceHistoryWorkTable: BillingTable;
+
+export declare const billingInvoiceObservationsTable: BillingTable;
+
+/** Retained invoice-event history; current writes use billingInvoiceObservationsTable. */
 export declare const billingInvoicesTable: BillingTable;
 
+export declare type BillingInvoiceTrigger = BillingInvoiceTriggerFields & ({
+    readonly _tag: 'invoicePaid';
+} | {
+    readonly _tag: 'invoicePaymentFailed';
+});
+
+/** Verified provider invoice trigger. Tenant metadata is never ownership evidence. */
+declare interface BillingInvoiceTriggerFields {
+    readonly providerCustomerId: string;
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly occurredAt: Date | null;
+}
+
 export declare const billingPlugin: (options?: BillingPluginOptions) => VoltroPlugin;
 
 export declare interface BillingPluginOptions {
@@ -275,17 +417,14 @@ export declare interface BillingPluginOptions {
     readonly name?: string;
 }
 
-/**
- * Dumb adapter over a billing provider. Holds NO policy — checkout/portal
- * URL minting, usage push, and pure payload→event mapping only. The
- * `BillingService` wraps it with the entitlement engine, the DB rows, and
- * transient retry.
- *
- * `normalizeEvent` receives a payload whose signature was ALREADY verified
- * by @voltro/plugin-webhooks' mounter — this is pure mapping, never a
- * second signature check.
- */
 export declare interface BillingProvider {
+    /** Required by account-qualified custody consumers; absence is unsupported, not fallback authority. */
+    readonly fetchAccountIdentity?: () => Effect.Effect<ProviderAccountIdentity, BillingError>;
+    /** Must reject a different account/mode before reading customer data. A 404 is not positive deletion evidence. */
+    readonly fetchCustomerSnapshot?: (input: {
+        readonly account: ProviderAccountIdentity;
+        readonly providerCustomerId: string;
+    }) => Effect.Effect<ProviderCustomerSnapshot, BillingError>;
     readonly name: string;
     /** Whether the provider supports server-pushed metered usage. Stripe
      *  does (subscription-item usage records); a flat-plan provider may not.
@@ -296,9 +435,13 @@ export declare interface BillingProvider {
      *  meters map events to a customer by id, so an unlinked tenant's usage
      *  stays pending instead of being sent unattributable. */
     readonly usageRequiresCustomer?: boolean;
-    readonly createCheckoutSession: (input: CheckoutInput) => Effect.Effect<{
-        url: string;
-    }, BillingError>;
+    readonly createCheckoutSession: (input: CheckoutInput) => Effect.Effect<CheckoutSessionReceipt, BillingError>;
+    /** Read positive evidence for one exact persisted checkout intent. */
+    readonly findCheckoutSession: (input: {
+        readonly tenantId: string;
+        readonly providerCustomerId?: string;
+        readonly operationId: string;
+    }) => Effect.Effect<CheckoutSessionLookup, BillingError>;
     readonly createPortalSession: (input: PortalInput) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -330,6 +473,10 @@ export declare interface BillingProvider {
      * matters — the subscription's status right now does. Returns null when the
      * provider does not know the id.
      */
+    /** Direct customer-qualified observation, including terminal subscriptions.
+     * Null is absence, never proof of cancellation. Required for retired-customer
+     * reconciliation and for subscriptions absent from the live listing. */
+    readonly fetchSubscriptionSnapshot?: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionSnapshot | null, BillingError>;
     readonly fetchSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState | null, BillingError>;
     /**
      * Every live (not yet ended) subscription at the provider, optionally for
@@ -339,12 +486,19 @@ export declare interface BillingProvider {
     readonly listSubscriptions: (input: {
         readonly providerCustomerId?: string;
     }) => Effect.Effect<ReadonlyArray<ProviderSubscriptionSnapshot>, BillingError>;
-    /** End a subscription — at period end (reversible) or immediately with a
-     *  final invoice. Returns the provider's state afterwards. */
+    /** Quote the provider-clock settlement deadline after final usage dispatch.
+     * Persist it before requesting account-close cancellation. */
+    readonly prepareSubscriptionClose: (providerSubscriptionId: string) => Effect.Effect<{
+        readonly cancelAt: Date;
+    }, BillingError>;
     readonly cancelSubscription: (input: {
         readonly providerSubscriptionId: string;
-        readonly mode: CancelMode;
-    }) => Effect.Effect<ProviderSubscriptionState, BillingError>;
+    } & ({
+        readonly mode: 'periodEnd';
+    } | {
+        readonly mode: 'close';
+        readonly closeOperation: SubscriptionCloseOperation;
+    })) => Effect.Effect<ProviderSubscriptionState, BillingError>;
     /** Undo a period-end cancellation that has not taken effect yet. */
     readonly resumeSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState, BillingError>;
     /**
@@ -361,6 +515,7 @@ export declare interface BillingProvider {
      *  can be paid. Returns how many were expired. */
     readonly expireOpenCheckouts: (input: {
         readonly providerCustomerId: string;
+        readonly exceptOperationId?: string;
     }) => Effect.Effect<number, BillingError>;
     /** Add prices the subscription is missing (metered items), without
      *  proration. Prices already present are left alone. */
@@ -374,12 +529,22 @@ export declare interface BillingProvider {
      * the app keeps its own. Optional: a provider may model no customer email.
      */
     readonly customerEmail?: (providerCustomerId: string) => Effect.Effect<string | null, BillingError>;
-    /** The provider's invoice history. We mirror it for listing but never
-     *  render an invoice ourselves — `hostedUrl` / `pdfUrl` are theirs. */
+    /** Bounded recent invoice preview, not complete history. Provider-hosted
+     * links remain theirs; use listInvoiceHistory for explicit cursor traversal. */
     readonly listInvoices: (input: {
         readonly providerCustomerId: string;
         readonly limit?: number;
     }) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
+    /** Explicit bounded history pages, including draft and terminal statuses.
+     * Cursor exhaustion describes this traversal, not a stable global snapshot.
+     * Unsupported adapters must fail; the latest-preview list is no fallback. */
+    readonly listInvoiceHistory?: (input: ProviderInvoiceHistoryInput) => Effect.Effect<ProviderInvoiceHistoryPage, BillingError>;
+    /** Read one finalized invoice with every line, after confirming its customer.
+     * Absence means this provider cannot supply detailed invoice evidence. */
+    readonly fetchInvoiceSnapshot?: (input: {
+        readonly providerCustomerId: string;
+        readonly providerInvoiceId: string;
+    }) => Effect.Effect<ProviderInvoiceSnapshot, BillingError>;
     /**
      * Verify a webhook signature and decode the payload, using the provider's
      * OWN verification. Returns `null` when this provider does not do its own
@@ -390,10 +555,10 @@ export declare interface BillingProvider {
         readonly signatureHeader: string;
         readonly secret: string;
     }) => Effect.Effect<unknown, BillingError>;
-    /** Map a verified, decoded webhook payload to a `BillingEvent`, or
+    /** Map a verified, decoded webhook payload to a `BillingProviderEvent`, or
      *  `null` for an event type this provider doesn't model (handler
      *  no-ops, still 200). */
-    readonly normalizeEvent: (raw: unknown) => Effect.Effect<BillingEvent | null, BillingError>;
+    readonly normalizeEvent: (raw: unknown) => Effect.Effect<BillingProviderEvent | null, BillingError>;
     /**
      * Who and when a verified payload is about: the provider customer it names
      * and when the provider created it. The webhook syncs that customer from a
@@ -410,11 +575,22 @@ export declare interface BillingProvider {
      * it keeps them (Stripe: 30 days) — what an outage of the endpoint left
      * behind. Optional: a provider without it has no catch-up.
      */
-    readonly listUndeliveredEvents?: () => Effect.Effect<ReadonlyArray<UndeliveredEvent>, BillingError>;
+    readonly listUndeliveredEvents?: (input: {
+        readonly cursor: string | null;
+        readonly limit: number;
+    }) => Effect.Effect<UndeliveredEventPage, BillingError>;
 }
 
+/** Invoice ownership is resolved from native customer links before dispatch. */
+export declare type BillingProviderEvent = Exclude<BillingEvent, {
+    readonly _tag: 'invoicePaid' | 'invoicePaymentFailed';
+}> | BillingInvoiceTrigger;
+
 export declare type BillingProviderName = 'stripe' | 'mock';
 
+/** Retained unqualified observations are not adopted by the current writer. */
+export declare const billingRetainedInvoiceObservationsTable: BillingTable;
+
 /** The billing service Tag — `const billing = yield* BillingService`. */
 export declare class BillingService extends BillingService_base {
 }
@@ -521,6 +697,8 @@ export declare interface BillingServiceShape {
     readonly consumeEntitlement: (tenantId: string, key: string, cost: number) => Effect.Effect<void, BillingError | EntitlementExceeded>;
     /** Record metered usage locally; flushed to the provider in batches. */
     readonly reportUsage: (tenantId: string, key: string, qty: number) => Effect.Effect<void, BillingError>;
+    /** Atomically retain an occurrence receipt and increment its original UTC month. */
+    readonly reportUsageEvent: (event: MeteredUsageEvent) => Effect.Effect<void, BillingError>;
     /** Flush all pending local usage counters to the provider. */
     readonly flushUsage: () => Effect.Effect<void, BillingError>;
     /** What a plan/seat change WOULD cost, from the provider's own invoice
@@ -530,8 +708,27 @@ export declare interface BillingServiceShape {
         readonly plan?: PlanId;
         readonly quantity?: number;
     }) => Effect.Effect<SubscriptionChange, BillingError>;
-    /** The provider's invoice history for this tenant. */
+    /** Bounded recent provider invoice preview for this tenant, not history coverage. */
     readonly invoices: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
+    /** Read history for an exact current or retained customer owned by the tenant.
+     * Does not create custody or persist observations. The caller authorizes access. */
+    readonly invoiceHistory: (tenantId: string, providerCustomerId: string, options?: {
+        readonly cursor?: ProviderInvoiceHistoryCursor;
+        readonly limit?: number;
+    }) => Effect.Effect<ProviderInvoiceHistoryPage, BillingError>;
+    /** Fresh detailed provider evidence for this tenant's current linked customer.
+     * This read neither grants entitlements nor replaces native reconciliation. */
+    readonly invoiceSnapshot: (tenantId: string, providerInvoiceId: string) => Effect.Effect<ProviderInvoiceSnapshot, BillingError>;
+    /** Persist and read back a complete owned observation. A lost revision race
+     * repeats the provider read; event payloads never replace provider evidence. */
+    readonly reconcileInvoice: (tenantId: string, providerInvoiceId: string, expectedCustomerId?: string) => Effect.Effect<InvoiceObservation, BillingError>;
+    /** One bounded durable account/customer pass. Counts are work observations,
+     * not global, payment or historical financial completion. */
+    readonly reconcileInvoiceHistory: () => Effect.Effect<InvoiceHistoryPassResult, BillingError>;
+    /** Process one retained owned history reference with fresh provider/native
+     * reads and a fenced durable result. Open/draft/error work stays pending;
+     * an observed result is not settlement or historical entitlement coverage. */
+    readonly processInvoiceHistoryReference: (tenantId: string, providerCustomerId: string, referenceId: string) => Effect.Effect<InvoiceHistoryReferenceResult, BillingError>;
     /** Mint a provider-hosted checkout URL for `plan`. */
     readonly startCheckout: (input: {
         readonly tenantId: string;
@@ -540,6 +737,9 @@ export declare interface BillingServiceShape {
         readonly cancelUrl: string;
         /** Seats to buy up front. Omit for 1. */
         readonly quantity?: number;
+        /** Server-call authority check repeated after waits, before provider work.
+         * Native RPC routes supply their current declared-guard check. */
+        readonly authorize?: () => Effect.Effect<void, BillingError>;
     }) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -589,8 +789,8 @@ export declare interface BillingServiceShape {
      * load. Every call that changes what a tenant pays already runs it first.
      */
     readonly syncTenant: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
-    /** Apply a normalized provider event to the DB rows (idempotent upsert). */
-    readonly applyEvent: (event: BillingEvent) => Effect.Effect<void, BillingError>;
+    /** Apply a verified provider trigger and return its native tenant-resolved event. */
+    readonly applyEvent: (event: BillingProviderEvent) => Effect.Effect<BillingEvent, BillingError>;
     /**
      * Change the tenant's plan mid-cycle. Computes a TIME-BASED prorated
      * settlement on the amount difference for the unused remainder of the
@@ -610,9 +810,14 @@ export declare interface BillingServiceShape {
 }
 
 export declare interface BillingStores {
+    readonly closures: BillingCloseStore;
+    readonly checkouts: CheckoutOperationStore;
     readonly customers: CustomerStore;
     readonly subscriptions: SubscriptionStore;
     readonly invoices: InvoiceStore;
+    readonly historyJournal: InvoiceHistoryJournal;
+    readonly historyWork: InvoiceHistoryWorkStore;
+    readonly historyProgress: InvoiceHistoryProgressStore;
     readonly usage: UsageStore;
     /** The dunning sent-notice ledger — the send gate, not a report. */
     readonly dunningNotices: DunningNoticeStore;
@@ -634,6 +839,8 @@ export declare interface BillingTable extends TableLike {
 
 export declare const billingTables: () => ReadonlyArray<BillingTable>;
 
+export declare const billingUsageEventsTable: BillingTable;
+
 /** Per-tenant metered counters driving the entitlement engine. */
 export declare const billingUsageTable: BillingTable;
 
@@ -648,6 +855,8 @@ declare interface BillingWebhookOptions {
     readonly provider: BillingProvider;
     readonly service: BillingServiceShape;
     readonly onEvent?: OnEventMap;
+    /** Shared native receipt binding; standalone mounts otherwise retain process memory only. */
+    readonly receipts?: BillingDeliveryReceipts;
     /** The signing secret. It is BOTH the secret the mount's generic HMAC check
      *  verifies with AND the one the provider's own verifier (Stripe's
      *  `constructEvent`) uses. Null → the mount answers 503: an unverifiable
@@ -717,6 +926,12 @@ export declare type CatalogFinding = {
 
 export declare interface CheckoutInput {
     readonly tenantId: string;
+    /** Identity of one logical checkout request. Providers that support request
+     * idempotency must forward it unchanged across transport retries. The
+     * caller owns persistence and must not reuse it for different parameters. */
+    readonly idempotencyKey?: string;
+    /** Fixed deadline of a persisted intent; providers enforce it on creation. */
+    readonly expiresAt?: Date;
     /** Provider price id to subscribe to. */
     readonly priceId: string;
     /** Usage-based prices added next to `priceId` (no quantity). */
@@ -737,6 +952,65 @@ export declare interface CheckoutInput {
     readonly trialDays?: number;
 }
 
+export declare interface CheckoutOperation {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly provider: string;
+    readonly requestDigest: string;
+    readonly plan: string;
+    readonly quantity: number;
+    readonly providerCustomerId: string | null;
+    readonly providerSessionId: string | null;
+    readonly phase: CheckoutPhase;
+    readonly revision: number;
+    readonly active: number | null;
+    readonly slot: string;
+    readonly createdAt: Date;
+    readonly expiresAt: Date;
+    readonly updatedAt: Date;
+}
+
+export declare interface CheckoutOperationStore {
+    readonly reserve: (input: CheckoutReservation) => Effect.Effect<CheckoutOperation, BillingError>;
+    readonly getActive: (tenantId: string) => Effect.Effect<CheckoutOperation | null, BillingError>;
+    readonly patch: (operationId: string, patch: {
+        readonly phase?: CheckoutPhase;
+        readonly providerCustomerId?: string;
+        readonly providerSessionId?: string;
+    }) => Effect.Effect<CheckoutOperation, BillingError>;
+}
+
+export declare type CheckoutPhase = 'preparing' | 'creating' | 'ready' | 'completed' | 'expired' | 'retired';
+
+export declare type CheckoutReservation = Pick<CheckoutOperation, 'tenantId' | 'provider' | 'requestDigest' | 'plan' | 'quantity' | 'createdAt' | 'expiresAt'>;
+
+export declare interface CheckoutSessionLookup {
+    readonly receipt: CheckoutSessionReceipt | null;
+    /** Provider-clock evidence, never the application host's clock. */
+    readonly observedAt: Date | null;
+}
+
+/**
+ * Dumb adapter over a billing provider. Holds NO policy — checkout/portal
+ * URL minting, usage push, and pure payload→event mapping only. The
+ * `BillingService` wraps it with the entitlement engine, the DB rows, and
+ * transient retry.
+ *
+ * `normalizeEvent` receives a payload whose signature was ALREADY verified
+ * by @voltro/plugin-webhooks' mounter — this is pure mapping, never a
+ * second signature check.
+ */
+export declare interface CheckoutSessionReceipt {
+    readonly id: string;
+    readonly operationId: string | null;
+    readonly tenantId: string | null;
+    readonly providerCustomerId: string | null;
+    readonly providerSubscriptionId: string | null;
+    readonly status: 'open' | 'complete' | 'expired';
+    readonly url: string | null;
+    readonly expiresAt: Date;
+}
+
 /**
  * Try to claim the flush window. INSERT-wins: the first replica's row is the
  * winner; a racing replica's `insertIgnore` returns that same row, so it sees a
@@ -749,29 +1023,68 @@ export declare const claimFlushWindow: (store: DataStore, windowKey: string, rep
 /** What `closeAccount` did at the provider. */
 export declare interface CloseAccountResult {
     readonly tenantId: string;
-    /** Provider subscriptions ended (immediately, with a final invoice). */
+    /** Provider subscriptions positively confirmed canceled. A scheduled close remains pending. */
     readonly canceled: ReadonlyArray<string>;
 }
 
-declare interface CustomerRecord {
+export declare interface CustomerBinding extends CustomerScope {
     readonly tenantId: string;
-    readonly provider: string;
     readonly providerCustomerId: string;
 }
 
+export declare interface CustomerCustodyInventoryPage {
+    readonly customers: ReadonlyArray<CustomerRecord>;
+    /** Read continuation only; not global or financial completion. */
+    readonly nextCustodyId: string | null;
+}
+
+declare interface CustomerRecord extends CustomerBinding {
+    readonly id: string;
+    readonly retiredAt: Date | null;
+}
+
+export declare interface CustomerScope {
+    readonly provider: string;
+    readonly account: ProviderAccountIdentity;
+}
+
 export declare interface CustomerStore {
-    readonly upsert: (record: CustomerRecord) => Effect.Effect<void, BillingError>;
+    /** Immutable financial namespace intent, separate from customer ownership. */
+    readonly accountForTenant: (tenantId: string) => Effect.Effect<CustomerScope | null, BillingError>;
+    readonly assertAccount: (tenantId: string, scope: CustomerScope) => Effect.Effect<boolean, BillingError>;
+    readonly reserveAccount: (tenantId: string, scope: CustomerScope) => Effect.Effect<void, BillingError>;
+    /** Never overwrites ownership or resurrects a retired customer. */
+    readonly bind: (binding: CustomerBinding, snapshot: ProviderCustomerSnapshot) => Effect.Effect<CustomerRecord, BillingError>;
     readonly getByTenant: (tenantId: string) => Effect.Effect<CustomerRecord | null, BillingError>;
-    readonly getByProviderCustomerId: (providerCustomerId: string) => Effect.Effect<CustomerRecord | null, BillingError>;
-    /** Every linked customer — the provider reconcile's per-customer pass. */
-    readonly list: () => Effect.Effect<ReadonlyArray<CustomerRecord>, BillingError>;
-    /** Drop the link to a provider customer that no longer exists. Returns the
-     *  tenant it belonged to, or null when it was not linked. */
-    readonly removeByProviderCustomerId: (providerCustomerId: string) => Effect.Effect<string | null, BillingError>;
+    /** Includes retained retired ownership, within this exact provider account/mode. */
+    readonly getByProviderCustomerId: (providerCustomerId: string, scope: CustomerScope) => Effect.Effect<CustomerRecord | null, BillingError>;
+    readonly list: (scope: CustomerScope) => Effect.Effect<ReadonlyArray<CustomerRecord>, BillingError>;
+    /** Bounded exact-account inventory including retained retired customers.
+     * Restart at the head in later passes to discover newly inserted custody. */
+    readonly inventory: (scope: CustomerScope, input?: {
+        readonly afterCustodyId?: string;
+        readonly limit?: number;
+    }) => Effect.Effect<CustomerCustodyInventoryPage, BillingError>;
+    /** Only positive provider deletion retires this exact customer; history is retained. */
+    readonly retire: (scope: CustomerScope, snapshot: ProviderCustomerSnapshot) => Effect.Effect<CustomerRecord | null, BillingError>;
 }
 
+export declare const dataStoreBillingCloseStore: (store: DataStore) => BillingCloseStore;
+
+export declare const dataStoreCheckoutOperationStore: (store: DataStore) => CheckoutOperationStore;
+
 export declare const dataStoreDunningNoticeStore: (store: DataStore) => DunningNoticeStore;
 
+export declare const dataStoreInvoiceHistoryJournal: (store: DataStore) => InvoiceHistoryJournal;
+
+/** Traversal hints never qualify an invoice or own its execution. Native journal,
+ * custody and work claims remain authoritative; every update is revision fenced. */
+export declare const dataStoreInvoiceHistoryProgressStore: (store: DataStore) => InvoiceHistoryProgressStore;
+
+/** Per-reference results live in this native table, not the expiring Framework
+ * receipt. Receipt ownership and the business acknowledgement commit together. */
+export declare const dataStoreInvoiceHistoryWorkStore: (store: DataStore) => InvoiceHistoryWorkStore;
+
 export declare const dataStoreStores: (store: DataStore) => BillingStores;
 
 /**
@@ -1092,6 +1405,184 @@ export declare const formEncode: (params: Readonly<Record<string, unknown>>) =>
 /** When the grace for an episode runs out. */
 export declare const graceEndOf: (pastDueSince: Date, graceHours: number) => Date;
 
+/** Trusted operator/server utility. The caller authorizes tenant access and
+ * supplies a root DataStore, outside any application transaction. It deliberately
+ * uses integrity reads, explicit tenant predicates and all deletion/expiry scopes.
+ * No provider call, customer binding, account reservation or native write occurs.
+ * A custom store without integrityQuery is unsupported; query is no fallback. */
+export declare const inspectBillingCustody: (store: DataStore, input: BillingCustodyInventoryOptions) => Effect.Effect<BillingCustodyInventory, BillingError>;
+
+/** Immutable native ownership of one provider invoice, not payment authority. */
+export declare interface InvoiceBinding extends ProviderAccountIdentity {
+    readonly tenantId: string;
+    readonly provider: string;
+    readonly providerCustomerId: string;
+    readonly providerInvoiceId: string;
+}
+
+export declare interface InvoiceHistoryAccountProgress extends CustomerScope {
+    readonly id: string;
+    readonly revision: number;
+    readonly afterCustodyId: string | null;
+    readonly updatedAt: Date;
+}
+
+export declare interface InvoiceHistoryCustomerProgress extends InvoiceHistoryDispatchPosition {
+    readonly id: string;
+    readonly revision: number;
+    readonly owner: CustomerRecord;
+    readonly updatedAt: Date;
+}
+
+export declare interface InvoiceHistoryDispatchPosition {
+    readonly walkId: string | null;
+    readonly cursors: Readonly<Record<InvoiceHistoryWorkLane, string | null>>;
+}
+
+export declare interface InvoiceHistoryJournal {
+    readonly begin: (owner: CustomerRecord) => Effect.Effect<InvoiceHistoryWalk, BillingError>;
+    readonly read: (owner: CustomerRecord) => Effect.Effect<InvoiceHistoryWalk | null, BillingError>;
+    /** Null means a stale checkpoint with no committed change. Discard that
+     * offered page and reread both native checkpoint and provider page. */
+    readonly commitPage: (expected: InvoiceHistoryWalk, page: ProviderInvoiceHistoryPage) => Effect.Effect<InvoiceHistoryWalk | null, BillingError>;
+    /** Retain every old page/reference when a cursor is lost or a new head is scanned. */
+    readonly restart: (expected: InvoiceHistoryWalk) => Effect.Effect<InvoiceHistoryWalk | null, BillingError>;
+    readonly reference: (owner: CustomerRecord, referenceId: string) => Effect.Effect<InvoiceHistoryJournalReference | null, BillingError>;
+    readonly references: (owner: CustomerRecord, input?: {
+        readonly afterReferenceId?: string;
+        readonly limit?: number;
+    }) => Effect.Effect<InvoiceHistoryReferencePage, BillingError>;
+}
+
+export declare interface InvoiceHistoryJournalOwner extends CustomerBinding {
+    readonly custodyId: string;
+}
+
+export declare interface InvoiceHistoryJournalReference extends InvoiceHistoryJournalOwner {
+    readonly id: string;
+    readonly walkId: string;
+    readonly round: number;
+    readonly pageId: string;
+    readonly pageOrdinal: number;
+    readonly position: number;
+    readonly providerInvoiceId: string;
+    readonly discoveryStatus: ProviderInvoiceHistoryEntry['status'];
+    readonly providerCreatedAt: Date;
+}
+
+export declare interface InvoiceHistoryPassResult {
+    readonly kind: 'idle' | 'advanced' | 'contended';
+    readonly customerCustodyId: string | null;
+    readonly admittedPages: number;
+    readonly observed: number;
+    readonly deferred: number;
+    readonly busy: number;
+    readonly unconfirmed: number;
+}
+
+export declare interface InvoiceHistoryProgressStore {
+    readonly account: (scope: CustomerScope, now: Date) => Effect.Effect<InvoiceHistoryAccountProgress, BillingError>;
+    readonly advanceAccount: (expected: InvoiceHistoryAccountProgress, afterCustodyId: string | null, now: Date) => Effect.Effect<InvoiceHistoryAccountProgress | null, BillingError>;
+    readonly customer: (owner: CustomerRecord, now: Date) => Effect.Effect<InvoiceHistoryCustomerProgress, BillingError>;
+    readonly advanceCustomer: (expected: InvoiceHistoryCustomerProgress, next: InvoiceHistoryDispatchPosition, now: Date) => Effect.Effect<InvoiceHistoryCustomerProgress | null, BillingError>;
+}
+
+export declare interface InvoiceHistoryReferencePage {
+    readonly references: ReadonlyArray<InvoiceHistoryJournalReference>;
+    readonly nextReferenceId: string | null;
+    /** This read's admitted-page bound, never a global completion receipt. */
+    readonly watermarkPageOrdinal: number;
+    readonly walkRevision: number;
+}
+
+export declare interface InvoiceHistoryReferenceResult {
+    readonly kind: 'observed' | 'deferred' | 'busy';
+    readonly work: InvoiceHistoryWork;
+}
+
+export declare interface InvoiceHistoryWalk extends InvoiceHistoryJournalOwner {
+    readonly id: string;
+    readonly revision: number;
+    readonly round: number;
+    /** Monotonic across rounds; restarting never renumbers admitted pages. */
+    readonly pageOrdinal: number;
+    readonly cursor: ProviderInvoiceHistoryCursor | null;
+    /** Provider enumeration ended, not processing or financial completion. */
+    readonly exhausted: boolean;
+}
+
+export declare interface InvoiceHistoryWork extends InvoiceHistoryJournalOwner {
+    readonly id: string;
+    readonly walkId: string;
+    readonly referenceId: string;
+    readonly providerInvoiceId: string;
+    readonly revision: number;
+    /** Logical attempts and acquired execution identities survive restarts. */
+    readonly attempt: number;
+    readonly executions: number;
+    readonly state: 'queued' | 'working' | 'retry' | 'deferred' | 'observed';
+    readonly activeClaimId: string | null;
+    readonly nextAttemptAt: Date;
+    readonly lastOutcome: 'unconfirmed' | 'open' | 'observed';
+    /** An observed native version, never a payment or entitlement receipt. */
+    readonly observationId: string | null;
+    readonly observationRevision: number | null;
+    readonly updatedAt: Date;
+}
+
+export declare type InvoiceHistoryWorkAcquisition = {
+    readonly kind: 'claimed';
+    readonly work: InvoiceHistoryWork;
+    readonly attempt: InvoiceHistoryWorkAttempt;
+} | {
+    readonly kind: 'busy' | 'observed';
+    readonly work: InvoiceHistoryWork;
+};
+
+export declare interface InvoiceHistoryWorkAttempt {
+    readonly work: InvoiceHistoryWork;
+    readonly claim: IdempotencyClaim;
+}
+
+export declare interface InvoiceHistoryWorkCursor {
+    readonly lane: InvoiceHistoryWorkLane;
+    readonly walkId: string;
+    readonly afterId: string;
+}
+
+export declare type InvoiceHistoryWorkLane = 'unprepared' | 'ready' | 'working';
+
+export declare interface InvoiceHistoryWorkPage {
+    readonly entries: ReadonlyArray<{
+        readonly reference: InvoiceHistoryJournalReference;
+        readonly work: InvoiceHistoryWork | null;
+    }>;
+    /** Read pagination only; null never establishes global/financial completion. */
+    readonly nextCursor: InvoiceHistoryWorkCursor | null;
+    readonly walkRevision: number;
+}
+
+export declare interface InvoiceHistoryWorkStore {
+    /** Independent bounded lanes keep new references separate from due retries
+     * and claimed executions. Selection grants no execution ownership. */
+    readonly pending: (owner: CustomerRecord, lane: InvoiceHistoryWorkLane, now: Date, input?: {
+        readonly limit?: number;
+        readonly cursor?: InvoiceHistoryWorkCursor;
+    }) => Effect.Effect<InvoiceHistoryWorkPage, BillingError>;
+    readonly claim: (owner: CustomerRecord, referenceId: string, now: Date) => Effect.Effect<InvoiceHistoryWorkAcquisition, BillingError>;
+    readonly observed: (owner: CustomerRecord, attempt: InvoiceHistoryWorkAttempt, observation: InvoiceObservation, now: Date) => Effect.Effect<InvoiceHistoryWork | null, BillingError>;
+    readonly failed: (owner: CustomerRecord, attempt: InvoiceHistoryWorkAttempt, now: Date) => Effect.Effect<InvoiceHistoryWork | null, BillingError>;
+    /** Uses the shared Framework heartbeat. Stopping never proves SDK work stopped. */
+    readonly hold: (attempt: InvoiceHistoryWorkAttempt, now?: () => number) => () => void;
+}
+
+export declare interface InvoiceObservation extends InvoiceBinding {
+    readonly id: string;
+    readonly identityKey: string;
+    readonly revision: number;
+    readonly snapshot: ProviderInvoiceSnapshot;
+}
+
 declare interface InvoiceRecord {
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
@@ -1103,28 +1594,12 @@ declare interface InvoiceRecord {
     readonly pdfUrl: string | null;
 }
 
-declare interface InvoiceRecord_2 {
-    readonly tenantId: string;
-    readonly provider: string;
-    readonly providerInvoiceId: string;
-    readonly amountMinor: number;
-    readonly currency: string;
-    /** 'paid' | 'open' | 'uncollectible' | 'void'. */
-    readonly status: string;
-    /** Provider-event timestamp this `status` came from; null when undated. */
-    readonly statusEventAt: Date | null;
-}
-
 export declare interface InvoiceStore {
-    /**
-     * Upsert by `providerInvoiceId` (idempotent under webhook replay), with the
-     * same stale-event guard the subscription row carries: a late-delivered
-     * `payment_failed` must not flip an invoice that has since been paid back to
-     * `'open'`, which is what a naive last-write-wins mirror does under Stripe's
-     * unordered delivery.
-     */
-    readonly upsert: (invoice: InvoiceRecord_2) => Effect.Effect<void, BillingError>;
-    readonly listByTenant: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord_2>, BillingError>;
+    /** Read the revision before a provider observation, without reserving unproven ownership. */
+    readonly get: (binding: InvoiceBinding) => Effect.Effect<InvoiceObservation | null, BillingError>;
+    /** Insert only if absent, or compare the previously read revision. False requires
+     * another native AND provider read; never retry a captured payload alone. */
+    readonly complete: (binding: InvoiceBinding, expected: InvoiceObservation | null, snapshot: ProviderInvoiceSnapshot) => Effect.Effect<boolean, BillingError>;
 }
 
 /** Is this a real deployment boot? Only an explicitly dev-like NODE_ENV is not. */
@@ -1143,6 +1618,10 @@ export declare const isStaleStatusEvent: (existing: Date | null, incoming: Date
  */
 export declare type LockoutMode = 'hard' | 'soft';
 
+export declare const memoryBillingCloseStore: () => BillingCloseStore;
+
+export declare const memoryCheckoutOperationStore: () => CheckoutOperationStore;
+
 export declare const memoryDunningNoticeStore: () => DunningNoticeStore;
 
 export declare const memoryStores: () => BillingStores;
@@ -1150,6 +1629,15 @@ export declare const memoryStores: () => BillingStores;
 /** Replace (or add) `NAME=value` lines; every other line is kept as it was. */
 export declare const mergeEnvFile: (text: string, values: Readonly<Record<string, string>>) => string;
 
+export declare interface MeteredUsageEvent {
+    readonly tenantId: string;
+    readonly entitlementKey: string;
+    readonly quantity: number;
+    readonly occurredAt: Date;
+    /** Stable tenant-scoped occurrence identity, reused unchanged on every retry. */
+    readonly idempotencyKey: string;
+}
+
 /** `meterKey → source`. The meterKey is the entitlement/usage key reported to
  *  the provider (`billing.reportUsage(tenant, meterKey, qty)`). */
 declare type MeteringConfig = Readonly<Record<string, MeterSource>>;
@@ -1179,11 +1667,19 @@ declare type MeterSource =
  * In-memory provider with deterministic outputs. Checkout/portal URLs are
  * stable functions of the input so tests can assert on them; usage pushes
  * are recorded on `pushed` for assertion. `normalizeEvent` accepts the
- * already-normalized `BillingEvent` shape directly (the test feeds events
- * straight through) OR a `{ type, data }` envelope mirroring the Stripe
- * mapping, so the same webhook path exercises the mock end-to-end.
+ * verified `BillingProviderEvent` shape directly (the test feeds events
+ * straight through). Invoice triggers carry providerCustomerId; an event never seeds provider state.
  */
 export declare interface MockProvider extends BillingProvider {
+    readonly fetchAccountIdentity: NonNullable<BillingProvider['fetchAccountIdentity']>;
+    readonly fetchCustomerSnapshot: NonNullable<BillingProvider['fetchCustomerSnapshot']>;
+    /** Independent provider state; an event or invoice is not customer evidence. */
+    readonly setCustomerSnapshot: (snapshot: ProviderCustomerSnapshot) => void;
+    /** Supply actual simulated provider state; webhook payloads never create this evidence. */
+    readonly setInvoiceSnapshot: (snapshot: ProviderInvoiceSnapshot) => void;
+    /** Independent provider history, including drafts and original creation dates.
+     * Detailed snapshots and event payloads do not manufacture this history. */
+    readonly setInvoiceHistory: (entries: ReadonlyArray<ProviderInvoiceHistoryEntry>) => void;
     /** Recorded usage pushes — assertion surface for tests. */
     readonly pushed: ReadonlyArray<UsagePush>;
     /** Recorded subscription updates. The point of asserting on these is that
@@ -1232,6 +1728,9 @@ export declare interface MockProvider extends BillingProvider {
 export declare const mockProvider: (options?: {
     readonly baseUrl?: string;
     readonly supportsMeteredUsage?: boolean;
+    readonly now?: () => Date;
+    /** Explicit stable account for controlled fixtures; otherwise this mock instance owns a fresh account. */
+    readonly accountId?: string;
 }) => MockProvider;
 
 /** A monetary amount: integer minor units + ISO-4217 currency. */
@@ -1262,10 +1761,9 @@ declare interface MountBillingWebhookOptions extends BillingWebhookOptions {
  * not model (the handler no-ops and still answers 200, which is what stops
  * Stripe retrying an event we will never care about).
  */
-export declare const normalizeStripeEvent: (event: default_2.Event, resolvePrice?: (priceId: string) => string | null) => BillingEvent | null;
+export declare const normalizeStripeEvent: (event: default_2.Event, resolvePrice?: (priceId: string) => string | null) => BillingProviderEvent | null;
 
-/** Per-event side effect, run AFTER the row is updated. */
-export declare type OnEventMap = Readonly<Record<string, (event: BillingEvent) => Effect.Effect<void, unknown>>>;
+export declare type OnEventMap = Readonly<Record<string, (event: BillingEvent, delivery?: BillingEventDeliveryContext) => Effect.Effect<void, unknown>>>;
 
 /** Findings the account still differs by (after `apply`: what it could not fix). */
 export declare const openFindings: (findings: ProvisionResult["findings"]) => (CatalogFinding & {
@@ -1348,6 +1846,88 @@ export declare const portalParams: (portal: StripeCatalog["portal"], env: Stripe
     readonly priceId: string;
 }>) => Record<string, unknown>;
 
+/** Provider-observed account/mode, not a configured key prefix or tenant hint. */
+export declare interface ProviderAccountIdentity {
+    readonly providerAccountId: string;
+    readonly livemode: boolean;
+}
+
+/** A positive customer response in an explicitly expected provider namespace.
+ * observedAt is local observation time, never provider-clock settlement evidence. */
+export declare interface ProviderCustomerSnapshot {
+    readonly account: ProviderAccountIdentity;
+    readonly providerCustomerId: string;
+    readonly deleted: boolean;
+    readonly observedAt: Date;
+}
+
+/** Explicit provider namespace/customer binding; not a bearer authorization. */
+export declare interface ProviderInvoiceHistoryCursor extends ProviderAccountIdentity {
+    readonly providerCustomerId: string;
+    readonly afterInvoiceId: string;
+}
+
+/** One history reference, not a complete invoice observation or payment proof. */
+export declare interface ProviderInvoiceHistoryEntry extends InvoiceRecord {
+    readonly providerCustomerId: string;
+    readonly livemode: boolean;
+    readonly status: 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
+    readonly createdAt: Date;
+}
+
+export declare interface ProviderInvoiceHistoryInput {
+    readonly account: ProviderAccountIdentity;
+    readonly providerCustomerId: string;
+    readonly cursor?: ProviderInvoiceHistoryCursor;
+    /** 1..100; defaults to 100. Invalid values fail rather than clamp. */
+    readonly limit?: number;
+}
+
+export declare interface ProviderInvoiceHistoryPage {
+    readonly account: ProviderAccountIdentity;
+    readonly providerCustomerId: string;
+    readonly invoices: ReadonlyArray<ProviderInvoiceHistoryEntry>;
+    readonly nextCursor: ProviderInvoiceHistoryCursor | null;
+    /** Local observation time, not provider-clock or financial coverage evidence. */
+    readonly observedAt: Date;
+}
+
+export declare interface ProviderInvoiceLineSnapshot {
+    readonly providerLineId: string;
+    readonly providerSubscriptionId: string | null;
+    readonly providerSubscriptionItemId: string | null;
+    readonly providerPriceId: string | null;
+    readonly amountMinor: number;
+    readonly currency: string;
+    /** Exact provider decimal; absent precision must never be replaced by a truncated integer. */
+    readonly quantityDecimal: string | null;
+    /** Provider period bounds are inclusive; they are not paid-through authority. */
+    readonly periodStart: Date;
+    readonly periodEnd: Date;
+    /** Null means the provider did not identify the line's origin. */
+    readonly proration: boolean | null;
+}
+
+/** A complete provider observation, not an entitlement or a payment receipt. */
+export declare interface ProviderInvoiceSnapshot {
+    readonly providerInvoiceId: string;
+    readonly providerCustomerId: string;
+    readonly providerSubscriptionId: string | null;
+    readonly providerRevisionId: string | null;
+    readonly status: 'open' | 'paid' | 'uncollectible' | 'void';
+    readonly livemode: boolean;
+    readonly currency: string;
+    readonly amountDueMinor: number;
+    readonly amountPaidMinor: number;
+    readonly amountRemainingMinor: number;
+    readonly finalizedAt: Date;
+    readonly paidAt: Date | null;
+    /** Local read completion time, never a provider clock or entitlement deadline. */
+    readonly observedAt: Date;
+    /** All pages. A bounded or failed read must fail instead of returning a prefix. */
+    readonly lines: ReadonlyArray<ProviderInvoiceLineSnapshot>;
+}
+
 /** What `reconcileFromProvider` found and corrected. */
 export declare interface ProviderReconcileResult {
     /** Subscriptions compared (provider-listed plus local rows it did not list). */
@@ -1523,6 +2103,11 @@ export declare const runStripeProvision: (catalog: StripeCatalog, argv: Readonly
     readonly vars?: NodeJS.ProcessEnv;
 }) => Promise<number>;
 
+/** The row that speaks for a tenant: a live one first, then the newest. */
+export declare const selectCurrentSubscription: <T extends {
+    readonly status: string;
+}>(rows: ReadonlyArray<T>) => T | null;
+
 /** What only a human can settle before an environment sells. */
 export declare const sellingReadiness: (input: {
     readonly catalog: StripeCatalog;
@@ -1532,6 +2117,10 @@ export declare const sellingReadiness: (input: {
     readonly activeRegistrations: ReadonlyArray<string>;
 }) => ReadonlyArray<CatalogFinding>;
 
+export declare interface StoredUsageEvent extends MeteredUsageEvent {
+    readonly period: string;
+}
+
 /**
  * A mutable holder so `bindDataStore` can swap the stores AFTER the service
  * layer is built. The service reads `holder.stores` on every call rather
@@ -1822,6 +2411,12 @@ declare interface SubscriptionChangeResult {
     readonly currentPeriodEnd: Date | null;
 }
 
+export declare interface SubscriptionCloseOperation {
+    readonly id: string;
+    /** Provider-clock deadline captured after final usage dispatch. */
+    readonly cancelAt: Date;
+}
+
 /**
  * Raised when dunning has locked a tenant out — the grace period after a
  * provider-confirmed past-due has expired. Distinct from
@@ -1910,12 +2505,20 @@ declare interface SubscriptionUpdateInput {
 }
 
 /** An event the provider failed to deliver, reduced to what a catch-up needs. */
-declare interface UndeliveredEvent {
+export declare interface UndeliveredEvent {
     readonly id: string;
+    readonly event: BillingProviderEvent | null;
+    /** A recognized provider event could not be normalized; retry/report it, never fall back to discovery. */
+    readonly rejected?: true;
     readonly providerCustomerId: string | null;
     readonly createdAt: Date | null;
 }
 
+export declare interface UndeliveredEventPage {
+    readonly events: ReadonlyArray<UndeliveredEvent>;
+    readonly nextCursor: string | null;
+}
+
 export declare interface UsagePush {
     readonly tenantId: string;
     readonly entitlementKey: string;
@@ -1942,6 +2545,7 @@ declare interface UsageRow {
 }
 
 export declare interface UsageStore {
+    readonly recordEvent: (event: StoredUsageEvent) => Effect.Effect<void, BillingError>;
     /** Current used count for `(tenant, key, period)`; 0 when no row. */
     readonly used: (tenantId: string, key: string, period: string) => Effect.Effect<number, BillingError>;
     /**