@bitcobblers/wod-wiki-storage 0.35.2116 → 0.35.2119

package/dist/sql/index.d.cts

@@ -1,5 +1,5 @@
 import { Client } from '@libsql/client';
-import { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, E as TxOp, I as IStorage, S as StoreName, b as IReadOnlyStore, c as StoreType, d as IReadWriteStore, D as DomainQuery, f as IStorageTransaction } from '../wire-C7ZtlBKe.cjs';
+import { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, T as TxOp, I as IStorage, S as StoreName, b as IReadOnlyStore, c as StoreType, d as IReadWriteStore, D as DomainQuery, f as IStorageTransaction } from '../wire-CiFcjo6_.cjs';
 import '@bitcobblers/wod-wiki-core';
 import '@bitcobblers/wod-wiki-lang';
 
@@ -30,9 +30,14 @@ declare class StorageError extends Error {
 
 type SqlValue = string | number | null;
 type SqlRow = Record<string, unknown>;
+interface SqlStatement {
+    sql: string;
+    params?: SqlValue[];
+}
 interface SqlConnection {
     query(sql: string, params?: SqlValue[]): Promise<SqlRow[]>;
     exec(sql: string, params?: SqlValue[]): Promise<void>;
+    batch?(statements: SqlStatement[]): Promise<SqlRow[][]>;
 }
 interface Database extends SqlConnection {
     readonly dialect: 'sqlite' | 'postgres';
@@ -57,8 +62,6 @@ declare function libsqlDatabase(client: LibsqlClient): Database;
  * is typed `ArrayBuffer | string`; strings pass through, and only the exact
  * two-key tag revives.
  */
-/** Serialize a row; when `binaryField` is set and holds an ArrayBuffer, it is
- * replaced by the lossless tag (shallow copy — the input row is untouched). */
 declare function encodeRowJson(value: unknown, binaryField?: string): string;
 /** Parse a row; when `binaryField` is set, a tagged value there revives as an
  * ArrayBuffer. Every other value — including tag-shaped data in other fields
@@ -76,55 +79,34 @@ declare function decodeRowJson<T = unknown>(text: string, binaryField?: string):
 declare const SCHEMA_TABLE = "_wodwiki_schema";
 declare function storeDefinition(name: string): StoreDef;
 declare function getRow(conn: SqlConnection, def: StoreDef, key: KeyDTO): Promise<unknown | undefined>;
+declare function getRows(conn: SqlConnection, def: StoreDef, keys: KeyDTO[]): Promise<(unknown | undefined)[]>;
+declare function listRowsFromIndexMany(conn: SqlConnection, def: StoreDef, indexName: string, keys: KeyDTO[]): Promise<unknown[][]>;
 declare function listRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, count?: number, indexName?: string): Promise<unknown[]>;
 declare function countRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, indexName?: string): Promise<number>;
+declare function putRows(conn: SqlConnection, def: StoreDef, values: unknown[], changedKeys?: KeyDTO[]): Promise<KeyDTO[]>;
 declare function putRow(conn: SqlConnection, def: StoreDef, value: unknown): Promise<KeyDTO>;
 declare function deleteRows(conn: SqlConnection, def: StoreDef, keyOrRange: KeyDTO | RangeDTO): Promise<void>;
-declare function clearRows(conn: SqlConnection, def: StoreDef): Promise<void>;
+declare function clearRows(conn: SqlConnection, def: StoreDef, wipe?: boolean): Promise<void>;
 /** Wipe all user stores; system stores (memberships) survive and the internal
  * schema metadata table is not a store, so the version guard is untouched. */
 declare function wipeRows(conn: SqlConnection): Promise<void>;
-/** Internal schema metadata is not exposed or cleared by the store API. */
+/** Internal schema metadata is not exposed or cleared by the store API.
+ *
+ * Version policy: the SQL DDL derives entirely from STORE_DEFS, so two
+ * schema versions are compatible iff their derived table sets are equal.
+ *  - stored > DB_VERSION → refuse (never downgrade).
+ *  - stored < DB_VERSION with EQUAL table sets (v29 → v30: defs unchanged,
+ *    only browser-local sync stores were added) → bump the guard in place;
+ *    no row is read, rewritten or erased.
+ *  - stored < DB_VERSION with different tables → fail closed with the same
+ *    actionable schema_incompatible error as before.
+ *  - no guard + store tables → foreign database, refuse. */
 declare function initializeStore(db: Database): Promise<void>;
 
-/**
- * Domain read models + incremental projection refresh over the shared SQL
- * store tables.
- *
- * Three derived tables, rebuilt from the per-store source tables (source of
- * truth) when incompatible and refreshed per affected key inside the same
- * transaction as every mutation:
- *   domain_note  — note metadata selector + original payload
- *   query_block  — one occurrence row per block_index row, parent resolved by
- *                  exact noteId or sourcePath (ambiguous/orphan → NULL parent,
- *                  which gates ALL domain reads with 409 until healed)
- *   segment_head — MAX(version) per segment id taken BEFORE the isHistory
- *                  filter, so a superseded revision can never resurrect
- *
- * Rebuilds are guarded: a `_wodwiki_schema` row stamps the projection
- * version, so repeated ready()/boot cycles skip the rebuild while the
- * derived shape is already compatible.
- *
- * Query plans are fixed and fully validated: every value is a bound parameter,
- * names come from this module, counts run before paging, and text matching is
- * a literal substring over JS-lowercased materialized columns (Unicode-exact;
- * instr/strpos never treat % or _ as wildcards).
- *
- * `journal` is materialized in JS (sourceMatches from the wql package — the
- * exact predicate the app applies) so no SQL regex re-implementation exists.
- */
+/** Current Note and actionable-block SQL projections. */
 
-/**
- * Applies ops in order, collecting projection impact per affected key, then
- * refreshes derived rows — all on the caller's transaction. Returns one entry
- * per op: the put key, or null for delete/clear. `opts.deferProjection`
- * skips the per-key refresh pass; the caller MUST rebuild derived state in
- * the same transaction afterwards (see rebuildProjections) or reads will
- * operate on stale projections behind a valid guard.
- */
-declare function refreshDomain(conn: SqlConnection, ops: TxOp[], opts?: {
-    deferProjection?: boolean;
-}): Promise<(KeyDTO | null)[]>;
+/** Checks precede mutations; pins and projections commit with source rows. */
+declare function refreshDomain(conn: SqlConnection, ops: TxOp[]): Promise<(KeyDTO | null)[]>;
 /**
  * Rebuild the derived tables from the source-of-truth store rows and stamp
  * the projection guard. Caller owns the transaction (atomicity) — the guard
@@ -141,20 +123,7 @@ declare const MAX_BODY: number;
  * SqlStorage.queryDomain share this entry). */
 declare function handleDomainQuery(db: Database, body: unknown): Promise<DomainQueryResult>;
 
-/**
- * SqlStorage — IStorage over the shared SQL store operations (server or
- * browser). Transactions buffer writes and flush them as one refreshDomain
- * pass inside a real SQL transaction: throw → rollback, success → commit,
- * and buffered reads overlay committed rows (read-your-writes). Projections
- * refresh inside the same transaction; bulkTransaction() batches a migration
- * into one rebuild instead of per-key refreshes. verifyWritable() proves the
- * backend accepts writes with a real INSERT that is rolled back.
- *
- * BrowserTursoStorage opens a direct-to-Turso backend via @libsql/client/web;
- * the constructor only builds the client (HTTP is connectionless), `ready()`
- * initializes schema + projections and every operation awaits it, so a
- * transient init failure never wedges the backend — ready() retries.
- */
+/** SQL storage with atomic, change-scoped projections and buffered reads. */
 
 interface SqlStorageOptions {
     /** Rows in user-owned stores are stamped with this userId on write. Omit
@@ -182,11 +151,7 @@ declare class SqlStorage implements IStorage {
     readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
     queryDomain(query: DomainQuery): Promise<DomainQueryResult | undefined>;
     transaction<K extends StoreName, R>(stores: K[], mode: 'readonly' | 'readwrite', fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
-    /**
-     * Bulk load for migration destinations: like transaction(), but the
-     * buffered writes skip per-key projection refresh and derived state is
-     * rebuilt once — everything inside one SQL transaction (throw → rollback).
-     */
+    /** Bulk writes use the same affected-key refresh as ordinary transactions. */
     bulkTransaction<K extends StoreName, R>(stores: K[], fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
     private runTx;
     /**
@@ -217,4 +182,149 @@ declare class BrowserTursoStorage extends SqlStorage {
     constructor(settings: TursoSettings, options?: SqlStorageOptions);
 }
 
-export { BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, SCHEMA_TABLE, type SqlConnection, type SqlRow, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, putRow, rebuildProjections, refreshDomain, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };
+/**
+ * Turso backup/sync protocol — the local-first sync tables layered on top of
+ * any libsql database. The browser data plane is always IndexedDB; a saved
+ * Turso target is a backup/sync destination, never the read/write provider.
+ *
+ * Design: the remote holds ONE op log (`_wodwiki_sync_ops`) plus a state row
+ * (`_wodwiki_sync_state`) carrying {schema, rev}. Every committed local
+ * transaction group appends one idempotent op-group (uuid op_id,
+ * INSERT-or-ignore per op); `rev` is assigned monotonically per NEWLY applied
+ * group — a retried group is recognized by its first op id, consumes no rev
+ * and appends nothing. Pulls replay ops with rev > cursor in deterministic
+ * (rev, idx) order. Tombstones (delete/clear/wipe) are ordinary ops —
+ * deletions propagate.
+ *
+ * Fetch atomicity: a pull window is a set of WHOLE revision groups. The rev
+ * boundary is chosen with a bounded subquery, then every row of those revs is
+ * returned — a group is never split, so the cursor never skips the rest of
+ * a group (one pathologically large group can exceed the nominal row bound;
+ * that is the unavoidable atomicity ceiling).
+ *
+ * ponytail: op-log replay pulls — a fresh browser replays the whole log
+ * (O(history)) instead of reading per-store current-state tables. Upgrade
+ * path: add per-store state tables rev-indexed by primary key and collapse
+ * the log into them periodically; the wire format (op_id, rev, mutation)
+ * stays unchanged.
+ *
+ * Never-downgrade rule: the state row's `schema` is the managing client's
+ * DB_VERSION at init time. Uploads verify `schema` INSIDE the write
+ * transaction (a stale probe must not append current payloads to an old or
+ * newer remote); an older remote log is migrated forward by the caller
+ * (transform payloads, never just rewrite the marker), a newer remote is
+ * never rewritten — the client refuses and keeps working locally.
+ */
+
+declare const SYNC_OPS_TABLE = "_wodwiki_sync_ops";
+declare const SYNC_STATE_TABLE = "_wodwiki_sync_state";
+/** Pre-migration op log copies live here — the recoverable old source,
+ *  retained after a schema migration replaces the active log. */
+declare const SYNC_ARCHIVE_TABLE = "_wodwiki_sync_ops_archive";
+/** One committed local transaction group, as journaled in IndexedDB. */
+type SyncMutation = {
+    op: 'put';
+    store: StoreName;
+    key: KeyDTO;
+    value: unknown;
+} | {
+    op: 'delete';
+    store: StoreName;
+    key: KeyDTO;
+} | {
+    op: 'clear';
+    store: StoreName;
+} | {
+    op: 'wipe';
+};
+interface SyncEntry {
+    /** Idempotency key — one uuid per committed local transaction group. */
+    id: string;
+    at: number;
+    ops: SyncMutation[];
+}
+interface StoredSyncOp {
+    opId: string;
+    rev: number;
+    idx: number;
+    at: number;
+    mutation: SyncMutation;
+}
+type SyncTargetKind = 
+/** No tables at all (beyond libsql internals): fresh database. */
+'empty'
+/** Tables exist but neither sync state nor a legacy schema guard — not
+ *  ours; initializing over unknown data is refused by the caller. */
+ | {
+    kind: 'unknown';
+}
+/** Legacy direct-Turso SqlStorage layout (`_wodwiki_schema` guard). */
+ | {
+    kind: 'legacy';
+    schemaVersion: number;
+}
+/** This sync protocol's layout; payload = state row. */
+ | {
+    kind: 'current';
+    schemaVersion: number;
+    rev: number;
+};
+/** Classify the sync target WITHOUT mutating it. */
+declare function probeSyncTarget(db: Database): Promise<SyncTargetKind>;
+/** Create the sync tables + state row. Only for empty targets; existing
+ *  state (current, legacy or unknown) is never overwritten by init. */
+declare function initSyncTarget(db: Database, schemaVersion: number): Promise<void>;
+interface ApplySyncBatchOptions {
+    /** Schema the caller verified at probe time — rechecked INSIDE the write
+     *  transaction so a schema change between probe and append aborts. */
+    expectSchema?: number;
+    /** Bump the state schema version in the SAME transaction (remote-schema
+     *  migrations append converted payloads + move the marker atomically). */
+    toSchemaVersion?: number;
+}
+/**
+ * Append op-groups to the log in ONE SQL transaction, idempotently by
+ * group: a group whose first op id already exists is skipped entirely and
+ * consumes no rev (retries never duplicate, never allocate revisions).
+ * Returns the number of NEW groups committed — ack semantics for the
+ * uploader's watermark.
+ */
+declare function applySyncBatch(db: Database, entries: SyncEntry[], opts?: ApplySyncBatchOptions): Promise<number>;
+/**
+ * Replay window: ops with rev > afterRev, in deterministic commit order.
+ * The window covers WHOLE revision groups: up to `limit` distinct revs are
+ * chosen (bounded subquery), then every row of those revs is returned, so a
+ * cursor advanced to the last returned rev never splits a group. A single
+ * group larger than `limit` is returned whole — the atomicity ceiling.
+ */
+declare function fetchSyncOps(db: Database, afterRev: number, limit: number): Promise<StoredSyncOp[]>;
+/**
+ * Schema-migration replacement for the active op log, in ONE transaction:
+ * every previous op is copied into the archive table (the recoverable old
+ * source — nothing is destroyed), the active log is cleared, and the
+ * converted snapshot groups become the entire replayable history at
+ * rev 1..n with the schema marker moved forward atomically. Fresh browsers
+ * replay converted payloads only, so pulls never touch legacy row shapes.
+ */
+declare function replaceSyncLog(db: Database, entries: SyncEntry[], toSchemaVersion: number): Promise<void>;
+/** Migration-only raw replay: parsed op payloads WITHOUT store/key validation
+ *  (old logs reference era store names like `segments`). Only
+ *  migrateRemoteToCurrent consumes this — pulls use fetchSyncOps, which
+ *  validates every row against the current schema. Binary cells revive. */
+interface RawSyncOp {
+    op: string;
+    store: string;
+    key: unknown;
+    value?: unknown;
+}
+declare function readRawSyncOps(db: Database): Promise<RawSyncOp[]>;
+/**
+ * Import rows from a legacy direct-Turso (SqlStorage) database into op-
+ * groups. Reads the per-store JSON `data` columns directly — the legacy
+ * schema guard may hold an older version SqlStorage refuses to open, so the
+ * rows are lifted raw, never through SqlStorage. Missing tables contribute
+ * no rows; nothing is written or deleted remotely.
+ */
+declare function readLegacyRows(db: Database, table: string): Promise<unknown[]>;
+
+export { type ApplySyncBatchOptions, BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, type RawSyncOp, SCHEMA_TABLE, SYNC_ARCHIVE_TABLE, SYNC_OPS_TABLE, SYNC_STATE_TABLE, type SqlConnection, type SqlRow, type SqlStatement, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type StoredSyncOp, type SyncEntry, type SyncMutation, type SyncTargetKind, type TursoSettings, applySyncBatch, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, fetchSyncOps, getRow, getRows, handleDomainQuery, initSyncTarget, initializeDomain, initializeStore, libsqlDatabase, listRows, listRowsFromIndexMany, probeSyncTarget, putRow, putRows, readLegacyRows, readRawSyncOps, rebuildProjections, refreshDomain, replaceSyncLog, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };

package/dist/sql/index.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@libsql/client';
-import { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, E as TxOp, I as IStorage, S as StoreName, b as IReadOnlyStore, c as StoreType, d as IReadWriteStore, D as DomainQuery, f as IStorageTransaction } from '../wire-C7ZtlBKe.js';
+import { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, T as TxOp, I as IStorage, S as StoreName, b as IReadOnlyStore, c as StoreType, d as IReadWriteStore, D as DomainQuery, f as IStorageTransaction } from '../wire-CiFcjo6_.js';
 import '@bitcobblers/wod-wiki-core';
 import '@bitcobblers/wod-wiki-lang';
 
@@ -30,9 +30,14 @@ declare class StorageError extends Error {
 
 type SqlValue = string | number | null;
 type SqlRow = Record<string, unknown>;
+interface SqlStatement {
+    sql: string;
+    params?: SqlValue[];
+}
 interface SqlConnection {
     query(sql: string, params?: SqlValue[]): Promise<SqlRow[]>;
     exec(sql: string, params?: SqlValue[]): Promise<void>;
+    batch?(statements: SqlStatement[]): Promise<SqlRow[][]>;
 }
 interface Database extends SqlConnection {
     readonly dialect: 'sqlite' | 'postgres';
@@ -57,8 +62,6 @@ declare function libsqlDatabase(client: LibsqlClient): Database;
  * is typed `ArrayBuffer | string`; strings pass through, and only the exact
  * two-key tag revives.
  */
-/** Serialize a row; when `binaryField` is set and holds an ArrayBuffer, it is
- * replaced by the lossless tag (shallow copy — the input row is untouched). */
 declare function encodeRowJson(value: unknown, binaryField?: string): string;
 /** Parse a row; when `binaryField` is set, a tagged value there revives as an
  * ArrayBuffer. Every other value — including tag-shaped data in other fields
@@ -76,55 +79,34 @@ declare function decodeRowJson<T = unknown>(text: string, binaryField?: string):
 declare const SCHEMA_TABLE = "_wodwiki_schema";
 declare function storeDefinition(name: string): StoreDef;
 declare function getRow(conn: SqlConnection, def: StoreDef, key: KeyDTO): Promise<unknown | undefined>;
+declare function getRows(conn: SqlConnection, def: StoreDef, keys: KeyDTO[]): Promise<(unknown | undefined)[]>;
+declare function listRowsFromIndexMany(conn: SqlConnection, def: StoreDef, indexName: string, keys: KeyDTO[]): Promise<unknown[][]>;
 declare function listRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, count?: number, indexName?: string): Promise<unknown[]>;
 declare function countRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, indexName?: string): Promise<number>;
+declare function putRows(conn: SqlConnection, def: StoreDef, values: unknown[], changedKeys?: KeyDTO[]): Promise<KeyDTO[]>;
 declare function putRow(conn: SqlConnection, def: StoreDef, value: unknown): Promise<KeyDTO>;
 declare function deleteRows(conn: SqlConnection, def: StoreDef, keyOrRange: KeyDTO | RangeDTO): Promise<void>;
-declare function clearRows(conn: SqlConnection, def: StoreDef): Promise<void>;
+declare function clearRows(conn: SqlConnection, def: StoreDef, wipe?: boolean): Promise<void>;
 /** Wipe all user stores; system stores (memberships) survive and the internal
  * schema metadata table is not a store, so the version guard is untouched. */
 declare function wipeRows(conn: SqlConnection): Promise<void>;
-/** Internal schema metadata is not exposed or cleared by the store API. */
+/** Internal schema metadata is not exposed or cleared by the store API.
+ *
+ * Version policy: the SQL DDL derives entirely from STORE_DEFS, so two
+ * schema versions are compatible iff their derived table sets are equal.
+ *  - stored > DB_VERSION → refuse (never downgrade).
+ *  - stored < DB_VERSION with EQUAL table sets (v29 → v30: defs unchanged,
+ *    only browser-local sync stores were added) → bump the guard in place;
+ *    no row is read, rewritten or erased.
+ *  - stored < DB_VERSION with different tables → fail closed with the same
+ *    actionable schema_incompatible error as before.
+ *  - no guard + store tables → foreign database, refuse. */
 declare function initializeStore(db: Database): Promise<void>;
 
-/**
- * Domain read models + incremental projection refresh over the shared SQL
- * store tables.
- *
- * Three derived tables, rebuilt from the per-store source tables (source of
- * truth) when incompatible and refreshed per affected key inside the same
- * transaction as every mutation:
- *   domain_note  — note metadata selector + original payload
- *   query_block  — one occurrence row per block_index row, parent resolved by
- *                  exact noteId or sourcePath (ambiguous/orphan → NULL parent,
- *                  which gates ALL domain reads with 409 until healed)
- *   segment_head — MAX(version) per segment id taken BEFORE the isHistory
- *                  filter, so a superseded revision can never resurrect
- *
- * Rebuilds are guarded: a `_wodwiki_schema` row stamps the projection
- * version, so repeated ready()/boot cycles skip the rebuild while the
- * derived shape is already compatible.
- *
- * Query plans are fixed and fully validated: every value is a bound parameter,
- * names come from this module, counts run before paging, and text matching is
- * a literal substring over JS-lowercased materialized columns (Unicode-exact;
- * instr/strpos never treat % or _ as wildcards).
- *
- * `journal` is materialized in JS (sourceMatches from the wql package — the
- * exact predicate the app applies) so no SQL regex re-implementation exists.
- */
+/** Current Note and actionable-block SQL projections. */
 
-/**
- * Applies ops in order, collecting projection impact per affected key, then
- * refreshes derived rows — all on the caller's transaction. Returns one entry
- * per op: the put key, or null for delete/clear. `opts.deferProjection`
- * skips the per-key refresh pass; the caller MUST rebuild derived state in
- * the same transaction afterwards (see rebuildProjections) or reads will
- * operate on stale projections behind a valid guard.
- */
-declare function refreshDomain(conn: SqlConnection, ops: TxOp[], opts?: {
-    deferProjection?: boolean;
-}): Promise<(KeyDTO | null)[]>;
+/** Checks precede mutations; pins and projections commit with source rows. */
+declare function refreshDomain(conn: SqlConnection, ops: TxOp[]): Promise<(KeyDTO | null)[]>;
 /**
  * Rebuild the derived tables from the source-of-truth store rows and stamp
  * the projection guard. Caller owns the transaction (atomicity) — the guard
@@ -141,20 +123,7 @@ declare const MAX_BODY: number;
  * SqlStorage.queryDomain share this entry). */
 declare function handleDomainQuery(db: Database, body: unknown): Promise<DomainQueryResult>;
 
-/**
- * SqlStorage — IStorage over the shared SQL store operations (server or
- * browser). Transactions buffer writes and flush them as one refreshDomain
- * pass inside a real SQL transaction: throw → rollback, success → commit,
- * and buffered reads overlay committed rows (read-your-writes). Projections
- * refresh inside the same transaction; bulkTransaction() batches a migration
- * into one rebuild instead of per-key refreshes. verifyWritable() proves the
- * backend accepts writes with a real INSERT that is rolled back.
- *
- * BrowserTursoStorage opens a direct-to-Turso backend via @libsql/client/web;
- * the constructor only builds the client (HTTP is connectionless), `ready()`
- * initializes schema + projections and every operation awaits it, so a
- * transient init failure never wedges the backend — ready() retries.
- */
+/** SQL storage with atomic, change-scoped projections and buffered reads. */
 
 interface SqlStorageOptions {
     /** Rows in user-owned stores are stamped with this userId on write. Omit
@@ -182,11 +151,7 @@ declare class SqlStorage implements IStorage {
     readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
     queryDomain(query: DomainQuery): Promise<DomainQueryResult | undefined>;
     transaction<K extends StoreName, R>(stores: K[], mode: 'readonly' | 'readwrite', fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
-    /**
-     * Bulk load for migration destinations: like transaction(), but the
-     * buffered writes skip per-key projection refresh and derived state is
-     * rebuilt once — everything inside one SQL transaction (throw → rollback).
-     */
+    /** Bulk writes use the same affected-key refresh as ordinary transactions. */
     bulkTransaction<K extends StoreName, R>(stores: K[], fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
     private runTx;
     /**
@@ -217,4 +182,149 @@ declare class BrowserTursoStorage extends SqlStorage {
     constructor(settings: TursoSettings, options?: SqlStorageOptions);
 }
 
-export { BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, SCHEMA_TABLE, type SqlConnection, type SqlRow, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, putRow, rebuildProjections, refreshDomain, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };
+/**
+ * Turso backup/sync protocol — the local-first sync tables layered on top of
+ * any libsql database. The browser data plane is always IndexedDB; a saved
+ * Turso target is a backup/sync destination, never the read/write provider.
+ *
+ * Design: the remote holds ONE op log (`_wodwiki_sync_ops`) plus a state row
+ * (`_wodwiki_sync_state`) carrying {schema, rev}. Every committed local
+ * transaction group appends one idempotent op-group (uuid op_id,
+ * INSERT-or-ignore per op); `rev` is assigned monotonically per NEWLY applied
+ * group — a retried group is recognized by its first op id, consumes no rev
+ * and appends nothing. Pulls replay ops with rev > cursor in deterministic
+ * (rev, idx) order. Tombstones (delete/clear/wipe) are ordinary ops —
+ * deletions propagate.
+ *
+ * Fetch atomicity: a pull window is a set of WHOLE revision groups. The rev
+ * boundary is chosen with a bounded subquery, then every row of those revs is
+ * returned — a group is never split, so the cursor never skips the rest of
+ * a group (one pathologically large group can exceed the nominal row bound;
+ * that is the unavoidable atomicity ceiling).
+ *
+ * ponytail: op-log replay pulls — a fresh browser replays the whole log
+ * (O(history)) instead of reading per-store current-state tables. Upgrade
+ * path: add per-store state tables rev-indexed by primary key and collapse
+ * the log into them periodically; the wire format (op_id, rev, mutation)
+ * stays unchanged.
+ *
+ * Never-downgrade rule: the state row's `schema` is the managing client's
+ * DB_VERSION at init time. Uploads verify `schema` INSIDE the write
+ * transaction (a stale probe must not append current payloads to an old or
+ * newer remote); an older remote log is migrated forward by the caller
+ * (transform payloads, never just rewrite the marker), a newer remote is
+ * never rewritten — the client refuses and keeps working locally.
+ */
+
+declare const SYNC_OPS_TABLE = "_wodwiki_sync_ops";
+declare const SYNC_STATE_TABLE = "_wodwiki_sync_state";
+/** Pre-migration op log copies live here — the recoverable old source,
+ *  retained after a schema migration replaces the active log. */
+declare const SYNC_ARCHIVE_TABLE = "_wodwiki_sync_ops_archive";
+/** One committed local transaction group, as journaled in IndexedDB. */
+type SyncMutation = {
+    op: 'put';
+    store: StoreName;
+    key: KeyDTO;
+    value: unknown;
+} | {
+    op: 'delete';
+    store: StoreName;
+    key: KeyDTO;
+} | {
+    op: 'clear';
+    store: StoreName;
+} | {
+    op: 'wipe';
+};
+interface SyncEntry {
+    /** Idempotency key — one uuid per committed local transaction group. */
+    id: string;
+    at: number;
+    ops: SyncMutation[];
+}
+interface StoredSyncOp {
+    opId: string;
+    rev: number;
+    idx: number;
+    at: number;
+    mutation: SyncMutation;
+}
+type SyncTargetKind = 
+/** No tables at all (beyond libsql internals): fresh database. */
+'empty'
+/** Tables exist but neither sync state nor a legacy schema guard — not
+ *  ours; initializing over unknown data is refused by the caller. */
+ | {
+    kind: 'unknown';
+}
+/** Legacy direct-Turso SqlStorage layout (`_wodwiki_schema` guard). */
+ | {
+    kind: 'legacy';
+    schemaVersion: number;
+}
+/** This sync protocol's layout; payload = state row. */
+ | {
+    kind: 'current';
+    schemaVersion: number;
+    rev: number;
+};
+/** Classify the sync target WITHOUT mutating it. */
+declare function probeSyncTarget(db: Database): Promise<SyncTargetKind>;
+/** Create the sync tables + state row. Only for empty targets; existing
+ *  state (current, legacy or unknown) is never overwritten by init. */
+declare function initSyncTarget(db: Database, schemaVersion: number): Promise<void>;
+interface ApplySyncBatchOptions {
+    /** Schema the caller verified at probe time — rechecked INSIDE the write
+     *  transaction so a schema change between probe and append aborts. */
+    expectSchema?: number;
+    /** Bump the state schema version in the SAME transaction (remote-schema
+     *  migrations append converted payloads + move the marker atomically). */
+    toSchemaVersion?: number;
+}
+/**
+ * Append op-groups to the log in ONE SQL transaction, idempotently by
+ * group: a group whose first op id already exists is skipped entirely and
+ * consumes no rev (retries never duplicate, never allocate revisions).
+ * Returns the number of NEW groups committed — ack semantics for the
+ * uploader's watermark.
+ */
+declare function applySyncBatch(db: Database, entries: SyncEntry[], opts?: ApplySyncBatchOptions): Promise<number>;
+/**
+ * Replay window: ops with rev > afterRev, in deterministic commit order.
+ * The window covers WHOLE revision groups: up to `limit` distinct revs are
+ * chosen (bounded subquery), then every row of those revs is returned, so a
+ * cursor advanced to the last returned rev never splits a group. A single
+ * group larger than `limit` is returned whole — the atomicity ceiling.
+ */
+declare function fetchSyncOps(db: Database, afterRev: number, limit: number): Promise<StoredSyncOp[]>;
+/**
+ * Schema-migration replacement for the active op log, in ONE transaction:
+ * every previous op is copied into the archive table (the recoverable old
+ * source — nothing is destroyed), the active log is cleared, and the
+ * converted snapshot groups become the entire replayable history at
+ * rev 1..n with the schema marker moved forward atomically. Fresh browsers
+ * replay converted payloads only, so pulls never touch legacy row shapes.
+ */
+declare function replaceSyncLog(db: Database, entries: SyncEntry[], toSchemaVersion: number): Promise<void>;
+/** Migration-only raw replay: parsed op payloads WITHOUT store/key validation
+ *  (old logs reference era store names like `segments`). Only
+ *  migrateRemoteToCurrent consumes this — pulls use fetchSyncOps, which
+ *  validates every row against the current schema. Binary cells revive. */
+interface RawSyncOp {
+    op: string;
+    store: string;
+    key: unknown;
+    value?: unknown;
+}
+declare function readRawSyncOps(db: Database): Promise<RawSyncOp[]>;
+/**
+ * Import rows from a legacy direct-Turso (SqlStorage) database into op-
+ * groups. Reads the per-store JSON `data` columns directly — the legacy
+ * schema guard may hold an older version SqlStorage refuses to open, so the
+ * rows are lifted raw, never through SqlStorage. Missing tables contribute
+ * no rows; nothing is written or deleted remotely.
+ */
+declare function readLegacyRows(db: Database, table: string): Promise<unknown[]>;
+
+export { type ApplySyncBatchOptions, BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, type RawSyncOp, SCHEMA_TABLE, SYNC_ARCHIVE_TABLE, SYNC_OPS_TABLE, SYNC_STATE_TABLE, type SqlConnection, type SqlRow, type SqlStatement, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type StoredSyncOp, type SyncEntry, type SyncMutation, type SyncTargetKind, type TursoSettings, applySyncBatch, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, fetchSyncOps, getRow, getRows, handleDomainQuery, initSyncTarget, initializeDomain, initializeStore, libsqlDatabase, listRows, listRowsFromIndexMany, probeSyncTarget, putRow, putRows, readLegacyRows, readRawSyncOps, rebuildProjections, refreshDomain, replaceSyncLog, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };