@lunora/sql-store 1.0.0-alpha.16 → 1.0.0-alpha.160

package/dist/index.d.mts

@@ -1,139 +1,185 @@
-import { ServerDefaultContextLike, DatabaseWriterLike, SchedulerLike, SchemaLike, TableDefinitionLike, ValidatorLike } from '@lunora/do';
-import { SqlDialect, SqlRunResult } from "./dialect.mjs";
+import { TableDefinitionLike, ServerDefaultContextLike, DatabaseWriterLike, CrossShardReadArgs, QueryPage, SchedulerLike, SchemaLike, CdcChange, ValidatorLike } from '@lunora/shard-engine';
+import { SqlRunResult, SqlDialect } from "./dialect.mjs";
 export type { SqlExec } from "./dialect.mjs";
 import 'drizzle-orm';
 /**
-* Async SQL surface the D1 ORM needs: `all` for reads, `run` for writes.
-* Satisfied by a `D1Session`/`D1Client` in production and a `node:sqlite`
-* adapter in tests, so the query logic runs against a real SQLite engine.
-*/
+ * Async SQL surface the D1 ORM needs: `all` for reads, `run` for writes.
+ * Satisfied by a `D1Session`/`D1Client` in production and a `node:sqlite`
+ * adapter in tests, so the query logic runs against a real SQLite engine.
+ */
 interface SqlCtxExec {
   all: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  batch?: (statements: ReadonlyArray<{
+    params: ReadonlyArray<unknown>;
+    sql: string;
+  }>) => Promise<void>;
   run: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<SqlRunResult | void>;
 }
