@syncular/client 0.15.17 → 0.15.19

package/dist/client.js

@@ -69,6 +69,12 @@ function emptySummary(pushed) {
         failed: [],
     };
 }
+function isFinalPushResult(frame) {
+    return (frame.status !== 'rejected' ||
+        !frame.results.some((result) => result.status === 'error' &&
+            result.code === 'sync.idempotency_cache_miss' &&
+            result.retryable));
+}
 export class SyncClient {
     #config;
     #db;
@@ -112,6 +118,8 @@ export class SyncClient {
     /** §8.6: subscribable presence-change listeners (twin of onPresence). */
     #presenceListeners = new Set();
     #diagnostics = new ClientDiagnosticsEmitter();
+    #diagnosticsDeferralDepth = 0;
+    #diagnosticsPending = false;
     #lastRound;
     #lastChange;
     /** The batch accumulator; non-undefined only inside `#applyBatch`. */
@@ -630,19 +638,38 @@ export class SyncClient {
         }
     }
     #emitDiagnostics() {
-        if (!this.#started || this.#securityLifecycle !== 'active')
+        if (!this.#started ||
+            this.#securityLifecycle !== 'active' ||
+            !this.#diagnostics.observed) {
+            return;
+        }
+        if (this.#diagnosticsDeferralDepth > 0) {
+            this.#diagnosticsPending = true;
             return;
+        }
         this.#diagnostics.emit(this.diagnosticsSnapshot());
     }
+    #beginDiagnosticsDeferral() {
+        this.#diagnosticsDeferralDepth += 1;
+    }
+    #endDiagnosticsDeferral() {
+        if (this.#diagnosticsDeferralDepth === 0)
+            return;
+        this.#diagnosticsDeferralDepth -= 1;
+        if (this.#diagnosticsDeferralDepth === 0 && this.#diagnosticsPending) {
+            this.#diagnosticsPending = false;
+            this.#emitDiagnostics();
+        }
+    }
     /** One call for the complete status domain used by reactive hosts. */
     statusSnapshot() {
         this.#requireStarted();
         return this.#statusSnapshot();
     }
