@syncular/client 0.30.5 → 0.30.7

package/dist/client.js

@@ -2327,7 +2327,8 @@ export class SyncClient {
             };
             this.#emitDiagnostics();
             return summary;
-        }, (error) => {
+        }, (caught) => {
+            const error = classifySqliteFailure(caught).error;
             const completedAtMs = this.#now();
             const code = error.code;
             this.#progress.update({

package/dist/database.d.ts

@@ -63,4 +63,7 @@ export declare function assertImageAlias(alias: string): void;
  */
 export declare function runTransaction<T>(depthHolder: {
     depth: number;
+    aborted?: {
+        error: unknown;
+    };
 }, run: (sql: string) => void, fn: () => T): T;

package/dist/database.js

@@ -1,3 +1,4 @@
+import { classifySqliteFailure } from './errors.js';
 /** Attach-schema aliases are code-chosen, never user input — enforce it. */
 export function assertImageAlias(alias) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
@@ -10,6 +11,10 @@ export function assertImageAlias(alias) {
  */
 export function runTransaction(depthHolder, run, fn) {
     const depth = depthHolder.depth;
+    if (depth === 0)
+        delete depthHolder.aborted;
+    else if (depthHolder.aborted)
+        throw depthHolder.aborted.error;
     const savepoint = `syncular_sp_${depth}`;
     if (depth === 0)
         run('BEGIN');
@@ -18,6 +23,9 @@ export function runTransaction(depthHolder, run, fn) {
     depthHolder.depth = depth + 1;
     try {
         const result = fn();
+        const aborted = depthHolder.aborted;
+        if (aborted)
+            throw aborted.error;
         depthHolder.depth = depth;
         if (depth === 0)
             run('COMMIT');
@@ -25,15 +33,26 @@ export function runTransaction(depthHolder, run, fn) {
             run(`RELEASE ${savepoint}`);
         return result;
     }
-    catch (error) {
+    catch (caught) {
+        const aborted = depthHolder.aborted;
+        const error = aborted?.error ?? caught;
         depthHolder.depth = depth;
-        if (depth === 0) {
-            run('ROLLBACK');
+        try {
+            if (depth === 0)
+                run('ROLLBACK');
+            else {
+                run(`ROLLBACK TO ${savepoint}`);
+                run(`RELEASE ${savepoint}`);
+            }
         }
-        else {
-            run(`ROLLBACK TO ${savepoint}`);
-            run(`RELEASE ${savepoint}`);
+        catch (rollbackError) {
+            // SQLite can end the whole transaction after SQLITE_FULL or SQLITE_IOERR.
+            // Poison remaining nested scopes until the outer owner unwinds.
+            depthHolder.aborted = { error };
+            if (error instanceof Error && !('rollbackError' in error)) {
+                Object.defineProperty(error, 'rollbackError', { value: rollbackError });
+            }
         }
-        throw error;
+        throw classifySqliteFailure(error).error;
     }
 }

package/dist/diagnostics.d.ts

@@ -113,7 +113,7 @@ export interface DiagnosticQueryFailure {
     readonly id: string;
     /** Distinct generated table names the query depends on, ascending. */
     readonly tables: readonly string[];
-    readonly code: 'client.storage_corrupt' | 'client.storage_io' | 'client.query_failed';
+    readonly code: 'client.storage_corrupt' | 'client.storage_full' | 'client.storage_io' | 'client.query_failed';
     /** SQLite extended result code, when the driver exposed one. */
     readonly sqliteCode?: number;
     /** First failure since this id's last successful read. */

package/dist/errors.d.ts

@@ -5,6 +5,8 @@ export declare const STORAGE_BUSY_CODE = "client.storage_busy";
 export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
 /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
 export declare const STORAGE_CORRUPT_CODE = "client.storage_corrupt";
+/** Local SQLite storage has no space for the write. */
+export declare const STORAGE_FULL_CODE = "client.storage_full";
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export declare const STORAGE_IO_CODE = "client.storage_io";
 /** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
@@ -20,7 +22,8 @@ export declare class ClientSyncError extends Error {
     readonly name: string;
     readonly code: string;
     readonly retryable: boolean;
-    constructor(code: string, message: string, retryable?: boolean);
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>);
 }
 /**
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
@@ -60,6 +63,6 @@ export declare class RealtimeUnavailableError extends ClientSyncError {
  */
 export declare function classifySqliteFailure(error: unknown): {
     readonly sqliteCode: number | undefined;
-    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_IO_CODE | undefined;
+    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_FULL_CODE | typeof STORAGE_IO_CODE | undefined;
     readonly error: unknown;
 };

package/dist/errors.js

@@ -4,6 +4,8 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
 export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
 /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
 export const STORAGE_CORRUPT_CODE = 'client.storage_corrupt';
+/** Local SQLite storage has no space for the write. */
+export const STORAGE_FULL_CODE = 'client.storage_full';
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export const STORAGE_IO_CODE = 'client.storage_io';
 /** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
@@ -19,10 +21,12 @@ export class ClientSyncError extends Error {
     name = 'ClientSyncError';
     code;
     retryable;
-    constructor(code, message, retryable = false) {
+    details;
+    constructor(code, message, retryable = false, details) {
         super(message);
         this.code = code;
         this.retryable = retryable;
+        this.details = details;
     }
 }
 /**
@@ -71,6 +75,31 @@ export class RealtimeUnavailableError extends ClientSyncError {
  * original value.
  */
 export function classifySqliteFailure(error) {
+    if (error instanceof ClientSyncError) {
+        const sqliteCode = error.details?.sqliteCode;
+        let retained = error;
+        if ('rollbackError' in error &&
+            error.details?.rollbackFailure === undefined) {
+            const rollback = error.rollbackError;
+            retained = new ClientSyncError(error.code, error.message, error.retryable, {
+                ...error.details,
+                rollbackFailure: {
+                    message: rollback instanceof Error ? rollback.message : String(rollback),
+                    sqliteCode: classifySqliteFailure(rollback).sqliteCode,
+                },
+            });
+            Object.defineProperty(retained, 'cause', { value: error });
+        }
+        return {
+            sqliteCode: typeof sqliteCode === 'number' ? sqliteCode : undefined,
+            code: error.code === STORAGE_FULL_CODE ||
+                error.code === STORAGE_IO_CODE ||
+                error.code === STORAGE_CORRUPT_CODE
+                ? error.code
+                : undefined,
+            error: retained,
+        };
+    }
     const sqliteCode = error instanceof Error
         ? error.name === 'SQLiteError' &&
             'errno' in error &&
@@ -85,19 +114,34 @@ export function classifySqliteFailure(error) {
                     : undefined
         : undefined;
     const primary = sqliteCode === undefined ? undefined : sqliteCode & 0xff;
-    if (primary === 11 || primary === 26) {
-        return {
-            sqliteCode,
-            code: STORAGE_CORRUPT_CODE,
-            error: new ClientSyncError(STORAGE_CORRUPT_CODE, 'local SQLite storage is corrupt'),
-        };
-    }
-    if (primary === 10) {
-        return {
-            sqliteCode,
-            code: STORAGE_IO_CODE,
-            error: new ClientSyncError(STORAGE_IO_CODE, 'local SQLite storage I/O failed'),
-        };
-    }
-    return { sqliteCode, code: undefined, error };
+    const code = primary === 13
+        ? STORAGE_FULL_CODE
+        : primary === 10
+            ? STORAGE_IO_CODE
+            : primary === 11 || primary === 26
+                ? STORAGE_CORRUPT_CODE
+                : undefined;
+    if (code === undefined)
+        return { sqliteCode, code, error };
+    const rollback = error instanceof Error && 'rollbackError' in error
+        ? error.rollbackError
+        : undefined;
+    const failure = new ClientSyncError(code, primary === 13
+        ? 'local SQLite storage is full'
+        : primary === 10
+            ? 'local SQLite storage I/O failed'
+            : 'local SQLite storage is corrupt', false, {
+        sqliteCode,
+        sqliteMessage: error instanceof Error ? error.message : String(error),
+        ...(rollback !== undefined
+            ? {
+                rollbackFailure: {
+                    message: rollback instanceof Error ? rollback.message : String(rollback),
+                    sqliteCode: classifySqliteFailure(rollback).sqliteCode,
+                },
+            }
+            : {}),
+    });
+    Object.defineProperty(failure, 'cause', { value: error });
+    return { sqliteCode, code, error: failure };
 }

package/dist/http.js

@@ -1,8 +1,8 @@
 import { SSP2_CONTENT_TYPE } from './content-type.js';
 import { ClientSyncError } from './errors.js';
-async function throwHttpError(response) {
+async function throwHttpError(response, details) {
     let code = 'sync.transport_failed';
-    let message = `HTTP ${response.status}`;
+    let message = 'HTTP request failed';
     let retryable = response.status >= 500 || response.status === 429;
     try {
         const body = (await response.json());
@@ -16,7 +16,10 @@ async function throwHttpError(response) {
     catch {
         // non-JSON error body — keep the HTTP-status defaults
     }
-    throw new ClientSyncError(code, message, retryable);
+    throw new ClientSyncError(code, message, retryable, {
+        ...details,
+        httpStatus: response.status,
+    });
 }
 function hostHeaders(options) {
     const headers = options?.headers;
@@ -136,25 +139,39 @@ async function readSegmentBody(response, onProgress) {
 }
 export function httpSegmentDownloader(segmentsBaseUrl, options) {
     const doFetch = options?.fetch ?? fetch;
-    const direct = async (request) => {
-        const response = await doFetch(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
-            headers: {
-                'X-Syncular-Scopes': request.requestedScopesJson,
-                ...hostHeaders(options),
-            },
-        });
-        if (!response.ok)
-            await throwHttpError(response);
-        return readSegmentBody(response, request.onProgress);
-    };
-    const fetchUrl = async (url, onProgress) => {
-        // Deliberately headerless: the URL is the bearer grant (§5.4).
-        const response = await doFetch(url);
-        if (!response.ok) {
-            throw new ClientSyncError('sync.transport_failed', `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`, true);
+    const download = async (url, init, onProgress, signed = false) => {
+        // A capability's query/fragment and URL credentials never enter details.
+        const path = URL.canParse(url)
+            ? new URL(url).pathname
+            : url.split(/[?#]/)[0];
+        let response;
+        try {
+            response = await doFetch(url, init);
+            if (!response.ok) {
+                if (!signed)
+                    await throwHttpError(response, { path });
+                throw new ClientSyncError('sync.transport_failed', 'signed segment request failed; invalidate the descriptor and re-pull', true, { path, httpStatus: response.status });
+            }
+            return await readSegmentBody(response, onProgress);
+        }
+        catch (error) {
+            if (error instanceof ClientSyncError)
+                throw error;
+            throw new ClientSyncError('sync.transport_failed', 'segment transfer failed', true, {
+                path,
+                ...(response !== undefined ? { httpStatus: response.status } : {}),
+                causeMessage: error instanceof Error ? error.message : String(error),
+            });
         }
-        return readSegmentBody(response, onProgress);
     };
+    const direct = (request) => download(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
+        headers: {
+            'X-Syncular-Scopes': request.requestedScopesJson,
+            ...hostHeaders(options),
+        },
+    }, request.onProgress);
+    // Deliberately headerless: the URL is the bearer grant (§5.4).
+    const fetchUrl = (url, onProgress) => download(url, undefined, onProgress, true);
     return Object.assign(direct, { fetchUrl });
 }
 /**

package/dist/multi-tab.d.ts

@@ -86,6 +86,7 @@ interface ResMessage {
         code: string;
         message: string;
         retryable: boolean;
+        details?: Readonly<Record<string, unknown>>;
     };
 }
 interface EventMessage {

package/dist/multi-tab.js

@@ -206,6 +206,9 @@ export class LeaderBridge {
                     code: error.code,
                     message: error.message,
                     retryable: error.retryable,
+                    ...(error.details !== undefined
+                        ? { details: error.details }
+                        : {}),
                 }
                 : {
                     code: WORKER_FAILED_CODE,
@@ -470,7 +473,7 @@ export class FollowerLink {
             }
             else {
                 const err = message.error;
-                inflight.reject(new ClientSyncError(err?.code ?? WORKER_FAILED_CODE, err?.message ?? 'follower request failed', err?.retryable ?? false));
+                inflight.reject(new ClientSyncError(err?.code ?? WORKER_FAILED_CODE, err?.message ?? 'follower request failed', err?.retryable ?? false, err?.details));
             }
             return;
         }

package/dist/reactive-store.js

@@ -246,6 +246,13 @@ class ObservationCache {
 }
 const EMPTY_ROWS = Object.freeze([]);
 const unreadQuerySnapshots = new Map();
+/** Schema floors stop network transfer; the retained local replica remains readable.
+ * Leadership stops still refuse local access through the unavailable owner. */
+function localReadsBlocked(availability) {
+    return (availability.state === 'blocked' &&
+        (availability.reason === 'leader-unreachable' ||
+            availability.reason === 'leader-incompatible'));
+}
 /** One frozen snapshot per phase and availability for entries that have no
  * successful read, so switching between unread entries keeps the snapshot and
  * `rows` identity. */
@@ -458,7 +465,7 @@ class QueryEntry {
     }
     #onAvailabilityChange() {
         const availability = this.store.availabilitySnapshot();
-        if (availability.state === 'blocked') {
+        if (localReadsBlocked(availability)) {
             this.#publish({
                 ...this.#state,
                 phase: 'blocked',
@@ -512,7 +519,7 @@ class QueryEntry {
         try {
             do {
                 this.#requested = false;
-                if (this.store.availabilitySnapshot().state === 'blocked')
+                if (localReadsBlocked(this.store.availabilitySnapshot()))
                     break;
                 if (generation !== this.#generation || this.#listeners.size === 0)
                     return;
@@ -537,7 +544,7 @@ class QueryEntry {
                 if (this.#claimError !== undefined)
                     throw this.#claimError;
                 const availability = this.store.availabilitySnapshot();
-                if (availability.state === 'blocked') {
+                if (localReadsBlocked(availability)) {
                     this.#publish({
                         ...this.#state,
                         phase: 'blocked',

package/dist/worker-entry.js

@@ -16,16 +16,18 @@
 import { SyncClient } from './client.js';
 import { withClientDiagnosticsHost, } from './diagnostics.js';
 import { encryptionConfigFromKeyring } from './encryption.js';
-import { ClientSyncError, STORAGE_BUSY_CODE } from './errors.js';
+import { classifySqliteFailure, ClientSyncError, STORAGE_BUSY_CODE, } from './errors.js';
 import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
 import { openPersistentWasmDatabase } from './wasm-database.js';
 import { WORKER_FAILED_CODE, } from './worker-protocol.js';
-function toErrorShape(error) {
+function toErrorShape(caught) {
+    const error = classifySqliteFailure(caught).error;
     if (error instanceof ClientSyncError) {
         return {
             code: error.code,
             message: error.message,
             retryable: error.retryable,
+            ...(error.details !== undefined ? { details: error.details } : {}),
         };
     }
     return {

package/dist/worker-host.js

@@ -466,7 +466,7 @@ async function startWorkerCore(options) {
                 case 'error': {
                     const entry = pending.get(message.id);
                     pending.delete(message.id);
-                    entry?.reject(new ClientSyncError(message.error.code, message.error.message, message.error.retryable));
+                    entry?.reject(new ClientSyncError(message.error.code, message.error.message, message.error.retryable, message.error.details));
                     break;
                 }
                 case 'event':

package/dist/worker-protocol.d.ts

@@ -175,6 +175,7 @@ export type MainToWorkerMessage = {
     readonly config: WorkerInitConfig;
 } | WorkerCallMessage;
 export interface WorkerErrorShape {
+    readonly details?: Readonly<Record<string, unknown>>;
     readonly code: string;
     readonly message: string;
     readonly retryable: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.5",
+  "version": "0.30.7",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.5"
+    "@syncular/core": "0.30.7"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.5",
+    "@syncular/server": "0.30.7",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -3391,7 +3391,8 @@ export class SyncClient {
           this.#emitDiagnostics();
           return summary;
         },
-        (error: unknown) => {
+        (caught: unknown) => {
+          const error = classifySqliteFailure(caught).error;
           const completedAtMs = this.#now();
           const code = (error as { code?: unknown }).code;
           this.#progress.update({

package/src/database.ts

@@ -1,3 +1,5 @@
+import { classifySqliteFailure } from './errors';
+
 /**
  * Storage abstraction: the client core runs on any SQLite that
  * implements this minimal synchronous surface. Tests use bun:sqlite
@@ -75,29 +77,43 @@ export function assertImageAlias(alias: string): void {
  * `run` executes a parameterless statement.
  */
 export function runTransaction<T>(
-  depthHolder: { depth: number },
+  depthHolder: { depth: number; aborted?: { error: unknown } },
   run: (sql: string) => void,
   fn: () => T,
 ): T {
   const depth = depthHolder.depth;
+  if (depth === 0) delete depthHolder.aborted;
+  else if (depthHolder.aborted) throw depthHolder.aborted.error;
   const savepoint = `syncular_sp_${depth}`;
   if (depth === 0) run('BEGIN');
   else run(`SAVEPOINT ${savepoint}`);
   depthHolder.depth = depth + 1;
   try {
     const result = fn();
+    const aborted = depthHolder.aborted as { error: unknown } | undefined;
+    if (aborted) throw aborted.error;
     depthHolder.depth = depth;
     if (depth === 0) run('COMMIT');
     else run(`RELEASE ${savepoint}`);
     return result;
-  } catch (error) {
+  } catch (caught) {
+    const aborted = depthHolder.aborted as { error: unknown } | undefined;
+    const error = aborted?.error ?? caught;
     depthHolder.depth = depth;
-    if (depth === 0) {
-      run('ROLLBACK');
-    } else {
-      run(`ROLLBACK TO ${savepoint}`);
-      run(`RELEASE ${savepoint}`);
+    try {
+      if (depth === 0) run('ROLLBACK');
+      else {
+        run(`ROLLBACK TO ${savepoint}`);
+        run(`RELEASE ${savepoint}`);
+      }
+    } catch (rollbackError) {
+      // SQLite can end the whole transaction after SQLITE_FULL or SQLITE_IOERR.
+      // Poison remaining nested scopes until the outer owner unwinds.
+      depthHolder.aborted = { error };
+      if (error instanceof Error && !('rollbackError' in error)) {
+        Object.defineProperty(error, 'rollbackError', { value: rollbackError });
+      }
     }
-    throw error;
+    throw classifySqliteFailure(error).error;
   }
 }

package/src/diagnostics.ts

@@ -151,6 +151,7 @@ export interface DiagnosticQueryFailure {
   readonly tables: readonly string[];
   readonly code:
     | 'client.storage_corrupt'
+    | 'client.storage_full'
     | 'client.storage_io'
     | 'client.query_failed';
   /** SQLite extended result code, when the driver exposed one. */

package/src/errors.ts

@@ -9,6 +9,9 @@ export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
 /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
 export const STORAGE_CORRUPT_CODE = 'client.storage_corrupt';
 
+/** Local SQLite storage has no space for the write. */
+export const STORAGE_FULL_CODE = 'client.storage_full';
+
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export const STORAGE_IO_CODE = 'client.storage_io';
 
@@ -27,11 +30,18 @@ export class ClientSyncError extends Error {
   override readonly name: string = 'ClientSyncError';
   readonly code: string;
   readonly retryable: boolean;
+  readonly details: Readonly<Record<string, unknown>> | undefined;
 
-  constructor(code: string, message: string, retryable = false) {
+  constructor(
+    code: string,
+    message: string,
+    retryable = false,
+    details?: Readonly<Record<string, unknown>>,
+  ) {
     super(message);
     this.code = code;
     this.retryable = retryable;
+    this.details = details;
   }
 }
 
@@ -100,10 +110,45 @@ export function classifySqliteFailure(error: unknown): {
   readonly sqliteCode: number | undefined;
   readonly code:
     | typeof STORAGE_CORRUPT_CODE
+    | typeof STORAGE_FULL_CODE
     | typeof STORAGE_IO_CODE
     | undefined;
   readonly error: unknown;
 } {
+  if (error instanceof ClientSyncError) {
+    const sqliteCode = error.details?.sqliteCode;
+    let retained = error;
+    if (
+      'rollbackError' in error &&
+      error.details?.rollbackFailure === undefined
+    ) {
+      const rollback = error.rollbackError;
+      retained = new ClientSyncError(
+        error.code,
+        error.message,
+        error.retryable,
+        {
+          ...error.details,
+          rollbackFailure: {
+            message:
+              rollback instanceof Error ? rollback.message : String(rollback),
+            sqliteCode: classifySqliteFailure(rollback).sqliteCode,
+          },
+        },
+      );
+      Object.defineProperty(retained, 'cause', { value: error });
+    }
+    return {
+      sqliteCode: typeof sqliteCode === 'number' ? sqliteCode : undefined,
+      code:
+        error.code === STORAGE_FULL_CODE ||
+        error.code === STORAGE_IO_CODE ||
+        error.code === STORAGE_CORRUPT_CODE
+          ? error.code
+          : undefined,
+      error: retained,
+    };
+  }
   const sqliteCode =
     error instanceof Error
       ? error.name === 'SQLiteError' &&
@@ -119,25 +164,41 @@ export function classifySqliteFailure(error: unknown): {
             : undefined
       : undefined;
   const primary = sqliteCode === undefined ? undefined : sqliteCode & 0xff;
-  if (primary === 11 || primary === 26) {
-    return {
-      sqliteCode,
-      code: STORAGE_CORRUPT_CODE,
-      error: new ClientSyncError(
-        STORAGE_CORRUPT_CODE,
-        'local SQLite storage is corrupt',
-      ),
-    };
-  }
-  if (primary === 10) {
-    return {
+  const code =
+    primary === 13
+      ? STORAGE_FULL_CODE
+      : primary === 10
+        ? STORAGE_IO_CODE
+        : primary === 11 || primary === 26
+          ? STORAGE_CORRUPT_CODE
+          : undefined;
+  if (code === undefined) return { sqliteCode, code, error };
+  const rollback =
+    error instanceof Error && 'rollbackError' in error
+      ? error.rollbackError
+      : undefined;
+  const failure = new ClientSyncError(
+    code,
+    primary === 13
+      ? 'local SQLite storage is full'
+      : primary === 10
+        ? 'local SQLite storage I/O failed'
+        : 'local SQLite storage is corrupt',
+    false,
+    {
       sqliteCode,
-      code: STORAGE_IO_CODE,
-      error: new ClientSyncError(
-        STORAGE_IO_CODE,
-        'local SQLite storage I/O failed',
-      ),
-    };
-  }
-  return { sqliteCode, code: undefined, error };
+      sqliteMessage: error instanceof Error ? error.message : String(error),
+      ...(rollback !== undefined
+        ? {
+            rollbackFailure: {
+              message:
+                rollback instanceof Error ? rollback.message : String(rollback),
+              sqliteCode: classifySqliteFailure(rollback).sqliteCode,
+            },
+          }
+        : {}),
+    },
+  );
+  Object.defineProperty(failure, 'cause', { value: error });
+  return { sqliteCode, code, error: failure };
 }

package/src/http.ts

@@ -15,9 +15,12 @@ import type {
   SyncTransport,
 } from './transport';
 
-async function throwHttpError(response: Response): Promise<never> {
+async function throwHttpError(
+  response: Response,
+  details?: Readonly<Record<string, unknown>>,
+): Promise<never> {
   let code = 'sync.transport_failed';
-  let message = `HTTP ${response.status}`;
+  let message = 'HTTP request failed';
   let retryable = response.status >= 500 || response.status === 429;
   try {
     const body = (await response.json()) as {
@@ -31,7 +34,10 @@ async function throwHttpError(response: Response): Promise<never> {
   } catch {
     // non-JSON error body — keep the HTTP-status defaults
   }
-  throw new ClientSyncError(code, message, retryable);
+  throw new ClientSyncError(code, message, retryable, {
+    ...details,
+    httpStatus: response.status,
+  });
 }
 
 export interface HttpTransportOptions {
@@ -192,12 +198,49 @@ export function httpSegmentDownloader(
   options?: HttpTransportOptions,
 ): SegmentDownloader {
   const doFetch = options?.fetch ?? fetch;
-  const direct = async (request: {
+  const download = async (
+    url: string,
+    init?: RequestInit,
+    onProgress?: (bytesReceived: number) => void,
+    signed = false,
+  ) => {
+    // A capability's query/fragment and URL credentials never enter details.
+    const path = URL.canParse(url)
+      ? new URL(url).pathname
+      : url.split(/[?#]/)[0];
+    let response: Response | undefined;
+    try {
+      response = await doFetch(url, init);
+      if (!response.ok) {
+        if (!signed) await throwHttpError(response, { path });
+        throw new ClientSyncError(
+          'sync.transport_failed',
+          'signed segment request failed; invalidate the descriptor and re-pull',
+          true,
+          { path, httpStatus: response.status },
+        );
+      }
+      return await readSegmentBody(response, onProgress);
+    } catch (error) {
+      if (error instanceof ClientSyncError) throw error;
+      throw new ClientSyncError(
+        'sync.transport_failed',
+        'segment transfer failed',
+        true,
+        {
+          path,
+          ...(response !== undefined ? { httpStatus: response.status } : {}),
+          causeMessage: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  };
+  const direct = (request: {
     readonly segmentId: string;
     readonly requestedScopesJson: string;
     readonly onProgress?: (bytesReceived: number) => void;
-  }) => {
-    const response = await doFetch(
+  }) =>
+    download(
       `${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`,
       {
         headers: {
@@ -205,25 +248,13 @@ export function httpSegmentDownloader(
           ...hostHeaders(options),
         },
       },
+      request.onProgress,
     );
-    if (!response.ok) await throwHttpError(response);
-    return readSegmentBody(response, request.onProgress);
-  };
-  const fetchUrl = async (
+  // Deliberately headerless: the URL is the bearer grant (§5.4).
+  const fetchUrl = (
     url: string,
     onProgress?: (bytesReceived: number) => void,
-  ) => {
-    // Deliberately headerless: the URL is the bearer grant (§5.4).
-    const response = await doFetch(url);
-    if (!response.ok) {
-      throw new ClientSyncError(
-        'sync.transport_failed',
-        `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`,
-        true,
-      );
-    }
-    return readSegmentBody(response, onProgress);
-  };
+  ) => download(url, undefined, onProgress, true);
   return Object.assign(direct, { fetchUrl });
 }
 

package/src/multi-tab.ts

@@ -171,7 +171,12 @@ interface ResMessage {
   readonly reqId: number;
   readonly ok: boolean;
   readonly value?: unknown;
-  readonly error?: { code: string; message: string; retryable: boolean };
+  readonly error?: {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: Readonly<Record<string, unknown>>;
+  };
 }
 
 interface EventMessage {
@@ -336,6 +341,9 @@ export class LeaderBridge {
                 code: error.code,
                 message: error.message,
                 retryable: error.retryable,
+                ...(error.details !== undefined
+                  ? { details: error.details }
+                  : {}),
               }
             : {
                 code: WORKER_FAILED_CODE,
@@ -682,6 +690,7 @@ export class FollowerLink {
             err?.code ?? WORKER_FAILED_CODE,
             err?.message ?? 'follower request failed',
             err?.retryable ?? false,
+            err?.details,
           ),
         );
       }

package/src/reactive-store.ts

@@ -371,6 +371,16 @@ class ObservationCache {
 const EMPTY_ROWS: readonly never[] = Object.freeze([]);
 const unreadQuerySnapshots = new Map<string, LiveQueryResult<never>>();
 
+/** Schema floors stop network transfer; the retained local replica remains readable.
+ * Leadership stops still refuse local access through the unavailable owner. */
+function localReadsBlocked(availability: SyncAvailability): boolean {
+  return (
+    availability.state === 'blocked' &&
+    (availability.reason === 'leader-unreachable' ||
+      availability.reason === 'leader-incompatible')
+  );
+}
+
 /** One frozen snapshot per phase and availability for entries that have no
  * successful read, so switching between unread entries keeps the snapshot and
  * `rows` identity. */
@@ -598,7 +608,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
 
   #onAvailabilityChange(): void {
     const availability = this.store.availabilitySnapshot();
-    if (availability.state === 'blocked') {
+    if (localReadsBlocked(availability)) {
       this.#publish({
         ...this.#state,
         phase: 'blocked',
@@ -654,7 +664,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     try {
       do {
         this.#requested = false;
-        if (this.store.availabilitySnapshot().state === 'blocked') break;
+        if (localReadsBlocked(this.store.availabilitySnapshot())) break;
 
         if (generation !== this.#generation || this.#listeners.size === 0)
           return;
@@ -681,7 +691,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
           return;
         if (this.#claimError !== undefined) throw this.#claimError;
         const availability = this.store.availabilitySnapshot();
-        if (availability.state === 'blocked') {
+        if (localReadsBlocked(availability)) {
           this.#publish({
             ...this.#state,
             phase: 'blocked',

package/src/worker-entry.ts

@@ -20,7 +20,11 @@ import {
   withClientDiagnosticsHost,
 } from './diagnostics';
 import { encryptionConfigFromKeyring } from './encryption';
-import { ClientSyncError, STORAGE_BUSY_CODE } from './errors';
+import {
+  classifySqliteFailure,
+  ClientSyncError,
+  STORAGE_BUSY_CODE,
+} from './errors';
 import {
   httpBlobTransport,
   httpSegmentDownloader,
@@ -77,12 +81,14 @@ interface WorkerScope {
   ): void;
 }
 
-function toErrorShape(error: unknown): WorkerErrorShape {
+function toErrorShape(caught: unknown): WorkerErrorShape {
+  const error = classifySqliteFailure(caught).error;
   if (error instanceof ClientSyncError) {
     return {
       code: error.code,
       message: error.message,
       retryable: error.retryable,
+      ...(error.details !== undefined ? { details: error.details } : {}),
     };
   }
   return {

package/src/worker-host.ts

@@ -843,6 +843,7 @@ async function startWorkerCore(options: {
               message.error.code,
               message.error.message,
               message.error.retryable,
+              message.error.details,
             ),
           );
           break;

package/src/worker-protocol.ts

@@ -233,6 +233,7 @@ export type MainToWorkerMessage =
   | WorkerCallMessage;
 
 export interface WorkerErrorShape {
+  readonly details?: Readonly<Record<string, unknown>>;
   readonly code: string;
   readonly message: string;
   readonly retryable: boolean;