@gonvex/expo-sqlite 0.5.2-staging.13 → 0.5.2-staging.15

package/README.md

@@ -11,3 +11,35 @@ const client = new GonvexClient(url, {
   localReplica: { storage: expoSQLite(database) },
 });
 ```
+
+The SDK reads cold rows by primary key or a scalar secondary index. Unindexed
+reads use 256-row pages and retain only the requested result window. The adapter
+keeps normalized rows and query memberships on disk; it does not hydrate the
+whole database to execute a Reducer. Incoming projections update only their fields.
+Schema upgrades, cursor changes, row authority, and tombstones are transactional.
+
+## Durable reducer outbox
+
+`expoSQLiteOutbox(database)` stores queued reducer intents one row per intent,
+with every change in its own SQLite transaction and a persisted id sequence.
+It implements the same `OutboxStore` contract as the browser storage, so the
+SDK keeps owning ordering, retries and crash recovery.
+
+```ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { expoSQLite, expoSQLiteOutbox, migrateLegacyOutbox } from "@gonvex/expo-sqlite";
+
+const database = await openDatabaseAsync("gonvex.db");
+const outbox = expoSQLiteOutbox(database);
+// One-time import of an older whole-list AsyncStorage outbox. Safe on every
+// launch; the key is removed only after the import committed.
+await migrateLegacyOutbox({ store: outbox, storage: AsyncStorage, key: "wh_gonvex_v2_reducer_outbox" });
+
+const client = new GonvexClient(url, {
+  localReplica: { storage: expoSQLite(database) },
+  outbox: { store: outbox },
+});
+```
+
+Run the migration before constructing the client. Imported entries keep their
+ids and idempotency keys, so a replay is still deduplicated by the runtime.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { ReplicaWindow, LocalReplicaStorage, ReplicaScope, ReplicaRow, ReplicaSnapshot, ReplicaTransaction } from "@gonvex/client";
+import { type ReplicaReadCoverage, type ReplicaReducerReadView } from "@gonvex/client";
 export interface ExpoSQLiteDatabase {
     execAsync(sql: string): Promise<void>;
     runAsync(sql: string, ...params: unknown[]): Promise<unknown>;
@@ -17,18 +18,34 @@ export declare class ExpoSQLiteLocalReplicaStorage implements LocalReplicaStorag
     constructor(database: ExpoSQLiteDatabase);
     private initialize;
     private migrateSchema;
+    private rebuildLookup;
     load(scope?: ReplicaScope): Promise<ReplicaSnapshot | undefined>;
+    loadWorkingSet(scope: string, budget: {
+        maxRows: number;
+        maxBytes: number;
+    }): Promise<ReplicaSnapshot | undefined>;
+    loadEntityRows(scope: string, entity: string, ids: readonly string[]): Promise<{
+        id: string;
+        row: ReplicaRow;
+    }[]>;
+    loadWindowRows(scope: string, signature: string): Promise<{
+        window: ReplicaWindow;
+        rows: ReplicaRow[];
+    } | undefined>;
+    withReadView<T>(scope: string, coverage: ReplicaReadCoverage, run: (view: ReplicaReducerReadView) => Promise<T>): Promise<T>;
     loadSession(scope: string): Promise<import("@gonvex/client").LocalReplicaSession | undefined>;
     saveSession(scope: string, session: import("@gonvex/client").LocalReplicaSession | undefined): Promise<void>;
     applyTransaction(transaction: ReplicaTransaction, _snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
     advanceWatermark(windows: readonly ReplicaWindow[], cursor: ReplicaSnapshot["cursor"], scope?: ReplicaScope): Promise<void>;
     replaceSnapshot(snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
-    replaceWindow(window: ReplicaWindow, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
-    applyWindowDelta(window: ReplicaWindow, _delta: {
+    private writeRecords;
+    replaceWindow(window: ReplicaWindow, snapshot: ReplicaSnapshot, scope?: ReplicaScope, projection?: readonly ReplicaRow[]): Promise<void>;
+    applyWindowDelta(window: ReplicaWindow, delta: {
         upserts: ReplicaRow[];
         deleted: string[];
     }, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
     removeWindow(signature: string, snapshot: ReplicaSnapshot, scope?: ReplicaScope): Promise<void>;
     clear(scope?: ReplicaScope): Promise<void>;
 }
+export * from "./outbox.js";
 export declare function expoSQLite(database: ExpoSQLiteDatabase): LocalReplicaStorage;

package/dist/index.js

@@ -1,5 +1,6 @@
+import { pagedReplicaReadView, mergeReplicaRecord, } from "@gonvex/client";
 const defaultReplicaScope = "default";
-const replicaSchemaVersion = 2;
+const replicaSchemaVersion = 3;
 /**
  * Transactional, normalized SQLite persistence for Expo. Every server
  * transaction updates entities, Live Query memberships, and the replica
@@ -12,15 +13,17 @@ export class ExpoSQLiteLocalReplicaStorage {
         this.database = database;
     }
     initialize() {
-        return this.initialized ??= this.migrateSchema();
+        return (this.initialized ??= this.migrateSchema());
     }
     async migrateSchema() {
+        const storedVersion = await this.database.getFirstAsync("PRAGMA user_version");
         const [entities, queries, meta] = await Promise.all([
             this.database.getAllAsync(`PRAGMA table_info(_gonvex_replica_entities)`),
             this.database.getAllAsync(`PRAGMA table_info(_gonvex_replica_queries)`),
             this.database.getAllAsync(`PRAGMA table_info(_gonvex_replica_meta)`),
         ]);
-        const legacyEntities = entities.length > 0 && !entities.some((column) => column.name === "scope");
+        const legacyEntities = entities.length > 0 &&
+            !entities.some((column) => column.name === "scope");
         const legacyQueries = queries.length > 0 && !queries.some((column) => column.name === "scope");
         const legacyMeta = meta.length > 0 && !meta.some((column) => column.name === "scope");
         const createTables = `
