@spooky-sync/core 0.0.1-alpha.1 → 0.0.1-alpha.2

package/AGENTS.md

@@ -16,7 +16,10 @@ schema.gen.ts (typed schema + SURQL_SCHEMA constant)
 Sp00kyClient<S>  ── facade: every method = one saga run, selector or subscription
        │
        ├── Runtime (client/runtime.ts): one immutable ClientState, lanes, timers,
-       │     subscriptions, dirty -> materialize scheduling
+       │     subscriptions, dirty -> materialize scheduling. `query:status`,
+       │     `activity:changed` and `health:changed` are all notified from here,
+       │     off state transitions - never emitted by a saga, so a change made
+       │     outside a sync round (a socket drop, say) still reaches subscribers
        ├── Sagas (query/ mutation/ sync/ boot/): pure generators yielding effects
        └── Interpreter (kernel/interpreter.ts) -> adapters (services/):
              local store · remote socket · SSP wasm circuit · tabs broker · blobs

package/dist/index.d.ts

@@ -1689,6 +1689,7 @@ declare class Runtime {
   private readonly scheduledMaterialize;
   private readonly timerKeys;
   private lastActivity;
+  private lastHealth;
   private disposed;
   constructor(opts: RuntimeOptions);
   get state(): ClientState;

package/dist/index.js

@@ -1073,8 +1073,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-alpha.1";
-const WASM_VERSION = "0.0.1-alpha.1";
+const CORE_VERSION = "0.0.1-alpha.2";
+const WASM_VERSION = "0.0.1-alpha.2";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -2119,13 +2119,20 @@ const setConnection = (connection) => (s) => s.sync.health.connection === connec
 		}
 	}
 };
