okengine 0.18.4 → 0.19.0

package/src/elements/store/search-runtime.ts

@@ -0,0 +1,300 @@
+/**
+ * Built-in hybrid search runtime — BM25F ± LSH ± RRF/weighted fusion,
+ * composing {@link parseListQuery} for ordinary filters / pagination.
+ */
+
+import type { PromptRef } from "../../manifest/types.ts";
+import type { SqlConnection, SqlRow } from "../../drivers/types.ts";
+import { parseListQuery, resolveListScope, type ListOptions } from "./list-query.ts";
+import { bm25fScore, termFrequencies, tokenize } from "./search-bm25.ts";
+import { SearchConfigError, LSH_DEFAULT_K } from "./search-errors.ts";
+import { fuseLists, type FuseOptions } from "./search-fusion.ts";
+import {
+  cosineSimilarity,
+  deserializePlanes,
+  lshBucket,
+  lshBucketToSql,
+  neighborBuckets,
+} from "./search-lsh.ts";
+import {
+  embColumn,
+  lshColumn,
+  OKE_SEARCH_DF,
+  OKE_SEARCH_PLANES,
+  OKE_SEARCH_STATS,
+  OKE_TSV_COL,
+} from "./search-ddl.ts";
+import { compileWhere } from "./sql-condition.ts";
+import { resolveTableName, type TableHandle } from "./table.ts";
+
+/** Search options — `query` / `fuse` / `rerank` are search-specific; rest is list grammar. */
+export interface SqlSearchOptions extends ListOptions {
+  /** Hybrid relevance string (BM25 ± semantic). Not the same as list `?search=` LIKE. */
+  readonly query: string;
+  readonly fuse?: FuseOptions;
+  /** Default `false` — never silently invokes fx.ask. */
+  readonly rerank?: false | { readonly model: PromptRef };
+  /** Extra PostgREST-shaped filter input (same as list / live). */
+  readonly filterInput?: unknown;
+}
+
+export interface SqlSearchResult {
+  readonly data: SqlRow[];
+  readonly meta: {
+    readonly engine: Array<"bm25" | "lsh">;
+    readonly fusedBy?: "rrf" | "weighted";
+    readonly rrfK?: number;
+    readonly limit: number;
+  };
+}
+
+export interface SearchColumnMeta {
+  readonly key: string;
+  readonly sqlName: string;
+  readonly weight: number;
+  readonly embed?: { readonly dims: number; readonly model?: string };
+}
+
+export interface RunSqlSearchDeps {
+  readonly conn: SqlConnection;
+  readonly table: TableHandle | unknown;
+  readonly columns: readonly SearchColumnMeta[];
+  readonly pkSqlName: string;
+  readonly options: SqlSearchOptions;
+  /** Optional embed for the query string when LSH fields exist. */
+  readonly embedQuery?: (text: string, model?: string) => Promise<readonly number[]>;
+  /** Optional rerank via fx.ask — only when options.rerank is set. */
+  readonly askRerank?: (
+    model: PromptRef,
+    input: {
+      query: string;
+      docs: Array<{ id: string; text: string; score: number }>;
+    },
+  ) => Promise<{ rankedIds?: string[] }>;
+}
+
+/**
+ * Execute hybrid search against PostgreSQL using GIN + LSH B-tree candidates,
+ * then BM25F / cosine / fusion in-process (correct, testable math).
+ *
+ * @param deps - Connection, table meta, options
+ */
+export async function runSqlSearch(deps: RunSqlSearchDeps): Promise<SqlSearchResult> {
+  const { conn, options, columns, pkSqlName } = deps;
+  const tableName = resolveTableName(deps.table);
+  if (!tableName) throw new Error("search(): table name could not be resolved");
+
+  const searchable = columns.filter((c) => c.weight > 0);
+  if (searchable.length === 0) {
+    throw new SearchConfigError(tableName, "*", "no .searchable() columns on this table");
+  }
+
+  const { query, fuse, rerank, filterInput, ...listOpts } = options;
+  const scope = resolveListScope(deps.table, listOpts);
+  const parsed = parseListQuery(filterInput ?? {}, scope.query);
+  if (!parsed.ok) {
+    throw parsed.failure instanceof Error
+      ? parsed.failure
+      : new Error(`search(): invalid list filters (${String(parsed.failure)})`);
+  }
+
+  const limit = parsed.page.limit ?? scope.limit;
+  const engines: Array<"bm25" | "lsh"> = ["bm25"];
+  const embedFields = searchable.filter((c) => c.embed);
+  if (embedFields.length > 0) engines.push("lsh");
+
+  // Candidate retrieval: GIN tsvector match OR LSH buckets.
+  const params: unknown[] = [query];
+  let whereSql = `${OKE_TSV_COL} @@ plainto_tsquery('english', ?)`;
+  let queryVec: readonly number[] | undefined;
+  const bucketParams: bigint[] = [];
+
+  if (embedFields.length > 0 && deps.embedQuery) {
+    const model = embedFields[0]?.embed?.model;
+    queryVec = await deps.embedQuery(query, model);
+    for (const field of embedFields) {
+      const dims = field.embed!.dims;
+      if (queryVec.length !== dims) {
+        throw new SearchConfigError(
+          tableName,
+          field.sqlName,
+          `query embedding length ${queryVec.length} !== declared dims ${dims}`,
+        );
+      }
+      const planesRow = await conn.query(
+        `SELECT k, planes FROM ${OKE_SEARCH_PLANES} WHERE table_name = ? AND column_name = ?`,
+        [tableName, field.sqlName],
+      );
+      const row = planesRow[0];
+      if (!row) {
+        throw new SearchConfigError(
+          tableName,
+          field.sqlName,
+          `missing hyperplanes — run oke db search-backfill or ensure push applied search DDL`,
+        );
+      }
+      const k = Number(row["k"] ?? LSH_DEFAULT_K);
+      const planesBuf = row["planes"] as Buffer;
+      const planes = deserializePlanes(Buffer.from(planesBuf), k);
+      const bucket = lshBucket(queryVec, planes);
+      for (const b of neighborBuckets(bucket, k)) {
+        bucketParams.push(b);
+      }
+      whereSql += ` OR ${lshColumn(field.sqlName)} = ANY(?::bigint[])`;
+      params.push(`{${bucketParams.map((b) => lshBucketToSql(b)).join(",")}}`);
+    }
+  }
+
+  // Compose list-grammar filters.
+  if (parsed.page.where) {
+    const compiled = compileWhere(parsed.page.where);
+    if (compiled.clause) {
+      whereSql = `(${whereSql}) AND (${compiled.clause})`;
+      params.push(...compiled.params);
+    }
+  }
+
+  const selectCols = [
+    quoteIdent(pkSqlName),
+    ...searchable.map((c) => quoteIdent(c.sqlName)),
+    ...embedFields.map((c) => quoteIdent(embColumn(c.sqlName))),
+  ].join(", ");
+
+  // Oversample candidates for fusion then truncate.
+  const fetchLimit = Math.min(Math.max(limit * 5, 50), 500);
+  const candidateSql = `SELECT ${selectCols} FROM ${quoteIdent(tableName)} WHERE ${whereSql} LIMIT ${fetchLimit}`;
+  const candidates = await conn.query(candidateSql, params);
+
+  const statsRows = await conn.query(
+    `SELECT n, avgdl FROM ${OKE_SEARCH_STATS} WHERE table_name = ?`,
+    [tableName],
+  );
+  const N = Number(statsRows[0]?.["n"] ?? candidates.length) || candidates.length;
+  const avgdl = Number(statsRows[0]?.["avgdl"] ?? 50) || 50;
+
+  const dfRows = await conn.query(`SELECT term, df FROM ${OKE_SEARCH_DF} WHERE table_name = ?`, [
+    tableName,
+  ]);
+  const df = new Map<string, number>();
+  for (const r of dfRows) {
+    df.set(String(r["term"]), Number(r["df"] ?? 0));
+  }
+
+  const qTerms = tokenize(query);
+  const bm25Hits: Array<{ id: string; score: number; rank: number; row: SqlRow }> = [];
+  const vecHits: Array<{ id: string; score: number; rank: number; row: SqlRow }> = [];
+
+  for (const row of candidates) {
+    const id = String(row[pkSqlName] ?? row["id"] ?? "");
+    const fields = searchable.map((c) => {
+      const text = String(row[c.sqlName] ?? "");
+      return { weight: c.weight, tf: termFrequencies(tokenize(text)) };
+    });
+    let docLen = 0;
+    for (const f of fields) {
+      for (const n of f.tf.values()) docLen += n;
+    }
+    const score = bm25fScore(qTerms, fields, docLen, avgdl, N, df);
+    bm25Hits.push({ id, score, rank: 0, row });
+  }
+  bm25Hits.sort((a, b) => b.score - a.score);
+  bm25Hits.forEach((h, i) => {
+    h.rank = i + 1;
+  });
+
+  if (queryVec && embedFields.length > 0) {
+    for (const row of candidates) {
+      const id = String(row[pkSqlName] ?? row["id"] ?? "");
+      let best = -1;
+      for (const field of embedFields) {
+        const emb = parseRealArray(row[embColumn(field.sqlName)]);
+        if (!emb) continue;
+        if (emb.length !== field.embed!.dims) {
+          throw new SearchConfigError(
+            tableName,
+            field.sqlName,
+            `stored embedding length ${emb.length} !== declared dims ${field.embed!.dims}`,
+          );
+        }
+        const sim = cosineSimilarity(queryVec, emb);
+        if (sim > best) best = sim;
+      }
+      if (best >= 0) vecHits.push({ id, score: best, rank: 0, row });
+    }
+    vecHits.sort((a, b) => b.score - a.score);
+    vecHits.forEach((h, i) => {
+      h.rank = i + 1;
+    });
+  }
+
+  const rowById = new Map<string, SqlRow>();
+  for (const h of bm25Hits) rowById.set(h.id, h.row);
+  for (const h of vecHits) rowById.set(h.id, h.row);
+
+  let orderedIds: string[];
+  let fusedBy: "rrf" | "weighted" | undefined;
+  let rrfK: number | undefined;
+
+  if (vecHits.length > 0) {
+    const lists = new Map([
+      ["bm25", bm25Hits.map(({ id, score, rank }) => ({ id, score, rank }))],
+      ["vector", vecHits.map(({ id, score, rank }) => ({ id, score, rank }))],
+    ]);
+    const fused = fuseLists(lists, fuse);
+    orderedIds = fused.hits.map((h) => h.id);
+    fusedBy = fused.strategy;
+    rrfK = fused.k;
+  } else {
+    orderedIds = bm25Hits.map((h) => h.id);
+  }
+
+  let data = orderedIds
+    .slice(0, limit)
+    .map((id) => rowById.get(id))
+    .filter((r): r is SqlRow => r !== undefined);
+
+  if (rerank && typeof rerank === "object" && rerank.model && deps.askRerank) {
+    const docs = data.map((row) => {
+      const id = String(row[pkSqlName] ?? row["id"] ?? "");
+      const text = searchable.map((c) => String(row[c.sqlName] ?? "")).join("\n");
+      return { id, text, score: 0 };
+    });
+    const out = await deps.askRerank(rerank.model, { query, docs });
+    if (out.rankedIds && out.rankedIds.length > 0) {
+      const byId = new Map(data.map((r) => [String(r[pkSqlName] ?? r["id"]), r]));
+      data = out.rankedIds.map((id) => byId.get(id)).filter((r): r is SqlRow => r !== undefined);
+    }
+  }
+
+  return {
+    data,
+    meta: {
+      engine: engines,
+      ...(fusedBy ? { fusedBy } : {}),
+      ...(rrfK !== undefined ? { rrfK } : {}),
+      limit,
+    },
+  };
+}
+
+function quoteIdent(name: string): string {
+  if (!/^[a-z_][a-z0-9_]*$/i.test(name)) {
+    return `"${name.replaceAll('"', '""')}"`;
+  }
+  return name;
+}
+
+/**
+ * Coerce a Postgres `real[]` driver value into a number array.
+ *
+ * @param value - Array or `{1,2,3}` text
+ */
+function parseRealArray(value: unknown): number[] | undefined {
+  if (Array.isArray(value)) return value.map((x) => Number(x));
+  if (typeof value === "string") {
+    const inner = value.trim().replace(/^\{/, "").replace(/\}$/, "");
+    if (inner.length === 0) return [];
+    return inner.split(",").map((x) => Number(x.trim()));
+  }
+  return undefined;
+}

