@syncular/client 0.15.13 → 0.15.14

package/dist/reactive-store.js

@@ -1,3 +1,4 @@
+import { classifySyncAvailability, } from './availability.js';
 import { windowBaseKey } from './window.js';
 function errorOf(value) {
     return value instanceof Error ? value : new Error(String(value));
@@ -62,6 +63,19 @@ function encodeCanonical(value, stack) {
 export function canonicalValue(value) {
     return encodeCanonical(value, new Set());
 }
+const reactiveFunctionIds = new WeakMap();
+let nextReactiveFunctionId = 1;
+function reactiveFunctionId(fn) {
+    if (fn === undefined)
+        return undefined;
+    let id = reactiveFunctionIds.get(fn);
+    if (id === undefined) {
+        id = nextReactiveFunctionId;
+        nextReactiveFunctionId += 1;
+        reactiveFunctionIds.set(fn, id);
+    }
+    return id;
+}
 function scheduleMicrotask(task) {
     if (typeof queueMicrotask === 'function')
         queueMicrotask(task);
@@ -175,6 +189,7 @@ class QueryEntry {
         revision: undefined,
         error: undefined,
         isRefreshing: false,
+        availability: { state: 'ready' },
     };
     #subscribers = 0;
     #scheduled = false;
@@ -182,6 +197,7 @@ class QueryEntry {
     #requested = false;
     #desiredRevision = 0n;
     #claimReady = Promise.resolve();
+    #offStatus;
     constructor(store, spec) {
         this.store = store;
         this.spec = spec;
@@ -191,6 +207,8 @@ class QueryEntry {
         this.#listeners.add(listener);
         this.#subscribers += 1;
         if (this.#subscribers === 1) {
+            this.#offStatus = this.store.status.subscribe(() => this.#onAvailabilityChange());
+            this.#onAvailabilityChange();
             if (this.spec.claimCoverage !== false) {
                 const claims = [];
                 for (const coverage of this.spec.coverage ?? []) {
@@ -204,8 +222,11 @@ class QueryEntry {
             if (!this.#listeners.delete(listener))
                 return;
             this.#subscribers -= 1;
-            if (this.#subscribers === 0)
+            if (this.#subscribers === 0) {
+                this.#offStatus?.();
+                this.#offStatus = undefined;
                 this.store.releaseWindowClaims(this.#owner);
+            }
         };
     };
     refresh = () => this.#requestRead(true);
@@ -222,7 +243,9 @@ class QueryEntry {
         if (next.rows === this.#state.rows &&
             next.phase === this.#state.phase &&
             next.error === this.#state.error &&
-            next.isRefreshing === this.#state.isRefreshing) {
+            next.isRefreshing === this.#state.isRefreshing &&
+            canonicalValue(next.availability) ===
+                canonicalValue(this.#state.availability)) {
             return;
         }
         this.#state = next;
@@ -244,6 +267,30 @@ class QueryEntry {
             void this.#readLoop();
         });
     }
+    #onAvailabilityChange() {
+        const availability = this.store.availabilitySnapshot();
+        if (availability.state === 'blocked') {
+            this.#publish({
+                ...this.#state,
+                phase: 'blocked',
+                availability,
+                isRefreshing: false,
+            });
+            return;
+        }
+        const wasBlocked = this.#state.phase === 'blocked';
+        this.#publish({
+            ...this.#state,
+            phase: wasBlocked
+                ? this.#state.rows.length > 0
+                    ? 'partial'
+                    : 'loading'
+                : this.#state.phase,
+            availability,
+        });
+        if (wasBlocked)
+            this.#requestRead();
+    }
     async #readLoop() {
         if (this.#running || this.#subscribers === 0)
             return;
@@ -251,6 +298,8 @@ class QueryEntry {
         try {
             do {
                 this.#requested = false;
+                if (this.store.availabilitySnapshot().state === 'blocked')
+                    break;
                 await this.#claimReady;
                 const snapshot = await this.store.client.querySnapshot({
                     sql: this.spec.sql,
@@ -261,11 +310,24 @@ class QueryEntry {
                         ? { coverage: this.spec.coverage }
                         : {}),
                 });
+                const availability = this.store.availabilitySnapshot();
+                if (availability.state === 'blocked') {
+                    this.#publish({
+                        ...this.#state,
+                        phase: 'blocked',
+                        availability,
+                        isRefreshing: false,
+                    });
+                    break;
+                }
                 if (snapshot.revision < this.#desiredRevision) {
                     this.#requested = true;
                     continue;
                 }
-                const rows = reconcileRows(this.#state.rows, snapshot.rows, this.spec.rowKey);
+                const mappedRows = this.spec.mapRow === undefined
+                    ? snapshot.rows
+                    : snapshot.rows.map(this.spec.mapRow);
+                const rows = reconcileRows(this.#state.rows, mappedRows, this.spec.rowKey);
                 const phase = snapshot.coverage.complete
                     ? 'ready'
                     : rows.length > 0
@@ -277,6 +339,7 @@ class QueryEntry {
                     revision: snapshot.revision,
                     error: undefined,
                     isRefreshing: false,
+                    availability,
                 });
             } while (this.#requested && this.#subscribers > 0);
         }
@@ -287,6 +350,7 @@ class QueryEntry {
                 phase: this.#state.revision === undefined ? 'error' : this.#state.phase,
                 error: wrapped,
                 isRefreshing: false,
+                availability: this.store.availabilitySnapshot(),
             });
         }
         finally {
@@ -383,21 +447,33 @@ export class ReactiveClientStore {
     #windows = new Map();
     #windowClaims = new Map();
     #offChange;
+    #offLeadership;
     status;
     conflicts;
     outcomes;
     constructor(client) {
         this.client = client;
-        const status = new ValueEntry({ status: undefined, error: undefined, isLoading: true }, async () => {
+        const status = new ValueEntry({
+            status: undefined,
+            leadership: client.leadershipSnapshot?.(),
+            error: undefined,
+            isLoading: true,
+        }, async () => {
             try {
                 return {
                     status: await client.statusSnapshot(),
+                    leadership: client.leadershipSnapshot?.(),
                     error: undefined,
                     isLoading: false,
                 };
             }
             catch (error) {
-                return { status: undefined, error: errorOf(error), isLoading: false };
+                return {
+                    status: undefined,
+                    leadership: client.leadershipSnapshot?.(),
+                    error: errorOf(error),
+                    isLoading: false,
+                };
             }
         });
         const conflicts = new ValueEntry({ conflicts: [], rejections: [], error: undefined, isLoading: true }, async () => {
@@ -453,6 +529,7 @@ export class ReactiveClientStore {
             baseKey: windowBaseKey(item.base),
             units: [...new Set(item.units)].sort(),
         }));
+        const mapRowId = reactiveFunctionId(spec.mapRow);
         const key = canonicalValue({
             id: spec.id,
             sql: spec.sql,
@@ -460,6 +537,7 @@ export class ReactiveClientStore {
             dependencies,
             coverage,
             claimCoverage: spec.claimCoverage !== false,
+            ...(mapRowId === undefined ? {} : { mapRow: mapRowId }),
         });
         let entry = this.#queries.get(key);
         if (entry === undefined) {
@@ -468,6 +546,20 @@ export class ReactiveClientStore {
         }
         return entry;
     }
+    availabilitySnapshot() {
+        const snapshot = this.status.getSnapshot();
+        if (snapshot.status === undefined) {
+            return snapshot.leadership?.state === 'blocked'
+                ? {
+                    state: 'blocked',
+                    reason: 'leader-unreachable',
+                    currentSchemaVersion: this.client.currentSchemaVersion ?? 0,
+                    retryable: true,
+                }
+                : { state: 'ready' };
+        }
+        return classifySyncAvailability(snapshot.status, snapshot.leadership);
+    }
     /** Retain a composable window working set outside React. The returned
      * handle exposes registration completion and releases only this owner. */
     retainWindow(base, units) {
@@ -571,6 +663,7 @@ export class ReactiveClientStore {
             if (batch.status !== undefined) {
                 this.status.set({
                     status: batch.status,
+                    leadership: this.client.leadershipSnapshot?.(),
                     error: undefined,
                     isLoading: false,
                 });
@@ -581,10 +674,19 @@ export class ReactiveClientStore {
             if (batch.outcomesChanged)
                 this.outcomes.refresh();
         });
+        this.#offLeadership = this.client.onLeadershipChange?.((leadership) => {
+            const previous = this.status.getSnapshot();
+            this.status.set({
+                ...previous,
+                leadership,
+            });
+        });
     }
     dispose() {
         this.#offChange?.();
         this.#offChange = undefined;
+        this.#offLeadership?.();
+        this.#offLeadership = undefined;
         for (const group of this.#windowClaims.values()) {
             void Promise.resolve(this.client.setWindow(group.base, []));
         }

package/dist/worker-host.d.ts

@@ -29,7 +29,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 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';
@@ -37,6 +37,25 @@ 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';
 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
@@ -57,6 +76,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 +92,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 +130,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,6 +168,7 @@ 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>;
     unsubscribe(id: string): Promise<void>;
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;

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'));
@@ -407,14 +467,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 +490,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 +540,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 +554,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 +584,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 +622,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 +642,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
@@ -591,3 +667,27 @@ async function bootFollower(config, lockName, lock, parts) {
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.13",
+  "version": "0.15.14",
   "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.14"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.13",
+    "@syncular/server": "0.15.14",
     "@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' };
+}