flexpay-engine 0.2.1 → 0.3.0

package/README.md

@@ -1,21 +1,224 @@
 # flexpay-engine
 
-FlexPay loan servicing engine — pricing, schedules, allocation, delinquency.
+Loan-servicing engine for FlexPay. Owns **money truth** — pricing, schedules,
+payment allocation, delinquency, lock-state decisions, banking rails. Consumed
+by the rest of the FlexPay stack as an npm package today and as a Cloudflare
+Worker for banking integrations.
 
-## Installation
+> **Mental model**: Stripe-of-loans. This is the engine other services call.
+> Workflow, UI, identity, and device integrations live elsewhere.
+
+> **New here?** Read [`docs/roadmap.md`](docs/roadmap.md) — the Upya cutover
+> journey, where we are, and how the pieces connect.
+
+---
+
+## What this owns vs what it doesn't
+
+The test for whether something belongs here:
+**does it affect what a customer owes right now?**
+
+| Belongs in engine | Does NOT belong in engine |
+|---|---|
+| Ledger (contracts, payments, schedules) | Customer profiles / KYC |
+| Pricing, allocation, delinquency | Phone catalog / inventory |
+| Lock-state DECISION (locked/unlocked) | Lock-state EXECUTION (Trustonic, Nuovopay APIs) |
+| Payment rails (BNC, ChinChin) | Notification transport (SMS, email, push) |
+| Contract state events | Sales flow UI / portal forms |
+| Reconciliation against banking partners | Agent/store admin tools |
+| Append-only audit trail | Currency conversion / FX hedging |
+
+---
+
+## System map
+
+```
+                  ┌──────────────────────────────────────┐
+                  │  flexpay-engine (this repo)          │
+                  │  ──── money brain ────               │
+                  │                                      │
+                  │  • Ledger + schedules                │
+                  │  • Pricing, allocation, delinquency  │
+                  │  • Lock-state DECISION               │
+                  │  • Payment rails (BNC; ChinChin TBD) │
+                  │  • R2 audit mirror                   │
+                  │  • Emits state events                │
+                  └────────────┬─────────────────────────┘
+                               │ npm pkg + Service Binding RPC
+            ┌──────────────────┼──────────────────┐
+            ▼                  ▼                  ▼
+ ┌────────────────────┐ ┌──────────────┐ ┌─────────────────┐
+ │ flexpay-client-    │ │  Supabase    │ │ flexpay-backend │
+ │ worker (limbs)     │ │  (catalog +  │ │ (mobile)        │
+ │                    │ │   identity)  │ │                 │
+ │ • Lock execution   │ │              │ │ • KYC (Didit)   │
+ │   (Trustonic,      │ │ • Profiles   │ │ • Customer      │
+ │    Nuovopay)       │ │ • SKUs       │ │   self-service  │
+ │ • Sales flow       │ │ • Deals      │ │ • Mobile UX     │
+ │ • Customer CRUD    │ │ • Inventory  │ │                 │
+ │ • Signature        │ │ • Stores     │ │                 │
+ │ • Agents / stores  │ │ • Agents     │ │                 │
+ └────────────────────┘ └──────────────┘ └─────────────────┘
+            ▲                                    ▲
+            │ portal                             │ mobile app
+            │                                    │
+            └──── flexpay-portal (Next.js) ──────┘
+                  flexpay-app (React Native)
+```
+
+---
+
+## Capability inventory
+
+State as of 2026-05-22. Tracks what's owned, what's still on Upya, and what's
+in flight.
+
+### Payments — money in
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Pago Movil C2P (customer push w/ token) | ChinChin | engine via BNC SendC2P | ✅ sandbox-verified, ⏳ prod cert |
+| Pago Movil B2P (customer-initiated push) | ChinChin | engine via BNC webhook | ✅ webhook receiver shipped |
+| Débito Inmediato (recurring auto-debit) | not used | engine via BNC SIMF | ✅ sandbox-verified |
+| Cash at store | Upya | engine, recorded by portal | ❌ |
+| FX (USD ↔ VES) | ChinChin | TBD — not engine | ❌ scope decision pending |
+
+### Payments — money out
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Refunds | manual | engine via BNC SendP2P | ⏳ rail done, refund event TBD |
+| Store / agent commissions | manual | engine | ❌ |
+
+### Contract lifecycle
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Profile creation | Upya + Supabase | client-worker + Supabase | ❌ |
+| KYC (Didit) | backend | unchanged | ✅ |
+| Deal catalog | Upya + Supabase | Supabase only | ❌ — Upya sync to remove |
+| Deal application (deal → terms) | Upya `editTerms` | engine `originate(dealOptionId)` | ⏳ resolver TBD |
+| Unit assignment | Upya | client-worker + engine FK | ❌ |
+| Pricing calc | engine partial | engine | ✅ |
+| Schedule generation | engine | engine | ✅ |
+| Signature capture | client-worker + Supabase | unchanged | ✅ |
+| Downpayment | Upya hack | engine `recordPayment(kind=downpayment)` | ⏳ |
+| Activation | Upya | engine state derives from data | ❌ |
+| Status webhooks (lock/unlock) | Upya | engine emits events | ⏳ next: lock-state module |
+| Amendment / re-pricing | Upya `editTerms` | engine `amend()` | ❌ |
+| Closure (paid_off / repossessed / written_off) | manual + Upya | engine emits | ❌ |
+
+### Lock state
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Decision (should device be locked?) | Upya `nextStatusUpdate` | **engine** | ⏳ next — `context/specs/2026-05-22-feat-lock-state-decision.md` |
+| Execution (Trustonic, Nuovopay) | client-worker | client-worker | ✅ |
+| Registration (first-time provisioning) | client-worker | client-worker | ✅ |
+| Reconciliation (device state vs intent) | implicit / Upya | client-worker cron reading engine | ❌ |
+
+### Identity / org
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Customer profile CRUD | Supabase via Upya proxy | Supabase via client-worker | ❌ |
+| Agent directory | Upya | Supabase | ❌ |
+| Store directory | Supabase | unchanged | ✅ |
+| Auth (portal + app) | betterauth / supabase-auth | unchanged | ✅ |
+
+### Inventory
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Phone SKU catalog | Supabase phone_skus | unchanged | ✅ (decouple Upya template dep) |
+| Store inventory | Supabase store_inventory | unchanged | ✅ |
+| Unit lifecycle state machine | Upya | client-worker + Supabase | ❌ |
+
+### Notifications
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Payment received | partial | engine emits → notif worker | ⏳ |
+| Payment due reminder | scattered | engine emits | ❌ |
+| Lock-imminent warning | Upya | engine emits | ⏳ falls out of lock-state spec |
+| KYC reminder | backend | unchanged | ✅ |
+| Transport (SMS, email, push) | various | dedicated worker | (external) |
+
+### Reporting & reconciliation
+
+| Capability | Today | Target | Status |
+|---|---|---|---|
+| Internal finance reporting | Upya CSV | engine read replica + report-scribe | ❌ |
+| Customer receipts | partial | engine event | ❌ |
+| SUDEBAN regulatory | unknown | engine + accounting overlay | ❌ — confirm requirements |
+| 3-way reconciliation (engine ↔ BNC ↔ counterparty) | none | engine | ⏳ pre-prod gate |
+| Daily close (tie-out) | manual | engine | ❌ |
+
+**Legend**: ✅ shipped · ⏳ in flight · ❌ not started
+
+---
+
+## What's in this repo today
+
+```
+src/
+  calc/         pricing, schedule, allocation, delinquency, daysActivated
+  operations/   originate, recordPayment, recordEvent, seedContract
+  schema/       drizzle schema — npm-exported for consumers
+worker/
+  banking/
+    bnc/        BNC ESolutions API client (P2P, C2P, Débito, auth, audit)
+    event/      webhook → queue → idempotent processor + DLQ
+    schema/     bank_* tables (separate from engine_* tables)
+    services/   bake-check, archive-sweep, reconcile
+    lib/        archive (R2), observability, redaction, ulid, encoding
+  routes/       admin, health, BNC webhook
+  scheduled.ts  cron handlers (key rotation, bake, archive sweep)
+  index.ts      Hono app + queue consumer + scheduled dispatcher
+drizzle/
+  banking/      bank_* migrations
+docs/
+  bnc/          architecture, security, state-of-play, green-light criteria
+  runbooks/     bnc-banking ops procedures, R2 restore drill
+context/
+  specs/        active and shipped specs
+  tasks/        per-task progress notes
+```
+
+---
+
+## What's next
+
+Active specs:
+
+- **`context/specs/2026-05-22-feat-lock-state-decision.md`** — engine becomes the source of truth for lock state. Highest-priority Upya replacement.
+- **`docs/bnc/green-light-criteria.md`** — BNC production certification gates (14-day bake, 3-way reconciliation, prod creds).
+- **`docs/plans/2026-05-19-consumer-migration-spec.md`** — CHUNK 17: cut flexpay-backend and flexpay-client-worker off the npm package onto Service Binding RPC.
+
+The Upya cutover, sequenced:
+
+1. Lock-state decision in engine (next)
+2. Move ChinChin into engine alongside BNC (CHUNK A3)
+3. Strip Upya state polling from client-worker
+4. Strip Upya CRM calls from sales flow
+5. Decommission Upya integration
+
+Realistic runway: 6–10 weeks of focused work post-lock-state-decision.
+
+---
+
+## Installation (npm consumers)
 
 ```bash
 bun add flexpay-engine
 ```
 
