flexpay-engine 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog
+
+All notable changes to `flexpay-engine` (npm package). Only `src/` ships; the
+`worker/` runtime is deployed separately and is not part of the package.
+
+## 0.3.1 — 2026-07-31
+
+Released from `dev`. Supersedes **0.3.0, which must not be used** — 0.3.0 was
+published from an unmerged PR branch, carries the float-drift `daysActivated`
+bug fixed below, and predates migration `0004`. It is deprecated on npm.
+
+An earlier plan to ship this as `0.2.2` (off the 0.2.1 commit, allocation fix
+only) was dropped: `0.3.0` was already published, so a `0.2.2` would have moved
+the `latest` tag backwards. The `v0.2.2` git tag was created by mistake against
+0.3.0 content and has been moved.
+
+### ⚠️ REQUIRED before upgrading: migration `0004`
+
+`drizzle/engine/0004_next_state_change_at.sql` must be applied to a consumer's
+`ENGINE_DB` **before** it bumps to 0.3.1 and calls `recordEvent`/`recordPayment`,
+or the contract update fails on the missing `engine_contracts.next_state_change_at`
+column. Because engine writes are non-blocking in the backend, that failure is
+*silent* — a ledger gap, not an error the caller sees.
+
+The migration is additive: `ADD COLUMN` (nullable) plus a backfill gated on
+`paid_through_date IS NOT NULL`. Verified 2026-07-31 — 0 of 970 prod contracts
+have `paid_through_date` set, so the backfill touches no rows.
+
+State as of 2026-07-31: applied to `flexpay-engine-dev`; **not yet** applied to
+`flexpay-engine-prod`.
+
+### ⚠️ `paid_through_date` is provisional after this upgrade
+
+`recordEvent` now maintains `paid_through_date`, but all 970 prod contracts have
+it NULL, so `applyPaymentToLockState` bootstraps from the *payment date* rather
+than real entitlement. `snapshotSeedContract` (added in this release) exists to
+set it from Upya's `next_status_update` and has **never been run on prod**.
+
+This is safe only because nothing reads it yet: the sole consumer,
+`flexpay-client-worker` `lockDateProjectionService`, is gated by
+`SYNC_LOCK_DATE_FROM_ENGINE`, which is `"disabled"` on dev *and* prod.
+**Snapshot-seed prod before that flag is ever flipped to `"enabled"`.**
+
+### Added
+
+- `snapshotSeedContract` / `planSnapshotSeed` — seed `paid_through_date` / lock
+  state from an external snapshot without replaying payment history.
+- `engine_contracts.next_state_change_at` — denormalized lock boundary
+  (migration `0004`), maintained by `recordEvent` and `snapshotSeedContract`.
+
+### Packaging
+
+- **`drizzle/` and `CHANGELOG.md` now ship in the npm artifact.** Previously
+  `files` was `["src"]`, so a consumer upgrading through npm received neither the
+  migration SQL nor any upgrade notice — they could follow the published install
+  instructions and hit the silent ledger gap above. The `0.3.x` prerequisite is
+  now also stated at the top of the README, which npm does ship.
+
+### ⚠️ BREAKING (permitted on 0.x — SemVer §4)
+
+- **`allocatePayment` no longer throws `PaymentBelowMinimumError`.** It records any
+  positive amount. The rule refused to write down cash the app, ChinChin, the gateway
+  and Upya had all already accepted — a ledger declining money it holds. Sufficiency is
+  an entitlement question, decided from `paidThroughDate`.
+- **`PaymentBelowMinimumError` removed** from `src/types.ts` and the package entrypoint.
+- **`AllocationInput.minPayment` removed.** Callers passing it get TS2353; callers
+  reading it get TS2339.
+
+Known affected consumer: `flexpay-client-worker` `scripts/parity-legacy-seed.ts` on
+branch `feat/legacy-contract-seed-derivation` (imports the class, does `instanceof`,
+and passes `minPayment`). It needs a rewrite. Neither `flexpay-backend/src` nor
+`flexpay-client-worker/src` on their default branches references either symbol.
+
+No shim was added. A shim covering only the error class while leaving the type break
+would make the release look non-breaking without being non-breaking.
+
+### Fixed
+
+- **`daysActivated` is now fragmentation-invariant.** It was floored per payment, and
+  `floor()` drops the fraction every time, so paying one installment in pieces granted
+  fewer days than paying it at once — `$52` as `52 x $1` granted **zero** days. Days are
+  now the delta between cumulative entitlement before and after, which telescopes, so any
+  split of the same money sums to the same total. Deposit and overpayment behaviour are
+  unchanged.
+
+  This mattered because removing the minimum-payment rule is what made fragmented
+  payments reachable, and `daysActivated` feeds `paidThroughDate` — the engine's lock
+  decision. Without this, a customer paying in full by instalments would be locked for
+  not paying.
+
+  The delta is computed in **integer cents**, not floats. An earlier version of this
+  fix compared `round2(newTotalPaid)` against a raw unrounded sum of installment
+  amounts, so a day could appear or vanish purely from binary representation and land
+  on `paidThroughDate`. Verified 2026-07-31: the float path diverges at 272 of 1260
+  accumulation points; the shipped version holds fragmentation invariance across 420
+  scenarios (realistic recurring amounts — `3.35`, `22.86`, `11.43` — split 2/3/5/7/13/52/100
+  ways) with **zero** violations.
+
+- `seedContract` no longer aborts mid-replay when a contract's history contains a
+  below-minimum payment. This is what made 81 legacy contracts unreplayable.
+
+`min_payment_cents` remains on `engine_contracts` and is still written by
+`originate`/`seedContract` — it is a real quoting figure pushed to Upya. It simply no
+longer gates allocation.
+
+## 0.3.0 — 2026-06-03
+
+Lock-state decision module (L1–L6). Replaces Upya `nextStatusUpdate` as the
+authoritative answer to *"should this device be locked right now?"*. See
+`docs/roadmap.md` and `context/specs/2026-05-22-feat-lock-state-decision.md`.
+
+### Added
+
+- `decideLockState(input)` — pure, deterministic lock-state decision from
+  contract + payments + `asOf`. No I/O, no `Date.now()`.
+- `getLockState(db, { contractNumber, asOf? })` — D1-backed read; derives state
+  from the cached `paid_through_date`.
+- Types: `LockState`, `ClosureReason`, `LockStateContract`, `LockStatePayment`,
+  `LockStateInput`, `LockStateOutput`, `GetLockStateInput`.
+- Schema: `engine_lock_state_events` table + `EngineLockStateEvent` /
+  `NewEngineLockStateEvent` types; new `engine_contracts` columns
+  (`grace_days`, `timezone`, `closure`, `closure_at`, `closure_reason`,
+  `last_lock_state`, `last_lock_state_at`, `paid_through_date`).
+
+### Changed
+
+- **`recordPayment` / `recordEvent` now also maintain lock-state.** On each
+  payment they update the contract's `paid_through_date` + `last_lock_state`
+  cache and, on a state transition, append a row to `engine_lock_state_events`
+  — all inside the existing atomic `db.batch`. **This is not behaviorally
+  transparent**: a consumer that upgrades to 0.3.0 and calls `recordPayment`
+  starts writing these columns.
+
+### Migration required before upgrade
+
+A consumer's `ENGINE_DB` must have migrations `drizzle/engine/0001`–`0003`
+applied **before** it bumps to 0.3.0 and calls `recordPayment`, or the write
+will fail on the missing columns/table. Migrations are additive (new nullable
+columns + new empty table) and safe to apply ahead of the bump.
+
+Applied to `flexpay-engine-dev` and `flexpay-engine-prod` D1 as of 2026-06-03.
+
+### Notes
+
+- New exports (`decideLockState`, `getLockState`) are inert until called —
+  upgrading does not invoke them.
+- 181 tests pass; typecheck clean.
+
+## 0.2.1 — 2026-05
+
+- Canonical event log + `recordEvent` (first-writer model; engine state is a
+  projection of `engine_events`).
+- Pricing, schedule generation, payment allocation, delinquency, days-activated.
+- `originateContract`, `recordPayment`, `seedContract`, cents helpers, ULID.

