@koolbase/core 12.12.0 → 12.13.1

package/dist/cjs/cache-store.d.ts

@@ -58,3 +58,12 @@ export declare function addToWriteQueue(userId: string, write: Omit<LegacyPendin
 export declare function removeFromWriteQueue(userId: string, writeId: string): Promise<void>;
 export declare function incrementWriteRetry(userId: string, writeId: string): Promise<void>;
 export declare function optimisticallyInsert(userId: string, collection: string, record: KoolbaseRecord): Promise<void>;
+/**
+ * The reverse of optimisticallyInsert: takes one record out of every cached
+ * result of a collection.
+ *
+ * Precise on purpose. Dropping the collection's cached results instead would
+ * leave a device that is still offline with no saved lists to show at all,
+ * to get rid of one record.
+ */
+export declare function removeFromCachedQueries(userId: string, collection: string, recordId: string): Promise<void>;

package/dist/cjs/cache-store.js

@@ -13,6 +13,7 @@ exports.addToWriteQueue = addToWriteQueue;
 exports.removeFromWriteQueue = removeFromWriteQueue;
 exports.incrementWriteRetry = incrementWriteRetry;
 exports.optimisticallyInsert = optimisticallyInsert;
+exports.removeFromCachedQueries = removeFromCachedQueries;
 const platform_js_1 = require("./platform.js");
 const CACHE_VERSION = 'v1';
 function cacheKey(userId, collection, queryHash) {
@@ -211,3 +212,35 @@ async function optimisticallyInsert(userId, collection, record) {
         // ignore
     }
 }
+/**
+ * The reverse of optimisticallyInsert: takes one record out of every cached
+ * result of a collection.
+ *
+ * Precise on purpose. Dropping the collection's cached results instead would
+ * leave a device that is still offline with no saved lists to show at all,
+ * to get rid of one record.
+ */
+async function removeFromCachedQueries(userId, collection, recordId) {
+    try {
+        const keys = await (0, platform_js_1.getPlatform)().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        for (const key of keys.filter(k => k.startsWith(prefix))) {
+            const raw = await (0, platform_js_1.getPlatform)().storage.getItem(key);
+            if (!raw)
+                continue;
+            const cached = JSON.parse(raw);
+            if (!Array.isArray(cached.records))
+                continue;
+            const kept = cached.records.filter(r => r.id !== recordId);
+            const removed = cached.records.length - kept.length;
+            if (removed === 0)
+                continue;
+            cached.records = kept;
+            cached.total = Math.max(0, cached.total - removed);
+            await (0, platform_js_1.getPlatform)().storage.setItem(key, JSON.stringify(cached));
+        }
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/cjs/collection-controller.d.ts

@@ -11,8 +11,9 @@ export interface CollectionQuery {
     /**
      * Re-read page one, silently, when Koolbase realtime reports a record
      * created, updated or deleted in this collection (debounced: a burst is one
-     * read). Realtime needs a signed-in user; until there is one, the list
-     * behaves as a normal list and goes live once the session exists.
+     * read). Signed out, only a collection anyone can read (read rule
+     * "public") is live; any other behaves as a normal list until a user signs
+     * in, and goes live then.
      */
     live?: boolean;
 }

package/dist/cjs/database.d.ts

@@ -173,6 +173,15 @@ export declare class KoolbaseDatabase {
      */
     private requireUserId;
     private requireConflict;
+    /**
+     * Removes a decided conflict and points the writes held behind it at the
+     * state the record is now in -- in one transaction, so the conflict can
+     * never be gone while its held writes still describe the old world.
+     *
+     * Without a known state (a refused add, a delete) there is nothing to
+     * rebase onto: the conflict is removed and the held writes stay as they are.
+     */
+    private settleConflict;
     private dropConflict;
     /**
      * Issues the resolving write, conditional on the revision the refusal

package/dist/cjs/database.js

@@ -65,12 +65,15 @@ class KoolbaseDatabase {
             resolveWithServer: async (id) => {
                 const c = await this.requireConflict(id);
                 // The server's version stands. Recorded as a decision by removing the
-                // conflict, rather than the change quietly disappearing.
-                await this.dropConflict(c.id);
+                // conflict, rather than the change quietly disappearing -- and what
+                // stands is what the writes held behind it now build on.
+                await this.settleConflict(c, c.server, c.serverRevision);
             },
             abandon: async (id) => {
                 const c = await this.requireConflict(id);
-                await this.dropConflict(c.id);
+                // Neither version claimed to win, so the record stands as the server
+                // has it: what anything still queued must build on.
+                await this.settleConflict(c, c.server, c.serverRevision);
             },
         };
         this.config = config;
@@ -540,6 +543,25 @@ class KoolbaseDatabase {
         }
         return found;
     }
+    /**
+     * Removes a decided conflict and points the writes held behind it at the
+     * state the record is now in -- in one transaction, so the conflict can
+     * never be gone while its held writes still describe the old world.
+     *
+     * Without a known state (a refused add, a delete) there is nothing to
+     * rebase onto: the conflict is removed and the held writes stay as they are.
+     */
+    async settleConflict(c, resolved, revision) {
+        if (!resolved || !c.recordId) {
+            await this.dropConflict(c.id);
+            return;
+        }
+        const userId = this.requireUserId('conflict resolution');
+        await (0, offline_state_js_1.mutateOfflineState)(userId, (s) => {
+            s.conflicts = s.conflicts.filter((x) => x.id !== c.id);
+            (0, offline_state_js_1.rebaseHeldWrites)(s, c.recordId, resolved, revision);
+        });
+    }
     async dropConflict(id) {
         const userId = this.requireUserId('conflict resolution');
         await (0, offline_state_js_1.mutateOfflineState)(userId, (s) => {
@@ -554,6 +576,8 @@ class KoolbaseDatabase {
      */
     async applyResolution(c, payload) {
         const rev = c.serverRevision;
+        // What the server now holds, from its answer: the state held writes build on.
+        let landed = null;
         try {
             if (c.operation === 'insert') {
                 // Resolving a rejected insert IS the insert, retried — with amended
@@ -564,7 +588,7 @@ class KoolbaseDatabase {
                 // original on retry rather than duplicating — the queue's own
                 // lost-response discipline, extended to the one insert path that
                 // lacked it.
-                await this.request('POST', '/v1/sdk/db/insert', {
+                landed = await this.request('POST', '/v1/sdk/db/insert', {
                     collection: c.collection,
                     data: payload,
                     idempotency_key: c.id,
@@ -575,7 +599,7 @@ class KoolbaseDatabase {
                 await this.request('DELETE', `/v1/sdk/db/records/${c.recordId}${q}`);
             }
             else {
-                await this.request('PATCH', `/v1/sdk/db/records/${c.recordId}`, { data: payload, ...(rev !== undefined ? { expected_revision: rev } : {}) });
+                landed = await this.request('PATCH', `/v1/sdk/db/records/${c.recordId}`, { data: payload, ...(rev !== undefined ? { expected_revision: rev } : {}) });
             }
         }
         catch (e) {
@@ -604,7 +628,8 @@ class KoolbaseDatabase {
             }
             throw e;
         }
-        await this.dropConflict(c.id);
+        const landedRevision = landed && typeof landed.$revision === 'number' ? landed.$revision : undefined;
+        await this.settleConflict(c, landed ?? undefined, landedRevision);
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
         void (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
     }

package/dist/cjs/offline-state.d.ts

@@ -103,3 +103,19 @@ export declare function queueWrite(userId: string, write: Omit<QueuedWrite, 'ret
  * and nothing is written on a guess.
  */
 export declare function migrateLegacyQueue(userId: string): Promise<void>;
+/**
+ * Points the writes still queued for a record at the state it is now in.
+ *
+ * When a conflict is decided, the writes held behind it carry baselines
+ * describing the state the conflicted write would have produced -- a state
+ * that no longer exists, and may never have. Released unchanged they would
+ * replay against a revision that has moved on, and each would conflict in
+ * turn: one disagreement multiplying into as many conflicts as the user had
+ * queued. The same rule as the Flutter SDK's rebaseAfterResolution.
+ *
+ * Refreshing the baseline is enough because every operation is an absolute
+ * assignment: a patch says what a field becomes, not what to do to it. If a
+ * relative operation is ever added (an increment, an append), the chain must
+ * be replayed through its projected states instead.
+ */
+export declare function rebaseHeldWrites(state: OfflineState, recordId: string, resolved: Record<string, unknown>, revision: number | undefined): void;

package/dist/cjs/offline-state.js

@@ -8,6 +8,7 @@ exports.readOfflineState = readOfflineState;
 exports.mutateOfflineState = mutateOfflineState;
 exports.queueWrite = queueWrite;
 exports.migrateLegacyQueue = migrateLegacyQueue;
+exports.rebaseHeldWrites = rebaseHeldWrites;
 const platform_js_1 = require("./platform.js");
 const shared_js_1 = require("./shared.js");
 /**
@@ -213,3 +214,36 @@ async function migrateLegacyQueue(userId) {
     });
     await (0, platform_js_1.getPlatform)().storage.removeItem(legacyQueueKey(userId));
 }
+/**
+ * Points the writes still queued for a record at the state it is now in.
+ *
+ * When a conflict is decided, the writes held behind it carry baselines
+ * describing the state the conflicted write would have produced -- a state
+ * that no longer exists, and may never have. Released unchanged they would
+ * replay against a revision that has moved on, and each would conflict in
+ * turn: one disagreement multiplying into as many conflicts as the user had
+ * queued. The same rule as the Flutter SDK's rebaseAfterResolution.
+ *
+ * Refreshing the baseline is enough because every operation is an absolute
+ * assignment: a patch says what a field becomes, not what to do to it. If a
+ * relative operation is ever added (an increment, an append), the chain must
+ * be replayed through its projected states instead.
+ */
+function rebaseHeldWrites(state, recordId, resolved, revision) {
+    let current = {};
+    for (const [k, v] of Object.entries(resolved)) {
+        if (!k.startsWith('$'))
+            current[k] = v;
+    }
+    for (const w of state.pending) {
+        if (w.recordId !== recordId)
+            continue;
+        w.baseline = { ...current };
+        w.baseRevision = revision;
+        // Each write is composed against the one before it.
+        if (w.operation === 'update')
+            current = { ...current, ...(w.data ?? {}) };
+        else if (w.operation === 'delete')
+            break;
+    }
+}

package/dist/cjs/realtime.d.ts

@@ -9,6 +9,9 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private anonymous;
+    private connectedAs;
+    private generation;
     private idleTimer;
     /** How long an unused connection stays open, in ms: a screen that comes
      *  straight back (navigating back, React's development double start)
@@ -30,6 +33,9 @@ export declare class KoolbaseRealtime {
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    private send;
     /**
      * Reconnects with backoff, rather than every three seconds forever.
      *
@@ -51,6 +57,16 @@ export declare class KoolbaseRealtime {
      * it: reconnecting needs a subscriber.
      */
     private scheduleIdleClose;
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged(): void;
     disconnect(): void;
 }
 export {};

package/dist/cjs/realtime.js

@@ -41,6 +41,15 @@ class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // The open connection is a signed-out visitor's (the public key): its
+        // messages leave project_id out.
+        this.anonymous = false;
+        // Whose session the open connection was made for: the user id, or null
+        // when signed out. sessionChanged compares against it.
+        this.connectedAs = null;
+        // Bumped by sessionChanged: a connect still waiting for its token gives up
+        // rather than open a connection for the old session.
+        this.generation = 0;
         // Pending close of an unused connection (scheduleIdleClose); null while
         // anyone is subscribed.
         this.idleTimer = null;
@@ -101,28 +110,49 @@ class KoolbaseRealtime {
         // double start -- found nobody connecting and opened its own socket; only
         // the last was remembered, and the others stayed open for good.
         this.connecting = true;
+        const generation = this.generation;
         let token;
         try {
             token = await this.getToken();
         }
         catch {
-            token = null;
+            // A session that could not be refreshed is still a session: try again
+            // later, never as a signed-out visitor.
+            if (generation !== this.generation)
+                return;
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
         }
+        // The session changed while the token was on its way: sessionChanged
+        // has started the connection for the new one.
+        if (generation !== this.generation)
+            return;
         if (this.listeners.size === 0) {
             // Everyone left while the token was on its way: nothing to connect for.
             this.connecting = false;
             return;
         }
-        if (!token) {
+        const userId = this.getUserId?.() ?? null;
+        if (!token && userId) {
+            // Signed in, but no usable token right now: try again later rather
+            // than drop to public-only.
             this.connecting = false;
-            this.scheduleReconnect(); // sign-in may be in flight
+            this.scheduleReconnect();
             return;
         }
-        this.projectId = projectIdFromToken(token);
+        // Signed out: the project's public key, and only collections anyone can
+        // read. The server pins the connection to the key's project.
+        this.anonymous = !token;
+        this.connectedAs = token ? userId : null;
+        this.projectId = token ? projectIdFromToken(token) : null;
+        const credential = token
+            ? `token=${encodeURIComponent(token)}`
+            : `public_key=${encodeURIComponent(this.config.publicKey)}`;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
         let ws;
         try {
-            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?${credential}`);
         }
         catch {
             this.connecting = false;
@@ -186,14 +216,22 @@ class KoolbaseRealtime {
         ws.onerror = () => { };
     }
     sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+        this.send('subscribe', collection);
     }
     sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+        this.send('unsubscribe', collection);
+    }
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    send(action, collection) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+        if (this.anonymous) {
+            this.ws.send(JSON.stringify({ action, collection }));
+        }
+        else if (this.projectId) {
+            this.ws.send(JSON.stringify({ action, project_id: this.projectId, collection }));
+        }
     }
     /**
      * Reconnects with backoff, rather than every three seconds forever.
@@ -252,6 +290,42 @@ class KoolbaseRealtime {
         }, KoolbaseRealtime.idleGraceMs);
         this.idleTimer.unref?.();
     }
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged() {
+        if (!this.ws && !this.connecting && !this.reconnectTimer)
+            return;
+        if (this.ws && !this.connecting && (this.getUserId?.() ?? null) === this.connectedAs)
+            return;
+        this.generation += 1;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.connecting = false;
+        this.anonymous = false;
+        this.projectId = null;
+        this.reconnectAttempts = 0;
+        if (ws) {
+            // Detached first: this close is ours, not a dropped connection.
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+            ws.close();
+        }
+        if (this.listeners.size > 0)
+            void this.connect();
+    }
     disconnect() {
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);

package/dist/cjs/sync-engine.js

@@ -101,13 +101,21 @@ class SyncEngine {
             // being online — would give the same input different outcomes. It clears
             // the old key when done, so later calls find nothing and return.
             await (0, offline_state_js_1.migrateLegacyQueue)(userId);
-            const { pending } = await (0, offline_state_js_1.readOfflineState)(userId);
+            const { pending, conflicts } = await (0, offline_state_js_1.readOfflineState)(userId);
             if (pending.length === 0)
                 return;
             // Records whose chain stopped this pass. Writes queued after a conflicted
             // one were composed against the state it would have produced, so applying
             // them now would write against a state their baseline never described.
             const blocked = new Set();
+            // And records whose chain stopped in an EARLIER pass: a conflict waits
+            // for a decision across restarts, and so must the writes behind it.
+            // Seeded only from this pass's finds, the next pass replayed them
+            // against a state their baselines never described -- each becoming its
+            // own conflict. Deciding the conflict rebases and releases them.
+            for (const c of conflicts)
+                if (c.recordId)
+                    blocked.add(c.recordId);
             for (const queued of pending) {
                 if (queued.recordId && blocked.has(queued.recordId))
                     continue;
@@ -202,10 +210,15 @@ class SyncEngine {
                         // — cached at enqueue for a record the server refused to create.
                         // Left alone it is a phantom: it renders as saved, and an offline
                         // edit against it queues a write to a record that does not exist.
-                        // Evict it, and invalidate the collection so cached queries stop
-                        // serving it. The conflict above keeps the user's data and the
-                        // server's verdict; the cache stops testifying to a fiction.
-                        // MUTATION: phantom eviction removed
+                        // Evict it from the record cache and from every cached query that
+                        // holds it -- precisely, not by dropping the collection's saved
+                        // results, which a device still offline needs. The conflict above
+                        // keeps the user's data and the server's verdict; the cache stops
+                        // testifying to a fiction.
+                        if (write.operation === 'insert' && write.recordId) {
+                            await (0, cache_store_js_1.removeCachedRecord)(userId, write.recordId);
+                            await (0, cache_store_js_1.removeFromCachedQueries)(userId, write.collection, write.recordId);
+                        }
                         if (write.recordId)
                             blocked.add(write.recordId);
                         continue;

package/dist/esm/cache-store.d.ts

@@ -58,3 +58,12 @@ export declare function addToWriteQueue(userId: string, write: Omit<LegacyPendin
 export declare function removeFromWriteQueue(userId: string, writeId: string): Promise<void>;
 export declare function incrementWriteRetry(userId: string, writeId: string): Promise<void>;
 export declare function optimisticallyInsert(userId: string, collection: string, record: KoolbaseRecord): Promise<void>;
+/**
+ * The reverse of optimisticallyInsert: takes one record out of every cached
+ * result of a collection.
+ *
+ * Precise on purpose. Dropping the collection's cached results instead would
+ * leave a device that is still offline with no saved lists to show at all,
+ * to get rid of one record.
+ */
+export declare function removeFromCachedQueries(userId: string, collection: string, recordId: string): Promise<void>;

package/dist/esm/cache-store.js

@@ -196,3 +196,35 @@ export async function optimisticallyInsert(userId, collection, record) {
         // ignore
     }
 }
+/**
+ * The reverse of optimisticallyInsert: takes one record out of every cached
+ * result of a collection.
+ *
+ * Precise on purpose. Dropping the collection's cached results instead would
+ * leave a device that is still offline with no saved lists to show at all,
+ * to get rid of one record.
+ */
+export async function removeFromCachedQueries(userId, collection, recordId) {
+    try {
+        const keys = await getPlatform().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        for (const key of keys.filter(k => k.startsWith(prefix))) {
+            const raw = await getPlatform().storage.getItem(key);
+            if (!raw)
+                continue;
+            const cached = JSON.parse(raw);
+            if (!Array.isArray(cached.records))
+                continue;
+            const kept = cached.records.filter(r => r.id !== recordId);
+            const removed = cached.records.length - kept.length;
+            if (removed === 0)
+                continue;
+            cached.records = kept;
+            cached.total = Math.max(0, cached.total - removed);
+            await getPlatform().storage.setItem(key, JSON.stringify(cached));
+        }
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/esm/collection-controller.d.ts

@@ -11,8 +11,9 @@ export interface CollectionQuery {
     /**
      * Re-read page one, silently, when Koolbase realtime reports a record
      * created, updated or deleted in this collection (debounced: a burst is one
-     * read). Realtime needs a signed-in user; until there is one, the list
-     * behaves as a normal list and goes live once the session exists.
+     * read). Signed out, only a collection anyone can read (read rule
+     * "public") is live; any other behaves as a normal list until a user signs
+     * in, and goes live then.
      */
     live?: boolean;
 }

package/dist/esm/database.d.ts

@@ -173,6 +173,15 @@ export declare class KoolbaseDatabase {
      */
     private requireUserId;
     private requireConflict;
+    /**
+     * Removes a decided conflict and points the writes held behind it at the
+     * state the record is now in -- in one transaction, so the conflict can
+     * never be gone while its held writes still describe the old world.
+     *
+     * Without a known state (a refused add, a delete) there is nothing to
+     * rebase onto: the conflict is removed and the held writes stay as they are.
+     */
+    private settleConflict;
     private dropConflict;
     /**
      * Issues the resolving write, conditional on the revision the refusal

package/dist/esm/database.js

@@ -3,7 +3,7 @@ import { refreshCollectionQueries } from './query-refresh.js';
 import { KoolbaseRevisionMismatchError } from './database-errors.js';
 import { KoolbaseError, KoolbaseOfflineBaselineUnavailableError, KoolbaseUnauthenticatedError, } from './errors.js';
 import { cacheRecord, getCachedRecord, removeCachedRecord } from './cache-store.js';
-import { readOfflineState, mutateOfflineState, queueWrite, } from './offline-state.js';
+import { readOfflineState, mutateOfflineState, queueWrite, rebaseHeldWrites, } from './offline-state.js';
 import { KoolbaseConflict } from './conflict.js';
 import { toPendingWrite } from './pending-write.js';
 import { getCached, setCached, invalidateCache, optimisticallyInsert, hashQuery, } from './cache-store.js';
@@ -62,12 +62,15 @@ export class KoolbaseDatabase {
             resolveWithServer: async (id) => {
                 const c = await this.requireConflict(id);
                 // The server's version stands. Recorded as a decision by removing the
-                // conflict, rather than the change quietly disappearing.
-                await this.dropConflict(c.id);
+                // conflict, rather than the change quietly disappearing -- and what
+                // stands is what the writes held behind it now build on.
+                await this.settleConflict(c, c.server, c.serverRevision);
             },
             abandon: async (id) => {
                 const c = await this.requireConflict(id);
-                await this.dropConflict(c.id);
+                // Neither version claimed to win, so the record stands as the server
+                // has it: what anything still queued must build on.
+                await this.settleConflict(c, c.server, c.serverRevision);
             },
         };
         this.config = config;
@@ -537,6 +540,25 @@ export class KoolbaseDatabase {
         }
         return found;
     }
+    /**
+     * Removes a decided conflict and points the writes held behind it at the
+     * state the record is now in -- in one transaction, so the conflict can
+     * never be gone while its held writes still describe the old world.
+     *
+     * Without a known state (a refused add, a delete) there is nothing to
+     * rebase onto: the conflict is removed and the held writes stay as they are.
+     */
+    async settleConflict(c, resolved, revision) {
+        if (!resolved || !c.recordId) {
+            await this.dropConflict(c.id);
+            return;
+        }
+        const userId = this.requireUserId('conflict resolution');
+        await mutateOfflineState(userId, (s) => {
+            s.conflicts = s.conflicts.filter((x) => x.id !== c.id);
+            rebaseHeldWrites(s, c.recordId, resolved, revision);
+        });
+    }
     async dropConflict(id) {
         const userId = this.requireUserId('conflict resolution');
         await mutateOfflineState(userId, (s) => {
@@ -551,6 +573,8 @@ export class KoolbaseDatabase {
      */
     async applyResolution(c, payload) {
         const rev = c.serverRevision;
+        // What the server now holds, from its answer: the state held writes build on.
+        let landed = null;
         try {
             if (c.operation === 'insert') {
                 // Resolving a rejected insert IS the insert, retried — with amended
@@ -561,7 +585,7 @@ export class KoolbaseDatabase {
                 // original on retry rather than duplicating — the queue's own
                 // lost-response discipline, extended to the one insert path that
                 // lacked it.
-                await this.request('POST', '/v1/sdk/db/insert', {
+                landed = await this.request('POST', '/v1/sdk/db/insert', {
                     collection: c.collection,
                     data: payload,
                     idempotency_key: c.id,
@@ -572,7 +596,7 @@ export class KoolbaseDatabase {
                 await this.request('DELETE', `/v1/sdk/db/records/${c.recordId}${q}`);
             }
             else {
-                await this.request('PATCH', `/v1/sdk/db/records/${c.recordId}`, { data: payload, ...(rev !== undefined ? { expected_revision: rev } : {}) });
+                landed = await this.request('PATCH', `/v1/sdk/db/records/${c.recordId}`, { data: payload, ...(rev !== undefined ? { expected_revision: rev } : {}) });
             }
         }
         catch (e) {
@@ -601,7 +625,8 @@ export class KoolbaseDatabase {
             }
             throw e;
         }
-        await this.dropConflict(c.id);
+        const landedRevision = landed && typeof landed.$revision === 'number' ? landed.$revision : undefined;
+        await this.settleConflict(c, landed ?? undefined, landedRevision);
         await invalidateCache(this.getUserId() ?? 'anonymous', c.collection);
         void refreshCollectionQueries(c.collection);
     }

package/dist/esm/offline-state.d.ts

@@ -103,3 +103,19 @@ export declare function queueWrite(userId: string, write: Omit<QueuedWrite, 'ret
  * and nothing is written on a guess.
  */
 export declare function migrateLegacyQueue(userId: string): Promise<void>;
+/**
+ * Points the writes still queued for a record at the state it is now in.
+ *
+ * When a conflict is decided, the writes held behind it carry baselines
+ * describing the state the conflicted write would have produced -- a state
+ * that no longer exists, and may never have. Released unchanged they would
+ * replay against a revision that has moved on, and each would conflict in
+ * turn: one disagreement multiplying into as many conflicts as the user had
+ * queued. The same rule as the Flutter SDK's rebaseAfterResolution.
+ *
+ * Refreshing the baseline is enough because every operation is an absolute
+ * assignment: a patch says what a field becomes, not what to do to it. If a
+ * relative operation is ever added (an increment, an append), the chain must
+ * be replayed through its projected states instead.
+ */
+export declare function rebaseHeldWrites(state: OfflineState, recordId: string, resolved: Record<string, unknown>, revision: number | undefined): void;

package/dist/esm/offline-state.js

@@ -202,3 +202,36 @@ export async function migrateLegacyQueue(userId) {
     });
     await getPlatform().storage.removeItem(legacyQueueKey(userId));
 }
+/**
+ * Points the writes still queued for a record at the state it is now in.
+ *
+ * When a conflict is decided, the writes held behind it carry baselines
+ * describing the state the conflicted write would have produced -- a state
+ * that no longer exists, and may never have. Released unchanged they would
+ * replay against a revision that has moved on, and each would conflict in
+ * turn: one disagreement multiplying into as many conflicts as the user had
+ * queued. The same rule as the Flutter SDK's rebaseAfterResolution.
+ *
+ * Refreshing the baseline is enough because every operation is an absolute
+ * assignment: a patch says what a field becomes, not what to do to it. If a
+ * relative operation is ever added (an increment, an append), the chain must
+ * be replayed through its projected states instead.
+ */
+export function rebaseHeldWrites(state, recordId, resolved, revision) {
+    let current = {};
+    for (const [k, v] of Object.entries(resolved)) {
+        if (!k.startsWith('$'))
+            current[k] = v;
+    }
+    for (const w of state.pending) {
+        if (w.recordId !== recordId)
+            continue;
+        w.baseline = { ...current };
+        w.baseRevision = revision;
+        // Each write is composed against the one before it.
+        if (w.operation === 'update')
+            current = { ...current, ...(w.data ?? {}) };
+        else if (w.operation === 'delete')
+            break;
+    }
+}

package/dist/esm/realtime.d.ts

@@ -9,6 +9,9 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private anonymous;
+    private connectedAs;
+    private generation;
     private idleTimer;
     /** How long an unused connection stays open, in ms: a screen that comes
      *  straight back (navigating back, React's development double start)
@@ -30,6 +33,9 @@ export declare class KoolbaseRealtime {
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    private send;
     /**
      * Reconnects with backoff, rather than every three seconds forever.
      *
@@ -51,6 +57,16 @@ export declare class KoolbaseRealtime {
      * it: reconnecting needs a subscriber.
      */
     private scheduleIdleClose;
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged(): void;
     disconnect(): void;
 }
 export {};

package/dist/esm/realtime.js

@@ -38,6 +38,15 @@ export class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // The open connection is a signed-out visitor's (the public key): its
+        // messages leave project_id out.
+        this.anonymous = false;
+        // Whose session the open connection was made for: the user id, or null
+        // when signed out. sessionChanged compares against it.
+        this.connectedAs = null;
+        // Bumped by sessionChanged: a connect still waiting for its token gives up
+        // rather than open a connection for the old session.
+        this.generation = 0;
         // Pending close of an unused connection (scheduleIdleClose); null while
         // anyone is subscribed.
         this.idleTimer = null;
@@ -98,28 +107,49 @@ export class KoolbaseRealtime {
         // double start -- found nobody connecting and opened its own socket; only
         // the last was remembered, and the others stayed open for good.
         this.connecting = true;
+        const generation = this.generation;
         let token;
         try {
             token = await this.getToken();
         }
         catch {
-            token = null;
+            // A session that could not be refreshed is still a session: try again
+            // later, never as a signed-out visitor.
+            if (generation !== this.generation)
+                return;
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
         }
+        // The session changed while the token was on its way: sessionChanged
+        // has started the connection for the new one.
+        if (generation !== this.generation)
+            return;
         if (this.listeners.size === 0) {
             // Everyone left while the token was on its way: nothing to connect for.
             this.connecting = false;
             return;
         }
-        if (!token) {
+        const userId = this.getUserId?.() ?? null;
+        if (!token && userId) {
+            // Signed in, but no usable token right now: try again later rather
+            // than drop to public-only.
             this.connecting = false;
-            this.scheduleReconnect(); // sign-in may be in flight
+            this.scheduleReconnect();
             return;
         }
-        this.projectId = projectIdFromToken(token);
+        // Signed out: the project's public key, and only collections anyone can
+        // read. The server pins the connection to the key's project.
+        this.anonymous = !token;
+        this.connectedAs = token ? userId : null;
+        this.projectId = token ? projectIdFromToken(token) : null;
+        const credential = token
+            ? `token=${encodeURIComponent(token)}`
+            : `public_key=${encodeURIComponent(this.config.publicKey)}`;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
         let ws;
         try {
-            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?${credential}`);
         }
         catch {
             this.connecting = false;
@@ -183,14 +213,22 @@ export class KoolbaseRealtime {
         ws.onerror = () => { };
     }
     sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+        this.send('subscribe', collection);
     }
     sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+        this.send('unsubscribe', collection);
+    }
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    send(action, collection) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+        if (this.anonymous) {
+            this.ws.send(JSON.stringify({ action, collection }));
+        }
+        else if (this.projectId) {
+            this.ws.send(JSON.stringify({ action, project_id: this.projectId, collection }));
+        }
     }
     /**
      * Reconnects with backoff, rather than every three seconds forever.
@@ -249,6 +287,42 @@ export class KoolbaseRealtime {
         }, KoolbaseRealtime.idleGraceMs);
         this.idleTimer.unref?.();
     }
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged() {
+        if (!this.ws && !this.connecting && !this.reconnectTimer)
+            return;
+        if (this.ws && !this.connecting && (this.getUserId?.() ?? null) === this.connectedAs)
+            return;
+        this.generation += 1;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.connecting = false;
+        this.anonymous = false;
+        this.projectId = null;
+        this.reconnectAttempts = 0;
+        if (ws) {
+            // Detached first: this close is ours, not a dropped connection.
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+            ws.close();
+        }
+        if (this.listeners.size > 0)
+            void this.connect();
+    }
     disconnect() {
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);

package/dist/esm/sync-engine.js

@@ -2,7 +2,7 @@ import { koolbaseFetch } from './network.js';
 import { readOfflineState, mutateOfflineState, migrateLegacyQueue, flushLockName, } from './offline-state.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { getPlatform } from './platform.js';
-import { invalidateCache, removeCachedRecord, } from './cache-store.js';
+import { invalidateCache, removeCachedRecord, removeFromCachedQueries, } from './cache-store.js';
 /**
  * Internal signal that the server refused a write because the record moved.
  *
@@ -98,13 +98,21 @@ export class SyncEngine {
             // being online — would give the same input different outcomes. It clears
             // the old key when done, so later calls find nothing and return.
             await migrateLegacyQueue(userId);
-            const { pending } = await readOfflineState(userId);
+            const { pending, conflicts } = await readOfflineState(userId);
             if (pending.length === 0)
                 return;
             // Records whose chain stopped this pass. Writes queued after a conflicted
             // one were composed against the state it would have produced, so applying
             // them now would write against a state their baseline never described.
             const blocked = new Set();
+            // And records whose chain stopped in an EARLIER pass: a conflict waits
+            // for a decision across restarts, and so must the writes behind it.
+            // Seeded only from this pass's finds, the next pass replayed them
+            // against a state their baselines never described -- each becoming its
+            // own conflict. Deciding the conflict rebases and releases them.
+            for (const c of conflicts)
+                if (c.recordId)
+                    blocked.add(c.recordId);
             for (const queued of pending) {
                 if (queued.recordId && blocked.has(queued.recordId))
                     continue;
@@ -199,10 +207,15 @@ export class SyncEngine {
                         // — cached at enqueue for a record the server refused to create.
                         // Left alone it is a phantom: it renders as saved, and an offline
                         // edit against it queues a write to a record that does not exist.
-                        // Evict it, and invalidate the collection so cached queries stop
-                        // serving it. The conflict above keeps the user's data and the
-                        // server's verdict; the cache stops testifying to a fiction.
-                        // MUTATION: phantom eviction removed
+                        // Evict it from the record cache and from every cached query that
+                        // holds it -- precisely, not by dropping the collection's saved
+                        // results, which a device still offline needs. The conflict above
+                        // keeps the user's data and the server's verdict; the cache stops
+                        // testifying to a fiction.
+                        if (write.operation === 'insert' && write.recordId) {
+                            await removeCachedRecord(userId, write.recordId);
+                            await removeFromCachedQueries(userId, write.collection, write.recordId);
+                        }
                         if (write.recordId)
                             blocked.add(write.recordId);
                         continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.12.0",
+  "version": "12.13.1",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",