@qzsy/vinext 0.1.7

package/dist/server/navigation-trace.d.ts

@@ -0,0 +1,68 @@
+//#region src/server/navigation-trace.d.ts
+declare const NAVIGATION_TRACE_SCHEMA_VERSION = 0;
+type NavigationTraceSchemaVersion = 0;
+declare const NavigationTraceReasonCodes: {
+  cacheProofRejected: "NC_CACHE_REJECT";
+  cacheReuseTokenRejected: "NC_CACHE_TOKEN_REJECT";
+  commitCurrent: "NC_COMMIT";
+  crossDocumentFlight: "NC_CROSS_DOC_FLIGHT";
+  fetchFresh: "NC_FETCH_FRESH";
+  invalidRscPayload: "NC_RSC_INVALID";
+  interceptedCommitCurrent: "NC_INTERCEPT_COMMIT";
+  interceptedRejectedIncompatibleRoot: "NC_INTERCEPT_REJECT_ROOT";
+  interceptedRejectedMissingProof: "NC_INTERCEPT_REJECT_MISSING_PROOF";
+  interceptedRejectedMissingSlotProof: "NC_INTERCEPT_REJECT_SLOT";
+  interceptedRejectedTargetMismatch: "NC_INTERCEPT_REJECT_TARGET";
+  interceptedRejectedUndeclaredTopology: "NC_INTERCEPT_REJECT_GRAPH";
+  interceptedRejectedUnknownSource: "NC_INTERCEPT_REJECT_SOURCE";
+  optimisticRouteShell: "NC_OPTIMISTIC_SHELL";
+  prefetchOnly: "NC_PREFETCH_ONLY";
+  prefetchResponseReuse: "NC_PREFETCH_REUSE";
+  proceedToCommit: "NC_RSC_PROCEED";
+  redirectFollow: "NC_RSC_REDIRECT_FOLLOW";
+  redirectTerminalDepth: "NC_RSC_REDIRECT_DEPTH";
+  redirectTerminalExternal: "NC_RSC_REDIRECT_EXTERNAL";
+  requestWork: "NC_REQUEST";
+  rootBoundaryChanged: "NC_ROOT";
+  rootBoundaryUnknown: "NC_ROOT_UNKNOWN";
+  rscCompatibilityMismatch: "NC_RSC_COMPAT_MISMATCH";
+  rscNavigationError: "NC_RSC_NAV_ERROR";
+  sameDocumentScroll: "NC_SAME_DOC_SCROLL";
+  samePageSearch: "NC_SAME_PAGE_SEARCH";
+  serverActionRedirectCompatibilityMismatch: "NC_SA_REDIRECT_COMPAT";
+  serverActionRscCompatibilityMismatch: "NC_SA_RSC_COMPAT";
+  staleOperation: "NC_STALE";
+  streamedRedirectLoop: "NC_RSC_STREAMED_REDIRECT_LOOP";
+  visitedResponseReuse: "NC_VISITED_REUSE";
+};
+declare const NavigationTraceTransactionCodes: {
+  hardNavigate: "NT_HARD_NAVIGATE";
+  noCommit: "NT_NO_COMMIT";
+  visibleCommit: "NT_VISIBLE_COMMIT";
+};
+type NavigationTraceReasonCode = (typeof NavigationTraceReasonCodes)[keyof typeof NavigationTraceReasonCodes];
+type NavigationTraceTransactionCode = (typeof NavigationTraceTransactionCodes)[keyof typeof NavigationTraceTransactionCodes];
+type NavigationTraceCode = NavigationTraceReasonCode | NavigationTraceTransactionCode;
+type NavigationTraceFieldName = "activeNavigationId" | "cacheProofCode" | "cacheProofMode" | "cacheProofReuseClass" | "cacheProofScope" | "cacheReuseTokenReason" | "currentRootLayoutTreePath" | "currentVisibleCommitVersion" | "nextRootLayoutTreePath" | "eventKind" | "fetchResultSource" | "freshFetchReason" | "operationLane" | "pendingOperationId" | "redirectDepth" | "redirectSignal" | "startedVisibleCommitVersion" | "startedNavigationId" | "targetHref" | "traverseDirection";
+type NavigationTraceFieldValue = string | number | boolean | null;
+type NavigationTraceFields = Readonly<Partial<Record<NavigationTraceFieldName, NavigationTraceFieldValue>>>;
+type NavigationTraceEntry = Readonly<{
+  code: NavigationTraceCode;
+  fields: NavigationTraceFields;
+}>;
+type NavigationTrace = Readonly<{
+  schemaVersion: NavigationTraceSchemaVersion;
+  entries: readonly NavigationTraceEntry[];
+}>;
+declare function createNavigationLifecycleTraceFields(options: {
+  activeNavigationId?: number;
+  currentRootLayoutTreePath: string | null;
+  currentVisibleCommitVersion: number;
+  nextRootLayoutTreePath: string | null;
+  startedNavigationId?: number;
+  startedVisibleCommitVersion: number;
+}): NavigationTraceFields;
+declare function createNavigationTrace(code: NavigationTraceCode, fields?: NavigationTraceFields): NavigationTrace;
+declare function prependNavigationTraceEntry(trace: NavigationTrace, code: NavigationTraceCode, fields?: NavigationTraceFields): NavigationTrace;
+//#endregion
+export { NAVIGATION_TRACE_SCHEMA_VERSION, NavigationTrace, NavigationTraceFields, NavigationTraceReasonCode, NavigationTraceReasonCodes, NavigationTraceTransactionCode, NavigationTraceTransactionCodes, createNavigationLifecycleTraceFields, createNavigationTrace, prependNavigationTraceEntry };

