@spooky-sync/core 0.0.1-canary.29 → 0.0.1-canary.290

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

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { connectionChanged, selfHealTick, syncOutcome } from './connection.saga';
+
+const env = defaultEnv({ tables: [] } as any);
+
+describe('connectionChanged', () => {
+  it('a drop arms resubscribe and invalidates LIVE; the initial connect does nothing else', async () => {
+    const s = R.patchSync({ liveUuid: 'u', liveTable: 't' })(buildState());
+    const dropped = await runPure(connectionChanged(env, 'reconnecting'), { state: s });
+    expect(dropped.state.sync).toMatchObject({ needsResubscribe: true, liveUuid: null, health: { connection: 'reconnecting' } });
+    const first = await runPure(connectionChanged(env, 'connected'), { state: buildState() });
+    expect(first.dispatched).toEqual([]);
+    const connecting = await runPure(connectionChanged(env, 'connecting'), { state: dropped.state });
+    expect(connecting.dispatched).toEqual([]);
+  });
+  it('reconnect after a drop drops every registration and re-drives, once per cooldown window', async () => {
+    const s = R.patchSync({ needsResubscribe: true })(
+      buildState([
+        buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'registered' } }),
+        buildEntry({ def: { hash: 'b' }, lifecycle: { remote: 'failed' } }),
+        buildEntry({ def: { hash: 'c' } }),
+      ])
+    );
+    const out = await runPure(connectionChanged(env, 'connected'), { state: s, now: 1000 });
+    expect([...out.state.queries.values()].map((e) => e.lifecycle.remote)).toEqual(['unregistered', 'unregistered', 'unregistered']);
+    expect(out.state.sync).toMatchObject({ needsResubscribe: false, lastReconnectRefetchAt: 1000 });
+    expect(out.dispatched).toEqual([{ type: 'EnsureRegistered', requireAuth: true }, { type: 'LiveStart' }, { type: 'Drain' }]);
+    const burst = await runPure(connectionChanged(env, 'connected'), { state: R.patchSync({ needsResubscribe: true })(out.state), now: 5000 });
+    expect(burst.dispatched).toEqual([]);
+    expect(burst.state.sync.needsResubscribe).toBe(false);
+    const later = await runPure(connectionChanged(env, 'connected'), { state: R.patchSync({ needsResubscribe: true })(out.state), now: 20_000 });
+    expect(later.dispatched).toHaveLength(3);
+  });
+});
+
+describe('syncOutcome', () => {
+  it('degrades after the threshold (arming self-heal), recovers on success (disarming it)', async () => {
+    let state = buildState();
+    for (let i = 0; i < 2; i++) state = (await runPure(syncOutcome(env, false, new Error('socket')), { state })).state;
+    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');
+    // 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.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.state.sync.health).toBe(back.state.sync.health);
+  });
+});
+
+describe('selfHealTick', () => {
+  const degraded = (s: ReturnType<typeof buildState>) =>
+    R.compose(R.setHealth({ ...s.sync.health, status: 'degraded' }), R.patchSync({ selfHealAttempts: 1 }))(s);
+  it('does nothing when healthy; drains first, then re-registers (failed included), else probes; always re-arms', async () => {
+    expect((await runPure(selfHealTick(env), { state: buildState() })).timers.size).toBe(0);
+    const withOutbox = await runPure(selfHealTick(env), { state: degraded(buildState([], R.outboxReplace([buildOutboxItem()]))) });
+    expect(withOutbox.dispatched).toEqual([{ type: 'Drain' }]);
+    expect(withOutbox.timers.get('heal')).toEqual({ ms: 8000, event: { type: 'SelfHealTick' } });
+    const withFailed = await runPure(selfHealTick(env), { state: degraded(buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'failed' } })])) });
+    expect(withFailed.state.queries.get('a')!.lifecycle.remote).toBe('unregistered');
+    expect(withFailed.dispatched).toEqual([{ type: 'EnsureRegistered', requireAuth: true }]);
+    const withDesired = await runPure(selfHealTick(env), { state: degraded(buildState([buildEntry({ def: { hash: 'a' } })])) });
+    expect(withDesired.dispatched).toEqual([{ type: 'EnsureRegistered', requireAuth: true }]);
+    const probe = await runPure(selfHealTick(env), { state: degraded(buildState()), handlers: { 'remote.query': () => [{ status: 'OK', result: true }] } });
+    expect(probe.dispatched).toEqual([{ type: 'SyncOutcome', ok: true }]);
+    const probeFail = await runPure(selfHealTick(env), {
+      state: degraded(buildState()),
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(probeFail.dispatched).toEqual([{ type: 'SyncOutcome', ok: false, error: new Error('offline') }]);
+  });
+});

