@lunora/d1 1.0.0-alpha.18 → 1.0.0-alpha.181

package/dist/index.d.mts

@@ -1,6 +1,9 @@
-import { SchemaLike, DatabaseWriterLike } from '@lunora/do';
-import { SqlCtxDbOptions, createSqlCtxDb, SqlCtxExec, readSqlCdcChanges, SqlDialect } from '@lunora/sql-store';
+import { SchemaLike, DatabaseWriterLike } from '@lunora/shard-engine';
+export { applyCdcChanges } from '@lunora/shard-engine';
+import { SqlCtxDbOptions, SqlCtxExec, SqlSearchBackfillResult, createSqlCtxDb, readSqlCdcChanges, SqlDialect } from '@lunora/sql-store';
 export { type SqlCtxExec as D1Exec, type SqlCtxDbOptions, type SqlCtxExec, createSqlCtxDb } from '@lunora/sql-store';
+import { D1DatabaseLike, D1SessionLike, D1PreparedStatementLike } from '@lunora/platform';
+export type { D1DatabaseLike, D1PreparedStatementLike, D1SessionLike } from '@lunora/platform';
 import { BatchItem, BatchResponse } from 'drizzle-orm/batch';
 import { DrizzleD1Database } from 'drizzle-orm/d1';
 /** The D1 store options — the shared store options minus `dialect` (the SQLite dialect is injected for you). */
@@ -9,12 +12,14 @@ type D1ContextDatabaseOptions = Omit<SqlCtxDbOptions, "dialect">;
 declare const createD1ContextDatabase: (options: D1ContextDatabaseOptions) => ReturnType<typeof createSqlCtxDb>;
 /** Auto-provision the schema's `.global()` tables in D1 (idempotent `CREATE TABLE IF NOT EXISTS`). */
 declare const runD1GlobalTableMigrations: (exec: SqlCtxExec, schema: SchemaLike) => Promise<void>;
-/** Materialize the `__agg_&lt;index>` companion tables for the schema's aggregate indexes. */
+/** Materialize the `__agg_<index>` companion tables for the schema's aggregate indexes. */
 declare const runD1AggregateMigrations: (exec: SqlCtxExec, schema: SchemaLike) => Promise<void>;
-/** Materialize the `__rank_&lt;index>` companion tables for the schema's rank indexes. */
+/** Materialize the `__rank_<index>` companion tables for the schema's rank indexes. */
 declare const runD1RankMigrations: (exec: SqlCtxExec, schema: SchemaLike) => Promise<void>;
-/** Materialize the `__fts_&lt;index>` fts5 shadow tables for the schema's search indexes (no-op without fts5). */
+/** Materialize (and backfill) the `__fts_<index>` fts5 shadow tables for the schema's search indexes. */
 declare const runD1SearchMigrations: (exec: SqlCtxExec, schema: SchemaLike) => Promise<void>;
+/** Index existing rows into every search companion, including the `staged: true` ones migrations leave empty. */
+declare const backfillD1SearchIndexes: (exec: SqlCtxExec, schema: SchemaLike) => Promise<SqlSearchBackfillResult>;
 /** Create the `__cdc_log` table in D1 (idempotent; only run when CDC is enabled). */
 declare const runD1CdcMigration: (exec: SqlCtxExec) => Promise<void>;
 /** Read changelog entries newer than `sinceSeq` in commit order. */
@@ -22,11 +27,30 @@ declare const readD1CdcChanges: (exec: SqlCtxExec, options?: {
   limit?: number;
   sinceSeq?: number;
 }) => ReturnType<typeof readSqlCdcChanges>;
