okengine 0.18.4 → 0.19.0

package/src/elements/signal/key-ordering.test.ts

@@ -31,11 +31,7 @@ afterEach(async () => {
 
 describe("signal key ordering · memory", () => {
   test("same key: never concurrent; complete in emission order", async () => {
-    const once = signal("order-events", {
-      delivery: "once",
-      retries: 3,
-      deadLetter: true,
-    });
+    const once = signal.once("order-events", { retries: 3, deadLetter: true });
     const bus = await memorySignalDriver.open({
       signals: new Map([[once.name, once]]),
     });
@@ -75,11 +71,7 @@ describe("signal key ordering · memory", () => {
   });
 
   test("different keys: may process concurrently", async () => {
-    const once = signal("order-events", {
-      delivery: "once",
-      retries: 3,
-      deadLetter: true,
-    });
+    const once = signal.once("order-events", { retries: 3, deadLetter: true });
     const bus = await memorySignalDriver.open({
       signals: new Map([[once.name, once]]),
     });
@@ -110,11 +102,7 @@ describe("signal key ordering · memory", () => {
   });
 
   test("no key: unchanged competing-consumer (both may run concurrent)", async () => {
-    const once = signal("order-events", {
-      delivery: "once",
-      retries: 3,
-      deadLetter: true,
-    });
+    const once = signal.once("order-events", { retries: 3, deadLetter: true });
     const bus = await memorySignalDriver.open({
       signals: new Map([[once.name, once]]),
     });
@@ -148,7 +136,7 @@ describe("signal key ordering · memory", () => {
 describe("signal key ordering · postgres", () => {
   test("same-key pending blocked while sibling holds unexpired lease", async () => {
     let t = 10_000;
-    const once = signal("order-events", { delivery: "once", retries: 3 });
+    const once = signal.once("order-events", { retries: 3 });
     const sql = createPostgresSignalFake({ now: () => t });
     const runtime = createSignalRuntime({
       driver: postgresSignalDriver,
@@ -213,11 +201,7 @@ describe("signal key ordering · postgres", () => {
   });
 
   test("emit with key then drain preserves emission order", async () => {
-    const once = signal("order-events", {
-      delivery: "once",
-      retries: 3,
-      deadLetter: true,
-    });
+    const once = signal.once("order-events", { retries: 3, deadLetter: true });
     const bus = await postgresSignalDriver.open({
       signals: new Map([[once.name, once]]),
       sql: createPostgresSignalFake(),
@@ -246,11 +230,7 @@ describe("signal key ordering · lease reclaim", () => {
     const marker = join(dir, "claimed");
     try {
       let t = 5_000;
-      const once = signal("order-events", {
-        delivery: "once",
-        retries: 3,
-        deadLetter: true,
-      });
+      const once = signal.once("order-events", { retries: 3, deadLetter: true });
       const r1 = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,

package/src/elements/signal/lease-reclaim.test.ts

@@ -30,11 +30,7 @@ describe("signal lease reclaim", () => {
     const marker = join(dir, "claimed");
     try {
       let t = 5_000;
-      const once = signal("order-placed", {
-        delivery: "once",
-        retries: 3,
-        deadLetter: true,
-      });
+      const once = signal.once("order-placed", { retries: 3, deadLetter: true });
       const r1 = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,
@@ -83,7 +79,7 @@ describe("signal lease reclaim", () => {
 
   test("postgres: expired inflight reclaimed in the same claim query", async () => {
     let t = 10_000;
-    const once = signal("order-placed", { delivery: "once", retries: 3 });
+    const once = signal.once("order-placed", { retries: 3 });
     const sql = createPostgresSignalFake({ now: () => t });
     const runtime = createSignalRuntime({
       driver: postgresSignalDriver,

package/src/elements/signal/optional-emit.test.ts

@@ -1,5 +1,5 @@
 /**
- * Zero-subscriber emit — OKE1042 when optional is unset/false; allow when true.
+ * Zero-subscriber emit — OKE1240 when optional is unset/false; allow when true.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
@@ -44,8 +44,8 @@ for (const { label, driver, setup } of [
   },
 ] as const) {
   describe(`signal optional emit · ${label}`, () => {
-    test("optional unset/false: emit with zero subscribers throws OKE1042", async () => {
-      const once = signal("order-placed", { delivery: "once" });
+    test("optional unset/false: emit with zero subscribers throws OKE1240", async () => {
+      const once = signal.once("order-placed");
       expect(once.optional).toBe(false);
       const bus = await openBus(driver, [once], setup());
 
@@ -56,16 +56,13 @@ for (const { label, driver, setup } of [
         err = e;
       }
       expect(err).toBeInstanceOf(OkeError);
-      expect((err as OkeError).code).toBe(1042);
-      expect((err as Error).message).toContain("OKE1042");
+      expect((err as OkeError).code).toBe(1240);
+      expect((err as Error).message).toContain("OKE1240");
       expect((err as Error).message).toContain("no subscriber");
     });
 
     test("optional: true allows emit with zero subscribers", async () => {
-      const once = signal("hook", {
-        delivery: "once",
-        optional: true,
-      });
+      const once = signal.once("hook", { optional: true });
       const bus = await openBus(driver, [once], setup());
       await bus.emit("hook", { ok: true });
       await bus.drain();

package/src/elements/signal/order-lifecycle.test.ts

@@ -42,20 +42,11 @@ afterEach(async () => {
 describe("signal order lifecycle · once + broadcast + live", () => {
   test("one placed order: exclusive fulfill, fan-out side effects, live status replay", async () => {
     // once — queued job: exactly one competing consumer fulfills
-    const orderPlaced = signal("order-placed", {
-      delivery: "once",
-      retries: 2,
-      deadLetter: true,
-    });
+    const orderPlaced = signal.once("order-placed", { retries: 2, deadLetter: true });
     // broadcast — same domain event fan-out: every subscriber gets a copy
-    const orderChanged = signal("order-changed", {
-      delivery: "broadcast",
-    });
+    const orderChanged = signal.broadcast("order-changed");
     // live — client-visible status feed (bus.live; createClient has no subscribe yet)
-    const orderStatus = signal("order-status", {
-      delivery: "live",
-      optional: true,
-    });
+    const orderStatus = signal.live("order-status", { optional: true });
 
     const bus = await memorySignalDriver.open({
       signals: new Map([
@@ -118,11 +109,7 @@ describe("signal order lifecycle · once + broadcast + live", () => {
 
   test("once retries then DLQ still apply inside the same domain", async () => {
     // Light reuse of once retry/DLQ — full matrix lives in delivery-modes.test.ts.
-    const orderPlaced = signal("order-placed", {
-      delivery: "once",
-      retries: 1,
-      deadLetter: true,
-    });
+    const orderPlaced = signal.once("order-placed", { retries: 1, deadLetter: true });
     const bus = await memorySignalDriver.open({
       signals: new Map([[orderPlaced.name, orderPlaced]]),
     });

package/src/elements/signal/orphan-messages.test.ts

@@ -28,11 +28,7 @@ describe("orphan signal messages", () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-signal-orphan-"));
     const durablePath = join(dir, "bus.json");
     try {
-      const legacy = signal("legacy-shipped", {
-        delivery: "once",
-        retries: 0,
-        deadLetter: true,
-      });
+      const legacy = signal.once("legacy-shipped", { retries: 0, deadLetter: true });
       const runtime = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,
@@ -75,11 +71,7 @@ describe("orphan signal messages", () => {
       openRuntimes.pop();
 
       // Re-declare → DLQ processable again via replay.
-      const restored = signal("legacy-shipped", {
-        delivery: "once",
-        retries: 0,
-        deadLetter: true,
-      });
+      const restored = signal.once("legacy-shipped", { retries: 0, deadLetter: true });
       const again = await reconcileSignals([restored], store);
       expect(again.active).toEqual(["legacy-shipped"]);
       expect(again.orphaned).toEqual([]);
@@ -111,10 +103,7 @@ describe("orphan signal messages", () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-signal-orphan-pend-"));
     const durablePath = join(dir, "bus.json");
     try {
-      const once = signal("legacy-shipped", {
-        delivery: "once",
-        optional: true,
-      });
+      const once = signal.once("legacy-shipped", { optional: true });
       const runtime = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,
@@ -126,7 +115,7 @@ describe("orphan signal messages", () => {
       await runtime.close();
       openRuntimes.pop();
 
-      const other = signal("order-placed", { delivery: "once" });
+      const other = signal.once("order-placed");
       const next = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,

package/src/elements/signal/reconcile.test.ts

@@ -5,8 +5,8 @@ import { createMemorySignalConfigStore, reconcileSignals } from "./reconcile.ts"
 describe("reconcileSignals", () => {
   test("marks a removed signal orphaned without deleting it", async () => {
     const store = createMemorySignalConfigStore();
-    const a = signal("order-placed", { delivery: "once" });
-    const b = signal("legacy-shipped", { delivery: "once" });
+    const a = signal.once("order-placed");
+    const b = signal.once("legacy-shipped");
 
     await reconcileSignals([a, b], store);
     const second = await reconcileSignals([a], store);

package/src/elements/signal/runtime.ts

@@ -68,7 +68,7 @@ export interface SignalRuntime {
    */
   live(name: string, opts?: { readonly afterId?: string }): AsyncIterable<LiveEvent>;
   /**
-   * Validate a live resume cursor (auto-starts). Throws OKE1014 when missing.
+   * Validate a live resume cursor (auto-starts). Throws OKE1210 when missing.
    *
    * @param name - Signal name
    * @param afterId - SSE cursor

package/src/elements/signal/schema-emit.test.ts

@@ -49,9 +49,8 @@ const drivers: Array<{
 
 for (const { label, driver, setup } of drivers) {
   describe(`signal schema emit · ${label}`, () => {
-    test("invalid payload rejected at emit with OKE1043; valid succeeds", async () => {
-      const orderPlaced = signal("order-placed", {
-        delivery: "once",
+    test("invalid payload rejected at emit with OKE1250; valid succeeds", async () => {
+      const orderPlaced = signal.once("order-placed", {
         schema: z.object({
           orderId: z.string(),
           total: z.number(),
@@ -74,7 +73,7 @@ for (const { label, driver, setup } of drivers) {
       expect(rejected).toBeInstanceOf(OkeError);
       const oke = rejected as OkeError;
       expect(oke.code).toBe(OKE_ERRORS.SIGNAL_SCHEMA.code);
-      expect(oke.message).toContain("OKE1043");
+      expect(oke.message).toContain("OKE1250");
       expect(oke.message).toContain("order-placed");
 
       // Nothing staged while invalid.
@@ -90,10 +89,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("no schema: any payload still accepted", async () => {
-      const loose = signal("hook", {
-        delivery: "once",
-        optional: true,
-      });
+      const loose = signal.once("hook", { optional: true });
       const bus = await openBus(driver, [loose], setup?.() ?? {});
       const got: unknown[] = [];
       await bus.subscribe("hook", "c1", async (m) => {

package/src/elements/signal.test.ts

@@ -1,6 +1,6 @@
 /**
  * Signal element acceptance:
- * - delivery is mandatory with no default
+ * - delivery helpers: signal.once / broadcast / live
  * - rolled-back transaction emits nothing
  * - crash between write and emit loses nothing (transactional outbox)
  * - competing consumers under once receive each message once
@@ -76,25 +76,20 @@ async function openBus(
 }
 
 describe("signal declaration", () => {
-  test("delivery is mandatory with no default", () => {
-    expect(() =>
-      // @ts-expect-error delivery is required
-      signal("x", { retries: 1 }),
-    ).toThrow(/delivery is mandatory/);
-
-    const s = signal("order-placed", { delivery: "once" });
-    expect(s.delivery).toBe("once");
-    expect(s.name).toBe("order-placed");
+  test("helpers stamp delivery physics", () => {
+    expect(signal.once("order-placed").delivery).toBe("once");
+    expect(signal.broadcast("news").delivery).toBe("broadcast");
+    expect(signal.live("seat-feed").delivery).toBe("live");
+    expect(signal.once("order-placed").name).toBe("order-placed");
   });
 
   test("retention is live-only", () => {
     expect(() =>
       // @ts-expect-error retention is live-only
-      signal("order-placed", { delivery: "once", retention: { maxCount: 2 } }),
+      signal.once("order-placed", { retention: { maxCount: 2 } }),
     ).toThrow(/retention is only valid/);
 
-    const live = signal("order-status", {
-      delivery: "live",
+    const live = signal.live("order-status", {
       optional: true,
       retention: { maxAge: "24h", maxCount: 500 },
     });
@@ -105,7 +100,7 @@ describe("signal declaration", () => {
 for (const { label, driver, setup } of drivers) {
   describe(`signal driver · ${label}`, () => {
     test("rolled-back transaction emits nothing", async () => {
-      const once = signal("order-placed", { delivery: "once" });
+      const once = signal.once("order-placed");
       const bus = await openBus(driver, [once], setup?.() ?? {});
       const seen: unknown[] = [];
       await bus.subscribe("order-placed", "c1", async (m) => {
@@ -123,7 +118,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("commit makes write + emit visible together", async () => {
-      const once = signal("order-placed", { delivery: "once" });
+      const once = signal.once("order-placed");
       const bus = await openBus(driver, [once], setup?.() ?? {});
       const seen: unknown[] = [];
       await bus.subscribe("order-placed", "c1", async (m) => {
@@ -141,7 +136,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("competing consumers under once receive each message exactly once", async () => {
-      const once = signal("order-placed", { delivery: "once", retries: 2 });
+      const once = signal.once("order-placed", { retries: 2 });
       const bus = await openBus(driver, [once], setup?.() ?? {});
       const got: string[] = [];
 
@@ -163,7 +158,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("once: a single emit is received by exactly one of two consumers", async () => {
-      const once = signal("order-placed", { delivery: "once", retries: 2 });
+      const once = signal.once("order-placed", { retries: 2 });
       const bus = await openBus(driver, [once], setup?.() ?? {});
       const got: string[] = [];
       await bus.subscribe("order-placed", "worker-a", async () => {
@@ -179,7 +174,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("broadcast reaches every subscriber", async () => {
-      const bcast = signal("news", { delivery: "broadcast" });
+      const bcast = signal.broadcast("news");
       const bus = await openBus(driver, [bcast], setup?.() ?? {});
       const a: unknown[] = [];
       const b: unknown[] = [];
@@ -198,7 +193,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("live is client-subscribable", async () => {
-      const live = signal("seat-feed", { delivery: "live", optional: true });
+      const live = signal.live("seat-feed", { optional: true });
       const bus = await openBus(driver, [live], setup?.() ?? {});
       const it = bus.live("seat-feed")[Symbol.asyncIterator]();
       const pending = it.next();
@@ -211,11 +206,7 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("DLQ preserves typed failure reasons per attempt", async () => {
-      const once = signal("flaky", {
-        delivery: "once",
-        retries: 2,
-        deadLetter: true,
-      });
+      const once = signal.once("flaky", { retries: 2, deadLetter: true });
       const bus = await openBus(driver, [once], setup?.() ?? {});
       let attempts = 0;
       await bus.subscribe("flaky", "c1", async () => {
@@ -241,7 +232,7 @@ for (const { label, driver, setup } of drivers) {
 
 describe("postgres transactional emit (dual-write fix)", () => {
   test("fx.emit enrols in the caller's transaction via runtime", async () => {
-    const orderPlaced = signal("order-placed", { delivery: "once" });
+    const orderPlaced = signal.once("order-placed");
     const runtime = createSignalRuntime({
       driver: postgresSignalDriver,
       sql: createPostgresSignalFake(),
@@ -268,7 +259,7 @@ describe("postgres transactional emit (dual-write fix)", () => {
 
   test("LISTEN/NOTIFY wakes drain after commit", async () => {
     const sql = createPostgresSignalFake();
-    const once = signal("order-placed", { delivery: "once" });
+    const once = signal.once("order-placed");
     const bus = await openBus(postgresSignalDriver, [once], { sql });
     const seen: unknown[] = [];
     await bus.subscribe("order-placed", "c1", async (m) => {
@@ -291,7 +282,7 @@ describe("postgres transactional emit (dual-write fix)", () => {
 describe("redis / nats outbox relay", () => {
   test("redis relay publishes after commit, not on rollback", async () => {
     const redis = createSignalRedisFake();
-    const once = signal("order-placed", { delivery: "once", optional: true });
+    const once = signal.once("order-placed", { optional: true });
     const bus = await openBus(redisSignalDriver, [once], { redis });
 
     const tx = await bus.begin();
@@ -309,7 +300,7 @@ describe("redis / nats outbox relay", () => {
 
   test("nats relay publishes after commit, not on rollback", async () => {
     const nats = createSignalNatsFake();
-    const once = signal("order-placed", { delivery: "once", optional: true });
+    const once = signal.once("order-placed", { optional: true });
     const bus = await openBus(natsSignalDriver, [once], { nats });
 
     const tx = await bus.begin();
@@ -338,11 +329,7 @@ describe("chaos — kill process mid-transaction", () => {
       expect(code).toBe(99);
 
       // Recover: new process opens the same durable path.
-      const orderPlaced = signal("order-placed", {
-        delivery: "once",
-        retries: 3,
-        deadLetter: true,
-      });
+      const orderPlaced = signal.once("order-placed", { retries: 3, deadLetter: true });
       const runtime = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,
@@ -376,7 +363,7 @@ describe("chaos — kill process mid-transaction", () => {
           import { memorySignalDriver } from ${JSON.stringify(join(import.meta.dir, "../drivers/signal-memory.ts"))};
           import { signal } from ${JSON.stringify(join(import.meta.dir, "signal/declare.ts"))};
           import { createSignalRuntime } from ${JSON.stringify(join(import.meta.dir, "signal/runtime.ts"))};
-          const orderPlaced = signal("order-placed", { delivery: "once", retries: 3, deadLetter: true, optional: true });
+          const orderPlaced = signal.once("order-placed", { retries: 3, deadLetter: true, optional: true });
           const runtime = createSignalRuntime({ driver: memorySignalDriver, durablePath: ${JSON.stringify(durablePath)} });
           runtime.register(orderPlaced);
           const bus = await runtime.start();
@@ -396,11 +383,7 @@ describe("chaos — kill process mid-transaction", () => {
       child.kill(9);
       await child.exited;
 
-      const orderPlaced = signal("order-placed", {
-        delivery: "once",
-        retries: 3,
-        deadLetter: true,
-      });
+      const orderPlaced = signal.once("order-placed", { retries: 3, deadLetter: true });
       const runtime = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,
@@ -434,11 +417,7 @@ describe("chaos — kill process mid-transaction", () => {
       });
       expect(await child.exited).toBe(0);
 
-      const orderPlaced = signal("order-placed", {
-        delivery: "once",
-        retries: 3,
-        deadLetter: true,
-      });
+      const orderPlaced = signal.once("order-placed", { retries: 3, deadLetter: true });
       const runtime = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,
@@ -501,11 +480,7 @@ describe("chaos — kill process mid-transaction", () => {
       await Bun.sleep(leaseMs + 40);
 
       let clock = Date.now() + leaseMs + 1_000;
-      const orderPlaced = signal("order-placed", {
-        delivery: "once",
-        retries: 3,
-        deadLetter: true,
-      });
+      const orderPlaced = signal.once("order-placed", { retries: 3, deadLetter: true });
       const runtime = createSignalRuntime({
         driver: memorySignalDriver,
         durablePath,

package/src/elements/signal.ts

@@ -1,13 +1,20 @@
 /**
  * Signal element — data in motion.
  *
- * Delivery physics: `once` · `broadcast` · `live` (mandatory, no default).
+ * Delivery physics via helpers: `signal.once` · `signal.broadcast` · `signal.live`.
  * Drivers: `memory` · `postgres` (default / transactional) · `redis` · `nats`.
  * @module
  */
 
 export { signal } from "./signal/declare.ts";
-export type { SignalDecl, SignalOptions, SignalRetention } from "./signal/declare.ts";
+export type {
+  SignalDecl,
+  SignalLiveOptions,
+  SignalNamespace,
+  SignalOptions,
+  SignalRetention,
+  SignalSharedOptions,
+} from "./signal/declare.ts";
 export type { DeadLetter, SignalFailureReason } from "../drivers/signal-types.ts";
 
 export { createSignalRuntime } from "./signal/runtime.ts";

package/src/elements/store/domain-ddl.test.ts

@@ -1,5 +1,5 @@
 /**
- * Domain DDL policy — ensure vs migrate; missing schema → OKE1101.
+ * Domain DDL policy — ensure vs migrate; missing schema → OKE1110.
  */
 
 import { describe, expect, test } from "bun:test";

package/src/elements/store/live-http.test.ts

@@ -79,9 +79,11 @@ describe("manual live flow (.live(table) + liveQuery) — real boot", () => {
     const db = store.sql("app", { schema: { tasks, activity } });
 
     const tasksLive = on(
-      http.get("/tasks/live").public().live(tasks),
+      http
+        .get("/tasks/live", { in: { unknown: true } })
+        .public()
+        .live(tasks),
       flow("tasks.live", {
-        in: { unknown: true },
         effects: { reads: ["sql:app"] },
         do: async (input, fx) =>
           liveQuery(fx, tasks, input, {
@@ -93,9 +95,12 @@ describe("manual live flow (.live(table) + liveQuery) — real boot", () => {
     );
     // A plain flow writing to BOTH tables — the keel `writeActivity` shape.
     const createTask = on(
-      http.post("/tasks").public(),
+      http
+        .post("/tasks", {
+          in: { title: { type: "string" }, status: { type: "string" } },
+        })
+        .public(),
       flow("tasks.create", {
-        in: { title: { type: "string" }, status: { type: "string" } },
         effects: { writes: ["sql:app"] },
         do: async (input, fx) => {
           const s = fx.store(db);

package/src/elements/store/prepare-row.test.ts

@@ -0,0 +1,123 @@
+/**
+ * prepareInsertRow / prepareUpdateRow — temporal bind coercion.
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { timestamp, text, pgTable, integer } from "drizzle-orm/pg-core";
+import { pgliteDriver } from "../../drivers/pglite.ts";
+import type { SqlConnection } from "../../drivers/types.ts";
+import { field, store } from "../store.ts";
+import { createSqlStoreHandle, type SqlStoreHandle } from "./sql-session.ts";
+import { coerceTemporalBindValue, prepareInsertRow, prepareUpdateRow } from "./table.ts";
+
+describe("coerceTemporalBindValue", () => {
+  test("epoch-ms number → Date for TIMESTAMP and DATE", () => {
+    const at = coerceTemporalBindValue("TIMESTAMP", 1_700_000_000_000);
+    expect(at).toBeInstanceOf(Date);
+    expect((at as Date).getTime()).toBe(1_700_000_000_000);
+
+    const day = coerceTemporalBindValue("DATE", 0);
+    expect(day).toBeInstanceOf(Date);
+    expect((day as Date).getTime()).toBe(0);
+  });
+
+  test("leaves non-temporal and non-number values alone", () => {
+    expect(coerceTemporalBindValue("INTEGER", 42)).toBe(42);
+    expect(coerceTemporalBindValue("TIMESTAMP", "2024-01-01T00:00:00.000Z")).toBe(
+      "2024-01-01T00:00:00.000Z",
+    );
+    const d = new Date(5);
+    expect(coerceTemporalBindValue("TIMESTAMP", d)).toBe(d);
+    expect(coerceTemporalBindValue("TIMESTAMP", null)).toBe(null);
+    expect(coerceTemporalBindValue("TIMESTAMP", Number.NaN)).toBe(Number.NaN);
+  });
+});
+
+describe("prepareInsertRow / prepareUpdateRow — timestamp columns", () => {
+  const notes = store.schema.table("notes", {
+    id: field.id().primaryKey(),
+    createdAt: field.timestamp().notNull(),
+    archivedAt: field.timestamp(),
+  });
+
+  test("abstract schema: insert coerces epoch-ms on timestamp columns", () => {
+    const prepared = prepareInsertRow(notes, {
+      id: "welcome",
+      createdAt: 1,
+      archivedAt: null,
+    });
+    expect(prepared.created_at).toBeInstanceOf(Date);
+    expect((prepared.created_at as Date).getTime()).toBe(1);
+    expect(prepared.archived_at).toBe(null);
+    expect(prepared.id).toBe("welcome");
+  });
+
+  test("abstract schema: update coerces epoch-ms on timestamp columns", () => {
+    const prepared = prepareUpdateRow(notes, { archivedAt: 99 });
+    expect(prepared.archived_at).toBeInstanceOf(Date);
+    expect((prepared.archived_at as Date).getTime()).toBe(99);
+  });
+
+  test("drizzle pgTable timestamp: insert coerces epoch-ms", () => {
+    const posts = pgTable("posts", {
+      id: text("id").primaryKey(),
+      createdAt: timestamp("created_at", { mode: "date" }).notNull(),
+      hits: integer("hits").notNull(),
+    });
+    const prepared = prepareInsertRow(posts, {
+      id: "p1",
+      createdAt: 42,
+      hits: 7,
+    });
+    expect(prepared.created_at).toBeInstanceOf(Date);
+    expect((prepared.created_at as Date).getTime()).toBe(42);
+    expect(prepared.hits).toBe(7);
+  });
+});
+
+describe("SqlStoreHandle upsert — epoch-ms into timestamp (Postgres)", () => {
+  const notesTs = pgTable("notes_ts", {
+    id: text("id").primaryKey(),
+    title: text("title").notNull(),
+    createdAt: timestamp("created_at", { mode: "date" }).notNull(),
+  });
+
+  let conn: SqlConnection;
+  let handle: SqlStoreHandle;
+
+  beforeAll(async () => {
+    conn = await pgliteDriver.connect({
+      url: "memory://prepare-row-ts",
+      role: "primary",
+    });
+    handle = createSqlStoreHandle("sql:app", {
+      connection: conn,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "ensure",
+    });
+    await handle.insert(notesTs).values({ id: "_warmup", title: "x", createdAt: new Date(0) });
+    await conn.exec(`TRUNCATE "notes_ts" RESTART IDENTITY CASCADE`);
+  }, 15_000);
+
+  afterAll(async () => {
+    await conn.close();
+  });
+
+  beforeEach(async () => {
+    await conn.exec(`TRUNCATE "notes_ts" RESTART IDENTITY CASCADE`);
+  });
+
+  test("upsert accepts fx.clock.now()-style epoch-ms without Postgres type error", async () => {
+    const first = await handle.upsert(
+      notesTs,
+      { id: "welcome" },
+      { id: "welcome", title: "Welcome", createdAt: 1 },
+    );
+    expect(first.status).toBe("upserted");
+
+    const rows = await handle.select().from(notesTs);
+    expect(rows).toHaveLength(1);
+    expect(Number(rows[0]!.createdAt)).toBe(1);
+  });
+});