flexpay-engine 0.2.1 → 0.3.0

package/src/operations/snapshotSeed.ts

@@ -0,0 +1,377 @@
+// ============================================================
+// snapshotSeedContract — Seed an existing contract from Upya's snapshot
+// ============================================================
+//
+// Payments-truth cutover S1 (plan: context/specs/2026-07-11-payments-truth-
+// implementation-plan.md, rows S1/S2, ruling §H1).
+//
+// UNLIKE seedContract (which REPLAYS history through the engine's day-formula),
+// this seeds state DIRECTLY from Upya's authoritative snapshot, because replay
+// diverges from Upya universally (+8.5d median) and next_status_update is
+// path-dependent (only 25.5% reconstructable). Snapshot dissolves that by
+// construction, setting BOTH coupled dimensions:
+//
+//   1. TIME  — paid_through_date := Upya.next_status_update  (verbatim).
+//              Locks match Upya EXACTLY at cutover. NOT derived from day-math.
+//   2. MONEY — FIFO-allocate Upya.total_paid across the derived schedule, so the
+//              NEXT real payment lands on the correct installment + paid_off works.
+//
+// No historical replay. One synthetic `seed_snapshot` event (skipped by the W1
+// projector's event_type='payment_recorded' filter, so it never double-posts
+// into MAIN — MAIN already holds the historical payments). No engine_payments /
+// payment_lines rows: a snapshot has no real transaction to trace; the money
+// dimension lives on installment.amount_paid + contract.total_paid.
+//
+// INSERT-only: throws if the contract already exists. Re-seed policy (for the
+// ~902 stale lazy-replay contracts) is the S2 orchestrator's job, not the
+// primitive's. NOT gated on dealOptionId — caller supplies flat pricing inputs
+// derived from a deal_option OR from W3a legacyPricing for deal-less contracts.
+
+import { eq } from "drizzle-orm";
+import { calculatePricing } from "../calc/pricing";
+import { generateSchedule } from "../calc/schedule";
+import { allocatePayment } from "../calc/allocation";
+import { decideLockStateFromPaidThrough, lockBoundary } from "../lockState/decide";
+import type { InstallmentState, InstallmentStatus } from "../types";
+import type { LockStateContract } from "../lockState/types";
+import {
+  engineContracts,
+  engineEvents,
+  engineInstallments,
+  engineLockStateEvents,
+  type NewEngineContract,
+  type NewEngineEvent,
+  type NewEngineInstallment,
+  type NewEngineLockStateEvent,
+} from "../schema";
+import { toCents } from "../utils/cents";
+import { ulid } from "../utils/ulid";
+import {
+  EngineOperationError,
+  EngineSeedError,
+  type EngineDb,
+} from "./types";
+
+const DEFAULT_TIMEZONE = "America/Caracas";
+
+/** Everything the primitive needs to snapshot-seed one contract. */
+export interface SnapshotSeedInput {
+  contractNumber: string;
+  profileId: string | null;
+  storeId: number | null;
+  /** NOT gated — null for deal-less legacy contracts (schedule derived by caller). */
+  dealOptionId: number | null;
+
+  // Flat pricing inputs — from a deal_option snapshot OR W3a legacyPricing.
+  basePrice: number;
+  markupPct: number;
+  downPaymentPct: number;
+  numInstallments: number;
+  freqDays: number;
+  minPaymentDivisor: number;
+  signingDate: Date;
+
+  // Lock config (optional — engine defaults).
+  graceDays?: number;
+  timezone?: string;
+
+  /** TIME dimension: paid_through_date is set to this verbatim. Upya's nsu. */
+  nextStatusUpdate: Date;
+  /** MONEY dimension: FIFO-allocated across the schedule. Dollars (Upya total_paid). */
+  totalPaid: number;
+
+  /** Wall-clock for the lock-state decision. Defaults to now(). */
+  asOf?: Date;
+}
+
+/** Pre-computed rows for one snapshot seed — pure, no I/O. */
+export interface SnapshotSeedPlan {
+  contractRow: NewEngineContract;
+  installmentRows: NewEngineInstallment[];
+  eventRow: NewEngineEvent;
+  lockEventRow: NewEngineLockStateEvent;
+  summary: {
+    contractNumber: string;
+    paidThroughDate: string;
+    lockState: string;
+    totalPaidCents: number;
+    numInstallments: number;
+  };
+}
+
+export type SnapshotSeedResult = SnapshotSeedPlan["summary"];
+
+function isValidDate(d: unknown): d is Date {
+  return d instanceof Date && !Number.isNaN(d.getTime());
+}
+
+/**
+ * Pure: compute every row a snapshot seed writes. No DB access.
+ * Exhaustively unit-tested; the persist wrapper is thin glue.
+ */
+export function planSnapshotSeed(input: SnapshotSeedInput): SnapshotSeedPlan {
+  // ---- Validation (NOT dealOptionId — deal-less is legal) ----
+  if (input.numInstallments <= 0) {
+    throw new EngineSeedError(
+      input.contractNumber,
+      `invalid numInstallments: ${input.numInstallments}`,
+    );
+  }
+  if (!Number.isFinite(input.basePrice) || input.basePrice <= 0) {
+    throw new EngineSeedError(
+      input.contractNumber,
+      `invalid basePrice: ${input.basePrice}`,
+    );
+  }
+  if (!isValidDate(input.nextStatusUpdate)) {
+    throw new EngineSeedError(
+      input.contractNumber,
+      "nextStatusUpdate is not a valid date",
+    );
+  }
+  if (!isValidDate(input.signingDate)) {
+    throw new EngineSeedError(
+      input.contractNumber,
+      "signingDate is not a valid date",
+    );
+  }
+  if (!Number.isFinite(input.totalPaid) || input.totalPaid < 0) {
+    throw new EngineSeedError(
+      input.contractNumber,
+      `invalid totalPaid: ${input.totalPaid}`,
+    );
+  }
+  if (!Number.isInteger(input.freqDays) || input.freqDays <= 0) {
+    // freqDays <= 0 collapses the schedule onto one date + degenerates day-math.
+    throw new EngineSeedError(
+      input.contractNumber,
+      `invalid freqDays: ${input.freqDays}`,
+    );
+  }
+  if (input.numInstallments > 600) {
+    // Real terms are <= ~52; bound the batch statement count (D1 limit).
+    throw new EngineSeedError(
+      input.contractNumber,
+      `numInstallments too large: ${input.numInstallments}`,
+    );
+  }
+
+  const asOf = input.asOf ?? new Date();
+  const graceDays = input.graceDays ?? 0;
+  const timezone = input.timezone ?? DEFAULT_TIMEZONE;
+  const nowIso = asOf.toISOString();
+
+  // ---- 1. Pure pricing + schedule ----
+  const pricing = calculatePricing({
+    basePrice: input.basePrice,
+    markupPct: input.markupPct,
+    downPaymentPct: input.downPaymentPct,
+    numInstallments: input.numInstallments,
+    minPaymentDivisor: input.minPaymentDivisor,
+  });
+
+  const schedule = generateSchedule({
+    signingDate: input.signingDate,
+    downPayment: pricing.downPayment,
+    recurringPayment: pricing.recurringPayment,
+    numInstallments: input.numInstallments,
+    freqDays: input.freqDays,
+    financedAmount: pricing.financedAmount,
+    totalCost: pricing.totalCost,
+  });
+
+  // ---- 2. FIFO-allocate the MONEY dimension across the schedule ----
+  // Key installments by sequenceNumber (autoincrement ids don't exist pre-insert;
+  // a snapshot writes no payment_lines, so sequenceNumber is a sufficient key).
+  // (The minPayment=0 exemption this used to pass is gone — allocation no longer
+  // gates on amount at all.)
+  const calcInstallments: InstallmentState[] = schedule.map((inst) => ({
+    id: inst.sequenceNumber,
+    sequenceNumber: inst.sequenceNumber,
+    amountDue: inst.amountDue,
+    amountPaid: 0,
+    status: "PENDING" as InstallmentStatus,
+    dueDate: inst.dueDate,
+  }));
+
+  const allocation = allocatePayment({
+    paymentAmount: input.totalPaid,
+    installments: calcInstallments,
+    recurringPayment: pricing.recurringPayment,
+    freqDays: input.freqDays,
+  });
+
+  const paidBySeq = new Map(
+    allocation.allocations.map((a) => [
+      a.sequenceNumber,
+      { amountPaid: a.newAmountPaid, status: a.newStatus },
+    ]),
+  );
+
+  const installmentRows: NewEngineInstallment[] = schedule.map((inst) => {
+    const paid = paidBySeq.get(inst.sequenceNumber);
+    return {
+      contractNumber: input.contractNumber,
+      sequenceNumber: inst.sequenceNumber,
+      dueDate: inst.dueDate.toISOString(),
+      amountDueCents: toCents(inst.amountDue),
+      amountPaidCents: paid ? toCents(paid.amountPaid) : 0,
+      status: paid ? paid.status : "PENDING",
+    };
+  });
+
+  // ---- 3. TIME dimension: paid_through := nsu verbatim ----
+  const paidThrough = input.nextStatusUpdate;
+  const paidThroughIso = paidThrough.toISOString();
+
+  // ---- 4. Lock state from the snapshot's paid_through ----
+  // A fully-paid snapshot is paid_off — it must NOT derive 'locked' from a past
+  // nsu (a completed contract is never locked). Closure short-circuits decide's
+  // time classification, keeping status + lock state consistent.
+  const fullyPaid = allocation.contractFullyPaid;
+  const lockContract: LockStateContract = {
+    id: input.contractNumber,
+    signedAt: input.signingDate.toISOString(),
+    paymentFreqDays: input.freqDays,
+    upfrontDays: 0,
+    graceDays,
+    timezone,
+    totalScheduledPayments: input.numInstallments,
+    closure: fullyPaid ? "paid_off" : undefined,
+    closureAt: fullyPaid ? nowIso : undefined,
+  };
+  const lock = decideLockStateFromPaidThrough({
+    contract: lockContract,
+    paidThroughDate: paidThrough,
+    asOf,
+  });
+
+  const totalPaidCents = toCents(allocation.newTotalPaid);
+  const remainingCents = toCents(allocation.newRemainingDebt);
+  const totalCostCents = toCents(pricing.totalCost);
+
+  const contractRow: NewEngineContract = {
+    contractNumber: input.contractNumber,
+    profileId: input.profileId,
+    storeId: input.storeId,
+    dealOptionId: input.dealOptionId,
+    totalCostCents,
+    downPaymentCents: toCents(pricing.downPayment),
+    financedCents: toCents(pricing.financedAmount),
+    recurringCents: toCents(pricing.recurringPayment),
+    minPaymentCents: toCents(pricing.minPayment),
+    numInstallments: input.numInstallments,
+    freqDays: input.freqDays,
+    signingDate: input.signingDate.toISOString(),
+    status: fullyPaid ? "COMPLETED" : "ACTIVE",
+    totalPaidCents,
+    remainingCents,
+    daysActivated: allocation.daysActivated,
+    graceDays,
+    timezone,
+    closure: fullyPaid ? "paid_off" : null,
+    closureAt: fullyPaid ? nowIso : null,
+    closureReason: fullyPaid ? "seed_snapshot_paid_off" : null,
+    lastLockState: lock.state,
+    lastLockStateAt: nowIso,
+    paidThroughDate: paidThroughIso,
+    // Lock-boundary cache (see lockBoundary() + migration 0004): defined
+    // whenever paidThrough exists and the contract isn't terminal.
+    nextStateChangeAt:
+      paidThroughIso && !fullyPaid
+        ? lockBoundary(new Date(paidThroughIso), graceDays).toISOString()
+        : null,
+    seededFrom: "upya",
+    createdAt: nowIso,
+    updatedAt: nowIso,
+  };
+
+  // ---- 5. ONE synthetic seed_snapshot event (projector skips it) ----
+  const eventRow: NewEngineEvent = {
+    eventId: ulid(asOf.getTime()),
+    eventType: "seed_snapshot",
+    contractNumber: input.contractNumber,
+    source: "legacy_backfill",
+    sourceRef: null,
+    amountCents: totalPaidCents,
+    occurredAt: nowIso,
+    ingestedAt: nowIso,
+    actorId: null,
+    payloadJson: JSON.stringify({
+      snapshot: "upya",
+      nextStatusUpdate: paidThroughIso,
+      totalPaidCents,
+      lockState: lock.state,
+    }),
+    idempotencyKey: `legacy_backfill:${input.contractNumber}`,
+  };
+
+  // ---- 6. Lock-state transition event (null → seeded state) ----
+  const lockEventRow: NewEngineLockStateEvent = {
+    eventId: ulid(asOf.getTime()),
+    contractNumber: input.contractNumber,
+    fromState: null,
+    toState: lock.state,
+    reason: lock.reason,
+    computedAt: nowIso,
+    paidThroughDate: paidThroughIso,
+    nextStateChangeAt: lock.nextStateChangeAt?.toISOString() ?? null,
+    trigger: "seed",
+  };
+
+  return {
+    contractRow,
+    installmentRows,
+    eventRow,
+    lockEventRow,
+    summary: {
+      contractNumber: input.contractNumber,
+      paidThroughDate: paidThroughIso,
+      lockState: lock.state,
+      totalPaidCents,
+      numInstallments: input.numInstallments,
+    },
+  };
+}
+
+/**
+ * Snapshot-seed one contract into the engine ledger, atomically.
+ *
+ * INSERT-only: throws EngineOperationError('CONTRACT_EXISTS') if the contract
+ * already exists in engine D1. Re-seed / wipe policy is the S2 orchestrator's
+ * responsibility, kept out of the primitive so it stays pure + atomic.
+ */
+export async function snapshotSeedContract(
+  db: EngineDb,
+  input: SnapshotSeedInput,
+): Promise<SnapshotSeedResult> {
+  const existing = await db
+    .select({ contractNumber: engineContracts.contractNumber })
+    .from(engineContracts)
+    .where(eq(engineContracts.contractNumber, input.contractNumber))
+    .get();
+
+  if (existing) {
+    throw new EngineOperationError(
+      `Contract ${input.contractNumber} already exists in engine ledger — re-seed is the caller's responsibility`,
+      "CONTRACT_EXISTS",
+    );
+  }
+
+  const plan = planSnapshotSeed(input);
+
+  // Atomic batch: contract + installments + seed event + lock event.
+  // Individual inserts (D1 bound-parameter limit is 100/statement).
+  const statements = [
+    db.insert(engineContracts).values(plan.contractRow),
+    ...plan.installmentRows.map((row) =>
+      db.insert(engineInstallments).values(row),
+    ),
+    db.insert(engineEvents).values(plan.eventRow),
+    db.insert(engineLockStateEvents).values(plan.lockEventRow),
+  ];
+
+  await db.batch(statements as unknown as Parameters<typeof db.batch>[0]);
+
+  return plan.summary;
+}