package/README.md

@@ -1,21 +1,256 @@
 # 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.
+
+---
+
+## ⛔ Upgrading to 0.3.x — apply migration `0004` FIRST
+
+**Do not bump a consumer to `0.3.x` before applying
+[`drizzle/engine/0004_next_state_change_at.sql`](drizzle/engine/0004_next_state_change_at.sql)
+to that consumer's `ENGINE_DB`.**
+
+From `0.3.0`, `recordEvent` / `recordPayment` write
+`engine_contracts.next_state_change_at`. Without the column the contract update
+throws — and because engine writes are typically wired non-blocking, **the
+failure is silent: a ledger gap, not an error the caller sees.**
+
+The migration is additive and safe to apply ahead of the bump: `ADD COLUMN`
+(nullable) plus a backfill gated on `paid_through_date IS NOT NULL`. It is
+idempotent in effect (recomputes the same value) — but `ADD COLUMN` itself is
+not, so guard re-runs.
+
+Earlier lock-state columns need `0001`–`0003` for the same reason.
+
+**`0.3.0` is deprecated — use `0.3.1` or later.** It was published from an
+unmerged branch and carries a float-drift bug in `daysActivated` that can add or
+drop a day of entitlement, which feeds the lock decision.
+
+### `paid_through_date` is provisional after upgrading
+
+`recordEvent` maintains `paid_through_date`, but on a database where it is still
+NULL the lock-state bootstrap derives it from the *payment date* rather than the
+contract's real entitlement. Use `snapshotSeedContract` to seed it from an
+authoritative source **before** anything reads `paid_through_date` or
+`next_state_change_at`.
+
+---
+
+## 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 +259,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/drizzle/banking/0000_bank_foundation.sql

