vinext 1.0.0-beta.9 → 1.0.1

package/dist/shims/cache-runtime.js

@@ -1,16 +1,19 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { VINEXT_RSC_MARKER_HEADER } from "../server/headers.js";
+import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
+import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from "./cacheability-classification.js";
 import { getDataCacheHandler } from "./cache-handler.js";
 import { suppressHangingPromiseAbortRejections } from "./internal/make-hanging-promise.js";
 import { createPprFallbackShellSuspensePromise, trackPprFallbackShellCacheTask } from "./ppr-fallback-shell.js";
-import { isDraftModeEnabled, markDynamicUsage } from "./headers.js";
-import { _hasPendingRevalidatedTag, _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.js";
+import { markDynamicUsage, throwIfInsideCacheScope } from "./internal/headers-state.js";
+import { isDraftModeEnabled } from "./headers.js";
+import { _registerCacheContextAccessor } from "./internal/cache-context-accessor.js";
+import { _hasPendingRevalidatedTag, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
-import { isMarkedAppPagePropsObject, markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
-import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from "./cacheability-classification.js";
+import { makeThenableParams } from "./thenable-params.js";
+import { APP_PAGE_USE_CACHE_MARKER, hasUseCachePageMarker, isMarkedAppPagePropsObject, isUseCacheFunctionReference, markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
 import { getCurrentRootParams } from "./root-params.js";
-import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 //#region src/shims/cache-runtime.ts
 /**
 * "use cache" runtime
@@ -309,7 +312,8 @@ function propagateRootParamNamesToParent(names) {
 */
 function registerCachedFunction(fn, id, variant, options = {}) {
 	const cacheVariant = variant ?? "";
-	const omitAppPageSearchParamsFromFirstArg = options.appPageDefaultExport === true;
+	const omitAppPageSearchParams = cacheVariant !== "private";
+	const cacheFunctionId = options.serverReferenceId ? JSON.stringify([id, options.serverReferenceId]) : id;
 	const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
 	const cachedFn = (...args) => {
 		if (cacheVariant === "private") {
@@ -346,18 +350,29 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 			const keySeed = getUseCacheKeySeed();
 			const captures = options.decryptCaptures ? await options.decryptCaptures(args[0]) : void 0;
 			const hasCaptureEnvelope = captures !== void 0;
-			const admittedArgs = options.argumentCount === void 0 ? args : hasCaptureEnvelope ? [args[0], ...args.slice(1, 1 + options.argumentCount)] : args.slice(0, options.argumentCount);
+			const pagePropsArgIndex = args.findIndex(hasUseCachePageMarker);
+			const isPageInvocation = pagePropsArgIndex !== -1;
+			const invocationArgs = isPageInvocation ? replaceArgument(args, pagePropsArgIndex, withoutUseCachePageMarker(args[pagePropsArgIndex])) : args;
+			const admittedArgs = options.argumentCount === void 0 ? invocationArgs : hasCaptureEnvelope ? [invocationArgs[0], ...invocationArgs.slice(1, 1 + options.argumentCount)] : invocationArgs.slice(0, options.argumentCount);
 			const executionArgs = hasCaptureEnvelope ? [captures, ...admittedArgs.slice(1)] : admittedArgs;
-			const callArgs = executionArgs;
+			const pagePropsIndex = omitAppPageSearchParams && isPageInvocation ? pagePropsArgIndex : void 0;
+			const callArgs = pagePropsIndex === void 0 ? executionArgs : withErroringPageSearchParams(executionArgs, pagePropsIndex);
 			let cacheKey;
 			try {
-				const processedArgs = executionArgs.length > 0 ? unwrapThenableObjectArray(executionArgs, { omitAppPageSearchParamsFromFirstArg }) : [];
+				const processedArgs = executionArgs.length > 0 ? unwrapThenableObjectArray(executionArgs, {
+					pagePropsIndex,
+					omitMarkedAppPageSearchParams: omitAppPageSearchParams
+				}) : [];
 				if (rsc && executionArgs.length > 0) {
 					const tempRefs = rsc.createClientTemporaryReferenceSet();
-					cacheKey = buildUseCacheKey(id, keySeed, await replyToCacheKey(await rsc.encodeReply(processedArgs, { temporaryReferences: tempRefs })));
-				} else cacheKey = buildUseCacheKey(id, keySeed, processedArgs.length > 0 ? stableStringify(processedArgs) : void 0);
+					const encoded = await rsc.encodeReply(processedArgs, { temporaryReferences: tempRefs });
+					cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, await replyToCacheKey(encoded));
+				} else {
+					const argsKey = processedArgs.length > 0 ? stableStringify(processedArgs) : void 0;
+					cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, argsKey);
+				}
 			} catch {
-				return fn(...callArgs);
+				return (await executeWithContext(fn, callArgs, cacheVariant)).result;
 			}
 			if (cacheVariant === "private") {
 				const privateCache = _getPrivateState()._privateCache;
@@ -415,6 +430,15 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 			propagateCacheTagsToRequest(ctx.tags);
 			const revalidateSeconds = effectiveLife.revalidate ?? cacheLifeProfiles.default.revalidate ?? 900;
 			if (collectedResult?.cacheEntry) try {
+				let cacheFunctionInvocation;
+				if (options.serverReferenceId && options.encodeInvocationArgs) try {
+					cacheFunctionInvocation = {
+						encryptedArgs: await options.encodeInvocationArgs(pagePropsIndex === void 0 ? admittedArgs : toReplayablePageArgs(admittedArgs, pagePropsIndex)),
+						referenceId: options.serverReferenceId,
+						rootParams: Object.fromEntries(Object.entries(rootParams ?? {}).filter((entry) => entry[1] !== void 0)),
+						softTags
+					};
+				} catch {}
 				const serialized = collectedResult.cacheEntry;
 				const cacheValue = {
 					kind: "FETCH",
@@ -429,6 +453,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 				const cacheContext = {
 					fetchCache: true,
 					tags: ctx.tags,
+					...cacheFunctionInvocation ? { cacheFunctionInvocation } : {},
 					cacheControl: {
 						revalidate: revalidateSeconds,
 						expire: effectiveLife.expire,
@@ -470,6 +495,10 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
 /** @internal Symbol carrying transform-derived cached function argument metadata. */
 const USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL = Symbol.for("vinext.useCacheAcceptsSecondArgument");
+/** Whether a loaded server reference is a transformed `"use cache"` function. */
+function isUseCacheFunction(value) {
+	return isUseCacheFunctionReference(value);
+}
 function throwPrivateUseCacheInsidePublicUseCacheError() {
 	const error = /* @__PURE__ */ new Error("\"use cache: private\" must not be used within \"use cache\". It can only be nested inside of another \"use cache: private\".");
 	const ctx = getRequestContext();
@@ -551,11 +580,12 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 		invalidDynamicUsageError: void 0
 	};
 	let collectedResult;
-	const result = await cacheContextStorage.run(ctx, async () => {
+	const workUnitType = variant === "private" ? "private-cache" : "cache";
+	const result = await workUnitAsyncStorage.run({ type: workUnitType }, () => cacheContextStorage.run(ctx, async () => {
 		const value = await fn(...args);
 		if (collectResult) collectedResult = await collectResult(value, ctx);
 		return value;
-	});
+	}));
 	if (ctx.invalidDynamicUsageError) throw ctx.invalidDynamicUsageError;
 	const effectiveLife = resolveCacheLife(ctx.lifeConfigs);
 	if (parentCtx) {
@@ -575,27 +605,79 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 		collectedResult
 	};
 }
-function unwrapThenableObjects(value, options = {}) {
+function unwrapThenableObjects(value, options) {
 	if (value === null || value === void 0 || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map((item) => unwrapThenableObjects(item));
-	if (typeof value.then === "function") {
-		const keys = Object.keys(value);
-		if (keys.length > 0) {
-			const plain = {};
-			for (const key of keys) plain[key] = unwrapThenableObjects(value[key]);
-			return plain;
-		}
-		return value;
+	const childOptions = { omitMarkedAppPageSearchParams: options.omitMarkedAppPageSearchParams };
+	if (Array.isArray(value)) return value.map((item) => unwrapThenableObjects(item, childOptions));
+	if (isThenableObject(value)) {
+		const plain = {};
+		for (const key of Object.keys(value)) plain[key] = unwrapThenableObjects(value[key], childOptions);
+		return plain;
 	}
+	if (typeof value.then === "function") return value;
 	const result = {};
 	for (const key of Object.keys(value)) {
-		if (key === "searchParams" && (options.omitAppPageSearchParamsAtRoot || isMarkedAppPagePropsObject(value))) continue;
-		result[key] = unwrapThenableObjects(value[key]);
+		if (key === "searchParams" && (options.omitAppPageSearchParamsAtRoot || options.omitMarkedAppPageSearchParams && isMarkedAppPagePropsObject(value))) continue;
+		result[key] = unwrapThenableObjects(value[key], childOptions);
 	}
 	return result;
 }
+/**
+* A thenable (not an array) with own enumerable properties — the
+* `Object.assign(Promise.resolve(obj), obj)` pattern Next.js params use. The
+* cache key is built from its fields instead of the promise.
+*/
+function isThenableObject(value) {
+	return !Array.isArray(value) && "then" in value && typeof value.then === "function" && Object.keys(value).length > 0;
+}
+function isPagePropsObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function replaceArgument(args, index, value) {
+	const result = [...args];
+	result[index] = value;
+	return result;
+}
+/** Remove the `$$isPage` invocation marker before props reach the key or user code. */
+function withoutUseCachePageMarker(props) {
+	const { [APP_PAGE_USE_CACHE_MARKER]: _marker, ...pageProps } = props;
+	return isMarkedAppPagePropsObject(props) ? markAppPagePropsForUseCache(pageProps) : pageProps;
+}
+/**
+* Response Store replay args for a public page cache: drop `searchParams` from
+* the page props at `index` (after a capture envelope, if any), as Next.js does
+* for the serialized arguments (use-cache-wrapper.ts, `isPageSegmentFunction`),
+* and keep the `$$isPage` marker so a replay regains page semantics, including
+* the erroring searchParams fallback.
+*/
+function toReplayablePageArgs(args, index) {
+	const props = args[index];
+	if (!isPagePropsObject(props)) return [...args];
+	const { searchParams: _searchParams, ...pageProps } = props;
+	return replaceArgument(args, index, {
+		...pageProps,
+		[APP_PAGE_USE_CACHE_MARKER]: true
+	});
+}
+/**
+* Give page props at `index` without `searchParams` (a Response Store replay of
+* args encoded by `toReplayablePageArgs`) a value that throws on
+* access inside the cache scope, like Next.js's
+* `makeErroringSearchParamsForUseCache`, instead of `undefined`.
+*/
+function withErroringPageSearchParams(args, index) {
+	const props = args[index];
+	if (!isPagePropsObject(props) || "searchParams" in props) return args;
+	return replaceArgument(args, index, {
+		...props,
+		searchParams: makeThenableParams({}, { observeParamAccess: () => throwIfInsideCacheScope("searchParams") })
+	});
+}
 function unwrapThenableObjectArray(values, options) {
-	return values.map((value, index) => unwrapThenableObjects(value, { omitAppPageSearchParamsAtRoot: index === 0 && options.omitAppPageSearchParamsFromFirstArg }));
+	return values.map((value, index) => unwrapThenableObjects(value, {
+		omitAppPageSearchParamsAtRoot: index === options.pagePropsIndex,
+		omitMarkedAppPageSearchParams: options.omitMarkedAppPageSearchParams
+	}));
 }
 function stableStringify(value, seen) {
 	if (value === void 0) return "undefined";
@@ -622,4 +704,4 @@ function stableStringify(value, seen) {
 	return JSON.stringify(value);
 }
 //#endregion
-export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, isThenableObject, isUseCacheFunction, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };

package/dist/shims/cache.d.ts

@@ -1,6 +1,7 @@
 import { ExecutionContextLike, getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
-import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
+import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 //#region src/shims/cache.d.ts
 /**
  * Revalidate cached data associated with a specific cache tag.
@@ -15,7 +16,7 @@ import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerVa
  * @param tag - Cache tag to revalidate
  * @param profile - cacheLife profile name (e.g. 'max', 'hours') or inline { expire: number }
  */
-declare function revalidateTag(tag: string, profile?: string | {
+export declare function revalidateTag(tag: string, profile?: string | {
   expire?: number;
 }): undefined;
 /**
@@ -33,7 +34,7 @@ declare function revalidateTag(tag: string, profile?: string | {
  * The `type` parameter is App Router only — Pages Router does not generate
  * layout/page hierarchy tags, so only no-type invalidation applies there.
  */
-declare function revalidatePath(path: string, type?: "page" | "layout"): undefined;
+export declare function revalidatePath(path: string, type?: "page" | "layout"): undefined;
 /**
  * No-op shim for API compatibility.
  *
@@ -42,7 +43,7 @@ declare function revalidatePath(path: string, type?: "page" | "layout"): undefin
  * vinext reports the dynamic-only invalidation through the Server Action
  * response header that the client router already understands.
  */
-declare function refresh(): void;
+export declare function refresh(): void;
 /**
  * Expire a cache tag immediately (Next.js 16).
  *
@@ -56,7 +57,7 @@ declare function refresh(): void;
  *
  * @see https://nextjs.org/docs/app/api-reference/functions/updateTag
  */
-declare function updateTag(tag: string): undefined;
+export declare function updateTag(tag: string): undefined;
 /**
  * Opt out of static rendering and indicate a particular component should not be cached.
  *
@@ -65,7 +66,7 @@ declare function updateTag(tag: string): undefined;
  * have the same static/dynamic rendering split — all server rendering is on-demand.
  * It's provided for API compatibility so apps importing it don't break.
  */
-declare function unstable_noStore(): void;
+export declare function unstable_noStore(): void;
 /**
  * Marks an IO boundary in server components by returning a resolved promise
  * during requests and a hanging promise during prerendering.
@@ -89,13 +90,13 @@ declare function unstable_noStore(): void;
  * When no work unit store is present (e.g. client-side, standalone script),
  * resolves immediately — matching the browser/client implementation.
  */
-declare function io(): Promise<void>;
+export declare function io(): Promise<void>;
 /**
  * @deprecated Use `io` instead. Kept as a transitional alias since vinext
  * shipped the unstable name longer than upstream Next.js (see #805). Will be
  * removed in a future minor.
  */
-declare function unstable_io(): Promise<void>;
+export declare function unstable_io(): Promise<void>;
 /**
  * Set the cache lifetime for a "use cache" function.
  *
@@ -108,7 +109,7 @@ declare function unstable_io(): Promise<void>;
  *
  * When called outside a "use cache" context, this is a validated no-op.
  */
-declare function cacheLife(profile: string | CacheLifeConfig): void;
+export declare function cacheLife(profile: string | CacheLifeConfig): void;
 /**
  * Tag a "use cache" function's cached result for on-demand revalidation.
  *
@@ -120,15 +121,15 @@ declare function cacheLife(profile: string | CacheLifeConfig): void;
  *
  * When called outside a "use cache" context, this is a no-op.
  */
-declare function cacheTag(...tags: string[]): void;
-declare function unstable_cacheLife(profile: string | CacheLifeConfig): void;
-declare function unstable_cacheTag(...tags: string[]): void;
+export declare function cacheTag(...tags: string[]): void;
+export declare function unstable_cacheLife(profile: string | CacheLifeConfig): void;
+export declare function unstable_cacheTag(...tags: string[]): void;
 /**
  * Check if the current execution context is inside an unstable_cache() callback.
  * Used by headers(), cookies(), and connection() to throw errors when
  * dynamic request APIs are called inside a cache scope.
  */
-declare function isInsideUnstableCacheScope(): boolean;
+export declare function isInsideUnstableCacheScope(): boolean;
 type UnstableCacheOptions = {
   revalidate?: number | false;
   tags?: string[];
@@ -139,6 +140,6 @@ type UnstableCacheOptions = {
  * Returns a new function that caches results. The cache key is derived
  * from keyParts + serialized arguments.
  */
-declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
+export declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, recordUnstableCacheObservation, registerDataCacheHandler, registerLazyDataCacheHandler, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };

package/dist/shims/cache.js

@@ -1,16 +1,18 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope } from "./unified-request-context.js";
 import { getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
-import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
+import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { getCdnCacheAdapter } from "./cdn-cache.js";
+import { isStagedCacheabilityProbeActive } from "./cacheability-classification.js";
 import { fnv1a64 } from "../utils/hash.js";
+import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
-import { getHeadersAccessPhase, isDraftModeEnabled, markDynamicUsage } from "./headers.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { getHeadersAccessPhase, markDynamicUsage } from "./internal/headers-state.js";
+import { isDraftModeEnabled } from "./headers.js";
+import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
-import { isStagedCacheabilityProbeActive } from "./cacheability-classification.js";
-import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 //#region src/shims/cache.ts
 /**
 * next/cache shim
@@ -29,8 +31,7 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 *   vinext({ cache: { data: kvDataAdapter({ binding: 'VINEXT_KV_CACHE' }) } })
 *
 * The imperative `setCacheHandler` / `setDataCacheHandler` setters are
-* deprecated for consumers and retained only as the internal registration
-* target used by the generated cache-adapter module.
+* deprecated for consumers and retained for backwards compatibility.
 */
 const _g = globalThis;
 function scheduleRevalidation(promise) {
@@ -104,7 +105,8 @@ function revalidatePath(path, type) {
 	}
 	markActionRevalidation(1);
 	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
-	const encodedTag = encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`);
+	const tag = type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`;
+	const encodedTag = encodeCacheTag(tag);
 	_markPendingRevalidatedTag(encodedTag);
 	return scheduleRevalidation(_invalidateEncodedTag(encodedTag));
 }
@@ -418,12 +420,14 @@ function unstable_cache(fn, keyParts, options) {
 			});
 			if (existing?.value && existing.value.kind === "FETCH") {
 				const cached = tryDeserializeUnstableCacheResult(existing.value.data.body);
-				if (cached.ok) if (existing.cacheState === "stale") {
-					if (shouldServeStaleUnstableCacheEntry()) {
-						scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds));
-						return cached.value;
-					}
-				} else return cached.value;
+				if (cached.ok) {
+					if (existing.cacheState === "stale") {
+						if (shouldServeStaleUnstableCacheEntry()) {
+							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds));
+							return cached.value;
+						}
+					} else return cached.value;
+				}
 			}
 		}
 		if (isDraftMode) return await _unstableCacheAls.run(true, () => fn(...args));
@@ -432,4 +436,4 @@ function unstable_cache(fn, keyParts, options) {
 	return cachedFn;
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, registerDataCacheHandler, registerLazyDataCacheHandler, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/cacheability-classification.d.ts

@@ -1,16 +1,18 @@
 //#region src/shims/cacheability-classification.d.ts
-declare const CACHEABILITY_REQUEST_STATE: unique symbol;
-declare const CACHEABILITY_POLICY_HEADERS: readonly ["cache-control", "cdn-cache-control", "cloudflare-cdn-cache-control"];
-type CacheabilityPolicyHeader = (typeof CACHEABILITY_POLICY_HEADERS)[number];
-type RouteCacheabilityOutcome = {
+export declare const CACHEABILITY_REQUEST_STATE: unique symbol;
+export type RouteCacheabilityOutcome = {
   cacheControl?: string;
   cacheable: boolean;
   classificationFailure?: boolean;
   dynamicUsage?: boolean;
   reason?: string;
+  /** App pages: the render proved it left searchParams unread, so its response holds for every query. */
+  searchParamsUnread?: true;
+  /** A transient classification failure that may succeed on another bounded attempt. */
+  retryable?: true;
   tags?: readonly string[];
 };
-type RouteCacheabilityState = {
+export type RouteCacheabilityState = {
   admission?: {
     manifest?: unknown;
     policy: "deny" | "manifest" | "runtime";
@@ -26,60 +28,79 @@ type RouteCacheabilityState = {
   captureDeadlineAt: number;
   complete?: (outcome: RouteCacheabilityOutcome) => void;
   completion?: Promise<RouteCacheabilityOutcome>;
+  /** Canonical framework tags most recently handed to the active CDN adapter. */
+  cdnCacheTags?: readonly string[];
+  /** Private marker surrounding this render's injected client trace metadata. */
+  clientTraceMetadataMarker?: string;
   completedResponseBody?: boolean;
+  /** Whether admission must translate a completed response through the active adapter. */
+  applyCompletedResponsePolicy?: boolean;
+  /** Core- or adapter-owned cache policy headers set by next.config, by lowercased name. */
+  configCdnCachePolicy?: Map<string, string>;
   explicitConfigCachePolicy?: boolean;
   explicitResponseCachePolicy?: boolean;
   finalResponseVetoReason?: string;
   forcedDynamicReason?: string;
   /** A route-config decision that applies to every concrete identity for this pattern. */
   patternDynamicReason?: string;
-  frameworkResponseCachePolicy?: Partial<Record<CacheabilityPolicyHeader, string>>;
+  frameworkResponseCachePolicy?: Headers;
   mode: "admit" | "identity" | "probe";
   outcome?: RouteCacheabilityOutcome;
   preserveResponseCachePolicy?: boolean;
+  /** Whether an API request carried credentials that must not enter shared caching. */
+  credentialedRequest?: boolean;
   /** Cache-key behavior declared by the active CDN adapter. */
   responseVary?: "verbatim";
+  /** Concrete pathname resolved by the trusted request stage before rendering. */
+  resolvedRoutePathname?: string;
   probeBailout?: {
     kind: "private-cache";
     outcome: RouteCacheabilityOutcome;
   };
   route?: {
-    kind: "app-page" | "app-route" | "pages-page";
+    kind: "app-page" | "app-route" | "pages-api" | "pages-page";
     pattern: string;
   };
 };
+/** Retain canonical tags across completed-response admission and adapter header shaping. */
+export declare function recordRouteCacheabilityCdnTags(tags: readonly string[] | undefined): void;
+/** Retain the exact trace metadata marker for completed shared-response admission. */
+export declare function recordRouteCacheabilityClientTraceMetadataMarker(marker: string): void;
 /** Preserve the existing policy when hybrid routing hands the request to Pages Router. */
-declare function preserveRouteCacheabilityResponsePolicy(): void;
-declare function readRouteCacheabilityState(): RouteCacheabilityState | null;
-declare function beginRouteCacheability(kind: "app-page" | "app-route" | "pages-page", pattern: string): boolean;
+export declare function preserveRouteCacheabilityResponsePolicy(): void;
+export declare function readRouteCacheabilityState(): RouteCacheabilityState | null;
+export declare function beginRouteCacheability(kind: "app-page" | "app-route" | "pages-api" | "pages-page", pattern: string): boolean;
 /** Prevent shared caching when request processing before route dispatch was request-specific. */
-declare function markRouteCacheabilityDynamic(reason: string): void;
+export declare function markRouteCacheabilityDynamic(reason: string): void;
 /** Mark an effective route configuration that makes the whole pattern dynamic. */
-declare function markRouteCacheabilityPatternDynamic(reason: string): void;
+export declare function markRouteCacheabilityPatternDynamic(reason: string): void;
 /** Read a request-specific routing veto without making the route globally dynamic. */
-declare function getRouteCacheabilityDynamicReason(): string | null;
+export declare function getRouteCacheabilityDynamicReason(): string | null;
 /** Reuse the active request's bounded response-capture envelope when available. */
-declare function getRouteCacheabilityCaptureOptions(): Pick<RouteCacheabilityState, "captureBudget" | "captureDeadlineAt"> | null;
+export declare function getRouteCacheabilityCaptureOptions(): Pick<RouteCacheabilityState, "captureBudget" | "captureDeadlineAt"> | null;
 /** Keep a completed response private without treating it as static-to-dynamic. */
-declare function markRouteCacheabilityFinalResponseUncacheable(reason: string): void;
+export declare function markRouteCacheabilityFinalResponseUncacheable(reason: string): void;
 /** Record that next.config explicitly owns the final response cache policy. */
-declare function markRouteCacheabilityExplicitConfigPolicy(): void;
-/** Record a public cache policy supplied by the Route Handler itself. */
-declare function markRouteCacheabilityExplicitResponsePolicy(): void;
+export declare function markRouteCacheabilityExplicitConfigPolicy(): void;
+/** Record a cache policy header, not just Vary, that a next.config rule set. */
+export declare function markRouteCacheabilityConfigCdnCachePolicy(name: string, value: string): void;
+/** Record a next.config cache policy header with the value a response carries. */
+export declare function recordConfigCdnCachePolicyHeader(state: RouteCacheabilityState, name: string, value: string): void;
+/** Record an explicit cache policy supplied by the Route Handler itself. */
+export declare function markRouteCacheabilityExplicitResponsePolicy(): void;
 /** Record that the response body reached clean EOF and is now a replay stream. */
-declare function markRouteCacheabilityResponseBodyComplete(): void;
+export declare function markRouteCacheabilityResponseBodyComplete(): void;
 /** Record framework-owned policy so admission can identify policy added later. */
-declare function captureRouteCacheabilityResponsePolicy(headers: Headers): void;
+export declare function captureRouteCacheabilityResponsePolicy(headers: Headers): void;
 /** True only for an authenticated probe that must render the matched App Page. */
-declare function isRouteCacheabilityProbe(): boolean;
+export declare function isRouteCacheabilityProbe(): boolean;
 /** True when the outer Worker must decide cache admission after clean EOF. */
-declare function isRouteCacheabilityEvaluation(): boolean;
+export declare function isRouteCacheabilityEvaluation(): boolean;
 /** True for the authenticated routing pass that must not evaluate user components. */
-declare function isRouteCacheabilityIdentityProbe(): boolean;
+export declare function isRouteCacheabilityIdentityProbe(): boolean;
 /** True for every side-effect-free staged Worker observation request. */
-declare function isStagedCacheabilityProbeActive(): boolean;
-declare function deferRouteCacheability(): ((outcome: RouteCacheabilityOutcome) => void) | null;
-declare function recordRouteCacheability(outcome: RouteCacheabilityOutcome): void;
-declare function recordRouteCacheabilityProbeBailout(kind: "private-cache", outcome: RouteCacheabilityOutcome): void;
-//#endregion
-export { CACHEABILITY_POLICY_HEADERS, CACHEABILITY_REQUEST_STATE, RouteCacheabilityOutcome, RouteCacheabilityState, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordRouteCacheability, recordRouteCacheabilityProbeBailout };
+export declare function isStagedCacheabilityProbeActive(): boolean;
+export declare function deferRouteCacheability(): ((outcome: RouteCacheabilityOutcome) => void) | null;
+export declare function recordRouteCacheability(outcome: RouteCacheabilityOutcome): void;
+export declare function recordRouteCacheabilityProbeBailout(kind: "private-cache", outcome: RouteCacheabilityOutcome): void;
+//#endregion

package/dist/shims/cacheability-classification.js

@@ -1,11 +1,19 @@
 import { getRequestExecutionContext } from "./request-context.js";
 //#region src/shims/cacheability-classification.ts
 const CACHEABILITY_REQUEST_STATE = Symbol.for("vinext.cacheabilityRequestState");
-const CACHEABILITY_POLICY_HEADERS = [
-	"cache-control",
-	"cdn-cache-control",
-	"cloudflare-cdn-cache-control"
-];
+/** Retain canonical tags across completed-response admission and adapter header shaping. */
+function recordRouteCacheabilityCdnTags(tags) {
+	if (tags === void 0) return;
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "admit") return;
+	state.cdnCacheTags = [...tags];
+}
+/** Retain the exact trace metadata marker for completed shared-response admission. */
+function recordRouteCacheabilityClientTraceMetadataMarker(marker) {
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "admit") return;
+	state.clientTraceMetadataMarker = marker;
+}
 /** Preserve the existing policy when hybrid routing hands the request to Pages Router. */
 function preserveRouteCacheabilityResponsePolicy() {
 	const state = readRouteCacheabilityState();
@@ -64,10 +72,22 @@ function markRouteCacheabilityExplicitConfigPolicy() {
 	if (!state) return;
 	state.explicitConfigCachePolicy = true;
 }
-/** Record a public cache policy supplied by the Route Handler itself. */
+/** Record a cache policy header, not just Vary, that a next.config rule set. */
+function markRouteCacheabilityConfigCdnCachePolicy(name, value) {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	recordConfigCdnCachePolicyHeader(state, name, value);
+}
+/** Record a next.config cache policy header with the value a response carries. */
+function recordConfigCdnCachePolicyHeader(state, name, value) {
+	state.explicitConfigCachePolicy = true;
+	const applied = new Headers([[name, value]]).get(name) ?? value;
+	(state.configCdnCachePolicy ??= /* @__PURE__ */ new Map()).set(name.toLowerCase(), applied);
+}
+/** Record an explicit cache policy supplied by the Route Handler itself. */
 function markRouteCacheabilityExplicitResponsePolicy() {
 	const state = readRouteCacheabilityState();
-	if (!state || state.mode !== "admit") return;
+	if (!state) return;
 	state.explicitResponseCachePolicy = true;
 }
 /** Record that the response body reached clean EOF and is now a replay stream. */
@@ -80,12 +100,7 @@ function markRouteCacheabilityResponseBodyComplete() {
 function captureRouteCacheabilityResponsePolicy(headers) {
 	const state = readRouteCacheabilityState();
 	if (!state || state.mode !== "admit") return;
-	const policy = {};
-	for (const name of CACHEABILITY_POLICY_HEADERS) {
-		const value = headers.get(name);
-		if (value !== null) policy[name] = value;
-	}
-	state.frameworkResponseCachePolicy = policy;
+	state.frameworkResponseCachePolicy = new Headers(headers);
 }
 /** True only for an authenticated probe that must render the matched App Page. */
 function isRouteCacheabilityProbe() {
@@ -143,4 +158,4 @@ function recordRouteCacheabilityProbeBailout(kind, outcome) {
 	state.complete?.(outcome);
 }
 //#endregion
-export { CACHEABILITY_POLICY_HEADERS, CACHEABILITY_REQUEST_STATE, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordRouteCacheability, recordRouteCacheabilityProbeBailout };
+export { CACHEABILITY_REQUEST_STATE, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityConfigCdnCachePolicy, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordConfigCdnCachePolicyHeader, recordRouteCacheability, recordRouteCacheabilityCdnTags, recordRouteCacheabilityClientTraceMetadataMarker, recordRouteCacheabilityProbeBailout };

package/dist/shims/cdn-cache-state.d.ts

@@ -0,0 +1,13 @@
+import { CdnCacheAdapter } from "./cdn-cache.js";
+//#region src/shims/cdn-cache-state.d.ts
+/** Register an adapter without loading the origin cache implementation. */
+export declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
+/**
+ * Lazily keep the first declaratively configured adapter shared across
+ * duplicated stage modules. Failed factories remain retryable so a later
+ * entrypoint with the required runtime bindings can register successfully.
+ */
+export declare function registerCdnCacheAdapter(factory: () => CdnCacheAdapter): void;
+/** Read only an explicitly registered adapter; defaults belong to cdn-cache. */
+export declare function getExplicitCdnCacheAdapter(): CdnCacheAdapter | null;
+//#endregion