@spooky-sync/core 0.0.1-canary.31 → 0.0.1-canary.310

package/src/client/services.ts

@@ -0,0 +1,370 @@
+import type { Uuid } from 'surrealdb';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { Sp00kyConfig, PersistenceClient } from '../types';
+import type { Logger } from '../services/logger/index';
+import { LogTap, createLogger } from '../services/logger/index';
+import { ConnectionSupervisor, LocalMigrator, RemoteDatabaseService, createLocalEngine } from '../services/database/index';
+import type { LocalStore } from '../services/database/index';
+import { StreamProcessorService } from '../services/stream-processor/index';
+import type { StreamUpdate } from '../services/stream-processor/index';
+import { extractSelectPermissions } from '../services/stream-processor/permissions';
+import { EventSystem } from '../events/index';
+import { AuthService } from '../modules/auth/index';
+import { CrdtManager } from '../modules/crdt/index';
+import { preloadLoro } from '../modules/crdt/loro-loader';
+import { LocalStoragePersistenceClient } from '../services/persistence/localstorage';
+import { SurrealDBPersistenceClient } from '../services/persistence/surrealdb';
+import { ResilientPersistenceClient } from '../services/persistence/resilient';
+import { ANON_USER_ID } from '../modules/ref-tables';
+import { detectSharedTabsSupport } from '../services/tabs/support';
+import { TabsCoordinator, type CoordinatorHooks } from '../services/tabs/coordinator';
+import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
+import { computeTabsFingerprint, hash53 } from '../services/tabs/protocol';
+import type { SqliteCacheEngine } from '../services/database/sqlite-cache-engine';
+import type { BlobCache } from '../services/blobs/index';
+import { MemoryBlobStore, createBlobCache, resolveBlobBudget } from '../services/blobs/index';
+import type { Adapters } from '../kernel/interpreter';
+import type { RuntimeEvent } from '../kernel/events';
+import type { ServiceCalls } from '../kernel/effects';
+import { encodeRecordId } from '../utils/index';
+import { sha256Hex } from '../utils/sha256';
+import { hashOfEdge, rowOfEdge } from '../utils/edges';
+import { mintMutationId } from '../mutation/mutation-id';
+import { BucketHandle, bucketContentToBlob } from './bucket-handle';
+
+const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
+
+export function readBootBucketHint(): string | null {
+  try {
+    return typeof localStorage !== 'undefined' ? localStorage.getItem(LAST_BUCKET_KEY) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeBootBucketHint(bucketId: string): void {
+  try {
+    if (typeof localStorage !== 'undefined') localStorage.setItem(LAST_BUCKET_KEY, bucketId);
+  } catch {
+    /* private-mode storage errors: boot falls back to the anon bucket */
+  }
+}
+
+// Moved to a pure module so `@spooky-sync/core/pure` and the live feed share
+// it; re-exported here for existing imports.
+export { sha256Hex };
+
+export function mintSalt(): string {
+  const c = (globalThis as { crypto?: Crypto }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+}
+
+/** Everything the facade talks to besides the runtime. */
+export interface Services<S extends SchemaStructure> {
+  logger: Logger;
+  /** What the logger wrote, for the DevTools Logs tab. Absent in test fakes. */
+  logTap?: LogTap;
+  local: LocalStore;
+  remote: RemoteDatabaseService;
+  connectionSupervisor: ConnectionSupervisor;
+  blobs: BlobCache;
+  persistence: PersistenceClient;
+  streamProcessor: StreamProcessorService;
+  migrator: LocalMigrator;
+  crdt: CrdtManager;
+  auth: AuthService<S>;
+  tabs: TabsCoordinator | null;
+  tabsUnsupportedReason: string | undefined;
+  tabId: string;
+}
+
+/** What the services need back from the runtime once it exists. */
+export interface ServiceHost {
+  dispatch(event: RuntimeEvent): void;
+  /** Called by the tabs coordinator hooks with the hub / forwarder to relay through. */
+  setTabsChannel(channel: { hub: LeaderSyncHub | null; forwarder: SyncForwarder | null }): void;
+  /** Late-bound modules the boot saga starts (feature flags, app releases). */
+  initModules(): void;
+  detachWindow(): void;
+  setDetachWindow(fn: () => void): void;
+}
+
+export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S>): Services<S> {
+  const logTap = new LogTap(config.logLevel ?? 'info');
+  const logger = createLogger(config.logLevel ?? 'info', config.otelTransmit, logTap);
+  if (config.crdt) void preloadLoro();
+  const tabsSupport = detectSharedTabsSupport(config);
+  const local = createLocalEngine(config.localEngine, config.database, logger, { shared: tabsSupport.supported });
+  const remote = new RemoteDatabaseService(config.database, logger);
+  const connectionSupervisor = new ConnectionSupervisor(remote, logger);
+  const rawBucket = (name: string) => new BucketHandle(name, remote, null, { blurhash: config.blurhash, logger });
+  const blobs = createBlobCache({
+    local,
+    namespace: ANON_USER_ID,
+    logger,
+    fetchRemote: async (key) => bucketContentToBlob(await rawBucket(key.bucket).get(key.path)),
+    headRemote: (key) => rawBucket(key.bucket).head(key.path),
+    maxBytes: config.blobCache?.maxBytes,
+    store: config.blobCache?.enabled === false ? new MemoryBlobStore(ANON_USER_ID) : undefined,
+  });
+  let persistence: PersistenceClient;
+  if (config.persistenceClient === 'surrealdb') persistence = new SurrealDBPersistenceClient(local, logger);
+  else if (config.persistenceClient === 'localstorage' || !config.persistenceClient) persistence = new LocalStoragePersistenceClient(logger);
+  else persistence = config.persistenceClient;
+  persistence = new ResilientPersistenceClient(persistence, logger);
+  const streamProcessor = new StreamProcessorService(new EventSystem(['stream_update']), local, logger);
+  streamProcessor.configureCircuitPersistence(config.persistCircuit ?? config.localEngine === 'sqlite', config.circuitCheckpointMs);
+  streamProcessor.configureProjection(config.circuitProjection ?? true);
+  const migrator = new LocalMigrator(local, logger);
+  const crdt = new CrdtManager(config.schema, local, remote, logger, config.crdtDebounceMs ?? 500);
+  const auth = new AuthService(config.schema, remote, persistence, logger);
+  const tabId = typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `tab_${Math.random().toString(36).slice(2)}`;
+  return {
+    logger,
+    logTap,
+    local,
+    remote,
+    connectionSupervisor,
+    blobs,
+    persistence,
+    streamProcessor,
+    migrator,
+    crdt,
+    auth,
+    tabs: null,
+    tabsUnsupportedReason: tabsSupport.supported ? undefined : (tabsSupport as { reason: string }).reason,
+    tabId,
+  };
+}
+
+/** The shared-tabs coordinator, wired so role changes and relays become runtime events. */
+export function createTabsCoordinator<S extends SchemaStructure>(config: Sp00kyConfig<S>, s: Services<S>, host: ServiceHost): TabsCoordinator {
+  const engine = s.local as SqliteCacheEngine;
+  const hooks: CoordinatorHooks = {
+    adoptOwner: (bucketId, opts) =>
+      engine.adoptOwner(bucketId, { workerLockName: opts.workerLockName, allowMemoryFallback: opts.allowMemoryFallback, resumeHeld: opts.resumeHeld }),
+    adoptAttached: (dbPort, snapshot) => engine.adoptAttached(dbPort, snapshot, (reason) => engine.onLeaderLost(reason)),
+    releaseOwnership: () => engine.releaseOwnership(),
+    onLeaderLost: (reason) => engine.onLeaderLost(reason),
+    exposeClientPort: (clientId, port) => engine.exposeClientPort(clientId, port),
+    removeClientPort: (clientId) => engine.removeClientPort(clientId),
+    becomeSyncLeader: (hub) => {
+      s.streamProcessor.setPersistenceEnabled(true);
+      hub.onFollowerMessage = (_tabId, msg) => host.dispatch({ type: 'TabMessage', message: followerToRuntime(msg) });
+      host.setTabsChannel({ hub, forwarder: null });
+      host.dispatch({ type: 'TabRole', role: 'leader' });
+    },
+    resumeSyncLeaderDuties: async () => {
+      host.dispatch({ type: 'Drain' });
+      host.dispatch({ type: 'LiveStart' });
+    },
+    becomeSyncFollower: (forwarder) => {
+      s.streamProcessor.setPersistenceEnabled(false);
+      forwarder.onLeaderMessage = (msg) => host.dispatch({ type: 'TabMessage', message: leaderToRuntime(msg) });
+      host.setTabsChannel({ hub: null, forwarder });
+      host.dispatch({ type: 'TabRole', role: 'follower' });
+    },
+    becomeSyncSolo: () => {
+      s.streamProcessor.setPersistenceEnabled(true);
+      host.setTabsChannel({ hub: null, forwarder: null });
+      host.dispatch({ type: 'TabRole', role: 'solo' });
+    },
+    currentStorageHealth: () => s.local.storageHealth ?? { status: 'unknown', fallback: false },
+  };
+  return new TabsCoordinator({
+    tabId: s.tabId,
+    fingerprint: computeTabsFingerprint({
+      coreVersion: typeof __SP00KY_CORE_VERSION__ !== 'undefined' ? __SP00KY_CORE_VERSION__ : 'unknown',
+      schemaHash: hash53(config.schemaSurql),
+      endpoint: config.database.endpoint ?? '',
+      namespace: config.database.namespace,
+      database: config.database.database,
+    }),
+    hooks,
+    logger: s.logger,
+    onLeaderPageHide: () => void engine.shutdownOwnedWorker(),
+  });
+}
+
+/** Wire-protocol messages become the runtime's tab messages. */
+export function followerToRuntime(msg: { type: string; [k: string]: unknown }): unknown {
+  switch (msg.type) {
+    case 'mutation-enqueued':
+      return { type: 'outbox-changed', mutationId: msg.mutationId };
+    case 'ingest':
+      return { type: 'ingest', records: msg.tuples };
+    case 'request-poll':
+      return { type: 'membership-dirty', hashes: [] };
+    default:
+      return msg;
+  }
+}
+
+export function leaderToRuntime(msg: { type: string; [k: string]: unknown }): unknown {
+  switch (msg.type) {
+    case 'ingest-relay':
+      return { type: 'ingest', records: msg.tuples };
+    default:
+      return msg;
+  }
+}
+
+// Edge decoding lives in a pure module (the wasm-free live feed uses it too);
+// re-exported here for existing imports.
+export { hashOfEdge, rowOfEdge };
+
+/** Build the adapters the interpreter drives from the services. */
+export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S>, s: Services<S>, host: ServiceHost, lateModules: () => { init(): void }[]): Adapters {
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  const services: ServiceCalls = {
+    'hint.read': readBootBucketHint,
+    'hint.write': writeBootBucketHint,
+    'local.connect': (bucketId) => s.local.connect(bucketId),
+    'local.switchStore': (bucketId) => s.local.switchStore(bucketId),
+    'local.beginSwitch': () => s.local.beginSwitch(),
+    'local.currentBucketId': () => s.local.currentBucketId,
+    'local.usesSurqlSchema': () => s.local.usesSurqlSchema,
+    'local.dropBucket': async (bucketId) => {
+      await s.local.dropBucket?.(bucketId);
+    },
+    'migrator.provision': () => s.migrator.provision(config.schemaSurql),
+    'blobs.start': async (bucketId) => {
+      s.blobs.setMaxBytes(await resolveBlobBudget(config.blobCache?.maxBytes));
+      await s.blobs.start(bucketId);
+    },
+    'blobs.setNamespace': (bucketId) => s.blobs.setNamespace(bucketId),
+    'blobs.clear': () => s.blobs.clear(),
+    'ssp.init': () => s.streamProcessor.init(),
+    'ssp.setPermissions': () => s.streamProcessor.setPermissions(extractSelectPermissions(config.schemaSurql)),
+    'ssp.setSessionAuth': (authId, access) => s.streamProcessor.setSessionAuth(authId, access),
+    'ssp.prime': (pendingIds) =>
+      s.streamProcessor.primeFromLocal({
+        tables: [...config.schema.tables.map((t) => t.name), '_00_user_feature', '_00_app_release'],
+        schemaHash: String(hash53(config.schemaSurql)),
+        pendingIds: new Set(pendingIds),
+        onVersions: (_table, entries) => host.dispatch({ type: 'VersionsPrimed', entries }),
+      }),
+    'ssp.reset': () => s.streamProcessor.reset(),
+    'ssp.setPersistence': (enabled) => s.streamProcessor.setPersistenceEnabled(enabled),
+    'auth.restoreSession': () => s.auth.restoreSessionFromToken(),
+    'auth.init': () => s.auth.init(),
+    'auth.sessionAuthId': () => {
+      const id = s.auth.currentUser?.id;
+      if (!id) return null;
+      return typeof id === 'string' ? id : encodeRecordId(id);
+    },
+    'auth.access': () => s.auth.access,
+    'auth.token': () => s.auth.token,
+    'auth.currentUser': () => (s.auth.currentUser as Record<string, unknown> | null) ?? null,
+    'auth.consumeEndedImpersonation': () => s.auth.consumeEndedImpersonation(),
+    'remote.connect': () => s.remote.connect(),
+    'remote.releaseViews': (ids) => {
+      const list = ids
+        .map((id) => String(id))
+        .filter((id) => /^_00_query:[0-9a-f]{64}$/.test(id))
+        .join(', ');
+      if (list) s.remote.beaconSql(`FOR $id IN [${list}] { LET $_released = fn::query::unsubscribe($id); };`);
+    },
+    'supervisor.start': () => s.connectionSupervisor.start(),
+    'tabs.start': (bucketId) => {
+      if (!s.tabs) throw new Error('shared tabs unavailable');
+      return s.tabs.start(bucketId);
+    },
+    'tabs.moveToBucket': (bucketId) => {
+      if (!s.tabs) throw new Error('shared tabs unavailable');
+      return s.tabs.moveToBucket(bucketId);
+    },
+    'crdt.setSessionId': (id) => s.crdt.setSessionId(id),
+    'crdt.closeAll': (flush) => s.crdt.closeAll({ flush }),
+    'persistence.set': (key, value) => s.persistence.set(key, value),
+    'features.init': () => {
+      for (const m of lateModules()) m.init();
+    },
+    'releases.init': () => undefined,
+    'window.attach': () => {
+      if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return;
+      // Hidden is the last moment a page reliably gets to run: a reload or a
+      // closed tab follows it, and a backgrounded mobile tab may be killed
+      // without any further event. Pending debounced writes go out then.
+      const onPageHide = (event: PageTransitionEvent) => {
+        host.dispatch({ type: 'FlushPendingWrites' });
+        if (event.persisted) return;
+        host.dispatch({ type: 'PageHide' });
+      };
+      const onWake = () => {
+        if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return;
+        host.dispatch({ type: 'HeartbeatNow' });
+      };
+      const onVisibility = () => {
+        if (document.visibilityState === 'hidden') host.dispatch({ type: 'FlushPendingWrites' });
+        else onWake();
+      };
+      window.addEventListener('pagehide', onPageHide);
+      window.addEventListener('online', onWake);
+      if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility);
+      host.setDetachWindow(() => {
+        window.removeEventListener('pagehide', onPageHide);
+        window.removeEventListener('online', onWake);
+        if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility);
+      });
+    },
+  };
+  return {
+    local: s.local,
+    remote: {
+      queryResponses: (sql, vars) => s.remote.queryResponses(sql, vars),
+      live: async (table, onChange) => {
+        // `FETCH out` resolves the edge's target into the notification, so the
+        // body arrives with the doorbell instead of costing a second round
+        // trip. The clause is only ever added, never relied on: a server that
+        // ignores it, or a row the session cannot read, simply yields no
+        // inline row and the fetch path takes over.
+        const join = config.liveInlineBodies ? ' FETCH out' : '';
+        const [uuid] = await s.remote.query<[Uuid]>(`LIVE SELECT * FROM ${table}${join}`);
+        const live = await s.remote.getClient().liveOf(uuid);
+        live.subscribe((message) => {
+          if (message.action === 'KILLED') return;
+          const hash = hashOfEdge(message.value);
+          if (!hash) return;
+          // Not on DELETE: that edge is a row leaving the view, and for a row
+          // that was actually deleted the join yields nothing anyway. Landing
+          // a body there would only ever write back what is going away.
+          const row = message.action === 'DELETE' ? null : rowOfEdge(message.value);
+          onChange([hash], row ? [row] : undefined);
+        });
+        return String(uuid);
+      },
+      kill: async (uuid) => {
+        await s.remote.query('KILL $u', { u: uuid });
+      },
+    },
+    ssp: {
+      registerQueryPlan: (plan) => s.streamProcessor.registerQueryPlan(plan) as StreamUpdate | undefined,
+      unregisterQueryPlan: (hash) => s.streamProcessor.unregisterQueryPlan(hash),
+      ingestMany: (records) => s.streamProcessor.ingestMany(records),
+    },
+    timers: {
+      set: (key, ms, fire) => {
+        const prev = timers.get(key);
+        if (prev) clearTimeout(prev);
+        timers.set(
+          key,
+          setTimeout(() => {
+            timers.delete(key);
+            fire();
+          }, ms)
+        );
+      },
+      clear: (key) => {
+        const prev = timers.get(key);
+        if (prev) clearTimeout(prev);
+        timers.delete(key);
+      },
+    },
+    clock: { now: () => Date.now() },
+    ids: { mutation: () => mintMutationId(s.tabId), salt: mintSalt },
+    hash: sha256Hex,
+    services,
+  };
+}

