@voltro/plugin-billing 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -18,6 +18,8 @@ import { VoltroPlugin } from '@voltro/protocol';
 
 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_INVOICES_TABLE = "_voltro_billing_invoices";
@@ -45,6 +47,17 @@ export declare interface BillingContext {
 /** tenant ↔ provider customer link. */
 export declare const billingCustomersTable: BillingTable;
 
+/**
+ * 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
+ * CLAIMED by `insertIgnore` before it is sent, so a duplicated webhook
+ * delivery loses the race and sends nothing.
+ */
+export declare const billingDunningNoticesTable: TableLike & {
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+    readonly appliedIndexes: ReadonlyArray<TableIndex>;
+};
+
 /**
  * A billing failure. `transient: true` marks failures the service retries
  * (network blip talking to the provider); non-transient failures (a 4xx
@@ -82,26 +95,33 @@ export declare type BillingEvent = {
     readonly currentPeriodStart?: Date | null;
     readonly currentPeriodEnd: Date | null;
     readonly cancelAt: Date | null;
+    /** When the PROVIDER emitted this — the out-of-order guard. See
+     *  `occurredAt` on the union below. */
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'subscriptionCanceled';
     readonly tenantId: string;
     readonly providerSubscriptionId: string;
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'invoicePaid';
     readonly tenantId: string;
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
     readonly currency: string;
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'invoicePaymentFailed';
     readonly tenantId: string;
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
     readonly currency: string;
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'customerLinked';
     readonly tenantId: string;
     readonly providerCustomerId: string;
+    readonly occurredAt: Date | null;
 };
 
 /** The event tag union — handy for `onEvent` keys. */
