@rangojs/router 0.7.0 → 0.8.0

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

@@ -30,8 +30,6 @@ import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOpti
 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?;
@@ -43,6 +41,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly kvReadTimeoutMs;
     private readonly debug?;
     private readonly kv?;
+    /** True when constructed without KV: no durable tag history (see ctor). */
+    readonly tagHistoryInert?: boolean;
     private readonly onRevalidateTag?;
     private readonly tagPurge?;
     private readonly tagInvalidationTtl?;
@@ -257,15 +257,26 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     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.
+     * Warn once per isolate that a TAGGED shell landed on a store with no
+     * eviction path for it: no KV (markers) and no tagPurge (purge-by-tag).
+     * The shell still caches and expires by ttl+swr, but updateTag()/
+     * revalidateTag() cannot reach it — silent staleness a consumer who tagged
+     * the route clearly did not intend. Fired from putShell (not the
+     * constructor) so an untagged edge-only ppr config stays warning-free.
      * @internal
      */
-    private warnShellFamilyInertOnce;
+    private warnShellTagsNoEvictionOnce;
+    /**
+     * Generation gate for shell writes and the capture scheduler
+     * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
+     * Without KV there are no markers: in purge mode the per-request memo is
+     * the only signal — a capture racing THIS request's updateTag() is still
+     * rejected (read-your-own-writes), while cross-request races are bounded
+     * by ttl+swr exactly like the data families' purge-mode writes. Without
+     * either, fail open (ttl/swr-only semantics, warned at putShell).
+     * @internal
+     */
+    private isShellGenerationInvalidated;
     /**
      * 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,
@@ -278,13 +289,14 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
         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.
+     * Store a PPR shell envelope in Cache API and, when KV is configured and
+     * the retention meets its 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; a KV-less store is L1-only by design
+     * (edge-only ppr — see the section comment).
      */
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     /** Rebuild the public shell entry from its validated storage envelope. */
     private shellEnvelopeToEntry;
     /** Build the Cache API representation of the coupled shell envelope. */
@@ -569,7 +581,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * 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).
+     * shell generation check (marker >= since, fail open); KV-less it degrades
+     * to the per-request memo in purge mode and to false otherwise — see
+     * isShellGenerationInvalidated.
      */
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
     invalidateTags(tags: string[]): Promise<void>;

package/dist/types/cache/shell-snapshot.d.ts

@@ -90,7 +90,7 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }
 /** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
@@ -181,6 +181,6 @@ export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheSto
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }

package/dist/types/cache/types.d.ts

@@ -161,18 +161,37 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * @param tags - Optional cache tags for invalidation (participates in
      *   invalidateTags via the same tag machinery as the item family)
      * @returns `invalidated` when a generation marker rejected the write,
-     *   `stored` when acknowledged, or void for stores without acknowledgements.
+     *   `stored` when acknowledged, `uncacheable` when the entry can NEVER be
+     *   stored under the current configuration (every retry would refuse
+     *   identically — the capture scheduler backs the key off instead of
+     *   recapturing per MISS; CFCacheStore returns it for a tag set whose
+     *   Cache-Tag header overflows in KV-less purge mode), or void for stores
+     *   without acknowledgements.
      */
-    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     /**
      * Declares the shell family present-but-inert: getShell/putShell exist but
-     * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
-     * captures whose only write target is inert — the background render would be
-     * dead work that still occupies the per-isolate serialized capture queue
-     * (a promise-heavy route bakes for seconds per MISS with nothing stored).
-     * Absent/false means the family, when present, actually stores.
+     * no-op (a custom store whose backing tier is conditionally unavailable).
+     * scheduleShellCapture skips captures whose only write target is inert —
+     * the background render would be dead work that still occupies the
+     * per-isolate serialized capture queue (a promise-heavy route bakes for
+     * seconds per MISS with nothing stored). Absent/false means the family,
+     * when present, actually stores. The built-in stores never declare it:
+     * CFCacheStore is L1-only without KV (edge-only ppr), not inert.
      */
     shellFamilyInert?: boolean;
