@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -0,0 +1,616 @@
+declare global {
+    interface CacheStorage {
+        readonly default: Cache;
+    }
+}
+/**
+ * Cloudflare Edge Cache Store
+ *
+ * Production cache store using Cloudflare's Cache API (L1) with optional
+ * KV persistence (L2).
+ *
+ * L1 (Cache API): Per-colo, fast, ephemeral. Handles SWR atomically.
+ * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
+ *
+ * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
+ * Write flow: L1 write + L2 write (both via waitUntil)
+ *
+ * Features:
+ * - Extended TTL for SWR window (max-age = ttl + swr)
+ * - Staleness via x-edge-cache-stale-at header
+ * - Atomic REVALIDATING status for thundering herd prevention (L1 only)
+ * - Non-blocking writes via waitUntil
+ * - KV L2 for cross-colo cache persistence
+ */
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
+import { type RequestContext } from "../../server/request-context.js";
+import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
+export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
+import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions } from "./cf-cache-types.js";
+export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
+export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    readonly supportsPassiveShellReads: true;
+    /** True when constructed without KV: the shell family no-ops (see ctor). */
+    readonly shellFamilyInert?: boolean;
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    private readonly namespace?;
+    private readonly explicitBaseUrl?;
+    private readonly waitUntil?;
+    private readonly version?;
+    private readonly edgeLookupTimeoutMs;
+    private readonly edgeReadTimeoutMs;
+    private readonly kvReadTimeoutMs;
+    private readonly debug?;
+    private readonly kv?;
+    private readonly onRevalidateTag?;
+    private readonly tagPurge?;
+    private readonly tagInvalidationTtl?;
+    private readonly tagCacheTtl;
+    constructor(options: CFCacheStoreOptions<TEnv>);
+    /**
+     * Warn about a namespace-scoped misconfiguration once per namespace per
+     * isolate. `seen` is the module-level Set for that message family -- Sets
+     * are module-level (not instance fields) so re-constructed stores in the
+     * same isolate don't re-warn.
+     * @internal
+     */
+    private warnOncePerNamespace;
+    /**
+     * Validate a consumer-supplied tagInvalidationTtl against CF KV's expirationTtl
+     * floor. A finite value below KV_MIN_EXPIRATION_TTL is raised to it (with a
+     * one-time warning) so invalidation keeps working instead of every marker
+     * write throwing; a non-finite or non-positive value returns undefined (the
+     * no-expiry default). The warning still notes the sizing rule: the TTL must
+     * exceed the largest entry TTL+SWR or invalidated entries can resurrect.
+     * @internal
+     */
+    private sanitizeTagInvalidationTtl;
+    /**
+     * Emit a debug event if `debug` is enabled. Swallows sink errors so a faulty
+     * debug callback can never break a cache read.
+     * @internal
+     */
+    private emitDebug;
+    /** Build-time-gated shell tier trace for deployed cross-colo diagnostics. */
+    private debugShell;
+    /**
+     * Resolve the cache-key base URL for the current cache operation.
+     * Prefers an explicit `baseUrl` option; otherwise derives it from the live
+     * request. Called per operation (from keyToRequest), which runs inside the
+     * request-context ALS, so deriveBaseUrl sees the request and can use the
+     * production host instead of the internal fallback.
+     * @internal
+     */
+    private resolveBaseUrl;
+    /**
+     * Derive base URL from request hostname via requestContext.
+     * Uses internal fallback for dev/preview environments and untrusted hostnames.
+     * Must run inside the request context (invoked lazily via resolveBaseUrl).
+     * @internal
+     */
+    private deriveBaseUrl;
+    /**
+     * Get the cache instance - uses caches.default unless namespace is specified.
+     * @internal
+     */
+    private getCache;
+    /**
+     * Race an async cache read against a latency budget. Shared by all three read
+     * tiers (L1 match, L1 body, L2/KV) so the timeout policy lives in one place:
+     * on timeout it returns `{ value: undefined, timedOut: true }` and logs
+     * `${label} exceeded ${budgetMs}ms; treating as miss`; the abandoned read is
+     * left to settle in the background (late rejection swallowed) rather than
+     * aborted, since the underlying CF primitives expose no cancellation. A budget
+     * <= 0 disables the bound and awaits the read directly. `read` is a thunk so
+     * the disabled path and the raced path start the read identically.
+     * @internal
+     */
+    private readWithTimeout;
+    /**
+     * Read from the L1 edge cache under the edgeLookupTimeoutMs budget. A `match`
+     * slower than the budget is abandoned and reported as a miss
+     * (`{ response: undefined, timedOut: true }`) so a degraded colo cannot stall
+     * the request; callers fall through to their normal miss path (L2/KV or
+     * render). The `timedOut` flag lets callers distinguish an abandoned slow
+     * match from a genuine miss for debug reporting; `error` is set when the
+     * `match` itself rejected (a transient L1 infra error) so the caller can
+     * report it as cache-read while still degrading to L2/KV -- distinct from a
+     * genuine miss (no entry), which sets neither flag.
+     * @internal
+     */
+    private matchWithTimeout;
+    /**
+     * Read and JSON-parse a matched L1 Response's body under the edgeReadTimeoutMs
+     * budget. CF resolves `match()` with a lazily-streamed body, so the latency
+     * tail surfaces here -- after matchWithTimeout has already passed -- not in the
+     * match itself. On timeout `undefined` is returned so the caller falls through
+     * to L2/KV or render.
+     * @internal
+     */
+    private readJsonWithTimeout;
+    /**
+     * Self-heal a corrupt L1 entry, then return the fall-through result. Reports
+     * the corruption as cache-corrupt (so an onError consumer sees it distinctly
+     * from a transient outage), runs the caller's L2/KV fall-through, and evicts
+     * the faulty per-colo entry ONLY when that fall-through found no good copy.
+     *
+     * The conditional evict is the load-bearing detail: when KV DOES serve a copy,
+     * kvGet* has already scheduled a same-key promote (`cache.put`); an eager
+     * `cache.delete` here would race that put with no CF Cache API ordering
+     * guarantee and could clobber the freshly-restored entry. So in that case we
+     * lean on #558's heal-by-overwrite (the non-suppressed fall-through promotes /
+     * a fresh render re-`set`s over the bad entry) and skip the delete. Only when
+     * this request's fall-through found no copy (=== null) is the eager evict
+     * scheduled -- useful then, since nothing else will overwrite the poison entry.
+     * A null fall-through can also be a KV-read TIMEOUT rather than a genuine miss:
+     * a concurrent request that read KV successfully may be promoting the same key,
+     * and this evict could race it. That is benign -- the worst case is one wasted
+     * colo-local promote, never a wrong served value, and the next read self-heals
+     * -- so we accept it rather than suppressing the evict on a timeout (which
+     * would strand the poison entry when KV really is empty). The evict is
+     * non-blocking (waitUntil) so it never adds latency to the degraded read.
+     * @internal
+     */
+    private healCorruptL1;
+    /**
+     * Re-put a stale L1 entry marked REVALIDATING, so concurrent requests serve it
+     * without each triggering a revalidation. Shared by get()/getItem().
+     *
+     * The write is NON-BLOCKING (waitUntil) and best-effort by design:
+     * - It runs in waitUntil, so it never adds the put latency to the served stale
+     *   read and a put failure can never turn that good read into a miss. The put
+     *   is still initiated synchronously (this.waitUntil invokes its callback
+     *   immediately), so concurrent readers see the marker land at the same time an
+     *   awaited write would -- awaiting only blocks the current request.
+     * - The background revalidation's fresh set() is gated behind a full re-render,
+     *   so it lands well after this put; a stale-clobbers-fresh race would require
+     *   this single put to be slower than that entire render+set, and self-heals
+     *   within MAX_REVALIDATION_INTERVAL.
+     *
+     * Cache-Control is recomputed to the REMAINING ttl from the stored hard-expiry
+     * deadline (see remainingCacheControl), not copied from the original
+     * full-window header -- copying it would restart CF retention on every re-arm
+     * and pin a perpetually-failing entry past hard-expiry. A legacy/tampered entry
+     * without a valid deadline floors to max-age=1 and self-heals via KV.
+     * @internal
+     */
+    private markRevalidating;
+    /**
+     * Document-tier counterpart of markRevalidating for getResponse's herd guard.
+     * The segment/item tiers JSON-parse the body, so they re-put with a string
+     * body; document bodies are streamed verbatim, so we re-put with a CLONED
+     * response body (`response.clone()`) supplied by the caller -- the original
+     * body still streams to the client while the marker carries the clone. Same
+     * REVALIDATING status header, same revalidating-at stamp, same
+     * remainingCacheControl re-put math as markRevalidating, so the document tier
+     * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
+     * window the segment tier does. Best-effort and non-blocking: a failed marker
+     * write must not affect the served stale read.
+     * @internal
+     */
+    private markResponseRevalidating;
+    /**
+     * Guard the segment tier against a `keyGenerator` that returns a key colliding
+     * with a reserved tag-marker namespace: `__tag__/` (the KV marker key) or
+     * `__tagmarker__/` (the L1 Cache API marker request). The item/doc tiers are
+     * internally prefixed (`fn:`/`doc:`) so only the bare segment key can collide;
+     * a collision would let a segment write clobber - or a segment read/delete
+     * evict - a live tag marker, silently breaking invalidation. Report loudly
+     * (so a misconfigured keyGenerator surfaces immediately) and treat the segment
+     * operation as a miss/no-op rather than corrupting the marker namespace.
+     * @internal
+     */
+    private isReservedSegmentKey;
+    /**
+     * Get cached entry data by key.
+     *
+     * Handles SWR atomically:
+     * - If stale and not already revalidating, marks as REVALIDATING and returns shouldRevalidate: true
+     * - If already REVALIDATING (and recent), returns shouldRevalidate: false
+     * - If fresh, returns shouldRevalidate: false
+     *
+     * On L1 miss, falls back to KV (L2) if configured.
+     * KV hits are promoted to L1 in the background.
+     */
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    /**
+     * Store entry data with TTL and optional SWR window.
+     * Uses waitUntil for non-blocking write when available.
+     * When KV is configured, also persists to L2.
+     */
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    /**
+     * Delete a cached entry from L1 and L2.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Get a cached Response by key (for document-level caching).
+     * Returns the response and whether it should be revalidated (SWR).
+     * Falls back to KV (L2) on L1 miss.
+     */
+    getResponse(key: string): Promise<{
+        response: Response;
+        shouldRevalidate: boolean;
+    } | null>;
+    /**
+     * Strip internal edge headers and restore the author's Cache-Control before a
+     * cached document Response is served to a client. L1 entries carry the
+     * internal staleness/status headers and a rewritten Cache-Control; none of
+     * those should reach the browser or an upstream CDN.
+     */
+    private toClientResponse;
+    /**
+     * Store a Response with TTL and optional SWR window (for document-level caching).
+     * When KV is configured, also persists to L2.
+     */
+    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
+    /**
+     * Get a cached function result by key.
+     * Follows the same SWR pattern as get() for segment caching.
+     * Falls back to KV (L2) on L1 miss.
+     */
+    getItem(key: string): Promise<CacheItemResult | null>;
+    /**
+     * Store a function result with TTL and optional SWR window.
+     * When KV is configured, also persists to L2.
+     */
+    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
+    /**
+     * Warn once per isolate that the shell family is inert: getShell/putShell
+     * are ONLY called for routes that declared the `ppr` path option, so firing
+     * here (not in the constructor) scopes the warning to apps that actually
+     * use PPR — a KV-less CFCacheStore is a perfectly fine config otherwise.
+     * Without it, the correctness-first fail-open (issue #651) is invisible:
+     * every ppr route is a permanent MISS with zero diagnostics.
+     * @internal
+     */
+    private warnShellFamilyInertOnce;
+    /**
+     * Get a cached PPR shell entry from Cache API, falling through to KV and
+     * promoting a valid KV hit. Both tiers store one envelope so the prelude,
+     * postponed state, snapshot, versions, and generation metadata cannot mix.
+     * SWR remains a plain staleness flag; the capture scheduler's module-level
+     * in-flight set is the recapture stampede guard.
+     */
+    getShell(key: string): Promise<{
+        entry: ShellCacheEntry;
+        shouldRevalidate?: boolean;
+    } | null>;
+    /**
+     * Store a PPR shell envelope in Cache API and, when its retention meets KV's
+     * 60-second floor, KV. The shared write is registered with waitUntil and
+     * awaited so invalidation rejection can be acknowledged to the capture
+     * scheduler. Short-lived shells remain useful in L1 even though KV rejects
+     * them.
+     */
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /** Rebuild the public shell entry from its validated storage envelope. */
+    private shellEnvelopeToEntry;
+    /** Build the Cache API representation of the coupled shell envelope. */
+    private shellEnvelopeResponse;
+    /** KV shell fallback with corruption checks and background L1 promotion. */
+    private kvGetShell;
+    /** Promote a valid KV shell into the per-colo Cache API tier. */
+    private promoteShellToL1;
+    /**
+     * Convert string key to Request object for CF Cache API.
+     * Includes version in URL if specified (for cache invalidation on code changes).
+     * @internal
+     */
+    private keyToRequest;
+    /**
+     * Convert string key to KV key string.
+     * Uses same version prefix as Cache API for consistent invalidation.
+     *
+     * Single chokepoint for EVERY KV family (segments, items, shells, documents
+     * via toDocKVKey, tag markers via tagMarkerKey): a composed key over
+     * Cloudflare KV's 512-byte limit is normalized to a preserved readable
+     * prefix plus a SHA-256-derived 128-bit digest of the FULL key. Without
+     * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
+     * and the entry silently never reaches L2 (observed in production for
+     * "use cache" items whose serialized args — e.g. a CMS query object — blow
+     * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+     * normalization is semantics-preserving as long as distinct logical keys
+     * stay distinct: colliding requires an identical 400-byte prefix AND a
+     * 128-bit SHA-256 collision. Deterministic, so every family's read, write,
+     * and delete paths agree on the stored key.
+     * @internal
+     */
+    private toKVKey;
+    /**
+     * Host token for the current request, used to namespace the document KV key.
+     * Derived from the same resolveBaseUrl() that namespaces the L1 (Cache API)
+     * tier, so a doc entry's KV twin lands under the identical host bucket.
+     * Falls back to "_" if the base URL cannot be parsed (it always carries a
+     * trailing-slash origin, so parsing succeeds in practice).
+     * @internal
+     */
+    private docKVHost;
+    /**
+     * Convert a document key to its host-namespaced KV key. The L1 tier already
+     * namespaces document entries by host via keyToRequest/resolveBaseUrl, but the
+     * KV fallback keyed only on `doc:{key}`, so two hosts serving the same path
+     * could collide on the KV tier (one host serving another's cached document).
+     * Prefixing the host closes that cross-host collision. Deterministic per
+     * (host, key). Segment/fn/tag-marker KV keys keep toKVKey unchanged: tag
+     * markers are intentionally global (invalidation must cross hosts), and the
+     * document tier is the one with a request-host context here.
+     * @internal
+     */
+    private toDocKVKey;
+    /**
+     * Best-effort delete of a single KV key, reporting (not swallowing) a delete
+     * failure as cache-delete. Used by the corrupt-entry self-heal paths.
+     * @internal
+     */
+    private evictKvKey;
+    /**
+     * Schedule a corrupt-entry KV eviction as a NON-BLOCKING background task
+     * (waitUntil) instead of awaiting it on the request path. The corrupt read has
+     * already resolved to a miss; awaiting an unbounded kv.delete here would re-add
+     * exactly the multi-second stall the read budgets exist to prevent when the KV
+     * namespace is degraded. evictKvKey never rejects (it reports its own failure),
+     * so the fire-and-forget fallback is safe when no waitUntil is available.
+     * @internal
+     */
+    private scheduleKvEvict;
+    /**
+     * KV-get a JSON envelope, EVICTING the key only when it is genuinely corrupt.
+     *
+     * Reads as { type: "text" }, NOT { type: "json" }, on purpose: the "json" form
+     * fuses the network read and the JSON parse, so a transient KV outage (5xx/429/
+     * network blip) is indistinguishable from a malformed body and would delete a
+     * still-good cross-colo entry - a self-inflicted miss storm. Reading text lets a
+     * transient read error propagate to the caller's outer catch (reported
+     * cache-read, the entry left intact); only a JSON.parse failure on a body that
+     * WAS successfully read - or an envelope that parses but fails `validate`
+     * (fields missing from a truncated write) - is true corruption that evicts +
+     * reports cache-corrupt. A MISSING key (kv.get -> null) is a normal miss.
+     * @internal
+     */
+    private kvGetOrEvict;
+    /** KV key for a tag's invalidation marker. */
+    private tagMarkerKey;
+    /**
+     * Header entries carrying an entry's tags (JSON-encoded, comma-safe) and the
+     * timestamp they were attached. Returns an empty object when there are no
+     * tags so untagged entries stay header-free and skip the invalidation check.
+     *
+     * Also stamps the namespaced `Cache-Tag` header (see entryCacheTags) so a
+     * Cloudflare purge-by-tag can evict the entry — the mechanism purge mode
+     * (tagPurge) relies on. Written unconditionally (not only in purge mode):
+     * it costs a small header and makes existing entries purgeable the moment a
+     * consumer turns purge mode on, with no re-render needed.
+     */
+    private tagHeaderEntries;
+    /**
+     * Joined entry Cache-Tag header value for `tags`, or null when it would
+     * exceed Cloudflare's aggregate header limit. Tokens are pure ASCII
+     * (encodeURIComponent output), so .length is bytes.
+     * @internal
+     */
+    private entryCacheTagHeader;
+    /**
+     * Write-path gate for the one configuration where an over-limit tag set has
+     * NO invalidation path: purge mode WITHOUT KV. There the entry Cache-Tag
+     * tokens are the only eviction mechanism, and a tag set whose header
+     * overflows CACHE_TAG_HEADER_MAX_BYTES gets no tokens — a purge could never
+     * evict the entry and there is no KV marker fallback, so it would serve
+     * stale until TTL while updateTag() reports success. Returns true (and
+     * warns once) so the caller SKIPS caching: the route simply renders fresh,
+     * which is the fail-safe direction. With KV configured the omitted-header
+     * entry falls back to the marker check (see tagHeaderEntries), and KV-less
+     * MARKER mode keeps its documented no-read-side-invalidation semantics —
+     * neither is gated.
+     * @internal
+     */
+    private skipUncacheableTagSet;
+    /**
+     * Merge the internal tag headers onto an existing Headers instance. The
+     * from-scratch paths spread tagHeaderEntries() into an object-literal init;
+     * the document put/promote paths build a Headers first, so they .set() each
+     * entry instead — except `Cache-Tag`, which is APPENDED: a document author
+     * may have set their own Cache-Tag, and clobbering it would break their CDN
+     * purging. Append produces the comma-merged list CF expects.
+     */
+    private setTagHeaders;
+    /** Read an entry's tags/taggedAt back from its headers. */
+    private readTagInfo;
+    /**
+     * Whether an entry tagged at `taggedAt` with `tags` has been invalidated since.
+     * Reads the per-tag invalidation markers from KV and returns true if any tag's
+     * latest invalidation is at or after taggedAt (>= so a same-millisecond
+     * invalidate wins, favouring freshness over staleness). Fails open: KV errors
+     * never turn a hit into a wrongful miss-storm beyond this single read.
+     */
+    private isGloballyInvalidated;
+    /**
+     * Tag-invalidation check for an L1 (Cache API) hit. In purge mode (tagPurge
+     * configured), invalidateTags() evicts L1 entries via a Cloudflare
+     * purge-by-tag call, so a hit that SURVIVED is trusted without a per-read
+     * marker lookup — that skipped lookup is the entire point of purge mode.
+     * Only the per-request memo is consulted (synchronous, no KV read) so a
+     * request that ran updateTag() still masks its own entries during the purge
+     * propagation window (read-your-own-writes).
+     *
+     * The trust is conditional on the entry actually CARRYING this store's
+     * entry Cache-Tag tokens (`headers`): an entry a purge cannot reach — one
+     * written before the tokens existed, or whose tag set overflowed the
+     * Cache-Tag header limit — keeps the full marker check, or purge mode
+     * would serve it stale until TTL with no eviction path.
+     *
+     * Without tagPurge this is the full marker cascade. KV-tier reads and
+     * shells always use isGloballyInvalidated directly: purge cannot reach KV,
+     * so the markers stay their invalidation mechanism.
+     * @internal
+     */
+    private isL1Invalidated;
+    /** Synthetic Cache API request for a tag's L1-cached invalidation marker. */
+    private tagMarkerRequest;
+    /**
+     * Read a tag's latest invalidation timestamp (or null if never invalidated)
+     * through the cascade: per-request memo -> per-colo L1 cache (only when
+     * tagCacheTtl > 0) -> KV (the global truth). The memo is always consulted
+     * first so it stays authoritative within a request (read-your-own-writes),
+     * and every KV/L1 result is written back into the memo. A Cache API miss
+     * always falls through to KV; absence is represented by a cached sentinel,
+     * never by a miss.
+     *
+     * Concurrent reads of the same tag within a request share one in-flight read
+     * (the resolved-value memo only collapses sequential reads; parallel segment
+     * loading would otherwise issue one KV read per concurrent reader).
+     * @internal
+     */
+    private readTagMarker;
+    /**
+     * Uncached body of readTagMarker: L1 (per-colo Cache API, opt-in via
+     * tagCacheTtl) -> KV. Writes the resolved value back into the memo.
+     * @internal
+     */
+    private fetchTagMarker;
+    /**
+     * Namespace token used inside every `rg:*` Cache-Tag. encodeURIComponent'd
+     * like the tag values: a raw namespace containing a comma would split into
+     * bogus tokens inside the comma-delimited Cache-Tag header — breaking both
+     * stripInternalCacheTags (internal tokens would leak to clients) and the
+     * purge match (the purged tag string never equals any stored token).
+     * @internal
+     */
+    private nsToken;
+    /**
+     * Cloudflare Cache-Tags written on a tag's L1 marker entry, namespaced per
+     * store so purges never collide with other Cache-Tags in the zone. Three
+     * tiers, broad to specific:
+     *   rg:{ns}            - everything this store cached (deploy/nuclear reset)
+     *   rg:{ns}:lk         - all tag-lookup markers
+     *   rg:{ns}:lk:{tag}   - this tag's lookup (the normal updateTag purge target)
+     * The namespace and tag value are encodeURIComponent'd so commas/spaces
+     * can't corrupt the comma-delimited Cache-Tag header.
+     * @internal
+     */
+    private lookupCacheTags;
+    /**
+     * Build one `{prefix}{tag}` Cache-Tag token, bounded to CACHE_TAG_TOKEN_MAX:
+     * an over-long encoded tag collapses to `{prefix}h:{fnv1a64(tag)}` so a
+     * legally-long application tag can never blow Cloudflare's per-tag purge
+     * limit (1,024 chars) or bloat the header. Deterministic, so the write-time
+     * token and the invalidate-time purge token always agree.
+     * @internal
+     */
+    private boundedTagToken;
+    /** The specific Cache-Tag a consumer purges to evict tag `tag`'s lookup. */
+    private lookupPurgeTag;
+    /**
+     * Cloudflare Cache-Tags written on a tagged DATA entry (segment/item/doc),
+     * mirroring the lookup-marker tiers but under `:e` (entry):
+     *   rg:{ns}       - everything this store cached (deploy/nuclear reset)
+     *   rg:{ns}:e     - all data entries
+     *   rg:{ns}:e:{t} - entries carrying tag `t` (the purge-mode invalidation
+     *                   target; see CFCacheStoreOptions.tagPurge)
+     * Namespace and tag value encodeURIComponent'd like the lookup tier.
+     * @internal
+     */
+    private entryCacheTags;
+    /** The specific Cache-Tag purged to evict entries carrying tag `tag`. */
+    private entryPurgeTag;
+    /**
+     * Whether an L1 entry's stored headers carry this store's entry Cache-Tag
+     * tokens — i.e. whether a purge-by-tag can actually evict it. False for an
+     * entry written before this feature existed, or one whose tag set exceeded
+     * CACHE_TAG_HEADER_MAX_BYTES (header omitted). Purge mode only trusts
+     * entries a purge can reach; the rest keep the marker check.
+     * @internal
+     */
+    private hasEntryCacheTags;
+    /**
+     * Drop this store's namespaced tokens (`rg:{ns}` and `rg:{ns}:*`) from a
+     * Cache-Tag header, keeping author-set tokens intact. Deletes the header
+     * when nothing remains. Serve-path counterpart of setTagHeaders' append.
+     * An author token that exactly equals a reserved `rg:{ns}` tier is stripped
+     * too — `rg:` is this store's documented-reserved Cache-Tag prefix.
+     * @internal
+     */
+    private stripInternalCacheTags;
+    /**
+     * Write a tag marker value into the per-colo L1 Cache API with tagCacheTtl.
+     * `null` is stored as the TAG_MARKER_ABSENT sentinel so "no marker yet" is
+     * cacheable (most tags are never invalidated - that is where the read savings
+     * come from). The entry also carries a namespaced Cache-Tag so an external
+     * purge-by-tag (via onRevalidateTag) can evict it across colos promptly,
+     * rather than waiting out tagCacheTtl. Best-effort.
+     * @internal
+     */
+    private putTagMarkerL1;
+    /**
+     * Invalidate every entry tagged with any of `tags`. Receives the whole batch
+     * from one updateTag()/revalidateTag() call so the eager-purge hook fires
+     * ONCE (one CDN purge request, not one per tag). For each tag: records the KV
+     * marker (the durable cross-colo truth that reads compare taggedAt against),
+     * writes the fresh marker straight into this colo's L1 (write-through, NOT
+     * delete - a delete would let the next read re-read a not-yet-converged KV
+     * value and re-arm the stale window), and memoizes it for same-request
+     * read-your-own-writes. In purge mode (tagPurge) it then AWAITS the
+     * consumer's purge-by-tag call with the entry Cache-Tags — the eviction the
+     * per-read marker skip on L1 hits relies on. Finally fires onRevalidateTag
+     * with the namespaced lookup Cache-Tags so a consumer purge evicts the
+     * cached lookups in other colos promptly (otherwise they converge within
+     * tagCacheTtl).
+     *
+     * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
+     * runs ONLY after that tag's KV marker write is confirmed. If any KV write
+     * fails (transient error; over-limit keys are normalized by toKVKey rather
+     * than rejected), this rejects with the
+     * failed tags so an awaiting updateTag() surfaces the failure instead of
+     * silently reporting success while other requests/colos serve stale data. The
+     * eager purge still fires for the whole batch first (it is additive).
+     */
+    /**
+     * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
+     * SAME KV markers used by runtime envelopes also evict immutable build shells
+     * and captures whose write races updateTag(). Thin public wrapper over the
+     * private envelope check (marker >= since, fail open).
+     */
+    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * KV fallback for segment cache reads.
+     * Returns null if KV is not configured, entry is missing, or expired.
+     * Promotes hits to L1 via waitUntil.
+     * @internal
+     */
+    private kvGetSegment;
+    /**
+     * Write segment data to KV.
+     *
+     * `dataJson` is the already-serialized CachedEntryData body also stored in
+     * L1 — embedded as envelope.d without a second JSON.stringify walk.
+     * @internal
+     */
+    private kvSetSegment;
+    /**
+     * Promote segment data from KV to L1 Cache API.
+     * @internal
+     */
+    private promoteSegmentToL1;
+    /**
+     * KV fallback for function cache reads.
+     * @internal
+     */
+    private kvGetItem;
+    /**
+     * Promote function cache data from KV to L1.
+     * @internal
+     */
+    private promoteItemToL1;
+    /**
+     * KV fallback for document cache reads.
+     * @internal
+     */
+    private kvGetResponse;
+    /**
+     * Promote document cache data from KV to L1.
+     * @internal
+     */
+    private promoteResponseToL1;
+}