flexpay-engine 0.2.1 → 0.3.0

package/src/lockState/incremental.ts

@@ -0,0 +1,94 @@
+// Incremental lock-state update — applied after every payment is recorded.
+// Pure: takes the contract snapshot + payment delta, returns the new
+// paid-through date, new lock state, and whether a transition fired.
+//
+// recordEvent uses this to maintain engine_contracts.paid_through_date as
+// a cache, and to decide whether to insert an engine_lock_state_events row
+// in the atomic batch.
+
+import { decideLockStateFromPaidThrough } from "./decide";
+import type { ClosureReason, LockState, LockStateContract } from "./types";
+
+const MS_PER_DAY = 86_400_000;
+
+export interface IncrementalLockStateInput {
+  contract: {
+    contractNumber: string;
+    signingDate: string;
+    freqDays: number;
+    graceDays: number;
+    timezone: string;
+    numInstallments: number;
+    paidThroughDate: string | null;
+    lastLockState: string | null;
+    closure: string | null;
+    closureAt: string | null;
+  };
+  /** Real-world moment of the payment (ISO timestamp). */
+  paymentDate: Date;
+  /** Days credited by allocatePayment. Integer. */
+  daysActivated: number;
+  /** Our wall-clock moment we're computing this at. */
+  asOf: Date;
+}
+
+export interface IncrementalLockStateResult {
+  newPaidThrough: Date;
+  newState: LockState;
+  reason: string;
+  nextStateChangeAt: Date | null;
+  /** True if newState !== contract.lastLockState. */
+  transitioned: boolean;
+  /** The state BEFORE this payment landed (null if first computation). */
+  fromState: LockState | null;
+}
+
+export function applyPaymentToLockState(
+  input: IncrementalLockStateInput,
+): IncrementalLockStateResult {
+  if (!Number.isInteger(input.daysActivated)) {
+    throw new Error(
+      `applyPaymentToLockState: daysActivated must be an integer, got ${input.daysActivated}`,
+    );
+  }
+
+  const paymentDayMs = input.paymentDate.getTime();
+  const prevPaidThroughMs = input.contract.paidThroughDate
+    ? new Date(input.contract.paidThroughDate).getTime()
+    : null;
+  const baseMs =
+    prevPaidThroughMs != null && prevPaidThroughMs > paymentDayMs
+      ? prevPaidThroughMs
+      : paymentDayMs;
+  const newPaidThrough = new Date(
+    baseMs + input.daysActivated * MS_PER_DAY,
+  );
+
+  const lockContractInput: LockStateContract = {
+    id: input.contract.contractNumber,
+    signedAt: input.contract.signingDate,
+    paymentFreqDays: input.contract.freqDays,
+    upfrontDays: 0,
+    graceDays: input.contract.graceDays,
+    timezone: input.contract.timezone,
+    totalScheduledPayments: input.contract.numInstallments,
+    closure: (input.contract.closure as ClosureReason | null) ?? undefined,
+    closureAt: input.contract.closureAt ?? undefined,
+  };
+
+  const output = decideLockStateFromPaidThrough({
+    contract: lockContractInput,
+    paidThroughDate: newPaidThrough,
+    asOf: input.asOf,
+  });
+
+  const fromState = (input.contract.lastLockState as LockState | null) ?? null;
+  return {
+    newPaidThrough,
+    newState: output.state,
+    reason: output.reason,
+    nextStateChangeAt: output.nextStateChangeAt,
+    transitioned: fromState !== output.state,
+    fromState,
+  };
+}

package/src/lockState/index.ts

@@ -0,0 +1,9 @@
+export { decideLockState } from "./decide";
+export type {
+  LockState,
+  ClosureReason,
+  LockStateContract,
+  LockStatePayment,
+  LockStateInput,
+  LockStateOutput,
+} from "./types";

package/src/lockState/types.ts

