@syncular/client 0.32.1 → 0.33.0

package/dist/client.d.ts

@@ -639,6 +639,14 @@ export declare class SyncClient {
     /**
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+     *
+     * §8.4: every host trigger drives this same client — the scheduler, the
+     * realtime supervisor's connect-time catch-up, and app code — so a call
+     * that arrives while a drive is in flight waits for that drive and then
+     * runs one follow-up drive. The follow-up is required, not defensive: the
+     * caller may have mutated the outbox after the in-flight drive captured it.
+     * Callers that arrive during the same drive with the same budget share that
+     * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
      */
     syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
     connectRealtime(): Promise<void>;

package/dist/client.js

@@ -178,6 +178,14 @@ export class SyncClient {
      * (the fast-bail the delta path reads).
      */
     #syncOutstanding = false;
+    /**
+     * Idle drives run one after another (§8.4): `#syncIdleTail` settles when
+     * the last scheduled drive settles, and `#syncIdlePending` holds the
+     * scheduled drives that have not started, keyed by round budget, so a
+     * caller joins a waiting drive with its budget instead of queueing another.
+     */
+    #syncIdleTail;
+    #syncIdlePending = new Map();
     /**
      * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
      * round captures this epoch together with its subscription state; a
@@ -1829,7 +1837,12 @@ export class SyncClient {
             if (!sameIntent) {
                 throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
             }
-            return;
+            // §3.3: a revoked registration keeps its id and intent but no progress.
+            // Subscribing again with the same intent re-arms it, so the next pull
+            // resolves its scopes from scratch. A `failed` registration is a
+            // configuration error and stays put.
+            if (existing.status !== 'revoked')
+                return;
         }
         saveSubscription(this.#db, definedObject({
             id: input.id,
@@ -2918,6 +2931,14 @@ export class SyncClient {
     /**
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+     *
+     * §8.4: every host trigger drives this same client — the scheduler, the
+     * realtime supervisor's connect-time catch-up, and app code — so a call
+     * that arrives while a drive is in flight waits for that drive and then
+     * runs one follow-up drive. The follow-up is required, not defensive: the
+     * caller may have mutated the outbox after the in-flight drive captured it.
+     * Callers that arrive during the same drive with the same budget share that
+     * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
      */
     async syncUntilIdle(maxRounds) {
         // §7.7: an explicit budget is a strict positive round count. Zero,
@@ -2925,6 +2946,31 @@ export class SyncClient {
         if (maxRounds !== undefined &&
             (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
             throw invalidRequest('maxRounds must be a positive integer');
+        const pending = this.#syncIdlePending.get(maxRounds);
+        if (pending !== undefined)
+            return pending;
+        const previous = this.#syncIdleTail;
+        let drive;
+        if (previous === undefined) {
+            drive = this.#syncIdleRounds(maxRounds);
+        }
+        else {
+            drive = previous.then(() => {
+                this.#syncIdlePending.delete(maxRounds);
+                return this.#syncIdleRounds(maxRounds);
+            });
+            this.#syncIdlePending.set(maxRounds, drive);
+        }
+        const tail = drive.then(() => undefined, () => undefined);
+        this.#syncIdleTail = tail;
+        void tail.then(() => {
+            if (this.#syncIdleTail === tail)
+                this.#syncIdleTail = undefined;
+        });
+        return drive;
+    }
+    /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
+    async #syncIdleRounds(maxRounds) {
         const budget = maxRounds ?? 20;
         const aggregate = {
             pushed: 0,

package/dist/http.js

@@ -229,25 +229,30 @@ export function httpBlobTransport(blobsBaseUrl, options) {
                         : response.status === 401
                             ? 'sync.auth_required'
                             : 'sync.transport_failed');
-            // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
-            // an octet-stream body is inline bytes.
+            // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
+            // any other body is inline bytes. The body is read exactly once as bytes,
+            // so an inline blob stored as `application/json` stays readable.
             const contentType = response.headers.get('content-type') ?? '';
+            const bytes = new Uint8Array(await transfer('blob download body read failed', () => response.arrayBuffer(), response.status));
             if (contentType.includes('application/json')) {
-                const body = (await transfer('blob download body read failed', () => response.json(), response.status));
-                if (typeof body.url === 'string') {
+                let envelope = null;
+                try {
+                    envelope = JSON.parse(new TextDecoder().decode(bytes));
+                }
+                catch {
+                    // Not JSON: inline bytes.
+                }
+                if (typeof envelope?.url === 'string') {
                     return {
                         kind: 'url',
-                        url: body.url,
-                        ...(typeof body.urlExpiresAtMs === 'number'
-                            ? { urlExpiresAtMs: body.urlExpiresAtMs }
+                        url: envelope.url,
+                        ...(typeof envelope.urlExpiresAtMs === 'number'
+                            ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
                             : {}),
                     };
                 }
             }
-            return {
-                kind: 'bytes',
-                bytes: new Uint8Array(await transfer('blob download body read failed', () => response.arrayBuffer(), response.status)),
-            };
+            return { kind: 'bytes', bytes };
         },
         // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
         fetchUrl: async (url) => {

package/dist/sync-scheduler.d.ts

@@ -2,8 +2,10 @@ 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;
+    statusSnapshot(): {
+        readonly syncNeeded: boolean;
+    };
+    securityLifecycle(): SecurityLifecycle;
     syncUntilIdle(maxRounds?: number): Promise<unknown>;
     onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
     onSyncIntent(listener: (intent: SyncIntent) => void): () => void;

package/dist/sync-scheduler.js

@@ -47,7 +47,7 @@ export function installSyncScheduler(client, options = {}) {
     const run = () => {
         if (stopped || running)
             return;
-        if (client.securityLifecycle === 'preflight') {
+        if (client.securityLifecycle() === 'preflight') {
             immediatePending = false;
             return;
         }
@@ -110,7 +110,8 @@ export function installSyncScheduler(client, options = {}) {
         consume({ kind: 'interactive' });
     });
     const unsubscribeIntent = client.onSyncIntent(consume);
-    if (client.syncNeeded && client.securityLifecycle === 'active') {
+    if (client.statusSnapshot().syncNeeded &&
+        client.securityLifecycle() === 'active') {
         consume({ kind: 'interactive' });
     }
     return {

package/dist/worker-entry.js

@@ -76,15 +76,21 @@ export function startSyncWorker(overrides = {}) {
     let backgroundTimer;
     let backgroundDue = Number.POSITIVE_INFINITY;
     function runAutoSync() {
-        autoSyncScheduled = false;
         if (closed ||
             client === undefined ||
             offline ||
             client.securityLifecycle() === 'preflight') {
+            autoSyncScheduled = false;
             return;
         }
         const running = client;
-        void serializedSync(() => running.syncUntilIdle())
+        void serializedSync(() => {
+            // The queued round owns the flag from here. Clearing it at entry would
+            // let every wake-up that arrives while this round waits behind the
+            // running one queue its own full drive (§8.4 coalescing).
+            autoSyncScheduled = false;
+            return running.syncUntilIdle();
+        })
             .then((summary) => {
             if (!closed)
                 post({ t: 'event', event: { kind: 'synced', summary } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -97,10 +97,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.32.1"
+    "@syncular/core": "0.33.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.32.1",
+    "@syncular/server": "0.33.0",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/client.ts

@@ -893,6 +893,17 @@ export class SyncClient {
    * (the fast-bail the delta path reads).
    */
   #syncOutstanding = false;
+  /**
+   * Idle drives run one after another (§8.4): `#syncIdleTail` settles when
+   * the last scheduled drive settles, and `#syncIdlePending` holds the
+   * scheduled drives that have not started, keyed by round budget, so a
+   * caller joins a waiting drive with its budget instead of queueing another.
+   */
+  #syncIdleTail: Promise<void> | undefined;
+  readonly #syncIdlePending = new Map<
+    number | undefined,
+    Promise<SyncIdleResult>
+  >();
   /**
    * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
    * round captures this epoch together with its subscription state; a
@@ -2903,7 +2914,11 @@ export class SyncClient {
           'subscription id already names different table, scopes, or params',
         );
       }
-      return;
+      // §3.3: a revoked registration keeps its id and intent but no progress.
+      // Subscribing again with the same intent re-arms it, so the next pull
+      // resolves its scopes from scratch. A `failed` registration is a
+      // configuration error and stays put.
+      if (existing.status !== 'revoked') return;
     }
     saveSubscription(
       this.#db,
@@ -4227,6 +4242,14 @@ export class SyncClient {
   /**
    * Pull repeatedly until quiescent: no commits delivered, no bootstrap
    * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+   *
+   * §8.4: every host trigger drives this same client — the scheduler, the
+   * realtime supervisor's connect-time catch-up, and app code — so a call
+   * that arrives while a drive is in flight waits for that drive and then
+   * runs one follow-up drive. The follow-up is required, not defensive: the
+   * caller may have mutated the outbox after the in-flight drive captured it.
+   * Callers that arrive during the same drive with the same budget share that
+   * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
    */
   async syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult> {
     // §7.7: an explicit budget is a strict positive round count. Zero,
@@ -4236,6 +4259,34 @@ export class SyncClient {
       (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
     )
       throw invalidRequest('maxRounds must be a positive integer');
+    const pending = this.#syncIdlePending.get(maxRounds);
+    if (pending !== undefined) return pending;
+    const previous = this.#syncIdleTail;
+    let drive: Promise<SyncIdleResult>;
+    if (previous === undefined) {
+      drive = this.#syncIdleRounds(maxRounds);
+    } else {
+      drive = previous.then(() => {
+        this.#syncIdlePending.delete(maxRounds);
+        return this.#syncIdleRounds(maxRounds);
+      });
+      this.#syncIdlePending.set(maxRounds, drive);
+    }
+    const tail = drive.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.#syncIdleTail = tail;
+    void tail.then(() => {
+      if (this.#syncIdleTail === tail) this.#syncIdleTail = undefined;
+    });
+    return drive;
+  }
+
+  /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
+  async #syncIdleRounds(
+    maxRounds: number | undefined,
+  ): Promise<SyncIdleResult> {
     const budget = maxRounds ?? 20;
     const aggregate = {
       pushed: 0,

package/src/http.ts

@@ -355,38 +355,35 @@ export function httpBlobTransport(
                 ? 'sync.auth_required'
                 : 'sync.transport_failed',
         );
-      // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
-      // an octet-stream body is inline bytes.
+      // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
+      // any other body is inline bytes. The body is read exactly once as bytes,
+      // so an inline blob stored as `application/json` stays readable.
       const contentType = response.headers.get('content-type') ?? '';
-      if (contentType.includes('application/json')) {
-        const body = (await transfer(
+      const bytes = new Uint8Array(
+        await transfer(
           'blob download body read failed',
-          () => response.json(),
+          () => response.arrayBuffer(),
           response.status,
-        )) as {
-          url?: string;
-          urlExpiresAtMs?: number;
-        };
-        if (typeof body.url === 'string') {
+        ),
+      );
+      if (contentType.includes('application/json')) {
+        let envelope: { url?: unknown; urlExpiresAtMs?: unknown } | null = null;
+        try {
+          envelope = JSON.parse(new TextDecoder().decode(bytes));
+        } catch {
+          // Not JSON: inline bytes.
+        }
+        if (typeof envelope?.url === 'string') {
           return {
             kind: 'url',
-            url: body.url,
-            ...(typeof body.urlExpiresAtMs === 'number'
-              ? { urlExpiresAtMs: body.urlExpiresAtMs }
+            url: envelope.url,
+            ...(typeof envelope.urlExpiresAtMs === 'number'
+              ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
               : {}),
           };
         }
       }
-      return {
-        kind: 'bytes',
-        bytes: new Uint8Array(
-          await transfer(
-            'blob download body read failed',
-            () => response.arrayBuffer(),
-            response.status,
-          ),
-        ),
-      };
+      return { kind: 'bytes', bytes };
     },
     // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
     fetchUrl: async (url) => {

package/src/sync-scheduler.ts

@@ -3,8 +3,8 @@ import type { SecurityLifecycle } from './client';
 import type { SyncIntent } from './invalidation';
 
 export interface SyncSchedulerClient {
-  readonly syncNeeded: boolean;
-  readonly securityLifecycle: SecurityLifecycle;
+  statusSnapshot(): { readonly syncNeeded: boolean };
+  securityLifecycle(): SecurityLifecycle;
   syncUntilIdle(maxRounds?: number): Promise<unknown>;
   onSyncNeeded(
     listener: (reason: 'startup' | 'hello' | WakeReason) => void,
@@ -79,7 +79,7 @@ export function installSyncScheduler(
 
   const run = (): void => {
     if (stopped || running) return;
-    if (client.securityLifecycle === 'preflight') {
+    if (client.securityLifecycle() === 'preflight') {
       immediatePending = false;
       return;
     }
@@ -144,7 +144,10 @@ export function installSyncScheduler(
     consume({ kind: 'interactive' });
   });
   const unsubscribeIntent = client.onSyncIntent(consume);
-  if (client.syncNeeded && client.securityLifecycle === 'active') {
+  if (
+    client.statusSnapshot().syncNeeded &&
+    client.securityLifecycle() === 'active'
+  ) {
     consume({ kind: 'interactive' });
   }
 

package/src/worker-entry.ts

@@ -164,17 +164,23 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   let backgroundDue = Number.POSITIVE_INFINITY;
 
   function runAutoSync(): void {
-    autoSyncScheduled = false;
     if (
       closed ||
       client === undefined ||
       offline ||
       client.securityLifecycle() === 'preflight'
     ) {
+      autoSyncScheduled = false;
       return;
     }
     const running = client;
-    void serializedSync(() => running.syncUntilIdle())
+    void serializedSync(() => {
+      // The queued round owns the flag from here. Clearing it at entry would
+      // let every wake-up that arrives while this round waits behind the
+      // running one queue its own full drive (§8.4 coalescing).
+      autoSyncScheduled = false;
+      return running.syncUntilIdle();
+    })
       .then((summary) => {
         if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
         if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });