@spooky-sync/core 0.0.1-canary.165 → 0.0.1-canary.168

package/dist/index.d.ts

@@ -1636,6 +1636,15 @@ interface FeatureFlagOptions {
   fallback?: string;
   ttl?: QueryTimeToLive;
 }
+/**
+ * A locally forced variant. Applies to THIS browser only and is never sent to
+ * the server — the assignment in `_00_user_feature` is untouched, so clearing
+ * the override restores whatever the server says.
+ */
+interface FeatureFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
 declare class FeatureFlagHandle {
   readonly key: string;
   readonly fallback: string | undefined;
@@ -1672,6 +1681,7 @@ declare class FeatureFlagModule<S extends SchemaStructure> {
   private ttl;
   private snapshots;
   private loaded;
+  private overrides;
   constructor(deps: FeatureFlagModuleDeps<S>);
   init(): void;
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
@@ -1683,6 +1693,21 @@ declare class FeatureFlagModule<S extends SchemaStructure> {
   private ensureStarted;
   /** Live query result → per-key snapshots → push to every active handle. */
   private applyRecords;
+  /**
+   * Force `key` to `variant` in THIS browser. Pass `null` to clear.
+   *
+   * Nothing is written to the server: the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage on the page origin, so it survives a reload.
+   */
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void;
+  clearLocalOverrides(): void;
+  getLocalOverrides(): Record<string, FeatureFlagOverride>;
+  /** The assignment for `key`, with any local override taking precedence. */
+  private resolve;
+  private pushAll;
+  private loadOverrides;
+  private persistOverrides;
 }
 //#endregion
 //#region src/modules/app-release/index.d.ts
@@ -2126,6 +2151,22 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    * its own row, and cannot create or modify assignments.
    */
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
+  /**
+   * Force a feature flag to `variant` in THIS browser only; `null` clears it.
+   *
+   * Nothing is sent to the server — the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage, survives reloads, and applies while signed out. Backs the
+   * DevTools Flags tab, and is a convenient hook for tests.
+   *
+   * To change a flag for OTHER users you need admin rights (`spky admin add`)
+   * and the DevTools Flags tab, or `spky flag`.
+   */
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void;
+  /** Drop every local feature flag override set via `setFeatureOverride`. */
+  clearFeatureOverrides(): void;
+  /** The local feature flag overrides currently in effect, keyed by flag. */
+  getFeatureOverrides(): Record<string, FeatureFlagOverride>;
   /**
    * Observe the announced release of an app (`_00_app_release:<app>`, written
    * by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
@@ -2248,4 +2289,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };

package/dist/index.js

@@ -6541,10 +6541,196 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 	}
 }
 
+//#endregion
+//#region src/modules/devtools/flags.ts
+/**
+* SurrealDB's SDK returns one entry per statement; each entry is the rows for
+* that statement, but older/local shapes wrap them as `{ status, result }`.
+* `getTableData` in `index.ts` unwraps the same three shapes inline — this is
+* that logic, reusable.
+*/
+function statementRows(result, index = 0) {
+	if (!Array.isArray(result)) return [];
+	const entry = result[index];
+	if (Array.isArray(entry)) return entry;
+	if (entry && typeof entry === "object" && "result" in entry) {
+		const inner = entry.result;
+		return Array.isArray(inner) ? inner : inner === void 0 || inner === null ? [] : [inner];
+	}
+	return entry === void 0 || entry === null ? [] : [entry];
+}
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** Row shape guards. `key` is the only field the panel truly can't do without. */
+function hasStringKey(row) {
+	return !!row && typeof row === "object" && typeof row.key === "string";
+}
+function isAssignment(row) {
+	return hasStringKey(row);
+}
+function isFlagRow(row) {
+	return hasStringKey(row);
+}
+var FlagsAdminService = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Everything the Flags tab renders, in one round trip per source.
+	*
+	* Each section fails independently: a remote read that throws downgrades to
+	* `isAdmin: false` plus an `error`, while local assignments and overrides
+	* still render. Signing out must not blank the whole tab.
+	*/
+	async getFlags() {
+		const userId = this.deps.currentUserId();
+		const snapshot = {
+			at: Date.now(),
+			userId,
+			isAdmin: false,
+			flags: [],
+			assignments: [],
+			overrides: this.deps.overrides()?.getLocalOverrides() ?? {}
+		};
+		try {
+			snapshot.assignments = statementRows(await this.deps.local.query("SELECT key, variant, payload FROM _00_user_feature")).filter(isAssignment).map((r) => ({
+				key: r.key,
+				variant: r.variant,
+				payload: r.payload
+			}));
+		} catch (err) {
+			this.deps.logger.debug({
+				err,
+				Category: "sp00ky-client::FlagsAdminService::getFlags"
+			}, "Local feature assignments unavailable");
+		}
+		if (!userId) return snapshot;
+		try {
+			snapshot.isAdmin = statementRows(await this.deps.remote.query("SELECT VALUE id FROM _00_admin WHERE user = $auth.id LIMIT 1")).length > 0;
+		} catch (err) {
+			snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Flags tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
+			return snapshot;
+		}
+		if (!snapshot.isAdmin) return snapshot;
+		try {
+			snapshot.flags = statementRows(await this.deps.remote.query("SELECT key, description, variants, default_variant, enabled, payloads, rules, updated_at FROM _00_feature_flag ORDER BY key ASC")).filter(isFlagRow).map((flag) => ({
+				...flag,
+				rules: Array.isArray(flag.rules) ? flag.rules : [],
+				variants: Array.isArray(flag.variants) ? flag.variants : [],
+				selfAllowlistedVariant: selfAllowlistedVariant(flag, userId)
+			}));
+		} catch (err) {
+			snapshot.error = `Could not read feature flags: ${message(err)}`;
+		}
+		return snapshot;
+	}
+	/**
+	* Flip a flag's global `enabled` bit for EVERY user, then re-materialize.
+	*
+	* Both statements are one request so they share a transaction: if the
+	* materialize fails, the `enabled` change rolls back rather than leaving the
+	* definition and the assignments disagreeing.
+	*/
+	async setFlagEnabled(key, enabled) {
+		return this.mutate("UPDATE _00_feature_flag SET enabled = $enabled WHERE key = $key; RETURN fn::feature::materialize($key);", {
+			key,
+			enabled
+		}, 1);
+	}
+	/**
+	* Add or remove a user from `$key`'s allowlist for `$variant`, then
+	* re-materialize. Defaults to the signed-in user, so the common case
+	* ("turn this on for me, for real") needs no user picker.
+	*/
+	async setFlagUserVariant(key, variant, remove, userId) {
+		const target = userId ?? this.deps.currentUserId();
+		if (!target) return {
+			success: false,
+			error: "Not signed in"
+		};
+		let user;
+		try {
+			user = parseRecordIdString(target);
+		} catch (err) {
+			return {
+				success: false,
+				error: `Invalid user id '${target}': ${message(err)}`
+			};
+		}
+		return remove ? this.mutate("RETURN fn::feature::disallow($key, $user);", {
+			key,
+			user
+		}, 0) : this.mutate("RETURN fn::feature::allow($key, $variant, $user);", {
+			key,
+			variant,
+			user
+		}, 0);
+	}
+	setLocalFlagOverride(key, variant, payload) {
+		const store = this.deps.overrides();
+		store?.setLocalOverride(key, variant, payload);
+		return { overrides: store?.getLocalOverrides() ?? {} };
+	}
+	clearLocalFlagOverrides() {
+		const store = this.deps.overrides();
+		store?.clearLocalOverrides();
+		return { overrides: store?.getLocalOverrides() ?? {} };
+	}
+	/**
+	* Run a remote mutation, reporting the materialize count from `$index`.
+	*
+	* Retries on a transaction conflict. `fn::feature::allow` / `disallow` are
+	* read-modify-write over `_00_feature_flag.rules`, so two admins acting on
+	* the same flag at once collide. SurrealDB detects this and fails the loser
+	* with "Transaction conflict ... can be retried" rather than losing the
+	* write — verified against 3.1 — so nothing is silently dropped. Retrying
+	* turns that into the outcome the user expected instead of a raw engine
+	* error they can do nothing with.
+	*/
+	async mutate(sql, vars, index) {
+		let lastError;
+		for (let attempt = 0; attempt < MUTATE_ATTEMPTS; attempt++) try {
+			return {
+				success: true,
+				users: statementRows(await this.deps.remote.query(sql, vars), index)[0]?.users
+			};
+		} catch (err) {
+			lastError = err;
+			if (!isRetryableConflict(err) || attempt === MUTATE_ATTEMPTS - 1) break;
+			await sleep(40 * (attempt + 1) + Math.random() * 40);
+		}
+		this.deps.logger.warn({
+			err: lastError,
+			sql,
+			Category: "sp00ky-client::FlagsAdminService::mutate"
+		}, "Feature flag mutation failed");
+		return {
+			success: false,
+			error: message(lastError)
+		};
+	}
+};
+const MUTATE_ATTEMPTS = 3;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isRetryableConflict(err) {
+	return /transaction (write )?conflict/i.test(message(err));
+}
+/**
+* Which variant, if any, this user is explicitly allowlisted into.
+*
+* `rules[].users` holds record-id strings (`flag.rs` serialises them as JSON),
+* so compare as strings. Lets the panel show "you're on the list" without
+* making the user reason about a raw rules blob.
+*/
+function selfAllowlistedVariant(flag, userId) {
+	return (Array.isArray(flag.rules) ? flag.rules : []).find((rule) => rule?.kind === "allowlist" && Array.isArray(rule.users) && rule.users.some((u) => String(u) === userId))?.variant;
+}
+
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.165";
-const WASM_VERSION = "0.0.1-canary.165";
+const CORE_VERSION = "0.0.1-canary.168";
+const WASM_VERSION = "0.0.1-canary.168";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -6569,6 +6755,8 @@ var DevToolsService = class DevToolsService {
 	localTables = [];
 	localTablesFetching = false;
 	localTablesAt = 0;
+	featureOverrides = null;
+	flagsAdmin;
 	constructor(databaseService, remoteDatabaseService, logger, schema, authService, dataManager) {
 		this.databaseService = databaseService;
 		this.remoteDatabaseService = remoteDatabaseService;
@@ -6576,6 +6764,17 @@ var DevToolsService = class DevToolsService {
 		this.schema = schema;
 		this.authService = authService;
 		this.dataManager = dataManager;
+		this.flagsAdmin = new FlagsAdminService({
+			remote: this.remoteDatabaseService,
+			local: this.databaseService,
+			logger: this.logger,
+			currentUserId: () => {
+				const id = this.authService.currentUser?.id;
+				if (!id) return null;
+				return id instanceof RecordId ? encodeRecordId(id) : String(id);
+			},
+			overrides: () => this.featureOverrides
+		});
 		this.exposeToWindow();
 		if (typeof window !== "undefined") window.addEventListener("message", (e) => {
 			if (e.source !== window) return;
@@ -6888,11 +7087,24 @@ var DevToolsService = class DevToolsService {
 		}
 		return data;
 	}
+	/**
+	* Hand the FeatureFlagModule to the Flags tab so it can read and write local
+	* overrides. Called from `Sp00kyClient` once both are constructed; until then
+	* the override methods are no-ops that report an empty map.
+	*/
+	setFeatureFlagOverrides(store) {
+		this.featureOverrides = store;
+	}
 	exposeToWindow() {
 		if (typeof window !== "undefined") {
 			window.__00__ = {
 				version: this.version,
 				getState: () => this.getState(),
+				getFlags: () => this.flagsAdmin.getFlags(),
+				setFlagEnabled: (key, enabled) => this.flagsAdmin.setFlagEnabled(key, enabled),
+				setFlagUserVariant: (key, variant, remove, userId) => this.flagsAdmin.setFlagUserVariant(key, variant, remove, userId),
+				setLocalFlagOverride: (key, variant, payload) => this.flagsAdmin.setLocalFlagOverride(key, variant, payload),
+				clearLocalFlagOverrides: () => this.flagsAdmin.clearLocalFlagOverrides(),
 				clearHistory: () => {
 					this.eventsHistory = [];
 					this.notifyDevTools();
@@ -8504,6 +8716,7 @@ var CrdtManager = class {
 //#endregion
 //#region src/modules/feature-flag/index.ts
 const FEATURE_QUERY = "SELECT key, variant, payload FROM _00_user_feature";
+const OVERRIDE_STORAGE_KEY = "sp00ky:feature-overrides";
 var FeatureFlagHandle = class {
 	latest = {
 		variant: void 0,
@@ -8571,9 +8784,11 @@ var FeatureFlagModule = class {
 	ttl = "10m";
 	snapshots = /* @__PURE__ */ new Map();
 	loaded = false;
+	overrides = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
 		this.logger = deps.logger.child({ service: "FeatureFlagModule" });
+		this.loadOverrides();
 	}
 	init() {
 		if (this.authUnsubscribe) return;
@@ -8588,10 +8803,7 @@ var FeatureFlagModule = class {
 		this.handles.add(handle);
 		handle.onClose(() => this.handles.delete(handle));
 		if (options.ttl) this.ttl = options.ttl;
-		if (this.loaded) handle.set(this.snapshots.get(key) ?? {
-			variant: void 0,
-			payload: void 0
-		});
+		if (this.loaded || this.overrides.has(key)) handle.set(this.resolve(key));
 		this.ensureStarted();
 		return handle;
 	}
@@ -8606,10 +8818,7 @@ var FeatureFlagModule = class {
 		this.teardownQuery();
 		this.loaded = false;
 		this.snapshots.clear();
-		for (const handle of this.handles) handle.set({
-			variant: void 0,
-			payload: void 0
-		});
+		for (const handle of this.handles) handle.set(this.resolve(handle.key));
 		await this.ensureStarted();
 	}
 	teardownQuery() {
@@ -8644,10 +8853,73 @@ var FeatureFlagModule = class {
 			payload: row.payload
 		});
 		this.loaded = true;
-		for (const handle of this.handles) handle.set(this.snapshots.get(handle.key) ?? {
+		this.pushAll();
+	}
+	/**
+	* Force `key` to `variant` in THIS browser. Pass `null` to clear.
+	*
+	* Nothing is written to the server: the `_00_user_feature` assignment is
+	* untouched, so clearing restores whatever the server says. Persisted to
+	* localStorage on the page origin, so it survives a reload.
+	*/
+	setLocalOverride(key, variant, payload) {
+		if (variant === null) this.overrides.delete(key);
+		else this.overrides.set(key, {
+			variant,
+			payload
+		});
+		this.persistOverrides();
+		this.pushAll();
+	}
+	clearLocalOverrides() {
+		this.overrides.clear();
+		this.persistOverrides();
+		this.pushAll();
+	}
+	getLocalOverrides() {
+		return Object.fromEntries(this.overrides);
+	}
+	/** The assignment for `key`, with any local override taking precedence. */
+	resolve(key) {
+		const override = this.overrides.get(key);
+		if (override) return {
+			variant: override.variant,
+			payload: override.payload
+		};
+		return this.snapshots.get(key) ?? {
 			variant: void 0,
 			payload: void 0
-		});
+		};
+	}
+	pushAll() {
+		for (const handle of this.handles) handle.set(this.resolve(handle.key));
+	}
+	loadOverrides() {
+		try {
+			const raw = globalThis.localStorage?.getItem(OVERRIDE_STORAGE_KEY);
+			if (!raw) return;
+			const parsed = JSON.parse(raw);
+			for (const [key, value] of Object.entries(parsed ?? {})) if (value && typeof value.variant === "string") this.overrides.set(key, value);
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::FeatureFlagModule::loadOverrides"
+			}, "Failed to read local feature flag overrides");
+		}
+	}
+	persistOverrides() {
+		try {
+			if (this.overrides.size === 0) {
+				globalThis.localStorage?.removeItem(OVERRIDE_STORAGE_KEY);
+				return;
+			}
+			globalThis.localStorage?.setItem(OVERRIDE_STORAGE_KEY, JSON.stringify(this.getLocalOverrides()));
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::FeatureFlagModule::persistOverrides"
+			}, "Failed to persist local feature flag overrides");
+		}
 	}
 };
 
@@ -9536,6 +9808,9 @@ var TabsCoordinator = class {
 			}, "Promotion failed");
 			this.hub?.detachAll();
 			this.hub = null;
+			if (previousRole === "leader") await this.deps.hooks.releaseOwnership();
+			this.tabLock?.release();
+			this.tabLock = null;
 			this.broker.send({
 				type: "leader-failed",
 				tabId: this.deps.tabId,
@@ -10846,6 +11121,7 @@ var Sp00kyClient = class {
 			logger
 		});
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
+		this.devTools.setFeatureFlagOverrides(this.featureFlags);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
 		if (tabsSupport.supported) this.tabsCoordinator = this.buildTabsCoordinator();
@@ -10884,7 +11160,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.165",
+				coreVersion: "0.0.1-canary.168",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -10998,23 +11274,27 @@ var Sp00kyClient = class {
 		this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization started");
 		try {
 			const bootBucket = readBootBucketHint() ?? ANON_USER_ID;
-			if (this.tabsCoordinator) try {
-				const role = await this.tabsCoordinator.start(bootBucket);
-				this.sharedActive = true;
-				this.logger.info({
-					role,
-					bootBucket,
-					Category: "sp00ky-client::Sp00kyClient::init"
-				}, "Shared-tabs role assigned");
-			} catch (e) {
-				this.logger.warn({
-					err: e,
-					Category: "sp00ky-client::Sp00kyClient::init"
-				}, "Shared-tabs unavailable; booting solo");
-				this.sharedActive = false;
-				await this.local.connect(bootBucket);
-			}
-			else await this.local.connect(bootBucket);
+			if (this.tabsCoordinator) {
+				this.tabsCoordinator.onRoleChange((role) => {
+					this.sharedActive = role !== "solo";
+				});
+				try {
+					const role = await this.tabsCoordinator.start(bootBucket);
+					this.sharedActive = true;
+					this.logger.info({
+						role,
+						bootBucket,
+						Category: "sp00ky-client::Sp00kyClient::init"
+					}, "Shared-tabs role assigned");
+				} catch (e) {
+					this.logger.warn({
+						err: e,
+						Category: "sp00ky-client::Sp00kyClient::init"
+					}, "Shared-tabs unavailable; booting solo");
+					this.sharedActive = false;
+					await this.local.connect(bootBucket);
+				}
+			} else await this.local.connect(bootBucket);
 			this.logger.debug({
 				bootBucket,
 				Category: "sp00ky-client::Sp00kyClient::init"
@@ -11221,6 +11501,28 @@ var Sp00kyClient = class {
 		return this.featureFlags.feature(key, options);
 	}
 	/**
+	* Force a feature flag to `variant` in THIS browser only; `null` clears it.
+	*
+	* Nothing is sent to the server — the `_00_user_feature` assignment is
+	* untouched, so clearing restores whatever the server says. Persisted to
+	* localStorage, survives reloads, and applies while signed out. Backs the
+	* DevTools Flags tab, and is a convenient hook for tests.
+	*
+	* To change a flag for OTHER users you need admin rights (`spky admin add`)
+	* and the DevTools Flags tab, or `spky flag`.
+	*/
+	setFeatureOverride(key, variant, payload) {
+		this.featureFlags.setLocalOverride(key, variant, payload);
+	}
+	/** Drop every local feature flag override set via `setFeatureOverride`. */
+	clearFeatureOverrides() {
+		this.featureFlags.clearLocalOverrides();
+	}
+	/** The local feature flag overrides currently in effect, keyed by flag. */
+	getFeatureOverrides() {
+		return this.featureFlags.getLocalOverrides();
+	}
+	/**
 	* Observe the announced release of an app (`_00_app_release:<app>`, written
 	* by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
 	* announced version plus the cache-bust/mandatory flags, and

package/dist/tabs-broker-worker.js

@@ -3,7 +3,7 @@ const PING_INTERVAL_MS = 5e3;
 const PONG_TIMEOUT_MS = 15e3;
 const FORCE_TAKEOVER_TIMEOUT_MS = 1e3;
 const LEADER_FAILURE_BACKOFF_MS = 1e3;
-const OPFS_FAILED_CYCLES_BEFORE_MEMORY = 3;
+const FAILED_CYCLES_BEFORE_MEMORY = 3;
 const brokerInstanceId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `bk_${Math.random().toString(36).slice(2)}`;
 const namespaces = /* @__PURE__ */ new Map();
 /** Reverse index: which namespace a port belongs to (for pong routing). */
@@ -32,7 +32,7 @@ function getNamespace(fingerprint, bucketId) {
 			tabs: /* @__PURE__ */ new Map(),
 			leader: null,
 			failedUntil: /* @__PURE__ */ new Map(),
-			opfsFailedCycles: 0,
+			failedCycles: 0,
 			electing: false,
 			attachRetry: /* @__PURE__ */ new Map(),
 			tabLockMonitor: null
@@ -171,7 +171,7 @@ function electIfNeeded(ns, previous = null) {
 				brokerInstanceId,
 				leadershipId,
 				forceTakeover,
-				allowMemoryFallback: ns.opfsFailedCycles >= OPFS_FAILED_CYCLES_BEFORE_MEMORY,
+				allowMemoryFallback: ns.failedCycles >= FAILED_CYCLES_BEFORE_MEMORY,
 				resumeHeld
 			});
 		} finally {
@@ -358,7 +358,7 @@ function handleTabMessage(port, msg, ports) {
 				break;
 			}
 			ns.leader.ready = true;
-			ns.opfsFailedCycles = 0;
+			ns.failedCycles = 0;
 			startTabLockMonitor(ns, msg.leadershipId);
 			const tab = ns.tabs.get(msg.tabId);
 			if (tab) tab.heldLeadership = {
@@ -376,7 +376,7 @@ function handleTabMessage(port, msg, ports) {
 		}
 		case "leader-failed": {
 			if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) break;
-			if (msg.reason.includes("opfs-unavailable")) ns.opfsFailedCycles += 1;
+			ns.failedCycles += 1;
 			ns.failedUntil.set(msg.tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
 			const previous = clearLeader(ns, {
 				demote: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.165",
+  "version": "0.0.1-canary.168",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.165",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.165",
+    "@spooky-sync/query-builder": "0.0.1-canary.168",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.168",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   FeatureFlagModule,
   FeatureFlagHandle,
   type FeatureFlagOptions,
+  type FeatureFlagOverride,
   type FeatureFlagSnapshot,
 } from './modules/feature-flag/index';
 export {