@@ -0,0 +1,62 @@
+// Lock-state decision module types.
+// See context/specs/2026-05-22-feat-lock-state-decision.md for design rationale.
+
+export type LockState =
+  | "provisioning"
+  | "unlocked"
+  | "locked"
+  | "paid_off"
+  | "repossessed"
+  | "written_off";
+
+export type ClosureReason = "paid_off" | "repossessed" | "written_off";
+
+export interface LockStateContract {
+  id: string;
+  /** ISO timestamp the customer signed the contract. null = unsigned. */
+  signedAt: string | null;
+  /** Days between recurring payments (typically 7, 14, 15, 30). */
+  paymentFreqDays: number;
+  /** Days the device is unlocked after downpayment lands (often 1 or = freq). */
+  upfrontDays: number;
+  /** Grace days after paidThroughDate before locking. 0 today (Venezuela). */
+  graceDays: number;
+  /** IANA timezone for day-boundary calculations. Default America/Caracas. */
+  timezone: string;
+  /** Total scheduled payments needed to fully satisfy the contract. */
+  totalScheduledPayments: number;
+  /** Set by ops via closeContract — absorbing state. */
+  closure?: ClosureReason;
+  /** ISO timestamp when closure was set. */
+  closureAt?: string;
+}
+
+export interface LockStatePayment {
+  /** ISO timestamp the payment was received. */
+  receivedAt: string;
+  /** Days Upya (or our engine) credited this payment with. May be 0 for partial. */
+  daysActivated: number;
+  /** Payment classification. */
+  kind: "downpayment" | "regular" | "reversal";
+}
+
+export interface LockStateInput {
+  contract: LockStateContract;
+  payments: ReadonlyArray<LockStatePayment>;
+  /** Moment we're evaluating "is the device locked right now". */
+  asOf: Date;
+}
+
+export interface LockStateOutput {
+  state: LockState;
+  /** Stable, grep-friendly identifier for the rule that fired. */
+  reason: string;
+  /** Date through which the customer's coverage extends. null if not derivable. */
+  paidThroughDate: Date | null;
+  /** When the state would next change without further input. null = on next payment. */
+  nextStateChangeAt: Date | null;
+  /** Whole days until nextStateChangeAt. null when nextStateChangeAt is null. */
+  daysUntilNextChange: number | null;
+  /** asOf echoed back so consumers know what timestamp produced this output. */
+  computedAt: Date;
+}

package/src/operations/getLockState.ts

@@ -0,0 +1,67 @@
+// getLockState — read-only lock-state query.
+//
+// Derives lock state for a contract from its cached paid_through_date (the
+// authoritative value computed by recordPayment via real payment allocation,
+// see src/lockState/incremental.ts). No mutation.
+//
+// Used by:
+//   - the worker admin endpoint (GET /admin/lock-state/:contractNumber)
+//   - the getLockState RPC (consumers in shadow mode + post-cutover)
+//
+// Why the cache and not a fresh payment-walk: engine_payments has no per-row
+// days_activated. That integer is produced by allocatePayment at record time
+// and folded into engine_contracts.paid_through_date atomically. Re-deriving
+// it here (e.g. freq-per-payment) would ignore partial payments / overpayment
+// and diverge from what the ledger actually wrote. The cache IS the ledger's
+// answer.
+
+import { eq } from "drizzle-orm";
+import { engineContracts } from "../schema";
+import { decideLockStateFromPaidThrough } from "../lockState/decide";
+import type {
+  ClosureReason,
+  LockStateContract,
+  LockStateOutput,
+} from "../lockState/types";
+import { ContractNotFoundError, type EngineDb } from "./types";
+
+export interface GetLockStateInput {
+  contractNumber: string;
+  /** Defaults to now. Pass a fixed time for deterministic reads / backtests. */
+  asOf?: Date;
+}
+
+export async function getLockState(
+  db: EngineDb,
+  input: GetLockStateInput,
+): Promise<LockStateOutput> {
+  const contract = await db
+    .select()
+    .from(engineContracts)
+    .where(eq(engineContracts.contractNumber, input.contractNumber))
+    .get();
+
+  if (!contract) {
+    throw new ContractNotFoundError(input.contractNumber);
+  }
+
+  const lockContract: LockStateContract = {
+    id: contract.contractNumber,
+    signedAt: contract.signingDate,
+    paymentFreqDays: contract.freqDays,
+    upfrontDays: 0,
+    graceDays: contract.graceDays,
+    timezone: contract.timezone,
+    totalScheduledPayments: contract.numInstallments,
+    closure: (contract.closure as ClosureReason | null) ?? undefined,
+    closureAt: contract.closureAt ?? undefined,
+  };
+
+  return decideLockStateFromPaidThrough({
+    contract: lockContract,
+    paidThroughDate: contract.paidThroughDate
+      ? new Date(contract.paidThroughDate)
+      : null,
+    asOf: input.asOf ?? new Date(),
+  });
+}

package/src/operations/recordEvent.ts