+    /**
+     * Declares isTagsInvalidatedSince present-but-inert: the store implements
+     * the method but has no DURABLE invalidation history behind it (a KV-less
+     * CFCacheStore answers from the per-request memo at best). Runtime shells
+     * tolerate that — purge eviction plus ttl/swr bound their staleness — but
+     * a TAGGED build-manifest shell is immutable with no ttl of its own, so
+     * serving it on such a store would make updateTag() a permanent no-op for
+     * it. The build-shell read-through declines tagged entries on this flag
+     * (same declared-intent-cannot-be-honored doctrine as a store missing the
+     * method entirely). Absent/false means answers are durably backed.
+     */
+    tagHistoryInert?: boolean;
     /**
      * Get a cached function result by key.
      * Returns the serialized value, optional handle data, and staleness flag.

package/dist/types/rsc/shell-capture.d.ts

@@ -126,9 +126,10 @@ export interface ShellCaptureDebugEvent {
      *   the capture was not attempted
      * - skip-capacity: the isolate capture queue is full; a later request may retry
      * - skip-inert-store: the resolved store's shell family is missing or
-     *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
-     *   without a KV namespace); nothing could store the result, so the
-     *   background render was not scheduled at all
+     *   declared inert (SegmentCacheStore.shellFamilyInert — a custom store
+     *   whose backing tier is unavailable; built-in stores never declare it);
+     *   nothing could store the result, so the background render was not
+     *   scheduled at all
      * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
      *   behind other captures and was dropped unrun (no backoff — the route is
      *   not doomed, the isolate was busy; a later request re-probes). Carries
@@ -160,7 +161,7 @@ export interface ShellCaptureDebugEvent {
     /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
     untaggedBake?: true;
     /** Outcome reported by a store that supports shell-write acknowledgements. */
-    storeWrite?: "stored" | "invalidated";
+    storeWrite?: "stored" | "invalidated" | "uncacheable";
     /** Consecutive failure count in the key's backoff entry, when one exists. */
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */

package/dist/vite/index.js

@@ -3685,7 +3685,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -176,20 +176,6 @@
     "access": "public",
     "tag": "latest"
   },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:preload": "playwright test --config=playwright.preload.config.ts",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.31",
@@ -206,18 +192,18 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "vitest": "^4.1.9"
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -256,5 +242,18 @@
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:preload": "playwright test --config=playwright.preload.config.ts",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/cloudflare/SKILL.md

