@syncular/client 0.15.34 → 0.15.36

package/README.md

@@ -312,9 +312,22 @@ 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
+`alreadyApplied`, or counts that are not non-negative safe integers fail with
+`client.invalid_host_response`; raw bridge values and native error prose must
+not be persisted as recovery evidence. `decodeLocalDataRebootstrapResult()` is
+public for custom command hosts that expose the same operation.
 
 This API is not a security erase, sign-out, membership revocation, schema
 upgrade, or draft deletion mechanism. It fails closed during security

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

@@ -6,16 +6,29 @@
  * lease state, and protected bookkeeping. It only discards server-derived
  * projection state so the registered subscriptions can bootstrap it again.
  */
+/** A non-direct host returned a response that does not match its public API. */
+export declare const INVALID_HOST_RESPONSE_CODE = "client.invalid_host_response";
 /** A durable idempotency key supplied by the application repair coordinator. */
 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;
     readonly resetSubscriptions: number;
 }
+/**
+ * Strictly decode the privacy-safe acknowledgement returned by a Worker or
+ * native command bridge. Compile-time host types are not runtime proof: this
+ * rejects version drift and malformed bridge values before an application can
+ * persist or display them.
+ */
+export declare function decodeLocalDataRebootstrapResult(value: unknown): LocalDataRebootstrapResult;
 /** Validate before entering the recovery transaction. */
 export declare function compileLocalDataRebootstrap(input: LocalDataRebootstrapInput): string;
 export declare function localDataRebootstrapMetaKey(rebootstrapId: string): string;

package/dist/local-rebootstrap.js

@@ -8,6 +8,44 @@
  */
 import { ClientSyncError } from './errors.js';
 const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const RESULT_KEYS = [
+    'alreadyApplied',
+    'resetSubscriptions',
+    'retainedCommits',
+];
+/** A non-direct host returned a response that does not match its public API. */
+export const INVALID_HOST_RESPONSE_CODE = 'client.invalid_host_response';
+function invalidHostResponse() {
+    throw new ClientSyncError(INVALID_HOST_RESPONSE_CODE, 'rebootstrapLocalData returned an invalid host response');
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * Strictly decode the privacy-safe acknowledgement returned by a Worker or
+ * native command bridge. Compile-time host types are not runtime proof: this
+ * rejects version drift and malformed bridge values before an application can
+ * persist or display them.
+ */
+export function decodeLocalDataRebootstrapResult(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalidHostResponse();
+    }
+    const source = value;
+    const keys = Object.keys(source).sort();
+    if (keys.length !== RESULT_KEYS.length ||
+        keys.some((key, index) => key !== RESULT_KEYS[index]) ||
+        typeof source.alreadyApplied !== 'boolean' ||
+        !isCount(source.retainedCommits) ||
+        !isCount(source.resetSubscriptions)) {
+        return invalidHostResponse();
+    }
+    return {
+        alreadyApplied: source.alreadyApplied,
+        retainedCommits: source.retainedCommits,
+        resetSubscriptions: source.resetSubscriptions,
+    };
+}
 /** Validate before entering the recovery transaction. */
 export function compileLocalDataRebootstrap(input) {
     if (input.rebootstrapId.length === 0 ||

package/dist/worker-host.d.ts

@@ -31,7 +31,7 @@ import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
-import type { LocalDataRebootstrapInput, LocalDataRebootstrapResult } from './local-rebootstrap.js';
+import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import { type CrossTabChannel, FollowerLink, LeaderBridge, type LeadershipState } from './multi-tab.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';

package/dist/worker-host.js

@@ -3,6 +3,7 @@ import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnost
 import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
+import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
 import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
 import { NOT_LEADER_CODE, WORKER_FAILED_CODE, WORKER_RESTART_REQUIRED_CODE, } from './worker-protocol.js';
 const WORKER_BUNDLE_LOAD_FAILURE = /(?:failed to fetch dynamically imported module|error loading dynamically imported module|importing a module script failed|failed to load module script)/iu;
@@ -255,8 +256,8 @@ export class SyncClientHandle {
     purgeLocalData(input) {
         return this.#call('purgeLocalData', [input]);
     }
-    rebootstrapLocalData(input) {
-        return this.#call('rebootstrapLocalData', [input]);
+    async rebootstrapLocalData(input) {
+        return decodeLocalDataRebootstrapResult(await this.#call('rebootstrapLocalData', [input]));
     }
     sync() {
         return this.#call('sync', []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.34",
+  "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.34"
+    "@syncular/core": "0.15.36"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.34",
+    "@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

@@ -10,19 +10,72 @@
 import { ClientSyncError } from './errors';
 
 const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const RESULT_KEYS = [
+  'alreadyApplied',
+  'resetSubscriptions',
+  'retainedCommits',
+] as const;
+
+/** A non-direct host returned a response that does not match its public API. */
+export const INVALID_HOST_RESPONSE_CODE = 'client.invalid_host_response';
 
 /** A durable idempotency key supplied by the application repair coordinator. */
 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;
   readonly resetSubscriptions: number;
 }
 
+function invalidHostResponse(): never {
+  throw new ClientSyncError(
+    INVALID_HOST_RESPONSE_CODE,
+    'rebootstrapLocalData returned an invalid host response',
+  );
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * Strictly decode the privacy-safe acknowledgement returned by a Worker or
+ * native command bridge. Compile-time host types are not runtime proof: this
+ * rejects version drift and malformed bridge values before an application can
+ * persist or display them.
+ */
+export function decodeLocalDataRebootstrapResult(
+  value: unknown,
+): LocalDataRebootstrapResult {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return invalidHostResponse();
+  }
+  const source = value as Record<string, unknown>;
+  const keys = Object.keys(source).sort();
+  if (
+    keys.length !== RESULT_KEYS.length ||
+    keys.some((key, index) => key !== RESULT_KEYS[index]) ||
+    typeof source.alreadyApplied !== 'boolean' ||
+    !isCount(source.retainedCommits) ||
+    !isCount(source.resetSubscriptions)
+  ) {
+    return invalidHostResponse();
+  }
+  return {
+    alreadyApplied: source.alreadyApplied,
+    retainedCommits: source.retainedCommits,
+    resetSubscriptions: source.resetSubscriptions,
+  };
+}
+
 /** Validate before entering the recovery transaction. */
 export function compileLocalDataRebootstrap(
   input: LocalDataRebootstrapInput,

package/src/worker-host.ts

@@ -65,9 +65,10 @@ import {
   webLocksLeaderLock,
 } from './leader-lock';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge';
-import type {
-  LocalDataRebootstrapInput,
-  LocalDataRebootstrapResult,
+import {
+  decodeLocalDataRebootstrapResult,
+  type LocalDataRebootstrapInput,
+  type LocalDataRebootstrapResult,
 } from './local-rebootstrap';
 import {
   broadcastChannelFactory,
@@ -512,10 +513,12 @@ export class SyncClientHandle {
     return this.#call('purgeLocalData', [input]);
   }
 
-  rebootstrapLocalData(
+  async rebootstrapLocalData(
     input: LocalDataRebootstrapInput,
   ): Promise<LocalDataRebootstrapResult> {
-    return this.#call('rebootstrapLocalData', [input]);
+    return decodeLocalDataRebootstrapResult(
+      await this.#call('rebootstrapLocalData', [input]),
+    );
   }
 
   sync(): Promise<SyncSummary> {