okengine 0.19.9 → 0.21.0

package/src/elements/store/files-errors.test.ts

@@ -0,0 +1,149 @@
+/**
+ * `fs` / `s3` files errors → Forbidden / ServiceUnavailable.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import { createS3FakeClient, s3Driver } from "../../drivers/s3.ts";
+import { fsDriver } from "../../drivers/fs.ts";
+import { memoryDrivers } from "../../drivers/memory.ts";
+import { store } from "./declare.ts";
+import { filesErrorToFailure, isRetryableFilesError } from "./files-errors.ts";
+import { createStoreRuntime, type FilesStoreFxHandle } from "./runtime.ts";
+
+describe("filesErrorToFailure", () => {
+  test("AccessDenied / EACCES → Forbidden without copying message", () => {
+    const denied = filesErrorToFailure(
+      Object.assign(new Error("Access Denied"), { code: "AccessDenied", status: 403 }),
+    );
+    expect(denied?.error.code).toBe("Forbidden");
+    expect(JSON.stringify(denied)).not.toContain("Access Denied");
+
+    expect(
+      filesErrorToFailure(Object.assign(new Error("permission denied"), { code: "EACCES" }))?.error
+        .code,
+    ).toBe("Forbidden");
+    expect(isFlowFailure(denied)).toBe(true);
+  });
+
+  test("Invalid object key → Forbidden without copying the key", () => {
+    const mapped = filesErrorToFailure(new Error("Invalid object key: ../secret"));
+    expect(mapped?.error.code).toBe("Forbidden");
+    expect(mapped?.error.data).toMatchObject({ reason: "invalid_key" });
+    expect(JSON.stringify(mapped)).not.toContain("../secret");
+  });
+
+  test("NoSuchBucket / ENOSPC / connection → ServiceUnavailable", () => {
+    expect(filesErrorToFailure(new Error("The specified bucket does not exist"))?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      filesErrorToFailure(Object.assign(new Error("No space left on device"), { code: "ENOSPC" }))
+        ?.error.code,
+    ).toBe("ServiceUnavailable");
+    expect(
+      filesErrorToFailure(
+        Object.assign(new Error("connect ECONNREFUSED"), { code: "ECONNREFUSED" }),
+      )?.error.code,
+    ).toBe("ServiceUnavailable");
+    expect(
+      JSON.stringify(filesErrorToFailure(new Error("The specified bucket does not exist"))),
+    ).not.toContain("specified bucket");
+  });
+
+  test("SlowDown / EBUSY left thrown until retryable: unavailable", () => {
+    const slow = Object.assign(new Error("Please reduce your request rate"), { code: "SlowDown" });
+    expect(isRetryableFilesError(slow)).toBe(true);
+    expect(filesErrorToFailure(slow, { retryable: "leave" })).toBeUndefined();
+    expect(filesErrorToFailure(slow, { retryable: "unavailable" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      filesErrorToFailure(Object.assign(new Error("resource busy"), { code: "EBUSY" }), {
+        retryable: "leave",
+      }),
+    ).toBeUndefined();
+  });
+
+  test("NoSuchKey and generic throws stay unmapped", () => {
+    expect(
+      filesErrorToFailure(
+        Object.assign(new Error("The specified key does not exist"), { code: "NoSuchKey" }),
+      ),
+    ).toBeUndefined();
+    expect(filesErrorToFailure(new Error("boom"))).toBeUndefined();
+  });
+
+  test("walks .cause and S3 XML Code", () => {
+    const wrapped = {
+      message: "put failed",
+      cause: new Error("<?xml><Error><Code>AccessDenied</Code></Error>"),
+    };
+    expect(filesErrorToFailure(wrapped)?.error.code).toBe("Forbidden");
+    expect(JSON.stringify(filesErrorToFailure(wrapped))).not.toContain("put failed");
+  });
+});
+
+describe("openFiles maps S3 throws", () => {
+  test("AccessDenied on put becomes Forbidden", async () => {
+    const fake = createS3FakeClient();
+    const inner = fake.file.bind(fake);
+    fake.file = (key: string) => {
+      const file = inner(key);
+      return {
+        ...file,
+        write: async () => {
+          throw Object.assign(new Error("Access Denied"), { code: "AccessDenied", status: 403 });
+        },
+      };
+    };
+    const uploads = store.files("uploads");
+    const runtime = createStoreRuntime({
+      drivers: {
+        files: s3Driver,
+        kv: memoryDrivers.kv,
+        index: memoryDrivers.index,
+      },
+      files: { uploads: { client: fake } },
+    });
+    runtime.register(uploads);
+    const handle = (await runtime.open(uploads, { effects: {} })) as FilesStoreFxHandle;
+    try {
+      await handle.put("a.bin", new Uint8Array([1]));
+      throw new Error("expected mapped failure");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      expect((err as { error: { code: string } }).error.code).toBe("Forbidden");
+      expect(JSON.stringify(err)).not.toContain("Access Denied");
+    }
+    await runtime.close();
+  });
+
+  test("fs path-escape key becomes Forbidden", async () => {
+    const uploads = store.files("escapes");
+    const runtime = createStoreRuntime({
+      drivers: {
+        files: fsDriver,
+        kv: memoryDrivers.kv,
+        index: memoryDrivers.index,
+      },
+      files: { escapes: { root: `${process.env.TMPDIR ?? "/tmp"}/oke-files-escape` } },
+    });
+    runtime.register(uploads);
+    const handle = (await runtime.open(uploads, { effects: {} })) as FilesStoreFxHandle;
+    try {
+      await handle.put("../secret", "x");
+      throw new Error("expected mapped failure");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      expect((err as { error: { code: string; data?: { reason?: string } } }).error.code).toBe(
+        "Forbidden",
+      );
+      expect((err as { error: { data?: { reason?: string } } }).error.data?.reason).toBe(
+        "invalid_key",
+      );
+      expect(JSON.stringify(err)).not.toContain("../secret");
+    }
+    await runtime.close();
+  });
+});

package/src/elements/store/files-errors.ts

@@ -0,0 +1,189 @@
+/**
+ * Map `fs` / `s3` files-driver errors to typed {@link FlowFailure} values.
+ *
+ * Lives on the store path — not the kernel edge graph. Availability and
+ * throttle replies become `ServiceUnavailable`; access / path-escape become
+ * `Forbidden`. Missing `get` (`null`) is not auto-`NotFound`.
+ */
+
+import { fail } from "../../kernel/fail-helpers.ts";
+import type { FlowFailure } from "../../kernel/errors.ts";
+import type { BuiltinErrorMap } from "../../kernel/builtin-errors.ts";
+
+/** How to treat SlowDown / EBUSY / AWS `InternalError`. */
+export type FilesRetryableMode = "leave" | "unavailable";
+
+/** Options for {@link filesErrorToFailure}. */
+export interface FilesErrorToFailureOptions {
+  /**
+   * `leave` — return `undefined` so {@link flow.retry} can rethrow.
+   * `unavailable` — map to `ServiceUnavailable` after retries exhaust.
+   */
+  readonly retryable?: FilesRetryableMode;
+}
+
+type FilesFailure = FlowFailure<
+  BuiltinErrorMap["Forbidden"] | BuiltinErrorMap["ServiceUnavailable"]
+>;
+
+type FilesErrShape = {
+  readonly name?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+  readonly status?: unknown;
+  readonly statusCode?: unknown;
+  readonly message?: unknown;
+  readonly cause?: unknown;
+};
+
+const RETRY_TOKEN = new Set([
+  "SLOWDOWN",
+  "REQUESTTIMEOUT",
+  "INTERNALERROR",
+  "REDUCEYOURREQUESTRATE",
+  "PRIORREQUESTNOTCOMPLETE",
+  "OPERATIONABORTED",
+  "EBUSY",
+  "EAGAIN",
+  "EWOULDBLOCK",
+  "EIO",
+]);
+const UNAVAILABLE_TOKEN = new Set([
+  "NOSUCHBUCKET",
+  "SERVICEUNAVAILABLE",
+  "ENOSPC",
+  "EDQUOT",
+  "EMFILE",
+  "ENFILE",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EPIPE",
+  "ENETUNREACH",
+  "EAI_AGAIN",
+  "ECONNABORTED",
+]);
+const FORBIDDEN_TOKEN = new Set([
+  "ACCESSDENIED",
+  "ACCESSFORBIDDEN",
+  "ALLACCESSDISABLED",
+  "INVALIDACCESSKEYID",
+  "SIGNATUREDOESNOTMATCH",
+  "INVALIDSECURITY",
+  "EXPIREDTOKEN",
+  "TOKENREFRESHREQUIRED",
+  "ACCOUNTPROBLEM",
+  "EACCES",
+  "EPERM",
+  "EROFS",
+]);
+
+/**
+ * True when `err` is a throttle / busy files failure.
+ *
+ * Left thrown during retries; mapped to `ServiceUnavailable` after exhaust.
+ *
+ * @param err - Caught driver error
+ */
+export function isRetryableFilesError(err: unknown): boolean {
+  return walk(err, (node) => retrySignal(node));
+}
+
+/**
+ * Map an `fs` / `s3` driver throw to `Forbidden` or `ServiceUnavailable`,
+ * or `undefined` when it is not a known files failure.
+ *
+ * @param err - Caught value from `fx.store` files ops
+ * @param options - Retryable handling
+ */
+export function filesErrorToFailure(
+  err: unknown,
+  options: FilesErrorToFailureOptions = {},
+): FilesFailure | undefined {
+  const retryable = options.retryable ?? "leave";
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (!current || typeof current !== "object") break;
+    if (isInvalidObjectKey(current)) return fail.forbidden({ reason: "invalid_key" });
+    if (retrySignal(current)) {
+      if (retryable === "leave") return undefined;
+      return fail.serviceUnavailable();
+    }
+    if (isForbidden(current)) return fail.forbidden();
+    if (isUnavailable(current)) return fail.serviceUnavailable();
+    current = causeOf(current);
+  }
+  return undefined;
+}
+
+function retrySignal(err: unknown): boolean {
+  if (RETRY_TOKEN.has(filesToken(err))) return true;
+  return httpStatus(err) === 429;
+}
+
+function isForbidden(err: unknown): boolean {
+  if (FORBIDDEN_TOKEN.has(filesToken(err))) return true;
+  if (httpStatus(err) === 403) return true;
+  const message = errMessage(err);
+  return /access denied|not authorized to perform/i.test(message);
+}
+
+function isUnavailable(err: unknown): boolean {
+  const token = filesToken(err);
+  if (UNAVAILABLE_TOKEN.has(token)) return true;
+  const status = httpStatus(err);
+  if (status === 502 || status === 503 || status === 504) return true;
+  const message = errMessage(err);
+  if (/specified bucket does not exist|NoSuchBucket/i.test(message)) return true;
+  if (/connection (closed|refused|reset|timed out)/i.test(message)) return true;
+  if (/socket hang up|connect econn|read econn/i.test(message)) return true;
+  if (/ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOSPC|EMFILE/i.test(message)) return true;
+  return false;
+}
+
+function isInvalidObjectKey(err: unknown): boolean {
+  return /^Invalid object key:/i.test(errMessage(err));
+}
+
+function filesToken(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const e = err as FilesErrShape;
+  if (typeof e.code === "string" && e.code.length > 0) {
+    return e.code.toUpperCase().replace(/[^A-Z0-9]/g, "");
+  }
+  const xml = /<Code>([A-Za-z][A-Za-z0-9]+)<\/Code>/i.exec(errMessage(err));
+  if (xml?.[1]) return xml[1].toUpperCase();
+  const message = errMessage(err).trim();
+  const first = /^([A-Za-z][A-Za-z0-9_]+)/.exec(message)?.[1];
+  return first ? first.toUpperCase().replace(/[^A-Z0-9]/g, "") : "";
+}
+
+function httpStatus(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const e = err as FilesErrShape;
+  if (typeof e.status === "number") return e.status;
+  if (typeof e.statusCode === "number") return e.statusCode;
+  return undefined;
+}
+
+function errMessage(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const message = (err as FilesErrShape).message;
+  return typeof message === "string" ? message : "";
+}
+
+function causeOf(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  return (err as FilesErrShape).cause;
+}
+
+function walk(err: unknown, pred: (node: unknown) => boolean): boolean {
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (pred(current)) return true;
+    current = causeOf(current);
+    if (current === undefined) break;
+  }
+  return false;
+}

