@bitcobblers/wod-wiki-storage 0.39.2142 → 0.40.2144

package/dist/idb/index.d.cts

@@ -0,0 +1,156 @@
+import { IDBPDatabase, IDBPTransaction } from 'idb';
+import { I as IStorage, S as StoreName, a as IReadOnlyStore, b as StoreType, c as IReadWriteStore, d as IStorageTransaction } from '../wire-DGYxXt3I.cjs';
+import { U as UserScopeContext } from '../policy-DRYF6Y8i.cjs';
+import { S as SyncMutation, a as SyncEntry } from '../sync-DG4Z-szj.cjs';
+import { D as Database } from '../connection-DxuCLpRc.cjs';
+import '@bitcobblers/wod-wiki-core';
+import '@bitcobblers/wod-wiki-lang';
+import '@libsql/client';
+
+/**
+ * IndexedDB adapter — the browser data plane (moved verbatim from the
+ * playground app; the shared user policy and the schema32 sync cutover live
+ * here now). Local-first invariants:
+ *
+ *  - Every committed local transaction group is durable in `sync_outbox`,
+ *    written in the SAME native transaction as the data writes.
+ *  - Snapshots (`snapshotRows`, bootstrap, conversion) are policy-compliant:
+ *    they carry user data only, per the shared policy in `../policy`.
+ *  - `sync_state` holds pull cursors, upload watermarks and frozen
+ *    bootstrap runs (durable retry identities), all per backup target.
+ */
+
+declare const IDB_DB_NAME = "wodwiki-db";
+type Mode = 'readonly' | 'readwrite';
+/** Native tx handle; write methods are guarded at runtime by `mutable`, so
+ *  the handle is typed readwrite to keep put/delete/clear defined. */
+type Tx = IDBPTransaction<unknown, string, 'readwrite'>;
+declare function subscribeOutboxWrites(listener: () => void): () => void;
+declare class IndexedDBStorage implements IStorage {
+    private readonly options;
+    private opening?;
+    constructor(options?: {
+        getUserId?: () => string;
+        /** Called just before a schema migration runs (oldVersion < DB_VERSION). */
+        onUpgradeStart?: (fromVersion: number) => void;
+        /** Database file name; the sync engine migrates scratch copies under
+         *  their own name so a remote-schema conversion never touches the
+         *  live database. Defaults to the app database. */
+        dbName?: string;
+    });
+    open(): Promise<IDBPDatabase>;
+    stamp(store: StoreName, value: unknown): unknown;
+    /** User-scope context (proven seed note ids) from the notes of `tx` —
+     *  journal-time ownership classification reads it INSIDE the same
+     *  transaction, so a seed import's note writes are visible to the link
+     *  writes that follow in the same commit. Internal seam for IDBStore. */
+    policyContext(tx?: Tx): Promise<UserScopeContext>;
+    readonly<K extends StoreName>(store: K): IReadOnlyStore<StoreType<K>>;
+    readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
+    transaction<K extends StoreName, R>(stores: K[], mode: Mode, fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    wipeUserData(): Promise<void>;
+    wipe(): Promise<void>;
+    /** Pending committed transaction groups, in commit order. */
+    readOutbox(afterSeq: number, limit: number): Promise<{
+        seq: number;
+        id: string;
+        at: number;
+        ops: SyncMutation[];
+    }[]>;
+    /** Drop acknowledged groups. Callers pass only the contiguous acked
+     *  watermark — a failed upload never truncates pending writes. */
+    ackOutbox(upToSeq: number): Promise<void>;
+    getSyncState<T>(key: string): Promise<T | undefined>;
+    setSyncState(key: string, value: unknown): Promise<void>;
+    /**
+     * Freeze ONE durable bootstrap run for `key` (per backup target): a
+     * policy-compliant snapshot of the current rows, chunked into ≤500-op /
+     * ≤~1MB entries with a unique run UUID and stable chunk ids, persisted in
+     * `sync_state[key]` in the SAME readwrite transaction that reads the data
+     * — so a retry returns the byte-identical frozen entries (idempotent
+     * remote replays), and a crash before the commit freezes nothing. No
+     * network happens here.
+     *
+     * Pending outbox groups are read INSIDE the same transaction: their
+     * touched keys/stores are excluded from the snapshot so the journal (which
+     * ships after the bootstrap, in commit order) stays the last writer and
+     * nothing ships twice. A pending wipe freezes an empty run — the journal
+     * wipe itself still ships and decides the remote's end state.
+     *
+     * The engine deletes the frozen run (`db.delete('sync_state', key)`) only
+     * after the remote commit; until then every retry replays these entries.
+     */
+    captureSyncBootstrap(key: string): Promise<SyncEntry[]>;
+    /**
+     * Validate every stored pin (note blocks + session pins against
+     * block_revisions) in ONE consistent readonly read — the post-restore
+     * gate: a replayed backup with missing history fails loudly here instead
+     * of surfacing later as broken sessions.
+     */
+    validateSyncState(): Promise<void>;
+    /**
+     * Apply remotely committed mutations locally (pull/replay) WITHOUT
+     * journaling — a pulled mutation must never re-enter the outbox. Runs in
+     * one native transaction together with the cursor update.
+     *
+     * Unsent-edit overlay: pending outbox groups (committed local writes not
+     * yet acknowledged remotely) are read INSIDE the same transaction and
+     * replayed after the remote rows — a local edit/delete/clear/wipe that
+     * committed while the pull was on the network stays the visible state;
+     * the remote row is backed up locally, not clobbered over the user.
+     *
+     * Conflict policy (deterministic, history-preserving):
+     *  - notes: an incoming row with a LOWER sourceRevision than the existing
+     *    row is stale — skipped, never clobbers newer history.
+     *  - block_revisions: same key with different contents keeps BOTH rows —
+     *    the incoming version is re-keyed to the next free version for that
+     *    block. Immutable history is never silently replaced.
+     *  - memberships (system): remote mutations are skipped — identity truth
+     *    stays local and snapshot/upload never include them.
+     *
+     * Returns committed-boundary counts of canonical consumer records (notes +
+     *  efforts only; internal/journal rows never reach the sync toast).
+     * `cursorKey` keeps cursors per backup target.
+     */
+    applySyncMutations(mutations: SyncMutation[], cursorRev: number | null, cursorKey?: string): Promise<{
+        added: number;
+        updated: number;
+    }>;
+    /**
+     * Consistent atomic snapshot, policy-compliant (shared user policy): only
+     * user-scope rows of the non-system stores, read in ONE readonly
+     * transaction — the backup never mixes the pre/post state of a concurrent
+     * local commit. System stores (memberships) are excluded: they never sync.
+     * Use `snapshotAllRows` for the lossless (unfiltered) form.
+     */
+    snapshotRows(): Promise<{
+        store: StoreName;
+        rows: unknown[];
+    }[]>;
+    /** Lossless snapshot of every NON-SYSTEM store (meta included) in one
+     *  readonly transaction — local export / restore emptiness checks. A
+     *  freshly initialized database may hold a default membership, so the
+     *  system store is excluded from both uses. */
+    snapshotAllRows(): Promise<{
+        store: StoreName;
+        rows: unknown[];
+    }[]>;
+    close(): Promise<void>;
+}
+/**
+ * Convert an older backup into policy-compliant current-schema mutations
+ * WITHOUT touching the source:
+ *
+ *  1. Lift the source data as ordered scratch ops (op-log replay in log
+ *     order, or legacy direct-Turso per-store rows incl. segments/results).
+ *  2. Replay them into a unique scratch IndexedDB created AT `fromVersion`,
+ *     then open it through IndexedDBStorage — the same versioned migration
+ *     chain the browser runs locally rebuilds segments-era rows into
+ *     note-owned blocks, revisions, sessions and events.
+ *  3. Validate strictly (all note/session pins, binary payloads, derivable
+ *     keys — any miss fails the copy) and return policy-compliant PUTS ONLY
+ *     (the caller applies them to a fresh, reserved target).
+ */
+declare function convertSyncSource(db: Database, fromVersion: number, legacy: boolean): Promise<SyncMutation[]>;
+
+export { IDB_DB_NAME, IndexedDBStorage, convertSyncSource, subscribeOutboxWrites };

package/dist/idb/index.d.ts

@@ -0,0 +1,156 @@
+import { IDBPDatabase, IDBPTransaction } from 'idb';
+import { I as IStorage, S as StoreName, a as IReadOnlyStore, b as StoreType, c as IReadWriteStore, d as IStorageTransaction } from '../wire-DGYxXt3I.js';
+import { U as UserScopeContext } from '../policy-CPscN81J.js';
+import { S as SyncMutation, a as SyncEntry } from '../sync-Bjj_c1ea.js';
+import { D as Database } from '../connection-DxuCLpRc.js';
+import '@bitcobblers/wod-wiki-core';
+import '@bitcobblers/wod-wiki-lang';
+import '@libsql/client';
+
+/**
+ * IndexedDB adapter — the browser data plane (moved verbatim from the
+ * playground app; the shared user policy and the schema32 sync cutover live
+ * here now). Local-first invariants:
+ *
+ *  - Every committed local transaction group is durable in `sync_outbox`,
+ *    written in the SAME native transaction as the data writes.
+ *  - Snapshots (`snapshotRows`, bootstrap, conversion) are policy-compliant:
+ *    they carry user data only, per the shared policy in `../policy`.
+ *  - `sync_state` holds pull cursors, upload watermarks and frozen
+ *    bootstrap runs (durable retry identities), all per backup target.
+ */
+
+declare const IDB_DB_NAME = "wodwiki-db";
+type Mode = 'readonly' | 'readwrite';
+/** Native tx handle; write methods are guarded at runtime by `mutable`, so
+ *  the handle is typed readwrite to keep put/delete/clear defined. */
+type Tx = IDBPTransaction<unknown, string, 'readwrite'>;
+declare function subscribeOutboxWrites(listener: () => void): () => void;
+declare class IndexedDBStorage implements IStorage {
+    private readonly options;
+    private opening?;
+    constructor(options?: {
+        getUserId?: () => string;
+        /** Called just before a schema migration runs (oldVersion < DB_VERSION). */
+        onUpgradeStart?: (fromVersion: number) => void;
+        /** Database file name; the sync engine migrates scratch copies under
+         *  their own name so a remote-schema conversion never touches the
+         *  live database. Defaults to the app database. */
+        dbName?: string;
+    });
+    open(): Promise<IDBPDatabase>;
+    stamp(store: StoreName, value: unknown): unknown;
+    /** User-scope context (proven seed note ids) from the notes of `tx` —
+     *  journal-time ownership classification reads it INSIDE the same
+     *  transaction, so a seed import's note writes are visible to the link
+     *  writes that follow in the same commit. Internal seam for IDBStore. */
+    policyContext(tx?: Tx): Promise<UserScopeContext>;
+    readonly<K extends StoreName>(store: K): IReadOnlyStore<StoreType<K>>;
+    readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
+    transaction<K extends StoreName, R>(stores: K[], mode: Mode, fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    wipeUserData(): Promise<void>;
+    wipe(): Promise<void>;
+    /** Pending committed transaction groups, in commit order. */
+    readOutbox(afterSeq: number, limit: number): Promise<{
+        seq: number;
+        id: string;
+        at: number;
+        ops: SyncMutation[];
+    }[]>;
+    /** Drop acknowledged groups. Callers pass only the contiguous acked
+     *  watermark — a failed upload never truncates pending writes. */
+    ackOutbox(upToSeq: number): Promise<void>;
+    getSyncState<T>(key: string): Promise<T | undefined>;
+    setSyncState(key: string, value: unknown): Promise<void>;
+    /**
+     * Freeze ONE durable bootstrap run for `key` (per backup target): a
+     * policy-compliant snapshot of the current rows, chunked into ≤500-op /
+     * ≤~1MB entries with a unique run UUID and stable chunk ids, persisted in
+     * `sync_state[key]` in the SAME readwrite transaction that reads the data
+     * — so a retry returns the byte-identical frozen entries (idempotent
+     * remote replays), and a crash before the commit freezes nothing. No
+     * network happens here.
+     *
+     * Pending outbox groups are read INSIDE the same transaction: their
+     * touched keys/stores are excluded from the snapshot so the journal (which
+     * ships after the bootstrap, in commit order) stays the last writer and
+     * nothing ships twice. A pending wipe freezes an empty run — the journal
+     * wipe itself still ships and decides the remote's end state.
+     *
+     * The engine deletes the frozen run (`db.delete('sync_state', key)`) only
+     * after the remote commit; until then every retry replays these entries.
+     */
+    captureSyncBootstrap(key: string): Promise<SyncEntry[]>;
+    /**
+     * Validate every stored pin (note blocks + session pins against
+     * block_revisions) in ONE consistent readonly read — the post-restore
+     * gate: a replayed backup with missing history fails loudly here instead
+     * of surfacing later as broken sessions.
+     */
+    validateSyncState(): Promise<void>;
+    /**
+     * Apply remotely committed mutations locally (pull/replay) WITHOUT
+     * journaling — a pulled mutation must never re-enter the outbox. Runs in
+     * one native transaction together with the cursor update.
+     *
+     * Unsent-edit overlay: pending outbox groups (committed local writes not
+     * yet acknowledged remotely) are read INSIDE the same transaction and
+     * replayed after the remote rows — a local edit/delete/clear/wipe that
+     * committed while the pull was on the network stays the visible state;
+     * the remote row is backed up locally, not clobbered over the user.
+     *
+     * Conflict policy (deterministic, history-preserving):
+     *  - notes: an incoming row with a LOWER sourceRevision than the existing
+     *    row is stale — skipped, never clobbers newer history.
+     *  - block_revisions: same key with different contents keeps BOTH rows —
+     *    the incoming version is re-keyed to the next free version for that
+     *    block. Immutable history is never silently replaced.
+     *  - memberships (system): remote mutations are skipped — identity truth
+     *    stays local and snapshot/upload never include them.
+     *
+     * Returns committed-boundary counts of canonical consumer records (notes +
+     *  efforts only; internal/journal rows never reach the sync toast).
+     * `cursorKey` keeps cursors per backup target.
+     */
+    applySyncMutations(mutations: SyncMutation[], cursorRev: number | null, cursorKey?: string): Promise<{
+        added: number;
+        updated: number;
+    }>;
+    /**
+     * Consistent atomic snapshot, policy-compliant (shared user policy): only
+     * user-scope rows of the non-system stores, read in ONE readonly
+     * transaction — the backup never mixes the pre/post state of a concurrent
+     * local commit. System stores (memberships) are excluded: they never sync.
+     * Use `snapshotAllRows` for the lossless (unfiltered) form.
+     */
+    snapshotRows(): Promise<{
+        store: StoreName;
+        rows: unknown[];
+    }[]>;
+    /** Lossless snapshot of every NON-SYSTEM store (meta included) in one
+     *  readonly transaction — local export / restore emptiness checks. A
+     *  freshly initialized database may hold a default membership, so the
+     *  system store is excluded from both uses. */
+    snapshotAllRows(): Promise<{
+        store: StoreName;
+        rows: unknown[];
+    }[]>;
+    close(): Promise<void>;
+}
+/**
+ * Convert an older backup into policy-compliant current-schema mutations
+ * WITHOUT touching the source:
+ *
+ *  1. Lift the source data as ordered scratch ops (op-log replay in log
+ *     order, or legacy direct-Turso per-store rows incl. segments/results).
+ *  2. Replay them into a unique scratch IndexedDB created AT `fromVersion`,
+ *     then open it through IndexedDBStorage — the same versioned migration
+ *     chain the browser runs locally rebuilds segments-era rows into
+ *     note-owned blocks, revisions, sessions and events.
+ *  3. Validate strictly (all note/session pins, binary payloads, derivable
+ *     keys — any miss fails the copy) and return policy-compliant PUTS ONLY
+ *     (the caller applies them to a fresh, reserved target).
+ */
+declare function convertSyncSource(db: Database, fromVersion: number, legacy: boolean): Promise<SyncMutation[]>;
+
+export { IDB_DB_NAME, IndexedDBStorage, convertSyncSource, subscribeOutboxWrites };