package/src/schema/index.ts

@@ -38,12 +38,63 @@ export const engineContracts = sqliteTable("engine_contracts", {
   remainingCents: integer("remaining_cents").notNull().default(0),
   daysActivated: integer("days_activated").notNull().default(0),
 
+  // Lock-state config (see spec 2026-05-22-feat-lock-state-decision)
+  graceDays: integer("grace_days").notNull().default(0),
+  timezone: text("timezone").notNull().default("America/Caracas"),
+
+  // Closure — set by closeContract op, absorbing terminal state
+  closure: text("closure"), // 'paid_off' | 'repossessed' | 'written_off' | NULL
+  closureAt: text("closure_at"),
+  closureReason: text("closure_reason"),
+
+  // Lock-state read cache (truth is engine_lock_state_events)
+  lastLockState: text("last_lock_state"),
+  lastLockStateAt: text("last_lock_state_at"),
+  /** Cumulative paid-through cache. max(prev, paymentDay) + daysActivated. */
+  paidThroughDate: text("paid_through_date"),
+  /**
+   * Denormalized lock boundary: paidThrough + graceDays + 1 day (see
+   * lockBoundary() in lockState/decide.ts). Kept even when locked (past
+   * date) so bulk `date < now` sweeps can find overdue contracts. NULL for
+   * provisioning (no paidThrough) and terminal (closure set) contracts.
+   */
+  nextStateChangeAt: text("next_state_change_at"),
+
   // Provenance
   seededFrom: text("seeded_from").notNull(), // 'supabase' | 'upya' | 'origination'
   createdAt: text("created_at").notNull(), // ISO 8601
   updatedAt: text("updated_at").notNull(), // ISO 8601
 });
 
