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

package/dist/{chunk-W742GGZU.cjs → chunk-W6776MKF.cjs}

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6;// src/index.next-js.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6; var _class7; var _class8; var _class9; var _class10;// src/index.next-js.ts
 var _cache = require('next/cache');
 var _server = require('next/server');
 
@@ -559,7 +559,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) {
@@ -1028,25 +1028,16 @@ var _oidc = require('@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 (e5) {
-    return null;
   }
+  return null;
 }
 
 // src/controller/auth.ts
@@ -1058,8 +1049,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 {
@@ -1099,27 +1092,13 @@ var Authentication = class {
           `@vercel/flags-core: Invalid sdkKey. Expected string, got ${typeof sdkKeyOrConnectionString}`
         );
       }
-      const parsed = parseFlagsConnectionString(sdkKeyOrConnectionString);
-      if (_optionalChain([parsed, 'optionalAccess', _31 => _31.sdkKey]) && parsed.projectId) {
-        throw new Error(
-          "@vercel/flags-core: A connection string must contain either sdkKey or projectId, not both"
-        );
-      }
-      if (_optionalChain([parsed, 'optionalAccess', _32 => _32.sdkKey])) {
-        if (!isValidSdkKey(parsed.sdkKey)) {
-          throw new Error("@vercel/flags-core: Missing sdkKey");
-        }
-        this.sdkKey = parsed.sdkKey;
-      } else if (_optionalChain([parsed, 'optionalAccess', _33 => _33.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() {
@@ -1158,6 +1137,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) {
@@ -1166,7 +1182,7 @@ function getRuntimeIngestFor(auth) {
 function getRuntimeIngest() {
   try {
     const context = globalThis[FLAGS_CONTEXT_SYMBOL];
-    return typeof _optionalChain([context, 'optionalAccess', _34 => _34.ingest]) === "function" ? context.ingest : void 0;
+    return typeof _optionalChain([context, 'optionalAccess', _31 => _31.ingest]) === "function" ? context.ingest : void 0;
   } catch (e7) {
     return void 0;
   }
@@ -1177,9 +1193,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 = _optionalChain([process, 'access', _35 => _35.env, 'access', _36 => _36.DEBUG, 'optionalAccess', _37 => _37.includes, 'call', _38 => _38("@vercel/flags-core")]);
 var debugLog = (...args) => {
-  if (!isDebugMode) return;
+  if (!isDebugEnabled()) return;
   console.log(...args);
 };
 async function getEvaluatingOidcToken(auth) {
@@ -1202,7 +1217,7 @@ async function getIngestHeaders(options, flushReason) {
       "X-Vercel-Env": _nullishCoalesce(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) {
@@ -1214,7 +1229,7 @@ function getRuntimeIngestHeaders(options, flushReason) {
     ..._nullishCoalesce(options.metricEnvironment, () => ( process.env.VERCEL_ENV)) ? {
       "X-Vercel-Env": _nullishCoalesce(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) {
@@ -1276,7 +1291,7 @@ var SYMBOL_FOR_REQ_CONTEXT = /* @__PURE__ */ Symbol.for("@vercel/request-context
 var fromSymbol = globalThis;
 function getRequestContext() {
   try {
-    const ctx = _optionalChain([fromSymbol, 'access', _39 => _39[SYMBOL_FOR_REQ_CONTEXT], 'optionalAccess', _40 => _40.get, 'optionalCall', _41 => _41()]);
+    const ctx = _optionalChain([fromSymbol, 'access', _32 => _32[SYMBOL_FOR_REQ_CONTEXT], 'optionalAccess', _33 => _33.get, 'optionalCall', _34 => _34()]);
     if (ctx && Object.hasOwn(ctx, "headers")) {
       return {
         ctx,
@@ -1343,7 +1358,7 @@ var Scheduler = (_class = class {
   }
   resolveScheduledFlush(reason) {
     this.clearTimeouts();
-    _optionalChain([this, 'access', _42 => _42.resolveWait, 'optionalCall', _43 => _43(reason)]);
+    _optionalChain([this, 'access', _35 => _35.resolveWait, 'optionalCall', _36 => _36(reason)]);
   }
   reset() {
     this.pending = null;
@@ -1538,7 +1553,7 @@ var UsageTracker = (_class4 = class {
       this.inflightFlushes.add(flush);
       void flush.finally(() => this.inflightFlushes.delete(flush));
       try {
-        _optionalChain([this, 'access', _44 => _44.waitUntil, 'optionalCall', _45 => _45(flush)]);
+        _optionalChain([this, 'access', _37 => _37.waitUntil, 'optionalCall', _38 => _38(flush)]);
       } catch (e11) {
       }
     } else {
@@ -1617,7 +1632,7 @@ var BundledSource = class {
    */
   async tryLoad() {
     const result = await this.getResult();
-    if (_optionalChain([result, 'optionalAccess', _46 => _46.state]) === "ok" && result.definitions) {
+    if (_optionalChain([result, 'optionalAccess', _39 => _39.state]) === "ok" && result.definitions) {
       return result.definitions;
     }
     return void 0;
@@ -1630,6 +1645,391 @@ var BundledSource = class {
   }
 };
 
+// src/controller/debug.ts
+function debug(clientName, event, details) {
+  if (!isDebugEnabled()) {
+    return;
+  }
+  try {
+    console.debug("@vercel/flags-core", { event, clientName, ..._optionalChain([details, 'optionalCall', _40 => _40()]) });
+  } catch (e12) {
+  }
+}
+
+// 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 = (_class5 = class {
+  constructor(fetch, staleIfErrorMs = Infinity, waitUntil2 = () => {
+  }, clientName) {;_class5.prototype.__init12.call(this);_class5.prototype.__init13.call(this);
+    this.fetch = fetch;
+    this.staleIfErrorMs = staleIfErrorMs;
+    this.waitUntil = waitUntil2;
+    this.clientName = clientName;
+  }
+  
+  
+  
+  
+  
+  // Confirmations refresh age without rewriting the datafile's persisted fetch time.
+  
+  
+  __init12() {this.abortController = new AbortController()}
+  
+  __init13() {this.debugState = () => ({
+    projectId: _optionalChain([this, 'access', _49 => _49.data, 'optionalAccess', _50 => _50.projectId]),
+    environment: _optionalChain([this, 'access', _51 => _51.data, 'optionalAccess', _52 => _52.environment]),
+    hasData: this.hasData,
+    origin: _optionalChain([this, 'access', _53 => _53.data, 'optionalAccess', _54 => _54._origin]),
+    revision: this.revision,
+    configUpdatedAt: parseConfigUpdatedAt(_optionalChain([this, 'access', _55 => _55.data, 'optionalAccess', _56 => _56.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 _optionalChain([this, 'access', _57 => _57.data, 'optionalAccess', _58 => _58.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 _optionalChain([policy, 'access', _59 => _59.revalidate, 'optionalCall', _60 => _60(), 'access', _61 => _61.catch, 'call', _62 => _62(() => {
+    })]);
+    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 (e13) {
+    }
+  }
+  /** 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;
+  }
+}, _class5);
+
 // src/controller/fetch-datafile.ts
 var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_ATTEMPTS = 3;
@@ -1644,11 +2044,15 @@ var DatafileHttpError = class extends Error {
   }
 };
 async function fetchDatafile(options) {
-  _optionalChain([options, 'access', _47 => _47.signal, 'optionalAccess', _48 => _48.throwIfAborted, 'call', _49 => _49()]);
+  _optionalChain([options, 'access', _63 => _63.signal, 'optionalAccess', _64 => _64.throwIfAborted, 'call', _65 => _65()]);
   const maxAttempts = _nullishCoalesce(options.maxAttempts, () => ( DEFAULT_MAX_ATTEMPTS));
   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;
@@ -1657,17 +2061,26 @@ async function fetchDatafile(options) {
   });
   const onAbort = () => rejectAbort(signal.reason);
   signal.addEventListener("abort", onAbort, { once: true });
-  const onExternalAbort = () => controller.abort(_optionalChain([options, 'access', _50 => _50.signal, 'optionalAccess', _51 => _51.reason]));
-  _optionalChain([options, 'access', _52 => _52.signal, 'optionalAccess', _53 => _53.addEventListener, 'call', _54 => _54("abort", onExternalAbort, { once: true })]);
-  const timeoutId = setTimeout(
-    () => controller.abort(
+  const onExternalAbort = () => controller.abort(_optionalChain([options, 'access', _66 => _66.signal, 'optionalAccess', _67 => _67.reason]));
+  _optionalChain([options, 'access', _68 => _68.signal, 'optionalAccess', _69 => _69.addEventListener, 'call', _70 => _70("abort", onExternalAbort, { once: true })]);
+  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: {
@@ -1678,8 +2091,12 @@ async function fetchDatafile(options) {
       signal
     });
     signal.throwIfAborted();
+    debug(options.clientName, "datafile.fetch.response", () => ({
+      attempt,
+      status: res.status
+    }));
     if (!res.ok) {
-      void _optionalChain([res, 'access', _55 => _55.body, 'optionalAccess', _56 => _56.cancel, 'call', _57 => _57(), 'access', _58 => _58.catch, 'call', _59 => _59(() => {
+      void _optionalChain([res, 'access', _71 => _71.body, 'optionalAccess', _72 => _72.cancel, 'call', _73 => _73(), 'access', _74 => _74.catch, 'call', _75 => _75(() => {
       })]);
       throw new DatafileHttpError(
         res.status,
@@ -1688,6 +2105,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 {
@@ -1702,29 +2125,112 @@ 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: _optionalChain([options, 'access', _76 => _76.signal, 'optionalAccess', _77 => _77.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);
     signal.removeEventListener("abort", onAbort);
-    _optionalChain([options, 'access', _60 => _60.signal, 'optionalAccess', _61 => _61.removeEventListener, 'call', _62 => _62("abort", onExternalAbort)]);
+    _optionalChain([options, 'access', _78 => _78.signal, 'optionalAccess', _79 => _79.removeEventListener, 'call', _80 => _80("abort", onExternalAbort)]);
   }
 }
 
+// src/controller/header-source.ts
+var HeaderSource = (_class6 = class {
+  constructor(options) {;_class6.prototype.__init14.call(this);
+    this.options = options;
+  }
+  
+  __init14() {this.highestObserved = 0}
+  getVersionHeader() {
+    const { headers } = getRequestContext();
+    return _nullishCoalesce(_optionalChain([headers, 'optionalAccess', _81 => _81["x-vercel-flags-config-versions"]]), () => ( _optionalChain([headers, 'optionalAccess', _82 => _82["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 = _optionalChain([header, 'access', _83 => _83.split, 'call', _84 => _84(";"), 'access', _85 => _85.map, 'call', _86 => _86((part) => part.trim()), 'access', _87 => _87.find, 'call', _88 => _88((part) => part.startsWith(prefix)), 'optionalAccess', _89 => _89.slice, 'call', _90 => _90(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;
+  }
+}, _class6);
+
 // 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;
+var DEFAULT_STALE_WHILE_REVALIDATE = 10;
 function normalizeOptions(options) {
+  const staleIfError = _nullishCoalesce(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 = _nullishCoalesce(options.buildStep, () => ( autoDetectedBuildStep));
   let stream;
@@ -1756,11 +2262,20 @@ function normalizeOptions(options) {
       initTimeoutMs: options.polling.initTimeoutMs
     };
   }
+  const staleWhileRevalidate = _nullishCoalesce(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: _nullishCoalesce(options.vercel, () => ( process.env.VERCEL === "1")),
+    staleWhileRevalidateMs: staleWhileRevalidate * 1e3,
+    staleIfErrorMs: staleIfError * 1e3,
     buildStep,
     fetch: _nullishCoalesce(options.fetch, () => ( globalThis.fetch)),
     waitUntil: _nullishCoalesce(options.waitUntil, () => ( _functions.waitUntil)),
@@ -1772,8 +2287,8 @@ function normalizeOptions(options) {
 }
 
 // src/controller/typed-emitter.ts
-var TypedEmitter = (_class5 = class {constructor() { _class5.prototype.__init12.call(this); }
-  __init12() {this.handlers = /* @__PURE__ */ new Map()}
+var TypedEmitter = (_class7 = class {constructor() { _class7.prototype.__init15.call(this); }
+  __init15() {this.handlers = /* @__PURE__ */ new Map()}
   on(event, handler) {
     let set = this.handlers.get(event);
     if (!set) {
@@ -1798,36 +2313,70 @@ var TypedEmitter = (_class5 = class {constructor() { _class5.prototype.__init12.
       }
     }
   }
-}, _class5);
+}, _class7);
 
 // src/controller/polling-source.ts
-var PollingSource = class extends TypedEmitter {
+var PollingSource = (_class8 = class extends TypedEmitter {
+  
   
   
   
   constructor(config) {
-    super();
+    super();_class8.prototype.__init16.call(this);;
     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;
+  }
+  __init16() {this.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 (_optionalChain([this, 'access', _63 => _63.abortController, 'optionalAccess', _64 => _64.signal, 'access', _65 => _65.aborted])) return;
+    if (this.polling) {
+      debug(this.config.clientName, "poll.shared");
+      return this.polling;
+    }
+    if (_optionalChain([this, 'access', _91 => _91.abortController, 'optionalAccess', _92 => _92.signal, 'access', _93 => _93.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.
@@ -1836,6 +2385,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(() => {
       }),
@@ -1846,14 +2400,20 @@ 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;
     }
-    _optionalChain([this, 'access', _66 => _66.abortController, 'optionalAccess', _67 => _67.abort, 'call', _68 => _68()]);
+    _optionalChain([this, 'access', _94 => _94.abortController, 'optionalAccess', _95 => _95.abort, 'call', _96 => _96()]);
     this.abortController = void 0;
+    this.polling = void 0;
   }
-};
+}, _class8);
 
 // src/utils/runtime.ts
 function isBun() {
@@ -1869,7 +2429,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(
@@ -1892,9 +2454,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;
+    _optionalChain([onError, 'optionalCall', _97 => _97(
+      error instanceof Error ? error : new Error("Unknown stream error", { cause: error })
+    )]);
+  };
   let resolveInit;
   let rejectInit;
   const initPromise = new Promise((resolve, reject) => {
@@ -1906,6 +2474,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",
           _nullishCoalesce(lastError, () => ( "stream closed repeatedly without an error"))
@@ -1915,6 +2486,8 @@ async function connectStream(config, callbacks) {
             new Error("stream: max retry count exceeded before receiving data")
           );
         }
+        reportError(new Error("stream: max retry count exceeded"));
+        _optionalChain([onDisconnect, 'optionalCall', _98 => _98()]);
         abortController.abort();
         break;
       }
@@ -1923,20 +2496,24 @@ async function connectStream(config, callbacks) {
       abortController.signal.addEventListener("abort", onMainAbort, {
         once: true
       });
+      _optionalChain([onConnection, 'optionalCall', _99 => _99(() => connectionAbort.abort(PING_TIMEOUT))]);
       let pingTimeoutId;
-      let responseBody;
       const resetPingTimeout = () => {
         if (pingTimeoutId !== void 0) clearTimeout(pingTimeoutId);
         if (!initialDataReceived) return;
         pingTimeoutId = setTimeout(() => {
-          _optionalChain([responseBody, 'optionalAccess', _69 => _69.cancel, 'call', _70 => _70(), 'access', _71 => _71.catch, 'call', _72 => _72(() => {
-          })]);
-          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 = {
@@ -1951,7 +2528,7 @@ async function connectStream(config, callbacks) {
         if (vercelEnv) {
           headers["X-Vercel-Env"] = vercelEnv;
         }
-        const revision = _optionalChain([config, 'access', _73 => _73.revision, 'optionalCall', _74 => _74()]);
+        const revision = _optionalChain([config, 'access', _100 => _100.revision, 'optionalCall', _101 => _101()]);
         if (revision !== void 0) {
           headers["X-Revision"] = String(revision);
         }
@@ -1959,20 +2536,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);
           }
+          _optionalChain([onDisconnect, 'optionalCall', _102 => _102()]);
+          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 = [];
@@ -1983,10 +2566,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;
@@ -1997,7 +2583,7 @@ async function connectStream(config, callbacks) {
               let message;
               try {
                 message = JSON.parse(line);
-              } catch (e12) {
+              } catch (e14) {
                 console.warn(
                   "@vercel/flags-core: Failed to parse stream message, skipping"
                 );
@@ -2013,7 +2599,7 @@ async function connectStream(config, callbacks) {
                 resetPingTimeout();
               }
               if (message.type === "primed") {
-                _optionalChain([onPrimed, 'optionalCall', _75 => _75(message)]);
+                _optionalChain([onPrimed, 'optionalCall', _103 => _103(message)]);
                 retryCount = 0;
                 if (!initialDataReceived) {
                   initialDataReceived = true;
@@ -2022,6 +2608,7 @@ async function connectStream(config, callbacks) {
                 resetPingTimeout();
               }
               if (message.type === "ping" && initialDataReceived) {
+                _optionalChain([onPing, 'optionalCall', _104 => _104()]);
                 retryCount = 0;
                 resetPingTimeout();
               }
@@ -2036,11 +2623,19 @@ async function connectStream(config, callbacks) {
         clearTimeout(pingTimeoutId);
         abortController.signal.removeEventListener("abort", onMainAbort);
         if (!abortController.signal.aborted) {
-          _optionalChain([onDisconnect, 'optionalCall', _76 => _76()]);
+          if (connectionAbort.signal.reason !== PING_TIMEOUT) {
+            _optionalChain([onDisconnect, 'optionalCall', _105 => _105()]);
+          }
           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) {
@@ -2049,19 +2644,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;
+          _optionalChain([onDisconnect, 'optionalCall', _106 => _106()]);
         }
-        _optionalChain([onDisconnect, 'optionalCall', _77 => _77()]);
         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) {
@@ -2072,16 +2676,105 @@ async function connectStream(config, callbacks) {
 }
 
 // src/controller/stream-source.ts
-var StreamSource = class extends TypedEmitter {
+var STREAM_FRESH_MS = PING_MS * 2;
+var StreamSource = (_class9 = class extends TypedEmitter {
+  
+  
   
   
   
+  __init17() {this.connectionStartedAt = 0}
   
   constructor(options, revision) {
-    super();
+    super();_class9.prototype.__init17.call(this);_class9.prototype.__init18.call(this);;
     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) {
+      _optionalChain([this, 'access', _107 => _107.reconnect, 'optionalCall', _108 => _108()]);
+    }
+    return promise;
+  }
+  __init18() {this.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.
@@ -2089,6 +2782,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(
@@ -2097,6 +2795,7 @@ var StreamSource = class extends TypedEmitter {
         if (this.abortController === abortController) {
           this.promise = void 0;
           this.abortController = void 0;
+          this.emit("exhausted");
         }
       },
       { once: true }
@@ -2105,6 +2804,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,
@@ -2120,8 +2820,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();
           }
         }
       );
@@ -2137,111 +2845,167 @@ var StreamSource = class extends TypedEmitter {
    * Stop the stream connection.
    */
   stop() {
-    _optionalChain([this, 'access', _78 => _78.abortController, 'optionalAccess', _79 => _79.abort, 'call', _80 => _80()]);
+    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;
+    _optionalChain([this, 'access', _109 => _109.revalidation, 'optionalAccess', _110 => _110.fail, 'call', _111 => _111(new Error("stream: stopped"))]);
+    _optionalChain([abortController, 'optionalAccess', _112 => _112.abort, 'call', _113 => _113()]);
   }
-};
-
-// 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";
-  }
-}
+}, _class9);
 
 // 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 = (_class6 = class {
+var Controller = (_class10 = class {
   
   // State machine
-  __init13() {this.state = "idle"}
+  __init19() {this.state = "idle"}
   // Data state — tagged with origin
   
   // 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.
-  __init14() {this.dataViewSource = void 0}
-  __init15() {this.dataViewBase = void 0}
+  __init20() {this.dataViewSource = void 0}
+  __init21() {this.dataViewBase = void 0}
   // Sources (I/O delegates)
   
   
   
+  
+  
+  // Read policy while no live source confirms the cache; derived once from the options.
+  
   // Usage tracking
   
-  __init16() {this.isFirstGetData = true}
+  __init22() {this.isFirstGetData = true}
   // Build-step deduplication
-  __init17() {this.buildDataPromise = null}
-  __init18() {this.buildReadTracked = false}
+  __init23() {this.buildDataPromise = null}
+  __init24() {this.buildReadTracked = false}
   // Suppresses usage tracking while the credential is rejected. Set on a 401
   // from any source, cleared as soon as a source delivers data again.
-  __init19() {this.unauthorized = false}
-  constructor(options) {;_class6.prototype.__init13.call(this);_class6.prototype.__init14.call(this);_class6.prototype.__init15.call(this);_class6.prototype.__init16.call(this);_class6.prototype.__init17.call(this);_class6.prototype.__init18.call(this);_class6.prototype.__init19.call(this);_class6.prototype.__init20.call(this);_class6.prototype.__init21.call(this);_class6.prototype.__init22.call(this);_class6.prototype.__init23.call(this);_class6.prototype.__init24.call(this);_class6.prototype.__init25.call(this);
+  __init25() {this.unauthorized = false}
+  constructor(options) {;_class10.prototype.__init19.call(this);_class10.prototype.__init20.call(this);_class10.prototype.__init21.call(this);_class10.prototype.__init22.call(this);_class10.prototype.__init23.call(this);_class10.prototype.__init24.call(this);_class10.prototype.__init25.call(this);_class10.prototype.__init26.call(this);_class10.prototype.__init27.call(this);_class10.prototype.__init28.call(this);_class10.prototype.__init29.call(this);_class10.prototype.__init30.call(this);_class10.prototype.__init31.call(this);_class10.prototype.__init32.call(this);_class10.prototype.__init33.call(this);_class10.prototype.__init34.call(this);
     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,
-      () => _optionalChain([this, 'access', _81 => _81.data, 'optionalAccess', _82 => _82.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)
-  __init20() {this.onStreamData = (data) => {
+  __init26() {this.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");
   }}
-  __init21() {this.onStreamPrimed = () => {
+  __init27() {this.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");
     }
   }}
-  __init22() {this.onStreamConnected = () => {
+  __init28() {this.onStreamPing = () => {
+    debug(this.options.clientName, "stream.ping", this.debugState);
+    this.cache.confirm("stream");
+  }}
+  __init29() {this.onStreamConnected = () => {
     if (this.state === "degraded" || this.state === "initializing:stream") {
-      this.transition("streaming");
+      this.transition("streaming", "stream-connected");
     }
   }}
-  __init23() {this.onStreamDisconnected = () => {
+  __init30() {this.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");
     }
   }}
-  __init24() {this.onPollData = (data) => {
-    this.unauthorized = false;
-    if (this.isNewerData(data)) {
-      this.data = tagData(data, "poll");
+  __init31() {this.onStreamExhausted = () => {
+    if (this.state !== "streaming" && this.state !== "degraded") {
+      return;
     }
+    void this.activateFallbackSource().catch(() => {
+    });
   }}
-  __init25() {this.onPollError = (error) => {
+  __init32() {this.onSourceError = (error) => {
     this.noteUnauthorized(error);
-    console.error("@vercel/flags-core: Poll failed:", error);
+    this.cache.fail(error);
+  }}
+  __init33() {this.onPollingError = (error) => {
+    this.onSourceError(error);
+    if (this.state === "polling" && isUnauthorizedError(error)) {
+      this.pollingSource.stop();
+      this.transition("degraded", "polling-unauthorized");
+    }
   }}
   // ---------------------------------------------------------------------------
   // Source event wiring
@@ -2249,24 +3013,49 @@ var Controller = (_class6 = 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) {
+  __init34() {this.debugState = () => ({
+    state: this.state,
+    mode: this.mode,
+    projectId: _optionalChain([this, 'access', _117 => _117.cache, 'access', _118 => _118.metadata, 'optionalAccess', _119 => _119.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";
@@ -2278,6 +3067,8 @@ var Controller = (_class6 = class {
         return "streaming";
       case "polling":
         return "polling";
+      case "vercel":
+        return "vercel";
       default:
         return "offline";
     }
@@ -2291,193 +3082,344 @@ var Controller = (_class6 = 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");
-        }
-      } catch (e13) {
+        if (bundled) this.cache.seed(tagData({ ...bundled }, "bundled"));
+      } catch (e15) {
       }
     }
-    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 = _nullishCoalesce(result.data, () => ( this.cache.read()));
+      if (cached) {
+        return [cached, result.status];
+      }
+    }
+    try {
+      await this.cache.refresh();
+    } catch (e16) {
+      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;
@@ -2494,72 +3436,80 @@ var Controller = (_class6 = 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 (e14) {
-        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 (e15) {
+    } 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);
     }
   }
   // ---------------------------------------------------------------------------
@@ -2569,44 +3519,41 @@ var Controller = (_class6 = 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);
     }
@@ -2617,32 +3564,47 @@ var Controller = (_class6 = 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 (e16) {
+      } catch (e17) {
       }
     }
     throw this.noDefinitionsError(". Bundled definitions not found.");
@@ -2652,6 +3614,7 @@ var Controller = (_class6 = 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(
@@ -2659,51 +3622,39 @@ var Controller = (_class6 = 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"];
-      } catch (e17) {
+        fetched = await this.fetchOnce();
+      } catch (e18) {
+      }
+      if (fetched) {
+        const remote = this.acceptLastResortFetch(fetched);
+        this.transition("degraded", "fetched-fallback");
+        return [remote, "MISS"];
       }
     }
     throw this.noDefinitionsError(
@@ -2711,40 +3662,17 @@ var Controller = (_class6 = class {
     );
   }
   // ---------------------------------------------------------------------------
-  // 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 = {
@@ -2755,11 +3683,11 @@ var Controller = (_class6 = class {
       duration: Date.now() - startTime,
       mode: mode === "streaming" ? "stream" : mode === "polling" ? "poll" : mode
     };
-    const configUpdatedAt = _optionalChain([this, 'access', _83 => _83.data, 'optionalAccess', _84 => _84.configUpdatedAt]);
+    const configUpdatedAt = datafile.configUpdatedAt;
     if (typeof configUpdatedAt === "number") {
       trackOptions.configUpdatedAt = configUpdatedAt;
     }
-    const revision = _optionalChain([this, 'access', _85 => _85.data, 'optionalAccess', _86 => _86.revision]);
+    const revision = datafile.revision;
     if (typeof revision === "number") {
       trackOptions.revision = revision;
     }
@@ -2778,7 +3706,7 @@ var Controller = (_class6 = class {
       clientName: _nullishCoalesce(options.clientName, () => ( this.options.clientName))
     });
   }
-}, _class6);
+}, _class10);
 
 // src/index.make.ts
 function make(createRawClient, defaults) {
@@ -2829,7 +3757,7 @@ function setCacheLife() {
   try {
     _cache.cacheLife.call(void 0, { revalidate: 0, expire: 0 });
     _cache.cacheLife.call(void 0, { stale: 60 });
-  } catch (e18) {
+  } catch (e19) {
   }
 }
 var cachedFns = {
@@ -2879,4 +3807,4 @@ var { flagsClient, resetDefaultFlagsClient, createClient } = make(
 
 
 exports.ResolutionReason = ResolutionReason; exports.evaluate = evaluate; exports.FallbackNotFoundError = FallbackNotFoundError; exports.FallbackEntryNotFoundError = FallbackEntryNotFoundError; exports.Controller = Controller; exports.flagsClient = flagsClient; exports.resetDefaultFlagsClient = resetDefaultFlagsClient; exports.createClient = createClient;
-//# sourceMappingURL=chunk-W742GGZU.cjs.map
+//# sourceMappingURL=chunk-W6776MKF.cjs.map