@@ -14,13 +14,17 @@
 
 import { eq } from "drizzle-orm";
 import { allocatePayment } from "../calc/allocation";
+import { applyPaymentToLockState } from "../lockState/incremental";
+import { lockBoundary } from "../lockState/decide";
 import {
   engineContracts,
   engineEvents,
   engineInstallments,
+  engineLockStateEvents,
   enginePayments,
   enginePaymentLines,
   type NewEngineEvent,
+  type NewEngineLockStateEvent,
   type NewEnginePayment,
   type NewEnginePaymentLine,
 } from "../schema";
@@ -149,7 +153,6 @@ export async function recordEvent(
   const allocation = allocatePayment({
     paymentAmount: fromCents(input.amountCents),
     installments: calcInstallments,
-    minPayment: fromCents(contract.minPaymentCents),
     recurringPayment: fromCents(contract.recurringCents),
     freqDays: contract.freqDays,
   });
@@ -192,6 +195,43 @@ export async function recordEvent(
     ? "COMPLETED"
     : "ACTIVE";
 
+  // ----- Lock-state hook ------------------------------------------------
+  // Maintain engine_contracts.paid_through_date as a cache and emit a
+  // lock-state event in the same atomic batch on any transition. Pure
+  // helper — see src/lockState/incremental.ts.
+  const lock = applyPaymentToLockState({
+    contract: {
+      contractNumber: contract.contractNumber,
+      signingDate: contract.signingDate,
+      freqDays: contract.freqDays,
+      graceDays: contract.graceDays,
+      timezone: contract.timezone,
+      numInstallments: contract.numInstallments,
+      paidThroughDate: contract.paidThroughDate,
+      lastLockState: contract.lastLockState,
+      closure: contract.closure,
+      closureAt: contract.closureAt,
+    },
+    paymentDate: new Date(occurredAt),
+    daysActivated: allocation.daysActivated,
+    asOf: new Date(ingestedAt),
+  });
+
+  const lockEventRow: NewEngineLockStateEvent | null = lock.transitioned
+    ? {
+        eventId: ulid(),
+        contractNumber: input.contractNumber,
+        fromState: lock.fromState,
+        toState: lock.newState,
+        reason: lock.reason,
+        computedAt: ingestedAt,
+        paidThroughDate: lock.newPaidThrough.toISOString(),
+        nextStateChangeAt: lock.nextStateChangeAt?.toISOString() ?? null,
+        trigger: "payment",
+      }
+    : null;
+  // ---------------------------------------------------------------------
+
   const paymentLineRows: NewEnginePaymentLine[] = allocation.allocations.map(
     (a) => ({
       transactionId: input.transactionId!,
@@ -219,12 +259,25 @@ export async function recordEvent(
       daysActivated: newDaysActivated,
       status: newContractStatus,
       updatedAt: ingestedAt,
+      paidThroughDate: lock.newPaidThrough.toISOString(),
+      // Lock boundary cache — kept even when newState is locked (past date),
+      // so `date < now` bulk sweeps still see overdue contracts; NULLed when
+      // this payment completes the contract (fully paid ≈ terminal — a
+      // boundary here could point a sweep at a paid-off device). See
+      // lockBoundary() + migration 0004.
+      nextStateChangeAt:
+        newContractStatus === "COMPLETED"
+          ? null
+          : lockBoundary(lock.newPaidThrough, contract.graceDays).toISOString(),
+      lastLockState: lock.newState,
+      lastLockStateAt: ingestedAt,
     })
     .where(eq(engineContracts.contractNumber, input.contractNumber));
 
-  // 8. Single atomic batch — event log INSERT first, then projection writes.
-  // Stable user-supplied IDs (eventId, transactionId) used as FKs so no
-  // mid-batch lookups are needed. D1's batch is atomic per call.
+  // 8. Single atomic batch — event log INSERT first, then projection writes,
+  // then (optional) lock-state transition event. Stable user-supplied IDs
+  // (eventId, transactionId) used as FKs so no mid-batch lookups are needed.
+  // D1's batch is atomic per call.
   const statements = [
     db.insert(engineEvents).values(eventRow),
     db.insert(enginePayments).values(paymentRow),
@@ -233,6 +286,9 @@ export async function recordEvent(
     ),
     ...installmentUpdates,
     contractUpdate,
+    ...(lockEventRow
+      ? [db.insert(engineLockStateEvents).values(lockEventRow)]
+      : []),
   ];
 
   await db.batch(statements as unknown as Parameters<typeof db.batch>[0]);