@spooky-sync/core 0.0.1-canary.25 → 0.0.1-canary.255

package/src/client/sp00ky-client.ts

@@ -0,0 +1,499 @@
+import type { Surreal } from 'surrealdb';
+import type {
+  BackendNames,
+  BackendRoutes,
+  FinalQuery,
+  GetTable,
+  InnerQuery,
+  QueryOptions,
+  RoutePayload,
+  SchemaStructure,
+  TableModel,
+  TableNames,
+  BucketNames,
+} from '@spooky-sync/query-builder';
+import { QueryBuilder } from '@spooky-sync/query-builder';
+import type {
+  PreloadOptions,
+  QueryAuthorityCallback,
+  QueryStatusCallback,
+  QueryTimeToLive,
+  RunOptions,
+  Sp00kyConfig,
+  Sp00kyQueryResultPromise,
+  StorageHealth,
+  SyncHealth,
+  UpdateOptions,
+} from '../types';
+import type { TabRole } from '../services/tabs/protocol';
+import { StreamProcessorService } from '../services/stream-processor/index';
+import type { StreamUpdateReceiver } from '../services/stream-processor/index';
+import { AuthService } from '../modules/auth/index';
+import { CrdtField } from '../modules/crdt/index';
+import { FeatureFlagModule, FeatureFlagHandle } from '../modules/feature-flag/index';
+import type { FeatureFlagOptions, FeatureFlagOverride } from '../modules/feature-flag/index';
+import { AppReleaseModule, AppReleaseHandle } from '../modules/app-release/index';
+import type { AppReleaseOptions } from '../modules/app-release/index';
+import { DevToolsService } from '../modules/devtools/index';
+import type { DevToolsQuerySource } from '../modules/devtools/index';
+import { parseQueryParams, generateId } from '../utils/index';
+import type { OutEvent, RuntimeEvent } from '../kernel/events';
+import type { ClientState } from '../state/client-state';
+import * as R from '../state/reducers';
+import { pendingMutationCount, fetchingQueryCount, phaseTimings, toQueryState } from '../state/selectors';
+import { defaultEnv, type SagaEnv } from '../query/env';
+import { registerLocal, type RegisterInput } from '../query/register.saga';
+import { evictQuery } from '../query/lifecycle.saga';
+import { write } from '../mutation/write.saga';
+import { discardFailed, listFailed, retryFailed } from '../mutation/tray.saga';
+import type { FailedMutationRow } from '../mutation/rows';
+import { buildJobRecord } from '../mutation/jobs';
+import { boot } from '../boot/boot.saga';
+import { preload } from '../boot/preload.saga';
+import { DEGRADE_AFTER_FAILURES, OUTBOX_BATCH_SIZE, PUSH_TIMEOUT_MS } from '../kernel/constants';
+import { Runtime } from './runtime';
+import { createAdapters, createServices, createTabsCoordinator, type ServiceHost, type Services } from './services';
+import { BucketHandle } from './bucket-handle';
+import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
+
+const UNKNOWN_STORAGE_HEALTH: StorageHealth = Object.freeze({ status: 'unknown', fallback: false });
+
+export interface Sp00kyClientDeps<S extends SchemaStructure> {
+  services?: Services<S>;
+  runtime?: Runtime;
+  env?: Partial<SagaEnv>;
+}
+
+/**
+ * The public client. Every method is a thin translation into a saga run, a
+ * state read, or a subscription on the runtime; the engine's behaviour lives
+ * in the sagas.
+ */
+export class Sp00kyClient<S extends SchemaStructure> {
+  public readonly auth: AuthService<S>;
+  public readonly streamProcessor: StreamProcessorService;
+
+  private readonly services: Services<S>;
+  private readonly env: SagaEnv;
+  private readonly runtime: Runtime;
+  private readonly featureFlags: FeatureFlagModule<S>;
+  private readonly appReleases: AppReleaseModule<S>;
+  private readonly devTools: DevToolsService;
+  private hub: LeaderSyncHub | null = null;
+  private forwarder: SyncForwarder | null = null;
+  private detachWindow: (() => void) | null = null;
+  private sharedActive = false;
+
+  constructor(
+    private readonly config: Sp00kyConfig<S>,
+    deps: Sp00kyClientDeps<S> = {}
+  ) {
+    this.services = deps.services ?? createServices(config);
+    const s = this.services;
+    this.env = defaultEnv(config.schema, {
+      anonLive: config.enableAnonymousLiveQueries === true,
+      remoteTimeoutMs: Math.max(0, config.database.queryTimeoutMs ?? 60_000),
+      pushTimeoutMs: config.pushTimeoutMs ?? PUSH_TIMEOUT_MS,
+      outboxBatchSize: OUTBOX_BATCH_SIZE,
+      degradeAfter: config.syncHealth === false ? 0 : (config.syncHealth?.degradeAfterConsecutiveFailures ?? DEGRADE_AFTER_FAILURES),
+      materializeDebounceMs: config.streamDebounceTime ?? 50,
+      pollBaseMs: config.refSyncIntervalMs && config.refSyncIntervalMs > 0 ? config.refSyncIntervalMs : 500,
+      ...deps.env,
+    });
+    const host: ServiceHost = {
+      dispatch: (event) => void this.runtime.dispatch(event),
+      setTabsChannel: ({ hub, forwarder }) => {
+        this.hub = hub;
+        this.forwarder = forwarder;
+        this.sharedActive = hub !== null || forwarder !== null;
+      },
+      initModules: () => undefined,
+      detachWindow: () => this.detachWindow?.(),
+      setDetachWindow: (fn) => (this.detachWindow = fn),
+    };
+    if (!deps.runtime && s.tabs === null && s.tabsUnsupportedReason === undefined) {
+      s.tabs = createTabsCoordinator(config, s, host);
+    }
+    this.runtime =
+      deps.runtime ??
+      new Runtime({
+        env: this.env,
+        adapters: createAdapters(config, s, host, () => [this.featureFlags, this.appReleases]),
+        logger: s.logger,
+        tabId: s.tabId,
+      });
+    this.auth = s.auth;
+    this.streamProcessor = s.streamProcessor;
+
+    const liveQueryPort = {
+      query: (table: string, surql: string, params: Record<string, unknown>, ttl: QueryTimeToLive) =>
+        this.runtime.run(registerLocal(this.env, { tableName: table, surql, params, ttl })),
+      subscribe: (hash: string, cb: (records: Record<string, any>[]) => void, options?: { immediate?: boolean }) =>
+        this.runtime.subscribe(hash, cb, options),
+    };
+    const remoteRegisterPort = { enqueueDownEvent: () => void this.runtime.dispatch({ type: 'EnsureRegistered' }) };
+    this.featureFlags = new FeatureFlagModule<S>({ dataModule: liveQueryPort, sync: remoteRegisterPort, auth: s.auth, logger: s.logger });
+    this.appReleases = new AppReleaseModule<S>({ dataModule: liveQueryPort, sync: remoteRegisterPort, auth: s.auth, logger: s.logger });
+
+    const querySource: DevToolsQuerySource = {
+      getActiveQueries: () => [...this.runtime.state.queries.values()].map(toQueryState),
+      getQueryById: (id) => {
+        const entry = [...this.runtime.state.queries.values()].find((e) => String(e.def.id) === String(id));
+        return entry ? toQueryState(entry) : undefined;
+      },
+      phaseTimings: (q) => {
+        const entry = this.runtime.state.queries.get(q.config.id.id as string) ?? [...this.runtime.state.queries.values()].find((e) => String(e.def.id) === String(q.config.id));
+        return entry ? phaseTimings(entry) : ({} as never);
+      },
+    };
+    this.devTools = new DevToolsService(s.local, s.remote, s.logger, config.schema, s.auth, querySource);
+    this.devTools.setFeatureFlagOverrides(this.featureFlags);
+    s.streamProcessor.addReceiver(this.devTools);
+    this.devTools.setBlobInfoProvider(() => s.blobs.stats());
+    if (config.sharedTabs) {
+      this.devTools.setTabsInfoProvider(() => {
+        const c = s.tabs;
+        if (!this.sharedActive || !c) return { active: false, reason: s.tabsUnsupportedReason ?? 'fell-back' };
+        return {
+          active: true,
+          role: c.role,
+          tabId: c.tabId,
+          leadershipId: c.leadershipId,
+          leaderTabId: c.role === 'leader' ? c.tabId : c.leaderTabId,
+          ...(this.hub ? { followers: this.hub.followerCount, relayedBatches: this.hub.relayedBatches } : {}),
+        };
+      });
+    }
+    this.wireAdapters();
+  }
+
+  /** Adapter callbacks become runtime events; runtime events reach the legacy services. */
+  private wireAdapters(): void {
+    const s = this.services;
+    const receiver: StreamUpdateReceiver = { onStreamUpdate: (update) => void this.runtime.dispatch({ type: 'StreamUpdate', update }) };
+    s.streamProcessor.addReceiver(receiver);
+    s.connectionSupervisor.subscribe((state) => void this.runtime.dispatch({ type: 'ConnectionChanged', state }));
+    s.auth.subscribe((userId) => void this.runtime.dispatch({ type: 'AuthFlip', userId }));
+    this.runtime.on('tabs:broadcast', (e) => {
+      if (e.type !== 'tabs:broadcast') return;
+      const msg = e.message as { type: string; records?: unknown[]; mutationId?: string };
+      if (this.hub) {
+        if (msg.type === 'ingest') this.hub.relayIngest(msg.records as never);
+        else this.hub.broadcast(msg as never);
+      } else if (this.forwarder) {
+        if (msg.type === 'ingest') this.forwarder.ingest(msg.records as never);
+        else if (msg.type === 'outbox-changed' && msg.mutationId) this.forwarder.mutationEnqueued(msg.mutationId);
+      }
+    });
+    this.runtime.on('tabs:sendTo', (e) => {
+      if (e.type === 'tabs:sendTo' && this.hub) this.hub.sendTo(e.tabId, e.message as never);
+    });
+    this.runtime.on('*', (e) => this.forwardToDevTools(e));
+    s.local.getEvents().subscribe('DATABASE_LOCAL_QUERY', (event: any) => this.devTools.logEvent('LOCAL_QUERY', event.payload));
+    s.remote.getEvents().subscribe('DATABASE_REMOTE_QUERY', (event: any) => this.devTools.logEvent('REMOTE_QUERY', event.payload));
+  }
+
+  private forwardToDevTools(e: OutEvent): void {
+    switch (e.type) {
+      case 'query:status':
+        this.devTools.logEvent('QUERY_STATUS_CHANGED', { queryHash: e.hash, status: e.status });
+        break;
+      case 'query:authority':
+        this.devTools.logEvent('QUERY_AUTHORITY_CHANGED', { queryHash: e.hash, known: e.known });
+        break;
+      case 'query:view-lost':
+        this.devTools.logEvent('QUERY_VIEW_LOST', { queryHash: e.hash });
+        break;
+      case 'mutation:event':
+        this.devTools.onMutation([e.event]);
+        break;
+      case 'devtools':
+        this.devTools.logEvent(e.name, e.data);
+        break;
+      default:
+        break;
+    }
+  }
+
+  // ---- lifecycle ---------------------------------------------------------------
+
+  async init(): Promise<void> {
+    await this.runtime.run(boot(this.env, { sharedTabs: this.services.tabs !== null }));
+  }
+
+  async close(): Promise<void> {
+    const s = this.services;
+    s.connectionSupervisor.dispose();
+    this.runtime.dispose();
+    await this.featureFlags.closeAll();
+    await this.appReleases.closeAll();
+    s.crdt.closeAll();
+    s.crdt.dispose();
+    await s.blobs.close().catch(() => {});
+    await s.streamProcessor.checkpoint('close').catch(() => {});
+    if (s.tabs) await s.tabs.stop();
+    this.detachWindow?.();
+    this.detachWindow = null;
+    await s.local.close();
+    await s.remote.close();
+    s.streamProcessor.dispose();
+  }
+
+  isLocalReady(): boolean {
+    return this.runtime.state.localReady;
+  }
+
+  // ---- queries -----------------------------------------------------------------
+
+  query<Table extends TableNames<S>>(
+    table: Table,
+    options: QueryOptions<TableModel<GetTable<S, Table>>, false>,
+    ttl: QueryTimeToLive = '10m'
+  ): QueryBuilder<S, Table, Sp00kyQueryResultPromise> {
+    return new QueryBuilder<S, Table, Sp00kyQueryResultPromise>(this.config.schema, table, async (q) => ({ hash: await this.initQuery(table, q, ttl) }), options);
+  }
+
+  private registerInput(table: string, q: InnerQuery<any, any, any>, ttl: QueryTimeToLive): RegisterInput {
+    const tableSchema = this.config.schema.tables.find((t) => t.name === table);
+    if (!tableSchema) throw new Error(`Table ${table} not found`);
+    return {
+      tableName: table,
+      surql: q.selectQuery.query,
+      params: parseQueryParams(tableSchema.columns, q.selectQuery.vars ?? {}),
+      ttl,
+      plan: q.selectQuery.plan,
+    };
+  }
+
+  private initQuery(table: string, q: InnerQuery<any, any, any>, ttl: QueryTimeToLive): Promise<string> {
+    return this.runtime.run(registerLocal(this.env, this.registerInput(table, q, ttl)));
+  }
+
+  /**
+   * The raw remote escape hatches bypass the query builder, so their shapes
+   * can never be on the server's query allowlist. When the generated schema
+   * says the allowlist is on, refuse them unless the app opted in explicitly.
+   */
+  private assertRawRemoteAllowed(method: string): void {
+    const mode = this.config.schema.policy?.queryAllowlist;
+    if ((mode === 'warn' || mode === 'enforce') && !this.config.allowRawRemote) {
+      throw new Error(
+        `sp00ky: ${method} is disabled because sync.queryAllowlist is on for this schema; pass allowRawRemote: true in the client config to opt in`
+      );
+    }
+  }
+
+  async queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string> {
+    this.assertRawRemoteAllowed('queryRaw');
+    const tableName = sql.split('FROM ')[1]?.split(' ')[0] ?? '';
+    return this.runtime.run(registerLocal(this.env, { tableName, surql: sql, params, ttl }));
+  }
+
+  /**
+   * Preload = register a query nobody subscribes to. Resolved before on this
+   * device: returns at once. Never resolved: resolves when the server's
+   * membership and every body are local. `signal` aborts the wait.
+   */
+  async preload(finalQuery: FinalQuery<S, any, any, any, any, any>, options?: PreloadOptions): Promise<void> {
+    const q = finalQuery.innerQuery;
+    await this.runtime.run(preload(this.env, this.registerInput(q.tableName, q, '10m')), { signal: options?.signal });
+  }
+
+  async subscribe(queryHash: string, callback: (records: Record<string, any>[]) => void, options?: { immediate?: boolean }): Promise<() => void> {
+    return this.runtime.subscribe(queryHash, callback, options);
+  }
+
+  deregisterQuery(queryHash: string): void {
+    const entry = this.runtime.state.queries.get(queryHash);
+    if (!entry || entry.subscribers > 0) return;
+    void this.runtime.run(evictQuery(queryHash), { lane: { kind: 'serial', key: `mat:${queryHash}` } });
+  }
+
+  subscribeQueryStatus(queryHash: string, callback: QueryStatusCallback, options?: { immediate?: boolean }): () => void {
+    return this.runtime.subscribeStatus(queryHash, callback, options);
+  }
+
+  subscribeQueryAuthority(queryHash: string, callback: QueryAuthorityCallback, options?: { immediate?: boolean }): () => void {
+    return this.runtime.subscribeAuthority(queryHash, callback, options);
+  }
+
+  reportFrontendTiming(queryHash: string, ms: number): void {
+    if (Number.isFinite(ms)) this.runtime.update(R.recordPhase(queryHash, 'frontend', ms));
+  }
+
+  // ---- mutations ---------------------------------------------------------------
+
+  async create<T extends Record<string, unknown>>(id: string, data: T): Promise<T> {
+    const out = await this.runtime.run(write(this.env, { kind: 'create', recordId: id, data }));
+    return (out.record ?? data) as T;
+  }
+
+  async update<T extends Record<string, unknown>>(_table: string, id: string, data: Partial<T>, options?: UpdateOptions): Promise<T> {
+    const out = await this.runtime.run(write(this.env, { kind: 'update', recordId: id, data: data as Record<string, unknown>, options }));
+    return (out.record ?? data) as T;
+  }
+
+  async delete(_table: string, id: string): Promise<void> {
+    await this.runtime.run(write(this.env, { kind: 'delete', recordId: id }));
+  }
+
+  async run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void> {
+    const { tableName, record } = buildJobRecord(this.config.schema, String(backend), String(path), payload as Record<string, unknown>, options);
+    await this.create(`${tableName}:${generateId()}`, record);
+  }
+
+  // ---- failed-writes tray -------------------------------------------------------
+
+  get failedMutationCount(): number {
+    return this.runtime.state.failedCount;
+  }
+
+  subscribeToFailedMutations(cb: (count: number) => void): () => void {
+    cb(this.runtime.state.failedCount);
+    return this.runtime.on('tray:changed', (e) => {
+      if (e.type === 'tray:changed') cb(e.count);
+    });
+  }
+
+  listFailedMutations(): Promise<FailedMutationRow[]> {
+    return this.runtime.run(listFailed());
+  }
+
+  async retryFailedMutation(mutationId: string): Promise<boolean> {
+    return this.runtime.run(retryFailed(this.env, mutationId), { lane: { kind: 'serial', key: 'tray' } });
+  }
+
+  async discardFailedMutation(mutationId: string): Promise<boolean> {
+    return this.runtime.run(discardFailed(mutationId), { lane: { kind: 'serial', key: 'tray' } });
+  }
+
+  // ---- observability -----------------------------------------------------------
+
+  get tabRole(): TabRole | null {
+    return this.sharedActive && this.services.tabs ? this.services.tabs.role : null;
+  }
+
+  get remoteClient(): Surreal {
+    return this.services.remote.getClient();
+  }
+
+  get localClient(): unknown {
+    return this.services.local.getClient();
+  }
+
+  get pendingMutationCount(): number {
+    return pendingMutationCount(this.runtime.state);
+  }
+
+  /** Kept for the e2e suite; the saga core has no LIVE retry ladder. */
+  get liveRetryCount(): number {
+    return 0;
+  }
+
+  subscribeToPendingMutations(cb: (count: number) => void): () => void {
+    cb(this.pendingMutationCount);
+    return this.runtime.on('activity:changed', (e) => {
+      if (e.type === 'activity:changed') cb(e.pending);
+    });
+  }
+
+  get fetchingQueryCount(): number {
+    return fetchingQueryCount(this.runtime.state);
+  }
+
+  subscribeToFetchActivity(cb: (fetching: number) => void): () => void {
+    cb(this.fetchingQueryCount);
+    return this.runtime.on('activity:changed', (e) => {
+      if (e.type === 'activity:changed') cb(e.fetching);
+    });
+  }
+
+  get syncHealth(): SyncHealth {
+    return this.runtime.state.sync.health;
+  }
+
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    cb(this.syncHealth);
+    return this.runtime.on('health:changed', (e) => {
+      if (e.type === 'health:changed') cb(e.health);
+    });
+  }
+
+  get storageHealth(): StorageHealth {
+    return this.services.local.storageHealth ?? UNKNOWN_STORAGE_HEALTH;
+  }
+
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
+    if (this.services.local.subscribeToStorageHealth) return this.services.local.subscribeToStorageHealth(cb);
+    cb(UNKNOWN_STORAGE_HEALTH);
+    return () => {};
+  }
+
+  /** The engine state, read-only. For tests and DevTools. */
+  get state(): ClientState {
+    return this.runtime.state;
+  }
+
+  /** Feed an event into the engine. For adapters, tests and DevTools. */
+  dispatch(event: RuntimeEvent): Promise<void> {
+    return this.runtime.dispatch(event);
+  }
+
+  // ---- auth / remote / crdt / flags / buckets ------------------------------------
+
+  authenticate(token: string) {
+    this.services.remote.setAuthToken(token);
+    return this.services.remote.getClient().authenticate(token);
+  }
+
+  deauthenticate() {
+    return this.services.remote.getClient().invalidate();
+  }
+
+  async useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T> {
+    this.assertRawRemoteAllowed('useRemote');
+    return fn(this.services.remote.getClient());
+  }
+
+  async remoteQuery<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T> {
+    this.assertRawRemoteAllowed('remoteQuery');
+    return this.services.remote.query<T>(sql, vars);
+  }
+
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle {
+    return this.featureFlags.feature(key, options);
+  }
+
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void {
+    this.featureFlags.setLocalOverride(key, variant, payload);
+  }
+
+  clearFeatureOverrides(): void {
+    this.featureFlags.clearLocalOverrides();
+  }
+
+  getFeatureOverrides(): Record<string, FeatureFlagOverride> {
+    return this.featureFlags.getLocalOverrides();
+  }
+
+  appRelease(app: string, options?: AppReleaseOptions): AppReleaseHandle {
+    return this.appReleases.release(app, options);
+  }
+
+  async openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField> {
+    return this.services.crdt.open(table, recordId, field, fallbackText);
+  }
+
+  closeCrdtField(table: string, recordId: string, field: string): void {
+    this.services.crdt.close(table, recordId, field);
+  }
+
+  bucket<B extends BucketNames<S>>(name: B): BucketHandle {
+    return new BucketHandle(name, this.services.remote, this.services.blobs, { blurhash: this.config.blurhash, logger: this.services.logger });
+  }
+
+  getBlobCacheStats() {
+    return this.services.blobs.stats();
+  }
+}
+

