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

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/feature-flag/index.ts

@@ -0,0 +1,166 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { DataModule } from '../data/index';
+import type { Sp00kySync } from '../sync/index';
+import type { AuthService } from '../auth/index';
+import type { Logger } from '../../services/logger/index';
+import type { QueryTimeToLive } from '../../types';
+
+const FEATURE_QUERY =
+  'SELECT key, variant, payload FROM _00_user_feature WHERE key = $key';
+
+export interface FeatureFlagSnapshot {
+  variant: string | undefined;
+  payload: unknown | undefined;
+}
+
+export interface FeatureFlagOptions {
+  fallback?: string;
+  ttl?: QueryTimeToLive;
+}
+
+export class FeatureFlagHandle {
+  private latest: FeatureFlagSnapshot = { variant: undefined, payload: undefined };
+  private listeners = new Set<(s: FeatureFlagSnapshot) => void>();
+  private unsubscribeFn: (() => void) | null = null;
+  private onCloseFn: (() => void) | null = null;
+  private closed = false;
+
+  constructor(
+    public readonly key: string,
+    public readonly fallback: string | undefined,
+  ) {}
+
+  attach(unsubscribe: () => void): void {
+    this.unsubscribeFn?.();
+    this.unsubscribeFn = unsubscribe;
+  }
+
+  detach(): void {
+    this.unsubscribeFn?.();
+    this.unsubscribeFn = null;
+  }
+
+  set(snapshot: FeatureFlagSnapshot): void {
+    if (this.closed) return;
+    this.latest = snapshot;
+    for (const cb of this.listeners) cb(snapshot);
+  }
+
+  variant(): string | undefined {
+    return this.latest.variant ?? this.fallback;
+  }
+
+  payload<T = unknown>(): T | undefined {
+    return this.latest.payload as T | undefined;
+  }
+
+  enabled(): boolean {
+    const v = this.variant();
+    return v !== undefined && v !== 'off';
+  }
+
+  subscribe(cb: (s: FeatureFlagSnapshot) => void): () => void {
+    this.listeners.add(cb);
+    cb({ variant: this.variant(), payload: this.latest.payload });
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  onClose(cb: () => void): void {
+    this.onCloseFn = cb;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.detach();
+    this.onCloseFn?.();
+  }
+}
+
+export interface FeatureFlagModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger;
+}
+
+interface ActiveHandle {
+  handle: FeatureFlagHandle;
+  ttl: QueryTimeToLive;
+}
+
+export class FeatureFlagModule<S extends SchemaStructure> {
+  private logger: Logger;
+  private active = new Set<ActiveHandle>();
+  private authUnsubscribe: (() => void) | null = null;
+  private lastUserId: string | null = null;
+
+  constructor(private deps: FeatureFlagModuleDeps<S>) {
+    this.logger = deps.logger.child({ service: 'FeatureFlagModule' });
+  }
+
+  init(): void {
+    if (this.authUnsubscribe) return;
+    this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+      if (userId === this.lastUserId) return;
+      this.lastUserId = userId;
+      void this.refreshAll();
+    });
+  }
+
+  feature(key: string, options: FeatureFlagOptions = {}): FeatureFlagHandle {
+    const handle = new FeatureFlagHandle(key, options.fallback);
+    const entry: ActiveHandle = { handle, ttl: options.ttl ?? '10m' };
+    this.active.add(entry);
+    handle.onClose(() => this.active.delete(entry));
+    void this.register(entry);
+    return handle;
+  }
+
+  async closeAll(): Promise<void> {
+    this.authUnsubscribe?.();
+    this.authUnsubscribe = null;
+    for (const entry of [...this.active]) entry.handle.close();
+  }
+
+  private async refreshAll(): Promise<void> {
+    for (const entry of this.active) {
+      entry.handle.detach();
+      entry.handle.set({ variant: undefined, payload: undefined });
+      await this.register(entry);
+    }
+  }
+
+  private async register(entry: ActiveHandle): Promise<void> {
+    const { handle, ttl } = entry;
+    try {
+      const hash = await this.deps.dataModule.query(
+        '_00_user_feature' as any,
+        FEATURE_QUERY,
+        { key: handle.key },
+        ttl,
+      );
+
+      this.deps.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
+
+      const unsub = this.deps.dataModule.subscribe(
+        hash,
+        (records) => {
+          const row = records[0] as { variant?: string; payload?: unknown } | undefined;
+          handle.set({ variant: row?.variant, payload: row?.payload });
+        },
+        { immediate: true },
+      );
+
+      handle.attach(unsub);
+    } catch (err) {
+      this.logger.warn(
+        { err, key: handle.key, Category: 'sp00ky-client::FeatureFlagModule::register' },
+        'Failed to register feature flag query',
+      );
+    }
+  }
+}

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

@@ -38,8 +38,10 @@ import { EventSystem } from './events/index';
 import { CacheModule } from './modules/cache/index';
 import type { RecordWithId } from './modules/cache/index';
 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';
 
@@ -95,6 +97,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private sync: Sp00kySync<S>;
   private devTools: DevToolsService;
   private crdtManager: CrdtManager;
+  private featureFlags!: FeatureFlagModule<S>;
 
   private logger: ReturnType<typeof createLogger>;
   public auth: AuthService<S>;
@@ -203,6 +206,16 @@ export class Sp00kyClient<S extends SchemaStructure> {
       { refSyncIntervalMs: this.config.refSyncIntervalMs }
     );
 
+    // Initialize feature flags. Reuses the down-queue to register SSP plans
+    // on `_00_user_feature` and the auth subscription to re-register handles
+    // when the signed-in user changes.
+    this.featureFlags = new FeatureFlagModule({
+      dataModule: this.dataModule,
+      sync: this.sync,
+      auth: this.auth,
+      logger,
+    });
+
     // Initialize DevTools
     this.devTools = new DevToolsService(
       this.local,
@@ -368,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);
@@ -384,6 +407,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
       await this.sync.init();
       this.logger.debug({ Category: 'sp00ky-client::Sp00kyClient::init' }, 'Sync initialized');
 
+      this.featureFlags.init();
+      this.logger.debug(
+        { Category: 'sp00ky-client::Sp00kyClient::init' },
+        'FeatureFlagModule initialized'
+      );
+
       this.logger.info(
         { Category: 'sp00ky-client::Sp00kyClient::init' },
         'Sp00kyClient initialization completed successfully'
@@ -398,11 +427,25 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   async close() {
+    await this.featureFlags.closeAll();
     this.crdtManager.closeAll();
     await this.local.close();
     await this.remote.close();
   }
 
+  /**
+   * Subscribe to a feature flag for the current user. Returns a
+   * `FeatureFlagHandle` whose `variant()`, `payload()` and `enabled()`
+   * accessors reflect the latest assignment from `_00_user_feature`,
+   * and whose `subscribe(cb)` fires whenever that assignment changes.
+   *
+   * Permissions are enforced by SurrealDB: a client can only ever see
+   * its own row, and cannot create or modify assignments.
+   */
+  feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle {
+    return this.featureFlags.feature(key, options);
+  }
+
   authenticate(token: string) {
     return this.remote.getClient().authenticate(token);
   }

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