@vercel/flags-core 1.1.0-cea788b-20260305194413 → 1.1.0

package/dist/{chunk-EB6T2UJ6.js → chunk-J33BA25D.js}

@@ -4,9 +4,10 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/client-fns.ts
-var client_fns_exports = {};
-__export(client_fns_exports, {
+// src/controller-fns.ts
+var controller_fns_exports = {};
+__export(controller_fns_exports, {
+  controllerInstanceMap: () => controllerInstanceMap,
   evaluate: () => evaluate2,
   getDatafile: () => getDatafile,
   getFallbackDatafile: () => getFallbackDatafile,
@@ -14,9 +15,6 @@ __export(client_fns_exports, {
   shutdown: () => shutdown
 });
 
-// src/client-map.ts
-var clientMap = /* @__PURE__ */ new Map();
-
 // src/evaluate.ts
 import { xxHash32 as hashInput } from "js-xxhash";
 
@@ -46,12 +44,11 @@ var Packed;
   })(AccessorType = Packed2.AccessorType || (Packed2.AccessorType = {}));
 })(Packed || (Packed = {}));
 
-// src/utils.ts
+// src/evaluate.ts
+var MAX_REGEX_INPUT_LENGTH = 1e4;
 function exhaustivenessCheck(_) {
   throw new Error("Exhaustiveness check failed");
 }
