@syncular/client 0.41.2 → 0.42.0

package/dist/client.d.ts

@@ -402,6 +402,14 @@ export declare class SyncClient {
      */
     activateSecurity(options?: SecurityActivation): Promise<void>;
     get clientId(): string;
+    /**
+     * Rotate the caller's client id (§1.5). Use it after a
+     * `sync.invalid_client_id` refusal (`recommendedAction: resetClientId`):
+     * the next round carries the new id. The local replica and its outbox stay
+     * in place; wipe them yourself when the stored data belongs to the account
+     * that signed out.
+     */
+    resetClientId(): string;
     /** The underlying database: raw SQL is the local query API. */
     get database(): ClientDatabase;
     /**

package/dist/client.js

@@ -784,6 +784,21 @@ export class SyncClient {
     get clientId() {
         return this.#clientId;
     }
+    /**
+     * Rotate the caller's client id (§1.5). Use it after a
+     * `sync.invalid_client_id` refusal (`recommendedAction: resetClientId`):
+     * the next round carries the new id. The local replica and its outbox stay
+     * in place; wipe them yourself when the stored data belongs to the account
+     * that signed out.
+     */
+    resetClientId() {
+        this.#requireStarted();
+        this.disconnectRealtime();
+        const clientId = crypto.randomUUID();
+        setMeta(this.#db, 'clientId', clientId);
+        this.#clientId = clientId;
+        return clientId;
+    }
     /** The underlying database: raw SQL is the local query API. */
     get database() {
         this.#requireActive();
@@ -3510,6 +3525,7 @@ export class SyncClient {
         // at creation, never unhandled.
         const prefetched = new Map();
         let reporting;
+        const deleteKey = (commitSeq, table, rowId) => `${commitSeq}\u0000${table}\u0000${rowId}`;
         {
             let openSub;
             for (const frame of message.frames) {
@@ -3544,6 +3560,68 @@ export class SyncClient {
                 }
             }
         }
+        // §2.2 scope migration: the server emits the delete tagged with the old
+        // scope and the upsert tagged with the new one in one commit. A reader
+        // that holds both scopes receives them in two subscription sections, so
+        // the section order would otherwise decide whether the row survives. One
+        // commit's delete and upsert of the same row are one change, and the
+        // upsert wins. A frame that carries both itself keeps its own operation
+        // order; only a pair split across sections is coalesced.
+        const coalescedDeletes = new Set();
+        {
+            const ops = new Map();
+            const bothInFrame = new Set();
+            let openSub;
+            let frameIndex = -1;
+            for (const frame of message.frames) {
+                if (frame.type === 'SUB_START') {
+                    const sub = subsById.get(frame.id);
+                    openSub =
+                        sub === undefined ||
+                            (mode === 'delta' &&
+                                (sub.status !== 'active' || sub.bootstrapState !== undefined))
+                            ? undefined
+                            : sub;
+                }
+                else if (frame.type === 'SUB_END') {
+                    openSub = undefined;
+                }
+                else if (frame.type === 'ERROR') {
+                    break;
+                }
+                else if (frame.type === 'COMMIT' && openSub !== undefined) {
+                    frameIndex += 1;
+                    const local = new Map();
+                    for (const change of frame.changes) {
+                        const table = frame.tables[change.tableIndex];
+                        if (table === undefined)
+                            continue;
+                        const key = deleteKey(frame.commitSeq, table, change.rowId);
+                        const entry = ops.get(key) ?? {
+                            upserts: new Set(),
+                            deletes: new Set(),
+                        };
+                        if (change.op === 'upsert')
+                            entry.upserts.add(frameIndex);
+                        else
+                            entry.deletes.add(frameIndex);
+                        ops.set(key, entry);
+                        local.set(key, (local.get(key) ?? 0) | (change.op === 'upsert' ? 1 : 2));
+                    }
+                    for (const [key, seen] of local) {
+                        if (seen === 3)
+                            bothInFrame.add(key);
+                    }
+                }
+            }
+            for (const [key, entry] of ops) {
+                if (!bothInFrame.has(key) &&
+                    entry.upserts.size > 0 &&
+                    entry.deletes.size > 0) {
+                    coalescedDeletes.add(key);
+                }
+            }
+        }
         // Each durable observer transaction emits its own revisioned batch.
         // Async decrypt/download work happens outside SQLite transactions.
         this.#beginDiagnosticsDeferral();
@@ -3620,7 +3698,16 @@ export class SyncClient {
                     }
                     case 'COMMIT':
                         if (section !== undefined && !section.skip) {
-                            await this.#applyCommit(frame, summary);
+                            const changes = frame.changes.filter((change) => {
+                                if (change.op !== 'delete')
+                                    return true;
+                                const table = frame.tables[change.tableIndex];
+                                return (table === undefined ||
+                                    !coalescedDeletes.has(deleteKey(frame.commitSeq, table, change.rowId)));
+                            });
+                            if (changes.length > 0) {
+                                await this.#applyCommit({ ...frame, changes }, summary);
+                            }
                         }
                         break;
                     case 'SEGMENT_INLINE':
@@ -3708,12 +3795,27 @@ export class SyncClient {
                         section = undefined;
                         break;
                     }
-                    case 'ERROR':
+                    case 'ERROR': {
                         // §1.4 rule 5 / §1.6: the request failed; the open
                         // subscription's SUB_END values are never persisted.
-                        errorFrame = new ClientSyncError(frame.code, frame.message, frame.retryable);
+                        let details;
+                        if (frame.details !== undefined) {
+                            try {
+                                const parsed = JSON.parse(frame.details);
+                                if (typeof parsed === 'object' &&
+                                    parsed !== null &&
+                                    !Array.isArray(parsed)) {
+                                    details = parsed;
+                                }
+                            }
+                            catch {
+                                // A malformed details member adds no evidence.
+                            }
+                        }
+                        errorFrame = new ClientSyncError(frame.code, frame.message, frame.retryable, details, frame.recommendedAction);
                         section = undefined;
                         break;
+                    }
                     case 'UNKNOWN':
                         break; // §1.2 rule 2: skipped, never interpreted
                 }

package/dist/errors.d.ts

@@ -23,7 +23,9 @@ export declare class ClientSyncError extends Error {
     readonly code: string;
     readonly retryable: boolean;
     readonly details: Readonly<Record<string, unknown>> | undefined;
-    constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>);
+    /** §10.1 `recommendedAction` from an authenticated HTTP error body. */
+    readonly recommendedAction: string | undefined;
+    constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>, recommendedAction?: string);
 }
 /** Shared invalid-request construction for client validators and transport guards. */
 export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;

package/dist/errors.js

@@ -22,11 +22,14 @@ export class ClientSyncError extends Error {
     code;
     retryable;
     details;
-    constructor(code, message, retryable = false, details) {
+    /** §10.1 `recommendedAction` from an authenticated HTTP error body. */
+    recommendedAction;
+    constructor(code, message, retryable = false, details, recommendedAction) {
         super(message);
         this.code = code;
         this.retryable = retryable;
         this.details = details;
+        this.recommendedAction = recommendedAction;
     }
 }
 /** Shared invalid-request construction for client validators and transport guards. */
@@ -91,7 +94,7 @@ export function classifySqliteFailure(error) {
                     message: rollback instanceof Error ? rollback.message : String(rollback),
                     sqliteCode: classifySqliteFailure(rollback).sqliteCode,
                 },
-            });
+            }, error.recommendedAction);
             Object.defineProperty(retained, 'cause', { value: error });
         }
         return {

package/dist/http.js

@@ -28,6 +28,8 @@ async function throwHttpError(response, defaultCode = 'sync.transport_failed') {
     let retryable = response.status >= 500 ||
         response.status === 429 ||
         defaultCode === 'sync.auth_required';
+    let recommendedAction;
+    let serverDetails;
     try {
         const body = (await response.json());
         // Only the blob download endpoint can establish absence.
@@ -38,15 +40,22 @@ async function throwHttpError(response, defaultCode = 'sync.transport_failed') {
                 message = body.message;
             if (typeof body.retryable === 'boolean')
                 retryable = body.retryable;
+            if (typeof body.recommendedAction === 'string')
+                recommendedAction = body.recommendedAction;
+            if (typeof body.details === 'object' &&
+                body.details !== null &&
+                !Array.isArray(body.details))
+                serverDetails = body.details;
         }
     }
     catch {
         // non-JSON error body — keep the HTTP-status defaults
     }
     throw new ClientSyncError(code, message, retryable, {
+        ...serverDetails,
         causeKind: 'status',
         httpStatus: response.status,
-    });
+    }, recommendedAction);
 }
 function hostHeaders(options) {
     const headers = options?.headers;

package/dist/worker-entry.js

@@ -371,6 +371,7 @@ export function startSyncWorker(overrides = {}) {
             const running = requireClient();
             return serializedSync(() => running.syncUntilIdle(maxRounds));
         },
+        resetClientId: () => requireClient().resetClientId(),
         localRevision: () => requireClient().localRevision,
         diagnosticsSnapshot: (request) => {
             const snapshot = requireClient().diagnosticsSnapshot(request);

package/dist/worker-host.d.ts

@@ -246,6 +246,12 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
     }>;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+    /**
+     * Rotate the client id (§1.5) after a `sync.invalid_client_id` refusal.
+     * The worker's next round carries the new id; the replica and outbox stay
+     * in place.
+     */
+    resetClientId(): Promise<string>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
     authoritySnapshot(): Promise<import('./authority.js').AuthoritySnapshot>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;

package/dist/worker-host.js

@@ -332,6 +332,16 @@ export class SyncClientHandle {
     syncUntilIdle(maxRounds) {
         return this.#call('syncUntilIdle', [maxRounds]);
     }
+    /**
+     * Rotate the client id (§1.5) after a `sync.invalid_client_id` refusal.
+     * The worker's next round carries the new id; the replica and outbox stay
+     * in place.
+     */
+    async resetClientId() {
+        const clientId = await this.#call('resetClientId', []);
+        this.#clientId = clientId;
+        return clientId;
+    }
     query(sql, params) {
         return this.#call('query', [sql, params]);
     }

package/dist/worker-protocol.d.ts

@@ -139,6 +139,7 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
     };
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+    resetClientId(): string;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     authoritySnapshot(): import('./authority.js').AuthoritySnapshot;
     querySnapshot(spec: QueryReadSpec): QuerySnapshot;

package/package.json

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

package/src/client.ts

@@ -1617,6 +1617,22 @@ export class SyncClient {
     return this.#clientId;
   }
 
+  /**
+   * Rotate the caller's client id (§1.5). Use it after a
+   * `sync.invalid_client_id` refusal (`recommendedAction: resetClientId`):
+   * the next round carries the new id. The local replica and its outbox stay
+   * in place; wipe them yourself when the stored data belongs to the account
+   * that signed out.
+   */
+  resetClientId(): string {
+    this.#requireStarted();
+    this.disconnectRealtime();
+    const clientId = crypto.randomUUID();
+    setMeta(this.#db, 'clientId', clientId);
+    this.#clientId = clientId;
+    return clientId;
+  }
+
   /** The underlying database: raw SQL is the local query API. */
   get database(): ClientDatabase {
     this.#requireActive();
@@ -4903,6 +4919,8 @@ export class SyncClient {
     // at creation, never unhandled.
     const prefetched = new Map<SegmentRefFrame, Promise<Uint8Array>>();
     let reporting: SegmentRefFrame | undefined;
+    const deleteKey = (commitSeq: number, table: string, rowId: string) =>
+      `${commitSeq}\u0000${table}\u0000${rowId}`;
     {
       let openSub: SubscriptionRecord | undefined;
       for (const frame of message.frames) {
@@ -4939,6 +4957,70 @@ export class SyncClient {
       }
     }
 
+    // §2.2 scope migration: the server emits the delete tagged with the old
+    // scope and the upsert tagged with the new one in one commit. A reader
+    // that holds both scopes receives them in two subscription sections, so
+    // the section order would otherwise decide whether the row survives. One
+    // commit's delete and upsert of the same row are one change, and the
+    // upsert wins. A frame that carries both itself keeps its own operation
+    // order; only a pair split across sections is coalesced.
+    const coalescedDeletes = new Set<string>();
+    {
+      const ops = new Map<
+        string,
+        { readonly upserts: Set<number>; readonly deletes: Set<number> }
+      >();
+      const bothInFrame = new Set<string>();
+      let openSub: SubscriptionRecord | undefined;
+      let frameIndex = -1;
+      for (const frame of message.frames) {
+        if (frame.type === 'SUB_START') {
+          const sub = subsById.get(frame.id);
+          openSub =
+            sub === undefined ||
+            (mode === 'delta' &&
+              (sub.status !== 'active' || sub.bootstrapState !== undefined))
+              ? undefined
+              : sub;
+        } else if (frame.type === 'SUB_END') {
+          openSub = undefined;
+        } else if (frame.type === 'ERROR') {
+          break;
+        } else if (frame.type === 'COMMIT' && openSub !== undefined) {
+          frameIndex += 1;
+          const local = new Map<string, number>();
+          for (const change of frame.changes) {
+            const table = frame.tables[change.tableIndex];
+            if (table === undefined) continue;
+            const key = deleteKey(frame.commitSeq, table, change.rowId);
+            const entry = ops.get(key) ?? {
+              upserts: new Set<number>(),
+              deletes: new Set<number>(),
+            };
+            if (change.op === 'upsert') entry.upserts.add(frameIndex);
+            else entry.deletes.add(frameIndex);
+            ops.set(key, entry);
+            local.set(
+              key,
+              (local.get(key) ?? 0) | (change.op === 'upsert' ? 1 : 2),
+            );
+          }
+          for (const [key, seen] of local) {
+            if (seen === 3) bothInFrame.add(key);
+          }
+        }
+      }
+      for (const [key, entry] of ops) {
+        if (
+          !bothInFrame.has(key) &&
+          entry.upserts.size > 0 &&
+          entry.deletes.size > 0
+        ) {
+          coalescedDeletes.add(key);
+        }
+      }
+    }
+
     // Each durable observer transaction emits its own revisioned batch.
     // Async decrypt/download work happens outside SQLite transactions.
     this.#beginDiagnosticsDeferral();
@@ -5036,7 +5118,19 @@ export class SyncClient {
           }
           case 'COMMIT':
             if (section !== undefined && !section.skip) {
-              await this.#applyCommit(frame, summary);
+              const changes = frame.changes.filter((change) => {
+                if (change.op !== 'delete') return true;
+                const table = frame.tables[change.tableIndex];
+                return (
+                  table === undefined ||
+                  !coalescedDeletes.has(
+                    deleteKey(frame.commitSeq, table, change.rowId),
+                  )
+                );
+              });
+              if (changes.length > 0) {
+                await this.#applyCommit({ ...frame, changes }, summary);
+              }
             }
             break;
           case 'SEGMENT_INLINE':
@@ -5182,16 +5276,34 @@ export class SyncClient {
             section = undefined;
             break;
           }
-          case 'ERROR':
+          case 'ERROR': {
             // §1.4 rule 5 / §1.6: the request failed; the open
             // subscription's SUB_END values are never persisted.
+            let details: Readonly<Record<string, unknown>> | undefined;
+            if (frame.details !== undefined) {
+              try {
+                const parsed: unknown = JSON.parse(frame.details);
+                if (
+                  typeof parsed === 'object' &&
+                  parsed !== null &&
+                  !Array.isArray(parsed)
+                ) {
+                  details = parsed as Readonly<Record<string, unknown>>;
+                }
+              } catch {
+                // A malformed details member adds no evidence.
+              }
+            }
             errorFrame = new ClientSyncError(
               frame.code,
               frame.message,
               frame.retryable,
+              details,
+              frame.recommendedAction,
             );
             section = undefined;
             break;
+          }
           case 'UNKNOWN':
             break; // §1.2 rule 2: skipped, never interpreted
         }

package/src/errors.ts

@@ -31,17 +31,21 @@ export class ClientSyncError extends Error {
   readonly code: string;
   readonly retryable: boolean;
   readonly details: Readonly<Record<string, unknown>> | undefined;
+  /** §10.1 `recommendedAction` from an authenticated HTTP error body. */
+  readonly recommendedAction: string | undefined;
 
   constructor(
     code: string,
     message: string,
     retryable = false,
     details?: Readonly<Record<string, unknown>>,
+    recommendedAction?: string,
   ) {
     super(message);
     this.code = code;
     this.retryable = retryable;
     this.details = details;
+    this.recommendedAction = recommendedAction;
   }
 }
 
@@ -144,6 +148,7 @@ export function classifySqliteFailure(error: unknown): {
             sqliteCode: classifySqliteFailure(rollback).sqliteCode,
           },
         },
+        error.recommendedAction,
       );
       Object.defineProperty(retained, 'cause', { value: error });
     }

package/src/http.ts

@@ -52,25 +52,44 @@ async function throwHttpError(
     response.status >= 500 ||
     response.status === 429 ||
     defaultCode === 'sync.auth_required';
+  let recommendedAction: string | undefined;
+  let serverDetails: Readonly<Record<string, unknown>> | undefined;
   try {
     const body = (await response.json()) as {
       code?: string;
       message?: string;
       retryable?: boolean;
+      recommendedAction?: string;
+      details?: unknown;
     };
     // Only the blob download endpoint can establish absence.
     if (body.code !== 'blob.not_found' || defaultCode === 'blob.not_found') {
       if (typeof body.code === 'string') code = body.code;
       if (typeof body.message === 'string') message = body.message;
       if (typeof body.retryable === 'boolean') retryable = body.retryable;
+      if (typeof body.recommendedAction === 'string')
+        recommendedAction = body.recommendedAction;
+      if (
+        typeof body.details === 'object' &&
+        body.details !== null &&
+        !Array.isArray(body.details)
+      )
+        serverDetails = body.details as Readonly<Record<string, unknown>>;
     }
   } catch {
     // non-JSON error body — keep the HTTP-status defaults
   }
-  throw new ClientSyncError(code, message, retryable, {
-    causeKind: 'status',
-    httpStatus: response.status,
-  });
+  throw new ClientSyncError(
+    code,
+    message,
+    retryable,
+    {
+      ...serverDetails,
+      causeKind: 'status',
+      httpStatus: response.status,
+    },
+    recommendedAction,
+  );
 }
 
 export interface HttpTransportOptions {

package/src/worker-entry.ts

@@ -492,6 +492,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       const running = requireClient();
       return serializedSync(() => running.syncUntilIdle(maxRounds));
     },
+    resetClientId: () => requireClient().resetClientId(),
     localRevision: () => requireClient().localRevision,
     diagnosticsSnapshot: (request) => {
       const snapshot = requireClient().diagnosticsSnapshot(request);

package/src/worker-host.ts

@@ -661,6 +661,17 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('syncUntilIdle', [maxRounds]);
   }
 
+  /**
+   * Rotate the client id (§1.5) after a `sync.invalid_client_id` refusal.
+   * The worker's next round carries the new id; the replica and outbox stay
+   * in place.
+   */
+  async resetClientId(): Promise<string> {
+    const clientId = await this.#call('resetClientId', []);
+    this.#clientId = clientId;
+    return clientId;
+  }
+
   query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]> {
     return this.#call('query', [sql, params]);
   }

package/src/worker-protocol.ts

@@ -188,6 +188,7 @@ export interface WorkerApi extends Omit<
   previousVersionDiscard(): { present: boolean; discarded: boolean };
   sync(): Promise<SyncSummary>;
   syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
+  resetClientId(): string;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];
   authoritySnapshot(): import('./authority').AuthoritySnapshot;
   querySnapshot(spec: QueryReadSpec): QuerySnapshot;