@syncular/client 0.15.26 → 0.15.28

package/README.md

@@ -293,6 +293,35 @@ Only bounded, non-empty, code-like values on plaintext string schema columns
 are accepted. There is intentionally no full-table mode. The result exposes
 counts only—never row ids or selector values.
 
+## Application-authorized projection rebootstrap
+
+`rebootstrapLocalData({ rebootstrapId })` is the recovery primitive for a
+locally damaged or persistently inconsistent replicated projection. It drops
+and recreates only Syncular's server-derived tables, rewinds the existing
+subscription registrations, and requests a fresh bootstrap. It preserves the
+client id, lease state, pending outbox commits, commit outcomes, subscription
+intent, and protected bookkeeping.
+
+```ts
+const result = await client.rebootstrapLocalData({
+  rebootstrapId: crypto.randomUUID(),
+});
+```
+
+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.
+
+This API is not a security erase, sign-out, membership revocation, schema
+upgrade, or draft deletion mechanism. It fails closed during security
+preflight and while a schema-floor stop is active. The application must show a
+preview and explicit confirmation, preserve app-owned drafts/files separately,
+and reserve the operation for diagnostics/support recovery rather than normal
+startup.
+
 Validator rejections may include bounded `details` (`fieldPaths`, `reason`,
 `requiredAction`, and explicitly safe `references`). The details persist with
 the rejection. Treat every value as a machine hint: map known values to

package/dist/client.d.ts

@@ -15,6 +15,7 @@ import type { EncryptionConfig } from './encryption.js';
 import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLock } from './leader-lock.js';
 import { type LocalDataPurgeInput, type LocalDataPurgeResult } from './local-purge.js';
+import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import { type OutboxCommit } from './outbox.js';
 import { type CommitOutcome, type CommitOutcomeQuery, type ConflictRecord, type RejectionRecord, type ResolveCommitOutcomeInput } from './outcomes.js';
 import { type ClientSchema } from './schema.js';