package/src/sync/connection.saga.ts

@@ -0,0 +1,85 @@
+import type { ConnectionState } from '../types';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import { RECONNECT_REFETCH_COOLDOWN_MS } from '../kernel/constants';
+import type { ClientState } from '../state/client-state';
+import * as R from '../state/reducers';
+import { desiredRegistrations, pendingMutationCount } from '../state/selectors';
+import type { SagaEnv } from '../query/env';
+import { liveInvalidate } from './live.saga';
+import { nextHealth, selfHealDelayMs } from './policy';
+
+/**
+ * Transport state changes. A drop invalidates the live query and arms a
+ * resubscribe; the next `connected` (outside the burst cooldown) drops every
+ * remote registration so `ensureRegistered` rebuilds them behind the
+ * `$auth.id` gate, and restarts LIVE.
+ */
+export function* connectionChanged(env: SagaEnv, connection: ConnectionState): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  yield fx.state.update(R.setConnection(connection));
+  if (connection === 'disconnected' || connection === 'reconnecting') {
+    yield fx.state.update(R.patchSync({ needsResubscribe: true }));
+    yield* liveInvalidate();
+    return;
+  }
+  if (connection !== 'connected' || !state.sync.needsResubscribe) return;
+  const now = (yield fx.now()) as number;
+  const last = state.sync.lastReconnectRefetchAt;
+  if (last !== null && now - last < RECONNECT_REFETCH_COOLDOWN_MS) {
+    yield fx.state.update(R.patchSync({ needsResubscribe: false }));
+    return;
+  }
+  yield fx.state.update(
+    R.compose(
+      R.patchSync({ needsResubscribe: false, lastReconnectRefetchAt: now }),
+      ...[...state.queries.values()]
+        .filter((e) => e.lifecycle.remote !== 'unregistered')
+        .map((e) => R.applyLifecycle(e.def.hash, { type: 'remote-dropped' }))
+    )
+  );
+  yield fx.dispatch({ type: 'EnsureRegistered', requireAuth: true });
+  yield fx.dispatch({ type: 'LiveStart' });
+  yield fx.dispatch({ type: 'Drain' });
+}
+
+/** Fold one sync round's outcome into health; start / stop self-heal. */
+export function* syncOutcome(env: SagaEnv, ok: boolean, error?: unknown): Saga<void> {
+  const sync = (yield fx.state.read((s) => s.sync)) as ClientState['sync'];
+  const next = nextHealth({ health: sync.health, consecutiveFailures: sync.consecutiveFailures, hasSyncedOnce: sync.hasSyncedOnce }, ok, error, env.degradeAfter);
+  yield fx.state.update(
+    R.compose(R.setHealth(next.health), R.patchSync({ consecutiveFailures: next.consecutiveFailures, hasSyncedOnce: next.hasSyncedOnce }))
+  );
+  if (next.degradedNow) {
+    yield fx.state.update(R.patchSync({ selfHealAttempts: 0 }));
+    yield fx.timer.set('heal', selfHealDelayMs(0), { type: 'SelfHealTick' });
+  }
+  if (next.recoveredNow) yield fx.timer.clear('heal');
+}
+
+/**
+ * While degraded: re-drive whatever can prove the server is back, on a
+ * growing backoff. Retry the outbox first, then the registrations (failed
+ * ones included, behind the identity gate), else a bare probe.
+ */
+export function* selfHealTick(env: SagaEnv): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  if (state.sync.health.status !== 'degraded') return;
+  const attempt = state.sync.selfHealAttempts + 1;
+  yield fx.state.update(R.patchSync({ selfHealAttempts: attempt }));
+  const failed = [...state.queries.values()].filter((e) => e.lifecycle.remote === 'failed').map((e) => e.def.hash);
+  if (pendingMutationCount(state) > 0) {
+    yield fx.dispatch({ type: 'Drain' });
+  } else if (desiredRegistrations(state).length > 0 || failed.length > 0) {
+    if (failed.length > 0) yield fx.state.update(R.compose(...failed.map((h) => R.applyLifecycle(h, { type: 'remote-dropped' }))));
+    yield fx.dispatch({ type: 'EnsureRegistered', requireAuth: true });
+  } else {
+    try {
+      yield fx.remote.query('RETURN true', undefined, env.remoteTimeoutMs);
+      yield fx.dispatch({ type: 'SyncOutcome', ok: true });
+    } catch (error) {
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+    }
+  }
+  yield fx.timer.set('heal', selfHealDelayMs(attempt), { type: 'SelfHealTick' });
+}

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

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { liveChange, liveInvalidate, liveStart } from './live.saga';
+import { rowOfEdge } from '../client/services';
+
+const env = defaultEnv({ tables: [] } as any);
+
+describe('liveStart', () => {
+  it('subscribes on the session table and records the uuid; no-op when already on it; followers never subscribe', async () => {
+    const out = await runPure(liveStart(env), { state: { ...buildState(), userId: 'user:abc' }, handlers: { 'remote.live': (e: any) => `uuid-${e.table}` } });
+    expect(out.state.sync).toMatchObject({ liveUuid: 'uuid-_00_list_ref_user_abc', liveTable: '_00_list_ref_user_abc' });
+    const same = await runPure(liveStart(env), { state: out.state });
+    expect(same.log.filter((e) => e.kind === 'remote.live')).toHaveLength(0);
+    const follower = await runPure(liveStart(env), { state: { ...buildState(), tabRole: 'follower' } });
+    expect(follower.log.filter((e) => e.kind === 'remote.live')).toHaveLength(0);
+  });
+  it('kills the previous subscription when connected (ignoring kill errors), tolerates a failing subscribe', async () => {
+    const prev = R.compose(R.patchSync({ liveUuid: 'old', liveTable: '_00_list_ref' }), R.setConnection('connected'))({ ...buildState(), userId: 'user:x' });
+    const killed: string[] = [];
+    const out = await runPure(liveStart(env), {
+      state: prev,
+      handlers: {
+        'remote.kill': (e: any) => {
+          killed.push(e.uuid);
+          throw new Error('gone');
+        },
+        'remote.live': () => 'new',
+      },
+    });
+    expect(killed).toEqual(['old']);
+    expect(out.state.sync.liveUuid).toBe('new');
+    const clean = await runPure(liveStart(env), { state: prev, handlers: { 'remote.kill': () => undefined, 'remote.live': () => 'new2' } });
+    expect(clean.state.sync.liveUuid).toBe('new2');
+    expect(clean.emitted).toEqual([]);
+    const offline = R.patchSync({ liveUuid: 'old', liveTable: '_00_list_ref' })({ ...buildState(), userId: 'user:x' });
+    const noKill = await runPure(liveStart(env), {
+      state: offline,
+      handlers: {
+        'remote.live': () => {
+          throw new Error('not connected');
+        },
+      },
+    });
+    expect(noKill.log.filter((e) => e.kind === 'remote.kill')).toHaveLength(0);
+    expect(noKill.state.sync.liveUuid).toBeNull();
+    expect(noKill.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
+  });
+  it('liveInvalidate clears the bookkeeping', async () => {
+    const out = await runPure(liveInvalidate(), { state: R.patchSync({ liveUuid: 'u', liveTable: 't' })(buildState()) });
+    expect(out.state.sync).toMatchObject({ liveUuid: null, liveTable: null });
+  });
+});
+
+describe('liveChange', () => {
+  it('marks known hashes dirty, resets the poll streak, relays as leader; ignores unknown hashes', async () => {
+    const s = R.patchSync({ pollIdleStreak: 3 })(buildState([buildEntry({ def: { hash: 'a' } })]));
+    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.emitted).toEqual([{ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: ['a'] } }]);
+    const solo = await runPure(liveChange(env, ['a']), { state: s });
+    expect(solo.emitted).toEqual([]);
+    const none = await runPure(liveChange(env, ['zz']), { state: s });
+    expect(none.timers.size).toBe(0);
+  });
+
+  it('pulls a backed-off poll back to the base cadence, and leaves an already-base one alone', async () => {
+    const entry = buildEntry({ def: { hash: 'a' } });
+    // Coasted up to the cap: the armed timer is the reason a change the poll
+    // has to catch could wait 5s, so the event has to re-arm it, not just zero
+    // the streak the next tick would read.
+    const backedOff = R.patchSync({ pollIdleStreak: 4 })(buildState([entry]));
+    const out = await runPure(liveChange(env, ['a']), { state: backedOff });
+    expect(out.timers.get('poll')).toEqual({ ms: env.pollBaseMs, event: { type: 'PollTick' } });
+
+    // Already at base: re-arming here would push the poll out by another
+    // `pollBaseMs` on every notification and starve it under sustained LIVE.
+    const atBase = R.patchSync({ pollIdleStreak: 0 })(buildState([entry]));
+    const quiet = await runPure(liveChange(env, ['a']), { state: atBase });
+    expect(quiet.timers.has('poll')).toBe(false);
+    expect(quiet.state.membershipDirty.has('a')).toBe(true);
+
+    // An unknown hash is not activity: nothing is touched.
+    const unknown = await runPure(liveChange(env, ['zz']), { state: backedOff });
+    expect(unknown.timers.has('poll')).toBe(false);
+    expect(unknown.state.sync.pollIdleStreak).toBe(4);
+  });
+});
+
+describe('rowOfEdge', () => {
+  const rid = new RecordId('game', 'g1');
+
+  it('reads the joined body off the notification', () => {
+    expect(rowOfEdge({ in: new RecordId('_00_query', 'a'), out: { id: rid, result: '1-0' }, version: 7 })).toEqual({
+      id: 'game:g1',
+      version: 7,
+      record: { id: rid, result: '1-0' },
+    });
+  });
+
+  it('yields nothing when there is no body to read', () => {
+    // No FETCH clause: `out` is still just the record id.
+    expect(rowOfEdge({ out: rid, version: 7 })).toBeNull();
+    // The session may not read the row, or its target is gone.
+    expect(rowOfEdge({ out: null, version: 7 })).toBeNull();
+    // A body with no version cannot be placed against what we already hold.
+    expect(rowOfEdge({ out: { id: rid }, version: undefined })).toBeNull();
+    // `landChunk` keys off a real RecordId; a string id would record the
+    // version for a body it never wrote.
+    expect(rowOfEdge({ out: { id: 'game:g1' }, version: 7 })).toBeNull();
+    expect(rowOfEdge(null)).toBeNull();
+  });
+});
+
+describe('liveChange with the body joined on', () => {
+  const rid = new RecordId('game', 'g1');
+  const row = (version: number) => ({ id: 'game:g1', version, record: { id: rid, result: '1-0' } });
+  const handlers = { 'local.execute': () => undefined, 'ssp.ingest': () => undefined };
+
+  it('lands the pushed body so the fetch plan has nothing left to pull', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a'], [row(7)]), { state: s, handlers });
+
+    // Recorded at the edge's version: this is what makes `planFetch` skip it.
+    expect(out.state.versions.get('game:g1')).toBe(7);
+    // Written to the store and ingested into the circuit, exactly as a fetch would.
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(1);
+    expect(out.log.filter((e) => e.kind === 'ssp.ingest')).toHaveLength(1);
+    // Still a doorbell: membership is re-read regardless.
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+  });
+
+  it('ignores a body we already hold at that version or newer', async () => {
+    const s = R.setVersions([['game:g1', 7]])(buildState([buildEntry({ def: { hash: 'a' } })]));
+    const out = await runPure(liveChange(env, ['a'], [row(7)]), { state: s, handlers });
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(0);
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+  });
+
+  it('leaves a failed inline body for the fetch path without advancing its version', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a'], [row(7)]), {
+      state: s,
+      handlers: {
+        'local.execute': () => { throw new Error('stale local epoch'); },
+      },
+    });
+    expect(out.state.versions.has('game:g1')).toBe(false);
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+    expect(out.log.filter((e) => e.kind === 'ssp.ingest')).toHaveLength(0);
+    expect(out.emitted).toContainEqual({
+      type: 'log',
+      level: 'debug',
+      message: 'inline live body not landed; the fetch path will pull it',
+      data: { ids: ['game:g1'] },
+    });
+  });
+
+  it('writes one copy when the same row arrives for several views', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a'], [row(7), row(7), row(8)]), { state: s, handlers });
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(1);
+    expect(out.state.versions.get('game:g1')).toBe(8);
+  });
+
+  it('behaves exactly as before when no body rode along', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a']), { state: s, handlers });
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(0);
+    expect(out.state.versions.size).toBe(0);
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+  });
+});

