@syncular/client 0.15.13 → 0.15.15

package/dist/worker-host.d.ts

@@ -23,20 +23,39 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 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 CrossTabChannel, FollowerLink, LeaderBridge } from './multi-tab.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';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
-import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape } from './worker-protocol.js';
+import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
 export type HandleRole = 'leader' | 'follower';
+export type BrowserReplicaMode = {
+    readonly mode: 'shared';
+} | {
+    readonly mode: 'isolated';
+    readonly id: string;
+};
+export interface IsolatedReplicaNames {
+    readonly databaseName: string;
+    readonly databaseDirectory: string;
+    readonly lockName: string;
+    readonly channelName: string;
+}
+/** Derive the complete ownership tuple for an independently owned replica. */
+export declare function isolatedReplicaNames(options: {
+    readonly databaseName: string;
+    readonly databaseDirectory?: string;
+    readonly lockName?: string;
+    readonly replicaId: string;
+}): IsolatedReplicaNames;
 export interface SyncClientHandleConfig {
     /**
      * Spawns the worker running `startSyncWorker()` (a factory so bundlers
@@ -50,6 +69,8 @@ export interface SyncClientHandleConfig {
     readonly endpoints: WorkerEndpoints;
     /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
     readonly encryption?: EncryptionKeyringConfig;
+    /** Open the worker-owned replica behind the fail-closed security gate. */
+    readonly securityPreflight?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     /** Worker-side host loop (§8.4); default true. */
@@ -57,6 +78,8 @@ export interface SyncClientHandleConfig {
     /** Default: Web Locks when available, else single-owner. */
     readonly leaderLock?: LeaderLock;
     readonly lockName?: string;
+    /** Shared by default; isolated derives the database/lock/channel tuple. */
+    readonly replica?: BrowserReplicaMode;
     /**
      * Multi-tab followers (TODO 3.2). On by default: a tab that loses the
      * leader election becomes a FOLLOWER that proxies to the leader over a
@@ -71,6 +94,8 @@ export interface SyncClientHandleConfig {
     readonly followerCallTimeoutMs?: number;
     /** Fires when this handle's role changes (follower → leader on promotion). */
     readonly onRoleChange?: (role: HandleRole) => void;
+    /** Fires when reachability or ownership changes without replacing the handle. */
+    readonly onLeadershipChange?: (state: LeadershipState) => void;
     readonly onSyncNeeded?: (reason: 'startup' | 'hello' | WakeReason) => void;
     readonly onConflict?: (conflict: ConflictRecord) => void;
     /** A worker-side autoSync round finished (or failed). */
@@ -107,19 +132,27 @@ export declare class SyncClientHandle {
     get role(): HandleRole;
     /** Resolved client id — the leader's; shared by all tabs on this origin. */
     get clientId(): string;
+    get currentSchemaVersion(): number;
+    get leadership(): LeadershipState;
+    leadershipSnapshot(): LeadershipState;
     /** @internal — use {@link createSyncClientHandle}. */
     constructor(internals: {
         role: HandleRole;
         clientId: string;
+        currentSchemaVersion: number;
         core?: LeaderCore;
         follower?: FollowerLink;
         invalidation: InvalidationEmitter;
         changes: ChangeEmitter;
         presence: Set<(scopeKey: string) => void>;
         roleListeners?: Set<(role: HandleRole) => void>;
+        leadershipListeners?: Set<(state: LeadershipState) => void>;
+        leadership?: LeadershipState;
     });
     /** @internal — swap this handle from follower to leader (promotion). */
     __becomeLeader(core: LeaderCore): void;
+    /** @internal — apply a follower reachability snapshot in place. */
+    __setLeadership(state: LeadershipState): void;
     /** @internal — dispatch a worker/relayed event to handle-local listeners. */
     __dispatchEvent(event: SyncWorkerEvent): void;
     /**
@@ -137,7 +170,11 @@ export declare class SyncClientHandle {
     onPresence(listener: (scopeKey: string) => void): () => void;
     /** Subscribe to role transitions (follower → leader on promotion). */
     onRoleChange(listener: (role: HandleRole) => void): () => void;
+    onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
     subscribe(input: SubscribeInput): Promise<void>;
+    securityLifecycle(): Promise<SecurityLifecycle>;
+    beginSecurityPreflight(): Promise<void>;
+    activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
     unsubscribe(id: string): Promise<void>;
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
     windowState(base: WindowBase): Promise<WindowState>;

package/dist/worker-host.js

@@ -4,6 +4,21 @@ import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './i
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
 import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
 import { NOT_LEADER_CODE, WORKER_FAILED_CODE, } from './worker-protocol.js';
+/** Derive the complete ownership tuple for an independently owned replica. */
+export function isolatedReplicaNames(options) {
+    if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
+        throw new ClientSyncError('sync.invalid_request', 'an isolated replica id must contain only letters, numbers, dot, underscore, or dash');
+    }
+    const suffix = `--replica-${options.replicaId}`;
+    const databaseName = `${options.databaseName}${suffix}`;
+    const lockName = `${options.lockName ?? 'syncular-leader'}${suffix}`;
+    return {
+        databaseName,
+        databaseDirectory: `${options.databaseDirectory ?? `.syncular/${options.databaseName}`}${suffix}`,
+        lockName,
+        channelName: multiTabChannelName(lockName),
+    };
+}
 function defaultLeaderLock() {
     const nav = globalThis.navigator;
     return nav?.locks !== undefined
@@ -27,26 +42,50 @@ export class SyncClientHandle {
     get clientId() {
         return this.#clientId;
     }
+    get currentSchemaVersion() {
+        return this.#currentSchemaVersion;
+    }
+    get leadership() {
+        return this.#leadership;
+    }
+    leadershipSnapshot() {
+        return this.#leadership;
+    }
     #role;
     #clientId;
+    #currentSchemaVersion;
+    #leadership;
     #core;
     #follower;
     #invalidation;
     #changes;
     #presence;
     #roleListeners;
+    #leadershipListeners;
     #devtoolsUnregister;
     #closed = false;
     /** @internal — use {@link createSyncClientHandle}. */
     constructor(internals) {
         this.#role = internals.role;
         this.#clientId = internals.clientId;
+        this.#currentSchemaVersion = internals.currentSchemaVersion;
+        this.#leadership =
+            internals.leadership ??
+                (internals.role === 'leader'
+                    ? { state: 'leader', clientId: internals.clientId }
+                    : (internals.follower?.leadershipState ?? {
+                        state: 'blocked',
+                        reason: 'leader-unreachable',
+                        code: 'client.follower_timeout',
+                        retryable: true,
+                    }));
         this.#core = internals.core;
         this.#follower = internals.follower;
         this.#invalidation = internals.invalidation;
         this.#changes = internals.changes;
         this.#presence = internals.presence;
         this.#roleListeners = internals.roleListeners ?? new Set();
+        this.#leadershipListeners = internals.leadershipListeners ?? new Set();
         // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
         this.#devtoolsUnregister = registerDevtools({
             kind: 'handle',
@@ -69,6 +108,7 @@ export class SyncClientHandle {
         this.#core = core;
         this.#clientId = core.clientId;
         this.#role = 'leader';
+        this.__setLeadership({ state: 'leader', clientId: core.clientId });
         for (const listener of this.#roleListeners) {
             try {
                 listener('leader');
@@ -78,6 +118,20 @@ export class SyncClientHandle {
             }
         }
     }
+    /** @internal — apply a follower reachability snapshot in place. */
+    __setLeadership(state) {
+        this.#leadership = state;
+        if (state.state === 'follower')
+            this.#clientId = state.leaderClientId;
+        for (const listener of this.#leadershipListeners) {
+            try {
+                listener(state);
+            }
+            catch {
+                /* a UI listener must never break leadership transitions */
+            }
+        }
+    }
     /** @internal — dispatch a worker/relayed event to handle-local listeners. */
     __dispatchEvent(event) {
         if (event.kind === 'presence') {
@@ -126,6 +180,12 @@ export class SyncClientHandle {
             this.#roleListeners.delete(listener);
         };
     }
+    onLeadershipChange(listener) {
+        this.#leadershipListeners.add(listener);
+        return () => {
+            this.#leadershipListeners.delete(listener);
+        };
+    }
     #call(method, args) {
         if (this.#closed) {
             return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'));
@@ -146,6 +206,15 @@ export class SyncClientHandle {
     subscribe(input) {
         return this.#call('subscribe', [input]);
     }
+    securityLifecycle() {
+        return this.#call('securityLifecycle', []);
+    }
+    beginSecurityPreflight() {
+        return this.#call('beginSecurityPreflight', []);
+    }
+    activateSecurity(options = {}) {
+        return this.#call('activateSecurity', [options]);
+    }
     unsubscribe(id) {
         return this.#call('unsubscribe', [id]);
     }
@@ -373,6 +442,9 @@ function buildInitConfig(config) {
         ...(config.encryption !== undefined
             ? { encryption: config.encryption }
             : {}),
+        ...(config.securityPreflight !== undefined
+            ? { securityPreflight: config.securityPreflight }
+            : {}),
         ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
         ...(config.limits !== undefined ? { limits: config.limits } : {}),
         ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
@@ -407,14 +479,19 @@ function fireConfigCallbacks(config, event) {
  * `multiTab: false`: a losing tab resolves to a dead not-leader handle.
  */
 export async function createSyncClientHandle(config) {
-    const lock = config.leaderLock ?? defaultLeaderLock();
-    const lockName = config.lockName ?? 'syncular-leader';
+    const resolvedConfig = resolveReplicaConfig(config);
+    const lock = resolvedConfig.leaderLock ?? defaultLeaderLock();
+    const lockName = resolvedConfig.lockName ?? 'syncular-leader';
     const invalidation = new InvalidationEmitter();
     const changes = new ChangeEmitter();
     const presence = new Set();
     const roleListeners = new Set();
-    if (config.onRoleChange !== undefined)
-        roleListeners.add(config.onRoleChange);
+    if (resolvedConfig.onRoleChange !== undefined)
+        roleListeners.add(resolvedConfig.onRoleChange);
+    const leadershipListeners = new Set();
+    if (resolvedConfig.onLeadershipChange !== undefined) {
+        leadershipListeners.add(resolvedConfig.onLeadershipChange);
+    }
     // Leadership BEFORE the worker exists: one core per origin, and a losing
     // tab never boots a database it must not own.
     const lease = lock.tryAcquire !== undefined
@@ -425,32 +502,36 @@ export async function createSyncClientHandle(config) {
         // Epoch derivation for a fresh boot: epoch 0. A promoter (below) reads
         // the highest epoch it has seen and adds one, so leaders monotonically
         // increase it across handovers.
-        return await bootLeader(config, lockName, lease, {
+        return await bootLeader(resolvedConfig, lockName, lease, {
             epoch: 0,
             invalidation,
             changes,
             presence,
             roleListeners,
+            leadershipListeners,
         });
     }
     // ---- Lost the election. ----
-    if (config.multiTab === false) {
+    if (resolvedConfig.multiTab === false) {
         // Opted-out single-tab contract: a dead not-leader handle.
         return new SyncClientHandle({
             role: 'follower',
             clientId: '',
+            currentSchemaVersion: resolvedConfig.schema.version,
             invalidation,
             changes,
             presence,
             roleListeners,
+            leadershipListeners,
         });
     }
     // ---- Follower: proxy to the leader; contest + promote on its close. ----
-    return await bootFollower(config, lockName, lock, {
+    return await bootFollower(resolvedConfig, lockName, lock, {
         invalidation,
         changes,
         presence,
         roleListeners,
+        leadershipListeners,
     });
 }
 /** Boot (or promote to) a leader: spawn the worker, wire the bridge. */
@@ -471,6 +552,7 @@ async function bootLeader(config, lockName, lease, parts) {
                 epoch: parts.epoch ?? 0,
                 clientId,
                 invoke,
+                heartbeatMs: Math.max(10, Math.floor((config.followerCallTimeoutMs ?? 10_000) / 3)),
             });
         }
         : undefined;
@@ -484,11 +566,13 @@ async function bootLeader(config, lockName, lease, parts) {
     const handle = new SyncClientHandle({
         role: 'leader',
         clientId: core.clientId,
+        currentSchemaVersion: config.schema.version,
         core,
         invalidation: parts.invalidation,
         changes: parts.changes,
         presence: parts.presence,
         roleListeners: parts.roleListeners,
+        leadershipListeners: parts.leadershipListeners,
     });
     handleRef.handle = handle;
     return handle;
@@ -512,6 +596,7 @@ async function bootFollower(config, lockName, lock, parts) {
             // it after binding). Nothing else to do — calls already flush.
             void clientId;
         },
+        onStateChange: (state) => handleRef.handle?.__setLeadership(state),
         ...(config.followerCallTimeoutMs !== undefined
             ? { callTimeoutMs: config.followerCallTimeoutMs }
             : {}),
@@ -549,6 +634,7 @@ async function bootFollower(config, lockName, lock, parts) {
                                 epoch: nextEpoch,
                                 clientId,
                                 invoke,
+                                heartbeatMs: Math.max(10, Math.floor((config.followerCallTimeoutMs ?? 10_000) / 3)),
                             });
                         },
                     }
@@ -568,11 +654,13 @@ async function bootFollower(config, lockName, lock, parts) {
         // leave '' until promotion (the shared id is the leader's — hooks that
         // need it read it after a round). Followers rarely need clientId directly.
         clientId: '',
+        currentSchemaVersion: config.schema.version,
         follower,
         invalidation: parts.invalidation,
         changes: parts.changes,
         presence: parts.presence,
         roleListeners: parts.roleListeners,
+        leadershipListeners: parts.leadershipListeners,
     });
     handleRef.handle = handle;
     // Do not hand back a follower until its link has bound to the leader (the
@@ -589,5 +677,36 @@ async function bootFollower(config, lockName, lock, parts) {
     catch {
         /* bind timed out — return the (degraded but functional) handle anyway */
     }
+    // Init configuration belongs to the one leader worker. A newly opened
+    // follower that explicitly requests security preflight must therefore put
+    // the shared origin replica behind the same barrier before it is returned;
+    // otherwise an already-running leader would silently ignore the request.
+    if (config.securityPreflight === true) {
+        await handle.beginSecurityPreflight();
+    }
     return handle;
 }
+function resolveReplicaConfig(config) {
+    if (config.replica?.mode !== 'isolated')
+        return config;
+    if (config.database.mode !== 'persistent') {
+        throw new ClientSyncError('sync.invalid_request', 'isolated browser replicas require a named persistent database');
+    }
+    const names = isolatedReplicaNames({
+        databaseName: config.database.name,
+        ...(config.database.directory !== undefined
+            ? { databaseDirectory: config.database.directory }
+            : {}),
+        ...(config.lockName !== undefined ? { lockName: config.lockName } : {}),
+        replicaId: config.replica.id,
+    });
+    return {
+        ...config,
+        lockName: names.lockName,
+        database: {
+            ...config.database,
+            name: names.databaseName,
+            directory: names.databaseDirectory,
+        },
+    };
+}

package/dist/worker-protocol.d.ts

@@ -18,7 +18,7 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
@@ -65,6 +65,8 @@ export interface WorkerInitConfig {
     readonly endpoints: WorkerEndpoints;
     /** Portable raw keyring installed inside the worker-owned client core. */
     readonly encryption?: EncryptionKeyringConfig;
+    /** Open the worker-owned replica behind the fail-closed security gate. */
+    readonly securityPreflight?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     /**
@@ -78,7 +80,14 @@ export interface WorkerInitConfig {
 export interface WorkerInitResult {
     readonly clientId: string;
 }
+/** Structured-clone-safe key material installed at security activation. */
+export interface WorkerSecurityActivation {
+    readonly encryption?: EncryptionKeyringConfig;
+}
 export interface WorkerApi {
+    securityLifecycle(): SecurityLifecycle;
+    beginSecurityPreflight(): Promise<void>;
+    activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
     subscribe(input: SubscribeInput): void;
     unsubscribe(id: string): void;
     /** §4.8 windowed subscriptions: set the live units for a window base. */

package/package.json

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

package/src/availability.ts

@@ -0,0 +1,70 @@
+import type { SyncStatusSnapshot } from './invalidation';
+import type { LeadershipState } from './multi-tab';
+
+export type SyncAvailability =
+  | { readonly state: 'ready' }
+  | { readonly state: 'migrating'; readonly currentSchemaVersion: number }
+  | {
+      readonly state: 'blocked';
+      readonly reason:
+        | 'client-upgrade-required'
+        | 'server-behind'
+        | 'incompatible-schema'
+        | 'leader-unreachable';
+      readonly currentSchemaVersion: number;
+      readonly requiredSchemaVersion?: number;
+      readonly latestServerSchemaVersion?: number;
+      readonly retryable: boolean;
+    };
+
+/** Classify schema and browser-ownership state without parsing diagnostics. */
+export function classifySyncAvailability(
+  status: SyncStatusSnapshot,
+  leadership?: LeadershipState,
+): SyncAvailability {
+  const currentSchemaVersion = status.currentSchemaVersion;
+  if (leadership?.state === 'blocked') {
+    return {
+      state: 'blocked',
+      reason: 'leader-unreachable',
+      currentSchemaVersion,
+      retryable: true,
+    };
+  }
+  const required = status.schemaFloor?.requiredSchemaVersion;
+  const latest = status.schemaFloor?.latestSchemaVersion;
+  if (required !== undefined && required > currentSchemaVersion) {
+    return {
+      state: 'blocked',
+      reason: 'client-upgrade-required',
+      currentSchemaVersion,
+      requiredSchemaVersion: required,
+      ...(latest !== undefined ? { latestServerSchemaVersion: latest } : {}),
+      retryable: false,
+    };
+  }
+  if (latest !== undefined && latest < currentSchemaVersion) {
+    return {
+      state: 'blocked',
+      reason: 'server-behind',
+      currentSchemaVersion,
+      ...(required !== undefined ? { requiredSchemaVersion: required } : {}),
+      latestServerSchemaVersion: latest,
+      retryable: false,
+    };
+  }
+  if (status.schemaFloor !== undefined) {
+    return {
+      state: 'blocked',
+      reason: 'incompatible-schema',
+      currentSchemaVersion,
+      ...(required !== undefined ? { requiredSchemaVersion: required } : {}),
+      ...(latest !== undefined ? { latestServerSchemaVersion: latest } : {}),
+      retryable: false,
+    };
+  }
+  if (status.upgrading) {
+    return { state: 'migrating', currentSchemaVersion };
+  }
+  return { state: 'ready' };
+}