vinext 0.0.50 → 0.0.52

package/dist/server/app-ssr-stream.js

@@ -1,5 +1,20 @@
+import { NAVIGATION_RUNTIME_SYMBOL_DESCRIPTION } from "../client/navigation-runtime.js";
 import { createInlineScriptTag, safeJsonStringify } from "./html.js";
+import { bytesToBase64, concatUint8Arrays } from "./app-rsc-embedded-chunks.js";
 //#region src/server/app-ssr-stream.ts
+const NAVIGATION_RUNTIME_REFERENCE = `self[Symbol.for(${safeJsonStringify(NAVIGATION_RUNTIME_SYMBOL_DESCRIPTION)})]`;
+function navigationRuntimeRscBootstrapExpression() {
+	return `((${NAVIGATION_RUNTIME_REFERENCE}??={bootstrap:{routeManifest:null},functions:{}}).bootstrap.rsc??={rsc:[]})`;
+}
+function createNavigationRuntimeRscMetadataScript(params, nav) {
+	return "Object.assign(" + navigationRuntimeRscBootstrapExpression() + ",{params:" + safeJsonStringify(params) + ",nav:" + safeJsonStringify(nav) + "})";
+}
+function createNavigationRuntimeRscChunkScript(chunk) {
+	return navigationRuntimeRscBootstrapExpression() + ".rsc.push(" + safeJsonStringify(chunk) + ")";
+}
+function createNavigationRuntimeRscDoneScript() {
+	return navigationRuntimeRscBootstrapExpression() + ".done=true";
+}
 /**
 * Fix invalid preload "as" values in RSC Flight hint lines before they reach
 * the client. React Flight emits HL hints with as="stylesheet" for CSS, but
@@ -10,11 +25,10 @@ function fixFlightHints(text) {
 }
 /**
 * Create a helper that progressively embeds RSC chunks as inline <script> tags.
-* The browser entry turns the embedded text chunks back into Uint8Array data.
+* The browser entry turns the embedded chunks back into Uint8Array data.
 */
 function createRscEmbedTransform(embedStream, scriptNonce) {
 	const reader = embedStream.getReader();
-	const decoder = new TextDecoder();
 	let pendingChunks = [];
 	const rawChunks = [];
 	let reading = false;
@@ -26,8 +40,12 @@ function createRscEmbedTransform(embedStream, scriptNonce) {
 				const result = await reader.read();
 				if (result.done) break;
 				rawChunks.push(result.value);
-				const text = decoder.decode(result.value, { stream: true });
-				pendingChunks.push(fixFlightHints(text));
+				try {
+					const text = new TextDecoder("utf-8", { fatal: true }).decode(result.value);
+					pendingChunks.push(fixFlightHints(text));
+				} catch {
+					pendingChunks.push([3, bytesToBase64(result.value)]);
+				}
 			}
 		} catch (error) {
 			if (process.env.NODE_ENV !== "production") console.warn("[vinext] RSC embed stream read error:", error);
@@ -43,25 +61,18 @@ function createRscEmbedTransform(embedStream, scriptNonce) {
 			const chunks = pendingChunks;
 			pendingChunks = [];
 			let scripts = "";
-			for (const chunk of chunks) scripts += createInlineScriptTag("self.__VINEXT_RSC_CHUNKS__=self.__VINEXT_RSC_CHUNKS__||[];self.__VINEXT_RSC_CHUNKS__.push(" + safeJsonStringify(chunk) + ")", scriptNonce);
+			for (const chunk of chunks) scripts += createInlineScriptTag(createNavigationRuntimeRscChunkScript(chunk), scriptNonce);
 			return scripts;
 		},
 		async finalize() {
 			await pumpPromise;
 			let scripts = this.flush();
-			scripts += createInlineScriptTag("self.__VINEXT_RSC_DONE__=true", scriptNonce);
+			scripts += createInlineScriptTag(createNavigationRuntimeRscDoneScript(), scriptNonce);
 			return scripts;
 		},
 		async getRawBuffer() {
 			await pumpPromise;
-			let totalLength = 0;
-			for (const chunk of rawChunks) totalLength += chunk.byteLength;
-			const buffer = new Uint8Array(totalLength);
-			let offset = 0;
-			for (const chunk of rawChunks) {
-				buffer.set(chunk, offset);
-				offset += chunk.byteLength;
-			}
+			const buffer = concatUint8Arrays(rawChunks);
 			rawChunks.length = 0;
 			return buffer.buffer;
 		}
@@ -138,6 +149,6 @@ function createTickBufferedTransform(rscEmbed, injectHTML = "") {
 	});
 }
 //#endregion
-export { createRscEmbedTransform, createTickBufferedTransform, fixFlightHints, fixPreloadAs };
+export { createNavigationRuntimeRscMetadataScript, createRscEmbedTransform, createTickBufferedTransform, fixFlightHints, fixPreloadAs, navigationRuntimeRscBootstrapExpression };
 
 //# sourceMappingURL=app-ssr-stream.js.map

