fix(router): stabilize rango-state cookie — review findings + test gaps - #566

Stacked on #560 (base: feat/rango-state-cookie). This is the stabilization delta for the rango-state cookie work — three adversarial review rounds over #560 surfaced one latent data bug, three fence/guard correctness defects, and a set of missing contracts. Review it as the diff on top of #560.

Problem statement (consumer-observable)

Three issues a consumer could actually hit, none caught by #560's own tests:

1. A deploy mid-action could brick a tab. If a server action hits a freshly-deployed (version-mismatched) worker and the user cancels the resulting reload (a beforeunload "Stay" on a dirty form), the action fence leaked permanently: prefetch consumption stayed suspended and every fetch went no-store/SWR for the rest of the session.
2. A build version containing : or % silently defeated cache invalidation. The server's monotonic guard double-decoded the prior state value, so a same-millisecond server rotation could mint a value equal to the client's — the divergence observer never fired and the client kept serving stale, Vary-keyed bytes.
3. A pinned version could leak one user's Set-Cookie to another. The CF response cache stripped per-client signals only on write. A KV envelope written by a pre-fix build, or persisted under a consumer-pinned options.version, replayed its stored Set-Cookie (a session/consent cookie a loader set) to the next client for the whole ttl+swr window.

Before / after

(2) Server monotonic guard — request-context.ts:

// before: getParsedCookies() decodeURIComponent's the value, so a wire value
// "a%3Ab:1700000000" parses to "a:b:1700000000" -> split on the wrong ':'
// -> NaN timestamp -> prevTs 0 -> a same-ms server mint can equal the client.
const prevRaw =
  request.headers.get("x-rango-state") ??
  getParsedCookies()[stateCookieName] ?? null;

// after: raw read (decoded exactly once by decodeStateValue, matching the
// client), shared parser, and '' header/cookie counts as absent.
const prevRaw =
  (request.headers.get("x-rango-state") || null) ??
  getRawCookieValue(cookieHeader, stateCookieName);

(3) CF read-side strip — cf-cache-store.ts:

// before: kvGetResponse rebuilt the served Response and re-seeded L1 from
// envelope.hd verbatim; toClientResponse stripped only internal CACHE_* headers.
const headers = new Headers(envelope.hd);

// after: strip per-client signals on every serve path. Inside the corrupt-
// envelope try, so a malformed hd evicts instead of throwing through.
envelope.hd = envelope.hd.filter(([name]) => !isPerClientSignalHeader(name));
const headers = new Headers(envelope.hd);
// ...and toClientResponse() now also calls stripPerClientSignals(headers).

Terminal semantics (the fence-leak class)

Every action terminal must release the fence exactly once; the never-settling navigate-away terminals can't rely on the finally.

The reload row is the one this PR adds — it was the only never-settling terminal without an explicit release. It skips invalidation deliberately: nothing executed server-side, and a broadcast would only risk hard-reloading a sibling tab mid-task.

Code-change summary

• browser/server-action-bridge.ts — finalizeAction(skipInvalidation?) + try/finally; onReload releases the fence without invalidating; ungated repair-refetch comments point at the spec keep row.
• server/request-context.ts — raw monotonic-guard read via shared getRawCookieValue; empty header/cookie treated as absent; local parser removed.
• cache/cf/cf-cache-store.ts — read-side strip in toClientResponse + kvGetResponse (filter inside the corrupt-envelope try).
• browser/cookie-name.ts — single PER_CLIENT_SIGNAL_HEADERS source; stripPerClientSignals; shared getRawCookieValue (also used by the client readCookie).
• browser/{navigation-store,types}.ts — removed dead broadcastCacheInvalidation.
• Docs — design-doc terminal enumeration (+reload), keep-row exemption + end-state-delta, read-side strip rule; feature-file-map (+action-fence).

Test plan

• pnpm run typecheck
• pnpm run test:unit — 3630 pass (+ new: latch per terminal incl. reload times(0), equals-mirror observer, credentials/no-store on nav + prefetch, percent-encoded + empty header/cookie mint, CF KV-replay strip, malformed-hd evict, L1-serve strip)
• pnpm run lint / pnpm run format
• semantic matrix — green (dev + production)
• e2e dev + production — cookie-cleared-mid-session mints via popstate; Back-after-redirect revalidates the pre-mutation page
• pnpm check:e2e-bucketing (pre-commit) — every build-fixture describe correctly bucketed

Notes

• Deliberately not changed (verified, left alone): the getRangoState() double-read (load-bearing — the await between the prefetch-key read and the header read lets an external rotation correctly miss the stale entry); abort-before-response rotating despite keep intent (fail-toward-freshness).
• Deferred to follow-up (pure cleanup, no behavior): extracting a buildPayloadMetadata() helper across the five RSC render sites; hoisting the e2e readRangoState parser into the shared helper.