flexpay-engine 0.2.0 → 0.3.0

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,
+  };
+}

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(),
+  });
+}