@pylonsync/functions 0.3.249 → 0.3.251

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.249",
+  "version": "0.3.251",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -21,7 +21,8 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsc"
+    "build": "tsc",
+    "test": "bun test"
   },
   "keywords": [
     "pylon",
@@ -31,7 +32,12 @@
   ],
   "license": "MIT OR Apache-2.0",
   "devDependencies": {
-    "typescript": "^5.5"
+    "typescript": "^5.5",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "happy-dom": "^15.0.0"
   },
   "peerDependencies": {
     "bun-types": "*"

package/src/ssr-hydration.test.ts

@@ -0,0 +1,166 @@
+/**
+ * #278 Stage 2 — streaming-hydration regression guard (the prod-killer check).
+ *
+ * Proves the load-bearing claim behind multi-boundary streaming: hydrating the
+ * RESOLVED SSR DOM (which is what a streamed page's DOM becomes after React's
+ * $RC reveals run) with a `fulfilledThenable`-backed serverData shim produces
+ * clean output — the inner <Suspense> boundary renders its RESOLVED rows on the
+ * first committed pass, NOT a fallback, and React logs NO hydration mismatch.
+ *
+ * This is why Pylon needs NO inline per-boundary patch scripts: it withholds
+ * the bootstrap from renderToReadableStream and runs hydrateRoot ONCE, after
+ * the full ssrData blob — so `use()` reads a fulfilled value synchronously and
+ * never re-suspends. If a future change made `use()` suspend at hydration (a
+ * broken shim handing back a pending promise), the boundary would mismatch /
+ * lose its content — caught here.
+ *
+ * Isolated in its own file because it registers DOM globals (window/document)
+ * for react-dom/client; they're restored after each test.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import React, { Suspense, use } from "react";
+import { renderToReadableStream } from "react-dom/server.browser";
+
+// Mirrors `fulfilledThenable` in ssr-client-bundler.ts's CLIENT_RUNTIME_SOURCE:
+// a React-recognized fulfilled thenable so use() reads `.value` synchronously
+// (status === "fulfilled") instead of suspending.
+function fulfilledThenable<T>(value: T) {
+  return {
+    status: "fulfilled" as const,
+    value,
+    then(onFulfilled?: (v: T) => any) {
+      return onFulfilled ? onFulfilled(value) : (value as any);
+    },
+  };
+}
+
+function Rows({ p }: { p: PromiseLike<string[]> }) {
+  const rows = use(p as any) as string[];
+  return React.createElement(
+    "ul",
+    { id: "rows" },
+    rows.map((r) => React.createElement("li", { key: r }, r)),
+  );
+}
+function Page({ p }: { p: PromiseLike<string[]> }) {
+  return React.createElement(
+    "div",
+    { id: "app" },
+    React.createElement("h1", { id: "shell" }, "Shell"),
+    React.createElement(
+      Suspense,
+      { fallback: React.createElement("p", { id: "fallback" }, "Loading…") },
+      React.createElement(Rows, { p }),
+    ),
+  );
+}
+
+const dec = new TextDecoder();
+
+// Server-render the page (data pre-resolved) to its final resolved HTML — the
+// same DOM a streamed page settles to once React's reveal scripts have run.
+async function renderResolvedHtml(rows: string[]): Promise<string> {
+  const stream = await renderToReadableStream(
+    React.createElement(Page, { p: Promise.resolve(rows) }),
+  );
+  await (stream as any).allReady;
+  const reader = stream.getReader();
+  let html = "";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    html += dec.decode(value);
+  }
+  return html;
+}
+
+// Globals react-dom/client touches; saved + restored so this file's DOM
+// registration never bleeds into sibling test files.
+const DOM_GLOBAL_KEYS = [
+  "window",
+  "document",
+  "navigator",
+  "HTMLElement",
+  "Node",
+  "Event",
+  "MutationObserver",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+];
+let savedGlobals: Record<string, any> | null = null;
+
+function registerDom(win: any) {
+  const g = globalThis as any;
+  savedGlobals = {};
+  for (const k of DOM_GLOBAL_KEYS) savedGlobals[k] = g[k];
+  g.window = win;
+  g.document = win.document;
+  g.navigator = win.navigator;
+  g.HTMLElement = win.HTMLElement;
+  g.Node = win.Node;
+  g.Event = win.Event;
+  g.MutationObserver = win.MutationObserver;
+  g.requestAnimationFrame = (cb: any) => setTimeout(() => cb(Date.now()), 0);
+  g.cancelAnimationFrame = (id: any) => clearTimeout(id);
+}
+
+afterEach(() => {
+  if (!savedGlobals) return;
+  const g = globalThis as any;
+  for (const k of DOM_GLOBAL_KEYS) {
+    if (savedGlobals[k] === undefined) delete g[k];
+    else g[k] = savedGlobals[k];
+  }
+  savedGlobals = null;
+});
+
+describe("streaming hydration (#278)", () => {
+  test("fulfilledThenable shim → boundary hydrates to RESOLVED rows, no fallback, no mismatch", async () => {
+    const rows = ["alpha", "beta"];
+    const serverHtml = await renderResolvedHtml(rows);
+    // Sanity: the SSR DOM has the resolved rows (not a fallback).
+    expect(serverHtml).toContain("<li>alpha</li>");
+
+    const win = new Window({ url: "http://localhost/" });
+    // Parse the server HTML into a container element via HTML parsing (this
+    // preserves React's <!--$--> boundary comment markers, which hydrateRoot
+    // reads to locate Suspense boundaries). insertAdjacentHTML is the parse
+    // entry point; the input is our own rendered markup, not untrusted data.
+    const root = win.document.createElement("div");
+    root.setAttribute("id", "root");
+    root.insertAdjacentHTML("afterbegin", serverHtml);
+    win.document.body.appendChild(root);
+    registerDom(win);
+
+    const errors: string[] = [];
+    const origErr = console.error;
+    console.error = (...a: any[]) => {
+      errors.push(a.map(String).join(" "));
+    };
+    try {
+      const { hydrateRoot } = await import("react-dom/client");
+      // Client tree: same component, but serverData yields a fulfilled thenable
+      // (the value the server already streamed) — exactly the client shim's job.
+      hydrateRoot(
+        root as any,
+        React.createElement(Page, { p: fulfilledThenable(rows) }),
+      );
+      await new Promise((r) => setTimeout(r, 50));
+      const html = (root as any).innerHTML as string;
+
+      // The boundary committed its RESOLVED content on hydration...
+      expect(html).toContain("alpha");
+      expect(html).toContain("beta");
+      // ...NOT the fallback (no flash / no stuck boundary)...
+      expect(html).not.toContain("Loading…");
+      // ...and React logged NO hydration mismatch.
+      const mismatch = errors.filter((e) =>
+        /hydrat|did not match|mismatch|Text content does not match/i.test(e),
+      );
+      expect(mismatch).toEqual([]);
+    } finally {
+      console.error = origErr;
+    }
+  });
+});

package/src/ssr-runtime.ts

@@ -7,6 +7,20 @@
 // the dispatch arm) so projects without SSR routes pay nothing — no
 // react-dom dependency requirement, no startup cost.
 
+/**
+ * Is the runtime in dev mode? MUST match the Rust host's `is_dev_mode()`
+ * (crates/runtime/src/frontend.rs): `PYLON_DEV_MODE` is on ONLY for the exact
+ * strings "1" or "true" (case-insensitive). A bare `if (process.env.PYLON_DEV_MODE)`
+ * is WRONG — the string "false"/"0" is truthy in JS, so an explicit
+ * `PYLON_DEV_MODE=false` on a PROD machine would wrongly enable dev behavior
+ * (e.g. the live-reload `<script>` was being injected into prod pages, whose
+ * EventSource then 404-retried `/_pylon/dev/live` forever).
+ */
+export function isDevMode(): boolean {
+  const v = process.env.PYLON_DEV_MODE;
+  return v === "1" || v?.toLowerCase() === "true";
+}
+
 /**
  * The message payload the host sends. Matches RenderRouteMessage in
  * crates/functions/src/protocol.rs.
@@ -856,7 +870,7 @@ export function buildHydrationTail(args: {
   } else {
     tail += `<script>console.warn(${JSON.stringify(`[pylon ssr] hydration disabled: ${args.manifestErr}`)})</script>`;
   }
-  if (process.env.PYLON_DEV_MODE) tail += DEV_LIVE_RELOAD_SNIPPET;
+  if (isDevMode()) tail += DEV_LIVE_RELOAD_SNIPPET;
   return tail;
 }
 
@@ -1134,6 +1148,78 @@ function makeServerData(reader: any, valueCache: Record<string, any>): any {
   return sd;
 }
 
+/**
+ * #278: does this route STREAM (vs buffer the whole document)? Streaming is
+ * opt-in: a `loading.tsx` (route-level Suspense) or `export const streaming =
+ * true` (inner-boundary). Pure for testing.
+ */
+export function computeWantsStream(hasLoading: boolean, mod: any): boolean {
+  return hasLoading || mod?.streaming === true;
+}
+
+/**
+ * #277: how long an opt-in page stays cacheable, in seconds — or null if it
+ * never opted in. `export const revalidate = N` (N>0) → N; `dynamic:
+ * "force-static"` → a year (only a deploy invalidates); else null. Pure.
+ */
+export function computeRevalidateSecs(mod: any): number | null {
+  if (typeof mod?.revalidate === "number" && mod.revalidate > 0) {
+    return Math.floor(mod.revalidate);
+  }
+  if (mod?.dynamic === "force-static") return 31536000;
+  return null;
+}
+
+/**
+ * #277 cache verdict — the security-critical predicate, extracted pure so the
+ * leak class (a personalized/streaming render marked cacheable) is a TEST, not
+ * a mental walkthrough. INVARIANT: result ⟹ !wantsStream (a streaming render
+ * commits its head before auth/cookies/status are final, so it can never be
+ * cached). Fail-closed: every condition must hold.
+ */
+export function computeCacheVerdict(args: {
+  revalidateSecs: number | null;
+  forceDynamic: boolean;
+  authTouched: boolean;
+  cookieCount: number;
+  strictPolicies: boolean;
+  wantsStream: boolean;
+  status: number;
+}): boolean {
+  return (
+    args.revalidateSecs != null &&
+    !args.forceDynamic &&
+    !args.authTouched &&
+    args.cookieCount === 0 &&
+    !args.strictPolicies &&
+    !args.wantsStream &&
+    args.status === 200
+  );
+}
+
+/**
+ * #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
+ * that the already-sent head couldn't carry. Returns the dropped pieces, or
+ * null if nothing was lost. Pure.
+ */
+export function diffCommittedResponse(
+  snapshot: { status: number; cookies: string[]; headerKeys: string[] },
+  final: { status: number; cookies: string[]; headers: Record<string, string> },
+): { droppedCookies: string[]; statusChanged: boolean; newHeaderKeys: string[] } | null {
+  const droppedCookies = final.cookies.filter(
+    (c) => !snapshot.cookies.includes(c),
+  );
+  const statusChanged = final.status !== snapshot.status;
+  const newHeaderKeys = Object.keys(final.headers)
+    .sort()
+    .filter((k) => !snapshot.headerKeys.includes(k));
+  if (droppedCookies.length || statusChanged || newHeaderKeys.length) {
+    return { droppedCookies, statusChanged, newHeaderKeys };
+  }
+  return null;
+}
+
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
@@ -1307,6 +1393,16 @@ export async function handleRenderRoute(
       );
     }
 
