@spooky-sync/core 0.0.1-canary.131 → 0.0.1-canary.133

package/dist/index.d.ts

@@ -522,13 +522,6 @@ 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). */
@@ -1303,19 +1296,14 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   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.
+   * Background tail of {@link initQuery}: instant-hydrate (opt-in via
+   * `config.instantHydrate`, and only when the query is cold) 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. By default (hydrate off) the register lifecycle is the single
+   * freshness path; the one-shot fetch is an optimization apps enable
+   * explicitly, and it runs regardless of preload state — cache-first delivery
+   * never depends on WHY rows are cached.
    */
   private finishQueryInit;
   /**

package/dist/index.js

@@ -1693,9 +1693,14 @@ var SqliteCacheEngine = class {
 			});
 		});
 	}
-	async connect(bucketId) {
+	/**
+	* Spawn the worker and open `bucketId`'s DB. Uses {@link rawCall} (NOT
+	* {@link call}) so it can run as the body of an already-queued opQueue entry
+	* without re-queuing onto itself. Callers must run it through the opQueue.
+	*/
+	async openInternal(bucketId) {
 		this.worker = this.spawnWorker();
-		const { persisted } = await this.call("open", {
+		const { persisted } = await this.rawCall("open", {
 			dbName: bucketId,
 			useOpfs: this.useOpfs
 		});
@@ -1707,16 +1712,28 @@ var SqliteCacheEngine = class {
 			Category: "sp00ky-client::SqliteCacheEngine::connect"
 		}, persisted ? "SQLite OPFS store opened" : "SQLite in-memory store opened (no OPFS)");
 	}
+	/** Enqueue `fn` as a single serialized opQueue entry (mirrors {@link call}'s
+	*  chaining) so it can't interleave with reads/writes at the worker. */
+	enqueue(fn) {
+		const result = this.opQueue.then(fn, fn);
+		this.opQueue = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	async connect(bucketId) {
+		await this.enqueue(() => this.openInternal(bucketId));
+	}
 	async switchBucket(bucketId) {
 		this.storeEpoch++;
-		if (this.worker) {
-			try {
-				await this.call("close");
-			} catch {}
-			this.worker.terminate();
-			this.worker = null;
-		}
-		await this.connect(bucketId);
+		await this.enqueue(async () => {
+			if (this.worker) {
+				try {
+					await this.rawCall("close");
+				} catch {}
+				this.worker.terminate();
+				this.worker = null;
+			}
+			await this.openInternal(bucketId);
+		});
 	}
 	async close() {
 		if (!this.worker) return;
@@ -2795,16 +2812,6 @@ 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", new RecordId("_00_preload", hash), {
@@ -5141,8 +5148,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.131";
-const WASM_VERSION = "0.0.1-canary.131";
+const CORE_VERSION = "0.0.1-canary.133";
+const WASM_VERSION = "0.0.1-canary.133";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -7077,7 +7084,6 @@ 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;
@@ -7432,30 +7438,20 @@ var Sp00kyClient = class {
 		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.
+	* Background tail of {@link initQuery}: instant-hydrate (opt-in via
+	* `config.instantHydrate`, and only when the query is cold) 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. By default (hydrate off) the register lifecycle is the single
+	* freshness path; the one-shot fetch is an optimization apps enable
+	* explicitly, and it runs regardless of preload state — cache-first delivery
+	* never depends on WHY rows are cached.
 	*/
 	async finishQueryInit(hash, q, params) {
-		if (this.config.instantHydrate !== false && this.dataModule.isCold(hash)) try {
-			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");
+		if (this.config.instantHydrate === true && this.dataModule.isCold(hash)) try {
+			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 ?? []);
 		} catch (err) {
 			if (err instanceof StaleEpochError) this.logger.debug({
 				hash,

package/dist/types.d.ts

@@ -450,16 +450,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    */
   refSyncIntervalMs?: number;
   /**
-   * 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`.
+   * OPT-IN instant-hydrate for cold queries: when enabled and a query is
+   * registered with no server result yet, its surql also runs directly on the
+   * remote (one-shot, in the background, OFF the paint path) so rows can land
+   * before the full register lifecycle completes. Hydrated rows carry their
+   * `_00_rv` versions so the registration's `syncRecords` skips re-pulling
+   * unchanged bodies. Regardless of this flag, `useQuery` always resolves and
+   * paints from the local cache immediately — however the rows got there
+   * (preload, prior sync). Default `false`: the register lifecycle
+   * (`fn::query::register` → `_00_list_ref` → record sync) is the single
+   * freshness path and no duplicate one-shot fetches are made.
    */
   instantHydrate?: boolean;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.131",
+  "version": "0.0.1-canary.133",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.131",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.131",
+    "@spooky-sync/query-builder": "0.0.1-canary.133",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.133",
     "@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

@@ -4,11 +4,9 @@ import { DataModule } from './index';
 import type { QueryState } from '../../types';
 
 /**
- * Tests for instant-hydrate's DataModule half: `applyHydration` (run-once,
+ * 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).
+ * hydrate fetch moved off the paint path into a background chain.
  */
 
 function makeLogger(): any {
@@ -118,33 +116,27 @@ describe('DataModule.applyHydration', () => {
   });
 });
 
-describe('DataModule.isPreloadFresh', () => {
-  const maxAgeMs = 60_000;
-
-  function makeDm(getById: (table: string, id: string) => Promise<any>) {
+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('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('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('false when no marker exists', async () => {
-    const dm = makeDm(async () => null);
-    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  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('false when the marker read throws (treated as cold)', async () => {
+  it('returns null when the read throws', async () => {
     const dm = makeDm(async () => {
       throw new Error('boom');
     });
-    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+    expect(await dm.getPreloadMarker('h')).toBeNull();
   });
 });

package/src/modules/data/index.ts

@@ -890,17 +890,6 @@ 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> {
     // RecordId, not a bare string: the SurrealDB engine binds the id verbatim,

package/src/services/database/sqlite-cache-engine.test.ts

@@ -1,10 +1,98 @@
 import { describe, it, expect } from 'vitest';
 import { RecordId } from 'surrealdb';
-import { pureWriteOpResult } from './sqlite-cache-engine';
+import { pureWriteOpResult, SqliteCacheEngine } from './sqlite-cache-engine';
 import { translateSurql } from './surql-translate';
 import type { SqlOp } from './surql-translate';
 import { surql } from '../../utils/surql';
 
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+/**
+ * A fake Worker that models the real SQLite worker's open/closed lifecycle:
+ * `open` opens the DB, `close` closes it, and `exec`/`run` REJECT with
+ * "sqlite: DB not open" when the DB isn't currently open — exactly the failure
+ * the fix targets. Records every message `type` (across worker generations) so
+ * tests can also inspect dispatch order.
+ */
+class FakeWorker {
+  onmessage: ((ev: any) => void) | null = null;
+  onerror: any = null;
+  onmessageerror: any = null;
+  private dbOpen = false;
+  constructor(private log: string[]) {}
+  postMessage(msg: any) {
+    this.log.push(msg.type);
+    Promise.resolve().then(() => {
+      let ok = true;
+      let error: string | undefined;
+      let rest: Record<string, unknown> = {};
+      if (msg.type === 'open') {
+        this.dbOpen = true;
+        rest = { persisted: true };
+      } else if (msg.type === 'close') {
+        this.dbOpen = false;
+      } else if (msg.type === 'exec') {
+        if (!this.dbOpen) { ok = false; error = 'sqlite: DB not open'; }
+        else rest = { rows: [] };
+      } else if (msg.type === 'run' || msg.type === 'batch') {
+        if (!this.dbOpen) { ok = false; error = 'sqlite: DB not open'; }
+      }
+      this.onmessage?.({ data: { id: msg.id, ok, error, ...rest } });
+    });
+  }
+  terminate() {}
+}
+
+// Regression: switchBucket must run close → reopen as a single serialized
+// opQueue entry. Otherwise a read/write enqueued during an auth/bucket change
+// dispatches to the just-closed worker → "sqlite: DB not open" (the crash on
+// sign-in). The invariant: no `exec` may appear between a `close` and the next
+// `open` in the message stream.
+describe('SqliteCacheEngine.switchBucket serialization', () => {
+  it('never dispatches an op to a closed DB during a bucket switch', async () => {
+    const log: string[] = [];
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
+    // Replicate the real spawnWorker's onmessage wiring (resolve/reject pending).
+    (engine as any).spawnWorker = () => {
+      const w = new FakeWorker(log);
+      w.onmessage = (ev: any) => {
+        const { id, ok, error, ...rest } = ev.data ?? {};
+        const p = (engine as any).pending.get(id);
+        if (!p) return;
+        (engine as any).pending.delete(id);
+        if (ok) p.resolve(rest);
+        else p.reject(new Error(error));
+      };
+      return w as unknown as Worker;
+    };
+
+    await engine.connect('anon');
+    expect(log).toContain('open');
+
+    // Fire a switch and a concurrent read (exactly what the sign-in query
+    // re-registration does). With the old non-atomic switch the read's `exec`
+    // dispatched to the closed/terminated worker and REJECTED ("sqlite: DB not
+    // open" / "not connected") — the uncaught crash. The atomic switch makes the
+    // read wait for the reopen and resolve against the new bucket.
+    const switching = engine.switchBucket('user:abc');
+    const reading = engine.getById('_00_query', 'h1');
+    await expect(Promise.all([switching, reading])).resolves.toBeDefined();
+    await expect(reading).resolves.toBeNull(); // missing row → null, not a throw
+
+    // And the close→reopen ran with no op wedged between them.
+    const closeIdx = log.indexOf('close');
+    const openAfter = log.indexOf('open', closeIdx + 1);
+    expect(openAfter).toBeGreaterThan(closeIdx);
+    expect(log.slice(closeIdx + 1, openAfter)).not.toContain('exec');
+    expect(engine.currentBucketId).toBe('user:abc');
+  });
+});
+
 // `pureWriteOpResult` is the single source of truth for what a pure-write op
 // contributes to a query's per-statement results. The batched fast path in
 // `query()` and the per-op `execOp` path BOTH route through it, so a caller that

package/src/services/database/sqlite-cache-engine.ts

@@ -185,9 +185,14 @@ export class SqliteCacheEngine implements LocalStore {
     });
   }
 
-  async connect(bucketId: string): Promise<void> {
+  /**
+   * Spawn the worker and open `bucketId`'s DB. Uses {@link rawCall} (NOT
+   * {@link call}) so it can run as the body of an already-queued opQueue entry
+   * without re-queuing onto itself. Callers must run it through the opQueue.
+   */
+  private async openInternal(bucketId: string): Promise<void> {
     this.worker = this.spawnWorker();
-    const { persisted } = await this.call<{ persisted: boolean }>('open', {
+    const { persisted } = await this.rawCall<{ persisted: boolean }>('open', {
       dbName: bucketId,
       useOpfs: this.useOpfs,
     });
@@ -199,18 +204,43 @@ export class SqliteCacheEngine implements LocalStore {
     );
   }
 
+  /** Enqueue `fn` as a single serialized opQueue entry (mirrors {@link call}'s
+   *  chaining) so it can't interleave with reads/writes at the worker. */
+  private enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    const result = this.opQueue.then(fn, fn);
+    this.opQueue = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+
+  async connect(bucketId: string): Promise<void> {
+    // Serialize through the opQueue so an op racing boot can't dispatch to a
+    // half-open worker.
+    await this.enqueue(() => this.openInternal(bucketId));
+  }
+
   async switchBucket(bucketId: string): Promise<void> {
     this.storeEpoch++;
-    if (this.worker) {
-      try {
-        await this.call('close');
-      } catch {
-        /* ignore */
+    // Run close → terminate → reopen as ONE opQueue entry. Previously `close`
+    // and the new `open` were separate entries, so a query's `exec` (e.g. the
+    // query re-registration fired by an auth/bucket change) could slot in
+    // between and dispatch to the just-closed worker → "sqlite: DB not open".
+    // As a single entry, every other op runs fully before the close or after
+    // the reopen — never against a closed DB.
+    await this.enqueue(async () => {
+      if (this.worker) {
+        try {
+          await this.rawCall('close');
+        } catch {
+          /* ignore */
+        }
+        this.worker.terminate();
+        this.worker = null;
       }
-      this.worker.terminate();
-      this.worker = null;
-    }
-    await this.connect(bucketId);
+      await this.openInternal(bucketId);
+    });
   }
 
   async close(): Promise<void> {

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

@@ -5,11 +5,12 @@ 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.
+// network on the awaited path, while the opt-in instant-hydrate + the
+// `register` down-event run in a background chain that (a) keeps hydrate
+// strictly before the enqueue, (b) hydrates only when `instantHydrate:
+// true` (default off — the register lifecycle is the single freshness
+// path), (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
@@ -73,7 +74,6 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
   let calls: string[];
   let enqueued: any[];
   let epoch: number;
-  let preloadFresh: boolean;
   let cold: boolean;
   let remoteImpl: () => Promise<any>;
 
@@ -81,7 +81,6 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
     calls = [];
     enqueued = [];
     epoch = 1;
-    preloadFresh = false;
     cold = true;
     remoteImpl = async () => {
       calls.push('fetch');
@@ -112,7 +111,6 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
       },
       dataModule: {
         isCold: () => cold,
-        isPreloadFresh: async () => preloadFresh,
         applyHydration: async () => {
           calls.push('hydrate');
         },
@@ -121,22 +119,16 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
     });
   });
 
-  it('cold path: fetch → hydrate → enqueue, in order', async () => {
+  it('cold path with hydrate enabled: 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 () => {
+  it('a preloaded query still hydrates when enabled — cache-first never depends on WHY rows are cached', 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']);
+    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
   });
 
   it('warm query (not cold) goes straight to enqueue', async () => {
@@ -164,7 +156,13 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
     expect(calls).toEqual(['fetch', 'enqueue']);
   });
 
-  it('instantHydrate: false disables the hydrate fetch entirely', async () => {
+  it('default (instantHydrate unset) does not hydrate — register lifecycle is the only freshness path', async () => {
+    delete client.config.instantHydrate;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('instantHydrate: false does not hydrate', async () => {
     client.config.instantHydrate = false;
     await client.finishQueryInit(hash, q, {});
     expect(calls).toEqual(['enqueue']);

package/src/sp00ky.ts

@@ -103,12 +103,6 @@ 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;
@@ -738,47 +732,29 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   /**
-   * 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.
+   * Background tail of {@link initQuery}: instant-hydrate (opt-in via
+   * `config.instantHydrate`, and only when the query is cold) 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. By default (hydrate off) the register lifecycle is the single
+   * freshness path; the one-shot fetch is an optimization apps enable
+   * explicitly, and it runs regardless of preload state — cache-first delivery
+   * never depends on WHY rows are cached.
    */
   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)) {
+    if (this.config.instantHydrate === true && this.dataModule.isCold(hash)) {
       try {
-        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'
-          );
+        // 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 ?? []);
         }
       } catch (err) {
         if (err instanceof StaleEpochError) {

package/src/types.ts

@@ -163,16 +163,16 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    */
   refSyncIntervalMs?: number;
   /**
-   * 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`.
+   * OPT-IN instant-hydrate for cold queries: when enabled and a query is
+   * registered with no server result yet, its surql also runs directly on the
+   * remote (one-shot, in the background, OFF the paint path) so rows can land
+   * before the full register lifecycle completes. Hydrated rows carry their
+   * `_00_rv` versions so the registration's `syncRecords` skips re-pulling
+   * unchanged bodies. Regardless of this flag, `useQuery` always resolves and
+   * paints from the local cache immediately — however the rows got there
+   * (preload, prior sync). Default `false`: the register lifecycle
+   * (`fn::query::register` → `_00_list_ref` → record sync) is the single
+   * freshness path and no duplicate one-shot fetches are made.
    */
   instantHydrate?: boolean;
   /**