-    #statusSnapshot() {
+    #statusSnapshot(outboxCount) {
         return {
             currentSchemaVersion: this.#config.schema.version,
-            outbox: listOutbox(this.#db).length,
+            outbox: outboxCount ?? listOutbox(this.#db).length,
             upgrading: this.#upgrading,
             leaseState: this.#leaseState,
             schemaFloor: this.#schemaFloor,
@@ -655,7 +682,7 @@ export class SyncClient {
      * Re-entrant calls share the outer batch so a nested apply never
      * double-emits (e.g. purge → blob reconcile → replay inside one round).
      */
-    #applyBatch(fn) {
+    #applyBatch(fn, statusSnapshotOverride) {
         if (this.#batch !== undefined)
             return fn(this.#batch);
         const batch = new ChangeAccumulator();
@@ -669,8 +696,9 @@ export class SyncClient {
                     result = fn(batch);
                     if (batch.touched) {
                         revision = bumpLocalRevision(this.#db);
-                        if (batch.statusChanged)
-                            status = this.#statusSnapshot();
+                        if (batch.statusChanged) {
+                            status = statusSnapshotOverride?.() ?? this.#statusSnapshot();
+                        }
                     }
                 }
                 finally {
@@ -1061,13 +1089,13 @@ export class SyncClient {
         }
         const existing = getSubscription(this.#db, input.id);
         if (existing !== undefined) {
-            saveSubscription(this.#db, {
-                ...existing,
-                table: input.table,
-                scopes: input.scopes,
-                ...(input.params !== undefined ? { params: input.params } : {}),
-            });
-            this.#emitDiagnostics();
+            const sameIntent = existing.table === input.table &&
+                canonicalScopeJson(existing.scopes) ===
+                    canonicalScopeJson(input.scopes) &&
+                existing.params === input.params;
+            if (!sameIntent) {
+                throw new ClientSyncError('client.subscription_intent_mismatch', 'subscribe: the subscription id is already registered for a different table, scopes, or params');
+            }
             return;
         }
         saveSubscription(this.#db, {
@@ -1603,6 +1631,7 @@ export class SyncClient {
             return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
         }
         this.#syncOutstanding = true;
+        this.#beginDiagnosticsDeferral();
         const startedAtMs = this.#now();
         return this.#serialize(() => this.#runSync())
             .then((summary) => {
@@ -1633,6 +1662,7 @@ export class SyncClient {
         })
             .finally(() => {
             this.#syncOutstanding = false;
+            this.#endDiagnosticsDeferral();
         });
     }
     #diagnosticRoundCounters(summary) {
@@ -2027,10 +2057,16 @@ export class SyncClient {
         const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
         const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
         const rejectionDetailsByCommit = new Map();
+        let lastFinalPushResult;
         for (const frame of message.frames) {
-            if (frame.type !== 'PUSH_RESULT_DETAILS')
-                continue;
-            rejectionDetailsByCommit.set(frame.clientCommitId, new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])));
+            if (frame.type === 'PUSH_RESULT_DETAILS') {
+                rejectionDetailsByCommit.set(frame.clientCommitId, new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])));
+            }
+            else if (frame.type === 'PUSH_RESULT' &&
+                commitsById.has(frame.clientCommitId) &&
+                isFinalPushResult(frame)) {
+                lastFinalPushResult = frame;
+            }
         }
         const header = message.frames[0];
         if (header?.type !== 'RESP_HEADER') {
@@ -2060,8 +2096,10 @@ export class SyncClient {
         let section;
         let errorFrame;
         let deltaCursor = -1;
+        let responseOutboxCount;
         // Each durable observer transaction emits its own revisioned batch.
         // Async decrypt/download work happens outside SQLite transactions.
+        this.#beginDiagnosticsDeferral();
         try {
             for (const frame of message.frames.slice(1)) {
                 switch (frame.type) {
@@ -2075,9 +2113,16 @@ export class SyncClient {
                             expiresAtMs: frame.expiresAtMs,
                         });
                         break;
-                    case 'PUSH_RESULT':
-                        this.#applyBatch((batch) => this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId)));
+                    case 'PUSH_RESULT': {
+                        let outboxCount = responseOutboxCount ?? listOutbox(this.#db).length;
+                        this.#applyBatch((batch) => {
+                            const drained = this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId), frame === lastFinalPushResult);
+                            if (drained)
+                                outboxCount -= 1;
+                        }, () => this.#statusSnapshot(outboxCount));
+                        responseOutboxCount = outboxCount;
                         break;
+                    }
                     case 'PUSH_RESULT_DETAILS':
                         // Pre-indexed above so companion ordering remains wire-additive.
                         break;
@@ -2202,10 +2247,15 @@ export class SyncClient {
             }
         }
         finally {
-            // §7.1: local reads see outbox state applied optimistically — replay
-            // the still-pending commits on top of the freshly applied server state.
-            this.#replayOutbox();
-            this.#reconcileBlobs(false);
+            try {
+                // §7.1: local reads see outbox state applied optimistically — replay
+                // the still-pending commits on top of the freshly applied server state.
+                this.#replayOutbox();
+                this.#reconcileBlobs(false);
+            }
+            finally {
+                this.#endDiagnosticsDeferral();
+            }
         }
         if (errorFrame !== undefined)
             throw errorFrame;
@@ -2226,10 +2276,10 @@ export class SyncClient {
         }
         return { ...summary, bootstrapping };
     }
-    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
+    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails, pruneOutcomes) {
         const commit = commitsById.get(frame.clientCommitId);
         if (commit === undefined)
-            return;
+            return false;
         if (frame.status === 'applied' || frame.status === 'cached') {
             // §6.3: applied and cached both drain the outbox — cached means
             // "already applied, you may have missed the ack".
@@ -2243,11 +2293,13 @@ export class SyncClient {
                 })),
             });
             deleteOutboxCommit(this.#db, frame.clientCommitId);
-            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+            if (pruneOutcomes) {
+                pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+            }
             batch.status();
             batch.outcomes();
             summary.applied.push(frame.clientCommitId);
-            return;
+            return true;
         }
         // rejected
         const cacheMiss = frame.results.some((result) => result.status === 'error' &&
@@ -2257,7 +2309,7 @@ export class SyncClient {
             // §6.3: a serving failure, not the commit's outcome — keep the
             // commit queued and retry the identical push later.
             summary.retryable.push(frame.clientCommitId);
-            return;
+            return false;
         }
         const outcomeResults = [];
         for (const result of frame.results) {
@@ -2308,7 +2360,9 @@ export class SyncClient {
             results: outcomeResults,
             operations: commit.operations,
         });
-        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        if (pruneOutcomes) {
+            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        }
         batch.outcomes();
         // §7.2: remove the rejected optimistic layer. Before-images restore
         // validator-rejected updates even when the server emitted no new COMMIT;
@@ -2318,6 +2372,7 @@ export class SyncClient {
         });
         batch.status();
         summary.rejected.push(frame.clientCommitId);
+        return true;
     }
     #decodeServerRow(tableName, payload) {
         if (tableName === undefined)

package/dist/diagnostics.d.ts

@@ -126,6 +126,7 @@ export interface ClientDiagnosticsSnapshot {
 export type ClientDiagnosticsListener = (snapshot: ClientDiagnosticsSnapshot) => void;
 export declare class ClientDiagnosticsEmitter {
     #private;
+    get observed(): boolean;
     on(listener: ClientDiagnosticsListener): () => void;
     emit(snapshot: ClientDiagnosticsSnapshot): void;
 }

package/dist/diagnostics.js

@@ -3,6 +3,9 @@ export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
 export const MAX_DIAGNOSTIC_DOMAINS = 256;
 export class ClientDiagnosticsEmitter {
     #listeners = new Set();
+    get observed() {
+        return this.#listeners.size > 0;
+    }
     on(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.17",
+  "version": "0.15.19",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.17"
+    "@syncular/core": "0.15.19"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.17",
+    "@syncular/server": "0.15.19",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -503,6 +503,18 @@ function emptySummary(pushed: number): MutableSummary {
   };
 }
 
+function isFinalPushResult(frame: PushResultFrame): boolean {
+  return (
+    frame.status !== 'rejected' ||
+    !frame.results.some(
+      (result) =>
+        result.status === 'error' &&
+        result.code === 'sync.idempotency_cache_miss' &&
+        result.retryable,
+    )
+  );
+}
+
 export class SyncClient {
   readonly #config: SyncClientConfig;
   readonly #db: ClientDatabase;
@@ -546,6 +558,8 @@ export class SyncClient {
   /** §8.6: subscribable presence-change listeners (twin of onPresence). */
   readonly #presenceListeners = new Set<(scopeKey: string) => void>();
   readonly #diagnostics = new ClientDiagnosticsEmitter();
+  #diagnosticsDeferralDepth = 0;
+  #diagnosticsPending = false;
   #lastRound: DiagnosticLastRound | undefined;
   #lastChange: DiagnosticLastChange | undefined;
   /** The batch accumulator; non-undefined only inside `#applyBatch`. */
@@ -1159,20 +1173,43 @@ export class SyncClient {
   }
 
   #emitDiagnostics(): void {
-    if (!this.#started || this.#securityLifecycle !== 'active') return;
+    if (
+      !this.#started ||
+      this.#securityLifecycle !== 'active' ||
+      !this.#diagnostics.observed
+    ) {
+      return;
+    }
+    if (this.#diagnosticsDeferralDepth > 0) {
+      this.#diagnosticsPending = true;
+      return;
+    }
     this.#diagnostics.emit(this.diagnosticsSnapshot());
   }
 
+  #beginDiagnosticsDeferral(): void {
+    this.#diagnosticsDeferralDepth += 1;
+  }
+
+  #endDiagnosticsDeferral(): void {
+    if (this.#diagnosticsDeferralDepth === 0) return;
+    this.#diagnosticsDeferralDepth -= 1;
+    if (this.#diagnosticsDeferralDepth === 0 && this.#diagnosticsPending) {
+      this.#diagnosticsPending = false;
+      this.#emitDiagnostics();
+    }
+  }
+
   /** One call for the complete status domain used by reactive hosts. */
   statusSnapshot(): SyncStatusSnapshot {
     this.#requireStarted();
     return this.#statusSnapshot();
   }
 
-  #statusSnapshot(): SyncStatusSnapshot {
+  #statusSnapshot(outboxCount?: number): SyncStatusSnapshot {
     return {
       currentSchemaVersion: this.#config.schema.version,
-      outbox: listOutbox(this.#db).length,
+      outbox: outboxCount ?? listOutbox(this.#db).length,
       upgrading: this.#upgrading,
       leaseState: this.#leaseState,
       schemaFloor: this.#schemaFloor,
@@ -1186,7 +1223,10 @@ export class SyncClient {
    * Re-entrant calls share the outer batch so a nested apply never
    * double-emits (e.g. purge → blob reconcile → replay inside one round).
    */
-  #applyBatch<T>(fn: (batch: ChangeAccumulator) => T): T {
+  #applyBatch<T>(
+    fn: (batch: ChangeAccumulator) => T,
+    statusSnapshotOverride?: () => SyncStatusSnapshot,
+  ): T {
     if (this.#batch !== undefined) return fn(this.#batch);
     const batch = new ChangeAccumulator();
     let revision: LocalRevision | undefined;
@@ -1199,7 +1239,9 @@ export class SyncClient {
           result = fn(batch);
           if (batch.touched) {
             revision = bumpLocalRevision(this.#db);
-            if (batch.statusChanged) status = this.#statusSnapshot();
+            if (batch.statusChanged) {
+              status = statusSnapshotOverride?.() ?? this.#statusSnapshot();
+            }
           }
         } finally {
           this.#batch = undefined;
@@ -1697,13 +1739,17 @@ export class SyncClient {
     }
     const existing = getSubscription(this.#db, input.id);
     if (existing !== undefined) {
-      saveSubscription(this.#db, {
-        ...existing,
-        table: input.table,
-        scopes: input.scopes,
-        ...(input.params !== undefined ? { params: input.params } : {}),
-      });
-      this.#emitDiagnostics();
+      const sameIntent =
+        existing.table === input.table &&
+        canonicalScopeJson(existing.scopes) ===
+          canonicalScopeJson(input.scopes) &&
+        existing.params === input.params;
+      if (!sameIntent) {
+        throw new ClientSyncError(
+          'client.subscription_intent_mismatch',
+          'subscribe: the subscription id is already registered for a different table, scopes, or params',
+        );
+      }
       return;
     }
     saveSubscription(this.#db, {
@@ -2346,6 +2392,7 @@ export class SyncClient {
       );
     }
     this.#syncOutstanding = true;
+    this.#beginDiagnosticsDeferral();
     const startedAtMs = this.#now();
     return this.#serialize(() => this.#runSync())
       .then(
@@ -2380,6 +2427,7 @@ export class SyncClient {
       )
       .finally(() => {
         this.#syncOutstanding = false;
+        this.#endDiagnosticsDeferral();
       });
   }
 
@@ -2842,12 +2890,20 @@ export class SyncClient {
       string,
       ReadonlyMap<number, RejectionDetails>
     >();
+    let lastFinalPushResult: PushResultFrame | undefined;
     for (const frame of message.frames) {
-      if (frame.type !== 'PUSH_RESULT_DETAILS') continue;
-      rejectionDetailsByCommit.set(
-        frame.clientCommitId,
-        new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])),
-      );
+      if (frame.type === 'PUSH_RESULT_DETAILS') {
+        rejectionDetailsByCommit.set(
+          frame.clientCommitId,
+          new Map(frame.entries.map((entry) => [entry.opIndex, entry.details])),
+        );
+      } else if (
+        frame.type === 'PUSH_RESULT' &&
+        commitsById.has(frame.clientCommitId) &&
+        isFinalPushResult(frame)
+      ) {
+        lastFinalPushResult = frame;
+      }
     }
 
     const header = message.frames[0];
@@ -2879,9 +2935,11 @@ export class SyncClient {
     let section: OpenSection | undefined;
     let errorFrame: ClientSyncError | undefined;
     let deltaCursor = -1;
+    let responseOutboxCount: number | undefined;
 
     // Each durable observer transaction emits its own revisioned batch.
     // Async decrypt/download work happens outside SQLite transactions.
+    this.#beginDiagnosticsDeferral();
     try {
       for (const frame of message.frames.slice(1)) {
         switch (frame.type) {
@@ -2895,17 +2953,26 @@ export class SyncClient {
               expiresAtMs: frame.expiresAtMs,
             });
             break;
-          case 'PUSH_RESULT':
-            this.#applyBatch((batch) =>
-              this.#handlePushResult(
-                frame,
-                commitsById,
-                summary,
-                batch,
-                rejectionDetailsByCommit.get(frame.clientCommitId),
-              ),
+          case 'PUSH_RESULT': {
+            let outboxCount =
+              responseOutboxCount ?? listOutbox(this.#db).length;
+            this.#applyBatch(
+              (batch) => {
+                const drained = this.#handlePushResult(
+                  frame,
+                  commitsById,
+                  summary,
+                  batch,
+                  rejectionDetailsByCommit.get(frame.clientCommitId),
+                  frame === lastFinalPushResult,
+                );
+                if (drained) outboxCount -= 1;
+              },
+              () => this.#statusSnapshot(outboxCount),
             );
+            responseOutboxCount = outboxCount;
             break;
+          }
           case 'PUSH_RESULT_DETAILS':
             // Pre-indexed above so companion ordering remains wire-additive.
             break;
@@ -3103,10 +3170,14 @@ export class SyncClient {
         if (errorFrame !== undefined) break;
       }
     } finally {
-      // §7.1: local reads see outbox state applied optimistically — replay
-      // the still-pending commits on top of the freshly applied server state.
-      this.#replayOutbox();
-      this.#reconcileBlobs(false);
+      try {
+        // §7.1: local reads see outbox state applied optimistically — replay
+        // the still-pending commits on top of the freshly applied server state.
+        this.#replayOutbox();
+        this.#reconcileBlobs(false);
+      } finally {
+        this.#endDiagnosticsDeferral();
+      }
     }
 
     if (errorFrame !== undefined) throw errorFrame;
@@ -3136,9 +3207,10 @@ export class SyncClient {
     summary: MutableSummary,
     batch: ChangeAccumulator,
     rejectionDetails: ReadonlyMap<number, RejectionDetails> | undefined,
-  ): void {
+    pruneOutcomes: boolean,
+  ): boolean {
     const commit = commitsById.get(frame.clientCommitId);
-    if (commit === undefined) return;
+    if (commit === undefined) return false;
     if (frame.status === 'applied' || frame.status === 'cached') {
       // §6.3: applied and cached both drain the outbox — cached means
       // "already applied, you may have missed the ack".
@@ -3152,11 +3224,13 @@ export class SyncClient {
         })),
       });
       deleteOutboxCommit(this.#db, frame.clientCommitId);
-      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+      if (pruneOutcomes) {
+        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+      }
       batch.status();
       batch.outcomes();
       summary.applied.push(frame.clientCommitId);
-      return;
+      return true;
     }
     // rejected
     const cacheMiss = frame.results.some(
@@ -3169,7 +3243,7 @@ export class SyncClient {
       // §6.3: a serving failure, not the commit's outcome — keep the
       // commit queued and retry the identical push later.
       summary.retryable.push(frame.clientCommitId);
-      return;
+      return false;
     }
     const outcomeResults: CommitOperationOutcome[] = [];
     for (const result of frame.results) {
@@ -3218,7 +3292,9 @@ export class SyncClient {
       results: outcomeResults,
       operations: commit.operations,
     });
-    pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+    if (pruneOutcomes) {
+      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+    }
     batch.outcomes();
     // §7.2: remove the rejected optimistic layer. Before-images restore
     // validator-rejected updates even when the server emitted no new COMMIT;
@@ -3228,6 +3304,7 @@ export class SyncClient {
     });
     batch.status();
     summary.rejected.push(frame.clientCommitId);
+    return true;
   }
 
   #decodeServerRow(

package/src/diagnostics.ts

@@ -163,6 +163,10 @@ export type ClientDiagnosticsListener = (
 export class ClientDiagnosticsEmitter {
   readonly #listeners = new Set<ClientDiagnosticsListener>();
 
+  get observed(): boolean {
+    return this.#listeners.size > 0;
+  }
+
   on(listener: ClientDiagnosticsListener): () => void {
     this.#listeners.add(listener);
     return () => this.#listeners.delete(listener);