okengine 0.18.5 → 0.19.1

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

@@ -0,0 +1,314 @@
+/**
+ * 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,
+  lshHammingSql,
+} 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 lexical candidates UNION
+ * SimHash Hamming-rank (K=64 `bit_count` ORDER BY LIMIT), 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");
+
+  let queryVec: readonly number[] | undefined;
+  const hamExprs: string[] = [];
+  const hamParams: unknown[] = [];
+
+  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);
+      hamExprs.push(lshHammingSql(lshColumn(field.sqlName), "?"));
+      hamParams.push(lshBucketToSql(bucket));
+    }
+  }
+
+  let filterClause = "";
+  const filterParams: unknown[] = [];
+  if (parsed.page.where) {
+    const compiled = compileWhere(parsed.page.where);
+    if (compiled.clause) {
+      filterClause = ` AND (${compiled.clause})`;
+      filterParams.push(...compiled.params);
+    }
+  }
+
+  const selectCols = [
+    quoteIdent(pkSqlName),
+    ...searchable.map((c) => quoteIdent(c.sqlName)),
+    ...embedFields.map((c) => quoteIdent(embColumn(c.sqlName))),
+  ].join(", ");
+  const tableIdent = quoteIdent(tableName);
+
+  // Oversample candidates for fusion then truncate.
+  const fetchLimit = Math.min(Math.max(limit * 5, 50), 500);
+  const lexicalSql = `SELECT ${selectCols} FROM ${tableIdent} WHERE ${OKE_TSV_COL} @@ plainto_tsquery('english', ?)${filterClause} LIMIT ${fetchLimit}`;
+
+  // SimHash k-NN: rank by Hamming over the K=64 bit pack, then LIMIT.
+  // Hamming-1 equality (`= ANY(65 buckets)`) is not a candidate set — true
+  // near-neighbors sit at distance ~5–16, so that probe recovered ~0 rows.
+  let candidateSql: string;
+  const params: unknown[] = [];
+  if (hamExprs.length > 0) {
+    const lshPred = embedFields.map((f) => `${lshColumn(f.sqlName)} IS NOT NULL`).join(" OR ");
+    const orderExpr = hamExprs.length === 1 ? hamExprs[0]! : `LEAST(${hamExprs.join(", ")})`;
+    const lshSql = `SELECT ${selectCols} FROM ${tableIdent} WHERE (${lshPred})${filterClause} ORDER BY ${orderExpr} ASC NULLS LAST LIMIT ${fetchLimit}`;
+    candidateSql = `(${lexicalSql}) UNION (${lshSql})`;
+    params.push(query, ...filterParams, ...hamParams, ...filterParams);
+  } else {
+    candidateSql = lexicalSql;
+    params.push(query, ...filterParams);
+  }
+  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,226 @@
+/**
+ * Built-in hybrid search — unit correctness (BM25F, LSH, RRF, searchable API).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { field, store } from "../store.ts";
+import { bm25fScore, termFrequencies, tokenize } from "./search-bm25.ts";
+import { fuseLists, fuseRrf, fuseWeighted } from "./search-fusion.ts";
+import { LSH_DEFAULT_K, RRF_DEFAULT_K, SearchConfigError } from "./search-errors.ts";
+import {
+  cosineSimilarity,
+  deserializePlanes,
+  generateHyperplanes,
+  hammingDistance,
+  hyperplaneSeed,
+  lshBucket,
+  lshBucketFromSql,
+  lshBucketToSql,
+  lshHammingSql,
+  neighborBuckets,
+  serializePlanes,
+} 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");
+  });
+
+  test("write-time and query-time buckets are identical for the same vector", () => {
+    const seed = hyperplaneSeed("g17_docs", "body", 32, LSH_DEFAULT_K);
+    const planes = generateHyperplanes(seed, 32, LSH_DEFAULT_K);
+    const reloaded = deserializePlanes(serializePlanes(planes), LSH_DEFAULT_K);
+    const vector = synthHashBag(
+      "refund policy shipping delay. Document 0 discusses refund policy shipping delay.",
+    );
+    const write = lshBucket(vector, planes);
+    const query = lshBucket(vector, reloaded);
+    expect(write).toBe(query);
+    expect(lshBucketToSql(write)).toBe(lshBucketToSql(query));
+    expect(neighborBuckets(write, LSH_DEFAULT_K)).toHaveLength(LSH_DEFAULT_K + 1);
+  });
+
+  test("K=64 Hamming-1 misses G17-like neighbors; Hamming-rank recovers them", () => {
+    // Same deterministic hash-bag generator G17 uses — 40 docs, 8 topics.
+    const topics = [
+      "refund policy shipping delay",
+      "password reset two factor auth",
+      "invoice payment stripe webhook",
+      "search ranking bm25 hybrid",
+      "postgres gin btree index plan",
+      "tenant isolation row level security",
+      "durable flow journal resume",
+      "live query fanout subscriber",
+    ];
+    const planes = generateHyperplanes(hyperplaneSeed("g17_docs", "body", 32, 64), 32, 64);
+    const docs = topics.flatMap((topic, t) =>
+      [0, 1, 2, 3, 4].map((n) => {
+        const i = t + n * 8;
+        const body = `${topic}. Document ${i} discusses ${topic} with enough tokens for BM25.`;
+        const vec = synthHashBag(body);
+        return { i, vec, bucket: lshBucket(vec, planes) };
+      }),
+    );
+    const qVec = synthHashBag(topics[0]!);
+    const qBucket = lshBucket(qVec, planes);
+    const scored = docs.map((d) => ({
+      i: d.i,
+      cos: cosineSimilarity(qVec, d.vec),
+      ham: hammingDistance(qBucket, d.bucket),
+    }));
+    const exact = [...scored].sort((a, b) => b.cos - a.cos).slice(0, 10);
+    const exactSet = new Set(exact.map((x) => x.i));
+    const ham1 = scored.filter((s) => s.ham <= 1);
+    const ham1Hits = ham1.filter((s) => exactSet.has(s.i)).length;
+    const ranked = [...scored].sort((a, b) => a.ham - b.ham || b.cos - a.cos).slice(0, 50);
+    const rankedTop = [...ranked].sort((a, b) => b.cos - a.cos).slice(0, 10);
+    const rankedHits = rankedTop.filter((s) => exactSet.has(s.i)).length;
+    // Hamming-1 is the broken probe (G17 P@10 ≈ 0). Hamming-rank of the K=64
+    // pack recovers the exact cosine top-10 on this 40-row hand case.
+    expect(ham1Hits).toBe(0);
+    expect(rankedHits).toBe(10);
+    expect(exact.every((e) => e.ham > 1)).toBe(true);
+    expect(lshHammingSql("__oke_lsh_body")).toContain("bit_count");
+  });
+});
+
+/**
+ * G17 synthetic embedding — deterministic SHA-256 hash bag, L2-normalized.
+ *
+ * @param text - Source text
+ */
+function synthHashBag(text: string, dims = 32): number[] {
+  const v = Array.from({ length: dims }, () => 0);
+  const tokens = text.toLowerCase().split(/\W+/).filter(Boolean);
+  for (const t of tokens) {
+    const h = createHash("sha256").update(t).digest();
+    for (let i = 0; i < dims; i++) {
+      v[i]! += (h[i % h.length]! / 255) * 2 - 1;
+    }
+  }
+  let norm = 0;
+  for (const x of v) norm += x * x;
+  norm = Math.sqrt(norm) || 1;
+  return v.map((x) => x / norm);
+}
+
+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);