+// --- Lock-state events (APPEND-ONLY) -------------------------
+//
+// One row per state transition. The decision function reads contracts +
+// payments + computes state; this table records when state changed.
+// R2-mirrored via the existing archive pipeline.
+
+export const engineLockStateEvents = sqliteTable(
+  "engine_lock_state_events",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    eventId: text("event_id").notNull().unique(), // ULID
+    contractNumber: text("contract_number")
+      .notNull()
+      .references(() => engineContracts.contractNumber),
+    fromState: text("from_state"), // NULL on first computation
+    toState: text("to_state").notNull(),
+    reason: text("reason").notNull(),
+    computedAt: text("computed_at").notNull(),
+    paidThroughDate: text("paid_through_date"),
+    nextStateChangeAt: text("next_state_change_at"),
+    trigger: text("trigger").notNull(), // 'payment' | 'cron' | 'rpc' | 'origination' | 'closure'
+    archivedAt: text("archived_at"), // R2 mirror timestamp; NULL until swept
+  },
+  (t) => ({
+    contractIdx: index("idx_lock_events_contract").on(t.contractNumber, t.computedAt),
+    stateIdx: index("idx_lock_events_state").on(t.toState, t.computedAt),
+  }),
+);
+
 // --- Installments --------------------------------------------
 
 export const engineInstallments = sqliteTable(
@@ -155,3 +206,5 @@ export type EnginePaymentLine = typeof enginePaymentLines.$inferSelect;
 export type NewEnginePaymentLine = typeof enginePaymentLines.$inferInsert;
 export type EngineEvent = typeof engineEvents.$inferSelect;
 export type NewEngineEvent = typeof engineEvents.$inferInsert;
+export type EngineLockStateEvent = typeof engineLockStateEvents.$inferSelect;
+export type NewEngineLockStateEvent = typeof engineLockStateEvents.$inferInsert;

package/src/types.ts

@@ -59,7 +59,8 @@ export type InstallmentStatus =
 export interface AllocationInput {
   paymentAmount: number;
   installments: InstallmentState[];
-  minPayment: number;
+  // No minPayment: allocation records, it does not gate. The figure lives on
+  // PricingResult and engine_contracts.min_payment_cents as quoting data.
   recurringPayment: number;
   freqDays: number;
 }
@@ -121,18 +122,6 @@ export class LoanEngineError extends Error {
   }
 }
 