package/dist/server/navigation-trace.js

@@ -0,0 +1,71 @@
+//#region src/server/navigation-trace.ts
+const NAVIGATION_TRACE_SCHEMA_VERSION = 0;
+const NavigationTraceReasonCodes = {
+	cacheProofRejected: "NC_CACHE_REJECT",
+	cacheReuseTokenRejected: "NC_CACHE_TOKEN_REJECT",
+	commitCurrent: "NC_COMMIT",
+	crossDocumentFlight: "NC_CROSS_DOC_FLIGHT",
+	fetchFresh: "NC_FETCH_FRESH",
+	invalidRscPayload: "NC_RSC_INVALID",
+	interceptedCommitCurrent: "NC_INTERCEPT_COMMIT",
+	interceptedRejectedIncompatibleRoot: "NC_INTERCEPT_REJECT_ROOT",
+	interceptedRejectedMissingProof: "NC_INTERCEPT_REJECT_MISSING_PROOF",
+	interceptedRejectedMissingSlotProof: "NC_INTERCEPT_REJECT_SLOT",
+	interceptedRejectedTargetMismatch: "NC_INTERCEPT_REJECT_TARGET",
+	interceptedRejectedUndeclaredTopology: "NC_INTERCEPT_REJECT_GRAPH",
+	interceptedRejectedUnknownSource: "NC_INTERCEPT_REJECT_SOURCE",
+	optimisticRouteShell: "NC_OPTIMISTIC_SHELL",
+	prefetchOnly: "NC_PREFETCH_ONLY",
+	prefetchResponseReuse: "NC_PREFETCH_REUSE",
+	proceedToCommit: "NC_RSC_PROCEED",
+	redirectFollow: "NC_RSC_REDIRECT_FOLLOW",
+	redirectTerminalDepth: "NC_RSC_REDIRECT_DEPTH",
+	redirectTerminalExternal: "NC_RSC_REDIRECT_EXTERNAL",
+	requestWork: "NC_REQUEST",
+	rootBoundaryChanged: "NC_ROOT",
+	rootBoundaryUnknown: "NC_ROOT_UNKNOWN",
+	rscCompatibilityMismatch: "NC_RSC_COMPAT_MISMATCH",
+	rscNavigationError: "NC_RSC_NAV_ERROR",
+	sameDocumentScroll: "NC_SAME_DOC_SCROLL",
+	samePageSearch: "NC_SAME_PAGE_SEARCH",
+	serverActionRedirectCompatibilityMismatch: "NC_SA_REDIRECT_COMPAT",
+	serverActionRscCompatibilityMismatch: "NC_SA_RSC_COMPAT",
+	staleOperation: "NC_STALE",
+	streamedRedirectLoop: "NC_RSC_STREAMED_REDIRECT_LOOP",
+	visitedResponseReuse: "NC_VISITED_REUSE"
+};
+const NavigationTraceTransactionCodes = {
+	hardNavigate: "NT_HARD_NAVIGATE",
+	noCommit: "NT_NO_COMMIT",
+	visibleCommit: "NT_VISIBLE_COMMIT"
+};
+function createNavigationLifecycleTraceFields(options) {
+	return {
+		...options.activeNavigationId !== void 0 ? { activeNavigationId: options.activeNavigationId } : {},
+		currentRootLayoutTreePath: options.currentRootLayoutTreePath,
+		currentVisibleCommitVersion: options.currentVisibleCommitVersion,
+		nextRootLayoutTreePath: options.nextRootLayoutTreePath,
+		...options.startedNavigationId !== void 0 ? { startedNavigationId: options.startedNavigationId } : {},
+		startedVisibleCommitVersion: options.startedVisibleCommitVersion
+	};
+}
+function createNavigationTraceEntry(code, fields = {}) {
+	return {
+		code,
+		fields: { ...fields }
+	};
+}
+function createNavigationTrace(code, fields = {}) {
+	return {
+		schemaVersion: 0,
+		entries: [createNavigationTraceEntry(code, fields)]
+	};
+}
+function prependNavigationTraceEntry(trace, code, fields = {}) {
+	return {
+		schemaVersion: trace.schemaVersion,
+		entries: [createNavigationTraceEntry(code, fields), ...trace.entries]
+	};
+}
+//#endregion
+export { NAVIGATION_TRACE_SCHEMA_VERSION, NavigationTraceReasonCodes, NavigationTraceTransactionCodes, createNavigationLifecycleTraceFields, createNavigationTrace, prependNavigationTraceEntry };

