flexpay-engine 0.2.0 → 0.3.0

package/src/operations/recordEvent.ts

@@ -0,0 +1,309 @@
+// ============================================================
+// recordEvent — Canonical event log writer (first-writer)
+// ============================================================
+//
+// Inverts the prior model: engine_events is the source of truth,
+// engine_contracts/installments/payments/lines are projections of it.
+// Single atomic batch: event INSERT + projection writes.
+//
+// PoC scope: only event_type='payment_recorded' triggers projection
+// updates. Other event types throw EVENT_TYPE_UNSUPPORTED until
+// follow-up specs (refunds, originations) implement them.
+//
+// Spec: context/specs/2026-04-30-feat-canonical-engine-event-log.md
+
+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";
+import {
+  ContractAlreadyPaidOffError,
+  type InstallmentState,
+  type InstallmentStatus,
+} from "../types";
+import { fromCents, toCents } from "../utils/cents";
+import { ulid } from "../utils/ulid";
+import {
+  ContractNotFoundError,
+  EngineOperationError,
+  type EngineDb,
+  type RecordEventInput,
+  type RecordEventResult,
+} from "./types";
+
+// engine_events.source (lowercase) → engine_payments.source (legacy enum)
+function mapProjectionSource(
+  source: RecordEventInput["source"],
+): "CHINCHIN" | "PORTAL" | "HISTORICAL" {
+  switch (source) {
+    case "chinchin":
+      return "CHINCHIN";
+    case "portal":
+    case "cash":
+      return "PORTAL";
+    case "upya_legacy":
+    case "manual_correction":
+    case "legacy_backfill":
+      return "HISTORICAL";
+  }
+}
+
+// Idempotency key must be namespaced as `<source>:<ref>` to prevent
+// implicit collisions between channels. Enforced at the boundary so
+// every caller picks an unambiguous key.
+const IDEMPOTENCY_KEY_PATTERN = /^[a-z_]+:.+$/;
+
+export async function recordEvent(
+  db: EngineDb,
+  input: RecordEventInput,
+): Promise<RecordEventResult> {
+  if (!IDEMPOTENCY_KEY_PATTERN.test(input.idempotencyKey)) {
+    throw new EngineOperationError(
+      `idempotencyKey must match '<source>:<ref>' (got: ${input.idempotencyKey})`,
+      "INVALID_IDEMPOTENCY_KEY",
+    );
+  }
+
+  // 1. Idempotency check — caller-supplied key dedupes retries
+  const existing = await db
+    .select({ eventId: engineEvents.eventId })
+    .from(engineEvents)
+    .where(eq(engineEvents.idempotencyKey, input.idempotencyKey))
+    .get();
+
+  if (existing) {
+    return { status: "duplicate", existingEventId: existing.eventId };
+  }
+
+  // 2. PoC scope guard — only payment_recorded triggers projection writes
+  if (input.eventType !== "payment_recorded") {
+    throw new EngineOperationError(
+      `Event type '${input.eventType}' not yet supported in recordEvent`,
+      "EVENT_TYPE_UNSUPPORTED",
+    );
+  }
+
+  // 3. Validate payment-specific inputs
+  if (
+    typeof input.amountCents !== "number" ||
+    !Number.isInteger(input.amountCents) ||
+    input.amountCents <= 0
+  ) {
+    throw new EngineOperationError(
+      `Invalid amountCents: ${input.amountCents}`,
+      "INVALID_AMOUNT",
+    );
+  }
+  if (!input.transactionId) {
+    throw new EngineOperationError(
+      "transactionId is required for payment_recorded events",
+      "MISSING_TRANSACTION_ID",
+    );
+  }
+
+  // 4. Load contract
+  const contract = await db
+    .select()
+    .from(engineContracts)
+    .where(eq(engineContracts.contractNumber, input.contractNumber))
+    .get();
+
+  if (!contract) {
+    throw new ContractNotFoundError(input.contractNumber);
+  }
+  if (contract.status === "COMPLETED") {
+    throw new ContractAlreadyPaidOffError();
+  }
+
+  // 5. Load installments
+  const installmentRows = await db
+    .select()
+    .from(engineInstallments)
+    .where(eq(engineInstallments.contractNumber, input.contractNumber))
+    .all();
+
+  if (installmentRows.length === 0) {
+    throw new ContractNotFoundError(
+      `${input.contractNumber} has no installments in engine ledger`,
+    );
+  }
+
+  // 6. Pure allocation calc (cents → decimals at boundary)
+  const calcInstallments: InstallmentState[] = installmentRows.map((row) => ({
+    id: row.id,
+    sequenceNumber: row.sequenceNumber,
+    amountDue: fromCents(row.amountDueCents),
+    amountPaid: fromCents(row.amountPaidCents),
+    status: row.status as InstallmentStatus,
+    dueDate: new Date(row.dueDate),
+  }));
+
+  const allocation = allocatePayment({
+    paymentAmount: fromCents(input.amountCents),
+    installments: calcInstallments,
+    recurringPayment: fromCents(contract.recurringCents),
+    freqDays: contract.freqDays,
+  });
+
+  // 7. Pre-compute writes
+  const occurredAt = (input.occurredAt ?? new Date()).toISOString();
+  const ingestedAt = new Date().toISOString();
+  const eventId = ulid(input.occurredAt?.getTime());
+  const projectionSource = mapProjectionSource(input.source);
+
+  const eventRow: NewEngineEvent = {
+    eventId,
+    eventType: "payment_recorded",
+    contractNumber: input.contractNumber,
+    source: input.source,
+    sourceRef: input.sourceRef ?? null,
+    amountCents: input.amountCents,
+    occurredAt,
+    ingestedAt,
+    actorId: input.actorId ?? null,
+    payloadJson: input.payload ? JSON.stringify(input.payload) : null,
+    idempotencyKey: input.idempotencyKey,
+  };
+
+  const paymentRow: NewEnginePayment = {
+    contractNumber: input.contractNumber,
+    transactionId: input.transactionId,
+    amountCents: input.amountCents,
+    type: "PAYMENT",
+    source: projectionSource,
+    actorId: input.actorId ?? null,
+    note: input.note ?? null,
+    createdAt: occurredAt,
+  };
+
+  const newTotalPaidCents = toCents(allocation.newTotalPaid);
+  const newRemainingCents = toCents(allocation.newRemainingDebt);
+  const newDaysActivated = contract.daysActivated + allocation.daysActivated;
+  const newContractStatus = allocation.contractFullyPaid
+    ? "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!,
+      installmentId: a.installmentId,
+      amountCents: toCents(a.amountApplied),
+      createdAt: occurredAt,
+    }),
+  );
+
+  const installmentUpdates = allocation.allocations.map((a) =>
+    db
+      .update(engineInstallments)
+      .set({
+        amountPaidCents: toCents(a.newAmountPaid),
+        status: a.newStatus,
+      })
+      .where(eq(engineInstallments.id, a.installmentId)),
+  );
+
+  const contractUpdate = db
+    .update(engineContracts)
+    .set({
+      totalPaidCents: newTotalPaidCents,
+      remainingCents: newRemainingCents,
+      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,
+  // 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),
+    ...paymentLineRows.map((line) =>
+      db.insert(enginePaymentLines).values(line),
+    ),
+    ...installmentUpdates,
+    contractUpdate,
+    ...(lockEventRow
+      ? [db.insert(engineLockStateEvents).values(lockEventRow)]
+      : []),
+  ];
+
+  await db.batch(statements as unknown as Parameters<typeof db.batch>[0]);
+
+  return {
+    status: "recorded",
+    eventId,
+    projection: {
+      totalAllocatedCents: toCents(allocation.totalAllocated),
+      overpaymentCents: toCents(allocation.overpayment),
+      daysActivated: allocation.daysActivated,
+      newTotalPaidCents,
+      newRemainingCents,
+      contractFullyPaid: allocation.contractFullyPaid,
+      nextDueDate: allocation.nextDueDate?.toISOString() ?? null,
+    },
+  };
+}

