@lunora/sql-store 1.0.0-alpha.33 → 1.0.0-alpha.34

package/dist/dialect.d.mts

@@ -5,18 +5,18 @@ interface SqlRunResult {
   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.
-*/
+ * 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>;
@@ -26,19 +26,19 @@ 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`.
-  */
+   * 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`.
-  */
+   * 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;
@@ -47,18 +47,18 @@ interface SqlDialect {
     text: string;
   };
   /**
-  * Map a stored value back to its JS form, by effective validator `kind`
-  * (inverse of `encode`). NOTE: currently **unused** by the store core, which
-  * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
-  * seam for a future engine-native codec; an override here does not run today.
-  */
+   * Map a stored value back to its JS form, by effective validator `kind`
+   * (inverse of `encode`). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
+   * seam for a future engine-native codec; an override here does not run today.
+   */
   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). NOTE: currently **unused** by the store core, which
-  * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
-  * the seam for a future engine-native codec; an override here does not run today.
-  */
+   * Map a JS value to its bound storage form (boolean→1/0, bigint→string,
+   * object→JSON on SQLite). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
+   * the seam for a future engine-native codec; an override here does not run today.
+   */
   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<{
@@ -66,12 +66,12 @@ interface SqlDialect {
     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.
-  */
+   * 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;
@@ -80,13 +80,13 @@ interface SqlDialect {
   /** 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`.
-  */
+   * 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

@@ -5,18 +5,18 @@ interface SqlRunResult {
   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.
-*/
+ * 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>;
@@ -26,19 +26,19 @@ 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`.
-  */
+   * 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`.
-  */
+   * 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;
@@ -47,18 +47,18 @@ interface SqlDialect {
     text: string;
   };
   /**
-  * Map a stored value back to its JS form, by effective validator `kind`
-  * (inverse of `encode`). NOTE: currently **unused** by the store core, which
-  * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
-  * seam for a future engine-native codec; an override here does not run today.
-  */
+   * Map a stored value back to its JS form, by effective validator `kind`
+   * (inverse of `encode`). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
+   * seam for a future engine-native codec; an override here does not run today.
+   */
   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). NOTE: currently **unused** by the store core, which
-  * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
-  * the seam for a future engine-native codec; an override here does not run today.
-  */
+   * Map a JS value to its bound storage form (boolean→1/0, bigint→string,
+   * object→JSON on SQLite). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
+   * the seam for a future engine-native codec; an override here does not run today.
+   */
   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<{
@@ -66,12 +66,12 @@ interface SqlDialect {
     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.
-  */
+   * 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;
@@ -80,13 +80,13 @@ interface SqlDialect {
   /** 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`.
-  */
+   * 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/index.d.mts

@@ -3,118 +3,118 @@ 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.
-*/
+ * 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`).
-  */
+   * 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;
   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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-*/
+ * 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`).
-*/
+ * 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`).
-*/
+ * 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`).
-*/
+ * 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 {
@@ -131,9 +131,9 @@ interface CdcChange {
 /** 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.
-*/
+ * 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;
@@ -151,30 +151,30 @@ 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`.
-*/
+ * 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).
-*   CAVEAT: a union/any 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. This is inherent to sharing one TEXT column between a string
-*   and an object member; disambiguating would require a breaking storage-format
-*   change (tagging encoded non-scalars), so it is documented rather than fixed.
-* - 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`.
+ * - `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).
+ *   CAVEAT: a union/any 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. This is inherent to sharing one TEXT column between a string
+ *   and an object member; disambiguating would require a breaking storage-format
+ *   change (tagging encoded non-scalars), 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 };

package/dist/index.d.ts

@@ -3,118 +3,118 @@ 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.
-*/
+ * 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`).
-  */
+   * 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;
   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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-*/
+ * 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`).
-*/
+ * 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`).
-*/
+ * 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`).
-*/
+ * 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 {
@@ -131,9 +131,9 @@ interface CdcChange {
 /** 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.
-*/
+ * 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;
@@ -151,30 +151,30 @@ 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`.
-*/
+ * 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).
-*   CAVEAT: a union/any 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. This is inherent to sharing one TEXT column between a string
-*   and an object member; disambiguating would require a breaking storage-format
-*   change (tagging encoded non-scalars), so it is documented rather than fixed.
-* - 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`.
+ * - `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).
+ *   CAVEAT: a union/any 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. This is inherent to sharing one TEXT column between a string
+ *   and an object member; disambiguating would require a breaking storage-format
+ *   change (tagging encoded non-scalars), 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/sql-store",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.34",
   "description": "Internal dialect-parameterized SQL store core for Lunora .global() backends (D1, PlanetScale)",
   "keywords": [
     "cloudflare",
@@ -50,8 +50,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/do": "1.0.0-alpha.33",
-    "@lunora/errors": "1.0.0-alpha.5",
+    "@lunora/do": "1.0.0-alpha.34",
+    "@lunora/errors": "1.0.0-alpha.6",
     "drizzle-orm": "^0.45.2"
   },
   "engines": {