@bitcobblers/wod-wiki-storage 0.35.2117 → 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, 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-Cfvz-I0h.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';
 
@@ -90,7 +90,17 @@ declare function clearRows(conn: SqlConnection, def: StoreDef, wipe?: boolean):
 /** 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>;
 
 /** Current Note and actionable-block SQL projections. */
@@ -172,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, type SqlStatement, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, getRows, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, listRowsFromIndexMany, putRow, putRows, 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, 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-Cfvz-I0h.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';
 
@@ -90,7 +90,17 @@ declare function clearRows(conn: SqlConnection, def: StoreDef, wipe?: boolean):
 /** 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>;
 
 /** Current Note and actionable-block SQL projections. */
@@ -172,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, type SqlStatement, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, getRows, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, listRowsFromIndexMany, putRow, putRows, 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 };