package/src/operations/recordPayment.ts

@@ -1,191 +1,79 @@
 // ============================================================
-// recordPayment — Allocate a payment against an engine contract
+// recordPayment — Thin wrapper over recordEvent (legacy entry point)
 // ============================================================
-
-import { eq } from "drizzle-orm";
-import { allocatePayment } from "../calc/allocation";
-import {
-  engineContracts,
-  engineInstallments,
-  enginePayments,
-  enginePaymentLines,
-  type NewEnginePayment,
-  type NewEnginePaymentLine,
-} from "../schema";
+//
+// Existed before the canonical event log. Now delegates to recordEvent
+// with a derived idempotency key so legacy callers get event-log
+// participation for free.
+//
+// New callers should prefer recordEvent directly.
+
+import { recordEvent } from "./recordEvent";
 import {
-  ContractAlreadyPaidOffError,
-  type InstallmentState,
-  type InstallmentStatus,
-} from "../types";
-import { fromCents, toCents } from "../utils/cents";
-import {
-  ContractNotFoundError,
   EngineOperationError,
   type EngineDb,
+  type EngineEventSource,
   type RecordPaymentInput,
   type RecordPaymentResult,
 } from "./types";
 
-/**
- * Record a payment against a contract in the engine ledger.
- *
- * Flow:
- *   1. Load contract from D1 (throws ContractNotFoundError if missing)
- *   2. Idempotency check: duplicate transactionId → returns { status: "duplicate" }
- *   3. Load installments, convert cents→decimals for calc module
- *   4. Run pure FIFO allocation
- *   5. Pre-compute all D1 writes
- *   6. Atomic batch: INSERT payment + payment_lines (append-only),
- *      UPDATE installments + contract cached totals
- *
- * Caller is responsible for ensuring the contract exists (call seedContract first).
- * This function will throw ContractNotFoundError for unseeded contracts.
- */
+function mapLegacySource(
+  source: RecordPaymentInput["source"],
+): EngineEventSource {
+  switch (source) {
+    case "CHINCHIN":
+      return "chinchin";
+    case "PORTAL":
+      return "portal";
+    case "HISTORICAL":
+      return "legacy_backfill";
+  }
+}
+
 export async function recordPayment(
   db: EngineDb,
   input: RecordPaymentInput,
 ): Promise<RecordPaymentResult> {
-  // 1. Load contract
-  const contract = await db
-    .select()
-    .from(engineContracts)
-    .where(eq(engineContracts.contractNumber, input.contractNumber))
-    .get();
+  const eventInput = {
+    contractNumber: input.contractNumber,
+    eventType: "payment_recorded" as const,
+    source: mapLegacySource(input.source),
+    idempotencyKey: `txn:${input.transactionId}`,
+    sourceRef: input.transactionId,
+    amountCents: input.amountCents,
+    occurredAt: input.paymentDate,
+    actorId: input.actorId,
+    transactionId: input.transactionId,
+    note: input.note,
+  };
 
-  if (!contract) {
-    throw new ContractNotFoundError(input.contractNumber);
-  }
+  const result = await recordEvent(db, eventInput);
 
-  if (contract.status === "COMPLETED") {
-    throw new ContractAlreadyPaidOffError();
+  if (result.status === "duplicate") {
+    return {
+      status: "duplicate",
+      existingPaymentId: 0, // legacy sentinel; transactionId is the lookup
+      eventId: result.existingEventId,
+    };
   }
 
-  if (!Number.isInteger(input.amountCents) || input.amountCents <= 0) {
+  if (!result.projection) {
     throw new EngineOperationError(
-      `Invalid amountCents: ${input.amountCents}`,
-      "INVALID_AMOUNT",
-    );
-  }
-
-  // 2. Idempotency check — duplicate transactionId is a no-op success
-  const existing = await db
-    .select({ id: enginePayments.id })
-    .from(enginePayments)
-    .where(eq(enginePayments.transactionId, input.transactionId))
-    .get();
-
-  if (existing) {
-    return { status: "duplicate", existingPaymentId: existing.id };
-  }
-
-  // 3. Load installments
-  const installmentRows = await db
-    .select()
-    .from(engineInstallments)
-    .where(eq(engineInstallments.contractNumber, input.contractNumber))
-    .all();
-
-  if (installmentRows.length === 0) {
-    throw new ContractNotFoundError(
-      `${input.contractNumber} has no installments in engine ledger`,
+      "recordEvent did not return a projection for payment_recorded event",
+      "MISSING_PROJECTION",
     );
   }
 
-  // 4. Convert to calc-layer types (cents → decimals at boundary)
-  const calcInstallments: InstallmentState[] = installmentRows.map((row) => ({
-    id: row.id,
-    sequenceNumber: row.sequenceNumber,
-    amountDue: fromCents(row.amountDueCents),
-    amountPaid: fromCents(row.amountPaidCents),
-    status: row.status as InstallmentStatus,
-    dueDate: new Date(row.dueDate),
-  }));
-
-  // 5. Pure allocation calc
-  const allocation = allocatePayment({
-    paymentAmount: fromCents(input.amountCents),
-    installments: calcInstallments,
-    minPayment: fromCents(contract.minPaymentCents),
-    recurringPayment: fromCents(contract.recurringCents),
-    freqDays: contract.freqDays,
-  });
-
-  // 6. Pre-compute all D1 writes
-  const now = (input.paymentDate ?? new Date()).toISOString();
-  const updatedAt = new Date().toISOString();
-
-  const paymentRow: NewEnginePayment = {
-    contractNumber: input.contractNumber,
-    transactionId: input.transactionId,
-    amountCents: input.amountCents,
-    type: "PAYMENT",
-    source: input.source,
-    actorId: input.actorId ?? null,
-    note: input.note ?? null,
-    createdAt: now,
-  };
-
-  // New totals for contract (in cents)
-  const newTotalPaidCents = toCents(allocation.newTotalPaid);
-  const newRemainingCents = toCents(allocation.newRemainingDebt);
-  const newDaysActivated = contract.daysActivated + allocation.daysActivated;
-  const newContractStatus = allocation.contractFullyPaid
-    ? "COMPLETED"
-    : "ACTIVE";
-
-  // 7. Pre-compute all writes, then execute in ONE atomic batch.
-  // Uses transactionId (not auto-increment id) as payment_lines FK
-  // so everything fits in a single db.batch() — no orphan risk.
-  const paymentLineRows: NewEnginePaymentLine[] = allocation.allocations.map(
-    (a) => ({
-      transactionId: input.transactionId,
-      installmentId: a.installmentId,
-      amountCents: toCents(a.amountApplied),
-      createdAt: now,
-    }),
-  );
-
-  const installmentUpdates = allocation.allocations.map((a) => {
-    return db
-      .update(engineInstallments)
-      .set({
-        amountPaidCents: toCents(a.newAmountPaid),
-        status: a.newStatus,
-      })
-      .where(eq(engineInstallments.id, a.installmentId));
-  });
-
-  const contractUpdate = db
-    .update(engineContracts)
-    .set({
-      totalPaidCents: newTotalPaidCents,
-      remainingCents: newRemainingCents,
-      daysActivated: newDaysActivated,
-      status: newContractStatus,
-      updatedAt,
-    })
-    .where(eq(engineContracts.contractNumber, input.contractNumber));
-
-  const statements = [
-    db.insert(enginePayments).values(paymentRow),
-    ...paymentLineRows.map((line) => db.insert(enginePaymentLines).values(line)),
-    ...installmentUpdates,
-    contractUpdate,
-  ];
-
-  await db.batch(
-    statements as unknown as Parameters<typeof db.batch>[0],
-  );
-
   return {
     status: "recorded",
-    paymentId: 0, // no auto-increment — use transactionId for lookups
-    totalAllocatedCents: toCents(allocation.totalAllocated),
-    overpaymentCents: toCents(allocation.overpayment),
-    daysActivated: allocation.daysActivated,
-    newTotalPaidCents,
-    newRemainingCents,
-    contractFullyPaid: allocation.contractFullyPaid,
-    nextDueDate: allocation.nextDueDate?.toISOString() ?? null,
+    paymentId: 0,
+    totalAllocatedCents: result.projection.totalAllocatedCents,
+    overpaymentCents: result.projection.overpaymentCents,
+    daysActivated: result.projection.daysActivated,
+    newTotalPaidCents: result.projection.newTotalPaidCents,
+    newRemainingCents: result.projection.newRemainingCents,
+    contractFullyPaid: result.projection.contractFullyPaid,
+    nextDueDate: result.projection.nextDueDate,
+    eventId: result.eventId,
   };
 }