@@ -36,9 +39,34 @@ export class ExpoSQLiteLocalReplicaStorage {
         scope TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL,
         PRIMARY KEY (scope, key)
       );
+      CREATE TABLE IF NOT EXISTS _gonvex_replica_lookup (
+        scope TEXT NOT NULL, entity TEXT NOT NULL, column_name TEXT NOT NULL,
+        kind TEXT NOT NULL, scalar BLOB NOT NULL, id TEXT NOT NULL,
+        PRIMARY KEY(scope,entity,column_name,kind,scalar,id)
+      );
+      CREATE TRIGGER IF NOT EXISTS _gonvex_replica_lookup_insert AFTER INSERT ON _gonvex_replica_entities BEGIN
+        INSERT INTO _gonvex_replica_lookup SELECT NEW.scope,NEW.entity,j.key,
+          CASE WHEN j.type IN ('integer','real') THEN 'number' WHEN j.type IN ('true','false') THEN 'boolean' ELSE 'string' END,j.atom,NEW.id
+          FROM json_each(NEW.value) j WHERE j.type IN ('integer','real','true','false') OR (j.type='text' AND length(j.atom)<=256);
+      END;
+      CREATE TRIGGER IF NOT EXISTS _gonvex_replica_lookup_update AFTER UPDATE ON _gonvex_replica_entities BEGIN
+        DELETE FROM _gonvex_replica_lookup WHERE scope=OLD.scope AND entity=OLD.entity AND id=OLD.id;
+        INSERT INTO _gonvex_replica_lookup SELECT NEW.scope,NEW.entity,j.key,
+          CASE WHEN j.type IN ('integer','real') THEN 'number' WHEN j.type IN ('true','false') THEN 'boolean' ELSE 'string' END,j.atom,NEW.id
+          FROM json_each(NEW.value) j WHERE j.type IN ('integer','real','true','false') OR (j.type='text' AND length(j.atom)<=256);
+      END;
+      CREATE TRIGGER IF NOT EXISTS _gonvex_replica_lookup_delete AFTER DELETE ON _gonvex_replica_entities BEGIN
+        DELETE FROM _gonvex_replica_lookup WHERE scope=OLD.scope AND entity=OLD.entity AND id=OLD.id;
+      END;
+      CREATE INDEX IF NOT EXISTS _gonvex_replica_lookup_row ON _gonvex_replica_lookup(scope,entity,id);
     `;
         if (!legacyEntities && !legacyQueries && !legacyMeta) {
-            await this.database.execAsync(`PRAGMA user_version = ${replicaSchemaVersion};${createTables}`);
+            await this.database.withTransactionAsync(async () => {
+                await this.database.execAsync(createTables);
+                if ((storedVersion?.user_version ?? 0) < 3)
+                    await this.rebuildLookup();
+                await this.database.execAsync(`PRAGMA user_version = ${replicaSchemaVersion}`);
+            });
             return;
         }
         // The v1 tables had no namespace at all. Keep their contents available to
@@ -73,16 +101,23 @@ export class ExpoSQLiteLocalReplicaStorage {
                 await this.database.execAsync(`DROP TABLE _gonvex_replica_queries_legacy_v1`);
             if (legacyMeta)
                 await this.database.execAsync(`DROP TABLE _gonvex_replica_meta_legacy_v1`);
+            await this.rebuildLookup();
             await this.database.execAsync(`PRAGMA user_version = ${replicaSchemaVersion}`);
         });
     }
+    async rebuildLookup() {
+        await this.database.execAsync(`INSERT OR REPLACE INTO _gonvex_replica_lookup
+      SELECT e.scope,e.entity,j.key,CASE WHEN j.type IN ('integer','real') THEN 'number' WHEN j.type IN ('true','false') THEN 'boolean' ELSE 'string' END,j.atom,e.id
+      FROM _gonvex_replica_entities e,json_each(e.value) j WHERE j.type IN ('integer','real','true','false') OR (j.type='text' AND length(j.atom)<=256)`);
+    }
     async load(scope = defaultReplicaScope) {
         await this.initialize();
         const cursor = await this.database.getFirstAsync(`SELECT scope, key, value FROM _gonvex_replica_meta WHERE scope = ? AND key = 'cursor'`, scope);
         const entities = {};
         const entityRecords = await this.database.getAllAsync(`SELECT scope, entity, id, value FROM _gonvex_replica_entities WHERE scope = ? ORDER BY entity, id`, scope);
         for (const row of entityRecords) {
-            (entities[row.entity] ??= {})[row.id] = JSON.parse(row.value);
+            if (row.value !== "null")
+                (entities[row.entity] ??= {})[row.id] = JSON.parse(row.value);
         }
         const liveQueries = {};
         const queryRecords = await this.database.getAllAsync(`SELECT scope, signature, value FROM _gonvex_replica_queries WHERE scope = ? ORDER BY signature`, scope);
@@ -91,7 +126,148 @@ export class ExpoSQLiteLocalReplicaStorage {
         }
         if (!cursor && entityRecords.length === 0 && queryRecords.length === 0)
             return undefined;
-        return { cursor: cursor ? JSON.parse(cursor.value) : undefined, entities, liveQueries };
+        return {
+            cursor: cursor ? JSON.parse(cursor.value) : undefined,
+            entities,
+            liveQueries,
+        };
+    }
+    async loadWorkingSet(scope, budget) {
+        await this.initialize();
+        let snapshot;
+        await this.database.withTransactionAsync(async () => {
+            const cursor = await this.database.getFirstAsync(`SELECT scope, key, value FROM _gonvex_replica_meta WHERE scope = ? AND key = 'cursor'`, scope);
+            const queries = await this.database.getAllAsync(`SELECT scope, signature, value FROM _gonvex_replica_queries WHERE scope = ? ORDER BY signature`, scope);
+            const entities = {};
+            let count = 0, bytes = 0, afterEntity = "", afterId = "", finished = false;
+            while (count < budget.maxRows && !finished) {
+                const records = await this.database.getAllAsync(`SELECT scope, entity, id, value FROM _gonvex_replica_entities WHERE scope = ? AND (entity > ? OR (entity = ? AND id > ?)) ORDER BY entity, id LIMIT ?`, scope, afterEntity, afterEntity, afterId, Math.min(256, budget.maxRows - count));
+                if (!records.length)
+                    break;
+                for (const record of records) {
+                    if (record.value === "null")
+                        continue;
+                    const size = record.value.length * 2 + 256;
+                    if (bytes + size > budget.maxBytes) {
+                        finished = true;
+                        break;
+                    }
+                    (entities[record.entity] ??= {})[record.id] = JSON.parse(record.value);
+                    bytes += size;
+                    count++;
+                }
+                const last = records.at(-1);
+                afterEntity = last.entity;
+                afterId = last.id;
+            }
+            if (cursor || queries.length || count)
+                snapshot = {
+                    cursor: cursor ? JSON.parse(cursor.value) : undefined,
+                    entities,
+                    liveQueries: Object.fromEntries(queries.map((row) => [
+                        row.signature,
+                        normalizeWindow(JSON.parse(row.value)),
+                    ])),
+                };
+        });
+        return snapshot;
+    }
+    async loadEntityRows(scope, entity, ids) {
+        await this.initialize();
+        const result = [];
+        for (let offset = 0; offset < ids.length; offset += 256) {
+            const batch = ids.slice(offset, offset + 256);
+            const rows = await this.database.getAllAsync(`SELECT scope, entity, id, value FROM _gonvex_replica_entities WHERE scope = ? AND entity = ? AND id IN (${batch.map(() => "?").join(",")})`, scope, entity, ...batch);
+            const byId = new Map(rows.map((row) => [row.id, row]));
+            for (const id of batch) {
+                const row = byId.get(id);
+                if (row && row.value !== "null")
+                    result.push({ id, row: JSON.parse(row.value) });
+            }
+        }
+        return result;
+    }
+    async loadWindowRows(scope, signature) {
+        await this.initialize();
+        let result;
+        await this.database.withTransactionAsync(async () => {
+            const record = await this.database.getFirstAsync(`SELECT scope, signature, value FROM _gonvex_replica_queries WHERE scope = ? AND signature = ?`, scope, signature);
+            if (!record)
+                return;
+            const window = normalizeWindow(JSON.parse(record.value));
+            result = {
+                window,
+                rows: (await this.loadEntityRows(scope, window.entity, window.ids)).map((entry) => entry.row),
+            };
+        });
+        return result;
+    }
+    async withReadView(scope, coverage, run) {
+        await this.initialize();
+        let result;
+        await this.database.withTransactionAsync(async () => {
+            result = await run(pagedReplicaReadView(coverage, async (read, after) => {
+                const key = coverage[read.table]?.key ?? "_id";
+                const predicate = read.where;
+                const exact = predicate &&
+                    "column" in predicate &&
+                    !predicate.transform &&
+                    predicate.column === key &&
+                    predicate.op === "eq" &&
+                    typeof predicate.value === "string"
+                    ? predicate.value
+                    : undefined;
+                const restriction = (function equality(value) {
+                    if (!value)
+                        return;
+                    if ("and" in value) {
+                        const candidates = value.and
+                            .map(equality)
+                            .filter((candidate) => candidate !== undefined);
+                        return (candidates.find((candidate) => candidate.column === key) ??
+                            candidates[0]);
+                    }
+                    if ("or" in value || value.transform)
+                        return;
+                    const values = value.op === "eq"
+                        ? [value.value]
+                        : value.op === "in"
+                            ? [...value.values]
+                            : undefined;
+                    // Null is deliberately absent from the scalar index. Fall back to a
+                    // bounded scan when it can match, including mixed IN predicates.
+                    if (values?.every((value) => value !== null &&
+                        (typeof value === "number" ||
+                            typeof value === "boolean" ||
+                            (typeof value === "string" && value.length <= 256))))
+                        return { column: value.column, values };
+                })(predicate);
+                let records;
+                if (exact === undefined && restriction) {
+                    const values = restriction.values.map((value) => [
+                        typeof value,
+                        typeof value === "boolean" ? Number(value) : value,
+                    ]);
+                    records = values.length
+                        ? await this.database.getAllAsync(`SELECT e.scope,e.entity,e.id,e.value FROM _gonvex_replica_entities e WHERE e.scope=? AND e.entity=? AND e.id>? AND e.value<>'null' AND e.id IN (SELECT l.id FROM json_each(?) j JOIN _gonvex_replica_lookup l ON l.scope=? AND l.entity=? AND l.column_name=? AND l.kind=json_extract(j.value,'$[0]') AND l.scalar=json_extract(j.value,'$[1]')) ORDER BY e.id LIMIT 256`, scope, read.table, after ?? "", JSON.stringify(values), scope, read.table, restriction.column)
+                        : [];
+                }
+                else
+                    records =
+                        exact !== undefined
+                            ? after
+                                ? []
+                                : await this.database.getAllAsync(`SELECT scope, entity, id, value FROM _gonvex_replica_entities WHERE scope = ? AND entity = ? AND id = ?`, scope, read.table, exact)
+                            : await this.database.getAllAsync(`SELECT scope, entity, id, value FROM _gonvex_replica_entities WHERE scope = ? AND entity = ? AND id > ? AND value <> 'null' ORDER BY id LIMIT 256`, scope, read.table, after ?? "");
+                return records
+                    .filter((record) => record.value !== "null")
+                    .map((record) => ({
+                    id: record.id,
+                    row: JSON.parse(record.value),
+                }));
+            }));
+        });
+        return result;
     }
     async loadSession(scope) {
         await this.initialize();
@@ -109,25 +285,31 @@ export class ExpoSQLiteLocalReplicaStorage {
         await this.initialize();
         await this.database.withTransactionAsync(async () => {
             const previous = await this.database.getFirstAsync(`SELECT scope, key, value FROM _gonvex_replica_meta WHERE scope = ? AND key = 'cursor'`, scope);
-            if (previous && JSON.parse(previous.value).epoch !== transaction.cursor.epoch) {
+            if (previous &&
+                JSON.parse(previous.value).epoch !== transaction.cursor.epoch) {
+                await this.database.runAsync(`DELETE FROM _gonvex_replica_meta WHERE scope = ? AND key LIKE 'row:%'`, scope);
                 await this.database.runAsync(`DELETE FROM _gonvex_replica_entities WHERE scope = ?`, scope);
                 await this.database.runAsync(`DELETE FROM _gonvex_replica_queries WHERE scope = ?`, scope);
             }
+            const grouped = new Map();
             for (const change of transaction.changes) {
-                if (change.operation === "delete") {
-                    await this.database.runAsync(`DELETE FROM _gonvex_replica_entities WHERE scope = ? AND entity = ? AND id = ?`, scope, change.entity, change.id);
-                }
-                else {
-                    await this.database.runAsync(`INSERT INTO _gonvex_replica_entities (scope, entity, id, value) VALUES (?, ?, ?, ?)
-             ON CONFLICT(scope, entity, id) DO UPDATE SET value = excluded.value`, scope, change.entity, change.id, JSON.stringify(change.newValue));
-                }
+                const rows = grouped.get(change.entity) ?? [];
+                rows.push({
+                    id: change.id,
+                    row: change.operation === "delete" ? null : change.newValue,
+                });
+                grouped.set(change.entity, rows);
             }
+            for (const [entity, rows] of grouped)
+                await this.writeRecords(scope, entity, rows, transaction.cursor);
             for (const membership of transaction.memberships ?? []) {
                 await this.database.runAsync(`INSERT INTO _gonvex_replica_queries (scope, signature, value) VALUES (?, ?, ?)
            ON CONFLICT(scope, signature) DO UPDATE SET value = excluded.value`, scope, membership.signature, JSON.stringify(membership));
             }
             await this.database.runAsync(`INSERT INTO _gonvex_replica_meta (scope, key, value) VALUES (?, 'cursor', ?)