package/dist/server/next-error-digest.d.ts

@@ -0,0 +1,44 @@
+//#region src/server/next-error-digest.d.ts
+/**
+ * Helpers for parsing Next.js error `digest` strings shared across the App
+ * Router execution paths (server actions, page renders, route handlers).
+ *
+ * Next.js encodes special control flow as thrown errors carrying a `digest`
+ * field with one of these formats:
+ *  - `NEXT_REDIRECT;<type>;<encodedUrl>;<status>` — `redirect()` / `permanentRedirect()`
+ *  - `NEXT_NOT_FOUND` — `notFound()`
+ *  - `NEXT_HTTP_ERROR_FALLBACK;<status>` — `forbidden()` / `unauthorized()` / etc.
+ *
+ * Each call site needs slightly different post-processing (URL resolution
+ * against the request, 303-vs-307 status overrides for actions, etc.), so
+ * these helpers only handle the parsing — callers shape the result.
+ */
+type NextRedirectDigest = {
+  status: number;
+  type: string | null;
+  url: string;
+};
+type NextHttpErrorDigest = {
+  status: number;
+};
+/**
+ * Pulls a stringified `digest` off an unknown thrown value, or returns null
+ * when the value is not a digest-bearing error.
+ */
+declare function getNextErrorDigest(error: unknown): string | null;
+/**
+ * Parses a `NEXT_REDIRECT;<type>;<encodedUrl>;<status>` digest. Returns null
+ * when the digest is not a redirect digest or the encoded URL segment is
+ * missing. The `url` is decoded with `decodeURIComponent`; the `status`
+ * defaults to 307 when omitted; an omitted `type` is left as null so the
+ * caller can apply the correct context-sensitive default.
+ */
+declare function parseNextRedirectDigest(digest: string): NextRedirectDigest | null;
+/**
+ * Parses a `NEXT_NOT_FOUND` or `NEXT_HTTP_ERROR_FALLBACK;<status>` digest.
+ * Returns `{ status: 404 }` for `NEXT_NOT_FOUND` and the parsed status code
+ * for the fallback form. Returns null otherwise.
+ */
+declare function parseNextHttpErrorDigest(digest: string): NextHttpErrorDigest | null;
+//#endregion
+export { getNextErrorDigest, parseNextHttpErrorDigest, parseNextRedirectDigest };

package/dist/server/next-error-digest.js