-export class PaymentBelowMinimumError extends LoanEngineError {
-  constructor(
-    public readonly paymentAmount: number,
-    public readonly minPayment: number,
-  ) {
-    super(
-      `Payment ${paymentAmount} is below minimum ${minPayment}`,
-      "PAYMENT_BELOW_MINIMUM",
-    );
-  }
-}
-
 export class ContractAlreadyPaidOffError extends LoanEngineError {
   constructor() {
     super("Contract is already paid off", "CONTRACT_ALREADY_PAIDOFF");

package/src/utils/cents.test.ts

@@ -1,76 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { toCents, fromCents, formatCents } from "./cents";
-
-describe("toCents", () => {
-  test("converts basic decimals", () => {
-    expect(toCents(16.15)).toBe(1615);
-    expect(toCents(0)).toBe(0);
-    expect(toCents(1)).toBe(100);
-    expect(toCents(100)).toBe(10000);
-  });
-
-  test("handles string input (from DB numeric columns)", () => {
-    expect(toCents("16.15")).toBe(1615);
-    expect(toCents("196.80")).toBe(19680);
-    expect(toCents("0")).toBe(0);
-  });
-
-  test("handles the float precision edge cases", () => {
-    // 0.1 + 0.2 === 0.30000000000000004 in IEEE 754
-    expect(toCents(0.1 + 0.2)).toBe(30);
-    expect(toCents(1.005)).toBe(101); // rounds up correctly
-    expect(toCents(196.80000019073486)).toBe(19680); // real incident value
-  });
-
-  test("handles null and undefined gracefully", () => {
-    expect(toCents(null)).toBe(0);
-    expect(toCents(undefined)).toBe(0);
-  });
-
-  test("throws on invalid input", () => {
-    expect(() => toCents(NaN)).toThrow();
-    expect(() => toCents(Infinity)).toThrow();
-    expect(() => toCents("not a number")).toThrow();
-  });
-
-  test("handles negative values (for reversals)", () => {
-    expect(toCents(-16.15)).toBe(-1615);
-    expect(toCents(-0.01)).toBe(-1);
-  });
-});
-
-describe("fromCents", () => {
-  test("converts basic cents", () => {
-    expect(fromCents(1615)).toBe(16.15);
-    expect(fromCents(0)).toBe(0);
-    expect(fromCents(100)).toBe(1);
-    expect(fromCents(19680)).toBe(196.8);
-  });
-
-  test("handles negative values", () => {
-    expect(fromCents(-1615)).toBe(-16.15);
-  });
-
-  test("throws on non-integer input", () => {
-    expect(() => fromCents(16.15)).toThrow();
-    expect(() => fromCents(1.5)).toThrow();
-  });
-});
-
-describe("roundtrip", () => {
-  test("toCents then fromCents returns original", () => {
-    const values = [0, 1, 16.15, 196.8, 1000, 99.99, 0.01, 0.5];
-    for (const v of values) {
-      expect(fromCents(toCents(v))).toBe(v);
-    }
-  });
-});
-
-describe("formatCents", () => {
-  test("formats with 2 decimals", () => {
-    expect(formatCents(1615)).toBe("16.15");
-    expect(formatCents(0)).toBe("0.00");
-    expect(formatCents(100)).toBe("1.00");
-    expect(formatCents(19680)).toBe("196.80");
-  });
-});