flexpay-engine 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.3 — 2026-08-29
+
+### Migration `0005` — lock-event actor (FLEXPAY-240)
+
+`drizzle/engine/0005_lock_event_actor.sql` adds `actor_id` / `actor_name` /
+`actor_role` (all nullable) to `engine_lock_state_events` and backfills existing
+rows to `system:engine` / `System` / `system`. Additive on an append-only table:
+no rewrite, no downtime, safe to apply ahead of the code bump.
+
+**Must be applied before the FLEXPAY-240 code deploys.** `worker/lockState/sweep.ts`
+INSERTs those three columns literally; the daily cron sweep fails at runtime if the
+columns are absent.
+
+State as of 2026-08-28: **applied to `flexpay-engine-dev` (55 rows backfilled) AND
+`flexpay-engine-prod` (1992 rows backfilled)**; 0 NULL `actor_id` on either. Verified
+live via `PRAGMA table_info` + a NULL-actor count.
+
+### Migration `0006` — requeue actor-enriched lock archives (FLEXPAY-240)
+
+`drizzle/engine/0006_requeue_actor_archive.sql` clears `archived_at` on existing
+lock-state rows so the archive sweep rewrites their R2 objects with actor fields.
+The sweep uses archive version `v2` for the actor-enriched event shape. Deploy the
+worker containing `v2`, then apply `0006` after `0005`.
+
 ## 0.3.2 — 2026-07-31
 
 Packaging fix. **No source changes** — but `0.3.1` is effectively uninstallable for
@@ -72,8 +96,10 @@ 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`.
+State: applied to `flexpay-engine-dev` AND `flexpay-engine-prod`. Verified live
+2026-08-28 — `engine_contracts.next_state_change_at` present on both
+(`PRAGMA table_info`). The earlier "not yet applied to prod" note (2026-07-31) is
+superseded.
 
 ### ⚠️ `paid_through_date` is provisional after this upgrade
 

package/README.md

@@ -13,21 +13,26 @@ Worker for banking integrations.
 
 ---
 
-## ⛔ Upgrading to 0.3.x — apply migration `0004` FIRST
+## ⛔ Upgrading to 0.3.x — apply migrations `0004` and `0005` 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)
+and [`drizzle/engine/0005_lock_event_actor.sql`](drizzle/engine/0005_lock_event_actor.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.**
+`engine_contracts.next_state_change_at` and actor fields on
+`engine_lock_state_events`. Without these columns the contract update or event
+insert 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.
+The migrations are additive and safe to apply ahead of the bump. `0004` also
+backfills `next_state_change_at`; `0005` backfills legacy event actors. Guard
+re-runs because `ADD COLUMN` itself is not idempotent.
+
+After deploying the worker with actor-enriched archive version `v2`, apply
+[`drizzle/engine/0006_requeue_actor_archive.sql`](drizzle/engine/0006_requeue_actor_archive.sql)
+to clear archive markers and rewrite existing R2 objects with actor fields.
 
 Earlier lock-state columns need `0001`–`0003` for the same reason.
 
@@ -303,7 +308,10 @@ bunx wrangler tail flexpay-engine-dev
 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.
+bunx wrangler d1 execute <engine-db> --remote --file=drizzle/engine/0005_lock_event_actor.sql
+# Deploy the worker containing archive version v2, then:
+bunx wrangler d1 execute <engine-db> --remote --file=drizzle/engine/0006_requeue_actor_archive.sql
+# The requeue must run after v2 is deployed so the sweep rewrites R2 objects as v2.
 ```
 
 ---

package/drizzle/engine/0005_lock_event_actor.sql

@@ -0,0 +1,29 @@
+-- Who changed the lock state (FLEXPAY-240, feeds the FLEXPAY-239 activity feed).
+--
+-- engine_lock_state_events records WHAT changed (from_state -> to_state, reason,
+-- trigger) but not WHO. It was written for the cron, which has no user. A human
+-- clicking Lock in the portal is therefore indistinguishable from the overdue
+-- sweep, and the contract activity feed cannot answer "who locked this phone".
+--
+-- actor_role: 'owner' | 'admin' | 'agent' | 'system'.
+--
+-- Additive and nullable on an append-only table: no rewrite, no downtime.
+
+ALTER TABLE engine_lock_state_events ADD COLUMN actor_id TEXT;
+ALTER TABLE engine_lock_state_events ADD COLUMN actor_name TEXT;
+ALTER TABLE engine_lock_state_events ADD COLUMN actor_role TEXT;
+
+-- Backfill is a provable claim, not a default. The only writers of this table
+-- are operations/recordEvent.ts and operations/snapshotSeed.ts, both
+-- engine-internal. The portal lock route (flexpay-client-worker
+-- routes/portal/contracts.ts, PUT /:contractNumber/lock-status) writes Upya +
+-- the lock provider + MAIN Postgres and never touches ENGINE_DB. So every row
+-- that exists today was computed by the engine itself, and stamping it 'system'
+-- asserts nothing we cannot show.
+--
+-- Idempotent: re-running matches no rows once the columns are populated.
+UPDATE engine_lock_state_events
+SET actor_id = 'system:engine',
+    actor_name = 'System',
+    actor_role = 'system'
+WHERE actor_id IS NULL;

