@syncular/client 0.15.35 → 0.15.37

package/README.md

@@ -54,14 +54,48 @@ The handle exposes the same logical API as `SyncClient` (subscribe /
 mutate / sync / query / conflicts / …), every method a promise. It
 acquires the Web Locks leader lock *before* spawning the worker — one
 core per origin. Wake-ups are handled inside the worker (`autoSync`,
-SPEC §8.4: the sync-needed signal is host-driven and the worker IS the
-host); the main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
+SPEC §8.4); the supported page-level realtime supervisor owns reconnect and
+resume policy. The main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
 events for rendering.
 
 **Ephemeral in-memory mode is EXPLICIT.** `openWasmDatabase()` returns an
 in-memory sqlite-wasm database for tests, demos and SSR. Nothing
 persists, on purpose, and that is the only main-thread mode.
 
+## Supported realtime lifecycle
+
+Register subscriptions, then install the cross-host supervisor:
+
+```ts
+import {
+  browserConnectivitySignal,
+  documentLifecycleSignal,
+  installRealtimeSupervisor,
+} from '@syncular/client';
+
+await handle.subscribe({ id: 'todos', table: 'todos', scopes });
+installRealtimeSupervisor(handle, {
+  connectivity: browserConnectivitySignal(),
+  lifecycle: documentLifecycleSignal(),
+  // Encrypted/locked apps also pass their active/preflight signal.
+  protection,
+});
+```
+
+It owns one connection attempt, retries initial failure and later socket loss
+with bounded exponential jitter, suspends while offline/background/protected,
+runs `syncUntilIdle()` before reporting `connected`, and cancels before
+`close()`. `realtimeSupervisorSnapshot()` and
+`subscribeRealtimeSupervisor()` expose only `phase`, `attempt`, and the bounded
+library delay for UI/diagnostics—never raw transport prose or identities.
+
+The lower-level `connectRealtime()` is idempotent while connected and
+single-flight while connecting; disconnect invalidates an in-flight result so
+it cannot install a stale socket. It remains available for custom host loops.
+HTTP rounds still work with no socket, but do not imply continuous convergence:
+a host trigger must actually run them. See the complete
+[realtime lifecycle guide](https://syncular.dev/concepts-realtime/).
+
 ## Multi-tab followers (TODO 3.2, REVISE B3)
 
 By default, every tab of the same origin shares ONE core:
@@ -312,9 +346,15 @@ const result = await client.rebootstrapLocalData({
 The reset, durable idempotency marker, and optimistic outbox replay are one
 SQLite transaction. An interruption therefore leaves either the old
 projection or the fully reset projection with pending offline work still
-visible. Reusing the same id returns `alreadyApplied: true`. The counts-only
-result reports retained commits and reset subscriptions without exposing ids,
-rows, scopes, or clinical values.
+visible. Reusing the same id returns `alreadyApplied: true` together with the
+original `retainedCommits` and `resetSubscriptions` counts. The core stores
+that counts-only receipt atomically with the reset, so an application crash
+after the SQLite commit but before its own acknowledgement does not turn the
+retry into a misleading zero-impact result. Markers written before Syncular
+0.15.36 cannot reconstruct their historical counts and preserve the former
+zero-count replay behavior. A malformed or unreadable persisted receipt fails
+closed with the sanitized `sync.local_corrupt` client-local code and performs
+no reset. No receipt exposes ids, rows, scopes, or clinical values.
 
 Worker, Tauri, and React Native adapters strictly decode the exact result
 shape before returning it. Missing or additional fields, a non-boolean

package/dist/client.js

@@ -17,6 +17,7 @@ import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFrom
 import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
 import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
+import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
@@ -96,6 +97,8 @@ export class SyncClient {
     #conflicts = [];
     #rejections = [];
     #socket;
+    #realtimeConnectPromise;
+    #realtimeGeneration = 0;
     #pendingRound;
     #needsPull = false;
     #syncing = false;
@@ -314,8 +317,7 @@ export class SyncClient {
     async close() {
         this.#devtoolsUnregister?.();
         this.#devtoolsUnregister = undefined;
-        this.#socket?.close();
-        this.#socket = undefined;
+        this.disconnectRealtime();
         this.#abortPendingRound('client closed mid-round');
         await this.#lease?.release();
         this.#lease = undefined;
@@ -1509,11 +1511,13 @@ export class SyncClient {
         this.#requireActive();
         const rebootstrapId = compileLocalDataRebootstrap(input);
         const metaKey = localDataRebootstrapMetaKey(rebootstrapId);
-        if (getMeta(this.#db, metaKey) !== undefined) {
+        const persistedReceipt = getMeta(this.#db, metaKey);
+        if (persistedReceipt !== undefined) {
+            const receipt = decodeLocalDataRebootstrapReceipt(persistedReceipt);
             return {
                 alreadyApplied: true,
-                retainedCommits: 0,
-                resetSubscriptions: 0,
+                retainedCommits: receipt.retainedCommits,
+                resetSubscriptions: receipt.resetSubscriptions,
             };
         }
         if (this.#schemaFloor !== undefined) {
@@ -1536,7 +1540,10 @@ export class SyncClient {
                 for (const commit of pending) {
                     this.#applyOperationsLocally(commit.operations, batch);
                 }
-                setMeta(this.#db, metaKey, 'v1');
+                setMeta(this.#db, metaKey, encodeLocalDataRebootstrapReceipt({
+                    retainedCommits: pending.length,
+                    resetSubscriptions,
+                }));
             });
         }
         catch (error) {
@@ -1933,31 +1940,59 @@ export class SyncClient {
     }
     // -- realtime (§8 client side) ----------------------------------------------
     connectRealtime() {
-        return this.#runProtectedAsync(() => this.#connectRealtime());
+        this.#requireActive();
+        if (this.#socket !== undefined)
+            return Promise.resolve();
+        if (this.#realtimeConnectPromise !== undefined) {
+            return this.#realtimeConnectPromise;
+        }
+        const generation = this.#realtimeGeneration;
+        const task = this.#runProtectedAsync(() => this.#connectRealtime(generation));
+        this.#realtimeConnectPromise = task;
+        void task.then(() => {
+            if (this.#realtimeConnectPromise === task) {
+                this.#realtimeConnectPromise = undefined;
+            }
+        }, () => {
+            if (this.#realtimeConnectPromise === task) {
+                this.#realtimeConnectPromise = undefined;
+            }
+        });
+        return task;
     }
-    async #connectRealtime() {
+    async #connectRealtime(generation) {
         const connector = this.#config.realtime;
         if (connector === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
         }
+        let openedSocket;
         const socket = await connector({
             onText: (text) => this.#handleRealtimeText(text),
             onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
             onClose: () => {
+                if (openedSocket === undefined || this.#socket !== openedSocket)
+                    return;
                 this.#socket = undefined;
                 this.#presence.clear(); // §8.6.1: presence is per-connection
                 this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
                 this.#emitDiagnostics();
             },
         });
+        openedSocket = socket;
         if (this.#securityLifecycle === 'preflight') {
             socket.close();
             throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
         }
+        if (generation !== this.#realtimeGeneration || !this.#started) {
+            socket.close();
+            throw new ClientSyncError('client.realtime_cancelled', 'realtime connection was cancelled before activation');
+        }
         this.#socket = socket;
         this.#emitDiagnostics();
     }
     disconnectRealtime() {
+        this.#realtimeGeneration += 1;
+        this.#realtimeConnectPromise = undefined;
         this.#socket?.close();
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from './outbox.js';
 export * from './outcomes.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
+export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';

package/dist/index.js

@@ -29,6 +29,7 @@ export * from './outbox.js';
 export * from './outcomes.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
+export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';
 export * from './state.js';

package/dist/local-rebootstrap-receipt.d.ts

@@ -0,0 +1,12 @@
+export interface LocalDataRebootstrapReceipt {
+    readonly retainedCommits: number;
+    readonly resetSubscriptions: number;
+}
+/** Encode only the bounded counts that are safe to replay outside the core. */
+export declare function encodeLocalDataRebootstrapReceipt(receipt: LocalDataRebootstrapReceipt): string;
+/**
+ * Decode a committed receipt without leaking its application-owned key. The
+ * original counts were not retained by pre-0.15.36 `v1` markers, so those
+ * historical repairs keep their former zero-count replay behavior.
+ */
+export declare function decodeLocalDataRebootstrapReceipt(value: string): LocalDataRebootstrapReceipt;

package/dist/local-rebootstrap-receipt.js

@@ -0,0 +1,59 @@
+import { ClientSyncError } from './errors.js';
+const LEGACY_MARKER = 'v1';
+const RECEIPT_VERSION = 2;
+const RECEIPT_KEYS = [
+    'resetSubscriptions',
+    'retainedCommits',
+    'version',
+];
+function invalidReceipt() {
+    throw new ClientSyncError('sync.local_corrupt', 'persisted local rebootstrap receipt is invalid');
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+/** Encode only the bounded counts that are safe to replay outside the core. */
+export function encodeLocalDataRebootstrapReceipt(receipt) {
+    if (!isCount(receipt.retainedCommits) ||
+        !isCount(receipt.resetSubscriptions)) {
+        return invalidReceipt();
+    }
+    return JSON.stringify({
+        version: RECEIPT_VERSION,
+        retainedCommits: receipt.retainedCommits,
+        resetSubscriptions: receipt.resetSubscriptions,
+    });
+}
+/**
+ * Decode a committed receipt without leaking its application-owned key. The
+ * original counts were not retained by pre-0.15.36 `v1` markers, so those
+ * historical repairs keep their former zero-count replay behavior.
+ */
+export function decodeLocalDataRebootstrapReceipt(value) {
+    if (value === LEGACY_MARKER) {
+        return { retainedCommits: 0, resetSubscriptions: 0 };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return invalidReceipt();
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return invalidReceipt();
+    }
+    const source = parsed;
+    const keys = Object.keys(source).sort();
+    if (keys.length !== RECEIPT_KEYS.length ||
+        keys.some((key, index) => key !== RECEIPT_KEYS[index]) ||
+        source.version !== RECEIPT_VERSION ||
+        !isCount(source.retainedCommits) ||
+        !isCount(source.resetSubscriptions)) {
+        return invalidReceipt();
+    }
+    return {
+        retainedCommits: source.retainedCommits,
+        resetSubscriptions: source.resetSubscriptions,
+    };
+}

package/dist/local-rebootstrap.d.ts

@@ -12,7 +12,11 @@ export declare const INVALID_HOST_RESPONSE_CODE = "client.invalid_host_response"
 export interface LocalDataRebootstrapInput {
     readonly rebootstrapId: string;
 }
-/** Privacy-safe acknowledgement; no row or subscription identifiers escape. */
+/**
+ * Privacy-safe acknowledgement; no row or subscription identifiers escape.
+ * An idempotent replay sets `alreadyApplied` while retaining the first call's
+ * exact counts when that repair was first applied by Syncular 0.15.36 or later.
+ */
 export interface LocalDataRebootstrapResult {
     readonly alreadyApplied: boolean;
     readonly retainedCommits: number;

package/dist/realtime-supervisor.d.ts

@@ -0,0 +1,78 @@
+import type { SecurityLifecycle } from './client.js';
+import type { ClientDiagnosticsConnectivity, ClientDiagnosticsListener, ClientDiagnosticsSnapshot } from './diagnostics.js';
+type CancelTimer = () => void;
+export interface RealtimeSupervisorClient {
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): void | Promise<void>;
+    syncUntilIdle(maxRounds?: number): unknown | Promise<unknown>;
+    diagnosticsSnapshot(): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
+    close(): void | Promise<void>;
+}
+export interface RealtimeSupervisorSignal<State> {
+    current(): State;
+    subscribe(listener: (state: State) => void): () => void;
+}
+export type RealtimeSupervisorLifecycleState = 'active' | 'background' | 'unknown';
+export type RealtimeSupervisorProtectionState = SecurityLifecycle | 'unknown';
+type RealtimeSuspendedPhase = 'offline' | 'background' | 'protected';
+export type RealtimeSupervisorPhase = 'idle' | 'connecting' | 'connected' | 'retrying' | RealtimeSuspendedPhase | 'unsupported' | 'stopped';
+export interface RealtimeSupervisorSnapshot {
+    readonly phase: RealtimeSupervisorPhase;
+    /** One-based for retries; zero for the initial connection. */
+    readonly attempt: number;
+    /** Bounded host-policy delay, never server or transport prose. */
+    readonly retryDelayMs?: number;
+}
+export interface RealtimeSupervisorOptions {
+    /** Host online/offline evidence. Unknown remains connectable and observable. */
+    readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
+    /** Browser/native foreground evidence. Background always suspends the socket. */
+    readonly lifecycle?: RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
+    /** Publish preflight before draining keys so reconnect stops in the same turn. */
+    readonly protection?: RealtimeSupervisorSignal<RealtimeSupervisorProtectionState>;
+    /** Deterministic test/host timer seam. */
+    readonly schedule?: (callback: () => void, delayMs: number) => CancelTimer;
+    readonly random?: () => number;
+    readonly initialDelayMs?: number;
+    readonly maximumDelayMs?: number;
+}
+export interface RealtimeSupervisorEventTarget {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface BrowserConnectivitySignalOptions {
+    readonly events?: RealtimeSupervisorEventTarget;
+    readonly network?: {
+        readonly onLine?: boolean;
+    };
+}
+export interface DocumentLifecycleSignalOptions {
+    readonly events?: RealtimeSupervisorEventTarget;
+    readonly document?: {
+        readonly visibilityState?: string;
+    };
+}
+/** Browser/Tauri-webview connectivity evidence without importing DOM types. */
+export declare function browserConnectivitySignal(options?: BrowserConnectivitySignalOptions): RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
+/** Browser/Tauri-webview visibility evidence without importing DOM types. */
+export declare function documentLifecycleSignal(options?: DocumentLifecycleSignalOptions): RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
+/**
+ * Supported host policy for Syncular's explicit realtime transport. It owns
+ * exactly one connect attempt, runs an explicit catch-up round before claiming
+ * connected, retries transient loss with bounded exponential jitter, and
+ * suspends across offline, background, or protected-preflight state.
+ */
+export declare class RealtimeSupervisor {
+    #private;
+    constructor(client: RealtimeSupervisorClient, options?: RealtimeSupervisorOptions);
+    snapshot(): RealtimeSupervisorSnapshot;
+    subscribe(listener: () => void): () => void;
+    start(): void;
+    stop(): void;
+}
+/** Install one supervisor and make client disposal cancel it before close. */
+export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
+export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;
+export declare function subscribeRealtimeSupervisor(client: object, listener: () => void): () => void;
+export {};