cdk-nextjs 0.7.5 → 0.7.6

package/lib/adapter/adapter.mjs

@@ -808,11 +808,167 @@ import {
   writeFile
 } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep as sep2 } from "node:path";
+
+// src/adapter/cache-utils.ts
+import { createHash } from "node:crypto";
+import { sep } from "node:path";
 
 // src/constants.ts
 var LOG_PREFIX = "[cdk-nextjs]";
 
+// src/utils/base-path.ts
+function normalizeBasePath(basePath) {
+  return (basePath || "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function hasPathPrefix(path, prefix) {
+  return !!prefix && (path === prefix || path.startsWith(`${prefix}/`));
+}
+function basePathPrefix(basePath) {
+  const bare = normalizeBasePath(basePath);
+  return bare ? `/${bare}` : "";
+}
+
+// src/adapter/cache-utils.ts
+function preprocessValue(value) {
+  if (value == null) {
+    return value;
+  }
+  if (Buffer.isBuffer(value)) {
+    return {
+      __type: "Buffer",
+      base64: value.toString("base64")
+    };
+  }
+  if (value instanceof Map) {
+    const entries = {};
+    for (const [key, val] of value.entries()) {
+      entries[key] = preprocessValue(val);
+    }
+    return {
+      __type: "Map",
+      data: entries
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => preprocessValue(item));
+  }
+  if (typeof value === "object") {
+    const processed = {};
+    for (const [key, val] of Object.entries(value)) {
+      processed[key] = preprocessValue(val);
+    }
+    return processed;
+  }
+  return value;
+}
+function serializeCacheValue(value) {
+  const processed = preprocessValue(value);
+  return JSON.stringify(processed);
+}
+function prerenderPathToCacheKey(pathname, basePath) {
+  const route = (hasPathPrefix(pathname, basePath) ? pathname.slice(basePath.length) : pathname).replace(/^\/+/, "");
+  return route === "" ? "index" : route;
+}
+function cacheKeyFileName(cacheKey) {
+  let cleanCacheKey = cacheKey;
+  if (cacheKey === "/" || cacheKey === "") {
+    cleanCacheKey = "index";
+  } else if (cacheKey.startsWith("/")) {
+    cleanCacheKey = cacheKey.slice(1);
+  }
+  return `${cleanCacheKey}.json`;
+}
+function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+var MAX_S3_KEY_BYTES = 1024;
+var MAX_BUILD_ID_BYTES = 127;
+var LONG_KEY_PREFIX = "_long-key";
+function cacheObjectName(cacheKey) {
+  const name = cacheKeyFileName(cacheKey);
+  if (Buffer.byteLength(name) <= MAX_S3_KEY_BYTES - (MAX_BUILD_ID_BYTES + 1)) {
+    return name;
+  }
+  return `${LONG_KEY_PREFIX}/${sha256Hex(name)}.long`;
+}
+function routeCacheKeyFromFilePath(filePath) {
+  const path = filePath?.split(sep).join("/");
+  const at = path?.indexOf(ROUTE_CACHE_DIR) ?? -1;
+  if (at < 0) {
+    return void 0;
+  }
+  const key = path.slice(at + "/server/".length).replace(/\.[^./]+$/, "");
+  return ROUTE_CACHE_KEY_PREFIX.test(key) ? key : void 0;
+}
+var ROUTE_CACHE_DIR = "/server/route-cache/";
+var ROUTE_CACHE_KEY_PREFIX = /^route-cache\/[A-Z_]+\/[0-9a-f]{64}\/\$(?=\/)/;
+var INDEX_SUFFIX = "/index";
+var PAGES_DATA_PATHNAME = /^(.*)\/_next\/data\/[^/]+\/(.+)\.json$/;
+function groupPrerenders(prerenders) {
+  const htmlPathnames = new Set(
+    prerenders.map((p) => p.pathname).filter(
+      (p) => !p.endsWith(".rsc") && !p.includes(".segments/") && !PAGES_DATA_PATHNAME.test(p)
+    )
+  );
+  const groups = /* @__PURE__ */ new Map();
+  const variantsFor = (base) => {
+    let variants = groups.get(base);
+    if (!variants) {
+      variants = { segments: [] };
+      groups.set(base, variants);
+    }
+    return variants;
+  };
+  const routeOf = (base) => {
+    if (base.endsWith(INDEX_SUFFIX) && !htmlPathnames.has(base)) {
+      const parent = base.slice(0, -INDEX_SUFFIX.length) || "/";
+      if (htmlPathnames.has(parent)) {
+        return parent;
+      }
+    }
+    return base;
+  };
+  for (const prerender of prerenders) {
+    const { pathname } = prerender;
+    const dataRoute = PAGES_DATA_PATHNAME.exec(pathname);
+    if (dataRoute) {
+      variantsFor(routeOf(`${dataRoute[1]}/${dataRoute[2]}`)).data = prerender;
+    } else if (pathname.includes(".segments/")) {
+      variantsFor(routeOf(pathname.split(".segments/")[0])).segments.push(
+        prerender
+      );
+    } else if (pathname.endsWith(".rsc")) {
+      variantsFor(routeOf(pathname.slice(0, -".rsc".length))).rsc = prerender;
+    } else {
+      variantsFor(pathname).html = prerender;
+    }
+  }
+  return groups;
+}
+var NON_CACHEABLE_APP_PAGE_HEADERS = /* @__PURE__ */ new Set([
+  "content-type",
+  "vary",
+  "x-nextjs-prerender",
+  "x-nextjs-postponed"
+]);
+function appPageCacheHeaders(initialHeaders) {
+  const headers = {};
+  for (const [name, value] of Object.entries(initialHeaders)) {
+    if (!NON_CACHEABLE_APP_PAGE_HEADERS.has(name.toLowerCase())) {
+      headers[name] = value;
+    }
+  }
+  return headers;
+}
+var NEXT_CACHE_TAGS_HEADER = "x-next-cache-tags";
+function headerTags(value) {
+  const headers = value?.headers;
+  const header = headers?.[NEXT_CACHE_TAGS_HEADER];
+  return typeof header === "string" ? header.split(",").filter(Boolean) : [];
+}
+var INIT_CACHE_TAG_MANIFEST = "_cdk-nextjs-tag-manifest.json";
+
 // src/runtime/manifest.ts
 var ADAPTER_MANIFEST_VERSION = 1;
 var ADAPTER_DIR_NAME = "cdk-nextjs-adapter";
@@ -834,18 +990,6 @@ var ERROR_PAGE_SUFFIXES = [
 ];
 var RUNTIME_DIR_NAME = "cdk-nextjs-runtime";
 
-// src/utils/base-path.ts
-function normalizeBasePath(basePath) {
-  return (basePath || "").replace(/^\/+/, "").replace(/\/+$/, "");
-}
-function hasPathPrefix(path, prefix) {
-  return !!prefix && (path === prefix || path.startsWith(`${prefix}/`));
-}
-function basePathPrefix(basePath) {
-  const bare = normalizeBasePath(basePath);
-  return bare ? `/${bare}` : "";
-}
-
 // src/adapter/function-groups.ts
 var DEFAULT_FUNCTION_GROUP = "default";
 var FUNCTION_GROUPS_ENV_VAR = "CDK_NEXTJS_FUNCTION_GROUPS";
@@ -1532,6 +1676,12 @@ function withBasePath(path, basePath) {
   return path === "/" ? basePath || "/" : `${basePath}${path}`;
 }
 
+// src/utils/deployment-build-id.ts
+function deploymentBuildId(manifest) {
+  const { deploymentId } = manifest.config;
+  return deploymentId ? `${manifest.buildId}-${deploymentId}` : manifest.buildId;
+}
+
 // src/adapter/build-outputs.ts
 var ENV_FILES = [".env", ".env.production"];
 var RUNTIME_NEXT_MODULES = [
@@ -1671,6 +1821,7 @@ function buildAdapterManifest(ctx, options = {}) {
       }))
     } : {}
   };
