@pylonsync/functions 0.3.298 → 0.3.300

package/dist/ssr-runtime.d.ts

@@ -56,6 +56,12 @@ export interface RenderRouteMessage {
         tenant_id: string | null;
         roles: string[];
     };
+    /**
+     * Whether the request carried a session cookie (presence, not identity) —
+     * surfaced as the identity-free `props.session.exists` (Phase 0 auth
+     * bucketing). Default false / absent for back-compat.
+     */
+    session_present?: boolean;
     /**
      * Initial HTTP status the response controller starts at (default 200).
      * The host sets this to 404 when dispatching a `not-found.tsx` render
@@ -151,6 +157,30 @@ export declare function makeResponseController(state: ResponseState, defaultRedi
  * Exported for direct unit testing of that property.
  */
 export declare function makeReadTrackingProxy(obj: Record<string, unknown> | undefined, onTouch: () => void): Record<string, unknown>;
+/**
+ * Deep clone via JSON round-trip — drops functions / proxies / symbols, keeping
+ * only JSON-serializable data. Used to SNAPSHOT the bucket-tail props before any
+ * page code can mutate them, so a page can't smuggle identity through a nested
+ * field of params/searchParams into a shared cache entry. The deep copy is fully
+ * independent of the source: a later mutation of the original object can't reach
+ * the snapshot.
+ */
+export declare function jsonClone<T>(v: T): T;
+/**
+ * Revocable form of {@link makeReadTrackingProxy}. The render path wraps each
+ * per-request input (auth / headers / cookies / session) in one of these and
+ * REVOKES it once the render is done — so a page that stashed the props object
+ * (or `props.auth`) in module-level state and read it on a LATER render gets a
+ * hard throw instead of silently reading a prior request's identity WITHOUT
+ * tripping this render's read-tracking. Revocation is per-render (each render
+ * revokes only its own proxies), so it is sound even when the Bun runner
+ * multiplexes concurrent renders. Fail-closed: the stale read throws, the render
+ * fails, and nothing is cached.
+ */
+export declare function makeRevocableReadTrackingProxy(obj: Record<string, unknown> | undefined, onTouch: () => void): {
+    proxy: Record<string, unknown>;
+    revoke: () => void;
+};
 export declare function finalizeHeaders(state: ResponseState, extra?: Record<string, string>, internal?: Record<string, string>): Record<string, string>;
 /**
  * Phase 1 SSR handler. Resolves the component, renders it via
@@ -305,6 +335,13 @@ export declare function isSafeRedirect(url: string, opts: {
  *  into a page's metadata. Explicit `metadata.icons.*` wins. */
 export declare function applyAutoIcons(component: string, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
 export declare function applyAutoSocialImages(component: string, headers: Record<string, string> | undefined, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
+/**
+ * Dev-only tail chunk: the `__PYLON_DEV__` info blob (cache verdict, render
+ * mode/timing, route) + the HUD bootstrap. Embedded after the page tail so the
+ * marker + probe are in place before the deferred client entry boots the sync
+ * engine. `<` is escaped so the JSON can't break out of the script.
+ */
+export declare function buildDevHudChunk(devInfo: Record<string, unknown>): string;
 /**
  * Build the hydration tail appended after React's stream EOFs: the
  * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry
@@ -334,6 +371,9 @@ export declare function buildHydrationTail(args: {
         message: string;
         digest?: string;
     };
+    bucketAuth?: {
+        signedIn: boolean;
+    };
 }): string;
 /**
  * A short, non-reversible correlation id for an error — surfaced to the
@@ -361,6 +401,47 @@ export declare function computeRevalidateSecs(mod: any): number | null;
  * cached). Fail-closed: every condition must hold.
  */
 export declare function computeCacheVerdict(args: {
+    revalidateSecs: number | null;
+    forceDynamic: boolean;
+    authTouched: boolean;
+    dynamicTouched: boolean;
+    sessionTouched: boolean;
+    cookieCount: number;
+    strictPolicies: boolean;
+    wantsStream: boolean;
+    status: number;
+}): boolean;
+/**
+ * PPR Phase 0 — the AUTH-BUCKET verdict: may this render be stored as a SHARED
+ * cache entry keyed only on session-cookie PRESENCE (one signed-in shell + one
+ * signed-out shell, both IDENTITY-FREE)? Pure, exported, leak-class tested.
+ *
+ * Like `computeCacheVerdict` EXCEPT `sessionTouched` is ALLOWED (reading
+ * `props.session.exists` to render a binary signed-in/out nav is the whole
+ * point — that bit is what the bucket keys on, and it's identical across all
+ * users in the same bucket). Everything else still vetoes:
+ *
+ *  - `authTouched` — reading real `props.auth` (user_id/tenant_id/roles) makes
+ *    the output identity-SPECIFIC, not bucket-uniform. This is the load-bearing
+ *    gate: ANY identity-dependent output requires reading auth, so vetoing on
+ *    `authTouched` proves a bucketable body depends on nothing but the binary
+ *    session bit.
+ *  - `dynamicTouched` — reading request headers/cookies makes it request-specific.
+ *  - `strictPolicies` — in strict mode serverData reads are auth-FILTERED, so the
+ *    body/ssrData would vary by identity even without the page reading auth. In
+ *    the default (non-strict) mode serverData reads bypass the policy gate and
+ *    return identity-independent rows, so the cached body is safe to share within
+ *    the bucket. Strict mode therefore must NOT bucket.
+ *  - cookieCount / forceDynamic / wantsStream / non-200 — same reasons as the
+ *    anon verdict (a Set-Cookie, a streaming head, or an error/redirect can't be
+ *    safely shared).
+ *
+ * Requires the explicit `bucketOptIn` (`export const cache = "auth-bucketed"`)
+ * AND a TTL via `export const revalidate = N` — fail-closed: no opt-in or no TTL
+ * → no bucket.
+ */
+export declare function computeBucketVerdict(args: {
+    bucketOptIn: boolean;
     revalidateSecs: number | null;
     forceDynamic: boolean;
     authTouched: boolean;
@@ -370,6 +451,31 @@ export declare function computeCacheVerdict(args: {
     wantsStream: boolean;
     status: number;
 }): boolean;
+/**
+ * Dev HUD: explain the cache verdict for a finished render in human terms — the
+ * verdict, its TTL, and (when dynamic) the SINGLE reason it isn't cached. Pure so
+ * it's unit-tested and matches `computeCacheVerdict`/`computeBucketVerdict`
+ * exactly. The "why isn't my page caching?" answer the framework otherwise throws
+ * away.
+ */
+export declare function describeCacheVerdict(v: {
+    bucketOptIn: boolean;
+    cacheable: boolean;
+    bucketable: boolean;
+    revalidateSecs: number | null;
+    authTouched: boolean;
+    dynamicTouched: boolean;
+    sessionTouched: boolean;
+    cookieCount: number;
+    strictPolicies: boolean;
+    wantsStream: boolean;
+    forceDynamic: boolean;
+    status: number;
+}): {
+    verdict: "bucketed" | "cacheable" | "dynamic";
+    secs: number | null;
+    reason: string;
+};
 /**
  * #278: diff the response head committed at `response_start` against the final
  * state after EOF, to catch a late response.* mutation from a suspended subtree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.298",
+  "version": "0.3.300",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-runtime.test.ts

@@ -17,6 +17,8 @@ import {
   finalizeHeaders,
   makeResponseController,
   makeReadTrackingProxy,
+  makeRevocableReadTrackingProxy,
+  jsonClone,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -148,6 +150,42 @@ describe("reserved x-pylon-* header namespace (cache-proof forgery fence)", () =
     });
     expect(t).toBe(false);
   });
+
+  test("revocable proxy throws after revoke (stale module-stashed props fence)", () => {
+    // P0 (codex 2026-06-28): a page that stashes `props` (or `props.auth`) in
+    // module-level state and reads it on a LATER render must not silently read a
+    // prior request's identity without tripping THIS render's read-tracking. The
+    // render path revokes each per-request proxy when the render ends, so any
+    // retained reference throws on access — fail-closed.
+    const { proxy, revoke } = makeRevocableReadTrackingProxy(
+      { user_id: "alice" },
+      () => {},
+    );
+    expect((proxy as any).user_id).toBe("alice"); // live during the render
+    revoke();
+    // A stashed reference, read on a later render:
+    expect(() => (proxy as any).user_id).toThrow();
+    expect(() => "user_id" in proxy).toThrow();
+    expect(() => Object.keys(proxy)).toThrow();
+  });
+
+  test("jsonClone snapshot is independent of later source mutation (bucket params fence)", () => {
+    // The bucket-tail snapshot (bucketTailBase) is jsonClone'd at render START.
+    // The defense rests on the clone being decoupled from the live params object:
+    // a page mutating a NESTED field afterwards (props.searchParams.leak =
+    // props.auth) can't reach the already-captured snapshot.
+    const source: any = { id: "a", nested: { keep: 1 } };
+    const snap = jsonClone(source);
+    // Simulate the page smuggling identity in after the snapshot was taken.
+    source.leak = { user_id: "alice" };
+    source.nested.keep = 999;
+    expect(snap).toEqual({ id: "a", nested: { keep: 1 } });
+    expect((snap as any).leak).toBeUndefined();
+    // And it strips non-JSON values (a proxy aliased in would serialize as its
+    // target via JSON, but a function/symbol is dropped entirely).
+    const stripped = jsonClone({ ok: "v", fn: () => 1, sym: Symbol("x") } as any);
+    expect(stripped).toEqual({ ok: "v" });
+  });
 });
 
 // Pull the JSON out of the `__PYLON_DATA__` <script> a hydration tail emits.

package/src/ssr-runtime.ts

@@ -75,6 +75,12 @@ export interface RenderRouteMessage {
     tenant_id: string | null;
     roles: string[];
   };
+  /**
+   * Whether the request carried a session cookie (presence, not identity) —
+   * surfaced as the identity-free `props.session.exists` (Phase 0 auth
+   * bucketing). Default false / absent for back-compat.
+   */
+  session_present?: boolean;
   /**
    * Initial HTTP status the response controller starts at (default 200).
    * The host sets this to 404 when dispatching a `not-found.tsx` render
@@ -321,7 +327,37 @@ export function makeReadTrackingProxy(
   obj: Record<string, unknown> | undefined,
   onTouch: () => void,
 ): Record<string, unknown> {
-  return new Proxy((obj ?? {}) as Record<string, unknown>, {
+  return makeRevocableReadTrackingProxy(obj, onTouch).proxy;
+}
+
+/**
+ * Deep clone via JSON round-trip — drops functions / proxies / symbols, keeping
+ * only JSON-serializable data. Used to SNAPSHOT the bucket-tail props before any
+ * page code can mutate them, so a page can't smuggle identity through a nested
+ * field of params/searchParams into a shared cache entry. The deep copy is fully
+ * independent of the source: a later mutation of the original object can't reach
+ * the snapshot.
+ */
+export function jsonClone<T>(v: T): T {
+  return v == null ? v : (JSON.parse(JSON.stringify(v)) as T);
+}
+
+/**
+ * Revocable form of {@link makeReadTrackingProxy}. The render path wraps each
+ * per-request input (auth / headers / cookies / session) in one of these and
+ * REVOKES it once the render is done — so a page that stashed the props object
+ * (or `props.auth`) in module-level state and read it on a LATER render gets a
+ * hard throw instead of silently reading a prior request's identity WITHOUT
+ * tripping this render's read-tracking. Revocation is per-render (each render
+ * revokes only its own proxies), so it is sound even when the Bun runner
+ * multiplexes concurrent renders. Fail-closed: the stale read throws, the render
+ * fails, and nothing is cached.
+ */
+export function makeRevocableReadTrackingProxy(
+  obj: Record<string, unknown> | undefined,
+  onTouch: () => void,
+): { proxy: Record<string, unknown>; revoke: () => void } {
+  return Proxy.revocable((obj ?? {}) as Record<string, unknown>, {
     get(t, p, r) {
       onTouch();
       return Reflect.get(t, p, r);
@@ -1122,6 +1158,155 @@ const DEV_LIVE_RELOAD_SNIPPET =
   "if(b!==null&&e.data!==b){s.close();location.reload();return;}b=e.data;});" +
   "}catch(_){}})();</script>";
 
+/**
+ * The dev HUD (a floating bottom-left overlay, dev-only): surfaces the
+ * framework decisions a dev otherwise can't see — the cache verdict + WHY a page
+ * isn't cached, render mode + timing, sync connection + offline-outbox depth, and
+ * client error count. Written as a plain function and embedded via `.toString()`
+ * (Bun strips the TS annotations), so it ships as self-contained browser JS that
+ * closes over nothing. Browser globals go through `g` so it typechecks without a
+ * DOM lib. Mirrors Next's dev indicator, tuned to Pylon's hidden state.
+ */
+function pylonDevHud() {
+  const g: any = globalThis;
+  const d: any = g.document;
+  if (!d || g.__pylonHudMounted) return;
+  g.__pylonHudMounted = true;
+
+  let info: any = {};
+  try {
+    const el = d.getElementById("__PYLON_DEV__");
+    if (el) info = JSON.parse(el.textContent || "{}");
+  } catch (_e) {}
+  // Marker the sync engine checks before publishing its dev status probe.
+  g.__PYLON_DEV__ = info;
+
+  const errs: string[] = [];
+  const onErr = (m: any) => {
+    errs.push(String(m));
+    if (errs.length > 50) errs.shift();
+  };
+  if (g.addEventListener) {
+    g.addEventListener("error", (e: any) => onErr((e && (e.message || e.error)) || e));
+    g.addEventListener("unhandledrejection", (e: any) => onErr((e && e.reason) || e));
+  }
+
+  const C = { ok: "#3fb950", warn: "#d29922", bad: "#f85149", dim: "#6e7681" };
+  const make = (tag: string, css: string, text?: string) => {
+    const n = d.createElement(tag);
+    n.style.cssText = css;
+    if (text != null) n.textContent = text;
+    return n;
+  };
+  const dot = (color: string) =>
+    make("span", "display:inline-block;width:7px;height:7px;border-radius:50%;flex:0 0 auto;background:" + color);
+
+  const box = make(
+    "div",
+    "position:fixed;left:12px;bottom:12px;z-index:2147483646;font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace",
+  );
+  const panel = make(
+    "div",
+    "background:#0d1117;border:1px solid #30363d;border-radius:8px;padding:9px 11px;margin-bottom:6px;min-width:240px;max-width:360px;box-shadow:0 8px 28px rgba(0,0,0,.45)",
+  );
+  const pill = make(
+    "button",
+    "display:flex;align-items:center;gap:6px;background:#161b22;border:1px solid #30363d;border-radius:999px;padding:5px 11px;color:#e6edf3;cursor:pointer;font:inherit;box-shadow:0 2px 10px rgba(0,0,0,.35)",
+  );
+
+  const rowEl = (label: string) => {
+    const r = make("div", "display:flex;align-items:flex-start;gap:8px;margin:3px 0");
+    r.appendChild(make("span", "color:#8b949e;flex:0 0 60px", label));
+    const v = make("span", "color:#e6edf3;word-break:break-word;flex:1");
+    r.appendChild(v);
+    panel.appendChild(r);
+    return v;
+  };
+
+  const cache = info.cache || {};
+  const cacheLabel =
+    cache.verdict === "dynamic"
+      ? "dynamic"
+      : cache.verdict + (cache.secs ? " · " + cache.secs + "s" : "");
+  rowEl("route").textContent = info.route || "—";
+  rowEl("page").textContent = info.component || "—";
+  const cacheV = rowEl("cache");
+  cacheV.textContent = cacheLabel + (cache.reason ? "  ·  " + cache.reason : "");
+  cacheV.style.color = cache.verdict === "dynamic" ? C.warn : C.ok;
+  rowEl("render").textContent =
+    (info.renderMode || "ssr") + (info.renderMs != null ? " · " + info.renderMs + "ms" : "");
+  const syncV = rowEl("sync");
+  const errV = rowEl("errors");
+
+  pill.appendChild(dot(cache.verdict === "dynamic" ? C.warn : C.ok));
+  pill.appendChild(make("span", "font-weight:600;color:#e6edf3", "pylon"));
+  const pillSyncDot = dot(C.dim);
+  pill.appendChild(pillSyncDot);
+
+  let open = false;
+  try {
+    open = g.localStorage && g.localStorage.getItem("pylon.hud.open") === "1";
+  } catch (_e) {}
+  panel.style.display = open ? "block" : "none";
+  pill.onclick = () => {
+    open = !open;
+    panel.style.display = open ? "block" : "none";
+    try {
+      g.localStorage && g.localStorage.setItem("pylon.hud.open", open ? "1" : "0");
+    } catch (_e) {}
+  };
+
+  const refresh = () => {
+    const s = g.__pylonDevSync;
+    if (s) {
+      let st = "?";
+      let pend = 0;
+      let rows = 0;
+      try {
+        st = s.status();
+        pend = s.pending();
+        rows = s.rows();
+      } catch (_e) {}
+      syncV.textContent = st + " · " + pend + " pending · " + rows + " rows";
+      const col = st === "connected" ? C.ok : st === "offline" ? C.bad : C.warn;
+      syncV.style.color = col;
+      pillSyncDot.style.background = col;
+    } else {
+      const online = g.navigator ? g.navigator.onLine : true;
+      syncV.textContent = "no sync engine · " + (online ? "online" : "offline");
+      syncV.style.color = C.dim;
+      pillSyncDot.style.background = online ? C.dim : C.bad;
+    }
+    errV.textContent = errs.length === 0 ? "0" : errs.length + " · " + errs[errs.length - 1];
+    errV.style.color = errs.length ? C.bad : C.dim;
+  };
+
+  box.appendChild(panel);
+  box.appendChild(pill);
+  const mount = () => (d.body || d.documentElement).appendChild(box);
+  if (d.body) mount();
+  else if (g.addEventListener) g.addEventListener("DOMContentLoaded", mount);
+  refresh();
+  if (g.setInterval) g.setInterval(refresh, 1000);
+}
+
+/**
+ * Dev-only tail chunk: the `__PYLON_DEV__` info blob (cache verdict, render
+ * mode/timing, route) + the HUD bootstrap. Embedded after the page tail so the
+ * marker + probe are in place before the deferred client entry boots the sync
+ * engine. `<` is escaped so the JSON can't break out of the script.
+ */
+export function buildDevHudChunk(devInfo: Record<string, unknown>): string {
+  const json = JSON.stringify(devInfo)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  return (
+    `<script id="__PYLON_DEV__" type="application/json">${json}</script>` +
+    `<script>(${pylonDevHud.toString()})();</script>`
+  );
+}
+
 /**
  * Build the <head> blob for a boundary render: the union of every route's
  * stylesheet links from the client build manifest. Boundary modules aren't
@@ -1202,6 +1387,15 @@ export function buildHydrationTail(args: {
   manifestErr: string | null;
   kind?: "error" | "not-found";
   errorForClient?: { message: string; digest?: string };
+  // PPR Phase 0 (auth-bucketed caching): when set, this render is being stored
+  // as a SHARED cache entry keyed only on session-cookie PRESENCE, so its
+  // hydration tail must carry an IDENTITY-FREE auth — the binary `{ signedIn }`
+  // bit the bucket is keyed on, and NOTHING ELSE (no user_id / tenant_id /
+  // roles / email). Two different signed-in users hitting the same bucketed
+  // page MUST produce a byte-identical tail, or the shared cache replays one
+  // user's identity to another (the #277 leak class, at the body level). The
+  // raw `auth` is replaced AFTER the live-handle strip below.
+  bucketAuth?: { signedIn: boolean };
 }): string {
   // Strip live, non-serializable handles (serverData / response / reset) + the
   // request headers/cookies (SECURITY: never expose the session cookie to
@@ -1216,7 +1410,28 @@ export function buildHydrationTail(args: {
     error: _err,
     ...restProps
   } = args.props ?? {};
-  const serializableProps: any = { ...restProps, headers: {}, cookies: {} };
+  let serializableProps: any;
+  if (args.bucketAuth) {
+    // Bucketed render → SHARED entry. Serialize a strict ALLOWLIST of the
+    // framework props that are provably bucket-uniform — never a spread of the
+    // page's props object. A page can alias identity onto a custom key
+    // (`props.leak = props.auth`) without tripping read-tracking; spreading
+    // `restProps` would then serialize that identity into the shared tail. The
+    // allowlisted fields are all path/route-derived (in the cache key) or the
+    // collapsed binary auth bit. (params/searchParams are keyed by pathname; a
+    // bucket request has no query, so searchParams is empty.)
+    serializableProps = {
+      url: restProps.url,
+      params: restProps.params,
+      searchParams: restProps.searchParams,
+      auth: { signedIn: args.bucketAuth.signedIn },
+      session: { exists: args.bucketAuth.signedIn },
+      headers: {},
+      cookies: {},
+    };
+  } else {
+    serializableProps = { ...restProps, headers: {}, cookies: {} };
+  }
   if (args.errorForClient) serializableProps.error = args.errorForClient;
   const hydrationPayload: any = {
     component: args.component,
@@ -1563,6 +1778,11 @@ export function computeCacheVerdict(args: {
   // pathname, and Host via the host bucket — are handled by the cache key and do
   // not set this.)
   dynamicTouched: boolean;
+  // True when the render read `props.session.exists` (Phase 0). For the PLAIN
+  // anonymous cache this is a veto — the output varies by signed-in bucket, and
+  // the anon cache holds one entry for all. (The auth-BUCKET verdict, which keys
+  // the cache on the bucket, permits it; this gate does not.)
+  sessionTouched: boolean;
   cookieCount: number;
   strictPolicies: boolean;
   wantsStream: boolean;
@@ -1573,6 +1793,7 @@ export function computeCacheVerdict(args: {
     !args.forceDynamic &&
     !args.authTouched &&
     !args.dynamicTouched &&
+    !args.sessionTouched &&
     args.cookieCount === 0 &&
     !args.strictPolicies &&
     !args.wantsStream &&
@@ -1580,6 +1801,122 @@ export function computeCacheVerdict(args: {
   );
 }
 
+/**
+ * PPR Phase 0 — the AUTH-BUCKET verdict: may this render be stored as a SHARED
+ * cache entry keyed only on session-cookie PRESENCE (one signed-in shell + one
+ * signed-out shell, both IDENTITY-FREE)? Pure, exported, leak-class tested.
+ *
+ * Like `computeCacheVerdict` EXCEPT `sessionTouched` is ALLOWED (reading
+ * `props.session.exists` to render a binary signed-in/out nav is the whole
+ * point — that bit is what the bucket keys on, and it's identical across all
+ * users in the same bucket). Everything else still vetoes:
+ *
+ *  - `authTouched` — reading real `props.auth` (user_id/tenant_id/roles) makes
+ *    the output identity-SPECIFIC, not bucket-uniform. This is the load-bearing
+ *    gate: ANY identity-dependent output requires reading auth, so vetoing on
+ *    `authTouched` proves a bucketable body depends on nothing but the binary
+ *    session bit.
+ *  - `dynamicTouched` — reading request headers/cookies makes it request-specific.
+ *  - `strictPolicies` — in strict mode serverData reads are auth-FILTERED, so the
+ *    body/ssrData would vary by identity even without the page reading auth. In
+ *    the default (non-strict) mode serverData reads bypass the policy gate and
+ *    return identity-independent rows, so the cached body is safe to share within
+ *    the bucket. Strict mode therefore must NOT bucket.
+ *  - cookieCount / forceDynamic / wantsStream / non-200 — same reasons as the
+ *    anon verdict (a Set-Cookie, a streaming head, or an error/redirect can't be
+ *    safely shared).
+ *
+ * Requires the explicit `bucketOptIn` (`export const cache = "auth-bucketed"`)
+ * AND a TTL via `export const revalidate = N` — fail-closed: no opt-in or no TTL
+ * → no bucket.
+ */
+export function computeBucketVerdict(args: {
+  bucketOptIn: boolean;
+  revalidateSecs: number | null;
+  forceDynamic: boolean;
+  authTouched: boolean;
+  dynamicTouched: boolean;
+  cookieCount: number;
+  strictPolicies: boolean;
+  wantsStream: boolean;
+  status: number;
+}): boolean {
+  return (
+    args.bucketOptIn &&
+    args.revalidateSecs != null &&
+    !args.forceDynamic &&
+    !args.authTouched &&
+    !args.dynamicTouched &&
+    args.cookieCount === 0 &&
+    !args.strictPolicies &&
+    !args.wantsStream &&
+    args.status === 200
+  );
+}
+
+/**
+ * Dev HUD: explain the cache verdict for a finished render in human terms — the
+ * verdict, its TTL, and (when dynamic) the SINGLE reason it isn't cached. Pure so
+ * it's unit-tested and matches `computeCacheVerdict`/`computeBucketVerdict`
+ * exactly. The "why isn't my page caching?" answer the framework otherwise throws
+ * away.
+ */
+export function describeCacheVerdict(v: {
+  bucketOptIn: boolean;
+  cacheable: boolean;
+  bucketable: boolean;
+  revalidateSecs: number | null;
+  authTouched: boolean;
+  dynamicTouched: boolean;
+  sessionTouched: boolean;
+  cookieCount: number;
+  strictPolicies: boolean;
+  wantsStream: boolean;
+  forceDynamic: boolean;
+  status: number;
+}): { verdict: "bucketed" | "cacheable" | "dynamic"; secs: number | null; reason: string } {
+  if (v.bucketable) {
+    return {
+      verdict: "bucketed",
+      secs: v.revalidateSecs,
+      reason: "shared cache, keyed on session presence",
+    };
+  }
+  if (v.cacheable) {
+    return {
+      verdict: "cacheable",
+      secs: v.revalidateSecs,
+      reason: "anonymous shared cache",
+    };
+  }
+  // Dynamic — surface the single most useful reason (mirrors the verdict order).
+  let reason: string;
+  if (!v.bucketOptIn && v.revalidateSecs == null) {
+    reason = "not opted in — add `export const revalidate = N` (or `cache = \"auth-bucketed\"`)";
+  } else if (v.status !== 200) {
+    reason = `status ${v.status} (only 200 is cacheable)`;
+  } else if (v.forceDynamic) {
+    reason = "dynamic = \"force-dynamic\"";
+  } else if (v.wantsStream) {
+    reason = "streaming render (loading.tsx / streaming = true)";
+  } else if (v.cookieCount > 0) {
+    reason = "the render set a cookie";
+  } else if (v.strictPolicies) {
+    reason = "PYLON_STRICT_FN_POLICIES (serverData reads are auth-filtered)";
+  } else if (v.authTouched) {
+    reason = "read props.auth (identity-specific)";
+  } else if (v.dynamicTouched) {
+    reason = "read request headers/cookies";
+  } else if (v.sessionTouched) {
+    reason = v.bucketOptIn
+      ? "read props.session"
+      : "read props.session — add `export const cache = \"auth-bucketed\"` to bucket-cache it";
+  } else {
+    reason = "not cacheable";
+  }
+  return { verdict: "dynamic", secs: null, reason };
+}
+
 /**
  * #278: diff the response head committed at `response_start` against the final
  * state after EOF, to catch a late response.* mutation from a suspended subtree
@@ -1777,6 +2114,10 @@ export async function handleRenderRoute(
       : null;
   if (dataKind) return handleDataRoute(msg, dataKind, send);
 
+  // Dev HUD: wall-clock for the whole render, surfaced in the dev overlay's
+  // render row. `performance.now()` is monotonic; harmless in prod (unused).
+  const renderStart = isDevMode() ? performance.now() : 0;
+
   // Declared OUTSIDE the try so the catch can read page-set status/
   // cookies when turning a redirect()/notFound() throw into a response.
   const responseState: ResponseState = {
@@ -1791,6 +2132,11 @@ export async function handleRenderRoute(
   let React: any = null;
   let renderToReadableStream: any = null;
   let props: any = null;
+  // Revoke fns for this render's per-request proxies (auth/headers/cookies/
+  // session). Declared OUT here so the `finally` revokes them on EVERY exit path
+  // (success, redirect/notFound/error boundary, throw) — neutralizing any
+  // module-stashed reference to a prior request's identity.
+  const proxyRevokers: Array<() => void> = [];
   // Accumulates the resolved results of every `serverData.*` read the page
   // made during render, keyed identically to the client shim. Serialized
   // into `__PYLON_DATA__.ssrData` so hydration replays the same values
@@ -1869,14 +2215,24 @@ export async function handleRenderRoute(
 
     // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
     // if its output is independent of per-request inputs — so wrap each in a
-    // read-tracking Proxy (makeReadTrackingProxy) that flips a flag the moment a
-    // page/layout/generateMetadata observes it (get / `in` / Object.keys / probe).
-    // The raw objects are restored before serialization.
+    // read-tracking Proxy that flips a flag the moment a page/layout/
+    // generateMetadata observes it (get / `in` / Object.keys / probe). The
+    // proxies are REVOKED in the `finally` (never restored to raw onto `props`),
+    // so the live props object never aliases a prior request's identity. The tail
+    // serializes from the raw `msg` values via `tailProps` below.
+    const track = (
+      obj: Record<string, unknown> | undefined,
+      onTouch: () => void,
+    ) => {
+      const { proxy, revoke } = makeRevocableReadTrackingProxy(obj, onTouch);
+      proxyRevokers.push(revoke);
+      return proxy;
+    };
 
     // Reading auth at all (even for an anon request) opts the render OUT of
     // caching, because the output could differ by identity.
     let authTouched = false;
-    const authProxy = makeReadTrackingProxy(
+    const authProxy = track(
       msg.auth as Record<string, unknown> | undefined,
       () => {
         authTouched = true;
@@ -1889,10 +2245,24 @@ export async function handleRenderRoute(
     // cookies — the framework's metadata path reads `msg.headers` directly.
     let dynamicTouched = false;
     const touchProxy = (obj: Record<string, unknown> | undefined) =>
-      makeReadTrackingProxy(obj, () => {
+      track(obj, () => {
         dynamicTouched = true;
       });
 
+    // Phase 0 (auth bucketing): `props.session.exists` — the identity-FREE
+    // presence bit, so a page can render a binary auth nav WITHOUT reading real
+    // `auth`. Reading it sets `sessionTouched` (separate from authTouched): it
+    // vetoes the plain anonymous cache (the output now varies by signed-in
+    // bucket) but is PERMITTED by the bucket verdict (which keys the cache on the
+    // bucket).
+    let sessionTouched = false;
+    const sessionProxy = track(
+      { exists: msg.session_present === true },
+      () => {
+        sessionTouched = true;
+      },
+    );
+
     props = {
       url: msg.url,
       params: msg.params,
@@ -1900,6 +2270,7 @@ export async function handleRenderRoute(
       headers: touchProxy(msg.headers as Record<string, unknown> | undefined),
       cookies: touchProxy(msg.cookies as Record<string, unknown> | undefined),
       auth: authProxy,
+      session: sessionProxy,
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
       response,
@@ -1907,6 +2278,23 @@ export async function handleRenderRoute(
       serverData,
     };
 
+    // PPR Phase 0: an immutable, pre-render SNAPSHOT of the only props a bucketed
+    // (SHARED) tail may serialize — url/params/searchParams, all path-derived and
+    // in the cache key. Deep-cloned NOW, before any page/generateMetadata code
+    // runs, because `props.params`/`searchParams` ARE the live `msg` objects: a
+    // page could mutate a nested field to smuggle identity (e.g.
+    // `props.searchParams.leak = props.auth`) WITHOUT tripping read-tracking, and
+    // a shallow allowlist would copy that mutation by reference into the shared
+    // tail. Captured only for opted-in pages (zero cost otherwise).
+    const bucketOptIn = (mod as any).cache === "auth-bucketed";
+    const bucketTailBase = bucketOptIn
+      ? {
+          url: msg.url,
+          params: jsonClone(msg.params),
+          searchParams: jsonClone(msg.search_params),
+        }
+      : null;
+
     // SEO metadata: static `export const metadata` or dynamic
     // `export async function generateMetadata(props)`. Awaited before the
     // first byte, so keep it to cheap derivations (params → title); heavy
@@ -2063,7 +2451,31 @@ export async function handleRenderRoute(
     // `!Loading`) is the gate: a `streaming = true` page has `Loading` null but
     // `wantsStream` true, and must still be excluded. Fail-closed. (See
     // computeCacheVerdict — pure + unit-tested for the leak class.)
-    const cacheable = computeCacheVerdict({
+    // PPR Phase 0: `bucketOptIn` (`export const cache = "auth-bucketed"`) was
+    // resolved at props-construction time (it gates the immutable bucketTailBase
+    // snapshot). A bucketed render and the plain anon cache are mutually exclusive
+    // — `cacheable` excludes the opt-in so a bucket page never also emits the anon
+    // proof.
+    const cacheable =
+      !bucketOptIn &&
+      computeCacheVerdict({
+        revalidateSecs,
+        forceDynamic,
+        authTouched,
+        dynamicTouched,
+        sessionTouched,
+        cookieCount: responseState.cookies.length,
+        strictPolicies,
+        wantsStream,
+        status: responseState.status,
+      });
+    // The bucket verdict permits `sessionTouched` (reading the binary signed-in
+    // bit) but still vetoes any real-auth read. When true, this render is stored
+    // as a shared, identity-free, session-presence-keyed entry — so its
+    // hydration tail MUST be anonymized (bucketAuth below) and it advertises the
+    // TRUSTED internal `x-pylon-bucket` proof for the host to key + store it.
+    const bucketable = computeBucketVerdict({
+      bucketOptIn,
       revalidateSecs,
       forceDynamic,
       authTouched,
@@ -2073,13 +2485,26 @@ export async function handleRenderRoute(
       wantsStream,
       status: responseState.status,
     });
-    // Restore the raw auth/headers/cookies before any serialization below (the
-    // Proxies were only for the render-time touch probe).
-    if (props) {
-      props.auth = msg.auth;
-      props.headers = msg.headers;
-      props.cookies = msg.cookies;
-    }
+    // Serialization view of props built from the RAW `msg` values — the live
+    // `props` (with its read-tracking proxies) is NEVER mutated back to raw, so
+    // it can't become a vehicle that leaks a prior request's identity to a later
+    // render (the proxies are revoked in `finally`). headers/cookies are stripped
+    // inside buildHydrationTail; auth uses the raw value (so anon auth stays
+    // falsy/undefined rather than the proxy's empty `{}`). For a BUCKETED render,
+    // url/params/searchParams come from the pre-render `bucketTailBase` snapshot —
+    // NOT the live (page-mutable) props — so a page can't smuggle identity through
+    // a nested field into the shared tail. buildHydrationTail's bucket allowlist
+    // then serializes only these fields + the collapsed { signedIn } bit.
+    const tailProps = props
+      ? {
+          ...props,
+          auth: msg.auth,
+          headers: msg.headers,
+          cookies: msg.cookies,
+          session: { exists: msg.session_present === true },
+          ...(bucketable && bucketTailBase ? bucketTailBase : {}),
+        }
+      : props;
     // #278: on a STREAMING render the head commits NOW, before suspended
     // subtrees run. Snapshot what's committed so we can detect (after EOF) a
     // late response.setStatus/setCookie/setHeader from a suspended subtree that
@@ -2100,10 +2525,15 @@ export async function handleRenderRoute(
       headers: finalizeHeaders(
         responseState,
         undefined,
-        // The #277 proof rides the TRUSTED `internal` channel (never stripped),
-        // so userland (page setHeader / route-handler headers via `extra`) can't
-        // forge it.
-        cacheable ? { "x-pylon-cacheable": String(revalidateSecs) } : undefined,
+        // The #277 anon proof and the Phase 0 bucket proof both ride the TRUSTED
+        // `internal` channel (never stripped), so userland (page setHeader /
+        // route-handler headers via `extra`) can't forge either. Mutually
+        // exclusive (bucketOptIn splits the two verdicts).
+        bucketable
+          ? { "x-pylon-bucket": String(revalidateSecs) }
+          : cacheable
+            ? { "x-pylon-cacheable": String(revalidateSecs) }
+            : undefined,
       ),
     });
 
@@ -2242,7 +2672,7 @@ export async function handleRenderRoute(
       const tail = buildHydrationTail({
         component: msg.component,
         layouts: msg.layouts ?? [],
-        props,
+        props: tailProps,
         ssrData: ssrValueCache,
         manifestRoute: preloadManifestRoute,
         publicPrefix: preloadPublicPrefix,
@@ -2252,10 +2682,44 @@ export async function handleRenderRoute(
             ? "error"
             : "not-found"
           : undefined,
+        // A bucketed render is stored shared → its tail must carry ONLY the
+        // binary signed-in bit, never this request's real identity.
+        bucketAuth: bucketable
+          ? { signedIn: msg.session_present === true }
+          : undefined,
       });
       sendChunk(tail);
     }
 
+    // Dev HUD (dev only): append the cache-verdict + render-timing blob + the
+    // floating overlay. After the page tail so its marker/probe are in place
+    // before the deferred client entry boots the sync engine.
+    if (isDevMode()) {
+      const verdict = describeCacheVerdict({
+        bucketOptIn,
+        cacheable,
+        bucketable,
+        revalidateSecs,
+        authTouched,
+        dynamicTouched,
+        sessionTouched,
+        cookieCount: responseState.cookies.length,
+        strictPolicies,
+        wantsStream,
+        forceDynamic,
+        status: responseState.status,
+      });
+      sendChunk(
+        buildDevHudChunk({
+          route: msg.url,
+          component: msg.component,
+          renderMode: wantsStream ? "ssr-streaming" : "ssr-buffered",
+          renderMs: Math.round((performance.now() - renderStart) * 10) / 10,
+          cache: verdict,
+        }),
+      );
+    }
+
     send({ type: "render_done", call_id: msg.call_id });
   } catch (err: any) {
     // A page/layout called response.redirect()/response.notFound(), or
@@ -2344,5 +2808,17 @@ export async function handleRenderRoute(
       message:
         devMode && err?.stack ? String(err.stack) : err?.message ?? String(err),
     });
+  } finally {
+    // Revoke this render's per-request proxies. Any reference a page stashed in
+    // module-level state (props or props.auth/headers/cookies/session) now throws
+    // on access from a LATER render — fail-closed, so a prior request's identity
+    // can never silently enter a cached body without tripping read-tracking.
+    for (const revoke of proxyRevokers) {
+      try {
+        revoke();
+      } catch {
+        // best-effort
+      }
+    }
   }
 }

package/src/ssr-streaming.test.ts

@@ -18,9 +18,11 @@ import React, { Suspense, use } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
 import {
   buildHydrationTail,
+  computeBucketVerdict,
   computeCacheVerdict,
   computeRevalidateSecs,
   computeWantsStream,
+  describeCacheVerdict,
   diffCommittedResponse,
   isDevMode,
 } from "./ssr-runtime";
@@ -97,6 +99,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     forceDynamic: false,
     authTouched: false,
     dynamicTouched: false,
+    sessionTouched: false,
     cookieCount: 0,
     strictPolicies: false,
     wantsStream: false,
@@ -112,6 +115,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
     expect(computeCacheVerdict({ ...base, forceDynamic: true })).toBe(false);
     expect(computeCacheVerdict({ ...base, authTouched: true })).toBe(false); // read auth
     expect(computeCacheVerdict({ ...base, dynamicTouched: true })).toBe(false); // read headers/cookies
+    expect(computeCacheVerdict({ ...base, sessionTouched: true })).toBe(false); // read session.exists (anon cache)
     expect(computeCacheVerdict({ ...base, cookieCount: 1 })).toBe(false); // set a cookie
     expect(computeCacheVerdict({ ...base, strictPolicies: true })).toBe(false);
     expect(computeCacheVerdict({ ...base, wantsStream: true })).toBe(false); // STREAMING
@@ -136,6 +140,7 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
                     forceDynamic,
                     authTouched,
                     dynamicTouched: false,
+                    sessionTouched: false,
                     cookieCount,
                     strictPolicies,
                     wantsStream,
@@ -151,6 +156,128 @@ describe("computeCacheVerdict (the #277 leak-class gate)", () => {
   });
 });
 
+describe("computeBucketVerdict (PPR Phase 0 — session-presence shared cache)", () => {
+  const base = {
+    bucketOptIn: true,
+    revalidateSecs: 60 as number | null,
+    forceDynamic: false,
+    authTouched: false,
+    dynamicTouched: false,
+    cookieCount: 0,
+    strictPolicies: false,
+    wantsStream: false,
+    status: 200,
+  };
+
+  test("a clean opted-in bucketed 200 is bucketable", () => {
+    expect(computeBucketVerdict(base)).toBe(true);
+  });
+
+  test("sessionTouched is NOT a veto here (the whole point of a bucket)", () => {
+    // computeBucketVerdict has no sessionTouched field — reading session.exists
+    // is allowed. This test documents the contract by construction: the same
+    // base (which a bucket render reaches with sessionTouched=true) buckets.
+    expect(computeBucketVerdict(base)).toBe(true);
+  });
+
+  test("no opt-in → never buckets, even when otherwise clean", () => {
+    expect(computeBucketVerdict({ ...base, bucketOptIn: false })).toBe(false);
+  });
+
+  test("every identity/safety veto flips it to non-bucketable (fail-closed)", () => {
+    expect(computeBucketVerdict({ ...base, revalidateSecs: null })).toBe(false); // no TTL
+    expect(computeBucketVerdict({ ...base, forceDynamic: true })).toBe(false);
+    expect(computeBucketVerdict({ ...base, authTouched: true })).toBe(false); // read real auth
+    expect(computeBucketVerdict({ ...base, dynamicTouched: true })).toBe(false); // headers/cookies
+    expect(computeBucketVerdict({ ...base, cookieCount: 1 })).toBe(false); // set a cookie
+    expect(computeBucketVerdict({ ...base, strictPolicies: true })).toBe(false); // auth-filtered reads
+    expect(computeBucketVerdict({ ...base, wantsStream: true })).toBe(false); // streaming head
+    expect(computeBucketVerdict({ ...base, status: 404 })).toBe(false);
+    expect(computeBucketVerdict({ ...base, status: 307 })).toBe(false);
+  });
+
+  test("LOAD-BEARING: authTouched ALWAYS vetoes regardless of opt-in", () => {
+    // The proof that a bucketable body is identity-free: any output that depends
+    // on identity must read props.auth, which sets authTouched. So authTouched
+    // ⟹ !bucketable over the full cross-product.
+    const bools = [false, true];
+    for (const bucketOptIn of bools)
+      for (const dynamicTouched of bools)
+        for (const strictPolicies of bools)
+          for (const wantsStream of bools)
+            for (const cookieCount of [0, 1])
+              for (const status of [200, 404]) {
+                const v = computeBucketVerdict({
+                  bucketOptIn,
+                  revalidateSecs: 60,
+                  forceDynamic: false,
+                  authTouched: true,
+                  dynamicTouched,
+                  cookieCount,
+                  strictPolicies,
+                  wantsStream,
+                  status,
+                });
+                expect(v).toBe(false);
+              }
+  });
+});
+
+describe("describeCacheVerdict (dev HUD — why isn't my page cached?)", () => {
+  const base = {
+    bucketOptIn: false,
+    cacheable: false,
+    bucketable: false,
+    revalidateSecs: null as number | null,
+    authTouched: false,
+    dynamicTouched: false,
+    sessionTouched: false,
+    cookieCount: 0,
+    strictPolicies: false,
+    wantsStream: false,
+    forceDynamic: false,
+    status: 200,
+  };
+
+  test("cacheable / bucketed verdicts carry the TTL", () => {
+    expect(describeCacheVerdict({ ...base, cacheable: true, revalidateSecs: 60 })).toEqual({
+      verdict: "cacheable",
+      secs: 60,
+      reason: "anonymous shared cache",
+    });
+    const b = describeCacheVerdict({
+      ...base,
+      bucketOptIn: true,
+      bucketable: true,
+      revalidateSecs: 30,
+    });
+    expect(b.verdict).toBe("bucketed");
+    expect(b.secs).toBe(30);
+  });
+
+  test("dynamic verdict reports the SINGLE actionable reason", () => {
+    const why = (over: any) =>
+      describeCacheVerdict({ ...base, ...over }).reason;
+    // Not opted in at all.
+    expect(why({})).toContain("not opted in");
+    // Opted in (revalidate set) but each veto wins in priority order.
+    const opted = { revalidateSecs: 60 };
+    expect(why({ ...opted, status: 404 })).toContain("status 404");
+    expect(why({ ...opted, forceDynamic: true })).toContain("force-dynamic");
+    expect(why({ ...opted, wantsStream: true })).toContain("streaming");
+    expect(why({ ...opted, cookieCount: 1 })).toContain("set a cookie");
+    expect(why({ ...opted, strictPolicies: true })).toContain("STRICT");
+    expect(why({ ...opted, authTouched: true })).toContain("props.auth");
+    expect(why({ ...opted, dynamicTouched: true })).toContain("headers/cookies");
+    // Reading session on a non-bucket page → the actionable hint to opt into buckets.
+    expect(why({ ...opted, sessionTouched: true })).toContain("auth-bucketed");
+    // …but on a bucket-opted page that didn't bucket for another reason, no hint.
+    expect(why({ bucketOptIn: true, revalidateSecs: 60, sessionTouched: true })).not.toContain(
+      "auth-bucketed",
+    );
+  });
+});
+
 describe("diffCommittedResponse (#278 late-response.* drop detector)", () => {
   const snap = (over: any = {}) => ({
     status: 200,
@@ -303,3 +430,144 @@ describe("hydration tail ordering (#278: data blob before entry script)", () =>
     expect(tail).toContain('"body":"hi"');
   });
 });
+
+// ---------------------------------------------------------------------------
+// PPR Phase 0 — bucketed hydration tail must be IDENTITY-FREE
+// ---------------------------------------------------------------------------
+
+// Pull the __PYLON_DATA__ payload back out of a tail. JSON.parse natively
+// decodes the unicode escapes (< etc.) buildHydrationTail applies.
+function parsePylonData(tail: string): any {
+  const m = tail.match(
+    /<script id="__PYLON_DATA__" type="application\/json">([\s\S]*?)<\/script>/,
+  );
+  if (!m) throw new Error("no __PYLON_DATA__ blob in tail");
+  return JSON.parse(m[1]);
+}
+
+describe("bucketed hydration tail (PPR Phase 0 leak class)", () => {
+  // Two DIFFERENT signed-in identities. A non-bucketed tail serializes each
+  // verbatim; a bucketed tail MUST collapse both to `{ signedIn: true }`.
+  const alice = {
+    user_id: "user_alice",
+    tenant_id: "tenant_1",
+    roles: ["admin"],
+    email: "alice@x.com",
+  };
+  const bob = {
+    user_id: "user_bob",
+    tenant_id: "tenant_2",
+    roles: ["member"],
+    email: "bob@y.com",
+  };
+  const baseArgs = (auth: any) => ({
+    component: "app/page",
+    layouts: [],
+    props: {
+      url: "/",
+      params: {},
+      searchParams: {},
+      auth,
+      session: { exists: true },
+    },
+    ssrData: {},
+    manifestRoute: { file: "index.js", imports: [], css: [] },
+    publicPrefix: "/_pylon/build/",
+    manifestErr: null,
+  });
+
+  test("non-bucketed tail keeps real auth (unchanged legacy behavior)", () => {
+    const tail = buildHydrationTail(baseArgs(alice));
+    expect(parsePylonData(tail).props.auth).toEqual(alice);
+  });
+
+  test("bucketed signed-in tail carries ONLY { signedIn: true }", () => {
+    const tail = buildHydrationTail({
+      ...baseArgs(alice),
+      bucketAuth: { signedIn: true },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.auth).toEqual({ signedIn: true });
+    expect(data.props.session).toEqual({ exists: true });
+    // No identity escapes — not in props, not anywhere in the rendered tail.
+    expect(tail).not.toContain("user_alice");
+    expect(tail).not.toContain("tenant_1");
+    expect(tail).not.toContain("alice@x.com");
+    expect(tail).not.toContain("admin");
+  });
+
+  test("bucketed signed-out tail carries ONLY { signedIn: false }", () => {
+    const tail = buildHydrationTail({
+      ...baseArgs(null),
+      props: {
+        url: "/",
+        params: {},
+        searchParams: {},
+        auth: null,
+        session: { exists: false },
+      },
+      bucketAuth: { signedIn: false },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.auth).toEqual({ signedIn: false });
+    expect(data.props.session).toEqual({ exists: false });
+  });
+
+  test("LEAK INVARIANT: two identities → byte-identical bucketed tail", () => {
+    // The load-bearing property. If these two tails differed by a single byte,
+    // a shared cache entry would replay alice's identity to bob (or vice-versa).
+    const aTail = buildHydrationTail({
+      ...baseArgs(alice),
+      bucketAuth: { signedIn: true },
+    });
+    const bTail = buildHydrationTail({
+      ...baseArgs(bob),
+      bucketAuth: { signedIn: true },
+    });
+    expect(aTail).toBe(bTail);
+  });
+
+  test("bucketed tail DROPS page-added props (alias-identity fence, codex #4)", () => {
+    // A page can alias identity onto a custom key without tripping read-tracking
+    // (`props.leak = props.auth` — props is a plain object, no proxy trap). A
+    // bucketed (SHARED) tail must therefore serialize a strict ALLOWLIST of
+    // framework props, never a spread — else `leak` would carry one user's
+    // identity into every signed-in visitor's cached page.
+    const tail = buildHydrationTail({
+      ...baseArgs(alice),
+      props: {
+        url: "/",
+        params: { id: "x" },
+        searchParams: {},
+        auth: alice,
+        session: { exists: true },
+        // Page-aliased identity + a copied cookie bag.
+        leak: { uid: alice.user_id },
+        sneaky: alice.email,
+      },
+      bucketAuth: { signedIn: true },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.auth).toEqual({ signedIn: true });
+    // Allowlisted framework fields survive…
+    expect(data.props.url).toBe("/");
+    expect(data.props.params).toEqual({ id: "x" });
+    // …but the page-added keys are GONE, and no identity is anywhere in the tail.
+    expect(data.props.leak).toBeUndefined();
+    expect(data.props.sneaky).toBeUndefined();
+    expect(tail).not.toContain("user_alice");
+    expect(tail).not.toContain("alice@x.com");
+  });
+
+  test("NON-bucket tail still preserves page-added props (no behavior change)", () => {
+    // The allowlist applies ONLY to bucketed renders. A normal (non-shared)
+    // render keeps serializing all props so hydration matches the server tree.
+    const tail = buildHydrationTail({
+      ...baseArgs(alice),
+      props: { url: "/", params: {}, searchParams: {}, auth: alice, custom: 42 },
+    });
+    const data = parsePylonData(tail);
+    expect(data.props.custom).toBe(42);
+    expect(data.props.auth).toEqual(alice);
+  });
+});