@@ -0,0 +1,99 @@
+-- Banking foundation tables. New tables only. NEVER touches engine_* tables.
+-- Enforced by scripts/check-engine-tables.sh in CI.
+
+CREATE TABLE `bank_working_keys` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `bank_code` text NOT NULL,
+  `effective_date` text NOT NULL,
+  `key_blob_encrypted` text NOT NULL,
+  `key_fingerprint` text NOT NULL,
+  `source` text NOT NULL,
+  `status` text DEFAULT 'active' NOT NULL,
+  `rotated_at` text NOT NULL,
+  `expires_at` text,
+  `event_version` integer DEFAULT 1 NOT NULL
+);
+CREATE UNIQUE INDEX `idx_bank_working_keys_bank_date` ON `bank_working_keys` (`bank_code`,`effective_date`);
+CREATE INDEX `idx_bank_working_keys_bank_status` ON `bank_working_keys` (`bank_code`,`status`);
+
+CREATE TABLE `bank_processed_notifications` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `event_id` text NOT NULL,
+  `bank_code` text NOT NULL,
+  `payment_type` text NOT NULL,
+  `origin_ref` text NOT NULL,
+  `destiny_ref` text NOT NULL,
+  `origin_bank_code` text,
+  `amount_cents` integer NOT NULL,
+  `currency_code` text NOT NULL,
+  `occurred_at` text NOT NULL,
+  `received_at` text NOT NULL,
+  `source` text NOT NULL,
+  `raw_payload` text NOT NULL,
+  `contract_match_status` text DEFAULT 'unmatched' NOT NULL,
+  `matched_contract_number` text,
+  `event_version` integer DEFAULT 1 NOT NULL
+);
+CREATE UNIQUE INDEX `idx_bank_notifications_idempotency`
+  ON `bank_processed_notifications` (`bank_code`,`origin_ref`,`destiny_ref`,`payment_type`);
+CREATE INDEX `idx_bank_notifications_received` ON `bank_processed_notifications` (`received_at`);
+CREATE INDEX `idx_bank_notifications_payment_type` ON `bank_processed_notifications` (`bank_code`,`payment_type`);
+CREATE UNIQUE INDEX `idx_bank_notifications_event_id` ON `bank_processed_notifications` (`event_id`);
+
+CREATE TABLE `bank_payment_attempts` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `attempt_id` text NOT NULL UNIQUE,
+  `bank_code` text NOT NULL,
+  `operation_type` text NOT NULL,
+  `operation_ref` text NOT NULL,
+  `amount_cents` integer NOT NULL,
+  `beneficiary_id` text,
+  `beneficiary_phone` text,
+  `beneficiary_bank_code` text,
+  `status` text NOT NULL,
+  `bnc_reference` text,
+  `bnc_authorization_code` text,
+  `bnc_id_transaction` text,
+  `sw_already_sent` integer DEFAULT 0 NOT NULL,
+  `error_code` text,
+  `error_message` text,
+  `attempted_at` text NOT NULL,
+  `completed_at` text,
+  `retry_count` integer DEFAULT 0 NOT NULL,
+  `request_payload` text NOT NULL,
+  `response_payload` text,
+  `event_version` integer DEFAULT 1 NOT NULL
+);
+CREATE UNIQUE INDEX `idx_bank_attempts_operation_ref` ON `bank_payment_attempts` (`bank_code`,`operation_ref`);
+CREATE INDEX `idx_bank_attempts_status` ON `bank_payment_attempts` (`status`);
+CREATE INDEX `idx_bank_attempts_attempted_at` ON `bank_payment_attempts` (`attempted_at`);
+
+CREATE TABLE `bank_api_audit` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `event_id` text NOT NULL,
+  `bank_code` text NOT NULL,
+  `direction` text NOT NULL,
+  `operation` text NOT NULL,
+  `http_status` integer,
+  `request_summary` text NOT NULL,
+  `response_summary` text,
+  `duration_ms` integer,
+  `occurred_at` text NOT NULL,
+  `event_version` integer DEFAULT 1 NOT NULL
+);
+CREATE INDEX `idx_bank_audit_operation` ON `bank_api_audit` (`bank_code`,`operation`,`occurred_at`);
+CREATE INDEX `idx_bank_audit_event_id` ON `bank_api_audit` (`event_id`);
+
+CREATE TABLE `bank_webhook_dlq` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `bank_code` text NOT NULL,
+  `received_at` text NOT NULL,
+  `failure_reason` text NOT NULL,
+  `retry_count` integer DEFAULT 0 NOT NULL,
+  `raw_payload` text NOT NULL,
+  `resolved_at` text,
+  `resolved_by` text,
+  `event_version` integer DEFAULT 1 NOT NULL
+);
+CREATE INDEX `idx_bank_dlq_bank_received` ON `bank_webhook_dlq` (`bank_code`,`received_at`);
+CREATE INDEX `idx_bank_dlq_resolved` ON `bank_webhook_dlq` (`resolved_at`);