-         ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, scope, JSON.stringify(transaction.cursor));
+         ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value
+           WHERE json_extract(_gonvex_replica_meta.value, '$.epoch') <> json_extract(excluded.value, '$.epoch')
+              OR json_extract(_gonvex_replica_meta.value, '$.revision') <= json_extract(excluded.value, '$.revision')`, scope, JSON.stringify(transaction.cursor));
         });
     }
     async advanceWatermark(windows, cursor, scope = defaultReplicaScope) {
@@ -141,7 +323,9 @@ export class ExpoSQLiteLocalReplicaStorage {
             }
             if (cursor) {
                 await this.database.runAsync(`INSERT INTO _gonvex_replica_meta (scope, key, value) VALUES (?, 'cursor', ?)
-           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, scope, JSON.stringify(cursor));
+           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value
+           WHERE json_extract(_gonvex_replica_meta.value, '$.epoch') <> json_extract(excluded.value, '$.epoch')
+              OR json_extract(_gonvex_replica_meta.value, '$.revision') <= json_extract(excluded.value, '$.revision')`, scope, JSON.stringify(cursor));
             }
         });
     }
@@ -150,7 +334,7 @@ export class ExpoSQLiteLocalReplicaStorage {
         await this.database.withTransactionAsync(async () => {
             await this.database.runAsync(`DELETE FROM _gonvex_replica_entities WHERE scope = ?`, scope);
             await this.database.runAsync(`DELETE FROM _gonvex_replica_queries WHERE scope = ?`, scope);
-            await this.database.runAsync(`DELETE FROM _gonvex_replica_meta WHERE scope = ? AND key = 'cursor'`, scope);
+            await this.database.runAsync(`DELETE FROM _gonvex_replica_meta WHERE scope = ? AND (key = 'cursor' OR key LIKE 'row:%')`, scope);
             for (const [entity, rows] of Object.entries(snapshot.entities)) {
                 for (const [id, value] of Object.entries(rows)) {
                     await this.database.runAsync(`INSERT INTO _gonvex_replica_entities (scope, entity, id, value) VALUES (?, ?, ?, ?)`, scope, entity, id, JSON.stringify(value));
@@ -161,29 +345,96 @@ export class ExpoSQLiteLocalReplicaStorage {
             }
             if (snapshot.cursor) {
                 await this.database.runAsync(`INSERT INTO _gonvex_replica_meta (scope, key, value) VALUES (?, 'cursor', ?)
