@syncular/client 0.24.0 → 0.25.0

package/README.md

@@ -288,7 +288,12 @@ and generated table names, never scopes. It lets a support screen distinguish
 an absent registration from a legitimate zero-row completed bootstrap. The
 snapshot also distinguishes reset, revocation, failure, schema floor, lease
 stop, pending outbox, offline transport, and storage pressure/unreadability.
-Worker leaders and followers return identical evidence with their honest role.
+`queryFailures` retains at most 256 failed owned snapshot reads until each query
+reads successfully. An entry contains only its stable PHI-free owner id,
+generated table names, a stable code, an optional numeric SQLite result code,
+and the first failure time. It excludes SQL, parameters, rows, and SQLite error
+prose. Worker leaders and followers return identical evidence with their honest
+role.
 
 The contract intentionally excludes scope values, rows and clinical row
 counts, SQL, paths, client/actor/lease ids, auth, keys, mutation bodies, stack

package/dist/client.d.ts

@@ -246,6 +246,16 @@ export interface QueryReadSpec {
     readonly sql: string;
     readonly params?: readonly SqlValue[];
     readonly coverage?: readonly WindowCoverage[];
+    /**
+     * SPEC §7.5: the owning query. A failed owned read is reported in
+     * `diagnosticsSnapshot().queryFailures` until the owner reads successfully.
+     * The id is application-owned and must never contain PHI.
+     */
+    readonly owner?: QueryOwner;
+}
+export interface QueryOwner {
+    readonly id: string;
+    readonly tables: readonly string[];
 }
 export interface QuerySnapshot<Row = SqlRow> {
     readonly revision: LocalRevision;

package/dist/client.js

@@ -13,8 +13,8 @@ import { EncryptError } from '@syncular/core';
 import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
-import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.js';
-import { ClientSyncError } from './errors.js';
+import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
+import { ClientSyncError, classifySqliteFailure } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
@@ -182,6 +182,8 @@ export class SyncClient {
     #diagnosticsPending = false;
     #lastRound;
     #lastChange;
+    /** SPEC §7.6: owner id -> latest failed owned read, oldest first. */
+    #queryFailures = new Map();
     /** The batch accumulator; non-undefined only inside `#applyBatch`. */
     #batch;
     /**
@@ -604,7 +606,12 @@ export class SyncClient {
         assertReadOnlyQuery(sql);
         // RFC 0005's container lives in a separate database file, so this
         // connection cannot see it and there is no table-access guard to run.
-        return stripSyncColumns(this.#db.query(sql, params));
+        try {
+            return stripSyncColumns(this.#db.query(sql, params));
+        }
+        catch (error) {
+            throw classifySqliteFailure(error).error;
+        }
     }
     /** Current durable local observer revision (SPEC §7.5). */
     get localRevision() {
@@ -618,44 +625,81 @@ export class SyncClient {
      */
     querySnapshot(spec) {
         this.#requireActive();
-        assertReadOnlyQuery(spec.sql);
-        return this.#db.transaction(() => {
-            const revision = getLocalRevision(this.#db);
-            const rows = stripSyncColumns(this.#db.query(spec.sql, spec.params));
-            const pending = [];
-            const missing = [];
-            for (const requested of spec.coverage ?? []) {
-                const baseKey = windowBaseKey(requested.base);
-                const live = new Map(loadWindowUnits(this.#db, baseKey).map((entry) => [
-                    entry.unit,
-                    entry.subId,
-                ]));
-                for (const unit of new Set(requested.units)) {
-                    const subId = live.get(unit);
-                    const ref = { baseKey, unit };
-                    if (subId === undefined) {
-                        missing.push(ref);
-                        continue;
+        const owner = spec.owner;
+        let snapshot;
+        try {
+            assertReadOnlyQuery(spec.sql);
+            snapshot = this.#db.transaction(() => {
+                const revision = getLocalRevision(this.#db);
+                const rows = stripSyncColumns(this.#db.query(spec.sql, spec.params));
+                const pending = [];
+                const missing = [];
+                for (const requested of spec.coverage ?? []) {
+                    const baseKey = windowBaseKey(requested.base);
+                    const live = new Map(loadWindowUnits(this.#db, baseKey).map((entry) => [
+                        entry.unit,
+                        entry.subId,
+                    ]));
+                    for (const unit of new Set(requested.units)) {
+                        const subId = live.get(unit);
+                        const ref = { baseKey, unit };
+                        if (subId === undefined) {
+                            missing.push(ref);
+                            continue;
+                        }
+                        const sub = getSubscription(this.#db, subId);
+                        if (sub === undefined ||
+                            sub.status !== 'active' ||
+                            sub.cursor < 0 ||
+                            sub.bootstrapState !== undefined) {
+                            pending.push(ref);
+                        }
                     }
-                    const sub = getSubscription(this.#db, subId);
-                    if (sub === undefined ||
-                        sub.status !== 'active' ||
-                        sub.cursor < 0 ||
-                        sub.bootstrapState !== undefined) {
-                        pending.push(ref);
+                }
+                return {
+                    revision,
+                    rows,
+                    coverage: {
+                        complete: pending.length === 0 && missing.length === 0,
+                        pending,
+                        missing,
+                    },
+                };
+            });
+        }
+        catch (error) {
+            const failure = classifySqliteFailure(error);
+            const sqliteCode = failure.sqliteCode;
+            const code = failure.code ?? 'client.query_failed';
+            if (owner !== undefined) {
+                const tables = [...new Set(owner.tables)].sort();
+                const previous = this.#queryFailures.get(owner.id);
+                if (previous === undefined ||
+                    previous.code !== code ||
+                    previous.sqliteCode !== sqliteCode ||
+                    previous.tables.join('\0') !== tables.join('\0')) {
+                    this.#queryFailures.delete(owner.id);
+                    this.#queryFailures.set(owner.id, {
+                        id: owner.id,
+                        tables,
+                        code,
+                        ...(sqliteCode !== undefined ? { sqliteCode } : {}),
+                        atMs: this.#now(),
+                    });
+                    for (const id of this.#queryFailures.keys()) {
+                        if (this.#queryFailures.size <= MAX_DIAGNOSTIC_QUERY_FAILURES)
+                            break;
+                        this.#queryFailures.delete(id);
                     }
+                    this.#emitDiagnostics();
                 }
             }
-            return {
-                revision,
-                rows,
-                coverage: {
-                    complete: pending.length === 0 && missing.length === 0,
-                    pending,
-                    missing,
-                },
-            };
-        });
+            throw failure.error;
+        }
+        if (owner !== undefined && this.#queryFailures.delete(owner.id)) {
+            this.#emitDiagnostics();
+        }
+        return snapshot;
     }
     // -- previous-version context (RFC 0005) ----------------------------------
     /**
@@ -999,6 +1043,7 @@ export class SyncClient {
                 ? { lastChange: this.#lastChange }
                 : {}),
             storage: this.#diagnosticStorage(),
+            queryFailures: [...this.#queryFailures.values()],
         };
     }
     #diagnosticLease(nowMs) {
@@ -1822,7 +1867,20 @@ export class SyncClient {
                )`, [clientCommitId, blobId, blobId]);
                     }
                 }
-                this.#applyOperationsLocally(operations, batch);
+                try {
+                    this.#applyOperationsLocally(operations, batch);
+                }
+                catch (error) {
+                    if (error instanceof Error &&
+                        error.message.includes('UNIQUE constraint failed:') &&
+                        (('errno' in error && error.errno === 2067) ||
+                            ('errcode' in error && error.errcode === 2067) ||
+                            ('resultCode' in error &&
+                                (error.resultCode === 19 || error.resultCode === 2067)))) {
+                        throw new ClientSyncError('sync.constraint_violation', 'local write violates a unique constraint');
+                    }
+                    throw error;
+                }
                 batch.status();
             });
             this.#needsPull = true;

package/dist/diagnostics.d.ts

@@ -9,6 +9,7 @@ import type { SecurityLifecycle } from './client.js';
 export declare const CLIENT_DIAGNOSTICS_VERSION: 1;
 export declare const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
 export declare const MAX_DIAGNOSTIC_DOMAINS = 256;
+export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
 export type ClientDiagnosticsHostKind = 'direct' | 'worker' | 'tauri' | 'react-native';
 export type ClientDiagnosticsHostRole = 'single' | 'leader' | 'follower' | 'unknown';
 export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
@@ -95,6 +96,18 @@ export interface ClientDiagnosticsStorage {
     readonly blobCacheBytesApprox?: number;
     readonly pressureReasonCode?: 'client.blob_cache_over_limit';
 }
+/** The latest owned snapshot read of one query id failed (SPEC §7.6). */
+export interface DiagnosticQueryFailure {
+    /** Application-owned stable query id. It must never contain PHI. */
+    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';
+    /** SQLite extended result code, when the driver exposed one. */
+    readonly sqliteCode?: number;
+    /** First failure since this id's last successful read. */
+    readonly atMs: number;
+}
 export interface ClientDiagnosticsSnapshot {
     readonly version: typeof CLIENT_DIAGNOSTICS_VERSION;
     readonly capturedAtMs: number;
@@ -122,6 +135,7 @@ export interface ClientDiagnosticsSnapshot {
     readonly lastRound?: DiagnosticLastRound;
     readonly lastChange?: DiagnosticLastChange;
     readonly storage: ClientDiagnosticsStorage;
+    readonly queryFailures: readonly DiagnosticQueryFailure[];
 }
 export type ClientDiagnosticsListener = (snapshot: ClientDiagnosticsSnapshot) => void;
 export declare class ClientDiagnosticsEmitter {

package/dist/diagnostics.js

@@ -1,6 +1,7 @@
 export const CLIENT_DIAGNOSTICS_VERSION = 1;
 export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
 export const MAX_DIAGNOSTIC_DOMAINS = 256;
+export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
 export class ClientDiagnosticsEmitter {
     #listeners = new Set();
     get observed() {

package/dist/errors.d.ts

@@ -2,6 +2,10 @@
 export declare const STORAGE_BUSY_CODE = "client.storage_busy";
 /** The browser cannot provide the persistent storage APIs Syncular requires. */
 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";
+/** A local read hit SQLITE_IOERR (SPEC §7.5). */
+export declare const STORAGE_IO_CODE = "client.storage_io";
 /**
  * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
  * unchanged. Host/runtime-only conditions may use the separate `client.*`
@@ -13,3 +17,15 @@ export declare class ClientSyncError extends Error {
     readonly retryable: boolean;
     constructor(code: string, message: string, retryable?: boolean);
 }
+/**
+ * SPEC §7.5: classify a local SQLite read failure by the numeric result code
+ * the driver exposes (bun:sqlite `errno`, node:sqlite `errcode`, sqlite-wasm
+ * `resultCode`), never by message text. `error` is what the read throws: a
+ * stable `ClientSyncError` for corruption or I/O failure, otherwise the
+ * original value.
+ */
+export declare function classifySqliteFailure(error: unknown): {
+    readonly sqliteCode: number | undefined;
+    readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_IO_CODE | undefined;
+    readonly error: unknown;
+};

package/dist/errors.js

@@ -2,6 +2,10 @@
 export const STORAGE_BUSY_CODE = 'client.storage_busy';
 /** The browser cannot provide the persistent storage APIs Syncular requires. */
 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';
+/** A local read hit SQLITE_IOERR (SPEC §7.5). */
+export const STORAGE_IO_CODE = 'client.storage_io';
 /**
  * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
  * unchanged. Host/runtime-only conditions may use the separate `client.*`
@@ -17,3 +21,41 @@ export class ClientSyncError extends Error {
         this.retryable = retryable;
     }
 }
+/**
+ * SPEC §7.5: classify a local SQLite read failure by the numeric result code
+ * the driver exposes (bun:sqlite `errno`, node:sqlite `errcode`, sqlite-wasm
+ * `resultCode`), never by message text. `error` is what the read throws: a
+ * stable `ClientSyncError` for corruption or I/O failure, otherwise the
+ * original value.
+ */
+export function classifySqliteFailure(error) {
+    const sqliteCode = error instanceof Error
+        ? error.name === 'SQLiteError' &&
+            'errno' in error &&
+            typeof error.errno === 'number'
+            ? error.errno
+            : 'errcode' in error && typeof error.errcode === 'number'
+                ? error.errcode
+                : error.name === 'SQLite3Error' &&
+                    'resultCode' in error &&
+                    typeof error.resultCode === 'number'
+                    ? error.resultCode
+                    : 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 };
+}

package/dist/reactive-store.js

@@ -445,6 +445,10 @@ class QueryEntry {
                     ...(this.spec.coverage !== undefined
                         ? { coverage: this.spec.coverage }
                         : {}),
+                    owner: {
+                        id: this.spec.id,
+                        tables: this.spec.dependencies.map((dependency) => dependency.table),
+                    },
                 });
                 if (generation !== this.#generation || this.#listeners.size === 0)
                     return;
@@ -490,11 +494,12 @@ class QueryEntry {
         catch (error) {
             if (generation !== this.#generation || this.#listeners.size === 0)
                 return;
-            const wrapped = errorOf(error);
+            // SPEC §7.5: a failed latest read is never `ready`; the last
+            // successful rows and revision stay available beside the error.
             this.#publish({
                 ...this.#state,
-                phase: this.#state.revision === undefined ? 'error' : this.#state.phase,
-                error: wrapped,
+                phase: 'error',
+                error: errorOf(error),
                 isRefreshing: false,
                 availability: this.store.availabilitySnapshot(),
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "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.24.0"
+    "@syncular/core": "0.25.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.24.0",
+    "@syncular/server": "0.25.0",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -76,13 +76,15 @@ import {
   type ClientDiagnosticsStorage,
   type DiagnosticLastChange,
   type DiagnosticLastRound,
+  type DiagnosticQueryFailure,
   type DiagnosticRoundCounters,
   type DiagnosticSubscription,
   MAX_DIAGNOSTIC_DOMAINS,
   MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
+  MAX_DIAGNOSTIC_QUERY_FAILURES,
 } from './diagnostics';
 import type { EncryptionConfig } from './encryption';
-import { ClientSyncError } from './errors';
+import { ClientSyncError, classifySqliteFailure } from './errors';
 import {
   ChangeAccumulator,
   ChangeEmitter,
@@ -480,6 +482,17 @@ export interface QueryReadSpec {
   readonly sql: string;
   readonly params?: readonly SqlValue[];
   readonly coverage?: readonly WindowCoverage[];
+  /**
+   * SPEC §7.5: the owning query. A failed owned read is reported in
+   * `diagnosticsSnapshot().queryFailures` until the owner reads successfully.
+   * The id is application-owned and must never contain PHI.
+   */
+  readonly owner?: QueryOwner;
+}
+
+export interface QueryOwner {
+  readonly id: string;
+  readonly tables: readonly string[];
 }
 
 export interface QuerySnapshot<Row = SqlRow> {
@@ -757,6 +770,8 @@ export class SyncClient {
   #diagnosticsPending = false;
   #lastRound: DiagnosticLastRound | undefined;
   #lastChange: DiagnosticLastChange | undefined;
+  /** SPEC §7.6: owner id -> latest failed owned read, oldest first. */
+  readonly #queryFailures = new Map<string, DiagnosticQueryFailure>();
   /** The batch accumulator; non-undefined only inside `#applyBatch`. */
   #batch: ChangeAccumulator | undefined;
   /**
@@ -1250,7 +1265,11 @@ export class SyncClient {
     assertReadOnlyQuery(sql);
     // RFC 0005's container lives in a separate database file, so this
     // connection cannot see it and there is no table-access guard to run.
-    return stripSyncColumns(this.#db.query(sql, params));
+    try {
+      return stripSyncColumns(this.#db.query(sql, params));
+    } catch (error) {
+      throw classifySqliteFailure(error).error;
+    }
   }
 
   /** Current durable local observer revision (SPEC §7.5). */
@@ -1266,50 +1285,88 @@ export class SyncClient {
    */
   querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> {
     this.#requireActive();
-    assertReadOnlyQuery(spec.sql);
-    return this.#db.transaction(() => {
-      const revision = getLocalRevision(this.#db);
-      const rows = stripSyncColumns(
-        this.#db.query(spec.sql, spec.params),
-      ) as unknown as readonly Row[];
-      const pending: WindowUnitRef[] = [];
-      const missing: WindowUnitRef[] = [];
-      for (const requested of spec.coverage ?? []) {
-        const baseKey = windowBaseKey(requested.base);
-        const live = new Map(
-          loadWindowUnits(this.#db, baseKey).map((entry) => [
-            entry.unit,
-            entry.subId,
-          ]),
-        );
-        for (const unit of new Set(requested.units)) {
-          const subId = live.get(unit);
-          const ref = { baseKey, unit };
-          if (subId === undefined) {
-            missing.push(ref);
-            continue;
+    const owner = spec.owner;
+    let snapshot: QuerySnapshot<Row>;
+    try {
+      assertReadOnlyQuery(spec.sql);
+      snapshot = this.#db.transaction(() => {
+        const revision = getLocalRevision(this.#db);
+        const rows = stripSyncColumns(
+          this.#db.query(spec.sql, spec.params),
+        ) as unknown as readonly Row[];
+        const pending: WindowUnitRef[] = [];
+        const missing: WindowUnitRef[] = [];
+        for (const requested of spec.coverage ?? []) {
+          const baseKey = windowBaseKey(requested.base);
+          const live = new Map(
+            loadWindowUnits(this.#db, baseKey).map((entry) => [
+              entry.unit,
+              entry.subId,
+            ]),
+          );
+          for (const unit of new Set(requested.units)) {
+            const subId = live.get(unit);
+            const ref = { baseKey, unit };
+            if (subId === undefined) {
+              missing.push(ref);
+              continue;
+            }
+            const sub = getSubscription(this.#db, subId);
+            if (
+              sub === undefined ||
+              sub.status !== 'active' ||
+              sub.cursor < 0 ||
+              sub.bootstrapState !== undefined
+            ) {
+              pending.push(ref);
+            }
           }
-          const sub = getSubscription(this.#db, subId);
-          if (
-            sub === undefined ||
-            sub.status !== 'active' ||
-            sub.cursor < 0 ||
-            sub.bootstrapState !== undefined
-          ) {
-            pending.push(ref);
+        }
+        return {
+          revision,
+          rows,
+          coverage: {
+            complete: pending.length === 0 && missing.length === 0,
+            pending,
+            missing,
+          },
+        };
+      });
+    } catch (error) {
+      const failure = classifySqliteFailure(error);
+      const sqliteCode = failure.sqliteCode;
+      const code = failure.code ?? 'client.query_failed';
+      if (owner !== undefined) {
+        const tables = [...new Set(owner.tables)].sort();
+        const previous = this.#queryFailures.get(owner.id);
+        if (
+          previous === undefined ||
+          previous.code !== code ||
+          previous.sqliteCode !== sqliteCode ||
+          previous.tables.join('\0') !== tables.join('\0')
+        ) {
+          this.#queryFailures.delete(owner.id);
+          this.#queryFailures.set(owner.id, {
+            id: owner.id,
+            tables,
+            code,
+            ...(sqliteCode !== undefined ? { sqliteCode } : {}),
+            atMs: this.#now(),
+          });
+          for (const id of this.#queryFailures.keys()) {
+            if (this.#queryFailures.size <= MAX_DIAGNOSTIC_QUERY_FAILURES)
+              break;
+            this.#queryFailures.delete(id);
           }
+          this.#emitDiagnostics();
         }
       }
-      return {
-        revision,
-        rows,
-        coverage: {
-          complete: pending.length === 0 && missing.length === 0,
-          pending,
-          missing,
-        },
-      };
-    });
+      throw failure.error;
+    }
+    if (owner !== undefined && this.#queryFailures.delete(owner.id)) {
+      this.#emitDiagnostics();
+    }
+    return snapshot;
   }
 
   // -- previous-version context (RFC 0005) ----------------------------------
@@ -1729,6 +1786,7 @@ export class SyncClient {
         ? { lastChange: this.#lastChange }
         : {}),
       storage: this.#diagnosticStorage(),
+      queryFailures: [...this.#queryFailures.values()],
     };
   }
 
@@ -2751,7 +2809,24 @@ export class SyncClient {
             );
           }
         }
-        this.#applyOperationsLocally(operations, batch);
+        try {
+          this.#applyOperationsLocally(operations, batch);
+        } catch (error) {
+          if (
+            error instanceof Error &&
+            error.message.includes('UNIQUE constraint failed:') &&
+            (('errno' in error && error.errno === 2067) ||
+              ('errcode' in error && error.errcode === 2067) ||
+              ('resultCode' in error &&
+                (error.resultCode === 19 || error.resultCode === 2067)))
+          ) {
+            throw new ClientSyncError(
+              'sync.constraint_violation',
+              'local write violates a unique constraint',
+            );
+          }
+          throw error;
+        }
         batch.status();
       });
       this.#needsPull = true;

package/src/diagnostics.ts

@@ -10,6 +10,7 @@ import type { SecurityLifecycle } from './client';
 export const CLIENT_DIAGNOSTICS_VERSION = 1 as const;
 export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
 export const MAX_DIAGNOSTIC_DOMAINS = 256;
+export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
 
 export type ClientDiagnosticsHostKind =
   | 'direct'
@@ -127,6 +128,22 @@ export interface ClientDiagnosticsStorage {
   readonly pressureReasonCode?: 'client.blob_cache_over_limit';
 }
 
+/** The latest owned snapshot read of one query id failed (SPEC §7.6). */
+export interface DiagnosticQueryFailure {
+  /** Application-owned stable query id. It must never contain PHI. */
+  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';
+  /** SQLite extended result code, when the driver exposed one. */
+  readonly sqliteCode?: number;
+  /** First failure since this id's last successful read. */
+  readonly atMs: number;
+}
+
 export interface ClientDiagnosticsSnapshot {
   readonly version: typeof CLIENT_DIAGNOSTICS_VERSION;
   readonly capturedAtMs: number;
@@ -154,6 +171,7 @@ export interface ClientDiagnosticsSnapshot {
   readonly lastRound?: DiagnosticLastRound;
   readonly lastChange?: DiagnosticLastChange;
   readonly storage: ClientDiagnosticsStorage;
+  readonly queryFailures: readonly DiagnosticQueryFailure[];
 }
 
 export type ClientDiagnosticsListener = (

package/src/errors.ts

@@ -4,6 +4,12 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
 /** The browser cannot provide the persistent storage APIs Syncular requires. */
 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';
+
+/** A local read hit SQLITE_IOERR (SPEC §7.5). */
+export const STORAGE_IO_CODE = 'client.storage_io';
+
 /**
  * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
  * unchanged. Host/runtime-only conditions may use the separate `client.*`
@@ -20,3 +26,56 @@ export class ClientSyncError extends Error {
     this.retryable = retryable;
   }
 }
+
+/**
+ * SPEC §7.5: classify a local SQLite read failure by the numeric result code
+ * the driver exposes (bun:sqlite `errno`, node:sqlite `errcode`, sqlite-wasm
+ * `resultCode`), never by message text. `error` is what the read throws: a
+ * stable `ClientSyncError` for corruption or I/O failure, otherwise the
+ * original value.
+ */
+export function classifySqliteFailure(error: unknown): {
+  readonly sqliteCode: number | undefined;
+  readonly code:
+    | typeof STORAGE_CORRUPT_CODE
+    | typeof STORAGE_IO_CODE
+    | undefined;
+  readonly error: unknown;
+} {
+  const sqliteCode =
+    error instanceof Error
+      ? error.name === 'SQLiteError' &&
+        'errno' in error &&
+        typeof error.errno === 'number'
+        ? error.errno
+        : 'errcode' in error && typeof error.errcode === 'number'
+          ? error.errcode
+          : error.name === 'SQLite3Error' &&
+              'resultCode' in error &&
+              typeof error.resultCode === 'number'
+            ? error.resultCode
+            : 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 };
+}

package/src/reactive-store.ts

@@ -572,6 +572,12 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
           ...(this.spec.coverage !== undefined
             ? { coverage: this.spec.coverage }
             : {}),
+          owner: {
+            id: this.spec.id,
+            tables: this.spec.dependencies.map(
+              (dependency) => dependency.table,
+            ),
+          },
         });
         if (generation !== this.#generation || this.#listeners.size === 0)
           return;
@@ -621,11 +627,12 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
       } while (this.#requested && this.#listeners.size > 0);
     } catch (error) {
       if (generation !== this.#generation || this.#listeners.size === 0) return;
-      const wrapped = errorOf(error);
+      // SPEC §7.5: a failed latest read is never `ready`; the last
+      // successful rows and revision stay available beside the error.
       this.#publish({
         ...this.#state,
-        phase: this.#state.revision === undefined ? 'error' : this.#state.phase,
-        error: wrapped,
+        phase: 'error',
+        error: errorOf(error),
         isRefreshing: false,
         availability: this.store.availabilitySnapshot(),
       });