@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.210

package/src/modules/crdt/index.ts

@@ -0,0 +1,463 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
+import type { Logger } from '../../services/logger/index';
+import type { Uuid } from 'surrealdb';
+import { CrdtField } from './crdt-field';
+import { loadLoro } from './loro-loader';
+import { parseRecordIdString } from '../../utils/index';
+
+export { CrdtField, cursorColorFromName, CURSOR_COLORS } from './crdt-field';
+
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Collaborative state lives in two dedicated tables (defined in
+ * `apps/cli/src/meta_tables_remote.surql`):
+ *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+ *   - `_00_cursor` { record_id, session_id, field, state } — one row per
+ *                    (record, session, field)
+ *
+ * Splitting them off the parent row is what makes offline edits mergeable:
+ * each (record, field) gets its own row, so concurrent offline writes don't
+ * collide on the parent's last-write-wins semantics.
+ *
+ * Cross-browser delivery still rides the parent table's existing LIVE feed
+ * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+ * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+ * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+ * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+ * via subquery. Permission inheritance happens server-side via
+ * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
+ */
+export class CrdtManager {
+  private fields = new Map<string, CrdtField>();
+  // One LIVE subscription per parent table (e.g. "thread" → uuid).
+  private liveByTable = new Map<string, Uuid>();
+  // Coalesces concurrent first-time subscribes for the same table. Stamped with
+  // the connection generation it started under, so a restart after a drop can
+  // tell a reusable in-flight attempt from a doomed one.
+  private pendingLive = new Map<string, { promise: Promise<void>; generation: number }>();
+  // Tables whose LIVE died with a dropped socket, awaiting the next `connected`
+  // to be re-subscribed. Held separately because `liveByTable` is cleared on the
+  // drop (those uuids belong to a session that no longer exists).
+  private staleTables = new Set<string>();
+  // Bumped on every socket drop. A LIVE registration that started under an
+  // older generation is discarded rather than recorded, so a drop landing
+  // mid-registration can't leave a uuid from a dead session in `liveByTable`.
+  private connectionGeneration = 0;
+  private connectionUnsubscribes: Array<() => void> = [];
+  private logger: Logger;
+  // SurrealDB session id, used as the per-session key inside `_00_cursor`.
+  private sessionId: string = '';
+
+  constructor(
+    private schema: SchemaStructure,
+    private local: LocalStore,
+    private remote: RemoteDatabaseService,
+    logger: Logger,
+    private debounceMs: number = 500,
+  ) {
+    this.logger = logger.child({ service: 'CrdtManager' });
+    this.subscribeToReconnect();
+  }
+
+  /**
+   * Re-establish table LIVEs after a socket drop.
+   *
+   * A LIVE subscription lives and dies with its WebSocket session, and
+   * `ensureTableSubscription` is memoized on `liveByTable` — so without this,
+   * the first reconnect leaves CRDT realtime permanently dead: the map still
+   * holds a uuid for a subscription the server has forgotten, so every later
+   * `open()` short-circuits and no LIVE is ever re-issued.
+   *
+   * Both drop events matter: the SDK publishes `reconnecting` (not
+   * `disconnected`) when it intends to recover on its own, and `disconnected`
+   * only once it has given up.
+   */
+  private subscribeToReconnect(): void {
+    const onDrop = () => {
+      this.connectionGeneration++;
+      for (const table of this.liveByTable.keys()) this.staleTables.add(table);
+      // In-flight registrations count too: they'd otherwise complete against
+      // the dead session and be silently dropped by the generation guard.
+      for (const table of this.pendingLive.keys()) this.staleTables.add(table);
+      // No KILL: the server-side subscriptions are already gone, and these
+      // uuids would resolve against the new session.
+      this.liveByTable.clear();
+    };
+    this.connectionUnsubscribes.push(
+      this.remote.subscribeConnection('reconnecting', onDrop),
+      this.remote.subscribeConnection('disconnected', onDrop),
+      this.remote.subscribeConnection('connected', () => {
+        const tables = Array.from(this.staleTables);
+        this.staleTables.clear();
+        for (const table of tables) {
+          // Only resurrect tables that still have an open field — a drop can
+          // outlive the editor that needed the feed.
+          if (!this.hasOpenFieldFor(table)) continue;
+          void this.ensureTableSubscription(table);
+        }
+      })
+    );
+  }
+
+  /** Stop observing transport events. Separate from {@link closeAll}, which also
+   *  runs on a bucket switch where the manager keeps being used. */
+  dispose(): void {
+    for (const off of this.connectionUnsubscribes) {
+      try {
+        off();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.connectionUnsubscribes = [];
+    this.staleTables.clear();
+  }
+
+  private hasOpenFieldFor(table: string): boolean {
+    const prefix = `${table}:`;
+    return Array.from(this.fields.keys()).some((k) => k.startsWith(prefix));
+  }
+
+  /** Set the session id that scopes this client's cursor entries. Must be
+   *  called before `open()` for cursors to be pushed under a stable key.
+   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+   *  for the data-module salt). */
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+  }
+
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  async open(
+    table: string,
+    recordId: string,
+    field: string,
+    fallbackText?: string,
+  ): Promise<CrdtField> {
+    this.assertCrdtField(table, field);
+    const cursorsEnabled = this.fieldHasCursor(table, field);
+    const key = this.makeKey(table, recordId, field);
+    let crdtField = this.fields.get(key);
+
+    if (crdtField) {
+      return crdtField;
+    }
+
+    // Read the snapshot directly off the parent row. `@crdt`-only fields
+    // hold the base64 snapshot inline; `@crdt @cursor` fields hold a
+    // `{ state, cursors }` object so we drill into `.state`. The query
+    // always selects the local row — sync-down already populated it
+    // (the snapshot is a column on the parent, not a sidecar table) so
+    // there is no separate fetch on the happy path.
+    let initialCrdtState: Uint8Array | undefined;
+    try {
+      const [result] = await this.local.query<[unknown]>(
+        `SELECT VALUE ${field} FROM ONLY $id`,
+        { id: parseRecordIdString(recordId) },
+      );
+      const snapshot = this.extractSnapshot(result, cursorsEnabled);
+      if (snapshot) initialCrdtState = snapshot;
+    } catch (e) {
+      this.logger.info(
+        { error: String(e), recordId, field, Category: 'sp00ky-client::CrdtManager::open' },
+        'No existing CRDT state found in local cache (continuing with empty doc)'
+      );
+    }
+
+    // Load loro lazily (usually already resolved — the client preloads it at
+    // startup when `config.crdt` is on).
+    const { LoroDoc } = await loadLoro();
+    crdtField = new CrdtField(field, cursorsEnabled, LoroDoc, initialCrdtState, this.logger);
+    crdtField.startSync(this.local, this.remote, recordId, this.sessionId, this.debounceMs);
+    this.fields.set(key, crdtField);
+
+    this.logger.info(
+      { key, hasInitialState: !!initialCrdtState, hasFallback: !!fallbackText, Category: 'sp00ky-client::CrdtManager::open' },
+      'CrdtField opened'
+    );
+
+    // Fire-and-forget: the LIVE subscription receives *future* updates;
+    // the initial snapshot is already in hand. `ensureTableSubscription`
+    // coalesces concurrent calls via `pendingLive`, so this is safe.
+    void this.ensureTableSubscription(table);
+
+    // Local was empty — a fresh device, a memory-backed local DB after
+    // reload, or a record that hasn't been sync'd locally yet. Pull the
+    // parent row from remote and dispatch its CRDT field; otherwise the
+    // editor sits empty until the parent's LIVE feed happens to fire.
+    if (!initialCrdtState) {
+      void this.fetchAndDispatchRow(table, recordId);
+    }
+
+    return crdtField;
+  }
+
+  close(table: string, recordId: string, field: string): void {
+    const key = this.makeKey(table, recordId, field);
+    const crdtField = this.fields.get(key);
+    if (crdtField) {
+      crdtField.stopSync();
+      this.fields.delete(key);
+    }
+
+    // If no fields on this table remain open, tear down the table-wide LIVE.
+    if (!this.hasOpenFieldFor(table)) {
+      this.killTableSubscription(table);
+      // Also drop any pending post-reconnect restart for it.
+      this.staleTables.delete(table);
+    }
+
+    this.logger.debug(
+      { key, Category: 'sp00ky-client::CrdtManager::close' },
+      'CrdtField closed'
+    );
+  }
+
+  /**
+   * Close every open field + table LIVE. Fields flush a final remote push by
+   * default; pass `{ flush: false }` on a bucket switch, where that flush
+   * would push the previous user's snapshot under the next user's session.
+   */
+  closeAll(options: { flush?: boolean } = {}): void {
+    for (const [_, field] of this.fields) {
+      field.stopSync(options);
+    }
+    this.fields.clear();
+    for (const table of Array.from(this.liveByTable.keys())) {
+      this.killTableSubscription(table);
+    }
+    // Nothing is open any more, so nothing should be resurrected on the next
+    // reconnect; `open()` will re-subscribe on demand.
+    this.staleTables.clear();
+  }
+
+  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+   *  every open CrdtField on `table`. */
+  private async ensureTableSubscription(table: string): Promise<void> {
+    if (this.liveByTable.has(table)) return;
+
+    // Registering a LIVE takes two round-trips, so a socket drop can land
+    // mid-flight. The generation stamp is what keeps that honest: a registration
+    // that started before the drop must never record its uuid, because this
+    // method short-circuits on `liveByTable` and that stale entry (pointing at a
+    // session the server has forgotten) would block every future restart.
+    const generation = this.connectionGeneration;
+
+    const pending = this.pendingLive.get(table);
+    if (pending) {
+      if (pending.generation === generation) return pending.promise;
+      // A registration from before the drop is still settling. It will discard
+      // itself; wait it out, then register fresh on the new socket.
+      await pending.promise.catch(() => {});
+      if (this.liveByTable.has(table)) return;
+      if (generation !== this.connectionGeneration) return;
+      // Another caller may have won the race to re-register during that await;
+      // join it rather than opening a second LIVE on the same table.
+      const successor = this.pendingLive.get(table);
+      if (successor && successor.generation === generation) return successor.promise;
+    }
+
+    const start = (async () => {
+      try {
+        const [uuid] = await this.remote.query<[Uuid]>(
+          `LIVE SELECT * FROM ${table}`,
+        );
+
+        if (generation !== this.connectionGeneration) {
+          this.logger.debug(
+            { table, Category: 'sp00ky-client::CrdtManager::ensureTableSubscription' },
+            'Socket dropped while registering LIVE; discarding it'
+          );
+          return;
+        }
+
+        const subscription = await this.remote.getClient().liveOf(uuid);
+        subscription.subscribe((message) => {
+          if (message.action === 'KILLED') return;
+          if (message.action !== 'CREATE' && message.action !== 'UPDATE') return;
+          this.dispatchRow(table, message.value as Record<string, unknown>);
+        });
+
+        if (generation !== this.connectionGeneration) return;
+
+        this.liveByTable.set(table, uuid);
+        this.logger.info(
+          { table, Category: 'sp00ky-client::CrdtManager::ensureTableSubscription' },
+          'LIVE SELECT started'
+        );
+      } catch (e) {
+        this.logger.warn(
+          { error: e, table, Category: 'sp00ky-client::CrdtManager::ensureTableSubscription' },
+          'Failed to start LIVE SELECT'
+        );
+      }
+    })();
+
+    this.pendingLive.set(table, { promise: start, generation });
+    try {
+      await start;
+    } finally {
+      this.pendingLive.delete(table);
+    }
+  }
+
+  /** Apply a parent-row payload from a non-LIVE source (e.g. the
+   *  list_ref-driven sync engine, when the cross-user LIVE on the
+   *  parent table is filtered out by the SurrealDB cross-session
+   *  permission gap). Same semantics as the internal `dispatchRow`. */
+  applyRow(table: string, row: Record<string, unknown>): void {
+    this.dispatchRow(table, row);
+  }
+
+  /** Dispatch a parent-row LIVE event to every open CrdtField on that
+   *  record. Each open field reads its slice of the row directly — the
+   *  CRDT snapshot is a column on the parent now, so there is no
+   *  follow-up subquery. */
+  private dispatchRow(table: string, row: Record<string, unknown>): void {
+    const id = row.id != null ? String(row.id) : '';
+    if (!id) return;
+
+    const rowKeyPrefix = `${table}:${id}:`;
+    for (const [key, crdtField] of this.fields) {
+      if (!key.startsWith(rowKeyPrefix)) continue;
+      const fieldName = key.slice(rowKeyPrefix.length);
+      const cursorsEnabled = this.fieldHasCursor(table, fieldName);
+      const slice = row[fieldName];
+      const snapshot = this.extractSnapshot(slice, cursorsEnabled);
+      if (snapshot) crdtField.importRemote(snapshot);
+
+      if (cursorsEnabled && slice && typeof slice === 'object') {
+        const cursors = (slice as { cursors?: unknown }).cursors;
+        if (cursors && typeof cursors === 'object') {
+          for (const [sid, blob] of Object.entries(cursors as Record<string, unknown>)) {
+            if (sid === this.sessionId) continue;
+            if (typeof blob === 'string' && blob.length > 0) {
+              crdtField.importRemoteCursor(blob);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /** One-shot remote fetch for a row whose CRDT field hasn't synced
+   *  locally yet (fresh device, memory-backed local DB after reload, …).
+   *  Used by `open()` when the local read came up empty. Subsequent
+   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+  private async fetchAndDispatchRow(table: string, id: string): Promise<void> {
+    try {
+      const recordId = parseRecordIdString(id);
+      const [row] = await this.remote.query<[Record<string, unknown> | null]>(
+        `SELECT * FROM ONLY $id`,
+        { id: recordId },
+      );
+      if (!row || typeof row !== 'object') return;
+      this.dispatchRow(table, row as Record<string, unknown>);
+    } catch (e) {
+      this.logger.warn(
+        { error: e, table, id, Category: 'sp00ky-client::CrdtManager::fetchAndDispatchRow' },
+        'Failed to fetch parent row for CRDT hydration'
+      );
+    }
+  }
+
+  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+  private fieldHasCursor(table: string, field: string): boolean {
+    const tableSchema = this.schema.tables.find((t) => t.name === table);
+    return !!tableSchema?.columns[field]?.cursor;
+  }
+
+  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
+  private extractSnapshot(value: unknown, cursorsEnabled: boolean): Uint8Array | undefined {
+    const asBytes = (v: unknown): Uint8Array | undefined => {
+      if (v instanceof Uint8Array) return v.length > 0 ? v : undefined;
+      // SurrealDB ferries bytes through several shapes depending on
+      // transport and on whether the field is a top-level `bytes` column
+      // or bytes nested inside a FLEXIBLE object. Round-tripping bytes
+      // through `option<object> FLEXIBLE` (the `@crdt @cursor` shape) in
+      // particular comes back as a plain `number[]` from the local WASM
+      // DB and as `Uint8Array` from the remote WS engine. Normalize all
+      // recognized variants here so the receiving CrdtField doesn't care.
+      if (v instanceof ArrayBuffer) return new Uint8Array(v);
+      if (ArrayBuffer.isView(v)) {
+        const view = v as ArrayBufferView;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+      }
+      if (Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === 'number')) {
+        return Uint8Array.from(v as number[]);
+      }
+      return undefined;
+    };
+
+    if (cursorsEnabled) {
+      if (value && typeof value === 'object' && !(value instanceof Uint8Array)) {
+        return asBytes((value as { state?: unknown }).state);
+      }
+      return undefined;
+    }
+    return asBytes(value);
+  }
+
+  private killTableSubscription(table: string): void {
+    const uuid = this.liveByTable.get(table);
+    if (uuid) {
+      // 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);
+    }
+  }
+
+  private makeKey(table: string, recordId: string, field: string): string {
+    return `${table}:${recordId}:${field}`;
+  }
+
+  /**
+   * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
+   * typos, removed annotations, and stale schema codegen at the call site instead
+   * of silently producing a non-CRDT writer.
+   */
+  private assertCrdtField(table: string, field: string): void {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+      throw new Error(
+        `openCrdtField: refusing unsafe field identifier '${field}' — must match [a-zA-Z_][a-zA-Z0-9_]*`
+      );
+    }
+    const tableSchema = this.schema.tables.find((t) => t.name === table);
+    if (!tableSchema) {
+      throw new Error(
+        `openCrdtField: unknown table '${table}'. Available: ${this.schema.tables.map((t) => t.name).join(', ')}`
+      );
+    }
+    const column = tableSchema.columns[field];
+    if (!column) {
+      throw new Error(
+        `openCrdtField: '${table}.${field}' is not in the schema. Available fields: ${Object.keys(tableSchema.columns).join(', ')}`
+      );
+    }
+    if (!column.crdt) {
+      throw new Error(
+        `openCrdtField: '${table}.${field}' is not annotated '@crdt' in the schema. ` +
+          `Add '-- @crdt text' above the field's DEFINE FIELD and regenerate the client schema.`
+      );
+    }
+  }
+}

package/src/modules/crdt/loro-loader.ts

@@ -0,0 +1,25 @@
+/**
+ * Lazy, cached loader for `loro-crdt`. Keeping loro behind a dynamic `import()`
+ * (instead of a static top-level import in `crdt-field.ts`, which is re-exported
+ * from the package entry) breaks the static graph edge, so the loro chunk only
+ * ships to apps that actually use CRDT fields.
+ *
+ * `preloadLoro()` is fired from the client constructor when `config.crdt` is on,
+ * so the chunk is fetched at page load and the first `openCrdtField` doesn't
+ * block on a network round-trip. `loadLoro()` kicks the same import if it hasn't
+ * started, so opening a field still works when the flag is off.
+ */
+type LoroModule = typeof import('loro-crdt');
+
+let loroPromise: Promise<LoroModule> | null = null;
+
+/** Start (or return the in-flight/cached) `loro-crdt` import. Fire-and-forget. */
+export function preloadLoro(): Promise<LoroModule> {
+  loroPromise ??= import('loro-crdt');
+  return loroPromise;
+}
+
+/** Await the loro module, starting the import if `preloadLoro` hasn't run. */
+export function loadLoro(): Promise<LoroModule> {
+  return preloadLoro();
+}

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

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+import type { QueryState } from '../../types';
+
+/**
+ * Tests for instant-hydrate's DataModule half: `applyHydration` — run-once,
+ * remoteArray priming, subscriber notify, and the epoch guard added when the
+ * hydrate fetch moved off the paint path into a background chain.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+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,
+    lastUpdatedAt: null,
+    materializationSamples: [],
+    lastIngestLatencyMs: null,
+    errorCount: 0,
+    status: 'fetching',
+    phaseSamples: {},
+    phaseLast: {},
+    registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
+  };
+}
+
+const schema = { tables: [{ name: 'user', columns: {} }] } as any;
+
+function makeRow(id: string, rv = 1) {
+  return { id: new RecordId('user', id), name: id, _00_rv: rv };
+}
+
+describe('DataModule.applyHydration', () => {
+  const hash = 'h1';
+
+  function setup({ epochFlipsOnSave = false } = {}) {
+    let epoch = 1;
+    const saved: any[] = [];
+    const cache: any = {
+      saveBatch: async (batch: any[]) => {
+        saved.push(...batch);
+        if (epochFlipsOnSave) epoch = 2;
+      },
+    };
+    const local: any = {
+      get epoch() {
+        return epoch;
+      },
+      query: async () => [[makeRow('a')]],
+    };
+    const dm = new DataModule(cache, local, schema, makeLogger(), 100);
+    const state = makeQueryState(hash);
+    (dm as any).activeQueries.set(hash, state);
+    return { dm, state, saved };
+  }
+
+  it('primes remoteArray, materializes and notifies subscribers', async () => {
+    const { dm, state, saved } = setup();
+    const emissions: any[] = [];
+    dm.subscribe(hash, (records) => emissions.push(records));
+
+    await dm.applyHydration(hash, [makeRow('a', 3)]);
+
+    expect(state.hydrated).toBe(true);
+    expect(state.config.remoteArray).toEqual([['user:a', 3]]);
+    expect(saved.length).toBe(1);
+    expect(emissions.length).toBe(1);
+    expect(dm.isCold(hash)).toBe(false);
+  });
+
+  it('runs once even when the remote returns nothing (hydrated flag)', async () => {
+    const { dm, state, saved } = setup();
+    await dm.applyHydration(hash, []);
+    expect(state.hydrated).toBe(true);
+    expect(saved).toEqual([]);
+    expect(dm.isCold(hash)).toBe(false); // hydrated → no longer cold
+  });
+
+  it('is a no-op for an unknown query', async () => {
+    const { dm, saved } = setup();
+    await dm.applyHydration('nope', [makeRow('a')]);
+    expect(saved).toEqual([]);
+  });
+
+  it('bails before mutating state when the bucket epoch moves mid-persist', async () => {
+    const { dm, state } = setup({ epochFlipsOnSave: true });
+    const emissions: any[] = [];
+    dm.subscribe(hash, (records) => emissions.push(records));
+
+    await dm.applyHydration(hash, [makeRow('a', 3)]);
+
+    // Rows fetched under the previous auth context must not prime the new
+    // bucket's query state — the rebind's re-registration refills it.
+    expect(state.config.remoteArray).toEqual([]);
+    expect(state.records).toEqual([]);
+    expect(emissions).toEqual([]);
+  });
+});
+
+describe('DataModule.getPreloadMarker', () => {
+  function makeDm(getById: (table: string, id: unknown) => Promise<any>) {
+    const local: any = { getById };
+    return new DataModule({} as any, local, schema, makeLogger(), 100);
+  }
+
+  it('returns the marker fields for a real row', async () => {
+    const dm = makeDm(async () => ({ fetchedAt: 123, rowCount: 5 }));
+    expect(await dm.getPreloadMarker('h')).toEqual({ fetchedAt: 123, rowCount: 5 });
+  });
+
+  it('returns null on a miss and on a non-object echo (SurrealDB string quirk)', async () => {
+    expect(await makeDm(async () => null).getPreloadMarker('h')).toBeNull();
+    // `FROM ONLY <string>` used to echo the id string back — must not read as warm.
+    expect(await makeDm(async () => 'h' as any).getPreloadMarker('h')).toBeNull();
+  });
+
+  it('returns null when the read throws', async () => {
+    const dm = makeDm(async () => {
+      throw new Error('boom');
+    });
+    expect(await dm.getPreloadMarker('h')).toBeNull();
+  });
+});