@@ -137,6 +157,19 @@ export declare interface BillingPluginOptions {
      *  self-scheduled flush — call `billing.flushUsage()` from your own
      *  `*.cron.tsx` instead (e.g. for cluster-coordinated flushing). */
     readonly flushIntervalMs?: number;
+    /**
+     * Dunning: the past-due notification sequence, the grace clock, and the
+     * lockout. Composed on the PROVIDER'S outcomes — nothing here retries a
+     * payment or schedules one; Stripe owns the retry cadence and each attempt
+     * it makes is the tick that evaluates whichever steps have come due.
+     *
+     * Defaults: enabled, a 7-day grace, a 3-step sequence (0h / 72h / 144h), a
+     * hard lockout — and NO transport, so until `notify` is wired the sequence
+     * only claims + logs. Every number is overridable here and by env
+     * (`VOLTRO_BILLING_GRACE_HOURS`, `VOLTRO_BILLING_DUNNING_STEP_HOURS`,
+     * `VOLTRO_BILLING_LOCKOUT`, `VOLTRO_BILLING_DUNNING`).
+     */
+    readonly dunning?: DunningConfig;
     /** Typed per-event side effects, run AFTER the row is updated. */
     readonly onEvent?: OnEventMap;
     /** Transient-failure retries on provider calls. Default 3. */
@@ -163,7 +196,25 @@ export declare interface BillingPluginOptions {
      * static `plans` registry. Absent → static registry only.
      */
     readonly resolveEntitlementLimit?: (tenantId: string, key: string) => Effect.Effect<number | null, BillingError>;
-    /** Disambiguates multiple instances of this plugin in one app. */
+    /**
+     * Namespace for this plugin's rpc tags + inspect endpoints. Default `billing`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     *
+     * The cost, stated because nothing else states it: the local and cloud
+     * dashboards fetch this plugin's panel at the DEFAULT slug, so an aliased
+     * install keeps working while its dashboard panel 404s. Alias to escape a
+     * collision, not for taste.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-billing#analytics`). Not a rename — for that use
+     * `alias`.
+     */
     readonly name?: string;
 }
 
@@ -208,6 +259,23 @@ export declare interface BillingProvider {
      * is a support ticket.
      */
     readonly previewSubscriptionChange: (input: SubscriptionUpdateInput) => Effect.Effect<SubscriptionChangeResult, BillingError>;
+    /**
+     * The provider's CURRENT view of a subscription — a direct read, not an
+     * event body.
+     *
+     * This is the method dunning refuses to lock a customer out without. An
+     * `invoice.payment_failed` can arrive after the retry that succeeded, a
+     * redelivery can arrive days late, and neither carries the state that
+     * matters — the subscription's status right now does. Returns null when the
+     * provider does not know the id.
+     */
+    readonly fetchSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState | null, BillingError>;
+    /**
+     * The billing contact the PROVIDER has on file, when it has one. Used as the
+     * dunning recipient of last resort — `dunning.resolveRecipient` wins when
+     * 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. */
     readonly listInvoices: (input: {
@@ -259,8 +327,14 @@ export declare interface BillingServiceOptions {
         /** Free-trial length. The provider runs the trial and reports `trialing`. */
         readonly trialDays?: number;
     };
-    /** Clock injection for deterministic period windowing in tests. */
+    /** Clock injection for deterministic period + grace windowing in tests. */
     readonly now?: () => Date;
+    /**
+     * Dunning policy, already resolved against env by `billingPlugin`. Omitted
+     * → the documented defaults (7-day grace, 3-step sequence, hard lockout, no
+     * transport, so the sequence logs and sends nothing).
+     */
+    readonly dunning?: ResolvedDunningConfig;
     /**
      * Optional per-tenant entitlement-limit override — the seam for a
      * cloud-issued license snapshot (e.g. `@voltro/plugin-licensing`'s
@@ -276,6 +350,31 @@ export declare interface BillingServiceShape {
     readonly subscription: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
     /** Resolve the tenant's plan id; defaults to `'free'` when no row. */
     readonly plan: (tenantId: string) => Effect.Effect<PlanId, BillingError>;
+    /**
+     * "Is this tenant entitled right now?" — the one truthful answer, dunning
+     * state included. A PURE read of the local row (no provider call, no write),
+     * so it is safe on a hot path: the grace clock is a column and the lockout
+     * is derived from it, never a flag some job had to remember to set.
+     */
+    readonly entitlementStatus: (tenantId: string) => Effect.Effect<EntitlementStatus, BillingError>;
+    /**
+     * Re-derive dunning state for a tenant FROM THE PROVIDER, then fire whatever
+     * notification steps are now due (each at most once per episode).
+     *
+     * Runs automatically after every subscription/invoice event, which is what
+     * makes the provider's own retry cadence the schedule. Call it directly only
+     * to force a re-check (e.g. from a support tool). It is idempotent, it never
+     * charges anything, and it never asks the provider to retry.
+     */
+    readonly reconcileDunning: (tenantId: string) => Effect.Effect<EntitlementStatus, BillingError>;
+    /**
+     * Reconcile every past-due tenant. Optional — the event path already covers
+     * the normal case; a sweep exists so a step configured for a moment the
+     * provider happens not to emit an event (and a reconcile missed during a
+     * provider outage) still lands. Wire it from your own `*.cron.tsx` if you
+     * want that; nothing schedules it for you. Returns the number reconciled.
+     */
+    readonly dunningSweep: () => Effect.Effect<number, BillingError>;
     /** Pure read — would `cost` units of `key` be allowed? No mutation. */
     readonly checkEntitlement: (tenantId: string, key: string, cost: number) => Effect.Effect<EntitlementDecision, BillingError>;
     /** Check + decrement, atomically. Fails `EntitlementExceeded` over-limit. */
@@ -331,6 +430,8 @@ export declare interface BillingStores {
     readonly subscriptions: SubscriptionStore;
     readonly invoices: InvoiceStore;
     readonly usage: UsageStore;
+    /** The dunning sent-notice ledger — the send gate, not a report. */
+    readonly dunningNotices: DunningNoticeStore;
 }
 
 /** One active subscription per tenant. */
@@ -363,8 +464,10 @@ declare interface BillingWebhookOptions {
     readonly provider: BillingProvider;
     readonly service: BillingServiceShape;
     readonly onEvent?: OnEventMap;
-    /** The signing secret, so the provider can run its OWN verification on the
-     *  raw bytes. Null → only the mount's generic check applies. */
+    /** 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
+     *  billing webhook must not reach subscription state. */
     readonly webhookSecret?: string | null;
 }
 
@@ -433,11 +536,166 @@ export declare interface CustomerStore {
     readonly getByTenant: (tenantId: string) => Effect.Effect<CustomerRecord | null, BillingError>;
 }
 
+export declare const dataStoreDunningNoticeStore: (store: DataStore) => DunningNoticeStore;
+
 export declare const dataStoreStores: (store: DataStore) => BillingStores;
 
+/**
+ * The default sequence: on the first failure, again after 3 days, and a final
+ * warning 24h before the default grace runs out. Every number here is a
+ * default the framework picked on the app's behalf, so every one of them is
+ * overridable in `app.config.ts` AND by env.
+ */
+export declare const DEFAULT_DUNNING_STEPS: ReadonlyArray<DunningStep>;
+
+/** Default grace: 7 days from the first confirmed past-due. */
+export declare const DEFAULT_GRACE_HOURS = 168;
+
+/** Default lockout once grace expires. */
+export declare const DEFAULT_LOCKOUT: LockoutMode;
+
 /** The free/fallback plan id every app implicitly has. */
 export declare const DEFAULT_PLAN: PlanId;
 
+/**
+ * The default notice copy. Deliberately plain, unbranded, and link-light —
+ * it exists so the sequence is usable the moment `notify` is wired, not so
+ * apps ship it unchanged. Override by rendering from the structured fields in
+ * a custom `notify`.
+ */
+export declare const defaultDunningEmail: (notice: {
+    readonly stepId: string;
+    readonly locked: boolean;
+    readonly graceEndsAt: Date;
+    readonly portalUrl: string | null;
+}) => {
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+};
+
+/** The steps whose `afterHours` have elapsed. Ledger claims — not this
+ *  function — decide which of them actually SEND. */
+export declare const dueSteps: (steps: ReadonlyArray<DunningStep>, pastDueSince: Date, now: Date) => ReadonlyArray<DunningStep>;
+
+/** The synthetic step fired the first time an episode is observed LOCKED. */
+export declare const DUNNING_LOCK_STEP_ID = "locked";
+
+export declare interface DunningConfig {
+    /** Master switch. Default true — but with no `notify` the sequence only
+     *  logs, so nothing is sent until the app wires a transport. */
+    readonly enabled?: boolean;
+    /** Hours of grace from the first PROVIDER-CONFIRMED past-due. Default 168. */
+    readonly graceHours?: number;
+    /** The sequence. Default `DEFAULT_DUNNING_STEPS`. */
+    readonly steps?: ReadonlyArray<DunningStep>;
+    /** Hard (limits fall to free) or soft (report only). Default `'hard'`. */
+    readonly lockout?: LockoutMode;
+    /**
+     * Where a notice goes. Absent → the sequence is inert (it logs, claims the
+     * ledger, and sends nothing), which is the correct default for an
+     * irreversible action the framework cannot address on the app's behalf.
+     * `dunningMailNotifier(mail)` bridges to `@voltro/plugin-mail`.
+     */
+    readonly notify?: (notice: DunningNotice) => Effect.Effect<void, unknown>;
+    /**
+     * The billing contact for a tenant. Takes precedence over the provider's
+     * customer email — an app that keeps its own billing contact should say so
+     * rather than have Stripe's copy of an address win.
+     */
+    readonly resolveRecipient?: (tenantId: string) => Effect.Effect<string | null, BillingError>;
+    /** When set, each notice carries a freshly minted provider portal URL that
+     *  returns here — the one link a dunning email actually needs. */
+    readonly portalReturnUrl?: string;
+}
+
+/** The slice of `@voltro/plugin-mail`'s `MailService` a notice needs. Typed
+ *  STRUCTURALLY so this package carries no dependency on the mail plugin (the
+ *  `@voltro/plugin-auth` `mailSender` precedent). */
+export declare interface DunningMailLike {
+    readonly send: (message: {
+        readonly to: string;
+        readonly subject: string;
+        readonly html: string;
+        readonly text?: string;
+    }) => Effect.Effect<unknown, unknown>;
+}
+
+/**
+ * Bridge `notify` to `@voltro/plugin-mail`:
+ *
+ * ```ts
+ * const mail = yield* MailService
+ * billingPlugin({ dunning: { notify: dunningMailNotifier(mail) } })
+ * ```
+ *
+ * A notice with no resolvable recipient is skipped rather than failing — the
+ * ledger already recorded the step, and a hard failure here would only mean
+ * the webhook that triggered it gets retried into the same dead end.
+ */
+export declare const dunningMailNotifier: (mail: DunningMailLike) => ((notice: DunningNotice) => Effect.Effect<void, unknown>);
+
+/** The rendered notice handed to `notify`. */
+export declare interface DunningNotice {
+    /** The step's id, or `'locked'` for the lockout notice. */
+    readonly stepId: string;
+    readonly tenantId: string;
+    /** Resolved billing contact, or null when neither `resolveRecipient` nor the
+     *  provider could name one. A null `to` is still delivered to `notify` — an
+     *  app may route it in-product rather than by email. */
+    readonly to: string | null;
+    /** The plan the tenant is SUBSCRIBED to (not the locked-down effective one). */
+    readonly plan: PlanId;
+    readonly status: SubscriptionStatus;
+    readonly pastDueSince: Date;
+    readonly graceEndsAt: Date;
+    /** True once grace has run out — i.e. this is (or follows) the lockout. */
+    readonly locked: boolean;
+    readonly lockout: LockoutMode;
+    /** Provider-hosted billing portal, when `portalReturnUrl` is configured. */
+    readonly portalUrl: string | null;
+    /** Ready-to-send default copy. A custom `notify` may ignore all three. */
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+}
+
+export declare interface DunningNoticeRow {
+    readonly tenantId: string;
+    readonly episode: string;
+    readonly stepId: string;
+    readonly sentAt: Date | null;
+}
+
+export declare interface DunningNoticeStore {
+    /**
+     * Claim `(tenant, episode, step)`. `true` means THIS caller won and must
+     * send; `false` means someone already claimed it — a duplicate delivery, a
+     * second replica, or a re-reconcile.
+     *
+     * The claim happens BEFORE the send, deliberately. The failure mode of
+     * claim-then-send is a notice that is claimed but never delivered (one
+     * missing email); the failure mode of send-then-claim is a customer
+     * receiving the same dunning email twice. Only one of those is a real-world
+     * harm, so the ordering is not arbitrary.
+     */
+    readonly claim: (tenantId: string, episode: string, stepId: string, at: Date) => Effect.Effect<boolean, BillingError>;
+    /** Steps already claimed for an episode — assertion + inspect surface. */
+    readonly sentSteps: (tenantId: string, episode: string) => Effect.Effect<ReadonlyArray<DunningNoticeRow>, BillingError>;
+}
+
+/**
+ * One step of the sequence. `afterHours` is measured from `pastDueSince` —
+ * NOT from the previous step and NOT from a retry attempt, so a step cannot be
+ * pulled forward or pushed back by how often the provider happens to retry.
+ */
+export declare interface DunningStep {
+    /** Stable ledger key. Changing it re-opens the step for every live episode. */
+    readonly id: string;
+    /** Hours after the tenant went past-due at which this step becomes due. */
+    readonly afterHours: number;
+}
+
 /** A registry with a single zero-quota `free` plan — the zero-config default. */
 export declare const emptyPlanRegistry: () => PlanRegistry;
 
@@ -491,6 +749,49 @@ declare const EntitlementExceeded_base: Schema.TaggedErrorClass<EntitlementExcee
 /** An entitlement limit: a finite quota or the unbounded `'unlimited'`. */
 export declare type EntitlementLimit = number | 'unlimited';
 
+/** The truthful "is this tenant entitled right now" answer. */
+export declare interface EntitlementStatus {
+    readonly tenantId: string;
+    /** The plan whose LIMITS apply right now — `'free'` under a hard lockout. */
+    readonly plan: PlanId;
+    /** The plan the tenant is subscribed to, lockout or not. */
+    readonly billedPlan: PlanId;
+    readonly status: SubscriptionStatus | 'none';
+    /**
+     * False ONLY when dunning has locked this tenant out. A canceled
+     * subscription is not a lockout — it is simply the free tier, and reporting
+     * it as "not entitled" would conflate "never paid" with "stopped paying".
+     */
+    readonly entitled: boolean;
+    /** Past due, but still inside the grace window. */
+    readonly inGrace: boolean;
+    /** When grace runs out; null when the tenant is not past due — or when the
+     *  provider has not confirmed the past-due yet, in which case the tenant is
+     *  in grace with no expiry rather than locked. */
+    readonly graceEndsAt: Date | null;
+    /** Non-null iff locked out — the instant grace expired. */
+    readonly lockedSince: Date | null;
+    readonly lockout: LockoutMode;
+}
+
+/** The episode a `pastDueSince` identifies. Recovery clears the column, so the
+ *  next failure necessarily produces a different key. */
+export declare const episodeKeyOf: (pastDueSince: Date) => string;
+
+/**
+ * Derive the entitlement state from the subscription row. PURE — no I/O, no
+ * writes, so every read path can call it on the hot path.
+ *
+ * The one subtlety worth stating out loud: a `pastDue` row whose
+ * `pastDueSince` is null reports as IN GRACE, never locked. `pastDueSince` is
+ * written only after the provider itself confirmed the past-due (see
+ * `service.ts`'s `reconcileDunning`), so a `pastDue` status that arrived by
+ * webhook alone — or one whose reconcile failed against an unreachable
+ * provider — can never lock a customer out. Locking on unverified event data
+ * is the one failure mode here with a real-world cost.
+ */
+export declare const evaluateBillingEntitlement: (sub: Subscription | null, config: Pick<ResolvedDunningConfig, "graceHours" | "lockout" | "enabled">, now: Date, tenantId?: string) => EntitlementStatus;
+
 /**
  * Pure entitlement decision. `limit` is `Infinity` for an `'unlimited'`
  * plan. `'unlimited'` and any non-positive cost always allow without
@@ -502,6 +803,9 @@ export declare const evaluateEntitlement: (entitlement: string, limit: number, u
  *  flushing within the same interval land on the same key → one wins. */
 export declare const flushWindowKey: (nowMs: number, intervalMs: number) => string;
 
+/** When the grace for an episode runs out. */
+export declare const graceEndOf: (pastDueSince: Date, graceHours: number) => Date;
+
 declare interface InvoiceRecord {
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
@@ -521,14 +825,43 @@ declare interface InvoiceRecord_2 {
     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). */
+    /**
+     * 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>;
 }
 
+/**
+ * Is `incoming` older than what the row already reflects? Undated events never
+ * displace a dated one, and a dated event always wins over an undated row —
+ * that ordering is what makes a hand-built (undated) payload usable in tests
+ * without letting it stomp production ordering.
+ */
+export declare const isStaleStatusEvent: (existing: Date | null, incoming: Date | null) => boolean;
+
+/**
+ * What "locked" means once the grace period is over.
+ *
+ *   - `'hard'` — entitlement limits fall to the `'free'` plan's. The app needs
+ *     no new code: every existing `requireEntitlement` / `enforce` check
+ *     starts answering with the free tier's numbers.
+ *   - `'soft'` — limits stay on the paid plan; only `entitlementStatus()`
+ *     reports the lockout, so the app decides what to withhold.
+ */
+export declare type LockoutMode = 'hard' | 'soft';
+
+export declare const memoryDunningNoticeStore: () => DunningNoticeStore;
+
 export declare const memoryStores: () => BillingStores;
 
 /** `meterKey → source`. The meterKey is the entitlement/usage key reported to
@@ -571,6 +904,17 @@ export declare interface MockProvider extends BillingProvider {
      *  a change which never reaches the provider is a change the customer is
      *  not billed for — the exact defect this contract was widened to fix. */
     readonly updates: ReadonlyArray<SubscriptionUpdateInput>;
+    /**
+     * Set what the provider will report for `fetchSubscription`. This is the
+     * mock's most load-bearing seam: dunning refuses to act on an event body and
+     * reads the provider instead, so a test that wants "the retry actually
+     * succeeded" says so HERE, not by crafting a webhook.
+     */
+    readonly setSubscription: (providerSubscriptionId: string, state: ProviderSubscriptionState | null) => void;
+    /** Set the customer email `customerEmail` will report. */
+    readonly setCustomerEmail: (providerCustomerId: string, email: string | null) => void;
+    /** Every `fetchSubscription` id asked for — proves the reconcile happened. */
+    readonly fetched: ReadonlyArray<string>;
 }
 
 export declare const mockProvider: (options?: {
@@ -594,7 +938,8 @@ export declare interface Money {
 export declare const mountBillingWebhook: (options: MountBillingWebhookOptions) => (request: IncomingRequest) => Promise<IncomingResponse>;
 
 declare interface MountBillingWebhookOptions extends BillingWebhookOptions {
-    /** The provider webhook signing secret (`whsec_…`). Null skips verification. */
+    /** The provider webhook signing secret (`whsec_…`). Null does NOT skip
+     *  verification — every delivery answers 503 until it is configured. */
     readonly webhookSecret: string | null;
     /** Optional idempotency-cache override (tests pass a fresh cache). */
     readonly idempotencyCache?: Parameters<typeof mountIncomingWebhook>[1]['idempotencyCache'];
@@ -663,6 +1008,40 @@ export declare interface PortalInput {
     readonly returnUrl: string;
 }
 
+/** The provider's CURRENT view of a subscription — read directly, not from an
+ *  event body. `reconcileDunning` asks for this before it will lock anyone
+ *  out. */
+export declare interface ProviderSubscriptionState {
+    readonly status: SubscriptionStatus;
+    /** Null when the provider cannot map the price to one of our plans. */
+    readonly plan: PlanId | null;
+    readonly quantity: number;
+    readonly currentPeriodStart: Date | null;
+    readonly currentPeriodEnd: Date | null;
+    readonly cancelAt: Date | null;
+}
+
+/**
+ * In-handler DUNNING guard: refuse when the tenant's grace period has run out.
+ *
+ * Orthogonal to `requireEntitlement`, which answers "do you have quota left".
+ * This answers "did you pay". A tenant with plenty of quota can still be locked
+ * out, and a tenant in grace is NOT locked out — that is the whole point of the
+ * grace window.
+ *
+ * Under `lockout: 'hard'` the quota guards already degrade to the free plan's
+ * limits on their own, so reach for this when a feature has no numeric quota to
+ * degrade (an export, a webhook target, an admin action).
+ *
+ * ```ts
+ * export default (input, ctx) => Effect.gen(function* () {
+ *   yield* requireEntitled(ctx)
+ *   // …
+ * })
+ * ```
+ */
+export declare const requireEntitled: (ctx: BillingContext) => Effect.Effect<void, BillingError | SubscriptionLocked, BillingService>;
+
 /**
  * In-handler entitlement guard. Resolves `ctx.request.subject.tenantId`,
  * consumes `cost` units of `key`, and fails with the typed
@@ -680,6 +1059,28 @@ export declare interface PortalInput {
  */
 export declare const requireEntitlement: (ctx: BillingContext, key: string, cost: number) => Effect.Effect<void, BillingError | EntitlementExceeded, BillingService>;
 
+/** A `DunningConfig` with every default resolved and every number concrete. */
+export declare interface ResolvedDunningConfig {
+    readonly enabled: boolean;
+    readonly graceHours: number;
+    readonly steps: ReadonlyArray<DunningStep>;
+    readonly lockout: LockoutMode;
+    readonly notify?: (notice: DunningNotice) => Effect.Effect<void, unknown>;
+    readonly resolveRecipient?: (tenantId: string) => Effect.Effect<string | null, BillingError>;
+    readonly portalReturnUrl?: string;
+}
+
+/**
+ * Resolve the config against `app.config.ts` first and env second.
+ *
+ * Env overrides exist because these numbers gate money-adjacent behaviour and
+ * an operator must be able to widen the grace on a live incident without a
+ * redeploy. They FAIL LOUD rather than falling back to a default: a typo'd
+ * `VOLTRO_BILLING_GRACE_HOURS` that silently means "7 days" is precisely the
+ * kind of quiet wrong number this repo has been bitten by.
+ */
+export declare const resolveDunningConfig: (config: DunningConfig | undefined, env: NodeJS.ProcessEnv) => ResolvedDunningConfig;
+
 /**
  * Resolve `options.provider` to a concrete `BillingProvider`. A passed
  * object is used verbatim. `'stripe'` needs an api key (option or
@@ -743,6 +1144,27 @@ export declare interface Subscription {
     readonly currentPeriodEnd: Date | null;
     /** When the subscription is scheduled to cancel; null if not scheduled. */
     readonly cancelAt: Date | null;
+    /**
+     * When this tenant went past due — the dunning grace clock, and the identity
+     * of the current dunning episode.
+     *
+     * Written ONLY by a provider-confirmed reconcile, never straight off a
+     * webhook: it is the value the lockout is derived from, and locking a
+     * customer out on an event body alone is the one mistake here with a
+     * real-world cost. Cleared the moment the provider reports the
+     * subscription healthy again, which is also what cancels the rest of the
+     * notification sequence.
+     */
+    readonly pastDueSince: Date | null;
+    /**
+     * The provider-event timestamp the current `status` came from — the
+     * out-of-order guard. Provider webhooks are at-least-once AND unordered, so
+     * an event that is older than what the row already reflects is DROPPED
+     * rather than applied (a stale `active` must not un-do a `pastDue`, and a
+     * stale `pastDue` must not resurrect a resolved one). Null on rows written
+     * before any dated event.
+     */
+    readonly statusEventAt: Date | null;
 }
 
 /** The outcome of a mid-cycle plan/seat change — the prorated settlement. */
@@ -767,23 +1189,68 @@ declare interface SubscriptionChangeResult {
     readonly currentPeriodEnd: Date | null;
 }
 
+/**
+ * Raised when dunning has locked a tenant out — the grace period after a
+ * provider-confirmed past-due has expired. Distinct from
+ * `EntitlementExceeded`: that one means "you used your quota", this one means
+ * "you did not pay". Registered via `errorSchemas`, so a client can branch on
+ * `_tag === 'SubscriptionLocked'` and route the user to the billing portal
+ * rather than showing a generic failure.
+ *
+ * Dates cross the wire as ISO strings — a `Schema.DateFromSelf` would not
+ * survive the JSON boundary the error union is encoded through.
+ */
+export declare class SubscriptionLocked extends SubscriptionLocked_base {
+}
+
+declare const SubscriptionLocked_base: Schema.TaggedErrorClass<SubscriptionLocked, "SubscriptionLocked", {
+    readonly _tag: Schema.tag<"SubscriptionLocked">;
+} & {
+    tenantId: typeof Schema.String;
+    /** The subscription status at the time of the refusal (`'pastDue'`). */
+    status: typeof Schema.String;
+    /** ISO timestamp at which the grace period expired. */
+    lockedSince: typeof Schema.String;
+    /** `'hard'` (limits fell to the free plan) or `'soft'` (report only). */
+    lockout: typeof Schema.String;
+}>;
+
+/** Fields a mid-cycle / reconcile patch may set on the tenant's row. */
+export declare interface SubscriptionPatch {
+    readonly plan?: PlanId;
+    readonly quantity?: number;
+    readonly status?: SubscriptionStatus;
+    readonly currentPeriodStart?: Date | null;
+    readonly currentPeriodEnd?: Date | null;
+    /** The dunning grace clock. `null` clears it (recovery). */
+    readonly pastDueSince?: Date | null;
+    /** Provider-event (or direct-read) timestamp the `status` came from. */
+    readonly statusEventAt?: Date | null;
+}
+
 export declare type SubscriptionStatus = 'active' | 'trialing' | 'pastDue' | 'canceled' | 'incomplete';
 
 export declare interface SubscriptionStore {
-    /** Upsert by `providerSubscriptionId` — the webhook's idempotency anchor. */
+    /**
+     * Upsert by `providerSubscriptionId` — the webhook's idempotency anchor.
+     *
+     * STALE-EVENT GUARD: when the incoming `statusEventAt` is OLDER than the one
+     * already on the row, the whole upsert is skipped. Provider webhooks are
+     * at-least-once and unordered, so without this a redelivered `active` from
+     * before a decline silently un-does the past-due (and with it the dunning
+     * clock the lockout is derived from). `pastDueSince` is never written here —
+     * only a provider-confirmed reconcile sets it.
+     */
     readonly upsert: (sub: Subscription) => Effect.Effect<void, BillingError>;
     readonly getByTenant: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
+    /** Every subscription in a given status — the dunning sweep's only query. */
+    readonly listByStatus: (status: SubscriptionStatus) => Effect.Effect<ReadonlyArray<Subscription>, BillingError>;
     /** Mark a subscription canceled by provider id (no-op if absent). */
     readonly markCanceled: (providerSubscriptionId: string) => Effect.Effect<void, BillingError>;
     /** Apply a mid-cycle plan/seat/status change to the tenant's row (no-op if
      *  absent). Only the provided fields are patched. */
-    readonly patchByTenant: (tenantId: string, patch: {
-        readonly plan?: PlanId;
-        readonly quantity?: number;
-        readonly status?: SubscriptionStatus;
-    }) => Effect.Effect<void, BillingError>;
-    /** Set a subscription's status by provider id (no-op if absent) — the
-     *  dunning state machine's transition primitive. */
+    readonly patchByTenant: (tenantId: string, patch: SubscriptionPatch) => Effect.Effect<void, BillingError>;
+    /** Set a subscription's status by provider id (no-op if absent). */
     readonly setStatus: (providerSubscriptionId: string, status: SubscriptionStatus) => Effect.Effect<void, BillingError>;
 }