[ChristianPavilonis]

Summary

• adds a design specification for TS-owned dynamic response caching under issue Design TS dynamic response caching for origin templates and RSC/API #859
• defines a Fastly-first, disabled-by-default origin-template cache that remains upstream of HTML transformation and per-user SSAT assembly
• documents canonical anonymous requests, bounded cache keys, strict response admission, TTL/SWR, request collapsing, purge semantics, runtime fallbacks, observability, and rollout
• records sanitized findings from a production Next.js App Router/headless CMS audit and uses them to defer transformed-template and RSC/API caching into measured later phases

Key decisions for discussion

• final SSAT HTML remains private, max-age=0 and never enters shared cache
• eligible template fetches use canonical cookie-free origin requests; configured login, preview, paywall, and personalization signals bypass
• query-bearing requests, authorization, ranges, prefetches, and non-document response families bypass in phase one
• unknown or unaccounted Vary fields reject storage; configured variants are finite and cardinality-bounded
• origin Set-Cookie, private, no-store, no-cache, and must-revalidate reject storage
• Fastly HTTP readthrough cache provides the custom key, collapsing, revalidation, TTL/SWR, and surrogate purge behavior
• Axum, Cloudflare, and Spin preserve the current original-request origin path
• transformed templates and RSC/API caching remain deferred until their representation and key cardinality are measured

Fastly constraints captured by the design

• actual stored bytes require a counting insertion transform; over-limit insertion fails closed
• the current adapter drops the SDK response before returning to core, so the one SWR request selected for revalidation may block at the adapter boundary
• unsafe 304 metadata follows a distinct failure path rather than returning an empty 304
• Fastly cache/send errors are not retried without proof that origin dispatch did not occur
• pinned Viceroy 0.17.0 cannot emulate Fastly HTTP readthrough cache behavior, so collapse, insertion, SWR, 304 update, and purge require staging verification

Scope

This PR is specification-only. It does not add cache configuration, runtime cache calls, purge routes, or source behavior changes.

This is a stacked PR based on #884 (issue-858-ssat-compression-offload).

Related to #859. The issue remains open for implementation planning and delivery.

Validation

• npx --yes prettier@3.8.1 --check docs/superpowers/specs/2026-07-10-ts-dynamic-response-caching-design.md
• git diff --check
• reviewed for privacy/cache-poisoning safety, Fastly 0.12.1 feasibility, and scope/acceptance coverage
• verified the committed spec contains no production domain, cookie value, or audit artifact

[aram356]

To be reviewed with #884