Experimentation & Feature Flags

const { enabled, variant } = useFlag("checkout-v2", {
  userId: user.id,
  tenantId: tenant.id,
  attributes: { plan: tenant.plan },
});

// Deterministic sticky bucketing — no network call, stable across devices.
// Same (key, unit) always lands in the same bucket, so a reload cannot reroll.
export function assign(
  flagKey: string,
  unitId: string,          // stable id: userId, or anonymousId for logged-out
  salt: string,            // bump to re-randomise (e.g. quarterly holdout reset)
  variants: { name: string; weight: number }[],
): string {
  const bucket = fnv1a(`${flagKey}:${salt}:${unitId}`) % 10_000; // 0–9999
  let cursor = 0;
  for (const v of variants) {
    cursor += v.weight * 100;            // weight expressed in percent
    if (bucket < cursor) return v.name;
  }
  return variants[0].name;               // control is always the safe default
}

// Exposure is logged only when the gate is actually rendered, never on page load —
// otherwise the denominator inflates and every experiment looks flat.
export function useGate(flagKey: string) {
  const variant = useFlagVariant(flagKey);
  useEffect(() => {
    analytics.track("exposure", { flagKey, variant, unit: "user" });
  }, [flagKey, variant]);
  return variant;
}

// Guardrail watcher: abort the rollout without waking anyone up.
const GUARDRAILS = [
  { metric: "client_error_rate", max_delta: 0.0005 },  // +0.05pp
  { metric: "inp_p75_ms",        max_delta: 25 },
  { metric: "checkout_conversion", min_delta: -0.01, requireSignificance: true },
];

export async function evaluateRing(flagKey: string, ring: Ring): Promise<Verdict> {
  const stats = await metrics.compare({ flagKey, since: ring.startedAt });
  for (const g of GUARDRAILS) {
    const s = stats[g.metric];
    const breached =
      (g.max_delta !== undefined && s.delta > g.max_delta) ||
      (g.min_delta !== undefined && s.delta < g.min_delta);
    if (breached && (!g.requireSignificance || s.pValue < 0.05)) {
      await flags.setRollout(flagKey, ring.previous);   // seconds, no deploy
      await pager.notify({ flagKey, metric: g.metric, delta: s.delta });
      return { action: "rolled_back", metric: g.metric };
    }
  }
  return stats.soakedFor >= ring.soakMs ? { action: "advance" } : { action: "hold" };
}

// Layered read: streamed value first, CDN snapshot second, safe default last.
export function killSwitch(key: string): boolean {
  const streamed = sdk.peek(key);                 // undefined if SDK not ready
  if (streamed !== undefined) return streamed;

  const snapshot = cdnConfig.get(key);            // polled every 60s, cached in memory
  if (snapshot !== undefined) return snapshot;

  return SAFE_DEFAULTS[key] ?? false;             // "off" for anything expensive
}

// Guard the import, not just the render — a killed feature should cost zero bytes.
if (!killSwitch("disable_recommendations")) {
  const { Recommendations } = await import("./Recommendations");
  mount(Recommendations);
}

// Codemod input: flag GA'd as permanently true.
// npx jscodeshift -t remove-flag.ts src --flag=checkout-v2 --value=true
- const { enabled } = useFlag("checkout-v2");
- return enabled ? <CheckoutV2 /> : <CheckoutLegacy />;
+ return <CheckoutV2 />;

// CI gate: fail the build on expired keys.
// flags.registry.json => { "checkout-v2": { owner: "payments", expires: "2026-09-01" } }
for (const [key, meta] of Object.entries(registry)) {
  if (Date.parse(meta.expires) < Date.now()) {
    fail(`Flag ${key} expired on ${meta.expires} (owner: ${meta.owner})`);
  }
}