@scalebun/react-native 1.0.2 → 1.0.4

package/src/bucketing/fnv1a32.ts

@@ -1,40 +1,40 @@
-/**
- * Deterministic experiment/rollout bucketing — MUST stay byte-for-byte identical to
- * the backend (scalebun-dashboard-backend/src/common/bucketing/fnv1a32.ts). A shared test
- * vector is asserted in BOTH repos; if you change the hash, update both.
- *
- * Inputs are ASCII (installationId = UUID, salt = hex) so charCodeAt === UTF-8 byte.
- */
-export function fnv1a32(str: string): number {
-  let h = 0x811c9dc5; // FNV offset basis (2166136261)
-  for (let i = 0; i < str.length; i++) {
-    h ^= str.charCodeAt(i);
-    h = Math.imul(h, 0x01000193); // FNV prime (16777619)
-  }
-  return h >>> 0; // unsigned 32-bit
-}
-
-/** Stable 0..99 bucket for an install within an experiment/rollout (salt is immutable). */
-export function bucketOf(installationId: string, salt: string): number {
-  return fnv1a32(`${installationId}:${salt}`) % 100;
-}
-
-/**
- * Pick a variant by cumulative allocation. `variants` order is significant and
- * `allocationPct` should sum to 100; the last variant is the fallback so an install
- * always resolves to a variant.
- */
-export function pickVariant(
-  installationId: string,
-  salt: string,
-  variants: Array<{ key: string; allocationPct: number }>,
-): string | null {
-  if (!variants.length) return null;
-  const b = bucketOf(installationId, salt);
-  let cum = 0;
-  for (const v of variants) {
-    cum += v.allocationPct;
-    if (b < cum) return v.key;
-  }
-  return variants[variants.length - 1].key;
-}
+/**
+ * Deterministic experiment/rollout bucketing — MUST stay byte-for-byte identical to
+ * the backend (scalebun-dashboard-backend/src/common/bucketing/fnv1a32.ts). A shared test
+ * vector is asserted in BOTH repos; if you change the hash, update both.
+ *
+ * Inputs are ASCII (installationId = UUID, salt = hex) so charCodeAt === UTF-8 byte.
+ */
+export function fnv1a32(str: string): number {
+  let h = 0x811c9dc5; // FNV offset basis (2166136261)
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193); // FNV prime (16777619)
+  }
+  return h >>> 0; // unsigned 32-bit
+}
+
+/** Stable 0..99 bucket for an install within an experiment/rollout (salt is immutable). */
+export function bucketOf(installationId: string, salt: string): number {
+  return fnv1a32(`${installationId}:${salt}`) % 100;
+}
+
+/**
+ * Pick a variant by cumulative allocation. `variants` order is significant and
+ * `allocationPct` should sum to 100; the last variant is the fallback so an install
+ * always resolves to a variant.
+ */
+export function pickVariant(
+  installationId: string,
+  salt: string,
+  variants: Array<{ key: string; allocationPct: number }>,
+): string | null {
+  if (!variants.length) return null;
+  const b = bucketOf(installationId, salt);
+  let cum = 0;
+  for (const v of variants) {
+    cum += v.allocationPct;
+    if (b < cum) return v.key;
+  }
+  return variants[variants.length - 1].key;
+}

package/src/compat/codepush.ts

