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

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.74";
-const WASM_VERSION = "0.0.1-canary.74";
+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()
@@ -4626,6 +4832,135 @@ var CrdtManager = class {
 	}
 };
 
+//#endregion
+//#region src/modules/feature-flag/index.ts
+const FEATURE_QUERY = "SELECT key, variant, payload FROM _00_user_feature WHERE key = $key";
+var FeatureFlagHandle = class {
+	latest = {
+		variant: void 0,
+		payload: void 0
+	};
+	listeners = /* @__PURE__ */ new Set();
+	unsubscribeFn = null;
+	onCloseFn = null;
+	closed = false;
+	constructor(key, fallback) {
+		this.key = key;
+		this.fallback = fallback;
+	}
+	attach(unsubscribe) {
+		this.unsubscribeFn?.();
+		this.unsubscribeFn = unsubscribe;
+	}
+	detach() {
+		this.unsubscribeFn?.();
+		this.unsubscribeFn = null;
+	}
+	set(snapshot) {
+		if (this.closed) return;
+		this.latest = snapshot;
+		for (const cb of this.listeners) cb(snapshot);
+	}
+	variant() {
+		return this.latest.variant ?? this.fallback;
+	}
+	payload() {
+		return this.latest.payload;
+	}
+	enabled() {
+		const v = this.variant();
+		return v !== void 0 && v !== "off";
+	}
+	subscribe(cb) {
+		this.listeners.add(cb);
+		cb({
+			variant: this.variant(),
+			payload: this.latest.payload
+		});
+		return () => {
+			this.listeners.delete(cb);
+		};
+	}
+	onClose(cb) {
+		this.onCloseFn = cb;
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.listeners.clear();
+		this.detach();
+		this.onCloseFn?.();
+	}
+};
+var FeatureFlagModule = class {
+	logger;
+	active = /* @__PURE__ */ new Set();
+	authUnsubscribe = null;
+	lastUserId = null;
+	constructor(deps) {
+		this.deps = deps;
+		this.logger = deps.logger.child({ service: "FeatureFlagModule" });
+	}
+	init() {
+		if (this.authUnsubscribe) return;
+		this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+			if (userId === this.lastUserId) return;
+			this.lastUserId = userId;
+			this.refreshAll();
+		});
+	}
+	feature(key, options = {}) {
+		const handle = new FeatureFlagHandle(key, options.fallback);
+		const entry = {
+			handle,
+			ttl: options.ttl ?? "10m"
+		};
+		this.active.add(entry);
+		handle.onClose(() => this.active.delete(entry));
+		this.register(entry);
+		return handle;
+	}
+	async closeAll() {
+		this.authUnsubscribe?.();
+		this.authUnsubscribe = null;
+		for (const entry of [...this.active]) entry.handle.close();
+	}
+	async refreshAll() {
+		for (const entry of this.active) {
+			entry.handle.detach();
+			entry.handle.set({
+				variant: void 0,
+				payload: void 0
+			});
+			await this.register(entry);
+		}
+	}
+	async register(entry) {
+		const { handle, ttl } = entry;
+		try {
+			const hash = await this.deps.dataModule.query("_00_user_feature", 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];
+				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");
+		}
+	}
+};
+
 //#endregion
 //#region src/services/persistence/localstorage.ts
 var LocalStoragePersistenceClient = class {
@@ -4780,6 +5115,7 @@ var Sp00kyClient = class {
 	sync;
 	devTools;
 	crdtManager;
+	featureFlags;
 	logger;
 	auth;
 	streamProcessor;
@@ -4829,6 +5165,12 @@ var Sp00kyClient = class {
 		this.dataModule = new DataModule(this.cache, this.local, this.config.schema, logger, this.config.streamDebounceTime);
 		this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
 		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, { refSyncIntervalMs: this.config.refSyncIntervalMs });
+		this.featureFlags = new FeatureFlagModule({
+			dataModule: this.dataModule,
+			sync: this.sync,
+			auth: this.auth,
+			logger
+		});
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
@@ -4911,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);
@@ -4925,6 +5268,8 @@ var Sp00kyClient = class {
 			});
 			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");
 		} catch (e) {
 			this.logger.error({
@@ -4935,10 +5280,23 @@ var Sp00kyClient = class {
 		}
 	}
 	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, options) {
+		return this.featureFlags.feature(key, options);
+	}
 	authenticate(token) {
 		return this.remote.getClient().authenticate(token);
 	}
@@ -5056,4 +5414,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };
+export { AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, createAuthEventSystem, cursorColorFromName, fileToUint8Array, textToHtml };

package/dist/types.d.ts

@@ -123,6 +123,32 @@ declare class EventSystem<E extends EventTypeMap> {
   private broadcastEvent;
 }
 //#endregion
+//#region src/modules/sync/events/index.d.ts
+declare const SyncEventTypes: {
+  readonly QueryUpdated: "SYNC_QUERY_UPDATED";
+  readonly RemoteDataIngested: "SYNC_REMOTE_DATA_INGESTED";
+  readonly MutationRolledBack: "SYNC_MUTATION_ROLLED_BACK";
+};
+type SyncEventTypeMap = {
+  [SyncEventTypes.QueryUpdated]: EventDefinition<typeof SyncEventTypes.QueryUpdated, {
+    queryId: any;
+    localHash?: string;
+    localArray?: RecordVersionArray;
+    remoteHash?: string;
+    remoteArray?: RecordVersionArray;
+    records: Record<string, any>[];
+  }>;
+  [SyncEventTypes.RemoteDataIngested]: EventDefinition<typeof SyncEventTypes.RemoteDataIngested, {
+    records: Record<string, any>[];
+  }>;
+  [SyncEventTypes.MutationRolledBack]: EventDefinition<typeof SyncEventTypes.MutationRolledBack, {
+    eventType: string;
+    recordId: string;
+    error: string;
+  }>;
+};
+type SyncEventSystem = EventSystem<SyncEventTypeMap>;
+//#endregion
 //#region src/services/logger/index.d.ts
 type Logger$1 = Logger;
 //#endregion
@@ -301,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. */
@@ -457,4 +491,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { Logger$1 as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, EventSystem as M, TimingPhase as O, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, EventDefinition as j, UpdateOptions as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };
+export { UpEvent as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SyncEventSystem as M, EventDefinition as N, TimingPhase as O, EventSystem as P, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, Logger$1 as j, UpdateOptions as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.74",
+  "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.74",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.74",
+    "@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/index.ts

@@ -2,4 +2,10 @@ export * from './types';
 export * from './sp00ky';
 export * from './modules/auth/index';
 export { CrdtField, CrdtManager, cursorColorFromName, CURSOR_COLORS } from './modules/crdt/index';
+export {
+  FeatureFlagModule,
+  FeatureFlagHandle,
+  type FeatureFlagOptions,
+  type FeatureFlagSnapshot,
+} from './modules/feature-flag/index';
 export { fileToUint8Array, textToHtml } from './utils/index';

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'>