@spooky-sync/core 0.0.1-canary.129 → 0.0.1-canary.130

package/dist/index.d.ts

@@ -522,6 +522,13 @@ declare class DataModule<S extends SchemaStructure> {
     fetchedAt: number;
     rowCount: number;
   } | null>;
+  /**
+   * True when this query's preload marker exists and is younger than
+   * `maxAgeMs`. Used by instant-hydrate to skip its one-shot fetch for rows a
+   * recent `preload()` already persisted (the register lifecycle re-syncs them
+   * authoritatively). Missing or unreadable markers are treated as stale.
+   */
+  isPreloadFresh(hashKey: string, maxAgeMs: number): Promise<boolean>;
   /** Stamp the preload freshness marker after a successful snapshot fetch. */
   writePreloadMarker(hash: string, rowCount: number): Promise<void>;
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
@@ -1213,6 +1220,7 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private crdtManager;
   private featureFlags;
   private preloadedHashes;
+  private pendingQueryInits;
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
@@ -1294,6 +1302,22 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   deauthenticate(): Promise<void>;
   query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private initQuery;
+  /**
+   * Background tail of {@link initQuery}: instant-hydrate (when the query is
+   * cold AND wasn't freshly preloaded) followed by enqueuing the `register`
+   * down-event. Never rejects — both halves catch and log, so `void`-ing the
+   * returned promise can't produce an unhandled rejection.
+   *
+   * The fresh-preload skip: rows a recent `preload()` persisted are already in
+   * the local cache and were part of the first paint; the register lifecycle
+   * re-syncs them authoritatively, so the one-shot hydrate fetch would be a
+   * pure duplicate round trip. "Fresh" = preloaded this session
+   * (`preloadedHashes`) or a `_00_preload` marker younger than
+   * HYDRATE_PRELOAD_FRESH. Both are per-bucket (the Set is cleared on bucket
+   * switch, the marker table lives in the bucket), so neither can claim
+   * freshness across auth contexts.
+   */
+  private finishQueryInit;
   /**
    * Smart, awaitable preload/prewarm into the LOCAL cache — without registering a
    * live view (NO `_00_query`, NO subscription, NO TTL heartbeat).

package/dist/index.js

@@ -2724,8 +2724,10 @@ var DataModule = class {
 		if (!queryState) return;
 		queryState.hydrated = true;
 		if (rows.length === 0) return;
+		const epoch = this.local.epoch;
 		const tableName = queryState.config.tableName;
 		await this.buildAndSaveCacheBatch(tableName, rows);
+		if (epoch !== this.local.epoch) return;
 		queryState.config.remoteArray = rows.map((r) => [encodeRecordId(r.id), r._00_rv || 1]);
 		queryState.records = await this.materializeRecords(queryState);
 		const subscribers = this.subscriptions.get(hash);
@@ -2782,6 +2784,16 @@ var DataModule = class {
 			return null;
 		}
 	}
+	/**
+	* True when this query's preload marker exists and is younger than
+	* `maxAgeMs`. Used by instant-hydrate to skip its one-shot fetch for rows a
+	* recent `preload()` already persisted (the register lifecycle re-syncs them
+	* authoritatively). Missing or unreadable markers are treated as stale.
+	*/
+	async isPreloadFresh(hashKey, maxAgeMs) {
+		const marker = await this.getPreloadMarker(hashKey);
+		return marker !== null && Date.now() - marker.fetchedAt <= maxAgeMs;
+	}
 	/** Stamp the preload freshness marker after a successful snapshot fetch. */
 	async writePreloadMarker(hash, rowCount) {
 		await this.local.upsert("_00_preload", hash, {
@@ -5118,8 +5130,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.129";
-const WASM_VERSION = "0.0.1-canary.129";
+const CORE_VERSION = "0.0.1-canary.130";
+const WASM_VERSION = "0.0.1-canary.130";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -7054,6 +7066,7 @@ var BucketHandle = class {
 * callback switches to the user's bucket (cache + outbox intact).
 */
 const LAST_BUCKET_KEY = "sp00ky:last_bucket";
+const HYDRATE_PRELOAD_FRESH = "1h";
 function readBootBucketHint() {
 	try {
 		return typeof localStorage !== "undefined" ? localStorage.getItem(LAST_BUCKET_KEY) : null;
@@ -7078,6 +7091,7 @@ var Sp00kyClient = class {
 	crdtManager;
 	featureFlags;
 	preloadedHashes = /* @__PURE__ */ new Set();
+	pendingQueryInits = /* @__PURE__ */ new Map();
 	logger;
 	auth;
 	streamProcessor;
@@ -7398,21 +7412,62 @@ var Sp00kyClient = class {
 		if (!tableSchema) throw new Error(`Table ${table} not found`);
 		const params = parseParams(tableSchema.columns, q.selectQuery.vars ?? {});
 		const hash = await this.dataModule.query(table, q.selectQuery.query, params, ttl, q.selectQuery.plan);
+		if (!this.pendingQueryInits.has(hash)) {
+			const chain = this.finishQueryInit(hash, q, params).finally(() => {
+				this.pendingQueryInits.delete(hash);
+			});
+			this.pendingQueryInits.set(hash, chain);
+		}
+		return hash;
+	}
+	/**
+	* Background tail of {@link initQuery}: instant-hydrate (when the query is
+	* cold AND wasn't freshly preloaded) followed by enqueuing the `register`
+	* down-event. Never rejects — both halves catch and log, so `void`-ing the
+	* returned promise can't produce an unhandled rejection.
+	*
+	* The fresh-preload skip: rows a recent `preload()` persisted are already in
+	* the local cache and were part of the first paint; the register lifecycle
+	* re-syncs them authoritatively, so the one-shot hydrate fetch would be a
+	* pure duplicate round trip. "Fresh" = preloaded this session
+	* (`preloadedHashes`) or a `_00_preload` marker younger than
+	* HYDRATE_PRELOAD_FRESH. Both are per-bucket (the Set is cleared on bucket
+	* switch, the marker table lives in the bucket), so neither can claim
+	* freshness across auth contexts.
+	*/
+	async finishQueryInit(hash, q, params) {
 		if (this.config.instantHydrate !== false && this.dataModule.isCold(hash)) try {
-			const [rows] = await this.remote.query(q.selectQuery.query, params);
-			await this.dataModule.applyHydration(hash, rows ?? []);
+			if (!(this.preloadedHashes.has(q.hash) || await this.dataModule.isPreloadFresh(String(q.hash), parseDuration(HYDRATE_PRELOAD_FRESH)))) {
+				const epoch = this.local.epoch;
+				const [rows] = await this.remote.query(q.selectQuery.query, params);
+				if (epoch === this.local.epoch) await this.dataModule.applyHydration(hash, rows ?? []);
+			} else this.logger.debug({
+				hash,
+				Category: "sp00ky-client::Sp00kyClient::instantHydrate"
+			}, "Skipping instant hydrate; preload marker fresh");
 		} catch (err) {
-			this.logger.warn({
+			if (err instanceof StaleEpochError) this.logger.debug({
+				hash,
+				Category: "sp00ky-client::Sp00kyClient::instantHydrate"
+			}, "Dropped instant hydrate from before a bucket switch");
+			else this.logger.warn({
 				err,
 				hash,
 				Category: "sp00ky-client::Sp00kyClient::instantHydrate"
 			}, "Instant hydrate failed; proceeding with registration");
 		}
-		await this.sync.enqueueDownEvent({
-			type: "register",
-			payload: { hash }
-		});
-		return hash;
+		try {
+			await this.sync.enqueueDownEvent({
+				type: "register",
+				payload: { hash }
+			});
+		} catch (err) {
+			this.logger.error({
+				err,
+				hash,
+				Category: "sp00ky-client::Sp00kyClient::initQuery"
+			}, "Failed to enqueue register down-event");
+		}
 	}
 	/**
 	* Smart, awaitable preload/prewarm into the LOCAL cache — without registering a

package/dist/types.d.ts

@@ -450,13 +450,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    */
   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.
+   * Instant-hydrate cold queries: when a query is registered with no server
+   * result yet, run its surql directly on the remote (one-shot) and display
+   * the result as soon as it lands, while the full realtime registration
+   * proceeds in the background. The hydrated rows are ingested with their
+   * versions so the registration's `syncRecords` skips re-pulling unchanged
+   * bodies. The fetch runs OFF the paint path — `useQuery` resolves and paints
+   * from the local cache immediately, and hydrate only fills in what's
+   * missing. Skipped entirely when the query was `preload()`ed recently (its
+   * rows are already local and fresh; the registration re-syncs them), so a
+   * preloaded screen costs zero duplicate fetches. Defaults to `true`.
    */
   instantHydrate?: boolean;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.129",
+  "version": "0.0.1-canary.130",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.129",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.129",
+    "@spooky-sync/query-builder": "0.0.1-canary.130",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.130",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

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

@@ -0,0 +1,150 @@
+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) and
+ * `isPreloadFresh` (the marker check that lets a freshly-preloaded query skip
+ * the duplicate one-shot fetch entirely).
+ */
+
+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.isPreloadFresh', () => {
+  const maxAgeMs = 60_000;
+
+  function makeDm(getById: (table: string, id: string) => Promise<any>) {
+    const local: any = { getById };
+    return new DataModule({} as any, local, schema, makeLogger(), 100);
+  }
+
+  it('true for a marker younger than maxAgeMs', async () => {
+    const dm = makeDm(async () => ({ fetchedAt: Date.now() - 1_000, rowCount: 5 }));
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(true);
+  });
+
+  it('false for a marker older than maxAgeMs', async () => {
+    const dm = makeDm(async () => ({ fetchedAt: Date.now() - maxAgeMs - 1, rowCount: 5 }));
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  });
+
+  it('false when no marker exists', async () => {
+    const dm = makeDm(async () => null);
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  });
+
+  it('false when the marker read throws (treated as cold)', async () => {
+    const dm = makeDm(async () => {
+      throw new Error('boom');
+    });
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  });
+});

package/src/modules/data/index.ts

@@ -794,8 +794,14 @@ export class DataModule<S extends SchemaStructure> {
     queryState.hydrated = true; // run-once, even when the remote returns nothing
     if (rows.length === 0) return;
 
+    const epoch = this.local.epoch;
     const tableName = queryState.config.tableName;
     await this.buildAndSaveCacheBatch(tableName, rows);
+    // Bucket switched while we persisted: these rows were fetched under the
+    // previous auth context — don't let them prime the new bucket's query
+    // state; the rebind's re-registration refills it. (saveBatch's own epoch
+    // fence usually catches this, but the switch can land between it and here.)
+    if (epoch !== this.local.epoch) return;
 
     // Prime remoteArray from the hydrated id+version pairs: `materializeRecords`
     // prefers it for windowed queries (correct window) and it feeds the version
@@ -881,6 +887,17 @@ export class DataModule<S extends SchemaStructure> {
     }
   }
 
+  /**
+   * True when this query's preload marker exists and is younger than
+   * `maxAgeMs`. Used by instant-hydrate to skip its one-shot fetch for rows a
+   * recent `preload()` already persisted (the register lifecycle re-syncs them
+   * authoritatively). Missing or unreadable markers are treated as stale.
+   */
+  async isPreloadFresh(hashKey: string, maxAgeMs: number): Promise<boolean> {
+    const marker = await this.getPreloadMarker(hashKey);
+    return marker !== null && Date.now() - marker.fetchedAt <= maxAgeMs;
+  }
+
   /** Stamp the preload freshness marker after a successful snapshot fetch. */
   async writePreloadMarker(hash: string, rowCount: number): Promise<void> {
     await this.local.upsert(

package/src/sp00ky.init-query.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Sp00kyClient } from './sp00ky';
+
+// Guards for the local-first paint contract of `Sp00kyClient.initQuery`:
+// the hash must resolve (and the hook paint from local cache) without any
+// network on the awaited path, while instant-hydrate + the `register`
+// down-event run in a background chain that (a) keeps hydrate strictly
+// before the enqueue, (b) skips the duplicate one-shot fetch for freshly
+// preloaded queries, (c) never rejects, and (d) is shared by concurrent
+// mounts of the same query.
+//
+// Structural half: like sp00ky.auth-order.test.ts, a regex over the source
+// catches the ordering regressions a runtime mock can't cheaply cover
+// (Sp00kyClient's constructor drags in SurrealDB + the WASM SSP).
+// Behavioral half: `finishQueryInit`/`initQuery` only touch a handful of
+// injected fields, so a bare `Object.create(Sp00kyClient.prototype)` with
+// stubs exercises the real method bodies without the constructor.
+
+describe('Sp00kyClient.initQuery structural invariants', () => {
+  const source = readFileSync(resolve(__dirname, 'sp00ky.ts'), 'utf-8');
+
+  const methodBody = (name: string): string => {
+    const match = source.match(new RegExp(`private async ${name}[\\s\\S]*?\\n  \\}`));
+    expect(match, `expected a "private async ${name}" method in sp00ky.ts`).not.toBeNull();
+    // Strip line comments so prose mentioning awaits/calls can't trip the checks.
+    return match![0]
+      .split('\n')
+      .map((line) => line.replace(/\/\/.*$/, ''))
+      .join('\n');
+  };
+
+  it('initQuery returns the hash with no network on the awaited path', () => {
+    const body = methodBody('initQuery');
+    expect(body).toContain('return hash');
+    expect(body, 'initQuery must not await the remote (paint path is network-free)').not.toMatch(
+      /await this\.remote\./
+    );
+    expect(body, 'the register enqueue belongs to the background chain').not.toMatch(
+      /await this\.sync\.enqueueDownEvent/
+    );
+  });
+
+  it('finishQueryInit hydrates strictly before enqueuing register', () => {
+    const body = methodBody('finishQueryInit');
+    const fetchIdx = body.indexOf('this.remote.query');
+    const enqueueIdx = body.indexOf('this.sync.enqueueDownEvent');
+    expect(fetchIdx).toBeGreaterThanOrEqual(0);
+    expect(enqueueIdx).toBeGreaterThanOrEqual(0);
+    expect(
+      fetchIdx,
+      'hydrate must settle before the register enqueue so a stale one-shot snapshot can never land after the authoritative _00_list_ref overwrite'
+    ).toBeLessThan(enqueueIdx);
+  });
+
+  it('finishQueryInit captures the bucket epoch before the remote fetch', () => {
+    const body = methodBody('finishQueryInit');
+    const epochIdx = body.indexOf('this.local.epoch');
+    const fetchIdx = body.indexOf('this.remote.query');
+    expect(epochIdx).toBeGreaterThanOrEqual(0);
+    expect(epochIdx, 'epoch must be read before the fetch to fence bucket switches').toBeLessThan(
+      fetchIdx
+    );
+  });
+});
+
+describe('Sp00kyClient.finishQueryInit behavior', () => {
+  const hash = 'sha-hash';
+  const q: any = { hash: 42, selectQuery: { query: 'SELECT * FROM user', vars: {} } };
+
+  let client: any;
+  let calls: string[];
+  let enqueued: any[];
+  let epoch: number;
+  let preloadFresh: boolean;
+  let cold: boolean;
+  let remoteImpl: () => Promise<any>;
+
+  beforeEach(() => {
+    calls = [];
+    enqueued = [];
+    epoch = 1;
+    preloadFresh = false;
+    cold = true;
+    remoteImpl = async () => {
+      calls.push('fetch');
+      return [[{ id: 'user:a' }]];
+    };
+
+    const noop = () => {};
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+
+    client = Object.create(Sp00kyClient.prototype);
+    Object.assign(client, {
+      config: { instantHydrate: true, schema: { tables: [{ name: 'user', columns: {} }] } },
+      logger,
+      preloadedHashes: new Set<number>(),
+      pendingQueryInits: new Map<string, Promise<void>>(),
+      local: {
+        get epoch() {
+          return epoch;
+        },
+      },
+      remote: { query: (...args: any[]) => remoteImpl() },
+      sync: {
+        enqueueDownEvent: (event: any) => {
+          calls.push('enqueue');
+          enqueued.push(event);
+        },
+      },
+      dataModule: {
+        isCold: () => cold,
+        isPreloadFresh: async () => preloadFresh,
+        applyHydration: async () => {
+          calls.push('hydrate');
+        },
+        query: async () => hash,
+      },
+    });
+  });
+
+  it('cold path: fetch → hydrate → enqueue, in order', async () => {
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(enqueued).toEqual([{ type: 'register', payload: { hash } }]);
+  });
+
+  it('session-preloaded query skips the fetch but still enqueues register', async () => {
+    client.preloadedHashes.add(q.hash);
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('fresh preload marker skips the fetch but still enqueues register', async () => {
+    preloadFresh = true;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('warm query (not cold) goes straight to enqueue', async () => {
+    cold = false;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('a rejected hydrate fetch still enqueues register and never rejects', async () => {
+    remoteImpl = async () => {
+      calls.push('fetch');
+      throw new Error('offline');
+    };
+    await expect(client.finishQueryInit(hash, q, {})).resolves.toBeUndefined();
+    expect(calls).toEqual(['fetch', 'enqueue']);
+  });
+
+  it('a bucket switch during the fetch skips applyHydration', async () => {
+    remoteImpl = async () => {
+      calls.push('fetch');
+      epoch = 2; // switch lands while the fetch is in flight
+      return [[{ id: 'user:a' }]];
+    };
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['fetch', 'enqueue']);
+  });
+
+  it('instantHydrate: false disables the hydrate fetch entirely', async () => {
+    client.config.instantHydrate = false;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('concurrent initQuery calls for the same hash share one background chain', async () => {
+    const [h1, h2] = await Promise.all([
+      client.initQuery('user', q, '10m'),
+      client.initQuery('user', q, '10m'),
+    ]);
+    expect(h1).toBe(hash);
+    expect(h2).toBe(hash);
+    // Let the shared chain drain.
+    await Promise.all([...client.pendingQueryInits.values()]);
+    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(client.pendingQueryInits.size).toBe(0);
+  });
+});

package/src/sp00ky.ts

@@ -15,6 +15,7 @@ import {
   createLocalEngine,
 } from './services/database/index';
 import type { LocalStore } from './services/database/index';
+import { StaleEpochError } from './services/database/index';
 import type { UpEvent } from './modules/sync/index';
 import { Sp00kySync } from './modules/sync/index';
 import type {
@@ -102,6 +103,12 @@ export class BucketHandle {
  */
 const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
 
+// Max age of a `_00_preload` marker for which instant-hydrate is skipped —
+// a query preloaded this recently already painted from local rows and the
+// register lifecycle re-syncs it, so the one-shot hydrate fetch would be a
+// duplicate round trip. Matches `preload()`'s default `staleTime`.
+const HYDRATE_PRELOAD_FRESH: QueryTimeToLive = '1h';
+
 function readBootBucketHint(): string | null {
   try {
     return typeof localStorage !== 'undefined' ? localStorage.getItem(LAST_BUCKET_KEY) : null;
@@ -134,6 +141,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
   // fetches when the same preload query is requested again (e.g. a list row
   // re-rendering). Cleared on process/session end only.
   private preloadedHashes = new Set<number>();
+  // In-flight background init chains (instant-hydrate + register enqueue) keyed
+  // by registration hash. Concurrent mounts of the same query reuse the one
+  // chain instead of double-hydrating and double-enqueuing `register`.
+  // Sequential re-mounts intentionally start a fresh chain — the unconditional
+  // `register` re-enqueue is what freshens a warm preload on use.
+  private pendingQueryInits = new Map<string, Promise<void>>();
 
   private logger: ReturnType<typeof createLogger>;
   public auth: AuthService<S>;
@@ -705,31 +718,96 @@ export class Sp00kyClient<S extends SchemaStructure> {
       q.selectQuery.plan
     );
 
-    // Instant-hydrate: for a cold query, fetch its rows one-shot from the remote
-    // (its own surql, run directly like useRemote) and display them NOW; the full
-    // realtime registration proceeds below. Hydrated rows carry their `_00_rv`
-    // versions so the registration's syncRecords skips re-pulling unchanged bodies.
-    // Best-effort: any failure (e.g. offline) just falls through to registration.
+    // Local-first paint: the hash is returned as soon as the LOCAL registration
+    // above completes — `queryState.records` is already seeded from the local
+    // cache/SSP snapshot, so `useQuery` subscribes and paints from memory with
+    // zero network on the paint path. Instant-hydrate and the `register`
+    // down-event continue in a background chain (hydrate strictly before
+    // enqueue, so a stale one-shot snapshot can never land after the sync's
+    // authoritative `_00_list_ref` overwrite). Concurrent mounts of the same
+    // query share one chain; a sequential re-mount starts a fresh one so its
+    // `register` re-enqueue keeps freshening warm data on use.
+    if (!this.pendingQueryInits.has(hash)) {
+      const chain = this.finishQueryInit(hash, q, params).finally(() => {
+        this.pendingQueryInits.delete(hash);
+      });
+      this.pendingQueryInits.set(hash, chain);
+    }
+
+    return hash;
+  }
+
+  /**
+   * Background tail of {@link initQuery}: instant-hydrate (when the query is
+   * cold AND wasn't freshly preloaded) followed by enqueuing the `register`
+   * down-event. Never rejects — both halves catch and log, so `void`-ing the
+   * returned promise can't produce an unhandled rejection.
+   *
+   * The fresh-preload skip: rows a recent `preload()` persisted are already in
+   * the local cache and were part of the first paint; the register lifecycle
+   * re-syncs them authoritatively, so the one-shot hydrate fetch would be a
+   * pure duplicate round trip. "Fresh" = preloaded this session
+   * (`preloadedHashes`) or a `_00_preload` marker younger than
+   * HYDRATE_PRELOAD_FRESH. Both are per-bucket (the Set is cleared on bucket
+   * switch, the marker table lives in the bucket), so neither can claim
+   * freshness across auth contexts.
+   */
+  private async finishQueryInit(
+    hash: string,
+    q: InnerQuery<any, any, any>,
+    params: Record<string, any>
+  ): Promise<void> {
     if (this.config.instantHydrate !== false && this.dataModule.isCold(hash)) {
       try {
-        const [rows] = await this.remote.query<[RecordWithId[]]>(q.selectQuery.query, params);
-        await this.dataModule.applyHydration(hash, rows ?? []);
+        const preloadFresh =
+          this.preloadedHashes.has(q.hash) ||
+          (await this.dataModule.isPreloadFresh(
+            String(q.hash),
+            parseDuration(HYDRATE_PRELOAD_FRESH)
+          ));
+        if (!preloadFresh) {
+          // Fence against bucket switches: rows fetched under the previous
+          // auth context must not hydrate the new bucket's query state — the
+          // rebind's re-registration refills it from the right context.
+          const epoch = this.local.epoch;
+          const [rows] = await this.remote.query<[RecordWithId[]]>(q.selectQuery.query, params);
+          if (epoch === this.local.epoch) {
+            await this.dataModule.applyHydration(hash, rows ?? []);
+          }
+        } else {
+          this.logger.debug(
+            { hash, Category: 'sp00ky-client::Sp00kyClient::instantHydrate' },
+            'Skipping instant hydrate; preload marker fresh'
+          );
+        }
       } catch (err) {
-        this.logger.warn(
-          { err, hash, Category: 'sp00ky-client::Sp00kyClient::instantHydrate' },
-          'Instant hydrate failed; proceeding with registration'
-        );
+        if (err instanceof StaleEpochError) {
+          this.logger.debug(
+            { hash, Category: 'sp00ky-client::Sp00kyClient::instantHydrate' },
+            'Dropped instant hydrate from before a bucket switch'
+          );
+        } else {
+          this.logger.warn(
+            { err, hash, Category: 'sp00ky-client::Sp00kyClient::instantHydrate' },
+            'Instant hydrate failed; proceeding with registration'
+          );
+        }
       }
     }
 
-    await this.sync.enqueueDownEvent({
-      type: 'register',
-      payload: {
-        hash,
-      },
-    });
-
-    return hash;
+    try {
+      await this.sync.enqueueDownEvent({
+        type: 'register',
+        payload: {
+          hash,
+        },
+      });
+    } catch (err) {
+      this.logger.error(
+        { err, hash, Category: 'sp00ky-client::Sp00kyClient::initQuery' },
+        'Failed to enqueue register down-event'
+      );
+    }
   }
 
   /**

package/src/types.ts

@@ -163,13 +163,16 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    */
   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.
+   * Instant-hydrate cold queries: when a query is registered with no server
+   * result yet, run its surql directly on the remote (one-shot) and display
+   * the result as soon as it lands, while the full realtime registration
+   * proceeds in the background. The hydrated rows are ingested with their
+   * versions so the registration's `syncRecords` skips re-pulling unchanged
+   * bodies. The fetch runs OFF the paint path — `useQuery` resolves and paints
+   * from the local cache immediately, and hydrate only fills in what's
+   * missing. Skipped entirely when the query was `preload()`ed recently (its
+   * rows are already local and fresh; the registration re-syncs them), so a
+   * preloaded screen costs zero duplicate fetches. Defaults to `true`.
    */
   instantHydrate?: boolean;
   /**