@spooky-sync/core 0.0.1-canary.352 → 0.0.1-canary.354

package/dist/index.d.ts

@@ -1558,6 +1558,8 @@ declare class Runtime {
   private readonly lastStatus;
   private readonly listeners;
   private readonly scheduledMaterialize;
+  /** When each query last materialized, for the leading-edge throttle in `setState`. */
+  private readonly materializedAt;
   private readonly timerKeys;
   private lastActivity;
   private lastHealth;

package/dist/index.js

@@ -2286,8 +2286,8 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.352";
-const WASM_VERSION = "0.0.1-canary.352";
+const CORE_VERSION = "0.0.1-canary.354";
+const WASM_VERSION = "0.0.1-canary.354";
 const SURREAL_VERSION = "3.1.0";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
@@ -3102,10 +3102,24 @@ const isForegroundFetching = (l) => l.fetchDepth > l.backgroundDepth;
 * `setTimeout`; they yield `timer.set` effects with one of these delays, so a
 * test can pin the schedule by asserting the effect log.
 */
-/** Trailing coalesce for materialization after a state change. */
+/**
+* Minimum gap between two materializations of one query. The first change
+* after a quiet spell materializes on the next tick; changes inside the window
+* fold into one trailing run at its end.
+*/
 const MATERIALIZE_DEBOUNCE_MS = 50;
-/** Coalesce window for LIVE membership dirt before the batched edge re-read. */
+/**
+* Minimum gap between two batched edge re-reads driven by LIVE dirt. Dirt
+* after a quiet spell is read after {@link MEMBERSHIP_LEADING_MS}; dirt inside
+* the window waits for its end.
+*/
 const MEMBERSHIP_COALESCE_MS = 50;
+/**
+* Leading wait before the first re-read of a burst. One edge transaction fans
+* out as a run of notifications landing within a few milliseconds; this folds
+* the run into the first read instead of paying a second round trip for it.
+*/
+const MEMBERSHIP_LEADING_MS = 5;
 /** Re-read ladder while the server reports a view as `materializing`. */
 const MATERIALIZING_REREAD_LADDER_MS = [
 	150,
@@ -5039,9 +5053,14 @@ const stmt$1 = (results, i) => {
 * materializing, no view-lost recovery pending): before that the read decides
 * what the set is. Removals are never applied here, so a view whose edges
 * are being rewritten never loses (and garbage-collects) bodies mid-rewrite.
-* Nor for a query with a `LIMIT`: a row joining it pushes another out, and
-* rendering the joiner before the read removes the leaver would show one row
-* too many (the id-set render drops the `LIMIT`).
+* A query with a `LIMIT` takes it only when every delta is a version bump of
+* a row it already holds. A row JOINING it pushes another out, and rendering
+* the joiner before the read removes the leaver would show one row too many
+* (the id-set render drops the `LIMIT`); a bump cannot change the count. A row
+* that an edit moves out of the window arrives as its own `DELETE`, which still
+* marks the query dirty. Windowed lists are most lists, so this spares the
+* coalesce window and a full round trip on the common case of an edit to a
+* row already on screen.
 */
 function* applyEdgeDeltas(deltas) {
 	const settled = /* @__PURE__ */ new Set();
@@ -5050,7 +5069,10 @@ function* applyEdgeDeltas(deltas) {
 	for (const [hash, list] of byHash) {
 		const entry = yield fx.state.read((s) => s.queries.get(hash));
 		if (!entry || entry.lifecycle.phase !== "live" || entry.serverState === "materializing" || entry.viewLostRetryAt !== null) continue;
-		if (entry.def.plan ? entry.def.plan.limit != null : /\bLIMIT\b/i.test(entry.def.surql)) continue;
+		if (entry.def.plan ? entry.def.plan.limit != null : /\bLIMIT\b/i.test(entry.def.surql)) {
+			const held = new Set(entry.remoteArray.map(([id]) => id));
+			if (!list.every((d) => held.has(d.id))) continue;
+		}
 		const next = withDeltas(entry.remoteArray, list);
 		if (next !== entry.remoteArray) yield* applyMembership(hash, next);
 		settled.add(hash);
@@ -5163,11 +5185,22 @@ function* readMembership(env, hashes, opts = {}) {
 * `_00_list_ref` table (registrations, an import, another tab syncing) the
 * events never stop for a whole 50 ms and the read simply never ran, leaving
 * membership frozen until a poll tick happened to cover it.
+*
+* Leading edge: when none of these queries was read within the last
+* {@link MEMBERSHIP_COALESCE_MS}, the read goes out after the short
+* {@link MEMBERSHIP_LEADING_MS} instead of waiting the whole window. A lone
+* remote edit is the common case, and the full window sat in front of every
+* one of them. Dirt arriving while that read is in flight still gets its own
+* trailing read from {@link readDirtyMembership}, so the cap of one read per
+* window holds.
 */
 function* markMembershipDirty(hashes) {
-	const armed = yield fx.state.read((s) => s.membershipDirty.size > 0);
+	const [armed, lastRead] = yield fx.state.read((s) => [s.membershipDirty.size > 0, hashes.reduce((at, h) => Math.max(at, s.queries.get(h)?.lastPolledAt ?? 0), 0)]);
 	yield fx.state.update(markMembershipDirty$1(hashes));
-	if (!armed) yield fx.timer.set("membership", MEMBERSHIP_COALESCE_MS, { type: "ReadDirtyMembership" });
+	if (armed) return;
+	const now = yield fx.now();
+	const delay = Math.max(MEMBERSHIP_LEADING_MS, lastRead + MEMBERSHIP_COALESCE_MS - now);
+	yield fx.timer.set("membership", delay, { type: "ReadDirtyMembership" });
 }
 function* readDirtyMembership(env) {
 	const dirty = yield fx.state.read((s) => [...s.membershipDirty]);
@@ -7721,6 +7754,8 @@ var Runtime = class {
 	lastStatus = /* @__PURE__ */ new Map();
 	listeners = /* @__PURE__ */ new Map();
 	scheduledMaterialize = /* @__PURE__ */ new Set();
+	/** When each query last materialized, for the leading-edge throttle in `setState`. */
+	materializedAt = /* @__PURE__ */ new Map();
 	timerKeys = /* @__PURE__ */ new Set();
 	lastActivity = {
 		fetching: 0,
@@ -7812,11 +7847,15 @@ var Runtime = class {
 				w.resolve();
 			}
 		}
+		const now = this.adapters.clock.now();
 		for (const hash of next.dirty) {
 			if (this.scheduledMaterialize.has(hash)) continue;
 			this.scheduledMaterialize.add(hash);
-			this.adapters.timers.set(`mat:${hash}`, this.env.materializeDebounceMs, () => {
+			const last = this.materializedAt.get(hash);
+			const delay = last === void 0 ? 0 : Math.max(0, last + this.env.materializeDebounceMs - now);
+			this.adapters.timers.set(`mat:${hash}`, delay, () => {
 				this.scheduledMaterialize.delete(hash);
+				this.materializedAt.set(hash, this.adapters.clock.now());
 				this.dispatch({
 					type: "Materialize",
 					hash
@@ -16030,7 +16069,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.352",
+			coreVersion: "0.0.1-canary.354",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,

package/dist/types.d.ts

@@ -1620,10 +1620,10 @@ interface Sp00kyConfig<S extends SchemaStructure> {
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**
-   * Debounce time in milliseconds for stream updates (the client-side SSP
-   * aggregation throttle — coalesces the in-browser StreamProcessor's
-   * per-record updates per query before notifying readers).
-   * Defaults to 50ms.
+   * Minimum gap in milliseconds between two materializations of one query
+   * (coalesces per-record updates before notifying readers). The first change
+   * after a quiet spell is delivered on the next tick; later ones inside the
+   * window fold into one update at its end. Defaults to 50ms.
    */
   streamDebounceTime?: number;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.352",
+  "version": "0.0.1-canary.354",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.352",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.352",
+    "@spooky-sync/query-builder": "0.0.1-canary.354",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.354",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.1.0",
     "@surrealdb/wasm-native": "^3.3.4",

package/skills/sp00ky-core/SKILL.md

@@ -52,7 +52,7 @@ Key fields:
 - `schemaSurql` — The compiled SURQL schema string for local DB provisioning
 - `logLevel` — `'debug' | 'info' | 'warn' | 'error'`
 - `persistenceClient` — `'surrealdb'` (default), `'localstorage'`, or a custom `PersistenceClient`
-- `streamDebounceTime` — Debounce ms for stream updates (default: 100)
+- `streamDebounceTime` — Minimum gap in ms between re-materializations of one query; the first change after a quiet spell is immediate (default: 50)
 
 ## Querying
 

package/skills/sp00ky-core/references/config.md

@@ -31,7 +31,7 @@ interface Sp00kyConfig<S extends SchemaStructure> {
   persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel) */
   otelTransmit?: PinoTransmit;
-  /** Debounce time in ms for stream updates (default: 100) */
+  /** Minimum gap in ms between re-materializations of one query; first change is immediate (default: 50) */
   streamDebounceTime?: number;
 }
 ```

package/src/client/runtime.test.ts

@@ -90,6 +90,26 @@ describe('Runtime state hooks', () => {
     expect(seen).toEqual([[{ id: 'thing:1' }]]);
     expect(rt.state.dirty.has('q')).toBe(false);
   });
+  it('materializes the first change at once, and holds the next one to the window', async () => {
+    const { a, rt } = make(
+      { local: { select: async () => [{ id: 'thing:1' }] } },
+      buildState([buildEntry({ def: { hash: 'q', plan: { table: 'thing' } as any } })], R.reloadViews(new Map([['v', ['thing:1']]])))
+    );
+    rt.update(R.markDirty(['q']));
+    expect(a.timers.pending.get('mat:q')?.ms).toBe(0);
+    a.timers.fire('mat:q');
+    await tick();
+    await tick();
+    a.advance(2);
+    rt.update(R.markDirty(['q']));
+    expect(a.timers.pending.get('mat:q')?.ms).toBe(3);
+    a.timers.fire('mat:q');
+    await tick();
+    await tick();
+    a.advance(50);
+    rt.update(R.markDirty(['q']));
+    expect(a.timers.pending.get('mat:q')?.ms).toBe(0);
+  });
   it('the bucket-switch window: a re-seeded query never reads "known and idle" before its rows are painted', async () => {
     // A sign-in: the query was registered in the anon bucket (cold, nothing
     // painted), then the switch re-seeds it from the user's durable view.

package/src/client/runtime.ts

@@ -47,6 +47,8 @@ export class Runtime {
   private readonly lastStatus = new Map<QueryHash, QueryStatus>();
   private readonly listeners = new Map<string, Set<(event: OutEvent) => void>>();
   private readonly scheduledMaterialize = new Set<QueryHash>();
+  /** When each query last materialized, for the leading-edge throttle in `setState`. */
+  private readonly materializedAt = new Map<QueryHash, number>();
   private readonly timerKeys = new Set<string>();
   private lastActivity = { fetching: 0, pending: 0 };
   private lastHealth: ClientState['sync']['health'];
@@ -141,11 +143,20 @@ export class Runtime {
         w.resolve();
       }
     }
+    // Throttle with a leading edge: the first change after a quiet spell
+    // materializes on the next tick (a zero delay still folds every state
+    // update of the current turn into it), later ones inside the window fold
+    // into one run at its end. A trailing-only debounce put the whole window
+    // in front of every lone remote edit.
+    const now = this.adapters.clock.now();
     for (const hash of next.dirty) {
       if (this.scheduledMaterialize.has(hash)) continue;
       this.scheduledMaterialize.add(hash);
-      this.adapters.timers.set(`mat:${hash}`, this.env.materializeDebounceMs, () => {
+      const last = this.materializedAt.get(hash);
+      const delay = last === undefined ? 0 : Math.max(0, last + this.env.materializeDebounceMs - now);
+      this.adapters.timers.set(`mat:${hash}`, delay, () => {
         this.scheduledMaterialize.delete(hash);
+        this.materializedAt.set(hash, this.adapters.clock.now());
         void this.dispatch({ type: 'Materialize', hash });
       });
     }

package/src/kernel/constants.ts

@@ -4,10 +4,24 @@
  * test can pin the schedule by asserting the effect log.
  */
 
-/** Trailing coalesce for materialization after a state change. */
+/**
+ * Minimum gap between two materializations of one query. The first change
+ * after a quiet spell materializes on the next tick; changes inside the window
+ * fold into one trailing run at its end.
+ */
 export const MATERIALIZE_DEBOUNCE_MS = 50;
-/** Coalesce window for LIVE membership dirt before the batched edge re-read. */
+/**
+ * Minimum gap between two batched edge re-reads driven by LIVE dirt. Dirt
+ * after a quiet spell is read after {@link MEMBERSHIP_LEADING_MS}; dirt inside
+ * the window waits for its end.
+ */
 export const MEMBERSHIP_COALESCE_MS = 50;
+/**
+ * Leading wait before the first re-read of a burst. One edge transaction fans
+ * out as a run of notifications landing within a few milliseconds; this folds
+ * the run into the first read instead of paying a second round trip for it.
+ */
+export const MEMBERSHIP_LEADING_MS = 5;
 /** Re-read ladder while the server reports a view as `materializing`. */
 export const MATERIALIZING_REREAD_LADDER_MS: readonly number[] = [150, 400, 1000];
 /** How long an acked outbox item stays in the overlay when membership never names it. */

package/src/query/membership.saga.test.ts

@@ -379,7 +379,7 @@ describe('dirty helpers', () => {
     const s = buildState([buildEntry({ def: { hash: 'a' } })]);
     const out = await runPure(markMembershipDirty(['a']), { state: s });
     expect(out.state.membershipDirty.has('a')).toBe(true);
-    expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+    expect(out.timers.get('membership')).toEqual({ ms: 5, event: { type: 'ReadDirtyMembership' } });
     const clean = await runPure(readDirtyMembership(env), { state: s });
     expect(clean.log.filter((e) => e.kind === 'remote.query')).toHaveLength(0);
     const dirty = await runPure(readDirtyMembership(env), {
@@ -389,6 +389,17 @@ describe('dirty helpers', () => {
     expect(dirty.log.filter((e) => e.kind === 'remote.query')).toHaveLength(1);
   });
 
+  it('reads at once after a quiet spell, and waits out the window after a recent read', async () => {
+    const now = 1_000_000;
+    const quiet = await runPure(markMembershipDirty(['a']), { state: buildState([buildEntry({ def: { hash: 'a' }, lastPolledAt: now - 5_000 })]), now });
+    expect(quiet.timers.get('membership')?.ms).toBe(5);
+    const recent = await runPure(markMembershipDirty(['a', 'b']), {
+      state: buildState([buildEntry({ def: { hash: 'a' }, lastPolledAt: now - 30 }), buildEntry({ def: { hash: 'b' }, lastPolledAt: null })]),
+      now,
+    });
+    expect(recent.timers.get('membership')?.ms).toBe(20);
+  });
+
   it('arms the window once per burst, and again for dirt the read left behind', async () => {
     const s = buildState([buildEntry({ def: { hash: 'a' } }), buildEntry({ def: { hash: 'b' } })]);
     const first = await runPure(markMembershipDirty(['a']), { state: s });
@@ -459,6 +470,27 @@ describe('applyEdgeDeltas', () => {
     }
     expect((await runPure(applyEdgeDeltas([{ hash: 'zz', id: 't:2', version: 1 }]), { state: buildState([live()]) })).result.size).toBe(0);
   });
+
+  it('commits a version bump of a held row in a bounded view without reading the edges', async () => {
+    for (const def of [
+      { hash: 'a', viewKey: 'vk', surql: 'SELECT * FROM t ORDER BY at DESC LIMIT 10' },
+      { hash: 'a', viewKey: 'vk', plan: { table: 't', limit: 10 } },
+    ]) {
+      const out = await runPure(applyEdgeDeltas([{ hash: 'a', id: 't:1', version: 4 }]), { state: buildState([live({ def })]), handlers });
+      expect([...out.result]).toEqual(['a']);
+      expect(out.state.queries.get('a')!.remoteArray).toEqual([['t:1', 4]]);
+      expect(out.log.some((e) => e.kind === 'remote.query')).toBe(false);
+    }
+  });
+
+  it('leaves a bounded view to the read when any delta in the batch is a joiner', async () => {
+    const entry = live({ def: { hash: 'a', plan: { table: 't', limit: 10 } } });
+    const out = await runPure(applyEdgeDeltas([{ hash: 'a', id: 't:1', version: 4 }, { hash: 'a', id: 't:2', version: 1 }]), {
+      state: buildState([entry]),
+    });
+    expect(out.result.size).toBe(0);
+    expect(out.state.queries.get('a')!.remoteArray).toEqual([['t:1', 1]]);
+  });
 });
 
 describe('readMembership after a LIVE delta', () => {

package/src/query/membership.saga.ts

@@ -5,6 +5,7 @@ import { fx } from '../kernel/effects';
 import {
   MATERIALIZING_REREAD_LADDER_MS,
   MEMBERSHIP_COALESCE_MS,
+  MEMBERSHIP_LEADING_MS,
   VIEW_LOST_RETRY_BASE_MS,
   VIEW_LOST_RETRY_MAX_MS,
   backoffMs,
@@ -159,9 +160,14 @@ const stmt = (results: unknown, i: number): unknown => {
  * materializing, no view-lost recovery pending): before that the read decides
  * what the set is. Removals are never applied here, so a view whose edges
  * are being rewritten never loses (and garbage-collects) bodies mid-rewrite.
- * Nor for a query with a `LIMIT`: a row joining it pushes another out, and
- * rendering the joiner before the read removes the leaver would show one row
- * too many (the id-set render drops the `LIMIT`).
+ * A query with a `LIMIT` takes it only when every delta is a version bump of
+ * a row it already holds. A row JOINING it pushes another out, and rendering
+ * the joiner before the read removes the leaver would show one row too many
+ * (the id-set render drops the `LIMIT`); a bump cannot change the count. A row
+ * that an edit moves out of the window arrives as its own `DELETE`, which still
+ * marks the query dirty. Windowed lists are most lists, so this spares the
+ * coalesce window and a full round trip on the common case of an edit to a
+ * row already on screen.
  */
 export function* applyEdgeDeltas(deltas: EdgeDelta[]): Saga<Set<QueryHash>> {
   const settled = new Set<QueryHash>();
@@ -170,7 +176,11 @@ export function* applyEdgeDeltas(deltas: EdgeDelta[]): Saga<Set<QueryHash>> {
   for (const [hash, list] of byHash) {
     const entry = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
     if (!entry || entry.lifecycle.phase !== 'live' || entry.serverState === 'materializing' || entry.viewLostRetryAt !== null) continue;
-    if (entry.def.plan ? entry.def.plan.limit != null : /\bLIMIT\b/i.test(entry.def.surql)) continue;
+    const limited = entry.def.plan ? entry.def.plan.limit != null : /\bLIMIT\b/i.test(entry.def.surql);
+    if (limited) {
+      const held = new Set(entry.remoteArray.map(([id]) => id));
+      if (!list.every((d) => held.has(d.id))) continue;
+    }
     const next = withDeltas(entry.remoteArray, list);
     // Never empty, so always applied.
     if (next !== entry.remoteArray) yield* applyMembership(hash, next);
@@ -296,11 +306,25 @@ export function* readMembership(
  * `_00_list_ref` table (registrations, an import, another tab syncing) the
  * events never stop for a whole 50 ms and the read simply never ran, leaving
  * membership frozen until a poll tick happened to cover it.
+ *
+ * Leading edge: when none of these queries was read within the last
+ * {@link MEMBERSHIP_COALESCE_MS}, the read goes out after the short
+ * {@link MEMBERSHIP_LEADING_MS} instead of waiting the whole window. A lone
+ * remote edit is the common case, and the full window sat in front of every
+ * one of them. Dirt arriving while that read is in flight still gets its own
+ * trailing read from {@link readDirtyMembership}, so the cap of one read per
+ * window holds.
  */
 export function* markMembershipDirty(hashes: QueryHash[]): Saga<void> {
-  const armed = (yield fx.state.read((s) => s.membershipDirty.size > 0)) as boolean;
+  const [armed, lastRead] = (yield fx.state.read((s) => [
+    s.membershipDirty.size > 0,
+    hashes.reduce((at, h) => Math.max(at, s.queries.get(h)?.lastPolledAt ?? 0), 0),
+  ])) as [boolean, number];
   yield fx.state.update(R.markMembershipDirty(hashes));
-  if (!armed) yield fx.timer.set('membership', MEMBERSHIP_COALESCE_MS, { type: 'ReadDirtyMembership' });
+  if (armed) return;
+  const now = (yield fx.now()) as number;
+  const delay = Math.max(MEMBERSHIP_LEADING_MS, lastRead + MEMBERSHIP_COALESCE_MS - now);
+  yield fx.timer.set('membership', delay, { type: 'ReadDirtyMembership' });
 }
 
 export function* readDirtyMembership(env: SagaEnv): Saga<void> {

package/src/query/register.saga.test.ts

@@ -225,7 +225,7 @@ describe('registerRemote', () => {
       expect(e.registerAttempts).toBe(0);
       expect(e.lifecycle).toMatchObject({ remote: 'registered', fetchDepth: 0 });
       expect(out.state.membershipDirty.has('a')).toBe(true);
-      expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+      expect(out.timers.get('membership')).toEqual({ ms: 5, event: { type: 'ReadDirtyMembership' } });
       expect(out.dispatched).toContainEqual({ type: 'SyncOutcome', ok: false, error: 'registration read-back failed' });
     }
     const empty = await runPure(registerRemote(env, 'a'), { state: buildState([entry]), handlers: { 'remote.query': () => [] } });

package/src/sync/live.saga.test.ts

@@ -62,7 +62,7 @@ describe('liveChange', () => {
     const out = await runPure(liveChange(env, ['a', 'zz']), { state: { ...s, tabRole: 'leader' } });
     expect([...out.state.membershipDirty]).toEqual(['a']);
     expect(out.state.sync.pollIdleStreak).toBe(0);
-    expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+    expect(out.timers.get('membership')).toEqual({ ms: 5, event: { type: 'ReadDirtyMembership' } });
     expect(out.emitted).toEqual([{ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: ['a'] } }]);
     const solo = await runPure(liveChange(env, ['a']), { state: s });
     expect(solo.emitted).toEqual([]);
@@ -224,6 +224,6 @@ describe('liveChange with edge deltas', () => {
       { state: buildState([live('a'), cold]) }
     );
     expect([...out.state.membershipDirty].sort()).toEqual(['a', 'b']);
-    expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+    expect(out.timers.get('membership')).toEqual({ ms: 5, event: { type: 'ReadDirtyMembership' } });
   });
 });

package/src/types.ts

@@ -251,10 +251,10 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**
-   * Debounce time in milliseconds for stream updates (the client-side SSP
-   * aggregation throttle — coalesces the in-browser StreamProcessor's
-   * per-record updates per query before notifying readers).
-   * Defaults to 50ms.
+   * Minimum gap in milliseconds between two materializations of one query
+   * (coalesces per-record updates before notifying readers). The first change
+   * after a quiet spell is delivered on the next tick; later ones inside the
+   * window fold into one update at its end. Defaults to 50ms.
    */
   streamDebounceTime?: number;
   /**