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

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

@@ -1283,25 +1283,36 @@ var SurrealCacheEngine = class extends LocalDatabaseService {
 		}
 		return result;
 	}
-	async getById(_table, id) {
-		const [row] = await this.query("SELECT * FROM ONLY $__id;", { __id: id });
-		return row ?? null;
+	/**
+	* Coerce the contract's `Id` (a RecordId, a stable `table:id` string, or a
+	* bare id + the verb's `table` param) to a real RecordId. SurrealDB binds
+	* `$__id` verbatim: a plain string makes `FROM ONLY $__id` "select" the
+	* string itself (a truthy non-row) and `UPSERT $__id` an InternalError, so
+	* string ids silently broke every id-verb on this engine.
+	*/
+	toRecordId(table, id) {
+		if (typeof id !== "string") return id;
+		return new RecordId(table, id.startsWith(`${table}:`) ? id.slice(table.length + 1) : id);
+	}
+	async getById(table, id) {
+		const [row] = await this.query("SELECT * FROM ONLY $__id;", { __id: this.toRecordId(table, id) });
+		return row && typeof row === "object" ? row : null;
 	}
-	async upsert(_table, id, data, mode) {
+	async upsert(table, id, data, mode) {
 		const sql = mode === "merge" ? surql.upsertMerge("__id", "__data") : surql.upsert("__id", "__data");
 		await this.query(surql.seal(sql), {
-			__id: id,
+			__id: this.toRecordId(table, id),
 			__data: data
 		});
 	}
-	async patch(_table, id, patches) {
+	async patch(table, id, patches) {
 		await this.query(surql.seal("UPDATE ONLY $__id PATCH $__patches"), {
-			__id: id,
+			__id: this.toRecordId(table, id),
 			__patches: patches
 		});
 	}
-	async delete(_table, id) {
-		await this.query(surql.seal(surql.delete("__id")), { __id: id });
+	async delete(table, id) {
+		await this.query(surql.seal(surql.delete("__id")), { __id: this.toRecordId(table, id) });
 	}
 	/**
 	* Serialized (not strictly atomic) transaction: verbs run in order on the
@@ -2774,8 +2785,8 @@ var DataModule = class {
 	*/
 	async getPreloadMarker(hash) {
 		try {
-			const row = await this.local.getById("_00_preload", hash);
-			if (!row) return null;
+			const row = await this.local.getById("_00_preload", new RecordId("_00_preload", hash));
+			if (!row || typeof row !== "object") return null;
 			return {
 				fetchedAt: Number(row.fetchedAt) || 0,
 				rowCount: Number(row.rowCount) || 0
@@ -2784,19 +2795,9 @@ 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, {
+		await this.local.upsert("_00_preload", new RecordId("_00_preload", hash), {
 			fetchedAt: Date.now(),
 			rowCount
 		}, "replace");
@@ -5130,8 +5131,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.130";
-const WASM_VERSION = "0.0.1-canary.130";
+const CORE_VERSION = "0.0.1-canary.132";
+const WASM_VERSION = "0.0.1-canary.132";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -7066,7 +7067,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;
@@ -7421,30 +7421,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.130",
+  "version": "0.0.1-canary.132",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.130",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.130",
+    "@spooky-sync/query-builder": "0.0.1-canary.132",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.132",
     "@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

@@ -876,8 +876,11 @@ export class DataModule<S extends SchemaStructure> {
     hash: string
   ): Promise<{ fetchedAt: number; rowCount: number } | null> {
     try {
-      const row = await this.local.getById('_00_preload', hash);
-      if (!row) return null;
+      // Pass a real RecordId: a bare string id hits the SurrealDB engine's
+      // `FROM ONLY $__id` as a plain string, which "selects" the string itself
+      // (a truthy non-row) instead of the record — misread as a warm marker.
+      const row = await this.local.getById('_00_preload', new RecordId('_00_preload', hash));
+      if (!row || typeof row !== 'object') return null;
       return {
         fetchedAt: Number((row as any).fetchedAt) || 0,
         rowCount: Number((row as any).rowCount) || 0,
@@ -887,22 +890,14 @@ 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,
+    // and `UPSERT <string>` is an InternalError — the marker silently never
+    // landed (the write is awaited inside preload's best-effort catch).
     await this.local.upsert(
       '_00_preload',
-      hash,
+      new RecordId('_00_preload', hash),
       { fetchedAt: Date.now(), rowCount },
       'replace'
     );

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

@@ -15,6 +15,7 @@ import type {
 } from './cache-engine';
 import { stableKey } from './relation-resolver';
 import { surql } from '../../utils/surql';
+import { RecordId } from 'surrealdb';
 
 /**
  * Default local cache backend: the in-browser SurrealDB-WASM store. Implemented
@@ -83,25 +84,41 @@ export class SurrealCacheEngine extends LocalDatabaseService implements LocalCac
     return result;
   }
 
-  async getById(_table: string, id: Id): Promise<Row | null> {
-    const [row] = await this.query<[Row | null]>('SELECT * FROM ONLY $__id;', { __id: id });
-    return row ?? null;
+  /**
+   * Coerce the contract's `Id` (a RecordId, a stable `table:id` string, or a
+   * bare id + the verb's `table` param) to a real RecordId. SurrealDB binds
+   * `$__id` verbatim: a plain string makes `FROM ONLY $__id` "select" the
+   * string itself (a truthy non-row) and `UPSERT $__id` an InternalError, so
+   * string ids silently broke every id-verb on this engine.
+   */
+  private toRecordId(table: string, id: Id): unknown {
+    if (typeof id !== 'string') return id;
+    const raw = id.startsWith(`${table}:`) ? id.slice(table.length + 1) : id;
+    return new RecordId(table, raw);
+  }
+
+  async getById(table: string, id: Id): Promise<Row | null> {
+    const [row] = await this.query<[Row | null]>('SELECT * FROM ONLY $__id;', {
+      __id: this.toRecordId(table, id),
+    });
+    // `FROM ONLY <non-record>` echoes the value back; only a real row counts.
+    return row && typeof row === 'object' ? row : null;
   }
 
-  async upsert(_table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void> {
+  async upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void> {
     const sql = mode === 'merge' ? surql.upsertMerge('__id', '__data') : surql.upsert('__id', '__data');
-    await this.query(surql.seal(sql), { __id: id, __data: data });
+    await this.query(surql.seal(sql), { __id: this.toRecordId(table, id), __data: data });
   }
 
-  async patch(_table: string, id: Id, patches: unknown[]): Promise<void> {
+  async patch(table: string, id: Id, patches: unknown[]): Promise<void> {
     await this.query(surql.seal('UPDATE ONLY $__id PATCH $__patches'), {
-      __id: id,
+      __id: this.toRecordId(table, id),
       __patches: patches,
     });
   }
 
-  async delete(_table: string, id: Id): Promise<void> {
-    await this.query(surql.seal(surql.delete('__id')), { __id: id });
+  async delete(table: string, id: Id): Promise<void> {
+    await this.query(surql.seal(surql.delete('__id')), { __id: this.toRecordId(table, id) });
   }
 
   /**

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;
   /**