@nexussdk/flags 0.0.1

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/evaluator.ts","../src/sse-manager.ts","../src/storage.ts","../src/client.ts"],"names":["murmur3","key","seed","h","c1","c2","i","length4","k","k2","rem","computeRolloutBucket","userId","flagKey","hashInput","compareSemver","a","b","partsA","partsB","diff","resolveAttribute","ctx","attributePath","parts","current","part","evaluateSingleRule","rule","userCtx","userValue","targets","evaluateFlag","flag","SSEManager","options","url","evt","data","event","delay","computeBackoffMs","STORAGE_KEY_PREFIX","ANON_ID_KEY","FlagStorage","apiKeyPrefix","result","flags","value","id","testKey","raw","parsed","NexusFlagsClient","resolveApiKey","resolveBaseUrl","defaultValue","cached","variantKey","user","callback","flagDef","cb","fetchWithRetry","evaluated"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @fileoverview MurmurHash3 32-bit implementation and ABAC rule evaluator.\n * Pure TypeScript — no external dependencies. Implements deterministic rollout bucketing.\n * @module @nexus/sdk-flags/evaluator\n */\n\nimport type { FeatureFlag, FlagEvaluationResult, TargetingRule, UserContext } from '@nexussdk/contracts';\n\n// ---------------------------------------------------------------------------\n// MurmurHash3 32-bit Implementation (Pure TypeScript)\n// Used for deterministic user-to-bucket mapping without server round-trips.\n// ---------------------------------------------------------------------------\n\n/**\n * Converts a string to a Uint32 MurmurHash3 hash.\n * Implements the MurmurHash3 32-bit algorithm (x86 variant).\n *\n * @param key - Input string to hash.\n * @param seed - Optional seed value. Defaults to 0.\n * @returns Unsigned 32-bit integer hash value.\n *\n * @example\n * const hash = murmur3('user123:checkout_v2', 0);\n * const bucket = hash % 100; // 0-99 deterministic bucket\n */\nexport function murmur3(key: string, seed = 0): number {\n  let h = seed >>> 0;\n  const c1 = 0xcc9e2d51;\n  const c2 = 0x1b873593;\n\n  let i = 0;\n  // Process 4-byte chunks\n  const length4 = Math.floor(key.length / 4) * 4;\n  while (i < length4) {\n    let k =\n      ((key.charCodeAt(i) & 0xff)) |\n      ((key.charCodeAt(i + 1) & 0xff) << 8) |\n      ((key.charCodeAt(i + 2) & 0xff) << 16) |\n      ((key.charCodeAt(i + 3) & 0xff) << 24);\n\n    k = Math.imul(k, c1);\n    k = (k << 15) | (k >>> 17);\n    k = Math.imul(k, c2);\n\n    h ^= k;\n    h = (h << 13) | (h >>> 19);\n    h = (Math.imul(h, 5) + 0xe6546b64) >>> 0;\n    i += 4;\n  }\n\n  // Process remaining bytes\n  let k2 = 0;\n  const rem = key.length & 3;\n  if (rem >= 3) k2 ^= (key.charCodeAt(i + 2) & 0xff) << 16;\n  if (rem >= 2) k2 ^= (key.charCodeAt(i + 1) & 0xff) << 8;\n  if (rem >= 1) {\n    k2 ^= key.charCodeAt(i) & 0xff;\n    k2 = Math.imul(k2, c1);\n    k2 = (k2 << 15) | (k2 >>> 17);\n    k2 = Math.imul(k2, c2);\n    h ^= k2;\n  }\n\n  // Finalization mix\n  h ^= key.length;\n  h ^= h >>> 16;\n  h = Math.imul(h, 0x85ebca6b);\n  h ^= h >>> 13;\n  h = Math.imul(h, 0xc2b2ae35);\n  h ^= h >>> 16;\n\n  return h >>> 0; // Ensure unsigned\n}\n\n/**\n * Computes the deterministic rollout bucket (0-99) for a given user+flag combination.\n * Uses MurmurHash3 for even distribution without server state.\n *\n * @param userId - User's unique identifier (anonymous ID if not authenticated).\n * @param flagKey - Flag programmatic key.\n * @returns Bucket value between 0 and 99 (inclusive).\n *\n * @example\n * const bucket = computeRolloutBucket('usr_12345', 'checkout_v2');\n * // isEnabled = bucket < flag.rolloutPercentage\n */\nexport function computeRolloutBucket(userId: string, flagKey: string): number {\n  const hashInput = `${userId}:${flagKey}`;\n  return murmur3(hashInput) % 100;\n}\n\n// ---------------------------------------------------------------------------\n// ABAC Rule Evaluator\n// ---------------------------------------------------------------------------\n\n/**\n * Performs a simple semantic version comparison.\n * Compares two semver strings in \"MAJOR.MINOR.PATCH\" format.\n *\n * @param a - First version string.\n * @param b - Second version string.\n * @returns Positive if a > b, negative if a < b, 0 if equal.\n */\nfunction compareSemver(a: string, b: string): number {\n  const partsA = a.replace(/^v/, '').split('.').map(Number);\n  const partsB = b.replace(/^v/, '').split('.').map(Number);\n  for (let i = 0; i < 3; i++) {\n    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);\n    if (diff !== 0) return diff;\n  }\n  return 0;\n}\n\n/**\n * Extracts a nested attribute value from the UserContext by dot-notation path.\n *\n * @param ctx - UserContext object.\n * @param attributePath - Dot-separated path (e.g. \"custom.tier\", \"country\").\n * @returns The attribute value or `undefined` if not found.\n */\nfunction resolveAttribute(ctx: UserContext, attributePath: string): unknown {\n  const parts = attributePath.split('.');\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  let current: any = ctx;\n  for (const part of parts) {\n    if (current == null || typeof current !== 'object') return undefined;\n    current = current[part];\n  }\n  return current;\n}\n\n/**\n * Evaluates a single targeting rule against the user context.\n *\n * @param rule - The ABAC targeting rule to evaluate.\n * @param userCtx - The current user context.\n * @returns `true` if the rule passes for this user.\n */\nfunction evaluateSingleRule(rule: TargetingRule, userCtx: UserContext): boolean {\n  const userValue = resolveAttribute(userCtx, rule.attribute);\n  const targets = rule.values;\n\n  switch (rule.operator) {\n    case 'EQUALS':\n      return userValue === targets[0];\n    case 'NOT_EQUALS':\n      return userValue !== targets[0];\n    case 'IN':\n      return targets.includes(userValue as string | number | boolean);\n    case 'NOT_IN':\n      return !targets.includes(userValue as string | number | boolean);\n    case 'CONTAINS':\n      return typeof userValue === 'string' && userValue.includes(String(targets[0]));\n    case 'NOT_CONTAINS':\n      return typeof userValue === 'string' && !userValue.includes(String(targets[0]));\n    case 'STARTS_WITH':\n      return typeof userValue === 'string' && userValue.startsWith(String(targets[0]));\n    case 'ENDS_WITH':\n      return typeof userValue === 'string' && userValue.endsWith(String(targets[0]));\n    case 'GREATER_THAN':\n      return typeof userValue === 'number' && userValue > Number(targets[0]);\n    case 'LESS_THAN':\n      return typeof userValue === 'number' && userValue < Number(targets[0]);\n    case 'SEMVER_GTE':\n      return (\n        typeof userValue === 'string' &&\n        typeof targets[0] === 'string' &&\n        compareSemver(userValue, String(targets[0])) >= 0\n      );\n    case 'SEMVER_LTE':\n      return (\n        typeof userValue === 'string' &&\n        typeof targets[0] === 'string' &&\n        compareSemver(userValue, String(targets[0])) <= 0\n      );\n    default:\n      return false;\n  }\n}\n\n/**\n * Evaluates a FeatureFlag against a UserContext using the full ABAC + rollout engine.\n *\n * Evaluation Order:\n * 1. Kill-switch check (`isEnabled === false` → KILL_SWITCH)\n * 2. All targeting rules must pass (ABAC evaluation)\n * 3. Percentage rollout via MurmurHash3 bucketing\n * 4. Default enabled state\n *\n * @param flag - The feature flag definition from the cache.\n * @param userCtx - Current user context for targeting evaluation.\n * @returns Full {@link FlagEvaluationResult} with reason explanation.\n *\n * @example\n * const result = evaluateFlag(flag, { id: 'usr_12345', country: 'VN' });\n * if (result.enabled) {\n *   console.log(result.variants.discount_rate); // 20\n * }\n */\nexport function evaluateFlag(flag: FeatureFlag, userCtx: UserContext): FlagEvaluationResult {\n  // Step 1: Kill-switch\n  if (!flag.isEnabled) {\n    return {\n      key: flag.key,\n      enabled: false,\n      variants: {},\n      reason: 'KILL_SWITCH',\n      version: flag.version,\n    };\n  }\n\n  // Step 2: ABAC targeting rules — all must pass (AND logic)\n  if (flag.targetingRules.length > 0) {\n    const allRulesPass = flag.targetingRules.every((rule) =>\n      evaluateSingleRule(rule, userCtx),\n    );\n    if (!allRulesPass) {\n      return {\n        key: flag.key,\n        enabled: false,\n        variants: {},\n        reason: 'FALLBACK',\n        version: flag.version,\n      };\n    }\n    // All targeting rules matched\n    if (flag.rolloutPercentage >= 100) {\n      return {\n        key: flag.key,\n        enabled: true,\n        variants: flag.variants,\n        reason: 'TARGETING_MATCH',\n        version: flag.version,\n      };\n    }\n  }\n\n  // Step 3: Percentage rollout (MurmurHash3)\n  if (flag.rolloutPercentage > 0) {\n    const userId = userCtx.id ?? 'anon';\n    const bucket = computeRolloutBucket(userId, flag.key);\n    if (bucket < flag.rolloutPercentage) {\n      return {\n        key: flag.key,\n        enabled: true,\n        variants: flag.variants,\n        reason: flag.targetingRules.length > 0 ? 'TARGETING_MATCH' : 'ROLLOUT_MATCH',\n        version: flag.version,\n      };\n    }\n    return {\n      key: flag.key,\n      enabled: false,\n      variants: {},\n      reason: 'FALLBACK',\n      version: flag.version,\n    };\n  }\n\n  // Step 4: Full kill-switch off (rolloutPercentage === 0 with no rules)\n  return {\n    key: flag.key,\n    enabled: false,\n    variants: {},\n    reason: 'KILL_SWITCH',\n    version: flag.version,\n  };\n}\n","/**\n * @fileoverview Singleton SSE Manager with ref-counting and auto-reconnect.\n * Ensures exactly one EventSource connection per API key across all flag subscribers.\n * @module @nexus/sdk-flags/sse-manager\n */\n\nimport type { FlagStreamEvent } from '@nexussdk/contracts';\nimport { computeBackoffMs } from '@nexussdk/core';\n\n/**\n * Options for creating an SSE connection.\n */\nexport interface SSEManagerOptions {\n  /** Full SSE stream URL (e.g. \"http://localhost:8080/api/v1/flags/stream\"). */\n  url: string;\n  /** Public API key for authentication. */\n  apiKey: string;\n  /** Callback invoked for each received flag stream event. */\n  onEvent: (event: FlagStreamEvent) => void;\n  /** Callback invoked on connection state changes (optional). */\n  onStateChange?: (connected: boolean) => void;\n  /** Maximum reconnect attempts. Defaults to Infinity. */\n  maxReconnects?: number;\n}\n\n/**\n * Ref-counted Singleton SSE Manager.\n *\n * Multiple consumers sharing the same `apiKey` receive updates\n * from a single shared SSE connection. Connection is torn down when all\n * consumers have called `disconnect()`.\n *\n * Connection lifecycle:\n * 1. `connect()` → opens EventSource or streaming fetch\n * 2. On disconnect: exponential backoff reconnect (max 30s)\n * 3. `disconnect()` → decrements ref count; tears down on 0\n *\n * @example\n * const manager = new SSEManager({\n *   url: 'http://localhost:8080/api/v1/flags/stream',\n *   apiKey: 'pk_live_...',\n *   onEvent: (event) => updateCache(event),\n * });\n * manager.connect();\n * // Later:\n * manager.disconnect();\n */\nexport class SSEManager {\n  private readonly options: SSEManagerOptions;\n  private eventSource: EventSource | null = null;\n  private connected = false;\n  private destroyed = false;\n  private reconnectAttempt = 0;\n  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;\n  private readonly maxReconnects: number;\n\n  constructor(options: SSEManagerOptions) {\n    this.options = options;\n    this.maxReconnects = options.maxReconnects ?? Infinity;\n  }\n\n  /**\n   * Returns whether the SSE connection is currently active.\n   *\n   * @returns `true` if EventSource is open and receiving events.\n   */\n  get isConnected(): boolean {\n    return this.connected;\n  }\n\n  /**\n   * Opens the SSE connection to the Go-Gin stream endpoint.\n   * Safe to call multiple times — no-op if already connected.\n   *\n   * @example\n   * manager.connect();\n   */\n  connect(): void {\n    if (this.destroyed || this.connected || this.eventSource) return;\n    this.openConnection();\n  }\n\n  /**\n   * Closes the SSE connection and cancels any pending reconnect timers.\n   *\n   * @example\n   * manager.disconnect();\n   */\n  disconnect(): void {\n    this.destroyed = true;\n    this.cleanup();\n  }\n\n  private openConnection(): void {\n    if (this.destroyed) return;\n\n    try {\n      // Append API key as query parameter for SSE (EventSource doesn't support custom headers)\n      const url = new URL(this.options.url);\n      url.searchParams.set('apiKey', this.options.apiKey);\n\n      this.eventSource = new EventSource(url.toString());\n\n      this.eventSource.addEventListener('open', () => {\n        this.connected = true;\n        this.reconnectAttempt = 0;\n        this.options.onStateChange?.(true);\n      });\n\n      this.eventSource.addEventListener('message', (evt: MessageEvent<string>) => {\n        this.handleMessage(evt.data);\n      });\n\n      // Go-Gin sends events with event type 'message' by default\n      // Also listen for explicitly typed events\n      this.eventSource.addEventListener('flag_update', (evt: MessageEvent<string>) => {\n        this.handleMessage(evt.data);\n      });\n\n      this.eventSource.addEventListener('error', () => {\n        this.connected = false;\n        this.options.onStateChange?.(false);\n        this.cleanup();\n        this.scheduleReconnect();\n      });\n    } catch {\n      this.scheduleReconnect();\n    }\n  }\n\n  private handleMessage(data: string): void {\n    try {\n      const event = JSON.parse(data) as FlagStreamEvent;\n      this.options.onEvent(event);\n    } catch {\n      // Ignore malformed SSE payloads — never crash the host application\n    }\n  }\n\n  private cleanup(): void {\n    if (this.eventSource) {\n      this.eventSource.close();\n      this.eventSource = null;\n    }\n    if (this.reconnectTimer !== null) {\n      clearTimeout(this.reconnectTimer);\n      this.reconnectTimer = null;\n    }\n  }\n\n  private scheduleReconnect(): void {\n    if (this.destroyed) return;\n    if (this.reconnectAttempt >= this.maxReconnects) return;\n\n    const delay = computeBackoffMs(this.reconnectAttempt, 1000, 30_000);\n    this.reconnectAttempt++;\n\n    this.reconnectTimer = setTimeout(() => {\n      this.reconnectTimer = null;\n      if (!this.destroyed) {\n        this.openConnection();\n      }\n    }, delay);\n  }\n}\n","/**\n * @fileoverview In-memory flag storage with LocalStorage sync and incognito fallback.\n * @module @nexus/sdk-flags/storage\n */\n\nimport type { FlagEvaluationResult } from '@nexussdk/contracts';\n\nconst STORAGE_KEY_PREFIX = 'nexus_flags_';\nconst ANON_ID_KEY = 'nexus_anon_id';\n\n/**\n * In-memory flag cache with optional LocalStorage persistence.\n * Falls back to pure in-memory storage in SSR / Incognito / Worker contexts.\n *\n * @example\n * const store = new FlagStorage('pk_live_abc123');\n * store.set('checkout_v2', { key: 'checkout_v2', enabled: true, variants: {}, reason: 'ROLLOUT_MATCH', version: 3 });\n * const result = store.get('checkout_v2');\n */\nexport class FlagStorage {\n  private readonly memory = new Map<string, FlagEvaluationResult>();\n  private readonly storageKey: string;\n  private readonly localStorageAvailable: boolean;\n  private broadcastChannel: BroadcastChannel | null = null;\n\n  constructor(apiKeyPrefix: string) {\n    this.storageKey = `${STORAGE_KEY_PREFIX}${apiKeyPrefix}`;\n    this.localStorageAvailable = this.testLocalStorage();\n    this.hydrate();\n    this.setupBroadcastChannel();\n  }\n\n  /**\n   * Stores a flag evaluation result in memory (and localStorage if available).\n   *\n   * @param key - Flag programmatic key.\n   * @param result - Evaluation result to persist.\n   */\n  set(key: string, result: FlagEvaluationResult): void {\n    this.memory.set(key, result);\n    this.persist();\n    this.broadcastUpdate(key, result);\n  }\n\n  /**\n   * Retrieves a flag evaluation result by key.\n   *\n   * @param key - Flag programmatic key.\n   * @returns The cached evaluation result or `undefined`.\n   */\n  get(key: string): FlagEvaluationResult | undefined {\n    return this.memory.get(key);\n  }\n\n  /**\n   * Bulk-sets multiple flag results (e.g. after a batch fetch).\n   *\n   * @param flags - Record of flag key → evaluation result.\n   */\n  setAll(flags: Record<string, FlagEvaluationResult>): void {\n    for (const [key, value] of Object.entries(flags)) {\n      this.memory.set(key, value);\n    }\n    this.persist();\n  }\n\n  /**\n   * Removes a single flag from storage (e.g. on FLAG_DELETE SSE event).\n   *\n   * @param key - Flag programmatic key.\n   */\n  delete(key: string): void {\n    this.memory.delete(key);\n    this.persist();\n  }\n\n  /**\n   * Returns all cached flag results.\n   *\n   * @returns All stored flag results as a record.\n   */\n  getAll(): Record<string, FlagEvaluationResult> {\n    return Object.fromEntries(this.memory.entries());\n  }\n\n  /**\n   * Clears all cached flags from memory and localStorage.\n   */\n  clear(): void {\n    this.memory.clear();\n    if (this.localStorageAvailable) {\n      try {\n        window.localStorage.removeItem(this.storageKey);\n      } catch {\n        // Storage access denied\n      }\n    }\n    this.broadcastChannel?.close();\n  }\n\n  /**\n   * Retrieves or creates a persistent anonymous user ID.\n   *\n   * @returns Anonymous ID string (e.g. \"anon_xyz123abc\").\n   */\n  getOrCreateAnonymousId(): string {\n    if (typeof window === 'undefined') return 'anon-ssr-node';\n\n    if (this.localStorageAvailable) {\n      try {\n        let id = window.localStorage.getItem(ANON_ID_KEY);\n        if (!id) {\n          id = `anon_${Math.random().toString(36).substring(2, 11)}`;\n          window.localStorage.setItem(ANON_ID_KEY, id);\n        }\n        return id;\n      } catch {\n        // Incognito / locked storage\n      }\n    }\n\n    return `anon_${Math.random().toString(36).substring(2, 11)}`;\n  }\n\n  private testLocalStorage(): boolean {\n    try {\n      if (typeof window === 'undefined') return false;\n      const testKey = '__nexus_test__';\n      window.localStorage.setItem(testKey, '1');\n      window.localStorage.removeItem(testKey);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  private hydrate(): void {\n    if (!this.localStorageAvailable) return;\n    try {\n      const raw = window.localStorage.getItem(this.storageKey);\n      if (raw) {\n        const parsed = JSON.parse(raw) as Record<string, FlagEvaluationResult>;\n        for (const [key, value] of Object.entries(parsed)) {\n          this.memory.set(key, value);\n        }\n      }\n    } catch {\n      // Corrupt storage — start fresh\n    }\n  }\n\n  private persist(): void {\n    if (!this.localStorageAvailable) return;\n    try {\n      window.localStorage.setItem(\n        this.storageKey,\n        JSON.stringify(Object.fromEntries(this.memory.entries())),\n      );\n    } catch {\n      // Storage quota exceeded — in-memory only\n    }\n  }\n\n  private setupBroadcastChannel(): void {\n    try {\n      if (typeof BroadcastChannel !== 'undefined') {\n        this.broadcastChannel = new BroadcastChannel(`nexus_flags_${this.storageKey}`);\n        this.broadcastChannel.onmessage = (evt: MessageEvent<{ key: string; result: FlagEvaluationResult }>) => {\n          // Sync updates from other tabs into local memory cache\n          if (evt.data?.key && evt.data?.result) {\n            this.memory.set(evt.data.key, evt.data.result);\n          }\n        };\n      }\n    } catch {\n      // BroadcastChannel unavailable (e.g. Worker context)\n    }\n  }\n\n  private broadcastUpdate(key: string, result: FlagEvaluationResult): void {\n    try {\n      this.broadcastChannel?.postMessage({ key, result });\n    } catch {\n      // Broadcast failed — no-op\n    }\n  }\n}\n","/**\n * @fileoverview NexusFlagsClient — Full-featured feature flags SDK client.\n * In-memory evaluation, SSE real-time sync, ABAC targeting, and MurmurHash3 rollout.\n * @module @nexus/sdk-flags/client\n */\n\nimport type {\n  FlagEvaluationResult,\n  FlagVariants,\n  FeatureFlag,\n  UserContext,\n} from '@nexussdk/contracts';\nimport { resolveApiKey, resolveBaseUrl, fetchWithRetry } from '@nexussdk/core';\nimport { evaluateFlag } from './evaluator.js';\nimport { SSEManager } from './sse-manager.js';\nimport { FlagStorage } from './storage.js';\n\n/**\n * Options for initializing the NexusFlagsClient.\n *\n * @example\n * const client = new NexusFlagsClient({\n *   apiKey: 'pk_live_...',\n *   baseUrl: 'http://localhost:8080',\n *   user: { id: 'usr_12345', country: 'VN' },\n *   realtime: true,\n * });\n */\nexport interface NexusFlagsOptions {\n  /**\n   * Public API Key ('pk_live_...' or 'pk_test_...').\n   * If omitted, resolved automatically via env variables.\n   */\n  apiKey?: string;\n  /**\n   * Base ingestion URL. Defaults to 'https://api.nexus.dev'.\n   */\n  baseUrl?: string;\n  /**\n   * Initial user identity context for targeting and percentage rollouts.\n   */\n  user?: UserContext;\n  /**\n   * Pre-hydrated flags evaluated on the server (SSR) to prevent client-side UI flicker.\n   */\n  bootstrap?: Record<string, FlagEvaluationResult>;\n  /**\n   * Toggle real-time SSE updates. Defaults to true.\n   */\n  realtime?: boolean;\n  /**\n   * Network timeout in milliseconds for evaluation fetch. Defaults to 3000ms.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Public interface for the NexusFlagsClient.\n */\nexport interface INexusFlagsClient {\n  /**\n   * Synchronously checks if a flag is active for the current user.\n   *\n   * @param key - Unique flag identifier.\n   * @param defaultValue - Fallback returned if flag is absent or evaluating.\n   * @returns `true` if the flag is enabled.\n   *\n   * @example\n   * const showBanner = client.isEnabled('promo_banner_v2', false);\n   */\n  isEnabled(key: string, defaultValue?: boolean): boolean;\n\n  /**\n   * Synchronously retrieves a specific dynamic configuration variant.\n   *\n   * @param key - Unique flag identifier.\n   * @param variantKey - Property inside the variant object.\n   * @param defaultValue - Fallback returned if flag/variant is missing.\n   * @returns The variant value cast to type T.\n   *\n   * @example\n   * const rate = client.getVariant<number>('promo_banner_v2', 'discount_rate', 10);\n   */\n  getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T;\n\n  /**\n   * Updates current user context and re-evaluates all flags.\n   *\n   * @param user - New user context to apply.\n   * @returns Promise that resolves after flags are refreshed.\n   *\n   * @example\n   * await client.identify({ id: 'usr_99', country: 'SG' });\n   */\n  identify(user: UserContext): Promise<void>;\n\n  /**\n   * Resets user context to an anonymous persistent device identifier.\n   *\n   * @example\n   * client.reset(); // called on logout\n   */\n  reset(): void;\n\n  /**\n   * Subscribes to runtime flag changes triggered by SSE updates.\n   *\n   * @param key - Flag key to observe.\n   * @param callback - Called with new evaluation result when the flag changes.\n   * @returns Unsubscribe function — call to remove the listener.\n   *\n   * @example\n   * const unsub = client.onFlagChange('checkout_v2', (result) => {\n   *   setCheckoutEnabled(result.enabled);\n   * });\n   * // On component unmount:\n   * unsub();\n   */\n  onFlagChange(key: string, callback: (result: FlagEvaluationResult) => void): () => void;\n\n  /**\n   * Gracefully shuts down active SSE connections and observers.\n   *\n   * @example\n   * client.destroy();\n   */\n  destroy(): void;\n}\n\n/**\n * Feature Flags Client — the primary SDK entry point for flag evaluation.\n *\n * @implements {INexusFlagsClient}\n *\n * @example\n * const client = new NexusFlagsClient({ apiKey: 'pk_live_...' });\n * const enabled = client.isEnabled('new_checkout', false);\n */\nexport class NexusFlagsClient implements INexusFlagsClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly timeoutMs: number;\n  private user: UserContext;\n  private readonly storage: FlagStorage;\n  private readonly listeners = new Map<string, Set<(res: FlagEvaluationResult) => void>>();\n  private sseManager?: SSEManager;\n  private flagDefinitions = new Map<string, FeatureFlag>();\n\n  constructor(options: NexusFlagsOptions = {}) {\n    this.apiKey = resolveApiKey(options.apiKey);\n    this.baseUrl = resolveBaseUrl(options.baseUrl);\n    this.timeoutMs = options.timeoutMs ?? 3_000;\n    this.storage = new FlagStorage(this.apiKey.substring(0, 16));\n    this.user = options.user ?? { id: this.storage.getOrCreateAnonymousId() };\n\n    // Hydrate bootstrap flags (SSR pre-evaluation)\n    if (options.bootstrap) {\n      this.storage.setAll(options.bootstrap);\n    }\n\n    if (options.realtime !== false) {\n      this.initRealtimeSync();\n    }\n\n    // Prefetch flags asynchronously on init\n    void this.refreshFlags();\n  }\n\n  /**\n   * Evaluates whether a given feature flag is enabled for the current context.\n   */\n  public isEnabled(key: string, defaultValue = false): boolean {\n    const cached = this.storage.get(key);\n    return cached !== undefined ? cached.enabled : defaultValue;\n  }\n\n  /**\n   * Retrieves a typed variant configuration for an active feature flag.\n   */\n  public getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T {\n    const cached = this.storage.get(key);\n    if (!cached?.enabled || !cached.variants) {\n      return defaultValue as T;\n    }\n    const value = (cached.variants as FlagVariants)[variantKey];\n    return value !== undefined ? (value as T) : (defaultValue as T);\n  }\n\n  /**\n   * Identifies an authenticated user and triggers a flag evaluation refresh.\n   */\n  public async identify(user: UserContext): Promise<void> {\n    this.user = { ...this.user, ...user };\n    await this.refreshFlags();\n  }\n\n  /**\n   * Resets the active user context to a new anonymous identifier.\n   */\n  public reset(): void {\n    this.user = { id: this.storage.getOrCreateAnonymousId() };\n    void this.refreshFlags();\n  }\n\n  /**\n   * Registers a listener callback invoked when a flag's evaluation state changes.\n   */\n  public onFlagChange(key: string, callback: (result: FlagEvaluationResult) => void): () => void {\n    if (!this.listeners.has(key)) {\n      this.listeners.set(key, new Set());\n    }\n    this.listeners.get(key)!.add(callback);\n    return () => this.listeners.get(key)?.delete(callback);\n  }\n\n  /**\n   * Destroys the client, terminating SSE connections and clearing listeners.\n   */\n  public destroy(): void {\n    this.sseManager?.disconnect();\n    this.listeners.clear();\n    this.storage.clear();\n  }\n\n  private initRealtimeSync(): void {\n    this.sseManager = new SSEManager({\n      url: `${this.baseUrl}/api/v1/flags/stream`,\n      apiKey: this.apiKey,\n      onEvent: (event) => {\n        if (event.type === 'FLAG_UPDATE' && event.data) {\n          // Use locally evaluated result if we have the flag definition\n          const flagDef = this.flagDefinitions.get(event.key);\n          const result = flagDef\n            ? evaluateFlag(flagDef, this.user)\n            : event.data;\n\n          this.storage.set(event.key, result);\n          this.listeners.get(event.key)?.forEach((cb) => cb(result));\n        } else if (event.type === 'FLAG_DELETE') {\n          this.storage.delete(event.key);\n          this.flagDefinitions.delete(event.key);\n        }\n      },\n    });\n    this.sseManager.connect();\n  }\n\n  private async refreshFlags(): Promise<void> {\n    try {\n      const result = await fetchWithRetry<Record<string, FeatureFlag>>({\n        url: `${this.baseUrl}/api/v1/flags/eval`,\n        method: 'GET',\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'X-Nexus-User-Id': this.user.id ?? 'anon',\n          'X-Nexus-Country': this.user.country ?? '',\n        },\n        timeoutMs: this.timeoutMs,\n        maxRetries: 2,\n      });\n\n      for (const [key, flag] of Object.entries(result.data)) {\n        this.flagDefinitions.set(key, flag);\n        const evaluated = evaluateFlag(flag, this.user);\n        this.storage.set(key, evaluated);\n        this.listeners.get(key)?.forEach((cb) => cb(evaluated));\n      }\n    } catch {\n      // Offline fallback: retain existing in-memory cache silently\n      // Never throw from a background refresh — host app must not be affected\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nexussdk/flags",
+  "version": "0.0.1",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Ultra-lightweight feature flags and remote config client SDK for browsers and edge runtimes",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@nexussdk/contracts": "0.0.1",
+    "@nexussdk/core": "0.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "rimraf": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}