package/src/elements/store/search.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Built-in hybrid search — unit correctness (BM25F, LSH, RRF, searchable API).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { field, store } from "../store.ts";
+import { bm25fScore, termFrequencies, tokenize } from "./search-bm25.ts";
+import { fuseLists, fuseRrf, fuseWeighted } from "./search-fusion.ts";
+import { RRF_DEFAULT_K, SearchConfigError } from "./search-errors.ts";
+import {
+  cosineSimilarity,
+  generateHyperplanes,
+  hyperplaneSeed,
+  lshBucket,
+  lshBucketFromSql,
+  lshBucketToSql,
+  neighborBuckets,
+} from "./search-lsh.ts";
+
+describe("field.searchable / .embed", () => {
+  test("searchable weight defaults to 1; embed requires prior searchable", () => {
+    const articles = store.schema.table("articles", {
+      id: field.text().primaryKey(),
+      title: field.text().searchable({ weight: 2 }).notNull(),
+      body: field.text().searchable().embed({ dims: 8, model: "embedder" }),
+    });
+    expect(articles.columns.title.search).toEqual({ searchable: true, weight: 2 });
+    expect(articles.columns.body.search?.embed).toEqual({ dims: 8, model: "embedder" });
+    expect(() => field.text().embed({ dims: 8 })).toThrow(/prior \.searchable/);
+  });
+
+  test("bare .embed() and partial options are allowed at declare time", () => {
+    const bare = field.text().searchable().embed();
+    const modelOnly = field.text().searchable().embed({ model: "embedder" });
+    expect(bare).toBeDefined();
+    expect(modelOnly).toBeDefined();
+    const table = store.schema.table("articles", {
+      id: field.text().primaryKey(),
+      body: field.text().searchable().embed(),
+      caption: field.text().searchable().embed({ model: "other" }),
+    });
+    expect(table.columns.body.search?.embed).toEqual({});
+    expect(table.columns.caption.search?.embed).toEqual({ model: "other" });
+  });
+});
+
+describe("BM25F", () => {
+  test("field weight applied before saturation matches hand reference", () => {
+    const query = ["cat"];
+    const df = new Map([["cat", 1]]);
+    const N = 2;
+    const avgdl = 2;
+    // Doc A: title has cat once (weight 2); Doc B: body has cat once (weight 1)
+    const scoreA = bm25fScore(
+      query,
+      [{ weight: 2, tf: termFrequencies(["cat"]) }],
+      1,
+      avgdl,
+      N,
+      df,
+    );
+    const scoreB = bm25fScore(
+      query,
+      [{ weight: 1, tf: termFrequencies(["cat"]) }],
+      1,
+      avgdl,
+      N,
+      df,
+    );
+    expect(scoreA).toBeGreaterThan(scoreB);
+    // Hand: weightedTf=2 vs 1 with same IDF → A ranks higher
+    expect(tokenize("Hello, CAT!")).toEqual(["hello", "cat"]);
+  });
+});
+
+describe("LSH", () => {
+  test("planes are stable for the same seed; near vectors collide", () => {
+    const seed = hyperplaneSeed("articles", "body", 8, 16);
+    const a = generateHyperplanes(seed, 8, 16);
+    const b = generateHyperplanes(seed, 8, 16);
+    expect(a[0]![0]).toBe(b[0]![0]);
+    const v = [1, 0, 0, 0, 0, 0, 0, 0];
+    const near = [0.99, 0.01, 0, 0, 0, 0, 0, 0];
+    const ba = lshBucket(v, a);
+    const bn = lshBucket(near, a);
+    // Exact or Hamming-1 neighbor should include near for this orientation
+    const neighbors = new Set(neighborBuckets(ba, 16).map(String));
+    expect(neighbors.has(String(bn)) || ba === bn).toBe(true);
+    expect(cosineSimilarity(v, near)).toBeGreaterThan(0.9);
+  });
+
+  test("dimension mismatch fails loud", () => {
+    const planes = generateHyperplanes("s", 4, 8);
+    expect(() => lshBucket([1, 2], planes)).toThrow(/length/);
+  });
+
+  test("lshBucketToSql round-trips high bit into signed bigint range", () => {
+    const high = 1n << 63n;
+    const sql = lshBucketToSql(high);
+    expect(BigInt(sql) < 0n).toBe(true);
+    expect(lshBucketFromSql(sql)).toBe(high);
+    expect(lshBucketToSql(42n)).toBe("42");
+  });
+});
+
+describe("fusion", () => {
+  test("RRF default k=60 matches Cormack hand ranks", () => {
+    expect(RRF_DEFAULT_K).toBe(60);
+    const lists = new Map([
+      [
+        "bm25",
+        [
+          { id: "a", score: 10, rank: 1 },
+          { id: "b", score: 5, rank: 2 },
+        ],
+      ],
+      [
+        "vector",
+        [
+          { id: "b", score: 0.9, rank: 1 },
+          { id: "a", score: 0.5, rank: 2 },
+        ],
+      ],
+    ]);
+    const hits = fuseRrf(lists, 60);
+    // a: 1/61 + 1/62; b: 1/62 + 1/61 — equal contributions swapped → tied-ish; b wins on equal?
+    // a = 1/61 + 1/62; b = 1/62 + 1/61 — identical
+    expect(hits[0]!.score).toBeCloseTo(hits[1]!.score, 10);
+    const weighted = fuseWeighted(lists, { bm25: 1, vector: 0 });
+    expect(weighted[0]!.id).toBe("a");
+    const fused = fuseLists(lists);
+    expect(fused.strategy).toBe("rrf");
+    expect(fused.k).toBe(60);
+  });
+});
+
+describe("SearchConfigError", () => {
+  test("names table and column", () => {
+    const err = new SearchConfigError("notes", "body", "missing ai");
+    expect(err.name).toBe("SearchConfigError");
+    expect(err.table).toBe("notes");
+    expect(err.message).toContain("notes.body");
+  });
+});

