@lunora/sql-store 0.0.0 → 1.0.0-alpha.10

package/dist/dialect.d.mts

@@ -0,0 +1,82 @@
+import { SQL } from 'drizzle-orm';
+/** Outcome of a non-`SELECT` statement: the row count it changed (for MySQL OCC, which lacks `RETURNING`). */
+interface SqlRunResult {
+  /** Rows the statement inserted/updated/deleted. `0` when the engine can't report it. */
+  rowsAffected: number;
+}
+/**
+* The async SQL surface the store core consumes. Satisfied by a
+* `D1Session`/`D1Client` (D1), a `node:sqlite` adapter (tests), or a
+* Hyperdrive-backed `postgres`/`pg`/`mysql2` driver (PlanetScale).
+*
+* `all` runs a row-returning statement (incl. `... RETURNING ...`); `run` runs a
+* write and reports `rowsAffected` — the matched-rows count that drives the
+* MySQL optimistic-concurrency guard (which has no `RETURNING`).
+*
+* Note: companion writes (aggregate/rank/FTS/CDC) run as separate sequential
+* statements after the row write on every engine, so they share D1's
+* at-least-once caveat — there is no cross-statement transaction here.
+*/
+interface SqlExec {
+  all: (sql: string, params: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  run: (sql: string, params: ReadonlyArray<unknown>) => Promise<SqlRunResult>;
+}
+/** Everything engine-specific the store core needs. One value per engine; `sqliteDialect` (in `@lunora/d1`) is the reference, Postgres/MySQL live in `@lunora/hyperdrive/global`. */
+interface SqlDialect {
+  /** Affected-rows extractor for the OCC fallback when `supportsReturning` is false (MySQL). */
+  affectedRows?: (result: SqlRunResult) => number;
+  /**
+  * Storage SQL column type for a validator `kind`. SQLite affinity
+  * (`TEXT`/`INTEGER`/`REAL`/`BLOB`); Postgres `TEXT`/`DOUBLE PRECISION`/
+  * `BOOLEAN`/`JSONB`/`BYTEA`; MySQL `VARCHAR(255)`/`TEXT`/`DOUBLE`/
+  * `TINYINT(1)`/`JSON`/`LONGBLOB`.
+  */
+  columnType: (kind: string | undefined) => string;
+  /**
+  * Engine SQL types for the **internal companion tables** (aggregate / rank /
+  * CDC), which are built from raw SQL types, not validator kinds. SQLite uses
+  * `TEXT`/`REAL`/`INTEGER`/`BLOB` and `INTEGER PRIMARY KEY AUTOINCREMENT`;
+  * Postgres `TEXT`/`DOUBLE PRECISION`/`INTEGER`/`BYTEA` + `BIGSERIAL`; MySQL
+  * needs a bounded `VARCHAR` key, `DOUBLE`, `LONGBLOB`, `AUTO_INCREMENT`.
+  */
+  companionTypes: {
+    autoincrementPrimaryKey: string;
+    integer: string;
+    key: string;
+    real: string;
+    text: string;
+  };
+  /** Map a stored value back to its JS form, by effective validator `kind` (inverse of `encode`). */
+  decode: (value: unknown, kind: string | undefined) => unknown;
+  /** Map a JS value to its bound storage form (boolean→1/0, bigint→string, object→JSON on SQLite; mostly native on PG). */
+  encode: (value: unknown) => unknown;
+  /** The framework columns every global table carries — the `id` primary key and `_creationTime` — as `{ name, type }` so the DDL builder can quote each name through the engine's dialect. */
+  frameworkColumns: () => ReadonlyArray<{
+    name: string;
+    type: string;
+  }>;
+  /**
+  * Optional: the key-prefix length an indexed column of this `kind` needs.
+  * MySQL/InnoDB can't index a `TEXT`/`LONGTEXT`/`BLOB` column without a prefix
+  * (the store appends `(&lt;n>)` to the column reference); SQLite/Postgres index
+  * text columns directly and omit this hook (or return `undefined`). `kind` is
+  * the column's effective validator kind.
+  */
+  indexKeyPrefix?: (kind: string | undefined) => number | undefined;
+  /** True when an `error` thrown by a write is a UNIQUE-constraint breach (mapped to a 409 ConflictError). */
+  isUniqueViolation: (error: unknown) => boolean;
+  /** A short engine tag for diagnostics/branching (`"sqlite" | "postgres" | "mysql"`). The store core selects drizzle's matching dialect for rendering off this. */
+  readonly name: "mysql" | "postgres" | "sqlite";
+  /** True when the engine supports `UPDATE/DELETE ... RETURNING` (SQLite/PG yes, MySQL no → use `affectedRows`). */
+  supportsReturning: boolean;
+  /**
+  * The catalog probe for whether a physical `table` exists — backs the opt-in
+  * companion-table (`__agg_`/`__rank_`) existence checks. Returns a drizzle
+  * {@link SQL} (a non-empty result ⇒ the table exists) so it renders through
+  * the same per-engine path as every other statement, never a hand-built
+  * placeholder string. SQLite reads `sqlite_master`; Postgres/MySQL read
+  * `information_schema.tables`.
+  */
+  tableExists: (table: string) => SQL;
+}
+export { SqlDialect, SqlExec, SqlRunResult };

package/dist/dialect.d.ts

@@ -0,0 +1,82 @@
+import { SQL } from 'drizzle-orm';
+/** Outcome of a non-`SELECT` statement: the row count it changed (for MySQL OCC, which lacks `RETURNING`). */
+interface SqlRunResult {
+  /** Rows the statement inserted/updated/deleted. `0` when the engine can't report it. */
+  rowsAffected: number;
+}
+/**
+* The async SQL surface the store core consumes. Satisfied by a
+* `D1Session`/`D1Client` (D1), a `node:sqlite` adapter (tests), or a
+* Hyperdrive-backed `postgres`/`pg`/`mysql2` driver (PlanetScale).
+*
+* `all` runs a row-returning statement (incl. `... RETURNING ...`); `run` runs a
+* write and reports `rowsAffected` — the matched-rows count that drives the
+* MySQL optimistic-concurrency guard (which has no `RETURNING`).
+*
+* Note: companion writes (aggregate/rank/FTS/CDC) run as separate sequential
+* statements after the row write on every engine, so they share D1's
+* at-least-once caveat — there is no cross-statement transaction here.
+*/
+interface SqlExec {
+  all: (sql: string, params: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  run: (sql: string, params: ReadonlyArray<unknown>) => Promise<SqlRunResult>;
+}
+/** Everything engine-specific the store core needs. One value per engine; `sqliteDialect` (in `@lunora/d1`) is the reference, Postgres/MySQL live in `@lunora/hyperdrive/global`. */
+interface SqlDialect {
+  /** Affected-rows extractor for the OCC fallback when `supportsReturning` is false (MySQL). */
+  affectedRows?: (result: SqlRunResult) => number;
+  /**
+  * Storage SQL column type for a validator `kind`. SQLite affinity
+  * (`TEXT`/`INTEGER`/`REAL`/`BLOB`); Postgres `TEXT`/`DOUBLE PRECISION`/
+  * `BOOLEAN`/`JSONB`/`BYTEA`; MySQL `VARCHAR(255)`/`TEXT`/`DOUBLE`/
+  * `TINYINT(1)`/`JSON`/`LONGBLOB`.
+  */
+  columnType: (kind: string | undefined) => string;
+  /**
+  * Engine SQL types for the **internal companion tables** (aggregate / rank /
+  * CDC), which are built from raw SQL types, not validator kinds. SQLite uses
+  * `TEXT`/`REAL`/`INTEGER`/`BLOB` and `INTEGER PRIMARY KEY AUTOINCREMENT`;
+  * Postgres `TEXT`/`DOUBLE PRECISION`/`INTEGER`/`BYTEA` + `BIGSERIAL`; MySQL
+  * needs a bounded `VARCHAR` key, `DOUBLE`, `LONGBLOB`, `AUTO_INCREMENT`.
+  */
+  companionTypes: {
+    autoincrementPrimaryKey: string;
+    integer: string;
+    key: string;
+    real: string;
+    text: string;
+  };
+  /** Map a stored value back to its JS form, by effective validator `kind` (inverse of `encode`). */
+  decode: (value: unknown, kind: string | undefined) => unknown;
+  /** Map a JS value to its bound storage form (boolean→1/0, bigint→string, object→JSON on SQLite; mostly native on PG). */
+  encode: (value: unknown) => unknown;
+  /** The framework columns every global table carries — the `id` primary key and `_creationTime` — as `{ name, type }` so the DDL builder can quote each name through the engine's dialect. */
+  frameworkColumns: () => ReadonlyArray<{
+    name: string;
+    type: string;
+  }>;
+  /**
+  * Optional: the key-prefix length an indexed column of this `kind` needs.
+  * MySQL/InnoDB can't index a `TEXT`/`LONGTEXT`/`BLOB` column without a prefix
+  * (the store appends `(&lt;n>)` to the column reference); SQLite/Postgres index
+  * text columns directly and omit this hook (or return `undefined`). `kind` is
+  * the column's effective validator kind.
+  */
+  indexKeyPrefix?: (kind: string | undefined) => number | undefined;
+  /** True when an `error` thrown by a write is a UNIQUE-constraint breach (mapped to a 409 ConflictError). */
+  isUniqueViolation: (error: unknown) => boolean;
+  /** A short engine tag for diagnostics/branching (`"sqlite" | "postgres" | "mysql"`). The store core selects drizzle's matching dialect for rendering off this. */
+  readonly name: "mysql" | "postgres" | "sqlite";
+  /** True when the engine supports `UPDATE/DELETE ... RETURNING` (SQLite/PG yes, MySQL no → use `affectedRows`). */
+  supportsReturning: boolean;
+  /**
+  * The catalog probe for whether a physical `table` exists — backs the opt-in
+  * companion-table (`__agg_`/`__rank_`) existence checks. Returns a drizzle
+  * {@link SQL} (a non-empty result ⇒ the table exists) so it renders through
+  * the same per-engine path as every other statement, never a hand-built
+  * placeholder string. SQLite reads `sqlite_master`; Postgres/MySQL read
+  * `information_schema.tables`.
+  */
+  tableExists: (table: string) => SQL;
+}
+export { SqlDialect, SqlExec, SqlRunResult };

package/dist/dialect.mjs

@@ -0,0 +1 @@
+

package/dist/index.d.mts

@@ -0,0 +1,174 @@
+import { ServerDefaultContextLike, DatabaseWriterLike, SchedulerLike, SchemaLike, TableDefinitionLike, ValidatorLike } from '@lunora/do';
+import { SqlDialect, SqlRunResult } 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.
+*/
+interface SqlCtxExec {
+  all: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  run: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<SqlRunResult | void>;
+}
+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`).
+  */
+  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.
+  */
+  cdc?: boolean;
+  clock?: () => number;
+  /**
+  * 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"];
+  /**
+  * 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.
+  */
+  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.
+  */
+  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.
+*/
+declare const readSqlCdcChanges: (exec: SqlCtxExec, options: {
+  limit?: number;
+  sinceSeq?: number;
+}, dialect: SqlDialect) => Promise<{
+  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>;
+declare const createSqlCtxDb: (options: SqlCtxDbOptions) => DatabaseWriterLike;
+/** Map a JS value onto its SQLite storage form — SQLite has no boolean, so true/false → 1/0. */
+declare const sqliteEncode: (value: unknown) => 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. */
+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`.
+*/
+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.
+*/
+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 };

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+import { ServerDefaultContextLike, DatabaseWriterLike, SchedulerLike, SchemaLike, TableDefinitionLike, ValidatorLike } from '@lunora/do';
+import { SqlDialect, SqlRunResult } from "./dialect.js";
+export type { SqlExec } from "./dialect.js";
+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.
+*/
+interface SqlCtxExec {
+  all: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  run: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<SqlRunResult | void>;
+}
+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`).
+  */
+  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.
+  */
+  cdc?: boolean;
+  clock?: () => number;
+  /**
+  * 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"];
+  /**
+  * 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.
+  */
+  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.
+  */
+  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.
+*/
+declare const readSqlCdcChanges: (exec: SqlCtxExec, options: {
+  limit?: number;
+  sinceSeq?: number;
+}, dialect: SqlDialect) => Promise<{
+  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>;
+declare const createSqlCtxDb: (options: SqlCtxDbOptions) => DatabaseWriterLike;
+/** Map a JS value onto its SQLite storage form — SQLite has no boolean, so true/false → 1/0. */
+declare const sqliteEncode: (value: unknown) => 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. */
+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`.
+*/
+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.
+*/
+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 };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { createSqlCtxDb, decodeGlobalRow, readSqlCdcChanges, runSqlAggregateMigrations, runSqlCdcMigration, runSqlGlobalTableMigrations, runSqlRankMigrations, runSqlSearchMigrations, trimSqlCdcChanges } from './packem_shared/createSqlCtxDb-BlGq23Wp.mjs';
+export { decodeBigint, effectiveColumnKind, sqliteDecode, sqliteEncode, tryJsonParse } from './packem_shared/decodeBigint-Dedu92k4.mjs';