-
-// src/evaluate.ts
 function getProperty(obj, pathArray) {
   return pathArray.reduce((acc, key) => {
     if (acc && key in acc) {
@@ -96,10 +93,12 @@ var IGNORE_CASE_COMPARATORS = /* @__PURE__ */ new Set([
   "!contains" /* NOT_CONTAINS */
 ]);
 function matchTargetList(targets, params) {
-  for (const [kind, attributes] of Object.entries(targets)) {
-    for (const [attribute, values] of Object.entries(attributes)) {
+  for (const kind in targets) {
+    const attributes = targets[kind];
+    for (const attribute in attributes) {
       const entity = access([kind, attribute], params);
-      if (isString(entity) && values.includes(entity)) return true;
+      if (isString(entity) && attributes[attribute].includes(entity))
+        return true;
     }
   }
   return false;
@@ -232,12 +231,12 @@ function matchConditions(conditions, params) {
           if (lhs === null || lhs === void 0) return false;
           return (isNumber(rhs) || isString(rhs)) && lhs <= rhs;
         case "regex" /* REGEX */:
-          if (isString(lhs) && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
+          if (isString(lhs) && lhs.length <= MAX_REGEX_INPUT_LENGTH && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
             return new RegExp(rhs.pattern, rhs.flags).test(lhs);
           }
           return false;
         case "!regex" /* NOT_REGEX */:
-          if (isString(lhs) && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
+          if (isString(lhs) && lhs.length <= MAX_REGEX_INPUT_LENGTH && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
             return !new RegExp(rhs.pattern, rhs.flags).test(lhs);
           }
           return false;
@@ -328,7 +327,7 @@ function handleOutcome(params, outcome) {
     }
   }
 }
-function evaluate(params) {
+function evaluate(params, _visited) {
   const envConfig = params.definition.environments[params.environment];
   if (typeof envConfig === "number") {
     return Object.assign(handleOutcome(params, envConfig), {
@@ -349,7 +348,16 @@ function evaluate(params) {
         `Could not find envConfig for "${envConfig.reuse}" when reusing`
       );
     }
-    return evaluate({ ...params, environment: envConfig.reuse });
+    const visited = _visited ?? /* @__PURE__ */ new Set();
+    if (visited.has(envConfig.reuse)) {
+      return {
+        reason: "error" /* ERROR */,
+        errorMessage: `Circular environment reuse detected: "${envConfig.reuse}"`,
+        value: params.defaultValue
+      };
+    }
+    visited.add(params.environment);
+    return evaluate({ ...params, environment: envConfig.reuse }, visited);
   }
   if (envConfig.targets) {
     const matchedIndex = envConfig.targets.findIndex(
@@ -382,7 +390,7 @@ function findWeightedIndex(weights, value, maxValue) {
 }
 
 // package.json
-var version = "1.1.0-cea788b-20260305194413";
+var version = "1.1.0";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -394,37 +402,67 @@ function internalReportValue(key, value, data) {
   });
 }
 
-// src/client-fns.ts
+// src/controller-fns.ts
+var controllerInstanceMap = /* @__PURE__ */ new Map();
+function getInstance(id) {
+  const instance = controllerInstanceMap.get(id);
+  if (!instance) {
+    throw new Error(
+      `@vercel/flags-core: Client instance ${id} not found. It may have been shut down.`
+    );
+  }
+  return instance;
+}
 function initialize(id) {
-  return clientMap.get(id).dataSource.initialize();
+  return getInstance(id).controller.initialize();
 }
 function shutdown(id) {
-  return clientMap.get(id).dataSource.shutdown();
+  return getInstance(id).controller.shutdown();
 }
 function getDatafile(id) {
-  return clientMap.get(id).dataSource.getDatafile();
+  return getInstance(id).controller.getDatafile();
 }
 function getFallbackDatafile(id) {
-  const ds = clientMap.get(id).dataSource;
+  const ds = getInstance(id).controller;
   if (ds.getFallbackDatafile) return ds.getFallbackDatafile();
   throw new Error("flags: This data source does not support fallbacks");
 }
 async function evaluate2(id, flagKey, defaultValue, entities) {
-  const ds = clientMap.get(id).dataSource;
-  const datafile = await ds.read();
+  const controller = getInstance(id).controller;
+  let datafile;
+  try {
+    datafile = await controller.read();
+  } catch (error) {
+    if (defaultValue !== void 0) {
+      return {
+        value: defaultValue,
+        reason: "error" /* ERROR */,
+        errorMessage: error instanceof Error ? error.message : "Failed to read datafile"
+      };
+    }
+    throw error;
+  }
   const flagDefinition = datafile.definitions[flagKey];
   if (flagDefinition === void 0) {
+    if (datafile.projectId) {
+      internalReportValue(flagKey, defaultValue, {
+        originProjectId: datafile.projectId,
+        originProvider: "vercel",
+        reason: "error" /* ERROR */
+      });
+    }
     return {
       value: defaultValue,
       reason: "error" /* ERROR */,
       errorCode: "FLAG_NOT_FOUND" /* FLAG_NOT_FOUND */,
-      errorMessage: `Definition not found for flag "${flagKey}"`,
+      errorMessage: `@vercel/flags-core: Definition not found for flag "${flagKey}"`,
       metrics: {
         evaluationMs: 0,
         readMs: datafile.metrics.readMs,
         source: datafile.metrics.source,
         cacheStatus: datafile.metrics.cacheStatus,
-        connectionState: datafile.metrics.connectionState
+        connectionState: datafile.metrics.connectionState,
+        mode: datafile.metrics.mode
       }
     };
   }
@@ -451,7 +489,8 @@ async function evaluate2(id, flagKey, defaultValue, entities) {
       readMs: datafile.metrics.readMs,
       source: datafile.metrics.source,
       cacheStatus: datafile.metrics.cacheStatus,
-      connectionState: datafile.metrics.connectionState
+      connectionState: datafile.metrics.connectionState,
+      mode: datafile.metrics.mode
     }
   });
 }
@@ -469,18 +508,22 @@ async function performInitialize(instance, initFn) {
 }
 function createCreateRawClient(fns) {
   return function createRawClient({
-    dataSource,
+    controller,
     origin
   }) {
     const id = idCount++;
-    clientMap.set(id, { dataSource, initialized: false, initPromise: null });
+    controllerInstanceMap.set(id, {
+      controller,
+      initialized: false,
+      initPromise: null
+    });
     const api = {
       origin,
       initialize: async () => {
-        let instance = clientMap.get(id);
+        let instance = controllerInstanceMap.get(id);
         if (!instance) {
-          instance = { dataSource, initialized: false, initPromise: null };
-          clientMap.set(id, instance);
+          instance = { controller, initialized: false, initPromise: null };
+          controllerInstanceMap.set(id, instance);
         }
         if (instance.initialized) return;
         if (!instance.initPromise) {
@@ -493,15 +536,29 @@ function createCreateRawClient(fns) {
       },
       shutdown: async () => {
         await fns.shutdown(id);
-        clientMap.delete(id);
+        controllerInstanceMap.delete(id);
+      },
+      getDatafile: async () => {
+        const instance = controllerInstanceMap.get(id);
+        if (instance?.initPromise) {
+          try {
+            await instance.initPromise;
+          } catch {
+          }
+        }
+        return fns.getDatafile(id);
       },
-      getDatafile: () => fns.getDatafile(id),
       getFallbackDatafile: () => {
         return fns.getFallbackDatafile(id);
       },
       evaluate: async (flagKey, defaultValue, entities) => {
-        const instance = clientMap.get(id);
-        if (!instance?.initialized) await api.initialize();
+        const instance = controllerInstanceMap.get(id);
+        if (!instance?.initialized) {
+          try {
+            await api.initialize();
+          } catch {
+          }
+        }
         return fns.evaluate(id, flagKey, defaultValue, entities);
       }
     };
@@ -509,20 +566,6 @@ function createCreateRawClient(fns) {
   };
 }
 
-// src/errors.ts
-var FallbackNotFoundError = class extends Error {
-  constructor() {
-    super("@vercel/flags-core: Bundled definitions file not found.");
-    this.name = "FallbackNotFoundError";
-  }
-};
-var FallbackEntryNotFoundError = class extends Error {
-  constructor() {
-    super("@vercel/flags-core: No bundled definitions found for SDK key.");
-    this.name = "FallbackEntryNotFoundError";
-  }
-};
-
 // src/utils/read-bundled-definitions.ts
 var sdkKeyHashCache = /* @__PURE__ */ new Map();
 async function computeHash(sdkKey) {
@@ -567,11 +610,6 @@ async function readBundledDefinitions(sdkKey) {
   return { definitions: null, state: "missing-entry" };
 }
 
-// src/utils/sleep.ts
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 // src/utils/usage-tracker.ts
 import { waitUntil } from "@vercel/functions";
 var RESOLVED_VOID = Promise.resolve();
@@ -580,9 +618,9 @@ var debugLog = (...args) => {
   if (!isDebugMode) return;
   console.log(...args);
 };
+var MAX_RETRIES = 3;
 var MAX_BATCH_SIZE = 50;
 var MAX_BATCH_WAIT_MS = 5e3;
-var trackedRequests = /* @__PURE__ */ new WeakSet();
 var SYMBOL_FOR_REQ_CONTEXT = /* @__PURE__ */ Symbol.for("@vercel/request-context");
 var fromSymbol = globalThis;
 function getRequestContext() {
@@ -600,24 +638,30 @@ function getRequestContext() {
   }
 }
 var UsageTracker = class {
-  sdkKey;
-  host;
+  flushCounter = 0;
+  options;
+  trackedRequests = /* @__PURE__ */ new WeakSet();
   batcher = {
     events: [],
     resolveWait: null,
     pending: null
   };
   constructor(options) {
-    this.sdkKey = options.sdkKey;
-    this.host = options.host;
+    this.options = options;
   }
   /**
    * Triggers an immediate flush of any pending events.
    * Returns a promise that resolves when the flush completes.
    */
   flush() {
-    this.batcher.resolveWait?.();
-    return this.batcher.pending ?? RESOLVED_VOID;
+    if (this.batcher.pending) {
+      this.batcher.resolveWait?.();
+      return this.batcher.pending;
+    }
+    if (this.batcher.events.length > 0) {
+      return this.flushEvents();
+    }
+    return RESOLVED_VOID;
   }
   /**
    * Tracks a config read event. Deduplicates by request context.
@@ -626,8 +670,8 @@ var UsageTracker = class {
     try {
       const { ctx, headers } = getRequestContext();
       if (ctx) {
-        if (trackedRequests.has(ctx)) return;
-        trackedRequests.add(ctx);
+        if (this.trackedRequests.has(ctx)) return;
+        this.trackedRequests.add(ctx);
       }
       const event = {
         type: "FLAGS_CONFIG_READ",
@@ -646,6 +690,9 @@ var UsageTracker = class {
         if (options.cacheStatus !== void 0) {
           event.payload.cacheStatus = options.cacheStatus;
         }
+        if (options.cacheAction !== void 0) {
+          event.payload.cacheAction = options.cacheAction;
+        }
         if (options.cacheIsFirstRead !== void 0) {
           event.payload.cacheIsFirstRead = options.cacheIsFirstRead;
         }
@@ -658,6 +705,16 @@ var UsageTracker = class {
         if (options.configUpdatedAt !== void 0) {
           event.payload.configUpdatedAt = options.configUpdatedAt;
         }
+        if (options.mode !== void 0) {
+          event.payload.mode = options.mode;
+        }
+        if (options.revision !== void 0) {
+          event.payload.revision = String(options.revision);
+        }
+      }
+      const environment = process.env.VERCEL_ENV || process.env.NODE_ENV || void 0;
+      if (environment) {
+        event.payload.environment = environment;
       }
       this.batcher.events.push(event);
       this.scheduleFlush();
@@ -678,7 +735,10 @@ var UsageTracker = class {
         if (timeout) clearTimeout(timeout);
         await this.flushEvents();
       })();
-      waitUntil(pending);
+      try {
+        waitUntil(pending);
+      } catch {
+      }
       this.batcher.pending = pending;
     }
     if (this.batcher.events.length >= MAX_BATCH_SIZE) {
@@ -689,41 +749,301 @@ var UsageTracker = class {
     if (this.batcher.events.length === 0) return;
     const eventsToSend = this.batcher.events;
     this.batcher.events = [];
-    try {
-      const response = await fetch(`${this.host}/v1/ingest`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.sdkKey}`,
-          "User-Agent": `VercelFlagsCore/${version}`,
-          ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
-        },
-        body: JSON.stringify(eventsToSend)
-      });
-      debugLog(
-        `@vercel/flags-core: Ingest response ${response.status} for ${eventsToSend.length} events on ${response.headers.get("x-vercel-id")}`
-      );
-      if (!response.ok) {
+    const flushId = ++this.flushCounter;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const response = await this.options.fetch(
+          `${this.options.host}/v1/ingest`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.options.sdkKey}`,
+              "User-Agent": `VercelFlagsCore/${version}`,
+              ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
+            },
+            body: JSON.stringify(eventsToSend)
+          }
+        );
         debugLog(
-          "@vercel/flags-core: Failed to send events:",
-          response.statusText
+          `@vercel/flags-core: Ingest response ${response.status} for ${eventsToSend.length} events on ${response.headers.get("x-vercel-id")}`
+        );
+        if (response.ok) {
+          break;
+        }
+        throw new Error(
+          `Ingest endpoint responded with status ${response.status} for ${eventsToSend.length} events on request ${response.headers.get("x-vercel-id")}.
+Response body: ${await response.text().catch(() => null)}`
+        );
+      } catch (error) {
+        console.error(
+          `@vercel/flags-core: Error sending events (attempt=${attempt}/${MAX_RETRIES} flushId=${flushId}):`,
+          error
         );
+        if (attempt < MAX_RETRIES) {
+          await new Promise((res) => setTimeout(res, attempt * 100));
+        }
       }
+    }
+  }
+};
+
+// src/errors.ts
+var FallbackNotFoundError = class extends Error {
+  constructor() {
+    super("@vercel/flags-core: Bundled definitions file not found.");
+    this.name = "FallbackNotFoundError";
+  }
+};
+var FallbackEntryNotFoundError = class extends Error {
+  constructor() {
+    super("@vercel/flags-core: No bundled definitions found for SDK key.");
+    this.name = "FallbackEntryNotFoundError";
+  }
+};
+
+// src/controller/bundled-source.ts
+var BundledSource = class {
+  promise;
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Load bundled definitions.
+   * Throws if bundled definitions are not available.
+   */
+  async load() {
+    const result = await this.getResult();
+    if (result.state === "ok" && result.definitions) {
+      return result.definitions;
+    }
+    throw new Error(
+      "@vercel/flags-core: No flag definitions available. Bundled definitions not found."
+    );
+  }
+  /**
+   * Get the raw BundledDefinitions (for getFallbackDatafile).
+   * Throws typed errors if not available.
+   */
+  async getRaw() {
+    const result = await this.getResult();
+    switch (result.state) {
+      case "ok":
+        return result.definitions;
+      case "missing-file":
+        throw new FallbackNotFoundError();
+      case "missing-entry":
+        throw new FallbackEntryNotFoundError();
+      case "unexpected-error":
+        throw new Error(
+          "@vercel/flags-core: Failed to read bundled definitions: " + String(result.error)
+        );
+    }
+  }
+  /**
+   * Check if bundled definitions loaded successfully (without throwing).
+   */
+  async tryLoad() {
+    const result = await this.getResult();
+    if (result?.state === "ok" && result.definitions) {
+      return result.definitions;
+    }
+    return void 0;
+  }
+  getResult() {
+    if (!this.promise) {
+      this.promise = this.options.readBundledDefinitions(this.options.sdkKey);
+    }
+    return this.promise;
+  }
+};
+
+// src/controller/fetch-datafile.ts
+var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
+async function fetchDatafile(options) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    DEFAULT_FETCH_TIMEOUT_MS
+  );
+  const onExternalAbort = () => controller.abort();
+  if (options.signal) {
+    if (options.signal.aborted) {
+      clearTimeout(timeoutId);
+      throw new Error("Fetch aborted");
+    }
+    options.signal.addEventListener("abort", onExternalAbort, { once: true });
+  }
+  try {
+    const res = await options.fetch(`${options.host}/v1/datafile`, {
+      headers: {
+        Authorization: `Bearer ${options.sdkKey}`,
+        "User-Agent": `VercelFlagsCore/${version}`
+      },
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    options.signal?.removeEventListener("abort", onExternalAbort);
+    if (!res.ok) {
+      throw new Error(`Failed to fetch data: ${res.statusText}`);
+    }
+    return res.json();
+  } catch (error) {
+    clearTimeout(timeoutId);
+    options.signal?.removeEventListener("abort", onExternalAbort);
+    throw error instanceof Error ? error : new Error("Unknown fetch error");
+  }
+}
+
+// src/controller/normalized-options.ts
+var DEFAULT_STREAM_INIT_TIMEOUT_MS = 3e3;
+var DEFAULT_POLLING_INTERVAL_MS = 3e4;
+var MIN_POLLING_INTERVAL_MS = 3e4;
+var DEFAULT_POLLING_INIT_TIMEOUT_MS = 3e3;
+function normalizeOptions(options) {
+  const autoDetectedBuildStep = process.env.CI === "1" || process.env.NEXT_PHASE === "phase-production-build";
+  const buildStep = options.buildStep ?? autoDetectedBuildStep;
+  let stream;
+  if (options.stream === void 0 || options.stream === true) {
+    stream = { enabled: true, initTimeoutMs: DEFAULT_STREAM_INIT_TIMEOUT_MS };
+  } else if (options.stream === false) {
+    stream = { enabled: false, initTimeoutMs: 0 };
+  } else {
+    stream = { enabled: true, initTimeoutMs: options.stream.initTimeoutMs };
+  }
+  let polling;
+  if (options.polling === void 0 || options.polling === true) {
+    polling = {
+      enabled: true,
+      intervalMs: DEFAULT_POLLING_INTERVAL_MS,
+      initTimeoutMs: DEFAULT_POLLING_INIT_TIMEOUT_MS
+    };
+  } else if (options.polling === false) {
+    polling = { enabled: false, intervalMs: 0, initTimeoutMs: 0 };
+  } else {
+    if (options.polling.intervalMs < MIN_POLLING_INTERVAL_MS) {
+      throw new Error(
+        `@vercel/flags-core: Polling interval must be at least ${MIN_POLLING_INTERVAL_MS}ms, got ${options.polling.intervalMs}ms.`
+      );
+    }
+    polling = {
+      enabled: true,
+      intervalMs: options.polling.intervalMs,
+      initTimeoutMs: options.polling.initTimeoutMs
+    };
+  }
+  return {
+    sdkKey: options.sdkKey,
+    datafile: options.datafile,
+    stream,
+    polling,
+    buildStep,
+    fetch: options.fetch ?? globalThis.fetch,
+    host: "https://flags.vercel.com"
+  };
+}
+
+// src/controller/typed-emitter.ts
+var TypedEmitter = class {
+  handlers = /* @__PURE__ */ new Map();
+  on(event, handler) {
+    let set = this.handlers.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(event, set);
+    }
+    set.add(handler);
+  }
+  off(event, handler) {
+    this.handlers.get(event)?.delete(handler);
+  }
+  emit(event, ...args) {
+    const set = this.handlers.get(event);
+    if (set) {
+      for (const handler of set) {
+        handler(...args);
+      }
+    }
+  }
+};
+
+// src/controller/polling-source.ts
+var PollingSource = class extends TypedEmitter {
+  config;
+  intervalId;
+  abortController;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  /**
+   * Perform a single poll request.
+   * Emits 'data' on success, 'error' on failure.
+   */
+  async poll() {
+    if (this.abortController?.signal.aborted) return;
+    try {
+      const data = await fetchDatafile({
+        ...this.config,
+        signal: this.abortController?.signal
+      });
+      this.emit("data", data);
     } catch (error) {
-      debugLog("@vercel/flags-core: Error sending events:", error);
+      const err = error instanceof Error ? error : new Error("Unknown poll error");
+      this.emit("error", err);
+    }
+  }
+  /**
+   * Start interval-based polling.
+   * Polls at the configured interval. Does not perform an initial poll —
+   * callers should call poll() first if an immediate poll is needed.
+   */
+  startInterval() {
+    if (this.intervalId) return;
+    this.abortController = new AbortController();
+    this.intervalId = setInterval(
+      () => void this.poll(),
+      this.config.polling.intervalMs
+    );
+  }
+  /**
+   * Stop interval-based polling.
+   */
+  stop() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = void 0;
     }
+    this.abortController?.abort();
+    this.abortController = void 0;
   }
 };
 
-// src/data-source/stream-connection.ts
+// src/utils/sleep.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/controller/stream-connection.ts
 var MAX_RETRY_COUNT = 15;
-var BASE_DELAY_MS = 1e3;
-var MAX_DELAY_MS = 6e4;
+var BASE_RETRY_DELAY_MS = 1e3;
+var MAX_RETRY_DELAY_MS = 6e4;
+var PING_TIMEOUT_MS = 9e4;
 function backoff(retryCount) {
   if (retryCount === 1) return 0;
-  const delay = Math.min(BASE_DELAY_MS * 2 ** (retryCount - 2), MAX_DELAY_MS);
+  const delay = Math.min(
+    BASE_RETRY_DELAY_MS * 2 ** (retryCount - 2),
+    MAX_RETRY_DELAY_MS
+  );
   return delay + Math.random() * 1e3;
 }
+var UnauthorizedError = class extends Error {
+  constructor() {
+    super("stream: unauthorized (401)");
+    this.name = "UnauthorizedError";
+  }
+};
 async function connectStream(config, callbacks) {
   const {
     host,
@@ -731,8 +1051,9 @@ async function connectStream(config, callbacks) {
     abortController,
     fetch: fetchFn = globalThis.fetch
   } = config;
-  const { onMessage, onDisconnect } = callbacks;
+  const { onDatafile, onPrimed, onDisconnect } = callbacks;
   let retryCount = 0;
+  let lastAttemptTime = 0;
   let resolveInit;
   let rejectInit;
   const initPromise = new Promise((resolve, reject) => {
@@ -744,183 +1065,267 @@ async function connectStream(config, callbacks) {
     while (!abortController.signal.aborted) {
       if (retryCount > MAX_RETRY_COUNT) {
         console.error("@vercel/flags-core: Max retry count exceeded");
+        if (!initialDataReceived) {
+          rejectInit(
+            new Error("stream: max retry count exceeded before receiving data")
+          );
+        }
         abortController.abort();
         break;
       }
+      const connectionAbort = new AbortController();
+      const onMainAbort = () => connectionAbort.abort();
+      abortController.signal.addEventListener("abort", onMainAbort, {
+        once: true
+      });
+      let pingTimeoutId;
+      let responseBody;
+      const resetPingTimeout = () => {
+        if (pingTimeoutId !== void 0) clearTimeout(pingTimeoutId);
+        if (!initialDataReceived) return;
+        pingTimeoutId = setTimeout(() => {
+          responseBody?.cancel().catch(() => {
+          });
+          connectionAbort.abort();
+        }, PING_TIMEOUT_MS);
+      };
       try {
+        lastAttemptTime = Date.now();
+        const headers = {
+          Authorization: `Bearer ${sdkKey}`,
+          "User-Agent": `VercelFlagsCore/${version}`,
+          "X-Retry-Attempt": String(retryCount)
+        };
+        const revision = config.revision?.();
+        if (revision !== void 0) {
+          headers["X-Revision"] = String(revision);
+        }
         const response = await fetchFn(`${host}/v1/stream`, {
-          headers: {
-            Authorization: `Bearer ${sdkKey}`,
-            "User-Agent": `VercelFlagsCore/${version}`,
-            "X-Retry-Attempt": String(retryCount)
-          },
-          signal: abortController.signal
+          headers,
+          signal: connectionAbort.signal
         });
         if (!response.ok) {
           if (response.status === 401) {
+            if (!initialDataReceived) {
+              rejectInit(new UnauthorizedError());
+            }
             abortController.abort();
+            break;
           }
           throw new Error(`stream was not ok: ${response.status}`);
         }
         if (!response.body) {
           throw new Error("stream body was not present");
         }
+        responseBody = response.body;
+        const reader = response.body.getReader();
         const decoder = new TextDecoder();
-        let buffer = "";
-        for await (const chunk of response.body) {
-          if (abortController.signal.aborted) break;
-          buffer += decoder.decode(chunk, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop();
-          for (const line of lines) {
-            if (line === "") continue;
-            let message;
-            try {
-              message = JSON.parse(line);
-            } catch {
-              console.warn(
-                "@vercel/flags-core: Failed to parse stream message, skipping"
-              );
-              continue;
-            }
-            if (message.type === "datafile") {
-              onMessage(message.data);
-              retryCount = 0;
-              if (!initialDataReceived) {
-                initialDataReceived = true;
-                resolveInit();
+        const bufferChunks = [];
+        const onConnectionAbort = () => {
+          reader.cancel().catch(() => {
+          });
+        };
+        connectionAbort.signal.addEventListener("abort", onConnectionAbort, {
+          once: true
+        });
+        try {
+          while (true) {
+            const { done, value: chunk } = await reader.read();
+            if (done || abortController.signal.aborted) break;
+            bufferChunks.push(decoder.decode(chunk, { stream: true }));
+            const combined = bufferChunks.join("");
+            bufferChunks.length = 0;
+            const lines = combined.split("\n");
+            bufferChunks.push(lines.pop());
+            for (const line of lines) {
+              if (line === "") continue;
+              let message;
+              try {
+                message = JSON.parse(line);
+              } catch {
+                console.warn(
+                  "@vercel/flags-core: Failed to parse stream message, skipping"
+                );
+                continue;
+              }
+              if (message.type === "datafile") {
+                onDatafile(message.data);
+                retryCount = 0;
+                if (!initialDataReceived) {
+                  initialDataReceived = true;
+                  resolveInit();
+                }
+                resetPingTimeout();
+              }
+              if (message.type === "primed") {
+                onPrimed?.(message);
+                retryCount = 0;
+                if (!initialDataReceived) {
+                  initialDataReceived = true;
+                  resolveInit();
+                }
+                resetPingTimeout();
+              }
+              if (message.type === "ping" && initialDataReceived) {
+                retryCount = 0;
+                resetPingTimeout();
               }
             }
           }
+        } finally {
+          connectionAbort.signal.removeEventListener(
+            "abort",
+            onConnectionAbort
+          );
         }
+        clearTimeout(pingTimeoutId);
+        abortController.signal.removeEventListener("abort", onMainAbort);
         if (!abortController.signal.aborted) {
           onDisconnect?.();
           retryCount++;
-          await sleep(backoff(retryCount));
+          const elapsed = Date.now() - lastAttemptTime;
+          const minGap = Math.max(0, BASE_RETRY_DELAY_MS - elapsed);
+          await sleep(Math.max(backoff(retryCount), minGap));
           continue;
         }
       } catch (error) {
+        clearTimeout(pingTimeoutId);
+        abortController.signal.removeEventListener("abort", onMainAbort);
         if (abortController.signal.aborted) {
           break;
         }
-        console.error("@vercel/flags-core: Stream error", error);
-        onDisconnect?.();
-        if (!initialDataReceived) {
-          rejectInit(error);
-          break;
+        if (!connectionAbort.signal.aborted) {
+          console.error("@vercel/flags-core: Stream error", error);
         }
+        onDisconnect?.();
         retryCount++;
-        await sleep(backoff(retryCount));
+        const elapsed = Date.now() - lastAttemptTime;
+        const minGap = Math.max(0, BASE_RETRY_DELAY_MS - elapsed);
+        await sleep(Math.max(backoff(retryCount), minGap));
       }
     }
+    if (!initialDataReceived) {
+      rejectInit(new Error("stream: aborted before receiving data"));
+    }
   })();
   return initPromise;
 }
 
-// src/data-source/flag-network-data-source.ts
-var FLAGS_HOST = "https://flags.vercel.com";
-var DEFAULT_STREAM_INIT_TIMEOUT_MS = 3e3;
-var DEFAULT_POLLING_INTERVAL_MS = 3e4;
-var DEFAULT_POLLING_INIT_TIMEOUT_MS = 3e3;
-var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
-var MAX_FETCH_RETRIES = 3;
-var FETCH_RETRY_BASE_DELAY_MS = 500;
-function normalizeOptions(options) {
-  const autoDetectedBuildStep = process.env.CI === "1" || process.env.NEXT_PHASE === "phase-production-build";
-  const buildStep = options.buildStep ?? autoDetectedBuildStep;
-  let stream;
-  if (options.stream === void 0 || options.stream === true) {
-    stream = { enabled: true, initTimeoutMs: DEFAULT_STREAM_INIT_TIMEOUT_MS };
-  } else if (options.stream === false) {
-    stream = { enabled: false, initTimeoutMs: 0 };
-  } else {
-    stream = { enabled: true, initTimeoutMs: options.stream.initTimeoutMs };
-  }
-  let polling;
-  if (options.polling === void 0 || options.polling === true) {
-    polling = {
-      enabled: true,
-      intervalMs: DEFAULT_POLLING_INTERVAL_MS,
-      initTimeoutMs: DEFAULT_POLLING_INIT_TIMEOUT_MS
-    };
-  } else if (options.polling === false) {
-    polling = { enabled: false, intervalMs: 0, initTimeoutMs: 0 };
-  } else {
-    polling = {
-      enabled: true,
-      intervalMs: options.polling.intervalMs,
-      initTimeoutMs: options.polling.initTimeoutMs
-    };
+// src/controller/stream-source.ts
+var StreamSource = class extends TypedEmitter {
+  options;
+  revision;
+  abortController;
+  promise;
+  constructor(options, revision) {
+    super();
+    this.options = options;
+    this.revision = revision;
   }
-  return {
-    sdkKey: options.sdkKey,
-    datafile: options.datafile,
-    stream,
-    polling,
-    buildStep,
-    fetch: options.fetch ?? globalThis.fetch
-  };
-}
-async function fetchDatafile(host, sdkKey, fetchFn) {
-  let lastError;
-  for (let attempt = 0; attempt < MAX_FETCH_RETRIES; attempt++) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(
-      () => controller.abort(),
-      DEFAULT_FETCH_TIMEOUT_MS
+  /**
+   * Start the stream connection.
+   * Returns a promise that resolves when the first datafile or primed message arrives.
+   * If already started, returns the existing promise.
+   */
+  start() {
+    if (this.promise) return this.promise;
+    const abortController = new AbortController();
+    this.abortController = abortController;
+    abortController.signal.addEventListener(
+      "abort",
+      () => {
+        if (this.abortController === abortController) {
+          this.promise = void 0;
+          this.abortController = void 0;
+        }
+      },
+      { once: true }
     );
-    let shouldRetry = true;
     try {
-      const res = await fetchFn(`${host}/v1/datafile`, {
-        headers: {
-          Authorization: `Bearer ${sdkKey}`,
-          "User-Agent": `VercelFlagsCore/${version}`
+      const promise = connectStream(
+        {
+          host: this.options.host,
+          sdkKey: this.options.sdkKey,
+          abortController,
+          fetch: this.options.fetch,
+          revision: this.revision
         },
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!res.ok) {
-        if (res.status >= 400 && res.status < 500 && res.status !== 429) {
-          shouldRetry = false;
+        {
+          onDatafile: (newData) => {
+            this.emit("data", newData);
+            this.emit("connected");
+          },
+          onPrimed: (message) => {
+            this.emit("primed", message);
+            this.emit("connected");
+          },
+          onDisconnect: () => {
+            this.emit("disconnected");
+          }
         }
-        throw new Error(`Failed to fetch data: ${res.statusText}`);
-      }
-      return res.json();
+      );
+      this.promise = promise;
+      return promise;
     } catch (error) {
-      clearTimeout(timeoutId);
-      lastError = error instanceof Error ? error : new Error("Unknown fetch error");
-      if (!shouldRetry) throw lastError;
-      if (attempt < MAX_FETCH_RETRIES - 1) {
-        const delay = FETCH_RETRY_BASE_DELAY_MS * 2 ** attempt + Math.random() * 500;
-        await sleep(delay);
-      }
+      this.promise = void 0;
+      this.abortController = void 0;
+      throw error;
     }
   }
-  throw lastError ?? new Error("Failed to fetch data after retries");
+  /**
+   * Stop the stream connection.
+   */
+  stop() {
+    this.abortController?.abort();
+    this.abortController = void 0;
+    this.promise = void 0;
+  }
+};
+
+// src/controller/tagged-data.ts
+function tagData(data, origin) {
+  return Object.assign(data, { _origin: origin });
+}
+function originToMetricsSource(origin) {
+  switch (origin) {
+    case "stream":
+    case "poll":
+    case "provided":
+      return "in-memory";
+    case "fetched":
+      return "remote";
+    case "bundled":
+      return "embedded";
+  }
+}
+
+// src/controller/index.ts
+function parseConfigUpdatedAt(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? void 0 : parsed;
+  }
+  return void 0;
 }
-var FlagNetworkDataSource = class _FlagNetworkDataSource {
+var Controller = class {
   options;
-  host = FLAGS_HOST;
-  // Data state
+  // State machine
+  state = "idle";
+  // Data state — tagged with origin
   data;
-  bundledDefinitionsPromise;
-  // Stream state
-  streamAbortController;
-  streamPromise;
-  isStreamConnected = false;
-  hasWarnedAboutStaleData = false;
-  // Polling state
-  pollingIntervalId;
-  pollingAbortController;
-  // Initialization state — suppresses onDisconnect from starting polling
-  // while initialize() is still running its own fallback chain
-  isInitializing = false;
+  // Sources (I/O delegates)
+  streamSource;
+  pollingSource;
+  bundledSource;
   // Usage tracking
   usageTracker;
   isFirstGetData = true;
-  /**
-   * Creates a new FlagNetworkDataSource instance.
-   */
+  // Build-step deduplication
+  buildDataPromise = null;
+  buildReadTracked = false;
+  // Suppresses usage tracking when the SDK key is unauthorized
+  unauthorized = false;
   constructor(options) {
     if (!options.sdkKey || typeof options.sdkKey !== "string" || !options.sdkKey.startsWith("vf_")) {
       throw new Error(
@@ -928,16 +1333,88 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
       );
     }
     this.options = normalizeOptions(options);
-    this.bundledDefinitionsPromise = readBundledDefinitions(
-      this.options.sdkKey
+    this.streamSource = new StreamSource(
+      this.options,
+      () => this.data?.revision
     );
-    if (this.options.datafile) {
-      this.data = this.options.datafile;
-    }
-    this.usageTracker = new UsageTracker({
+    this.pollingSource = new PollingSource(this.options);
+    this.bundledSource = new BundledSource({
       sdkKey: this.options.sdkKey,
-      host: this.host
+      readBundledDefinitions
     });
+    this.wireSourceEvents();
+    if (this.options.datafile) {
+      this.data = tagData(this.options.datafile, "provided");
+    }
+    this.usageTracker = new UsageTracker(this.options);
+  }
+  // Source event handlers (stored for cleanup)
+  onStreamData = (data) => {
+    if (this.isNewerData(data)) {
+      this.data = tagData(data, "stream");
+    }
+  };
+  onStreamPrimed = () => {
+    if (this.state === "degraded" || this.state === "initializing:stream") {
+      this.transition("streaming");
+    }
+  };
+  onStreamConnected = () => {
+    if (this.state === "degraded" || this.state === "initializing:stream") {
+      this.transition("streaming");
+    }
+  };
+  onStreamDisconnected = () => {
+    if (this.state === "streaming") {
+      this.transition("degraded");
+    }
+  };
+  onPollData = (data) => {
+    if (this.isNewerData(data)) {
+      this.data = tagData(data, "poll");
+    }
+  };
+  onPollError = (error) => {
+    console.error("@vercel/flags-core: Poll failed:", error);
+  };
+  // ---------------------------------------------------------------------------
+  // Source event wiring
+  // ---------------------------------------------------------------------------
+  wireSourceEvents() {
+    this.streamSource.on("data", this.onStreamData);
+    this.streamSource.on("primed", this.onStreamPrimed);
+    this.streamSource.on("connected", this.onStreamConnected);
+    this.streamSource.on("disconnected", this.onStreamDisconnected);
+    this.pollingSource.on("data", this.onPollData);
+    this.pollingSource.on("error", this.onPollError);
+  }
+  unwireSourceEvents() {
+    this.streamSource.off("data", this.onStreamData);
+    this.streamSource.off("primed", this.onStreamPrimed);
+    this.streamSource.off("connected", this.onStreamConnected);
+    this.streamSource.off("disconnected", this.onStreamDisconnected);
+    this.pollingSource.off("data", this.onPollData);
+    this.pollingSource.off("error", this.onPollError);
+  }
+  // ---------------------------------------------------------------------------
+  // State machine
+  // ---------------------------------------------------------------------------
+  transition(to) {
+    this.state = to;
+  }
+  get isConnected() {
+    return this.state === "streaming";
+  }
+  get mode() {
+    if (this.options.buildStep) return "build";
+    switch (this.state) {
+      case "streaming":
+        return "streaming";
+      case "polling":
+        return "polling";
+      default:
+        return "offline";
+    }
   }
   // ---------------------------------------------------------------------------
   // Public API (DataSource interface)
@@ -945,155 +1422,187 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
   /**
    * Initializes the data source.
    *
-   * Build step: datafile → bundled → fetch
-   * Runtime: stream → poll → datafile → bundled
+   * Build step: datafile → bundled → one-time fetch
+   * Streaming mode: stream → datafile → bundled
+   * Polling mode (no stream): poll → datafile → bundled
+   * Offline mode (neither): datafile → bundled → one-time fetch
    */
   async initialize() {
     if (this.options.buildStep) {
+      this.transition("build:loading");
       await this.initializeForBuildStep();
+      this.transition("build:ready");
       return;
     }
     if (!this.data && this.options.datafile) {
-      this.data = this.options.datafile;
+      this.data = tagData(this.options.datafile, "provided");
+    }
+    if (!this.data) {
+      try {
+        const bundled = await this.bundledSource.tryLoad();
+        if (bundled) {
+          this.data = tagData(bundled, "bundled");
+        }
+      } catch {
+      }
     }
     if (this.data) {
-      this.startBackgroundUpdates();
+      if (this.options.stream.enabled) {
+        this.transition("initializing:stream");
+        await this.tryInitializeStream();
+      } else if (this.options.polling.enabled) {
+        this.transition("initializing:polling");
+        await this.tryInitializePolling();
+      } else {
+        this.transition("degraded");
+      }
       return;
     }
-    this.isInitializing = true;
-    try {
-      if (this.options.stream.enabled) {
-        const streamSuccess = await this.tryInitializeStream();
-        if (streamSuccess) return;
+    if (this.options.stream.enabled) {
+      this.transition("initializing:stream");
+      const streamSuccess = await this.tryInitializeStream();
+      if (streamSuccess) {
+        this.transition("streaming");
+        return;
       }
-      if (this.options.polling.enabled) {
-        const pollingSuccess = await this.tryInitializePolling();
-        if (pollingSuccess) return;
+    } else if (this.options.polling.enabled) {
+      this.transition("initializing:polling");
+      const pollingSuccess = await this.tryInitializePolling();
+      if (pollingSuccess) {
+        this.transition("polling");
+        return;
       }
-      if (this.data) return;
-      await this.initializeFromBundled();
-    } finally {
-      this.isInitializing = false;
     }
+    await this.initializeFromFallbacks();
   }
   /**
    * Reads the current datafile with metrics.
    */
   async read() {
     const startTime = Date.now();
-    const cachedData = this.data;
-    const cacheHadDefinitions = cachedData !== void 0;
+    const cacheHadDefinitions = this.data !== void 0;
     const isFirstRead = this.isFirstGetData;
     this.isFirstGetData = false;
-    let result;
-    let source;
-    let cacheStatus;
-    if (this.options.buildStep) {
-      [result, source, cacheStatus] = await this.getDataForBuildStep();
-    } else if (cachedData) {
-      [result, source, cacheStatus] = this.getDataFromCache(cachedData);
-    } else {
-      [result, source, cacheStatus] = await this.getDataWithFallbacks();
-    }
+    const [result, cacheStatus] = await this.resolveData();
     const readMs = Date.now() - startTime;
+    const { _origin, ...data } = result;
+    const source = originToMetricsSource(_origin);
     this.trackRead(startTime, cacheHadDefinitions, isFirstRead, source);
-    return Object.assign(result, {
+    return {
+      ...data,
       metrics: {
         readMs,
         source,
         cacheStatus,
-        connectionState: this.isStreamConnected ? "connected" : "disconnected"
+        connectionState: this.isConnected ? "connected" : "disconnected",
+        mode: this.mode
       }
-    });
+    };
   }
   /**
    * Shuts down the data source and releases resources.
    */
   async shutdown() {
-    this.stopStream();
-    this.stopPolling();
-    this.data = this.options.datafile;
-    this.isInitializing = false;
-    this.isStreamConnected = false;
-    this.hasWarnedAboutStaleData = false;
+    this.unwireSourceEvents();
+    this.streamSource.stop();
+    this.pollingSource.stop();
+    this.data = this.options.datafile ? tagData(this.options.datafile, "provided") : void 0;
+    this.transition("shutdown");
     await this.usageTracker.flush();
   }
   /**
    * Returns the datafile with metrics.
-   *
-   * During builds this will read from the bundled file if available.
-   *
-   * This method never opens a streaming connection, but will read from
-   * the stream if it is already open. Otherwise it fetches over the network.
+   * Uses in-memory data if available, otherwise falls back to bundled,
+   * then to a one-time fetch if called without prior initialization.
    */
   async getDatafile() {
     const startTime = Date.now();
+    this.isFirstGetData = false;
     let result;
-    let source;
     let cacheStatus;
     if (this.options.buildStep) {
-      [result, source, cacheStatus] = await this.getDataForBuildStep();
-    } else if (this.isStreamConnected && this.data) {
-      [result, source, cacheStatus] = this.getDataFromCache();
+      [result, cacheStatus] = await this.resolveDataForBuildStep();
+    } else if (this.data) {
+      cacheStatus = this.isConnected ? "HIT" : "STALE";
+      result = this.data;
     } else {
-      const fetched = await fetchDatafile(
-        this.host,
-        this.options.sdkKey,
-        this.options.fetch
-      );
-      if (this.isNewerData(fetched)) {
-        this.data = fetched;
+      const bundled = await this.bundledSource.tryLoad();
+      if (bundled) {
+        this.data = tagData(bundled, "bundled");
+        result = this.data;
+        cacheStatus = "MISS";
+      } else {
+        try {
+          const fetched = await fetchDatafile({
+            host: this.options.host,
+            sdkKey: this.options.sdkKey,
+            fetch: this.options.fetch
+          });
+          this.data = tagData(fetched, "fetched");
+          result = this.data;
+          cacheStatus = "MISS";
+        } catch {
+          throw new Error(
+            "@vercel/flags-core: No flag definitions available. Initialize the client or provide a datafile."
+          );
+        }
       }
-      [result, source, cacheStatus] = [this.data ?? fetched, "remote", "MISS"];
     }
-    return Object.assign(result, {
+    const source = originToMetricsSource(result._origin);
+    return {
+      ...result,
       metrics: {
         readMs: Date.now() - startTime,
         source,
         cacheStatus,
-        connectionState: this.isStreamConnected ? "connected" : "disconnected"
+        connectionState: this.isConnected ? "connected" : "disconnected",
+        mode: this.mode
       }
-    });
+    };
   }
   /**
    * Returns the bundled fallback datafile.
    */
   async getFallbackDatafile() {
-    if (!this.bundledDefinitionsPromise) {
-      throw new FallbackNotFoundError();
-    }
-    const bundledResult = await this.bundledDefinitionsPromise;
-    if (!bundledResult) {
-      throw new FallbackNotFoundError();
+    return this.bundledSource.getRaw();
+  }
+  // ---------------------------------------------------------------------------
+  // Data resolution (shared by read() and getDatafile())
+  // ---------------------------------------------------------------------------
+  /**
+   * Resolves the current data, using the appropriate strategy for the
+   * current mode. Returns tagged data and cache status.
+   *
+   * Build step: cached → bundled → one-time fetch
+   * Runtime with cache: return cached data
+   * Runtime without cache: stream/poll → datafile → bundled → fetch → throw
+   */
+  async resolveData() {
+    if (this.options.buildStep) {
+      return this.resolveDataForBuildStep();
     }
-    switch (bundledResult.state) {
-      case "ok":
-        return bundledResult.definitions;
-      case "missing-file":
-        throw new FallbackNotFoundError();
-      case "missing-entry":
-        throw new FallbackEntryNotFoundError();
-      case "unexpected-error":
-        throw new Error(
-          "@vercel/flags-core: Failed to read bundled definitions: " + String(bundledResult.error)
-        );
+    if (this.data) {
+      const cacheStatus = this.isConnected ? "HIT" : "STALE";
+      return [this.data, cacheStatus];
     }
+    return this.resolveDataWithFallbacks();
   }
   // ---------------------------------------------------------------------------
-  // Stream management
+  // Stream initialization
   // ---------------------------------------------------------------------------
   /**
    * Attempts to initialize via stream with timeout.
    * Returns true if stream connected successfully within timeout.
    */
   async tryInitializeStream() {
-    let streamPromise;
     if (this.options.stream.initTimeoutMs <= 0) {
       try {
-        streamPromise = this.startStream();
-        await streamPromise;
+        await this.streamSource.start();
         return true;
-      } catch {
+      } catch (error) {
+        if (error instanceof UnauthorizedError) {
+          this.unauthorized = true;
+        }
         return false;
       }
     }
@@ -1105,87 +1614,44 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
       );
     });
     try {
-      streamPromise = this.startStream();
-      const result = await Promise.race([streamPromise, timeoutPromise]);
+      const result = await Promise.race([
+        this.streamSource.start(),
+        timeoutPromise
+      ]);
       clearTimeout(timeoutId);
       if (result === "timeout") {
         console.warn(
           "@vercel/flags-core: Stream initialization timeout, falling back"
         );
+        void this.streamSource.start().catch(() => {
+        });
         return false;
       }
       return true;
-    } catch {
+    } catch (error) {
       clearTimeout(timeoutId);
+      if (error instanceof Error && error.message.includes("401")) {
+        this.unauthorized = true;
+      }
       return false;
     }
   }
-  /**
-   * Starts the stream connection with callbacks for data and disconnect.
-   */
-  startStream() {
-    if (this.streamPromise) return this.streamPromise;
-    this.streamAbortController = new AbortController();
-    this.isStreamConnected = false;
-    this.hasWarnedAboutStaleData = false;
-    try {
-      const streamPromise = connectStream(
-        {
-          host: this.host,
-          sdkKey: this.options.sdkKey,
-          abortController: this.streamAbortController,
-          fetch: this.options.fetch
-        },
-        {
-          onMessage: (newData) => {
-            if (this.isNewerData(newData)) {
-              this.data = newData;
-            }
-            this.isStreamConnected = true;
-            this.hasWarnedAboutStaleData = false;
-            if (this.pollingIntervalId) {
-              this.stopPolling();
-            }
-          },
-          onDisconnect: () => {
-            this.isStreamConnected = false;
-            if (this.options.polling.enabled && !this.pollingIntervalId && !this.isInitializing) {
-              this.startPolling();
-            }
-          }
-        }
-      );
-      this.streamPromise = streamPromise;
-      return streamPromise;
-    } catch (error) {
-      this.streamPromise = void 0;
-      this.streamAbortController = void 0;
-      throw error;
-    }
-  }
-  /**
-   * Stops the stream connection.
-   */
-  stopStream() {
-    this.streamAbortController?.abort();
-    this.streamAbortController = void 0;
-    this.streamPromise = void 0;
-  }
   // ---------------------------------------------------------------------------
-  // Polling management
+  // Polling initialization
   // ---------------------------------------------------------------------------
   /**
    * Attempts to initialize via polling with timeout.
    * Returns true if first poll succeeded within timeout.
+   *
+   * Only used when streaming is disabled and polling is the primary source.
    */
   async tryInitializePolling() {
-    this.pollingAbortController = new AbortController();
-    const pollPromise = this.performPoll();
+    const pollPromise = this.pollingSource.poll();
     if (this.options.polling.initTimeoutMs <= 0) {
       try {
         await pollPromise;
         if (this.data) {
-          this.startPollingInterval();
+          this.pollingSource.startInterval();
           return true;
         }
         return false;
@@ -1210,7 +1676,7 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
         return false;
       }
       if (this.data) {
-        this.startPollingInterval();
+        this.pollingSource.startInterval();
         return true;
       }
       return false;
@@ -1219,68 +1685,6 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
       return false;
     }
   }
-  /**
-   * Starts polling (initial poll + interval).
-   */
-  startPolling() {
-    if (this.pollingIntervalId) return;
-    this.pollingAbortController = new AbortController();
-    void this.performPoll();
-    this.startPollingInterval();
-  }
-  /**
-   * Starts the polling interval (without initial poll).
-   */
-  startPollingInterval() {
-    if (this.pollingIntervalId) return;
-    this.pollingIntervalId = setInterval(
-      () => void this.performPoll(),
-      this.options.polling.intervalMs
-    );
-  }
-  /**
-   * Stops polling.
-   */
-  stopPolling() {
-    if (this.pollingIntervalId) {
-      clearInterval(this.pollingIntervalId);
-      this.pollingIntervalId = void 0;
-    }
-    this.pollingAbortController?.abort();
-    this.pollingAbortController = void 0;
-  }
-  /**
-   * Performs a single poll request.
-   */
-  async performPoll() {
-    if (this.pollingAbortController?.signal.aborted) return;
-    try {
-      const data = await fetchDatafile(
-        this.host,
-        this.options.sdkKey,
-        this.options.fetch
-      );
-      if (this.isNewerData(data)) {
-        this.data = data;
-      }
-    } catch (error) {
-      console.error("@vercel/flags-core: Poll failed:", error);
-    }
-  }
-  // ---------------------------------------------------------------------------
-  // Background updates
-  // ---------------------------------------------------------------------------
-  /**
-   * Starts background updates (stream or polling) without blocking.
-   * Used when we already have data from provided datafile.
-   */
-  startBackgroundUpdates() {
-    if (this.options.stream.enabled) {
-      void this.startStream();
-    } else if (this.options.polling.enabled) {
-      this.startPolling();
-    }
-  }
   // ---------------------------------------------------------------------------
   // Build step helpers
   // ---------------------------------------------------------------------------
@@ -1289,116 +1693,139 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
    */
   async initializeForBuildStep() {
     if (this.data) return;
-    if (this.bundledDefinitionsPromise) {
-      const bundledResult = await this.bundledDefinitionsPromise;
-      if (bundledResult?.state === "ok" && bundledResult.definitions) {
-        this.data = bundledResult.definitions;
-        return;
-      }
+    if (!this.buildDataPromise) {
+      this.buildDataPromise = this.loadBuildData();
     }
-    this.data = await fetchDatafile(
-      this.host,
-      this.options.sdkKey,
-      this.options.fetch
-    );
+    this.data = await this.buildDataPromise;
   }
   /**
    * Retrieves data during build steps.
+   * Concurrent callers share a single load promise. The first caller to
+   * populate `this.data` gets cacheStatus MISS; subsequent callers get HIT.
    */
-  async getDataForBuildStep() {
+  async resolveDataForBuildStep() {
     if (this.data) {
-      return [this.data, "in-memory", "HIT"];
+      return [this.data, "HIT"];
     }
-    if (this.bundledDefinitionsPromise) {
-      const bundledResult = await this.bundledDefinitionsPromise;
-      if (bundledResult?.state === "ok" && bundledResult.definitions) {
-        this.data = bundledResult.definitions;
-        return [this.data, "embedded", "MISS"];
-      }
+    if (!this.buildDataPromise) {
+      this.buildDataPromise = this.loadBuildData();
+    }
+    const data = await this.buildDataPromise;
+    if (!this.data) {
+      this.data = data;
+      return [data, "MISS"];
+    }
+    return [this.data, "HIT"];
+  }
+  /**
+   * Loads data for a build step: bundled → one-time fetch.
+   */
+  async loadBuildData() {
+    const bundled = await this.bundledSource.tryLoad();
+    if (bundled) return tagData(bundled, "bundled");
+    try {
+      const fetched = await fetchDatafile({
+        host: this.options.host,
+        sdkKey: this.options.sdkKey,
+        fetch: this.options.fetch
+      });
+      return tagData(fetched, "fetched");
+    } catch {
     }
-    this.data = await fetchDatafile(
-      this.host,
-      this.options.sdkKey,
-      this.options.fetch
+    throw new Error(
+      "@vercel/flags-core: No flag definitions available during build. Provide a datafile or bundled definitions."
     );
-    return [this.data, "remote", "MISS"];
   }
   // ---------------------------------------------------------------------------
-  // Runtime helpers
+  // Fallback helpers
   // ---------------------------------------------------------------------------
   /**
-   * Returns data from the in-memory cache.
+   * Shared fallback chain used by both initialize() and resolveData().
    */
-  getDataFromCache(cachedData) {
-    const data = cachedData ?? this.data;
-    this.warnIfDisconnected();
-    const cacheStatus = this.isStreamConnected ? "HIT" : "STALE";
-    return [data, "in-memory", cacheStatus];
+  async initializeFromFallbacks() {
+    this.transition("initializing:fallback");
+    if (this.data) {
+      this.transition("degraded");
+      return;
+    }
+    const bundled = await this.bundledSource.tryLoad();
+    if (bundled) {
+      this.data = tagData(bundled, "bundled");
+      this.transition("degraded");
+      return;
+    }
+    if (!this.options.stream.enabled && !this.options.polling.enabled) {
+      try {
+        const fetched = await fetchDatafile({
+          host: this.options.host,
+          sdkKey: this.options.sdkKey,
+          fetch: this.options.fetch
+        });
+        this.data = tagData(fetched, "fetched");
+        this.transition("degraded");
+        return;
+      } catch {
+      }
+    }
+    throw new Error(
+      "@vercel/flags-core: No flag definitions available. Bundled definitions not found."
+    );
   }
   /**
-   * Retrieves data using the fallback chain.
+   * Retrieves data using the fallback chain (called when no cached data exists).
+   * Streaming mode: stream → datafile → bundled.
+   * Polling mode: poll → datafile → bundled.
+   * Offline mode: datafile → bundled → one-time fetch.
    */
-  async getDataWithFallbacks() {
+  async resolveDataWithFallbacks() {
     if (this.options.stream.enabled) {
+      this.transition("initializing:stream");
       const streamSuccess = await this.tryInitializeStream();
       if (streamSuccess && this.data) {
-        return [this.data, "in-memory", "MISS"];
+        this.transition("streaming");
+        return [this.data, "MISS"];
       }
-    }
-    if (this.options.polling.enabled) {
+    } else if (this.options.polling.enabled) {
+      this.transition("initializing:polling");
       const pollingSuccess = await this.tryInitializePolling();
       if (pollingSuccess && this.data) {
-        return [this.data, "remote", "MISS"];
+        this.transition("polling");
+        return [this.data, "MISS"];
       }
     }
+    this.transition("initializing:fallback");
     if (this.options.datafile) {
-      this.data = this.options.datafile;
-      return [this.data, "in-memory", "STALE"];
+      this.data = tagData(this.options.datafile, "provided");
+      this.transition("degraded");
+      return [this.data, "STALE"];
     }
-    if (this.bundledDefinitionsPromise) {
-      const bundledResult = await this.bundledDefinitionsPromise;
-      if (bundledResult?.state === "ok" && bundledResult.definitions) {
-        console.warn(
-          "@vercel/flags-core: Using bundled definitions as fallback"
-        );
-        this.data = bundledResult.definitions;
-        return [this.data, "embedded", "STALE"];
-      }
-    }
-    throw new Error(
-      "@vercel/flags-core: No flag definitions available. Ensure streaming/polling is enabled or provide a datafile."
-    );
-  }
-  /**
-   * Initializes from bundled definitions.
-   */
-  async initializeFromBundled() {
-    if (!this.bundledDefinitionsPromise) {
-      throw new Error(
-        "@vercel/flags-core: No flag definitions available. Ensure streaming/polling is enabled or provide a datafile."
-      );
+    const bundled = await this.bundledSource.tryLoad();
+    if (bundled) {
+      console.warn("@vercel/flags-core: Using bundled definitions as fallback");
+      this.data = tagData(bundled, "bundled");
+      this.transition("degraded");
+      return [this.data, "STALE"];
     }
-    const bundledResult = await this.bundledDefinitionsPromise;
-    if (bundledResult?.state === "ok" && bundledResult.definitions) {
-      this.data = bundledResult.definitions;
-      return;
+    if (!this.options.stream.enabled && !this.options.polling.enabled) {
+      try {
+        const fetched = await fetchDatafile({
+          host: this.options.host,
+          sdkKey: this.options.sdkKey,
+          fetch: this.options.fetch
+        });
+        this.data = tagData(fetched, "fetched");
+        this.transition("degraded");
+        return [this.data, "MISS"];
+      } catch {
+      }
     }
     throw new Error(
-      "@vercel/flags-core: No flag definitions available. Bundled definitions not found."
+      "@vercel/flags-core: No flag definitions available. Provide a datafile or bundled definitions."
     );
   }
-  /**
-   * Parses a configUpdatedAt value (number or string) into a numeric timestamp.
-   * Returns undefined if the value is missing or cannot be parsed.
-   */
-  static parseConfigUpdatedAt(value) {
-    if (typeof value === "number") return value;
-    if (typeof value === "string") {
-      const parsed = Number(value);
-      return Number.isNaN(parsed) ? void 0 : parsed;
-    }
-    return void 0;
-  }
+  // ---------------------------------------------------------------------------
+  // Data comparison
+  // ---------------------------------------------------------------------------
   /**
    * Checks if the incoming data is newer than the current in-memory data.
    * Returns true if the update should proceed, false if it should be skipped.
@@ -1408,50 +1835,47 @@ var FlagNetworkDataSource = class _FlagNetworkDataSource {
    * - The current data has no configUpdatedAt
    * - The incoming data has no configUpdatedAt
    *
-   * Skips the update only when both have configUpdatedAt and incoming is older.
+   * Skips the update only when both have configUpdatedAt and incoming is not newer.
    */
   isNewerData(incoming) {
     if (!this.data) return true;
-    const currentTs = _FlagNetworkDataSource.parseConfigUpdatedAt(
-      this.data.configUpdatedAt
-    );
-    const incomingTs = _FlagNetworkDataSource.parseConfigUpdatedAt(
-      incoming.configUpdatedAt
-    );
+    const currentTs = parseConfigUpdatedAt(this.data.configUpdatedAt);
+    const incomingTs = parseConfigUpdatedAt(incoming.configUpdatedAt);
     if (currentTs === void 0 || incomingTs === void 0) {
       return true;
     }
-    return incomingTs >= currentTs;
-  }
-  /**
-   * Logs a warning if returning cached data while stream is disconnected.
-   */
-  warnIfDisconnected() {
-    if (!this.isStreamConnected && !this.hasWarnedAboutStaleData) {
-      this.hasWarnedAboutStaleData = true;
-      console.warn(
-        "@vercel/flags-core: Returning in-memory flag definitions while stream is disconnected. Data may be stale."
-      );
-    }
+    return incomingTs > currentTs;
   }
   // ---------------------------------------------------------------------------
   // Usage tracking
   // ---------------------------------------------------------------------------
   /**
    * Tracks a read operation for usage analytics.
+   * During build steps, only the first read is tracked.
    */
   trackRead(startTime, cacheHadDefinitions, isFirstRead, source) {
+    if (this.unauthorized) return;
+    if (this.options.buildStep && this.buildReadTracked) return;
+    if (this.options.buildStep) this.buildReadTracked = true;
     const configOrigin = source === "embedded" ? "embedded" : "in-memory";
+    const cacheAction = this.state === "streaming" ? "FOLLOWING" : this.state === "polling" ? "REFRESHING" : "NONE";
+    const mode = this.mode;
     const trackOptions = {
       configOrigin,
       cacheStatus: cacheHadDefinitions ? "HIT" : "MISS",
+      cacheAction,
       cacheIsBlocking: !cacheHadDefinitions,
-      duration: Date.now() - startTime
+      duration: Date.now() - startTime,
+      mode: mode === "streaming" ? "stream" : mode === "polling" ? "poll" : mode
     };
     const configUpdatedAt = this.data?.configUpdatedAt;
     if (typeof configUpdatedAt === "number") {
       trackOptions.configUpdatedAt = configUpdatedAt;
     }
+    const revision = this.data?.revision;
+    if (typeof revision === "number") {
+      trackOptions.revision = revision;
+    }
     if (isFirstRead) {
       trackOptions.cacheIsFirstRead = true;
     }
@@ -1475,16 +1899,23 @@ function parseSdkKeyFromFlagsConnectionString(text) {
 function make(createRawClient) {
   let _defaultFlagsClient = null;
   function createClient2(sdkKeyOrConnectionString, options) {
-    if (!sdkKeyOrConnectionString) throw new Error("flags: Missing sdkKey");
+    if (!sdkKeyOrConnectionString)
+      throw new Error("@vercel/flags-core: Missing sdkKey");
+    if (typeof sdkKeyOrConnectionString !== "string")
+      throw new Error(
+        `@vercel/flags-core: Invalid sdkKey. Expected string, got ${typeof sdkKeyOrConnectionString}`
+      );
     const sdkKey = parseSdkKeyFromFlagsConnectionString(
       sdkKeyOrConnectionString
     );
     if (!sdkKey) {
-      throw new Error("flags: Missing sdkKey in connection string");
+      throw new Error(
+        "@vercel/flags-core: Missing sdkKey in connection string"
+      );
     }
-    const dataSource = new FlagNetworkDataSource({ sdkKey, ...options });
+    const controller = new Controller({ sdkKey, ...options });
     return createRawClient({
-      dataSource,
+      controller,
       origin: { provider: "vercel", sdkKey }
     });
   }
@@ -1499,7 +1930,7 @@ function make(createRawClient) {
         }
         const sdkKey = parseSdkKeyFromFlagsConnectionString(process.env.FLAGS);
         if (!sdkKey) {
-          throw new Error("flags: Missing sdkKey");
+          throw new Error("@vercel/flags-core: Missing sdkKey");
         }
         _defaultFlagsClient = createClient2(sdkKey);
       }
@@ -1530,16 +1961,16 @@ var {
    * Create a flags client based on an SDK Key
    */
   createClient
-} = make(createCreateRawClient(client_fns_exports));
+} = make(createCreateRawClient(controller_fns_exports));
 
 export {
   ResolutionReason,
   evaluate,
   FallbackNotFoundError,
   FallbackEntryNotFoundError,
-  FlagNetworkDataSource,
+  Controller,
   flagsClient,
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-EB6T2UJ6.js.map
+//# sourceMappingURL=chunk-J33BA25D.js.map