@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/src/modules/data/mutation-id.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { mintMutationId, mutationOwnerTabId } from './mutation-id';
+
+// The old `_00_pending_mutations:${Date.now()}` collided within a millisecond
+// (guaranteed once multiple tabs share a store) and never actually ordered the
+// drain. These pin the new id's three properties: unique, sortable, routable.
+describe('mutation ids', () => {
+  it('never collides within a burst', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => mintMutationId('tabx')));
+    expect(ids.size).toBe(1000);
+  });
+
+  it('sorts lexicographically in mint order (ORDER BY id is chronological)', () => {
+    const ids = Array.from({ length: 200 }, () => mintMutationId('tabx'));
+    expect([...ids].sort()).toEqual(ids);
+  });
+
+  it('routes back to the owning tab', () => {
+    expect(mutationOwnerTabId(mintMutationId('tab-abc'))).toBe('tab-abc');
+  });
+
+  it('returns null for a legacy numeric id instead of misrouting', () => {
+    expect(mutationOwnerTabId('_00_pending_mutations:1753875000000')).toBeNull();
+  });
+});

package/src/modules/data/mutation-id.ts

@@ -0,0 +1,35 @@
+/**
+ * Outbox mutation ids. Previously `_00_pending_mutations:${Date.now()}`, which
+ * (a) collides when two mutations land in the same millisecond, a real case
+ * once multiple tabs share one store, and (b) never actually ordered the
+ * drain, because `loadFromDatabase` sorted by a `created_at` field that does
+ * not exist on the table. The new shape is sortable AND collision-free:
+ *
+ *   <13-digit zero-padded ms timestamp>_<4-digit base36 seq>_<tabId>
+ *
+ * Lexicographic order == chronological order (per tab; cross-tab within-ms
+ * ordering is arbitrary, which matches reality), so `ORDER BY id` in the
+ * drain is now meaningful. The tabId suffix also routes rollbacks back to the
+ * tab that owns the mutation in shared-tabs mode.
+ */
+
+let seq = 0;
+
+/** Tab identity for mutation ids in SOLO mode, minted once per session. In
+ *  shared-tabs mode the coordinator's tabId is passed in instead. */
+const FALLBACK_TAB_ID = Math.random().toString(36).slice(2, 8);
+
+export function mintMutationId(tabId?: string): string {
+  const ts = Date.now().toString().padStart(13, '0');
+  const n = (seq = (seq + 1) % 36 ** 4).toString(36).padStart(4, '0');
+  return `_00_pending_mutations:${ts}_${n}_${tabId ?? FALLBACK_TAB_ID}`;
+}
+
+/** The tab that created the mutation, or null for a legacy numeric id. */
+export function mutationOwnerTabId(mutationId: string): string | null {
+  const raw = mutationId.startsWith('_00_pending_mutations:')
+    ? mutationId.slice('_00_pending_mutations:'.length)
+    : mutationId;
+  const parts = raw.split('_');
+  return parts.length >= 3 ? parts[parts.length - 1] : null;
+}

package/src/modules/data/window-query.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { buildWindowMaterialization } from './window-query';
+
+describe('buildWindowMaterialization', () => {
+  it('rewrites the game-list window query (START 30) to select the id-set, keeping ORDER BY', () => {
+    const surql =
+      'SELECT * FROM game WHERE database = $database ORDER BY sort_index asc, date desc LIMIT 30 START 30;';
+    const r = buildWindowMaterialization(surql);
+    expect(r).not.toBeNull();
+    expect(r!.query).toBe('SELECT * FROM $__win ORDER BY sort_index asc, date desc');
+  });
+
+  it('returns null for START 0 (offset-free windows still work via the normal re-query)', () => {
+    const surql =
+      'SELECT * FROM game WHERE database = $database ORDER BY sort_index asc, date desc LIMIT 30 START 0;';
+    expect(buildWindowMaterialization(surql)).toBeNull();
+  });
+
+  it('returns null when there is no START clause', () => {
+    expect(
+      buildWindowMaterialization('SELECT * FROM game WHERE database = $database LIMIT 30;')
+    ).toBeNull();
+    expect(buildWindowMaterialization('SELECT * FROM game;')).toBeNull();
+  });
+
+  it('preserves a custom projection', () => {
+    const surql = 'SELECT id, white, black FROM game ORDER BY date desc LIMIT 30 START 60;';
+    expect(buildWindowMaterialization(surql)!.query).toBe(
+      'SELECT id, white, black FROM $__win ORDER BY date desc'
+    );
+  });
+
+  it('omits ORDER BY when the query had none', () => {
+    const surql = 'SELECT * FROM game LIMIT 30 START 30;';
+    expect(buildWindowMaterialization(surql)!.query).toBe('SELECT * FROM $__win');
+  });
+
+  it('ignores FROM/ORDER BY/LIMIT/START inside subqueries (paren-aware)', () => {
+    const surql =
+      'SELECT *, (SELECT * FROM comment WHERE game = $parent.id ORDER BY created_at desc LIMIT 5) AS comments ' +
+      'FROM game ORDER BY sort_index asc LIMIT 30 START 90;';
+    expect(buildWindowMaterialization(surql)!.query).toBe(
+      'SELECT *, (SELECT * FROM comment WHERE game = $parent.id ORDER BY created_at desc LIMIT 5) AS comments FROM $__win ORDER BY sort_index asc'
+    );
+  });
+
+  it('does not treat a START inside a string literal as the offset', () => {
+    const surql = "SELECT * FROM game WHERE note = 'LIMIT 30 START 30' ORDER BY date desc LIMIT 30 START 30;";
+    const r = buildWindowMaterialization(surql);
+    expect(r!.query).toBe('SELECT * FROM $__win ORDER BY date desc');
+  });
+});