package/dist/server/app-ssr-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-ssr-stream.js","names":[],"sources":["../../src/server/app-ssr-stream.ts"],"sourcesContent":["import { createInlineScriptTag, safeJsonStringify } from \"./html.js\";\n\ntype RscEmbedTransform = {\n  flush(): string;\n  finalize(): Promise<string>;\n  /** Resolves when all raw bytes from the embed stream have been read. */\n  getRawBuffer(): Promise<ArrayBuffer>;\n};\n\ntype HtmlInsertion = string | (() => string);\n\n/**\n * Fix invalid preload \"as\" values in RSC Flight hint lines before they reach\n * the client. React Flight emits HL hints with as=\"stylesheet\" for CSS, but\n * the HTML spec requires as=\"style\" for <link rel=\"preload\">.\n */\nexport function fixFlightHints(text: string): string {\n  return text.replace(/(\\d*:HL\\[.*?),\"stylesheet\"(\\]|,)/g, '$1,\"style\"$2');\n}\n\n/**\n * Create a helper that progressively embeds RSC chunks as inline <script> tags.\n * The browser entry turns the embedded text chunks back into Uint8Array data.\n */\nexport function createRscEmbedTransform(\n  embedStream: ReadableStream<Uint8Array>,\n  scriptNonce?: string,\n): RscEmbedTransform {\n  const reader = embedStream.getReader();\n  const decoder = new TextDecoder();\n  let pendingChunks: string[] = [];\n  const rawChunks: Uint8Array[] = [];\n  let reading = false;\n\n  async function pumpReader(): Promise<void> {\n    if (reading) return;\n    reading = true;\n    try {\n      while (true) {\n        const result = await reader.read();\n        if (result.done) break;\n        // Accumulate raw bytes BEFORE fixFlightHints so the cache stores\n        // unmodified RSC data. The embed script path below applies fixes.\n        rawChunks.push(result.value);\n        const text = decoder.decode(result.value, { stream: true });\n        // The RSC entry already fixes HL hints at the source. Keep this second\n        // pass as defense in depth for any embed stream that bypasses that\n        // wrapper; the rewrite is idempotent, so double-application is safe.\n        pendingChunks.push(fixFlightHints(text));\n      }\n    } catch (error) {\n      if (process.env.NODE_ENV !== \"production\") {\n        console.warn(\"[vinext] RSC embed stream read error:\", error);\n      }\n      throw error;\n    } finally {\n      reading = false;\n    }\n  }\n\n  const pumpPromise = pumpReader();\n\n  return {\n    flush(): string {\n      if (pendingChunks.length === 0) return \"\";\n\n      const chunks = pendingChunks;\n      pendingChunks = [];\n\n      let scripts = \"\";\n      for (const chunk of chunks) {\n        scripts += createInlineScriptTag(\n          \"self.__VINEXT_RSC_CHUNKS__=self.__VINEXT_RSC_CHUNKS__||[];self.__VINEXT_RSC_CHUNKS__.push(\" +\n            safeJsonStringify(chunk) +\n            \")\",\n          scriptNonce,\n        );\n      }\n      return scripts;\n    },\n\n    async finalize(): Promise<string> {\n      await pumpPromise;\n      let scripts = this.flush();\n      scripts += createInlineScriptTag(\"self.__VINEXT_RSC_DONE__=true\", scriptNonce);\n      return scripts;\n    },\n\n    async getRawBuffer(): Promise<ArrayBuffer> {\n      await pumpPromise;\n      let totalLength = 0;\n      for (const chunk of rawChunks) {\n        totalLength += chunk.byteLength;\n      }\n      const buffer = new Uint8Array(totalLength);\n      let offset = 0;\n      for (const chunk of rawChunks) {\n        buffer.set(chunk, offset);\n        offset += chunk.byteLength;\n      }\n      rawChunks.length = 0;\n      return buffer.buffer;\n    },\n  };\n}\n\n/**\n * Fix invalid preload \"as\" values in server-rendered HTML.\n * React Fizz emits <link rel=\"preload\" as=\"stylesheet\"> for CSS, but the\n * HTML spec requires as=\"style\" for <link rel=\"preload\">.\n */\nexport function fixPreloadAs(html: string): string {\n  return html.replace(/<link(?=[^>]*\\srel=\"preload\")[^>]*>/g, (tag) =>\n    tag.replace(' as=\"stylesheet\"', ' as=\"style\"'),\n  );\n}\n\n/**\n * Create the tick-buffered HTML transform that injects RSC scripts between\n * React Fizz flush cycles without corrupting split HTML chunks.\n */\nexport function createTickBufferedTransform(\n  rscEmbed: RscEmbedTransform,\n  injectHTML: HtmlInsertion = \"\",\n): TransformStream<Uint8Array, Uint8Array> {\n  const decoder = new TextDecoder();\n  const encoder = new TextEncoder();\n  const insertsPerFlush = typeof injectHTML === \"function\";\n  let injected = false;\n  let buffered: string[] = [];\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  const readInsertion = (): string =>\n    typeof injectHTML === \"function\" ? injectHTML() : injectHTML;\n  const emitInsertion = (controller: TransformStreamDefaultController<Uint8Array>): void => {\n    const insertion = readInsertion();\n    if (insertion) {\n      controller.enqueue(encoder.encode(insertion));\n    }\n  };\n\n  const flushBuffered = (controller: TransformStreamDefaultController<Uint8Array>): void => {\n    if (buffered.length === 0) return;\n\n    if (injected && insertsPerFlush) {\n      // Emit newly collected server-inserted HTML before the next Fizz HTML\n      // batch so CSS-in-JS styles precede the elements they style.\n      emitInsertion(controller);\n    }\n\n    for (const chunk of buffered) {\n      if (!injected) {\n        const headEnd = chunk.indexOf(\"</head>\");\n        if (headEnd !== -1) {\n          const before = chunk.slice(0, headEnd);\n          const after = chunk.slice(headEnd);\n          controller.enqueue(encoder.encode(before + readInsertion() + after));\n          injected = true;\n          continue;\n        }\n      }\n      controller.enqueue(encoder.encode(chunk));\n    }\n    buffered = [];\n  };\n\n  return new TransformStream<Uint8Array, Uint8Array>({\n    transform(chunk, controller) {\n      buffered.push(fixPreloadAs(decoder.decode(chunk, { stream: true })));\n\n      if (timeoutId !== null) return;\n\n      timeoutId = setTimeout(() => {\n        try {\n          flushBuffered(controller);\n\n          const rscScripts = rscEmbed.flush();\n          if (rscScripts) {\n            controller.enqueue(encoder.encode(rscScripts));\n          }\n        } catch {\n          // Stream was cancelled between when the timeout was registered and\n          // when it fired (e.g. client disconnected, health-check cancelled\n          // the response body). Ignore — the stream is already closed.\n        }\n\n        timeoutId = null;\n      }, 0);\n    },\n\n    async flush(controller) {\n      if (timeoutId !== null) {\n        clearTimeout(timeoutId);\n        timeoutId = null;\n      }\n\n      flushBuffered(controller);\n\n      if (!injected) {\n        emitInsertion(controller);\n        injected = true;\n      } else if (insertsPerFlush) {\n        emitInsertion(controller);\n      }\n\n      const finalScripts = await rscEmbed.finalize();\n      if (finalScripts) {\n        controller.enqueue(encoder.encode(finalScripts));\n      }\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"app-ssr-stream.js","names":[],"sources":["../../src/server/app-ssr-stream.ts"],"sourcesContent":["import { createInlineScriptTag, safeJsonStringify } from \"./html.js\";\nimport {\n  bytesToBase64,\n  concatUint8Arrays,\n  RSC_EMBEDDED_BINARY_CHUNK,\n  type RscEmbeddedChunk,\n} from \"./app-rsc-embedded-chunks.js\";\nimport { NAVIGATION_RUNTIME_SYMBOL_DESCRIPTION } from \"../client/navigation-runtime.js\";\n\ntype RscEmbedTransform = {\n  flush(): string;\n  finalize(): Promise<string>;\n  /** Resolves when all raw bytes from the embed stream have been read. */\n  getRawBuffer(): Promise<ArrayBuffer>;\n};\n\ntype HtmlInsertion = string | (() => string);\n\nconst NAVIGATION_RUNTIME_REFERENCE = `self[Symbol.for(${safeJsonStringify(\n  NAVIGATION_RUNTIME_SYMBOL_DESCRIPTION,\n)})]`;\n\nexport function navigationRuntimeRscBootstrapExpression(): string {\n  return `((${NAVIGATION_RUNTIME_REFERENCE}??={bootstrap:{routeManifest:null},functions:{}}).bootstrap.rsc??={rsc:[]})`;\n}\n\nexport function createNavigationRuntimeRscMetadataScript(\n  params: Record<string, string | string[]>,\n  nav: { pathname: string; searchParams: [string, string][] },\n): string {\n  return (\n    \"Object.assign(\" +\n    navigationRuntimeRscBootstrapExpression() +\n    \",{params:\" +\n    safeJsonStringify(params) +\n    \",nav:\" +\n    safeJsonStringify(nav) +\n    \"})\"\n  );\n}\n\nfunction createNavigationRuntimeRscChunkScript(chunk: RscEmbeddedChunk): string {\n  return navigationRuntimeRscBootstrapExpression() + \".rsc.push(\" + safeJsonStringify(chunk) + \")\";\n}\n\nfunction createNavigationRuntimeRscDoneScript(): string {\n  return navigationRuntimeRscBootstrapExpression() + \".done=true\";\n}\n\n/**\n * Fix invalid preload \"as\" values in RSC Flight hint lines before they reach\n * the client. React Flight emits HL hints with as=\"stylesheet\" for CSS, but\n * the HTML spec requires as=\"style\" for <link rel=\"preload\">.\n */\nexport function fixFlightHints(text: string): string {\n  return text.replace(/(\\d*:HL\\[.*?),\"stylesheet\"(\\]|,)/g, '$1,\"style\"$2');\n}\n\n/**\n * Create a helper that progressively embeds RSC chunks as inline <script> tags.\n * The browser entry turns the embedded chunks back into Uint8Array data.\n */\nexport function createRscEmbedTransform(\n  embedStream: ReadableStream<Uint8Array>,\n  scriptNonce?: string,\n): RscEmbedTransform {\n  const reader = embedStream.getReader();\n  let pendingChunks: RscEmbeddedChunk[] = [];\n  const rawChunks: Uint8Array[] = [];\n  let reading = false;\n\n  async function pumpReader(): Promise<void> {\n    if (reading) return;\n    reading = true;\n    try {\n      while (true) {\n        const result = await reader.read();\n        if (result.done) break;\n        // Accumulate raw bytes BEFORE fixFlightHints so the cache stores\n        // unmodified RSC data. The embed script path below applies fixes.\n        rawChunks.push(result.value);\n        try {\n          const decoder = new TextDecoder(\"utf-8\", { fatal: true });\n          const text = decoder.decode(result.value);\n          // The RSC entry already fixes HL hints at the source. Keep this second\n          // pass as defense in depth for any embed stream that bypasses that\n          // wrapper; the rewrite is idempotent, so double-application is safe.\n          pendingChunks.push(fixFlightHints(text));\n        } catch {\n          pendingChunks.push([RSC_EMBEDDED_BINARY_CHUNK, bytesToBase64(result.value)]);\n        }\n      }\n    } catch (error) {\n      if (process.env.NODE_ENV !== \"production\") {\n        console.warn(\"[vinext] RSC embed stream read error:\", error);\n      }\n      throw error;\n    } finally {\n      reading = false;\n    }\n  }\n\n  const pumpPromise = pumpReader();\n\n  return {\n    flush(): string {\n      if (pendingChunks.length === 0) return \"\";\n\n      const chunks = pendingChunks;\n      pendingChunks = [];\n\n      let scripts = \"\";\n      for (const chunk of chunks) {\n        scripts += createInlineScriptTag(createNavigationRuntimeRscChunkScript(chunk), scriptNonce);\n      }\n      return scripts;\n    },\n\n    async finalize(): Promise<string> {\n      await pumpPromise;\n      let scripts = this.flush();\n      scripts += createInlineScriptTag(createNavigationRuntimeRscDoneScript(), scriptNonce);\n      return scripts;\n    },\n\n    async getRawBuffer(): Promise<ArrayBuffer> {\n      await pumpPromise;\n      const buffer = concatUint8Arrays(rawChunks);\n      rawChunks.length = 0;\n      return buffer.buffer;\n    },\n  };\n}\n\n/**\n * Fix invalid preload \"as\" values in server-rendered HTML.\n * React Fizz emits <link rel=\"preload\" as=\"stylesheet\"> for CSS, but the\n * HTML spec requires as=\"style\" for <link rel=\"preload\">.\n */\nexport function fixPreloadAs(html: string): string {\n  return html.replace(/<link(?=[^>]*\\srel=\"preload\")[^>]*>/g, (tag) =>\n    tag.replace(' as=\"stylesheet\"', ' as=\"style\"'),\n  );\n}\n\n/**\n * Create the tick-buffered HTML transform that injects RSC scripts between\n * React Fizz flush cycles without corrupting split HTML chunks.\n */\nexport function createTickBufferedTransform(\n  rscEmbed: RscEmbedTransform,\n  injectHTML: HtmlInsertion = \"\",\n): TransformStream<Uint8Array, Uint8Array> {\n  const decoder = new TextDecoder();\n  const encoder = new TextEncoder();\n  const insertsPerFlush = typeof injectHTML === \"function\";\n  let injected = false;\n  let buffered: string[] = [];\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  const readInsertion = (): string =>\n    typeof injectHTML === \"function\" ? injectHTML() : injectHTML;\n  const emitInsertion = (controller: TransformStreamDefaultController<Uint8Array>): void => {\n    const insertion = readInsertion();\n    if (insertion) {\n      controller.enqueue(encoder.encode(insertion));\n    }\n  };\n\n  const flushBuffered = (controller: TransformStreamDefaultController<Uint8Array>): void => {\n    if (buffered.length === 0) return;\n\n    if (injected && insertsPerFlush) {\n      // Emit newly collected server-inserted HTML before the next Fizz HTML\n      // batch so CSS-in-JS styles precede the elements they style.\n      emitInsertion(controller);\n    }\n\n    for (const chunk of buffered) {\n      if (!injected) {\n        const headEnd = chunk.indexOf(\"</head>\");\n        if (headEnd !== -1) {\n          const before = chunk.slice(0, headEnd);\n          const after = chunk.slice(headEnd);\n          controller.enqueue(encoder.encode(before + readInsertion() + after));\n          injected = true;\n          continue;\n        }\n      }\n      controller.enqueue(encoder.encode(chunk));\n    }\n    buffered = [];\n  };\n\n  return new TransformStream<Uint8Array, Uint8Array>({\n    transform(chunk, controller) {\n      buffered.push(fixPreloadAs(decoder.decode(chunk, { stream: true })));\n\n      if (timeoutId !== null) return;\n\n      timeoutId = setTimeout(() => {\n        try {\n          flushBuffered(controller);\n\n          const rscScripts = rscEmbed.flush();\n          if (rscScripts) {\n            controller.enqueue(encoder.encode(rscScripts));\n          }\n        } catch {\n          // Stream was cancelled between when the timeout was registered and\n          // when it fired (e.g. client disconnected, health-check cancelled\n          // the response body). Ignore — the stream is already closed.\n        }\n\n        timeoutId = null;\n      }, 0);\n    },\n\n    async flush(controller) {\n      if (timeoutId !== null) {\n        clearTimeout(timeoutId);\n        timeoutId = null;\n      }\n\n      flushBuffered(controller);\n\n      if (!injected) {\n        emitInsertion(controller);\n        injected = true;\n      } else if (insertsPerFlush) {\n        emitInsertion(controller);\n      }\n\n      const finalScripts = await rscEmbed.finalize();\n      if (finalScripts) {\n        controller.enqueue(encoder.encode(finalScripts));\n      }\n    },\n  });\n}\n"],"mappings":";;;;AAkBA,MAAM,+BAA+B,mBAAmB,kBACtD,sCACD,CAAC;AAEF,SAAgB,0CAAkD;CAChE,OAAO,KAAK,6BAA6B;;AAG3C,SAAgB,yCACd,QACA,KACQ;CACR,OACE,mBACA,yCAAyC,GACzC,cACA,kBAAkB,OAAO,GACzB,UACA,kBAAkB,IAAI,GACtB;;AAIJ,SAAS,sCAAsC,OAAiC;CAC9E,OAAO,yCAAyC,GAAG,eAAe,kBAAkB,MAAM,GAAG;;AAG/F,SAAS,uCAA+C;CACtD,OAAO,yCAAyC,GAAG;;;;;;;AAQrD,SAAgB,eAAe,MAAsB;CACnD,OAAO,KAAK,QAAQ,qCAAqC,iBAAe;;;;;;AAO1E,SAAgB,wBACd,aACA,aACmB;CACnB,MAAM,SAAS,YAAY,WAAW;CACtC,IAAI,gBAAoC,EAAE;CAC1C,MAAM,YAA0B,EAAE;CAClC,IAAI,UAAU;CAEd,eAAe,aAA4B;EACzC,IAAI,SAAS;EACb,UAAU;EACV,IAAI;GACF,OAAO,MAAM;IACX,MAAM,SAAS,MAAM,OAAO,MAAM;IAClC,IAAI,OAAO,MAAM;IAGjB,UAAU,KAAK,OAAO,MAAM;IAC5B,IAAI;KAEF,MAAM,OAAO,IADO,YAAY,SAAS,EAAE,OAAO,MAAM,CACpC,CAAC,OAAO,OAAO,MAAM;KAIzC,cAAc,KAAK,eAAe,KAAK,CAAC;YAClC;KACN,cAAc,KAAK,CAAA,GAA4B,cAAc,OAAO,MAAM,CAAC,CAAC;;;WAGzE,OAAO;GACd,IAAI,QAAQ,IAAI,aAAa,cAC3B,QAAQ,KAAK,yCAAyC,MAAM;GAE9D,MAAM;YACE;GACR,UAAU;;;CAId,MAAM,cAAc,YAAY;CAEhC,OAAO;EACL,QAAgB;GACd,IAAI,cAAc,WAAW,GAAG,OAAO;GAEvC,MAAM,SAAS;GACf,gBAAgB,EAAE;GAElB,IAAI,UAAU;GACd,KAAK,MAAM,SAAS,QAClB,WAAW,sBAAsB,sCAAsC,MAAM,EAAE,YAAY;GAE7F,OAAO;;EAGT,MAAM,WAA4B;GAChC,MAAM;GACN,IAAI,UAAU,KAAK,OAAO;GAC1B,WAAW,sBAAsB,sCAAsC,EAAE,YAAY;GACrF,OAAO;;EAGT,MAAM,eAAqC;GACzC,MAAM;GACN,MAAM,SAAS,kBAAkB,UAAU;GAC3C,UAAU,SAAS;GACnB,OAAO,OAAO;;EAEjB;;;;;;;AAQH,SAAgB,aAAa,MAAsB;CACjD,OAAO,KAAK,QAAQ,yCAAyC,QAC3D,IAAI,QAAQ,sBAAoB,gBAAc,CAC/C;;;;;;AAOH,SAAgB,4BACd,UACA,aAA4B,IACa;CACzC,MAAM,UAAU,IAAI,aAAa;CACjC,MAAM,UAAU,IAAI,aAAa;CACjC,MAAM,kBAAkB,OAAO,eAAe;CAC9C,IAAI,WAAW;CACf,IAAI,WAAqB,EAAE;CAC3B,IAAI,YAAkD;CACtD,MAAM,sBACJ,OAAO,eAAe,aAAa,YAAY,GAAG;CACpD,MAAM,iBAAiB,eAAmE;EACxF,MAAM,YAAY,eAAe;EACjC,IAAI,WACF,WAAW,QAAQ,QAAQ,OAAO,UAAU,CAAC;;CAIjD,MAAM,iBAAiB,eAAmE;EACxF,IAAI,SAAS,WAAW,GAAG;EAE3B,IAAI,YAAY,iBAGd,cAAc,WAAW;EAG3B,KAAK,MAAM,SAAS,UAAU;GAC5B,IAAI,CAAC,UAAU;IACb,MAAM,UAAU,MAAM,QAAQ,UAAU;IACxC,IAAI,YAAY,IAAI;KAClB,MAAM,SAAS,MAAM,MAAM,GAAG,QAAQ;KACtC,MAAM,QAAQ,MAAM,MAAM,QAAQ;KAClC,WAAW,QAAQ,QAAQ,OAAO,SAAS,eAAe,GAAG,MAAM,CAAC;KACpE,WAAW;KACX;;;GAGJ,WAAW,QAAQ,QAAQ,OAAO,MAAM,CAAC;;EAE3C,WAAW,EAAE;;CAGf,OAAO,IAAI,gBAAwC;EACjD,UAAU,OAAO,YAAY;GAC3B,SAAS,KAAK,aAAa,QAAQ,OAAO,OAAO,EAAE,QAAQ,MAAM,CAAC,CAAC,CAAC;GAEpE,IAAI,cAAc,MAAM;GAExB,YAAY,iBAAiB;IAC3B,IAAI;KACF,cAAc,WAAW;KAEzB,MAAM,aAAa,SAAS,OAAO;KACnC,IAAI,YACF,WAAW,QAAQ,QAAQ,OAAO,WAAW,CAAC;YAE1C;IAMR,YAAY;MACX,EAAE;;EAGP,MAAM,MAAM,YAAY;GACtB,IAAI,cAAc,MAAM;IACtB,aAAa,UAAU;IACvB,YAAY;;GAGd,cAAc,WAAW;GAEzB,IAAI,CAAC,UAAU;IACb,cAAc,WAAW;IACzB,WAAW;UACN,IAAI,iBACT,cAAc,WAAW;GAG3B,MAAM,eAAe,MAAM,SAAS,UAAU;GAC9C,IAAI,cACF,WAAW,QAAQ,QAAQ,OAAO,aAAa,CAAC;;EAGrD,CAAC"}

package/dist/server/artifact-compatibility.d.ts

@@ -17,9 +17,19 @@ type ArtifactCompatibilityEnvelopeInput = Readonly<{
   rootBoundaryId?: string | null;
   renderEpoch?: string | null;
 }>;
+type ArtifactCompatibilitySet = readonly [string, string, ...string[]];
+type ArtifactCompatibilityMap = Readonly<{
+  graphVersions?: readonly ArtifactCompatibilitySet[];
+  deploymentVersions?: readonly ArtifactCompatibilitySet[];
+  rootBoundaryIds?: readonly ArtifactCompatibilitySet[];
+  renderEpochs?: readonly ArtifactCompatibilitySet[];
+}>;
+type ArtifactCompatibilityEvaluationOptions = Readonly<{
+  compatibilityMap?: ArtifactCompatibilityMap;
+}>;
 type ArtifactCompatibilityFallback = "renderFresh";
 type ArtifactCompatibilityUnknownReason = "graphVersionUnknown" | "deploymentVersionUnknown" | "rootBoundaryIdUnknown" | "renderEpochUnknown";
-type ArtifactCompatibilityIncompatibleReason = "appElementsSchemaVersionMismatch" | "deploymentVersionMismatch" | "graphVersionMismatch" | "renderEpochMismatch" | "rootBoundaryIdMismatch" | "rscPayloadSchemaVersionMismatch" | "schemaVersionMismatch";
+type ArtifactCompatibilityIncompatibleReason = "appElementsSchemaVersionMismatch" | "deploymentVersionNotDeclaredCompatible" | "deploymentVersionMismatch" | "graphVersionNotDeclaredCompatible" | "graphVersionMismatch" | "renderEpochNotDeclaredCompatible" | "renderEpochMismatch" | "rootBoundaryIdNotDeclaredCompatible" | "rootBoundaryIdMismatch" | "rscPayloadSchemaVersionMismatch" | "schemaVersionMismatch";
 type ArtifactCompatibilityDecision = Readonly<{
   kind: "compatible";
 } | {
@@ -38,7 +48,7 @@ type ArtifactCompatibilityGraphVersionInput = Readonly<{
 declare function createArtifactCompatibilityEnvelope(input?: ArtifactCompatibilityEnvelopeInput): ArtifactCompatibilityEnvelope;
 declare function createArtifactCompatibilityGraphVersion(input: ArtifactCompatibilityGraphVersionInput): string;
 declare function parseArtifactCompatibilityEnvelope(value: unknown): ArtifactCompatibilityEnvelope | null;
-declare function evaluateArtifactCompatibility(current: ArtifactCompatibilityEnvelope, candidate: ArtifactCompatibilityEnvelope): ArtifactCompatibilityDecision;
+declare function evaluateArtifactCompatibility(current: ArtifactCompatibilityEnvelope, candidate: ArtifactCompatibilityEnvelope, options?: ArtifactCompatibilityEvaluationOptions): ArtifactCompatibilityDecision;
 //#endregion
-export { APP_ELEMENTS_SCHEMA_VERSION, ARTIFACT_COMPATIBILITY_SCHEMA_VERSION, ArtifactCompatibilityEnvelope, RSC_PAYLOAD_SCHEMA_VERSION, createArtifactCompatibilityEnvelope, createArtifactCompatibilityGraphVersion, evaluateArtifactCompatibility, parseArtifactCompatibilityEnvelope };
+export { APP_ELEMENTS_SCHEMA_VERSION, ARTIFACT_COMPATIBILITY_SCHEMA_VERSION, ArtifactCompatibilityEnvelope, ArtifactCompatibilityEvaluationOptions, ArtifactCompatibilityMap, ArtifactCompatibilitySet, RSC_PAYLOAD_SCHEMA_VERSION, createArtifactCompatibilityEnvelope, createArtifactCompatibilityGraphVersion, evaluateArtifactCompatibility, parseArtifactCompatibilityEnvelope };
 //# sourceMappingURL=artifact-compatibility.d.ts.map

package/dist/server/artifact-compatibility.js

@@ -57,22 +57,26 @@ function unknown(reason) {
 		reason
 	};
 }
-function compareKnownField(currentValue, candidateValue, unknownReason, mismatchReason) {
+function compareKnownField(currentValue, candidateValue, unknownReason, mismatchReason, notDeclaredCompatibleReason, compatibilitySets) {
 	if (currentValue === null || candidateValue === null) return unknown(unknownReason);
-	if (currentValue !== candidateValue) return incompatible(mismatchReason);
-	return null;
+	if (currentValue === candidateValue) return null;
+	if (compatibilitySets === void 0) return incompatible(mismatchReason);
+	return isDeclaredCompatible(currentValue, candidateValue, compatibilitySets) ? null : incompatible(notDeclaredCompatibleReason);
 }
-function evaluateArtifactCompatibility(current, candidate) {
+function isDeclaredCompatible(currentValue, candidateValue, compatibilitySets) {
+	return compatibilitySets.some((compatibilitySet) => compatibilitySet.includes(currentValue) && compatibilitySet.includes(candidateValue));
+}
+function evaluateArtifactCompatibility(current, candidate, options = {}) {
 	if (current.schemaVersion !== candidate.schemaVersion) return incompatible("schemaVersionMismatch");
 	if (current.appElementsSchemaVersion !== candidate.appElementsSchemaVersion) return incompatible("appElementsSchemaVersionMismatch");
 	if (current.rscPayloadSchemaVersion !== candidate.rscPayloadSchemaVersion) return incompatible("rscPayloadSchemaVersionMismatch");
-	const graphDecision = compareKnownField(current.graphVersion, candidate.graphVersion, "graphVersionUnknown", "graphVersionMismatch");
+	const graphDecision = compareKnownField(current.graphVersion, candidate.graphVersion, "graphVersionUnknown", "graphVersionMismatch", "graphVersionNotDeclaredCompatible", options.compatibilityMap?.graphVersions);
 	if (graphDecision) return graphDecision;
-	const deploymentDecision = compareKnownField(current.deploymentVersion, candidate.deploymentVersion, "deploymentVersionUnknown", "deploymentVersionMismatch");
+	const deploymentDecision = compareKnownField(current.deploymentVersion, candidate.deploymentVersion, "deploymentVersionUnknown", "deploymentVersionMismatch", "deploymentVersionNotDeclaredCompatible", options.compatibilityMap?.deploymentVersions);
 	if (deploymentDecision) return deploymentDecision;
-	const rootBoundaryDecision = compareKnownField(current.rootBoundaryId, candidate.rootBoundaryId, "rootBoundaryIdUnknown", "rootBoundaryIdMismatch");
+	const rootBoundaryDecision = compareKnownField(current.rootBoundaryId, candidate.rootBoundaryId, "rootBoundaryIdUnknown", "rootBoundaryIdMismatch", "rootBoundaryIdNotDeclaredCompatible", options.compatibilityMap?.rootBoundaryIds);
 	if (rootBoundaryDecision) return rootBoundaryDecision;
-	const renderEpochDecision = compareKnownField(current.renderEpoch, candidate.renderEpoch, "renderEpochUnknown", "renderEpochMismatch");
+	const renderEpochDecision = compareKnownField(current.renderEpoch, candidate.renderEpoch, "renderEpochUnknown", "renderEpochMismatch", "renderEpochNotDeclaredCompatible", options.compatibilityMap?.renderEpochs);
 	if (renderEpochDecision) return renderEpochDecision;
 	return { kind: "compatible" };
 }

package/dist/server/artifact-compatibility.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-compatibility.js","names":[],"sources":["../../src/server/artifact-compatibility.ts"],"sourcesContent":["import { fnv1a64 } from \"../utils/hash.js\";\n\nexport const ARTIFACT_COMPATIBILITY_SCHEMA_VERSION = 1;\n\n// These versions describe separate protocol layers. For example, a future\n// rolling deploy can bump the flat AppElements row shape while keeping the\n// envelope object and serialized RSC transport version stable.\nexport const APP_ELEMENTS_SCHEMA_VERSION = 1;\nexport const RSC_PAYLOAD_SCHEMA_VERSION = 1;\n\nexport type ArtifactCompatibilityEnvelope = Readonly<{\n  schemaVersion: typeof ARTIFACT_COMPATIBILITY_SCHEMA_VERSION;\n  graphVersion: string | null;\n  deploymentVersion: string | null;\n  appElementsSchemaVersion: typeof APP_ELEMENTS_SCHEMA_VERSION;\n  rscPayloadSchemaVersion: typeof RSC_PAYLOAD_SCHEMA_VERSION;\n  rootBoundaryId: string | null;\n  renderEpoch: string | null;\n}>;\n\ntype ArtifactCompatibilityEnvelopeInput = Readonly<{\n  graphVersion?: string | null;\n  deploymentVersion?: string | null;\n  rootBoundaryId?: string | null;\n  renderEpoch?: string | null;\n}>;\n\ntype ArtifactCompatibilityFallback = \"renderFresh\";\n\ntype ArtifactCompatibilityUnknownReason =\n  | \"graphVersionUnknown\"\n  | \"deploymentVersionUnknown\"\n  | \"rootBoundaryIdUnknown\"\n  | \"renderEpochUnknown\";\n\ntype ArtifactCompatibilityIncompatibleReason =\n  | \"appElementsSchemaVersionMismatch\"\n  | \"deploymentVersionMismatch\"\n  | \"graphVersionMismatch\"\n  | \"renderEpochMismatch\"\n  | \"rootBoundaryIdMismatch\"\n  | \"rscPayloadSchemaVersionMismatch\"\n  | \"schemaVersionMismatch\";\n\ntype ArtifactCompatibilityDecision = Readonly<\n  | { kind: \"compatible\" }\n  | {\n      kind: \"unknown\";\n      fallback: ArtifactCompatibilityFallback;\n      reason: ArtifactCompatibilityUnknownReason;\n    }\n  | {\n      kind: \"incompatible\";\n      fallback: ArtifactCompatibilityFallback;\n      reason: ArtifactCompatibilityIncompatibleReason;\n    }\n>;\n\ntype ArtifactCompatibilityGraphVersionInput = Readonly<{\n  routePattern: string;\n  rootBoundaryId: string | null;\n}>;\n\nexport function createArtifactCompatibilityEnvelope(\n  input: ArtifactCompatibilityEnvelopeInput = {},\n): ArtifactCompatibilityEnvelope {\n  return {\n    schemaVersion: ARTIFACT_COMPATIBILITY_SCHEMA_VERSION,\n    graphVersion: input.graphVersion ?? null,\n    deploymentVersion: input.deploymentVersion ?? null,\n    appElementsSchemaVersion: APP_ELEMENTS_SCHEMA_VERSION,\n    rscPayloadSchemaVersion: RSC_PAYLOAD_SCHEMA_VERSION,\n    rootBoundaryId: input.rootBoundaryId ?? null,\n    renderEpoch: input.renderEpoch ?? null,\n  };\n}\n\nexport function createArtifactCompatibilityGraphVersion(\n  input: ArtifactCompatibilityGraphVersionInput,\n): string {\n  const fingerprint = fnv1a64(JSON.stringify([input.routePattern, input.rootBoundaryId]));\n  return `app-route-graph:${fingerprint}`;\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isStringOrNull(value: unknown): value is string | null {\n  return typeof value === \"string\" || value === null;\n}\n\nfunction hasCurrentSchemaVersions(record: Readonly<Record<string, unknown>>): boolean {\n  return (\n    record.schemaVersion === ARTIFACT_COMPATIBILITY_SCHEMA_VERSION &&\n    record.appElementsSchemaVersion === APP_ELEMENTS_SCHEMA_VERSION &&\n    record.rscPayloadSchemaVersion === RSC_PAYLOAD_SCHEMA_VERSION\n  );\n}\n\nexport function parseArtifactCompatibilityEnvelope(\n  value: unknown,\n): ArtifactCompatibilityEnvelope | null {\n  if (!isRecord(value)) return null;\n  // The Wave01 skeleton intentionally collapses version mismatch and malformed\n  // metadata into \"not current\". Cache/skip callers must split those cases\n  // before treating unknown compatibility as anything other than a miss/reject.\n  if (!hasCurrentSchemaVersions(value)) return null;\n  if (!isStringOrNull(value.graphVersion)) return null;\n  if (!isStringOrNull(value.deploymentVersion)) return null;\n  if (!isStringOrNull(value.rootBoundaryId)) return null;\n  if (!isStringOrNull(value.renderEpoch)) return null;\n\n  // This parser intentionally returns a normalized current-version proof. A\n  // future-compatible reader should introduce a separate parsed type instead of\n  // widening this Wave01 envelope after the current-version checks above.\n  return {\n    schemaVersion: ARTIFACT_COMPATIBILITY_SCHEMA_VERSION,\n    graphVersion: value.graphVersion,\n    deploymentVersion: value.deploymentVersion,\n    appElementsSchemaVersion: APP_ELEMENTS_SCHEMA_VERSION,\n    rscPayloadSchemaVersion: RSC_PAYLOAD_SCHEMA_VERSION,\n    rootBoundaryId: value.rootBoundaryId,\n    renderEpoch: value.renderEpoch,\n  };\n}\n\nfunction incompatible(\n  reason: ArtifactCompatibilityIncompatibleReason,\n): ArtifactCompatibilityDecision {\n  return { kind: \"incompatible\", fallback: \"renderFresh\", reason };\n}\n\nfunction unknown(reason: ArtifactCompatibilityUnknownReason): ArtifactCompatibilityDecision {\n  return { kind: \"unknown\", fallback: \"renderFresh\", reason };\n}\n\nfunction compareKnownField(\n  currentValue: string | null,\n  candidateValue: string | null,\n  unknownReason: ArtifactCompatibilityUnknownReason,\n  mismatchReason: ArtifactCompatibilityIncompatibleReason,\n): ArtifactCompatibilityDecision | null {\n  if (currentValue === null || candidateValue === null) {\n    return unknown(unknownReason);\n  }\n  if (currentValue !== candidateValue) {\n    return incompatible(mismatchReason);\n  }\n  return null;\n}\n\nexport function evaluateArtifactCompatibility(\n  current: ArtifactCompatibilityEnvelope,\n  candidate: ArtifactCompatibilityEnvelope,\n): ArtifactCompatibilityDecision {\n  // Pre-positioned for #726-COMPAT-04/05, where cache and visited-response\n  // reuse paths will compare the current render proof with a candidate payload.\n  if (current.schemaVersion !== candidate.schemaVersion) {\n    return incompatible(\"schemaVersionMismatch\");\n  }\n  if (current.appElementsSchemaVersion !== candidate.appElementsSchemaVersion) {\n    return incompatible(\"appElementsSchemaVersionMismatch\");\n  }\n  if (current.rscPayloadSchemaVersion !== candidate.rscPayloadSchemaVersion) {\n    return incompatible(\"rscPayloadSchemaVersionMismatch\");\n  }\n\n  const graphDecision = compareKnownField(\n    current.graphVersion,\n    candidate.graphVersion,\n    \"graphVersionUnknown\",\n    \"graphVersionMismatch\",\n  );\n  if (graphDecision) return graphDecision;\n\n  const deploymentDecision = compareKnownField(\n    current.deploymentVersion,\n    candidate.deploymentVersion,\n    \"deploymentVersionUnknown\",\n    \"deploymentVersionMismatch\",\n  );\n  if (deploymentDecision) return deploymentDecision;\n\n  const rootBoundaryDecision = compareKnownField(\n    current.rootBoundaryId,\n    candidate.rootBoundaryId,\n    \"rootBoundaryIdUnknown\",\n    \"rootBoundaryIdMismatch\",\n  );\n  if (rootBoundaryDecision) return rootBoundaryDecision;\n\n  const renderEpochDecision = compareKnownField(\n    current.renderEpoch,\n    candidate.renderEpoch,\n    \"renderEpochUnknown\",\n    \"renderEpochMismatch\",\n  );\n  if (renderEpochDecision) return renderEpochDecision;\n\n  return { kind: \"compatible\" };\n}\n"],"mappings":";;AAEA,MAAa,wCAAwC;AAKrD,MAAa,8BAA8B;AAC3C,MAAa,6BAA6B;AAuD1C,SAAgB,oCACd,QAA4C,EAAE,EACf;CAC/B,OAAO;EACL,eAAA;EACA,cAAc,MAAM,gBAAgB;EACpC,mBAAmB,MAAM,qBAAqB;EAC9C,0BAAA;EACA,yBAAA;EACA,gBAAgB,MAAM,kBAAkB;EACxC,aAAa,MAAM,eAAe;EACnC;;AAGH,SAAgB,wCACd,OACQ;CAER,OAAO,mBADa,QAAQ,KAAK,UAAU,CAAC,MAAM,cAAc,MAAM,eAAe,CAAC,CACjD;;AAGvC,SAAS,SAAS,OAA4D;CAC5E,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,MAAM;;AAG7E,SAAS,eAAe,OAAwC;CAC9D,OAAO,OAAO,UAAU,YAAY,UAAU;;AAGhD,SAAS,yBAAyB,QAAoD;CACpF,OACE,OAAO,kBAAA,KACP,OAAO,6BAAA,KACP,OAAO,4BAAA;;AAIX,SAAgB,mCACd,OACsC;CACtC,IAAI,CAAC,SAAS,MAAM,EAAE,OAAO;CAI7B,IAAI,CAAC,yBAAyB,MAAM,EAAE,OAAO;CAC7C,IAAI,CAAC,eAAe,MAAM,aAAa,EAAE,OAAO;CAChD,IAAI,CAAC,eAAe,MAAM,kBAAkB,EAAE,OAAO;CACrD,IAAI,CAAC,eAAe,MAAM,eAAe,EAAE,OAAO;CAClD,IAAI,CAAC,eAAe,MAAM,YAAY,EAAE,OAAO;CAK/C,OAAO;EACL,eAAA;EACA,cAAc,MAAM;EACpB,mBAAmB,MAAM;EACzB,0BAAA;EACA,yBAAA;EACA,gBAAgB,MAAM;EACtB,aAAa,MAAM;EACpB;;AAGH,SAAS,aACP,QAC+B;CAC/B,OAAO;EAAE,MAAM;EAAgB,UAAU;EAAe;EAAQ;;AAGlE,SAAS,QAAQ,QAA2E;CAC1F,OAAO;EAAE,MAAM;EAAW,UAAU;EAAe;EAAQ;;AAG7D,SAAS,kBACP,cACA,gBACA,eACA,gBACsC;CACtC,IAAI,iBAAiB,QAAQ,mBAAmB,MAC9C,OAAO,QAAQ,cAAc;CAE/B,IAAI,iBAAiB,gBACnB,OAAO,aAAa,eAAe;CAErC,OAAO;;AAGT,SAAgB,8BACd,SACA,WAC+B;CAG/B,IAAI,QAAQ,kBAAkB,UAAU,eACtC,OAAO,aAAa,wBAAwB;CAE9C,IAAI,QAAQ,6BAA6B,UAAU,0BACjD,OAAO,aAAa,mCAAmC;CAEzD,IAAI,QAAQ,4BAA4B,UAAU,yBAChD,OAAO,aAAa,kCAAkC;CAGxD,MAAM,gBAAgB,kBACpB,QAAQ,cACR,UAAU,cACV,uBACA,uBACD;CACD,IAAI,eAAe,OAAO;CAE1B,MAAM,qBAAqB,kBACzB,QAAQ,mBACR,UAAU,mBACV,4BACA,4BACD;CACD,IAAI,oBAAoB,OAAO;CAE/B,MAAM,uBAAuB,kBAC3B,QAAQ,gBACR,UAAU,gBACV,yBACA,yBACD;CACD,IAAI,sBAAsB,OAAO;CAEjC,MAAM,sBAAsB,kBAC1B,QAAQ,aACR,UAAU,aACV,sBACA,sBACD;CACD,IAAI,qBAAqB,OAAO;CAEhC,OAAO,EAAE,MAAM,cAAc"}
+{"version":3,"file":"artifact-compatibility.js","names":[],"sources":["../../src/server/artifact-compatibility.ts"],"sourcesContent":["import { fnv1a64 } from \"../utils/hash.js\";\n\nexport const ARTIFACT_COMPATIBILITY_SCHEMA_VERSION = 1;\n\n// These versions describe separate protocol layers. For example, a future\n// rolling deploy can bump the flat AppElements row shape while keeping the\n// envelope object and serialized RSC transport version stable.\nexport const APP_ELEMENTS_SCHEMA_VERSION = 1;\nexport const RSC_PAYLOAD_SCHEMA_VERSION = 1;\n\nexport type ArtifactCompatibilityEnvelope = Readonly<{\n  schemaVersion: typeof ARTIFACT_COMPATIBILITY_SCHEMA_VERSION;\n  graphVersion: string | null;\n  deploymentVersion: string | null;\n  appElementsSchemaVersion: typeof APP_ELEMENTS_SCHEMA_VERSION;\n  rscPayloadSchemaVersion: typeof RSC_PAYLOAD_SCHEMA_VERSION;\n  rootBoundaryId: string | null;\n  renderEpoch: string | null;\n}>;\n\ntype ArtifactCompatibilityEnvelopeInput = Readonly<{\n  graphVersion?: string | null;\n  deploymentVersion?: string | null;\n  rootBoundaryId?: string | null;\n  renderEpoch?: string | null;\n}>;\n\nexport type ArtifactCompatibilitySet = readonly [string, string, ...string[]];\n\nexport type ArtifactCompatibilityMap = Readonly<{\n  graphVersions?: readonly ArtifactCompatibilitySet[];\n  deploymentVersions?: readonly ArtifactCompatibilitySet[];\n  rootBoundaryIds?: readonly ArtifactCompatibilitySet[];\n  renderEpochs?: readonly ArtifactCompatibilitySet[];\n}>;\n\nexport type ArtifactCompatibilityEvaluationOptions = Readonly<{\n  compatibilityMap?: ArtifactCompatibilityMap;\n}>;\n\ntype ArtifactCompatibilityFallback = \"renderFresh\";\n\ntype ArtifactCompatibilityUnknownReason =\n  | \"graphVersionUnknown\"\n  | \"deploymentVersionUnknown\"\n  | \"rootBoundaryIdUnknown\"\n  | \"renderEpochUnknown\";\n\ntype ArtifactCompatibilityIncompatibleReason =\n  | \"appElementsSchemaVersionMismatch\"\n  | \"deploymentVersionNotDeclaredCompatible\"\n  | \"deploymentVersionMismatch\"\n  | \"graphVersionNotDeclaredCompatible\"\n  | \"graphVersionMismatch\"\n  | \"renderEpochNotDeclaredCompatible\"\n  | \"renderEpochMismatch\"\n  | \"rootBoundaryIdNotDeclaredCompatible\"\n  | \"rootBoundaryIdMismatch\"\n  | \"rscPayloadSchemaVersionMismatch\"\n  | \"schemaVersionMismatch\";\n\ntype ArtifactCompatibilityDecision = Readonly<\n  | { kind: \"compatible\" }\n  | {\n      kind: \"unknown\";\n      fallback: ArtifactCompatibilityFallback;\n      reason: ArtifactCompatibilityUnknownReason;\n    }\n  | {\n      kind: \"incompatible\";\n      fallback: ArtifactCompatibilityFallback;\n      reason: ArtifactCompatibilityIncompatibleReason;\n    }\n>;\n\ntype ArtifactCompatibilityGraphVersionInput = Readonly<{\n  routePattern: string;\n  rootBoundaryId: string | null;\n}>;\n\nexport function createArtifactCompatibilityEnvelope(\n  input: ArtifactCompatibilityEnvelopeInput = {},\n): ArtifactCompatibilityEnvelope {\n  return {\n    schemaVersion: ARTIFACT_COMPATIBILITY_SCHEMA_VERSION,\n    graphVersion: input.graphVersion ?? null,\n    deploymentVersion: input.deploymentVersion ?? null,\n    appElementsSchemaVersion: APP_ELEMENTS_SCHEMA_VERSION,\n    rscPayloadSchemaVersion: RSC_PAYLOAD_SCHEMA_VERSION,\n    rootBoundaryId: input.rootBoundaryId ?? null,\n    renderEpoch: input.renderEpoch ?? null,\n  };\n}\n\nexport function createArtifactCompatibilityGraphVersion(\n  input: ArtifactCompatibilityGraphVersionInput,\n): string {\n  const fingerprint = fnv1a64(JSON.stringify([input.routePattern, input.rootBoundaryId]));\n  return `app-route-graph:${fingerprint}`;\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isStringOrNull(value: unknown): value is string | null {\n  return typeof value === \"string\" || value === null;\n}\n\nfunction hasCurrentSchemaVersions(record: Readonly<Record<string, unknown>>): boolean {\n  return (\n    record.schemaVersion === ARTIFACT_COMPATIBILITY_SCHEMA_VERSION &&\n    record.appElementsSchemaVersion === APP_ELEMENTS_SCHEMA_VERSION &&\n    record.rscPayloadSchemaVersion === RSC_PAYLOAD_SCHEMA_VERSION\n  );\n}\n\nexport function parseArtifactCompatibilityEnvelope(\n  value: unknown,\n): ArtifactCompatibilityEnvelope | null {\n  if (!isRecord(value)) return null;\n  // The Wave01 skeleton intentionally collapses version mismatch and malformed\n  // metadata into \"not current\". Cache/skip callers must split those cases\n  // before treating unknown compatibility as anything other than a miss/reject.\n  if (!hasCurrentSchemaVersions(value)) return null;\n  if (!isStringOrNull(value.graphVersion)) return null;\n  if (!isStringOrNull(value.deploymentVersion)) return null;\n  if (!isStringOrNull(value.rootBoundaryId)) return null;\n  if (!isStringOrNull(value.renderEpoch)) return null;\n\n  // This parser intentionally returns a normalized current-version proof. A\n  // future-compatible reader should introduce a separate parsed type instead of\n  // widening this Wave01 envelope after the current-version checks above.\n  return {\n    schemaVersion: ARTIFACT_COMPATIBILITY_SCHEMA_VERSION,\n    graphVersion: value.graphVersion,\n    deploymentVersion: value.deploymentVersion,\n    appElementsSchemaVersion: APP_ELEMENTS_SCHEMA_VERSION,\n    rscPayloadSchemaVersion: RSC_PAYLOAD_SCHEMA_VERSION,\n    rootBoundaryId: value.rootBoundaryId,\n    renderEpoch: value.renderEpoch,\n  };\n}\n\nfunction incompatible(\n  reason: ArtifactCompatibilityIncompatibleReason,\n): ArtifactCompatibilityDecision {\n  return { kind: \"incompatible\", fallback: \"renderFresh\", reason };\n}\n\nfunction unknown(reason: ArtifactCompatibilityUnknownReason): ArtifactCompatibilityDecision {\n  return { kind: \"unknown\", fallback: \"renderFresh\", reason };\n}\n\nfunction compareKnownField(\n  currentValue: string | null,\n  candidateValue: string | null,\n  unknownReason: ArtifactCompatibilityUnknownReason,\n  mismatchReason: ArtifactCompatibilityIncompatibleReason,\n  notDeclaredCompatibleReason: ArtifactCompatibilityIncompatibleReason,\n  compatibilitySets: readonly ArtifactCompatibilitySet[] | undefined,\n): ArtifactCompatibilityDecision | null {\n  if (currentValue === null || candidateValue === null) {\n    return unknown(unknownReason);\n  }\n  if (currentValue === candidateValue) {\n    return null;\n  }\n  if (compatibilitySets === undefined) {\n    return incompatible(mismatchReason);\n  }\n  return isDeclaredCompatible(currentValue, candidateValue, compatibilitySets)\n    ? null\n    : incompatible(notDeclaredCompatibleReason);\n}\n\nfunction isDeclaredCompatible(\n  currentValue: string,\n  candidateValue: string,\n  compatibilitySets: readonly ArtifactCompatibilitySet[],\n): boolean {\n  // Compatibility is intentionally scoped to one declared set. Overlapping\n  // pair sets like [a,b] and [b,c] must not silently make a compatible with c.\n  return compatibilitySets.some(\n    (compatibilitySet) =>\n      compatibilitySet.includes(currentValue) && compatibilitySet.includes(candidateValue),\n  );\n}\n\nexport function evaluateArtifactCompatibility(\n  current: ArtifactCompatibilityEnvelope,\n  candidate: ArtifactCompatibilityEnvelope,\n  options: ArtifactCompatibilityEvaluationOptions = {},\n): ArtifactCompatibilityDecision {\n  // This remains a proof evaluator: mismatched fields are compatible only when\n  // the current build's compatibility map explicitly declares that relationship.\n  if (current.schemaVersion !== candidate.schemaVersion) {\n    return incompatible(\"schemaVersionMismatch\");\n  }\n  if (current.appElementsSchemaVersion !== candidate.appElementsSchemaVersion) {\n    return incompatible(\"appElementsSchemaVersionMismatch\");\n  }\n  if (current.rscPayloadSchemaVersion !== candidate.rscPayloadSchemaVersion) {\n    return incompatible(\"rscPayloadSchemaVersionMismatch\");\n  }\n\n  const graphDecision = compareKnownField(\n    current.graphVersion,\n    candidate.graphVersion,\n    \"graphVersionUnknown\",\n    \"graphVersionMismatch\",\n    \"graphVersionNotDeclaredCompatible\",\n    options.compatibilityMap?.graphVersions,\n  );\n  if (graphDecision) return graphDecision;\n\n  const deploymentDecision = compareKnownField(\n    current.deploymentVersion,\n    candidate.deploymentVersion,\n    \"deploymentVersionUnknown\",\n    \"deploymentVersionMismatch\",\n    \"deploymentVersionNotDeclaredCompatible\",\n    options.compatibilityMap?.deploymentVersions,\n  );\n  if (deploymentDecision) return deploymentDecision;\n\n  const rootBoundaryDecision = compareKnownField(\n    current.rootBoundaryId,\n    candidate.rootBoundaryId,\n    \"rootBoundaryIdUnknown\",\n    \"rootBoundaryIdMismatch\",\n    \"rootBoundaryIdNotDeclaredCompatible\",\n    options.compatibilityMap?.rootBoundaryIds,\n  );\n  if (rootBoundaryDecision) return rootBoundaryDecision;\n\n  const renderEpochDecision = compareKnownField(\n    current.renderEpoch,\n    candidate.renderEpoch,\n    \"renderEpochUnknown\",\n    \"renderEpochMismatch\",\n    \"renderEpochNotDeclaredCompatible\",\n    options.compatibilityMap?.renderEpochs,\n  );\n  if (renderEpochDecision) return renderEpochDecision;\n\n  return { kind: \"compatible\" };\n}\n"],"mappings":"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"}

package/dist/server/cache-headers.d.ts

@@ -0,0 +1,7 @@
+//#region src/server/cache-headers.d.ts
+type VinextCacheState = "HIT" | "MISS" | "STALE" | "STATIC";
+declare function setCacheStateHeaders(headers: Headers, cacheState: VinextCacheState): void;
+declare function buildCacheStateHeaders(cacheState: VinextCacheState): Record<string, string>;
+//#endregion
+export { buildCacheStateHeaders, setCacheStateHeaders };
+//# sourceMappingURL=cache-headers.d.ts.map

package/dist/server/cache-headers.js

@@ -0,0 +1,19 @@
+import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER } from "./headers.js";
+//#region src/server/cache-headers.ts
+function toNextJsCacheState(cacheState) {
+	return cacheState === "STATIC" ? "HIT" : cacheState;
+}
+function setCacheStateHeaders(headers, cacheState) {
+	headers.set(VINEXT_CACHE_HEADER, cacheState);
+	headers.set(NEXTJS_CACHE_HEADER, toNextJsCacheState(cacheState));
+}
+function buildCacheStateHeaders(cacheState) {
+	return {
+		[VINEXT_CACHE_HEADER]: cacheState,
+		[NEXTJS_CACHE_HEADER]: toNextJsCacheState(cacheState)
+	};
+}
+//#endregion
+export { buildCacheStateHeaders, setCacheStateHeaders };
+
+//# sourceMappingURL=cache-headers.js.map

