EXP-3418: skip init wait when the routed config version is already loaded

[luismeyer]

EXP-3418

@vercel/flags-core waits for a stream confirmation or a first poll on every cold start, even when the definitions it already has in hand are current. Vercel already tells us which config version a request was routed to, so that wait is avoidable.

What changed

• Parser — src/utils/edge-config-versions.ts parses the existing x-vercel-edge-config-versions request header, a semicolon-separated map of store name to version (flags_prj_123=1758000000000;ecfg_abc=1757000000000). It selects only the exact flags_<projectId> entry — no prefix, suffix or substring matching — and accepts only non-negative safe integers.
• Decision — src/controller/routed-init.ts reads the header from the existing Vercel request context (utils/request-context.ts), derives the key from the projectId of the loaded data, and compares the local configUpdatedAt against the routed version.
• Controller — after local data loads (provided datafile or bundled definitions) but before awaiting stream/poll, initialize() returns immediately when local configUpdatedAt >= routed version, while the stream (or poll + interval) keeps updating in the background.

No config id is involved and no new header is requested — only the header that is already on the request context.

Preserved behavior

All of these keep waiting up to initTimeoutMs exactly as before:

• no request context, or a context without headers
• no projectId on the loaded data
• no exact entry for this project (including keys that merely overlap)
• malformed or unsafe versions: empty, non-numeric, signed, fractional, exponent/hex, NaN/Infinity, beyond Number.MAX_SAFE_INTEGER
• the routed key appearing more than once (reported, never resolved to one of them)
• loaded data without a usable configUpdatedAt

Two more invariants are covered by tests:

• No connection is reported before one exists. The controller stays in initializing:* after an immediate init, so reads report connectionState: 'disconnected' and mode: 'offline' until the source emits connected.
• Newer state is never replaced by equal or older data. The existing configUpdatedAt guard still applies to the background stream/poll updates.

Metrics

FLAGS_CONFIG_READ events carry a new configRoutedInit field — one of immediate, behind, invalid, duplicate, unknown-local. It is a fixed low-cardinality enum, carries no project ids or header values, and is omitted entirely when no routed version applied, so existing event payloads are unchanged.

Tests

• src/utils/edge-config-versions.test.ts — 18 focused parser tests (exact match, whitespace, duplicates, malformed/unsafe versions)
• src/controller/routed-init.test.ts — 31 focused decision tests (missing context/project/match, comparison, unsafe values on both sides)
• src/black-box.test.ts — 23 tests through the public API: immediate init for provided datafile, equal version, bundled definitions and polling mode; the full preserve-behavior table; connection reporting; the equal/older guard; and the metric assertions including a negative check that no ids or header values are ingested

pnpm test        565 passed (15 files), was 493
pnpm type-check  clean
pnpm check       clean (1 pre-existing warning, unchanged from main)
pnpm build       success

Repo-wide pnpm type-check (18/18) and pnpm test (17/17) also pass.

Notes

• cacheStatus stays STALE during the immediate-init window because it is derived from the connection state, matching the existing timeout-fallback and polling-with-data paths. Changing that is a separate metrics decision.
• Biome's autofix wanted to rewrite an unrelated mock in src/index.make.test.ts in a way its own comment forbids; that change was reverted and is not part of this PR.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
flags-playground	Ready	Preview, v0	Sep 2, 2026 9:19am UTC
shirt-shop	Ready	Preview, v0	Sep 2, 2026 9:19am UTC
shirt-shop-api	Ready	Preview, v0	Sep 2, 2026 9:19am UTC