@@ -130,9 +130,11 @@ export const router = createRouter<AppBindings>({
 ```
 
 PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
-L2; a KV hit promotes the coupled shell envelope back into L1. KV remains
-required for this family. `CFCacheStore` without `kv` can still cache
-segment/response entries in Cache API, but its shell family is inert.
+L2; a KV hit promotes the coupled shell envelope back into L1. KV is optional:
+`CFCacheStore` without `kv` runs the shell family L1-only (edge-only ppr —
+each colo captures and serves its own shell). Tag eviction then needs purge
+mode (`tagPurge`); a tagged shell without either warns once and expires by
+ttl+swr only.
 
 ## Commands
 

package/skills/ppr/SKILL.md

@@ -356,13 +356,17 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   key — no header + a declared `ppr` means look for that warning.
 - On Cloudflare, `CFCacheStore` reads PPR shells from the per-colo Cache API,
   falls through to KV on a miss, and promotes the KV hit back into that colo.
-  WITHOUT a KV namespace its shell family remains inert: every ppr route stays
-  `MISS` forever. The store warns once per isolate — bind KV
-  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store. An
-  inert store also stops captures at the gate: the store declares
-  `shellFamilyInert` and the scheduler skips the background render entirely
-  (`skip-inert-store` on the debug event) instead of burning a full capture per
-  MISS whose write could only no-op.
+  WITHOUT a KV namespace the family runs L1-only (edge-only ppr): every colo
+  captures and serves its own shell from the Cache API. What changes KV-less
+  is tag eviction — with `tagPurge` the purge-by-tag evicts shell L1 entries;
+  without it a TAGGED shell warns once that `updateTag()` cannot reach it
+  (ttl/swr-only freshness). Untagged edge-only ppr is warning-free. Tagged
+  BUILD-manifest shells decline on a KV-less store (`tagHistoryInert` — the
+  immutable asset could never be evicted), and an over-limit tag set is
+  acknowledged `"uncacheable"` so the capture backs off instead of
+  re-rendering per MISS. A custom store can still declare `shellFamilyInert`
+  to stop captures at the gate (`skip-inert-store` on the debug event); the
+  built-in stores never do.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each

package/src/cache/cf/cf-cache-store.ts

@@ -145,11 +145,12 @@ const warnedNoKvReadInvalidation = new Set<string>();
 const warnedTagInvalidationTtlFloor = new Set<string>();
 
 /**
- * Stores (by namespace) already warned about the shell family being inert
- * (getShell/putShell no-op without a KV namespace), so a ppr route hitting the
- * silent fail-open warns once per isolate instead of on every request.
+ * Stores (by namespace) already warned that a TAGGED shell was written on a
+ * KV-less store without tagPurge: no markers and no purge means updateTag()
+ * cannot reach the shell (freshness is ttl/swr only). Once per isolate, not
+ * per capture (CFCacheStore is constructed per request).
  */
-const warnedShellFamilyInert = new Set<string>();
+const warnedShellTagsNoEviction = new Set<string>();
 
 /**
  * Stores (by namespace) already warned that tag invalidation is writing KV
@@ -412,8 +413,6 @@ interface KVResponseEnvelope {
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   readonly supportsPassiveShellReads: true = true;
-  /** True when constructed without KV: the shell family no-ops (see ctor). */
-  readonly shellFamilyInert?: boolean;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -429,6 +428,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly kvReadTimeoutMs: number;
   private readonly debug?: (event: CFCacheReadDebugEvent) => void;
   private readonly kv?: KVNamespace;
+  /** True when constructed without KV: no durable tag history (see ctor). */
+  readonly tagHistoryInert?: boolean;
   private readonly onRevalidateTag?: (tags: string[]) => Promise<void>;
   private readonly tagPurge?: (cacheTags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
@@ -485,11 +486,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
-    // The shell family requires KV (getShell/putShell no-op without it — see
-    // warnShellFamilyInertOnce). Declaring it lets scheduleShellCapture skip
-    // captures whose write could only no-op instead of burning a background
-    // render per MISS that still occupies the serialized capture queue.
-    this.shellFamilyInert = options.kv ? undefined : true;
+    // Without KV, isTagsInvalidatedSince has no durable history — it answers
+    // from the per-request memo at best. Runtime shells tolerate that (purge
+    // eviction + ttl/swr bound the staleness), but an immutable TAGGED
+    // build-manifest shell must not serve on such a store: nothing could ever
+    // evict it (purge cannot delete a build asset), so the manifest gate
+    // declines on this flag (shell-build-manifest.ts).
+    this.tagHistoryInert = options.kv ? undefined : true;
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -506,9 +509,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // marker write throw and break ALL invalidation. Floor it (and warn once);
     // a non-finite/non-positive value falls back to the no-expiry default
     // (markers persist) rather than silently sailing a NaN into expirationTtl.
-    this.tagInvalidationTtl = this.sanitizeTagInvalidationTtl(
-      options.tagInvalidationTtl,
-    );
+    // KV-less the option is dead config — no markers to expire, and the
+    // retention cap it used to imply is KV-conditional (putShell) — so it is
+    // dropped without the KV-floor validation/warning, which would misdirect.
+    this.tagInvalidationTtl = options.kv
+      ? this.sanitizeTagInvalidationTtl(options.tagInvalidationTtl)
+      : undefined;
     // tagCacheTtl gates the L1 marker cache via `> 0`. A non-finite value (NaN
     // from `Number(env.UNSET)`) is not null/undefined, so `?? 0` would let it
     // through and silently disable the cache while reading as "configured".
@@ -1876,40 +1882,75 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   // ============================================================================
-  // Shell Cache Methods (PPR shell resume) — Cache API L1 + KV L2
+  // Shell Cache Methods (PPR shell resume) — Cache API L1 + optional KV L2
   // ============================================================================
   //
-  // KV remains the durable, cross-colo shell tier. Cache API is a per-colo
-  // read-through accelerator: writes populate both tiers, and a valid KV hit
-  // promotes the same coupled envelope into L1. The family still requires KV;
-  // without it, getShell/putShell no-op and PPR fails open to a full HTML render.
+  // With KV it is the durable, cross-colo shell tier: writes populate both
+  // tiers, a valid KV hit promotes the same coupled envelope into L1, and
+  // shell L1 hits deliberately keep the KV generation-marker check even in
+  // purge mode. A shell's taggedAt is its CAPTURE START, not its write time:
+  // an invalidation can purge while an older capture is still running, then
+  // that capture can land after the purge. The marker check rejects that
+  // resurrection.
   //
-  // Shell L1 hits deliberately keep the KV generation-marker check even in
-  // purge mode. A shell's taggedAt is its CAPTURE START, not its write time: an
-  // invalidation can purge while an older capture is still running, then that
-  // capture can land after the purge. The marker check rejects that resurrection.
+  // Without KV the family is L1-only (edge-only ppr): every colo captures and
+  // serves its own shell from the Cache API. Tag eviction then needs purge
+  // mode (tagPurge) — shell L1 entries carry the same namespaced Cache-Tag
+  // tokens as the data families, read-your-own-writes comes from the
+  // per-request marker memo, and the capture resurrection race narrows to
+  // cross-request timing bounded by ttl+swr (the data families' documented
+  // purge-mode stance). KV-less WITHOUT tagPurge still caches: freshness is
+  // ttl/swr only, and a tagged write warns once that invalidation cannot
+  // reach it (see warnShellTagsNoEvictionOnce).
 
   /**
-   * 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.
+   * Warn once per isolate that a TAGGED shell landed on a store with no
+   * eviction path for it: no KV (markers) and no tagPurge (purge-by-tag).
+   * The shell still caches and expires by ttl+swr, but updateTag()/
+   * revalidateTag() cannot reach it — silent staleness a consumer who tagged
+   * the route clearly did not intend. Fired from putShell (not the
+   * constructor) so an untagged edge-only ppr config stays warning-free.
    * @internal
    */
-  private warnShellFamilyInertOnce(): void {
+  private warnShellTagsNoEvictionOnce(): void {
     this.warnOncePerNamespace(
-      warnedShellFamilyInert,
-      `[CFCacheStore] a ppr route resolved to this store, but no KV namespace ` +
-        `is configured, so the shell family (getShell/putShell) is a no-op: ` +
-        `every ppr route stays a permanent shell MISS (the page still serves ` +
-        `via a full render). Bind a KV namespace and pass it — ` +
-        `new CFCacheStore({ ctx, kv: env.CACHE_KV }) — or use a shell-capable ` +
-        `store via createRouter({ cache }).`,
+      warnedShellTagsNoEviction,
+      `[CFCacheStore] a ppr shell with tags was stored on a KV-less store ` +
+        `without tagPurge: tag invalidation cannot evict it (no KV markers, ` +
+        `no purge-by-tag), so updateTag()/revalidateTag() will not reach ` +
+        `this shell — it serves until ttl+swr expiry. Configure { kv } for ` +
+        `marker invalidation or { tagPurge } for purge-by-tag eviction; ` +
+        `untagged ppr routes (ttl/swr freshness) are unaffected.`,
     );
   }
 
+  /**
+   * Generation gate for shell writes and the capture scheduler
+   * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
+   * Without KV there are no markers: in purge mode the per-request memo is
+   * the only signal — a capture racing THIS request's updateTag() is still
+   * rejected (read-your-own-writes), while cross-request races are bounded
+   * by ttl+swr exactly like the data families' purge-mode writes. Without
+   * either, fail open (ttl/swr-only semantics, warned at putShell).
+   * @internal
+   */
+  private async isShellGenerationInvalidated(
+    tags: string[] | undefined,
+    since: number | undefined,
+  ): Promise<boolean> {
+    if (this.kv) return this.isGloballyInvalidated(tags, since);
+    if (!this.tagPurge || !Array.isArray(tags) || tags.length === 0 || !since)
+      return false;
+    const ctx = _getRequestContext();
+    if (!ctx) return false;
+    const memo = getTagMarkerMemo(ctx, this);
+    for (const tag of tags) {
+      const marker = memo.get(tag);
+      if (marker != null && marker >= since) return true;
+    }
+    return false;
+  }
+
   /**
    * 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,
@@ -1920,10 +1961,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   async getShell(
     key: string,
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    if (!this.kv) {
-      this.warnShellFamilyInertOnce();
-      return null;
-    }
     try {
       const cache = await this.getCache();
       const request = this.keyToRequest(`shell:${key}`);
@@ -2005,10 +2042,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetShell(key);
       }
 
-      // Unlike other L1 families, shells always check the durable generation
-      // marker. See the capture-start/purge race documented above.
+      // Unlike other L1 families, shells with KV always check the durable
+      // generation marker — see the capture-start/purge race documented
+      // above. Without KV there are no markers: L1-only shells adopt the
+      // data families' purge-mode read semantics (a hit that survived the
+      // purge is trusted; the per-request memo masks this request's own
+      // updateTag() writes; entries a purge cannot reach fall back to the
+      // marker check, which fails open KV-less).
       const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const invalidated = await this.isGloballyInvalidated(value.t, value.ta);
+      const invalidated = this.kv
+        ? await this.isGloballyInvalidated(value.t, value.ta)
+        : await this.isL1Invalidated(value.t, value.ta, response.headers);
       const markerMs = INTERNAL_RANGO_DEBUG
         ? Date.now() - markerStartedAt
         : undefined;
@@ -2042,11 +2086,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * 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.
+   * Store a PPR shell envelope in Cache API and, when KV is configured and
+   * the retention meets its 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; a KV-less store is L1-only by design
+   * (edge-only ppr — see the section comment).
    */
   async putShell(
     key: string,
@@ -2054,20 +2099,29 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void> {
-    // KV remains required for durable generation markers and cross-colo reads.
-    if (!this.kv) {
-      this.warnShellFamilyInertOnce();
-      return;
-    }
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
     if (!this.waitUntil) return;
+    // Same write gate as the data families: in KV-less purge mode an
+    // over-limit tag set has NO eviction path (no tokens, no markers), so the
+    // shell is not cached rather than becoming un-invalidatable. Unlike the
+    // void-returning data puts, this is ACKNOWLEDGED — the capture scheduler
+    // must back the key off (every write would refuse identically), not
+    // treat the capture as stored and re-render on every MISS.
+    if (this.skipUncacheableTagSet(tags)) return "uncacheable";
+    if (!this.kv && !this.tagPurge && Array.isArray(tags) && tags.length > 0) {
+      this.warnShellTagsNoEvictionOnce();
+    }
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
       const totalTtl = ttl + swrWindow;
 
+      // The tagInvalidationTtl cap exists so a tagged entry can never outlive
+      // its KV markers (an expired marker would resurrect it). Without KV
+      // there are no markers to outlive — capping would just hard-expire the
+      // shell below its declared ttl+swr — so the cap is KV-conditional.
       const retentionTtl =
-        tags && tags.length > 0 && this.tagInvalidationTtl
+        tags && tags.length > 0 && this.kv && this.tagInvalidationTtl
           ? Math.min(totalTtl, this.tagInvalidationTtl)
           : totalTtl;
       const now = Date.now();
@@ -2076,14 +2130,14 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const taggedAt =
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
-      const kvKey = await this.toKVKey(`shell:${key}`);
-      const writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
+      const writeKv = !!this.kv && retentionTtl >= KV_MIN_EXPIRATION_TTL;
+      const kvKey = writeKv ? await this.toKVKey(`shell:${key}`) : null;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
           tags &&
           tags.length > 0 &&
-          (await this.isGloballyInvalidated(tags, entry.createdAt))
+          (await this.isShellGenerationInvalidated(tags, entry.createdAt))
         ) {
           this.debugShell(key, "write-invalidated");
           return "invalidated";
@@ -2132,7 +2186,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             }
           })(),
         ];
-        if (writeKv) {
+        if (writeKv && kvKey !== null) {
           writes.push(
             (async () => {
               try {
@@ -3029,13 +3083,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * 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).
+   * shell generation check (marker >= since, fail open); KV-less it degrades
+   * to the per-request memo in purge mode and to false otherwise — see
+   * isShellGenerationInvalidated.
    */
   async isTagsInvalidatedSince(
     tags: string[],
     sinceMs: number,
   ): Promise<boolean> {
-    return this.isGloballyInvalidated(tags, sinceMs);
+    return this.isShellGenerationInvalidated(tags, sinceMs);
   }
 
   async invalidateTags(tags: string[]): Promise<void> {

package/src/cache/shell-snapshot.ts

@@ -250,7 +250,7 @@ export class RecordingShellStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void> {
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
     return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
   }
 
@@ -506,7 +506,7 @@ export class SeededShellStore<
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void> {
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
     return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
   }
 

package/src/cache/types.ts

@@ -188,7 +188,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param tags - Optional cache tags for invalidation (participates in
    *   invalidateTags via the same tag machinery as the item family)
    * @returns `invalidated` when a generation marker rejected the write,
-   *   `stored` when acknowledged, or void for stores without acknowledgements.
+   *   `stored` when acknowledged, `uncacheable` when the entry can NEVER be
+   *   stored under the current configuration (every retry would refuse
+   *   identically — the capture scheduler backs the key off instead of
+   *   recapturing per MISS; CFCacheStore returns it for a tag set whose
+   *   Cache-Tag header overflows in KV-less purge mode), or void for stores
+   *   without acknowledgements.
    */
   putShell?(
     key: string,
@@ -196,18 +201,33 @@ export interface SegmentCacheStore<TEnv = unknown> {
     ttlSeconds?: number,
     swrSeconds?: number,
     tags?: string[],
-  ): Promise<"stored" | "invalidated" | void>;
+  ): Promise<"stored" | "invalidated" | "uncacheable" | void>;
 
   /**
    * Declares the shell family present-but-inert: getShell/putShell exist but
-   * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
-   * captures whose only write target is inert — the background render would be
-   * dead work that still occupies the per-isolate serialized capture queue
-   * (a promise-heavy route bakes for seconds per MISS with nothing stored).
-   * Absent/false means the family, when present, actually stores.
+   * no-op (a custom store whose backing tier is conditionally unavailable).
+   * scheduleShellCapture skips captures whose only write target is inert —
+   * the background render would be dead work that still occupies the
+   * per-isolate serialized capture queue (a promise-heavy route bakes for
+   * seconds per MISS with nothing stored). Absent/false means the family,
+   * when present, actually stores. The built-in stores never declare it:
+   * CFCacheStore is L1-only without KV (edge-only ppr), not inert.
    */
   shellFamilyInert?: boolean;
 
+  /**
+   * Declares isTagsInvalidatedSince present-but-inert: the store implements
+   * the method but has no DURABLE invalidation history behind it (a KV-less
+   * CFCacheStore answers from the per-request memo at best). Runtime shells
+   * tolerate that — purge eviction plus ttl/swr bound their staleness — but
+   * a TAGGED build-manifest shell is immutable with no ttl of its own, so
+   * serving it on such a store would make updateTag() a permanent no-op for
+   * it. The build-shell read-through declines tagged entries on this flag
+   * (same declared-intent-cannot-be-honored doctrine as a store missing the
+   * method entirely). Absent/false means answers are durably backed.
+   */
+  tagHistoryInert?: boolean;
+
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.

package/src/rsc/shell-build-manifest.ts

@@ -306,20 +306,27 @@ export async function lookupBuildShell(
     const entry = record.entry;
     if (record.tags && record.tags.length > 0) {
       const check = store.isTagsInvalidatedSince;
-      if (typeof check !== "function") {
+      if (typeof check !== "function" || store.tagHistoryInert) {
         // A tagged build entry on a store that cannot answer "was this tag
         // invalidated since the build" must not serve: updateTag() could
-        // never evict it. Declared intent that cannot be honored deserves a
+        // never evict it. That covers a store missing the method AND one
+        // whose answers have no durable history behind them
+        // (SegmentCacheStore.tagHistoryInert — a KV-less CFCacheStore's
+        // memo-only answers would let the immutable asset resurrect on the
+        // next request). Declared intent that cannot be honored deserves a
         // diagnostic; the route keeps runtime-capture semantics.
         const key = buildShellManifestKey(url.pathname);
         if (!warnedTagCheckUnsupported.has(key)) {
           warnedTagCheckUnsupported.add(key);
           console.warn(
             `[rango] Build-time shell for "${url.pathname}" carries cache tags, but ` +
-              "the app cache store does not implement isTagsInvalidatedSince(), so " +
-              "updateTag() could not evict it. The entry is not served; the route " +
-              "keeps runtime shell capture. Use MemorySegmentCacheStore, CFCacheStore, " +
-              "or VercelCacheStore (or add the method to your custom store).",
+              "the app cache store cannot answer tag-invalidation history durably " +
+              (typeof check !== "function"
+                ? "(isTagsInvalidatedSince() is not implemented), "
+                : "(no durable tag history — a CFCacheStore without a KV namespace), ") +
+              "so updateTag() could not evict it. The entry is not served; the route " +
+              "keeps runtime shell capture. Use MemorySegmentCacheStore, a KV-backed " +
+              "CFCacheStore, or VercelCacheStore (or add the method to your custom store).",
           );
         }
         return null;

package/src/rsc/shell-capture.ts

@@ -509,9 +509,10 @@ export interface ShellCaptureDebugEvent {
    *   the capture was not attempted
    * - skip-capacity: the isolate capture queue is full; a later request may retry
    * - skip-inert-store: the resolved store's shell family is missing or
-   *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
-   *   without a KV namespace); nothing could store the result, so the
-   *   background render was not scheduled at all
+   *   declared inert (SegmentCacheStore.shellFamilyInert — a custom store
+   *   whose backing tier is unavailable; built-in stores never declare it);
+   *   nothing could store the result, so the background render was not
+   *   scheduled at all
    * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
    *   behind other captures and was dropped unrun (no backoff — the route is
    *   not doomed, the isolate was busy; a later request re-probes). Carries
@@ -554,7 +555,7 @@ export interface ShellCaptureDebugEvent {
   /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
   untaggedBake?: true;
   /** Outcome reported by a store that supports shell-write acknowledgements. */
-  storeWrite?: "stored" | "invalidated";
+  storeWrite?: "stored" | "invalidated" | "uncacheable";
   /** Consecutive failure count in the key's backoff entry, when one exists. */
   backoffFailures?: number;
   /** Ms remaining in the key's backoff window, when one exists. */
@@ -1005,7 +1006,8 @@ export function scheduleShellCapture(
   // serialized queue (a promise-heavy route bakes for seconds per MISS),
   // starving captures that CAN store. Skip scheduling entirely when the
   // resolved store (same defaulting as captureAndStoreShell) has no shell
-  // family or declared it inert (CFCacheStore without a KV namespace).
+  // family or declared it inert (a custom-store escape hatch; built-in
+  // stores never declare it — a KV-less CFCacheStore stores L1-only).
   const scheduledStore = descriptor.store ?? reqCtx._cacheStore;
   if (!scheduledStore?.putShell || scheduledStore.shellFamilyInert) {
     publishCaptureDebugEvent(descriptor, { key, outcome: "skip-inert-store" });
@@ -2028,6 +2030,21 @@ async function captureAndStoreShell(
           );
           return "refused";
         }
+        if (storeWrite === "uncacheable") {
+          // The store declared the entry unstorable under its current
+          // configuration — every retry would refuse identically, so back
+          // the key off like any refused capture instead of burning a full
+          // serialized render per MISS. Store-neutral on purpose: the
+          // acknowledging store emits its own diagnostic naming the specific
+          // limit (CFCacheStore warns about the over-limit Cache-Tag set).
+          warnCaptureRefusedOnce(
+            capture.key,
+            "the store cannot cache this shell under its current configuration and acknowledged " +
+              "the write as permanently refusable, so the key is backed off. See the cache store's " +
+              "own warning for the specific limit and remedy.",
+          );
+          return "refused";
+        }
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.
         reportCacheError(