@koolbase/core 10.0.0

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

@@ -0,0 +1,50 @@
+import { KoolbaseRecord, LegacyPendingWrite, QueryResult } from './types.js';
+export declare function hashQuery(collection: string, options: Record<string, unknown>): string;
+export declare function getCached(userId: string, collection: string, queryHash: string): Promise<QueryResult | null>;
+export declare function setCached(userId: string, collection: string, queryHash: string, result: QueryResult): Promise<void>;
+export declare function invalidateCache(userId: string, collection: string): Promise<void>;
+/**
+ * Drops everything cached for a user.
+ *
+ * Deliberately spares the write queue. The prefix covers every key for this
+ * user, and the queue lives under one of them — so clearing the cache used to
+ * delete offline writes the user believes are saved, silently and
+ * irrecoverably. A cache is what can be refetched; queued writes are not that.
+ */
+export declare function clearUserCache(userId: string): Promise<void>;
+/**
+ * A record as the SDK last saw it, with the revision it was read at.
+ *
+ * Separate from the query cache, which answers "what did this query return".
+ * This answers "what is the latest copy of this record" — and an offline
+ * mutation composes against the second. Scanning query blobs for one would mean
+ * the same record appearing in several snapshots at different revisions, with no
+ * principled way to choose.
+ *
+ * Keyed with `record` where a collection name would sit, so invalidateCache —
+ * which scopes to a collection and runs after every write — cannot reach these.
+ * A user's own edit must not remove the baseline they need for the next one.
+ */
+export interface CachedRecord {
+    collection: string;
+    data: Record<string, unknown>;
+    revision?: number;
+    cachedAt: string;
+}
+export declare function getCachedRecord(userId: string, recordId: string): Promise<CachedRecord | null>;
+/**
+ * Stores a record, refusing to move it backwards.
+ *
+ * Query responses can arrive out of order — a slow request from an earlier
+ * screen resolving after a fresh one — and an older copy overwriting a newer
+ * would compose the next mutation against a stale revision, producing a conflict
+ * the user never caused. False conflicts teach people to force-overwrite, which
+ * is worse than none.
+ */
+export declare function cacheRecord(userId: string, collection: string, recordId: string, data: Record<string, unknown>, revision?: number): Promise<void>;
+export declare function removeCachedRecord(userId: string, recordId: string): Promise<void>;
+export declare function getWriteQueue(userId: string): Promise<LegacyPendingWrite[]>;
+export declare function addToWriteQueue(userId: string, write: Omit<LegacyPendingWrite, 'retries' | 'createdAt'>): Promise<void>;
+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>;

package/dist/esm/cache-store.js