-/** Drop changelog entries at or below a checkpointed `throughSeq`. */
-declare const trimD1CdcChanges: (exec: SqlCtxExec, throughSeq: number) => Promise<void>;
+/**
+ * Delete `.global()` changelog entries older than `retentionMs`, if this writer
+ * wins the fleet's sweep lease. See `sweepSqlCdcRetention`.
+ *
+ * Replaces the seq-based `trimD1CdcChanges`, which took a checkpoint no caller
+ * could compute: the log is shared across every shard and region, so no single
+ * caller knows a `seq` that is safe for all of them. A time window is a bound
+ * they can all reason about, and the lease is what stops them racing.
+ */
+declare const sweepD1CdcRetention: (exec: SqlCtxExec, retentionMs: number, now: number) => Promise<void>;
 /** One exported row: `doc` is reconstructed from the column tuple. */
 interface ExportRow {
   doc: Record<string, unknown>;
+  /**
+   * True physical source line, when the caller has it (e.g. a global row
+   * pulled out of an interspersed NDJSON import stream by
+   * `@lunora/runtime`'s `import-stream.ts`). When present this overrides the
+   * position-derived line below — the caller-side positions of a
+   * global-only subset don't line up with the original file once
+   * non-global rows have been filtered out. Absent for callers with no
+   * physical source to attribute (e.g. a fresh `exportGlobalRows` roundtrip
+   * in tests), which keeps the positional fallback.
+   */
+  line?: number;
   table: string;
 }
 interface ImportError {
@@ -42,32 +66,42 @@ interface ImportResult {
   inserted: Record<string, number>;
 }
 /**
-* Return every `.global()` table in the schema, optionally narrowed by an
-* allowlist. Shard-local tables are skipped here — they're handled by the DO
-* helpers — so callers get a clean separation between the two storage planes.
-*/
+ * Return every `.global()` table in the schema, optionally narrowed by an
+ * allowlist. Shard-local tables are skipped here — they're handled by the DO
+ * helpers — so callers get a clean separation between the two storage planes.
+ */
 declare const selectGlobalTables: (schema: SchemaLike, requested?: ReadonlyArray<string>) => string[];
 interface ExportGlobalArgs {
   batchSize?: number;
   tables?: ReadonlyArray<string>;
 }
 /**
-* Yield rows from every requested `.global()` table in batches. Uses
-* `LIMIT ?/OFFSET ?` because D1 globals don't have a stable keyset abstraction
-* here (the writer's `findMany` does, but at the cost of routing through the
-* full validator pipeline; for a snapshot stream a plain offset scan is
-* sufficient and predictable).
-*/
+ * Yield rows from every requested `.global()` table in batches.
+ *
+ * Keyset-paginates on the physical primary key (`id` — every `.global()` table
+ * carries it, see `frameworkColumnDdl`): `WHERE "id" > ? ORDER BY "id" LIMIT ?`,
+ * carrying the last id forward. A plain `LIMIT/OFFSET` scan would be wrong here —
+ * SQLite gives no ordering guarantee for an unordered SELECT and each page is a
+ * separate query, so pages could overlap or skip rows (and any concurrent
+ * insert/delete would shift offsets and silently drop/duplicate rows in the
+ * snapshot). Keyset paging is deterministic under concurrent writes and avoids
+ * O(n^2) OFFSET scans on large tables.
+ *
+ * Tables are provisioned first (idempotent `CREATE … IF NOT EXISTS`): `.global()`
+ * tables are created lazily on first write, so a fresh deployment — or any table
+ * never written — would otherwise abort the stream with a raw `no such table`
+ * instead of exporting it as empty.
+ */
 declare const exportGlobalRows: (exec: SqlCtxExec, schema: SchemaLike, args: ExportGlobalArgs) => AsyncGenerator<ExportRow, void, undefined>;
 interface ImportGlobalArgs {
   /**
-  * Optional direct exec handle to the same D1 database the writer targets.
-  * When supplied, the conflict pre-probe issues a single
-  * `SELECT 1 FROM &lt;table> WHERE id = ? LIMIT 1` against the row's declared
-  * table instead of falling back to `writer.get(id)`, which scans every
-  * global table looking for the id. Strongly recommended for large schemas
-  * — the writer-fallback is O(N tables) per row.
-  */
+   * Optional direct exec handle to the same D1 database the writer targets.
+   * When supplied, the conflict pre-probe issues a single
+   * `SELECT 1 FROM <table> WHERE id = ? LIMIT 1` against the row's declared
+   * table instead of falling back to `writer.get(id)`, which scans every
+   * global table looking for the id. Strongly recommended for large schemas
+   * — the writer-fallback is O(N tables) per row.
+   */
   exec?: D1ExecLike;
   rows: ReadonlyArray<ExportRow>;
   startLine?: number;
@@ -77,121 +111,129 @@ interface D1ExecLike {
   all: (sql: string, parameters: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
 }
 /**
-* Import rows into `.global()` tables via the schema-aware D1 writer. The
-* writer rejects unknown ids on `insert` (the writer assigns one when `_id` is
-* absent); we pre-probe each row's `_id` so a collision is reported as a
-* conflict instead of bubbled as a UNIQUE error. Schema-failed rows surface in
-* `errors`; the rest land.
-*/
+ * Import rows into `.global()` tables via the schema-aware D1 writer. The
+ * writer rejects unknown ids on `insert` (the writer assigns one when `_id` is
+ * absent); we pre-probe each row's `_id` so a collision is reported as a
+ * conflict instead of bubbled as a UNIQUE error. Schema-failed rows surface in
+ * `errors`; the rest land.
+ */
 declare const importGlobalRows: (writer: DatabaseWriterLike, schema: SchemaLike, args: ImportGlobalArgs) => Promise<ImportResult>;
 /**
-* Minimal structural projection of `D1Database` to keep the adapter
-* compatible with the real workers-types value as well as unit-test doubles.
-*/
-interface D1DatabaseLike {
-  batch?: (statements: D1PreparedStatementLike[]) => Promise<unknown[]>;
-  exec?: (sql: string) => Promise<unknown>;
-  prepare: (sql: string) => D1PreparedStatementLike;
-  withSession: (bookmark?: string) => D1SessionLike;
-}
-interface D1SessionLike {
-  batch?: (statements: D1PreparedStatementLike[]) => Promise<unknown[]>;
-  getBookmark: () => string | null;
-  prepare: (sql: string) => D1PreparedStatementLike;
-}
-interface D1PreparedStatementLike {
-  all: <T = unknown>() => Promise<{
-    results: T[];
-    success: boolean;
-  }>;
-  bind: (...values: unknown[]) => D1PreparedStatementLike;
-  first: <T = unknown>(column?: string) => Promise<T | null>;
-  raw: <T = unknown>() => Promise<T[][]>;
-  run: <T = unknown>() => Promise<{
-    meta?: Record<string, unknown>;
-    results?: T[];
-    success: boolean;
-  }>;
-}
-/** Thin wrapper over a `D1DatabaseSession` exposing bookmark plumbing. */
+ * Thin wrapper over a `D1DatabaseSession` exposing bookmark plumbing.
+ *
+ * `all` and `first` retry D1's expected transient failures — but only for a
+ * statement that is provably read-only. D1 produces a documented
+ * baseline of infrastructural errors even when healthy (Cloudflare's team calls
+ * a handful every few hours "not unexpected") and their guidance is to retry;
+ * a client that does not has adopted that error rate as the application's own.
+ *
+ * Nothing else on this class or on {@link D1Client} retries. `run` is the write
+ * path, and every transient D1 error is ambiguous about whether the statement
+ * applied — re-running a non-idempotent write after a lost response
+ * double-applies it. `all` is not a read path either: D1 runs
+ * `UPDATE … RETURNING` through it, so the retry is gated on the statement's
+ * leading keyword rather than on the method name. Wrap a genuinely idempotent
+ * write in {@link withD1Retry} yourself, per call.
+ */
 declare class D1Session {
   private readonly session;
   /** See {@link D1Client.stmtCache}. Scoped per session. */
   private readonly stmtCache;
   constructor(session: D1SessionLike);
   prepare(sql: string): D1PreparedStatementLike;
+  /**
+   * Execute a statement. **Not retried** — `run` is the write path, and a
+   * transient D1 error does not say whether the write applied.
+   */
   run<T = unknown>(sql: string, ...binds: unknown[]): Promise<{
     meta?: Record<string, unknown>;
     results?: T[];
     success: boolean;
   }>;
+  /**
+   * Read all rows, retrying D1's transient failures when `sql` is a
+   * read-only statement. An `UPDATE … RETURNING` runs through here too and is
+   * left unretried.
+   */
   all<T = unknown>(sql: string, ...binds: unknown[]): Promise<{
+    meta?: Record<string, unknown>;
     results: T[];
     success: boolean;
   }>;
+  /** Read the first row, retrying under the same read-only rule as {@link all}. */
   first<T = unknown>(sql: string, ...binds: unknown[]): Promise<T | null>;
   /**
-  * Returns the most recent bookmark known to the session, or `undefined`
-  * when D1 has not issued one yet.
-  */
+   * Returns the most recent bookmark known to the session, or `undefined`
+   * when D1 has not issued one yet.
+   */
   getBookmark(): string | undefined;
 }
+/**
+ * A D1 handle: prepared-statement caching, Sessions-API sessions, and the
+ * drizzle-typed accessors.
+ *
+ * **Nothing on this class retries.** `prepare`, `drizzle`, `drizzleSession`,
+ * `batch` and `raw` all hand back the underlying D1 surface untouched. The
+ * automatic retry lives on {@link D1Session.all} / {@link D1Session.first} and
+ * on `retryingExec` (the seam `.global()` tables read through); wrap anything
+ * else in {@link withD1Retry} yourself, and only when it is safe to run twice.
+ */
 declare class D1Client {
   private readonly db;
   /**
-  * SQL string -> prepared statement. Prepared statements are reusable in
-  * D1; preparing the same SQL twice forces the worker to round-trip the
-  * statement plan. Caching is per-instance so unit-test isolation holds.
-  * Bounded to {@link STMT_CACHE_CAPACITY} via LRU eviction.
-  */
+   * SQL string -> prepared statement. Prepared statements are reusable in
+   * D1; preparing the same SQL twice forces the worker to round-trip the
+   * statement plan. Caching is per-instance so unit-test isolation holds.
+   * Bounded to {@link STMT_CACHE_CAPACITY} via LRU eviction.
+   */
   private readonly stmtCache;
   /**
-  * Lazily-built drizzle handle over the bare binding. Memoised so a single
-  * `D1Client` reuses the same dialect/session machinery across calls.
-  */
+   * Lazily-built drizzle handle over the bare binding. Memoised so a single
+   * `D1Client` reuses the same dialect/session machinery across calls.
+   */
   private drizzleHandle;
   constructor(database: D1DatabaseLike);
   /**
-  * Open a Sessions-API scoped session. Pass the bookmark forwarded by
-  * the client to opt into read-your-writes consistency.
-  *
-  * With no bookmark this is the first request of a session — there is no
-  * prior write to read, so we open with the explicit `"first-unconstrained"`
-  * constraint (Cloudflare's lowest-latency default: the first read may serve
-  * from any replica). Read-your-writes for sequenced requests still flows
-  * through the forwarded bookmark; a caller needing a strongly-consistent
-  * very-first read should pass `"first-primary"` as the bookmark instead.
-  */
+   * Open a Sessions-API scoped session. Pass the bookmark forwarded by
+   * the client to opt into read-your-writes consistency.
+   *
+   * With no bookmark this is the first request of a session — there is no
+   * prior write to read, so we open with the explicit `"first-unconstrained"`
+   * constraint (Cloudflare's lowest-latency default: the first read may serve
+   * from any replica). Read-your-writes for sequenced requests still flows
+   * through the forwarded bookmark; a caller needing a strongly-consistent
+   * very-first read should pass `"first-primary"` as the bookmark instead.
+   */
   withSession(bookmark?: string): D1Session;
   /**
-  * Prepare a statement, reusing a cached one when the SQL text matches.
-  * `bind()` on a prepared statement returns a new bound statement and
-  * leaves the underlying prepared plan reusable, so cache hits are safe
-  * even when the previous caller already called `.bind(...).run()`.
-  */
+   * Prepare a statement, reusing a cached one when the SQL text matches.
+   * `bind()` on a prepared statement returns a new bound statement and
+   * leaves the underlying prepared plan reusable, so cache hits are safe
+   * even when the previous caller already called `.bind(...).run()`.
+   */
   prepare(sql: string): D1PreparedStatementLike;
   /**
-  * Drizzle handle over the bare `env.DB` binding. Used for typed queries
-  * against generated `sqliteTable` schemas; does **not** participate in the
-  * D1 Sessions API (no bookmark pinning). For bookmark-scoped reads, use
-  * {@link drizzleSession} instead.
-  */
+   * Drizzle handle over the bare `env.DB` binding. Used for typed queries
+   * against generated `sqliteTable` schemas; does **not** participate in the
+   * D1 Sessions API (no bookmark pinning). For bookmark-scoped reads, use
+   * {@link drizzleSession} instead.
+   */
   get drizzle(): DrizzleD1Database<Record<string, unknown>>;
   /**
-  * Drizzle handle scoped to a D1 Sessions-API session. The bookmark, when
-  * supplied, opts into read-your-writes consistency for follow-up reads on
-  * the same session.
-  *
-  * A `D1DatabaseSession` exposes the same `prepare` / `batch` surface
-  * drizzle calls into, so a single `unknown` cast lets us treat the session
-  * as a `D1Database` for driver-construction purposes.
-  */
+   * Drizzle handle scoped to a D1 Sessions-API session. The bookmark, when
+   * supplied, opts into read-your-writes consistency for follow-up reads on
+   * the same session.
+   *
+   * A `D1DatabaseSession` exposes the same `prepare` / `batch` surface
+   * drizzle calls into, so a single `unknown` cast lets us hand the session to
+   * the driver.
+   */
   drizzleSession(bookmark?: string): DrizzleD1Database<Record<string, unknown>>;
   /**
-  * Atomic batch over the drizzle d1 driver. Mirrors `db.batch([...])`
-  * exactly; exposed on the client so callers don't need to hold a drizzle
-  * handle just to run a typed batch.
-  */
+   * Atomic batch over the drizzle d1 driver. Mirrors `db.batch([...])`
+   * exactly; exposed on the client so callers don't need to hold a drizzle
+   * handle just to run a typed batch.
+   */
   batch<U extends BatchItem<"sqlite">, T extends Readonly<[U, ...U[]]>>(items: T): Promise<BatchResponse<T>>;
   /** Direct access to the underlying binding (advanced use only). */
   get raw(): D1DatabaseLike;
@@ -205,24 +247,26 @@ interface GlobalTableInfo {
 interface GlobalTablePage {
   columns: string[];
   /**
-  * Foreign-key columns (local column → referenced table) for tables that carry
-  * real SQL `REFERENCES` constraints — recovered from `PRAGMA foreign_key_list`.
-  * Schema `.global()` tables omit this (their refs come from `describeTables`);
-  * external tables (e.g. better-auth's `session`/`twoFactor`) expose it so the
-  * schema diagram can draw their global→global FK edges.
-  */
+   * Foreign-key columns (local column → referenced table) for tables that carry
+   * real SQL `REFERENCES` constraints — recovered from `PRAGMA foreign_key_list`.
+   * Schema `.global()` tables omit this (their refs come from `describeTables`);
+   * external tables (e.g. better-auth's `session`/`twoFactor`) expose it so the
+   * schema diagram can draw their global→global FK edges.
+   */
   refs?: Record<string, string>;
   rows: Record<string, unknown>[];
   total: number;
 }
 /**
-* One equality constraint a facet-value click adds to the global browser's view:
-* `column = value` (or `column IS NULL` when `value` is nullish). `column` is a
-* displayed column name, validated against the table's columns and mapped to its
-* physical column (`_id` → `id`) before it is quoted; `value` is the **raw stored
-* value** the facet returned (a SQLite scalar), bound as a parameter and never
-* interpolated. AND-combined with the other clauses.
-*/
+ * One equality constraint a facet-value click adds to the global browser's view:
+ * `column = value` (or `column IS NULL` when `value` is nullish). `column` is a
+ * displayed column name, validated against the table's columns and mapped to its
+ * physical column (`_id` → `id`) before it is quoted; `value` is the **raw stored
+ * value** the facet returned (a SQLite scalar — including a BLOB, which reaches
+ * here as bytes because the facet payload is wire-encoded), normalised by
+ * {@link sqliteEncode} and bound as a parameter, never interpolated.
+ * AND-combined with the other clauses.
+ */
 interface GlobalFilterClause {
   column: string;
   value: unknown;
@@ -234,13 +278,13 @@ interface ReadGlobalTablePageOptions {
   table: string;
 }
 /**
-* Options for {@link facetGlobalColumn} — the read-only "what values does this
-* column hold?" summary for the global (D1) browser. `column` is the displayed
-* column to group by (validated and mapped to its physical column, never
-* interpolated); `filters` mirrors {@link ReadGlobalTablePageOptions}'s eq
-* constraints so the facet reflects the **active view** (the same rows the
-* browser is previewing); `limit` caps the distinct values returned (clamped).
-*/
+ * Options for {@link facetGlobalColumn} — the read-only "what values does this
+ * column hold?" summary for the global (D1) browser. `column` is the displayed
+ * column to group by (validated and mapped to its physical column, never
+ * interpolated); `filters` mirrors {@link ReadGlobalTablePageOptions}'s eq
+ * constraints so the facet reflects the **active view** (the same rows the
+ * browser is previewing); `limit` caps the distinct values returned (clamped).
+ */
 interface FacetGlobalColumnOptions {
   column: string;
   filters?: GlobalFilterClause[];
@@ -253,43 +297,49 @@ interface GlobalFacetValue {
   value: unknown;
 }
 /**
-* Payload of a {@link facetGlobalColumn} call: the top-N distinct `values` (each
-* with a `count`) ordered by frequency, plus `truncated` — `true` when more
-* distinct values existed beyond the cap, so the UI can say so rather than imply
-* the list is exhaustive. Mirrors the shard browser's `FacetColumnResult`.
-*/
+ * Payload of a {@link facetGlobalColumn} call: the top-N distinct `values` (each
+ * with a `count`) ordered by frequency, plus `truncated` — `true` when more
+ * distinct values existed beyond the cap, so the UI can say so rather than imply
+ * the list is exhaustive. Mirrors the shard browser's `FacetColumnResult`.
+ */
 interface GlobalFacetResult {
   truncated: boolean;
   values: GlobalFacetValue[];
 }
 /**
-* List every browsable D1 table with its row count, ordered by name. Surfaces
-* both the schema's `.global()` tables (provisioned first) and external tables
-* (auth, etc.); internal/companion tables are excluded.
-*/
+ * List every browsable D1 table with its row count, ordered by name. Surfaces
+ * both the schema's `.global()` tables (provisioned first) and external tables
+ * (auth, etc.); internal/companion tables are excluded.
+ */
 declare const listGlobalTables: (exec: SqlCtxExec, schema: SchemaLike) => Promise<GlobalTableInfo[]>;
 /**
-* Read a page of rows from one D1 table. The table is validated against the live
-* browsable-table list before its name is interpolated, so this can't be coerced
-* into reading an internal table or injecting SQL. `limit` is clamped to
-* `[1, 500]`; `offset` floors at `0`. `filters` AND-narrows the page to rows
-* matching each `column = value` eq constraint (a facet-value drill-down), bound
-* through {@link buildEqPredicate} so they never inject SQL.
-*/
+ * Read a page of rows from one D1 table. The table is validated against the live
+ * browsable-table list before its name is interpolated, so this can't be coerced
+ * into reading an internal table or injecting SQL. `limit` is clamped to
+ * `[1, 500]`; `offset` floors at `0`. `filters` AND-narrows the page to rows
+ * matching each `column = value` eq constraint (a facet-value drill-down), bound
+ * through {@link buildEqPredicate} so they never inject SQL.
+ */
 declare const readGlobalTablePage: (exec: SqlCtxExec, schema: SchemaLike, options: ReadGlobalTablePageOptions) => Promise<GlobalTablePage>;
 /**
-* Summarise the distinct values of one displayed column over the **active view**
-* (the same eq `filters` the global browser is previewing) — the D1 twin of the
-* shard browser's `facetColumn`. Read-only: a `SELECT col AS value, COUNT(*) AS
-* count … GROUP BY col ORDER BY count DESC LIMIT N+1`, with the column validated
-* against the table's displayed columns (typed 404 if unknown), mapped to its
-* physical column, and quoted — never interpolated from caller input. The extra
-* over-fetched row is dropped and surfaced as `truncated`. A sensitive column on
-* an external (non-schema) table is never grouped — it collapses to a single
-* redacted `•••` bucket — mirroring the page browser's value redaction so the
-* facet can't leak credentials. The returned `value` is the raw stored scalar, so
-* a click feeds it straight back as an eq filter.
-*/
+ * Summarise the distinct values of one displayed column over the **active view**
+ * (the same eq `filters` the global browser is previewing) — the D1 twin of the
+ * shard browser's `facetColumn`. Read-only: a `SELECT col AS value, COUNT(*) AS
+ * count … GROUP BY col ORDER BY count DESC LIMIT N+1`, with the column validated
+ * against the table's displayed columns (typed 404 if unknown), mapped to its
+ * physical column, and quoted — never interpolated from caller input. The extra
+ * over-fetched row is dropped and surfaced as `truncated`. A sensitive column on
+ * an external (non-schema) table is never grouped — it collapses to a single
+ * redacted `•••` bucket — mirroring the page browser's value redaction so the
+ * facet can't leak credentials. The returned `value` is the raw stored scalar, so
+ * a click feeds it straight back as an eq filter.
+ *
+ * The payload is wire-encoded on the way out, like the page read's rows: a BLOB
+ * column's stored value is bytes, and `Response.json` flattens those to `{}` —
+ * which is not a display glitch but a broken drill-down, since the flattened
+ * value is what the click sends back as the filter. `needsWireEncoding` leaves a
+ * facet over an ordinary text/numeric column untouched.
+ */
 declare const facetGlobalColumn: (exec: SqlCtxExec, schema: SchemaLike, options: FacetGlobalColumnOptions) => Promise<GlobalFacetResult>;
 interface Migration {
   /** Human-readable name, e.g. `001_init` (used in logs). */
@@ -310,30 +360,171 @@ interface MigrationRunnerResult {
   }[];
 }
 /**
-* Sequentially applies pending migrations against a D1 database via the
-* drizzle-orm/d1 driver. Each migration is hashed (SHA-256 over its SQL
-* text); the hash is stored in `__drizzle_migrations`, so re-applying the
-* same SQL under a different `version` is rejected and identical migrations
-* are skipped idempotently.
-*/
+ * Sequentially applies pending migrations against a D1 database via the
+ * drizzle-orm/d1 driver, recording each one's `version` and SHA-256 in
+ * `__drizzle_migrations`.
+ *
+ * A migration is skipped when its VERSION is recorded, never by its text alone.
+ * Deduplicating by hash re-applied any migration whose text changed after it
+ * ran — a comment, a whitespace fix, a CRLF checkout — so a non-idempotent one
+ * (`SET balance = balance * 100`) ran twice. A recorded version whose hash no
+ * longer matches is refused as `MIGRATION_DRIFT` instead: the runner cannot
+ * tell a harmless edit from a changed migration, and running either again is
+ * the one outcome that is never right.
+ */
 declare class MigrationRunner {
   private readonly client;
   private readonly migrations;
   /**
-  * Accepts either a {@link D1Client} (preferred — gets typed batches +
-  * drizzle handle for free) or a raw `D1DatabaseLike` binding (wrapped on
-  * the caller's behalf so existing `@lunora/cli` callers keep working).
-  */
+   * Accepts either a {@link D1Client} (preferred — gets typed batches +
+   * drizzle handle for free) or a raw `D1DatabaseLike` binding (wrapped on
+   * the caller's behalf so existing `@lunora/cli` callers keep working).
+   */
   constructor(database: D1Client | D1DatabaseLike, migrations: Migration[]);
   run(): Promise<MigrationRunnerResult>;
+  /** Does the tracking table carry the `version` column yet? One catalog read. */
+  private hasVersionColumn;
+  /**
+   * Create the tracking table, or bring one written before `version` existed
+   * up to the current shape.
+   *
+   * Two runners can upgrade the same table at once (parallel deploys): both
+   * see no column, and the second `ADD COLUMN` fails with "duplicate column
+   * name". That failure is only accepted once a re-read shows the column
+   * really is there — any other failure of the `ALTER` still surfaces.
+   */
+  private ensureTrackingTable;
+  /**
+   * Read the tracking rows, first giving every row recorded before versions
+   * were tracked the version whose SQL it hashed — the only link to a version
+   * such a row has. A row whose hash matches no current migration stays
+   * unversioned, and {@link run} refuses to guess around it.
+   */
+  private readTrackingRows;
   private applyOne;
   private assertUniqueVersions;
   private assertUniqueSql;
 }
 /**
-* The canonical SQLite dialect: column affinities, the shared SQLite value
-* codec, `RETURNING` support (both D1 and `node:sqlite`), and `sqlite_master`
-* table probing. The rest of the per-statement shaping is drizzle's.
-*/
+ * Derive a low-cardinality tag for a rendered statement — `select:users`,
+ * `insert:orders`, `select:unknown` when no table token is recognisable.
+ *
+ * Cardinality is the whole design constraint. The rendered SQL is unique per
+ * shape and near-unique per call site, so grouping on it produces a tag space
+ * that grows without bound and answers nothing; verb + table is the coarsest
+ * label that still points at a specific culprit.
+ */
+declare const d1QueryTag: (sql: string) => string;
+/** One statement's cost, read off D1's `meta`. */
+interface D1QueryCost {
+  /** D1's own server-side duration in ms, when reported. */
+  durationMs?: number;
+  /** Rows D1 SCANNED — the billed number, and the one a missing index inflates. */
+  rowsRead: number;
+  /** Rows written by a DML statement; `0` for reads. */
+  rowsWritten: number;
+}
+/**
+ * Project D1's `meta` onto {@link D1QueryCost}, or `undefined` when the result
+ * carried no usable accounting — a test double, or a `batch()` leg that reports
+ * none. Callers skip the emit entirely in that case rather than logging zeroes,
+ * which would read as "this query was free".
+ */
+declare const readD1QueryCost: (meta: Record<string, unknown> | undefined) => D1QueryCost | undefined;
+/**
+ * Emit one structured cost event per D1 statement into Workers Logs, so
+ * "D1 reads spiked" resolves to a tag by group-by.
+ *
+ * Best-effort by contract, exactly like the request-log emit: a serialization
+ * hiccup must never turn a served query into a failed one, so the caller wraps
+ * this and swallows. Emitting one line per D1 statement is proportionate —
+ * every one of them is already a network round trip, so the line is noise-free
+ * next to the work it describes.
+ *
+ * The SQL text itself is NEVER emitted: it carries inlined literals on some
+ * render paths, and the tag is the groupable thing anyway.
+ */
+declare const emitD1QueryCost: (sql: string, meta: Record<string, unknown> | undefined) => void;
+/** Tuning for {@link withD1Retry}. */
+interface D1RetryOptions {
+  /** Total attempts including the first. Default 3. Must be >= 1. */
+  attempts?: number;
+  /**
+   * Total budget across every attempt and backoff, in ms. An attempt still
+   * running when the budget expires is abandoned, and a backoff never sleeps
+   * past it.
+   *
+   * `timeoutMs` bounds one attempt; this bounds the operation.
+   */
+  deadlineMs?: number;
+  /** Sleep implementation. Injected so tests need no timers. */
+  sleep?: (ms: number) => Promise<void>;
+  /**
+   * Abandon a single attempt that has not settled within this many ms, and
+   * treat it as a transient failure.
+   *
+   * There is no default — a legitimate analytical query and a stalled one
+   * look identical from outside, so the value has to come from what your
+   * workload actually needs. Unset, {@link SLOW_FAILURE_MS} stops a slow
+   * failure from being retried rather than guessing a bound for you.
+   *
+   * Only ever applied to operations that are safe to abandon. It does not
+   * cancel the underlying D1 call.
+   */
+  timeoutMs?: number;
+}
+/**
+ * True when `error` looks like one of D1's expected transient failures.
+ *
+ * Deliberately conservative: an unrecognised error is treated as **permanent**
+ * and surfaces immediately. Retrying a genuine bug — a syntax error, a
+ * constraint violation — turns one fast failure into three slow ones and
+ * hides the cause.
+ */
+declare const isTransientD1Error: (error: unknown) => boolean;
+/**
+ * Thrown when an attempt is abandoned for exceeding
+ * {@link D1RetryOptions.timeoutMs}.
+ *
+ * Its own class so a caller can tell "D1 hung" apart from "D1 returned an
+ * error" — they have different remedies, and collapsing them hides which one
+ * is happening.
+ */
+declare class D1TimeoutError extends Error {
+  /** Milliseconds waited before the attempt was abandoned. */
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number);
+}
+/**
+ * Run `operation`, retrying D1's transient failures with exponential backoff
+ * and jitter.
+ *
+ * **Only wrap operations that are safe to run more than once.** Reads always
+ * are. A write is only if it is idempotent — an upsert keyed on a primary key,
+ * a delete by id, an `INSERT OR IGNORE`. A bare `INSERT` or a relative
+ * `UPDATE` is not, and re-running one after a lost response double-applies it.
+ */
+declare const withD1Retry: <T>(operation: () => Promise<T>, options?: D1RetryOptions) => Promise<T>;
+/**
+ * Wrap a `.global()` exec so its **read-only** statements retry D1's transient
+ * failures.
+ *
+ * This is where the retry has to live to reach an application: `.global()`
+ * tables run every read through the exec codegen builds over the raw D1
+ * binding, not through a `D1Client`. `run` and `batch` are passed straight
+ * through — they are the write path, and a transient D1 error does not say
+ * whether the write applied.
+ *
+ * `all` is not the read path either. It only retries when
+ * {@link isReadOnlyD1Sql} proves the statement is one, because `UPDATE …
+ * RETURNING` runs through `all` too.
+ */
+declare const retryingExec: (exec: SqlCtxExec, options?: D1RetryOptions) => SqlCtxExec;
+/**
+ * The canonical SQLite dialect: column affinities, `RETURNING` support (both D1
+ * and `node:sqlite`), and `sqlite_master` table probing. The rest of the
+ * per-statement shaping is drizzle's. The value codec is NOT a dialect member —
+ * the store core runs `sqliteEncode`/`sqliteDecode` on every engine.
+ */
 declare const sqliteDialect: SqlDialect;
-export { D1Client, type D1ContextDatabaseOptions as D1CtxDbOptions, type D1DatabaseLike, type D1PreparedStatementLike, D1Session, type D1SessionLike, type ExportGlobalArgs, type FacetGlobalColumnOptions, type ExportRow as GlobalExportRow, type GlobalFacetResult, type GlobalFacetValue, type GlobalFilterClause, type ImportError as GlobalImportError, type ImportResult as GlobalImportResult, type GlobalTableInfo, type GlobalTablePage, type ImportGlobalArgs, type Migration, MigrationRunner, type MigrationRunnerResult, type ReadGlobalTablePageOptions, createD1ContextDatabase as createD1CtxDb, exportGlobalRows, facetGlobalColumn, importGlobalRows, listGlobalTables, readD1CdcChanges, readGlobalTablePage, runD1AggregateMigrations, runD1CdcMigration, runD1GlobalTableMigrations, runD1RankMigrations, runD1SearchMigrations, selectGlobalTables, sqliteDialect, trimD1CdcChanges };
+export { D1Client, type D1ContextDatabaseOptions as D1CtxDbOptions, type D1QueryCost, type D1RetryOptions, D1Session, D1TimeoutError, type ExportGlobalArgs, type FacetGlobalColumnOptions, type ExportRow as GlobalExportRow, type GlobalFacetResult, type GlobalFacetValue, type GlobalFilterClause, type ImportError as GlobalImportError, type ImportResult as GlobalImportResult, type GlobalTableInfo, type GlobalTablePage, type ImportGlobalArgs, type Migration, MigrationRunner, type MigrationRunnerResult, type ReadGlobalTablePageOptions, backfillD1SearchIndexes, createD1ContextDatabase as createD1CtxDb, d1QueryTag, emitD1QueryCost, exportGlobalRows, facetGlobalColumn, importGlobalRows, isTransientD1Error, listGlobalTables, readD1CdcChanges, readD1QueryCost, readGlobalTablePage, retryingExec, runD1AggregateMigrations, runD1CdcMigration, runD1GlobalTableMigrations, runD1RankMigrations, runD1SearchMigrations, selectGlobalTables, sqliteDialect, sweepD1CdcRetention, withD1Retry };