-           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, scope, JSON.stringify(snapshot.cursor));
+           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value
+           WHERE json_extract(_gonvex_replica_meta.value, '$.epoch') <> json_extract(excluded.value, '$.epoch')
+              OR json_extract(_gonvex_replica_meta.value, '$.revision') <= json_extract(excluded.value, '$.revision')`, scope, JSON.stringify(snapshot.cursor));
             }
         });
     }
-    async replaceWindow(window, snapshot, scope = defaultReplicaScope) {
+    async writeRecords(scope, entity, rows, cursor) {
+        const previous = new Map((await this.loadEntityRows(scope, entity, rows.map((row) => row.id))).map((entry) => [entry.id, entry.row]));
+        for (let offset = 0; offset < rows.length; offset += 100) {
+            const batch = rows.slice(offset, offset + 100);
+            const authorityKey = (id) => `row:${JSON.stringify([entity, id])}`;
+            const records = cursor
+                ? await this.database.getAllAsync(`SELECT scope,key,value FROM _gonvex_replica_meta WHERE scope=? AND key IN (${batch.map(() => "?").join(",")})`, scope, ...batch.map((entry) => authorityKey(entry.id)))
+                : [];
+            const authorities = new Map(records.map((record) => [
+                record.key,
+                JSON.parse(record.value),
+            ]));
+            const versions = batch.map(({ id, row }) => {
+                const old = previous.get(id) ?? null;
+                if (!cursor)
+                    return {
+                        id,
+                        row: row === null ? null : { ...old, ...row },
+                        authority: undefined,
+                    };
+                const prior = authorities.get(authorityKey(id)) ?? {
+                    epoch: cursor.epoch,
+                    fields: Object.fromEntries(Object.keys(old ?? {}).map((key) => [key, 0])),
+                };
+                return {
+                    id,
+                    ...mergeReplicaRecord({ row: old, authority: prior }, row, cursor),
+                };
+            });
+            const params = versions.flatMap(({ id, row }) => [
+                scope,
+                entity,
+                id,
+                JSON.stringify(row),
+            ]);
+            await this.database.runAsync(`INSERT INTO _gonvex_replica_entities (scope,entity,id,value) VALUES ${batch.map(() => "(?,?,?,?)").join(",")} ON CONFLICT(scope,entity,id) DO UPDATE SET value=excluded.value`, ...params);
+            if (cursor)
+                await this.database.runAsync(`INSERT INTO _gonvex_replica_meta(scope,key,value) VALUES ${batch.map(() => "(?,?,?)").join(",")} ON CONFLICT(scope,key) DO UPDATE SET value=excluded.value`, ...versions.flatMap(({ id, authority }) => [
+                    scope,
+                    authorityKey(id),
+                    JSON.stringify(authority),
+                ]));
+        }
+    }
+    async replaceWindow(window, snapshot, scope = defaultReplicaScope, projection) {
         await this.initialize();
         await this.database.withTransactionAsync(async () => {
-            for (const [entity, rows] of Object.entries(snapshot.entities)) {
-                for (const [id, value] of Object.entries(rows)) {
-                    await this.database.runAsync(`INSERT INTO _gonvex_replica_entities (scope, entity, id, value) VALUES (?, ?, ?, ?)
-             ON CONFLICT(scope, entity, id) DO UPDATE SET value = excluded.value`, scope, entity, id, JSON.stringify(value));
-                }
-            }
+            const oldRecord = await this.database.getFirstAsync(`SELECT scope,signature,value FROM _gonvex_replica_queries WHERE scope=? AND signature=?`, scope, window.signature);
+            const oldWindow = oldRecord
+                ? JSON.parse(oldRecord.value)
+                : undefined;
+            if (oldWindow?.cursor &&
+                window.cursor &&
+                oldWindow.cursor.epoch === window.cursor.epoch &&
+                oldWindow.cursor.revision > window.cursor.revision)
+                return;
+            const rows = projection ??
+                window.ids
+                    .map((id) => snapshot.entities[window.entity]?.[id])
+                    .filter((row) => row !== undefined);
+            await this.writeRecords(scope, window.entity, rows.map((row) => ({ id: String(row[window.key]), row })), window.cursor);
             await this.database.runAsync(`INSERT INTO _gonvex_replica_queries (scope, signature, value) VALUES (?, ?, ?)
          ON CONFLICT(scope, signature) DO UPDATE SET value = excluded.value`, scope, window.signature, JSON.stringify(normalizeWindow(window)));
+            const removed = oldWindow?.ids.filter((id) => !window.ids.includes(id)) ?? [];
+            if (removed.length) {
+                const windows = await this.database.getAllAsync(`SELECT scope,signature,value FROM _gonvex_replica_queries WHERE scope=?`, scope);
+                const retained = new Set(windows.flatMap((record) => {
+                    const other = JSON.parse(record.value);
+                    return other.entity === window.entity ? other.ids : [];
+                }));
+                await this.writeRecords(scope, window.entity, removed
+                    .filter((id) => !retained.has(id))
+                    .map((id) => ({ id, row: null })), window.cursor);
+            }
             if (snapshot.cursor) {
                 await this.database.runAsync(`INSERT INTO _gonvex_replica_meta (scope, key, value) VALUES (?, 'cursor', ?)