package/src/elements/store/sql-session.test.ts

@@ -71,6 +71,7 @@ describe("SqlStoreHandle — no relational query surface (path b)", () => {
         "count",
         "page",
         "ensureTable",
+        "search",
       ].sort(),
     );
 

package/src/elements/store/sql-session.ts

@@ -19,8 +19,8 @@ import { maskRows, tableFromSql } from "./classify.ts";
 import { isMissingDomainRelationError } from "./missing-relation.ts";
 import {
   andWhere,
-  compileOrderBy,
   compileWhere,
+  compileOrderBy,
   resolveSelectColumns,
   type WhereMap,
 } from "./sql-condition.ts";
@@ -32,6 +32,9 @@ import {
   resolveTableName,
   type TableHandle,
 } from "./table.ts";
+import { isSchemaTableDecl } from "./schema-decl.ts";
+import { SearchConfigError } from "./search-errors.ts";
+import { runSqlSearch, type SearchColumnMeta, type SqlSearchOptions } from "./search-runtime.ts";
 
 export type { WhereMap } from "./sql-condition.ts";
 
@@ -204,6 +207,11 @@ export interface SqlSessionOptions {
   readonly domainDdl?: DomainDdlMode;
   /** Gate identity — stamps `oke.*` on postgres / pglite. */
   readonly rls?: RlsIdentity;
+  /**
+   * Optional query-time embedding for hybrid LSH (wired from `fx.embed` at boot).
+   * When omitted, search is BM25-only even if columns declare `.embed()`.
+   */
+  readonly embedQuery?: (text: string, model?: string) => Promise<readonly number[]>;
 }
 
 /**
@@ -363,6 +371,11 @@ export interface SqlStoreHandle {
   readonly routedRole: "primary" | "replica";
   /** Underlying driver id. */
   readonly driverId: SqlConnection["driverId"];