package/src/elements/store/kv-errors.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Redis-wire KV errors → ServiceUnavailable (availability / retry exhaust).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import { createRedisFakeClient, redisDriver } from "../../drivers/redis.ts";
+import { memoryDrivers } from "../../drivers/memory.ts";
+import { store } from "./declare.ts";
+import { isRetryableKvError, kvErrorToFailure } from "./kv-errors.ts";
+import { createStoreRuntime, type KvStoreFxHandle } from "./runtime.ts";
+
+describe("kvErrorToFailure", () => {
+  test("connection / cluster → ServiceUnavailable without copying message", () => {
+    const closed = kvErrorToFailure(
+      Object.assign(new Error("Connection closed"), { code: "ECONNREFUSED" }),
+    );
+    expect(closed?.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(closed)).not.toContain("Connection closed");
+
+    expect(kvErrorToFailure(new Error("CLUSTERDOWN The cluster is down"))?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      kvErrorToFailure(new Error("READONLY You can't write against a read only replica."))?.error
+        .code,
+    ).toBe("ServiceUnavailable");
+    expect(
+      kvErrorToFailure(new Error("OOM command not allowed when used memory > 'maxmemory'."))?.error
+        .code,
+    ).toBe("ServiceUnavailable");
+    expect(isFlowFailure(closed)).toBe(true);
+  });
+
+  test("BUSY / TRYAGAIN left thrown until retryable: unavailable", () => {
+    const busy = new Error("BUSY Redis is busy running a script");
+    expect(isRetryableKvError(busy)).toBe(true);
+    expect(kvErrorToFailure(busy, { retryable: "leave" })).toBeUndefined();
+    expect(kvErrorToFailure(busy, { retryable: "unavailable" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      kvErrorToFailure(new Error("TRYAGAIN Multiple keys request during rehashing"), {
+        retryable: "leave",
+      }),
+    ).toBeUndefined();
+  });
+
+  test("WRONGTYPE / NOSCRIPT stay unmapped", () => {
+    expect(
+      kvErrorToFailure(
+        new Error("WRONGTYPE Operation against a key holding the wrong kind of value"),
+      ),
+    ).toBeUndefined();
+    expect(
+      kvErrorToFailure(new Error("NOSCRIPT No matching script. Please use EVAL.")),
+    ).toBeUndefined();
+    expect(kvErrorToFailure(new Error("boom"))).toBeUndefined();
+  });
+
+  test("walks .cause for connection failures", () => {
+    const wrapped = {
+      message: "kv get failed",
+      cause: Object.assign(new Error("Connection closed"), { code: "ECONNRESET" }),
+    };
+    expect(kvErrorToFailure(wrapped)?.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(kvErrorToFailure(wrapped))).not.toContain("kv get failed");
+  });
+});
+
+describe("openKv maps Redis throws", () => {
+  test("connection failure on get becomes ServiceUnavailable", async () => {
+    const fake = createRedisFakeClient();
+    fake.get = async () => {
+      throw Object.assign(new Error("Connection closed"), { code: "ECONNREFUSED" });
+    };
+    const sessions = store.kv("sessions");
+    const runtime = createStoreRuntime({
+      drivers: {
+        kv: redisDriver,
+        files: memoryDrivers.files,
+        index: memoryDrivers.index,
+      },
+      kv: { sessions: { client: fake } },
+    });
+    runtime.register(sessions);
+    const handle = (await runtime.open(sessions, { effects: {} })) as KvStoreFxHandle;
+    try {
+      await handle.get("sid");
+      throw new Error("expected mapped failure");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      expect((err as { error: { code: string } }).error.code).toBe("ServiceUnavailable");
+      expect(JSON.stringify(err)).not.toContain("Connection closed");
+    }
+    await runtime.close();
+  });
+});

package/src/elements/store/kv-errors.ts

@@ -0,0 +1,139 @@
+/**
+ * Map Redis-wire KV errors to typed {@link FlowFailure} values.
+ *
+ * Lives on the store path — not the kernel edge graph. Availability and
+ * retryable script/cluster replies become `ServiceUnavailable`. Programmer
+ * mistakes (`WRONGTYPE`, `NOSCRIPT`) stay unmapped so the HTTP encoder
+ * sanitizes them as `InternalError`.
+ */
+
+import { fail } from "../../kernel/fail-helpers.ts";
+import type { FlowFailure } from "../../kernel/errors.ts";
+import type { BuiltinErrorMap } from "../../kernel/builtin-errors.ts";
+
+/** How to treat Redis `BUSY` / `TRYAGAIN` / `LOADING`. */
+export type KvRetryableMode = "leave" | "unavailable";
+
+/** Options for {@link kvErrorToFailure}. */
+export interface KvErrorToFailureOptions {
+  /**
+   * `leave` — return `undefined` so {@link flow.retry} can rethrow.
+   * `unavailable` — map to `ServiceUnavailable` after retries exhaust.
+   */
+  readonly retryable?: KvRetryableMode;
+}
+
+type KvFailure = FlowFailure<BuiltinErrorMap["ServiceUnavailable"]>;
+
+type KvErrShape = {
+  readonly name?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+  readonly message?: unknown;
+  readonly cause?: unknown;
+};
+
+const RETRY_TOKEN = new Set(["BUSY", "BUSYKEY", "TRYAGAIN", "LOADING"]);
+const UNAVAILABLE_TOKEN = new Set([
+  "CLUSTERDOWN",
+  "MASTERDOWN",
+  "READONLY",
+  "MISCONF",
+  "OOM",
+  "MOVED",
+  "ASK",
+  "UNBLOCKED",
+]);
+const CONN_CODE = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EPIPE",
+  "ENETUNREACH",
+  "EAI_AGAIN",
+  "ECONNABORTED",
+]);
+
+/**
+ * True when `err` is a Redis `BUSY` / `TRYAGAIN` / `LOADING` reply.
+ *
+ * Left thrown during retries; mapped to `ServiceUnavailable` after exhaust.
+ *
+ * @param err - Caught driver error
+ */
+export function isRetryableKvError(err: unknown): boolean {
+  return walk(err, (node) => retrySignal(node));
+}
+
+/**
+ * Map a Redis-wire KV error to `ServiceUnavailable`, or `undefined` when it
+ * is not an availability / retryable Redis failure.
+ *
+ * @param err - Caught value from `fx.store` KV ops
+ * @param options - Retryable handling
+ */
+export function kvErrorToFailure(
+  err: unknown,
+  options: KvErrorToFailureOptions = {},
+): KvFailure | undefined {
+  const retryable = options.retryable ?? "leave";
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (!current || typeof current !== "object") break;
+    if (retrySignal(current)) {
+      if (retryable === "leave") return undefined;
+      return fail.serviceUnavailable();
+    }
+    if (isUnavailable(current)) return fail.serviceUnavailable();
+    current = causeOf(current);
+  }
+  return undefined;
+}
+
+function retrySignal(err: unknown): boolean {
+  return RETRY_TOKEN.has(redisToken(err));
+}
+
+function isUnavailable(err: unknown): boolean {
+  const token = redisToken(err);
+  if (UNAVAILABLE_TOKEN.has(token)) return true;
+  if (CONN_CODE.has(token)) return true;
+  if (/^ERR_REDIS_(CONNECTION|CONNECT|CLOSED|TIMEOUT|NETWORK)/.test(token)) return true;
+  const message = errMessage(err);
+  if (/max number of clients/i.test(message)) return true;
+  if (/connection (closed|refused|reset|timed out)/i.test(message)) return true;
+  if (/socket hang up|connect econn|read econn/i.test(message)) return true;
+  if (/ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EPIPE/i.test(message)) return true;
+  return false;
+}
+
+function redisToken(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const e = err as KvErrShape;
+  if (typeof e.code === "string" && e.code.length > 0) return e.code.toUpperCase();
+  const message = typeof e.message === "string" ? e.message.trim() : "";
+  const first = /^([A-Za-z][A-Za-z0-9_]+)/.exec(message)?.[1];
+  return first ? first.toUpperCase() : "";
+}
+
+function errMessage(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const message = (err as KvErrShape).message;
+  return typeof message === "string" ? message : "";
+}
+
+function causeOf(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  return (err as KvErrShape).cause;
+}
+
+function walk(err: unknown, pred: (node: unknown) => boolean): boolean {
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (pred(current)) return true;
+    current = causeOf(current);
+    if (current === undefined) break;
+  }
+  return false;
+}