-           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, scope, JSON.stringify(snapshot.cursor));
+           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value
+           WHERE json_extract(_gonvex_replica_meta.value, '$.epoch') <> json_extract(excluded.value, '$.epoch')
+              OR json_extract(_gonvex_replica_meta.value, '$.revision') <= json_extract(excluded.value, '$.revision')`, scope, JSON.stringify(snapshot.cursor));
             }
         });
     }
-    async applyWindowDelta(window, _delta, snapshot, scope = defaultReplicaScope) {
-        await this.replaceWindow(window, snapshot, scope);
+    async applyWindowDelta(window, delta, snapshot, scope = defaultReplicaScope) {
+        await this.replaceWindow(window, snapshot, scope, delta.upserts);
     }
     async removeWindow(signature, snapshot, scope = defaultReplicaScope) {
         await this.initialize();
@@ -191,7 +442,9 @@ export class ExpoSQLiteLocalReplicaStorage {
             await this.database.runAsync(`DELETE FROM _gonvex_replica_queries WHERE scope = ? AND signature = ?`, scope, signature);
             if (snapshot.cursor) {
                 await this.database.runAsync(`INSERT INTO _gonvex_replica_meta (scope, key, value) VALUES (?, 'cursor', ?)
-           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value`, scope, JSON.stringify(snapshot.cursor));
+           ON CONFLICT(scope, key) DO UPDATE SET value = excluded.value
+           WHERE json_extract(_gonvex_replica_meta.value, '$.epoch') <> json_extract(excluded.value, '$.epoch')
+              OR json_extract(_gonvex_replica_meta.value, '$.revision') <= json_extract(excluded.value, '$.revision')`, scope, JSON.stringify(snapshot.cursor));
             }
         });
     }