+  /**
+   * Egress identity when the SQL connection leaves the process.
+   * Omitted for in-process drivers (`pglite`, `memory`).
+   */
+  readonly external?: SqlConnection["external"];
   /**
    * Start a select. No-arg form infers the row from `.from(table)`.
    * A column map (`select({ clicks: links.clicks })`) stays {@link SqlRow}.
@@ -453,6 +466,18 @@ export interface SqlStoreHandle {
    * @param options - Page options
    */
   page(table: TableHandle | unknown, options: SqlPageOptions): Promise<SqlRow[]>;
+  /**
+   * Built-in hybrid search (BM25 ± LSH ± fusion) on `.searchable()` columns.
+   * Reuses {@link parseListQuery} for filters / limit / cursor; `query` is
+   * the relevance string (not list-grammar `?search=` LIKE).
+   *
+   * @param table - Table with searchable columns
+   * @param options - query + list filters + optional fuse / rerank
+   */
+  search(
+    table: TableHandle | unknown,
+    options: import("./search-runtime.ts").SqlSearchOptions,
+  ): Promise<import("./search-runtime.ts").SqlSearchResult>;
   /**
    * Ensure a simple table exists (test / bootstrap helper).
    *
@@ -507,7 +532,7 @@ export function createSqlStoreHandle(
   ref: `sql:${string}`,
   options: SqlSessionOptions,
 ): SqlStoreHandle {
-  const { connection, classifications, revealPii, rls } = options;
+  const { connection, classifications, revealPii, rls, embedQuery } = options;
   const domainDdl: DomainDdlMode = options.domainDdl ?? "ensure";
 
   function mask(rows: SqlRow[], table?: string): SqlRow[] {
@@ -515,7 +540,7 @@ export function createSqlStoreHandle(
   }
 
   /**
-   * Run a connection op; remap missing-relation driver errors to OKE1101
+   * Run a connection op; remap missing-relation driver errors to OKE1110
    * when domain auto-DDL is off.
    */
   async function withSchemaGuard<T>(fn: () => Promise<T>): Promise<T> {
@@ -744,6 +769,7 @@ export function createSqlStoreHandle(
     ref,
     routedRole: options.routedRole,
     driverId: connection.driverId,
+    ...(connection.external !== undefined ? { external: connection.external } : {}),
 
     select(columns?: unknown) {
       return {
@@ -1134,6 +1160,20 @@ export function createSqlStoreHandle(
       });
     },
 
+    async search(table: TableHandle | unknown, searchOptions: SqlSearchOptions) {
+      await ensureFromMeta(table);
+      const columns = searchColumnsFromTable(table);
+      const pk = resolvePkColumn(table);
+      return runSqlSearch({
+        conn: connection,
+        table,
+        columns,
+        pkSqlName: pk,
+        options: searchOptions,
+        ...(embedQuery ? { embedQuery } : {}),
+      });
+    },
+
     async ensureTable(table: TableHandle) {
       const cols = Object.values(table.columns);
       const pk = resolvePkColumn(table);
@@ -1169,6 +1209,46 @@ export function resolvePkColumn(table: unknown): string {
   return "id";
 }
 
+/**
+ * Collect `.searchable()` / `.embed()` column meta from a schema table.
+ *
+ * @param table - Table handle
+ */
+function searchColumnsFromTable(table: unknown): SearchColumnMeta[] {
+  if (!isSchemaTableDecl(table)) {
+    throw new Error(
+      "search(): table must be a store.schema.table() declaration with .searchable() columns",
+    );
+  }
+  const out: SearchColumnMeta[] = [];
+  const tableName = resolveTableName(table);
+  for (const [key, col] of Object.entries(table.columns)) {
+    if (!col.search?.searchable) continue;
+    let embed: SearchColumnMeta["embed"];
+    if (col.search.embed) {
+      const dims = col.search.embed.dims;
+      if (dims === undefined) {
+        throw new SearchConfigError(
+          tableName,
+          key,
+          `.embed() needs dims — set oke({ store: { search: { embed: { model, dims } } } }) or pass dims on .embed({ dims })`,
+        );
+      }
+      embed = {
+        dims,
+        ...(col.search.embed.model ? { model: col.search.embed.model } : {}),
+      };
+    }
+    out.push({
+      key,
+      sqlName: col.sqlName,
+      weight: col.search.weight,
+      ...(embed ? { embed } : {}),
+    });
+  }
+  return out;
+}
+
 function asNumber(value: unknown, column: string): number {
   if (typeof value === "number") return value;
   if (typeof value === "bigint") return Number(value);

package/src/elements/store/table.ts

@@ -293,6 +293,27 @@ function drizzleSqlType(
   return "TEXT";
 }
 
+/**
+ * Bind value for a temporal SQL column. Epoch-ms numbers (e.g. `fx.clock.now()`)
+ * become `Date` so Postgres `timestamp` / `date` accept them; other values pass through.
+ *
+ * @param sqlType - Resolved DDL type
+ * @param value - Incoming JS value
+ */
+export function coerceTemporalBindValue(
+  sqlType: ResolvedColumn["sqlType"],
+  value: unknown,
+): unknown {
+  if (
+    (sqlType === "TIMESTAMP" || sqlType === "DATE") &&
+    typeof value === "number" &&
+    Number.isFinite(value)
+  ) {
+    return new Date(value);
+  }
+  return value;
+}
+
 /**
  * Map a JS-keyed row to SQL column names; apply Drizzle `$defaultFn`s.
  *
@@ -315,7 +336,7 @@ export function prepareInsertRow(
     else if (col.sqlName in row) value = row[col.sqlName];
     else if (col.defaultFn) value = col.defaultFn();
     else continue;
-    out[col.sqlName] = value;
+    out[col.sqlName] = coerceTemporalBindValue(col.sqlType, value);
   }
   // Pass through unknown keys as-is (already SQL names).
   for (const [k, v] of Object.entries(row)) {
@@ -344,7 +365,7 @@ export function prepareUpdateRow(
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(row)) {
     const col = byKey.get(k) ?? bySql.get(k);
-    out[col?.sqlName ?? k] = v;
+    out[col?.sqlName ?? k] = col ? coerceTemporalBindValue(col.sqlType, v) : v;
   }
   return out;
 }

package/src/elements/store/upsert-app.test.ts

@@ -45,10 +45,8 @@ describe("fx.store(db).upsert via app.fetch (real boot)", () => {
     const db = store.sql("app", { schema: { notes } });
 
     const seed = on(
-      http.post("/seed").public(),
+      http.post("/seed", { in: UpsertIn, out: UpsertOut }).public(),
       flow("notes.seed", {
-        in: UpsertIn,
-        out: UpsertOut,
         effects: { writes: ["sql:app"], reads: ["sql:app"] },
         do: async (input, fx) =>
           fx