package/dist/server/cache-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-headers.js","names":[],"sources":["../../src/server/cache-headers.ts"],"sourcesContent":["import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER } from \"./headers.js\";\n\ntype VinextCacheState = \"HIT\" | \"MISS\" | \"STALE\" | \"STATIC\";\ntype NextJsCacheState = \"HIT\" | \"MISS\" | \"STALE\";\n\nfunction toNextJsCacheState(cacheState: VinextCacheState): NextJsCacheState {\n  return cacheState === \"STATIC\" ? \"HIT\" : cacheState;\n}\n\nexport function setCacheStateHeaders(headers: Headers, cacheState: VinextCacheState): void {\n  headers.set(VINEXT_CACHE_HEADER, cacheState);\n  headers.set(NEXTJS_CACHE_HEADER, toNextJsCacheState(cacheState));\n}\n\nexport function buildCacheStateHeaders(cacheState: VinextCacheState): Record<string, string> {\n  return {\n    [VINEXT_CACHE_HEADER]: cacheState,\n    [NEXTJS_CACHE_HEADER]: toNextJsCacheState(cacheState),\n  };\n}\n"],"mappings":";;AAKA,SAAS,mBAAmB,YAAgD;CAC1E,OAAO,eAAe,WAAW,QAAQ;;AAG3C,SAAgB,qBAAqB,SAAkB,YAAoC;CACzF,QAAQ,IAAI,qBAAqB,WAAW;CAC5C,QAAQ,IAAI,qBAAqB,mBAAmB,WAAW,CAAC;;AAGlE,SAAgB,uBAAuB,YAAsD;CAC3F,OAAO;GACJ,sBAAsB;GACtB,sBAAsB,mBAAmB,WAAW;EACtD"}