package/src/client.ts

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview NexusFlagsClient — Full-featured feature flags SDK client.
+ * In-memory evaluation, SSE real-time sync, ABAC targeting, and MurmurHash3 rollout.
+ * @module @nexus/sdk-flags/client
+ */
+
+import type {
+  FlagEvaluationResult,
+  FlagVariants,
+  FeatureFlag,
+  UserContext,
+} from '@nexussdk/contracts';
+import { resolveApiKey, resolveBaseUrl, fetchWithRetry } from '@nexussdk/core';
+import { evaluateFlag } from './evaluator.js';
+import { SSEManager } from './sse-manager.js';
+import { FlagStorage } from './storage.js';
+
+/**
+ * Options for initializing the NexusFlagsClient.
+ *
+ * @example
+ * const client = new NexusFlagsClient({
+ *   apiKey: 'pk_live_...',
+ *   baseUrl: 'http://localhost:8080',
+ *   user: { id: 'usr_12345', country: 'VN' },
+ *   realtime: true,
+ * });
+ */
+export interface NexusFlagsOptions {
+  /**
+   * Public API Key ('pk_live_...' or 'pk_test_...').
+   * If omitted, resolved automatically via env variables.
+   */
+  apiKey?: string;
+  /**
+   * Base ingestion URL. Defaults to 'https://api.nexus.dev'.
+   */
+  baseUrl?: string;
+  /**
+   * Initial user identity context for targeting and percentage rollouts.
+   */
+  user?: UserContext;
+  /**
+   * Pre-hydrated flags evaluated on the server (SSR) to prevent client-side UI flicker.
+   */
+  bootstrap?: Record<string, FlagEvaluationResult>;
+  /**
+   * Toggle real-time SSE updates. Defaults to true.
+   */
+  realtime?: boolean;
+  /**
+   * Network timeout in milliseconds for evaluation fetch. Defaults to 3000ms.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Public interface for the NexusFlagsClient.
+ */
+export interface INexusFlagsClient {
+  /**
+   * Synchronously checks if a flag is active for the current user.
+   *
+   * @param key - Unique flag identifier.
+   * @param defaultValue - Fallback returned if flag is absent or evaluating.
+   * @returns `true` if the flag is enabled.
+   *
+   * @example
+   * const showBanner = client.isEnabled('promo_banner_v2', false);
+   */
+  isEnabled(key: string, defaultValue?: boolean): boolean;
+
+  /**
+   * Synchronously retrieves a specific dynamic configuration variant.
+   *
+   * @param key - Unique flag identifier.
+   * @param variantKey - Property inside the variant object.
+   * @param defaultValue - Fallback returned if flag/variant is missing.
+   * @returns The variant value cast to type T.
+   *
+   * @example
+   * const rate = client.getVariant<number>('promo_banner_v2', 'discount_rate', 10);
+   */
+  getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T;
+
+  /**
+   * Updates current user context and re-evaluates all flags.
+   *
+   * @param user - New user context to apply.
+   * @returns Promise that resolves after flags are refreshed.
+   *
+   * @example
+   * await client.identify({ id: 'usr_99', country: 'SG' });
+   */
+  identify(user: UserContext): Promise<void>;
+
+  /**
+   * Resets user context to an anonymous persistent device identifier.
+   *
+   * @example
+   * client.reset(); // called on logout
+   */
+  reset(): void;
+
+  /**
+   * Subscribes to runtime flag changes triggered by SSE updates.
+   *
+   * @param key - Flag key to observe.
+   * @param callback - Called with new evaluation result when the flag changes.
+   * @returns Unsubscribe function — call to remove the listener.
+   *
+   * @example
+   * const unsub = client.onFlagChange('checkout_v2', (result) => {
+   *   setCheckoutEnabled(result.enabled);
+   * });
+   * // On component unmount:
+   * unsub();
+   */
+  onFlagChange(key: string, callback: (result: FlagEvaluationResult) => void): () => void;
+
+  /**
+   * Gracefully shuts down active SSE connections and observers.
+   *
+   * @example
+   * client.destroy();
+   */
+  destroy(): void;
+}
+
+/**
+ * Feature Flags Client — the primary SDK entry point for flag evaluation.
+ *
+ * @implements {INexusFlagsClient}
+ *
+ * @example
+ * const client = new NexusFlagsClient({ apiKey: 'pk_live_...' });
+ * const enabled = client.isEnabled('new_checkout', false);
+ */
+export class NexusFlagsClient implements INexusFlagsClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private user: UserContext;
+  private readonly storage: FlagStorage;
+  private readonly listeners = new Map<string, Set<(res: FlagEvaluationResult) => void>>();
+  private sseManager?: SSEManager;
+  private flagDefinitions = new Map<string, FeatureFlag>();
+
+  constructor(options: NexusFlagsOptions = {}) {
+    this.apiKey = resolveApiKey(options.apiKey);
+    this.baseUrl = resolveBaseUrl(options.baseUrl);
+    this.timeoutMs = options.timeoutMs ?? 3_000;
+    this.storage = new FlagStorage(this.apiKey.substring(0, 16));
+    this.user = options.user ?? { id: this.storage.getOrCreateAnonymousId() };
+
+    // Hydrate bootstrap flags (SSR pre-evaluation)
+    if (options.bootstrap) {
+      this.storage.setAll(options.bootstrap);
+    }
+
+    if (options.realtime !== false) {
+      this.initRealtimeSync();
+    }
+
+    // Prefetch flags asynchronously on init
+    void this.refreshFlags();
+  }
+
+  /**
+   * Evaluates whether a given feature flag is enabled for the current context.
+   */
+  public isEnabled(key: string, defaultValue = false): boolean {
+    const cached = this.storage.get(key);
+    return cached !== undefined ? cached.enabled : defaultValue;
+  }
+
+  /**
+   * Retrieves a typed variant configuration for an active feature flag.
+   */
+  public getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T {
+    const cached = this.storage.get(key);
+    if (!cached?.enabled || !cached.variants) {
+      return defaultValue as T;
+    }
+    const value = (cached.variants as FlagVariants)[variantKey];
+    return value !== undefined ? (value as T) : (defaultValue as T);
+  }
+
+  /**
+   * Identifies an authenticated user and triggers a flag evaluation refresh.
+   */
+  public async identify(user: UserContext): Promise<void> {
+    this.user = { ...this.user, ...user };
+    await this.refreshFlags();
+  }
+
+  /**
+   * Resets the active user context to a new anonymous identifier.
+   */
+  public reset(): void {
+    this.user = { id: this.storage.getOrCreateAnonymousId() };
+    void this.refreshFlags();
+  }
+
+  /**
+   * Registers a listener callback invoked when a flag's evaluation state changes.
+   */
+  public onFlagChange(key: string, callback: (result: FlagEvaluationResult) => void): () => void {
+    if (!this.listeners.has(key)) {
+      this.listeners.set(key, new Set());
+    }
+    this.listeners.get(key)!.add(callback);
+    return () => this.listeners.get(key)?.delete(callback);
+  }
+
+  /**
+   * Destroys the client, terminating SSE connections and clearing listeners.
+   */
+  public destroy(): void {
+    this.sseManager?.disconnect();
+    this.listeners.clear();
+    this.storage.clear();
+  }
+
+  private initRealtimeSync(): void {
+    this.sseManager = new SSEManager({
+      url: `${this.baseUrl}/api/v1/flags/stream`,
+      apiKey: this.apiKey,
+      onEvent: (event) => {
+        if (event.type === 'FLAG_UPDATE' && event.data) {
+          // Use locally evaluated result if we have the flag definition
+          const flagDef = this.flagDefinitions.get(event.key);
+          const result = flagDef
+            ? evaluateFlag(flagDef, this.user)
+            : event.data;
+
+          this.storage.set(event.key, result);
+          this.listeners.get(event.key)?.forEach((cb) => cb(result));
+        } else if (event.type === 'FLAG_DELETE') {
+          this.storage.delete(event.key);
+          this.flagDefinitions.delete(event.key);
+        }
+      },
+    });
+    this.sseManager.connect();
+  }
+
+  private async refreshFlags(): Promise<void> {
+    try {
+      const result = await fetchWithRetry<Record<string, FeatureFlag>>({
+        url: `${this.baseUrl}/api/v1/flags/eval`,
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          'X-Nexus-User-Id': this.user.id ?? 'anon',
+          'X-Nexus-Country': this.user.country ?? '',
+        },
+        timeoutMs: this.timeoutMs,
+        maxRetries: 2,
+      });
+
+      for (const [key, flag] of Object.entries(result.data)) {
+        this.flagDefinitions.set(key, flag);
+        const evaluated = evaluateFlag(flag, this.user);
+        this.storage.set(key, evaluated);
+        this.listeners.get(key)?.forEach((cb) => cb(evaluated));
+      }
+    } catch {
+      // Offline fallback: retain existing in-memory cache silently
+      // Never throw from a background refresh — host app must not be affected
+    }
+  }
+}