-const setHealth = (health) => (s) => ({
+/**
+* Shallow value equality over {@link SyncHealth}. `nextHealth` rebuilds the
+* snapshot on every sync round, so identity alone would report a change each
+* time; the runtime uses identity to decide whether to notify subscribers, and
+* this is what keeps that identity stable while nothing actually moved.
+*/
+const sameHealth = (a, b) => a.status === b.status && a.consecutiveFailures === b.consecutiveFailures && a.everConnected === b.everConnected && a.connection === b.connection && a.kind === b.kind && a.error === b.error;
+const setHealth = (health) => (s) => sameHealth(s.sync.health, health) ? s : {
 	...s,
 	sync: {
 		...s.sync,
 		health
 	}
-});
+};
 const patchSync = (patch) => (s) => ({
 	...s,
 	sync: {
@@ -2807,25 +2814,20 @@ function recordVersionArraysEqual(a, b) {
 function nextHealth(input, ok, error, degradeAfter) {
 	const base = {
 		...input,
-		changed: false,
 		degradedNow: false,
 		recoveredNow: false
 	};
 	if (degradeAfter <= 0) return base;
 	if (ok) {
 		const everConnected = true;
-		if (input.consecutiveFailures === 0) {
-			const changed = !input.health.everConnected;
-			return {
-				...base,
-				hasSyncedOnce: true,
-				health: {
-					...input.health,
-					everConnected
-				},
-				changed
-			};
-		}
+		if (input.consecutiveFailures === 0) return {
+			...base,
+			hasSyncedOnce: true,
+			health: {
+				...input.health,
+				everConnected
+			}
+		};
 		const recovered = input.health.status === "degraded";
 		return {
 			...base,
@@ -2838,7 +2840,6 @@ function nextHealth(input, ok, error, degradeAfter) {
 				error: void 0,
 				everConnected
 			},
-			changed: true,
 			recoveredNow: recovered
 		};
 	}
@@ -2855,7 +2856,6 @@ function nextHealth(input, ok, error, degradeAfter) {
 			kind,
 			error: message
 		},
-		changed: true,
 		degradedNow: true
 	};
 	return {
@@ -5145,10 +5145,6 @@ function* syncOutcome(env, ok, error) {
 		consecutiveFailures: next.consecutiveFailures,
 		hasSyncedOnce: next.hasSyncedOnce
 	})));
-	if (next.changed) yield fx.emit({
-		type: "health:changed",
-		health: next.health
-	});
 	if (next.degradedNow) {
 		yield fx.state.update(patchSync({ selfHealAttempts: 0 }));
 		yield fx.timer.set("heal", selfHealDelayMs(0), { type: "SelfHealTick" });
@@ -5633,11 +5629,13 @@ var Runtime = class {
 		fetching: 0,
 		pending: 0
 	};
+	lastHealth;
 	disposed = false;
 	constructor(opts) {
 		this.env = opts.env;
 		this.logger = opts.logger;
 		this.stateValue = opts.initialState ?? emptyState({ tabId: opts.tabId });
+		this.lastHealth = this.stateValue.sync.health;
 		const timers = opts.adapters.timers;
 		this.adapters = {
 			...opts.adapters,
@@ -5752,6 +5750,13 @@ var Runtime = class {
 				...activity
 			});
 		}
+		if (next.sync.health !== this.lastHealth) {
+			this.lastHealth = next.sync.health;
+			this.notify({
+				type: "health:changed",
+				health: next.sync.health
+			});
+		}
 	}
 	waitFor(until, signal) {
 		try {
@@ -6894,6 +6899,7 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 		try {
 			await withTimeout(this.remote.query("RETURN true"), this.config.heartbeatTimeoutMs, `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`);
 			this.heartbeatFailures = 0;
+			this.setState("connected");
 			this.startHeartbeat();
 		} catch (err) {
 			this.heartbeatFailures++;
@@ -12467,7 +12473,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-alpha.1",
+			coreVersion: "0.0.1-alpha.2",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-alpha.1",
+  "version": "0.0.1-alpha.2",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -63,8 +63,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-alpha.1",
-    "@spooky-sync/ssp-wasm": "0.0.1-alpha.1",
+    "@spooky-sync/query-builder": "0.0.1-alpha.2",
+    "@spooky-sync/ssp-wasm": "0.0.1-alpha.2",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/client/runtime.test.ts

@@ -111,6 +111,20 @@ describe('Runtime state hooks', () => {
     rt.subscribeAuthority('zz', () => missing.push('x'), { immediate: true });
     expect(missing).toEqual([]);
   });
+  it('notifies health on a transport change, and only on a real move', () => {
+    const { rt } = make();
+    const seen: string[] = [];
+    rt.on('health:changed', (e) => seen.push(e.type === 'health:changed' ? e.health.connection : '?'));
+    rt.update(R.setConnection('connected'));
+    rt.update(R.setConnection('connected'));
+    rt.update(R.setConnection('reconnecting'));
+    expect(seen).toEqual(['connected', 'reconnecting']);
+    // A health snapshot rebuilt with the same values must not re-notify.
+    rt.update(R.setHealth({ ...rt.state.sync.health }));
+    expect(seen).toHaveLength(2);
+    rt.update(R.setHealth({ ...rt.state.sync.health, status: 'degraded' }));
+    expect(seen).toHaveLength(3);
+  });
   it('activity, listeners, records subscription bookkeeping, waitFor and dispose', async () => {
     const { a, rt } = make({}, buildState([buildEntry({ def: { hash: 'q' } })]));
     const events: string[] = [];

package/src/client/runtime.ts

@@ -49,12 +49,14 @@ export class Runtime {
   private readonly scheduledMaterialize = new Set<QueryHash>();
   private readonly timerKeys = new Set<string>();
   private lastActivity = { fetching: 0, pending: 0 };
+  private lastHealth: ClientState['sync']['health'];
   private disposed = false;
 
   constructor(opts: RuntimeOptions) {
     this.env = opts.env;
     this.logger = opts.logger;
     this.stateValue = opts.initialState ?? emptyState({ tabId: opts.tabId });
+    this.lastHealth = this.stateValue.sync.health;
     const timers = opts.adapters.timers;
     this.adapters = {
       ...opts.adapters,
@@ -161,6 +163,15 @@ export class Runtime {
       this.lastActivity = activity;
       this.notify({ type: 'activity:changed', ...activity });
     }
+    // Health is notified from here, not from the saga that folds a sync round:
+    // `connection` moves through `setConnection` on a transport event with no
+    // round attached, and a subscriber that only heard the round would show a
+    // stale socket state forever. `setHealth` keeps the identity stable while
+    // the values are unchanged, so this fires exactly on real transitions.
+    if (next.sync.health !== this.lastHealth) {
+      this.lastHealth = next.sync.health;
+      this.notify({ type: 'health:changed', health: next.sync.health });
+    }
   }
 
   waitFor(until: (s: ClientState) => boolean, signal?: AbortSignal): Promise<void> {

package/src/services/database/connection-supervisor.test.ts

@@ -229,6 +229,35 @@ describe('ConnectionSupervisor', () => {
     sup.dispose();
   });
 
+  it('un-sticks the forced offline state when the SDK slept through the outage', async () => {
+    const listeners = new Map<string, Array<() => void>>();
+    vi.stubGlobal('window', {
+      addEventListener: (e: string, cb: () => void) => {
+        listeners.set(e, [...(listeners.get(e) ?? []), cb]);
+      },
+      removeEventListener: () => {},
+    });
+    const { remote, emit } = makeRemote();
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    // The browser reports offline, but the SDK's own socket never notices: its
+    // status stays `connected` throughout, so it emits no transition at all.
+    listeners.get('offline')?.forEach((cb) => cb());
+    expect(sup.connection).toBe('disconnected');
+
+    // Back online. Nothing but the probe can correct the forced state here -
+    // there is no SDK event coming - and traffic flowing under a permanent
+    // "offline" indicator is exactly the bug.
+    listeners.get('online')?.forEach((cb) => cb());
+    await vi.advanceTimersByTimeAsync(10);
+    expect(remote.query).toHaveBeenCalled();
+    expect(sup.connection).toBe('connected');
+
+    sup.dispose();
+  });
+
   it('probes immediately when a hidden tab becomes visible', async () => {
     const listeners = new Map<string, Array<() => void>>();
     vi.stubGlobal('document', {

package/src/services/database/connection-supervisor.ts

@@ -286,6 +286,13 @@ export class ConnectionSupervisor {
         `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`
       );
       this.heartbeatFailures = 0;
+      // A round trip is the strongest evidence there is that the socket works,
+      // so it also RECONCILES the reported state. The `offline` handler forces
+      // `disconnected` without the SDK's agreement; if the SDK never noticed
+      // the outage it emits no transition when the network returns, and that
+      // forced state would otherwise stick for the life of the page - traffic
+      // flowing while every indicator says offline.
+      this.setState('connected');
       this.startHeartbeat();
     } catch (err) {
       this.heartbeatFailures++;

package/src/state/reducers.ts

@@ -447,9 +447,23 @@ export const setConnection =
   (s) =>
     s.sync.health.connection === connection ? s : { ...s, sync: { ...s.sync, health: { ...s.sync.health, connection } } };
 
+/**
+ * Shallow value equality over {@link SyncHealth}. `nextHealth` rebuilds the
+ * snapshot on every sync round, so identity alone would report a change each
+ * time; the runtime uses identity to decide whether to notify subscribers, and
+ * this is what keeps that identity stable while nothing actually moved.
+ */
+export const sameHealth = (a: SyncHealth, b: SyncHealth): boolean =>
+  a.status === b.status &&
+  a.consecutiveFailures === b.consecutiveFailures &&
+  a.everConnected === b.everConnected &&
+  a.connection === b.connection &&
+  a.kind === b.kind &&
+  a.error === b.error;
+
 export const setHealth =
   (health: SyncHealth): Reducer =>
-  (s) => ({ ...s, sync: { ...s.sync, health } });
+  (s) => (sameHealth(s.sync.health, health) ? s : { ...s, sync: { ...s.sync, health } });
 
 export const patchSync =
   (patch: Partial<Omit<ClientState['sync'], 'health'>>): Reducer =>

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

@@ -44,15 +44,17 @@ describe('syncOutcome', () => {
     expect(state.sync.health.status).toBe('healthy');
     const third = await runPure(syncOutcome(env, false, new Error('socket')), { state });
     expect(third.state.sync.health.status).toBe('degraded');
-    expect(third.emitted).toEqual([{ type: 'health:changed', health: third.state.sync.health }]);
+    // The saga emits nothing: the runtime notifies `health:changed` off the
+    // health object's identity, which `setHealth` only replaces on a real move.
+    expect(third.emitted).toEqual([]);
     expect(third.timers.get('heal')).toEqual({ ms: 2000, event: { type: 'SelfHealTick' } });
     expect(third.state.sync.selfHealAttempts).toBe(0);
     const back = await runPure(syncOutcome(env, true), { state: third.state });
     expect(back.state.sync.health.status).toBe('healthy');
-    expect(back.emitted).toHaveLength(1);
+    expect(back.state.sync.health).not.toBe(third.state.sync.health);
     expect(back.log.some((e) => e.kind === 'timer.clear' && (e as any).key === 'heal')).toBe(true);
     const quiet = await runPure(syncOutcome(env, true), { state: back.state });
-    expect(quiet.emitted).toEqual([]);
+    expect(quiet.state.sync.health).toBe(back.state.sync.health);
   });
 });
 

package/src/sync/connection.saga.ts

@@ -50,7 +50,6 @@ export function* syncOutcome(env: SagaEnv, ok: boolean, error?: unknown): Saga<v
   yield fx.state.update(
     R.compose(R.setHealth(next.health), R.patchSync({ consecutiveFailures: next.consecutiveFailures, hasSyncedOnce: next.hasSyncedOnce }))
   );
-  if (next.changed) yield fx.emit({ type: 'health:changed', health: next.health });
   if (next.degradedNow) {
     yield fx.state.update(R.patchSync({ selfHealAttempts: 0 }));
     yield fx.timer.set('heal', selfHealDelayMs(0), { type: 'SelfHealTick' });

package/src/sync/policy.health.test.ts

@@ -1,21 +1,22 @@
 import { describe, expect, it } from 'vitest';
 import { nextHealth, selfHealDelayMs } from './policy';
 import { initialHealth } from '../state/client-state';
+import { sameHealth } from '../state/reducers';
 
 const start = { health: initialHealth('connected'), consecutiveFailures: 0, hasSyncedOnce: false };
 
 describe('nextHealth', () => {
   it('disabled reporting never changes anything', () => {
     const out = nextHealth(start, false, new Error('x'), 0);
-    expect(out).toMatchObject({ ...start, changed: false, degradedNow: false, recoveredNow: false });
+    expect(out).toMatchObject({ ...start, degradedNow: false, recoveredNow: false });
   });
   it('first success latches everConnected and hasSyncedOnce', () => {
     const out = nextHealth(start, true, undefined, 3);
     expect(out.health.everConnected).toBe(true);
     expect(out.hasSyncedOnce).toBe(true);
-    expect(out.changed).toBe(true);
+    // A second success moves nothing, so the runtime must not re-notify.
     const again = nextHealth(out, true, undefined, 3);
-    expect(again.changed).toBe(false);
+    expect(sameHealth(again.health, out.health)).toBe(true);
   });
   it('failures accumulate, degrade at the threshold once, recover on success', () => {
     let s = nextHealth(start, false, new Error('socket closed'), 3);
@@ -30,7 +31,6 @@ describe('nextHealth', () => {
     expect(s.health.consecutiveFailures).toBe(3);
     s = nextHealth(s, false, new Error('timeout'), 3);
     expect(s.degradedNow).toBe(false);
-    expect(s.changed).toBe(false);
     expect(s.consecutiveFailures).toBe(4);
     const r = nextHealth(s, true, undefined, 3);
     expect(r.health.status).toBe('healthy');
@@ -42,7 +42,7 @@ describe('nextHealth', () => {
     const s = nextHealth(start, false, new Error('x'), 3);
     const r = nextHealth(s, true, undefined, 3);
     expect(r.recoveredNow).toBe(false);
-    expect(r.changed).toBe(true);
+    expect(r.consecutiveFailures).toBe(0);
   });
 });
 

package/src/sync/policy.ts

@@ -452,8 +452,6 @@ export interface HealthInput {
 }
 
 export interface HealthOutput extends HealthInput {
-  /** The health changed in a way subscribers must hear about. */
-  changed: boolean;
   /** Crossed into degraded on this outcome: start self-heal. */
   degradedNow: boolean;
   /** Left degraded on this outcome: stop self-heal. */
@@ -466,13 +464,12 @@ export interface HealthOutput extends HealthInput {
  * back. `degradeAfter <= 0` disables reporting.
  */
 export function nextHealth(input: HealthInput, ok: boolean, error: unknown, degradeAfter: number): HealthOutput {
-  const base = { ...input, changed: false, degradedNow: false, recoveredNow: false };
+  const base = { ...input, degradedNow: false, recoveredNow: false };
   if (degradeAfter <= 0) return base;
   if (ok) {
     const everConnected = true;
     if (input.consecutiveFailures === 0) {
-      const changed = !input.health.everConnected;
-      return { ...base, hasSyncedOnce: true, health: { ...input.health, everConnected }, changed };
+      return { ...base, hasSyncedOnce: true, health: { ...input.health, everConnected } };
     }
     const recovered = input.health.status === 'degraded';
     return {
@@ -480,7 +477,6 @@ export function nextHealth(input: HealthInput, ok: boolean, error: unknown, degr
       hasSyncedOnce: true,
       consecutiveFailures: 0,
       health: { ...input.health, status: 'healthy', kind: undefined, error: undefined, everConnected },
-      changed: true,
       recoveredNow: recovered,
     };
   }
@@ -492,7 +488,6 @@ export function nextHealth(input: HealthInput, ok: boolean, error: unknown, degr
       ...base,
       consecutiveFailures,
       health: { ...input.health, status: 'degraded', consecutiveFailures, kind, error: message },
-      changed: true,
       degradedNow: true,
     };
   }