feat(flags-core): add header-driven Vercel mode on the shared cache

[luismeyer]

Stacked on #510.

Adds header-driven reads on Vercel, enabled by default when VERCEL=1. Initialization loads provided or bundled definitions before selecting Vercel mode. Request headers identify newer configuration; an empty cache fetches on its first read. getDatafile() remains a snapshot read without header checks.

The controller wires one source getStatus callback (fresh, stale, expired, or unknown) and an optional fetch callback into the shared cache. HeaderSource parses request timestamps and tracks the highest observed timestamp. The cache owns age, serving decisions, shared fetches, background work, cancellation, and stale-if-error.

• An evaluation with a missing or empty version header permanently starts streaming when enabled, otherwise polling. Missing-header reads reuse resolveDataWithFallbacks(), preserving the current cache before considering provided/bundled definitions. Concurrent reads share only pending startup work, and pending header refreshes are cancelled without losing cached data or resetting the failure deadline. Later headers do not switch the client back. Present malformed/unrelated headers retain cached-read behavior, subject to stale-if-error.
• Accepted data and valid equal-version confirmations reset cache age. Persisted fetchedAt initializes age and remains the actual fetch timestamp; confirmations never rewrite it.
• Polling data becomes stale after the polling interval, streaming data after 30 seconds. Pings reset age and clear stale-if-error failures: every stream connection sends primed or a datafile before pings. A later disconnect starts a new allowance.
• Streaming and polling retain their existing schedules, retries, and timeouts after startup; reads do not start extra requests. Missing-header fallback starts the polling interval even if its first poll times out. Shutdown prevents late polling startup from restarting the interval.
• staleWhileRevalidate defaults to 10 seconds and staleIfError to Infinity. Public inputs use seconds, including fractions; zero disables the corresponding stale allowance.
• Provided/bundled initialization and build/offline loading retain their existing behavior. Build embedding preserves optional fetchedAt.

Validation: 880 core package tests passed (19 suites; live-service integration suite excluded), TypeScript passed, and Biome passed on all TypeScript files changed since the previous push. Coverage includes freshness boundaries, confirmation without replacement, request isolation, shared/cancelled fetches, permanent stream/poll fallback, shutdown during startup, ping recovery, consecutive outage deadlines, retained cache data after startup timeout, and retry after failed fallback.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
flags-playground	Ready	Preview, v0	Sep 25, 2026 10:28am UTC
flags-sdk-dev	Ready	Preview, v0	Sep 25, 2026 10:28am UTC
flags-sdk-snippets	Ready	Preview, v0	Sep 25, 2026 10:28am UTC
flags-sdk-sveltekit-snippets	Ready	Preview, v0	Sep 25, 2026 10:28am UTC
shirt-shop	Ready	Preview, v0	Sep 25, 2026 10:28am UTC
shirt-shop-api	Ready	Preview, v0	Sep 25, 2026 10:28am UTC