@@ -204,6 +457,7 @@ export class ExpoSQLiteLocalReplicaStorage {
         });
     }
 }
+export * from "./outbox.js";
 export function expoSQLite(database) {
     return new ExpoSQLiteLocalReplicaStorage(database);
 }

package/dist/outbox.d.ts

@@ -0,0 +1,71 @@
+import type { OutboxStore, ReducerOutboxEntry } from "@gonvex/client";
+import type { ExpoSQLiteDatabase } from "./index.js";
+/**
+ * Durable reducer outbox storage on Expo SQLite.
+ *
+ * One row per intent, keyed by the SDK's sequence id, with every mutation in
+ * its own SQLite transaction. Unlike a single JSON blob rewritten on each
+ * change, an update touches one row and a crash can never truncate the whole
+ * queue. Ids come from a persisted sequence, so a deleted entry's id is never
+ * reused across restarts.
+ *
+ * Pass the same database handle that backs the Local Replica or a dedicated
+ * one; the tables are prefixed with `_gonvex_outbox`.
+ */
+export declare class ExpoSQLiteOutboxStore implements OutboxStore {
+    private readonly database;
+    readonly strictPersistence = false;
+    private initialized?;
+    private queue;
+    constructor(database: ExpoSQLiteDatabase);
+    load(scope?: string): Promise<ReducerOutboxEntry[]>;
+    put(entry: ReducerOutboxEntry): Promise<void>;
+    delete(id: number): Promise<void>;
+    clear(scope?: string): Promise<void>;
+    allocateId(): Promise<number>;
+    append(draft: Omit<ReducerOutboxEntry, "id">): Promise<ReducerOutboxEntry>;
+    update(id: number, change: (entry: ReducerOutboxEntry) => ReducerOutboxEntry): Promise<ReducerOutboxEntry | undefined>;
+    /**
+     * Import entries from a legacy whole-list JSON blob (for example the value
+     * an app kept under an AsyncStorage key). Runs in one transaction and is
+     * idempotent: an entry whose scope and idempotency key already exist is
+     * skipped, so re-running after a crash never duplicates an intent. Legacy
+     * ids are preserved to keep enqueue order; an id already taken by a
+     * different intent gets a fresh sequence id.
+     */
+    importLegacy(legacy: string | readonly unknown[] | null | undefined): Promise<LegacyOutboxImport>;
+    private initialize;
+    /**
+     * Expo's withTransactionAsync is not exclusive against other statements on
+     * the same connection. Serialize this store's own work so two outbox
+     * transactions never interleave.
+     */
+    private serial;
+    private transaction;
+    private reserveId;
+    private write;
+}
+export type LegacyOutboxImport = {
+    imported: number;
+    /** Entries already present (same scope and idempotency key). */
+    skipped: number;
+    /** Values that were not recognizable outbox entries. */
+    invalid: number;
+};
+export declare function expoSQLiteOutbox(database: ExpoSQLiteDatabase): ExpoSQLiteOutboxStore;
+/** The subset of AsyncStorage the one-time migration needs. */
+export type LegacyKeyValueStorage = {
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+};
+/**
+ * One-time move of a legacy AsyncStorage outbox blob into SQLite. Run it
+ * before constructing the GonvexClient. The legacy key is removed only after
+ * the import committed; an unreadable blob throws and is left untouched so no
+ * intent is ever lost. Safe to call on every launch.
+ */
+export declare function migrateLegacyOutbox(options: {
+    store: ExpoSQLiteOutboxStore;
+    storage: LegacyKeyValueStorage;
+    key: string;
+}): Promise<LegacyOutboxImport>;

