feat(plugin): split swr out of cache-hit + per-route serve/age metrics; v0.33.0

[harper-joseph]

Why

Phase 1 of TTL-decision telemetry: make "should this route's renderInterval move up or down" answerable from recorded metrics instead of a one-off investigation. Two gaps found while tuning the kohls TTLs:

1. An SWR serve is recorded as hit. cacheStatus: 'hit' covers everything inside expiresAt + swrTtl, so the headline hit rate can't distinguish "TTL is being met" from "we're serving out of the stale window because the re-render is late". At one measured point, 71.9% "hit" quietly included ~13% of the corpus being served past expiry.
2. Nothing is recorded per route. TTLs are per route (home 1h / catalog 6h / PDP 48h on kohls), but bot_serve/page_age aggregate across all of them, so a per-route TTL decision has no data.

What

• bot_serve cacheStatus splits hit → hit | swr. hit = expiresAt still ahead (the renderInterval is being met); swr = past expiresAt, inside the stale-while-revalidate window. The serve itself is unchanged, and the source dimension is untouched (origin-offload reads identically). The x-harper-cache debug header reports the same split.
• New route_serve (route, cacheStatus, deviceType) — per-route delivery: swr/stale share says whether that route's cadence is being delivered; miss share says whether its corpus is covered.
• New route_page_age (route, cacheStatus, deviceType; ms since render, cache-served only) — served age against that route's own interval: the direct "should this TTL move" number.
• The hit/swr boundary is one exported pure function, cacheServeStatus(expiresAtMs, swrTtl, now), with its edges pinned in tests (expiry instant is already swr; window edge exclusive; NaN never serves; swrTtl: 0 disables the window).

Why separate metrics instead of a 4th dimension

recordAnalytics has exactly three dimension slots (path/method/type — verified in harper-pro dist/core/resources/analytics/write.js), and bot_serve uses all three. Route label cardinality is tiny and stable: the matched route's path, else the route class, else 'unrouted'.

Why the request path, not the backlog snapshot

The kohls deployment just disabled the 15-min backlog snapshot timer (kohls-pr#52) because its getRecordCount walk issues a multi-second synchronous native iteration that stalls worker 0 and bot serving (harper-pro#664). These metrics ride the request path instead: two boolean counter bumps per request, two numeric samples on cache serves, buffered in-memory by recordAnalytics — no storage touch, no await, nothing on the response path, and nothing that runs when no bots are being served.

Breaking-ish

Dashboards keying bot_serve on cacheStatus='hit' will see it split into hit + swr after this release — sum them to recover the old cache-served rate. Dimension order is unchanged everywhere.

Tests

392/392 pass (7 in botServe.test.js, covering dimension order for all four metrics, the route-label fallback chain, swr propagation, the age guards, and the cacheServeStatus edges). Lint + format clean.

Follow-ups (not this PR)

• Per-route swrTtl alongside renderInterval (the global value can't fit 1h/6h/48h intervals at once).
• Admin Overview panel reading these metrics (needs the node-local vs cluster aggregation decision noted in admin/views/overview.js).
• Phase 2: content-drift sampling (cached snapshot vs live origin per route) — separate project, hosting decision pending.

[gemini-code-assist]

Code Review

This pull request bumps the package version to 0.33.0 and introduces per-route analytics tracking for the prerender plugin. Specifically, it adds route_serve and route_page_age metrics to allow independent tuning of each route's render interval. It also refactors the cache freshness logic by introducing a cacheServeStatus helper function to distinguish between 'hit' and 'swr' (stale-while-revalidate) cache statuses. Comprehensive unit tests have been added to verify these new metrics and helper logic. There are no review comments to address, and I have no additional feedback to provide.

[harper-joseph]

Self-review pass for efficiency + maintainability, one commit added:

Efficiency (verified, no change needed): the serve path gained two numeric comparisons (cacheServeStatus — NaN falls out of the comparisons, so the old isNaN call is actually gone) and two recordAnalytics calls per request — each a string-key Map bump, no allocation, no await, gated on analytics.enabled. Nothing rides the backlog snapshot (disabled on kohls per harper-pro#664).

Maintainability (fixed): PrerenderAdmin.js carried three hand-copied freshness computations, one commented "same rule the serving path applies, so this cannot disagree" — aspirational, not structural. cacheServeStatus moved to util/pageFreshness.js (resources shouldn't import from a handler module) and all three admin sites now call it. grep confirms zero remaining copies. renderNow's lastCached >= since deliberately stays separate — different concept (re-rendered since request start, not swr servability).

392/392 tests, lint + format clean.