@@ -0,0 +1,179 @@
+import { getPlatform } from './platform.js';
+const CACHE_VERSION = 'v1';
+function cacheKey(userId, collection, queryHash) {
+    return `koolbase:${CACHE_VERSION}:${userId}:${collection}:${queryHash}`;
+}
+function writeQueueKey(userId) {
+    return `koolbase:${CACHE_VERSION}:${userId}:write_queue`;
+}
+export function hashQuery(collection, options) {
+    return `${collection}:${JSON.stringify(options)}`;
+}
+// ─── Cache ──────────────────────────────────────────────────────────────────
+export async function getCached(userId, collection, queryHash) {
+    try {
+        const raw = await getPlatform().storage.getItem(cacheKey(userId, collection, queryHash));
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function setCached(userId, collection, queryHash, result) {
+    try {
+        await getPlatform().storage.setItem(cacheKey(userId, collection, queryHash), JSON.stringify(result));
+    }
+    catch {
+        // ignore storage errors
+    }
+}
+export async function invalidateCache(userId, collection) {
+    try {
+        const keys = await getPlatform().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        const toDelete = keys.filter(k => k.startsWith(prefix));
+        for (const key of toDelete) {
+            await getPlatform().storage.removeItem(key);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Drops everything cached for a user.
+ *
+ * Deliberately spares the write queue. The prefix covers every key for this
+ * user, and the queue lives under one of them — so clearing the cache used to
+ * delete offline writes the user believes are saved, silently and
+ * irrecoverably. A cache is what can be refetched; queued writes are not that.
+ */
+export async function clearUserCache(userId) {
+    try {
+        const keys = await getPlatform().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:`;
+        const queueKey = writeQueueKey(userId);
+        const toDelete = keys.filter(k => k.startsWith(prefix) && k !== queueKey);
+        for (const key of toDelete) {
+            await getPlatform().storage.removeItem(key);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+function recordCacheKey(userId, recordId) {
+    return `koolbase:${CACHE_VERSION}:${userId}:record:${recordId}`;
+}
+export async function getCachedRecord(userId, recordId) {
+    try {
+        const raw = await getPlatform().storage.getItem(recordCacheKey(userId, recordId));
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stores a record, refusing to move it backwards.
+ *
+ * Query responses can arrive out of order — a slow request from an earlier
+ * screen resolving after a fresh one — and an older copy overwriting a newer
+ * would compose the next mutation against a stale revision, producing a conflict
+ * the user never caused. False conflicts teach people to force-overwrite, which
+ * is worse than none.
+ */
+export async function cacheRecord(userId, collection, recordId, data, revision) {
+    try {
+        const existing = await getCachedRecord(userId, recordId);
+        if (existing?.revision !== undefined &&
+            revision !== undefined &&
+            revision < existing.revision) {
+            return;
+        }
+        const entry = {
+            collection,
+            data,
+            revision,
+            cachedAt: new Date().toISOString(),
+        };
+        await getPlatform().storage.setItem(recordCacheKey(userId, recordId), JSON.stringify(entry));
+    }
+    catch {
+        // ignore
+    }
+}
+export async function removeCachedRecord(userId, recordId) {
+    try {
+        await getPlatform().storage.removeItem(recordCacheKey(userId, recordId));
+    }
+    catch {
+        // ignore
+    }
+}
+// ─── Write Queue ────────────────────────────────────────────────────────────
+export async function getWriteQueue(userId) {
+    try {
+        const raw = await getPlatform().storage.getItem(writeQueueKey(userId));
+        if (!raw)
+            return [];
+        return JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+}
+export async function addToWriteQueue(userId, write) {
+    try {
+        const queue = await getWriteQueue(userId);
+        queue.push({ ...write, retries: 0, createdAt: new Date().toISOString() });
+        await getPlatform().storage.setItem(writeQueueKey(userId), JSON.stringify(queue));
+    }
+    catch {
+        // ignore
+    }
+}
+export async function removeFromWriteQueue(userId, writeId) {
+    try {
+        const queue = await getWriteQueue(userId);
+        const updated = queue.filter(w => w.id !== writeId);
+        await getPlatform().storage.setItem(writeQueueKey(userId), JSON.stringify(updated));
+    }
+    catch {
+        // ignore
+    }
+}
+export async function incrementWriteRetry(userId, writeId) {
+    try {
+        const queue = await getWriteQueue(userId);
+        const updated = queue.map(w => w.id === writeId ? { ...w, retries: w.retries + 1 } : w);
+        // Drop writes that have exceeded 3 retries
+        const filtered = updated.filter(w => w.retries <= 3);
+        await getPlatform().storage.setItem(writeQueueKey(userId), JSON.stringify(filtered));
+    }
+    catch {
+        // ignore
+    }
+}
+// ─── Optimistic cache update ─────────────────────────────────────────────────
+export async function optimisticallyInsert(userId, collection, record) {
+    try {
+        const keys = await getPlatform().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        const collectionKeys = keys.filter(k => k.startsWith(prefix));
+        for (const key of collectionKeys) {
+            const raw = await getPlatform().storage.getItem(key);
+            if (!raw)
+                continue;
+            const cached = JSON.parse(raw);
+            cached.records = [record, ...cached.records];
+            cached.total = cached.total + 1;
+            await getPlatform().storage.setItem(key, JSON.stringify(cached));
+        }
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/esm/conflict.d.ts

@@ -0,0 +1,80 @@
+import { ConflictReason } from './offline-state.js';
+/** Resolves conflicts by id. */
+export interface ConflictResolver {
+    resolveWithLocal(conflictId: string): Promise<void>;
+    resolveWithServer(conflictId: string): Promise<void>;
+    resolveWithMerge(conflictId: string, data: Record<string, unknown>): Promise<void>;
+    abandon(conflictId: string): Promise<void>;
+}
+/**
+ * A queued offline write that could not be applied, waiting for a decision.
+ *
+ * Not an error to dismiss and not a write to retry: retrying cannot help, and
+ * discarding it would lose a change the user believes is saved. It waits, and
+ * keeps waiting across restarts, until the application decides.
+ *
+ * Only the application can decide. Whether a later edit should win depends on
+ * what the data means, and a platform that chooses for everyone is wrong for
+ * someone.
+ */
+export declare class KoolbaseConflict {
+    readonly id: string;
+    readonly reason: ConflictReason;
+    readonly operation: 'insert' | 'update' | 'delete';
+    readonly collection: string;
+    readonly recordId: string;
+    /** The change the user made, still unapplied. */
+    readonly local: Record<string, unknown> | undefined;
+    /** The record as it was when the change was composed, where that is known. */
+    readonly baseline: Record<string, unknown> | undefined;
+    /**
+     * The record as the server held it when the write was refused, captured with
+     * the refusal so deciding needs no fetch and cannot race one.
+     *
+     * Undefined when the reason is `baseline_unavailable` — nothing was ever
+     * sent, so the server never answered.
+     */
+    readonly server: Record<string, unknown> | undefined;
+    readonly baseRevision: number | undefined;
+    readonly serverRevision: number | undefined;
+    readonly createdAt: string;
+    private readonly resolver;
+    constructor(id: string, reason: ConflictReason, operation: 'insert' | 'update' | 'delete', collection: string, recordId: string, 
+    /** The change the user made, still unapplied. */
+    local: Record<string, unknown> | undefined, 
+    /** The record as it was when the change was composed, where that is known. */
+    baseline: Record<string, unknown> | undefined, 
+    /**
+     * The record as the server held it when the write was refused, captured with
+     * the refusal so deciding needs no fetch and cannot race one.
+     *
+     * Undefined when the reason is `baseline_unavailable` — nothing was ever
+     * sent, so the server never answered.
+     */
+    server: Record<string, unknown> | undefined, baseRevision: number | undefined, serverRevision: number | undefined, createdAt: string, resolver: ConflictResolver);
+    /**
+     * Fields where the user's change and the server's version disagree.
+     *
+     * Only the fields the change touches: a record accumulates values the write
+     * never asserted, and listing those would bury the real disagreement. Empty
+     * when there is no server version to compare against.
+     */
+    get divergentFields(): string[];
+    /** How long this has been waiting. Metadata, not a deletion rule. */
+    get ageMs(): number;
+    /**
+     * Reapplies the user's change to the record as it stands now.
+     *
+     * An explicit decision to overwrite the server's version of the fields that
+     * disagree. Conditional where a revision is known, so a record that moved
+     * again while someone was deciding produces a new conflict rather than an
+     * unnoticed overwrite.
+     */
+    resolveWithLocal(): Promise<void>;
+    /** Keeps the server's version and discards the user's change, as a decision. */
+    resolveWithServer(): Promise<void>;
+    /** Applies something the application composed from both versions. */
+    resolveWithMerge(data: Record<string, unknown>): Promise<void>;
+    /** Drops the change without claiming either version won. */
+    abandon(): Promise<void>;
+}

package/dist/esm/conflict.js

@@ -0,0 +1,80 @@
+/**
+ * A queued offline write that could not be applied, waiting for a decision.
+ *
+ * Not an error to dismiss and not a write to retry: retrying cannot help, and
+ * discarding it would lose a change the user believes is saved. It waits, and
+ * keeps waiting across restarts, until the application decides.
+ *
+ * Only the application can decide. Whether a later edit should win depends on
+ * what the data means, and a platform that chooses for everyone is wrong for
+ * someone.
+ */
+export class KoolbaseConflict {
+    constructor(id, reason, operation, collection, recordId, 
+    /** The change the user made, still unapplied. */
+    local, 
+    /** The record as it was when the change was composed, where that is known. */
+    baseline, 
+    /**
+     * The record as the server held it when the write was refused, captured with
+     * the refusal so deciding needs no fetch and cannot race one.
+     *
+     * Undefined when the reason is `baseline_unavailable` — nothing was ever
+     * sent, so the server never answered.
+     */
+    server, baseRevision, serverRevision, createdAt, resolver) {
+        this.id = id;
+        this.reason = reason;
+        this.operation = operation;
+        this.collection = collection;
+        this.recordId = recordId;
+        this.local = local;
+        this.baseline = baseline;
+        this.server = server;
+        this.baseRevision = baseRevision;
+        this.serverRevision = serverRevision;
+        this.createdAt = createdAt;
+        this.resolver = resolver;
+    }
+    /**
+     * Fields where the user's change and the server's version disagree.
+     *
+     * Only the fields the change touches: a record accumulates values the write
+     * never asserted, and listing those would bury the real disagreement. Empty
+     * when there is no server version to compare against.
+     */
+    get divergentFields() {
+        if (!this.local)
+            return [];
+        if (!this.server)
+            return Object.keys(this.local);
+        return Object.keys(this.local).filter((k) => JSON.stringify(this.server[k]) !== JSON.stringify(this.local[k]));
+    }
+    /** How long this has been waiting. Metadata, not a deletion rule. */
+    get ageMs() {
+        return Date.now() - new Date(this.createdAt).getTime();
+    }
+    /**
+     * Reapplies the user's change to the record as it stands now.
+     *
+     * An explicit decision to overwrite the server's version of the fields that
+     * disagree. Conditional where a revision is known, so a record that moved
+     * again while someone was deciding produces a new conflict rather than an
+     * unnoticed overwrite.
+     */
+    resolveWithLocal() {
+        return this.resolver.resolveWithLocal(this.id);
+    }
+    /** Keeps the server's version and discards the user's change, as a decision. */
+    resolveWithServer() {
+        return this.resolver.resolveWithServer(this.id);
+    }
+    /** Applies something the application composed from both versions. */
+    resolveWithMerge(data) {
+        return this.resolver.resolveWithMerge(this.id, data);
+    }
+    /** Drops the change without claiming either version won. */
+    abandon() {
+        return this.resolver.abandon(this.id);
+    }
+}

package/dist/esm/database-errors.d.ts

@@ -0,0 +1,101 @@
+import { KoolbaseError } from './errors.js';
+/**
+ * Base class for errors surfaced by the Koolbase data layer (database reads
+ * and writes). Every data error carries a `message` and, when the server
+ * provides one, its stable `code` (e.g. `not_found`, `validation_error`,
+ * `unique_violation`).
+ *
+ * Catch this to handle any data-layer failure generically, or catch a
+ * specific subclass to branch on the kind of failure.
+ */
+export declare class KoolbaseDataError extends KoolbaseError {
+    /**
+     * Structured payload from the server's error body, when it sent one — e.g. a
+     * revision_mismatch 409 carries {expected_revision, current_revision,
+     * record}. Attached by the factory; absent when the body had none.
+     */
+    details?: Record<string, unknown>;
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown when a write is rejected because the value would violate a
+ * collection's unique constraint — the server responds with 409 Conflict.
+ * Catch it to handle duplicates, e.g. an email or username already in use.
+ *
+ * `field` names the field that collided, when the server reports it
+ * (`details.field`) — useful when a collection has more than one unique
+ * constraint and you need to know which value clashed.
+ *
+ * Surfaced by `insert`, `update`, and `upsert` whenever the server is
+ * reachable and rejects the write with a 409. These writes are online-first:
+ * a server-side conflict throws immediately. Only a genuine network failure
+ * falls back to the offline queue, where a conflict that surfaces at sync
+ * time is handled by the sync engine rather than thrown here.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.upsert('users', { email }, { name });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseConflictError) {
+ *     showError(`That ${e.field ?? 'value'} is already registered.`);
+ *   }
+ * }
+ */
+export declare class KoolbaseConflictError extends KoolbaseDataError {
+    field?: string;
+    constructor(message?: string, field?: string);
+}
+/**
+ * Thrown when the requested record or collection does not exist — the server
+ * responds with 404 and code `not_found` / `record_not_found` /
+ * `collection_not_found`.
+ */
+export declare class KoolbaseNotFoundError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the request is rejected as invalid — the server responds with
+ * 400 and code `validation_error`.
+ */
+export declare class KoolbaseValidationError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the caller is authenticated but not allowed to perform the
+ * operation — the server responds with 403 and code `permission_denied`
+ * (typically a collection access rule rejecting the read/write).
+ */
+export declare class KoolbasePermissionError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the server is rate-limiting the caller — 429 with code
+ * `rate_limit`. Back off and retry after a short delay.
+ */
+export declare class KoolbaseRateLimitError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the supplied vector's length does not match the dimension
+ * declared on the collection's vector field — the server responds with
+ * 400 and code `vector_dimension_mismatch`. The message includes both
+ * the expected and actual dimensions so you can surface a precise error.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.setVector(id, 'embedding', [0.1, 0.2]); // 2 dims
+ * } catch (e) {
+ *   if (e instanceof KoolbaseVectorDimensionMismatchError) {
+ *     showError(e.message); // "expected 1536, got 2"
+ *   }
+ * }
+ */
+export declare class KoolbaseVectorDimensionMismatchError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * Maps a non-2xx data-layer response to a typed {@link KoolbaseDataError},
+ * preferring the server's stable `code` and falling back to the HTTP status
+ * for older or uncoded responses. Always returns an error to throw.
+ */
+export declare function koolbaseDataError(status: number, body: any, fallbackMessage?: string): KoolbaseError;

package/dist/esm/database-errors.js

@@ -0,0 +1,189 @@
+import { KoolbaseError, KoolbaseUnauthenticatedError } from './errors.js';
+/**
+ * Base class for errors surfaced by the Koolbase data layer (database reads
+ * and writes). Every data error carries a `message` and, when the server
+ * provides one, its stable `code` (e.g. `not_found`, `validation_error`,
+ * `unique_violation`).
+ *
+ * Catch this to handle any data-layer failure generically, or catch a
+ * specific subclass to branch on the kind of failure.
+ */
+export class KoolbaseDataError extends KoolbaseError {
+    constructor(message, code) {
+        super(message, code);
+        this.name = 'KoolbaseDataError';
+        Object.setPrototypeOf(this, KoolbaseDataError.prototype);
+    }
+}
+/**
+ * Thrown when a write is rejected because the value would violate a
+ * collection's unique constraint — the server responds with 409 Conflict.
+ * Catch it to handle duplicates, e.g. an email or username already in use.
+ *
+ * `field` names the field that collided, when the server reports it
+ * (`details.field`) — useful when a collection has more than one unique
+ * constraint and you need to know which value clashed.
+ *
+ * Surfaced by `insert`, `update`, and `upsert` whenever the server is
+ * reachable and rejects the write with a 409. These writes are online-first:
+ * a server-side conflict throws immediately. Only a genuine network failure
+ * falls back to the offline queue, where a conflict that surfaces at sync
+ * time is handled by the sync engine rather than thrown here.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.upsert('users', { email }, { name });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseConflictError) {
+ *     showError(`That ${e.field ?? 'value'} is already registered.`);
+ *   }
+ * }
+ */
+export class KoolbaseConflictError extends KoolbaseDataError {
+    constructor(message, field) {
+        super(message ?? 'Value violates a unique constraint', 'unique_violation');
+        this.field = field;
+        this.name = 'KoolbaseConflictError';
+        Object.setPrototypeOf(this, KoolbaseConflictError.prototype);
+    }
+}
+/**
+ * Thrown when the requested record or collection does not exist — the server
+ * responds with 404 and code `not_found` / `record_not_found` /
+ * `collection_not_found`.
+ */
+export class KoolbaseNotFoundError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'The requested resource was not found', 'not_found');
+        this.name = 'KoolbaseNotFoundError';
+        Object.setPrototypeOf(this, KoolbaseNotFoundError.prototype);
+    }
+}
+/**
+ * Thrown when the request is rejected as invalid — the server responds with
+ * 400 and code `validation_error`.
+ */
+export class KoolbaseValidationError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'The request was invalid', 'validation_error');
+        this.name = 'KoolbaseValidationError';
+        Object.setPrototypeOf(this, KoolbaseValidationError.prototype);
+    }
+}
+/**
+ * Thrown when the caller is authenticated but not allowed to perform the
+ * operation — the server responds with 403 and code `permission_denied`
+ * (typically a collection access rule rejecting the read/write).
+ */
+export class KoolbasePermissionError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'You do not have permission to perform this action', 'permission_denied');
+        this.name = 'KoolbasePermissionError';
+        Object.setPrototypeOf(this, KoolbasePermissionError.prototype);
+    }
+}
+/**
+ * Thrown when the server is rate-limiting the caller — 429 with code
+ * `rate_limit`. Back off and retry after a short delay.
+ */
+export class KoolbaseRateLimitError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Too many requests, please slow down', 'rate_limit');
+        this.name = 'KoolbaseRateLimitError';
+        Object.setPrototypeOf(this, KoolbaseRateLimitError.prototype);
+    }
+}
+/**
+ * Thrown when the supplied vector's length does not match the dimension
+ * declared on the collection's vector field — the server responds with
+ * 400 and code `vector_dimension_mismatch`. The message includes both
+ * the expected and actual dimensions so you can surface a precise error.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.setVector(id, 'embedding', [0.1, 0.2]); // 2 dims
+ * } catch (e) {
+ *   if (e instanceof KoolbaseVectorDimensionMismatchError) {
+ *     showError(e.message); // "expected 1536, got 2"
+ *   }
+ * }
+ */
+export class KoolbaseVectorDimensionMismatchError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Vector dimension does not match field declaration', 'vector_dimension_mismatch');
+        this.name = 'KoolbaseVectorDimensionMismatchError';
+        Object.setPrototypeOf(this, KoolbaseVectorDimensionMismatchError.prototype);
+    }
+}
+/**
+ * Maps a non-2xx data-layer response to a typed {@link KoolbaseDataError},
+ * preferring the server's stable `code` and falling back to the HTTP status
+ * for older or uncoded responses. Always returns an error to throw.
+ */
+export function koolbaseDataError(status, body, fallbackMessage = 'Request failed') {
+    const code = body?.code;
+    const message = body?.error ?? fallbackMessage;
+    const field = body?.details?.field;
+    const attach = (err) => {
+        // The body's structured details ride along on data errors — a
+        // revision_mismatch 409 carries the current revision and record, and
+        // discarding them here is how a refused conflict-resolution became
+        // permanently unresolvable: the information arrived and died in this file.
+        if (err instanceof KoolbaseDataError && body?.details) {
+            err.details = body.details;
+        }
+        return err;
+    };
+    // Status-first for auth: a 401 means the credentials were not accepted,
+    // whatever code the body claims. Trusting a mislabelled body here bypasses
+    // session-clearing and strands the app signed-in with dead credentials.
+    if (status === 401) {
+        return new KoolbaseUnauthenticatedError(message);
+    }
+    // ─── code-first ───
+    switch (code) {
+        case 'unique_violation':
+            return attach(new KoolbaseConflictError(message, field));
+        case 'not_found':
+        case 'record_not_found':
+        case 'collection_not_found':
+        case 'vector_not_found':
+        case 'vector_field_not_found':
+            return attach(new KoolbaseNotFoundError(message));
+        case 'unauthenticated':
+        case 'session_expired':
+        case 'invalid_token':
+            return attach(new KoolbaseUnauthenticatedError(message));
+        case 'permission_denied':
+            return attach(new KoolbasePermissionError(message));
+        case 'rate_limit':
+            return attach(new KoolbaseRateLimitError(message));
+        case 'validation_error':
+        case 'vector_collection_mismatch':
+        case 'unsupported_dimension':
+            return attach(new KoolbaseValidationError(message));
+        case 'vector_dimension_mismatch':
+            return attach(new KoolbaseVectorDimensionMismatchError(message));
+    }
+    // ─── status fallback (pre-code servers) ───
+    switch (status) {
+        case 409:
+            return attach(new KoolbaseConflictError(message));
+        case 404:
+            return attach(new KoolbaseNotFoundError(message));
+        case 401:
+            // The status carries the meaning: every 401 from this server reports the
+            // same code, so it cannot say whether the session expired, the key was
+            // revoked, or the header was malformed. Safe to treat uniformly because a
+            // permission failure is 403 — a 401 means the credentials were not
+            // accepted, not that this caller may not proceed.
+            return attach(new KoolbaseUnauthenticatedError(message));
+        case 403:
+            return attach(new KoolbasePermissionError(message));
+        case 429:
+            return attach(new KoolbaseRateLimitError(message));
+        case 400:
+            return attach(new KoolbaseValidationError(message));
+    }
+    return attach(new KoolbaseDataError(message, code));
+}