@@ -1,118 +1,118 @@
-import { otaOrchestrator } from '../features/ota/OtaOrchestrator';
-
-export enum CodePushInstallMode {
-  IMMEDIATE = 0,
-  ON_NEXT_RESTART = 1,
-  ON_NEXT_RESUME = 2,
-  ON_NEXT_SUSPEND = 3,
-}
-
-export enum CodePushSyncStatus {
-  UP_TO_DATE = 0,
-  UPDATE_INSTALLED = 1,
-  UPDATE_IGNORED = 2,
-  UNKNOWN_ERROR = 3,
-  CHECKING_FOR_UPDATE = 4,
-  DOWNLOADING_PACKAGE = 5,
-  INSTALLING_UPDATE = 6,
-}
-
-export interface CodePushOptions {
-  checkFrequency?: number;
-  installMode?: CodePushInstallMode;
-  mandatoryInstallMode?: CodePushInstallMode;
-  minimumBackgroundDuration?: number;
-}
-
-export interface CodePushPackage {
-  appVersion: string;
-  deploymentKey: string;
-  description: string;
-  failedInstall: boolean;
-  isFirstRun: boolean;
-  isMandatory: boolean;
-  isPending: boolean;
-  label: string;
-  packageHash: string;
-  packageSize: number;
-}
-
-/**
- * Microsoft CodePush Drop-in Compatibility Shim — Sprint 10 (S10-CLI-1).
- *
- * Allows developers to migrate from CodePush to Scalebun OTA by simply changing:
- *   - import codePush from 'react-native-code-push'
- *   + import codePush from '@scalebun/react-native/compat/codepush'
- */
-const codePushShim = function <P>(rootComponent: React.ComponentType<P>) {
-  return rootComponent;
-};
-
-codePushShim.sync = async (
-  options?: CodePushOptions,
-  syncStatusCallback?: (status: CodePushSyncStatus) => void,
-  downloadProgressCallback?: (progress: { receivedBytes: number; totalBytes: number }) => void,
-): Promise<CodePushSyncStatus> => {
-  try {
-    syncStatusCallback?.(CodePushSyncStatus.CHECKING_FOR_UPDATE);
-    const result = await otaOrchestrator.sync({
-      apiUrl: 'http://localhost:3001/api/v1',
-      clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
-      appVersion: '1.0.0',
-      installationId: 'codepush_shim',
-    });
-
-    if (result.status === 'UP_TO_DATE') {
-      syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
-      return CodePushSyncStatus.UP_TO_DATE;
-    }
-
-    if (result.status === 'UPDATE_INSTALLED') {
-      syncStatusCallback?.(CodePushSyncStatus.UPDATE_INSTALLED);
-      return CodePushSyncStatus.UPDATE_INSTALLED;
-    }
-
-    syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
-    return CodePushSyncStatus.UP_TO_DATE;
-  } catch (err) {
-    syncStatusCallback?.(CodePushSyncStatus.UNKNOWN_ERROR);
-    return CodePushSyncStatus.UNKNOWN_ERROR;
-  }
-};
-
-codePushShim.checkForUpdate = async (): Promise<CodePushPackage | null> => {
-  const check = await otaOrchestrator.checkForUpdate({
-    apiUrl: 'http://localhost:3001/api/v1',
-    clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
-    appVersion: '1.0.0',
-    installationId: 'codepush_shim',
-  });
-  if (check.action === 'NONE' || !check.bundle) return null;
-
-  return {
-    appVersion: '1.0.0',
-    deploymentKey: 'scalebun_ota',
-    description: check.bundle.releaseNote ?? '',
-    failedInstall: false,
-    isFirstRun: false,
-    isMandatory: check.bundle.isMandatory,
-    isPending: false,
-    label: `v${check.bundle.version}`,
-    packageHash: check.bundle.sha256,
-    packageSize: check.bundle.size,
-  };
-};
-
-codePushShim.disallowRestart = () => {
-  // Scalebun handles restart safety automatically via boot guard
-};
-
-codePushShim.allowRestart = () => {
-  // Scalebun handles restart safety automatically via boot guard
-};
-
-codePushShim.getUpdateMetadata = async (): Promise<CodePushPackage | null> => {
-  return null;
-};
-
-export default codePushShim;
+import { otaOrchestrator } from '../features/ota/OtaOrchestrator';
+
+export enum CodePushInstallMode {
+  IMMEDIATE = 0,
+  ON_NEXT_RESTART = 1,
+  ON_NEXT_RESUME = 2,
+  ON_NEXT_SUSPEND = 3,
+}
+
+export enum CodePushSyncStatus {
+  UP_TO_DATE = 0,
+  UPDATE_INSTALLED = 1,
+  UPDATE_IGNORED = 2,
+  UNKNOWN_ERROR = 3,
+  CHECKING_FOR_UPDATE = 4,
+  DOWNLOADING_PACKAGE = 5,
+  INSTALLING_UPDATE = 6,
+}
+
+export interface CodePushOptions {
+  checkFrequency?: number;
+  installMode?: CodePushInstallMode;
+  mandatoryInstallMode?: CodePushInstallMode;
+  minimumBackgroundDuration?: number;
+}
+
+export interface CodePushPackage {
+  appVersion: string;
+  deploymentKey: string;
+  description: string;
+  failedInstall: boolean;
+  isFirstRun: boolean;
+  isMandatory: boolean;
+  isPending: boolean;
+  label: string;
+  packageHash: string;
+  packageSize: number;
+}
+
+/**
+ * Microsoft CodePush Drop-in Compatibility Shim — Sprint 10 (S10-CLI-1).
+ *
+ * Allows developers to migrate from CodePush to Scalebun OTA by simply changing:
+ *   - import codePush from 'react-native-code-push'
+ *   + import codePush from '@scalebun/react-native/compat/codepush'
+ */
+const codePushShim = function <P>(rootComponent: React.ComponentType<P>) {
+  return rootComponent;
+};
+
+codePushShim.sync = async (
+  options?: CodePushOptions,
+  syncStatusCallback?: (status: CodePushSyncStatus) => void,
+  downloadProgressCallback?: (progress: { receivedBytes: number; totalBytes: number }) => void,
+): Promise<CodePushSyncStatus> => {
+  try {
+    syncStatusCallback?.(CodePushSyncStatus.CHECKING_FOR_UPDATE);
+    const result = await otaOrchestrator.sync({
+      apiUrl: 'http://localhost:3001/api/v1',
+      clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
+      appVersion: '1.0.0',
+      installationId: 'codepush_shim',
+    });
+
+    if (result.status === 'UP_TO_DATE') {
+      syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
+      return CodePushSyncStatus.UP_TO_DATE;
+    }
+
+    if (result.status === 'UPDATE_INSTALLED') {
+      syncStatusCallback?.(CodePushSyncStatus.UPDATE_INSTALLED);
+      return CodePushSyncStatus.UPDATE_INSTALLED;
+    }
+
+    syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
+    return CodePushSyncStatus.UP_TO_DATE;
+  } catch (err) {
+    syncStatusCallback?.(CodePushSyncStatus.UNKNOWN_ERROR);
+    return CodePushSyncStatus.UNKNOWN_ERROR;
+  }
+};
+
+codePushShim.checkForUpdate = async (): Promise<CodePushPackage | null> => {
+  const check = await otaOrchestrator.checkForUpdate({
+    apiUrl: 'http://localhost:3001/api/v1',
+    clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
+    appVersion: '1.0.0',
+    installationId: 'codepush_shim',
+  });
+  if (check.action === 'NONE' || !check.bundle) return null;
+
+  return {
+    appVersion: '1.0.0',
+    deploymentKey: 'scalebun_ota',
+    description: check.bundle.releaseNote ?? '',
+    failedInstall: false,
+    isFirstRun: false,
+    isMandatory: check.bundle.isMandatory,
+    isPending: false,
+    label: `v${check.bundle.version}`,
+    packageHash: check.bundle.sha256,
+    packageSize: check.bundle.size,
+  };
+};
+
+codePushShim.disallowRestart = () => {
+  // Scalebun handles restart safety automatically via boot guard
+};
+
+codePushShim.allowRestart = () => {
+  // Scalebun handles restart safety automatically via boot guard
+};
+
+codePushShim.getUpdateMetadata = async (): Promise<CodePushPackage | null> => {
+  return null;
+};
+
+export default codePushShim;

