flexpay-engine 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexpay-engine",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "FlexPay loan servicing engine — pricing, schedules, allocation, delinquency",
   "license": "MIT",
   "main": "src/index.ts",

package/src/index.ts

@@ -11,9 +11,13 @@ export { computeDaysActivated } from "./calc/daysActivated";
 
 // --- Operations layer (D1-backed) ---
 export { originateContract } from "./operations/originate";
+export { recordEvent } from "./operations/recordEvent";
 export { recordPayment } from "./operations/recordPayment";
 export { seedContract } from "./operations/seedContract";
 
+// --- Utilities ---
+export { ulid } from "./utils/ulid";
+
 // --- Money helpers ---
 export { toCents, fromCents, formatCents } from "./utils/cents";
 
@@ -36,8 +40,12 @@ export type {
 // --- Operation types ---
 export type {
   EngineDb,
+  EngineEventSource,
+  EngineEventType,
   OriginateContractInput,
   OriginateContractResult,
+  RecordEventInput,
+  RecordEventResult,
   RecordPaymentInput,
   RecordPaymentResult,
 } from "./operations/types";

package/src/operations/recordEvent.ts

@@ -0,0 +1,253 @@
+// ============================================================
+// 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 {
+  engineContracts,
+  engineEvents,
+  engineInstallments,
+  enginePayments,
+  enginePaymentLines,
+  type NewEngineEvent,
+  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,
+    minPayment: fromCents(contract.minPaymentCents),
+    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";
+
+  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,
+    })
+    .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.
+  const statements = [
+    db.insert(engineEvents).values(eventRow),
+    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",
+    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,
   };
 }

package/src/operations/types.ts

@@ -58,10 +58,74 @@ export type RecordPaymentResult =
       newRemainingCents: number;
       contractFullyPaid: boolean;
       nextDueDate: string | null;
+      /** ULID of the canonical event log entry. */
+      eventId: string;
     }
   | {
       status: "duplicate";
       existingPaymentId: number;
+      eventId: string;
+    };
+
+// ============================================================
+// recordEvent — canonical event log writer
+// ============================================================
+
+/** Source channel for an engine event. */
+export type EngineEventSource =
+  | "chinchin"
+  | "portal"
+  | "cash"
+  | "upya_legacy"
+  | "manual_correction"
+  | "legacy_backfill";
+
+/** Event type. PoC only supports 'payment_recorded'. */
+export type EngineEventType =
+  | "payment_recorded"
+  | "payment_reversed"
+  | "contract_originated";
+
+/** Inputs for recording an event in the canonical log. */
+export interface RecordEventInput {
+  contractNumber: string;
+  eventType: EngineEventType;
+  source: EngineEventSource;
+  /** Caller-supplied dedupe key. UNIQUE on engine_events. */
+  idempotencyKey: string;
+  /** Upstream id for traceability — e.g. chinchin order_id, upya transactionNumber. */
+  sourceRef?: string;
+  /** Required for 'payment_recorded'. Cents. */
+  amountCents?: number;
+  /** Real-world time. Defaults to now(). */
+  occurredAt?: Date;
+  actorId?: string;
+  /** Event-type-specific structured data. */
+  payload?: Record<string, unknown>;
+  /** For 'payment_recorded' — the engine_payments.transaction_id. UNIQUE. */
+  transactionId?: string;
+  note?: string;
+}
+
+/** Result of recording an event. */
+export type RecordEventResult =
+  | {
+      status: "recorded";
+      eventId: string;
+      /** Projection updates applied alongside event INSERT. Only present for payment events. */
+      projection?: {
+        totalAllocatedCents: number;
+        overpaymentCents: number;
+        daysActivated: number;
+        newTotalPaidCents: number;
+        newRemainingCents: number;
+        contractFullyPaid: boolean;
+        nextDueDate: string | null;
+      };
+    }
+  | {
+      status: "duplicate";
+      existingEventId: string;
     };
 
 // ============================================================

