@syncular/tauri 0.30.15 → 0.31.0

package/README.md

@@ -154,7 +154,8 @@ available. The native database opens and migrates, but query/snapshot, mutation,
 subscription, sync, realtime, presence, blob, and automatic retry work fails
 with `client.security_preflight_required`. Status, local revision, lifecycle,
 and `purgeLocalData` remain available. A creation-time `defineAuthorityReads`
-policy also enables the read-only `authoritySnapshot()` described below.
+policy on `createTauriAuthoritySyncClient` enables the read-only
+`authoritySnapshot()` described below.
 
 ```ts
 const client = await createTauriSyncClient({
@@ -184,16 +185,17 @@ registration and local progress reads throw that code. `close()` is idempotent.
 ## Authority evidence before activation
 
 Declare authority reads at client creation with `defineAuthorityReads` from
-`@syncular/client`. Each table declares plain columns, including its primary
-key and scope columns, and concrete scope selectors. These selectors remain
+`@syncular/client/authority`. Each table declares plain columns, including
+its primary key and scope columns, and concrete scope selectors. These selectors remain
 fixed for that client. A declaration cannot include encrypted, bytes, blob,
 CRDT or internal columns. Choose only authority fields; clinical fields and
 credentials do not belong in this policy.
 
 ```ts
-import { defineAuthorityReads } from '@syncular/client';
+import { defineAuthorityReads } from '@syncular/client/authority';
+import { createTauriAuthoritySyncClient } from '@syncular/tauri/authority';
 