package/src/elements/store/load-plugin-tables.ts

@@ -2,7 +2,7 @@
  * Load plugin table contributions from a live `oke()` app entry.
  *
  * Used by `oke db` emit so `.plug()`-registered `field.*` tables merge into
- * `schema.drizzle.ts` — not only at unit-test merge call sites.
+ * `drizzle.ts` — not only at unit-test merge call sites.
  */
 
 import { resolve } from "node:path";

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

@@ -3,6 +3,7 @@
  */
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { lte } from "drizzle-orm";
 import { timestamp, text, pgTable, integer } from "drizzle-orm/pg-core";
 import { pgliteDriver } from "../../drivers/pglite.ts";
 import type { SqlConnection } from "../../drivers/types.ts";
@@ -21,11 +22,19 @@ describe("coerceTemporalBindValue", () => {
     expect((day as Date).getTime()).toBe(0);
   });
 
-  test("leaves non-temporal and non-number values alone", () => {
+  test("ISO datetime string → Date for TIMESTAMP and DATE", () => {
+    const at = coerceTemporalBindValue("TIMESTAMP", "2024-01-01T00:00:00.000Z");
+    expect(at).toBeInstanceOf(Date);
+    expect((at as Date).toISOString()).toBe("2024-01-01T00:00:00.000Z");
+
+    const day = coerceTemporalBindValue("DATE", "2024-01-01T00:00:00.000Z");
+    expect(day).toBeInstanceOf(Date);
+    expect((day as Date).toISOString()).toBe("2024-01-01T00:00:00.000Z");
+  });
+
+  test("leaves non-temporal and unparseable values alone", () => {
     expect(coerceTemporalBindValue("INTEGER", 42)).toBe(42);
-    expect(coerceTemporalBindValue("TIMESTAMP", "2024-01-01T00:00:00.000Z")).toBe(
-      "2024-01-01T00:00:00.000Z",
-    );
+    expect(coerceTemporalBindValue("TIMESTAMP", "not-an-instant")).toBe("not-an-instant");
     const d = new Date(5);
     expect(coerceTemporalBindValue("TIMESTAMP", d)).toBe(d);
     expect(coerceTemporalBindValue("TIMESTAMP", null)).toBe(null);
@@ -73,6 +82,17 @@ describe("prepareInsertRow / prepareUpdateRow — timestamp columns", () => {
     expect((prepared.created_at as Date).getTime()).toBe(42);
     expect(prepared.hits).toBe(7);
   });
+
+  test("abstract schema: insert coerces ISO datetime on timestamp columns", () => {
+    const prepared = prepareInsertRow(notes, {
+      id: "welcome",
+      createdAt: "2026-09-14T12:00:00.000Z",
+      archivedAt: null,
+    });
+    expect(prepared.created_at).toBeInstanceOf(Date);
+    expect((prepared.created_at as Date).toISOString()).toBe("2026-09-14T12:00:00.000Z");
+    expect(prepared.archived_at).toBe(null);
+  });
 });
 
 describe("SqlStoreHandle upsert — epoch-ms into timestamp (Postgres)", () => {
@@ -120,4 +140,37 @@ describe("SqlStoreHandle upsert — epoch-ms into timestamp (Postgres)", () => {
     expect(rows).toHaveLength(1);
     expect(Number(rows[0]!.createdAt)).toBe(1);
   });
+
+  test("select/update WHERE coerces epoch-ms on timestamp columns", async () => {
+    await handle.insert(notesTs).values({ id: "old", title: "old", createdAt: 1 });
+    await handle.insert(notesTs).values({ id: "new", title: "new", createdAt: 100 });
+
+    // Drizzle types timestamp `{ mode: "date" }` as Date; the store still
+    // coerces epoch-ms binds (`fx.clock.now()`) at WHERE compile time.
+    const before = 50 as unknown as Date;
+    const rows = await handle.select().from(notesTs).where(lte(notesTs.createdAt, before));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.id).toBe("old");
+
+    const n = await handle
+      .update(notesTs)
+      .set({ title: "archived" })
+      .where(lte(notesTs.createdAt, before));
+    expect(n).toBe(1);
+    const archived = await handle.findById(notesTs, "old");
+    expect(archived?.title).toBe("archived");
+  });
+
+  test("upsert accepts ISO datetime strings without Postgres type error", async () => {
+    const first = await handle.upsert(
+      notesTs,
+      { id: "welcome" },
+      { id: "welcome", title: "Welcome", createdAt: "2026-09-14T12:00:00.000Z" },
+    );
+    expect(first.status).toBe("upserted");
+
+    const rows = await handle.select().from(notesTs);
+    expect(rows).toHaveLength(1);
+    expect(new Date(rows[0]!.createdAt as Date).toISOString()).toBe("2026-09-14T12:00:00.000Z");
+  });
 });