package/src/modules/data/window-query.ts

@@ -0,0 +1,194 @@
+/**
+ * Rewrite a windowed (`LIMIT n START m`, m>0) SELECT so its rows are
+ * materialized from an explicit record-id set — the window the SSP already
+ * computed — instead of re-running the original query (with its `START m`)
+ * against the shared local DB.
+ *
+ * Why: `DataModule.processStreamUpdate` materializes a query's rows by
+ * re-querying the local in-browser SurrealDB with the original surql. For an
+ * offset query that re-applies `START m` against the *shared* local store —
+ * which, with sparse windowing, may hold only this window's rows — so it skips
+ * them all and returns nothing (the "page 2 returns 0 rows" bug). The SSP's
+ * materialized view (`StreamUpdate.localArray`) is exactly this window's row
+ * ids, so we select those ids directly and re-apply the original `ORDER BY` for
+ * stable display order.
+ *
+ * Returns `null` for non-offset queries (`START` absent or 0) — the caller
+ * keeps the normal re-query path, so only the broken case changes behavior.
+ *
+ * Preserves the `SELECT <projection>` clause and the top-level `ORDER BY`;
+ * drops the original `FROM`/`WHERE`/`LIMIT`/`START`. Subqueries inside the
+ * projection are preserved verbatim (the scanner is paren/quote aware), with
+ * one caveat: SurrealDB v3 drops `*` in the `SELECT *, <subquery> FROM $param`
+ * shape — such windowed+subquery queries are rare and were already returning 0,
+ * so this is no regression.
+ */
+import type { QueryPlan } from '@spooky-sync/query-builder';
+
+/**
+ * Plan-level window materialization: restrict a windowed query's base rows to
+ * exactly the SSP-computed id-set, dropping `where`/`limit`/`offset` but keeping
+ * `orderBy`, `select` and `relations`. The engine-neutral counterpart of
+ * {@link buildWindowMaterialization} (which does the same by string surgery for
+ * the raw-SurrealQL path). Returns `null` for non-offset queries so the caller
+ * keeps the normal re-query path.
+ */
+export function buildWindowMaterializationPlan(
+  plan: QueryPlan,
+  ids: unknown[]
+): QueryPlan | null {
+  if (plan.offset === undefined || plan.offset <= 0) return null;
+  return buildIdSetPlan(plan, ids);
+}
+
+/**
+ * Raw-SurrealQL counterpart of {@link buildIdSetPlan}, for queries that arrived
+ * without a plan. Same rewrite as {@link buildWindowMaterialization} without the
+ * offset guard: keep the projection and top-level `ORDER BY`, replace the source
+ * with the bound id-set.
+ */
+export function buildIdSetSurql(
+  surql: string,
+  idsParam = '__win'
+): { query: string } | null {
+  const kw = scanTopLevelClauses(surql);
+  if (kw.fromIndex === null) return null;
+  return { query: renderIdSetSelect(surql, kw, idsParam) };
+}
+
+/** Shared body of the two id-set surql rewrites: keep the projection and the
+ *  top-level `ORDER BY`, replace the source with the bound id-set. */
+function renderIdSetSelect(surql: string, kw: TopLevelClauses, idsParam: string): string {
+  const selectClause = surql.slice(0, kw.fromIndex!).trimEnd(); // "SELECT <projection>"
+
+  let orderBy = '';
+  const orderByIndex = kw.orderByIndex;
+  if (orderByIndex !== null) {
+    const ends = [kw.limitIndex, kw.startIndex, kw.semicolonIndex, surql.length].filter(
+      (n): n is number => n !== null && n > orderByIndex
+    );
+    orderBy = ' ' + surql.slice(orderByIndex, Math.min(...ends)).trim();
+  }
+
+  return `${selectClause} FROM $${idsParam}${orderBy}`;
+}
+
+/**
+ * Restrict any plan's base rows to an explicit id-set, regardless of offset.
+ *
+ * Same rewrite as {@link buildWindowMaterializationPlan} without the offset
+ * guard, for rendering a query from its authoritative membership list rather
+ * than by re-running its predicate.
+ *
+ * `where` is dropped deliberately: the id-set already IS the answer to the
+ * predicate as the server evaluated it, and re-applying the `WHERE` locally is
+ * exactly the bug — a row that left the window keeps its (stale, never
+ * re-fetched) local body, so it keeps matching and keeps rendering.
+ * `limit`/`offset` go for the same reason: both are already baked into which ids
+ * are in the set, so the set itself is the bound. (Both engines ignore them on
+ * the `ids` path regardless — only `select` and `orderBy` are honored there.)
+ * `orderBy` is kept so display order stays deterministic.
+ */
+export function buildIdSetPlan(plan: QueryPlan, ids: unknown[]): QueryPlan {
+  return {
+    ...plan,
+    ids,
+    where: undefined,
+    limit: undefined,
+    offset: undefined,
+  };
+}
+
+export function buildWindowMaterialization(
+  surql: string,
+  idsParam = '__win'
+): { query: string } | null {
+  const kw = scanTopLevelClauses(surql);
+  if (kw.startValue === null || kw.startValue <= 0) return null;
+  if (kw.fromIndex === null) return null;
+  return { query: renderIdSetSelect(surql, kw, idsParam) };
+}
+
+interface TopLevelClauses {
+  fromIndex: number | null;
+  orderByIndex: number | null;
+  limitIndex: number | null;
+  startIndex: number | null;
+  startValue: number | null;
+  semicolonIndex: number | null;
+}
+
+// Single pass over the query, tracking paren depth and single-quoted strings so
+// that clauses inside subqueries (which live in parens) are ignored — only the
+// outermost (depth-0) clause keywords are recorded.
+function scanTopLevelClauses(sql: string): TopLevelClauses {
+  const out: TopLevelClauses = {
+    fromIndex: null,
+    orderByIndex: null,
+    limitIndex: null,
+    startIndex: null,
+    startValue: null,
+    semicolonIndex: null,
+  };
+  let depth = 0;
+  let inStr = false;
+
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (inStr) {
+      if (ch === '\\') i++; // skip escaped char
+      else if (ch === "'") inStr = false;
+      continue;
+    }
+    if (ch === "'") { inStr = true; continue; }
+    if (ch === '(') { depth++; continue; }
+    if (ch === ')') { depth--; continue; }
+    if (depth !== 0) continue;
+    if (ch === ';' && out.semicolonIndex === null) { out.semicolonIndex = i; continue; }
+
+    // Only test keywords at a word boundary.
+    if (!isWordBoundary(sql, i)) continue;
+    if (out.fromIndex === null && matchKeyword(sql, i, 'FROM')) { out.fromIndex = i; continue; }
+    // FROM must come before the trailing clauses; only record them once seen.
+    if (out.fromIndex === null) continue;
+    if (out.orderByIndex === null && matchKeyword(sql, i, 'ORDER BY')) { out.orderByIndex = i; continue; }
+    if (out.limitIndex === null && matchKeyword(sql, i, 'LIMIT')) { out.limitIndex = i; continue; }
+    if (out.startIndex === null && matchKeyword(sql, i, 'START')) {
+      out.startIndex = i;
+      out.startValue = readNumberAfter(sql, i + 'START'.length);
+      continue;
+    }
+  }
+  return out;
+}
+
+function isWordBoundary(sql: string, i: number): boolean {
+  if (i === 0) return true;
+  return !/[A-Za-z0-9_]/.test(sql[i - 1]);
+}
+
+// Case-insensitive keyword match where internal whitespace (e.g. "ORDER BY")
+// matches any run of whitespace, and the keyword ends on a non-word char.
+function matchKeyword(sql: string, i: number, keyword: string): boolean {
+  const parts = keyword.split(' ');
+  let pos = i;
+  for (let p = 0; p < parts.length; p++) {
+    const word = parts[p];
+    if (sql.slice(pos, pos + word.length).toUpperCase() !== word) return false;
+    pos += word.length;
+    if (p < parts.length - 1) {
+      const wsStart = pos;
+      while (pos < sql.length && /\s/.test(sql[pos])) pos++;
+      if (pos === wsStart) return false; // required whitespace
+    }
+  }
+  // Must end on a non-word char (or end of string).
+  return pos >= sql.length || !/[A-Za-z0-9_]/.test(sql[pos]);
+}
+
+function readNumberAfter(sql: string, from: number): number | null {
+  let pos = from;
+  while (pos < sql.length && /\s/.test(sql[pos])) pos++;
+  const m = /^\d+/.exec(sql.slice(pos));
+  return m ? parseInt(m[0], 10) : null;
+}