package/drizzle/engine/0006_requeue_actor_archive.sql

@@ -0,0 +1,9 @@
+-- Requeue lock-state rows after the FLEXPAY-240 actor backfill.
+--
+-- Migration 0005 changed the serialized event body, but archived_at remained set
+-- on rows whose R2 object still contains the pre-actor shape. Clear the marker so
+-- the archive sweep writes the actor-enriched body before treating the row as
+-- durable again. The update is safe to re-run and does not touch the ledger row.
+UPDATE engine_lock_state_events
+SET archived_at = NULL
+WHERE archived_at IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexpay-engine",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "FlexPay loan servicing engine \u2014 pricing, schedules, allocation, delinquency, lock-state",
   "license": "MIT",
   "main": "src/index.ts",
@@ -32,6 +32,7 @@
     "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",
+    "check:deployment-authority": "bun run scripts/check-deployment-authority.ts",
     "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",

package/src/index.ts

@@ -11,6 +11,8 @@ export { computeDaysActivated } from "./calc/daysActivated";
 
 // --- Lock-state decision (replaces Upya nextStatusUpdate) ---
 export { decideLockState } from "./lockState/decide";
+export { SYSTEM_ACTOR } from "./lockState/actor";
+export type { LockActor, LockActorRole } from "./lockState/actor";
 export type {
   LockState,
   ClosureReason,

package/src/lockState/actor.ts

@@ -0,0 +1,25 @@
+// Who caused a lock-state transition (FLEXPAY-240).
+//
+// The engine decides state on its own: a payment lands, the boundary moves,
+// the device unlocks. Nobody clicked anything, so the actor is the engine —
+// and the person who made the payment is already the actor on the payment
+// row, which renders as its own line in the contract activity feed. Copying
+// them onto the transition too would attribute a decision to someone who did
+// not make it, and print the same name twice.
+//
+// A human appears here only when they override state by hand from the portal.
+
+export type LockActorRole = "owner" | "admin" | "agent" | "system";
+
+export interface LockActor {
+  actorId: string;
+  actorName: string;
+  actorRole: LockActorRole;
+}
+
+/** The engine acting on its own — payment-driven, cron sweep, seeding. */
+export const SYSTEM_ACTOR: LockActor = {
+  actorId: "system:engine",
+  actorName: "System",
+  actorRole: "system",
+};

package/src/operations/recordEvent.ts

@@ -35,6 +35,7 @@ import {
 } from "../types";
 import { fromCents, toCents } from "../utils/cents";
 import { ulid } from "../utils/ulid";
+import { SYSTEM_ACTOR } from "../lockState/actor";
 import {
   ContractNotFoundError,
   EngineOperationError,
@@ -228,6 +229,9 @@ export async function recordEvent(
         paidThroughDate: lock.newPaidThrough.toISOString(),
         nextStateChangeAt: lock.nextStateChangeAt?.toISOString() ?? null,
         trigger: "payment",
+        // The engine decided this, not input.actorId — that person made a
+        // payment, which is its own row with its own actor. See lockState/actor.
+        ...SYSTEM_ACTOR,
       }
     : null;
   // ---------------------------------------------------------------------

package/src/operations/snapshotSeed.ts

@@ -46,6 +46,7 @@ import {
 } from "../schema";
 import { toCents } from "../utils/cents";
 import { ulid } from "../utils/ulid";
+import { SYSTEM_ACTOR } from "../lockState/actor";
 import {
   EngineOperationError,
   EngineSeedError,
@@ -317,6 +318,7 @@ export function planSnapshotSeed(input: SnapshotSeedInput): SnapshotSeedPlan {
     paidThroughDate: paidThroughIso,
     nextStateChangeAt: lock.nextStateChangeAt?.toISOString() ?? null,
     trigger: "seed",
+    ...SYSTEM_ACTOR,
   };
 
   return {

package/src/schema/index.ts

@@ -87,6 +87,12 @@ export const engineLockStateEvents = sqliteTable(
     paidThroughDate: text("paid_through_date"),
     nextStateChangeAt: text("next_state_change_at"),
     trigger: text("trigger").notNull(), // 'payment' | 'cron' | 'rpc' | 'origination' | 'closure'
+    // Who caused the transition (FLEXPAY-240). The engine computes state on its
+    // own, so 'system:engine' is the norm; a human only appears when the portal
+    // overrides a lock by hand. Without this, a sweep and a person are the same row.
+    actorId: text("actor_id"), // 'system:engine' | member id
+    actorName: text("actor_name"),
+    actorRole: text("actor_role"), // 'owner' | 'admin' | 'agent' | 'system'
     archivedAt: text("archived_at"), // R2 mirror timestamp; NULL until swept
   },
   (t) => ({