package/dist/server/cache-proof.d.ts

@@ -1,9 +1,12 @@
 import { AppRouteSemanticIds } from "../routing/app-route-graph.js";
+import { ArtifactCompatibilityEnvelope, ArtifactCompatibilityEvaluationOptions } from "./artifact-compatibility.js";
 
 //#region src/server/cache-proof.d.ts
-declare const CACHE_PROOF_MODEL_SCHEMA_VERSION = 0;
-type CacheProofModelSchemaVersion = 0;
-type CacheProofRejectionCode = "CP_MODEL_DISABLED" | "CP_DIMENSION_COUNT_EXCEEDED" | "CP_DIMENSION_NAME_MISSING" | "CP_DIMENSION_NAME_TOO_LONG" | "CP_DIMENSION_VALUE_COUNT_EXCEEDED" | "CP_DIMENSION_VALUE_TOO_LONG" | "CP_DIMENSION_VALUES_MISSING" | "CP_ENCODED_VARIANT_TOO_LONG" | "CP_INVALID_VARIANT_BUDGET" | "CP_ROUTE_VARIANT_CEILING_EXCEEDED" | "CP_UNSAFE_PUBLIC_DIMENSION" | "CP_BOUNDARY_OUTCOME_MISMATCH" | "CP_BOUNDARY_OUTCOME_UNKNOWN";
+declare const CACHE_PROOF_MODEL_SCHEMA_VERSION = 1;
+type CacheProofModelSchemaVersion = 1;
+type CacheProofRejectionCode = "CP_CACHE_ENTRY_PROOF_MISSING" | "CP_MODEL_DISABLED" | "CP_ARTIFACT_COMPATIBILITY_INCOMPATIBLE" | "CP_ARTIFACT_COMPATIBILITY_UNKNOWN" | "CP_DIMENSION_COUNT_EXCEEDED" | "CP_DIMENSION_NAME_MISSING" | "CP_DIMENSION_NAME_TOO_LONG" | "CP_DIMENSION_VALUE_COUNT_EXCEEDED" | "CP_DIMENSION_VALUE_TOO_LONG" | "CP_DIMENSION_VALUES_MISSING" | "CP_ENCODED_VARIANT_TOO_LONG" | "CP_INVALID_VARIANT_BUDGET" | "CP_ROUTE_VARIANT_BUDGET_ROUTE_MISMATCH" | "CP_ROUTE_VARIANT_CEILING_EXCEEDED" | "CP_UNSAFE_PUBLIC_DIMENSION" | "CP_BOUNDARY_OUTCOME_MISMATCH" | "CP_BOUNDARY_OUTCOME_UNKNOWN" | "CP_PRIVATE_DYNAMIC_DOWNGRADE" | "CP_STATIC_LAYOUT_CANDIDATE_OUTPUT_KIND" | "CP_STATIC_LAYOUT_CURRENT_OUTPUT_KIND" | "CP_STATIC_LAYOUT_ID_MISMATCH" | "CP_STATIC_LAYOUT_OBSERVATION_OUTPUT_KIND" | "CP_STATIC_LAYOUT_OBSERVATION_OUTPUT_MISMATCH" | "CP_STATIC_LAYOUT_PRIVATE_DYNAMIC_DOWNGRADE" | "CP_STATIC_LAYOUT_REQUEST_API_OBSERVED" | "CP_STATIC_LAYOUT_REQUEST_API_UNKNOWN" | "CP_STATIC_LAYOUT_ROOT_BOUNDARY_MISMATCH" | "CP_STATIC_LAYOUT_ROOT_BOUNDARY_UNKNOWN" | "CP_STATIC_LAYOUT_VARIANT_DIMENSION_UNPROVEN";
+type CacheProofAcceptanceCode = "CP_STATIC_LAYOUT_REUSE_PROVEN";
+type CacheProofTraceCode = CacheProofAcceptanceCode | CacheProofRejectionCode;
 type CacheProofTraceFieldValue = string | number | boolean | null | readonly string[];
 type CacheProofTraceFields = Readonly<Record<string, CacheProofTraceFieldValue>>;
 type CacheProofBreakerFallbackMode = "renderFresh" | "privateUncacheable";
