@syncular/client 0.15.35 → 0.15.36

package/README.md

@@ -312,9 +312,15 @@ const result = await client.rebootstrapLocalData({
 The reset, durable idempotency marker, and optimistic outbox replay are one
 SQLite transaction. An interruption therefore leaves either the old
 projection or the fully reset projection with pending offline work still
-visible. Reusing the same id returns `alreadyApplied: true`. The counts-only
-result reports retained commits and reset subscriptions without exposing ids,
-rows, scopes, or clinical values.
+visible. Reusing the same id returns `alreadyApplied: true` together with the
+original `retainedCommits` and `resetSubscriptions` counts. The core stores
+that counts-only receipt atomically with the reset, so an application crash
+after the SQLite commit but before its own acknowledgement does not turn the
+retry into a misleading zero-impact result. Markers written before Syncular
+0.15.36 cannot reconstruct their historical counts and preserve the former
+zero-count replay behavior. A malformed or unreadable persisted receipt fails
+closed with the sanitized `sync.local_corrupt` client-local code and performs
+no reset. No receipt exposes ids, rows, scopes, or clinical values.
 
 Worker, Tauri, and React Native adapters strictly decode the exact result
 shape before returning it. Missing or additional fields, a non-boolean

package/dist/client.js

@@ -17,6 +17,7 @@ import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFrom
 import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
 import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
+import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
@@ -1509,11 +1510,13 @@ export class SyncClient {
         this.#requireActive();
         const rebootstrapId = compileLocalDataRebootstrap(input);
         const metaKey = localDataRebootstrapMetaKey(rebootstrapId);
-        if (getMeta(this.#db, metaKey) !== undefined) {
+        const persistedReceipt = getMeta(this.#db, metaKey);
+        if (persistedReceipt !== undefined) {
+            const receipt = decodeLocalDataRebootstrapReceipt(persistedReceipt);
             return {
                 alreadyApplied: true,
-                retainedCommits: 0,
-                resetSubscriptions: 0,
+                retainedCommits: receipt.retainedCommits,
+                resetSubscriptions: receipt.resetSubscriptions,
             };
         }
         if (this.#schemaFloor !== undefined) {
@@ -1536,7 +1539,10 @@ export class SyncClient {
                 for (const commit of pending) {
                     this.#applyOperationsLocally(commit.operations, batch);
                 }
-                setMeta(this.#db, metaKey, 'v1');
+                setMeta(this.#db, metaKey, encodeLocalDataRebootstrapReceipt({
+                    retainedCommits: pending.length,
+                    resetSubscriptions,
+                }));
             });
         }
         catch (error) {

package/dist/local-rebootstrap-receipt.d.ts

@@ -0,0 +1,12 @@
+export interface LocalDataRebootstrapReceipt {
+    readonly retainedCommits: number;
+    readonly resetSubscriptions: number;
+}
+/** Encode only the bounded counts that are safe to replay outside the core. */
+export declare function encodeLocalDataRebootstrapReceipt(receipt: LocalDataRebootstrapReceipt): string;
+/**
+ * Decode a committed receipt without leaking its application-owned key. The
+ * original counts were not retained by pre-0.15.36 `v1` markers, so those
+ * historical repairs keep their former zero-count replay behavior.
+ */
+export declare function decodeLocalDataRebootstrapReceipt(value: string): LocalDataRebootstrapReceipt;

package/dist/local-rebootstrap-receipt.js

@@ -0,0 +1,59 @@
+import { ClientSyncError } from './errors.js';
+const LEGACY_MARKER = 'v1';
+const RECEIPT_VERSION = 2;
+const RECEIPT_KEYS = [
+    'resetSubscriptions',
+    'retainedCommits',
+    'version',
+];
+function invalidReceipt() {
+    throw new ClientSyncError('sync.local_corrupt', 'persisted local rebootstrap receipt is invalid');
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+/** Encode only the bounded counts that are safe to replay outside the core. */
+export function encodeLocalDataRebootstrapReceipt(receipt) {
+    if (!isCount(receipt.retainedCommits) ||
+        !isCount(receipt.resetSubscriptions)) {
+        return invalidReceipt();
+    }
+    return JSON.stringify({
+        version: RECEIPT_VERSION,
+        retainedCommits: receipt.retainedCommits,
+        resetSubscriptions: receipt.resetSubscriptions,
+    });
+}
+/**
+ * Decode a committed receipt without leaking its application-owned key. The
+ * original counts were not retained by pre-0.15.36 `v1` markers, so those
+ * historical repairs keep their former zero-count replay behavior.
+ */
+export function decodeLocalDataRebootstrapReceipt(value) {
+    if (value === LEGACY_MARKER) {
+        return { retainedCommits: 0, resetSubscriptions: 0 };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return invalidReceipt();
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return invalidReceipt();
+    }
+    const source = parsed;
+    const keys = Object.keys(source).sort();
+    if (keys.length !== RECEIPT_KEYS.length ||
+        keys.some((key, index) => key !== RECEIPT_KEYS[index]) ||
+        source.version !== RECEIPT_VERSION ||
+        !isCount(source.retainedCommits) ||
+        !isCount(source.resetSubscriptions)) {
+        return invalidReceipt();
+    }
+    return {
+        retainedCommits: source.retainedCommits,
+        resetSubscriptions: source.resetSubscriptions,
+    };
+}

package/dist/local-rebootstrap.d.ts

@@ -12,7 +12,11 @@ export declare const INVALID_HOST_RESPONSE_CODE = "client.invalid_host_response"
 export interface LocalDataRebootstrapInput {
     readonly rebootstrapId: string;
 }
-/** Privacy-safe acknowledgement; no row or subscription identifiers escape. */
+/**
+ * Privacy-safe acknowledgement; no row or subscription identifiers escape.
+ * An idempotent replay sets `alreadyApplied` while retaining the first call's
+ * exact counts when that repair was first applied by Syncular 0.15.36 or later.
+ */
 export interface LocalDataRebootstrapResult {
     readonly alreadyApplied: boolean;
     readonly retainedCommits: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.35",
+  "version": "0.15.36",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.35"
+    "@syncular/core": "0.15.36"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.35",
+    "@syncular/server": "0.15.36",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -109,6 +109,10 @@ import {
   type LocalDataRebootstrapResult,
   localDataRebootstrapMetaKey,
 } from './local-rebootstrap';
+import {
+  decodeLocalDataRebootstrapReceipt,
+  encodeLocalDataRebootstrapReceipt,
+} from './local-rebootstrap-receipt';
 import {
   appendOutboxCommit,
   deleteOutboxCommit,
@@ -2244,11 +2248,13 @@ export class SyncClient {
     this.#requireActive();
     const rebootstrapId = compileLocalDataRebootstrap(input);
     const metaKey = localDataRebootstrapMetaKey(rebootstrapId);
-    if (getMeta(this.#db, metaKey) !== undefined) {
+    const persistedReceipt = getMeta(this.#db, metaKey);
+    if (persistedReceipt !== undefined) {
+      const receipt = decodeLocalDataRebootstrapReceipt(persistedReceipt);
       return {
         alreadyApplied: true,
-        retainedCommits: 0,
-        resetSubscriptions: 0,
+        retainedCommits: receipt.retainedCommits,
+        resetSubscriptions: receipt.resetSubscriptions,
       };
     }
     if (this.#schemaFloor !== undefined) {
@@ -2275,7 +2281,14 @@ export class SyncClient {
         for (const commit of pending) {
           this.#applyOperationsLocally(commit.operations, batch);
         }
-        setMeta(this.#db, metaKey, 'v1');
+        setMeta(
+          this.#db,
+          metaKey,
+          encodeLocalDataRebootstrapReceipt({
+            retainedCommits: pending.length,
+            resetSubscriptions,
+          }),
+        );
       });
     } catch (error) {
       this.#upgrading = priorUpgrading;

package/src/local-rebootstrap-receipt.ts

@@ -0,0 +1,79 @@
+import { ClientSyncError } from './errors';
+
+const LEGACY_MARKER = 'v1';
+const RECEIPT_VERSION = 2;
+const RECEIPT_KEYS = [
+  'resetSubscriptions',
+  'retainedCommits',
+  'version',
+] as const;
+
+export interface LocalDataRebootstrapReceipt {
+  readonly retainedCommits: number;
+  readonly resetSubscriptions: number;
+}
+
+function invalidReceipt(): never {
+  throw new ClientSyncError(
+    'sync.local_corrupt',
+    'persisted local rebootstrap receipt is invalid',
+  );
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** Encode only the bounded counts that are safe to replay outside the core. */
+export function encodeLocalDataRebootstrapReceipt(
+  receipt: LocalDataRebootstrapReceipt,
+): string {
+  if (
+    !isCount(receipt.retainedCommits) ||
+    !isCount(receipt.resetSubscriptions)
+  ) {
+    return invalidReceipt();
+  }
+  return JSON.stringify({
+    version: RECEIPT_VERSION,
+    retainedCommits: receipt.retainedCommits,
+    resetSubscriptions: receipt.resetSubscriptions,
+  });
+}
+
+/**
+ * Decode a committed receipt without leaking its application-owned key. The
+ * original counts were not retained by pre-0.15.36 `v1` markers, so those
+ * historical repairs keep their former zero-count replay behavior.
+ */
+export function decodeLocalDataRebootstrapReceipt(
+  value: string,
+): LocalDataRebootstrapReceipt {
+  if (value === LEGACY_MARKER) {
+    return { retainedCommits: 0, resetSubscriptions: 0 };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return invalidReceipt();
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return invalidReceipt();
+  }
+  const source = parsed as Record<string, unknown>;
+  const keys = Object.keys(source).sort();
+  if (
+    keys.length !== RECEIPT_KEYS.length ||
+    keys.some((key, index) => key !== RECEIPT_KEYS[index]) ||
+    source.version !== RECEIPT_VERSION ||
+    !isCount(source.retainedCommits) ||
+    !isCount(source.resetSubscriptions)
+  ) {
+    return invalidReceipt();
+  }
+  return {
+    retainedCommits: source.retainedCommits,
+    resetSubscriptions: source.resetSubscriptions,
+  };
+}

package/src/local-rebootstrap.ts

@@ -24,7 +24,11 @@ export interface LocalDataRebootstrapInput {
   readonly rebootstrapId: string;
 }
 
-/** Privacy-safe acknowledgement; no row or subscription identifiers escape. */
+/**
+ * Privacy-safe acknowledgement; no row or subscription identifiers escape.
+ * An idempotent replay sets `alreadyApplied` while retaining the first call's
+ * exact counts when that repair was first applied by Syncular 0.15.36 or later.
+ */
 export interface LocalDataRebootstrapResult {
   readonly alreadyApplied: boolean;
   readonly retainedCommits: number;