@syncular/client 0.15.13 → 0.15.15

package/README.md

@@ -73,7 +73,9 @@ const handle = await createSyncClientHandle({
   schema, database: { mode: 'persistent', name: 'app' }, endpoints,
   onRoleChange: (role) => console.log('now', role), // 'follower' → 'leader'
 });
-// handle.role is 'leader' or 'follower'; the API is identical either way.
+// Compatibility: handle.role is 'leader' or 'follower'.
+// Detailed state: handle.leadership / handle.leadershipSnapshot().
+handle.onLeadershipChange((state) => renderConnectionState(state));
 ```
 
 **Topology.** The tab that wins the Web Locks election is the **leader**:
@@ -105,6 +107,15 @@ flushed to the new leader on its announce; past the deadline they fail
 loudly with `client.follower_timeout` (never a silent hang), and an
 overflowing queue rejects rather than growing unbounded.
 
+Leader announcements continue as heartbeats while followers are attached. If
+a tab can acquire neither a response nor a new lock grant before the configured
+`followerCallTimeoutMs`, `handle.leadership` becomes
+`{ state: 'blocked', reason: 'leader-unreachable', code:
+'client.follower_timeout', retryable: true }`. Calls then reject immediately.
+A later announcement rebinds the same handle; a granted Web Lock promotes it.
+An unreachable `BroadcastChannel` is never treated as evidence that the lock
+owner is stale, so it never authorizes a second worker or database owner.
+
 **Presence semantics — one device, one peer.** All tabs share the leader's
 single connection, so a device is exactly ONE presence peer collectively:
 identity is `(actorId, leaderClientId)`. A follower's `setPresence`
@@ -112,8 +123,61 @@ forwards to the leader's single publisher; there is no per-tab presence
 peer. This is the honest model — the wire only ever sees one connection per
 device.
 
+The default is a **shared replica**: same-origin tabs must use the same
+persistent database name, lock name, and derived channel name. For an embed,
+preview, or history entry that is intentionally independent, derive the whole
+ownership tuple from one stable identity:
+
+```ts
+const preview = await createSyncClientHandle({
+  worker,
+  schema,
+  database: { mode: 'persistent', name: 'medical' },
+  endpoints,
+  replica: { mode: 'isolated', id: 'preview-42' },
+});
+```
+
+This derives a distinct database name and pool directory, Web Lock name, and
+`BroadcastChannel` name together. `isolatedReplicaNames()` exposes the same
+deterministic tuple for diagnostics and host integration. Replica IDs are
+stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
+
+During Vite development, retain the React client resource only while its
+captured generated schema version matches. The
+[schema-aware Vite guide](https://syncular.dev/guide-vite/) uses
+`retainViteSyncClientResource` to close the old worker before constructing a
+schema-bump replacement; hot-reloading query code alone does not migrate the
+worker-owned database.
+
 Set `multiTab: false` to opt out. A losing tab then becomes an
-`isLeader === false` handle whose calls reject with `client.not_leader`.
+`isLeader === false` handle whose calls reject with `client.not_leader`. This
+does not solve a coordination-partition mismatch by itself: an independent
+instance must also use an isolated database and lock identity. Changing only
+the channel, lock, or database name is unsafe or ineffective.
+
+## React availability guard
+
+The worker handle's schema and leadership snapshots feed the same public React
+boundary as native clients. Guard the application once instead of parsing
+errors or inspecting generated schema modules:
+
+```tsx
+<SyncProvider
+  client={clientResource}
+  renderBoundary={(state, actions) => (
+    <SyncBlockedScreen state={state} onRetry={actions.retry} />
+  )}
+>
+  <App />
+</SyncProvider>
+```
+
+The state is a discriminated union covering startup, migration,
+`client-upgrade-required`, `server-behind`, `incompatible-schema`, and
+`leader-unreachable`. Recovery changes the same handle/provider back to its
+children; a blocked live query has `phase === 'blocked'`, never an indefinite
+loading state.
 
 ## Durable commit outcomes
 
@@ -168,6 +232,28 @@ subscription that could download the protected rows again. This method does
 not authenticate a directive, revoke server authority, delete app-owned files,
 or remove a key from the OS secure store.
 
+For a race-free bootstrap, construct the client/worker handle with
+`securityPreflight: true`. Before activation, protected reads, writes,
+subscriptions, sync/realtime, blobs, and the automatic host loop fail with
+`client.security_preflight_required`; status, local revision, lifecycle, and
+the exact local purge remain available.
+
+```ts
+const client = await createSyncClientHandle({
+  ...config,
+  securityPreflight: true,
+});
+
+await client.purgeLocalData(directive.plan);
+await client.activateSecurity({ encryption: acceptedKeyring });
+```
+
+Use `beginSecurityPreflight()` before a live key rotation/revocation. It gates
+new calls immediately, disconnects realtime, waits for in-flight core/blob work,
+and releases the old keyring before resolving. In multi-tab mode the gate
+belongs to the single shared leader replica. Direct clients expose the same
+lifecycle with an `EncryptionConfig`; Worker handles use the portable keyring.
+
 Within one local SQLite transaction the engine deletes exactly the matching
 synced rows, lets generated FTS triggers remove their projections, drops every
 whole pending commit with a matching operation, restores/replays unrelated

package/dist/availability.d.ts

@@ -0,0 +1,17 @@
+import type { SyncStatusSnapshot } from './invalidation.js';
+import type { LeadershipState } from './multi-tab.js';
+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 declare function classifySyncAvailability(status: SyncStatusSnapshot, leadership?: LeadershipState): SyncAvailability;

package/dist/availability.js

@@ -0,0 +1,48 @@
+/** Classify schema and browser-ownership state without parsing diagnostics. */
+export function classifySyncAvailability(status, leadership) {
+    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' };
+}

package/dist/client.d.ts

@@ -147,6 +147,25 @@ export interface SyncClientConfig {
      * `client.decrypt_failed`, never silent plaintext).
      */
     readonly encryption?: EncryptionConfig;
+    /**
+     * Open the local replica in the fail-closed security preflight state.
+     *
+     * Preflight opens/migrates the database but suppresses every protected read,
+     * mutation, subscription, transport, realtime, presence, and blob operation.
+     * Only lifecycle/status inspection and `purgeLocalData` remain available.
+     * Install the post-authentication keyring and release the gate with
+     * `activateSecurity`. This is mutually exclusive with `encryption`: secure
+     * hosts must not materialize key bytes before their preflight has passed.
+     */
+    readonly securityPreflight?: boolean;
+}
+/** The fail-closed local-replica security lifecycle shared by every host. */
+export type SecurityLifecycle = 'preflight' | 'active';
+/** Stable client-local error while protected operations are preflight-gated. */
+export declare const SECURITY_PREFLIGHT_REQUIRED_CODE = "client.security_preflight_required";
+/** Key material installed atomically when a direct client becomes active. */
+export interface SecurityActivation {
+    readonly encryption?: EncryptionConfig;
 }
 /** §8.6 a peer's ephemeral presence document on a scope key. */
 export interface PresencePeer {
@@ -216,6 +235,20 @@ export declare class SyncClient {
     /** Acquire leadership, create local tables, resolve the clientId. */
     start(): Promise<void>;
     close(): Promise<void>;
+    /** Current fail-closed local-replica security state. */
+    get securityLifecycle(): SecurityLifecycle;
+    /**
+     * Block new protected operations immediately, then wait for every already
+     * serialized database/network operation to settle before releasing key
+     * references. Hosts await this barrier before applying a quarantine purge.
+     */
+    beginSecurityPreflight(): Promise<void>;
+    /**
+     * Atomically install the post-authentication keyring and release the gate.
+     * Persisted subscriptions/outbox work produces one exact startup intent only
+     * after activation, never while the local quarantine decision is pending.
+     */
+    activateSecurity(options?: SecurityActivation): Promise<void>;
     get clientId(): string;
     /** The underlying database — raw SQL is the local query API (B3). */
     get database(): ClientDatabase;

package/dist/client.js

@@ -21,6 +21,8 @@ import { assertReadOnlyQuery } from './query-guard.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
+/** Stable client-local error while protected operations are preflight-gated. */
+export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
 /**
  * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
  * registered and not pending. A unit with zero server rows still becomes
@@ -72,6 +74,7 @@ export class SyncClient {
     #schema;
     /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
     #encryption;
+    #securityLifecycle;
     #now;
     #outcomeRetentionMaxEntries;
     #started = false;
@@ -124,11 +127,21 @@ export class SyncClient {
      * sections, when the seam is quiescent.
      */
     #opChain = Promise.resolve();
+    /** Async protected operations outside the SQLite serialization chain
+     * (blob I/O and realtime connect). Security preflight waits for this set to
+     * drain after synchronously closing the gate. */
+    #protectedAsync = new Set();
+    #preflightBarrier;
     constructor(config) {
+        if (config.securityPreflight === true && config.encryption !== undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
+        }
         this.#config = config;
         this.#db = config.database;
         this.#schema = compileClientSchema(config.schema);
         this.#encryption = config.encryption;
+        this.#securityLifecycle =
+            config.securityPreflight === true ? 'preflight' : 'active';
         this.#now = config.now ?? Date.now;
         const outcomeRetentionMaxEntries = config.limits?.outcomeRetentionMaxEntries ?? 1_000;
         if (!Number.isSafeInteger(outcomeRetentionMaxEntries) ||
@@ -192,7 +205,7 @@ export class SyncClient {
         const startupWork = this.#schemaFloor === undefined &&
             (listOutbox(this.#db).length > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
-        if (startupWork) {
+        if (startupWork && this.#securityLifecycle === 'active') {
             this.#needsPull = true;
             this.#config.onSyncNeeded?.('startup');
             this.#config.onSyncIntent?.({ kind: 'interactive' });
@@ -294,12 +307,66 @@ export class SyncClient {
         this.#lease = undefined;
         this.#started = false;
     }
+    /** Current fail-closed local-replica security state. */
+    get securityLifecycle() {
+        return this.#securityLifecycle;
+    }
+    /**
+     * Block new protected operations immediately, then wait for every already
+     * serialized database/network operation to settle before releasing key
+     * references. Hosts await this barrier before applying a quarantine purge.
+     */
+    beginSecurityPreflight() {
+        this.#requireStarted();
+        if (this.#preflightBarrier !== undefined)
+            return this.#preflightBarrier;
+        this.#securityLifecycle = 'preflight';
+        this.disconnectRealtime();
+        const barrier = (async () => {
+            await Promise.allSettled([this.#opChain, ...this.#protectedAsync]);
+            this.disconnectRealtime();
+            this.#encryption = undefined;
+            this.#syncOutstanding = false;
+        })();
+        this.#preflightBarrier = barrier;
+        void barrier.then(() => {
+            if (this.#preflightBarrier === barrier)
+                this.#preflightBarrier = undefined;
+        }, () => {
+            if (this.#preflightBarrier === barrier)
+                this.#preflightBarrier = undefined;
+        });
+        return barrier;
+    }
+    /**
+     * Atomically install the post-authentication keyring and release the gate.
+     * Persisted subscriptions/outbox work produces one exact startup intent only
+     * after activation, never while the local quarantine decision is pending.
+     */
+    async activateSecurity(options = {}) {
+        this.#requireStarted();
+        if (this.#securityLifecycle === 'active') {
+            throw new ClientSyncError('sync.invalid_request', 'activateSecurity requires the client to be in security preflight');
+        }
+        await (this.#preflightBarrier ?? this.#opChain);
+        this.#encryption = options.encryption;
+        this.#securityLifecycle = 'active';
+        const startupWork = this.#schemaFloor === undefined &&
+            (listOutbox(this.#db).length > 0 ||
+                loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
+        if (startupWork) {
+            this.#setSyncNeeded(true);
+            this.#config.onSyncNeeded?.('startup');
+            this.#config.onSyncIntent?.({ kind: 'interactive' });
+        }
+    }
     // -- accessors ------------------------------------------------------------
     get clientId() {
         return this.#clientId;
     }
     /** The underlying database — raw SQL is the local query API (B3). */
     get database() {
+        this.#requireActive();
         return this.#db;
     }
     /**
@@ -311,6 +378,7 @@ export class SyncClient {
      * internals read `this.#db` directly and skip this method by design.
      */
     query(sql, params) {
+        this.#requireActive();
         assertReadOnlyQuery(sql);
         return stripSyncColumns(this.#db.query(sql, params));
     }
@@ -325,7 +393,7 @@ export class SyncClient {
      * `windowState()` across separate worker/IPC calls.
      */
     querySnapshot(spec) {
-        this.#requireStarted();
+        this.#requireActive();
         assertReadOnlyQuery(spec.sql);
         return this.#db.transaction(() => {
             const revision = getLocalRevision(this.#db);
@@ -391,6 +459,7 @@ export class SyncClient {
     }
     #statusSnapshot() {
         return {
+            currentSchemaVersion: this.#config.schema.version,
             outbox: listOutbox(this.#db).length,
             upgrading: this.#upgrading,
             leaseState: this.#leaseState,
@@ -455,6 +524,13 @@ export class SyncClient {
         this.#opChain = next.then(() => undefined, () => undefined);
         return next;
     }
+    #runProtectedAsync(fn) {
+        this.#requireActive();
+        const task = Promise.resolve().then(fn);
+        this.#protectedAsync.add(task);
+        void task.then(() => this.#protectedAsync.delete(task), () => this.#protectedAsync.delete(task));
+        return task;
+    }
     // -- blobs (§5.9) ---------------------------------------------------------
     /**
      * Stage a blob for attachment (§5.9.7): hash the bytes into the content
@@ -463,7 +539,10 @@ export class SyncClient {
      * a `blob_ref` column of a mutation. The referencing row MUST be written
      * (via `mutate`) after this call so upload-before-push holds (§5.9.3).
      */
-    async uploadBlob(bytes, options) {
+    uploadBlob(bytes, options) {
+        return this.#runProtectedAsync(() => this.#uploadBlob(bytes, options));
+    }
+    async #uploadBlob(bytes, options) {
         if (this.#config.blobs === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
         }
@@ -495,7 +574,10 @@ export class SyncClient {
      * transport (§5.9.5), verifies the content address, caches, and returns.
      * Accepts a raw `blob_ref` column string or a bare `blobId`.
      */
-    async fetchBlob(blobIdOrRef) {
+    fetchBlob(blobIdOrRef) {
+        return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
+    }
+    async #fetchBlob(blobIdOrRef) {
         const blobId = blobIdOrRef.startsWith('sha256:')
             ? blobIdOrRef
             : parseBlobRef(blobIdOrRef).blobId;
@@ -549,7 +631,10 @@ export class SyncClient {
         enforceBlobCacheCap(this.#db, cap);
     }
     /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
-    async flushBlobUploads() {
+    flushBlobUploads() {
+        return this.#runProtectedAsync(() => this.#flushBlobUploads());
+    }
+    async #flushBlobUploads() {
         const transport = this.#config.blobs;
         if (transport === undefined || !this.#hasBlobs)
             return;
@@ -597,19 +682,21 @@ export class SyncClient {
         await transport.upload(blobId, bytes, mediaType);
     }
     get conflicts() {
+        this.#requireActive();
         return this.#conflicts;
     }
     get rejections() {
+        this.#requireActive();
         return this.#rejections;
     }
     /** One durable final outcome by the originating client commit id. */
     commitOutcome(clientCommitId) {
-        this.#requireStarted();
+        this.#requireActive();
         return readCommitOutcome(this.#db, clientCommitId);
     }
     /** Newest-first durable outcome journal. */
     commitOutcomes(query = {}) {
-        this.#requireStarted();
+        this.#requireActive();
         return listCommitOutcomes(this.#db, query);
     }
     /**
@@ -619,7 +706,7 @@ export class SyncClient {
      * dismissed. The transition is one-way and survives restart.
      */
     resolveCommitOutcome(input) {
-        this.#requireStarted();
+        this.#requireActive();
         const current = readCommitOutcome(this.#db, input.clientCommitId);
         if (current === undefined) {
             throw new ClientSyncError('sync.outcome_not_found', `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`);
@@ -703,11 +790,13 @@ export class SyncClient {
      * Ephemeral — reflects only what the socket has delivered.
      */
     presence(scopeKey) {
+        this.#requireActive();
         const peers = this.#presence.get(scopeKey);
         return peers === undefined ? [] : [...peers.values()];
     }
     /** Every scope key this client currently has presence state for. */
     presenceKeys() {
+        this.#requireActive();
         return [...this.#presence.keys()];
     }
     /**
@@ -730,7 +819,7 @@ export class SyncClient {
      * by the server with `presence.forbidden`.
      */
     setPresence(scopeKey, doc) {
-        this.#requireStarted();
+        this.#requireActive();
         const socket = this.#socket;
         if (socket === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'setPresence requires a connected realtime socket (§8.6)');
@@ -756,20 +845,20 @@ export class SyncClient {
             (urlCapable ? ACCEPT_SIGNED_URLS : 0));
     }
     subscriptions() {
-        this.#requireStarted();
+        this.#requireActive();
         return loadSubscriptions(this.#db);
     }
     subscription(id) {
-        this.#requireStarted();
+        this.#requireActive();
         return getSubscription(this.#db, id);
     }
     pendingCommits() {
-        this.#requireStarted();
+        this.#requireActive();
         return listOutbox(this.#db);
     }
     // -- subscriptions ----------------------------------------------------------
     subscribe(input) {
-        this.#requireStarted();
+        this.#requireActive();
         if (!this.#schema.tables.has(input.table)) {
             throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
         }
@@ -793,7 +882,7 @@ export class SyncClient {
         });
     }
     unsubscribe(id) {
-        this.#requireStarted();
+        this.#requireActive();
         deleteSubscription(this.#db, id);
     }
     // -- windowed subscriptions (§4.8) ------------------------------------------
@@ -815,7 +904,7 @@ export class SyncClient {
     }
     /** Exact core command result consumed by automatic host loops (§7.5). */
     async setWindowCommand(base, units) {
-        this.#requireStarted();
+        this.#requireActive();
         const table = this.#table(base.table);
         if (!table.scopeColumnByVariable.has(base.variable)) {
             throw new ClientSyncError('sync.invalid_request', `setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
@@ -878,7 +967,7 @@ export class SyncClient {
      * advances past -1 with no resume token held).
      */
     windowState(base) {
-        this.#requireStarted();
+        this.#requireActive();
         const baseKey = windowBaseKey(base);
         const live = loadWindowUnits(this.#db, baseKey);
         const pending = [];
@@ -977,7 +1066,7 @@ export class SyncClient {
         return this.#recordMutations(mutations);
     }
     #recordMutations(mutations, changedFieldsByIndex = []) {
-        this.#requireStarted();
+        this.#requireActive();
         const clientCommitId = crypto.randomUUID();
         const operations = mutations.map((mutation, index) => {
             const table = this.#table(mutation.table);
@@ -1038,7 +1127,7 @@ export class SyncClient {
      * an error — there is no base to merge into.
      */
     patch(table, rowId, partial, options) {
-        this.#requireStarted();
+        this.#requireActive();
         const compiled = this.#table(table);
         const pkColumn = compiled.columns[compiled.primaryKeyIndex];
         const rows = this.#db.query(`SELECT * FROM ${quoteIdent(compiled.name)} WHERE ${quoteIdent(pkColumn.name)} = ?`, [rowId]);
@@ -1309,7 +1398,7 @@ export class SyncClient {
      * `setWindow` at an await point.
      */
     sync() {
-        this.#requireStarted();
+        this.#requireActive();
         if (this.#syncOutstanding) {
             return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
         }
@@ -1488,13 +1577,15 @@ export class SyncClient {
         round.reject(new ClientSyncError('sync.transport_failed', reason, true));
     }
     // -- realtime (§8 client side) ----------------------------------------------
-    async connectRealtime() {
-        this.#requireStarted();
+    connectRealtime() {
+        return this.#runProtectedAsync(() => this.#connectRealtime());
+    }
+    async #connectRealtime() {
         const connector = this.#config.realtime;
         if (connector === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
         }
-        this.#socket = await connector({
+        const socket = await connector({
             onText: (text) => this.#handleRealtimeText(text),
             onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
             onClose: () => {
@@ -1503,6 +1594,11 @@ export class SyncClient {
                 this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
             },
         });
+        if (this.#securityLifecycle === 'preflight') {
+            socket.close();
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
+        }
+        this.#socket = socket;
     }
     disconnectRealtime() {
         this.#socket?.close();
@@ -2409,4 +2505,10 @@ export class SyncClient {
             throw new ClientSyncError('sync.invalid_request', 'SyncClient.start() has not completed');
         }
     }
+    #requireActive() {
+        this.#requireStarted();
+        if (this.#securityLifecycle === 'preflight') {
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data');
+        }
+    }
 }

package/dist/index.d.ts

@@ -9,6 +9,7 @@
  * import no SQLite.
  */
 export * from './apply.js';
+export * from './availability.js';
 export * from './blob.js';
 export * from './client.js';
 export * from './content-type.js';

package/dist/index.js

@@ -9,6 +9,7 @@
  * import no SQLite.
  */
 export * from './apply.js';
+export * from './availability.js';
 export * from './blob.js';
 export * from './client.js';
 export * from './content-type.js';

package/dist/invalidation.d.ts

@@ -20,6 +20,7 @@ export interface WindowChange {
     readonly units: ReadonlySet<string>;
 }
 export interface SyncStatusSnapshot {
+    readonly currentSchemaVersion: number;
     readonly outbox: number;
     readonly upgrading: boolean;
     readonly leaseState: LeaseState | undefined;