-## Usage
-
 ```typescript
 import { recordPayment, toCents, seedContract } from 'flexpay-engine';
 import { engineContracts, enginePayments } from 'flexpay-engine/schema';
 ```
 
-## Publishing to npm
+### Publishing a new version
 
 1. Bump version in `package.json`
 2. Commit: `git commit -am "chore: bump to vX.Y.Z"`
@@ -24,29 +227,90 @@ import { engineContracts, enginePayments } from 'flexpay-engine/schema';
    ```bash
    # In flexpay-client-worker
    bun add flexpay-engine@X.Y.Z
-   
    # In flexpay-backend
    bun add flexpay-engine@X.Y.Z
    ```
 5. Commit lockfile changes in each consumer repo
 
-## Versioning
+### Versioning
 
 - **Patch** (0.1.x): Bug fixes, no API changes
 - **Minor** (0.x.0): New features, backwards compatible
 - **Major** (x.0.0): Breaking changes
 
-## Consumers
-
-- `flexpay-client-worker` — portal payments (PORTAL source)
-- `flexpay-backend` — ChinChin payments (CHINCHIN source)
-
-Both write to shared D1 database `ENGINE_DB`.
+---
 
 ## Development
 
 ```bash
 bun install
-bun test
+bun test         # 135+ tests covering calc, banking, lib
 bun run typecheck
 ```