@@ -0,0 +1,40 @@
+//#region src/server/next-error-digest.ts
+/**
+* Pulls a stringified `digest` off an unknown thrown value, or returns null
+* when the value is not a digest-bearing error.
+*/
+function getNextErrorDigest(error) {
+	if (!error || typeof error !== "object" || !("digest" in error)) return null;
+	return String(error.digest);
+}
+/**
+* Parses a `NEXT_REDIRECT;<type>;<encodedUrl>;<status>` digest. Returns null
+* when the digest is not a redirect digest or the encoded URL segment is
+* missing. The `url` is decoded with `decodeURIComponent`; the `status`
+* defaults to 307 when omitted; an omitted `type` is left as null so the
+* caller can apply the correct context-sensitive default.
+*/
+function parseNextRedirectDigest(digest) {
+	if (!digest.startsWith("NEXT_REDIRECT;")) return null;
+	const parts = digest.split(";");
+	const encodedUrl = parts[2];
+	if (!encodedUrl) return null;
+	const type = parts[1];
+	return {
+		status: parts[3] ? parseInt(parts[3], 10) : 307,
+		type: type || null,
+		url: decodeURIComponent(encodedUrl)
+	};
+}
+/**
+* Parses a `NEXT_NOT_FOUND` or `NEXT_HTTP_ERROR_FALLBACK;<status>` digest.
+* Returns `{ status: 404 }` for `NEXT_NOT_FOUND` and the parsed status code
+* for the fallback form. Returns null otherwise.
+*/
+function parseNextHttpErrorDigest(digest) {
+	if (digest === "NEXT_NOT_FOUND") return { status: 404 };
+	if (digest.startsWith("NEXT_HTTP_ERROR_FALLBACK;")) return { status: parseInt(digest.split(";")[1], 10) };
+	return null;
+}
+//#endregion
+export { getNextErrorDigest, parseNextHttpErrorDigest, parseNextRedirectDigest };

package/dist/server/normalize-path.d.ts

@@ -0,0 +1,38 @@
+//#region src/server/normalize-path.d.ts
+declare function escapePathDelimiters(segment: string, escapeEncoded?: boolean): string;
+/**
+ * Decode a URL pathname segment-by-segment, preserving encoded path delimiters.
+ * Non-ASCII characters (e.g. %C3%A9 -> e) are decoded, but structural characters
+ * like %2F (/) %23 (#) %3F (?) %5C (\) are re-encoded after decoding.
+ *
+ * This prevents encoded slashes from changing the path structure (e.g.
+ * /admin%2Fpanel stays as a single segment, not /admin/panel).
+ *
+ * Ported from Next.js: packages/next/src/server/lib/router-utils/decode-path-params.ts
+ * https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-utils/decode-path-params.ts
+ */
+declare function decodePathParams(pathname: string): string;
+declare function isInterceptionMatchedUrlPath(value: string): boolean;
+/**
+ * Path normalization utility for request handling.
+ *
+ * Normalizes URL pathnames to a canonical form BEFORE any matching occurs
+ * (middleware, routing, redirects, rewrites). This ensures middleware and
+ * the router always see the same path, preventing path-confusion issues like
+ * double-slash mismatches.
+ *
+ * Normalization rules:
+ *  1. Collapse consecutive slashes: //foo///bar → /foo/bar
+ *  2. Resolve single-dot segments:  /foo/./bar  → /foo/bar
+ *  3. Resolve double-dot segments:  /foo/../bar → /bar
+ *  4. Ensure leading slash:         foo/bar     → /foo/bar
+ *  5. Preserve root:                /           → /
+ *
+ * This function does NOT:
+ *  - Strip or add trailing slashes (handled separately by trailingSlash config)
+ *  - Decode percent-encoded characters (callers should decode before calling this)
+ *  - Lowercase the path (route matching is case-sensitive)
+ */
+declare function normalizePath(pathname: string): string;
+//#endregion
+export { decodePathParams, escapePathDelimiters, isInterceptionMatchedUrlPath, normalizePath };

package/dist/server/normalize-path.js

