@vercel/flags-core 1.9.0 → 1.10.0-0037f35-20261006132750

package/dist/{chunk-SLNLPFKU.js → chunk-SYXANNZ4.js}

@@ -576,7 +576,7 @@ function bulkEvaluate(flags, shared) {
 }
 
 // package.json
-var version = "1.9.0";
+var version = "1.10.0-0037f35-20261006132750";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -1045,25 +1045,16 @@ import { getVercelOidcToken } from "@vercel/oidc";
 
 // src/utils/sdk-keys.ts
 var SDK_KEY_REGEX = /^vf_(?:server|client)_/;
-function isValidSdkKey(value) {
-  return SDK_KEY_REGEX.test(value);
-}
-var PROJECT_ID_REGEX = /^[A-Za-z0-9_]{1,64}$/;
-function isValidProjectId(value) {
-  return PROJECT_ID_REGEX.test(value);
-}
-function parseFlagsConnectionString(text) {
-  if (SDK_KEY_REGEX.test(text)) return { sdkKey: text, projectId: null };
-  if (!text.startsWith("flags:")) return null;
+function parseSdkKeyFromFlagsConnectionString(text) {
+  if (SDK_KEY_REGEX.test(text)) return text;
   try {
+    if (!text.startsWith("flags:")) return null;
     const params = new URLSearchParams(text.slice(6));
-    return {
-      sdkKey: params.get("sdkKey") || null,
-      projectId: params.get("projectId") || null
-    };
+    const sdkKey = params.get("sdkKey");
+    if (sdkKey && SDK_KEY_REGEX.test(sdkKey)) return sdkKey;
   } catch {
-    return null;
   }
+  return null;
 }
 
 // src/controller/auth.ts
@@ -1075,8 +1066,10 @@ function authHeaders(token, sourceProjectId) {
   };
 }
 function unauthorizedMessage(sourceProjectId) {
-  if (!sourceProjectId) return "unauthorized (401)";
-  return `unauthorized (401): this deployment is not allowed to read the flags of project "${sourceProjectId}". Check the connection string and that the project is connected.`;
+  if (!sourceProjectId) {
+    return "unauthorized (401)";
+  }
+  return `unauthorized (401): this deployment is not allowed to read the flags of project "${sourceProjectId}". Check that the project is connected.`;
 }
 async function getOidcToken() {
   try {
@@ -1116,27 +1109,13 @@ var Authentication = class {
           `@vercel/flags-core: Invalid sdkKey. Expected string, got ${typeof sdkKeyOrConnectionString}`
         );
       }
-      const parsed = parseFlagsConnectionString(sdkKeyOrConnectionString);
-      if (parsed?.sdkKey && parsed.projectId) {
-        throw new Error(
-          "@vercel/flags-core: A connection string must contain either sdkKey or projectId, not both"
-        );
-      }
-      if (parsed?.sdkKey) {
-        if (!isValidSdkKey(parsed.sdkKey)) {
-          throw new Error("@vercel/flags-core: Missing sdkKey");
-        }
-        this.sdkKey = parsed.sdkKey;
-      } else if (parsed?.projectId) {
-        if (!isValidProjectId(parsed.projectId)) {
-          throw new Error(
-            "@vercel/flags-core: Invalid projectId in connection string"
-          );
-        }
-        this.sourceProjectId = parsed.projectId;
-      } else {
+      const parsed = parseSdkKeyFromFlagsConnectionString(
+        sdkKeyOrConnectionString
+      );
+      if (!parsed) {
         throw new Error("@vercel/flags-core: Missing sdkKey");
       }
+      this.sdkKey = parsed;
     }
   }
   async resolveToken() {
@@ -1175,6 +1154,43 @@ function getJitteredWaitMs(baseMs, ratio) {
   return Math.floor(min + Math.random() * span);
 }
 
+// src/utils/debug-enabled.ts
+var NAMESPACE = "@vercel/flags-core";
+var lastValue;
+var lastEnabled = false;
+function matches(pattern, namespace) {
+  if (!pattern.includes("*")) {
+    return pattern === namespace;
+  }
+  const expression = pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+  return new RegExp(`^${expression}$`).test(namespace);
+}
+function isDebugEnabled() {
+  const value = process.env.DEBUG;
+  if (value === lastValue) {
+    return lastEnabled;
+  }
+  let enabled = false;
+  if (value) {
+    for (const entry of value.split(/[\s,]+/)) {
+      if (!entry) {
+        continue;
+      }
+      if (entry.startsWith("-")) {
+        if (matches(entry.slice(1), NAMESPACE)) {
+          enabled = false;
+          break;
+        }
+      } else if (matches(entry, NAMESPACE)) {
+        enabled = true;
+      }
+    }
+  }
+  lastValue = value;
+  lastEnabled = enabled;
+  return enabled;
+}
+
 // src/utils/runtime-ingest.ts
 var FLAGS_CONTEXT_SYMBOL = /* @__PURE__ */ Symbol.for("@vercel/flags-context");
 function getRuntimeIngestFor(auth) {
@@ -1194,9 +1210,8 @@ var MAX_RETRIES = 3;
 var MAX_EVENTS_PER_REQUEST = 2e3;
 var EVALUATING_OIDC_TOKEN_HEADER = "X-Vercel-Flags-OIDC-Token";
 var FLUSH_REASON_HEADER = "X-Vercel-Flags-Flush-Reason";
-var isDebugMode = process.env.DEBUG?.includes("@vercel/flags-core");
 var debugLog = (...args) => {
-  if (!isDebugMode) return;
+  if (!isDebugEnabled()) return;
   console.log(...args);
 };
 async function getEvaluatingOidcToken(auth) {
@@ -1219,7 +1234,7 @@ async function getIngestHeaders(options, flushReason) {
       "X-Vercel-Env": options.metricEnvironment ?? process.env.VERCEL_ENV
     } : null,
     ...evaluatingOidcToken ? { [EVALUATING_OIDC_TOKEN_HEADER]: evaluatingOidcToken } : null,
-    ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
+    ...isDebugEnabled() ? { "x-vercel-debug-ingest": "1" } : null
   };
 }
 function getRuntimeIngestHeaders(options, flushReason) {
@@ -1231,7 +1246,7 @@ function getRuntimeIngestHeaders(options, flushReason) {
     ...options.metricEnvironment ?? process.env.VERCEL_ENV ? {
       "X-Vercel-Env": options.metricEnvironment ?? process.env.VERCEL_ENV
     } : null,
-    ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
+    ...isDebugEnabled() ? { "x-vercel-debug-ingest": "1" } : null
   };
 }
 async function sendIngestEvents(options, events, flushId, flushReason) {
@@ -1647,6 +1662,391 @@ var BundledSource = class {
   }
 };
 
+// src/controller/debug.ts
+function debug(clientName, event, details) {
+  if (!isDebugEnabled()) {
+    return;
+  }
+  try {
+    console.debug("@vercel/flags-core", { event, clientName, ...details?.() });
+  } catch {
+  }
+}
+
+// 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/datafile-cache.ts
+var SOURCE_CONFIRMED = new Error(
+  "Refresh superseded by a source confirmation"
+);
+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 DatafileCache = class {
+  constructor(fetch, staleIfErrorMs = Infinity, waitUntil3 = () => {
+  }, clientName) {
+    this.fetch = fetch;
+    this.staleIfErrorMs = staleIfErrorMs;
+    this.waitUntil = waitUntil3;
+    this.clientName = clientName;
+  }
+  fetch;
+  staleIfErrorMs;
+  waitUntil;
+  clientName;
+  data;
+  // Confirmations refresh age without rewriting the datafile's persisted fetch time.
+  freshAt;
+  failure;
+  abortController = new AbortController();
+  fetching;
+  debugState = () => ({
+    projectId: this.data?.projectId,
+    environment: this.data?.environment,
+    hasData: this.hasData,
+    origin: this.data?._origin,
+    revision: this.revision,
+    configUpdatedAt: parseConfigUpdatedAt(this.data?.configUpdatedAt),
+    ageMs: this.ageMs,
+    failed: this.failure !== void 0,
+    failureAgeMs: this.failure ? Date.now() - this.failure.startedAt : void 0,
+    staleIfErrorMs: this.staleIfErrorMs,
+    canServe: this.hasData && this.canServe(),
+    fetching: this.fetching !== void 0
+  });
+  /** Expired data still exists; fallback loading must not bypass its failure policy. */
+  get hasData() {
+    return this.data !== void 0;
+  }
+  /** Retained revisions remain available for reconnecting after serving expires. */
+  get revision() {
+    return this.data?.revision;
+  }
+  /** Time since the latest freshness evidence, if known. */
+  get ageMs() {
+    return this.freshAt === void 0 ? Infinity : Math.max(0, Date.now() - this.freshAt);
+  }
+  /** Records freshness evidence without confirming recovery from a failure. */
+  resetAge() {
+    if (this.data) this.freshAt = Date.now();
+  }
+  /** Freshness checks can inspect retained metadata even after serving expires. */
+  get metadata() {
+    if (!this.data) return void 0;
+    const { projectId, environment, configUpdatedAt, revision } = this.data;
+    return {
+      projectId,
+      environment,
+      configUpdatedAt,
+      revision,
+      ageMs: this.ageMs
+    };
+  }
+  /** Stores initial or fallback data without confirming recovery from a failure. */
+  seed(data) {
+    this.data = data;
+    this.freshAt = typeof data.fetchedAt === "number" && Number.isFinite(data.fetchedAt) && data.fetchedAt >= 0 ? data.fetchedAt : void 0;
+    debug(this.clientName, "cache.seed", this.debugState);
+  }
+  /** Stores data and returns it through the serving boundary. */
+  seedAndRead(data) {
+    this.seed(data);
+    const seeded = this.read();
+    if (!seeded) {
+      throw new Error("@vercel/flags-core: Seeded definitions unavailable");
+    }
+    return seeded;
+  }
+  /**
+   * Accepts a newer source response, or keeps the stored data when the version
+   * guard rejects it. Every successful response proves the source is reachable,
+   * so it renews cache age and clears the failure either way.
+   */
+  updateFromSource(incoming, origin) {
+    if (this.isNewerData(incoming)) {
+      this.data = tagData({ ...incoming, fetchedAt: Date.now() }, origin);
+      this.confirm(origin);
+      debug(this.clientName, "cache.update.accepted", this.debugState);
+      return;
+    }
+    this.confirm(origin);
+    debug(this.clientName, "cache.update.ignored", () => ({
+      ...this.debugState(),
+      incomingOrigin: origin,
+      incomingRevision: incoming.revision,
+      incomingConfigUpdatedAt: parseConfigUpdatedAt(incoming.configUpdatedAt)
+    }));
+  }
+  /** Confirms a same-version message without replacing stored data. */
+  tryConfirm(incoming, version2 = "configUpdatedAt", source = "header") {
+    if (!this.matchesStored(incoming, version2)) {
+      return false;
+    }
+    this.confirm(source);
+    debug(this.clientName, "cache.confirmed", () => ({
+      version: version2,
+      source,
+      ...this.debugState()
+    }));
+    return true;
+  }
+  /** Whether a message refers to the stored entry: finite equal version and same identity. */
+  matchesStored(incoming, version2) {
+    if (!this.data) {
+      return false;
+    }
+    const currentTs = version2 === "revision" ? this.data.revision : parseConfigUpdatedAt(this.data.configUpdatedAt);
+    const incomingTs = version2 === "revision" ? incoming.revision : parseConfigUpdatedAt(incoming.configUpdatedAt);
+    return Number.isFinite(currentTs) && Number.isFinite(incomingTs) && currentTs === incomingTs && this.data.projectId === incoming.projectId && this.data.environment === incoming.environment;
+  }
+  /** Renews freshness and retires HTTP work superseded by stream evidence. */
+  confirm(source = "header") {
+    const recovered = this.failure !== void 0;
+    this.resetAge();
+    this.failure = void 0;
+    if (recovered) {
+      debug(this.clientName, "cache.recovered", this.debugState);
+    }
+    if (source === "stream" && this.fetching) {
+      debug(this.clientName, "cache.fetch.cancel", () => ({
+        reason: "source-confirmed",
+        ...this.debugState()
+      }));
+      this.abortController.abort(SOURCE_CONFIRMED);
+      this.abortController = new AbortController();
+      this.fetching = void 0;
+    }
+  }
+  /** Preserves existing acceptance, including missing or unparseable versions. */
+  isNewerData(incoming) {
+    if (!this.data) return true;
+    const currentTs = parseConfigUpdatedAt(this.data.configUpdatedAt);
+    const incomingTs = parseConfigUpdatedAt(incoming.configUpdatedAt);
+    if (currentTs === void 0 || incomingTs === void 0) {
+      return true;
+    }
+    return incomingTs > currentTs;
+  }
+  fail(error) {
+    const repeated = this.failure !== void 0;
+    this.failure ??= { error, startedAt: Date.now() };
+    debug(this.clientName, "cache.failure", () => ({
+      repeated,
+      ...this.debugState()
+    }));
+  }
+  canServe() {
+    if (!this.failure || this.staleIfErrorMs === Infinity) return true;
+    return this.staleIfErrorMs > 0 && Date.now() - this.failure.startedAt <= this.staleIfErrorMs;
+  }
+  /** The serving boundary for both snapshot and policy-driven reads. */
+  read() {
+    if (!this.data) return void 0;
+    if (!this.canServe()) {
+      debug(this.clientName, "cache.stale-if-error.expired", this.debugState);
+      throw this.failure.error;
+    }
+    return this.data;
+  }
+  async resolve(policy) {
+    const metadata = this.metadata;
+    if (metadata) {
+      const { status, confirmed } = policy.assess(metadata);
+      if (status === "error") {
+        debug(this.clientName, "cache.source-error", this.debugState);
+        return {
+          data: this.canServe() ? this.read() : void 0,
+          status: "STALE",
+          hasError: true
+        };
+      }
+      if (confirmed) this.confirm();
+      debug(this.clientName, "cache.freshness", () => ({
+        status,
+        confirmed: confirmed === true,
+        ...this.debugState()
+      }));
+      if (status === "fresh" || status === "unknown") {
+        return {
+          data: this.read(),
+          status: status === "fresh" && !this.failure ? "HIT" : "STALE"
+        };
+      }
+      if (this.failure) {
+        if (!policy.retryOnFailure) {
+          debug(this.clientName, "cache.stale-if-error", () => ({
+            ...this.debugState(),
+            recovery: "scheduled-source-update"
+          }));
+          return { data: this.read(), status: "STALE" };
+        }
+        if (this.canServe()) {
+          const stale = this.read();
+          debug(this.clientName, "cache.refresh.background", () => ({
+            ...this.debugState(),
+            reason: "retry-after-failure"
+          }));
+          this.fetchInBackground();
+          return { data: stale, status: "STALE" };
+        }
+      }
+      if (status === "stale" && this.canServe()) {
+        const stale = this.read();
+        if (!policy.revalidate) {
+          debug(this.clientName, "cache.refresh.background", () => ({
+            ...this.debugState(),
+            reason: "stale"
+          }));
+          this.fetchInBackground();
+        }
+        return { data: stale, status: "STALE" };
+      }
+      if (policy.revalidate) {
+        return this.resolveThroughSource(policy);
+      }
+    }
+    debug(this.clientName, "cache.refresh.blocking", () => ({
+      ...this.debugState(),
+      reason: !metadata ? "empty-cache" : "expired"
+    }));
+    const { promise, signal } = this.startFetch("fetched");
+    try {
+      await promise;
+      signal.throwIfAborted();
+    } catch (error) {
+      if (signal.aborted) {
+        if (signal.reason === SOURCE_CONFIRMED && this.data) {
+          debug(this.clientName, "cache.refresh.superseded", this.debugState);
+          return { data: this.read(), status: "HIT" };
+        }
+        throw error;
+      }
+      const stale = this.read();
+      if (!stale) {
+        throw error;
+      }
+      debug(this.clientName, "cache.stale-if-error", () => ({
+        ...this.debugState(),
+        recovery: "refresh-failed"
+      }));
+      return { data: stale, status: "STALE" };
+    }
+    if (!metadata && this.metadata) {
+      const { confirmed } = policy.assess(this.metadata);
+      if (confirmed) this.confirm();
+    }
+    const data = this.read();
+    if (!data) {
+      throw new Error("@vercel/flags-core: Fetch returned no definitions");
+    }
+    return { data, status: "MISS" };
+  }
+  /**
+   * Waits for the live source to confirm or replace the cache, then serves
+   * whatever it left behind. A failed or silent source leaves the failure
+   * policy to decide; the source's own fallback path takes over from there.
+   */
+  async resolveThroughSource(policy) {
+    await policy.revalidate?.().catch(() => {
+    });
+    const data = this.read();
+    const metadata = this.metadata;
+    if (!data || !metadata) {
+      throw new Error("@vercel/flags-core: Definitions unavailable");
+    }
+    const { status } = policy.assess(metadata);
+    return {
+      data,
+      status: status === "fresh" && !this.failure ? "HIT" : "STALE"
+    };
+  }
+  /** Runs the one shared datafile refresh used by reads and polling. */
+  refresh(origin = "fetched") {
+    return this.startFetch(origin).promise;
+  }
+  startFetch(origin) {
+    const { signal } = this.abortController;
+    if (this.fetching) {
+      debug(this.clientName, "cache.fetch.shared", () => ({
+        requestedOrigin: origin,
+        ...this.debugState()
+      }));
+      return { promise: this.fetching, signal };
+    }
+    debug(this.clientName, "cache.fetch.start", () => ({
+      requestedOrigin: origin,
+      ...this.debugState()
+    }));
+    const promise = Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return this.fetch(signal);
+    }).then((data) => {
+      signal.throwIfAborted();
+      this.updateFromSource(data, origin);
+      debug(this.clientName, "cache.fetch.applied", this.debugState);
+    }).catch((error) => {
+      if (signal.aborted) {
+        debug(this.clientName, "cache.fetch.aborted", () => ({
+          reason: signal.reason === SOURCE_CONFIRMED ? "source-confirmed" : "cache-cleared"
+        }));
+      }
+      signal.throwIfAborted();
+      const err = error instanceof Error ? error : new Error("Unknown fetch error");
+      this.fail(err);
+      debug(this.clientName, "cache.fetch.failed", this.debugState);
+      throw err;
+    }).finally(() => {
+      if (this.abortController.signal === signal) {
+        this.fetching = void 0;
+      }
+    });
+    this.fetching = promise;
+    return { promise, signal };
+  }
+  fetchInBackground() {
+    const { promise, signal } = this.startFetch("fetched");
+    const background = promise.catch((error) => {
+      if (!signal.aborted) {
+        console.error("@vercel/flags-core: Revalidation failed:", error);
+      }
+    });
+    try {
+      this.waitUntil(background);
+    } catch {
+    }
+  }
+  /** Resets storage, age, and the failure deadline so a restarted client begins clean. */
+  clear() {
+    debug(this.clientName, "cache.clear", this.debugState);
+    this.abortController.abort();
+    this.abortController = new AbortController();
+    this.fetching = void 0;
+    this.data = void 0;
+    this.freshAt = void 0;
+    this.failure = void 0;
+  }
+};
+
 // src/controller/fetch-datafile.ts
 var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_ATTEMPTS = 3;