+
+### Worker dev
+
+```bash
+# Local
+bun run dev
+
+# Dry-run deploy
+bunx wrangler deploy --dry-run
+
+# Deploy to dev
+bunx wrangler deploy --env=""
+
+# Tail logs
+bunx wrangler tail flexpay-engine-dev
+```
+
+### Migrations
+
+```bash
+# Banking tables (worker)
+bunx wrangler d1 execute flexpay-engine-dev --remote --file=drizzle/banking/XXXX_*.sql
+
+# Engine tables (npm package — applied by consumers)
+# Live in src/schema/ as drizzle definitions; migrations TBD per consumer.
+```
+
+---
+
+## Live URLs
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `https://flexpay-engine-dev.achilleas-dbe.workers.dev` | n/a | Dev worker |
+| `GET /health/bake-summary` | none | Bake-check status (14-day clock) |
+| `GET /admin/bnc/status` | Bearer | Detailed health |
+| `GET /admin/bnc/ping` | Bearer | BNC sandbox connectivity |
+| `POST /admin/bnc/bake/run` | Bearer | Force a bake-check now |
+| `POST /webhooks/bnc` | BNC creds | Inbound BNC webhook |
+
+R2 buckets: `bank-audit-archive-{dev,prod}` (append-only audit mirror).
+
+---
+
+## Architecture decisions worth knowing
+
+- **Single writer per table.** `src/` writes only `engine_*` tables. `worker/banking/` writes only `bank_*` tables. CI guard enforces (`scripts/check-engine-tables.sh`).
+- **Append-only ledger.** No UPDATE/DELETE on `engine_payments` except via the audited `forceReseedContract` path. Same rule for `engine_lock_state_events` once shipped.
+- **Cents only.** No floats touching D1.
+- **Idempotency via DB constraints**, not error-string matching. UNIQUE indexes + `onConflictDoNothing`.
+- **R2 mirror.** Every banking row is mirrored to R2 within ~1s of D1 write; hourly sweep retries failures. D1 restore drill executed 2026-05-22.
+- **Best-effort archive, never blocks.** R2 write failures log + retry via sweep; never break the payment path.
+- **Per-message queue ack/retry.** Never throw from the queue handler — that retries the whole batch.
+
+---
+
+## Key docs
+
+| Doc | When to read |
+|---|---|
+| `docs/bnc/README.md` | Anything BNC-related |
+| `docs/bnc/state-of-play.md` | What works / doesn't / unknown |
+| `docs/bnc/security.md` | Threat model, crypto, secrets |
+| `docs/bnc/green-light-criteria.md` | When can we cut over to prod |
+| `docs/runbooks/bnc-banking.md` | Ops procedures, R2 drill |
+| `context/specs/` | Active and shipped specs |
+| `CLAUDE.md` (parent dir) | Cross-repo conventions |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flexpay-engine",
-  "version": "0.2.1",
-  "description": "FlexPay loan servicing engine — pricing, schedules, allocation, delinquency",
+  "version": "0.3.0",
+  "description": "FlexPay loan servicing engine \u2014 pricing, schedules, allocation, delinquency, lock-state",
   "license": "MIT",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -23,15 +23,32 @@
   "scripts": {
     "test": "bun test",
     "test:watch": "bun test --watch",
-    "typecheck": "bunx tsc --noEmit"
+    "typecheck": "bunx tsc --noEmit",
+    "typecheck:worker": "bunx tsc --noEmit -p tsconfig.worker.json",
+    "dev": "wrangler dev",
+    "deploy:dev": "wrangler deploy",
+    "deploy:prod": "wrangler deploy --env prod",
+    "db:migrate:dev": "wrangler d1 migrations apply flexpay-engine-dev --remote",
+    "db:migrate:prod": "wrangler d1 migrations apply flexpay-engine-prod --remote --env prod",
+    "guard:deps": "bash scripts/check-deps.sh",
+    "guard:migrations": "bash scripts/check-engine-tables.sh",
+    "guard:all": "bun run guard:deps && bun run guard:migrations",
+    "probe:bnc": "bun run scripts/probe-bnc-sandbox.ts",
+    "ci:verify": "bash scripts/check-deps.sh && bash scripts/check-engine-tables.sh && bun run typecheck && bun run typecheck:worker"
+  },
+  "dependencies": {
+    "@sentry/cloudflare": "^10.20.0",
+    "drizzle-orm": "^0.44.7",
+    "hono": "^4.6.0"
   },
   "peerDependencies": {
     "drizzle-orm": "^0.44.7"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250101.0",
     "@types/bun": "latest",
-    "drizzle-orm": "^0.44.7",
     "fast-check": "^3.22.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "wrangler": "^4.0.0"
   }
 }

