@spooky-sync/core 0.0.1-canary.69 → 0.0.1-canary.70

package/dist/otel/index.d.ts

@@ -1,4 +1,4 @@
-import { l as PinoTransmit } from "../types.js";
+import { u as PinoTransmit } from "../types.js";
 import { Level } from "pino";
 
 //#region src/otel/index.d.ts

package/dist/types.d.ts

@@ -255,6 +255,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * values fall back to the default (500ms).
    */
   refSyncIntervalMs?: number;
+  /**
+   * Instant-hydrate cold queries: when a query is registered with no local
+   * data yet, first run its surql directly on the remote (one-shot) and display
+   * the result immediately, THEN do the full realtime registration in the
+   * background. The hydrated rows are ingested with their versions so the
+   * registration's `syncRecords` skips re-pulling unchanged bodies. Cuts cold
+   * first-paint from ~one full registration round-trip to ~one query.
+   * Defaults to `true`; set `false` to keep the old wait-for-registration path.
+   */
+  instantHydrate?: boolean;
 }
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;
@@ -301,6 +311,14 @@ interface QueryConfig {
 type QueryConfigRecord = QueryConfig & {
   id: string;
 };
+/**
+ * Runtime fetch status of a live query.
+ * - `idle`: not currently fetching missing records.
+ * - `fetching`: the sync engine is fetching/ingesting missing records for this
+ *   query. UI notifications are coalesced so the result lands as a single
+ *   update once fetching completes.
+ */
+type QueryStatus = 'idle' | 'fetching';
 /**
  * Internal state of a live query.
  */
@@ -309,6 +327,9 @@ interface QueryState {
   config: QueryConfig;
   /** The current cached records for this query. */
   records: Record<string, any>[];
+  /** Set once `applyHydration` has run for this query, so the cold instant-hydrate
+   * path fires at most once per query (see DataModule.isCold/applyHydration). */
+  hydrated?: boolean;
   /** Timer for TTL expiration. */
   ttlTimer: NodeJS.Timeout | null;
   /** TTL duration in milliseconds. */
@@ -325,10 +346,62 @@ interface QueryState {
   lastIngestLatencyMs: number | null;
   /** Cumulative count of ingest/materialization errors observed for this query. */
   errorCount: number;
+  /**
+   * Ephemeral runtime fetch status. Not persisted to `_00_query`; observable
+   * via DevTools and the `useQuery` hook. `fetching` while the sync engine is
+   * pulling missing records for this query, otherwise `idle`.
+   */
+  status: QueryStatus;
+  /**
+   * Rolling per-phase timing samples (ms), in addition to `materializationSamples`
+   * (which holds the SSP whole-ingest wall time). Keyed by `TimingPhase` minus
+   * `ssp`. Not persisted — surfaced live to DevTools + MCP via `phaseTimings`.
+   */
+  phaseSamples: Record<string, number[]>;
+  /** Most recent sample (ms) per phase, or null. */
+  phaseLast: Record<string, number | null>;
+  /** One-shot SSP registration timings (ms). */
+  registrationTimings: RegistrationTimings;
 }
 /** Cap on the rolling materialization-sample window kept per query in memory. */
 declare const MATERIALIZATION_SAMPLE_WINDOW = 100;
+/** Timed processing phases surfaced per query. `ssp` is the WASM-ingest wall
+ *  time; the `ssp*` phases are its internal breakdown from the SSP binding. */
+type TimingPhase = 'ssp' | 'sspStoreApply' | 'sspCircuitStep' | 'sspTransform' | 'localFetch' | 'remoteFetch' | 'frontend';
+/** One-shot registration timings (ms), captured once when a query registers. */
+interface RegistrationTimings {
+  /** SSP surql→plan parse + permission injection. */
+  parseMs: number | null;
+  /** SSP operator-DAG build. */
+  planMs: number | null;
+  /** SSP initial snapshot evaluation. */
+  snapshotMs: number | null;
+  /** Wall time of `cache.registerQuery` (register_view round-trip). */
+  wallMs: number | null;
+}
+/** Percentile summary for one timed phase, surfaced to DevTools + MCP. */
+interface PhaseStat {
+  lastMs: number | null;
+  p50: number | null;
+  p90: number | null;
+  p99: number | null;
+  count: number;
+}
+/** Per-query processing-time breakdown surfaced via DevTools panel + MCP. */
+interface QueryTimings {
+  ssp: PhaseStat;
+  sspStoreApply: PhaseStat;
+  sspCircuitStep: PhaseStat;
+  sspTransform: PhaseStat;
+  localFetch: PhaseStat;
+  remoteFetch: PhaseStat;
+  frontend: PhaseStat;
+  registration: RegistrationTimings;
+  updateCount: number;
+  errorCount: number;
+}
 type QueryUpdateCallback = (records: Record<string, any>[]) => void;
+type QueryStatusCallback = (status: QueryStatus) => void;
 type MutationCallback = (mutations: UpEvent[]) => void;
 type MutationEventType = 'create' | 'update' | 'delete';
 /**
@@ -384,4 +457,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { UpdateOptions as C, EventSystem as E, StoreType as S, EventDefinition as T, RecordVersionDiff as _, MutationCallback as a, Sp00kyQueryResult as b, PersistenceClient as c, QueryConfigRecord as d, QueryHash as f, RecordVersionArray as g, QueryUpdateCallback as h, MATERIALIZATION_SAMPLE_WINDOW as i, PinoTransmit as l, QueryTimeToLive as m, EventSubscriptionOptions as n, MutationEvent as o, QueryState as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, QueryConfig as u, RunOptions as v, Logger$1 as w, Sp00kyQueryResultPromise as x, Sp00kyConfig as y };
+export { Logger$1 as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, EventSystem as M, TimingPhase as O, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, EventDefinition as j, UpdateOptions as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.69",
+  "version": "0.0.1-canary.70",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -61,7 +61,7 @@
   "dependencies": {
     "@spooky-sync/query-builder": "workspace:*",
     "@spooky-sync/ssp-wasm": "workspace:*",
-    "@surrealdb/wasm": "^3.0.0",
+    "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",
     "pino": "^10.1.0",

package/src/build-globals.d.ts

@@ -0,0 +1,6 @@
+// Build-time string constants injected by tsdown's `define` (see
+// tsdown.config.ts). They carry the real bundled frontend package versions so
+// the DevTools can surface frontend/backend version drift.
+declare const __SP00KY_CORE_VERSION__: string;
+declare const __SP00KY_WASM_VERSION__: string;
+declare const __SP00KY_SURREAL_VERSION__: string;

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/modules/cache/index.ts

@@ -119,12 +119,16 @@ export class CacheModule implements StreamUpdateReceiver {
         await this.local.execute(query, params);
       }
 
-      // 2. Batch ingest into DBSP (use populatedRecords which has _00_rv set)
-      for (const record of populatedRecords) {
+      // 2. Bulk ingest into DBSP (use populatedRecords which has _00_rv set).
+      // ingestMany coalesces the per-record stream updates into a single
+      // notification per affected query — the UI then updates once, after the
+      // whole batch is ingested, instead of row-by-row.
+      const bulk = populatedRecords.map((record) => {
         const recordId = encodeRecordId(record.record.id);
         this.versionLookups[recordId] = record.version;
-        this.streamProcessor.ingest(record.table, record.op, recordId, record.record);
-      }
+        return { table: record.table, op: record.op, id: recordId, record: record.record };
+      });
+      this.streamProcessor.ingestMany(bulk);
 
       this.logger.debug(
         { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
@@ -175,7 +179,10 @@ export class CacheModule implements StreamUpdateReceiver {
    * Register a query with DBSP to create a materialized view
    * Returns the initial result array
    */
-  registerQuery(config: QueryConfig): { localArray: RecordVersionArray } {
+  registerQuery(config: QueryConfig): {
+    localArray: RecordVersionArray;
+    registrationTimings?: { parseMs: number; planMs: number; snapshotMs: number };
+  } {
     this.logger.debug(
       {
         queryHash: config.queryHash,
@@ -212,7 +219,7 @@ export class CacheModule implements StreamUpdateReceiver {
         'Query registered successfully'
       );
 
-      return { localArray: update.localArray };
+      return { localArray: update.localArray, registrationTimings: update.registration };
     } catch (err) {
       this.logger.error(
         { err, queryHash: config.queryHash, Category: 'sp00ky-client::CacheModule::registerQuery' },

package/src/modules/crdt/index.ts

@@ -302,7 +302,15 @@ export class CrdtManager {
   private killTableSubscription(table: string): void {
     const uuid = this.liveByTable.get(table);
     if (uuid) {
-      this.remote.query('KILL $uuid', { uuid }).catch(() => {});
+      // We're tearing down: KILL on an already-dead/closed LIVE throws, and the
+      // subscription may have ended on its own, so the failure is expected and
+      // safe to drop.
+      this.remote.query('KILL $uuid', { uuid }).catch((err) => {
+        this.logger.debug(
+          { err, table, Category: 'sp00ky-client::CrdtManager::killTableSubscription' },
+          'KILL of table LIVE failed (already closed?)'
+        );
+      });
       this.liveByTable.delete(table);
     }
   }

package/src/modules/data/data.status.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+import type { QueryState, QueryStatus } from '../../types';
+
+/**
+ * Tests for the per-query fetch status (idle/fetching) added to DataModule:
+ * setQueryStatus updates the query object and notifies both the DevTools
+ * observer hook and subscribeStatus listeners.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+function makeDataModule(): DataModule<any> {
+  return new DataModule(
+    {} as any, // cache — unused by status methods
+    {} as any, // local — unused by status methods
+    { tables: [] } as any, // schema — unused by status methods
+    makeLogger(),
+    100
+  );
+}
+
+function makeQueryState(hash: string): QueryState {
+  return {
+    config: {
+      id: new RecordId('_00_query', hash),
+      surql: 'SELECT * FROM user',
+      params: {},
+      localArray: [],
+      remoteArray: [],
+      ttl: '10m',
+      lastActiveAt: new Date(),
+      tableName: 'user',
+    },
+    records: [],
+    ttlTimer: null,
+    ttlDurationMs: 0,
+    updateCount: 0,
+    materializationSamples: [],
+    lastIngestLatencyMs: null,
+    errorCount: 0,
+    status: 'idle',
+  };
+}
+
+describe('DataModule query fetch status', () => {
+  let dm: DataModule<any>;
+  const hash = 'h1';
+
+  beforeEach(() => {
+    dm = makeDataModule();
+    (dm as any).activeQueries.set(hash, makeQueryState(hash));
+  });
+
+  it('subscribeStatus with immediate reports the current status', () => {
+    const seen: QueryStatus[] = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s), { immediate: true });
+    expect(seen).toEqual(['idle']);
+  });
+
+  it('setQueryStatus updates the query object and notifies subscribers + observer', () => {
+    const observed: Array<[string, QueryStatus]> = [];
+    dm.onQueryStatusChange = (h, s) => observed.push([h, s]);
+
+    const seen: QueryStatus[] = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s));
+
+    dm.setQueryStatus(hash, 'fetching');
+    expect((dm as any).activeQueries.get(hash).status).toBe('fetching');
+    expect(seen).toEqual(['fetching']);
+    expect(observed).toEqual([[hash, 'fetching']]);
+
+    dm.setQueryStatus(hash, 'idle');
+    expect(seen).toEqual(['fetching', 'idle']);
+    expect(observed).toEqual([[hash, 'fetching'], [hash, 'idle']]);
+  });
+
+  it('setQueryStatus is a no-op when the status is unchanged', () => {
+    const seen: QueryStatus[] = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s));
+    dm.setQueryStatus(hash, 'idle'); // already idle
+    expect(seen).toEqual([]);
+  });
+
+  it('setQueryStatus is a no-op for an unknown query', () => {
+    let called = false;
+    dm.onQueryStatusChange = () => {
+      called = true;
+    };
+    dm.setQueryStatus('does-not-exist', 'fetching');
+    expect(called).toBe(false);
+  });
+
+  it('unsubscribe stops further status notifications', () => {
+    const seen: QueryStatus[] = [];
+    const unsub = dm.subscribeStatus(hash, (s) => seen.push(s));
+    dm.setQueryStatus(hash, 'fetching');
+    unsub();
+    dm.setQueryStatus(hash, 'idle');
+    expect(seen).toEqual(['fetching']);
+  });
+});