package/src/config/ConfigManager.ts

@@ -1,167 +1,167 @@
-/**
- * ScaleBun SDK — runtime config (Phase 4).
- *
- * Polls GET {apiBaseUrl}/config (client-key authed), caches it to disk, and resolves
- * flags / remote config / rollouts / experiments LOCALLY (deterministic fnv1a32 — the
- * backend never assigns). Experiment exposure flows through the normal event lane:
- * variant() emits one `experiment_exposure` event per (install, experiment) and stamps
- * `experiment_<key>=<variant>` onto subsequent events.
- *
- * Every method is non-throwing with a safe default — an app that can't reach /config
- * behaves exactly as it would with no experiments configured.
- */
-import { createStorageBackend, StorageBackend } from '../storage/StorageBackend';
-import { logger } from '../core/logger/internalLogger';
-import { bucketOf, pickVariant } from '../bucketing/fnv1a32';
-import { EMPTY_CONFIG, SdkConfigPayload } from './configTypes';
-
-const K_CONFIG = 'scalebun_config_payload';
-const K_CONFIG_VERSION = 'scalebun_config_version';
-const K_EXPOSED = 'scalebun_exp_exposed';
-const DEFAULT_TTL_MS = 5 * 60 * 1000; // foreground refreshes throttled to 5 min
-
-export interface ConfigManagerDeps {
-  apiBaseUrl: string;
-  clientKey: string;
-  installationId: string;
-  /** Emit an exposure event (→ EventTracker.track('experiment_exposure', …)). */
-  emitExposure: (experiment: string, variant: string) => void;
-  /** Stamp a persistent property onto all subsequent events (→ EventTracker.stamp). */
-  stamp: (key: string, value: string) => void;
-}
-
-function coerce(value: string, type: string, fallback: any): any {
-  try {
-    if (type === 'number') { const n = Number(value); return Number.isNaN(n) ? fallback : n; }
-    if (type === 'boolean') return value === 'true';
-    if (type === 'json') return JSON.parse(value);
-    return value;
-  } catch {
-    return fallback;
-  }
-}
-
-export class ConfigManager {
-  private storage: StorageBackend;
-  private payload: SdkConfigPayload = EMPTY_CONFIG;
-  private exposed = new Set<string>();
-  private lastFetch = 0;
-
-  constructor(private readonly deps: ConfigManagerDeps) {
-    this.storage = createStorageBackend();
-    this.loadCached();
-    this.loadExposed();
-  }
-
-  /** Fetch /config (ETag-aware). Keeps the cached payload on 304 / failure. */
-  async refresh(): Promise<void> {
-    try {
-      const version = this.storage.get(K_CONFIG_VERSION);
-      const res = await fetch(`${this.deps.apiBaseUrl}/config`, {
-        headers: {
-          'x-scalebun-client-key': this.deps.clientKey,
-          ...(version ? { 'If-None-Match': `"${version}"` } : {}),
-        },
-      });
-      this.lastFetch = Date.now();
-      if (res.status === 304) return; // unchanged — keep cache
-      if (!res.ok) return; // keep cache / defaults
-      const payload = (await res.json()) as SdkConfigPayload;
-      if (payload && Array.isArray(payload.flags) && Array.isArray(payload.experiments)) {
-        this.payload = payload;
-        try {
-          this.storage.set(K_CONFIG, JSON.stringify(payload));
-          if (payload.version) this.storage.set(K_CONFIG_VERSION, payload.version);
-        } catch { /* no-throw */ }
-      }
-    } catch (err) {
-      logger.warn(`[ScaleBun.config] refresh failed: ${(err as Error)?.message}`);
-    }
-  }
-
-  /** Refresh if the TTL has elapsed (call on app-foreground). Fire-and-forget. */
-  maybeRefresh(): void {
-    if (Date.now() - this.lastFetch > DEFAULT_TTL_MS) this.refresh().catch(() => {});
-  }
-
-  // ── resolution (all local + non-throwing) ──────────────────────────────────
-  isEnabled(key: string): boolean {
-    return this.payload.flags.find((f) => f.key === key)?.enabled ?? false;
-  }
-
-  get<T = any>(key: string, fallback: T): T {
-    const e = this.payload.remoteConfig.find((r) => r.key === key);
-    return e ? coerce(e.value, e.type, fallback) : fallback;
-  }
-
-  rolloutIsOn(key: string): boolean {
-    const r = this.payload.rollouts.find((x) => x.key === key);
-    return r ? bucketOf(this.deps.installationId, r.salt) < r.percentage : false;
-  }
-
-  /**
-   * Whether the org is entitled to a SDK-suppressible feature. Fail-OPEN: an
-   * absent/unknown entitlement (e.g. before the first /config) returns true so we
-   * never wrongly disable a paying customer. The server is the real gate.
-   */
-  isFeatureEntitled(feature: string): boolean {
-    const e = this.payload.entitlements as Record<string, boolean> | undefined;
-    return e?.[feature] ?? true;
-  }
-
-  /**
-   * Read the cached config's entitlements synchronously WITHOUT a full
-   * ConfigManager (which needs the EventTracker, created during bootstrap). Lets
-   * the facade suppress closed-feature collectors at bootstrap time on any run
-   * after the first. Returns {} when no cache exists (→ fail-open).
-   */
-  static readCachedEntitlements(): Record<string, boolean> {
-    try {
-      const storage = createStorageBackend();
-      const raw = storage.get(K_CONFIG);
-      if (!raw) return {};
-      const parsed = JSON.parse(raw) as SdkConfigPayload;
-      return (parsed?.entitlements as Record<string, boolean>) ?? {};
-    } catch {
-      return {};
-    }
-  }
-
-  variant(key: string): string | null {
-    const exp = this.payload.experiments.find((e) => e.key === key);
-    if (!exp) return null;
-    const v = pickVariant(this.deps.installationId, exp.salt, exp.variants);
-    if (!v) return null;
-    // Log exposure exactly once per (install, experiment).
-    if (!this.exposed.has(key)) {
-      this.exposed.add(key);
-      this.persistExposed();
-      try { this.deps.emitExposure(key, v); } catch { /* no-throw */ }
-    }
-    // Stamp the assignment onto subsequent events for downstream slicing.
-    try { this.deps.stamp(`experiment_${key}`, v); } catch { /* no-throw */ }
-    return v;
-  }
-
-  // ── persistence ─────────────────────────────────────────────────────────────
-  private loadCached(): void {
-    try {
-      const raw = this.storage.get(K_CONFIG);
-      if (raw) {
-        const parsed = JSON.parse(raw);
-        if (parsed && Array.isArray(parsed.flags)) this.payload = parsed;
-      }
-    } catch { this.payload = EMPTY_CONFIG; }
-  }
-
-  private loadExposed(): void {
-    try {
-      const raw = this.storage.get(K_EXPOSED);
-      if (raw) { const a = JSON.parse(raw); if (Array.isArray(a)) this.exposed = new Set(a); }
-    } catch { /* no-throw */ }
-  }
-
-  private persistExposed(): void {
-    try { this.storage.set(K_EXPOSED, JSON.stringify([...this.exposed])); } catch { /* no-throw */ }
-  }
-}
+/**
+ * ScaleBun SDK — runtime config (Phase 4).
+ *
+ * Polls GET {apiBaseUrl}/config (client-key authed), caches it to disk, and resolves
+ * flags / remote config / rollouts / experiments LOCALLY (deterministic fnv1a32 — the
+ * backend never assigns). Experiment exposure flows through the normal event lane:
+ * variant() emits one `experiment_exposure` event per (install, experiment) and stamps
+ * `experiment_<key>=<variant>` onto subsequent events.
+ *
+ * Every method is non-throwing with a safe default — an app that can't reach /config
+ * behaves exactly as it would with no experiments configured.
+ */
+import { createStorageBackend, StorageBackend } from '../storage/StorageBackend';
+import { logger } from '../core/logger/internalLogger';
+import { bucketOf, pickVariant } from '../bucketing/fnv1a32';
+import { EMPTY_CONFIG, SdkConfigPayload } from './configTypes';
+
+const K_CONFIG = 'scalebun_config_payload';
+const K_CONFIG_VERSION = 'scalebun_config_version';
+const K_EXPOSED = 'scalebun_exp_exposed';
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // foreground refreshes throttled to 5 min
+
+export interface ConfigManagerDeps {
+  apiBaseUrl: string;
+  clientKey: string;
+  installationId: string;
+  /** Emit an exposure event (→ EventTracker.track('experiment_exposure', …)). */
+  emitExposure: (experiment: string, variant: string) => void;
+  /** Stamp a persistent property onto all subsequent events (→ EventTracker.stamp). */
+  stamp: (key: string, value: string) => void;
+}
+
+function coerce(value: string, type: string, fallback: any): any {
+  try {
+    if (type === 'number') { const n = Number(value); return Number.isNaN(n) ? fallback : n; }
+    if (type === 'boolean') return value === 'true';
+    if (type === 'json') return JSON.parse(value);
+    return value;
+  } catch {
+    return fallback;
+  }
+}
+
+export class ConfigManager {
+  private storage: StorageBackend;
+  private payload: SdkConfigPayload = EMPTY_CONFIG;
+  private exposed = new Set<string>();
+  private lastFetch = 0;
+
+  constructor(private readonly deps: ConfigManagerDeps) {
+    this.storage = createStorageBackend();
+    this.loadCached();
+    this.loadExposed();
+  }
+
+  /** Fetch /config (ETag-aware). Keeps the cached payload on 304 / failure. */
+  async refresh(): Promise<void> {
+    try {
+      const version = this.storage.get(K_CONFIG_VERSION);
+      const res = await fetch(`${this.deps.apiBaseUrl}/config`, {
+        headers: {
+          'x-scalebun-client-key': this.deps.clientKey,
+          ...(version ? { 'If-None-Match': `"${version}"` } : {}),
+        },
+      });
+      this.lastFetch = Date.now();
+      if (res.status === 304) return; // unchanged — keep cache
+      if (!res.ok) return; // keep cache / defaults
+      const payload = (await res.json()) as SdkConfigPayload;
+      if (payload && Array.isArray(payload.flags) && Array.isArray(payload.experiments)) {
+        this.payload = payload;
+        try {
+          this.storage.set(K_CONFIG, JSON.stringify(payload));
+          if (payload.version) this.storage.set(K_CONFIG_VERSION, payload.version);
+        } catch { /* no-throw */ }
+      }
+    } catch (err) {
+      logger.warn(`[ScaleBun.config] refresh failed: ${(err as Error)?.message}`);
+    }
+  }
+
+  /** Refresh if the TTL has elapsed (call on app-foreground). Fire-and-forget. */
+  maybeRefresh(): void {
+    if (Date.now() - this.lastFetch > DEFAULT_TTL_MS) this.refresh().catch(() => {});
+  }
+
+  // ── resolution (all local + non-throwing) ──────────────────────────────────
+  isEnabled(key: string): boolean {
+    return this.payload.flags.find((f) => f.key === key)?.enabled ?? false;
+  }
+
+  get<T = any>(key: string, fallback: T): T {
+    const e = this.payload.remoteConfig.find((r) => r.key === key);
+    return e ? coerce(e.value, e.type, fallback) : fallback;
+  }
+
+  rolloutIsOn(key: string): boolean {
+    const r = this.payload.rollouts.find((x) => x.key === key);
+    return r ? bucketOf(this.deps.installationId, r.salt) < r.percentage : false;
+  }
+
+  /**
+   * Whether the org is entitled to a SDK-suppressible feature. Fail-OPEN: an
+   * absent/unknown entitlement (e.g. before the first /config) returns true so we
+   * never wrongly disable a paying customer. The server is the real gate.
+   */
+  isFeatureEntitled(feature: string): boolean {
+    const e = this.payload.entitlements as Record<string, boolean> | undefined;
+    return e?.[feature] ?? true;
+  }
+
+  /**
+   * Read the cached config's entitlements synchronously WITHOUT a full
+   * ConfigManager (which needs the EventTracker, created during bootstrap). Lets
+   * the facade suppress closed-feature collectors at bootstrap time on any run
+   * after the first. Returns {} when no cache exists (→ fail-open).
+   */
+  static readCachedEntitlements(): Record<string, boolean> {
+    try {
+      const storage = createStorageBackend();
+      const raw = storage.get(K_CONFIG);
+      if (!raw) return {};
+      const parsed = JSON.parse(raw) as SdkConfigPayload;
+      return (parsed?.entitlements as Record<string, boolean>) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  variant(key: string): string | null {
+    const exp = this.payload.experiments.find((e) => e.key === key);
+    if (!exp) return null;
+    const v = pickVariant(this.deps.installationId, exp.salt, exp.variants);
+    if (!v) return null;
+    // Log exposure exactly once per (install, experiment).
+    if (!this.exposed.has(key)) {
+      this.exposed.add(key);
+      this.persistExposed();
+      try { this.deps.emitExposure(key, v); } catch { /* no-throw */ }
+    }
+    // Stamp the assignment onto subsequent events for downstream slicing.
+    try { this.deps.stamp(`experiment_${key}`, v); } catch { /* no-throw */ }
+    return v;
+  }
+
+  // ── persistence ─────────────────────────────────────────────────────────────
+  private loadCached(): void {
+    try {
+      const raw = this.storage.get(K_CONFIG);
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.flags)) this.payload = parsed;
+      }
+    } catch { this.payload = EMPTY_CONFIG; }
+  }
+
+  private loadExposed(): void {
+    try {
+      const raw = this.storage.get(K_EXPOSED);
+      if (raw) { const a = JSON.parse(raw); if (Array.isArray(a)) this.exposed = new Set(a); }
+    } catch { /* no-throw */ }
+  }
+
+  private persistExposed(): void {
+    try { this.storage.set(K_EXPOSED, JSON.stringify([...this.exposed])); } catch { /* no-throw */ }
+  }
+}