package/src/evaluator.ts

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview MurmurHash3 32-bit implementation and ABAC rule evaluator.
+ * Pure TypeScript — no external dependencies. Implements deterministic rollout bucketing.
+ * @module @nexus/sdk-flags/evaluator
+ */
+
+import type { FeatureFlag, FlagEvaluationResult, TargetingRule, UserContext } from '@nexussdk/contracts';
+
+// ---------------------------------------------------------------------------
+// MurmurHash3 32-bit Implementation (Pure TypeScript)
+// Used for deterministic user-to-bucket mapping without server round-trips.
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts a string to a Uint32 MurmurHash3 hash.
+ * Implements the MurmurHash3 32-bit algorithm (x86 variant).
+ *
+ * @param key - Input string to hash.
+ * @param seed - Optional seed value. Defaults to 0.
+ * @returns Unsigned 32-bit integer hash value.
+ *
+ * @example
+ * const hash = murmur3('user123:checkout_v2', 0);
+ * const bucket = hash % 100; // 0-99 deterministic bucket
+ */
+export function murmur3(key: string, seed = 0): number {
+  let h = seed >>> 0;
+  const c1 = 0xcc9e2d51;
+  const c2 = 0x1b873593;
+
+  let i = 0;
+  // Process 4-byte chunks
+  const length4 = Math.floor(key.length / 4) * 4;
+  while (i < length4) {
+    let k =
+      ((key.charCodeAt(i) & 0xff)) |
+      ((key.charCodeAt(i + 1) & 0xff) << 8) |
+      ((key.charCodeAt(i + 2) & 0xff) << 16) |
+      ((key.charCodeAt(i + 3) & 0xff) << 24);
+
+    k = Math.imul(k, c1);
+    k = (k << 15) | (k >>> 17);
+    k = Math.imul(k, c2);
+
+    h ^= k;
+    h = (h << 13) | (h >>> 19);
+    h = (Math.imul(h, 5) + 0xe6546b64) >>> 0;
+    i += 4;
+  }
+
+  // Process remaining bytes
+  let k2 = 0;
+  const rem = key.length & 3;
+  if (rem >= 3) k2 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+  if (rem >= 2) k2 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+  if (rem >= 1) {
+    k2 ^= key.charCodeAt(i) & 0xff;
+    k2 = Math.imul(k2, c1);
+    k2 = (k2 << 15) | (k2 >>> 17);
+    k2 = Math.imul(k2, c2);
+    h ^= k2;
+  }
+
+  // Finalization mix
+  h ^= key.length;
+  h ^= h >>> 16;
+  h = Math.imul(h, 0x85ebca6b);
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+
+  return h >>> 0; // Ensure unsigned
+}
+
+/**
+ * Computes the deterministic rollout bucket (0-99) for a given user+flag combination.
+ * Uses MurmurHash3 for even distribution without server state.
+ *
+ * @param userId - User's unique identifier (anonymous ID if not authenticated).
+ * @param flagKey - Flag programmatic key.
+ * @returns Bucket value between 0 and 99 (inclusive).
+ *
+ * @example
+ * const bucket = computeRolloutBucket('usr_12345', 'checkout_v2');
+ * // isEnabled = bucket < flag.rolloutPercentage
+ */
+export function computeRolloutBucket(userId: string, flagKey: string): number {
+  const hashInput = `${userId}:${flagKey}`;
+  return murmur3(hashInput) % 100;
+}
+
+// ---------------------------------------------------------------------------
+// ABAC Rule Evaluator
+// ---------------------------------------------------------------------------
+
+/**
+ * Performs a simple semantic version comparison.
+ * Compares two semver strings in "MAJOR.MINOR.PATCH" format.
+ *
+ * @param a - First version string.
+ * @param b - Second version string.
+ * @returns Positive if a > b, negative if a < b, 0 if equal.
+ */
+function compareSemver(a: string, b: string): number {
+  const partsA = a.replace(/^v/, '').split('.').map(Number);
+  const partsB = b.replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Extracts a nested attribute value from the UserContext by dot-notation path.
+ *
+ * @param ctx - UserContext object.
+ * @param attributePath - Dot-separated path (e.g. "custom.tier", "country").
+ * @returns The attribute value or `undefined` if not found.
+ */
+function resolveAttribute(ctx: UserContext, attributePath: string): unknown {
+  const parts = attributePath.split('.');
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: any = ctx;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Evaluates a single targeting rule against the user context.
+ *
+ * @param rule - The ABAC targeting rule to evaluate.
+ * @param userCtx - The current user context.
+ * @returns `true` if the rule passes for this user.
+ */
+function evaluateSingleRule(rule: TargetingRule, userCtx: UserContext): boolean {
+  const userValue = resolveAttribute(userCtx, rule.attribute);
+  const targets = rule.values;
+
+  switch (rule.operator) {
+    case 'EQUALS':
+      return userValue === targets[0];
+    case 'NOT_EQUALS':
+      return userValue !== targets[0];
+    case 'IN':
+      return targets.includes(userValue as string | number | boolean);
+    case 'NOT_IN':
+      return !targets.includes(userValue as string | number | boolean);
+    case 'CONTAINS':
+      return typeof userValue === 'string' && userValue.includes(String(targets[0]));
+    case 'NOT_CONTAINS':
+      return typeof userValue === 'string' && !userValue.includes(String(targets[0]));
+    case 'STARTS_WITH':
+      return typeof userValue === 'string' && userValue.startsWith(String(targets[0]));
+    case 'ENDS_WITH':
+      return typeof userValue === 'string' && userValue.endsWith(String(targets[0]));
+    case 'GREATER_THAN':
+      return typeof userValue === 'number' && userValue > Number(targets[0]);
+    case 'LESS_THAN':
+      return typeof userValue === 'number' && userValue < Number(targets[0]);
+    case 'SEMVER_GTE':
+      return (
+        typeof userValue === 'string' &&
+        typeof targets[0] === 'string' &&
+        compareSemver(userValue, String(targets[0])) >= 0
+      );
+    case 'SEMVER_LTE':
+      return (
+        typeof userValue === 'string' &&
+        typeof targets[0] === 'string' &&
+        compareSemver(userValue, String(targets[0])) <= 0
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Evaluates a FeatureFlag against a UserContext using the full ABAC + rollout engine.
+ *
+ * Evaluation Order:
+ * 1. Kill-switch check (`isEnabled === false` → KILL_SWITCH)
+ * 2. All targeting rules must pass (ABAC evaluation)
+ * 3. Percentage rollout via MurmurHash3 bucketing
+ * 4. Default enabled state
+ *
+ * @param flag - The feature flag definition from the cache.
+ * @param userCtx - Current user context for targeting evaluation.
+ * @returns Full {@link FlagEvaluationResult} with reason explanation.
+ *
+ * @example
+ * const result = evaluateFlag(flag, { id: 'usr_12345', country: 'VN' });
+ * if (result.enabled) {
+ *   console.log(result.variants.discount_rate); // 20
+ * }
+ */
+export function evaluateFlag(flag: FeatureFlag, userCtx: UserContext): FlagEvaluationResult {
+  // Step 1: Kill-switch
+  if (!flag.isEnabled) {
+    return {
+      key: flag.key,
+      enabled: false,
+      variants: {},
+      reason: 'KILL_SWITCH',
+      version: flag.version,
+    };
+  }
+
+  // Step 2: ABAC targeting rules — all must pass (AND logic)
+  if (flag.targetingRules.length > 0) {
+    const allRulesPass = flag.targetingRules.every((rule) =>
+      evaluateSingleRule(rule, userCtx),
+    );
+    if (!allRulesPass) {
+      return {
+        key: flag.key,
+        enabled: false,
+        variants: {},
+        reason: 'FALLBACK',
+        version: flag.version,
+      };
+    }
+    // All targeting rules matched
+    if (flag.rolloutPercentage >= 100) {
+      return {
+        key: flag.key,
+        enabled: true,
+        variants: flag.variants,
+        reason: 'TARGETING_MATCH',
+        version: flag.version,
+      };
+    }
+  }
+
+  // Step 3: Percentage rollout (MurmurHash3)
+  if (flag.rolloutPercentage > 0) {
+    const userId = userCtx.id ?? 'anon';
+    const bucket = computeRolloutBucket(userId, flag.key);
+    if (bucket < flag.rolloutPercentage) {
+      return {
+        key: flag.key,
+        enabled: true,
+        variants: flag.variants,
+        reason: flag.targetingRules.length > 0 ? 'TARGETING_MATCH' : 'ROLLOUT_MATCH',
+        version: flag.version,
+      };
+    }
+    return {
+      key: flag.key,
+      enabled: false,
+      variants: {},
+      reason: 'FALLBACK',
+      version: flag.version,
+    };
+  }
+
+  // Step 4: Full kill-switch off (rolloutPercentage === 0 with no rules)
+  return {
+    key: flag.key,
+    enabled: false,
+    variants: {},
+    reason: 'KILL_SWITCH',
+    version: flag.version,
+  };
+}