@@ -83,6 +86,9 @@ type CacheProofOutputScope = Readonly<{
   routeId: string;
   templateId: string;
 }>;
+type StaticLayoutCacheProofOutputScope = Extract<CacheProofOutputScope, {
+  kind: "layout";
+}>;
 type CacheVariant = Readonly<{
   budget: CacheVariantBudget;
   cacheKey: string;
@@ -94,7 +100,6 @@ type CacheVariant = Readonly<{
 type BuildCacheVariantInput = Readonly<{
   budget: CacheVariantBudget;
   dimensions: readonly CacheVariantDimensionInput[];
-  existingVariantCount: number;
   output: CacheProofOutputScope;
 }>;
 type BuildCacheVariantResult = Readonly<{
@@ -104,6 +109,24 @@ type BuildCacheVariantResult = Readonly<{
   kind: "breakerFallback";
   fallback: CacheProofBreakerFallback;
 }>;
+type CacheVariantRouteBudget = Readonly<{
+  routeId: string;
+  variantCacheKeys: readonly string[];
+}>;
+type CacheVariantRouteBudgetAdmission = Readonly<{
+  didConsumeRouteVariantBudget: boolean;
+  kind: "variant";
+  routeBudget: CacheVariantRouteBudget;
+  variant: CacheVariant;
+}> | Readonly<{
+  fallback: CacheProofBreakerFallback;
+  kind: "breakerFallback";
+  routeBudget: CacheVariantRouteBudget | null;
+}>;
+type BuildCacheVariantWithRouteBudgetInput = BuildCacheVariantInput & Readonly<{
+  routeBudget: CacheVariantRouteBudget | null;
+}>;
+type BuildCacheVariantWithRouteBudgetResult = CacheVariantRouteBudgetAdmission;
 type AppRouteCacheProofGraphScopeInput = Readonly<{
   ids: AppRouteSemanticIds;
 }>;
@@ -150,21 +173,146 @@ type RenderObservationCompleteness = "complete" | "partial" | "unknown";
 type RenderCacheability = "private" | "public" | "uncacheable" | "unknown";
 type RenderRequestApiKind = "connection" | "cookies" | "draftMode" | "headers" | "params" | "searchParams";
 type RenderRequestApiStatus = "notObserved" | "observed" | "unknown";
+declare const ALL_RENDER_REQUEST_API_KINDS: readonly RenderRequestApiKind[];
 type RenderRequestApiObservation = Readonly<{
   kind: RenderRequestApiKind;
   status: RenderRequestApiStatus;
 }>;
+type CacheProofDowngradeTarget = "freshRender" | "private" | "privateUncacheable" | "public" | "publicVariant";
+type CacheProofDowngradeReason = Readonly<{
+  code: "CP_DOWNGRADE_CACHEABILITY_PRIVATE";
+  target: "private";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_CACHEABILITY_UNCACHEABLE";
+  target: "privateUncacheable";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_CACHEABILITY_UNKNOWN";
+  target: "freshRender";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_DYNAMIC_FETCH";
+  dynamicFetchCount: number;
+  target: "freshRender";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_DYNAMIC_REQUEST_API";
+  requestApi: "connection";
+  target: "freshRender";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_DRAFT_MODE";
+  requestApi: "draftMode";
+  target: "privateUncacheable";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_INCOMPLETE_OBSERVATION";
+  completeness: Exclude<RenderObservationCompleteness, "complete">;
+  target: "freshRender";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_PRIVATE_DIMENSION";
+  inputClass: "auth" | "draft" | "private" | "session";
+  source: "auth" | "cookie" | "draft-mode" | "header" | "session";
+  target: "private" | "privateUncacheable";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_PRIVATE_REQUEST_API";
+  requestApi: "cookies" | "headers";
+  target: "private";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_PUBLIC_REQUEST_API";
+  requestApi: "params" | "searchParams";
+  target: "publicVariant";
+}> | Readonly<{
+  code: "CP_DOWNGRADE_UNKNOWN_REQUEST_API";
+  requestApi: RenderRequestApiKind;
+  target: "freshRender";
+}>;
+type CacheProofDowngradeClassification = Readonly<{
+  fallback: CacheProofBreakerFallback | null;
+  isPublicCacheCandidate: boolean;
+  reasons: readonly CacheProofDowngradeReason[];
+  target: CacheProofDowngradeTarget;
+}>;
+type ClassifyRenderObservationDowngradeInput = Readonly<{
+  cacheability: RenderCacheability;
+  completeness: RenderObservationCompleteness;
+  dynamicFetches: readonly string[];
+  requestApis: readonly RenderRequestApiObservation[];
+}>;
+type ClassifyCacheVariantDimensionDowngradeInput = Pick<CacheVariantDimensionInput, "source">;
 type RenderObservation = Readonly<{
   boundaryOutcome: BoundaryOutcome;
   cacheTags: readonly string[];
   cacheability: RenderCacheability;
   completeness: RenderObservationCompleteness;
+  downgrade: CacheProofDowngradeClassification;
   dynamicFetches: readonly string[];
   output: CacheProofOutputScope;
   pathTags: readonly string[];
   requestApis: readonly RenderRequestApiObservation[];
   schemaVersion: CacheProofModelSchemaVersion;
 }>;
+type StaticLayoutReuseProof = Readonly<{
+  authorizesRuntimeReuse: true;
+  candidateOutput: StaticLayoutCacheProofOutputScope;
+  code: "CP_STATIC_LAYOUT_REUSE_PROVEN";
+  currentOutput: StaticLayoutCacheProofOutputScope;
+  fields: CacheProofTraceFields;
+  observation: RenderObservation;
+  requiredNegativeRequestApis: readonly RenderRequestApiKind[];
+  reuseClass: "static-layout";
+  variant: CacheVariant;
+}>;
+type StaticLayoutArtifactReuseProof = StaticLayoutReuseProof & Readonly<{
+  candidateArtifactCompatibility: ArtifactCompatibilityEnvelope;
+}>;
+type BuildStaticLayoutReuseProofInput = Readonly<{
+  candidateObservation: RenderObservation;
+  candidateVariant: CacheVariant;
+  currentOutput: CacheProofOutputScope;
+}>;
+type BuildStaticLayoutReuseProofResult = Readonly<{
+  kind: "proof";
+  proof: StaticLayoutReuseProof;
+}> | Readonly<{
+  kind: "rejected";
+  fallback: CacheProofBreakerFallback;
+}>;
+type CacheProofHotPathMetric = Readonly<{
+  code: CacheProofTraceCode;
+  fields: CacheProofTraceFields;
+  name: "vinext.cache.static_layout_artifact_reuse";
+  outcome: "fallback" | "reuse";
+}>;
+type StaticLayoutArtifactReuseDecision = Readonly<{
+  canReuse: true;
+  kind: "reuse";
+  metric: CacheProofHotPathMetric;
+  proof: StaticLayoutArtifactReuseProof;
+}> | Readonly<{
+  canReuse: false;
+  fallback: CacheProofBreakerFallback;
+  kind: "fallback";
+  metric: CacheProofHotPathMetric;
+}>;
+type CacheEntryReuseDecision = Readonly<{
+  canReuse: true;
+  code: CacheProofAcceptanceCode;
+  kind: "reuse";
+  reuseClass: StaticLayoutReuseProof["reuseClass"];
+}> | Readonly<{
+  canReuse: false;
+  code: CacheProofRejectionCode;
+  kind: "reject";
+  mode: CacheProofBreakerFallbackMode;
+  scope: CacheProofFallbackScope;
+}>;
+type CacheEntryReuseProof = Readonly<{
+  decision: CacheEntryReuseDecision | null;
+  kind: "runtime-cache-entry";
+}>;
+type CreateStaticLayoutArtifactReuseDecisionInput = Readonly<{
+  candidateArtifactCompatibility: ArtifactCompatibilityEnvelope;
+  candidateObservation: RenderObservation;
+  candidateVariant: BuildCacheVariantWithRouteBudgetResult;
+  currentArtifactCompatibility: ArtifactCompatibilityEnvelope;
+  currentOutput: CacheProofOutputScope;
+}> & ArtifactCompatibilityEvaluationOptions;
 type BuildRenderObservationInput = Readonly<{
   boundaryOutcome: BoundaryOutcome;
   cacheTags: readonly string[];
@@ -175,26 +323,43 @@ type BuildRenderObservationInput = Readonly<{
   pathTags: readonly string[];
   requestApis: readonly RenderRequestApiObservation[];
 }>;
+type BuildRenderRequestApiObservationsInput = Readonly<{
+  completeness: RenderObservationCompleteness;
+  observed: readonly RenderRequestApiKind[];
+}>;
 type DisabledCacheProofDecision = Readonly<{
   canReuse: false;
   fallback: CacheProofBreakerFallback;
   kind: "disabled";
   observation: RenderObservation;
+  staticLayoutProof?: StaticLayoutReuseProof;
   variant: CacheVariant;
 }>;
 type CreateDisabledCacheProofDecisionInput = Readonly<{
   observation: RenderObservation;
+  staticLayoutProof?: StaticLayoutReuseProof;
   variant: CacheVariant;
 }>;
 declare function createAppRouteCacheProofGraphScope(route: AppRouteCacheProofGraphScopeInput): AppRouteCacheProofGraphScope;
 declare function buildCacheVariant(input: BuildCacheVariantInput): BuildCacheVariantResult;
+declare function enforceCacheVariantRouteBudget(input: {
+  routeBudget: CacheVariantRouteBudget | null;
+  variant: CacheVariant;
+}): CacheVariantRouteBudgetAdmission;
+declare function buildCacheVariantWithRouteBudget(input: BuildCacheVariantWithRouteBudgetInput): BuildCacheVariantWithRouteBudgetResult;
 declare function buildBoundaryOutcomeCompatibility(input: {
   candidate: BoundaryOutcome;
   expected: BoundaryOutcome;
 }): BoundaryOutcomeCompatibility;
+declare function classifyCacheVariantDimensionDowngrade(input: ClassifyCacheVariantDimensionDowngradeInput): CacheProofDowngradeReason | null;
+declare function classifyRenderObservationDowngrade(input: ClassifyRenderObservationDowngradeInput): CacheProofDowngradeClassification;
+declare function buildRenderRequestApiObservations(input: BuildRenderRequestApiObservationsInput): RenderRequestApiObservation[];
 declare function buildRenderObservation(input: BuildRenderObservationInput): RenderObservation;
 declare function hasCompleteNegativeRequestApiProof(observation: RenderObservation, requiredApis: readonly RenderRequestApiKind[]): boolean;
+declare function buildStaticLayoutReuseProof(input: BuildStaticLayoutReuseProofInput): BuildStaticLayoutReuseProofResult;
+declare function createStaticLayoutArtifactReuseDecision(input: CreateStaticLayoutArtifactReuseDecisionInput): StaticLayoutArtifactReuseDecision;
+declare function createCacheEntryReuseProof(decision: StaticLayoutArtifactReuseDecision | null): CacheEntryReuseProof;
 declare function createDisabledCacheProofDecision(input: CreateDisabledCacheProofDecisionInput): DisabledCacheProofDecision;
 //#endregion
-export { AppRouteCacheProofGraphScope, AppRouteCacheProofGraphScopeInput, BoundaryOutcome, BoundaryOutcomeCompatibility, BuildCacheVariantInput, BuildCacheVariantResult, BuildRenderObservationInput, CACHE_PROOF_MODEL_SCHEMA_VERSION, CacheProofBreakerFallback, CacheProofBreakerFallbackMode, CacheProofFallbackScope, CacheProofModelSchemaVersion, CacheProofOutputScope, CacheProofRejectionCode, CacheProofTraceFieldValue, CacheProofTraceFields, CacheVariant, CacheVariantBudget, CacheVariantDimension, CacheVariantDimensionInput, CacheVariantDimensionPrivacy, CacheVariantDimensionSource, CreateDisabledCacheProofDecisionInput, DEFAULT_CACHE_VARIANT_BUDGET, DisabledCacheProofDecision, RenderCacheability, RenderObservation, RenderObservationCompleteness, RenderRequestApiKind, RenderRequestApiObservation, RenderRequestApiStatus, buildBoundaryOutcomeCompatibility, buildCacheVariant, buildRenderObservation, createAppRouteCacheProofGraphScope, createDisabledCacheProofDecision, hasCompleteNegativeRequestApiProof };
+export { ALL_RENDER_REQUEST_API_KINDS, AppRouteCacheProofGraphScope, AppRouteCacheProofGraphScopeInput, BoundaryOutcome, BoundaryOutcomeCompatibility, BuildCacheVariantInput, BuildCacheVariantResult, BuildCacheVariantWithRouteBudgetInput, BuildCacheVariantWithRouteBudgetResult, BuildRenderObservationInput, BuildRenderRequestApiObservationsInput, BuildStaticLayoutReuseProofInput, BuildStaticLayoutReuseProofResult, CACHE_PROOF_MODEL_SCHEMA_VERSION, CacheEntryReuseDecision, CacheEntryReuseProof, CacheProofAcceptanceCode, CacheProofBreakerFallback, CacheProofBreakerFallbackMode, CacheProofDowngradeClassification, CacheProofDowngradeReason, CacheProofDowngradeTarget, CacheProofFallbackScope, CacheProofHotPathMetric, CacheProofModelSchemaVersion, CacheProofOutputScope, CacheProofRejectionCode, CacheProofTraceCode, CacheProofTraceFieldValue, CacheProofTraceFields, CacheVariant, CacheVariantBudget, CacheVariantDimension, CacheVariantDimensionInput, CacheVariantDimensionPrivacy, CacheVariantDimensionSource, CacheVariantRouteBudget, CacheVariantRouteBudgetAdmission, ClassifyCacheVariantDimensionDowngradeInput, ClassifyRenderObservationDowngradeInput, CreateDisabledCacheProofDecisionInput, CreateStaticLayoutArtifactReuseDecisionInput, DEFAULT_CACHE_VARIANT_BUDGET, DisabledCacheProofDecision, RenderCacheability, RenderObservation, RenderObservationCompleteness, RenderRequestApiKind, RenderRequestApiObservation, RenderRequestApiStatus, StaticLayoutArtifactReuseDecision, StaticLayoutArtifactReuseProof, StaticLayoutCacheProofOutputScope, StaticLayoutReuseProof, buildBoundaryOutcomeCompatibility, buildCacheVariant, buildCacheVariantWithRouteBudget, buildRenderObservation, buildRenderRequestApiObservations, buildStaticLayoutReuseProof, classifyCacheVariantDimensionDowngrade, classifyRenderObservationDowngrade, createAppRouteCacheProofGraphScope, createCacheEntryReuseProof, createDisabledCacheProofDecision, createStaticLayoutArtifactReuseDecision, enforceCacheVariantRouteBudget, hasCompleteNegativeRequestApiProof };
 //# sourceMappingURL=cache-proof.d.ts.map