+/**
+ * Decode a SELECTed row back into a document: `id` → `_id`, `_creationTime`
+ * preserved, and every column run through the shared {@link sqliteDecode} so the
+ * stored form is reversed back into its JS shape. Exported so the data-browser
+ * (`introspect.ts`) and admin export/import paths share the exact same decode.
+ *
+ * The decode is engine-agnostic: every backend stores SQLite-shaped values
+ * (boolean → 1/0, JSON → text, bigint → an order-preserving text key), and `sqliteDecode` is
+ * robust to a driver returning either the stored string OR a natively-parsed
+ * value (e.g. mysql2 returns JSON columns pre-parsed) — so the same decoder is
+ * correct on SQLite, Postgres and MySQL.
+ */
+declare const decodeGlobalRow: (definition: TableDefinitionLike, row: Record<string, unknown>) => Record<string, unknown>;
 interface SqlCtxDbOptions {
   /**
-  * Resolved request auth handed to `.serverDefault(fn)` column factories so
-  * server-trusted columns (owner/tenant ids) stamp from the verified caller,
-  * never the client. The generated worker passes the per-request identity;
-  * absent it, server-trusted columns stamp the anonymous slice (`userId: null`).
-  */
+   * Resolved request auth handed to `.serverDefault(fn)` column factories so
+   * server-trusted columns (owner/tenant ids) stamp from the verified caller,
+   * never the client. The generated worker passes the per-request identity;
+   * absent it, server-trusted columns stamp the anonymous slice (`userId: null`).
+   */
   auth?: ServerDefaultContextLike["auth"];
   /**
-  * Opt into change-data-capture: when `true`, every committed write appends a
-  * post-image to the `__cdc_log` table (created lazily alongside the other
-  * companion tables). Backs CDC streaming export for `.global()` tables — the
-  * log is for export/CDC consumers, NOT point-in-time recovery: D1's PITR is
-  * the platform's own Time Travel (`wrangler d1 time-travel restore`), an
-  * atomic restore, not a changelog replay. Leave undefined for zero-cost
-  * legacy behaviour.
-  */
+   * Opt into change-data-capture: when `true`, every committed write appends a
+   * post-image to the `__cdc_log` table (created lazily alongside the other
+   * companion tables). Backs CDC streaming export for `.global()` tables — the
+   * log is for export/CDC consumers, NOT point-in-time recovery: D1's PITR is
+   * the platform's own Time Travel (`wrangler d1 time-travel restore`), an
+   * atomic restore, not a changelog replay. Leave undefined for zero-cost
+   * legacy behaviour.
+   */
   cdc?: boolean;
+  /**
+   * How long `.global()` changelog entries are kept, in milliseconds. Absent
+   * (the default) means forever — the log grows for the life of the database.
+   *
+   * Opt-in for the same reason the shard-local windows are, and the reason is
+   * not caution: this log's streaming-export consumers hold opaque cursors
+   * issued outside this deployment, and nothing here can see where they sit.
+   * A default window would be a guess whose failure mode is silent data loss
+   * in someone's warehouse. A deployment that wants the log bounded states a
+   * window it knows covers its consumers; `.global()` shape pollers are then
+   * protected exactly, by the floor this read path reports rather than by the
+   * window. See `sweepSqlCdcRetention`.
+   *
+   * Time rather than rows because the log is SHARED: every shard in every
+   * region writes it, so a row count is not a bound any single consumer can
+   * reason about, while "older than N" is exactly what they compare their own
+   * lag against.
+   */
+  cdcRetentionMs?: number;
   clock?: () => number;
   /**
-  * Cross-shard counter for **reverse cross-backend relations** — the `_count`
-  * mirror of the `crossShardReader` option below.
-  */
+   * Cross-shard counter for **reverse cross-backend relations** — the `_count`
+   * mirror of the `crossShardReader` option below.
+   */
   crossShardCounter?: DatabaseWriterLike["count"];
   /**
-  * Optional cross-shard reader for **reverse cross-backend relations**: a
-  * `.global()` (D1) parent loading a shard-local (`.shardBy()`/root) child.
-  * Such a child's rows are partitioned across every shard DO, so the local D1
-  * writer can't resolve it. When provided, the relation loader routes the
-  * child's read through this (the host wires it to the Query Coordinator's
-  * RLS-correct `fanOut`, with identity forwarded so each shard applies its own
-  * RLS). Absent it, loading such a relation throws a clear "not supported"
-  * error (legacy behaviour). The forward direction (shard-local parent →
-  * global child) and same-backend relations never touch this.
-  */
-  crossShardReader?: DatabaseWriterLike["findMany"];
+   * Optional cross-shard reader for **reverse cross-backend relations**: a
+   * `.global()` (D1) parent loading a shard-local (`.shardBy()`/root) child.
+   * Such a child's rows are partitioned across every shard DO, so the local D1
+   * writer can't resolve it. When provided, the relation loader routes the
+   * child's read through this (the host wires it to the Query Coordinator's
+   * RLS-correct `fanOut`, with identity forwarded so each shard applies its own
+   * RLS). Absent it, loading such a relation throws a clear "not supported"
+   * error (legacy behaviour). The forward direction (shard-local parent →
+   * global child) and same-backend relations never touch this.
+   *
+   * Takes {@link CrossShardReadArgs}, not `QueryArgs`: the hop is JSON, so the
+   * RLS filters are handed over as data (see that type's docblock).
+   */
+  crossShardReader?: (table: string, args: CrossShardReadArgs) => Promise<QueryPage>;
   /**
-  * The SQL dialect that shapes every statement (identifier quoting, value
-  * encode/decode, column types, upserts, RETURNING vs affected-rows).
-  * `@lunora/d1` passes its `sqliteDialect`; the PlanetScale/Hyperdrive backend
-  * passes its Postgres/MySQL dialect. Required — the core is engine-blind.
-  */
+   * The SQL dialect that shapes every statement (identifier quoting, value
+   * encode/decode, column types, upserts, RETURNING vs affected-rows).
+   * `@lunora/d1` passes its `sqliteDialect`; the PlanetScale/Hyperdrive backend
+   * passes its Postgres/MySQL dialect. Required — the core is engine-blind.
+   */
   dialect: SqlDialect;
   exec: SqlCtxExec;
   idGenerator?: () => string;
   /**
-  * Ceiling on the number of child join keys a relation-crossing `where`
-  * predicate may materialize before the semijoin pre-resolver fails closed
-  * (`relation predicate … exceeding the N-key limit`). D1 has no EXISTS
-  * push-down, so an overflow here can only fail closed — never truncate the
-  * `IN (...)` and silently mis-match. Defaults to the pre-resolver's shared
-  * key cap when omitted.
-  */
+   * Ceiling on the number of child join keys a relation-crossing `where`
+   * predicate may materialize before the semijoin pre-resolver fails closed
+   * (`relation predicate … exceeding the N-key limit`). D1 has no EXISTS
+   * push-down, so an overflow here can only fail closed — never truncate the
+   * `IN (...)` and silently mis-match. Defaults to the pre-resolver's shared
+   * key cap when omitted.
+   */
   maxRelationKeys?: number;
   /**
-  * Scheduler exposed to global-table trigger handlers as `ctx.scheduler`.
-  * Absent it, `ctx.scheduler` is a stub that throws on use — pass one when
-  * triggers on `.global()` tables need to enqueue follow-up work.
-  */
+   * Object identifying the database this store provisions, so the one-shot
+   * `CREATE TABLE/INDEX IF NOT EXISTS` sweep is shared by every ctx-db built
+   * against it instead of repeating per instance.
+   *
+   * Hosts build a ctx-db **per request** (the writer captures the caller's
+   * identity and D1 bookmark), so without this the sweep — one round trip per
+   * global table plus one per index — runs again on the first `.global()`
+   * access of every request. On a 50-table schema that is ~1s in `lunora dev`
+   * and a real latency floor in production.
+   *
+   * WHAT TO PASS: something that outlives the request AND names one database
+   * (and one configuration). The D1 binding off `env` and the declaration
+   * object a host builds once both qualify; the result of a per-request
+   * factory does not — it keys the memo on a fresh object every time and
+   * shares nothing (which is silent, and looks exactly like not passing it).
+   *
+   * INVARIANT, unenforced: one scope ⇒ one `schema`, `dialect` and `cdc`. The
+   * memoised run closes over the FIRST writer's, so a later writer sharing a
+   * scope with `cdc: true` behind one with `cdc: false` never gets
+   * `__cdc_log`. Hosts pass app-level constants for all three, which is why
+   * this is a note rather than a composite key.
+   *
+   * Two behaviours change with a shared memo, both benign and both worth
+   * knowing: the DDL runs in the FIRST writer's D1 session, so a later
+   * session's first read is no longer implicitly pinned behind a write of its
+   * own (on a replicated binding that can mean one transient stale read on a
+   * freshly-provisioned database); and a database reset out from under a live
+   * isolate is no longer healed by the next request, since the entry lives as
+   * long as the scope does.
+   *
+   * Omit it and the memo stays per ctx-db — slower, never wrong, and what the
+   * tests want (they pair a fresh database with a reused schema object).
+   */
+  provisionScope?: object;
+  /**
+   * Scheduler exposed to global-table trigger handlers as `ctx.scheduler`.
+   * Absent it, `ctx.scheduler` is a stub that throws on use — pass one when
+   * triggers on `.global()` tables need to enqueue follow-up work.
+   */
   scheduler?: SchedulerLike;
   schema: SchemaLike;
 }
