@spooky-sync/core 0.0.1-canary.75 → 0.0.1-canary.76

package/dist/index.d.ts

@@ -186,6 +186,7 @@ declare class StreamProcessorService {
   private receivers;
   private batching;
   private batchBuffer;
+  private sessionAuth;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -240,6 +241,17 @@ declare class StreamProcessorService {
    * non-`_00_` tables are default-denied and registration fails.
    */
   setPermissions(permissions: Record<string, string>): void;
+  /**
+   * Set the current session's auth identity for permission injection,
+   * mirroring the server's `fn::query::register`
+   * (`object::extend(params, { auth: { id: $auth.id }, access: $access })`).
+   * Stored as strings (empty when logged out) and applied to every
+   * `register_view` in {@link registerQueryPlan}. Must be set before a
+   * `$auth`-gated query registers (and re-set on auth state changes), or the
+   * in-browser SSP's `permission_inject` rejects it with
+   * "requires $auth but registration params lack it".
+   */
+  setSessionAuth(authId: string | null, access: string | null): void;
   saveState(): Promise<void>;
   /**
    * Ingest a record change into the processor.
@@ -464,6 +476,18 @@ declare class DataModule<S extends SchemaStructure> {
    * still hydrate. A warm re-subscribe (remoteArray already populated) is skipped.
    */
   isCold(hash: string): boolean;
+  /**
+   * Walk a hydrated record's fields and append any EMBEDDED child records to
+   * `batch` (recursing for nested related fields). An embedded child is a
+   * value that is itself a record — a non-null object whose `id` is a
+   * `RecordId` — or an array of such records (one-to-many vs one-to-one). A
+   * bare `RecordId` (a foreign-key reference) or any other value is skipped,
+   * so this never mistakes a FK column for an embedded body. Children are
+   * keyed by their own `record.id.table`, versioned by `_00_rv`, and cleaned
+   * to their table's real columns (which strips the alias/related fields).
+   * `seen` dedupes within the batch.
+   */
+  private collectEmbeddedChildren;
   /**
    * Instant-hydrate: ingest rows fetched one-shot from the remote (the query's own
    * surql run directly) so the query DISPLAYS immediately, while the full realtime
@@ -651,6 +675,19 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private subscribeToReconnect;
   private startRefLiveQueries;
   private handleRemoteListRefChange;
+  /**
+   * Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
+   * `parent` set) for a `.related()` query. Unlike primary rows, child rows
+   * must NOT touch the query's `localArray`/`remoteArray`/`rowCount`; we only
+   * keep the child BODY fresh in the local cache so the in-browser SSP's
+   * subquery-table dependency re-materializes the parent view.
+   *
+   * CREATE/UPDATE fetch+upsert the child body. DELETE is intentionally a
+   * no-op: a child leaving this query's set must not delete a body another
+   * query may still show (see `syncSubqueryChildren` deletion-safety note);
+   * a genuine record delete propagates via the normal delete path.
+   */
+  private handleRemoteSubqueryChange;
   /**
    * Enqueues a 'down' event (from remote to local) for processing.
    * @param event The DownEvent to enqueue.
@@ -687,6 +724,26 @@ declare class Sp00kySync<S extends SchemaStructure> {
   enqueueMutation(mutations: UpEvent[]): Promise<void>;
   private registerQuery;
   private createRemoteQuery;
+  /**
+   * Sync the BODIES of a `.related()` query's subquery child rows into the
+   * local cache, separately from the primary window array. The SSP writes
+   * each matched child as a `_00_list_ref` edge tagged `parent`/`parent_rel`;
+   * `buildSubqueryListRefSelect` pulls those `out`+`version` pairs (any
+   * nesting depth). We diff against the in-memory `subqueryRemoteArray` and
+   * fetch added/updated bodies through the SyncEngine — which `saveBatch`s
+   * them into the local DB AND the in-browser SSP, whose subquery-table
+   * dependency then re-materializes the parent view (no explicit notify).
+   *
+   * Deletion safety: we pass `removed: []` deliberately. A child body can be
+   * shared by other queries; letting `handleRemovedRecords` delete one that
+   * merely left THIS query's child set would clobber data another query still
+   * shows. Genuine record deletes flow through the normal delete path; a
+   * lingering orphan body is invisible (the correlated WHERE stops matching).
+   *
+   * Kept off `runSyncForQuery` on purpose so child fetches never flip the
+   * query to `fetching` or skew its DevTools timings.
+   */
+  private syncSubqueryChildren;
   heartbeatQuery(queryHash: string): Promise<void>;
   private cleanupQuery;
 }
@@ -713,6 +770,13 @@ declare class AuthService<S extends SchemaStructure> {
   token: string | null;
   currentUser: any | null;
   isAuthenticated: boolean;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  access: string | null;
   isLoading: boolean;
   private events;
   get eventSystem(): AuthEventSystem;
@@ -734,6 +798,9 @@ declare class AuthService<S extends SchemaStructure> {
    */
   signOut(): Promise<void>;
   private setSession;
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName;
   signUp<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signup'>): Promise<void>;
   signIn<Name extends keyof S['access'] & string>(accessName: Name, params: ExtractAccessParams<S, Name, 'signIn'>): Promise<void>;
 }

package/dist/index.js

@@ -747,6 +747,37 @@ var DataModule = class {
 		return !!qs && !qs.hydrated && (qs.config.remoteArray?.length ?? 0) === 0;
 	}
 	/**
+	* Walk a hydrated record's fields and append any EMBEDDED child records to
+	* `batch` (recursing for nested related fields). An embedded child is a
+	* value that is itself a record — a non-null object whose `id` is a
+	* `RecordId` — or an array of such records (one-to-many vs one-to-one). A
+	* bare `RecordId` (a foreign-key reference) or any other value is skipped,
+	* so this never mistakes a FK column for an embedded body. Children are
+	* keyed by their own `record.id.table`, versioned by `_00_rv`, and cleaned
+	* to their table's real columns (which strips the alias/related fields).
+	* `seen` dedupes within the batch.
+	*/
+	collectEmbeddedChildren(record, batch, seen) {
+		const isEmbeddedRecord = (v) => !!v && typeof v === "object" && !(v instanceof RecordId) && v.id instanceof RecordId;
+		for (const value of Object.values(record)) {
+			const children = Array.isArray(value) ? value.filter(isEmbeddedRecord) : isEmbeddedRecord(value) ? [value] : [];
+			for (const child of children) {
+				const key = encodeRecordId(child.id);
+				if (seen.has(key)) continue;
+				seen.add(key);
+				this.collectEmbeddedChildren(child, batch, seen);
+				const table = child.id.table.toString();
+				const tableSchema = this.schema.tables.find((t) => t.name === table);
+				batch.push({
+					table,
+					op: "CREATE",
+					record: tableSchema ? cleanRecord(tableSchema.columns, child) : child,
+					version: child._00_rv || 1
+				});
+			}
+		}
+	}
+	/**
 	* Instant-hydrate: ingest rows fetched one-shot from the remote (the query's own
 	* surql run directly) so the query DISPLAYS immediately, while the full realtime
 	* registration proceeds in the background. Ingests with versions (`_00_rv`) so the
@@ -766,6 +797,8 @@ var DataModule = class {
 			record,
 			version: record._00_rv || 1
 		}));
+		const seen = new Set(rows.map((r) => encodeRecordId(r.id)));
+		for (const record of rows) this.collectEmbeddedChildren(record, batch, seen);
 		await this.cache.saveBatch(batch);
 		queryState.config.remoteArray = rows.map((r) => [encodeRecordId(r.id), r._00_rv || 1]);
 		queryState.records = await this.materializeRecords(queryState);
@@ -2244,6 +2277,21 @@ function buildListRefSelect(table) {
 	return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NONE`;
 }
 /**
+* Build the SurrealQL select for a query's SUBQUERY child edges — the
+* mirror of {@link buildListRefSelect}. `.related()` queries register a
+* correlated subquery; the SSP materializes each matched child as a
+* `_00_list_ref` edge tagged with `parent`/`parent_rel` (see
+* `apps/ssp` edge writer). `parent IS NONE` (the primary select) drops
+* these, so their bodies never reach the local cache and a cold-reload
+* re-materialization of the correlated surql yields empty related
+* fields. This `parent IS NOT NONE` variant pulls the child `out`+`version`
+* pairs (any nesting depth) so we can sync their bodies into the local
+* store SEPARATELY from the primary window array.
+*/
+function buildSubqueryListRefSelect(table) {
+	return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NOT NONE`;
+}
+/**
 * Resolve the effective list-ref poll interval. Negative or zero
 * values fall back to the default — accepting them would either
 * disable polling silently or busy-loop the event loop.
@@ -2743,6 +2791,13 @@ var Sp00kySync = class {
 				Category: "sp00ky-client::Sp00kySync::refetchListRefForQuery"
 			}, "syncQuery failed during poll");
 		}
+		await this.syncSubqueryChildren(queryHash).catch((err) => {
+			this.logger.info({
+				err: err?.message ?? err,
+				queryHash,
+				Category: "sp00ky-client::Sp00kySync::refetchListRefForQuery"
+			}, "Subquery child sync failed during poll");
+		});
 		if (removedIds.length > 0) try {
 			await this.dataModule.notifyQuerySynced(queryHash);
 		} catch (err) {
@@ -2827,7 +2882,15 @@ var Sp00kySync = class {
 				Category: "sp00ky-client::Sp00kySync::startRefLiveQueries"
 			}, "Live update received");
 			if (message.action === "KILLED") return;
-			if (message.value.parent != null) return;
+			if (message.value.parent != null) {
+				this.handleRemoteSubqueryChange(message.action, message.value.in, message.value.out, message.value.version).catch((err) => {
+					this.logger.error({
+						err,
+						Category: "sp00ky-client::Sp00kySync::startRefLiveQueries"
+					}, "Error handling remote subquery change");
+				});
+				return;
+			}
 			this.handleRemoteListRefChange(message.action, message.value.in, message.value.out, message.value.version).catch((err) => {
 				this.logger.error({
 					err,
@@ -2861,6 +2924,41 @@ var Sp00kySync = class {
 		await this.runSyncForQuery(hash, diff);
 	}
 	/**
+	* Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
+	* `parent` set) for a `.related()` query. Unlike primary rows, child rows
+	* must NOT touch the query's `localArray`/`remoteArray`/`rowCount`; we only
+	* keep the child BODY fresh in the local cache so the in-browser SSP's
+	* subquery-table dependency re-materializes the parent view.
+	*
+	* CREATE/UPDATE fetch+upsert the child body. DELETE is intentionally a
+	* no-op: a child leaving this query's set must not delete a body another
+	* query may still show (see `syncSubqueryChildren` deletion-safety note);
+	* a genuine record delete propagates via the normal delete path.
+	*/
+	async handleRemoteSubqueryChange(action, queryId, childId, version) {
+		this.lastLiveEventAt = Date.now();
+		this.listRefIdleStreak = 0;
+		if (action === "DELETE") return;
+		const existing = this.dataModule.getQueryById(queryId);
+		if (!existing) return;
+		const item = {
+			id: childId,
+			version
+		};
+		await this.syncEngine.syncRecords(action === "CREATE" ? {
+			added: [item],
+			updated: [],
+			removed: []
+		} : {
+			added: [],
+			updated: [item],
+			removed: []
+		});
+		const key = encodeRecordId(childId);
+		const prev = existing.config.subqueryRemoteArray ?? [];
+		existing.config.subqueryRemoteArray = [...prev.filter(([id]) => id !== key), [key, version]];
+	}
+	/**
 	* Enqueues a 'down' event (from remote to local) for processing.
 	* @param event The DownEvent to enqueue.
 	*/
@@ -3083,6 +3181,49 @@ var Sp00kySync = class {
 			Category: "sp00ky-client::Sp00kySync::createRemoteQuery"
 		}, "createdRemoteQuery");
 		if (array) await this.dataModule.updateQueryRemoteArray(queryHash, array);
+		await this.syncSubqueryChildren(queryHash).catch((err) => {
+			this.logger.info({
+				err: err?.message ?? err,
+				queryHash,
+				Category: "sp00ky-client::Sp00kySync::createRemoteQuery"
+			}, "Subquery child sync failed during registration; poll will retry");
+		});
+	}
+	/**
+	* Sync the BODIES of a `.related()` query's subquery child rows into the
+	* local cache, separately from the primary window array. The SSP writes
+	* each matched child as a `_00_list_ref` edge tagged `parent`/`parent_rel`;
+	* `buildSubqueryListRefSelect` pulls those `out`+`version` pairs (any
+	* nesting depth). We diff against the in-memory `subqueryRemoteArray` and
+	* fetch added/updated bodies through the SyncEngine — which `saveBatch`s
+	* them into the local DB AND the in-browser SSP, whose subquery-table
+	* dependency then re-materializes the parent view (no explicit notify).
+	*
+	* Deletion safety: we pass `removed: []` deliberately. A child body can be
+	* shared by other queries; letting `handleRemovedRecords` delete one that
+	* merely left THIS query's child set would clobber data another query still
+	* shows. Genuine record deletes flow through the normal delete path; a
+	* lingering orphan body is invisible (the correlated WHERE stops matching).
+	*
+	* Kept off `runSyncForQuery` on purpose so child fetches never flip the
+	* query to `fetching` or skew its DevTools timings.
+	*/
+	async syncSubqueryChildren(queryHash) {
+		const queryState = this.dataModule.getQueryByHash(queryHash);
+		if (!queryState) return;
+		const listRefTbl = this.listRefTable();
+		const [items] = await this.remote.query(buildSubqueryListRefSelect(listRefTbl), { in: queryState.config.id });
+		if (!Array.isArray(items)) return;
+		const fresh = items.map((item) => [encodeRecordId(item.out), item.version]);
+		const prev = queryState.config.subqueryRemoteArray ?? [];
+		if (recordVersionArraysEqual(fresh, prev)) return;
+		const diff = diffRecordVersionArray(prev, fresh);
+		if (diff.added.length > 0 || diff.updated.length > 0) await this.syncEngine.syncRecords({
+			added: diff.added,
+			updated: diff.updated,
+			removed: []
+		});
+		queryState.config.subqueryRemoteArray = fresh;
 	}
 	async heartbeatQuery(queryHash) {
 		const queryState = this.dataModule.getQueryByHash(queryHash);
@@ -3171,8 +3312,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.75";
-const WASM_VERSION = "0.0.1-canary.75";
+const CORE_VERSION = "0.0.1-canary.76";
+const WASM_VERSION = "0.0.1-canary.76";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -3463,10 +3604,38 @@ var DevToolsService = class {
 
 //#endregion
 //#region src/modules/auth/index.ts
+/**
+* Read the `AC` (access-method name) claim from a SurrealDB record-access
+* JWT without verifying it — we only need the claim, the server enforces the
+* token. Returns null on any malformed input. The in-browser SSP needs this
+* to resolve `$access` in table permission predicates (mirrors the session's
+* `$access` that the server's `fn::query::register` reads).
+*/
+function decodeAccessFromToken(token) {
+	try {
+		const payload = token.split(".")[1];
+		if (!payload) return null;
+		let b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+		b64 += "=".repeat((4 - b64.length % 4) % 4);
+		const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("binary");
+		const claims = JSON.parse(json);
+		const ac = claims.AC ?? claims.ac;
+		return typeof ac === "string" ? ac : null;
+	} catch {
+		return null;
+	}
+}
 var AuthService = class {
 	token = null;
 	currentUser = null;
 	isAuthenticated = false;
+	/**
+	* The record-access method name for the current session (e.g. `"account"`),
+	* derived from the token's `AC` claim. Consumed by the in-browser SSP's
+	* permission injection so `$access`-gated table predicates resolve locally,
+	* mirroring the server's `$access`. Null when logged out.
+	*/
+	access = null;
 	isLoading = true;
 	events = createAuthEventSystem();
 	get eventSystem() {
@@ -3559,6 +3728,7 @@ var AuthService = class {
 		this.token = null;
 		this.currentUser = null;
 		this.isAuthenticated = false;
+		this.access = null;
 		await this.persistenceClient.remove("sp00ky_auth_token");
 		try {
 			await this.remote.getClient().invalidate();
@@ -3569,9 +3739,16 @@ var AuthService = class {
 		this.token = token;
 		this.currentUser = user;
 		this.isAuthenticated = true;
+		this.access = decodeAccessFromToken(token) ?? this.defaultAccessName();
 		await this.persistenceClient.set("sp00ky_auth_token", token);
 		this.notifyListeners();
 	}
+	/** Fallback when the token carries no `AC` claim: if the schema defines
+	*  exactly one record-access method, assume the session used it. */
+	defaultAccessName() {
+		const names = Object.keys(this.schema.access ?? {});
+		return names.length === 1 ? names[0] : null;
+	}
 	async signUp(accessName, params) {
 		const def = this.getAccessDefinition(accessName);
 		if (!def) throw new Error(`Access definition '${accessName}' not found`);
@@ -3617,6 +3794,10 @@ var StreamProcessorService = class {
 	receivers = [];
 	batching = false;
 	batchBuffer = /* @__PURE__ */ new Map();
+	sessionAuth = {
+		authId: "",
+		access: ""
+	};
 	constructor(events, db, persistenceClient, logger) {
 		this.events = events;
 		this.db = db;
@@ -3757,6 +3938,27 @@ var StreamProcessorService = class {
 			Category: "sp00ky-client::StreamProcessorService::setPermissions"
 		}, "Seeded table permissions");
 	}
+	/**
+	* Set the current session's auth identity for permission injection,
+	* mirroring the server's `fn::query::register`
+	* (`object::extend(params, { auth: { id: $auth.id }, access: $access })`).
+	* Stored as strings (empty when logged out) and applied to every
+	* `register_view` in {@link registerQueryPlan}. Must be set before a
+	* `$auth`-gated query registers (and re-set on auth state changes), or the
+	* in-browser SSP's `permission_inject` rejects it with
+	* "requires $auth but registration params lack it".
+	*/
+	setSessionAuth(authId, access) {
+		this.sessionAuth = {
+			authId: authId ?? "",
+			access: access ?? ""
+		};
+		this.logger.debug({
+			authId: this.sessionAuth.authId,
+			access: this.sessionAuth.access,
+			Category: "sp00ky-client::StreamProcessorService::setSessionAuth"
+		}, "Session auth context updated");
+	}
 	async saveState() {
 		if (!this.processor) return;
 		try {
@@ -3841,11 +4043,15 @@ var StreamProcessorService = class {
 			Category: "sp00ky-client::StreamProcessorService::registerQueryPlan"
 		}, "Registering query plan");
 		try {
-			const normalizedParams = this.normalizeValue(queryPlan.params);
+			const paramsWithAuth = {
+				...this.normalizeValue(queryPlan.params),
+				auth: { id: this.sessionAuth.authId },
+				access: this.sessionAuth.access
+			};
 			const initialUpdate = this.processor.register_view({
 				id: queryPlan.queryHash,
 				surql: queryPlan.surql,
-				params: normalizedParams,
+				params: paramsWithAuth,
 				clientId: "local",
 				ttl: queryPlan.ttl.toString(),
 				lastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -5047,6 +5253,7 @@ var Sp00kyClient = class {
 			}, "DataModule initialized");
 			this.auth.subscribe(async (userId) => {
 				this.dataModule.setCurrentUserId(userId);
+				this.streamProcessor.setSessionAuth(this.auth.currentUser?.id ? encodeRecordId(this.auth.currentUser.id) : null, this.auth.access);
 				const next = await this.fetchSessionId();
 				this.dataModule.setSessionId(next);
 				this.crdtManager.setSessionId(next);

package/dist/types.d.ts

@@ -327,6 +327,14 @@ interface QueryConfig {
   localArray: RecordVersionArray;
   /** The version array representing the remote (server) state of results. */
   remoteArray: RecordVersionArray;
+  /**
+   * In-memory only (never persisted to `_00_query`): version array of the
+   * subquery CHILD rows pulled via `parent IS NOT NONE` edges, so the
+   * child-body sync is idempotent across polls. Kept separate from
+   * `remoteArray` so related child rows never enter the primary window /
+   * `rowCount` / `localArray`.
+   */
+  subqueryRemoteArray?: RecordVersionArray;
   /** Time-To-Live for this query. */
   ttl: QueryTimeToLive;
   /** Timestamp when the query was last accessed/active. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.75",
+  "version": "0.0.1-canary.76",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.75",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.75",
+    "@spooky-sync/query-builder": "0.0.1-canary.76",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.76",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/auth/index.ts

@@ -35,11 +35,41 @@ type ExtractAccessParams<
       }>
     : never;
 
+/**
+ * Read the `AC` (access-method name) claim from a SurrealDB record-access
+ * JWT without verifying it — we only need the claim, the server enforces the
+ * token. Returns null on any malformed input. The in-browser SSP needs this
+ * to resolve `$access` in table permission predicates (mirrors the session's
+ * `$access` that the server's `fn::query::register` reads).
+ */
+function decodeAccessFromToken(token: string): string | null {
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return null;
+    let b64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+    b64 += '='.repeat((4 - (b64.length % 4)) % 4);
+    const json =
+      typeof atob === 'function' ? atob(b64) : Buffer.from(b64, 'base64').toString('binary');
+    const claims = JSON.parse(json) as Record<string, unknown>;
+    const ac = claims.AC ?? claims.ac;
+    return typeof ac === 'string' ? ac : null;
+  } catch {
+    return null;
+  }
+}
+
 export class AuthService<S extends SchemaStructure> {
   // State
   public token: string | null = null;
   public currentUser: any | null = null;
   public isAuthenticated: boolean = false;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  public access: string | null = null;
   public isLoading: boolean = true;
 
   private events = createAuthEventSystem();
@@ -167,6 +197,7 @@ export class AuthService<S extends SchemaStructure> {
     this.token = null;
     this.currentUser = null;
     this.isAuthenticated = false;
+    this.access = null;
 
     await this.persistenceClient.remove('sp00ky_auth_token');
 
@@ -183,10 +214,21 @@ export class AuthService<S extends SchemaStructure> {
     this.token = token;
     this.currentUser = user;
     this.isAuthenticated = true;
+    // Resolve the access-method name (e.g. "account") for in-browser SSP
+    // permission injection. Prefer the token's `AC` claim; fall back to the
+    // schema's sole record-access method if the claim is absent.
+    this.access = decodeAccessFromToken(token) ?? this.defaultAccessName();
     await this.persistenceClient.set('sp00ky_auth_token', token);
     this.notifyListeners();
   }
 
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName(): string | null {
+    const names = Object.keys(this.schema.access ?? {});
+    return names.length === 1 ? names[0] : null;
+  }
+
   async signUp<Name extends keyof S['access'] & string>(
     accessName: Name,
     params: ExtractAccessParams<S, Name, 'signup'>

package/src/modules/data/index.ts

@@ -35,6 +35,7 @@ import {
   withRetry,
   surql,
   parseParams,
+  cleanRecord,
   extractTablePart,
   generateId,
 } from '../../utils/index';
@@ -606,6 +607,55 @@ export class DataModule<S extends SchemaStructure> {
     return !!qs && !qs.hydrated && (qs.config.remoteArray?.length ?? 0) === 0;
   }
 
+  /**
+   * Walk a hydrated record's fields and append any EMBEDDED child records to
+   * `batch` (recursing for nested related fields). An embedded child is a
+   * value that is itself a record — a non-null object whose `id` is a
+   * `RecordId` — or an array of such records (one-to-many vs one-to-one). A
+   * bare `RecordId` (a foreign-key reference) or any other value is skipped,
+   * so this never mistakes a FK column for an embedded body. Children are
+   * keyed by their own `record.id.table`, versioned by `_00_rv`, and cleaned
+   * to their table's real columns (which strips the alias/related fields).
+   * `seen` dedupes within the batch.
+   */
+  private collectEmbeddedChildren(
+    record: Record<string, any>,
+    batch: CacheRecord[],
+    seen: Set<string>
+  ): void {
+    const isEmbeddedRecord = (v: unknown): v is RecordWithId =>
+      !!v &&
+      typeof v === 'object' &&
+      !(v instanceof RecordId) &&
+      (v as { id?: unknown }).id instanceof RecordId;
+
+    for (const value of Object.values(record)) {
+      const children = Array.isArray(value)
+        ? value.filter(isEmbeddedRecord)
+        : isEmbeddedRecord(value)
+          ? [value]
+          : [];
+      for (const child of children) {
+        const key = encodeRecordId(child.id);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        // Recurse FIRST so nested grandchildren are captured before `cleanRecord`
+        // strips this child's alias fields.
+        this.collectEmbeddedChildren(child, batch, seen);
+        const table = child.id.table.toString();
+        const tableSchema = this.schema.tables.find((t) => t.name === table);
+        batch.push({
+          table,
+          op: 'CREATE',
+          record: (tableSchema
+            ? cleanRecord(tableSchema.columns, child)
+            : child) as RecordWithId,
+          version: (child._00_rv as number) || 1,
+        });
+      }
+    }
+  }
+
   /**
    * Instant-hydrate: ingest rows fetched one-shot from the remote (the query's own
    * surql run directly) so the query DISPLAYS immediately, while the full realtime
@@ -627,6 +677,20 @@ export class DataModule<S extends SchemaStructure> {
       record,
       version: (record._00_rv as number) || 1,
     }));
+
+    // Flicker-free related data on cold first paint: a `.related()` query's
+    // rows arrive with their child rows EMBEDDED (the correlated subquery,
+    // e.g. `(SELECT * FROM comment WHERE game=$parent.id) AS comments`). The
+    // primary batch above persists only the parent table, so the immediate
+    // `materializeRecords` below would re-run the correlated surql against a
+    // local DB with no child rows and overwrite the embedded result with
+    // empties. Extract those embedded children (any nesting depth) and
+    // persist them as their own records so the re-materialization finds them.
+    const seen = new Set<string>(rows.map((r) => encodeRecordId(r.id)));
+    for (const record of rows) {
+      this.collectEmbeddedChildren(record, batch, seen);
+    }
+
     await this.cache.saveBatch(batch);
 
     // Prime remoteArray from the hydrated id+version pairs: `materializeRecords`

package/src/modules/sync/sync.ts

@@ -8,7 +8,9 @@ import type { RecordId, Uuid } from 'surrealdb';
 import {
   ArraySyncer,
   buildListRefSelect,
+  buildSubqueryListRefSelect,
   createDiffFromDbOp,
+  diffRecordVersionArray,
   listRefPollDelayMs,
   recordVersionArraysEqual,
   resolveListRefPollInterval,
@@ -350,6 +352,15 @@ export class Sp00kySync<S extends SchemaStructure> {
         'syncQuery failed during poll'
       );
     }
+    // Cross-session fallback for `.related()` child rows: the LIVE-permission
+    // gap can drop child-edge notifications, so converge their bodies on the
+    // poll too (idempotent — no-op when nothing changed).
+    await this.syncSubqueryChildren(queryHash).catch((err) => {
+      this.logger.info(
+        { err: (err as Error)?.message ?? err, queryHash, Category: 'sp00ky-client::Sp00kySync::refetchListRefForQuery' },
+        'Subquery child sync failed during poll'
+      );
+    });
     // A REMOVAL needs no record fetch, so unlike the added-row path it doesn't
     // get a re-render from the SSP stream on this code path reliably (and the
     // non-windowed window-0 query re-queries the local DB rather than the id-set).
@@ -463,12 +474,26 @@ export class Sp00kySync<S extends SchemaStructure> {
         'Live update received'
       );
       if (message.action === 'KILLED') return;
-      // Skip subquery entries (rows with `parent` set) — they're synthetic
-      // CRDT/cursor metadata rows. The poll filters them with `parent IS NONE`
-      // (the client's RecordVersionArray only tracks primary rows); the LIVE
-      // feed delivers every row, so without this they'd surface as spurious
-      // "added" diffs.
-      if ((message.value as { parent?: unknown }).parent != null) return;
+      // Subquery child edges (rows with `parent` set) are NOT primary window
+      // rows — the client's `RecordVersionArray` only tracks primary rows, so
+      // routing them through `handleRemoteListRefChange` would surface them as
+      // spurious "added" diffs and pollute the window. Instead route them to
+      // the dedicated child-body sync so `.related()` data stays realtime
+      // cross-session (the LIVE-permission gap otherwise leaves it to the poll).
+      if ((message.value as { parent?: unknown }).parent != null) {
+        this.handleRemoteSubqueryChange(
+          message.action,
+          message.value.in as RecordId<string>,
+          message.value.out as RecordId<string>,
+          message.value.version as number
+        ).catch((err) => {
+          this.logger.error(
+            { err, Category: 'sp00ky-client::Sp00kySync::startRefLiveQueries' },
+            'Error handling remote subquery change'
+          );
+        });
+        return;
+      }
       this.handleRemoteListRefChange(
         message.action,
         message.value.in as RecordId<string>,
@@ -535,6 +560,46 @@ export class Sp00kySync<S extends SchemaStructure> {
     await this.runSyncForQuery(hash, diff);
   }
 
+  /**
+   * Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
+   * `parent` set) for a `.related()` query. Unlike primary rows, child rows
+   * must NOT touch the query's `localArray`/`remoteArray`/`rowCount`; we only
+   * keep the child BODY fresh in the local cache so the in-browser SSP's
+   * subquery-table dependency re-materializes the parent view.
+   *
+   * CREATE/UPDATE fetch+upsert the child body. DELETE is intentionally a
+   * no-op: a child leaving this query's set must not delete a body another
+   * query may still show (see `syncSubqueryChildren` deletion-safety note);
+   * a genuine record delete propagates via the normal delete path.
+   */
+  private async handleRemoteSubqueryChange(
+    action: 'CREATE' | 'UPDATE' | 'DELETE',
+    queryId: RecordId,
+    childId: RecordId,
+    version: number
+  ) {
+    this.lastLiveEventAt = Date.now();
+    this.listRefIdleStreak = 0;
+
+    if (action === 'DELETE') return;
+
+    const existing = this.dataModule.getQueryById(queryId);
+    if (!existing) return;
+
+    const item = { id: childId, version };
+    await this.syncEngine.syncRecords(
+      action === 'CREATE'
+        ? { added: [item], updated: [], removed: [] }
+        : { added: [], updated: [item], removed: [] }
+    );
+
+    // Keep the in-memory child array in step so the poll's idempotent diff
+    // doesn't re-fetch this body on the next tick.
+    const key = encodeRecordId(childId);
+    const prev = existing.config.subqueryRemoteArray ?? [];
+    existing.config.subqueryRemoteArray = [...prev.filter(([id]) => id !== key), [key, version]];
+  }
+
   /**
    * Enqueues a 'down' event (from remote to local) for processing.
    * @param event The DownEvent to enqueue.
@@ -860,6 +925,64 @@ export class Sp00kySync<S extends SchemaStructure> {
       /// Incantation existed already
       await this.dataModule.updateQueryRemoteArray(queryHash, array);
     }
+
+    // Pull the bodies of any `.related()` subquery children into the local
+    // cache. The primary fetch above (`parent IS NONE`) tracks only window
+    // rows, so without this a cold-reload re-materialization of the
+    // correlated surql finds no child rows and related fields come back
+    // empty. Best-effort: never fail registration over it.
+    await this.syncSubqueryChildren(queryHash).catch((err) => {
+      this.logger.info(
+        { err: (err as Error)?.message ?? err, queryHash, Category: 'sp00ky-client::Sp00kySync::createRemoteQuery' },
+        'Subquery child sync failed during registration; poll will retry'
+      );
+    });
+  }
+
+  /**
+   * Sync the BODIES of a `.related()` query's subquery child rows into the
+   * local cache, separately from the primary window array. The SSP writes
+   * each matched child as a `_00_list_ref` edge tagged `parent`/`parent_rel`;
+   * `buildSubqueryListRefSelect` pulls those `out`+`version` pairs (any
+   * nesting depth). We diff against the in-memory `subqueryRemoteArray` and
+   * fetch added/updated bodies through the SyncEngine — which `saveBatch`s
+   * them into the local DB AND the in-browser SSP, whose subquery-table
+   * dependency then re-materializes the parent view (no explicit notify).
+   *
+   * Deletion safety: we pass `removed: []` deliberately. A child body can be
+   * shared by other queries; letting `handleRemovedRecords` delete one that
+   * merely left THIS query's child set would clobber data another query still
+   * shows. Genuine record deletes flow through the normal delete path; a
+   * lingering orphan body is invisible (the correlated WHERE stops matching).
+   *
+   * Kept off `runSyncForQuery` on purpose so child fetches never flip the
+   * query to `fetching` or skew its DevTools timings.
+   */
+  private async syncSubqueryChildren(queryHash: string): Promise<void> {
+    const queryState = this.dataModule.getQueryByHash(queryHash);
+    if (!queryState) return;
+
+    const listRefTbl = this.listRefTable();
+    const [items] = await this.remote.query<[{ out: RecordId<string>; version: number }[]]>(
+      buildSubqueryListRefSelect(listRefTbl),
+      { in: queryState.config.id }
+    );
+    if (!Array.isArray(items)) return;
+
+    const fresh: RecordVersionArray = items.map((item) => [encodeRecordId(item.out), item.version]);
+    const prev = queryState.config.subqueryRemoteArray ?? [];
+    if (recordVersionArraysEqual(fresh, prev)) return; // idempotent: nothing new
+
+    const diff = diffRecordVersionArray(prev, fresh);
+    if (diff.added.length > 0 || diff.updated.length > 0) {
+      await this.syncEngine.syncRecords({
+        added: diff.added,
+        updated: diff.updated,
+        removed: [], // never delete child bodies here — see method doc
+      });
+    }
+    // In-memory only — child rows must never enter the persisted primary array.
+    queryState.config.subqueryRemoteArray = fresh;
   }
 
   public async heartbeatQuery(queryHash: string) {

package/src/modules/sync/utils.test.ts

@@ -8,6 +8,7 @@ import {
   resolveListRefPollInterval,
   DEFAULT_LIST_REF_POLL_INTERVAL_MS,
   buildListRefSelect,
+  buildSubqueryListRefSelect,
   nextPollDelayMs,
   listRefPollDelayMs,
   LIST_REF_POLL_MAX_INTERVAL_MS,
@@ -377,6 +378,35 @@ describe('buildListRefSelect', () => {
   });
 });
 
+describe('buildSubqueryListRefSelect', () => {
+  it('substitutes the table name', () => {
+    expect(buildSubqueryListRefSelect('_00_list_ref')).toContain('FROM _00_list_ref ');
+    expect(buildSubqueryListRefSelect('_00_list_ref_user_abc')).toContain(
+      'FROM _00_list_ref_user_abc '
+    );
+  });
+
+  it('filters by the bound query id', () => {
+    expect(buildSubqueryListRefSelect('_00_list_ref')).toContain('WHERE in = $in');
+  });
+
+  it('selects ONLY subquery child rows via parent IS NOT NONE', () => {
+    // The mirror of `buildListRefSelect`'s `parent IS NONE`: the SSP writes
+    // `.related()` child rows into list_ref tagged with `parent`/`parent_rel`;
+    // this select pulls exactly those so their bodies can be synced into the
+    // local cache (separately from the primary window) and the correlated
+    // surql re-materializes with related data on a cold reload.
+    const sql = buildSubqueryListRefSelect('_00_list_ref');
+    expect(sql).toContain('parent IS NOT NONE');
+    expect(sql).not.toContain('parent IS NONE ');
+  });
+
+  it('selects only `out` and `version`', () => {
+    const sql = buildSubqueryListRefSelect('_00_list_ref');
+    expect(sql.startsWith('SELECT out, version FROM ')).toBe(true);
+  });
+});
+
 describe('nextPollDelayMs', () => {
   it('returns the base interval when LIVE has never delivered', () => {
     expect(

package/src/modules/sync/utils.ts

@@ -188,6 +188,22 @@ export function buildListRefSelect(table: string): string {
   return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NONE`;
 }
 
+/**
+ * Build the SurrealQL select for a query's SUBQUERY child edges — the
+ * mirror of {@link buildListRefSelect}. `.related()` queries register a
+ * correlated subquery; the SSP materializes each matched child as a
+ * `_00_list_ref` edge tagged with `parent`/`parent_rel` (see
+ * `apps/ssp` edge writer). `parent IS NONE` (the primary select) drops
+ * these, so their bodies never reach the local cache and a cold-reload
+ * re-materialization of the correlated surql yields empty related
+ * fields. This `parent IS NOT NONE` variant pulls the child `out`+`version`
+ * pairs (any nesting depth) so we can sync their bodies into the local
+ * store SEPARATELY from the primary window array.
+ */
+export function buildSubqueryListRefSelect(table: string): string {
+  return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NOT NONE`;
+}
+
 /**
  * Resolve the effective list-ref poll interval. Negative or zero
  * values fall back to the default — accepting them would either

package/src/services/stream-processor/index.ts

@@ -68,6 +68,13 @@ export class StreamProcessorService {
   // query, so the UI updates once after the whole batch rather than row-by-row.
   private batching = false;
   private batchBuffer: Map<string, StreamUpdate> = new Map();
+  // Current session's auth identity, injected into every `register_view`'s
+  // params so the in-browser SSP can resolve `$auth`/`$access` in table
+  // permission predicates (mirrors the server's `fn::query::register`). Empty
+  // strings when logged out — a non-null `auth` keeps `permission_inject` from
+  // rejecting `$auth`-gated tables; the predicate just degrades to its public
+  // branch. Set via `setSessionAuth` on every auth state change.
+  private sessionAuth: { authId: string; access: string } = { authId: '', access: '' };
 
   constructor(
     public events: EventSystem<StreamProcessorEvents>,
@@ -288,6 +295,28 @@ export class StreamProcessorService {
     );
   }
 
+  /**
+   * Set the current session's auth identity for permission injection,
+   * mirroring the server's `fn::query::register`
+   * (`object::extend(params, { auth: { id: $auth.id }, access: $access })`).
+   * Stored as strings (empty when logged out) and applied to every
+   * `register_view` in {@link registerQueryPlan}. Must be set before a
+   * `$auth`-gated query registers (and re-set on auth state changes), or the
+   * in-browser SSP's `permission_inject` rejects it with
+   * "requires $auth but registration params lack it".
+   */
+  setSessionAuth(authId: string | null, access: string | null) {
+    this.sessionAuth = { authId: authId ?? '', access: access ?? '' };
+    this.logger.debug(
+      {
+        authId: this.sessionAuth.authId,
+        access: this.sessionAuth.access,
+        Category: 'sp00ky-client::StreamProcessorService::setSessionAuth',
+      },
+      'Session auth context updated'
+    );
+  }
+
   async saveState() {
     if (!this.processor) return;
     try {
@@ -411,10 +440,23 @@ export class StreamProcessorService {
     try {
       const normalizedParams = this.normalizeValue(queryPlan.params);
 
+      // Mirror the server's `fn::query::register` auth injection so the
+      // in-browser SSP can resolve `$auth`/`$access` in a table's permission
+      // predicate. Without this, any `$auth`-gated table (e.g. `thread`) is
+      // rejected by `permission_inject` and its local view never materializes.
+      // Injected only into the params handed to the in-browser SSP — never into
+      // the persisted `queryState.config.params` / query hash / server payload
+      // (the server does its own injection), so the view id stays shared.
+      const paramsWithAuth = {
+        ...(normalizedParams as Record<string, unknown>),
+        auth: { id: this.sessionAuth.authId },
+        access: this.sessionAuth.access,
+      };
+
       const initialUpdate = this.processor.register_view({
         id: queryPlan.queryHash,
         surql: queryPlan.surql,
-        params: normalizedParams,
+        params: paramsWithAuth,
         clientId: 'local',
         ttl: queryPlan.ttl.toString(),
         lastActiveAt: new Date().toISOString(),

package/src/sp00ky.ts

@@ -41,7 +41,7 @@ import { CrdtManager, CrdtField } from './modules/crdt/index';
 import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/index';
 import type { FeatureFlagOptions } from './modules/feature-flag/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
-import { parseParams } from './utils/index';
+import { parseParams, encodeRecordId } from './utils/index';
 import { SurrealDBPersistenceClient } from './services/persistence/surrealdb';
 import { ResilientPersistenceClient } from './services/persistence/resilient';
 
@@ -381,6 +381,16 @@ export class Sp00kyClient<S extends SchemaStructure> {
       // table.
       this.auth.subscribe(async (userId) => {
         this.dataModule.setCurrentUserId(userId);
+        // Mirror the server's `fn::query::register` auth injection for the
+        // in-browser SSP: feed the current user's full record id + access
+        // method so `$auth`-gated table permissions (e.g. `thread`) resolve
+        // locally instead of being rejected. Set synchronously BEFORE the
+        // first `await` (like `setCurrentUserId` above) so queries that
+        // re-register on this auth flip see the fresh context, not a stale one.
+        this.streamProcessor.setSessionAuth(
+          this.auth.currentUser?.id ? encodeRecordId(this.auth.currentUser.id) : null,
+          this.auth.access
+        );
         const next = await this.fetchSessionId();
         this.dataModule.setSessionId(next);
         this.crdtManager.setSessionId(next);

package/src/types.ts

@@ -178,6 +178,14 @@ export interface QueryConfig {
   localArray: RecordVersionArray;
   /** The version array representing the remote (server) state of results. */
   remoteArray: RecordVersionArray;
+  /**
+   * In-memory only (never persisted to `_00_query`): version array of the
+   * subquery CHILD rows pulled via `parent IS NOT NONE` edges, so the
+   * child-body sync is idempotent across polls. Kept separate from
+   * `remoteArray` so related child rows never enter the primary window /
+   * `rowCount` / `localArray`.
+   */
+  subqueryRemoteArray?: RecordVersionArray;
   /** Time-To-Live for this query. */
   ttl: QueryTimeToLive;
   /** Timestamp when the query was last accessed/active. */