+  assertBuildIdFits(manifest);
   const groups = assignment ? Object.entries(assignment.templates).map(([name, templates]) => ({
     name,
     dirName: groupStagingDirName(name),
@@ -1689,6 +1840,18 @@ function buildAdapterManifest(ctx, options = {}) {
   ];
   return { manifest, groups };
 }
+function assertBuildIdFits(manifest) {
+  const bytes = Buffer.byteLength(deploymentBuildId(manifest));
+  if (bytes > MAX_BUILD_ID_BYTES) {
+    const { what, fix } = manifest.config.deploymentId ? {
+      what: "The build ID and deploymentId together are",
+      fix: "Use a shorter deploymentId or generateBuildId."
+    } : { what: "The build ID is", fix: "Use a shorter generateBuildId." };
+    throw new Error(
+      `${LOG_PREFIX} ${what} ${bytes} bytes; cdk-nextjs stores cache entries under it and allows at most ${MAX_BUILD_ID_BYTES}. ${fix}`
+    );
+  }
+}
 function collectGroupStagingPlan(ctx, invocable, entrypoints, templates) {
   const basePath = ctx.config.basePath || "";
   const ownedEntrypoints = [
@@ -1798,7 +1961,7 @@ function collectStaticFiles(ctx) {
   const { repoRoot } = ctx;
   const basePath = ctx.config.basePath || "";
   const staticFiles = /* @__PURE__ */ new Map();
-  const pagesDir = join(ctx.distDir, "server", "pages") + sep;
+  const pagesDir = join(ctx.distDir, "server", "pages") + sep2;
   for (const output of ctx.outputs.staticFiles) {
     const key = toPosix(relative(repoRoot, output.filePath));
     const pathnames = routablePathnames(
@@ -1828,9 +1991,9 @@ function routablePathnames(pathname, basePath, fromPagesRouter) {
 }
 function stageServedStaticFiles(ctx, staging) {
   const { repoRoot, distDir } = ctx;
-  const clientStaticDir = join(distDir, "static") + sep;
+  const clientStaticDir = join(distDir, "static") + sep2;
   for (const output of ctx.outputs.staticFiles) {
-    const servedByS3 = output.filePath.startsWith(clientStaticDir) || !output.filePath.startsWith(distDir + sep);
+    const servedByS3 = output.filePath.startsWith(clientStaticDir) || !output.filePath.startsWith(distDir + sep2);
     if (servedByS3) {
       continue;
     }
@@ -1956,7 +2119,7 @@ async function stageFiles(staging, stagingDir) {
     }
     await mkdir(dirname(dest), { recursive: true });
     const resolved = resolve(dirname(dest), linkTarget);
-    if (resolved === stagingDir || resolved.startsWith(stagingDir + sep)) {
+    if (resolved === stagingDir || resolved.startsWith(stagingDir + sep2)) {
       await symlink(linkTarget, dest);
     } else {
       await cp(source, dest, { recursive: true, dereference: true });
@@ -2044,7 +2207,7 @@ function assertStagingKey(key, source) {
   }
 }
 function toPosix(path) {
-  return sep === "/" ? path : path.split(sep).join("/");
+  return sep2 === "/" ? path : path.split(sep2).join("/");
 }
 function sortedUnique(values) {
   return [...new Set(values)].sort();
@@ -2054,7 +2217,8 @@ function sortedUnique(values) {
 var import_debug = __toESM(require_src());
 import { existsSync as existsSync2 } from "node:fs";
 import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { createRequire as createRequire2 } from "node:module";
+import { dirname as dirname2, join as join2 } from "node:path";
 import { CachedRouteKind as CachedRouteKind2 } from "next/dist/server/response-cache/index.js";
 
 // src/adapter/cache-kinds.ts
@@ -2076,113 +2240,6 @@ function cacheKindResolver(outputs) {
   };
 }
 
-// src/adapter/cache-utils.ts
-function preprocessValue(value) {
-  if (value == null) {
-    return value;
-  }
-  if (Buffer.isBuffer(value)) {
-    return {
-      __type: "Buffer",
-      base64: value.toString("base64")
-    };
-  }
-  if (value instanceof Map) {
-    const entries = {};
-    for (const [key, val] of value.entries()) {
-      entries[key] = preprocessValue(val);
-    }
-    return {
-      __type: "Map",
-      data: entries
-    };
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => preprocessValue(item));
-  }
-  if (typeof value === "object") {
-    const processed = {};
-    for (const [key, val] of Object.entries(value)) {
-      processed[key] = preprocessValue(val);
-    }
-    return processed;
-  }
-  return value;
-}
-function serializeCacheValue(value) {
-  const processed = preprocessValue(value);
-  return JSON.stringify(processed);
-}
-function prerenderPathToCacheKey(pathname, basePath) {
-  const route = (hasPathPrefix(pathname, basePath) ? pathname.slice(basePath.length) : pathname).replace(/^\/+/, "");
-  return route === "" ? "index" : route;
-}
-var INDEX_SUFFIX = "/index";
-var PAGES_DATA_PATHNAME = /^(.*)\/_next\/data\/[^/]+\/(.+)\.json$/;
-function groupPrerenders(prerenders) {
-  const htmlPathnames = new Set(
-    prerenders.map((p) => p.pathname).filter(
-      (p) => !p.endsWith(".rsc") && !p.includes(".segments/") && !PAGES_DATA_PATHNAME.test(p)
-    )
-  );
-  const groups = /* @__PURE__ */ new Map();
-  const variantsFor = (base) => {
-    let variants = groups.get(base);
-    if (!variants) {
-      variants = { segments: [] };
-      groups.set(base, variants);
-    }
-    return variants;
-  };
-  const routeOf = (base) => {
-    if (base.endsWith(INDEX_SUFFIX) && !htmlPathnames.has(base)) {
-      const parent = base.slice(0, -INDEX_SUFFIX.length) || "/";
-      if (htmlPathnames.has(parent)) {
-        return parent;
-      }
-    }
-    return base;
-  };
-  for (const prerender of prerenders) {
-    const { pathname } = prerender;
-    const dataRoute = PAGES_DATA_PATHNAME.exec(pathname);
-    if (dataRoute) {
-      variantsFor(routeOf(`${dataRoute[1]}/${dataRoute[2]}`)).data = prerender;
-    } else if (pathname.includes(".segments/")) {
-      variantsFor(routeOf(pathname.split(".segments/")[0])).segments.push(
-        prerender
-      );
-    } else if (pathname.endsWith(".rsc")) {
-      variantsFor(routeOf(pathname.slice(0, -".rsc".length))).rsc = prerender;
-    } else {
-      variantsFor(pathname).html = prerender;
-    }
-  }
-  return groups;
-}
-var NON_CACHEABLE_APP_PAGE_HEADERS = /* @__PURE__ */ new Set([
-  "content-type",
-  "vary",
-  "x-nextjs-prerender",
-  "x-nextjs-postponed"
-]);
-function appPageCacheHeaders(initialHeaders) {
-  const headers = {};
-  for (const [name, value] of Object.entries(initialHeaders)) {
-    if (!NON_CACHEABLE_APP_PAGE_HEADERS.has(name.toLowerCase())) {
-      headers[name] = value;
-    }
-  }
-  return headers;
-}
-var NEXT_CACHE_TAGS_HEADER = "x-next-cache-tags";
-function headerTags(value) {
-  const headers = value?.headers;
-  const header = headers?.[NEXT_CACHE_TAGS_HEADER];
-  return typeof header === "string" ? header.split(",").filter(Boolean) : [];
-}
-var INIT_CACHE_TAG_MANIFEST = "_cdk-nextjs-tag-manifest.json";
-
 // src/adapter/init-cache.ts
 var debug = (0, import_debug.default)("cdk-nextjs:adapter");
 async function writeInitCache(ctx, cacheDir) {
@@ -2192,6 +2249,8 @@ async function writeInitCache(ctx, cacheDir) {
   debug(`Prerender groups: ${prerenderGroups.size} groups`);
   const cacheKindOf = cacheKindResolver(ctx.outputs);
   const tagManifest = {};
+  const scopesKeysByRoute = nextScopesKeysByRoute(ctx.projectDir);
+  const unscopedRoutes = [];
   for (const [basePath, variants] of prerenderGroups) {
     try {
       const kind = cacheKindOf(variants);
@@ -2212,12 +2271,12 @@ async function writeInitCache(ctx, cacheDir) {
       }
       let cacheEntry;
       if (kind === CachedRouteKind2.APP_PAGE) {
-        const html = await readPrerenderAsText(htmlPrerender);
+        const html = (await readPrerender(htmlPrerender))?.toString();
         if (!html) {
           debug(`SKIP: No HTML content for APP_PAGE ${basePath}`);
           continue;
         }
-        const rscData = await readPrerenderAsBuffer(rscPrerender);
+        const rscData = await readPrerender(rscPrerender);
         const segmentData = await getSegmentData(segmentPrerenders);
         const headers = appPageCacheHeaders(
           htmlPrerender?.fallback?.initialHeaders || rscPrerender?.fallback?.initialHeaders || {}
@@ -2238,7 +2297,7 @@ async function writeInitCache(ctx, cacheDir) {
           }
         };
       } else if (kind === CachedRouteKind2.APP_ROUTE) {
-        const body = await readPrerenderAsBuffer(htmlPrerender);
+        const body = await readPrerender(htmlPrerender);
         if (!body) {
           debug(`SKIP: No body content for APP_ROUTE ${basePath}`);
           continue;
@@ -2261,12 +2320,12 @@ async function writeInitCache(ctx, cacheDir) {
           );
           continue;
         }
-        const html = await readPrerenderAsText(htmlPrerender);
+        const html = (await readPrerender(htmlPrerender))?.toString();
         if (!html) {
           debug(`SKIP: No HTML content for PAGES ${basePath}`);
           continue;
         }
-        const pageDataJson = await readPrerenderAsText(dataPrerender);
+        const pageDataJson = (await readPrerender(dataPrerender))?.toString();
         cacheEntry = {
           lastModified: Date.now(),
           value: {
@@ -2287,14 +2346,16 @@ async function writeInitCache(ctx, cacheDir) {
         debug(`SKIP: Unsupported route kind ${kind} for ${basePath}`);
         continue;
       }
-      const cacheKey = prerenderPathToCacheKey(
-        basePath,
-        ctx.config.basePath || ""
+      const routeCacheKey = routeCacheKeyFromFilePath(
+        prerenderFilePath(htmlPrerender)
       );
-      const cacheFilePath = join2(cacheDir, `${cacheKey}.json`);
-      await mkdir2(join2(cacheDir, cacheKey.split("/").slice(0, -1).join("/")), {
-        recursive: true
-      });
+      if (!routeCacheKey && scopesKeysByRoute) {
+        unscopedRoutes.push(basePath);
+        continue;
+      }
+      const cacheKey = routeCacheKey ?? prerenderPathToCacheKey(basePath, ctx.config.basePath || "");
+      const cacheFilePath = join2(cacheDir, cacheObjectName(cacheKey));
+      await mkdir2(dirname2(cacheFilePath), { recursive: true });
       await writeFile2(cacheFilePath, serializeCacheValue(cacheEntry));
       for (const tag of headerTags(cacheEntry.value)) {
         (tagManifest[tag] ??= []).push(cacheKey);
@@ -2304,6 +2365,11 @@ async function writeInitCache(ctx, cacheDir) {
       console.error(`Error processing prerender group ${basePath}:`, error);
     }
   }
+  if (unscopedRoutes.length > 0) {
+    throw new Error(
+      `${LOG_PREFIX} Next.js ${ctx.nextVersion} wrote ${unscopedRoutes.length} prerender(s) outside <distDir>/server/route-cache/, so cdk-nextjs cannot tell the cache key it reads them back with: ${unscopedRoutes.slice(0, 5).join(", ")}${unscopedRoutes.length > 5 ? ", ..." : ""}`
+    );
+  }
   const taggedKeys = Object.keys(tagManifest).length;
   if (taggedKeys > 0) {
     await writeFile2(
@@ -2313,23 +2379,28 @@ async function writeInitCache(ctx, cacheDir) {
     debug(`Wrote ${INIT_CACHE_TAG_MANIFEST} with ${taggedKeys} tags`);
   }
 }
-async function readPrerenderAsText(prerender) {
-  if (prerender?.fallback && "filePath" in prerender.fallback && prerender.fallback.filePath && existsSync2(prerender.fallback.filePath)) {
-    return readFile(prerender.fallback.filePath, "utf-8");
+function nextScopesKeysByRoute(projectDir) {
+  try {
+    createRequire2(join2(projectDir, "package.json")).resolve(
+      "next/dist/server/lib/route-cache-key.js"
+    );
+    return true;
+  } catch {
+    return false;
   }
-  return void 0;
 }
-async function readPrerenderAsBuffer(prerender) {
-  if (prerender?.fallback && "filePath" in prerender.fallback && prerender.fallback.filePath && existsSync2(prerender.fallback.filePath)) {
-    return readFile(prerender.fallback.filePath);
-  }
-  return void 0;
+function prerenderFilePath(prerender) {
+  return prerender?.fallback && "filePath" in prerender.fallback ? prerender.fallback.filePath : void 0;
+}
+async function readPrerender(prerender) {
+  const filePath = prerenderFilePath(prerender);
+  return filePath && existsSync2(filePath) ? readFile(filePath) : void 0;
 }
 async function getSegmentData(segmentPrerenders) {
   const segmentData = /* @__PURE__ */ new Map();
   for (const segmentPrerender of segmentPrerenders) {
-    if (segmentPrerender.fallback && "filePath" in segmentPrerender.fallback && segmentPrerender.fallback.filePath && existsSync2(segmentPrerender.fallback.filePath)) {
-      const segmentContent = await readFile(segmentPrerender.fallback.filePath);
+    const segmentContent = await readPrerender(segmentPrerender);
+    if (segmentContent) {
       const segmentName = "/" + segmentPrerender.pathname.split(".segments/")[1].replace(/\.segment\.rsc$/, "");
       segmentData.set(segmentName, segmentContent);
     }

package/lib/adapter/aws-cache-store.d.ts

@@ -25,6 +25,8 @@ export declare function resolveAwsCacheConfig(): AwsCacheConfig;
  * which is what keeps it disjoint from {@link useCacheS3Key}.
  */
 export declare function buildS3Key(buildId: string, cacheKey: string): string;
+/** `{buildId}/` + {@link cacheObjectName}: the S3 object an entry is stored in. */
+export declare function s3ObjectKey(buildId: string, cacheKey: string): string;
 /**
  * The folder under the build prefix that `'use cache'` entries are stored in.
  * @see useCacheS3Key
@@ -36,8 +38,9 @@ export declare const USE_CACHE_KEY_PREFIX = "_use-cache";
  * Hashed because a `'use cache'` key is the serialized arguments of the call and
  * has no length limit, where an S3 key stops at 1024 bytes. The `.entry` suffix
  * rather than `.json` is what makes a collision with the incremental cache
- * impossible rather than unlikely: every key {@link buildS3Key} writes ends in
- * `.json`, including one for a route that happens to be named `/_use-cache/…`.
+ * impossible rather than unlikely: every object {@link s3ObjectKey} names ends
+ * in `.json` or `.long`, including one for a route that happens to be named
+ * `/_use-cache/…`.
  * Still under the build prefix, so post-deploy pruning drops them with the build.
  */
 export declare function useCacheS3Key(buildId: string, keyHash: string): string;
@@ -113,9 +116,29 @@ export declare const BATCH_GET_MAX_KEYS = 100;
  * revalidation log, the reads scale with instances instead of requests or tags.
  */
 export declare const DEFAULT_TAG_REFRESH_MS = 1000;
+/** DynamoDB's limit on a sort key, in UTF-8 bytes. */
+export declare const MAX_SORT_KEY_BYTES = 1024;
+/**
+ * `#<sha256(tag)>`, standing in for a tag in a sort key it would push past
+ * {@link MAX_SORT_KEY_BYTES}. Next.js caps the tags an app names, but not an
+ * implicit `_N_T_/…` tag, which is as long as its path, and a rejected write
+ * left `revalidatePath` on a long path recorded nowhere.
+ */
+export declare function hashedTag(tag: string): string;
+/**
+ * The longest tag a sort key spells out; past it, {@link sortKeyTag} hashes
+ * it. One cap for every row the tag is in, so a row's writer and reader agree
+ * without each working out what else shares its key. It leaves room for the
+ * most any row puts beside the tag: a mapping row's `#<buildId>/#<sha256>`,
+ * with the build ID capped at `MAX_BUILD_ID_BYTES`.
+ */
+export declare const MAX_TAG_BYTES = 768;
+/** `tag` as a sort key spells it: itself, or {@link hashedTag} past {@link MAX_TAG_BYTES}. */
+export declare function sortKeyTag(tag: string): string;
 /**
  * The bare-tag marker rows of the revalidation table (`pk = buildId`,
- * `sk = tag`), which record when a tag was last revalidated and how.
+ * `sk = tag`, or {@link hashedTag} past {@link MAX_TAG_BYTES}), which record when a tag
+ * was last revalidated and how.
  *
  * The table also holds the incremental cache's `tag#s3Key` mapping rows, which
  * are its own business and stay in `S3CacheHandler`: only the markers mean the
@@ -166,7 +189,8 @@ export interface RevalidationLogRow {
 /**
  * The revalidation log: one row per tag revalidation (`pk = <buildId>#log`,
  * `sk = <Date.now(), zero-padded>#<tag>`), which expires after
- * {@link REVALIDATION_LOG_TTL_MS}.
+ * {@link REVALIDATION_LOG_TTL_MS}. A tag past {@link MAX_TAG_BYTES} is
+ * {@link hashedTag} there, and spelled out in the row's `longTag` instead.
  *
  * The marker rows stay the source of truth. The log exists so an instance
  * can ask "what was revalidated since I last looked?" in one `Query`, instead