package/src/sync/live.saga.ts

@@ -0,0 +1,107 @@
+import type { InlineRow, QueryHash } from '../types';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import type { ClientState } from '../state/client-state';
+import * as R from '../state/reducers';
+import type { SagaEnv } from '../query/env';
+import { listRefTable } from '../query/env';
+import { markMembershipDirty } from '../query/membership.saga';
+import { landChunk } from '../query/fetch.saga';
+
+/**
+ * LIVE on the session's `_00_list_ref` table. An event marks its query's
+ * membership dirty and the batched re-read decides; followers get the same
+ * dirt relayed by the leader.
+ *
+ * When the subscription was opened with the body joined on
+ * (`liveInlineBodies`) the event ALSO carries the changed row. That is an
+ * optimisation on top, never a source of truth: the row is landed exactly as a
+ * fetched body would be, so a notification the server drops costs nothing but
+ * the round trip it would have saved.
+ */
+export function* liveStart(env: SagaEnv): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  if (state.tabRole === 'follower') return;
+  const table = listRefTable(env, state);
+  if (state.sync.liveUuid && state.sync.liveTable === table) return;
+  if (state.sync.liveUuid && state.sync.health.connection === 'connected') {
+    try {
+      yield fx.remote.kill(state.sync.liveUuid);
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'debug', message: 'kill of the previous live query failed', data: { error } });
+    }
+  }
+  yield fx.state.update(R.patchSync({ liveUuid: null, liveTable: null }));
+  try {
+    const uuid = (yield fx.remote.live(table)) as string;
+    yield fx.state.update(R.patchSync({ liveUuid: uuid, liveTable: table }));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'live subscription failed; the poll covers membership', data: { table, error } });
+  }
+}
+
+/** The socket dropped: the server-side live query is gone with it. */
+export function* liveInvalidate(): Saga<void> {
+  yield fx.state.update(R.patchSync({ liveUuid: null, liveTable: null }));
+}
+
+/** One or more edges of these queries changed on the server. */
+export function* liveChange(env: SagaEnv, hashes: QueryHash[], rows?: InlineRow[]): Saga<void> {
+  const [known, role, streak] = (yield fx.state.read((s) => [hashes.filter((h) => s.queries.has(h)), s.tabRole, s.sync.pollIdleStreak])) as [
+    QueryHash[],
+    ClientState['tabRole'],
+    number,
+  ];
+  if (known.length === 0) return;
+  // Zeroing the streak only decides the delay the NEXT tick picks: `pollTick`
+  // arms its timer at the end of a tick, so a page that had coasted up to the
+  // 5s cap still waited out that armed timer. When the poll is the thing that
+  // catches a change (a notification the server dropped, a row LIVE never
+  // carried) that made the worst case 5s even though LIVE had just proved the
+  // page was active. Re-arm at the base cadence too, so the safety net is back
+  // under us immediately.
+  //
+  // Only when the poll had actually backed off. A `set` on the same key
+  // replaces the pending timer, so re-arming on every event while LIVE is
+  // delivering faster than `pollBaseMs` would push the poll out forever and
+  // starve the full-membership reconciliation it exists to provide. A streak
+  // of 0 means the cadence is already base and there is nothing to correct.
+  if (streak > 0) {
+    yield fx.state.update(R.patchSync({ pollIdleStreak: 0 }));
+    yield fx.timer.set('poll', env.pollBaseMs, { type: 'PollTick' });
+  }
+  // Before marking membership dirty: recording the version here is what makes
+  // the re-read's `planFetch` find nothing left to pull for this row.
+  if (rows && rows.length > 0) yield* landInlineRows(env, rows);
+  yield* markMembershipDirty(known);
+  if (role === 'leader') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: known } });
+}
+
+/**
+ * Land bodies that rode in on the notification. Rows already held at this
+ * version or newer are dropped: one edit bumps the edge in every view holding
+ * the row, so the same body arrives once per view.
+ */
+function* landInlineRows(env: SagaEnv, rows: InlineRow[]): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  const fresh = new Map<string, InlineRow>();
+  for (const row of rows) {
+    if ((state.versions.get(row.id) ?? -1) >= row.version) continue;
+    const held = fresh.get(row.id);
+    if (!held || held.version < row.version) fresh.set(row.id, row);
+  }
+  if (fresh.size === 0) return;
+  const picked = [...fresh.values()];
+  const epoch = (yield fx.local.epoch()) as number;
+  const landed = yield* landChunk(
+    env,
+    picked.map((r) => r.id),
+    picked.map((r) => r.record),
+    new Map(picked.map((r) => [r.id, r.version] as const)),
+    state,
+    epoch
+  );
+  if (!landed) {
+    yield fx.emit({ type: 'log', level: 'debug', message: 'inline live body not landed; the fetch path will pull it', data: { ids: picked.map((r) => r.id) } });
+  }
+}

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