-const client = await createTauriSyncClient({
+const client = await createTauriAuthoritySyncClient({
   schema,
   securityPreflight: true,
   transportEnabled: false,
@@ -206,6 +208,11 @@ const client = await createTauriSyncClient({
 const evidence = await client.authoritySnapshot();
 ```
 
+Use `createTauriAuthoritySyncClient` for the bridge that exposes
+`authoritySnapshot()`. The ordinary `createTauriSyncClient` class does not
+contain that method or its reply decoder. Upgrade 0.30.15 callers to these
+explicit subpaths; the snapshot and native security checks keep their semantics.
+
 The native application must also set an independent ceiling at plugin creation:
 
 ```rust

package/dist/authority.d.ts

@@ -0,0 +1,10 @@
+import type { AuthorityReadPolicy, AuthoritySnapshot } from '@syncular/client/authority';
+import { TauriSyncClient, type TauriSyncClientConfig } from './index.js';
+/** Explicit native bridge with the zero-argument preflight authority read. */
+export declare class TauriAuthoritySyncClient extends TauriSyncClient {
+    authoritySnapshot(): Promise<AuthoritySnapshot>;
+}
+/** Construct an authority-enabled bridge; Rust still enforces its independent ceiling. */
+export declare function createTauriAuthoritySyncClient(config: TauriSyncClientConfig & {
+    readonly authorityReads: AuthorityReadPolicy;
+}): Promise<TauriAuthoritySyncClient>;

package/dist/authority.js

@@ -0,0 +1,26 @@
+import { createTauriSyncClient, decodeRow, TauriSyncClient, TauriSyncError, } from './index.js';
+/** Explicit native bridge with the zero-argument preflight authority read. */
+export class TauriAuthoritySyncClient extends TauriSyncClient {
+    async authoritySnapshot() {
+        this.requireOpen();
+        if (arguments.length)
+            throw new TauriSyncError('client.authority_read_forbidden', 'authoritySnapshot accepts no arguments');
+        const result = (await this.command('authoritySnapshot', {}));
+        this.requireOpen();
+        return {
+            ...result,
+            revision: BigInt(result.revision),
+            tables: result.tables.map((table) => ({
+                ...table,
+                rows: table.rows.map((row) => ({
+                    ...row,
+                    values: decodeRow(row.values),
+                })),
+            })),
+        };
+    }
+}
+/** Construct an authority-enabled bridge; Rust still enforces its independent ceiling. */
+export function createTauriAuthoritySyncClient(config) {
+    return createTauriSyncClient(config, (...args) => new TauriAuthoritySyncClient(...args));
+}

package/dist/index.d.ts

@@ -28,12 +28,20 @@ import type { ClientSnapshotMethods, PromiseMethods } from '@syncular/client';
  * `invoke`/`listen` either from its ESM entry points, from the ambient
  * `window.__TAURI__`, or via injected doubles (tests).
  */
-import type { AuthorityReadPolicy, AuthoritySnapshot, ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SecurityLifecycle, SqlRow, SqlValue, SyncClientConfig, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { AuthorityReadPolicy, ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SqlRow, SqlValue, SyncClientConfig, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /** One event pushed on `syncular://event` (the derived client-observable set). */
 interface SyncularEvent {
     readonly type: string;
     readonly [key: string]: unknown;
 }
+/** §7.5: one read-only statement in an atomic sidecar snapshot read. */
+export type { SnapshotStatement } from '@syncular/client';
+/** §7.5: the catch-up state of one subscription from the sidecar. */
+export type { SubscriptionCatchup } from '@syncular/client';
+/** §7.5: delivery status for one client commit id. */
+export type { CommitDelivery } from '@syncular/client';
+/** §7.5: one atomic sidecar snapshot read result with decoded rows. */
+export type SnapshotReadResult = SnapshotRead;
 /** The two Tauri primitives the bridge needs — injectable for tests. */
 export interface TauriApi {
     invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T>;
@@ -97,6 +105,8 @@ export interface TauriSyncClientConfig {
 export type BytesEnvelope = {
     readonly $bytes: string;
 };
+/** @internal Shared native row codec. */
+export declare function decodeRow(row: Record<string, unknown>): SqlRow;
 /**
  * The webview-side proxy implementing `SyncClientLike` over the plugin. Every
  * snapshot method returns a promise from an IPC round trip. React hooks accept
@@ -106,6 +116,10 @@ export declare class TauriSyncClient implements PromiseMethods<ClientSnapshotMet
     #private;
     /** @internal — use {@link createTauriSyncClient}. */
     constructor(tauri: TauriApi, unlisten: () => void, securityLifecycle?: SecurityLifecycle);
+    /** @internal Shared command gate for explicit bridge extensions. */
+    protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
+    /** @internal Recheck local close after an extension's asynchronous reply. */
+    protected requireOpen(): void;
     /** @internal — fan an incoming plugin event out to the local listeners. */
     __dispatchEvent(event: SyncularEvent): void;
     securityLifecycle(): Promise<SecurityLifecycle>;
@@ -128,9 +142,14 @@ export declare class TauriSyncClient implements PromiseMethods<ClientSnapshotMet
     onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
-    authoritySnapshot(): Promise<AuthoritySnapshot>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
     localRevision(): Promise<bigint>;
+    /**
+     * §7.5: one atomic read over the file-backed sidecar. Every statement and
+     * every catch-up/delivery read shares one revision (a `bigint`, matching
+     * `querySnapshot`) and one read transaction; every query row is decoded.
+     */
+    snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead>;
     statusSnapshot(): Promise<SyncStatusSnapshot>;
     diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
     mutate(mutations: readonly MutationInput[]): Promise<string>;
@@ -195,7 +214,8 @@ export declare class TauriSyncClient implements PromiseMethods<ClientSnapshotMet
 export declare class TauriSyncError extends Error {
     readonly code: string;
     readonly details: Readonly<Record<string, unknown>> | undefined;
-    constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>);
+    readonly retryable: boolean;
+    constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>, retryable?: boolean);
 }
 /**
  * Construct the bridge and issue the native `create` (opening/attaching the
@@ -204,4 +224,5 @@ export declare class TauriSyncError extends Error {
  * React `<SyncProvider client={…}>`.
  */
 export declare function createTauriSyncClient(config: TauriSyncClientConfig): Promise<TauriSyncClient>;
-export {};
+/** @internal Explicit bridge extension used by the authority entry. */
+export declare function createTauriSyncClient<Client extends TauriSyncClient>(config: TauriSyncClientConfig, createClient: (...args: ConstructorParameters<typeof TauriSyncClient>) => Client): Promise<Client>;

package/dist/index.js

@@ -7,9 +7,23 @@ import { decodeLocalDataRebootstrapResult, decodePreviousVersionAuditResult, dec
 export const SYNCULAR_EVENT = 'syncular://event';
 const PLUGIN = 'plugin:syncular|';
 function isBytesEnvelope(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        typeof value.$bytes === 'string');
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return (Object.keys(record).length === 1 &&
+        typeof record.$bytes === 'string' &&
+        /^(?:[0-9a-fA-F]{2})*$/.test(record.$bytes));
+}
+/**
+ * §7.1: a host reply that carries an envelope-shaped object with a malformed
+ * body is refused, never padded into different bytes. Objects without a
+ * `$bytes` key keep the defensive JSON text round-trip below.
+ */
+function assertBytesEnvelope(value) {
+    if (typeof value !== 'object' || value === null || !('$bytes' in value))
+        return;
+    if (!isBytesEnvelope(value))
+        throw new TauriSyncError('sync.invalid_request', 'a $bytes envelope requires exactly one $bytes key holding an even-length hexadecimal string');
 }
 function isBigIntEnvelope(value) {
     return (typeof value === 'object' &&
@@ -24,10 +38,11 @@ function bytesToHex(bytes) {
     return out;
 }
 function hexToBytes(hex) {
-    const clean = hex.length % 2 === 0 ? hex : `0${hex}`;
-    const out = new Uint8Array(clean.length / 2);
+    if (!/^(?:[0-9a-fA-F]{2})*$/.test(hex))
+        throw new TauriSyncError('sync.invalid_request', 'a $bytes envelope requires an even-length hexadecimal string');
+    const out = new Uint8Array(hex.length / 2);
     for (let i = 0; i < out.length; i++) {
-        out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
     }
     return out;
 }
@@ -68,6 +83,7 @@ function encodeEncryption(config) {
 }
 /** Decode one query-result cell back to an `SqlValue` (`{$bytes}` → bytes). */
 function decodeCell(value) {
+    assertBytesEnvelope(value);
     if (isBytesEnvelope(value))
         return hexToBytes(value.$bytes);
     if (isBigIntEnvelope(value))
@@ -82,7 +98,65 @@ function decodeCell(value) {
     // string (SQLite json columns arrive as text already; this is defensive).
     return JSON.stringify(value);
 }
-function decodeRow(row) {
+/** Decode one native outcome row image. Only the `{$bytes}` envelope is
+ * honored; operation `values` stay `JsonRowValue` and are not passed here. */
+function decodeOutcomeRow(row) {
+    const out = {};
+    for (const [key, value] of Object.entries(row)) {
+        // Reserved `_sync_*` columns stay engine-internal, matching `decodeRow`.
+        if (key.startsWith('_sync_'))
+            continue;
+        assertBytesEnvelope(value);
+        if (value === null ||
+            typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean') {
+            out[key] = value;
+        }
+        else if (isBytesEnvelope(value)) {
+            out[key] = hexToBytes(value.$bytes);
+        }
+        else {
+            out[key] = JSON.stringify(value);
+        }
+    }
+    return out;
+}
+/** Decode the row images a native `CommitOutcome` carries: conflict server
+ * rows and retained-row images. */
+function decodeCommitOutcome(outcome) {
+    return {
+        ...outcome,
+        results: outcome.results.map((result) => result.status === 'conflict'
+            ? {
+                ...result,
+                conflict: {
+                    ...result.conflict,
+                    serverRow: decodeOutcomeRow(result.conflict.serverRow),
+                },
+            }
+            : result),
+        ...(outcome.retainedRows !== undefined
+            ? {
+                retainedRows: outcome.retainedRows.map((row) => ({
+                    ...row,
+                    localRow: row.localRow === null ? null : decodeOutcomeRow(row.localRow),
+                    serverRow: row.serverRow === null ? null : decodeOutcomeRow(row.serverRow),
+                    ...(row.uniqueConflicts !== undefined
+                        ? {
+                            uniqueConflicts: row.uniqueConflicts.map((conflict) => ({
+                                ...conflict,
+                                serverRow: decodeOutcomeRow(conflict.serverRow),
+                            })),
+                        }
+                        : {}),
+                })),
+            }
+            : {}),
+    };
+}
+/** @internal Shared native row codec. */
+export function decodeRow(row) {
     const out = {};
     for (const [key, value] of Object.entries(row)) {
         // Reserved `_sync_*` columns stay engine-internal (parity with the
@@ -178,7 +252,7 @@ export class TauriSyncClient {
         }
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_command`, { command: { method, params } });
         if (reply.error !== undefined) {
-            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined);
+            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined, reply.error.retryable ?? false);
         }
         return reply.result;
     }
@@ -190,6 +264,14 @@ export class TauriSyncClient {
             throw new TauriSyncError('client.closed', 'the Tauri sync client is closed');
         }
     }
+    /** @internal Shared command gate for explicit bridge extensions. */
+    command(method, params) {
+        return this.#command(method, params);
+    }
+    /** @internal Recheck local close after an extension's asynchronous reply. */
+    requireOpen() {
+        this.#requireOpen();
+    }
     #requireActive() {
         this.#requireOpen();
         if (this.#securityLifecycle === 'preflight')
@@ -360,29 +442,11 @@ export class TauriSyncClient {
         this.#requireActive();
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_query`, { sql, params: (params ?? []).map(encodeParam) });
         if (reply.error !== undefined) {
-            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined);
+            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined, reply.error.retryable ?? false);
         }
         const rows = reply.result.rows ?? [];
         return rows.map((r) => decodeRow(r));
     }
-    async authoritySnapshot() {
-        this.#requireOpen();
-        if (arguments.length)
-            throw new TauriSyncError('client.authority_read_forbidden', 'authoritySnapshot accepts no arguments');
-        const result = (await this.#command('authoritySnapshot', {}));
-        this.#requireOpen();
-        return {
-            ...result,
-            revision: BigInt(result.revision),
-            tables: result.tables.map((table) => ({
-                ...table,
-                rows: table.rows.map((row) => ({
-                    ...row,
-                    values: decodeRow(row.values),
-                })),
-            })),
-        };
-    }
     async querySnapshot(spec) {
         this.#requireActive();
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_query_snapshot`, {
@@ -392,7 +456,7 @@ export class TauriSyncClient {
             ...(spec.owner !== undefined ? { owner: spec.owner } : {}),
         });
         if (reply.error !== undefined) {
-            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined);
+            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined, reply.error.retryable ?? false);
         }
         const result = reply.result;
         return {
@@ -405,6 +469,37 @@ export class TauriSyncClient {
         const result = (await this.#command('localRevision', {}));
         return BigInt(result.revision);
     }
+    /**
+     * §7.5: one atomic read over the file-backed sidecar. Every statement and
+     * every catch-up/delivery read shares one revision (a `bigint`, matching
+     * `querySnapshot`) and one read transaction; every query row is decoded.
+     */
+    async snapshotRead(request) {
+        this.#requireActive();
+        const reply = await this.#tauri.invoke(`${PLUGIN}syncular_snapshot_read`, {
+            statements: request.statements.map((statement) => ({
+                sql: statement.sql,
+                params: (statement.params ?? []).map(encodeParam),
+            })),
+            coverage: request.coverage ?? [],
+            subscriptions: request.subscriptions ?? [],
+            commitIds: request.commitIds ?? [],
+            ...(request.owner !== undefined ? { owner: request.owner } : {}),
+        });
+        if (reply.error !== undefined) {
+            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined, reply.error.retryable ?? false);
+        }
+        const result = reply.result;
+        return {
+            revision: BigInt(result.revision),
+            queries: result.queries.map((rows) => rows.map(decodeRow)),
+            coverage: result.coverage,
+            subscriptions: result.subscriptions,
+            deliveries: result.deliveries.map((delivery) => delivery.status === 'known'
+                ? { ...delivery, outcome: decodeCommitOutcome(delivery.outcome) }
+                : delivery),
+        };
+    }
     async statusSnapshot() {
         return (await this.#command('statusSnapshot', {}));
     }
@@ -470,7 +565,7 @@ export class TauriSyncClient {
         this.#requireActive();
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_set_headers`, { headers });
         if (reply.error !== undefined) {
-            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined);
+            throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined, reply.error.retryable ?? false);
         }
     }
     // -- Native CRDT (SPEC.md §5.10.5; needs the plugin `crdt-yjs` feature) ------
@@ -564,17 +659,19 @@ export class TauriSyncClient {
         const result = (await this.#command('commitOutcome', {
             clientCommitId,
         }));
-        return result.outcome;
+        return result.outcome === undefined
+            ? undefined
+            : decodeCommitOutcome(result.outcome);
     }
     async commitOutcomes(query = {}) {
         const result = (await this.#command('commitOutcomes', { query }));
-        return result.outcomes;
+        return result.outcomes.map(decodeCommitOutcome);
     }
     async resolveCommitOutcome(input) {
         const result = (await this.#command('resolveCommitOutcome', {
             input,
         }));
-        return result.outcome;
+        return decodeCommitOutcome(result.outcome);
     }
     async pendingCommits() {
         const result = (await this.#command('pendingCommitIds', {}));
@@ -629,11 +726,13 @@ function decodeDiagnosticsSnapshot(value, kind) {
 export class TauriSyncError extends Error {
     code;
     details;
-    constructor(code, message, details) {
+    retryable;
+    constructor(code, message, details, retryable = false) {
         super(message);
         this.name = 'TauriSyncError';
         this.code = code;
         this.details = details;
+        this.retryable = retryable;
     }
 }
 function toStringSet(value) {
@@ -720,13 +819,7 @@ function encodeMutation(mutation) {
     }
     return { ...mutation, values };
 }
-/**
- * Construct the bridge and issue the native `create` (opening/attaching the
- * file DB on the Rust side per the plugin config). Returns a ready
- * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
- * React `<SyncProvider client={…}>`.
- */
-export async function createTauriSyncClient(config) {
+export async function createTauriSyncClient(config, createClient = (...args) => new TauriSyncClient(...args)) {
     const tauri = await resolveTauri(config.tauri);
     // Wire the event stream BEFORE create, so no early change batch is missed.
     const clientRef = {
@@ -739,7 +832,7 @@ export async function createTauriSyncClient(config) {
         unlisten();
         throw new TauriSyncError('sync.invalid_request', 'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
     }
-    const client = new TauriSyncClient(tauri, unlisten, config.securityPreflight === true ? 'preflight' : 'active');
+    const client = createClient(tauri, unlisten, config.securityPreflight === true ? 'preflight' : 'active');
     clientRef.client = client;
     // The native side owns every path (plugin config); the JS side names a
     // database and supplies the schema, clientId, and limits.
@@ -777,7 +870,7 @@ export async function createTauriSyncClient(config) {
     });
     if (reply.error !== undefined) {
         unlisten();
-        throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined);
+        throw new TauriSyncError(reply.error.code, reply.error.message, reply.error.details ?? undefined, reply.error.retryable ?? false);
     }
     return client;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/tauri",
-  "version": "0.30.15",
+  "version": "0.31.0",
   "description": "Tauri integration for the Syncular client",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -33,6 +33,14 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./authority": {
+      "bun": "./src/authority.ts",
+      "browser": "./dist/authority.js",
+      "import": {
+        "types": "./dist/authority.d.ts",
+        "default": "./dist/authority.js"
+      }
     }
   },
   "files": [
@@ -48,13 +56,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@syncular/client": "0.30.15"
+    "@syncular/client": "0.31.0"
   },
   "peerDependencies": {
     "@tauri-apps/api": ">=2.0.0"
   },
   "devDependencies": {
-    "@syncular/react": "0.30.15",
-    "@syncular/server": "0.30.15"
+    "@syncular/react": "0.31.0",
+    "@syncular/server": "0.31.0"
   }
 }

package/src/authority.ts

@@ -0,0 +1,51 @@
+import type {
+  AuthorityReadPolicy,
+  AuthoritySnapshot,
+} from '@syncular/client/authority';
+import {
+  createTauriSyncClient,
+  decodeRow,
+  TauriSyncClient,
+  TauriSyncError,
+  type TauriSyncClientConfig,
+} from './index';
+
+/** Explicit native bridge with the zero-argument preflight authority read. */
+export class TauriAuthoritySyncClient extends TauriSyncClient {
+  async authoritySnapshot(): Promise<AuthoritySnapshot> {
+    this.requireOpen();
+    if (arguments.length)
+      throw new TauriSyncError(
+        'client.authority_read_forbidden',
+        'authoritySnapshot accepts no arguments',
+      );
+    const result = (await this.command('authoritySnapshot', {})) as Omit<
+      AuthoritySnapshot,
+      'revision'
+    > & { revision: string };
+    this.requireOpen();
+    return {
+      ...result,
+      revision: BigInt(result.revision),
+      tables: result.tables.map((table) => ({
+        ...table,
+        rows: table.rows.map((row) => ({
+          ...row,
+          values: decodeRow(row.values),
+        })),
+      })),
+    };
+  }
+}
+
+/** Construct an authority-enabled bridge; Rust still enforces its independent ceiling. */
+export function createTauriAuthoritySyncClient(
+  config: TauriSyncClientConfig & {
+    readonly authorityReads: AuthorityReadPolicy;
+  },
+): Promise<TauriAuthoritySyncClient> {
+  return createTauriSyncClient(
+    config,
+    (...args) => new TauriAuthoritySyncClient(...args),
+  );
+}

package/src/index.ts

@@ -35,7 +35,6 @@ import type { ClientSnapshotMethods, PromiseMethods } from '@syncular/client';
 
 import type {
   AuthorityReadPolicy,
-  AuthoritySnapshot,
   ClientChangeBatch,
   ClientChangeListener,
   ClientDiagnosticsListener,
@@ -61,6 +60,8 @@ import type {
   RejectionRecord,
   ResolveCommitOutcomeInput,
   SecurityLifecycle,
+  SnapshotRead,
+  SnapshotReadRequest,
   SqlRow,
   SqlValue,
   SyncClientConfig,
@@ -87,6 +88,7 @@ interface CommandReply {
     readonly code: string;
     readonly message: string;
     readonly details?: Readonly<Record<string, unknown>> | null;
+    readonly retryable?: boolean;
   };
 }
 
@@ -96,6 +98,18 @@ interface SyncularEvent {
   readonly [key: string]: unknown;
 }
 
+/** §7.5: one read-only statement in an atomic sidecar snapshot read. */
+export type { SnapshotStatement } from '@syncular/client';
+
+/** §7.5: the catch-up state of one subscription from the sidecar. */
+export type { SubscriptionCatchup } from '@syncular/client';
+
+/** §7.5: delivery status for one client commit id. */
+export type { CommitDelivery } from '@syncular/client';
+
+/** §7.5: one atomic sidecar snapshot read result with decoded rows. */
+export type SnapshotReadResult = SnapshotRead;
+
 /** The two Tauri primitives the bridge needs — injectable for tests. */
 export interface TauriApi {
   invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T>;
@@ -166,13 +180,30 @@ export type BytesEnvelope = { readonly $bytes: string };
 type BigIntEnvelope = { readonly $bigint: string };
 
 function isBytesEnvelope(value: unknown): value is BytesEnvelope {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    typeof (value as { $bytes?: unknown }).$bytes === 'string'
+    Object.keys(record).length === 1 &&
+    typeof record.$bytes === 'string' &&
+    /^(?:[0-9a-fA-F]{2})*$/.test(record.$bytes)
   );
 }
 
+/**
+ * §7.1: a host reply that carries an envelope-shaped object with a malformed
+ * body is refused, never padded into different bytes. Objects without a
+ * `$bytes` key keep the defensive JSON text round-trip below.
+ */
+function assertBytesEnvelope(value: unknown): void {
+  if (typeof value !== 'object' || value === null || !('$bytes' in value))
+    return;
+  if (!isBytesEnvelope(value))
+    throw new TauriSyncError(
+      'sync.invalid_request',
+      'a $bytes envelope requires exactly one $bytes key holding an even-length hexadecimal string',
+    );
+}
+
 function isBigIntEnvelope(value: unknown): value is BigIntEnvelope {
   return (
     typeof value === 'object' &&
@@ -190,10 +221,14 @@ function bytesToHex(bytes: Uint8Array): string {
 }
 
 function hexToBytes(hex: string): Uint8Array {
-  const clean = hex.length % 2 === 0 ? hex : `0${hex}`;
-  const out = new Uint8Array(clean.length / 2);
+  if (!/^(?:[0-9a-fA-F]{2})*$/.test(hex))
+    throw new TauriSyncError(
+      'sync.invalid_request',
+      'a $bytes envelope requires an even-length hexadecimal string',
+    );
+  const out = new Uint8Array(hex.length / 2);
   for (let i = 0; i < out.length; i++) {
-    out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
   }
   return out;
 }
@@ -235,6 +270,7 @@ function encodeEncryption(config: EncryptionKeyringConfig): unknown {
 
 /** Decode one query-result cell back to an `SqlValue` (`{$bytes}` → bytes). */
 function decodeCell(value: unknown): SqlValue {
+  assertBytesEnvelope(value);
   if (isBytesEnvelope(value)) return hexToBytes(value.$bytes);
   if (isBigIntEnvelope(value)) return BigInt(value.$bigint);
   if (
@@ -250,7 +286,76 @@ function decodeCell(value: unknown): SqlValue {
   return JSON.stringify(value);
 }
 
-function decodeRow(row: Record<string, unknown>): SqlRow {
+/** A decoded outcome row cell. Structurally the shared `RowValue` (bytes are
+ * `Uint8Array`); native outcome rows emit plain JSON numbers, never `$bigint`. */
+type OutcomeRowValue = ConflictRecord['serverRow'][string];
+
+/** Decode one native outcome row image. Only the `{$bytes}` envelope is
+ * honored; operation `values` stay `JsonRowValue` and are not passed here. */
+function decodeOutcomeRow(
+  row: Readonly<Record<string, unknown>>,
+): Record<string, OutcomeRowValue> {
+  const out: Record<string, OutcomeRowValue> = {};
+  for (const [key, value] of Object.entries(row)) {
+    // Reserved `_sync_*` columns stay engine-internal, matching `decodeRow`.
+    if (key.startsWith('_sync_')) continue;
+    assertBytesEnvelope(value);
+    if (
+      value === null ||
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean'
+    ) {
+      out[key] = value;
+    } else if (isBytesEnvelope(value)) {
+      out[key] = hexToBytes(value.$bytes);
+    } else {
+      out[key] = JSON.stringify(value);
+    }
+  }
+  return out;
+}
+
+/** Decode the row images a native `CommitOutcome` carries: conflict server
+ * rows and retained-row images. */
+function decodeCommitOutcome(outcome: CommitOutcome): CommitOutcome {
+  return {
+    ...outcome,
+    results: outcome.results.map((result) =>
+      result.status === 'conflict'
+        ? {
+            ...result,
+            conflict: {
+              ...result.conflict,
+              serverRow: decodeOutcomeRow(result.conflict.serverRow),
+            },
+          }
+        : result,
+    ),
+    ...(outcome.retainedRows !== undefined
+      ? {
+          retainedRows: outcome.retainedRows.map((row) => ({
+            ...row,
+            localRow:
+              row.localRow === null ? null : decodeOutcomeRow(row.localRow),
+            serverRow:
+              row.serverRow === null ? null : decodeOutcomeRow(row.serverRow),
+            ...(row.uniqueConflicts !== undefined
+              ? {
+                  uniqueConflicts: row.uniqueConflicts.map((conflict) => ({
+                    ...conflict,
+                    serverRow: decodeOutcomeRow(conflict.serverRow),
+                  })),
+                }
+              : {}),
+          })),
+        }
+      : {}),
+  };
+}
+
+/** @internal Shared native row codec. */
+export function decodeRow(row: Record<string, unknown>): SqlRow {
   const out: SqlRow = {};
   for (const [key, value] of Object.entries(row)) {
     // Reserved `_sync_*` columns stay engine-internal (parity with the
@@ -373,6 +478,7 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
         reply.error.code,
         reply.error.message,
         reply.error.details ?? undefined,
+        reply.error.retryable ?? false,
       );
     }
     return reply.result;
@@ -394,6 +500,19 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     }
   }
 
+  /** @internal Shared command gate for explicit bridge extensions. */
+  protected command(
+    method: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    return this.#command(method, params);
+  }
+
+  /** @internal Recheck local close after an extension's asynchronous reply. */
+  protected requireOpen(): void {
+    this.#requireOpen();
+  }
+
   #requireActive(): void {
     this.#requireOpen();
     if (this.#securityLifecycle === 'preflight') this.#throwSecurityPreflight();
@@ -587,37 +706,13 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
         reply.error.code,
         reply.error.message,
         reply.error.details ?? undefined,
+        reply.error.retryable ?? false,
       );
     }
     const rows = (reply.result as { rows?: unknown[] }).rows ?? [];
     return rows.map((r) => decodeRow(r as Record<string, unknown>));
   }
 
-  async authoritySnapshot(): Promise<AuthoritySnapshot> {
-    this.#requireOpen();
-    if (arguments.length)
-      throw new TauriSyncError(
-        'client.authority_read_forbidden',
-        'authoritySnapshot accepts no arguments',
-      );
-    const result = (await this.#command('authoritySnapshot', {})) as Omit<
-      AuthoritySnapshot,
-      'revision'
-    > & { revision: string };
-    this.#requireOpen();
-    return {
-      ...result,
-      revision: BigInt(result.revision),
-      tables: result.tables.map((table) => ({
-        ...table,
-        rows: table.rows.map((row) => ({
-          ...row,
-          values: decodeRow(row.values),
-        })),
-      })),
-    };
-  }
-
   async querySnapshot<Row = SqlRow>(
     spec: QueryReadSpec,
   ): Promise<QuerySnapshot<Row>> {
@@ -636,6 +731,7 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
         reply.error.code,
         reply.error.message,
         reply.error.details ?? undefined,
+        reply.error.retryable ?? false,
       );
     }
     const result = reply.result as {
@@ -657,6 +753,54 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     return BigInt(result.revision);
   }
 
+  /**
+   * §7.5: one atomic read over the file-backed sidecar. Every statement and
+   * every catch-up/delivery read shares one revision (a `bigint`, matching
+   * `querySnapshot`) and one read transaction; every query row is decoded.
+   */
+  async snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead> {
+    this.#requireActive();
+    const reply = await this.#tauri.invoke<CommandReply>(
+      `${PLUGIN}syncular_snapshot_read`,
+      {
+        statements: request.statements.map((statement) => ({
+          sql: statement.sql,
+          params: (statement.params ?? []).map(encodeParam),
+        })),
+        coverage: request.coverage ?? [],
+        subscriptions: request.subscriptions ?? [],
+        commitIds: request.commitIds ?? [],
+        ...(request.owner !== undefined ? { owner: request.owner } : {}),
+      },
+    );
+    if (reply.error !== undefined) {
+      throw new TauriSyncError(
+        reply.error.code,
+        reply.error.message,
+        reply.error.details ?? undefined,
+        reply.error.retryable ?? false,
+      );
+    }
+    const result = reply.result as {
+      revision: string;
+      queries: readonly (readonly Record<string, unknown>[])[];
+      coverage: SnapshotRead['coverage'];
+      subscriptions: SnapshotRead['subscriptions'];
+      deliveries: SnapshotRead['deliveries'];
+    };
+    return {
+      revision: BigInt(result.revision),
+      queries: result.queries.map((rows) => rows.map(decodeRow)),
+      coverage: result.coverage,
+      subscriptions: result.subscriptions,
+      deliveries: result.deliveries.map((delivery) =>
+        delivery.status === 'known'
+          ? { ...delivery, outcome: decodeCommitOutcome(delivery.outcome) }
+          : delivery,
+      ),
+    };
+  }
+
   async statusSnapshot(): Promise<SyncStatusSnapshot> {
     return (await this.#command('statusSnapshot', {})) as SyncStatusSnapshot;
   }
@@ -766,6 +910,7 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
         reply.error.code,
         reply.error.message,
         reply.error.details ?? undefined,
+        reply.error.retryable ?? false,
       );
     }
   }
@@ -909,7 +1054,9 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     const result = (await this.#command('commitOutcome', {
       clientCommitId,
     })) as { outcome?: CommitOutcome };
-    return result.outcome;
+    return result.outcome === undefined
+      ? undefined
+      : decodeCommitOutcome(result.outcome);
   }
 
   async commitOutcomes(
@@ -918,7 +1065,7 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     const result = (await this.#command('commitOutcomes', { query })) as {
       outcomes: CommitOutcome[];
     };
-    return result.outcomes;
+    return result.outcomes.map(decodeCommitOutcome);
   }
 
   async resolveCommitOutcome(
@@ -927,7 +1074,7 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     const result = (await this.#command('resolveCommitOutcome', {
       input,
     })) as { outcome: CommitOutcome };
-    return result.outcome;
+    return decodeCommitOutcome(result.outcome);
   }
 
   async pendingCommits(): Promise<unknown[]> {
@@ -996,15 +1143,18 @@ function decodeDiagnosticsSnapshot(
 export class TauriSyncError extends Error {
   readonly code: string;
   readonly details: Readonly<Record<string, unknown>> | undefined;
+  readonly retryable: boolean;
   constructor(
     code: string,
     message: string,
     details?: Readonly<Record<string, unknown>>,
+    retryable = false,
   ) {
     super(message);
     this.name = 'TauriSyncError';
     this.code = code;
     this.details = details;
+    this.retryable = retryable;
   }
 }
 
@@ -1097,8 +1247,20 @@ function encodeMutation(mutation: MutationInput): unknown {
  * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
  * React `<SyncProvider client={…}>`.
  */
+export function createTauriSyncClient(
+  config: TauriSyncClientConfig,
+): Promise<TauriSyncClient>;
+/** @internal Explicit bridge extension used by the authority entry. */
+export function createTauriSyncClient<Client extends TauriSyncClient>(
+  config: TauriSyncClientConfig,
+  createClient: (
+    ...args: ConstructorParameters<typeof TauriSyncClient>
+  ) => Client,
+): Promise<Client>;
 export async function createTauriSyncClient(
   config: TauriSyncClientConfig,
+  createClient = (...args: ConstructorParameters<typeof TauriSyncClient>) =>
+    new TauriSyncClient(...args),
 ): Promise<TauriSyncClient> {
   const tauri = await resolveTauri(config.tauri);
 
@@ -1121,7 +1283,7 @@ export async function createTauriSyncClient(
     );
   }
 
-  const client = new TauriSyncClient(
+  const client = createClient(
     tauri,
     unlisten,
     config.securityPreflight === true ? 'preflight' : 'active',
@@ -1168,6 +1330,7 @@ export async function createTauriSyncClient(
       reply.error.code,
       reply.error.message,
       reply.error.details ?? undefined,
+      reply.error.retryable ?? false,
     );
   }