@@ -0,0 +1,70 @@
+//#region src/server/normalize-path.ts
+/**
+* Re-encode path delimiter characters that were decoded by decodeURIComponent.
+* After decoding a URL segment, characters like / # ? \ need to be re-encoded
+* so they don't change the path structure.
+*
+* Ported from Next.js: packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts
+*/
+const PATH_DELIMITERS_RE = /([/#?])/gi;
+const PATH_DELIMITERS_ENCODED_RE = /([/#?]|%(2f|23|3f|5c))/gi;
+function escapePathDelimiters(segment, escapeEncoded) {
+	return segment.replace(escapeEncoded ? PATH_DELIMITERS_ENCODED_RE : PATH_DELIMITERS_RE, (char) => encodeURIComponent(char));
+}
+/**
+* Decode a URL pathname segment-by-segment, preserving encoded path delimiters.
+* Non-ASCII characters (e.g. %C3%A9 -> e) are decoded, but structural characters
+* like %2F (/) %23 (#) %3F (?) %5C (\) are re-encoded after decoding.
+*
+* This prevents encoded slashes from changing the path structure (e.g.
+* /admin%2Fpanel stays as a single segment, not /admin/panel).
+*
+* Ported from Next.js: packages/next/src/server/lib/router-utils/decode-path-params.ts
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-utils/decode-path-params.ts
+*/
+function decodePathParams(pathname) {
+	return pathname.split("/").map((seg) => {
+		try {
+			return escapePathDelimiters(decodeURIComponent(seg), true);
+		} catch {
+			return seg;
+		}
+	}).join("/");
+}
+function isInterceptionMatchedUrlPath(value) {
+	return value.startsWith("/") && !value.startsWith("//") && !value.includes("?") && !value.includes("#") && !value.includes("\0");
+}
+/**
+* Path normalization utility for request handling.
+*
+* Normalizes URL pathnames to a canonical form BEFORE any matching occurs
+* (middleware, routing, redirects, rewrites). This ensures middleware and
+* the router always see the same path, preventing path-confusion issues like
+* double-slash mismatches.
+*
+* Normalization rules:
+*  1. Collapse consecutive slashes: //foo///bar → /foo/bar
+*  2. Resolve single-dot segments:  /foo/./bar  → /foo/bar
+*  3. Resolve double-dot segments:  /foo/../bar → /bar
+*  4. Ensure leading slash:         foo/bar     → /foo/bar
+*  5. Preserve root:                /           → /
+*
+* This function does NOT:
+*  - Strip or add trailing slashes (handled separately by trailingSlash config)
+*  - Decode percent-encoded characters (callers should decode before calling this)
+*  - Lowercase the path (route matching is case-sensitive)
+*/
+function normalizePath(pathname) {
+	if (pathname === "/" || pathname.length > 1 && pathname[0] === "/" && !pathname.includes("//") && !pathname.includes("/./") && !pathname.includes("/../") && !pathname.endsWith("/.") && !pathname.endsWith("/..")) return pathname;
+	const segments = pathname.split("/");
+	const resolved = [];
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") resolved.pop();
+		else resolved.push(segment);
+	}
+	return "/" + resolved.join("/");
+}
+//#endregion
+export { decodePathParams, escapePathDelimiters, isInterceptionMatchedUrlPath, normalizePath };

package/dist/server/open-redirect.d.ts

@@ -0,0 +1,12 @@
+//#region src/server/open-redirect.d.ts
+/**
+ * Returns true if a request pathname looks like a protocol-relative open
+ * redirect, in either literal or percent-encoded form.
+ *
+ * A pathname is considered "open redirect shaped" when its first segment,
+ * after decoding backslashes and encoded delimiters, would cause a browser
+ * to resolve a `Location` containing the pathname as protocol-relative.
+ */
+declare function isOpenRedirectShaped(rawPathname: string): boolean;
+//#endregion
+export { isOpenRedirectShaped };

package/dist/server/open-redirect.js

@@ -0,0 +1,21 @@
+//#region src/server/open-redirect.ts
+/**
+* Returns true if a request pathname looks like a protocol-relative open
+* redirect, in either literal or percent-encoded form.
+*
+* A pathname is considered "open redirect shaped" when its first segment,
+* after decoding backslashes and encoded delimiters, would cause a browser
+* to resolve a `Location` containing the pathname as protocol-relative.
+*/
+function isOpenRedirectShaped(rawPathname) {
+	if (!rawPathname.startsWith("/")) return false;
+	const afterSlash = rawPathname.slice(1);
+	if (afterSlash.startsWith("/") || afterSlash.startsWith("\\")) return true;
+	if (afterSlash.length >= 3 && afterSlash[0] === "%") {
+		const encoded = afterSlash.slice(0, 3).toLowerCase();
+		if (encoded === "%5c" || encoded === "%2f") return true;
+	}
+	return false;
+}
+//#endregion
+export { isOpenRedirectShaped };

package/dist/server/operation-token.d.ts

@@ -0,0 +1,40 @@
+//#region src/server/operation-token.d.ts
+type OperationLane = "hmr" | "navigation" | "prefetch" | "refresh" | "server-action" | "traverse";
+type OperationToken = {
+  operationId: number;
+  lane: OperationLane;
+  navigationId: number;
+  baseVisibleCommitVersion: number;
+  graphVersion: string | null;
+  deploymentVersion: string | null;
+  targetSnapshotFingerprint: string;
+  cacheVariantFingerprint?: string;
+};
+declare const verifiedOperationTokenBrand: unique symbol;
+type VerifiedOperationToken = OperationToken & {
+  readonly [verifiedOperationTokenBrand]: true;
+};
+type OperationTokenAuthority = {
+  activeNavigationId: number;
+  visibleCommitVersion: number;
+  graphVersion: string | null;
+  installedCacheVariantFingerprint: string | null;
+};
+type OperationTokenDimension = "navigation" | "visibleCommit" | "graphVersion" | "cacheVariant";
+type OperationTokenRejectionReason = "staleNavigation" | "staleVisibleCommit" | "graphVersionMismatch" | "graphVersionMissing" | "cacheVariantMismatch" | "cacheVariantMissing";
+type OperationTokenVerdict = {
+  readonly authorized: true;
+  readonly token: VerifiedOperationToken;
+} | {
+  readonly authorized: false;
+  readonly reason: OperationTokenRejectionReason;
+};
+type OperationTokenVerificationPolicy = {
+  check: readonly OperationTokenDimension[];
+  require: readonly OperationTokenDimension[];
+};
+declare function verifyOperationToken(token: OperationToken, authority: OperationTokenAuthority, policy: OperationTokenVerificationPolicy): OperationTokenVerdict;
+declare function verifyOperationTokenForCommit(token: OperationToken, authority: Pick<OperationTokenAuthority, "activeNavigationId" | "visibleCommitVersion">): OperationTokenVerdict;
+declare function verifyOperationTokenForCacheReuse(token: OperationToken, authority: Pick<OperationTokenAuthority, "graphVersion" | "installedCacheVariantFingerprint">): OperationTokenVerdict;
+//#endregion
+export { OperationLane, OperationToken, OperationTokenAuthority, OperationTokenRejectionReason, OperationTokenVerdict, OperationTokenVerificationPolicy, VerifiedOperationToken, verifyOperationToken, verifyOperationTokenForCacheReuse, verifyOperationTokenForCommit };

package/dist/server/operation-token.js

@@ -0,0 +1,85 @@
+//#region src/server/operation-token.ts
+const DIMENSION_ORDER = [
+	"navigation",
+	"visibleCommit",
+	"graphVersion",
+	"cacheVariant"
+];
+function evaluateDimension(dimension, token, authority) {
+	switch (dimension) {
+		case "navigation": return token.navigationId === authority.activeNavigationId ? { kind: "satisfied" } : {
+			kind: "mismatch",
+			reason: "staleNavigation"
+		};
+		case "visibleCommit": return token.baseVisibleCommitVersion === authority.visibleCommitVersion ? { kind: "satisfied" } : {
+			kind: "mismatch",
+			reason: "staleVisibleCommit"
+		};
+		case "graphVersion":
+			if (token.graphVersion === null || authority.graphVersion === null) return {
+				kind: "absent",
+				missingReason: "graphVersionMissing"
+			};
+			return token.graphVersion === authority.graphVersion ? { kind: "satisfied" } : {
+				kind: "mismatch",
+				reason: "graphVersionMismatch"
+			};
+		case "cacheVariant": {
+			const tokenVariant = token.cacheVariantFingerprint;
+			const installedVariant = authority.installedCacheVariantFingerprint;
+			if (tokenVariant === void 0 || installedVariant === null) return {
+				kind: "absent",
+				missingReason: "cacheVariantMissing"
+			};
+			return tokenVariant === installedVariant ? { kind: "satisfied" } : {
+				kind: "mismatch",
+				reason: "cacheVariantMismatch"
+			};
+		}
+		default: throw new Error("[vinext] Unknown operation-token dimension: " + String(dimension));
+	}
+}
+function verifyOperationToken(token, authority, policy) {
+	const required = new Set(policy.require);
+	const evaluated = new Set([...policy.check, ...policy.require]);
+	for (const dimension of DIMENSION_ORDER) {
+		if (!evaluated.has(dimension)) continue;
+		const status = evaluateDimension(dimension, token, authority);
+		if (status.kind === "mismatch") return {
+			authorized: false,
+			reason: status.reason
+		};
+		if (status.kind === "absent" && required.has(dimension)) return {
+			authorized: false,
+			reason: status.missingReason
+		};
+	}
+	return {
+		authorized: true,
+		token
+	};
+}
+function verifyOperationTokenForCommit(token, authority) {
+	return verifyOperationToken(token, {
+		activeNavigationId: authority.activeNavigationId,
+		visibleCommitVersion: authority.visibleCommitVersion,
+		graphVersion: token.graphVersion,
+		installedCacheVariantFingerprint: token.cacheVariantFingerprint ?? null
+	}, {
+		check: ["navigation", "visibleCommit"],
+		require: ["navigation", "visibleCommit"]
+	});
+}
+function verifyOperationTokenForCacheReuse(token, authority) {
+	return verifyOperationToken(token, {
+		activeNavigationId: token.navigationId,
+		visibleCommitVersion: token.baseVisibleCommitVersion,
+		graphVersion: authority.graphVersion,
+		installedCacheVariantFingerprint: authority.installedCacheVariantFingerprint
+	}, {
+		check: ["graphVersion", "cacheVariant"],
+		require: []
+	});
+}
+//#endregion
+export { verifyOperationToken, verifyOperationTokenForCacheReuse, verifyOperationTokenForCommit };

package/dist/server/otel-tracer-extension.d.ts

@@ -0,0 +1,45 @@
+//#region src/server/otel-tracer-extension.d.ts
+/**
+ * OpenTelemetry tracer provider extension for Cache Components.
+ *
+ * When `cacheComponents: true` is enabled in next.config, component renders
+ * go through multiple phases (warmup → resume). During these phases, the
+ * `workUnitAsyncStorage` carries a prerender or cache store. Without this
+ * extension, calls to `tracer.startSpan()` / `tracer.startActiveSpan()` from
+ * inside user RSC code would inherit that prerender context, causing:
+ *
+ *  1. Spans to reuse the same trace ID across requests (the frozen prerender
+ *     context bleeds into the runtime resume render).
+ *  2. Spans not being created at all during fallback resume (the work unit
+ *     context gates span creation in some OTel SDK implementations).
+ *
+ * The fix mirrors Next.js's `instrumentation-node-extensions.ts`:
+ *  - Wrap `tracer.startSpan` to exit `workUnitAsyncStorage` before creating
+ *    the span, ensuring a clean context for span ID generation.
+ *  - Wrap `tracer.startActiveSpan` similarly and re-enter the work unit store
+ *    for the callback, so that the callback runs with the correct request
+ *    context restored.
+ *
+ * This extension is intentionally a no-op when:
+ *  - `@opentelemetry/api` is not installed (graceful degradation).
+ *  - No OTel tracer provider has been registered (provider is the noop provider).
+ *  - `workUnitAsyncStorage` has no active store (non-render contexts).
+ *
+ * References:
+ *  - packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+ *  - https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+ */
+/**
+ * Extend the registered OTel tracer provider so that `startSpan` and
+ * `startActiveSpan` exit the `workUnitAsyncStorage` context before creating
+ * spans. This prevents the prerender/cache work unit store from leaking into
+ * span ID generation during Cache Component fallback resumes.
+ *
+ * Safe to call multiple times — subsequent calls are no-ops once the provider
+ * has been wrapped.
+ *
+ * Must only be called in Node.js environments (not Edge runtime).
+ */
+declare function extendTracerProviderForCacheComponents(): void;
+//#endregion
+export { extendTracerProviderForCacheComponents };

package/dist/server/otel-tracer-extension.js

@@ -0,0 +1,89 @@
+import { workUnitAsyncStorage } from "../shims/internal/work-unit-async-storage.js";
+//#region src/server/otel-tracer-extension.ts
+/**
+* OpenTelemetry tracer provider extension for Cache Components.
+*
+* When `cacheComponents: true` is enabled in next.config, component renders
+* go through multiple phases (warmup → resume). During these phases, the
+* `workUnitAsyncStorage` carries a prerender or cache store. Without this
+* extension, calls to `tracer.startSpan()` / `tracer.startActiveSpan()` from
+* inside user RSC code would inherit that prerender context, causing:
+*
+*  1. Spans to reuse the same trace ID across requests (the frozen prerender
+*     context bleeds into the runtime resume render).
+*  2. Spans not being created at all during fallback resume (the work unit
+*     context gates span creation in some OTel SDK implementations).
+*
+* The fix mirrors Next.js's `instrumentation-node-extensions.ts`:
+*  - Wrap `tracer.startSpan` to exit `workUnitAsyncStorage` before creating
+*    the span, ensuring a clean context for span ID generation.
+*  - Wrap `tracer.startActiveSpan` similarly and re-enter the work unit store
+*    for the callback, so that the callback runs with the correct request
+*    context restored.
+*
+* This extension is intentionally a no-op when:
+*  - `@opentelemetry/api` is not installed (graceful degradation).
+*  - No OTel tracer provider has been registered (provider is the noop provider).
+*  - `workUnitAsyncStorage` has no active store (non-render contexts).
+*
+* References:
+*  - packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+*  - https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+*/
+const extendedProviders = /* @__PURE__ */ new WeakSet();
+const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
+function isUseCacheFn(fn) {
+	return typeof fn === "function" && fn[USE_CACHE_FUNCTION_SYMBOL] === true;
+}
+/**
+* Extend the registered OTel tracer provider so that `startSpan` and
+* `startActiveSpan` exit the `workUnitAsyncStorage` context before creating
+* spans. This prevents the prerender/cache work unit store from leaking into
+* span ID generation during Cache Component fallback resumes.
+*
+* Safe to call multiple times — subsequent calls are no-ops once the provider
+* has been wrapped.
+*
+* Must only be called in Node.js environments (not Edge runtime).
+*/
+function extendTracerProviderForCacheComponents() {
+	let api;
+	try {
+		const req = globalThis.require;
+		if (typeof req === "function") api = req("@opentelemetry/api");
+	} catch {
+		return;
+	}
+	if (!api) return;
+	const provider = api.trace.getTracerProvider();
+	if (!provider || typeof provider.getTracer !== "function") return;
+	if (extendedProviders.has(provider)) return;
+	extendedProviders.add(provider);
+	const originalGetTracer = provider.getTracer.bind(provider);
+	const wrappedTracers = /* @__PURE__ */ new WeakSet();
+	provider.getTracer = (...args) => {
+		const tracer = originalGetTracer(...args);
+		if (!tracer || wrappedTracers.has(tracer)) return tracer;
+		const originalStartSpan = tracer.startSpan;
+		if (typeof originalStartSpan === "function") tracer.startSpan = (...startSpanArgs) => workUnitAsyncStorage.exit(() => originalStartSpan.apply(tracer, startSpanArgs));
+		const originalStartActiveSpan = tracer.startActiveSpan;
+		if (typeof originalStartActiveSpan === "function") tracer.startActiveSpan = (...startActiveSpanArgs) => {
+			const workUnitStore = workUnitAsyncStorage.getStore();
+			if (!workUnitStore) return originalStartActiveSpan.apply(tracer, startActiveSpanArgs);
+			let fnIdx = 0;
+			if (startActiveSpanArgs.length === 2 && typeof startActiveSpanArgs[1] === "function") fnIdx = 1;
+			else if (startActiveSpanArgs.length === 3 && typeof startActiveSpanArgs[2] === "function") fnIdx = 2;
+			else if (startActiveSpanArgs.length > 3 && typeof startActiveSpanArgs[3] === "function") fnIdx = 3;
+			if (fnIdx > 0) {
+				const originalFn = startActiveSpanArgs[fnIdx];
+				if (isUseCacheFn(originalFn)) console.error("A Cache Function (`use cache`) was passed to startActiveSpan which means it will receive a Span argument with a possibly random ID on every invocation leading to cache misses. Provide a wrapping function around the Cache Function that does not forward the Span argument to avoid this issue.");
+				startActiveSpanArgs[fnIdx] = (...cbArgs) => workUnitAsyncStorage.run(workUnitStore, originalFn, ...cbArgs);
+			}
+			return workUnitAsyncStorage.exit(() => originalStartActiveSpan.apply(tracer, startActiveSpanArgs));
+		};
+		wrappedTracers.add(tracer);
+		return tracer;
+	};
+}
+//#endregion
+export { extendTracerProviderForCacheComponents };