package/src/client/sp00ky-client.test.ts

@@ -0,0 +1,303 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { Sp00kyClient } from './sp00ky-client';
+import { Runtime } from './runtime';
+import { fakeAdapters } from '../testing/adapters';
+import { fakeServiceBundle } from '../testing/fake-services';
+import { defaultEnv } from '../query/env';
+import type { StatementResult } from '../kernel/effects';
+
+const schema = { tables: [{ name: 'thing', columns: { a: {} } }], backends: { api: { outboxTable: 'thing', routes: { go: { args: {} } } } } } as any;
+const config = { database: { namespace: 'n', database: 'd' }, schema, schemaSurql: '', logLevel: 'silent' } as any;
+const ok = (result: unknown): StatementResult => ({ status: 'OK', result });
+const tick = () => new Promise((r) => setTimeout(r, 0));
+const flush = async (n = 6) => {
+  for (let i = 0; i < n; i++) await tick();
+};
+
+function makeClient(over: Parameters<typeof fakeAdapters>[0] = {}) {
+  const services = fakeServiceBundle<any>();
+  const a = fakeAdapters({
+    services: {
+      'hint.read': () => 'u1',
+      'local.usesSurqlSchema': () => false,
+      'auth.restoreSession': async () => null,
+      'auth.sessionAuthId': () => null,
+      'remote.connect': () => new Promise(() => {}),
+      ...over.services,
+    },
+    ...over,
+  });
+  const runtime = new Runtime({ env: defaultEnv(schema, { materializeDebounceMs: 1 }), adapters: a.adapters, logger: services.logger, tabId: 'tab-test' });
+  const client = new Sp00kyClient<any>(config, { services, runtime });
+  return { client, a, services, runtime };
+}
+
+describe('Sp00kyClient facade', () => {
+  it('hands DevTools the outbox and the failed tray', async () => {
+    const { client } = makeClient();
+    await client.init();
+    const source = (client as any).devTools.mutationSource;
+    expect(source.state()).toBe(client.state);
+    expect(await source.listFailed()).toEqual([]);
+    expect(await source.retryFailed('_00_pending_mutations:gone')).toBe(false);
+    expect(await source.discardFailed('_00_pending_mutations:gone')).toBe(false);
+  });
+
+  it('logs each finished statement at debug, and nothing below it', () => {
+    const { services } = makeClient();
+    const lines: unknown[] = [];
+    const log = services.logger as any;
+    log.debug = (fields: unknown, msg: string) => lines.push([fields, msg]);
+    log.isLevelEnabled = () => true;
+    const long = `SELECT * FROM thing WHERE ${'a = 1 AND '.repeat(30)}b = 2`;
+    services.emitStoreEvent('DATABASE_LOCAL_QUERY', { query: 'SELECT\n  1', vars: {}, duration: 1.234, success: true });
+    services.emitStoreEvent('DATABASE_REMOTE_QUERY', { query: long, duration: 3, success: false, error: 'boom' });
+    services.emitStoreEvent('DATABASE_LOCAL_QUERY', undefined);
+    log.isLevelEnabled = () => false;
+    services.emitStoreEvent('DATABASE_LOCAL_QUERY', { query: 'SELECT 3' });
+    expect(lines).toEqual([
+      [expect.objectContaining({ store: 'local', ms: 1.2, ok: true }), 'SELECT 1'],
+      [expect.objectContaining({ store: 'remote', query: long, ok: false, error: 'boom' }), `${long.slice(0, 160)}…`],
+      [expect.objectContaining({ store: 'local', ms: 0, ok: true }), ''],
+    ]);
+    expect((lines[0] as any[])[0].query).toBeUndefined();
+  });
+
+  it('init resolves from the local store while the remote connect never does', async () => {
+    const { client, a } = makeClient();
+    expect(client.isLocalReady()).toBe(false);
+    await client.init();
+    expect(client.isLocalReady()).toBe(true);
+    await flush();
+    expect(a.names()).toContain('service.remote.connect');
+    expect(a.names().indexOf('service.local.connect')).toBeLessThan(a.names().indexOf('service.remote.connect'));
+    expect(client.syncHealth.status).toBe('healthy');
+    expect(client.storageHealth).toEqual({ status: 'unknown', fallback: false });
+    expect(client.tabRole).toBeNull();
+    expect(client.liveRetryCount).toBe(0);
+  });
+
+  it('queryRaw registers locally and returns the hash before any remote work; subscribers paint from the local store', async () => {
+    // Boot loads the view index: `thing:1` is vouched for, `thing:2` is an orphan and stays hidden.
+    const stored = (sql: string) =>
+      sql.startsWith('SELECT * FROM thing')
+        ? [[{ id: 'thing:1' }, { id: 'thing:2' }]]
+        : sql === 'SELECT * FROM _00_view'
+          ? [[{ id: '_00_view:k', ids: [['thing:1', 1]] }]]
+          : [];
+    const { client, a } = makeClient({ local: { query: (async (sql: string) => stored(sql)) as any } });
+    await client.init();
+    const hash = await client.queryRaw('SELECT * FROM thing', {}, '10m');
+    expect(client.state.queries.get(hash)!.lifecycle.phase).toBe('cold');
+    const rows: unknown[] = [];
+    const off = await client.subscribe(hash, (r) => rows.push(r), { immediate: true });
+    a.timers.fire(`mat:${hash}`);
+    await flush();
+    expect(rows.at(-1)).toEqual([{ id: 'thing:1' }]);
+    const statuses: string[] = [];
+    client.subscribeQueryStatus(hash, (s) => statuses.push(s), { immediate: true });
+    const auth: boolean[] = [];
+    client.subscribeQueryAuthority(hash, (k) => auth.push(k), { immediate: true });
+    expect(statuses[0]).toBeDefined();
+    expect(auth).toEqual([false]);
+    client.reportFrontendTiming(hash, 3);
+    client.reportFrontendTiming(hash, Number.NaN);
+    expect(client.state.queries.get(hash)!.telemetry.phaseLast.frontend).toBe(3);
+    off();
+    client.deregisterQuery(hash);
+    await flush();
+    expect(client.state.queries.has(hash)).toBe(false);
+    client.deregisterQuery('missing');
+  });
+
+  it('create writes locally, mirrors the outbox and reports activity; the tray API reads state', async () => {
+    const { client } = makeClient({
+      local: {
+        execute: (async () => ({ id: new RecordId('thing', '1'), a: 1 })) as any,
+        // The drain reads the pending rows back; hand it delete rows so the (empty) push answer keeps them queued.
+        query: (async (sql: string, vars: any) =>
+          sql === 'SELECT * FROM $ids' && String(vars.ids[0]).startsWith('_00_pending_mutations')
+            ? [vars.ids.map((id: unknown) => ({ id: String(id), mutationType: 'delete', recordId: 'thing:1' }))]
+            : []) as any,
+      },
+    });
+    await client.init();
+    const counts: number[] = [];
+    const off = client.subscribeToPendingMutations((n) => counts.push(n));
+    const created = await client.create('thing:1', { a: 1 });
+    expect(created).toEqual({ id: new RecordId('thing', '1'), a: 1 });
+    expect(client.pendingMutationCount).toBe(1);
+    expect(counts).toEqual([0, 1]);
+    off();
+    const updated = await client.update('thing', 'thing:1', { a: 2 });
+    expect(updated).toEqual({ a: 2 });
+    await client.delete('thing', 'thing:1');
+    await client.run('api', 'go', {} as never);
+    expect(client.state.outbox).toHaveLength(4);
+    const fetching: number[] = [];
+    client.subscribeToFetchActivity((n) => fetching.push(n));
+    expect(fetching).toEqual([0]);
+    const tray: number[] = [];
+    client.subscribeToFailedMutations((n) => tray.push(n));
+    expect(tray).toEqual([0]);
+    expect(client.failedMutationCount).toBe(0);
+    expect(await client.listFailedMutations()).toEqual([]);
+    expect(await client.retryFailedMutation('nope')).toBe(false);
+    expect(await client.discardFailedMutation('nope')).toBe(false);
+    const health: unknown[] = [];
+    client.subscribeToSyncHealth((h) => health.push(h.status));
+    expect(health).toEqual([client.syncHealth.status]);
+    let stored = 0;
+    client.subscribeToStorageHealth(() => stored++);
+    expect(stored).toBe(1);
+  });
+
+  it('preload: cold waits for membership + bodies; cached returns at once; abort rejects', async () => {
+    const edges = [{ out: new RecordId('thing', '1'), version: 1 }];
+    const { client, a } = makeClient({
+      remote: {
+        queryResponses: async (sql: string) => {
+          if (sql.startsWith('fn::query::register')) return [ok(null), ok(edges), ok({ rowCount: 1, state: 'ready' }), ok([])];
+          if (sql.startsWith('SELECT * FROM $ids')) return [ok([{ id: new RecordId('thing', '1'), a: 1 }])];
+          return [ok(null)];
+        },
+      },
+      local: { select: (async () => [{ id: 'thing:1' }]) as any },
+    });
+    await client.init();
+    a.timers.fire('lifecycle');
+    const q = { innerQuery: { tableName: 'thing', selectQuery: { query: 'SELECT * FROM thing', vars: {}, plan: { table: 'thing' } } } } as any;
+    const done = client.preload(q).then(() => 'settled');
+    await flush(10);
+    for (const key of [...a.timers.pending.keys()]) if (key.startsWith('mat:')) a.timers.fire(key);
+    await flush(10);
+    expect(await done).toBe('settled');
+    const hash = [...client.state.queries.keys()][0];
+    expect(client.state.queries.get(hash)!.lifecycle.phase).toBe('live');
+    await expect(client.preload(q)).resolves.toBeUndefined();
+    const ctrl = new AbortController();
+    const q2 = { innerQuery: { tableName: 'thing', selectQuery: { query: 'SELECT * FROM thing WHERE a = 1', vars: {} } } } as any;
+    const aborted = client.preload(q2, { signal: ctrl.signal });
+    await flush(4);
+    ctrl.abort();
+    await expect(aborted).rejects.toThrow('aborted');
+  });
+
+  it('adapter callbacks become runtime events; tabs relays reach the hub/forwarder; close tears down', async () => {
+    const { client, services, runtime } = makeClient();
+    await client.init();
+    const seen: string[] = [];
+    runtime.on('*', (e) => seen.push(e.type));
+    services.receivers.forEach((r: any) => r.onStreamUpdate?.({ queryHash: 'zz', localArray: [] }));
+    services.connectionListeners.forEach((cb) => cb('connected'));
+    services.authListeners.forEach((cb) => cb(null));
+    await flush();
+    const sent: unknown[] = [];
+    (client as any).hub = { relayIngest: (t: unknown) => sent.push(['relay', t]), broadcast: (m: unknown) => sent.push(['bcast', m]), sendTo: (id: string, m: unknown) => sent.push(['to', id, m]) };
+    runtime.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records: [] } });
+    runtime.emit({ type: 'tabs:broadcast', message: { type: 'mutation-settled' } });
+    runtime.emit({ type: 'tabs:sendTo', tabId: 'x', message: { type: 'mutation-rolled-back' } });
+    (client as any).hub = null;
+    (client as any).forwarder = { ingest: (t: unknown) => sent.push(['f-ingest', t]), mutationEnqueued: (id: string) => sent.push(['f-enq', id]) };
+    runtime.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records: [] } });
+    runtime.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: 'm' } });
+    runtime.emit({ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: [] } });
+    expect(sent).toEqual([['relay', []], ['bcast', { type: 'mutation-settled' }], ['to', 'x', { type: 'mutation-rolled-back' }], ['f-ingest', []], ['f-enq', 'm']]);
+    runtime.emit({ type: 'query:status', hash: 'h', status: 'idle' });
+    runtime.emit({ type: 'query:authority', hash: 'h', known: true });
+    runtime.emit({ type: 'query:view-lost', hash: 'h' });
+    runtime.emit({ type: 'mutation:event', event: { type: 'create', record_id: new RecordId('thing', '1'), data: {} } });
+    runtime.emit({ type: 'mutation:settled', mutationId: 'm', recordId: 'thing:1', eventType: 'create' });
+    runtime.emit({ type: 'mutation:rolled-back', mutationId: 'm2', recordId: 'thing:1', eventType: 'update', error: 'denied' });
+    runtime.emit({ type: 'tray:changed', count: 1 });
+    expect(await client.authenticate('tok')).toBe('tok');
+    await client.deauthenticate();
+    expect(await client.useRemote(async () => 'r')).toBe('r');
+    expect(await client.remoteQuery('RETURN 1')).toEqual(['remote']);
+    expect(client.remoteClient).toBeDefined();
+    expect(client.localClient).toBe('local-client');
+    expect(client.getBlobCacheStats()).toEqual({ entries: 0 });
+    expect(client.bucket('files')).toBeDefined();
+    expect(await client.openCrdtField('t', 'r', 'f')).toBe('field');
+    client.closeCrdtField('t', 'r', 'f');
+    expect(client.getFeatureOverrides()).toEqual({});
+    client.setFeatureOverride('k', 'v');
+    client.clearFeatureOverrides();
+    expect(client.feature('k')).toBeDefined();
+    expect(client.appRelease('web')).toBeDefined();
+    await client.close();
+    expect(client.state.localReady).toBe(true);
+  });
+});
+
+describe('Sp00kyClient facade (builder, devtools source, event fan-out)', () => {
+  it('query() builds through the QueryBuilder and registers locally; dispatch feeds the engine; DevTools reads state', async () => {
+    const { client, runtime } = makeClient();
+    await client.init();
+    const { hash } = await (client.query('thing', {} as any) as any).build().run();
+    expect(client.state.queries.has(hash)).toBe(true);
+    const source = (client as any).devTools.dataManager;
+    expect(source.getActiveQueries().map((q: any) => q.config.surql)).toEqual(['SELECT * FROM thing;']);
+    const entry = client.state.queries.get(hash)!;
+    expect(source.getQueryById(entry.def.id)!.config.membershipKey).toBe(entry.def.viewKey);
+    expect(source.getQueryById({ id: 'nope', table: '_00_query' } as any)).toBeUndefined();
+    expect(source.phaseTimings(source.getActiveQueries()[0]).updateCount).toBe(0);
+    expect(source.phaseTimings({ config: { id: { id: 'nope' } } } as any)).toEqual({});
+    await client.dispatch({ type: 'PollTick' });
+    await expect((client.query('nope' as any, {} as any) as any).build().run()).rejects.toThrow('Table nope not found');
+    const tray: number[] = [];
+    const fetching: number[] = [];
+    const health: string[] = [];
+    client.subscribeToFailedMutations((n) => tray.push(n));
+    client.subscribeToFetchActivity((n) => fetching.push(n));
+    client.subscribeToSyncHealth((h) => health.push(h.status));
+    runtime.emit({ type: 'tray:changed', count: 2 });
+    runtime.emit({ type: 'activity:changed', fetching: 3, pending: 0 });
+    runtime.emit({ type: 'health:changed', health: { ...client.syncHealth, status: 'degraded' } });
+    runtime.emit({ type: 'query:evicted', hash });
+    expect(tray).toEqual([0, 2]);
+    expect(fetching).toEqual([0, 3]);
+    expect(health).toEqual(['healthy', 'degraded']);
+    const pending: number[] = [];
+    client.subscribeToPendingMutations((n) => pending.push(n));
+    runtime.emit({ type: 'activity:changed', fetching: 0, pending: 4 });
+    expect(pending).toEqual([0, 4]);
+  });
+  it('gates queryRaw/useRemote/remoteQuery behind allowRawRemote when the schema policy turns the allowlist on', async () => {
+    const services = fakeServiceBundle<any>();
+    const a = fakeAdapters({});
+    const runtime = new Runtime({ env: defaultEnv(schema), adapters: a.adapters, logger: services.logger, tabId: 't' });
+    const withPolicy = (mode: string | undefined, allowRawRemote?: boolean) =>
+      new Sp00kyClient<any>(
+        { ...config, schema: mode === undefined ? schema : { ...schema, policy: { queryAllowlist: mode } }, allowRawRemote } as any,
+        { services, runtime }
+      );
+    const msg = (m: string) => `sp00ky: ${m} is disabled because sync.queryAllowlist is on for this schema; pass allowRawRemote: true in the client config to opt in`;
+    for (const mode of ['warn', 'enforce']) {
+      const gated = withPolicy(mode);
+      await expect(gated.queryRaw('SELECT * FROM thing', {}, '10m')).rejects.toThrow(msg('queryRaw'));
+      await expect(gated.useRemote(() => 1)).rejects.toThrow(msg('useRemote'));
+      await expect(gated.remoteQuery('RETURN 1')).rejects.toThrow(msg('remoteQuery'));
+      expect(a.names().filter((n) => n === 'remote.query')).toEqual([]);
+    }
+    for (const client of [withPolicy('enforce', true), withPolicy('off'), withPolicy(undefined)]) {
+      await expect(client.useRemote(() => 1)).resolves.toBe(1);
+      await expect(client.remoteQuery('RETURN 1')).resolves.toBeDefined();
+    }
+  });
+
+  it('honours config knobs when building the saga env', () => {
+    const services = fakeServiceBundle<any>();
+    const a = fakeAdapters();
+    const runtime = new Runtime({ env: defaultEnv(schema), adapters: a.adapters, logger: services.logger, tabId: 't' });
+    const tuned = new Sp00kyClient<any>(
+      { ...config, database: { ...config.database, queryTimeoutMs: 5 }, syncHealth: false, pushTimeoutMs: 7, refSyncIntervalMs: 9, streamDebounceTime: 11, enableAnonymousLiveQueries: true, sharedTabs: true } as any,
+      { services, runtime, env: { defaultTtlMs: 1 } }
+    );
+    expect((tuned as any).env).toMatchObject({ remoteTimeoutMs: 5, degradeAfter: 0, pushTimeoutMs: 7, pollBaseMs: 9, materializeDebounceMs: 11, anonLive: true, defaultTtlMs: 1 });
+    const degraded = new Sp00kyClient<any>({ ...config, syncHealth: { degradeAfterConsecutiveFailures: 2 } } as any, { services, runtime });
+    expect((degraded as any).env.degradeAfter).toBe(2);
+    expect(tuned.tabRole).toBeNull();
+  });
+});