chore(router): #684 follow-ups — DRY consolidations + docs-api guard over caching/PPR skills - #686

Closes out groups A (DRY consolidations) and D (tooling) of #684. Chore-class PR: no consumer-visible behavior change; cache key strings and warning text are byte-identical to before.

Problem statement

The #685 audit wave landed three new code sites that each correctly mirrored an established idiom inline (blocked-redirect landing, host-namespaced cache key, once-per-namespace warn). Idioms copied inline drift; #684-A asks for one owner each. Separately (#684-D), the caching/PPR skills teach API surface with no existence guard — the render-callable cacheTag() drift (plan 003) recurred silently because check:docs-api only covered README + why-rango.

Changes

1. safeSameOriginLanding(basename) — new in src/redirect-origin.ts beside the two resolvers. rsc/redirect-guard.ts:82 and resolveShellHitRedirectTarget (rsc/rsc-rendering.ts) now share the one "where does a blocked redirect go" answer.

2. cacheKeyBase(host, pathname, searchParams?, params?) — new in src/cache/cache-key-utils.ts (the module that already owns the sort helpers). cache-scope.ts dropped its private getCacheKeyBase; document-cache.ts dropped its inline default-key template. Both tiers now compose ${host}${pathname}[:params][?search] from the one function; the JSDoc pins the byte-stability contract (changing the composition silently invalidates every persisted entry). The consumer keyGenerator branch is untouched.

3. CFCacheStore.warnOncePerNamespace(seen, message) — private method collapsing the three open-coded namespace ?? "default" + Set dances (no-KV read invalidation, tagInvalidationTtl floor, no-TTL marker growth).

4. check:docs-api now guards the 8 caching/PPR skills (cache-guide, caching, defer-hydration, document-cache, ppr, prerender, shell-manifest, use-cache). The shakedown immediately caught two things:

   • a real guard false-negative: class declarations sit in none of the definition-ish positions the regex matched, so Skip (src/errors.ts:267, taught by the prerender skill) MISSed. Added a class <name> alternation.
   • createHydrationGate — a suggested userland factory name in the defer-hydration recipe, allowlisted like the existing withCaching/withAuth.

   Guard now verifies 167 identifiers (was 68 over the two positioning docs).

Internal docs updated in the same PR: feature-map.md + feature-file-map.md (three shared redirect-origin rules; cache-key-utils.ts added to the Cache APIs row).

Deliberately unchanged

Test plan

• pnpm run typecheck clean
• pnpm run test:unit:all — all packages pass (router 108 targeted: document-cache, cf-cache-store-tags, shell-hit-redirect-guard; full recursive run green)
• pnpm run lint (oxlint --deny-warnings) 0/0
• pnpm run format clean on all touched files
• node tools/check-docs-api.mjs — 167 identifiers verified
• No new tests: pure consolidation; existing suites pin the behavior (key shapes via document-cache/cache-scope tests, landing via shell-hit-redirect-guard.test.ts + redirect-guard suites, warn-once via cf-cache-store-tags.test.ts)
• No route changes → no *.gen.ts churn (verified git status empty of .gen.ts)

Notes

Groups B and C of #684 are reported on the issue directly: B (shell-HIT redirect flip e2e) is not deterministically reachable through real routing — analysis with path:line evidence in the issue comment; C investigations ran as five independent read-only agents, verdicts posted there.