package/dist/outbox.js

@@ -0,0 +1,207 @@
+const outboxStates = new Set(["pending", "inflight", "committed", "failed", "rejected"]);
+/**
+ * Durable reducer outbox storage on Expo SQLite.
+ *
+ * One row per intent, keyed by the SDK's sequence id, with every mutation in
+ * its own SQLite transaction. Unlike a single JSON blob rewritten on each
+ * change, an update touches one row and a crash can never truncate the whole
+ * queue. Ids come from a persisted sequence, so a deleted entry's id is never
+ * reused across restarts.
+ *
+ * Pass the same database handle that backs the Local Replica or a dedicated
+ * one; the tables are prefixed with `_gonvex_outbox`.
+ */
+export class ExpoSQLiteOutboxStore {
+    database;
+    strictPersistence = false;
+    initialized;
+    queue = Promise.resolve();
+    constructor(database) {
+        this.database = database;
+    }
+    load(scope) {
+        return this.serial(async () => {
+            const rows = scope === undefined
+                ? await this.database.getAllAsync(`SELECT value FROM _gonvex_outbox ORDER BY id`)
+                : await this.database.getAllAsync(`SELECT value FROM _gonvex_outbox WHERE scope = ? ORDER BY id`, scope);
+            const entries = [];
+            for (const row of rows) {
+                const entry = parseEntry(row.value);
+                if (entry)
+                    entries.push(entry);
+            }
+            return entries;
+        });
+    }
+    put(entry) {
+        return this.serial(() => this.transaction(() => this.write(entry)));
+    }
+    delete(id) {
+        return this.serial(async () => {
+            await this.database.runAsync(`DELETE FROM _gonvex_outbox WHERE id = ?`, id);
+        });
+    }
+    clear(scope) {
+        return this.serial(async () => {
+            if (scope === undefined)
+                await this.database.runAsync(`DELETE FROM _gonvex_outbox`);
+            else
+                await this.database.runAsync(`DELETE FROM _gonvex_outbox WHERE scope = ?`, scope);
+        });
+    }
+    allocateId() {
+        return this.serial(() => this.transaction(() => this.reserveId()));
+    }
+    append(draft) {
+        return this.serial(() => this.transaction(async () => {
+            const entry = { ...draft, id: await this.reserveId() };
+            await this.write(entry);
+            return entry;
+        }));
+    }
+    update(id, change) {
+        return this.serial(() => this.transaction(async () => {
+            const row = await this.database.getFirstAsync(`SELECT value FROM _gonvex_outbox WHERE id = ?`, id);
+            const prior = row ? parseEntry(row.value) : undefined;
+            if (!prior)
+                return undefined;
+            const next = change(prior);
+            if (next.id !== prior.id || next.scope !== prior.scope || next.idempotencyKey !== prior.idempotencyKey) {
+                throw new Error("Outbox identity cannot change");
+            }
+            if (JSON.stringify(next) !== JSON.stringify(prior))
+                await this.write(next);
+            return next;
+        }));
+    }
+    /**
+     * Import entries from a legacy whole-list JSON blob (for example the value
+     * an app kept under an AsyncStorage key). Runs in one transaction and is
+     * idempotent: an entry whose scope and idempotency key already exist is
+     * skipped, so re-running after a crash never duplicates an intent. Legacy
+     * ids are preserved to keep enqueue order; an id already taken by a
+     * different intent gets a fresh sequence id.
+     */
+    importLegacy(legacy) {
+        const parsed = typeof legacy === "string" ? JSON.parse(legacy) : legacy;
+        if (parsed === null || parsed === undefined)
+            return Promise.resolve({ imported: 0, skipped: 0, invalid: 0 });
+        if (!Array.isArray(parsed))
+            return Promise.reject(new Error("Legacy Gonvex outbox must be a JSON array"));
+        return this.serial(() => this.transaction(async () => {
+            const sorted = parsed
+                .map((value) => validEntry(value))
+                .filter((entry) => entry !== undefined)
+                .sort((left, right) => left.id - right.id);
+            const result = { imported: 0, skipped: 0, invalid: parsed.length - sorted.length };
+            for (const entry of sorted) {
+                const existing = await this.database.getFirstAsync(`SELECT id FROM _gonvex_outbox WHERE scope = ? AND idempotency_key = ?`, entry.scope, entry.idempotencyKey);
+                if (existing) {
+                    result.skipped += 1;
+                    continue;
+                }
+                const taken = await this.database.getFirstAsync(`SELECT id FROM _gonvex_outbox WHERE id = ?`, entry.id);
+                // A legacy row that was mid-send when the app died is resumed exactly
+                // like the SDK's own crash recovery: back to pending, same key.
+                const imported = {
+                    ...entry,
+                    ...(taken ? { id: await this.reserveId() } : {}),
+                    ...(entry.state === "inflight" ? { state: "pending" } : {}),
+                };
+                await this.write(imported);
+                result.imported += 1;
+            }
+            return result;
+        }));
+    }
+    initialize() {
+        return (this.initialized ??= this.database.withTransactionAsync(async () => {
+            await this.database.execAsync(`
+        CREATE TABLE IF NOT EXISTS _gonvex_outbox (
+          id INTEGER PRIMARY KEY,
+          scope TEXT NOT NULL,
+          idempotency_key TEXT NOT NULL,
+          state TEXT NOT NULL,
+          value TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS _gonvex_outbox_scope ON _gonvex_outbox(scope, id);
+        CREATE UNIQUE INDEX IF NOT EXISTS _gonvex_outbox_intent ON _gonvex_outbox(scope, idempotency_key);
+        CREATE TABLE IF NOT EXISTS _gonvex_outbox_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+      `);
+        }).catch((error) => {
+            this.initialized = undefined;
+            throw error;
+        }));
+    }
+    /**
+     * Expo's withTransactionAsync is not exclusive against other statements on
+     * the same connection. Serialize this store's own work so two outbox
+     * transactions never interleave.
+     */
+    serial(run) {
+        const job = this.queue.then(async () => {
+            await this.initialize();
+            return run();
+        });
+        this.queue = job.catch(() => undefined);
+        return job;
+    }
+    async transaction(run) {
+        let result;
+        await this.database.withTransactionAsync(async () => { result = await run(); });
+        return result;
+    }
+    async reserveId() {
+        const counter = await this.database.getFirstAsync(`SELECT value FROM _gonvex_outbox_meta WHERE key = 'sequence'`);
+        const highest = await this.database.getFirstAsync(`SELECT MAX(id) AS id FROM _gonvex_outbox`);
+        const id = Math.max(Number(counter?.value ?? 0), Number(highest?.id ?? 0)) + 1;
+        await this.database.runAsync(`INSERT INTO _gonvex_outbox_meta (key, value) VALUES ('sequence', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, id);
+        return id;
+    }
+    async write(entry) {
+        await this.database.runAsync(`INSERT OR REPLACE INTO _gonvex_outbox (id, scope, idempotency_key, state, value) VALUES (?, ?, ?, ?, ?)`, entry.id, entry.scope, entry.idempotencyKey, entry.state, JSON.stringify(entry));
+    }
+}
+export function expoSQLiteOutbox(database) {
+    return new ExpoSQLiteOutboxStore(database);
+}
+/**
+ * One-time move of a legacy AsyncStorage outbox blob into SQLite. Run it
+ * before constructing the GonvexClient. The legacy key is removed only after
+ * the import committed; an unreadable blob throws and is left untouched so no
+ * intent is ever lost. Safe to call on every launch.
+ */
+export async function migrateLegacyOutbox(options) {
+    const raw = await options.storage.getItem(options.key);
+    if (raw === null || raw === undefined)
+        return { imported: 0, skipped: 0, invalid: 0 };
+    const result = await options.store.importLegacy(raw);
+    await options.storage.removeItem(options.key);
+    return result;
+}
+function parseEntry(value) {
+    try {
+        return validEntry(JSON.parse(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function validEntry(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const entry = value;
+    if (typeof entry.id !== "number" || !Number.isSafeInteger(entry.id) || entry.id <= 0
+        || typeof entry.scope !== "string" || entry.scope.length === 0
+        || typeof entry.path !== "string"
+        || typeof entry.idempotencyKey !== "string" || entry.idempotencyKey.length === 0
+        || typeof entry.state !== "string" || !outboxStates.has(entry.state))
+        return undefined;
+    return {
+        ...entry,
+        entityKeys: Array.isArray(entry.entityKeys) ? entry.entityKeys : [],
+        createdAt: typeof entry.createdAt === "number" ? entry.createdAt : 0,
+        attempts: typeof entry.attempts === "number" ? entry.attempts : 0,
+        nextAttemptAt: typeof entry.nextAttemptAt === "number" ? entry.nextAttemptAt : 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonvex/expo-sqlite",
-  "version": "0.5.2-staging.13",
+  "version": "0.5.2-staging.15",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@gonvex/client": "0.5.2-staging.13"
+    "@gonvex/client": "0.5.2-staging.15"
   },
   "devDependencies": {
     "typescript": "^6.0.3",