package/src/modules/devtools/flags.ts

@@ -0,0 +1,349 @@
+/**
+ * Feature flag administration for the DevTools panel.
+ *
+ * Two independent capabilities, deliberately kept apart:
+ *
+ * - **Local overrides** force a variant in THIS browser. No auth, no network,
+ *   works signed out and offline. Delegated straight to `FeatureFlagModule`.
+ * - **Remote changes** flip a flag for EVERY user. These require the caller to
+ *   be listed in `_00_admin` (`spky admin add <user>`); SurrealDB enforces
+ *   that, not this file. A non-admin's SELECT returns `[]` rather than an
+ *   error, and the `fn::feature::*` calls are hard-denied.
+ *
+ * Everything remote goes through `RemoteDatabaseService` with BOUND params.
+ * The panel's generic `runQuery` bridge is not usable here: it interpolates
+ * the SurrealQL into an `inspectedWindow.eval` string (so a DB-sourced flag
+ * key or record id would be concatenated into code) and it rejects after 10s,
+ * which a materialize over a real user table will exceed.
+ *
+ * Definitions live in `_00_feature_flag`, which is NOT synced to clients, so
+ * flags must be read remotely. Per-user assignments live in `_00_user_feature`,
+ * which IS live-synced, so those come from the local store for free.
+ */
+
+import type { Logger } from '../../services/logger/index';
+import { parseRecordIdString } from '../../utils/index';
+
+/**
+ * The only thing this service needs from a database. Structural rather than
+ * `AbstractDatabaseService`, because the local side is a `LocalStore` (which
+ * wraps a database rather than extending it) and both must satisfy it.
+ */
+export interface FlagQueryable {
+  query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+}
+
+/** A targeting rule as written by `spky flag` / `fn::feature::allow`. */
+export interface DevToolsFlagRule {
+  kind: 'allowlist' | 'rollout' | string;
+  variant: string;
+  /** Allowlist only. Stored as record-id STRINGS, not records. */
+  users?: string[];
+  /** Rollout only, 0..100. */
+  percent?: number;
+  priority: number;
+}
+
+export interface DevToolsFlagRow {
+  key: string;
+  description?: string;
+  variants: string[];
+  default_variant: string;
+  enabled: boolean;
+  payloads?: Record<string, unknown>;
+  rules: DevToolsFlagRule[];
+  updated_at?: string;
+  /** Derived: the variant the signed-in user is allowlisted into, if any. */
+  selfAllowlistedVariant?: string;
+}
+
+export interface DevToolsFlagAssignment {
+  key: string;
+  variant: string;
+  payload?: unknown;
+}
+
+export interface DevToolsFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
+
+export interface DevToolsFlagsSnapshot {
+  at: number;
+  /** Null when signed out. */
+  userId: string | null;
+  /** True when `_00_admin` has a row for the signed-in user. */
+  isAdmin: boolean;
+  /** Empty for non-admins — SurrealDB filters the rows, it does not error. */
+  flags: DevToolsFlagRow[];
+  /** From the LOCAL `_00_user_feature`: what this browser actually resolves. */
+  assignments: DevToolsFlagAssignment[];
+  /** Local-only forced variants, page-origin localStorage. */
+  overrides: Record<string, DevToolsFlagOverride>;
+  /**
+   * Set when the internal schema predates this feature (no `_00_admin` table),
+   * or the remote read failed. The panel shows it instead of a bare empty
+   * state, so "not migrated" doesn't look like "you're not an admin".
+   */
+  error?: string;
+}
+
+export interface DevToolsFlagResult {
+  success: boolean;
+  error?: string;
+  /** Users re-evaluated by `fn::feature::materialize`. */
+  users?: number;
+}
+
+/** The slice of `FeatureFlagModule` this service needs. */
+export interface LocalOverrideStore {
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void;
+  clearLocalOverrides(): void;
+  getLocalOverrides(): Record<string, DevToolsFlagOverride>;
+}
+
+export interface FlagsAdminDeps {
+  remote: FlagQueryable;
+  local: FlagQueryable;
+  logger: Logger;
+  /** Resolves the signed-in user's record id, or null. */
+  currentUserId: () => string | null;
+  /** Set once the client has built its FeatureFlagModule. */
+  overrides: () => LocalOverrideStore | null;
+}
+
+/**
+ * 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: unknown, index = 0): unknown[] {
+  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 as { result?: unknown }).result;
+    return Array.isArray(inner) ? inner : inner === undefined || inner === null ? [] : [inner];
+  }
+  return entry === undefined || entry === null ? [] : [entry];
+}
+
+function message(err: unknown): string {
+  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: unknown): row is { key: string } {
+  return !!row && typeof row === 'object' && typeof (row as { key?: unknown }).key === 'string';
+}
+
+function isAssignment(row: unknown): row is DevToolsFlagAssignment {
+  return hasStringKey(row);
+}
+
+function isFlagRow(row: unknown): row is DevToolsFlagRow {
+  return hasStringKey(row);
+}
+
+export class FlagsAdminService {
+  constructor(private deps: FlagsAdminDeps) {}
+
+  /**
+   * Everything the Access 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(): Promise<DevToolsFlagsSnapshot> {
+    const userId = this.deps.currentUserId();
+    const snapshot: DevToolsFlagsSnapshot = {
+      at: Date.now(),
+      userId,
+      isAdmin: false,
+      flags: [],
+      assignments: [],
+      overrides: this.deps.overrides()?.getLocalOverrides() ?? {},
+    };
+
+    // Local assignments: available signed out and offline.
+    try {
+      const rows = statementRows(
+        await this.deps.local.query('SELECT key, variant, payload FROM _00_user_feature')
+      );
+      snapshot.assignments = rows.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 {
+      // Self-scoped by `_00_admin`'s own select rule: an admin sees exactly
+      // their own row, a non-admin sees nothing. The roster never leaks.
+      const admin = statementRows(
+        await this.deps.remote.query('SELECT VALUE id FROM _00_admin WHERE user = $auth.id LIMIT 1')
+      );
+      snapshot.isAdmin = admin.length > 0;
+    } catch (err) {
+      // A missing `_00_admin` table means the deployment hasn't applied the
+      // internal schema yet. Say so — otherwise it reads as "not an admin".
+      snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Access tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
+      return snapshot;
+    }
+
+    if (!snapshot.isAdmin) return snapshot;
+
+    try {
+      const rows = 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'
+        )
+      );
+      snapshot.flags = rows
+        .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: string, enabled: boolean): Promise<DevToolsFlagResult> {
+    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: string,
+    variant: string,
+    remove: boolean,
+    userId?: string
+  ): Promise<DevToolsFlagResult> {
+    const target = userId ?? this.deps.currentUserId();
+    if (!target) return { success: false, error: 'Not signed in' };
+
+    // `fn::feature::allow/disallow` declare `$user: record`. A string binding
+    // is rejected by the type check, so parse it into a real RecordId.
+    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: string,
+    variant: string | null,
+    payload?: unknown
+  ): { overrides: Record<string, DevToolsFlagOverride> } {
+    const store = this.deps.overrides();
+    store?.setLocalOverride(key, variant, payload);
+    return { overrides: store?.getLocalOverrides() ?? {} };
+  }
+
+  clearLocalFlagOverrides(): { overrides: Record<string, DevToolsFlagOverride> } {
+    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.
+   */
+  private async mutate(
+    sql: string,
+    vars: Record<string, unknown>,
+    index: number
+  ): Promise<DevToolsFlagResult> {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < MUTATE_ATTEMPTS; attempt++) {
+      try {
+        const result = await this.deps.remote.query(sql, vars);
+        const materialized = statementRows(result, index)[0] as { users?: number } | undefined;
+        return { success: true, users: materialized?.users };
+      } catch (err) {
+        lastError = err;
+        if (!isRetryableConflict(err) || attempt === MUTATE_ATTEMPTS - 1) break;
+        // Staggered so two collided clients don't line up again on the retry.
+        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: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function isRetryableConflict(err: unknown): boolean {
+  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: DevToolsFlagRow, userId: string): string | undefined {
+  const rules = Array.isArray(flag.rules) ? flag.rules : [];
+  const hit = rules.find(
+    (rule) =>
+      rule?.kind === 'allowlist' &&
+      Array.isArray(rule.users) &&
+      rule.users.some((u) => String(u) === userId)
+  );
+  return hit?.variant;
+}