flexpay-engine 0.2.1 → 0.3.1

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.2.1",
-  "description": "FlexPay loan servicing engine — pricing, schedules, allocation, delinquency",
+  "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": {
     ".": {
@@ -23,15 +25,32 @@
   "scripts": {
     "test": "bun test",
     "test:watch": "bun test --watch",
-    "typecheck": "bunx tsc --noEmit"
+    "typecheck": "bunx tsc --noEmit",
+    "typecheck:worker": "bunx tsc --noEmit -p tsconfig.worker.json",
+    "dev": "wrangler dev",
+    "deploy:dev": "wrangler deploy",
+    "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",
+    "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",
+    "probe:bnc": "bun run scripts/probe-bnc-sandbox.ts",
+    "ci:verify": "bash scripts/check-deps.sh && bash scripts/check-engine-tables.sh && bun run typecheck && bun run typecheck:worker"
+  },
+  "dependencies": {
+    "@sentry/cloudflare": "^10.20.0",
+    "drizzle-orm": "^0.44.7",
+    "hono": "^4.6.0"
   },
   "peerDependencies": {
     "drizzle-orm": "^0.44.7"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250101.0",
     "@types/bun": "latest",
-    "drizzle-orm": "^0.44.7",
     "fast-check": "^3.22.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "wrangler": "^4.0.0"
   }
 }

package/src/calc/allocation.ts

@@ -3,20 +3,26 @@ import type {
   AllocationResult,
   InstallmentAllocation,
 } from "../types";
-import { PaymentBelowMinimumError } from "../types";
 import { round2 } from "./pricing";
+import { toCents } from "../utils/cents";
 
 /**
  * Allocate a payment across installments using FIFO (earliest unpaid first).
  *
+ * Records the payment as given; it does not judge whether the amount is enough.
+ * Sufficiency is an entitlement question, decided from paidThroughDate.
+ * See context/specs/2026-07-30-fix-engine-below-minimum-payment.md
+ *
  * Rules:
- * - Rejects payments below minPayment
+ * - Records any positive amount
  * - Fills installments in sequence order
  * - Partial payments create PARTIAL status
  * - Overpayment (beyond all installments) is tracked separately
- * - daysActivated = floor(totalAllocated / recurringPayment * freqDays)
+ * - daysActivated = the delta between cumulative entitlement before and after,
+ *   NOT this payment floored on its own — see below
  *
  * INVARIANTS:
+ * - fragmentation invariance: any split of the same money grants the same days
  * - totalAllocated + overpayment === paymentAmount
  * - installment.amountPaid <= installment.amountDue (never overpay an installment)
  * - newTotalPaid + newRemainingDebt === totalCost
@@ -27,14 +33,6 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
     .filter((i) => i.status !== "PAID" && i.status !== "WAIVED")
     .sort((a, b) => a.sequenceNumber - b.sequenceNumber);
 
-  // Only enforce minimum on recurring payments (not deposits, not overpayments).
-  // Deposits (sequence 0) may be below minPayment for cheap phones / 0% down promos.
-  // Overpayments (all installments paid) should flow through regardless of amount.
-  const hasUnpaidRecurring = unpaid.some((i) => i.sequenceNumber > 0);
-  if (hasUnpaidRecurring && input.paymentAmount < input.minPayment) {
-    throw new PaymentBelowMinimumError(input.paymentAmount, input.minPayment);
-  }
-
   let remaining = input.paymentAmount;
   const allocations: InstallmentAllocation[] = [];
 
@@ -61,12 +59,6 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
 
   const totalAllocated = round2(input.paymentAmount - remaining);
 
-  // Days activated: proportional to payment relative to recurring
-  const daysActivated =
-    input.recurringPayment > 0
-      ? Math.floor((totalAllocated / input.recurringPayment) * input.freqDays)
-      : 0;
-
   // Calculate new totals from installment state
   const currentTotalPaid = input.installments.reduce(
     (sum, i) => sum + i.amountPaid,
@@ -79,6 +71,39 @@ export function allocatePayment(input: AllocationInput): AllocationResult {
   const newTotalPaid = round2(currentTotalPaid + totalAllocated);
   const newRemainingDebt = round2(totalCost - newTotalPaid);
 
+  // Days activated: the DELTA between cumulative entitlement before and after.
+  //
+  // This used to floor each payment on its own — and floor() discards the
+  // fraction every single time, so paying one installment in pieces granted
+  // fewer days than paying it at once. $52 as 52 x $1 granted ZERO days,
+  // because floor(1/52 * 15) === 0 each time.
+  //
+  // That was unreachable while allocation rejected below-minimum payments.
+  // Removing the rule made it reachable, and daysActivated feeds
+  // paidThroughDate (recordEvent -> applyPaymentToLockState), which is the
+  // engine's lock decision. A customer paying in full, in instalments, would
+  // have been locked for not paying.
+  //
+  // Deltas off a cumulative floor telescope, so any split of the same money
+  // 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) =>
+    recurringCents > 0
+      ? Math.floor((toCents(total) * input.freqDays) / recurringCents)
+      : 0;
+  const daysActivated =
+    cumulativeDays(newTotalPaid) - cumulativeDays(currentTotalPaid);
+
   // Find next due date: first installment that will still be unpaid after allocation
   const paidIds = new Set(
     allocations.filter((a) => a.newStatus === "PAID").map((a) => a.installmentId),

package/src/index.ts

@@ -9,11 +9,33 @@ export { allocatePayment } from "./calc/allocation";
 export { checkDelinquency } from "./calc/delinquency";
 export { computeDaysActivated } from "./calc/daysActivated";
 
+// --- Lock-state decision (replaces Upya nextStatusUpdate) ---
+export { decideLockState } from "./lockState/decide";
+export type {
+  LockState,
+  ClosureReason,
+  LockStateContract,
+  LockStatePayment,
+  LockStateInput,
+  LockStateOutput,
+} from "./lockState/types";
+
 // --- Operations layer (D1-backed) ---
 export { originateContract } from "./operations/originate";
 export { recordEvent } from "./operations/recordEvent";
 export { recordPayment } from "./operations/recordPayment";
 export { seedContract } from "./operations/seedContract";
+export {
+  snapshotSeedContract,
+  planSnapshotSeed,
+} from "./operations/snapshotSeed";
+export type {
+  SnapshotSeedInput,
+  SnapshotSeedPlan,
+  SnapshotSeedResult,
+} from "./operations/snapshotSeed";
+export { getLockState } from "./operations/getLockState";
+export type { GetLockStateInput } from "./operations/getLockState";
 
 // --- Utilities ---
 export { ulid } from "./utils/ulid";
@@ -59,7 +81,6 @@ export type {
 // --- Errors ---
 export {
   LoanEngineError,
-  PaymentBelowMinimumError,
   ContractAlreadyPaidOffError,
 } from "./types";
 

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