package/drizzle/banking/0001_archived_at.sql

@@ -0,0 +1,11 @@
+-- R2 mirror archived_at column: TIMESTAMP (ISO-8601 string) when the row was
+-- confirmed written to R2. NULL = not yet archived, picked up by hourly sweep.
+ALTER TABLE bank_api_audit ADD COLUMN archived_at TEXT;
+ALTER TABLE bank_processed_notifications ADD COLUMN archived_at TEXT;
+ALTER TABLE bank_payment_attempts ADD COLUMN archived_at TEXT;
+ALTER TABLE bank_webhook_dlq ADD COLUMN archived_at TEXT;
+
+CREATE INDEX idx_bank_audit_archived_at ON bank_api_audit (archived_at);
+CREATE INDEX idx_bank_notifications_archived_at ON bank_processed_notifications (archived_at);
+CREATE INDEX idx_bank_attempts_archived_at ON bank_payment_attempts (archived_at);
+CREATE INDEX idx_bank_dlq_archived_at ON bank_webhook_dlq (archived_at);

package/drizzle/engine/0001_lock_state.sql

@@ -0,0 +1,34 @@
+-- Lock-state decision module — schema additions.
+-- See context/specs/2026-05-22-feat-lock-state-decision.md
+--
+-- Consumers (flexpay-client-worker, flexpay-backend) must apply this
+-- migration before upgrading to a flexpay-engine version that uses
+-- decideLockState end-to-end. The npm package's decideLockState function
+-- is pure and does not require these columns to exist for L1 usage.
+
+-- Per-contract lock-state config + cache + closure
+ALTER TABLE engine_contracts ADD COLUMN grace_days INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE engine_contracts ADD COLUMN timezone TEXT NOT NULL DEFAULT 'America/Caracas';
+ALTER TABLE engine_contracts ADD COLUMN closure TEXT;
+ALTER TABLE engine_contracts ADD COLUMN closure_at TEXT;
+ALTER TABLE engine_contracts ADD COLUMN closure_reason TEXT;
+ALTER TABLE engine_contracts ADD COLUMN last_lock_state TEXT;
+ALTER TABLE engine_contracts ADD COLUMN last_lock_state_at TEXT;
+
+-- Append-only transition log. R2-mirrored by the worker's archive sweep.
+CREATE TABLE engine_lock_state_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_id TEXT NOT NULL UNIQUE,
+  contract_number TEXT NOT NULL,
+  from_state TEXT,
+  to_state TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  computed_at TEXT NOT NULL,
+  paid_through_date TEXT,
+  next_state_change_at TEXT,
+  trigger TEXT NOT NULL,
+  FOREIGN KEY (contract_number) REFERENCES engine_contracts (contract_number)
+);
+
+CREATE INDEX idx_lock_events_contract ON engine_lock_state_events (contract_number, computed_at DESC);
+CREATE INDEX idx_lock_events_state ON engine_lock_state_events (to_state, computed_at DESC);

package/drizzle/engine/0002_paid_through_date.sql

@@ -0,0 +1,9 @@
+-- Cached cumulative paid-through-date on engine_contracts. Updated by
+-- recordPayment via the lock-state formula:
+--   paidThrough(n) = max(paidThrough(n-1), payment_day(n)) + days_activated(n)
+--
+-- Storing this on the contract avoids walking the full payment history on
+-- every state computation. The event log (engine_lock_state_events) remains
+-- the source of truth for transitions; this column is a cache.
+
+ALTER TABLE engine_contracts ADD COLUMN paid_through_date TEXT;

package/drizzle/engine/0003_lock_events_archive.sql

@@ -0,0 +1,9 @@
+-- Add archived_at to engine_lock_state_events so the hourly archive sweep can
+-- mirror it to R2, matching the durability of the 4 banking tables.
+-- NULL = not yet archived; the sweep retries until set.
+
+ALTER TABLE engine_lock_state_events ADD COLUMN archived_at TEXT;
+
+CREATE INDEX idx_lock_events_unarchived
+  ON engine_lock_state_events (archived_at, computed_at)
+  WHERE archived_at IS NULL;