@koolbase/react-native 9.0.0 → 9.2.0

package/dist/database.js

@@ -1,13 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseDatabase = void 0;
+const errors_1 = require("./errors");
 const cache_store_1 = require("./cache-store");
+const offline_state_1 = require("./offline-state");
+const conflict_1 = require("./conflict");
+const pending_write_1 = require("./pending-write");
+const cache_store_2 = require("./cache-store");
 const sync_engine_1 = require("./sync-engine");
 const record_1 = require("./record");
 const database_errors_1 = require("./database-errors");
-function generateId() {
+function generateWriteId() {
     return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
+// Record ids are UUIDs from birth: the server honors a caller-supplied UUID id,
+// so the optimistic identity and the server identity are the same string and
+// chained offline writes need no remapping on replay. Write ids (above) stay
+// local_-prefixed — they are idempotency keys, never addresses.
+function generateRecordId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
 function batchOpToWire(op) {
     switch (op.type) {
         case 'insert':
@@ -26,11 +41,40 @@ function batchOpToWire(op) {
     }
 }
 class KoolbaseDatabase {
-    constructor(config, getUserId, getToken) {
+    constructor(config, getUserId, getToken, onSessionExpired) {
+        /**
+         * Resolves by id, reloading the stored conflict first.
+         *
+         * A conflict object handed to a UI can sit there while someone decides, and a
+         * sync pass may resolve it or another write supersede it meanwhile. Acting on
+         * values captured when the object was built would write against a state that
+         * no longer exists.
+         */
+        this.conflictResolver = {
+            resolveWithLocal: async (id) => {
+                const c = await this.requireConflict(id);
+                await this.applyResolution(c, c.local ?? {});
+            },
+            resolveWithMerge: async (id, data) => {
+                const c = await this.requireConflict(id);
+                await this.applyResolution(c, data);
+            },
+            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);
+            },
+            abandon: async (id) => {
+                const c = await this.requireConflict(id);
+                await this.dropConflict(c.id);
+            },
+        };
         this.config = config;
         this.getUserId = getUserId;
         this.getToken = getToken;
-        this.syncEngine = new sync_engine_1.SyncEngine(config, getUserId, getToken);
+        this.onSessionExpired = onSessionExpired;
+        this.syncEngine = new sync_engine_1.SyncEngine(config, getUserId, getToken, undefined, onSessionExpired);
         this.syncEngine.start();
     }
     // getUserId is kept only for local cache keys / offline metadata; request
@@ -49,12 +93,64 @@ class KoolbaseDatabase {
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
         });
-        const data = await res.json();
+        // A 204 carries no body, and some error responses carry none either.
+        // Parsing unconditionally would throw before the status was ever checked,
+        // which is why delete was written to bypass this path — and why its errors
+        // went unreported.
+        const text = await res.text();
+        let data = null;
+        if (text.length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                // Leave data null: a body that is not JSON is not more informative than
+                // the status, and failing to parse it must not mask the status.
+            }
+        }
         if (!res.ok) {
-            throw (0, database_errors_1.koolbaseDataError)(res.status, data, `Request failed: ${res.status}`);
+            const err = (0, database_errors_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
+            if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
+                await this.onSessionExpired?.();
+            }
+            throw err;
         }
         return data;
     }
