@syncular/client 0.15.13 → 0.15.15

package/dist/multi-tab.d.ts

@@ -5,6 +5,22 @@ export declare const FOLLOWER_TIMEOUT_CODE = "client.follower_timeout";
 export declare const DEFAULT_FOLLOWER_CALL_TIMEOUT_MS = 10000;
 /** Max follower calls queued across a handover before we fail loudly. */
 export declare const DEFAULT_FOLLOWER_QUEUE_LIMIT = 256;
+export type LeadershipState = {
+    readonly state: 'leader';
+    readonly clientId: string;
+} | {
+    readonly state: 'follower';
+    readonly leaderClientId: string;
+    readonly epoch: number;
+} | {
+    readonly state: 'waiting';
+    readonly reason: 'handover' | 'leader-announcement';
+} | {
+    readonly state: 'blocked';
+    readonly reason: 'leader-unreachable';
+    readonly code: typeof FOLLOWER_TIMEOUT_CODE;
+    readonly retryable: true;
+};
 interface HelloMessage {
     readonly t: 'hello';
     readonly fromId: string;
@@ -16,6 +32,10 @@ interface ByeMessage {
     readonly t: 'bye';
     readonly fromId: string;
 }
+interface BoundMessage {
+    readonly t: 'bound';
+    readonly fromId: string;
+}
 interface ReqMessage {
     readonly t: 'req';
     readonly epoch: number;
@@ -46,7 +66,7 @@ interface EventMessage {
     readonly epoch: number;
     readonly event: SyncWorkerEvent;
 }
-export type MultiTabMessage = HelloMessage | ByeMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
+export type MultiTabMessage = HelloMessage | ByeMessage | BoundMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
 /**
  * The tiny cross-tab channel surface we depend on — the DOM `BroadcastChannel`
  * satisfies it. Injectable so bun tests can pair two instances by name.
@@ -80,6 +100,7 @@ export declare class LeaderBridge {
         epoch: number;
         clientId: string;
         invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
+        heartbeatMs?: number;
     });
     /** Re-announce leadership (on promotion and on a follower `hello`). */
     announce(): void;
@@ -101,12 +122,14 @@ export declare class FollowerLink {
         fromId: string;
         onEvent: (event: SyncWorkerEvent) => void;
         onLeaderChange: (clientId: string) => void;
+        onStateChange?: (state: LeadershipState) => void;
         callTimeoutMs?: number;
         queueLimit?: number;
     });
     get epoch(): number;
     get maxEpochSeen(): number;
     get leaderClientId(): string;
+    get leadershipState(): LeadershipState;
     /** Whether a leader is currently bound (an announce has been heard). */
     get bound(): boolean;
     /**

package/dist/multi-tab.js

@@ -73,12 +73,18 @@ export class LeaderBridge {
     #clientId;
     #invoke;
     #onMessage;
+    #heartbeatMs;
+    #followers = new Set();
+    #heartbeat;
     #closed = false;
     constructor(options) {
         this.#channel = options.channel;
         this.#epoch = options.epoch;
         this.#clientId = options.clientId;
         this.#invoke = options.invoke;
+        this.#heartbeatMs =
+            options.heartbeatMs ??
+                Math.max(50, Math.floor(DEFAULT_FOLLOWER_CALL_TIMEOUT_MS / 3));
         this.#onMessage = (event) => this.#handle(event.data);
         this.#channel.addEventListener('message', this.#onMessage);
         this.announce();
@@ -104,9 +110,22 @@ export class LeaderBridge {
             return;
         if (message.t === 'hello') {
             // A follower joined (or is contesting) — tell it who leads.
+            this.#trackFollower(message.fromId);
             this.announce();
             return;
         }
+        if (message.t === 'bound') {
+            this.#trackFollower(message.fromId);
+            return;
+        }
+        if (message.t === 'bye') {
+            this.#followers.delete(message.fromId);
+            if (this.#followers.size === 0 && this.#heartbeat !== undefined) {
+                clearInterval(this.#heartbeat);
+                this.#heartbeat = undefined;
+            }
+            return;
+        }
         if (message.t !== 'req')
             return;
         // Ignore requests stamped for a different (dead/older) leader; that
@@ -143,11 +162,21 @@ export class LeaderBridge {
             });
         });
     }
+    #trackFollower(fromId) {
+        this.#followers.add(fromId);
+        if (this.#heartbeat !== undefined)
+            return;
+        this.#heartbeat = setInterval(() => this.announce(), this.#heartbeatMs);
+    }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
+        if (this.#heartbeat !== undefined)
+            clearInterval(this.#heartbeat);
+        this.#heartbeat = undefined;
         this.#channel.removeEventListener('message', this.#onMessage);
+        this.#channel.close();
     }
 }
 /**
@@ -162,6 +191,7 @@ export class FollowerLink {
     #fromId;
     #onEvent;
     #onLeaderChange;
+    #onStateChange;
     #callTimeoutMs;
     #queueLimit;
     #onMessage;
@@ -174,6 +204,12 @@ export class FollowerLink {
     #inFlight = new Map();
     #queue = [];
     #closed = false;
+    #state = {
+        state: 'waiting',
+        reason: 'leader-announcement',
+    };
+    #waitingTimer;
+    #blockedTimer;
     /** Resolvers waiting for the first `announce` to bind a leader. */
     #bindWaiters = [];
     constructor(options) {
@@ -181,6 +217,7 @@ export class FollowerLink {
         this.#fromId = options.fromId;
         this.#onEvent = options.onEvent;
         this.#onLeaderChange = options.onLeaderChange;
+        this.#onStateChange = options.onStateChange ?? (() => { });
         this.#callTimeoutMs =
             options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
         this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
@@ -188,6 +225,7 @@ export class FollowerLink {
         this.#channel.addEventListener('message', this.#onMessage);
         // Ask the current leader to announce itself.
         this.#channel.postMessage({ t: 'hello', fromId: this.#fromId });
+        this.#armUnboundDeadline();
     }
     get epoch() {
         return this.#epoch;
@@ -198,6 +236,9 @@ export class FollowerLink {
     get leaderClientId() {
         return this.#leaderClientId;
     }
+    get leadershipState() {
+        return this.#state;
+    }
     /** Whether a leader is currently bound (an announce has been heard). */
     get bound() {
         return this.#epoch >= 0;
@@ -221,7 +262,8 @@ export class FollowerLink {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.#dropBindWaiter(settle);
-                reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader announced within the follower bind timeout'));
+                this.#setBlocked();
+                reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader announced within the follower bind timeout', true));
             }, timeoutMs);
             const settle = () => {
                 clearTimeout(timer);
@@ -248,6 +290,9 @@ export class FollowerLink {
         if (this.#closed) {
             return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the follower link is closed'));
         }
+        if (this.#state.state === 'blocked') {
+            return Promise.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the follower cannot reach the tab that owns the database', true));
+        }
         return new Promise((resolve, reject) => {
             const queued = {
                 method,
@@ -259,12 +304,14 @@ export class FollowerLink {
             if (this.#epoch < 0) {
                 // No leader bound yet — queue with a deadline so we never hang.
                 if (this.#queue.length >= this.#queueLimit) {
-                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'follower call queue overflow while awaiting a leader'));
+                    this.#setBlocked();
+                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'follower call queue overflow while awaiting a leader', true));
                     return;
                 }
                 queued.timer = setTimeout(() => {
                     this.#dropQueued(queued);
-                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout'));
+                    this.#setBlocked();
+                    reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout', true));
                 }, this.#callTimeoutMs);
                 this.#queue.push(queued);
                 return;
@@ -279,7 +326,8 @@ export class FollowerLink {
             reject: queued.reject,
             timer: setTimeout(() => {
                 this.#inFlight.delete(reqId);
-                queued.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the leader did not answer within the follower call timeout'));
+                this.#setBlocked();
+                queued.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the leader did not answer within the follower call timeout', true));
             }, this.#callTimeoutMs),
         };
         this.#inFlight.set(reqId, inflight);
@@ -313,6 +361,15 @@ export class FollowerLink {
             this.#leaderClientId = message.clientId;
             if (changed)
                 this.#onLeaderChange(message.clientId);
+            this.#setState({
+                state: 'follower',
+                leaderClientId: message.clientId,
+                epoch: message.epoch,
+            });
+            this.#armBoundDeadline();
+            if (changed) {
+                this.#channel.postMessage({ t: 'bound', fromId: this.#fromId });
+            }
             this.#resolveBindWaiters();
             this.#flushQueue();
             return;
@@ -366,6 +423,8 @@ export class FollowerLink {
             return;
         this.#epoch = -1;
         this.#leaderClientId = '';
+        this.#setState({ state: 'waiting', reason: 'handover' });
+        this.#armUnboundDeadline();
         this.#channel.postMessage({
             t: 'hello',
             fromId: this.#fromId,
@@ -376,6 +435,7 @@ export class FollowerLink {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#clearReachabilityTimers();
         this.#channel.removeEventListener('message', this.#onMessage);
         this.#channel.postMessage({ t: 'bye', fromId: this.#fromId });
         const closedError = new ClientSyncError(WORKER_FAILED_CODE, 'the follower link was closed');
@@ -396,4 +456,53 @@ export class FollowerLink {
         this.#resolveBindWaiters();
         this.#channel.close();
     }
+    #setState(state) {
+        const previous = this.#state;
+        if (previous.state === state.state &&
+            (state.state === 'blocked' ||
+                (state.state === 'waiting' &&
+                    previous.state === 'waiting' &&
+                    previous.reason === state.reason) ||
+                (state.state === 'follower' &&
+                    previous.state === 'follower' &&
+                    previous.epoch === state.epoch &&
+                    previous.leaderClientId === state.leaderClientId))) {
+            return;
+        }
+        this.#state = state;
+        try {
+            this.#onStateChange(state);
+        }
+        catch {
+            // A status listener must never break cross-tab coordination.
+        }
+    }
+    #setBlocked() {
+        this.#clearReachabilityTimers();
+        this.#setState({
+            state: 'blocked',
+            reason: 'leader-unreachable',
+            code: FOLLOWER_TIMEOUT_CODE,
+            retryable: true,
+        });
+    }
+    #armUnboundDeadline() {
+        this.#clearReachabilityTimers();
+        this.#blockedTimer = setTimeout(() => this.#setBlocked(), this.#callTimeoutMs);
+    }
+    #armBoundDeadline() {
+        this.#clearReachabilityTimers();
+        this.#waitingTimer = setTimeout(() => {
+            this.#setState({ state: 'waiting', reason: 'leader-announcement' });
+        }, Math.max(1, Math.floor((this.#callTimeoutMs * 2) / 3)));
+        this.#blockedTimer = setTimeout(() => this.#setBlocked(), this.#callTimeoutMs);
+    }
+    #clearReachabilityTimers() {
+        if (this.#waitingTimer !== undefined)
+            clearTimeout(this.#waitingTimer);
+        if (this.#blockedTimer !== undefined)
+            clearTimeout(this.#blockedTimer);
+        this.#waitingTimer = undefined;
+        this.#blockedTimer = undefined;
+    }
 }

package/dist/reactive-store.d.ts

@@ -1,6 +1,8 @@
+import { type SyncAvailability } from './availability.js';
 import type { CommitOutcome, QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
 import type { SqlValue } from './database.js';
 import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
+import type { LeadershipState } from './multi-tab.js';
 import { type WindowBase } from './window.js';
 export interface QueryDependency {
     readonly table: string;
@@ -12,21 +14,26 @@ export interface ReactiveQuerySpec<Row> {
     readonly params?: readonly SqlValue[];
     readonly dependencies: readonly QueryDependency[];
     readonly coverage?: readonly WindowCoverage[];
+    readonly mapRow?: (row: Readonly<Record<string, SqlValue>>) => Row;
     readonly rowKey?: (row: Row) => readonly SqlValue[];
     readonly claimCoverage?: boolean;
 }
-export type LiveQueryPhase = 'loading' | 'partial' | 'ready' | 'error';
+export type LiveQueryPhase = 'loading' | 'partial' | 'ready' | 'blocked' | 'error';
 export interface LiveQueryResult<Row> {
     readonly rows: readonly Row[];
     readonly phase: LiveQueryPhase;
     readonly revision: bigint | undefined;
     readonly error: Error | undefined;
     readonly isRefreshing: boolean;
+    readonly availability: SyncAvailability;
 }
 export interface ReactiveQueryClient {
+    readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
     querySnapshot<Row = Record<string, SqlValue>>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
     statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
+    leadershipSnapshot?(): LeadershipState | undefined;
+    onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
     readonly conflicts: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
     readonly rejections: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
     commitOutcomes(): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
@@ -46,6 +53,7 @@ export interface WindowRetention {
 }
 export interface StatusStoreSnapshot {
     readonly status: SyncStatusSnapshot | undefined;
+    readonly leadership: LeadershipState | undefined;
     readonly error: Error | undefined;
     readonly isLoading: boolean;
 }
@@ -70,6 +78,7 @@ export declare class ReactiveClientStore {
     readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
     constructor(client: ReactiveQueryClient);
     query<Row>(spec: ReactiveQuerySpec<Row>): ExternalStoreEntry<LiveQueryResult<Row>>;
+    availabilitySnapshot(): SyncAvailability;
     /** Retain a composable window working set outside React. The returned
      * handle exposes registration completion and releases only this owner. */
     retainWindow(base: WindowBase, units: readonly string[]): WindowRetention;

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-entry.js

@@ -88,8 +88,11 @@ export function startSyncWorker(overrides = {}) {
     let backgroundDue = Number.POSITIVE_INFINITY;
     function runAutoSync() {
         autoSyncScheduled = false;
-        if (closed || client === undefined)
+        if (closed ||
+            client === undefined ||
+            client.securityLifecycle === 'preflight') {
             return;
+        }
         const running = client;
         void serializedSync(() => running.syncUntilIdle())
             .then((summary) => {
@@ -106,7 +109,11 @@ export function startSyncWorker(overrides = {}) {
         });
     }
     function consumeSyncIntent(intent) {
-        if (!autoSync || closed || client === undefined || intent.kind === 'none') {
+        if (!autoSync ||
+            closed ||
+            client === undefined ||
+            client.securityLifecycle === 'preflight' ||
+            intent.kind === 'none') {
             return;
         }
         if (intent.kind === 'background') {
@@ -220,6 +227,9 @@ export function startSyncWorker(overrides = {}) {
             ...(config.encryption !== undefined
                 ? { encryption: encryptionConfigFromKeyring(config.encryption) }
                 : {}),
+            ...(config.securityPreflight !== undefined
+                ? { securityPreflight: config.securityPreflight }
+                : {}),
             onSyncNeeded: (reason) => {
                 post({ t: 'event', event: { kind: 'sync-needed', reason } });
                 consumeSyncIntent({ kind: 'interactive' });
@@ -257,6 +267,22 @@ export function startSyncWorker(overrides = {}) {
         return { clientId: started.clientId };
     }
     const api = {
+        securityLifecycle: () => requireClient().securityLifecycle,
+        beginSecurityPreflight: async () => {
+            if (backgroundTimer !== undefined)
+                clearTimeout(backgroundTimer);
+            backgroundTimer = undefined;
+            backgroundDue = Number.POSITIVE_INFINITY;
+            autoSyncScheduled = false;
+            await requireClient().beginSecurityPreflight();
+        },
+        activateSecurity: async (options = {}) => {
+            await requireClient().activateSecurity({
+                ...(options.encryption !== undefined
+                    ? { encryption: encryptionConfigFromKeyring(options.encryption) }
+                    : {}),
+            });
+        },
         subscribe: (input) => requireClient().subscribe(input),
         unsubscribe: (id) => requireClient().unsubscribe(id),
         setWindow: async (base, units) => {