@spooky-sync/core 0.0.1-canary.31 → 0.0.1-canary.310

package/src/modules/devtools/storage-info.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { walkOpfs } from './storage-info';
+
+/** Minimal in-memory OPFS: directories are nested objects, files are numbers
+ *  (their size) or 'locked' (getFile() throws, like a live SAHPool handle). */
+type FakeTree = { [name: string]: FakeTree | number | 'locked' };
+
+function makeDirHandle(tree: FakeTree): any {
+  return {
+    kind: 'directory',
+    entries: async function* () {
+      for (const [name, node] of Object.entries(tree)) {
+        if (typeof node === 'object') {
+          yield [name, makeDirHandle(node)];
+        } else {
+          yield [
+            name,
+            {
+              kind: 'file',
+              getFile: async () => {
+                if (node === 'locked') throw new DOMException('locked', 'NoModificationAllowedError');
+                return { size: node };
+              },
+            },
+          ];
+        }
+      }
+    },
+  };
+}
+
+function stubOpfs(tree: FakeTree | null) {
+  vi.stubGlobal('navigator', tree === null ? {} : {
+    storage: { getDirectory: async () => makeDirHandle(tree) },
+  });
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('walkOpfs', () => {
+  it('reports unsupported without OPFS APIs', async () => {
+    stubOpfs(null);
+    expect(await walkOpfs()).toEqual({
+      supported: false,
+      entries: [],
+      totalBytes: 0,
+      truncated: false,
+    });
+  });
+
+  it('walks recursively, sums readable sizes, and omits size for locked files', async () => {
+    stubOpfs({
+      '.sp00ky-anon': { '0000000001': 4096, '0000000002': 'locked' },
+      'other.txt': 10,
+    });
+    const res = await walkOpfs();
+    expect(res.supported).toBe(true);
+    expect(res.truncated).toBe(false);
+    // Locked file present but without a size; total counts only readable bytes.
+    expect(res.totalBytes).toBe(4106);
+    expect(res.entries).toEqual([
+      { path: '.sp00ky-anon', kind: 'directory' },
+      { path: '.sp00ky-anon/0000000001', kind: 'file', size: 4096 },
+      { path: '.sp00ky-anon/0000000002', kind: 'file' },
+      { path: 'other.txt', kind: 'file', size: 10 },
+    ]);
+  });
+
+  it('caps the listing and flags truncation', async () => {
+    const big: FakeTree = {};
+    for (let i = 0; i < 10; i++) big[`f${i}`] = 1;
+    stubOpfs(big);
+    const res = await walkOpfs(5);
+    expect(res.truncated).toBe(true);
+    expect(res.entries.length).toBe(5);
+  });
+});

package/src/modules/devtools/storage-info.ts

@@ -0,0 +1,168 @@
+/**
+ * Storage diagnostics for the DevTools Storage tab: what engine backs the
+ * local cache, whether it actually persists, how much of the device's quota
+ * the origin uses, and what is physically sitting in OPFS. Assembled by
+ * `DevToolsService.getStorageInfo()`; everything here is JSON-safe.
+ */
+
+export interface OpfsEntry {
+  /** Path relative to the OPFS root, e.g. `.sp00ky-anon/0000000000000001`. */
+  path: string;
+  kind: 'file' | 'directory';
+  /** Absent when the file's size can't be read (e.g. an exclusive sync access
+   *  handle is held on it — exactly the case during SAHPool contention). */
+  size?: number;
+}
+
+/** Engine-side numbers only the engine can produce (worker round-trips). */
+export interface EngineStorageDiagnostics {
+  engine: 'sqlite';
+  bucketId: string;
+  useOpfs: boolean;
+  workerSelectConfigured: boolean;
+  /** `false` while configured `true` means the runtime downgraded to the
+   *  legacy multi-hop select (stale cached worker bundle). */
+  workerSelectEffective: boolean;
+  /** page_count * page_size. */
+  dbSizeBytes?: number;
+  /** freelist_count * page_size — reclaimable via VACUUM. */
+  freelistBytes?: number;
+  tableCounts?: { table: string; rows: number }[];
+  error?: string;
+}
+
+/**
+ * Shared-tabs coordination state. Reported ONLY when `sharedTabs: true` was
+ * configured (apps that never asked for it get `null`, so the panel shows
+ * nothing). `active: false` with a `reason` is itself the useful signal: the
+ * app asked to share one store and this tab is not, so it owns or contends for
+ * the OPFS pool alone.
+ */
+export interface SharedTabsInfo {
+  active: boolean;
+  /** Why inactive: a capability gate reason, or 'fell-back' when the broker
+   *  was reachable but no role landed (election timeout, rejected tab). */
+  reason?: string;
+  role?: 'solo' | 'leader' | 'follower';
+  /** This tab's id (also the suffix of every mutation id it mints). */
+  tabId?: string;
+  /** Monotonic id of the current leadership term; embedded in the worker lock. */
+  leadershipId?: number;
+  /** Who owns the store: this tab when leader, else the leader's tab id. */
+  leaderTabId?: string | null;
+  /** Leader only: attached follower tabs. */
+  followers?: number;
+  /** Leader only: ingest batches relayed to followers so far. */
+  relayedBatches?: number;
+}
+
+export interface StorageInfo {
+  at: number;
+  engine: { kind: 'surrealdb' | 'sqlite' | 'custom'; store: string; bucketId: string };
+  health: { status: 'unknown' | 'persistent' | 'memory'; fallback: boolean; error?: string };
+  /** Shared-tabs state, or null when the feature was never requested. */
+  tabs?: SharedTabsInfo | null;
+  browser: {
+    /** `navigator.storage.persisted()` — whether the origin's storage is
+     *  exempt from eviction (unrelated to the OPFS pool lock). */
+    persisted?: boolean;
+    usage?: number;
+    quota?: number;
+    /** Chrome-only per-system breakdown from `estimate()`. */
+    usageDetails?: Record<string, number>;
+    error?: string;
+  };
+  opfs: {
+    supported: boolean;
+    entries: OpfsEntry[];
+    totalBytes: number;
+    truncated: boolean;
+    error?: string;
+  };
+  /**
+   * Bucket-file cache counters. `evicted*` is cumulative for this tab's
+   * session, so a number that climbs while `totalBytes` sits at the budget is
+   * the signal that `blobCache.maxBytes` is too small for the working set.
+   */
+  blobs?: BlobCacheInfo;
+  /** Snapshot of `globalThis.__sqliteStats` (SQLite engine only). */
+  sqliteStats?: Record<string, unknown>;
+  engineDiagnostics?: EngineStorageDiagnostics;
+}
+
+export interface BlobCacheInfo {
+  entries: number;
+  totalBytes: number;
+  budgetBytes: number;
+  pinnedBytes: number;
+  evictedEntries: number;
+  evictedBytes: number;
+  /** Manifest rows rebuilt from disk at the last reconcile. */
+  reconciledEntries: number;
+  hits: number;
+  misses: number;
+  /** False when OPFS is unwritable or the quota was exhausted — the cache is
+   *  running in per-tab memory and nothing survives a reload. */
+  persistent: boolean;
+  /** Over budget with only pinned or on-screen entries left: new files are no
+   *  longer written rather than pinned ones being discarded. */
+  persistPaused: boolean;
+}
+
+/**
+ * Recursively list the origin's OPFS. Sizes come from `handle.getFile()`,
+ * which throws for a file another context holds an exclusive sync access
+ * handle on — SAHPool does exactly that for its whole pool, so a locked file
+ * (size omitted) is a live "who has the pool" signal, not a failure.
+ */
+export async function walkOpfs(maxEntries = 2000, maxDepth = 8): Promise<StorageInfo['opfs']> {
+  const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+  if (!nav?.storage?.getDirectory) {
+    return { supported: false, entries: [], totalBytes: 0, truncated: false };
+  }
+  const entries: OpfsEntry[] = [];
+  let totalBytes = 0;
+  let truncated = false;
+  try {
+    const root = await nav.storage.getDirectory();
+    const walk = async (dir: FileSystemDirectoryHandle, prefix: string, depth: number) => {
+      if (depth > maxDepth) return;
+      // entries() is standard; older lib.dom typings may lack it.
+      for await (const [name, handle] of (dir as any).entries() as AsyncIterable<
+        [string, FileSystemHandle]
+      >) {
+        if (entries.length >= maxEntries) {
+          truncated = true;
+          return;
+        }
+        const path = prefix ? `${prefix}/${name}` : name;
+        if (handle.kind === 'directory') {
+          entries.push({ path, kind: 'directory' });
+          await walk(handle as FileSystemDirectoryHandle, path, depth + 1);
+        } else {
+          let size: number | undefined;
+          try {
+            size = (await (handle as FileSystemFileHandle).getFile()).size;
+            totalBytes += size;
+          } catch {
+            // Locked by an exclusive access handle (e.g. a live SAHPool).
+          }
+          const entry: OpfsEntry = { path, kind: 'file' };
+          if (size !== undefined) entry.size = size;
+          entries.push(entry);
+        }
+      }
+    };
+    await walk(root, '', 0);
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { supported: true, entries, totalBytes, truncated };
+  } catch (e) {
+    return {
+      supported: true,
+      entries,
+      totalBytes,
+      truncated,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}

package/src/modules/devtools/versions.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import {
+  emptyBackendInfo,
+  emptyBackendVersions,
+  parseBackendInfo,
+  toEntityArray,
+  UNAVAILABLE,
+} from './versions';
+
+describe('toEntityArray', () => {
+  it('passes through an array, dropping non-objects', () => {
+    expect(toEntityArray([{ entity: 'ssp' }, null, 'x'])).toEqual([{ entity: 'ssp' }]);
+  });
+
+  it('wraps a single object', () => {
+    expect(toEntityArray({ entity: 'ssp' })).toEqual([{ entity: 'ssp' }]);
+  });
+
+  it('returns [] for null/undefined/primitives', () => {
+    expect(toEntityArray(null)).toEqual([]);
+    expect(toEntityArray(undefined)).toEqual([]);
+    expect(toEntityArray(42)).toEqual([]);
+  });
+});
+
+describe('parseBackendInfo', () => {
+  it('parses the singlenode shape (ssp only) incl. surrealdb_version', () => {
+    const { versions, entities } = parseBackendInfo([
+      { entity: 'ssp', version: '0.0.1-canary.69', surrealdb_version: '2.0.3', status: 'ready' },
+    ]);
+    expect(versions.ssp).toBe('0.0.1-canary.69');
+    expect(versions.surrealdb).toBe('2.0.3');
+    expect(versions.scheduler).toBe(UNAVAILABLE);
+    expect(entities).toHaveLength(1);
+  });
+
+  it('parses the cluster shape (scheduler + ssp + backend)', () => {
+    const { versions, entities } = parseBackendInfo([
+      { entity: 'scheduler', version: '0.9.0', surrealdb_version: '2.0.3', status: 'ready' },
+      { entity: 'ssp', version: '0.9.0', status: 'ready' },
+      { entity: 'backend', id: 'surrealdb', status: 'healthy' },
+    ]);
+    expect(versions.scheduler).toBe('0.9.0');
+    expect(versions.ssp).toBe('0.9.0');
+    expect(versions.surrealdb).toBe('2.0.3');
+    expect(entities).toHaveLength(3);
+  });
+
+  it('strips a leading surrealdb- prefix', () => {
+    const { versions } = parseBackendInfo([
+      { entity: 'ssp', version: '1.0.0', surrealdb_version: 'surrealdb-2.1.0' },
+    ]);
+    expect(versions.surrealdb).toBe('2.1.0');
+  });
+
+  it('takes surrealdb_version from whichever entity reports it', () => {
+    const { versions } = parseBackendInfo([
+      { entity: 'scheduler', version: '0.9.0' },
+      { entity: 'ssp', version: '0.9.0', surrealdb_version: '3.1.0' },
+    ]);
+    expect(versions.surrealdb).toBe('3.1.0');
+  });
+
+  it('tolerates a single object instead of an array', () => {
+    const { versions } = parseBackendInfo({ entity: 'ssp', version: '1.2.3' });
+    expect(versions.ssp).toBe('1.2.3');
+  });
+
+  it('returns all-unavailable / empty for null or garbage', () => {
+    expect(parseBackendInfo(null)).toEqual(emptyBackendInfo());
+    expect(parseBackendInfo('nope').versions).toEqual(emptyBackendVersions());
+    expect(parseBackendInfo([{ foo: 'bar' }]).versions).toEqual(emptyBackendVersions());
+  });
+});

package/src/modules/devtools/versions.ts

@@ -0,0 +1,110 @@
+/**
+ * Backend versions of the stack components, derived from the entity list the
+ * backend `/info` endpoint exposes (read via the `fn::spooky::info()` SurrealQL
+ * function). Any component that isn't reported degrades to `'unavailable'`.
+ */
+export interface BackendVersions {
+  ssp: string;
+  scheduler: string;
+  surrealdb: string;
+}
+
+export const UNAVAILABLE = 'unavailable';
+
+/**
+ * A single stack entity as reported by `/info` (one per ssp / scheduler /
+ * backend). Carries far more than versions — status, uptime, ip, views — so the
+ * DevTools can render the whole stack. Extra fields are preserved verbatim.
+ */
+/** One end-to-end sync-pipeline probe cycle recorded by the scheduler. */
+export interface HeartbeatSample {
+  ts: number;
+  /** `null` for a failed cycle. */
+  ms: number | null;
+  ok: boolean;
+}
+
+/**
+ * E2E heartbeat state, reported on the scheduler entity only. The scheduler
+ * times a probe row's full round trip (DB event → ingest → broadcast → SSP
+ * circuit step); `samples` is its rolling window of recent cycles, which the
+ * DevTools sparkline renders.
+ */
+export interface HeartbeatInfo {
+  enabled: boolean;
+  stale: boolean;
+  /** Nothing to measure right now (e.g. no ready SSPs mid-bootstrap). */
+  blocked?: boolean;
+  blocked_reason?: string | null;
+  last_e2e_ms: number | null;
+  last_ok_epoch_ms: number | null;
+  consecutive_failures: number;
+  interval_secs: number;
+  samples?: HeartbeatSample[];
+}
+
+export interface BackendEntity {
+  entity: string;
+  id?: string;
+  ip?: string | null;
+  status?: string;
+  version?: string;
+  surrealdb_version?: string;
+  uptime_seconds?: number;
+  views?: number;
+  /** Scheduler entity only. */
+  heartbeat?: HeartbeatInfo;
+  [key: string]: unknown;
+}
+
+export interface BackendInfo {
+  versions: BackendVersions;
+  entities: BackendEntity[];
+}
+
+export function emptyBackendVersions(): BackendVersions {
+  return { ssp: UNAVAILABLE, scheduler: UNAVAILABLE, surrealdb: UNAVAILABLE };
+}
+
+export function emptyBackendInfo(): BackendInfo {
+  return { versions: emptyBackendVersions(), entities: [] };
+}
+
+/** Strip a leading `surrealdb-` so versions read as bare semver (e.g. `2.0.3`). */
+function normalizeServerVersion(v: string): string {
+  return String(v).replace(/^surrealdb-/i, '').trim();
+}
+
+/**
+ * Normalize whatever `RETURN fn::spooky::info()` resolves to into the entity
+ * array. The SurrealQL function returns the parsed `/info` array; depending on
+ * how the result is unwrapped it may arrive as the array itself, a single
+ * object, or `null`. Tolerant of all three.
+ */
+export function toEntityArray(raw: unknown): BackendEntity[] {
+  if (Array.isArray(raw)) return raw.filter((e): e is BackendEntity => !!e && typeof e === 'object');
+  if (raw && typeof raw === 'object') return [raw as BackendEntity];
+  return [];
+}
+
+/**
+ * Derive component versions + the full entity list from a `/info` entity array.
+ * `surrealdb` is taken from whichever entity reports `surrealdb_version` (ssp or
+ * scheduler). Never throws; missing pieces stay `'unavailable'`.
+ */
+export function parseBackendInfo(raw: unknown): BackendInfo {
+  const entities = toEntityArray(raw);
+  const versions = emptyBackendVersions();
+
+  for (const entity of entities) {
+    const version = entity.version ? String(entity.version) : undefined;
+    if (entity.entity === 'ssp' && version) versions.ssp = version;
+    else if (entity.entity === 'scheduler' && version) versions.scheduler = version;
+
+    if (versions.surrealdb === UNAVAILABLE && entity.surrealdb_version) {
+      versions.surrealdb = normalizeServerVersion(String(entity.surrealdb_version));
+    }
+  }
+
+  return { versions, entities };
+}

package/src/modules/feature-flag/index.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FeatureFlagModule } from './index';
+
+// vitest runs in the `node` environment here, so there is no localStorage.
+// The module guards every access with `globalThis.localStorage?.`, which keeps
+// overrides in-memory-only — this shim lets the persistence path be tested.
+function installLocalStorage() {
+  const store = new Map<string, string>();
+  const shim = {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => void store.set(k, v),
+    removeItem: (k: string) => void store.delete(k),
+  };
+  (globalThis as any).localStorage = shim;
+  return { store, uninstall: () => delete (globalThis as any).localStorage };
+}
+
+// Minimal mocks for the three deps the module touches. The DataModule mock
+// captures the single subscribe callback so a test can push live results, and
+// counts query() calls to assert the query is SHARED (one registration for all
+// flags), not per-key.
+function makeDeps() {
+  let subCb: ((records: unknown[]) => void) | null = null;
+  const calls: Array<{ sql: string; params: unknown }> = [];
+  let authCb: ((userId: string | null) => void) | null = null;
+
+  const dataModule = {
+    query: async (_table: string, sql: string, params: unknown) => {
+      calls.push({ sql, params });
+      return `hash:${calls.length}`;
+    },
+    subscribe: (_hash: string, cb: (records: unknown[]) => void) => {
+      subCb = cb;
+      return () => {
+        subCb = null;
+      };
+    },
+  };
+  const sync = { enqueueDownEvent: () => {} };
+  const auth = {
+    subscribe: (cb: (userId: string | null) => void) => {
+      authCb = cb;
+      return () => {
+        authCb = null;
+      };
+    },
+  };
+  const logger = { child: () => ({ warn: () => {} }) };
+
+  const deps = { dataModule, sync, auth, logger } as any;
+  return {
+    deps,
+    calls,
+    push: (records: unknown[]) => subCb?.(records),
+    setUser: (id: string | null) => authCb?.(id),
+    hasSub: () => subCb !== null,
+  };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('FeatureFlagModule', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: FeatureFlagModule<any>;
+
+  beforeEach(() => {
+    env = makeDeps();
+    mod = new FeatureFlagModule(env.deps);
+  });
+
+  it('registers ONE shared, unfiltered query for many flags', async () => {
+    mod.feature('alpha');
+    mod.feature('beta');
+    mod.feature('gamma');
+    await tick();
+
+    expect(env.calls.length).toBe(1);
+    expect(env.calls[0].sql).not.toContain('WHERE');
+    expect(env.calls[0].sql).toContain('FROM _00_user_feature');
+    expect(env.calls[0].params).toEqual({});
+  });
+
+  it('fans the shared result out to each handle by key', async () => {
+    const alpha = mod.feature('alpha', { fallback: 'off' });
+    const beta = mod.feature('beta', { fallback: 'off' });
+    const missing = mod.feature('missing', { fallback: 'off' });
+    await tick();
+
+    env.push([
+      { key: 'alpha', variant: 'on' },
+      { key: 'beta', variant: 'off' },
+    ]);
+
+    expect(alpha.enabled()).toBe(true);
+    expect(alpha.variant()).toBe('on');
+    expect(beta.enabled()).toBe(false); // assigned 'off'
+    expect(missing.enabled()).toBe(false); // no row → fallback 'off'
+  });
+
+  it('observes NEW assignments live without re-registering', async () => {
+    const flag = mod.feature('live', { fallback: 'off' });
+    await tick();
+
+    env.push([]); // user starts with no assignment
+    expect(flag.enabled()).toBe(false);
+
+    env.push([{ key: 'live', variant: 'on' }]); // assigned while observing
+    expect(flag.enabled()).toBe(true);
+
+    expect(env.calls.length).toBe(1); // still the same single query
+  });
+
+  it('seeds a late-created handle from the already-loaded snapshot', async () => {
+    mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'on' }]);
+
+    const late = mod.feature('alpha', { fallback: 'off' });
+    expect(late.enabled()).toBe(true); // no fallback flash
+  });
+
+  it('clears flags and re-observes on user change', async () => {
+    mod.init();
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'on' }]);
+    expect(flag.enabled()).toBe(true);
+
+    env.setUser('user:other'); // sign-in as a different user
+    await tick();
+    expect(flag.enabled()).toBe(false); // cleared until the new query resolves
+    expect(env.hasSub()).toBe(true); // re-registered for the new user
+  });
+});
+
+// Local overrides force a variant in THIS browser only. They must win over the
+// server assignment on every read path — `variant()`, `payload()`, `enabled()`
+// and `subscribe()` all funnel through the same resolver, so a gap in any one
+// of them is a gap in all of them.
+describe('FeatureFlagModule local overrides', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: FeatureFlagModule<any>;
+  let ls: ReturnType<typeof installLocalStorage>;
+
+  beforeEach(() => {
+    ls = installLocalStorage();
+    env = makeDeps();
+    mod = new FeatureFlagModule(env.deps);
+  });
+
+  afterEach(() => ls.uninstall());
+
+  it('wins over the server assignment', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off' }]);
+    expect(flag.enabled()).toBe(false);
+
+    mod.setLocalOverride('alpha', 'on');
+    expect(flag.variant()).toBe('on');
+    expect(flag.enabled()).toBe(true);
+  });
+
+  it('survives a later live result for the same key', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    mod.setLocalOverride('alpha', 'on');
+
+    env.push([{ key: 'alpha', variant: 'off' }]); // server disagrees
+    expect(flag.variant()).toBe('on');
+  });
+
+  it('applies before the first result, without a fallback flash', () => {
+    mod.setLocalOverride('alpha', 'on');
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    expect(flag.variant()).toBe('on'); // seeded even though nothing loaded yet
+  });
+
+  it('carries its own payload', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off', payload: { copy: 'server' } }]);
+
+    mod.setLocalOverride('alpha', 'on', { copy: 'local' });
+    expect(flag.payload()).toEqual({ copy: 'local' });
+  });
+
+  it('notifies subscribers when set and cleared', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off' }]);
+
+    const seen: (string | undefined)[] = [];
+    flag.subscribe((s) => seen.push(s.variant));
+    expect(seen).toEqual(['off']); // immediate call
+
+    mod.setLocalOverride('alpha', 'on');
+    mod.setLocalOverride('alpha', null);
+    expect(seen).toEqual(['off', 'on', 'off']);
+  });
+
+  it('restores the server assignment when cleared', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'treatment', payload: { copy: 'server' } }]);
+
+    mod.setLocalOverride('alpha', 'off');
+    expect(flag.variant()).toBe('off');
+
+    mod.clearLocalOverrides();
+    expect(flag.variant()).toBe('treatment');
+    expect(flag.payload()).toEqual({ copy: 'server' });
+  });
+
+  it('survives a user change — it is a browser setting, not a session one', async () => {
+    mod.init();
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    mod.setLocalOverride('alpha', 'on');
+
+    env.setUser('user:other');
+    await tick();
+    expect(flag.variant()).toBe('on');
+  });
+
+  it('persists to localStorage and reloads into a fresh module', () => {
+    mod.setLocalOverride('alpha', 'on', { copy: 'local' });
+    expect(mod.getLocalOverrides()).toEqual({ alpha: { variant: 'on', payload: { copy: 'local' } } });
+
+    // A new module reads the same page-origin store, as after a reload.
+    const reloaded = new FeatureFlagModule(makeDeps().deps);
+    expect(reloaded.getLocalOverrides()).toEqual({
+      alpha: { variant: 'on', payload: { copy: 'local' } },
+    });
+    expect(reloaded.feature('alpha', { fallback: 'off' }).variant()).toBe('on');
+  });
+
+  it('drops the storage key entirely once the last override is cleared', () => {
+    mod.setLocalOverride('alpha', 'on');
+    expect(ls.store.size).toBe(1);
+
+    mod.setLocalOverride('alpha', null);
+    expect(ls.store.size).toBe(0);
+    expect(new FeatureFlagModule(makeDeps().deps).getLocalOverrides()).toEqual({});
+  });
+
+  it('ignores a corrupt store rather than failing to construct', () => {
+    ls.store.set('sp00ky:feature-overrides', '{not json');
+    expect(() => new FeatureFlagModule(makeDeps().deps)).not.toThrow();
+  });
+});