+    // Streaming decision (#278). Computed from STATIC module exports only —
+    // knowable before any await, so the buffer/cache decision never reads
+    // non-final render state. A page STREAMS (shell + each inner <Suspense>
+    // fallback flush immediately, content reveals as data resolves) when it has
+    // a loading.tsx (route-level boundary, #278 Stage 1) OR explicitly opts in
+    // with `export const streaming = true` (inner-boundary streaming, Stage 2).
+    // Every un-annotated page keeps the byte-identical BUFFERED path (allReady)
+    // that 100% of today's prod traffic rides — this is opt-in, never default.
+    const wantsStream = computeWantsStream(!!Loading, mod);
+
     // Resolve the layout chain. Each layout module exports a default
     // function that accepts the same props + `children`. Walk leaf →
     // root: start with the page component as `tree`, then for each
@@ -1324,9 +1420,26 @@ export async function handleRenderRoute(
       {
         onError(err: unknown) {
           // React captures render errors during the streaming render
-          // and feeds them here. Phase 1 logs to stderr; Phase 1.5
-          // sends a structured signal so the host can truncate the
-          // body + emit a debug overlay.
+          // and feeds them here. We log to stderr; we do NOT truncate or
+          // rewrite the response here — on a streamed render the HTTP head is
+          // already committed, so a mid-stream error just closes the body
+          // (partial HTML); the dev overlay (#275) only covers failures BEFORE
+          // response_start (host-side err channel). Buffered renders surface
+          // their error through the catch/boundary path below.
+          if (err instanceof PylonRouteControl) {
+            // A redirect()/notFound() thrown from BELOW a <Suspense> boundary:
+            // the shell already committed the head, so React swallowed it and
+            // it can't change the response. This is a known limitation on BOTH
+            // the buffered and streamed paths (response.* must fire in the
+            // synchronous shell). Surface it loudly instead of silently losing.
+            // eslint-disable-next-line no-console
+            console.error(
+              `[ssr] response.${err.kind}() called below a <Suspense> boundary was ignored — ` +
+                `the HTTP head was already sent. Call response.redirect()/notFound() in the ` +
+                `synchronous shell render, before any await/<Suspense>.`,
+            );
+            return;
+          }
           // eslint-disable-next-line no-console
           console.error("[ssr] renderToReadableStream onError:", err);
         },
@@ -1343,15 +1456,17 @@ export async function handleRenderRoute(
     // fallback). Pages with no async data have no boundaries, so `allReady`
     // resolves immediately — zero cost for the common case.
     //
-    // EXCEPTION (#278): when a loading.tsx wraps the page in a Suspense
-    // boundary, we DELIBERATELY skip the buffer and stream — the shell +
-    // skeleton flush first, then React reveals the real content + its reveal
-    // script as the page's `use()` resolves. Hydration stays clean because
-    // there's exactly ONE route-level boundary and the tail `__PYLON_DATA__`
-    // (emitted below, after the stream drains to EOF) still carries a fully
-    // resolved `ssrData` map — so the client's `use()` reads a fulfilled
-    // value and never re-suspends.
-    if (!Loading && (stream as any).allReady) {
+    // EXCEPTION (#278): a STREAMING render (loading.tsx route-level boundary,
+    // or `export const streaming = true` for inner boundaries) DELIBERATELY
+    // skips the buffer — the shell + each <Suspense> fallback flush first, then
+    // React reveals each boundary's real content + its reveal script as that
+    // boundary's `use()` resolves. Hydration stays clean for ANY number of
+    // boundaries because Pylon runs hydrateRoot ONCE, post-EOF: the entry
+    // <script> is appended AFTER the full `__PYLON_DATA__` blob (which carries
+    // the fully-resolved `ssrData` map) and after all of React's $RC reveals,
+    // so the client's `use()` reads a fulfilled value and never re-suspends —
+    // there is no progressive hydration racing the stream.
+    if (!wantsStream && (stream as any).allReady) {
       await (stream as any).allReady;
     }
 
@@ -1372,25 +1487,41 @@ export async function handleRenderRoute(
     // public Cache-Control and STRIPS; its ABSENCE is the fail-closed default
     // (the host keeps no-cache / no-store). The 200-only guard avoids caching
     // an error/redirect.
-    const revalidateSecs =
-      typeof (mod as any).revalidate === "number" && (mod as any).revalidate > 0
-        ? Math.floor((mod as any).revalidate)
-        : (mod as any).dynamic === "force-static"
-          ? 31536000 // a year — only a deploy invalidates a force-static page
-          : null;
+    const revalidateSecs = computeRevalidateSecs(mod);
     const forceDynamic = (mod as any).dynamic === "force-dynamic";
     const strictPolicies = process.env.PYLON_STRICT_FN_POLICIES === "1";
-    const cacheable =
-      revalidateSecs != null &&
-      !forceDynamic &&
-      !authTouched &&
-      responseState.cookies.length === 0 &&
-      !strictPolicies &&
-      !Loading &&
-      responseState.status === 200;
+    // INVARIANT: cacheable ⟹ !wantsStream. A streaming render commits its head
+    // (response_start) BEFORE suspended subtrees finish, so `authTouched`,
+    // `responseState.cookies`, and `.status` are NOT final here — caching it
+    // could share a personalized/non-final body. So `!wantsStream` (NOT just
+    // `!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({
+      revalidateSecs,
+      forceDynamic,
+      authTouched,
+      cookieCount: responseState.cookies.length,
+      strictPolicies,
+      wantsStream,
+      status: responseState.status,
+    });
     // Restore the raw auth before any serialization below (the Proxy was only
     // for the render-time auth-touch probe).
     if (props) props.auth = msg.auth;
+    // #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
+    // got silently dropped — and warn loudly instead of leaving the dev to
+    // debug a missing Set-Cookie. Buffered renders need no snapshot (the whole
+    // render is done before this point, so nothing can change after).
+    const committedSnapshot = wantsStream
+      ? {
+          status: responseState.status,
+          cookies: responseState.cookies.map((c) => String(c)),
+          headerKeys: Object.keys(responseState.headers).sort(),
+        }
+      : null;
     send({
       type: "response_start",
       call_id: msg.call_id,
@@ -1464,6 +1595,47 @@ export async function handleRenderRoute(
     };
     await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
 
+    // #278: detect a late response.* mutation from a suspended subtree that the
+    // already-committed head couldn't carry, and warn loudly (a silently
+    // dropped Set-Cookie reads as "logged out" / missing CSRF in prod). Only
+    // for streamed renders — a buffered render finalized before response_start,
+    // so nothing changes after. The fix for the dev is to move the call into
+    // the synchronous shell (or drop `streaming = true`); we name what was lost.
+    if (committedSnapshot) {
+      // Same diff the unit tests exercise — call the pure helper so the tested
+      // path IS the prod path (no drift).
+      const dropped = diffCommittedResponse(committedSnapshot, {
+        status: responseState.status,
+        cookies: responseState.cookies,
+        headers: responseState.headers,
+      });
+      if (dropped) {
+        const parts: string[] = [];
+        if (dropped.droppedCookies.length)
+          parts.push(
+            `Set-Cookie [${dropped.droppedCookies
+              .map((c) => {
+                const eq = c.indexOf("="); // serialized "name=value; …"
+                return eq >= 0 ? c.slice(0, eq) : c;
+              })
+              .join(", ")}]`,
+          );
+        if (dropped.statusChanged)
+          parts.push(
+            `status ${committedSnapshot.status}→${responseState.status}`,
+          );
+        if (dropped.newHeaderKeys.length)
+          parts.push(`headers [${dropped.newHeaderKeys.join(", ")}]`);
+        // eslint-disable-next-line no-console
+        console.error(
+          `[ssr] response.* called below a <Suspense> boundary on a streaming ` +
+            `route was DROPPED (the HTTP head already shipped): ${parts.join("; ")}. ` +
+            `Set response status/cookies/headers in the synchronous shell render, ` +
+            `before any await/<Suspense> — or remove \`export const streaming = true\`.`,
+        );
+      }
+    }
+
     // Hydration tail. After React's stream EOFs we append the
     // hydration markers so the browser can hydrate:
     //   1. `__PYLON_DATA__` — JSON-typed script with the props the
@@ -1583,8 +1755,7 @@ export async function handleRenderRoute(
     // In dev, send the full stack as the message so the host can paint a
     // useful error overlay instead of an opaque 500. In prod, send only the
     // message (the host shows a generic page; the stack stays in logs).
-    const devMode =
-      process.env.PYLON_DEV_MODE === "1" || process.env.PYLON_DEV_MODE === "true";
+    const devMode = isDevMode();
     send({
       type: "error",
       call_id: msg.call_id,

package/src/ssr-streaming.test.ts

@@ -0,0 +1,302 @@
+/**
+ * #278 Stage 2 — progressive streaming harness.
+ *
+ * Two layers:
+ *  1. PURE verdict logic (computeWantsStream / computeRevalidateSecs /
+ *     computeCacheVerdict / diffCommittedResponse) — the security-critical
+ *     "is this render cacheable / should it stream" gate, tested directly
+ *     including the leak-class invariant `cacheable ⟹ !wantsStream`.
+ *  2. The actual React streaming MECHANISM through react-dom/server.browser —
+ *     proving the buffered (allReady) path emits clean inline HTML, and the
+ *     streamed path flushes the shell + Suspense fallback first then reveals.
+ *
+ * Hydration (the prod-killer "stuck on fallback" check) lives in the sibling
+ * ssr-hydration.test.ts (it mutates DOM globals, so it's isolated).
+ */
+import { describe, expect, test } from "bun:test";
+import React, { Suspense, use } from "react";
+import { renderToReadableStream } from "react-dom/server.browser";
+import {
+  buildHydrationTail,
+  computeCacheVerdict,
+  computeRevalidateSecs,
+  computeWantsStream,
+  diffCommittedResponse,
+  isDevMode,
+} from "./ssr-runtime";
+
+// ---------------------------------------------------------------------------
+// isDevMode — must match the Rust host's is_dev_mode() exactly
+// ---------------------------------------------------------------------------
+
+describe("isDevMode (PYLON_DEV_MODE parity with Rust host)", () => {
+  const orig = process.env.PYLON_DEV_MODE;
+  const set = (v: string | undefined) => {
+    if (v === undefined) delete process.env.PYLON_DEV_MODE;
+    else process.env.PYLON_DEV_MODE = v;
+  };
+
+  test("ONLY '1' / 'true' (case-insensitive) are dev; 'false'/'0'/unset are NOT", () => {
+    try {
+      set("1");
+      expect(isDevMode()).toBe(true);
+      set("true");
+      expect(isDevMode()).toBe(true);
+      set("TRUE");
+      expect(isDevMode()).toBe(true);
+      // The bug this guards: a prod machine explicitly set PYLON_DEV_MODE=false,
+      // and `if (process.env.PYLON_DEV_MODE)` treated the truthy STRING "false"
+      // as dev → injected the live-reload script → EventSource 404-looped on
+      // /_pylon/dev/live in prod.
+      set("false");
+      expect(isDevMode()).toBe(false);
+      set("0");
+      expect(isDevMode()).toBe(false);
+      set("");
+      expect(isDevMode()).toBe(false);
+      set(undefined);
+      expect(isDevMode()).toBe(false);
+    } finally {
+      set(orig);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Pure verdict logic
+// ---------------------------------------------------------------------------
+
+describe("computeWantsStream", () => {
+  test("loading.tsx OR streaming=true opts in; nothing else does", () => {
+    expect(computeWantsStream(true, {})).toBe(true); // loading.tsx
+    expect(computeWantsStream(false, { streaming: true })).toBe(true); // opt-in
+    expect(computeWantsStream(true, { streaming: true })).toBe(true);
+    expect(computeWantsStream(false, {})).toBe(false); // default = buffered
+    expect(computeWantsStream(false, { streaming: false })).toBe(false);
+    expect(computeWantsStream(false, { streaming: 1 as any })).toBe(false); // strict ===
+    expect(computeWantsStream(false, null)).toBe(false);
+  });
+});
+
+describe("computeRevalidateSecs", () => {
+  test("revalidate>0 → floor; force-static → a year; else null", () => {
+    expect(computeRevalidateSecs({ revalidate: 60 })).toBe(60);
+    expect(computeRevalidateSecs({ revalidate: 12.9 })).toBe(12);
+    expect(computeRevalidateSecs({ revalidate: 0 })).toBeNull();
+    expect(computeRevalidateSecs({ revalidate: -5 })).toBeNull();
+    expect(computeRevalidateSecs({ dynamic: "force-static" })).toBe(31536000);
+    expect(computeRevalidateSecs({ dynamic: "force-dynamic" })).toBeNull();
+    expect(computeRevalidateSecs({})).toBeNull();
+    expect(computeRevalidateSecs(null)).toBeNull();
+  });
+});
+
+describe("computeCacheVerdict (the #277 leak-class gate)", () => {
+  const base = {
+    revalidateSecs: 60 as number | null,
+    forceDynamic: false,
+    authTouched: false,
+    cookieCount: 0,
+    strictPolicies: false,
+    wantsStream: false,
+    status: 200,
+  };
+
+  test("a clean opted-in buffered 200 is cacheable", () => {
+    expect(computeCacheVerdict(base)).toBe(true);
+  });
+
+  test("every single veto flips it to non-cacheable (fail-closed)", () => {
+    expect(computeCacheVerdict({ ...base, revalidateSecs: null })).toBe(false); // no opt-in
+    expect(computeCacheVerdict({ ...base, forceDynamic: true })).toBe(false);
+    expect(computeCacheVerdict({ ...base, authTouched: true })).toBe(false); // read auth
+    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
+    expect(computeCacheVerdict({ ...base, status: 404 })).toBe(false);
+    expect(computeCacheVerdict({ ...base, status: 307 })).toBe(false);
+  });
+
+  test("INVARIANT: cacheable ⟹ !wantsStream over the full cross-product", () => {
+    const bools = [false, true];
+    const statuses = [200, 201, 302, 404, 500];
+    const revs: (number | null)[] = [null, 0 as any, 60, 31536000];
+    let checked = 0;
+    for (const forceDynamic of bools)
+      for (const authTouched of bools)
+        for (const strictPolicies of bools)
+          for (const wantsStream of bools)
+            for (const cookieCount of [0, 1])
+              for (const status of statuses)
+                for (const revalidateSecs of revs) {
+                  const c = computeCacheVerdict({
+                    revalidateSecs,
+                    forceDynamic,
+                    authTouched,
+                    cookieCount,
+                    strictPolicies,
+                    wantsStream,
+                    status,
+                  });
+                  // The load-bearing security invariant: a streaming render is
+                  // NEVER cacheable (its head commits before auth/cookies/status
+                  // are final).
+                  if (c) expect(wantsStream).toBe(false);
+                  checked++;
+                }
+    expect(checked).toBe(640); // 2^4 (bools) × 2 (cookies) × 5 (status) × 4 (revs)
+  });
+});
+
+describe("diffCommittedResponse (#278 late-response.* drop detector)", () => {
+  const snap = (over: any = {}) => ({
+    status: 200,
+    cookies: ["sid=committed"],
+    headerKeys: ["x-base"],
+    ...over,
+  });
+
+  test("no change → null", () => {
+    const r = diffCommittedResponse(snap(), {
+      status: 200,
+      cookies: ["sid=committed"],
+      headers: { "x-base": "1" },
+    });
+    expect(r).toBeNull();
+  });
+
+  test("a late Set-Cookie from a suspended subtree is reported", () => {
+    const r = diffCommittedResponse(snap(), {
+      status: 200,
+      cookies: ["sid=committed", "flash=late"],
+      headers: { "x-base": "1" },
+    });
+    expect(r).not.toBeNull();
+    expect(r!.droppedCookies).toEqual(["flash=late"]);
+  });
+
+  test("a late status change + new header are reported", () => {
+    const r = diffCommittedResponse(snap(), {
+      status: 201,
+      cookies: ["sid=committed"],
+      headers: { "x-base": "1", "x-late": "2" },
+    });
+    expect(r!.statusChanged).toBe(true);
+    expect(r!.newHeaderKeys).toEqual(["x-late"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// React streaming mechanism (real renderToReadableStream)
+// ---------------------------------------------------------------------------
+
+function makeDeferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => (resolve = r));
+  return { promise, resolve };
+}
+
+function Rows({ p }: { p: Promise<string[]> }) {
+  const rows = use(p);
+  return React.createElement(
+    "ul",
+    { id: "rows" },
+    rows.map((r) => React.createElement("li", { key: r }, r)),
+  );
+}
+
+// A page with an inner <Suspense> reading async data — the /notes shape.
+function Page({ p }: { p: Promise<string[]> }) {
+  return React.createElement(
+    "div",
+    { id: "app" },
+    React.createElement("h1", { id: "shell" }, "Shell"),
+    React.createElement(
+      Suspense,
+      { fallback: React.createElement("p", { id: "fallback" }, "Loading…") },
+      React.createElement(Rows, { p }),
+    ),
+  );
+}
+
+const dec = new TextDecoder();
+
+describe("react streaming mechanism", () => {
+  test("BUFFERED (await allReady, then drain) → clean inline, no reveal scripts", async () => {
+    // Mirrors the runtime's `if (!wantsStream) await stream.allReady` path.
+    const d = makeDeferred<string[]>();
+    setTimeout(() => d.resolve(["a", "b"]), 5);
+    const stream = await renderToReadableStream(
+      React.createElement(Page, { p: d.promise }),
+    );
+    await (stream as any).allReady;
+    const reader = stream.getReader();
+    let html = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      html += dec.decode(value);
+    }
+    // Resolved rows inline; NO fallback, NO pending marker, NO $RC reveal /
+    // <template>. This is the byte-identical buffered contract today's prod
+    // traffic rides — the regression lock.
+    expect(html).toContain("<li>a</li>");
+    expect(html).toContain("<li>b</li>");
+    expect(html).not.toContain("Loading…");
+    expect(html).not.toContain("<!--$?-->"); // no PENDING boundary marker
+    expect(html).not.toContain("<template");
+    expect(/\$RC|completeBoundary/.test(html)).toBe(false);
+  });
+
+  test("STREAMING (drain progressively) → shell+fallback first, rows+reveal later", async () => {
+    const d = makeDeferred<string[]>();
+    const stream = await renderToReadableStream(
+      React.createElement(Page, { p: d.promise }),
+    );
+    const reader = stream.getReader();
+    // First flush = the shell with the fallback (data still pending).
+    const first = await reader.read();
+    const firstHtml = dec.decode(first.value);
+    expect(firstHtml).toContain("Shell");
+    expect(firstHtml).toContain("Loading…"); // fallback streamed
+    expect(firstHtml).not.toContain("<li>a</li>"); // rows NOT here yet
+    expect(firstHtml).toContain("<template"); // boundary placeholder
+    // Now the data resolves → React reveals the boundary in a later chunk.
+    d.resolve(["a", "b"]);
+    let rest = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      rest += dec.decode(value);
+    }
+    expect(rest).toContain("<li>a</li>");
+    expect(rest).toContain("<li>b</li>");
+    expect(/\$RC|completeBoundary|<template/.test(rest)).toBe(true); // reveal
+  });
+});
+
+describe("hydration tail ordering (#278: data blob before entry script)", () => {
+  test("__PYLON_DATA__ carries ssrData and the entry <script type=module> is LAST", () => {
+    const ssrData = { 'list:["Note"]': [{ id: "1", body: "hi" }] };
+    const tail = buildHydrationTail({
+      component: "app/notes/page",
+      layouts: [],
+      props: { url: "/notes", params: {}, searchParams: {} },
+      ssrData,
+      manifestRoute: { file: "notes.js", imports: ["chunk.js"], css: [] },
+      publicPrefix: "/_pylon/build/",
+      manifestErr: null,
+    });
+    const dataIdx = tail.indexOf('id="__PYLON_DATA__"');
+    const entryIdx = tail.indexOf("notes.js");
+    expect(dataIdx).toBeGreaterThanOrEqual(0);
+    expect(entryIdx).toBeGreaterThanOrEqual(0);
+    // The entry script MUST come after the data blob so hydrateRoot (which the
+    // entry triggers) sees a fully-seeded ssrData — the whole reason multi-
+    // boundary streaming hydrates cleanly without inline patch scripts.
+    expect(entryIdx).toBeGreaterThan(dataIdx);
+    // ssrData round-trips into the blob.
+    expect(tail).toContain("Note");
+    expect(tail).toContain('"body":"hi"');
+  });
+});