okengine 0.19.8 → 0.20.0

package/src/elements/clock/reconcile.ts

@@ -75,6 +75,14 @@ export interface CronStore {
    * @param leaseMs - Lease TTL
    */
   acquireLease(name: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
+  /**
+   * Atomic read-modify-write. Reconcile uses this so a concurrent
+   * {@link CronStore.acquireLease} cannot be clobbered by a stale `get` + `put`.
+   *
+   * @param name - Cron name
+   * @param fn - Receives the current row (or `undefined`); return the next row
+   */
+  update(name: string, fn: (prev: CronRow | undefined) => CronRow): Promise<void>;
 }
 
 /** Result of one reconciliation pass. */
@@ -200,30 +208,29 @@ export async function orphanPerTenantCronRows(
 }
 
 async function putActiveRow(store: CronStore, decl: ClockDecl, name: string): Promise<void> {
-  const prev = await store.get(name);
-  const overrideCron =
-    decl.overridable && prev?.overrideCron !== undefined ? prev.overrideCron : undefined;
-  const overrideEvery =
-    decl.overridable && prev?.overrideEvery !== undefined ? prev.overrideEvery : undefined;
-
-  const row: CronRow = {
-    name,
-    declaredCron: decl.cron,
-    declaredEvery: decl.every,
-    overrideCron,
-    overrideEvery,
-    effectiveCron: overrideCron ?? decl.cron,
-    effectiveEvery: overrideEvery ?? decl.every,
-    timezone: decl.timezone,
-    overridable: decl.overridable,
-    status: "active",
-    leaderInstanceId: prev?.leaderInstanceId,
-    leaderLeaseUntil: prev?.leaderLeaseUntil,
-    lastRunAt: prev?.lastRunAt,
-    nextRunAt: prev?.nextRunAt,
-    dstAmbiguity: prev?.dstAmbiguity,
-  };
-  await store.put(row);
+  await store.update(name, (prev) => {
+    const overrideCron =
+      decl.overridable && prev?.overrideCron !== undefined ? prev.overrideCron : undefined;
+    const overrideEvery =
+      decl.overridable && prev?.overrideEvery !== undefined ? prev.overrideEvery : undefined;
+    return {
+      name,
+      declaredCron: decl.cron,
+      declaredEvery: decl.every,
+      overrideCron,
+      overrideEvery,
+      effectiveCron: overrideCron ?? decl.cron,
+      effectiveEvery: overrideEvery ?? decl.every,
+      timezone: decl.timezone,
+      overridable: decl.overridable,
+      status: "active",
+      leaderInstanceId: prev?.leaderInstanceId,
+      leaderLeaseUntil: prev?.leaderLeaseUntil,
+      lastRunAt: prev?.lastRunAt,
+      nextRunAt: prev?.nextRunAt,
+      dstAmbiguity: prev?.dstAmbiguity,
+    };
+  });
 }
 
 /**
@@ -305,6 +312,12 @@ export function createMemoryCronStore(seed?: readonly CronRow[]): CronStore {
         return true;
       });
     },
+    async update(name, fn) {
+      return withLock(name, () => {
+        const prev = rows.get(name);
+        rows.set(name, structuredClone(fn(prev ? structuredClone(prev) : undefined)));
+      });
+    },
   };
 }
 
@@ -409,5 +422,13 @@ export function createFileCronStore(path: string): CronStore {
         return true;
       });
     },
+    async update(name, fn) {
+      await withFileLock(async () => {
+        const map = await loadUnlocked();
+        const prev = map.get(name);
+        map.set(name, structuredClone(fn(prev ? structuredClone(prev) : undefined)));
+        await flushUnlocked(map);
+      });
+    },
   };
 }

package/src/elements/clock.test.ts

@@ -25,6 +25,7 @@ import {
 import {
   clock,
   createClockRuntime,
+  createFileCronStore,
   createMemoryCronStore,
   createTestClockRuntime,
   createTimeTravel,
@@ -218,6 +219,38 @@ describe("leader election", () => {
     expect(fired).toEqual([winner, "i-b"]);
   });
 
+  test("file store: overlapping reconcile cannot double-fire a due tick", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-clock-file-race-"));
+    try {
+      const store = createFileCronStore(join(dir, "crons.json"));
+      const fired: string[] = [];
+      const mk = (instanceId: string) => {
+        const rt = createClockRuntime({ instanceId, store, leaseMs: 200 });
+        rt.register(clock("once", { every: "1h" }));
+        rt.onCron("once", () => {
+          fired.push(instanceId);
+        });
+        return rt;
+      };
+      const a = mk("a");
+      const b = mk("b");
+      const results = await Promise.all([
+        (async () => {
+          await a.reconcile();
+          return a.tick();
+        })(),
+        (async () => {
+          await b.reconcile();
+          return b.tick();
+        })(),
+      ]);
+      expect(results.flatMap((r) => r.ran).filter((n) => n === "once")).toHaveLength(1);
+      expect(fired).toHaveLength(1);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("tryAcquireLease is exclusive within the lease window", async () => {
     const store = createMemoryCronStore([
       {

package/src/elements/store/emit-drizzle.ts

@@ -6,8 +6,8 @@
  */
 
 import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import type { TableContribution } from "../../kernel/plugin.ts";
 import {
   isFieldBuilder,
@@ -34,11 +34,35 @@ export type SqlDialect = "postgres";
 /** Header written at the top of generated files. */
 export const GENERATED_SCHEMA_HEADER = "// generated by oke — do not edit";
 
-/** Default output path (relative to project root). */
-export const DEFAULT_GENERATED_SCHEMA_REL = "src/db/schema.drizzle.ts";
+/** Default generated Drizzle barrel (relative to project root). */
+export const DEFAULT_GENERATED_SCHEMA_REL = "src/db/drizzle/index.ts";
 
-/** Default declaration module path (relative to project root). */
-export const DEFAULT_DECLARE_SCHEMA_REL = "src/db/schema.decl.ts";
+/**
+ * Prior single-file emit (`src/db/drizzle.ts`). Folder emit deletes this
+ * sibling when it still carries the generated header.
+ */
+export const PREV_SINGLE_DRIZZLE_REL = "src/db/drizzle.ts";
+
+/**
+ * Prior emit filename (`src/db/schema.drizzle.ts`) — still resolved when
+ * present and the new default does not exist yet.
+ */
+export const PREV_DRIZZLE_EMIT_REL = "src/db/schema.drizzle.ts";
+
+/** Single-file declare module (takes priority when both layouts exist). */
+export const DEFAULT_DECLARE_SCHEMA_REL = "src/db/schema.ts";
+
+/**
+ * Prior single-file declare (`src/db/schema.decl.ts`) — still resolved when
+ * present and `schema.ts` does not exist yet.
+ */
+export const PREV_DECLARE_SCHEMA_REL = "src/db/schema.decl.ts";
+
+/**
+ * Folder declare module — `src/db/schema/index.ts`.
+ * Used when {@link DEFAULT_DECLARE_SCHEMA_REL} is absent.
+ */
+export const DEFAULT_DECLARE_SCHEMA_DIR_REL = "src/db/schema/index.ts";
 
 /**
  * Prior `src/db/` emit filename — still resolved when present and the new
@@ -289,19 +313,26 @@ export interface EmitDrizzleSourceOptions {
   readonly relations?: readonly SchemaRelationsDecl[];
 }
 
-/**
- * Emit a full Drizzle schema module from abstract table decls.
- *
- * @param tables - App + plugin tables (already merged)
- * @param dialect - Always `postgres` (`pgTable`); retained for call-site clarity
- * @param options - Optional relations to emit as `defineRelations`
- */
-export function emitDrizzleSource(
+function tableExportName(table: SchemaTableDecl): string {
+  return exportNameForTable(schemaTableSqlName(table) ?? table.name);
+}
+
+function referencedExportNames(table: SchemaTableDecl): string[] {
+  const self = tableExportName(table);
+  const names = new Set<string>();
+  for (const col of Object.values(table.columns)) {
+    if (!col.references) continue;
+    const target = col.references.ref();
+    const targetName = exportNameForTable(target.tableName ?? "unknown");
+    if (targetName !== self) names.add(targetName);
+  }
+  return [...names].sort();
+}
+
+function emitImportLines(
   tables: readonly SchemaTableDecl[],
-  dialect: SqlDialect = "postgres",
-  options: EmitDrizzleSourceOptions = {},
-): string {
-  void dialect;
+  options: { readonly relations?: boolean } = {},
+): string[] {
   const usedFactories = new Set<string>();
   for (const table of tables) {
     for (const col of Object.values(table.columns)) {
@@ -316,8 +347,9 @@ export function emitDrizzleSource(
   const coreNames = ["pgTable", ...pgIntImport, needsPolicy ? "pgPolicy" : null].filter(
     (name): name is string => name !== null,
   );
-  const coreImport = `import { ${coreNames.join(", ")} } from "drizzle-orm/pg-core";`;
-  const sqlImport = needsPolicy ? `import { sql } from "drizzle-orm";\n` : "";
+  const lines = [`import { ${coreNames.join(", ")} } from "drizzle-orm/pg-core";`];
+  if (needsPolicy) lines.push(`import { sql } from "drizzle-orm";`);
+  if (options.relations) lines.push(`import { defineRelations } from "drizzle-orm";`);
 
   const needsId = tables.some((t) =>
     Object.values(t.columns).some((c) => c.defaultFnKind === "id"),
@@ -337,30 +369,146 @@ export function emitDrizzleSource(
     needsNowIso ? "nowIso" : null,
     needsNowDate ? "nowDate" : null,
   ].filter((x): x is string => x !== null);
-  const helperImport =
-    helperNames.length > 0 ? `import { ${helperNames.join(", ")} } from "okengine/store";\n` : "";
+  if (helperNames.length > 0) {
+    lines.push(`import { ${helperNames.join(", ")} } from "okengine/store";`);
+  }
+  return lines;
+}
 
-  const relations = options.relations ?? [];
-  const relationsImport =
-    relations.length > 0 ? `import { defineRelations } from "drizzle-orm";\n` : "";
+function joinGeneratedModule(parts: readonly string[]): string {
+  return parts.filter((line, i, arr) => !(line === "" && arr[i - 1] === "")).join("\n");
+}
 
+/**
+ * Emit a full Drizzle schema module from abstract table decls.
+ *
+ * @param tables - App + plugin tables (already merged)
+ * @param dialect - Always `postgres` (`pgTable`); retained for call-site clarity
+ * @param options - Optional relations to emit as `defineRelations`
+ */
+export function emitDrizzleSource(
+  tables: readonly SchemaTableDecl[],
+  dialect: SqlDialect = "postgres",
+  options: EmitDrizzleSourceOptions = {},
+): string {
+  const relations = options.relations ?? [];
   const blocks = tables.map((table) => emitTableBlock(table, dialect));
-
   const relationsBlock = emitRelationsSource(relations);
-
-  return [
+  return joinGeneratedModule([
     GENERATED_SCHEMA_HEADER,
-    coreImport,
-    sqlImport.trimEnd(),
-    relationsImport.trimEnd(),
-    helperImport.trimEnd(),
+    ...emitImportLines(tables, { relations: relations.length > 0 }),
     "",
     blocks.join("\n\n"),
     relationsBlock ? `\n${relationsBlock}` : "",
     "",
-  ]
-    .filter((line, i, arr) => !(line === "" && arr[i - 1] === ""))
-    .join("\n");
+  ]);
+}
+
+/**
+ * One generated table module (`drizzle/<export>.ts`).
+ *
+ * @param table - Table declaration
+ * @param dialect - Always `postgres`
+ */
+export function emitDrizzleTableSource(
+  table: SchemaTableDecl,
+  dialect: SqlDialect = "postgres",
+): string {
+  const refs = referencedExportNames(table).map(
+    (name) => `import { ${name} } from ${JSON.stringify(`./${name}.ts`)};`,
+  );
+  return joinGeneratedModule([
+    GENERATED_SCHEMA_HEADER,
+    ...emitImportLines([table]),
+    ...refs,
+    "",
+    emitTableBlock(table, dialect),
+    "",
+  ]);
+}
+
+/**
+ * Generated `drizzle/relations.ts` when declare relations exist.
+ *
+ * @param relations - Relations declarations
+ */
+export function emitDrizzleRelationsFileSource(relations: readonly SchemaRelationsDecl[]): string {
+  if (relations.length === 0) return "";
+  const keys = new Set<string>();
+  for (const rel of relations) {
+    for (const k of rel.tableKeys) keys.add(k);
+  }
+  const imports = [...keys]
+    .sort()
+    .map((name) => `import { ${name} } from ${JSON.stringify(`./${name}.ts`)};`);
+  return joinGeneratedModule([
+    GENERATED_SCHEMA_HEADER,
+    `import { defineRelations } from "drizzle-orm";`,
+    ...imports,
+    "",
+    emitRelationsSource(relations),
+    "",
+  ]);
+}
+
+/**
+ * Generated `drizzle/index.ts` barrel.
+ *
+ * @param fileNames - Table (and relations) filenames to re-export
+ */
+export function emitDrizzleIndexSource(fileNames: readonly string[]): string {
+  const exports = fileNames.map((name) => `export * from ${JSON.stringify(`./${name}`)};`);
+  return `${GENERATED_SCHEMA_HEADER}\n${exports.join("\n")}\n`;
+}
+
+/**
+ * Filename → source for a generated `drizzle/` folder (one table per file).
+ *
+ * @param tables - App + plugin tables (already merged)
+ * @param dialect - Always `postgres`
+ * @param options - Optional relations file
+ */
+export function emitDrizzleFolderSources(
+  tables: readonly SchemaTableDecl[],
+  dialect: SqlDialect = "postgres",
+  options: EmitDrizzleSourceOptions = {},
+): ReadonlyMap<string, string> {
+  const files = new Map<string, string>();
+  const tableFiles: string[] = [];
+  for (const table of tables) {
+    const name = `${tableExportName(table)}.ts`;
+    files.set(name, emitDrizzleTableSource(table, dialect));
+    tableFiles.push(name);
+  }
+  const relations = options.relations ?? [];
+  const extra: string[] = [];
+  if (relations.length > 0) {
+    files.set("relations.ts", emitDrizzleRelationsFileSource(relations));
+    extra.push("relations.ts");
+  }
+  files.set("index.ts", emitDrizzleIndexSource([...tableFiles, ...extra]));
+  return files;
+}
+
+/**
+ * Whether `db.generated` is the folder barrel (`drizzle/index.ts`).
+ *
+ * @param rel - Path relative to project root
+ */
+export function isFolderGeneratedRel(rel: string): boolean {
+  const n = rel.replace(/\\/g, "/").replace(/\/$/, "");
+  return /(?:^|\/)drizzle\/index\.tsx?$/.test(n) || /(?:^|\/)drizzle$/.test(n);
+}
+
+/**
+ * Normalize `db.generated` so a directory `drizzle` becomes `drizzle/index.ts`.
+ *
+ * @param rel - Path relative to project root
+ */
+export function normalizeGeneratedRel(rel: string): string {
+  const n = rel.replace(/\\/g, "/").replace(/\/$/, "");
+  if (n.endsWith("/drizzle") || n === "drizzle") return `${n}/index.ts`;
+  return n;
 }
 
 function emitTableBlock(table: SchemaTableDecl, dialect: SqlDialect): string {
@@ -534,6 +682,19 @@ export async function maybeEmitDomainSchema(
   }
 
   const tables = mergeSchemaTables(appTables, fromPlugins);
+  if (isFolderGeneratedRel(outRel)) {
+    const dirAbs = dirname(outAbs);
+    const files = emitDrizzleFolderSources(tables, options.dialect, {
+      relations: appRelations,
+    });
+    await writeGeneratedFolder(dirAbs, files);
+    await removeLegacySingleDrizzleFile(dirAbs);
+    options.write?.(
+      `oke db: emitted ${outRel} (${tables.length} table${tables.length === 1 ? "" : "s"}, ${options.dialect})\n`,
+    );
+    return { emitted: true, path: outAbs, tableCount: tables.length };
+  }
+
   const source = emitDrizzleSource(tables, options.dialect, { relations: appRelations });
   await mkdir(dirname(outAbs), { recursive: true });
   await writeFile(outAbs, source, "utf8");
@@ -543,9 +704,95 @@ export async function maybeEmitDomainSchema(
   return { emitted: true, path: outAbs, tableCount: tables.length };
 }
 
+async function writeGeneratedFolder(
+  dirAbs: string,
+  files: ReadonlyMap<string, string>,
+): Promise<void> {
+  await mkdir(dirAbs, { recursive: true });
+  for (const [name, source] of files) {
+    await writeFile(join(dirAbs, name), source, "utf8");
+  }
+  let existing: string[] = [];
+  try {
+    existing = await readdir(dirAbs);
+  } catch {
+    return;
+  }
+  for (const name of existing) {
+    if (!name.endsWith(".ts") && !name.endsWith(".tsx")) continue;
+    if (files.has(name)) continue;
+    const abs = join(dirAbs, name);
+    try {
+      const content = await readFile(abs, "utf8");
+      if (content.startsWith(GENERATED_SCHEMA_HEADER)) await unlink(abs);
+    } catch {
+      // ignore prune failures
+    }
+  }
+}
+
+async function removeLegacySingleDrizzleFile(dirAbs: string): Promise<void> {
+  if (basename(dirAbs) !== "drizzle") return;
+  const sibling = join(dirname(dirAbs), basename(PREV_SINGLE_DRIZZLE_REL));
+  if (!existsSync(sibling)) return;
+  try {
+    const content = await readFile(sibling, "utf8");
+    if (content.startsWith(GENERATED_SCHEMA_HEADER)) await unlink(sibling);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Discover the declare module when `db.declare` is omitted.
+ *
+ * Order: `schema.ts` (single file) → `schema.decl.ts` (prior name) →
+ * `schema/index.ts` (folder) → legacy `src/schema.decl.ts` → default
+ * `schema.ts` (may not exist yet).
+ *
+ * @param cwd - Project root
+ */
+export function discoverDeclareRel(cwd: string): string {
+  if (existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_REL))) {
+    return DEFAULT_DECLARE_SCHEMA_REL;
+  }
+  if (existsSync(join(cwd, PREV_DECLARE_SCHEMA_REL))) {
+    return PREV_DECLARE_SCHEMA_REL;
+  }
+  if (existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_DIR_REL))) {
+    return DEFAULT_DECLARE_SCHEMA_DIR_REL;
+  }
+  if (existsSync(join(cwd, LEGACY_DECLARE_SCHEMA_REL))) {
+    return LEGACY_DECLARE_SCHEMA_REL;
+  }
+  return DEFAULT_DECLARE_SCHEMA_REL;
+}
+
+/**
+ * Discover the generated Drizzle emit path when `db.generated` is omitted.
+ *
+ * Order: `src/db/drizzle/index.ts`, except legacy `src/schema.generated.ts`
+ * when the declare module is still on the old `src/` layout. Older single
+ * files (`drizzle.ts`, `schema.drizzle.ts`) are not re-targeted — set
+ * `db.generated` to keep emitting them.
+ *
+ * @param cwd - Project root
+ * @param declareRel - Resolved declare relative path
+ */
+export function discoverGeneratedRel(cwd: string, declareRel: string): string {
+  const preferSrcLegacy =
+    declareRel === LEGACY_DECLARE_SCHEMA_REL ||
+    (!existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_REL)) &&
+      !existsSync(join(cwd, PREV_DECLARE_SCHEMA_REL)) &&
+      !existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_DIR_REL)) &&
+      existsSync(join(cwd, LEGACY_GENERATED_SCHEMA_REL)));
+  if (preferSrcLegacy) return LEGACY_GENERATED_SCHEMA_REL;
+  return DEFAULT_GENERATED_SCHEMA_REL;
+}
+
 /**
  * Resolve declare/out paths from an optional db config slice.
- * Prefers explicit config, then new `src/db/*` defaults, then legacy `src/*`.
+ * Prefers explicit `db.declare` / `db.generated`, then discovery.
  *
  * @param cwd - Project root
  * @param db - Config `db` block
@@ -554,35 +801,8 @@ export function resolveEmitPaths(
   cwd: string,
   db?: { readonly declare?: string; readonly generated?: string },
 ): { readonly declarePath: string; readonly outPath: string } {
-  let declareRel = db?.declare;
-  if (!declareRel) {
-    if (existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_REL))) {
-      declareRel = DEFAULT_DECLARE_SCHEMA_REL;
-    } else if (existsSync(join(cwd, LEGACY_DECLARE_SCHEMA_REL))) {
-      declareRel = LEGACY_DECLARE_SCHEMA_REL;
-    } else {
-      declareRel = DEFAULT_DECLARE_SCHEMA_REL;
-    }
-  }
-
-  let outRel = db?.generated;
-  if (!outRel) {
-    const preferSrcLegacy =
-      declareRel === LEGACY_DECLARE_SCHEMA_REL ||
-      (!existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_REL)) &&
-        existsSync(join(cwd, LEGACY_GENERATED_SCHEMA_REL)));
-    if (preferSrcLegacy) {
-      outRel = LEGACY_GENERATED_SCHEMA_REL;
-    } else if (
-      !existsSync(join(cwd, DEFAULT_GENERATED_SCHEMA_REL)) &&
-      existsSync(join(cwd, PREV_GENERATED_SCHEMA_REL))
-    ) {
-      outRel = PREV_GENERATED_SCHEMA_REL;
-    } else {
-      outRel = DEFAULT_GENERATED_SCHEMA_REL;
-    }
-  }
-
+  const declareRel = db?.declare ?? discoverDeclareRel(cwd);
+  const outRel = normalizeGeneratedRel(db?.generated ?? discoverGeneratedRel(cwd, declareRel));
   return {
     declarePath: join(cwd, declareRel),
     outPath: join(cwd, outRel),

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");
+  });
 });