@@ -0,0 +1,56 @@
+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, 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);
+    // A second success moves nothing, so the runtime must not re-notify.
+    const again = nextHealth(out, true, undefined, 3);
+    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);
+    expect(s.health.status).toBe('healthy');
+    expect(s.consecutiveFailures).toBe(1);
+    expect(s.health.kind).toBe('network');
+    s = nextHealth(s, false, 'permission denied', 3);
+    expect(s.health.kind).toBe('application');
+    s = nextHealth(s, false, new Error('timeout'), 3);
+    expect(s.health.status).toBe('degraded');
+    expect(s.degradedNow).toBe(true);
+    expect(s.health.consecutiveFailures).toBe(3);
+    s = nextHealth(s, false, new Error('timeout'), 3);
+    expect(s.degradedNow).toBe(false);
+    expect(s.consecutiveFailures).toBe(4);
+    const r = nextHealth(s, true, undefined, 3);
+    expect(r.health.status).toBe('healthy');
+    expect(r.recoveredNow).toBe(true);
+    expect(r.health.kind).toBeUndefined();
+    expect(r.consecutiveFailures).toBe(0);
+  });
+  it('a success after sub-threshold failures resets without a recovery flag', () => {
+    const s = nextHealth(start, false, new Error('x'), 3);
+    const r = nextHealth(s, true, undefined, 3);
+    expect(r.recoveredNow).toBe(false);
+    expect(r.consecutiveFailures).toBe(0);
+  });
+});
+
+describe('selfHealDelayMs', () => {
+  it('doubles from 2s and caps at 30s', () => {
+    expect(selfHealDelayMs(0)).toBe(2000);
+    expect(selfHealDelayMs(2)).toBe(8000);
+    expect(selfHealDelayMs(10)).toBe(30000);
+    expect(selfHealDelayMs(100)).toBe(30000);
+  });
+});