flexpay-engine 0.3.0 → 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

@@ -13,6 +13,38 @@ Worker for banking integrations.
 
 ---
 
+## ⛔ 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:

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;

package/drizzle/engine/0004_next_state_change_at.sql

@@ -0,0 +1,28 @@
+-- Denormalized lock boundary on engine_contracts (FLEXPAY-140 cutover T1).
+--   next_state_change_at = paid_through_date + (grace_days + 1) days
+--
+-- This is the bulk-queryable "next lock date" (Upya nextStatusUpdate
+-- equivalent) for the Postgres projection + enforcement predicates. Unlike
+-- LockStateOutput.nextStateChangeAt (null once locked), the column keeps the
+-- boundary for LOCKED contracts too (a past date) — `date < now` sweep
+-- predicates need overdue contracts to remain visible. NULL only for
+-- provisioning (no paid_through_date), terminal (closure set), and fully-paid
+-- (status COMPLETED) contracts — a boundary on a paid-off contract could point
+-- a sweep at a device that must never lock again.
+--
+-- Truth remains engine_events / engine_lock_state_events; this is a cache,
+-- maintained by recordEvent (same atomic batch as the event row) and
+-- snapshotSeed. The backfill below is idempotent (recomputes the same value)
+-- and safe to re-run.
+
+ALTER TABLE engine_contracts ADD COLUMN next_state_change_at TEXT;
+
+UPDATE engine_contracts
+SET next_state_change_at = strftime(
+  '%Y-%m-%dT%H:%M:%fZ',
+  paid_through_date,
+  '+' || (grace_days + 1) || ' days'
+)
+WHERE closure IS NULL
+  AND status != 'COMPLETED'
+  AND paid_through_date IS NOT NULL;

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "flexpay-engine",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "FlexPay loan servicing engine \u2014 pricing, schedules, allocation, delinquency, lock-state",
   "license": "MIT",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "files": [
-    "src"
+    "src",
+    "drizzle",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {

package/src/calc/allocation.ts

@@ -4,6 +4,7 @@ import type {
   InstallmentAllocation,
 } from "../types";
 import { round2 } from "./pricing";
+import { toCents } from "../utils/cents";
 
 /**
  * Allocate a payment across installments using FIFO (earliest unpaid first).
@@ -87,9 +88,18 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
   // 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.
+  // INTEGER CENTS, not floats. `newTotalPaid` is round2()'d but `currentTotalPaid`
+  // is a raw sum of installment amounts, so comparing their floors compared a
+  // rounded value against an unrounded one. Measured: 474 of 1260 accumulation
+  // points diverge — e.g. recurring 3.35 after 13 payments sums to
+  // 43.55000000000001 (floor 91) where the previous call stored 43.55 (floor 90).
+  // A day appears or vanishes purely from binary representation, and it lands on
+  // paidThroughDate. Cents make both terms exact, so the subtraction is honest and
+  // the result can never be negative.
+  const recurringCents = toCents(input.recurringPayment);
   const cumulativeDays = (total: number) =>
-    input.recurringPayment > 0
-      ? Math.floor((total / input.recurringPayment) * input.freqDays)
+    recurringCents > 0
+      ? Math.floor((toCents(total) * input.freqDays) / recurringCents)
       : 0;
   const daysActivated =
     cumulativeDays(newTotalPaid) - cumulativeDays(currentTotalPaid);