@@ -1666,6 +2066,10 @@ async function fetchDatafile(options) {
   if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
     throw new Error("maxAttempts must be a positive integer");
   }
+  debug(options.clientName, "datafile.fetch.start", () => ({
+    maxAttempts,
+    timeoutMs: DEFAULT_FETCH_TIMEOUT_MS
+  }));
   const controller = new AbortController();
   const { signal } = controller;
   let rejectAbort;
@@ -1676,15 +2080,24 @@ async function fetchDatafile(options) {
   signal.addEventListener("abort", onAbort, { once: true });
   const onExternalAbort = () => controller.abort(options.signal?.reason);
   options.signal?.addEventListener("abort", onExternalAbort, { once: true });
-  const timeoutId = setTimeout(
-    () => controller.abort(
+  const timeoutId = setTimeout(() => {
+    debug(options.clientName, "datafile.fetch.timeout", () => ({
+      timeoutMs: DEFAULT_FETCH_TIMEOUT_MS
+    }));
+    controller.abort(
       new Error("@vercel/flags-core: Datafile fetch deadline exceeded")
-    ),
-    DEFAULT_FETCH_TIMEOUT_MS
-  );
+    );
+  }, DEFAULT_FETCH_TIMEOUT_MS);
   let delay;
-  const fetchAttempt = async () => {
-    const token = await options.auth.resolveToken();
+  const fetchAttempt = async (attempt) => {
+    debug(options.clientName, "datafile.fetch.attempt", () => ({
+      attempt,
+      maxAttempts
+    }));
+    const token = await options.auth.resolveToken().catch((error) => {
+      debug(options.clientName, "datafile.auth.failed", () => ({ attempt }));
+      throw error;
+    });
     signal.throwIfAborted();
     const res = await options.fetch(`${options.host}/v1/datafile`, {
       headers: {
@@ -1695,6 +2108,10 @@ async function fetchDatafile(options) {
       signal
     });
     signal.throwIfAborted();
+    debug(options.clientName, "datafile.fetch.response", () => ({
+      attempt,
+      status: res.status
+    }));
     if (!res.ok) {
       void res.body?.cancel().catch(() => {
       });
@@ -1705,6 +2122,12 @@ async function fetchDatafile(options) {
     }
     const data = await res.json();
     signal.throwIfAborted();
+    debug(options.clientName, "datafile.fetch.complete", () => ({
+      attempt,
+      projectId: data.projectId,
+      revision: data.revision,
+      configUpdatedAt: Number(data.configUpdatedAt)
+    }));
     return data;
   };
   try {
@@ -1719,14 +2142,31 @@ async function fetchDatafile(options) {
       }
       signal.throwIfAborted();
       try {
-        return await Promise.race([fetchAttempt(), aborted]);
+        return await Promise.race([fetchAttempt(attempt + 1), aborted]);
       } catch (error) {
         signal.throwIfAborted();
         if (attempt === maxAttempts - 1 || error instanceof DatafileHttpError && !error.retryable) {
           throw error instanceof Error ? error : new Error("Unknown fetch error");
         }
+        debug(options.clientName, "datafile.fetch.retry", () => ({
+          nextAttempt: attempt + 2,
+          delayMs: 100 * 2 ** attempt,
+          status: error instanceof DatafileHttpError ? error.status : void 0
+        }));
       }
     }
+  } catch (error) {
+    if (signal.aborted) {
+      debug(options.clientName, "datafile.fetch.aborted", () => ({
+        // The internal deadline aborts too; only the caller's signal is external.
+        reason: options.signal?.aborted ? "external" : "timeout"
+      }));
+    } else {
+      debug(options.clientName, "datafile.fetch.failed", () => ({
+        status: error instanceof DatafileHttpError ? error.status : void 0
+      }));
+    }
+    throw error;
   } finally {
     clearTimeout(timeoutId);
     clearTimeout(delay);
@@ -1735,13 +2175,79 @@ async function fetchDatafile(options) {
   }
 }
 
+// src/controller/header-source.ts
+var HeaderSource = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  highestObserved = 0;
+  getVersionHeader() {
+    const { headers } = getRequestContext();
+    return headers?.["x-vercel-flags-config-versions"] ?? headers?.["flags-config-versions"];
+  }
+  /** Capture the header now so a shared fetch cannot switch the request being assessed. */
+  getAssessment() {
+    const header = this.getVersionHeader();
+    return (data) => {
+      const headerTs = this.getUpdatedAtHeader(data.projectId, header);
+      debug(this.options.clientName, "header.observed", () => ({
+        projectId: data.projectId,
+        hasHeader: Boolean(header),
+        headerTimestamp: headerTs,
+        configUpdatedAt: Number(data.configUpdatedAt),
+        previousHighestObserved: this.highestObserved,
+        staleWhileRevalidateMs: this.options.staleWhileRevalidateMs
+      }));
+      if (headerTs === void 0) {
+        return { status: "error" };
+      }
+      const currentTs = Number(data.configUpdatedAt);
+      this.highestObserved = Math.max(this.highestObserved, headerTs);
+      if (!Number.isFinite(currentTs) || currentTs <= 0) {
+        return { status: "error" };
+      }
+      if (headerTs <= currentTs) {
+        return {
+          status: "fresh",
+          confirmed: headerTs === currentTs && headerTs === this.highestObserved
+        };
+      }
+      const { staleWhileRevalidateMs } = this.options;
+      return {
+        status: staleWhileRevalidateMs > 0 && data.ageMs <= staleWhileRevalidateMs ? "stale" : "expired"
+      };
+    };
+  }
+  getUpdatedAtHeader(projectId, header) {
+    if (!header) return;
+    const prefix = `flags_${projectId}=`;
+    const value = header.split(";").map((part) => part.trim()).find((part) => part.startsWith(prefix))?.slice(prefix.length);
+    const timestamp = Number(value);
+    return Number.isFinite(timestamp) && timestamp > 0 ? timestamp : void 0;
+  }
+  isEnabled() {
+    return this.options.vercel && (this.options.stream.enabled || this.options.polling.enabled);
+  }
+  stop() {
+    this.highestObserved = 0;
+  }
+};
+
 // src/controller/normalized-options.ts
 import { waitUntil as defaultWaitUntil2 } from "@vercel/functions";
 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;
+var DEFAULT_STALE_WHILE_REVALIDATE = 10;
 function normalizeOptions(options) {
+  const staleIfError = options.staleIfError ?? Infinity;
+  if (typeof staleIfError !== "number" || !(staleIfError >= 0)) {
+    throw new Error(
+      "@vercel/flags-core: staleIfError must be a nonnegative number of seconds or Infinity."
+    );
+  }
   const autoDetectedBuildStep = process.env.CI === "1" || process.env.NEXT_PHASE === "phase-production-build";
   const buildStep = options.buildStep ?? autoDetectedBuildStep;
   let stream;
@@ -1773,11 +2279,20 @@ function normalizeOptions(options) {
       initTimeoutMs: options.polling.initTimeoutMs
     };
   }
+  const staleWhileRevalidate = options.staleWhileRevalidate ?? DEFAULT_STALE_WHILE_REVALIDATE;
+  if (!Number.isFinite(staleWhileRevalidate) || staleWhileRevalidate < 0) {
+    throw new Error(
+      "@vercel/flags-core: staleWhileRevalidate must be a finite, non-negative number of seconds."
+    );
+  }
   return {
     auth: options.auth,
     datafile: options.datafile,
     stream,
     polling,
+    vercel: options.vercel ?? process.env.VERCEL === "1",
+    staleWhileRevalidateMs: staleWhileRevalidate * 1e3,
+    staleIfErrorMs: staleIfError * 1e3,
     buildStep,
     fetch: options.fetch ?? globalThis.fetch,
     waitUntil: options.waitUntil ?? defaultWaitUntil2,
@@ -1822,29 +2337,63 @@ var PollingSource = class extends TypedEmitter {
   config;
   intervalId;
   abortController;
+  polling;
   constructor(config) {
     super();
     this.config = config;
   }
+  /** Allow the scheduled poll its entire fetch deadline before revalidating. */
+  get staleAfterMs() {
+    return this.config.polling.intervalMs + DEFAULT_FETCH_TIMEOUT_MS;
+  }
+  /** Age after which reads block on a refresh. */
+  get expiresAfterMs() {
+    return this.staleAfterMs + this.config.staleWhileRevalidateMs;
+  }
+  assess = ({ ageMs }) => {
+    if (ageMs === Infinity) {
+      return { status: "unknown" };
+    }
+    if (ageMs <= this.staleAfterMs) {
+      return { status: "fresh" };
+    }
+    if (ageMs <= this.expiresAfterMs) {
+      return { status: "stale" };
+    }
+    return { status: "expired" };
+  };
   /**
    * Perform a single poll request.
-   * Emits 'data' on success, 'error' on failure.
+   * Updates the cache on success; emits 'error' and rejects on failure.
    */
   async poll() {
+    if (this.polling) {
+      debug(this.config.clientName, "poll.shared");
+      return this.polling;
+    }
     if (this.abortController?.signal.aborted) return;
     this.abortController ??= new AbortController();
     const controller = this.abortController;
-    try {
-      const data = await fetchDatafile({
-        ...this.config,
-        signal: controller.signal
-      });
-      this.emit("data", data);
-    } catch (error) {
-      controller.signal.throwIfAborted();
-      const err = error instanceof Error ? error : new Error("Unknown poll error");
-      this.emit("error", err);
-    }
+    debug(this.config.clientName, "poll.start");
+    this.polling = (async () => {
+      try {
+        await this.config.refresh();
+        controller.signal.throwIfAborted();
+        debug(this.config.clientName, "poll.complete");
+      } catch (error) {
+        debug(
+          this.config.clientName,
+          controller.signal.aborted ? "poll.aborted" : "poll.failed"
+        );
+        controller.signal.throwIfAborted();
+        const err = error instanceof Error ? error : new Error("Unknown poll error");
+        this.emit("error", err);
+        throw err;
+      }
+    })().finally(() => {
+      if (this.abortController === controller) this.polling = void 0;
+    });
+    return this.polling;
   }
   /**
    * Start interval-based polling.
@@ -1853,6 +2402,11 @@ var PollingSource = class extends TypedEmitter {
    */
   startInterval() {
     if (this.intervalId) return;
+    debug(this.config.clientName, "poll.interval.start", () => ({
+      intervalMs: this.config.polling.intervalMs,
+      staleAfterMs: this.config.polling.intervalMs + DEFAULT_FETCH_TIMEOUT_MS,
+      expiresAfterMs: 2 * this.config.polling.intervalMs + DEFAULT_FETCH_TIMEOUT_MS
+    }));
     this.intervalId = setInterval(
       () => void this.poll().catch(() => {
       }),
@@ -1863,12 +2417,18 @@ var PollingSource = class extends TypedEmitter {
    * Stop interval-based polling.
    */
   stop() {
+    if (this.intervalId || this.polling) {
+      debug(this.config.clientName, "poll.stop", () => ({
+        pendingPoll: this.polling !== void 0
+      }));
+    }
     if (this.intervalId) {
       clearInterval(this.intervalId);
       this.intervalId = void 0;
     }
     this.abortController?.abort();
     this.abortController = void 0;
+    this.polling = void 0;
   }
 };
 
@@ -1886,7 +2446,9 @@ function sleep(ms) {
 var MAX_RETRY_COUNT = 15;
 var BASE_RETRY_DELAY_MS = 1e3;
 var MAX_RETRY_DELAY_MS = 6e4;
-var PING_TIMEOUT_MS = 9e4;
+var PING_MS = 3e4;
+var PING_TIMEOUT_MS = PING_MS * 3;
+var PING_TIMEOUT = new Error("stream: ping timeout");
 function backoff(retryCount) {
   if (retryCount === 1) return 0;
   const delay = Math.min(
@@ -1909,9 +2471,15 @@ var TokenResolutionError = class extends Error {
 };
 async function connectStream(config, callbacks) {
   const { host, abortController, fetch: fetchFn = globalThis.fetch } = config;
-  const { onDatafile, onPrimed, onDisconnect } = callbacks;
+  const { onDatafile, onPrimed, onPing, onDisconnect, onError, onConnection } = callbacks;
   let retryCount = 0;
   let lastAttemptTime = 0;
+  const reportError = (error) => {
+    if (abortController.signal.aborted) return;
+    onError?.(
+      error instanceof Error ? error : new Error("Unknown stream error", { cause: error })
+    );
+  };
   let resolveInit;
   let rejectInit;
   const initPromise = new Promise((resolve, reject) => {
@@ -1923,6 +2491,9 @@ async function connectStream(config, callbacks) {
     let lastError;
     while (!abortController.signal.aborted) {
       if (retryCount > MAX_RETRY_COUNT) {
+        debug(config.clientName, "stream.retries.exhausted", () => ({
+          retryCount
+        }));
         console.error(
           "@vercel/flags-core: Max retry count exceeded",
           lastError ?? "stream closed repeatedly without an error"
@@ -1932,6 +2503,8 @@ async function connectStream(config, callbacks) {
             new Error("stream: max retry count exceeded before receiving data")
           );
         }
+        reportError(new Error("stream: max retry count exceeded"));
+        onDisconnect?.();
         abortController.abort();
         break;
       }
@@ -1940,20 +2513,24 @@ async function connectStream(config, callbacks) {
       abortController.signal.addEventListener("abort", onMainAbort, {
         once: true
       });
+      onConnection?.(() => connectionAbort.abort(PING_TIMEOUT));
       let pingTimeoutId;
-      let responseBody;
       const resetPingTimeout = () => {
         if (pingTimeoutId !== void 0) clearTimeout(pingTimeoutId);
         if (!initialDataReceived) return;
         pingTimeoutId = setTimeout(() => {
-          responseBody?.cancel().catch(() => {
-          });
-          connectionAbort.abort();
+          debug(config.clientName, "stream.ping.timeout", () => ({
+            timeoutMs: PING_TIMEOUT_MS
+          }));
+          lastError = PING_TIMEOUT;
+          connectionAbort.abort(PING_TIMEOUT);
         }, PING_TIMEOUT_MS);
       };
       try {
+        debug(config.clientName, "stream.connect", () => ({ retryCount }));
         lastAttemptTime = Date.now();
         const token = await config.resolveToken().catch((error) => {
+          debug(config.clientName, "stream.auth.failed");
           throw new TokenResolutionError(error);
         });
         const headers = {
@@ -1976,20 +2553,26 @@ async function connectStream(config, callbacks) {
           headers,
           signal: connectionAbort.signal
         });
-        if (!response.ok) {
-          if (response.status === 401) {
-            if (!initialDataReceived) {
-              rejectInit(new UnauthorizedError(config.sourceProjectId));
-            }
-            abortController.abort();
-            break;
+        debug(config.clientName, "stream.response", () => ({
+          status: response.status,
+          revision
+        }));
+        if (!response.ok && response.status === 401) {
+          const error = new UnauthorizedError(config.sourceProjectId);
+          reportError(error);
+          if (!initialDataReceived) {
+            rejectInit(error);
           }
+          onDisconnect?.();
+          abortController.abort();
+          break;
+        }
+        if (!response.ok) {
           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();
         const bufferChunks = [];
@@ -2000,10 +2583,13 @@ async function connectStream(config, callbacks) {
         connectionAbort.signal.addEventListener("abort", onConnectionAbort, {
           once: true
         });
+        resetPingTimeout();
         try {
           while (true) {
             const { done, value: chunk } = await reader.read();
-            if (done || abortController.signal.aborted) break;
+            if (done || connectionAbort.signal.aborted) {
+              break;
+            }
             bufferChunks.push(decoder.decode(chunk, { stream: true }));
             const combined = bufferChunks.join("");
             bufferChunks.length = 0;
@@ -2039,6 +2625,7 @@ async function connectStream(config, callbacks) {
                 resetPingTimeout();
               }
               if (message.type === "ping" && initialDataReceived) {
+                onPing?.();
                 retryCount = 0;
                 resetPingTimeout();
               }
@@ -2053,11 +2640,19 @@ async function connectStream(config, callbacks) {
         clearTimeout(pingTimeoutId);
         abortController.signal.removeEventListener("abort", onMainAbort);
         if (!abortController.signal.aborted) {
-          onDisconnect?.();
+          if (connectionAbort.signal.reason !== PING_TIMEOUT) {
+            onDisconnect?.();
+          }
           retryCount++;
           const elapsed = Date.now() - lastAttemptTime;
           const minGap = Math.max(0, BASE_RETRY_DELAY_MS - elapsed);
-          await sleep(Math.max(backoff(retryCount), minGap));
+          const delayMs = Math.max(backoff(retryCount), minGap);
+          debug(config.clientName, "stream.reconnect", () => ({
+            retryCount,
+            delayMs,
+            reason: connectionAbort.signal.reason === PING_TIMEOUT ? "ping-timeout" : "connection-closed"
+          }));
+          await sleep(delayMs);
           continue;
         }
       } catch (error) {
@@ -2066,19 +2661,28 @@ async function connectStream(config, callbacks) {
         if (abortController.signal.aborted) {
           break;
         }
+        if (connectionAbort.signal.reason !== PING_TIMEOUT) {
+          reportError(error);
+        }
         if (error instanceof TokenResolutionError && !initialDataReceived) {
           rejectInit(error.cause);
           abortController.abort();
           break;
         }
-        if (!connectionAbort.signal.aborted) {
+        if (connectionAbort.signal.reason !== PING_TIMEOUT) {
           lastError = error;
+          onDisconnect?.();
         }
-        onDisconnect?.();
         retryCount++;
         const elapsed = Date.now() - lastAttemptTime;
         const minGap = Math.max(0, BASE_RETRY_DELAY_MS - elapsed);
-        await sleep(Math.max(backoff(retryCount), minGap));
+        const delayMs = Math.max(backoff(retryCount), minGap);
+        debug(config.clientName, "stream.reconnect", () => ({
+          retryCount,
+          delayMs,
+          reason: connectionAbort.signal.reason === PING_TIMEOUT ? "ping-timeout" : "connection-error"
+        }));
+        await sleep(delayMs);
       }
     }
     if (!initialDataReceived) {
@@ -2089,16 +2693,105 @@ async function connectStream(config, callbacks) {
 }
 
 // src/controller/stream-source.ts
+var STREAM_FRESH_MS = PING_MS * 2;
 var StreamSource = class extends TypedEmitter {
   options;
   revision;
   abortController;
   promise;
+  reconnect;
+  connectionStartedAt = 0;
+  revalidation;
   constructor(options, revision) {
     super();
     this.options = options;
     this.revision = revision;
   }
+  /** Age after which reads revalidate in the background. */
+  get staleAfterMs() {
+    return STREAM_FRESH_MS;
+  }
+  /** Age after which reads block on a refresh. */
+  get expiresAfterMs() {
+    return STREAM_FRESH_MS + this.options.staleWhileRevalidateMs;
+  }
+  /** The connection loop is connecting or connected; false once it gave up or was stopped. */
+  get active() {
+    return this.abortController !== void 0;
+  }
+  /**
+   * Drops a connection that has been silent beyond the fresh window and
+   * resolves once the stream delivers any message, which confirms or replaces
+   * the cache through the usual events. A younger connection, such as the
+   * replacement a ping timeout just opened, is kept and awaited instead.
+   * Rejects when the stream disconnects, gives up, is stopped, or stays silent
+   * for the fetch deadline. Concurrent callers share one wait.
+   */
+  revalidate() {
+    if (this.revalidation) {
+      return this.revalidation.promise;
+    }
+    if (!this.active) {
+      return Promise.reject(new Error("stream: not active"));
+    }
+    let cleanup = () => {
+    };
+    let fail = (_error) => {
+    };
+    const promise = new Promise((resolve, reject) => {
+      const confirmed = () => {
+        cleanup();
+        resolve();
+      };
+      fail = (error) => {
+        cleanup();
+        reject(error);
+      };
+      const interrupted = () => {
+        fail(new Error("stream: revalidation interrupted"));
+      };
+      const timer = setTimeout(() => {
+        fail(new Error("stream: revalidation timed out"));
+      }, DEFAULT_FETCH_TIMEOUT_MS);
+      cleanup = () => {
+        clearTimeout(timer);
+        this.off("data", confirmed);
+        this.off("primed", confirmed);
+        this.off("ping", confirmed);
+        this.off("disconnected", interrupted);
+        this.off("exhausted", interrupted);
+      };
+      this.on("data", confirmed);
+      this.on("primed", confirmed);
+      this.on("ping", confirmed);
+      this.on("disconnected", interrupted);
+      this.on("exhausted", interrupted);
+    });
+    const revalidation = { promise, fail };
+    this.revalidation = revalidation;
+    void promise.catch(() => {
+    }).finally(() => {
+      if (this.revalidation === revalidation) {
+        this.revalidation = void 0;
+      }
+    });
+    if (Date.now() - this.connectionStartedAt >= STREAM_FRESH_MS) {
+      this.reconnect?.();
+    }
+    return promise;
+  }
+  assess = ({ ageMs }) => {
+    if (ageMs === Infinity) {
+      return { status: "unknown" };
+    }
+    if (ageMs <= this.staleAfterMs) {
+      return { status: "fresh" };
+    }
+    if (ageMs <= this.expiresAfterMs) {
+      return { status: "stale" };
+    }
+    return { status: "expired" };
+  };
   /**
    * Start the stream connection.
    * Returns a promise that resolves when the first datafile or primed message arrives.
@@ -2106,6 +2799,11 @@ var StreamSource = class extends TypedEmitter {
    */
   start() {
     if (this.promise) return this.promise;
+    debug(this.options.clientName, "stream.start", () => ({
+      revision: this.revision(),
+      staleAfterMs: this.staleAfterMs,
+      expiresAfterMs: this.expiresAfterMs
+    }));
     const abortController = new AbortController();
     this.abortController = abortController;
     abortController.signal.addEventListener(
@@ -2114,6 +2812,7 @@ var StreamSource = class extends TypedEmitter {
         if (this.abortController === abortController) {
           this.promise = void 0;
           this.abortController = void 0;
+          this.emit("exhausted");
         }
       },
       { once: true }
@@ -2122,6 +2821,7 @@ var StreamSource = class extends TypedEmitter {
       const promise = connectStream(
         {
           host: this.options.host,
+          clientName: this.options.clientName,
           resolveToken: () => this.options.auth.resolveToken(),
           sourceProjectId: this.options.auth.sourceProjectId,
           abortController,
@@ -2137,8 +2837,16 @@ var StreamSource = class extends TypedEmitter {
             this.emit("primed", message);
             this.emit("connected");
           },
+          onPing: () => this.emit("ping"),
           onDisconnect: () => {
             this.emit("disconnected");
+          },
+          onError: (error) => {
+            this.emit("error", error);
+          },
+          onConnection: (reconnect) => {
+            this.reconnect = reconnect;
+            this.connectionStartedAt = Date.now();
           }
         }
       );
@@ -2154,46 +2862,39 @@ var StreamSource = class extends TypedEmitter {
    * Stop the stream connection.
    */
   stop() {
-    this.abortController?.abort();
+    if (this.abortController) {
+      debug(this.options.clientName, "stream.stop");
+    }
+    const abortController = this.abortController;
     this.abortController = void 0;
     this.promise = void 0;
+    this.reconnect = void 0;
+    this.revalidation?.fail(new Error("stream: stopped"));
+    abortController?.abort();
   }
 };
 
-// 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;
+var UNKNOWN_FRESHNESS = {
+  assess: () => ({ status: "unknown" })
+};
+function isUnauthorizedError(error) {
+  if (error instanceof UnauthorizedError) {
+    return true;
   }
-  return void 0;
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.message.includes("401") || "status" in error && error.status === 401;
 }
 var Controller = class {
   options;
   // State machine
   state = "idle";
   // Data state — tagged with origin
-  data;
+  cache;
   // Memoized data spread for read() / getDatafile().
-  // Rebuilt only when `this.data` reference changes (e.g. on stream/poll update).
+  // Rebuilt only when the cached data reference changes (e.g. on stream/poll update).
   // Holds the result of stripping `_origin`; metrics are appended per-call.
   dataViewSource = void 0;
   dataViewBase = void 0;
@@ -2201,6 +2902,10 @@ var Controller = class {
   streamSource;
   pollingSource;
   bundledSource;
+  headerSource;
+  sourceStartup;
+  // Read policy while no live source confirms the cache; derived once from the options.
+  degradedReadPolicy;
   // Usage tracking
   usageTracker;
   isFirstGetData = true;
@@ -2212,53 +2917,112 @@ var Controller = class {
   unauthorized = false;
   constructor(options) {
     this.options = normalizeOptions(options);
+    this.cache = new DatafileCache(
+      async (signal) => {
+        try {
+          const data = await fetchDatafile({ ...this.options, signal });
+          signal.throwIfAborted();
+          this.unauthorized = false;
+          return data;
+        } catch (error) {
+          signal.throwIfAborted();
+          this.noteUnauthorized(error);
+          throw error;
+        }
+      },
+      this.options.staleIfErrorMs,
+      this.options.waitUntil,
+      this.options.clientName
+    );
     this.streamSource = new StreamSource(
       this.options,
-      () => this.data?.revision
+      () => this.cache.revision
     );
-    this.pollingSource = new PollingSource(this.options);
+    this.pollingSource = new PollingSource({
+      clientName: this.options.clientName,
+      polling: this.options.polling,
+      staleWhileRevalidateMs: this.options.staleWhileRevalidateMs,
+      refresh: () => this.cache.refresh("poll")
+    });
+    this.headerSource = new HeaderSource(this.options);
+    this.degradedReadPolicy = this.createDegradedReadPolicy();
     this.bundledSource = new BundledSource({
       auth: this.options.auth,
       readBundledDefinitions
     });
     this.wireSourceEvents();
     if (this.options.datafile) {
-      this.data = tagData(this.options.datafile, "provided");
+      this.cache.seed(tagData({ ...this.options.datafile }, "provided"));
     }
     this.usageTracker = new UsageTracker(this.options);
+    debug(this.options.clientName, "client.created", () => ({
+      ...this.debugState(),
+      buildStep: this.options.buildStep,
+      vercel: this.options.vercel,
+      stream: this.options.stream.enabled,
+      streamInitTimeoutMs: this.options.stream.initTimeoutMs,
+      polling: this.options.polling.enabled,
+      pollingIntervalMs: this.options.polling.intervalMs,
+      pollingInitTimeoutMs: this.options.polling.initTimeoutMs,
+      staleWhileRevalidateMs: this.options.staleWhileRevalidateMs,
+      staleIfErrorMs: this.options.staleIfErrorMs
+    }));
   }
   // Source event handlers (stored for cleanup)
   onStreamData = (data) => {
+    debug(this.options.clientName, "stream.data", () => ({
+      projectId: data.projectId,
+      revision: data.revision,
+      configUpdatedAt: Number(data.configUpdatedAt)
+    }));
     this.unauthorized = false;
-    if (this.isNewerData(data)) {
-      this.data = tagData(data, "stream");
-    }
+    this.cache.updateFromSource(data, "stream");
   };
-  onStreamPrimed = () => {
+  onStreamPrimed = (message) => {
     this.unauthorized = false;
+    const confirmed = this.cache.tryConfirm(message, "revision", "stream");
+    debug(this.options.clientName, "stream.primed", () => ({
+      ...this.debugState(),
+      incomingRevision: message.revision,
+      confirmed
+    }));
     if (this.state === "degraded" || this.state === "initializing:stream") {
-      this.transition("streaming");
+      this.transition("streaming", "stream-primed");
     }
   };
+  onStreamPing = () => {
+    debug(this.options.clientName, "stream.ping", this.debugState);
+    this.cache.confirm("stream");
+  };
   onStreamConnected = () => {
     if (this.state === "degraded" || this.state === "initializing:stream") {
-      this.transition("streaming");
+      this.transition("streaming", "stream-connected");
     }
   };
   onStreamDisconnected = () => {
+    debug(this.options.clientName, "stream.disconnected", this.debugState);
+    this.cache.fail(new Error("stream: disconnected"));
     if (this.state === "streaming") {
-      this.transition("degraded");
+      this.transition("degraded", "stream-disconnected");
     }
   };
-  onPollData = (data) => {
-    this.unauthorized = false;
-    if (this.isNewerData(data)) {
-      this.data = tagData(data, "poll");
+  onStreamExhausted = () => {
+    if (this.state !== "streaming" && this.state !== "degraded") {
+      return;
     }
+    void this.activateFallbackSource().catch(() => {
+    });
   };
-  onPollError = (error) => {
+  onSourceError = (error) => {
     this.noteUnauthorized(error);
-    console.error("@vercel/flags-core: Poll failed:", error);
+    this.cache.fail(error);
+  };
+  onPollingError = (error) => {
+    this.onSourceError(error);
+    if (this.state === "polling" && isUnauthorizedError(error)) {
+      this.pollingSource.stop();
+      this.transition("degraded", "polling-unauthorized");
+    }
   };
   // ---------------------------------------------------------------------------
   // Source event wiring
@@ -2266,24 +3030,49 @@ var Controller = class {
   wireSourceEvents() {
     this.streamSource.on("data", this.onStreamData);
     this.streamSource.on("primed", this.onStreamPrimed);
+    this.streamSource.on("ping", this.onStreamPing);
     this.streamSource.on("connected", this.onStreamConnected);
     this.streamSource.on("disconnected", this.onStreamDisconnected);
-    this.pollingSource.on("data", this.onPollData);
-    this.pollingSource.on("error", this.onPollError);
+    this.streamSource.on("exhausted", this.onStreamExhausted);
+    this.streamSource.on("error", this.onSourceError);
+    this.pollingSource.on("error", this.onPollingError);
   }
   unwireSourceEvents() {
     this.streamSource.off("data", this.onStreamData);
     this.streamSource.off("primed", this.onStreamPrimed);
+    this.streamSource.off("ping", this.onStreamPing);
     this.streamSource.off("connected", this.onStreamConnected);
     this.streamSource.off("disconnected", this.onStreamDisconnected);
-    this.pollingSource.off("data", this.onPollData);
-    this.pollingSource.off("error", this.onPollError);
+    this.streamSource.off("exhausted", this.onStreamExhausted);
+    this.streamSource.off("error", this.onSourceError);
+    this.pollingSource.off("error", this.onPollingError);
   }
   // ---------------------------------------------------------------------------
   // State machine
   // ---------------------------------------------------------------------------
-  transition(to) {
+  debugState = () => ({
+    state: this.state,
+    mode: this.mode,
+    projectId: this.cache.metadata?.projectId,
+    hasData: this.cache.hasData,
+    revision: this.cache.revision,
+    ageMs: this.cache.ageMs,
+    unauthorized: this.unauthorized
+  });
+  transition(to, reason) {
+    const from = this.state;
     this.state = to;
+    if (from !== to) {
+      debug(this.options.clientName, "client.state", () => ({
+        ...this.debugState(),
+        from,
+        to,
+        reason
+      }));
+    }
+  }
+  get isShutdown() {
+    return this.state === "shutdown";
   }
   get isConnected() {
     return this.state === "streaming";
@@ -2295,6 +3084,8 @@ var Controller = class {
         return "streaming";
       case "polling":
         return "polling";
+      case "vercel":
+        return "vercel";
       default:
         return "offline";
     }
@@ -2308,193 +3099,344 @@ var Controller = class {
    * Build step: datafile → bundled → one-time fetch
    * Streaming mode: stream → datafile → bundled
    * Polling mode (no stream): poll → datafile → bundled
+   * Vercel mode: datafile → bundled; fetch only on a read
    * Offline mode (neither): datafile → bundled → one-time fetch
    */
   async initialize() {
+    debug(this.options.clientName, "client.initialize", this.debugState);
     if (this.options.buildStep) {
-      this.transition("build:loading");
+      this.transition("build:loading", "build-initialize");
       await this.initializeForBuildStep();
-      this.transition("build:ready");
+      this.transition("build:ready", "build-data-ready");
       return;
     }
-    if (!this.data && this.options.datafile) {
-      this.data = tagData(this.options.datafile, "provided");
+    if (this.isShutdown) {
+      this.wireSourceEvents();
+      this.transition("idle", "restart-after-shutdown");
     }
-    if (!this.data) {
+    if (!this.cache.hasData && this.options.datafile) {
+      this.cache.seed(tagData({ ...this.options.datafile }, "provided"));
+    }
+    if (!this.cache.hasData) {
       try {
         const bundled = await this.bundledSource.tryLoad();
-        if (bundled) {
-          this.data = tagData(bundled, "bundled");
-        }
+        if (bundled) this.cache.seed(tagData({ ...bundled }, "bundled"));
       } catch {
       }
     }
-    if (this.data) {
-      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");
-      }
+    if (this.headerSource.isEnabled()) {
+      this.transition("vercel", "header-mode-enabled");
       return;
     }
-    if (this.options.stream.enabled) {
-      this.transition("initializing:stream");
-      const streamSuccess = await this.tryInitializeStream();
-      if (streamSuccess) {
-        this.transition("streaming");
-        return;
-      }
-    } else if (this.options.polling.enabled) {
-      this.transition("initializing:polling");
-      const pollingSuccess = await this.tryInitializePolling();
-      if (pollingSuccess) {
-        this.transition("polling");
-        return;
-      }
+    if (!this.options.stream.enabled && !this.options.polling.enabled) {
+      await this.initializeFromFallbacks();
+      return;
+    }
+    await this.activateFallbackSource();
+    if (this.cache.hasData) return;
+    if (this.unauthorized) {
+      throw this.noDefinitionsError(
+        ". Provide a datafile or bundled definitions."
+      );
+    }
+    const fetched = await this.cache.resolve(this.cacheReadPolicy);
+    if (!fetched.data) {
+      await this.initializeFromFallbacks();
     }
-    await this.initializeFromFallbacks();
   }
   /**
    * Reads the current datafile with metrics.
    */
   async read() {
     const startTime = Date.now();
-    const cacheHadDefinitions = this.data !== void 0;
+    const cacheHadDefinitions = this.cache.hasData;
     const isFirstRead = this.isFirstGetData;
     this.isFirstGetData = false;
-    const [result, cacheStatus] = await this.resolveData();
-    const readMs = Date.now() - startTime;
-    const source = originToMetricsSource(result._origin);
-    this.trackRead(startTime, cacheHadDefinitions, isFirstRead, source);
-    if (this.dataViewSource !== result) {
-      const { _origin, ...rest } = result;
-      this.dataViewBase = rest;
-      this.dataViewSource = result;
-    }
-    return {
-      ...this.dataViewBase,
-      metrics: {
-        readMs,
-        source,
-        cacheStatus,
-        connectionState: this.isConnected ? "connected" : "disconnected",
-        mode: this.mode
-      }
-    };
+    debug(this.options.clientName, "client.read.start", this.debugState);
+    const [result, cacheStatus] = await this.resolveData().catch((error) => {
+      debug(this.options.clientName, "client.read.failed", this.debugState);
+      throw error;
+    });
+    const datafile = this.toDatafile(result, cacheStatus, startTime);
+    debug(this.options.clientName, "client.read", () => ({
+      ...this.debugState(),
+      ...datafile.metrics
+    }));
+    this.trackRead(startTime, cacheHadDefinitions, isFirstRead, datafile);
+    return datafile;
   }
   /**
    * Shuts down the data source and releases resources.
    */
   async shutdown() {
+    debug(this.options.clientName, "client.shutdown.start", this.debugState);
     this.unwireSourceEvents();
     this.streamSource.stop();
     this.pollingSource.stop();
-    this.data = this.options.datafile ? tagData(this.options.datafile, "provided") : void 0;
-    this.transition("shutdown");
+    this.headerSource.stop();
+    this.cache.clear();
+    if (this.options.datafile) {
+      this.cache.seed(tagData({ ...this.options.datafile }, "provided"));
+    }
+    this.transition("shutdown", "shutdown");
     await this.usageTracker.shutdown();
+    debug(this.options.clientName, "client.shutdown.complete", this.debugState);
   }
   /**
-   * Returns the datafile with metrics.
-   * Uses in-memory data if available, otherwise falls back to bundled,
-   * then to a one-time fetch if called without prior initialization.
+   * Returns the datafile with metrics as a snapshot: it never starts streaming
+   * or polling. Cached data is served through the active source policy
+   * (header checks and HTTP revalidation); an empty cache loads bundled
+   * definitions, then performs a one-time fetch.
    */
   async getDatafile() {
+    debug(this.options.clientName, "client.getDatafile.start", this.debugState);
     const startTime = Date.now();
     this.isFirstGetData = false;
-    let result;
-    let cacheStatus;
-    if (this.options.buildStep) {
-      [result, cacheStatus] = await this.resolveDataForBuildStep();
-    } else if (this.data) {
-      cacheStatus = this.isConnected ? "HIT" : "STALE";
-      result = this.data;
-    } else {
-      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,
-            auth: this.options.auth,
-            fetch: this.options.fetch
-          });
-          this.data = tagData(fetched, "fetched");
-          result = this.data;
-          cacheStatus = "MISS";
-        } catch (error) {
-          this.noteUnauthorized(error);
-          throw this.noDefinitionsError(
-            ". Initialize the client or provide a datafile."
-          );
-        }
+    const [result, cacheStatus] = await this.resolveSnapshot().catch(
+      (error) => {
+        debug(
+          this.options.clientName,
+          "client.getDatafile.failed",
+          this.debugState
+        );
+        throw error;
       }
-    }
-    const source = originToMetricsSource(result._origin);
+    );
+    const datafile = this.toDatafile(result, cacheStatus, startTime);
+    debug(this.options.clientName, "client.getDatafile", () => ({
+      ...this.debugState(),
+      cacheStatus,
+      origin: result._origin
+    }));
+    return datafile;
+  }
+  /**
+   * Returns the bundled fallback datafile.
+   */
+  async getFallbackDatafile() {
+    return this.bundledSource.getRaw();
+  }
+  // ---------------------------------------------------------------------------
+  // Data resolution
+  // ---------------------------------------------------------------------------
+  toDatafile(result, cacheStatus, startTime) {
     if (this.dataViewSource !== result) {
       const { _origin, ...rest } = result;
       this.dataViewBase = rest;
       this.dataViewSource = result;
     }
+    debug(this.options.clientName, "client.getDatafile", () => ({
+      ...this.debugState(),
+      cacheStatus,
+      origin: result._origin
+    }));
     return {
       ...this.dataViewBase,
       metrics: {
         readMs: Date.now() - startTime,
-        source,
+        source: originToMetricsSource(result._origin),
         cacheStatus,
         connectionState: this.isConnected ? "connected" : "disconnected",
         mode: this.mode
       }
     };
   }
-  /**
-   * Returns the bundled fallback datafile.
-   */
-  async getFallbackDatafile() {
-    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
+   * Runtime: source policy chooses cached data or refresh; fall back if empty.
    */
   async resolveData() {
     if (this.options.buildStep) {
       return this.resolveDataForBuildStep();
     }
-    if (this.data) {
-      const cacheStatus = this.isConnected ? "HIT" : "STALE";
-      return [this.data, cacheStatus];
+    return this.resolveRuntimeData();
+  }
+  /** Initializes the active runtime source, then resolves through its policy. */
+  async resolveRuntimeData() {
+    if (this.sourceStartup) {
+      debug(this.options.clientName, "source.startup.shared", this.debugState);
+      await this.sourceStartup;
+    }
+    if (!this.cache.hasData && !this.options.stream.enabled && !this.options.polling.enabled) {
+      return this.resolveStaticFallbackData();
+    }
+    const result = await this.cache.resolve(this.cacheReadPolicy);
+    if (result.hasError || !result.data) {
+      debug(this.options.clientName, "header.fallback", () => ({
+        ...this.debugState(),
+        reason: "source-assessment-error"
+      }));
+      await this.activateFallbackSource();
+      return this.resolveRuntimeData();
     }
-    return this.resolveDataWithFallbacks();
+    return [result.data, result.status];
+  }
+  /**
+   * Resolves data for getDatafile() without starting a runtime source.
+   * Build step: cached → bundled → one-time fetch
+   * Runtime: cached data through the source policy; otherwise bundled → one-time fetch → throw
+   */
+  async resolveSnapshot() {
+    if (this.options.buildStep) {
+      return this.resolveDataForBuildStep();
+    }
+    if (this.sourceStartup) {
+      await this.sourceStartup.catch(() => {
+      });
+    }
+    if (this.state === "idle" && this.headerSource.isEnabled()) {
+      this.transition("vercel", "header-mode-enabled");
+    }
+    if (!this.cache.hasData) {
+      const bundled = await this.bundledSource.tryLoad();
+      if (bundled) {
+        this.cache.seed(tagData({ ...bundled }, "bundled"));
+      }
+    }
+    if (this.cache.hasData || this.state === "vercel") {
+      const result = await this.cache.resolve(this.cacheReadPolicy);
+      const cached = result.data ?? this.cache.read();
+      if (cached) {
+        return [cached, result.status];
+      }
+    }
+    try {
+      await this.cache.refresh();
+    } catch {
+      throw this.noDefinitionsError(
+        ". Initialize the client or provide a datafile."
+      );
+    }
+    const fetched = this.cache.read();
+    if (!fetched) {
+      throw this.noDefinitionsError(
+        ". Initialize the client or provide a datafile."
+      );
+    }
+    return [fetched, "MISS"];
+  }
+  get cacheReadPolicy() {
+    if (this.state === "vercel") {
+      return {
+        assess: this.headerSource.getAssessment(),
+        retryOnFailure: true
+      };
+    }
+    if (this.state === "streaming") {
+      return {
+        assess: this.streamSource.assess,
+        revalidate: () => this.streamSource.revalidate()
+      };
+    }
+    if (this.state === "polling") {
+      return { assess: this.pollingSource.assess };
+    }
+    if (this.state === "degraded") {
+      return this.degradedReadPolicy;
+    }
+    return UNKNOWN_FRESHNESS;
+  }
+  /**
+   * Without a live source nothing confirms the cache, so reads apply plain
+   * stale-while-revalidate over HTTP from the two public windows: data
+   * refreshed within `staleWhileRevalidateMs` is served as is, older data is
+   * served while refreshing in the background, and data older than that
+   * window plus `staleIfErrorMs` is expired and waits for the refresh. An
+   * unknown age is not known to be old, so it refreshes in the background.
+   * Offline clients never refresh.
+   */
+  createDegradedReadPolicy() {
+    if (!this.options.stream.enabled && !this.options.polling.enabled) {
+      return UNKNOWN_FRESHNESS;
+    }
+    const { staleWhileRevalidateMs, staleIfErrorMs } = this.options;
+    const expiresAfterMs = staleWhileRevalidateMs + staleIfErrorMs;
+    return {
+      assess: ({ ageMs }) => {
+        if (ageMs <= staleWhileRevalidateMs) {
+          return { status: "fresh" };
+        }
+        if (ageMs === Infinity || ageMs <= expiresAfterMs) {
+          return { status: "stale" };
+        }
+        return { status: "expired" };
+      },
+      retryOnFailure: true
+    };
+  }
+  /**
+   * Advances through the runtime source chain. Every caller uses the same path:
+   * request headers → stream → polling → direct cache refresh.
+   */
+  activateFallbackSource() {
+    if (this.sourceStartup) {
+      debug(this.options.clientName, "source.startup.shared", this.debugState);
+      return this.sourceStartup;
+    }
+    debug(this.options.clientName, "source.startup", this.debugState);
+    const startup = this.startFallbackSource().finally(() => {
+      if (this.sourceStartup === startup) {
+        this.sourceStartup = void 0;
+      }
+      debug(this.options.clientName, "source.startup.settled", this.debugState);
+    });
+    this.sourceStartup = startup;
+    return startup;
+  }
+  async startFallbackSource() {
+    if (this.isShutdown) {
+      throw new Error("@vercel/flags-core: Client is shut down");
+    }
+    if ((this.state === "idle" || this.state === "vercel") && this.options.stream.enabled) {
+      this.transition("initializing:stream", "start-stream");
+      const outcome = await this.tryInitializeStream();
+      if (this.isShutdown) {
+        throw new Error("@vercel/flags-core: Client is shut down");
+      }
+      if (outcome === "connected" || this.isConnected) {
+        this.transition("streaming", "stream-initialized");
+        return;
+      }
+      if (outcome === "connecting" && this.streamSource.active) {
+        this.transition("degraded", "stream-still-connecting");
+        return;
+      }
+    }
+    if (this.options.polling.enabled) {
+      if (this.state !== "polling") {
+        this.transition("polling", "start-polling");
+        this.pollingSource.startInterval();
+      }
+      await this.initializePolling();
+      if (this.isShutdown) {
+        throw new Error("@vercel/flags-core: Client is shut down");
+      }
+      return;
+    }
+    this.transition("degraded", "no-active-update-source");
   }
   // ---------------------------------------------------------------------------
   // Stream initialization
   // ---------------------------------------------------------------------------
   /**
-   * Attempts to initialize via stream with timeout.
-   * Returns true if stream connected successfully within timeout.
+   * Attempts to initialize via stream with timeout. A timeout leaves the
+   * stream connecting in the background; a rejection means it gave up.
    */
   async tryInitializeStream() {
+    debug(this.options.clientName, "stream.initialize", () => ({
+      timeoutMs: this.options.stream.initTimeoutMs,
+      ...this.debugState()
+    }));
     if (this.options.stream.initTimeoutMs <= 0) {
       try {
         await this.streamSource.start();
-        return true;
+        return "connected";
       } catch (error) {
         this.noteUnauthorized(error);
-        return false;
+        return "failed";
       }
     }
     let timeoutId;
@@ -2511,72 +3453,80 @@ var Controller = class {
       ]);
       clearTimeout(timeoutId);
       if (result === "timeout") {
+        debug(this.options.clientName, "stream.initialize.timeout", () => ({
+          timeoutMs: this.options.stream.initTimeoutMs,
+          ...this.debugState()
+        }));
         console.warn(
           "@vercel/flags-core: Stream initialization timeout, falling back while continuing to connect in the background"
         );
-        void this.streamSource.start().catch(() => {
-        });
-        return false;
+        if (this.streamSource.active) {
+          void this.streamSource.start().catch(() => {
+          });
+        }
+        return "connecting";
       }
-      return true;
+      return "connected";
     } catch (error) {
       clearTimeout(timeoutId);
       this.noteUnauthorized(error);
-      return false;
+      return "failed";
     }
   }
   // ---------------------------------------------------------------------------
   // 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.
+   * Waits for the first poll whenever polling becomes the active runtime source.
+   * On timeout, initialization falls back while the pending poll and interval
+   * continue in the background. Poll errors propagate if no data is cached or
+   * the client is shutting down.
    */
-  async tryInitializePolling() {
-    const pollPromise = this.pollingSource.poll();
-    if (this.options.polling.initTimeoutMs <= 0) {
-      try {
-        await pollPromise;
-        if (this.data) {
-          this.pollingSource.startInterval();
-          return true;
-        }
-        return false;
-      } catch {
-        return false;
+  async initializePolling() {
+    debug(this.options.clientName, "poll.initialize", () => ({
+      timeoutMs: this.options.polling.initTimeoutMs,
+      ...this.debugState()
+    }));
+    const poll = this.pollingSource.poll().catch((error) => {
+      if (!this.cache.hasData || this.isShutdown) {
+        throw error;
       }
-    }
-    let timeoutId;
-    const timeoutPromise = new Promise((resolve) => {
-      timeoutId = setTimeout(
-        () => resolve("timeout"),
-        this.options.polling.initTimeoutMs
+      debug(
+        this.options.clientName,
+        "poll.initialize.fallback",
+        this.debugState
       );
     });
+    const timeoutMs = this.options.polling.initTimeoutMs;
+    if (timeoutMs <= 0) {
+      await poll;
+      return;
+    }
+    let timeoutId;
     try {
-      const result = await Promise.race([pollPromise, timeoutPromise]);
-      clearTimeout(timeoutId);
-      if (result === "timeout") {
+      const outcome = await Promise.race([
+        poll,
+        new Promise((resolve) => {
+          timeoutId = setTimeout(() => resolve("timeout"), timeoutMs);
+        })
+      ]);
+      if (outcome === "timeout") {
+        debug(this.options.clientName, "poll.initialize.timeout", () => ({
+          timeoutMs,
+          ...this.debugState()
+        }));
         console.warn(
           "@vercel/flags-core: Polling initialization timeout, falling back while continuing to poll in the background"
         );
-        return false;
-      }
-      if (this.data) {
-        this.pollingSource.startInterval();
-        return true;
       }
-      return false;
-    } catch {
+    } finally {
       clearTimeout(timeoutId);
-      return false;
     }
   }
   noteUnauthorized(error) {
-    if (error instanceof UnauthorizedError || error instanceof Error && error.message.includes("401")) {
+    if (isUnauthorizedError(error)) {
       this.unauthorized = true;
+      debug(this.options.clientName, "client.unauthorized", this.debugState);
     }
   }
   // ---------------------------------------------------------------------------
@@ -2586,44 +3536,41 @@ var Controller = class {
    * Initializes data for build step environments.
    */
   async initializeForBuildStep() {
-    if (this.data) return;
+    if (this.cache.hasData) return;
     if (!this.buildDataPromise) {
       this.buildDataPromise = this.loadBuildData();
     }
-    this.data = await this.buildDataPromise;
+    this.cache.seed(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.
+   * populate the cache gets cacheStatus MISS; subsequent callers get HIT.
    */
   async resolveDataForBuildStep() {
-    if (this.data) {
-      return [this.data, "HIT"];
+    const cached = this.cache.read();
+    if (cached) {
+      return [cached, "HIT"];
     }
     if (!this.buildDataPromise) {
       this.buildDataPromise = this.loadBuildData();
     }
     const data = await this.buildDataPromise;
-    if (!this.data) {
-      this.data = data;
-      return [data, "MISS"];
+    const loaded = this.cache.read();
+    if (loaded) {
+      return [loaded, "HIT"];
     }
-    return [this.data, "HIT"];
+    return [this.cache.seedAndRead(data), "MISS"];
   }
   /**
    * Loads data for a build step: bundled → one-time fetch.
    */
   async loadBuildData() {
     const bundled = await this.bundledSource.tryLoad();
-    if (bundled) return tagData(bundled, "bundled");
+    if (bundled) return tagData({ ...bundled }, "bundled");
     try {
-      const fetched = await fetchDatafile({
-        host: this.options.host,
-        auth: this.options.auth,
-        fetch: this.options.fetch
-      });
-      return tagData(fetched, "fetched");
+      const fetched = await this.fetchOnce();
+      return tagData({ ...fetched, fetchedAt: Date.now() }, "fetched");
     } catch (error) {
       this.noteUnauthorized(error);
     }
@@ -2634,30 +3581,45 @@ var Controller = class {
   // ---------------------------------------------------------------------------
   // Fallback helpers
   // ---------------------------------------------------------------------------
+  fetchOnce() {
+    return fetchDatafile({
+      host: this.options.host,
+      clientName: this.options.clientName,
+      auth: this.options.auth,
+      fetch: this.options.fetch
+    });
+  }
+  /**
+   * Stores a last-resort fetch as a source response, which clears any failure,
+   * and serves it through the cache boundary.
+   */
+  acceptLastResortFetch(fetched) {
+    this.cache.updateFromSource(fetched, "fetched");
+    const remote = this.cache.read();
+    if (!remote) {
+      throw new Error("@vercel/flags-core: Fetch returned no definitions");
+    }
+    return remote;
+  }
   /**
    * Shared fallback chain used by both initialize() and resolveData().
    */
   async initializeFromFallbacks() {
-    this.transition("initializing:fallback");
-    if (this.data) {
-      this.transition("degraded");
+    this.transition("initializing:fallback", "initialize-static-fallback");
+    if (this.cache.hasData) {
+      this.transition("degraded", "cached-fallback");
       return;
     }
     const bundled = await this.bundledSource.tryLoad();
     if (bundled) {
-      this.data = tagData(bundled, "bundled");
-      this.transition("degraded");
+      this.cache.seed(tagData({ ...bundled }, "bundled"));
+      this.transition("degraded", "bundled-fallback");
       return;
     }
     if (!this.options.stream.enabled && !this.options.polling.enabled) {
       try {
-        const fetched = await fetchDatafile({
-          host: this.options.host,
-          auth: this.options.auth,
-          fetch: this.options.fetch
-        });
-        this.data = tagData(fetched, "fetched");
-        this.transition("degraded");
+        this.acceptLastResortFetch(await this.fetchOnce());
+        this.transition("degraded", "fetched-fallback");
         return;
       } catch {
       }
@@ -2669,6 +3631,7 @@ var Controller = class {
    * starts with either "." or " during build.".
    */
   noDefinitionsError(detail) {
+    debug(this.options.clientName, "client.no-definitions", this.debugState);
     const { sourceProjectId } = this.options.auth;
     const reason = this.unauthorized && sourceProjectId ? ` Request was ${unauthorizedMessage(sourceProjectId)}` : "";
     return new Error(
@@ -2676,92 +3639,57 @@ var Controller = class {
     );
   }
   /**
-   * 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.
+   * Retrieves data when the cache is empty in offline mode:
+   * datafile → bundled → one-time fetch.
    */
-  async resolveDataWithFallbacks() {
-    if (this.options.stream.enabled) {
-      this.transition("initializing:stream");
-      const streamSuccess = await this.tryInitializeStream();
-      if (streamSuccess && this.data) {
-        this.transition("streaming");
-        return [this.data, "MISS"];
-      }
-    } else if (this.options.polling.enabled) {
-      this.transition("initializing:polling");
-      const pollingSuccess = await this.tryInitializePolling();
-      if (pollingSuccess && this.data) {
-        this.transition("polling");
-        return [this.data, "MISS"];
-      }
-    }
-    this.transition("initializing:fallback");
+  async resolveStaticFallbackData() {
+    const cached = this.cache.read();
+    if (cached) return [cached, "STALE"];
+    this.transition("initializing:fallback", "read-static-fallback");
     if (this.options.datafile) {
-      this.data = tagData(this.options.datafile, "provided");
-      this.transition("degraded");
-      return [this.data, "STALE"];
+      const provided = this.cache.seedAndRead(
+        tagData({ ...this.options.datafile }, "provided")
+      );
+      this.transition("degraded", "provided-fallback");
+      return [provided, "STALE"];
     }
     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 embedded = this.cache.seedAndRead(
+        tagData({ ...bundled }, "bundled")
+      );
+      this.transition("degraded", "bundled-fallback");
+      return [embedded, "STALE"];
     }
     if (!this.options.stream.enabled && !this.options.polling.enabled) {
+      let fetched;
       try {
-        const fetched = await fetchDatafile({
-          host: this.options.host,
-          auth: this.options.auth,
-          fetch: this.options.fetch
-        });
-        this.data = tagData(fetched, "fetched");
-        this.transition("degraded");
-        return [this.data, "MISS"];
+        fetched = await this.fetchOnce();
       } catch {
       }
+      if (fetched) {
+        const remote = this.acceptLastResortFetch(fetched);
+        this.transition("degraded", "fetched-fallback");
+        return [remote, "MISS"];
+      }
     }
     throw this.noDefinitionsError(
       ". Provide a datafile or bundled definitions."
     );
   }
   // ---------------------------------------------------------------------------
-  // 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.
-   *
-   * Always accepts the update if:
-   * - There is no current data
-   * - The current data has no configUpdatedAt
-   * - The incoming data has no configUpdatedAt
-   *
-   * Skips the update only when both have configUpdatedAt and incoming is not newer.
-   */
-  isNewerData(incoming) {
-    if (!this.data) return true;
-    const currentTs = parseConfigUpdatedAt(this.data.configUpdatedAt);
-    const incomingTs = parseConfigUpdatedAt(incoming.configUpdatedAt);
-    if (currentTs === void 0 || incomingTs === void 0) {
-      return true;
-    }
-    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) {
+  trackRead(startTime, cacheHadDefinitions, isFirstRead, datafile) {
     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 configOrigin = datafile.metrics.source === "embedded" ? "embedded" : "in-memory";
     const cacheAction = this.state === "streaming" ? "FOLLOWING" : this.state === "polling" ? "REFRESHING" : "NONE";
     const mode = this.mode;
     const trackOptions = {
@@ -2772,11 +3700,11 @@ var Controller = class {
       duration: Date.now() - startTime,
       mode: mode === "streaming" ? "stream" : mode === "polling" ? "poll" : mode
     };
-    const configUpdatedAt = this.data?.configUpdatedAt;
+    const configUpdatedAt = datafile.configUpdatedAt;
     if (typeof configUpdatedAt === "number") {
       trackOptions.configUpdatedAt = configUpdatedAt;
     }
-    const revision = this.data?.revision;
+    const revision = datafile.revision;
     if (typeof revision === "number") {
       trackOptions.revision = revision;
     }
@@ -2870,4 +3798,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-SLNLPFKU.js.map
+//# sourceMappingURL=chunk-SYXANNZ4.js.map