-/**
-* Decode a SELECTed row back into a document: `id` → `_id`, `_creationTime`
-* preserved, and every column run through the shared {@link sqliteDecode} so the
-* stored form is reversed back into its JS shape. Exported so the data-browser
-* (`introspect.ts`) and admin export/import paths share the exact same decode.
-*
-* The decode is engine-agnostic: every backend stores SQLite-shaped values
-* (boolean → 1/0, JSON → text, bigint → decimal string), and `sqliteDecode` is
-* robust to a driver returning either the stored string OR a natively-parsed
-* value (e.g. mysql2 returns JSON columns pre-parsed) — so the same decoder is
-* correct on SQLite, Postgres and MySQL.
-*/
-declare const decodeGlobalRow: (definition: TableDefinitionLike, row: Record<string, unknown>) => Record<string, unknown>;
-declare const runSqlGlobalTableMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
-/**
-* Materialize the `__agg_&lt;index>` companion tables for every declared
-* `aggregateIndex` on a global table. Global tables in Lunora ship their own
-* DDL — counter tables are opt-in so production hosts can decide where they
-* live. Tests and dev hosts can call this once after their schema migration to
-* unlock O(1) counts.
-*
-* Idempotent (`CREATE TABLE IF NOT EXISTS`).
-*/
-declare const runSqlAggregateMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
-/**
-* Materialize the `__rank_&lt;index>` companion tables for every declared
-* `rankIndex` on a global table. Mirrors `runSqlAggregateMigrations` — same
-* opt-in pattern so production hosts decide whether to spend the DDL.
-*
-* Idempotent (`CREATE TABLE IF NOT EXISTS` + `createIndexIfNotExists`).
-*/
-declare const runSqlRankMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
-/**
-* Materialize the `__fts_&lt;index>` FTS5 shadow tables for every declared
-* `.searchIndex()` on a global table. Mirrors `runSqlAggregateMigrations` — same
-* opt-in pattern so production hosts decide whether to spend the DDL. Only runs
-* on engines that ship FTS5 (D1 does; the `node:sqlite` test runner doesn't,
-* where `.search()` transparently falls back to a scan). `__text__` holds the
-* indexed field; `__id__` (UNINDEXED) joins back to the row.
-*
-* Idempotent (`CREATE VIRTUAL TABLE IF NOT EXISTS`).
-*/
-declare const runSqlSearchMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
-/** One change-data-capture entry: a committed mutation, in monotonic `seq` order. Mirrors the DO twin. */
-interface CdcChange {
-  /** Post-image document for insert/update; absent for delete (the `id` identifies the removed row). */
-  doc?: Record<string, unknown>;
-  id: string;
-  op: "delete" | "insert" | "update";
-  /** Monotonic per-database cursor — strictly increasing, never reused. */
-  seq: number;
-  table: string;
-  /** Wall-clock millis when the change committed (the ctx-db `clock`). */
-  ts: number;
-}
 /** Create the `__cdc_log` table. Idempotent; only run when CDC is enabled. */
 declare const runSqlCdcMigration: (exec: SqlCtxExec, dialect: SqlDialect) => Promise<void>;
 /**
-* Read changelog entries newer than `sinceSeq` in commit order, up to `limit`
-* (clamped to [1, 10000]); plus the cursor to resume from.
-*/
+ * Delete `.global()` changelog entries older than `retentionMs`, at most
+ * {@link GLOBAL_CDC_SWEEP_MAX_ROWS} per pass, and only if this writer wins the lease.
+ *
+ * **Time, not rows.** The shard-local twin bounds its log by row count because
+ * one shard owns it and a row count is a memory bound on that one object. This
+ * log is shared, so a row count means nothing to any individual consumer — but
+ * "older than N" is directly what every consumer needs to reason about, and it
+ * is the unit an operator can compare against their own connector's lag.
+ *
+ * **Which consumers this can strand, and what protects each:**
+ *
+ * - `.global()` shape pollers hold in-memory cursors this store cannot see. They
+ *   are protected EXACTLY rather than approximately: {@link readSqlCdcChangedTables}
+ *   reports the retained floor, and a poller below it treats the tick as "no
+ *   visibility" and re-reads every shape. That is the same self-healing path a
+ *   changelog error already takes, so a trimmed poller is slow for one tick, not
+ *   wrong. No cursor registry, no assumption about how far behind a shard can be.
+ * - Streaming-export / warehouse consumers hold opaque cursors issued outside
+ *   this deployment. Nothing here can see them, so nothing here guesses:
+ *   {@link readSqlCdcChanges} refuses a page below the floor rather than serving
+ *   the surviving tail, and retention stays OFF unless an operator states a
+ *   window they know covers their connector.
+ */
+declare const sweepSqlCdcRetention: (exec: SqlCtxExec, dialect: SqlDialect, retentionMs: number, now: number) => Promise<void>;
+/** Oldest `seq` still retained in the `.global()` changelog, or `undefined` when it is empty. */
+declare const readSqlCdcFloor: (exec: SqlCtxExec, dialect: SqlDialect) => Promise<number | undefined>;
+/**
+ * Read changelog entries newer than `sinceSeq` in commit order, up to `limit`
+ * (clamped to [1, 10000]); plus the cursor to resume from.
+ */
 declare const readSqlCdcChanges: (exec: SqlCtxExec, options: {
   limit?: number;
   sinceSeq?: number;
@@ -141,34 +187,233 @@ declare const readSqlCdcChanges: (exec: SqlCtxExec, options: {
   changes: CdcChange[];
   cursor: number;
 }>;
-/** Drop changelog entries at or below a checkpointed `throughSeq` (retention). */
-declare const trimSqlCdcChanges: (exec: SqlCtxExec, throughSeq: number, dialect: SqlDialect) => Promise<void>;
+/**
+ * Which tables the changelog recorded a write to after `sinceSeq`, plus the
+ * cursor to resume from. Metadata only — it reads no `doc`, so its cost is a
+ * grouped scan over an index range rather than the size of the documents in it.
+ *
+ * The `.global()` shape poll asks this once per tick for the whole shard, and a
+ * shape whose table is absent from the answer skips its membership read
+ * entirely.
+ *
+ * **One statement, and the cursor comes out of the same rows as the tables.**
+ * Reading the head separately — in either order — opens a window where a write
+ * commits between the two round trips and ends up absent from `tables` while
+ * sitting at or below the adopted `cursor`, which loses it for good. Deriving
+ * the cursor as the max `seq` actually returned closes that window by
+ * construction: the caller can never advance past a row this scan did not see.
+ *
+ * **Late commits.** Postgres and MySQL allocate `seq` at INSERT, not at commit,
+ * so an append holding `N` can commit after one holding `N + 1`. A poll that
+ * adopts `N + 1` while `N` is still in flight skips `N` until the next resync
+ * pass. So on those engines the cursor stops below the first HOLE in `seq`
+ * rather than at the highest row seen: a hole is an allocated `seq` that is not
+ * (yet) visible, which is exactly what an in-flight append looks like. Tables
+ * above the hole are still reported, so nothing is delayed — rows past the
+ * cursor are just reported again next tick.
+ *
+ * A hole can also be permanent (a failed append burns its `seq`), and a cursor
+ * pinned under one forever would re-report everything above it on every tick.
+ * So a hole only holds the cursor while the first row after it is younger than
+ * {@link CDC_LATE_COMMIT_WINDOW_MS}: that row's append started before its own
+ * `seq` was allocated, which is after the hole's, so once it is that old the
+ * hole's owner has either committed (and is visible) or never will. An append
+ * slower than the window falls back to the resync interval, as before. A MySQL
+ * `auto_increment_increment` above 1 makes every step a hole, which holds the
+ * cursor one window behind the head: correct, just less narrowing.
+ *
+ * D1 skips all of this: single writer, `AUTOINCREMENT`, and `withSession` gives
+ * both reads one snapshot, so there is no hole to wait for — and D1 bills rows
+ * read.
+ */
+declare const readSqlCdcChangedTables: (exec: SqlCtxExec, sinceSeq: number, dialect: SqlDialect, options?: {
+  cursorOnly?: boolean;
+  now?: number;
+  retained?: boolean;
+}) => Promise<{
+  cursor: number;
+  floor?: number;
+  tables: string[];
+}>;
 declare const createSqlCtxDb: (options: SqlCtxDbOptions) => DatabaseWriterLike;
+/**
+ * Auto-provision every `.global()` table from the schema: `CREATE TABLE IF NOT
+ * EXISTS` with the physical `id`/`_creationTime` columns plus a typed column per
+ * declared field, then its secondary and `.unique()` indexes. This is the D1
+ * twin of `@lunora/do`'s `runShardMigrations` (which self-creates shard-local
+ * tables) — it makes the schema the single source of truth for global tables
+ * too, so a fresh database serves them without a hand-applied migration. The
+ * column set and dialect match exactly what this module reads and writes
+ * (`columnRef`, `serializeColumnValue`, `decodeGlobalRow`).
+ *
+ * Idempotent (`CREATE TABLE/INDEX IF NOT EXISTS`); additive only — it never
+ * drops or retypes an existing column, so destructive schema changes still need
+ * an explicit migration.
+ */
+declare const runSqlGlobalTableMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
+/**
+ * Materialize the `__agg_<index>` companion tables for every declared
+ * `aggregateIndex` on a global table. Global tables in Lunora ship their own
+ * DDL — counter tables are opt-in so production hosts can decide where they
+ * live. Tests and dev hosts can call this once after their schema migration to
+ * unlock O(1) counts.
+ *
+ * Idempotent (`CREATE TABLE IF NOT EXISTS`).
+ */
+declare const runSqlAggregateMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
+/**
+ * Materialize the `__rank_<index>` companion tables for every declared
+ * `rankIndex` on a global table. Mirrors `runSqlAggregateMigrations` — same
+ * opt-in pattern so production hosts decide whether to spend the DDL.
+ *
+ * Idempotent (`CREATE TABLE IF NOT EXISTS` + `createIndexIfNotExists`).
+ */
+declare const runSqlRankMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
+/** What {@link backfillSqlSearchIndexes} could not finish. */
+interface SqlSearchBackfillResult {
+  /**
+   * Inverted companions that still lack their unique `(token, id)` key. Writes
+   * keep working without it, but two backfills racing over one row can index
+   * it twice; the warning logged for each says why the key was refused.
+   */
+  uniqueKeyMissing: string[];
+  /** A previous build's rows left unmigrated because every attempt at them lost to a concurrent write. */
+  unmappedSkipped: number;
+}
+/**
+ * Provision the search companions, then index one bounded page of the rows that
+ * predate each index — unless it is declared `staged: true`, which leaves the
+ * whole backfill to {@link backfillSqlSearchIndexes}.
+ *
+ * Idempotent (`CREATE … IF NOT EXISTS` throughout, and the backfill resumes
+ * from recorded progress).
+ */
+declare const runSqlSearchMigrations: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<void>;
+/**
+ * Run every declared search index — including the `staged: true` ones the
+ * migration pass skips — through to completion. The entry point a host calls
+ * out-of-band after deploying a search index over a table too large to index a
+ * page at a time.
+ *
+ * Idempotent and resumable: an index recorded as complete is skipped, and an
+ * interrupted run picks up from its cursor.
+ */
+declare const backfillSqlSearchIndexes: (exec: SqlCtxExec, schema: SchemaLike, dialect: SqlDialect) => Promise<SqlSearchBackfillResult>;
+/** Reserved table holding one backfill-progress row per search companion. */
+declare const SEARCH_STATE_TABLE = "__lunora_search_state";
+/** Create the progress table. Idempotent; runs alongside the companion DDL. */
+declare const migrateSearchState: (exec: SqlCtxExec, dialect: SqlDialect) => Promise<void>;
 /** Map a JS value onto its SQLite storage form — SQLite has no boolean, so true/false → 1/0. */
-declare const sqliteEncode: (value: unknown) => unknown;
+declare const sqliteEncode: (value: unknown, kind?: string) => unknown;
 /** Parse `raw` as JSON, returning `raw` unchanged when it is not valid JSON. */
 declare const tryJsonParse: (raw: string) => unknown;
-/** Decode a `bigint` column: a decimal string back into a `BigInt`, else verbatim. */
+/**
+ * Decode a `bigint` column: the order-preserving key {@link bigintSqlKey} writes,
+ * or — for a row stored by a build that wrote plain decimal text — the decimal
+ * string, else verbatim.
+ */
 declare const decodeBigint: (raw: unknown) => unknown;
 /**
-* Resolve the *effective* storage kind of a column validator. Encoding keys off
-* the runtime value's JS type, so a `v.optional(inner)` column stores its
-* present value exactly as `inner` would. The validator's own `kind` is
-* `"optional"`, which hides that — unwrap to the inner validator's kind so the
-* decode reverses the real storage form. The inner validator is stashed on
-* `_meta.inner` by `@lunora/values`' `createValidator`.
-*/
+ * Resolve the *effective* storage kind of a column validator: `v.optional(inner)`
+ * unwrapped to `inner`'s kind, since encoding keys off the runtime value's JS
+ * type and the validator's own `kind` of `"optional"` hides that.
+ *
+ * A thin alias over `shared/effective-kind`, which is where the rule lives so
+ * the DO row store applies the identical one — it reads the same validators and
+ * has the same failure mode, and two copies drifted the last time.
+ */
 declare const effectiveColumnKind: (validator: ValidatorLike) => string | undefined;
 /**
-* Inverse of {@link sqliteEncode}: map a SQLite storage value back onto its JS
-* form, driven by the field's effective validator `kind`:
-*
-* - `boolean`: 1/0 → true/false (SQLite has no boolean type).
-* - `bigint`: decimal string → `BigInt`.
-* - `object`/`array`/`record`: JSON string → parsed value.
-* - `union`/`any`: parsed back only when the stored string is a JSON non-scalar
-*   (a scalar union member round-trips through SQLite's native column type).
-* - everything else (string/number/date/timestamp/id/literal): verbatim.
-*/
+ * Inverse of {@link sqliteEncode}: map a SQLite storage value back onto its JS
+ * form, driven by the field's effective validator `kind`:
+ *
+ * - `boolean`: 1/0 → true/false (SQLite has no boolean type).
+ * - `bigint`: decimal string → `BigInt`.
+ * - `bytes`: normalizes any driver return shape to a genuine `ArrayBuffer` — a
+ *   view (`Uint8Array`/`Buffer`/…) is sliced to its own byte window, a plain
+ *   `ArrayBuffer` passes through, and an array of byte values is packed into a
+ *   fresh buffer. Required because `v.bytes()` validates
+ *   `value instanceof ArrayBuffer` and different backends return different BLOB
+ *   shapes: the D1 binding `Array<number>`, workerd's raw SQLite `ArrayBuffer`,
+ *   node:sqlite `Uint8Array`, pg/mysql2 `Buffer`. The D1 one is the shape only a
+ *   real binding produces, so the array case has its test in the workerd suite.
+ * - `object`/`array`/`record`/`geoPoint`: JSON string → parsed value. `geoPoint`
+ *   belongs here because {@link sqliteEncode} keys off the runtime JS type and
+ *   stores the `{ lat, lng }` object as JSON in a TEXT column; without the case
+ *   it fell through to `default:` and every client read back the raw JSON text.
+ * - `union`/`any`/`from`: parsed back when the stored string is a JSON
+ *   non-scalar, or when it carries the {@link WIRE_PREFIX} marker.
+ *   A `number` or `boolean` does NOT round-trip through the column's native
+ *   type — all three kinds store as TEXT on every engine, which coerces a bound
+ *   `42` to the text `42.0` — so {@link sqliteEncode} writes those two in the
+ *   marked form and this branch reverses them by the marker alone. A number's
+ *   marked payload is `float64SqlKey`, so its text order is numeric order; the
+ *   marked JSON an earlier build wrote is still read back here, which is what
+ *   makes a table correct between the format change and the rewrite pass.
+ *   `from` belongs to THIS group, not to `object`/`array`/`record`: an external
+ *   Standard Schema can describe a string just as easily as an object, and
+ *   {@link sqliteEncode} keys off the runtime JS type — so a `v.from(z.string())`
+ *   column holding `"123"` is stored verbatim, and unconditional parsing would
+ *   read it back as the NUMBER 123.
+ *   A `bigint` member decodes too, by SHAPE: {@link sqliteEncode} keys off the
+ *   runtime type, so a bigint here is stored as the same order-preserving key a
+ *   declared `v.bigint()` column gets, and returning that verbatim handed the
+ *   caller 40 characters of padding instead of the value it wrote. See the
+ *   ambiguity this buys, and why the wire marker cannot carry it instead, below.
+ *   CAVEAT: a union/any/from member is stored verbatim by {@link sqliteEncode}, so
+ *   a legitimate *string* value that itself looks like JSON (`'{"a":1}'`, `'[1,2]'`)
+ *   is ambiguous on read and decodes back to the parsed object/array, not the
+ *   original string. The bigint test admits the same class of ambiguity, narrower
+ *   but real: `decodeBigintSqlKey` accepts EXACTLY 40 characters — `"0"` or `"1"`,
+ *   then 39 digits — and a stored *string* of that shape (a zero-padded account
+ *   number, a numeric external id) is byte-identical on disk to a key and reads
+ *   back as a `bigint`. Pinned by a test in `ctx-db.test.ts` so the trade is
+ *   visible rather than rediscovered.
+ *
+ *   Preferred anyway, because the alternative is not "no ambiguity" but
+ *   guaranteed corruption: WITHOUT the test, every bigint any code writes to an
+ *   untyped column comes back as padding, on every read. The narrow false
+ *   positive costs a specific 40-character digit string its type; the absent test
+ *   cost every such column its value.
+ *
+ *   The unambiguous {@link WIRE_PREFIX} marker cannot carry this instead. It is
+ *   not reached: {@link sqliteEncode} returns at its `bigint` branch first, and it
+ *   takes no `kind`, so it cannot encode an untyped column differently from a
+ *   declared one. It is also `serializeColumnValue`, which builds every WHERE
+ *   binding — a prefixed bigint would never match a row stored as a key, and the
+ *   padded key is order-preserving on purpose (indexes, range predicates, MIN/MAX
+ *   all read it). Two storage forms for one runtime type breaks comparison
+ *   between them. Disambiguating properly means tagging every encoded non-scalar,
+ *   a breaking storage-format change, so it is documented rather than fixed.
+ * - everything else (string/number/date/timestamp/id/literal): verbatim.
+ */
 declare const sqliteDecode: (raw: unknown, kind: string | undefined) => unknown;
-export { type SqlCtxDbOptions, type SqlCtxExec, type SqlDialect, type SqlRunResult, createSqlCtxDb, decodeBigint, decodeGlobalRow, effectiveColumnKind, readSqlCdcChanges, runSqlAggregateMigrations, runSqlCdcMigration, runSqlGlobalTableMigrations, runSqlRankMigrations, runSqlSearchMigrations, sqliteDecode, sqliteEncode, trimSqlCdcChanges, tryJsonParse };
+export { SEARCH_STATE_TABLE,
+/**
+ * `@lunora/sql-store` — the internal, dialect-parameterized SQL store core
+ * shared by Lunora's `.global()` table backends.
+ *
+ * One ORM implementation (`createSqlCtxDb`) drives any SQL engine through a
+ * `SqlDialect`: SQLite via `@lunora/d1`, and Postgres/MySQL (PlanetScale, Neon,
+ * any Hyperdrive-reachable database) via `@lunora/hyperdrive`. Reactivity is
+ * unaffected — the writer is injected as `globalDb` into `createShardCtxDb`,
+ * whose `broadcast` hook drives live queries regardless of engine.
+ *
+ * This package is internal: consumers depend on `@lunora/d1` or
+ * `@lunora/hyperdrive`, which assemble the concrete dialect and wrap the core.
+ */
+type SqlCtxDbOptions,
+/**
+ * `@lunora/sql-store` — the internal, dialect-parameterized SQL store core
+ * shared by Lunora's `.global()` table backends.
+ *
+ * One ORM implementation (`createSqlCtxDb`) drives any SQL engine through a
+ * `SqlDialect`: SQLite via `@lunora/d1`, and Postgres/MySQL (PlanetScale, Neon,
+ * any Hyperdrive-reachable database) via `@lunora/hyperdrive`. Reactivity is
+ * unaffected — the writer is injected as `globalDb` into `createShardCtxDb`,
+ * whose `broadcast` hook drives live queries regardless of engine.
+ *
+ * This package is internal: consumers depend on `@lunora/d1` or
+ * `@lunora/hyperdrive`, which assemble the concrete dialect and wrap the core.
+ */
+type SqlCtxExec, type SqlDialect, type SqlRunResult, type SqlSearchBackfillResult, backfillSqlSearchIndexes, createSqlCtxDb, decodeBigint, decodeGlobalRow, effectiveColumnKind, migrateSearchState, readSqlCdcChangedTables, readSqlCdcChanges, readSqlCdcFloor, runSqlAggregateMigrations, runSqlCdcMigration, runSqlGlobalTableMigrations, runSqlRankMigrations, runSqlSearchMigrations, sqliteDecode, sqliteEncode, sweepSqlCdcRetention, tryJsonParse };