+    /**
+     * Like [request], but returns the status alongside the body.
+     *
+     * Several operations need it — upsert distinguishes create from update by a
+     * 201, batch reports per-operation outcomes — and needing it was why they
+     * hand-rolled their own fetch, each mapping errors slightly differently and
+     * none of them clearing a rejected session. One path, two shapes of result.
+     */
+    async requestWithStatus(method, path, body) {
+        const res = await fetch(`${this.config.baseUrl}${path}`, {
+            method,
+            headers: await this.buildHeaders(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        let data = null;
+        if (text.length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                // Not JSON: the status is more informative than an unparseable body,
+                // and failing to parse must not mask it.
+            }
+        }
+        if (!res.ok) {
+            const err = (0, database_errors_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
+            if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
+                await this.onSessionExpired?.();
+            }
+            throw err;
+        }
+        return { status: res.status, data: data };
+    }
     // ─── Query (cache-first) ───────────────────────────────────────────────────
     async runQuery(collection, options) {
         const raw = await this.request('POST', '/v1/sdk/db/query', {
@@ -66,22 +162,53 @@ class KoolbaseDatabase {
             order_desc: options.orderDesc ?? false,
             populate: options.populate ?? [],
         });
-        return { records: raw.records.map(record_1.recordFromWire), total: raw.total };
+        const records = raw.records.map(record_1.recordFromWire);
+        // Individually, as well as under the query key. The query cache answers
+        // "what did this query return"; the record cache answers "what is the
+        // latest copy of this record" — and an offline mutation composes against
+        // the second. Without this, listing records and editing one, the most
+        // ordinary flow there is, would have no baseline and be refused.
+        //
+        // Only the top-level records. Populated relations arrive embedded rather
+        // than fetched in their own right, and caching them as if they were would
+        // risk storing a shape that is not the whole record.
+        const userId = this.getUserId() ?? 'anonymous';
+        await Promise.all(records.map((r) => r.collection
+            ? (0, cache_store_1.cacheRecord)(userId, r.collection, r.id, r.data, r.revision)
+            : Promise.resolve()));
+        return { records, total: raw.total };
     }
+    /**
+     * Query records, cache-first (stale-while-revalidate).
+     *
+     * A cache hit is returned immediately with `isFromCache: true`, and a
+     * background refresh updates the cache for the next call — so a repeat
+     * query converges on the server's state one call behind it. Only a cache
+     * miss awaits the network (`isFromCache: false`).
+     *
+     * Two consequences worth designing for: results can be one refresh stale,
+     * even online — re-query if you need convergence after a known write; and
+     * background refresh failures are swallowed by design (the cached result
+     * has already been returned), so a dead network looks identical to a slow
+     * refresh. Check `isFromCache` when the difference matters.
+     *
+     * The cache is per-user and persisted; it doubles as the offline baseline
+     * store for `update`/`delete`.
+     */
     async query(collection, options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
-        const queryHash = (0, cache_store_1.hashQuery)(collection, options);
-        const cached = await (0, cache_store_1.getCached)(userId, collection, queryHash);
-        this.runQuery(collection, options)
-            .then(result => (0, cache_store_1.setCached)(userId, collection, queryHash, result))
-            .catch(() => {
-            // Network unavailable — cached data already returned
-        });
+        const queryHash = (0, cache_store_2.hashQuery)(collection, options);
+        const cached = await (0, cache_store_2.getCached)(userId, collection, queryHash);
         if (cached) {
+            this.runQuery(collection, options)
+                .then(result => (0, cache_store_2.setCached)(userId, collection, queryHash, result))
+                .catch(() => {
+                // Network unavailable — cached data already returned
+            });
             return { ...cached, isFromCache: true };
         }
         const result = await this.runQuery(collection, options);
-        await (0, cache_store_1.setCached)(userId, collection, queryHash, result);
+        await (0, cache_store_2.setCached)(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
@@ -105,7 +232,10 @@ class KoolbaseDatabase {
             // next query sees real data instead of a stale optimistic copy.
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = (0, record_1.recordFromWire)(raw);
-            await (0, cache_store_1.invalidateCache)(userId, collection);
+            await (0, cache_store_2.invalidateCache)(userId, collection);
+            // The response carries a fresh revision, so caching it keeps the
+            // baseline current for whatever edits this record next.
+            await (0, cache_store_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
             return record;
         }
         catch (e) {
@@ -113,24 +243,43 @@ class KoolbaseDatabase {
             // Surface to the caller without writing optimistic state or queuing —
             // the server has already decided it will not accept this write, and
             // queuing it would just spin SyncEngine until max retries.
-            if (e instanceof database_errors_1.KoolbaseDataError)
+            // Anything the server answered with — a refusal, a conflict, a rejected
+            // credential — must not be queued: it will be refused again on every
+            // retry. Checked against the root rather than the data family, because a
+            // rejected credential belongs to no single surface.
+            if (e instanceof errors_1.KoolbaseError)
                 throw e;
+            // The queue is per-user, and signed out there is no user: filing this
+            // into the anonymous bucket would queue real work where no signed-in
+            // sync ever looks — the fake-zero's origin. Refusing is honest; the
+            // caller knows the change did not save and can say so.
+            if (!this.getUserId()) {
+                throw new errors_1.KoolbaseUnauthenticatedError('Signed out and offline — this change cannot be queued for sync.');
+            }
             // Genuine network failure → offline path: save to local cache and
             // queue for SyncEngine to retry when online. Return the optimistic
             // record so the UI has something to render in the meantime.
+            const recordId = generateRecordId();
             const optimisticRecord = {
-                id: generateId(),
+                id: recordId,
                 createdBy: userId,
-                data,
+                data: { ...data, id: recordId },
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
             };
-            await (0, cache_store_1.optimisticallyInsert)(userId, collection, optimisticRecord);
-            await (0, cache_store_1.addToWriteQueue)(userId, {
-                id: generateId(),
-                type: 'insert',
+            await (0, cache_store_2.optimisticallyInsert)(userId, collection, optimisticRecord);
+            // No baseline: an insert has no prior state, and the record does not
+            // exist on the server yet, so there is nothing to be conditional against.
+            // An offline edit to it composes against this queued write instead.
+            await (0, offline_state_1.queueWrite)(userId, {
+                id: generateWriteId(),
+                operation: 'insert',
                 collection,
-                data,
+                recordId: optimisticRecord.id,
+                // The record's UUID travels inside the payload: the server honors a
+                // caller-supplied id, which is what keeps offline identity alive across
+                // the boundary — the whole reason record ids are UUIDs from birth.
+                data: optimisticRecord.data,
             });
             return optimisticRecord;
         }
@@ -152,20 +301,13 @@ class KoolbaseDatabase {
      * created, 200 = updated.
      */
     async upsert(collection, match, data) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/upsert`, {
-            method: 'POST',
-            headers: await this.buildHeaders(),
-            body: JSON.stringify({ collection, match, data }),
-        });
-        const body = await res.json();
-        if (!res.ok) {
-            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Upsert failed: ${res.status}`);
-        }
-        const created = res.status === 201;
+        const { status, data: body } = await this.requestWithStatus('POST', '/v1/sdk/db/upsert', { collection, match, data });
+        const created = status === 201;
         const record = (0, record_1.recordFromWire)(body);
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_1.invalidateCache)(userId, collection);
+        await (0, cache_store_2.invalidateCache)(userId, collection);
+        await (0, cache_store_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
     // ─── Delete where (online-only) ─────────────────────────────────────────────
@@ -181,17 +323,9 @@ class KoolbaseDatabase {
      * The collection cache is invalidated on success.
      */
     async deleteWhere(collection, filters) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-where`, {
-            method: 'POST',
-            headers: await this.buildHeaders(),
-            body: JSON.stringify({ collection, filters }),
-        });
-        const body = await res.json();
-        if (!res.ok) {
-            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Delete failed: ${res.status}`);
-        }
+        const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_1.invalidateCache)(userId, collection);
+        await (0, cache_store_2.invalidateCache)(userId, collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -222,17 +356,9 @@ class KoolbaseDatabase {
         if (operations.length === 0) {
             throw new Error('batch requires at least one operation');
         }
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/batch`, {
-            method: 'POST',
-            headers: await this.buildHeaders(),
-            body: JSON.stringify({
-                operations: operations.map(batchOpToWire),
-            }),
+        const body = await this.request('POST', '/v1/sdk/db/batch', {
+            operations: operations.map(batchOpToWire),
         });
-        const body = await res.json();
-        if (!res.ok) {
-            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Batch failed: ${res.status}`);
-        }
         const results = (body.results ?? []).map(r => ({
             type: r.type ?? '',
             record: r.record
@@ -246,6 +372,15 @@ class KoolbaseDatabase {
         // don't know the collection at this layer — those refresh naturally on
         // the next query for the affected collection.
         const userId = this.getUserId() ?? 'anonymous';
+        // Records returned by a batch carry their own collection on the wire, so
+        // they can be cached even where the input op did not name one — which is
+        // what the invalidation below cannot do. A batch commits transactionally, so
+        // every record here landed together and carries a fresh revision.
+        for (const r of results) {
+            if (r.record?.collection) {
+                await (0, cache_store_1.cacheRecord)(userId, r.record.collection, r.record.id, r.record.data, r.record.revision);
+            }
+        }
         const touched = new Set();
         for (const op of operations) {
             if (op.type === 'insert' || op.type === 'upsert') {
@@ -253,7 +388,7 @@ class KoolbaseDatabase {
             }
         }
         for (const col of touched) {
-            await (0, cache_store_1.invalidateCache)(userId, col);
+            await (0, cache_store_2.invalidateCache)(userId, col);
         }
         return results;
     }
@@ -261,7 +396,126 @@ class KoolbaseDatabase {
     // ─── Get single record ──────────────────────────────────────────────────────
     async get(recordId) {
         const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);
-        return (0, record_1.recordFromWire)(raw);
+        const record = (0, record_1.recordFromWire)(raw);
+        // Opening a record then editing it is the other ordinary flow, and a deep
+        // link reaches it without a query ever having run.
+        if (record.collection) {
+            await (0, cache_store_1.cacheRecord)(this.getUserId() ?? 'anonymous', record.collection, record.id, record.data, record.revision);
+        }
+        return record;
+    }
+    // ─── Conflicts ──────────────────────────────────────────────────────────────
+    /**
+     * Writes that could not be applied, waiting for a decision.
+     *
+     * Held rather than discarded, and surviving restarts. An app that never reads
+     * these accumulates them invisibly, with the changes they hold never applied —
+     * so if you support offline editing, surface them somewhere.
+     */
+    /**
+     * Changes made offline, waiting to be sent. Oldest first.
+     *
+     * For sync indicators ("3 changes waiting") and for warning a user who is
+     * about to log out with unsynced edits — see [PendingWrite] for why that
+     * moment matters. Snapshot, not a live handle; per-user.
+     */
+    async pendingWrites() {
+        const userId = this.requireUserId('the pending-write queue');
+        const { pending } = await (0, offline_state_1.readOfflineState)(userId);
+        return pending.map(pending_write_1.toPendingWrite);
+    }
+    async conflicts() {
+        const userId = this.requireUserId('the conflict list');
+        const { conflicts } = await (0, offline_state_1.readOfflineState)(userId);
+        return conflicts.map((c) => new conflict_1.KoolbaseConflict(c.id, c.reason, c.operation, c.collection, c.recordId, c.local, c.baseline, c.server, c.baseRevision, c.serverRevision, c.createdAt, this.conflictResolver));
+    }
+    /**
+     * Per-user state demands a user. Signed out, "no answer" must not be
+     * disguised as "empty" — tonight's fake-zero: the display read the anonymous
+     * bucket while a signed-in user's writes sat unseen in theirs.
+     */
+    requireUserId(doing) {
+        const userId = this.getUserId();
+        if (!userId) {
+            throw new errors_1.KoolbaseUnauthenticatedError(`Signed out — ${doing} is per-user state and has no answer without a user.`);
+        }
+        return userId;
+    }
+    async requireConflict(id) {
+        const userId = this.requireUserId('conflict resolution');
+        const { conflicts } = await (0, offline_state_1.readOfflineState)(userId);
+        const found = conflicts.find((c) => c.id === id);
+        if (!found) {
+            throw new database_errors_1.KoolbaseDataError('That conflict is no longer outstanding — it may already have been resolved.', 'conflict_not_found');
+        }
+        return found;
+    }
+    async dropConflict(id) {
+        const userId = this.requireUserId('conflict resolution');
+        await (0, offline_state_1.mutateOfflineState)(userId, (s) => {
+            s.conflicts = s.conflicts.filter((c) => c.id !== id);
+        });
+    }
+    /**
+     * Issues the resolving write, conditional on the revision the refusal
+     * reported, and clears the conflict only once the server accepts it.
+     *
+     * Clearing first would lose the change if the write then failed.
+     */
+    async applyResolution(c, payload) {
+        const rev = c.serverRevision;
+        try {
+            if (c.operation === 'insert') {
+                // Resolving a rejected insert IS the insert, retried — with amended
+                // data via resolveWithMerge (the "fix the colliding title" path).
+                // Unconditional: there is no revision to be conditional against,
+                // because there is no record. The conflict's id rides as the
+                // idempotency key, so a resolution whose response is lost returns the
+                // 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', {
+                    collection: c.collection,
+                    data: payload,
+                    idempotency_key: c.id,
+                });
+            }
+            else if (c.operation === 'delete') {
+                const q = rev !== undefined ? `?expected_revision=${rev}` : '';
+                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 } : {}) });
+            }
+        }
+        catch (e) {
+            // A refusal must teach the stored conflict, not just gate it. The 409
+            // carries the server's current revision and record; absorbing them makes
+            // the NEXT attempt conditional against reality. Without this, every
+            // retry replays the stale condition and a conflict whose resolution
+            // fails once is permanently unresolvable except by abandon —
+            // device-proven: three identical refusals against an unchanged server.
+            const details = e instanceof database_errors_1.KoolbaseDataError ? e.details : undefined;
+            const current = details?.current_revision;
+            const record = details?.record;
+            if (typeof current === 'number') {
+                await (0, offline_state_1.mutateOfflineState)(this.requireUserId('conflict resolution'), (st) => {
+                    const stored = st.conflicts.find((x) => x.id === c.id);
+                    if (!stored)
+                        return;
+                    stored.serverRevision = current;
+                    // Storing the fresh server snapshot IS the divergence update: the
+                    // public conflict computes divergentFields from local vs server.
+                    if (record)
+                        stored.server = record;
+                });
+                throw new database_errors_1.KoolbaseDataError('The record has changed again while deciding. The conflict now ' +
+                    'reflects the server\'s current state — review and retry.', 'revision_mismatch');
+            }
+            throw e;
+        }
+        await this.dropConflict(c.id);
+        await (0, cache_store_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -277,46 +531,136 @@ class KoolbaseDatabase {
      * optimistic record is returned so the UI can re-render the new fields
      * immediately.
      */
+    /**
+     * The record's state as the SDK last knew it, for composing an offline
+     * mutation against.
+     *
+     * Two sources, in order. A record created offline is not in the cache as a
+     * server record, but its queued insert holds the state a later edit builds on
+     * — insert-then-correct is the ordinary offline sequence. Otherwise the cached
+     * copy, with the revision it was read at.
+     *
+     * Null when neither exists: never seen on this device, or a queued delete has
+     * already removed it locally.
+     */
+    async resolveBaseline(userId, recordId) {
+        const state = await (0, offline_state_1.readOfflineState)(userId);
+        const queued = state.pending.filter((w) => w.recordId === recordId);
+        if (queued.length > 0) {
+            let projected = null;
+            for (const w of queued) {
+                if (w.operation === 'insert')
+                    projected = { ...(w.data ?? {}) };
+                else if (w.operation === 'update')
+                    projected = { ...(projected ?? {}), ...(w.data ?? {}) };
+                else if (w.operation === 'delete')
+                    projected = null;
+            }
+            // A chain ending in a delete leaves nothing to build on: editing a record
+            // already removed locally is a contradiction in the SDK's own state, not
+            // a conflict to resolve against the server.
+            if (projected === null)
+                return null;
+            return {
+                baseline: projected,
+                revision: queued[queued.length - 1].baseRevision,
+                collection: queued[0].collection,
+            };
+        }
+        const cached = await (0, cache_store_1.getCachedRecord)(userId, recordId);
+        if (!cached)
+            return null;
+        return { baseline: cached.data, revision: cached.revision, collection: cached.collection };
+    }
     async update(recordId, data) {
         const userId = this.getUserId() ?? 'anonymous';
+        // Resolved before the request, so a network failure has somewhere to go.
+        const base = await this.resolveBaseline(userId, recordId);
         try {
             const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
-            return (0, record_1.recordFromWire)(raw);
+            const updated = (0, record_1.recordFromWire)(raw);
+            if (updated.collection) {
+                await (0, cache_store_1.cacheRecord)(userId, updated.collection, updated.id, updated.data, updated.revision);
+            }
+            return updated;
         }
         catch (e) {
             // Server-reachable rejection: surface to caller without queuing — the
             // server already refused the write and will refuse it again on retry.
-            if (e instanceof database_errors_1.KoolbaseDataError)
+            // Anything the server answered with — a refusal, a conflict, a rejected
+            // credential — must not be queued: it will be refused again on every
+            // retry. Checked against the root rather than the data family, because a
+            // rejected credential belongs to no single surface.
+            if (e instanceof errors_1.KoolbaseError)
                 throw e;
-            // Genuine network failure → queue for sync and return an optimistic
-            // partial record so the UI reflects the update immediately.
-            await (0, cache_store_1.addToWriteQueue)(userId, {
-                id: generateId(),
-                type: 'update',
+            // Genuine network failure. Queueable only if the SDK knows what the
+            // change was composed against — without that, replay would apply it
+            // blindly and overwrite whatever happened while the device was away.
+            if (!base) {
+                throw new errors_1.KoolbaseOfflineBaselineUnavailableError('This record must be read at least once before it can be updated offline.');
+            }
+            await (0, offline_state_1.queueWrite)(userId, {
+                id: generateWriteId(),
+                operation: 'update',
+                collection: base.collection,
                 recordId,
                 data,
+                baseline: base.baseline,
+                baseRevision: base.revision,
             });
+            const merged = { ...base.baseline, ...data };
+            await (0, cache_store_1.cacheRecord)(userId, base.collection, recordId, merged, base.revision);
+            // Optimistic: durable locally and queued to send, not yet accepted.
             return {
                 id: recordId,
-                data,
+                collection: base.collection,
+                data: merged,
                 createdAt: '',
                 updatedAt: new Date().toISOString(),
+                revision: base.revision,
             };
         }
     }
     // ─── Delete ─────────────────────────────────────────────────────────────────
     async delete(recordId) {
         const userId = this.getUserId() ?? 'anonymous';
-        // Add to write queue
-        await (0, cache_store_1.addToWriteQueue)(userId, {
-            id: generateId(),
-            type: 'delete',
-            recordId,
-        });
-        // Try network
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/records/${recordId}`, { method: 'DELETE', headers: await this.buildHeaders(), });
-        if (!res.ok && res.status !== 204) {
-            // Queued for sync — will retry when online
+        const base = await this.resolveBaseline(userId, recordId);
+        try {
+            await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
+            await (0, cache_store_1.removeCachedRecord)(userId, recordId);
+        }
+        catch (e) {
+            // A server that answered has refused: a permission denial or a missing
+            // record will be refused again on every retry, so surface it rather than
+            // queueing. An app told a delete succeeded when it did not has no way to
+            // learn otherwise.
+            // Anything the server answered with — a refusal, a conflict, a rejected
+            // credential — must not be queued: it will be refused again on every
+            // retry. Checked against the root rather than the data family, because a
+            // rejected credential belongs to no single surface.
+            if (e instanceof errors_1.KoolbaseError)
+                throw e;
+            // Genuine network failure. Queued here rather than before the request,
+            // which would leave a successful delete in the queue to replay later
+            // against a record that may since have been recreated under the same id.
+            // A delete replayed without knowing what the record was would remove
+            // something the user last saw hours earlier and which may have changed
+            // since — the more destructive kind of stale write.
+            if (!base) {
+                throw new errors_1.KoolbaseOfflineBaselineUnavailableError('This record must be read at least once before it can be deleted offline.');
+            }
+            await (0, offline_state_1.queueWrite)(userId, {
+                id: generateWriteId(),
+                operation: 'delete',
+                collection: base.collection,
+                recordId,
+                baseline: base.baseline,
+                baseRevision: base.revision,
+            });
+            // The queued write holds its own copy of the baseline, so removing the
+            // cached record costs nothing and keeps local reads consistent with what
+            // the user just did.
+            await (0, cache_store_1.removeCachedRecord)(userId, recordId);
         }
     }
     // ─── Vectors ────────────────────────────────────────────────────────────────
@@ -338,15 +682,11 @@ class KoolbaseDatabase {
      * );
      */
     async setVector(recordId, field, vector) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/set-vector`, {
-            method: 'POST',
-            headers: await this.buildHeaders(),
-            body: JSON.stringify({ record_id: recordId, field, vector }),
+        await this.request('POST', '/v1/sdk/db/set-vector', {
+            record_id: recordId,
+            field,
+            vector,
         });
-        if (res.status !== 204) {
-            const body = await res.json().catch(() => ({}));
-            throw (0, database_errors_1.koolbaseDataError)(res.status, body, 'Set vector failed');
-        }
     }
     /**
      * Read a record's stored vector on the named `field`.
@@ -384,15 +724,10 @@ class KoolbaseDatabase {
      * collection and is still settable on other records.
      */
     async deleteVector(recordId, field) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-vector`, {
-            method: 'POST',
-            headers: await this.buildHeaders(),
-            body: JSON.stringify({ record_id: recordId, field }),
+        await this.request('POST', '/v1/sdk/db/delete-vector', {
+            record_id: recordId,
+            field,
         });
-        if (res.status !== 204) {
-            const body = await res.json().catch(() => ({}));
-            throw (0, database_errors_1.koolbaseDataError)(res.status, body, 'Delete vector failed');
-        }
     }
     /**
      * Queue an embedding job for a record's vector field. The server's
@@ -492,11 +827,20 @@ class KoolbaseDatabase {
             body.min_similarity = opts.minSimilarity;
         }
         const raw = await this.request('POST', '/v1/sdk/db/search-semantic', body);
+        // A hit carries the complete public record, not a projection, so these are
+        // safe to cache as baselines. A trimmed record would be worse than none: an
+        // offline edit would compose against an incomplete picture and conflict
+        // detection would compare against fields that were never there.
+        const hits = (raw.results ?? []).map((r) => ({
+            record: (0, record_1.recordFromWire)(r.record),
+            distance: r.distance,
+        }));
+        const searchUserId = this.getUserId() ?? 'anonymous';
+        await Promise.all(hits.map((h) => h.record.collection
+            ? (0, cache_store_1.cacheRecord)(searchUserId, h.record.collection, h.record.id, h.record.data, h.record.revision)
+            : Promise.resolve()));
         return {
-            hits: (raw.results ?? []).map(r => ({
-                record: (0, record_1.recordFromWire)(r.record),
-                distance: r.distance,
-            })),
+            hits: hits,
             total: raw.total ?? (raw.results ?? []).length,
         };
     }