package/src/schema/index.ts

@@ -113,6 +113,36 @@ export const enginePaymentLines = sqliteTable(
   }),
 );
 
+// --- Events (APPEND-ONLY canonical log) ----------------------
+//
+// First-writer event log per spec 2026-04-30. Engine state
+// (contracts, installments, payments, lines) is a projection
+// of this table. Never UPDATE or DELETE rows.
+// Reversals/corrections are NEW events referencing the original
+// via payload_json.original_event_id.
+
+export const engineEvents = sqliteTable(
+  "engine_events",
+  {
+    eventId: text("event_id").primaryKey(), // ULID — sortable, globally unique
+    eventType: text("event_type").notNull(), // payment_recorded | payment_reversed | contract_originated | ...
+    contractNumber: text("contract_number").notNull(),
+    source: text("source").notNull(), // chinchin | portal | cash | upya_legacy | manual_correction | legacy_backfill
+    sourceRef: text("source_ref"), // upstream id: chinchin order_id, etc.
+    amountCents: integer("amount_cents"), // null for non-payment events
+    occurredAt: text("occurred_at").notNull(), // real-world time, ISO 8601
+    ingestedAt: text("ingested_at").notNull(), // when we received it, ISO 8601
+    actorId: text("actor_id"),
+    payloadJson: text("payload_json"), // event-type-specific structured data
+    idempotencyKey: text("idempotency_key").notNull().unique(), // dedupe key
+  },
+  (t) => ({
+    contractIdx: index("idx_events_contract").on(t.contractNumber),
+    occurredIdx: index("idx_events_occurred").on(t.occurredAt),
+    sourceIdx: index("idx_events_source").on(t.source),
+  }),
+);
+
 // --- Type exports --------------------------------------------
 
 export type EngineContract = typeof engineContracts.$inferSelect;
@@ -123,3 +153,5 @@ export type EnginePayment = typeof enginePayments.$inferSelect;
 export type NewEnginePayment = typeof enginePayments.$inferInsert;
 export type EnginePaymentLine = typeof enginePaymentLines.$inferSelect;
 export type NewEnginePaymentLine = typeof enginePaymentLines.$inferInsert;
+export type EngineEvent = typeof engineEvents.$inferSelect;
+export type NewEngineEvent = typeof engineEvents.$inferInsert;

package/src/utils/ulid.ts

@@ -0,0 +1,36 @@
+// ULID — Crockford-base32, 48-bit timestamp + 80-bit randomness.
+// 26 chars, lexicographically sortable by time. No deps.
+// Spec: https://github.com/ulid/spec
+//
+// Randomness from crypto.getRandomValues (Workers/V8 globalThis.crypto).
+// Within the same millisecond, ULIDs are NOT guaranteed monotonic — two
+// calls in the same ms may sort by random suffix, not insertion order.
+// For payment events at chinchin/portal volume, sub-ms collisions are
+// vanishingly rare; if monotonicity is needed later, add a per-ms counter.
+
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford base32
+
+function encodeTime(now: number, len: number): string {
+  let out = "";
+  for (let i = len - 1; i >= 0; i--) {
+    const mod = now % 32;
+    out = ENCODING[mod] + out;
+    now = (now - mod) / 32;
+  }
+  return out;
+}
+
+function encodeRandom(len: number): string {
+  const bytes = new Uint8Array(len);
+  // crypto.getRandomValues is available in Cloudflare Workers and Node 20+.
+  (globalThis as unknown as { crypto: Crypto }).crypto.getRandomValues(bytes);
+  let out = "";
+  for (let i = 0; i < len; i++) {
+    out += ENCODING[bytes[i]! % 32];
+  }
+  return out;
+}
+
+export function ulid(now: number = Date.now()): string {
+  return encodeTime(now, 10) + encodeRandom(16);
+}