package/src/events/events.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { EventSystem, EventDefinition } from './index';
+import type { EventDefinition } from './index';
+import { EventSystem } from './index';
 
 // Define test event types
 type TestEvents = {

package/src/events/index.ts

@@ -172,6 +172,9 @@ export class EventSystem<E extends EventTypeMap> {
    * @param payload The data associated with the event.
    */
   emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void {
+    // `{ type, payload }` structurally matches `Event<E, T>` (= the indexed
+    // access `E[T]`), but TS can't verify assignability to an indexed-access
+    // type over the generic `E`/`T`, so the constructed event is asserted.
     const event = {
       type,
       payload,

package/src/index.ts

@@ -1,4 +1,39 @@
 export * from './types';
-export * from './spooky';
+export * from './sp00ky';
 export * from './modules/auth/index';
-export { fileToUint8Array } from './utils/index';
+export { CrdtField, CrdtManager, cursorColorFromName, CURSOR_COLORS } from './modules/crdt/index';
+export {
+  FeatureFlagModule,
+  FeatureFlagHandle,
+  type FeatureFlagOptions,
+  type FeatureFlagOverride,
+  type FeatureFlagSnapshot,
+} from './modules/feature-flag/index';
+export {
+  AppReleaseModule,
+  AppReleaseHandle,
+  type AppReleaseOptions,
+  type AppReleaseSnapshot,
+} from './modules/app-release/index';
+export type {
+  BlobCacheStats,
+  BlobEntry,
+  BlobKey,
+  BlobReadOptions,
+  BlobUrlLease,
+} from './services/blobs/index';
+export type { FailedMutationRow as FailedMutation } from './mutation/rows';
+export { semverGt } from './utils/semver';
+export { LocalOpTimeoutError, DEFAULT_LOCAL_OP_TIMEOUT_MS } from './services/database/errors';
+export { fileToUint8Array, textToHtml } from './utils/index';
+export {
+  blurhashSidecarPath,
+  encodeImageToBlurhash,
+  encodeBlurhash,
+  decodeBlurhash,
+  isBlurhashValid,
+  isImagePath,
+  BLURHASH_IMAGE_EXTENSIONS,
+  type BlurhashSetting,
+  type BlurhashEncodeOptions,
+} from './utils/blurhash';

package/src/kernel/constants.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { backoffMs, RETRY_BASE_MS, RETRY_MAX_MS } from './constants';
+
+describe('backoffMs', () => {
+  it('doubles from the base and caps at the max', () => {
+    expect(backoffMs(0)).toBe(RETRY_BASE_MS);
+    expect(backoffMs(1)).toBe(RETRY_BASE_MS * 2);
+    expect(backoffMs(3)).toBe(RETRY_BASE_MS * 8);
+    expect(backoffMs(20)).toBe(RETRY_MAX_MS);
+  });
+  it('clamps negative and huge attempts', () => {
+    expect(backoffMs(-5)).toBe(RETRY_BASE_MS);
+    expect(backoffMs(10_000)).toBe(RETRY_MAX_MS);
+  });
+  it('honours custom base and max', () => {
+    expect(backoffMs(2, 100, 250)).toBe(250);
+    expect(backoffMs(1, 100, 250)).toBe(200);
+  });
+});

package/src/kernel/constants.ts

@@ -0,0 +1,54 @@
+/**
+ * Every timing constant of the saga core in one place. Sagas never call
+ * `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. */
+export const MATERIALIZE_DEBOUNCE_MS = 50;
+/** Coalesce window for LIVE membership dirt before the batched edge re-read. */
+export const MEMBERSHIP_COALESCE_MS = 50;
+/** 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. */
+export const ACK_GRACE_MS = 30_000;
+/** Ids per body-fetch statement. */
+export const FETCH_CHUNK = 500;
+/** Outbox statements per push request. */
+export const OUTBOX_BATCH_SIZE = 50;
+/** Push deadline per outbox batch. */
+export const PUSH_TIMEOUT_MS = 30_000;
+/** Exponential backoff for outbox / fetch / registration retries. */
+export const RETRY_BASE_MS = 500;
+export const RETRY_MAX_MS = 15_000;
+/** Registration attempts before a query is reported as failed to settle. */
+export const REGISTER_MAX_RETRIES = 3;
+/** `_00_list_ref` poll cadence (fallback when LIVE is quiet). */
+export const LIST_REF_POLL_BASE_MS = 500;
+export const LIST_REF_POLL_MAX_MS = 5_000;
+export const LIST_REF_ROW_BUDGET = 1_500;
+export const LIST_REF_LARGE_VIEW_EDGES = 1_000;
+export const LIST_REF_LARGE_VIEW_POLL_MS = 15_000;
+/** Self-heal cadence while sync health is degraded. */
+export const SELF_HEAL_BASE_MS = 2_000;
+export const SELF_HEAL_MAX_MS = 30_000;
+/** Consecutive failed rounds before health flips to degraded. */
+export const DEGRADE_AFTER_FAILURES = 3;
+/** Burst coalescing of reconnects. */
+export const RECONNECT_REFETCH_COOLDOWN_MS = 10_000;
+/** Waiting for `$auth.id` to be visible after a reconnect. */
+export const AUTH_READY_RETRY_MS = 500;
+export const AUTH_READY_MAX_ATTEMPTS = 10;
+/** Heartbeat at this fraction of the shortest ttl in state. */
+export const TTL_HEARTBEAT_FRACTION = 0.5;
+/** Orphan body garbage collection cadence. */
+export const GC_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Remote adapter slot limit. */
+export const REMOTE_CONCURRENCY = 16;
+/** Rolling telemetry sample window per query. */
+export const TELEMETRY_SAMPLE_WINDOW = 100;
+
+export function backoffMs(attempt: number, base = RETRY_BASE_MS, max = RETRY_MAX_MS): number {
+  const n = Math.max(0, Math.min(attempt, 30));
+  return Math.min(max, base * 2 ** n);
+}

package/src/kernel/effects.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { fx } from './effects';
+
+describe('effect constructors', () => {
+  it('build every effect kind as plain data', () => {
+    const sealed = { sql: 'x;', extract: (r: unknown[]) => r[0] };
+    const plan = { table: 't' } as any;
+    const cases: Array<[ReturnType<typeof fx.now>, string]> = [
+      [fx.local.query('SELECT 1', { a: 1 }, 3), 'local.query'],
+      [fx.local.select(plan, { b: 2 }), 'local.select'],
+      [fx.local.execute(sealed, {}, 1), 'local.execute'],
+      [fx.local.getById('t', 'x'), 'local.getById'],
+      [fx.local.upsert('t', 'x', { a: 1 }, 'merge'), 'local.upsert'],
+      [fx.local.delete('t', 'x'), 'local.delete'],
+      [fx.remote.query('RETURN true', undefined, 10), 'remote.query'],
+      [fx.remote.live('_00_list_ref'), 'remote.live'],
+      [fx.remote.kill('u'), 'remote.kill'],
+      [fx.ssp.register({ queryHash: 'h', surql: 's', params: {}, ttl: '10m', tableName: 't' }), 'ssp.register'],
+      [fx.ssp.unregister('h'), 'ssp.unregister'],
+      [fx.ssp.ingest([]), 'ssp.ingest'],
+      [fx.timer.set('k', 5, { type: 'Drain' }), 'timer.set'],
+      [fx.timer.clear('k'), 'timer.clear'],
+      [fx.state.read((s) => s.tabId), 'state.read'],
+      [fx.state.update((s) => s), 'state.update'],
+      [fx.state.wait((s) => s.primed), 'state.wait'],
+      [fx.now(), 'now'],
+      [fx.id('mutation'), 'id'],
+      [fx.hash('abc'), 'hash'],
+      [fx.emit({ type: 'tray:changed', count: 1 }), 'emit'],
+      [fx.dispatch({ type: 'FetchRows' }), 'dispatch'],
+      [fx.all([fx.now()]), 'all'],
+      [fx.service('local.connect', 'anon'), 'service'],
+    ];
+    for (const [effect, kind] of cases) expect(effect.kind).toBe(kind);
+    expect(fx.local.query('SELECT 1', { a: 1 }, 3)).toEqual({ kind: 'local.query', sql: 'SELECT 1', vars: { a: 1 }, epoch: 3 });
+    expect(fx.local.epoch()).toEqual({ kind: 'local.epoch' });
+    expect(fx.timer.set('k', 5, { type: 'Drain' })).toEqual({ kind: 'timer.set', key: 'k', ms: 5, event: { type: 'Drain' } });
+    expect(fx.service('hint.write', 'u1')).toEqual({ kind: 'service', name: 'hint.write', args: ['u1'] });
+  });
+});