@@ -435,6 +436,17 @@ export declare class SyncClient {
      * reused id with different selectors fails closed.
      */
     purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
+    /**
+     * Rebuild the server-derived local projection without sacrificing offline
+     * work or device identity. The reset, subscription rewind, durable
+     * idempotency marker, and optimistic outbox replay are one SQLite
+     * transaction, so an interruption cannot expose a half-repaired replica.
+     *
+     * This is an application-authorized repair primitive, not a security purge.
+     * It is unavailable during security preflight and while a schema-floor stop
+     * is active: neither condition can be repaired by redownloading data.
+     */
+    rebootstrapLocalData(input: LocalDataRebootstrapInput): LocalDataRebootstrapResult;
     /** Host-facing patch result with explicit network work intent (§7.5). */
     patchCommand(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;

package/dist/client.js

@@ -16,6 +16,7 @@ import { ClientSyncError } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
+import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.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';
@@ -1494,6 +1495,65 @@ export class SyncClient {
             throw error;
         }
     }
+    /**
+     * Rebuild the server-derived local projection without sacrificing offline
+     * work or device identity. The reset, subscription rewind, durable
+     * idempotency marker, and optimistic outbox replay are one SQLite
+     * transaction, so an interruption cannot expose a half-repaired replica.
+     *
+     * This is an application-authorized repair primitive, not a security purge.
+     * It is unavailable during security preflight and while a schema-floor stop
+     * is active: neither condition can be repaired by redownloading data.
+     */
+    rebootstrapLocalData(input) {
+        this.#requireActive();
+        const rebootstrapId = compileLocalDataRebootstrap(input);
+        const metaKey = localDataRebootstrapMetaKey(rebootstrapId);
+        if (getMeta(this.#db, metaKey) !== undefined) {
+            return {
+                alreadyApplied: true,
+                retainedCommits: 0,
+                resetSubscriptions: 0,
+            };
+        }
+        if (this.#schemaFloor !== undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'local rebootstrap cannot bypass an active schema-floor stop; update the application first');
+        }
+        const pending = listOutbox(this.#db);
+        const resetSubscriptions = loadSubscriptions(this.#db).length;
+        const priorUpgrading = this.#upgrading;
+        const priorNeedsPull = this.#needsPull;
+        try {
+            this.#applyBatch((batch) => {
+                this.#upgrading = true;
+                this.#needsPull = true;
+                batch.status();
+                dropAndRecreateSyncedTables(this.#db, this.#schema);
+                resetSubscriptionsForBump(this.#db);
+                for (const table of this.#schema.tables.values()) {
+                    batch.table(table.name);
+                }
+                for (const commit of pending) {
+                    this.#applyOperationsLocally(commit.operations, batch);
+                }
+                setMeta(this.#db, metaKey, 'v1');
+            });
+        }
+        catch (error) {
+            this.#upgrading = priorUpgrading;
+            this.#needsPull = priorNeedsPull;
+            throw error;
+        }
+        if (!priorUpgrading)
+            this.#config.onUpgrading?.(true);
+        this.#config.onSyncNeeded?.('startup');
+        this.#config.onSyncIntent?.({ kind: 'interactive' });
+        return {
+            alreadyApplied: false,
+            retainedCommits: pending.length,
+            resetSubscriptions,
+        };
+    }
     #localPurgeTargetsByTable(purge) {
         const byTable = new Map();
         for (const target of purge.targets) {

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from './http.js';
 export * from './invalidation.js';
 export * from './leader-lock.js';
 export * from './local-purge.js';
+export * from './local-rebootstrap.js';
 export * from './multi-tab.js';
 export * from './naming.js';
 export * from './outbox.js';

package/dist/index.js

@@ -22,6 +22,7 @@ export * from './http.js';
 export * from './invalidation.js';
 export * from './leader-lock.js';
 export * from './local-purge.js';
+export * from './local-rebootstrap.js';
 export * from './multi-tab.js';
 export * from './naming.js';
 export * from './outbox.js';

package/dist/local-rebootstrap.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Application-authorized recovery of the replicated local projection.
+ *
+ * This is deliberately separate from `purgeLocalData`: rebootstrap keeps
+ * device identity, the outbox, commit outcomes, subscription registrations,
+ * lease state, and protected bookkeeping. It only discards server-derived
+ * projection state so the registered subscriptions can bootstrap it again.
+ */
+/** 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. */
+export interface LocalDataRebootstrapResult {
+    readonly alreadyApplied: boolean;
+    readonly retainedCommits: number;
+    readonly resetSubscriptions: number;
+}
+/** 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

@@ -0,0 +1,22 @@
+/**
+ * Application-authorized recovery of the replicated local projection.
+ *
+ * This is deliberately separate from `purgeLocalData`: rebootstrap keeps
+ * device identity, the outbox, commit outcomes, subscription registrations,
+ * lease state, and protected bookkeeping. It only discards server-derived
+ * projection state so the registered subscriptions can bootstrap it again.
+ */
+import { ClientSyncError } from './errors.js';
+const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+/** Validate before entering the recovery transaction. */
+export function compileLocalDataRebootstrap(input) {
+    if (input.rebootstrapId.length === 0 ||
+        input.rebootstrapId.length > 128 ||
+        !CODE_LIKE_VALUE.test(input.rebootstrapId)) {
+        throw new ClientSyncError('sync.invalid_request', 'local rebootstrap rebootstrapId must be a 1–128 character code-like identifier');
+    }
+    return input.rebootstrapId;
+}
+export function localDataRebootstrapMetaKey(rebootstrapId) {
+    return `localRebootstrap:${rebootstrapId}`;
+}

package/dist/worker-entry.js

@@ -321,6 +321,7 @@ export function startSyncWorker(overrides = {}) {
             return result.value;
         },
         purgeLocalData: (input) => requireClient().purgeLocalData(input),
+        rebootstrapLocalData: (input) => requireClient().rebootstrapLocalData(input),
         sync: () => {
             const running = requireClient();
             return serializedSync(() => running.sync());

package/dist/worker-host.d.ts

@@ -30,6 +30,7 @@ import type { EncryptionKeyringConfig } from './encryption.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 CrossTabChannel, FollowerLink, LeaderBridge, type LeadershipState } from './multi-tab.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
@@ -189,6 +190,7 @@ export declare class SyncClientHandle {
         readonly baseVersion?: number;
     }): Promise<string>;
     purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
+    rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;

package/dist/worker-host.js

@@ -247,6 +247,9 @@ export class SyncClientHandle {
     purgeLocalData(input) {
         return this.#call('purgeLocalData', [input]);
     }
+    rebootstrapLocalData(input) {
+        return this.#call('rebootstrapLocalData', [input]);
+    }
     sync() {
         return this.#call('sync', []);
     }

package/dist/worker-protocol.d.ts

@@ -24,6 +24,7 @@ import type { ClientDiagnosticsRequest, ClientDiagnosticsSnapshot } from './diag
 import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
+import type { LocalDataRebootstrapInput, LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
 import type { ClientSchema } from './schema.js';
@@ -102,6 +103,8 @@ export interface WorkerApi {
     }): string;
     /** Application-authorized, idempotent local security purge. */
     purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
+    /** Application-authorized, outbox-preserving projection recovery. */
+    rebootstrapLocalData(input: LocalDataRebootstrapInput): LocalDataRebootstrapResult;
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.26",
+  "version": "0.15.28",
   "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.26"
+    "@syncular/core": "0.15.28"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.26",
+    "@syncular/server": "0.15.28",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -103,6 +103,12 @@ import {
   localDataPurgeMetaKey,
   localDataPurgeTargetMatches,
 } from './local-purge';
+import {
+  compileLocalDataRebootstrap,
+  type LocalDataRebootstrapInput,
+  type LocalDataRebootstrapResult,
+  localDataRebootstrapMetaKey,
+} from './local-rebootstrap';
 import {
   appendOutboxCommit,
   deleteOutboxCommit,
@@ -2222,6 +2228,71 @@ export class SyncClient {
     }
   }
 
+  /**
+   * Rebuild the server-derived local projection without sacrificing offline
+   * work or device identity. The reset, subscription rewind, durable
+   * idempotency marker, and optimistic outbox replay are one SQLite
+   * transaction, so an interruption cannot expose a half-repaired replica.
+   *
+   * This is an application-authorized repair primitive, not a security purge.
+   * It is unavailable during security preflight and while a schema-floor stop
+   * is active: neither condition can be repaired by redownloading data.
+   */
+  rebootstrapLocalData(
+    input: LocalDataRebootstrapInput,
+  ): LocalDataRebootstrapResult {
+    this.#requireActive();
+    const rebootstrapId = compileLocalDataRebootstrap(input);
+    const metaKey = localDataRebootstrapMetaKey(rebootstrapId);
+    if (getMeta(this.#db, metaKey) !== undefined) {
+      return {
+        alreadyApplied: true,
+        retainedCommits: 0,
+        resetSubscriptions: 0,
+      };
+    }
+    if (this.#schemaFloor !== undefined) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        'local rebootstrap cannot bypass an active schema-floor stop; update the application first',
+      );
+    }
+
+    const pending = listOutbox(this.#db);
+    const resetSubscriptions = loadSubscriptions(this.#db).length;
+    const priorUpgrading = this.#upgrading;
+    const priorNeedsPull = this.#needsPull;
+    try {
+      this.#applyBatch((batch) => {
+        this.#upgrading = true;
+        this.#needsPull = true;
+        batch.status();
+        dropAndRecreateSyncedTables(this.#db, this.#schema);
+        resetSubscriptionsForBump(this.#db);
+        for (const table of this.#schema.tables.values()) {
+          batch.table(table.name);
+        }
+        for (const commit of pending) {
+          this.#applyOperationsLocally(commit.operations, batch);
+        }
+        setMeta(this.#db, metaKey, 'v1');
+      });
+    } catch (error) {
+      this.#upgrading = priorUpgrading;
+      this.#needsPull = priorNeedsPull;
+      throw error;
+    }
+
+    if (!priorUpgrading) this.#config.onUpgrading?.(true);
+    this.#config.onSyncNeeded?.('startup');
+    this.#config.onSyncIntent?.({ kind: 'interactive' });
+    return {
+      alreadyApplied: false,
+      retainedCommits: pending.length,
+      resetSubscriptions,
+    };
+  }
+
   #localPurgeTargetsByTable(
     purge: CompiledLocalDataPurge,
   ): Map<string, CompiledLocalDataPurgeTarget[]> {

package/src/index.ts

@@ -22,6 +22,7 @@ export * from './http';
 export * from './invalidation';
 export * from './leader-lock';
 export * from './local-purge';
+export * from './local-rebootstrap';
 export * from './multi-tab';
 export * from './naming';
 export * from './outbox';

package/src/local-rebootstrap.ts

@@ -0,0 +1,45 @@
+/**
+ * Application-authorized recovery of the replicated local projection.
+ *
+ * This is deliberately separate from `purgeLocalData`: rebootstrap keeps
+ * device identity, the outbox, commit outcomes, subscription registrations,
+ * lease state, and protected bookkeeping. It only discards server-derived
+ * projection state so the registered subscriptions can bootstrap it again.
+ */
+
+import { ClientSyncError } from './errors';
+
+const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+/** 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. */
+export interface LocalDataRebootstrapResult {
+  readonly alreadyApplied: boolean;
+  readonly retainedCommits: number;
+  readonly resetSubscriptions: number;
+}
+
+/** Validate before entering the recovery transaction. */
+export function compileLocalDataRebootstrap(
+  input: LocalDataRebootstrapInput,
+): string {
+  if (
+    input.rebootstrapId.length === 0 ||
+    input.rebootstrapId.length > 128 ||
+    !CODE_LIKE_VALUE.test(input.rebootstrapId)
+  ) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'local rebootstrap rebootstrapId must be a 1–128 character code-like identifier',
+    );
+  }
+  return input.rebootstrapId;
+}
+
+export function localDataRebootstrapMetaKey(rebootstrapId: string): string {
+  return `localRebootstrap:${rebootstrapId}`;
+}

package/src/worker-entry.ts

@@ -419,6 +419,8 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       return result.value;
     },
     purgeLocalData: (input) => requireClient().purgeLocalData(input),
+    rebootstrapLocalData: (input) =>
+      requireClient().rebootstrapLocalData(input),
     sync: () => {
       const running = requireClient();
       return serializedSync(() => running.sync());

package/src/worker-host.ts

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

package/src/worker-protocol.ts

@@ -45,6 +45,10 @@ import type {
   SyncStatusSnapshot,
 } from './invalidation';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge';
+import type {
+  LocalDataRebootstrapInput,
+  LocalDataRebootstrapResult,
+} from './local-rebootstrap';
 import type { OutboxCommit } from './outbox';
 import type {
   CommitOutcome,
@@ -151,6 +155,10 @@ export interface WorkerApi {
   ): string;
   /** Application-authorized, idempotent local security purge. */
   purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult;
+  /** Application-authorized, outbox-preserving projection recovery. */
+  rebootstrapLocalData(
+    input: LocalDataRebootstrapInput,
+  ): LocalDataRebootstrapResult;
   sync(): Promise<SyncSummary>;
   syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];