@syncular/client 0.15.47 → 0.16.1

package/dist/remote.js

@@ -2,7 +2,7 @@
  * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
  * through the existing push path without creating a local replica or outbox.
  */
-import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
+import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, } from '@syncular/core';
 import { encryptRowValues } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { compileClientSchema, recordToRowValues, } from './schema.js';
@@ -71,10 +71,14 @@ export class SyncRemoteClient {
     #operationSocketGeneration = 0;
     #watches = new Map();
     #encryption;
+    #logEpoch;
     constructor(config) {
         if (config.clientId.length === 0) {
             throw invalid('SyncRemoteClient clientId must be non-empty');
         }
+        if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
+            throw invalid('SyncRemoteClient logEpoch must be non-empty');
+        }
         this.#schema =
             config.schema === undefined
                 ? undefined
@@ -84,6 +88,7 @@ export class SyncRemoteClient {
         this.#operations = config.operations;
         this.#operationRealtime = config.operationRealtime;
         this.#encryption = config.encryption;
+        this.#logEpoch = config.logEpoch;
     }
     async prepareCommit(input) {
         const schema = this.#schema;
@@ -137,13 +142,16 @@ export class SyncRemoteClient {
         return {
             requestId: input.requestId,
             bytes: encodeMessage({
-                wireVersion: PROTOCOL_WIRE_VERSION,
+                wireVersion: this.#logEpoch === undefined ? 1 : 2,
                 msgKind: 'request',
                 frames: [
                     {
                         type: 'REQ_HEADER',
                         clientId: this.#clientId,
                         schemaVersion: schema.version,
+                        ...(this.#logEpoch !== undefined
+                            ? { logEpoch: this.#logEpoch }
+                            : {}),
                     },
                     {
                         type: 'PUSH_COMMIT',

package/dist/sync-scheduler.d.ts

@@ -0,0 +1,23 @@
+import type { WakeReason } from '@syncular/core';
+import type { SecurityLifecycle } from './client.js';
+import type { SyncIntent } from './invalidation.js';
+export interface SyncSchedulerClient {
+    readonly syncNeeded: boolean;
+    readonly securityLifecycle: SecurityLifecycle;
+    syncUntilIdle(maxRounds?: number): Promise<unknown>;
+    onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
+    onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
+}
+export interface SyncSchedulerOptions {
+    readonly maxRounds?: number;
+    readonly onError?: (error: unknown) => void;
+    readonly now?: () => number;
+    readonly queueMicrotask?: (callback: () => void) => void;
+    readonly schedule?: (callback: () => void, delayMs: number) => () => void;
+}
+export interface SyncScheduler {
+    readonly stopped: boolean;
+    stop(): void;
+}
+/** Install the event-driven single-flight host loop for a direct client. */
+export declare function installSyncScheduler(client: SyncSchedulerClient, options?: SyncSchedulerOptions): SyncScheduler;

package/dist/sync-scheduler.js

@@ -0,0 +1,122 @@
+/** Install the event-driven single-flight host loop for a direct client. */
+export function installSyncScheduler(client, options = {}) {
+    const now = options.now ?? Date.now;
+    const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
+    const schedule = options.schedule ??
+        ((callback, delayMs) => {
+            const timer = globalThis.setTimeout(callback, delayMs);
+            return () => globalThis.clearTimeout(timer);
+        });
+    let stopped = false;
+    let running = false;
+    let immediatePending = false;
+    let immediateQueued = false;
+    let backgroundReady = false;
+    let backgroundDue = Number.POSITIVE_INFINITY;
+    let cancelBackground;
+    const report = (error) => {
+        if (options.onError !== undefined) {
+            options.onError(error);
+            return;
+        }
+        const root = globalThis;
+        if (root.reportError !== undefined)
+            root.reportError(error);
+        else
+            console.error(error);
+    };
+    const clearBackground = () => {
+        cancelBackground?.();
+        cancelBackground = undefined;
+        backgroundReady = false;
+        backgroundDue = Number.POSITIVE_INFINITY;
+    };
+    const queueImmediate = () => {
+        immediatePending = true;
+        if (stopped || running || immediateQueued)
+            return;
+        immediateQueued = true;
+        enqueue(() => {
+            immediateQueued = false;
+            if (stopped || !immediatePending)
+                return;
+            immediatePending = false;
+            run();
+        });
+    };
+    const run = () => {
+        if (stopped || running)
+            return;
+        if (client.securityLifecycle === 'preflight') {
+            immediatePending = false;
+            return;
+        }
+        running = true;
+        backgroundReady = false;
+        void client
+            .syncUntilIdle(options.maxRounds)
+            .catch((error) => {
+            if (!stopped)
+                report(error);
+        })
+            .finally(() => {
+            running = false;
+            if (stopped)
+                return;
+            if (immediatePending || backgroundReady) {
+                queueImmediate();
+                return;
+            }
+            if (cancelBackground !== undefined && backgroundDue <= now()) {
+                clearBackground();
+                queueImmediate();
+            }
+        });
+    };
+    const consume = (intent) => {
+        if (stopped)
+            return;
+        if (intent.kind === 'none') {
+            clearBackground();
+            immediatePending = false;
+            return;
+        }
+        if (intent.kind === 'interactive') {
+            clearBackground();
+            queueImmediate();
+            return;
+        }
+        if (immediatePending || immediateQueued)
+            return;
+        clearBackground();
+        backgroundDue = now() + Math.max(0, intent.delayMs);
+        cancelBackground = schedule(() => {
+            cancelBackground = undefined;
+            backgroundDue = Number.POSITIVE_INFINITY;
+            backgroundReady = true;
+            if (!running)
+                queueImmediate();
+        }, Math.max(0, intent.delayMs));
+    };
+    const unsubscribeNeeded = client.onSyncNeeded(() => {
+        consume({ kind: 'interactive' });
+    });
+    const unsubscribeIntent = client.onSyncIntent(consume);
+    if (client.syncNeeded && client.securityLifecycle === 'active') {
+        consume({ kind: 'interactive' });
+    }
+    return {
+        get stopped() {
+            return stopped;
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearBackground();
+            immediatePending = false;
+            unsubscribeNeeded();
+            unsubscribeIntent();
+        },
+    };
+}

package/dist/window.d.ts

@@ -14,6 +14,11 @@
  */
 import { type ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
+export type TimeBucketUnit = 'month';
+/** Derive the immutable UTC scope value stored when a row is created. */
+export declare function creationTimeBucket(createdAtMs: number, unit: TimeBucketUnit): string;
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export declare function last(count: number, unit: TimeBucketUnit, nowMs?: number): string[];
 /**
  * A window base: one table, one variable whose values are the window
  * units, and any FIXED scopes every unit shares (other variables pinned

package/dist/window.js

@@ -13,6 +13,45 @@
  * transaction and the invalidation choke point.
  */
 import { canonicalScopeJson } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
+const MAX_TIME_BUCKET_MS = 253_402_300_799_999;
+function monthBucket(year, month) {
+    return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}`;
+}
+/** Derive the immutable UTC scope value stored when a row is created. */
+export function creationTimeBucket(createdAtMs, unit) {
+    if (unit !== 'month' ||
+        !Number.isSafeInteger(createdAtMs) ||
+        createdAtMs < 0 ||
+        createdAtMs > MAX_TIME_BUCKET_MS) {
+        throw new ClientSyncError('sync.invalid_request', 'creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999');
+    }
+    const date = new Date(createdAtMs);
+    return monthBucket(date.getUTCFullYear(), date.getUTCMonth() + 1);
+}
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export function last(count, unit, nowMs = Date.now()) {
+    if (unit !== 'month' ||
+        !Number.isSafeInteger(count) ||
+        count < 1 ||
+        count > 1_200 ||
+        !Number.isSafeInteger(nowMs) ||
+        nowMs < 0 ||
+        nowMs > MAX_TIME_BUCKET_MS) {
+        throw new ClientSyncError('sync.invalid_request', 'last requires a supported unit, a count from 1 through 1200, and a UTC timestamp from 1970 through 9999');
+    }
+    const date = new Date(nowMs);
+    const current = date.getUTCFullYear() * 12 + date.getUTCMonth();
+    if (current - (count - 1) < 1970 * 12) {
+        throw new ClientSyncError('sync.invalid_request', 'last requires every returned UTC month to fall from 1970 through 9999');
+    }
+    const units = [];
+    for (let offset = count - 1; offset >= 0; offset -= 1) {
+        const value = current - offset;
+        units.push(monthBucket(Math.floor(value / 12), (value % 12) + 1));
+    }
+    return units;
+}
 /**
  * A stable, server-opaque key for a window base — table + variable +
  * canonical fixed scopes. Two `setWindow` calls with the same base

package/dist/worker-entry.js

@@ -91,7 +91,7 @@ export function startSyncWorker(overrides = {}) {
         autoSyncScheduled = false;
         if (closed ||
             client === undefined ||
-            client.securityLifecycle === 'preflight') {
+            client.securityLifecycle() === 'preflight') {
             return;
         }
         const running = client;
@@ -113,7 +113,7 @@ export function startSyncWorker(overrides = {}) {
         if (!autoSync ||
             closed ||
             client === undefined ||
-            client.securityLifecycle === 'preflight' ||
+            client.securityLifecycle() === 'preflight' ||
             intent.kind === 'none') {
             return;
         }
@@ -147,9 +147,6 @@ export function startSyncWorker(overrides = {}) {
         autoSyncScheduled = true;
         queueMicrotask(runAutoSync);
     }
-    function consumeEffects(effects) {
-        consumeSyncIntent(effects.sync);
-    }
     function requireClient() {
         if (client === undefined) {
             throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker received a call before init completed');
@@ -280,12 +277,12 @@ export function startSyncWorker(overrides = {}) {
         // `start()` may discover persisted subscriptions/outbox work. Its callback
         // fires before this worker publishes the initialized client, so consume
         // the durable state once here as well; coalescing makes this a single task.
-        if (started.syncNeeded)
+        if (started.statusSnapshot().syncNeeded)
             consumeSyncIntent({ kind: 'interactive' });
         return { clientId: started.clientId };
     }
     const api = {
-        securityLifecycle: () => requireClient().securityLifecycle,
+        securityLifecycle: () => requireClient().securityLifecycle(),
         beginSecurityPreflight: async () => {
             if (backgroundTimer !== undefined)
                 clearTimeout(backgroundTimer);
@@ -304,20 +301,16 @@ export function startSyncWorker(overrides = {}) {
         subscribe: (input) => requireClient().subscribe(input),
         unsubscribe: (id) => requireClient().unsubscribe(id),
         setWindow: async (base, units) => {
-            const result = await requireClient().setWindowCommand(base, units);
-            consumeEffects(result.effects);
+            await requireClient().setWindowCommand(base, units);
         },
         windowState: (base) => requireClient().windowState(base),
         mutate: (mutations) => {
-            const result = requireClient().mutateCommand(mutations);
-            consumeEffects(result.effects);
-            return result.value;
+            return requireClient().mutateCommand(mutations).value;
         },
         patch: (table, rowId, partial, options) => {
             // Same §8.4 rule as `mutate`: a local write must push without the app
             // orchestrating sync, so consume the core's immediate intent.
             const result = requireClient().patchCommand(table, rowId, partial, options);
-            consumeEffects(result.effects);
             return result.value;
         },
         purgeLocalData: (input) => requireClient().purgeLocalData(input),
@@ -343,15 +336,11 @@ export function startSyncWorker(overrides = {}) {
                 realtime: snapshot.host.realtime,
             });
         },
-        conflicts: () => requireClient().conflicts,
-        rejections: () => requireClient().rejections,
+        conflicts: () => requireClient().conflicts(),
+        rejections: () => requireClient().rejections(),
         commitOutcome: (clientCommitId) => requireClient().commitOutcome(clientCommitId),
         commitOutcomes: (query) => requireClient().commitOutcomes(query),
         resolveCommitOutcome: (input) => requireClient().resolveCommitOutcome(input),
-        schemaFloor: () => requireClient().schemaFloor,
-        leaseState: () => requireClient().leaseState,
-        upgrading: () => requireClient().upgrading,
-        syncNeeded: () => requireClient().syncNeeded,
         pendingCommits: () => requireClient().pendingCommits(),
         subscriptions: () => requireClient().subscriptions(),
         subscription: (id) => requireClient().subscription(id),

package/dist/worker-host.d.ts

@@ -1,3 +1,4 @@
+import type { PromiseMethods } from './client.js';
 /**
  * Main-thread side of the worker mode and the
  * multi-tab topology.
@@ -23,7 +24,7 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
@@ -38,7 +39,7 @@ import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } fro
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
-import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
+import { type SyncWorkerEvent, type WorkerApi, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
 /** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
 export declare function workerStartupError(message: unknown): ClientSyncError;
 export type HandleRole = 'leader' | 'follower';
@@ -132,7 +133,7 @@ interface LeaderCore {
  * promise. `role` is `'leader'` (owns the worker) or `'follower'` (proxies to
  * the leader over the channel). Constructed via {@link createSyncClientHandle}.
  */
-export declare class SyncClientHandle {
+export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
     #private;
     /** True only for a leader handle. Kept for the pre-multiTab contract. */
     get isLeader(): boolean;
@@ -214,11 +215,7 @@ export declare class SyncClientHandle {
     commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
     commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
     resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
-    schemaFloor(): Promise<SchemaFloor | undefined>;
-    leaseState(): Promise<LeaseState | undefined>;
     /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
-    upgrading(): Promise<boolean>;
-    syncNeeded(): Promise<boolean>;
     pendingCommits(): Promise<OutboxCommit[]>;
     subscriptions(): Promise<SubscriptionRecord[]>;
     subscription(id: string): Promise<SubscriptionRecord | undefined>;

package/dist/worker-host.js

@@ -104,12 +104,12 @@ export class SyncClientHandle {
             ref: this,
             clientId: () => this.#clientId,
             role: () => this.#role,
-            outbox: async () => (await this.pendingCommits()).length,
+            outbox: async () => (await this.statusSnapshot()).outbox,
             subscriptions: () => this.subscriptions(),
             conflicts: async () => (await this.conflicts()).length,
             rejections: async () => (await this.rejections()).length,
-            syncNeeded: () => this.syncNeeded(),
-            upgrading: () => this.upgrading(),
+            syncNeeded: async () => (await this.statusSnapshot()).syncNeeded,
+            upgrading: async () => (await this.statusSnapshot()).upgrading,
             onInvalidate: (listener) => this.onInvalidate(listener),
         });
     }
@@ -310,19 +310,7 @@ export class SyncClientHandle {
     resolveCommitOutcome(input) {
         return this.#call('resolveCommitOutcome', [input]);
     }
-    schemaFloor() {
-        return this.#call('schemaFloor', []);
-    }
-    leaseState() {
-        return this.#call('leaseState', []);
-    }
     /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
-    upgrading() {
-        return this.#call('upgrading', []);
-    }
-    syncNeeded() {
-        return this.#call('syncNeeded', []);
-    }
     pendingCommits() {
         return this.#call('pendingCommits', []);
     }

package/dist/worker-protocol.d.ts

@@ -18,15 +18,14 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
-import type { ClientDiagnosticsRequest, ClientDiagnosticsSnapshot } from './diagnostics.js';
+import type { ClientDiagnosticsSnapshot } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
-import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
+import type { ClientChangeBatch, LocalRevision } from './invalidation.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
 import type { LocalDataRebootstrapInput, LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import type { OutboxCommit } from './outbox.js';
-import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
@@ -88,7 +87,7 @@ export interface WorkerInitResult {
 export interface WorkerSecurityActivation {
     readonly encryption?: EncryptionKeyringConfig;
 }
-export interface WorkerApi {
+export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'> {
     securityLifecycle(): SecurityLifecycle;
     beginSecurityPreflight(): Promise<void>;
     activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
@@ -112,19 +111,6 @@ export interface WorkerApi {
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     querySnapshot(spec: QueryReadSpec): QuerySnapshot;
     localRevision(): LocalRevision;
-    statusSnapshot(): SyncStatusSnapshot;
-    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot;
-    conflicts(): readonly ConflictRecord[];
-    rejections(): readonly RejectionRecord[];
-    commitOutcome(clientCommitId: string): CommitOutcome | undefined;
-    commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[];
-    resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
-    schemaFloor(): SchemaFloor | undefined;
-    /** §7.3.5: the opaque auth-lease state, or undefined. */
-    leaseState(): LeaseState | undefined;
-    /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
-    upgrading(): boolean;
-    syncNeeded(): boolean;
     pendingCommits(): OutboxCommit[];
     subscriptions(): SubscriptionRecord[];
     subscription(id: string): SubscriptionRecord | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.47",
+  "version": "0.16.1",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -34,14 +34,6 @@
         "default": "./dist/index.js"
       }
     },
-    "./realtime-supervisor-observation": {
-      "bun": "./src/realtime-supervisor-observation.ts",
-      "browser": "./dist/realtime-supervisor-observation.js",
-      "import": {
-        "types": "./dist/realtime-supervisor-observation.d.ts",
-        "default": "./dist/realtime-supervisor-observation.js"
-      }
-    },
     "./bun": {
       "bun": "./src/bun-database.ts",
       "browser": "./dist/bun-database.js",
@@ -97,9 +89,9 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.47"
+    "@syncular/core": "0.16.1"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.47"
+    "@syncular/server": "0.16.1"
   }
 }

package/src/bun-database.ts

@@ -15,6 +15,12 @@ import {
   type SqlValue,
 } from './database';
 
+declare module 'bun:sqlite' {
+  interface Database {
+    clearQueryCache(): void;
+  }
+}
+
 type BunParam = string | number | bigint | Uint8Array | null;
 
 function coerceParams(params: readonly SqlValue[]): BunParam[] {
@@ -34,6 +40,11 @@ export class BunClientDatabase implements ClientDatabase {
 
   exec(sql: string, params: readonly SqlValue[] = []): void {
     this.db.query(sql).run(...coerceParams(params));
+    // `Database.query()` caches prepared statements. Clear that cache after
+    // schema DDL so a reset does not reprepare every later row upsert.
+    if (/^\s*(?:CREATE|DROP|ALTER)\b/i.test(sql)) {
+      this.db.clearQueryCache();
+    }
   }
 
   query(sql: string, params: readonly SqlValue[] = []): SqlRow[] {