package/src/calc/allocation.ts

@@ -3,20 +3,25 @@ import type {
   AllocationResult,
   InstallmentAllocation,
 } from "../types";
-import { PaymentBelowMinimumError } from "../types";
 import { round2 } from "./pricing";
 
 /**
  * Allocate a payment across installments using FIFO (earliest unpaid first).
  *
+ * Records the payment as given; it does not judge whether the amount is enough.
+ * Sufficiency is an entitlement question, decided from paidThroughDate.
+ * See context/specs/2026-07-30-fix-engine-below-minimum-payment.md
+ *
  * Rules:
- * - Rejects payments below minPayment
+ * - Records any positive amount
  * - Fills installments in sequence order
  * - Partial payments create PARTIAL status
  * - Overpayment (beyond all installments) is tracked separately
- * - daysActivated = floor(totalAllocated / recurringPayment * freqDays)
+ * - daysActivated = the delta between cumulative entitlement before and after,
+ *   NOT this payment floored on its own — see below
  *
  * INVARIANTS:
+ * - fragmentation invariance: any split of the same money grants the same days
  * - totalAllocated + overpayment === paymentAmount
  * - installment.amountPaid <= installment.amountDue (never overpay an installment)
  * - newTotalPaid + newRemainingDebt === totalCost
@@ -27,14 +32,6 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
     .filter((i) => i.status !== "PAID" && i.status !== "WAIVED")
     .sort((a, b) => a.sequenceNumber - b.sequenceNumber);
 
-  // Only enforce minimum on recurring payments (not deposits, not overpayments).
-  // Deposits (sequence 0) may be below minPayment for cheap phones / 0% down promos.
-  // Overpayments (all installments paid) should flow through regardless of amount.
-  const hasUnpaidRecurring = unpaid.some((i) => i.sequenceNumber > 0);
-  if (hasUnpaidRecurring && input.paymentAmount < input.minPayment) {
-    throw new PaymentBelowMinimumError(input.paymentAmount, input.minPayment);
-  }
-
   let remaining = input.paymentAmount;
   const allocations: InstallmentAllocation[] = [];
 
@@ -61,12 +58,6 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
 
   const totalAllocated = round2(input.paymentAmount - remaining);
 
-  // Days activated: proportional to payment relative to recurring
-  const daysActivated =
-    input.recurringPayment > 0
-      ? Math.floor((totalAllocated / input.recurringPayment) * input.freqDays)
-      : 0;
-
   // Calculate new totals from installment state
   const currentTotalPaid = input.installments.reduce(
     (sum, i) => sum + i.amountPaid,
@@ -79,6 +70,30 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
   const newTotalPaid = round2(currentTotalPaid + totalAllocated);
   const newRemainingDebt = round2(totalCost - newTotalPaid);
 
+  // Days activated: the DELTA between cumulative entitlement before and after.
+  //
+  // This used to floor each payment on its own — and floor() discards the
+  // fraction every single time, so paying one installment in pieces granted
+  // fewer days than paying it at once. $52 as 52 x $1 granted ZERO days,
+  // because floor(1/52 * 15) === 0 each time.
+  //
+  // That was unreachable while allocation rejected below-minimum payments.
+  // Removing the rule made it reachable, and daysActivated feeds
+  // paidThroughDate (recordEvent -> applyPaymentToLockState), which is the
+  // engine's lock decision. A customer paying in full, in instalments, would
+  // have been locked for not paying.
+  //
+  // Deltas off a cumulative floor telescope, so any split of the same money
+  // sums to the same days. Deposit and overpayment behaviour are unchanged:
+  // the deposit still earns on the same ratio, and overpayment is excluded
+  // because it never enters totalAllocated.
+  const cumulativeDays = (total: number) =>
+    input.recurringPayment > 0
+      ? Math.floor((total / input.recurringPayment) * input.freqDays)
+      : 0;
+  const daysActivated =
+    cumulativeDays(newTotalPaid) - cumulativeDays(currentTotalPaid);
+
   // Find next due date: first installment that will still be unpaid after allocation
   const paidIds = new Set(
     allocations.filter((a) => a.newStatus === "PAID").map((a) => a.installmentId),

package/src/index.ts

@@ -9,11 +9,33 @@ export { allocatePayment } from "./calc/allocation";
 export { checkDelinquency } from "./calc/delinquency";
 export { computeDaysActivated } from "./calc/daysActivated";
 
+// --- Lock-state decision (replaces Upya nextStatusUpdate) ---
+export { decideLockState } from "./lockState/decide";
+export type {
+  LockState,
+  ClosureReason,
+  LockStateContract,
+  LockStatePayment,
+  LockStateInput,
+  LockStateOutput,
+} from "./lockState/types";
+
 // --- Operations layer (D1-backed) ---
 export { originateContract } from "./operations/originate";
 export { recordEvent } from "./operations/recordEvent";
 export { recordPayment } from "./operations/recordPayment";
 export { seedContract } from "./operations/seedContract";
+export {
+  snapshotSeedContract,
+  planSnapshotSeed,
+} from "./operations/snapshotSeed";
+export type {
+  SnapshotSeedInput,
+  SnapshotSeedPlan,
+  SnapshotSeedResult,
+} from "./operations/snapshotSeed";
+export { getLockState } from "./operations/getLockState";
+export type { GetLockStateInput } from "./operations/getLockState";
 
 // --- Utilities ---
 export { ulid } from "./utils/ulid";
@@ -59,7 +81,6 @@ export type {
 // --- Errors ---
 export {
   LoanEngineError,
-  PaymentBelowMinimumError,
   ContractAlreadyPaidOffError,
 } from "./types";
 

package/src/lockState/decide.ts

@@ -0,0 +1,180 @@
+// Lock-state decision function.
+// Pure — no I/O, no Date.now() reads. Deterministic from input alone.
+// Replaces Upya `nextStatusUpdate`. See spec for design + validation evidence.
+
+import type {
+  LockStateInput,
+  LockStateOutput,
+  LockStatePayment,
+  LockStateContract,
+} from "./types";
+
+const MS_PER_DAY = 86_400_000;
+
+export function decideLockState(input: LockStateInput): LockStateOutput {
+  const { contract, payments, asOf } = input;
+  const computedAt = new Date(asOf.getTime());
+
+  if (contract.closure) {
+    return absorbingClosure(contract, computedAt);
+  }
+
+  if (!contract.signedAt) {
+    return provisioning("awaiting_signing", computedAt);
+  }
+
+  const downpayment = payments.find((p) => p.kind === "downpayment");
+  if (!downpayment) {
+    return provisioning("awaiting_downpayment", computedAt);
+  }
+
+  const paidThrough = walkPaidThrough(payments);
+  if (!paidThrough) {
+    // Defensive: downpayment present but no credit applied (e.g. all reversals).
+    return provisioning("no_coverage_applied", computedAt);
+  }
+
+  return classifyByTime({ paidThrough, contract, asOf, computedAt });
+}
+
+function provisioning(reason: string, computedAt: Date): LockStateOutput {
+  return {
+    state: "provisioning",
+    reason,
+    paidThroughDate: null,
+    nextStateChangeAt: null,
+    daysUntilNextChange: null,
+    computedAt,
+  };
+}
+
+function absorbingClosure(
+  contract: LockStateContract,
+  computedAt: Date,
+): LockStateOutput {
+  return {
+    state: contract.closure!,
+    reason: `closed_${contract.closure}`,
+    paidThroughDate: null,
+    nextStateChangeAt: null,
+    daysUntilNextChange: null,
+    computedAt,
+  };
+}
+
+/**
+ * Walk payments oldest-first, applying:
+ *   paidThrough(n) = max(paidThrough(n-1), paymentDay(n)) + daysActivated(n)
+ *
+ * `max(...)` is the late-payment rule: late payments don't retroactively
+ * credit the days the device was locked. Reversals subtract via negative
+ * daysActivated (callers send a negative value for refunds).
+ *
+ * Validated against 47 production contracts. Match rate 77% exactly. Known
+ * outliers are "ahead of schedule" customers — see
+ * docs/lock-state-validation.md.
+ */
+function walkPaidThrough(
+  payments: ReadonlyArray<LockStatePayment>,
+): Date | null {
+  let paidThrough: Date | null = null;
+  for (const p of payments) {
+    const paymentDay = new Date(p.receivedAt);
+    if (Number.isNaN(paymentDay.getTime())) {
+      throw new Error(`decideLockState: invalid receivedAt ${p.receivedAt}`);
+    }
+    if (!Number.isInteger(p.daysActivated)) {
+      throw new Error(
+        `decideLockState: daysActivated must be an integer, got ${p.daysActivated}`,
+      );
+    }
+    const base: Date =
+      paidThrough && paidThrough.getTime() > paymentDay.getTime()
+        ? paidThrough
+        : paymentDay;
+    paidThrough = new Date(base.getTime() + p.daysActivated * MS_PER_DAY);
+  }
+  return paidThrough;
+}
+
+/**
+ * The lock boundary: the instant the unlock window ends (or ended) —
+ * paidThrough + graceDays + 1 day, the same formula classifyByTime uses for
+ * `nextStateChangeAt` in the unlocked branch.
+ *
+ * Unlike LockStateOutput.nextStateChangeAt (null once locked — "next change
+ * comes from a payment, not a clock"), the boundary is defined whenever
+ * paidThrough exists, INCLUDING for locked contracts (where it lies in the
+ * past). The denormalized `engine_contracts.next_state_change_at` cache
+ * stores this boundary so bulk consumers (projection, enforcement sweeps
+ * with `date < now` predicates) can find overdue contracts — an
+ * always-null-when-locked cache would hide exactly the contracts a lock
+ * sweep needs to see.
+ */
+export function lockBoundary(paidThrough: Date, graceDays: number): Date {
+  return new Date(paidThrough.getTime() + graceDays * MS_PER_DAY + MS_PER_DAY);
+}
+
+/**
+ * Same state classification as decideLockState, but accepts a pre-computed
+ * paidThroughDate instead of walking a payment list. Use this from places
+ * that already maintain a cached paidThroughDate (e.g. recordEvent inside
+ * the engine, where each payment incrementally updates the cache).
+ *
+ * `paidThroughDate === null` is treated as provisioning (no coverage yet).
+ */
+export function decideLockStateFromPaidThrough(input: {
+  contract: LockStateContract;
+  paidThroughDate: Date | null;
+  asOf: Date;
+}): LockStateOutput {
+  const { contract, paidThroughDate, asOf } = input;
+  const computedAt = new Date(asOf.getTime());
+
+  if (contract.closure) {
+    return absorbingClosure(contract, computedAt);
+  }
+  if (!contract.signedAt) {
+    return provisioning("awaiting_signing", computedAt);
+  }
+  if (!paidThroughDate) {
+    return provisioning("awaiting_downpayment", computedAt);
+  }
+  return classifyByTime({ paidThrough: paidThroughDate, contract, asOf, computedAt });
+}
+
+function classifyByTime(args: {
+  paidThrough: Date;
+  contract: LockStateContract;
+  asOf: Date;
+  computedAt: Date;
+}): LockStateOutput {
+  const { paidThrough, contract, asOf, computedAt } = args;
+  const asOfMs = asOf.getTime();
+  const graceEndMs = paidThrough.getTime() + contract.graceDays * MS_PER_DAY;
+
+  if (asOfMs <= graceEndMs) {
+    const lockTransitionAt = lockBoundary(paidThrough, contract.graceDays);
+    const inGrace = contract.graceDays > 0 && asOfMs > paidThrough.getTime();
+    return {
+      state: "unlocked",
+      reason: inGrace ? "within_grace" : "current",
+      paidThroughDate: paidThrough,
+      nextStateChangeAt: lockTransitionAt,
+      daysUntilNextChange: Math.max(
+        0,
+        Math.ceil((lockTransitionAt.getTime() - asOfMs) / MS_PER_DAY),
+      ),
+      computedAt,
+    };
+  }
+
+  return {
+    state: "locked",
+    reason: "past_paid_through",
+    paidThroughDate: paidThrough,
+    nextStateChangeAt: null,
+    daysUntilNextChange: null,
+    computedAt,
+  };
+}