cdk-nextjs 0.6.2 → 0.7.0

package/docs/harness-coverage.md

@@ -0,0 +1,598 @@
+# Next.js compatibility harness — coverage record
+
+What has been run from [vercel/next.js's own e2e suite][harness] against a real
+cdk-nextjs deployment, and — for anything that fails — why, with a verdict on
+whether the failure is acceptable or a bug to fix.
+
+`test/deploy-tests-manifest.json` is the machine-readable half and the source of
+truth for what runs: `rules.include` (whole files) and `suites` (a file minus
+named cases). Nothing goes in either that has not been watched to pass. Its
+`excluded-notes` carries a one-line verdict for everything deliberately left out,
+pointing back here. See `scripts/e2e-harness/README.md` for how the harness works
+and how to screen a new candidate.
+
+## Verdict key
+
+| Verdict           | Meaning                                                                                        |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| **pass**          | Runs and passes against a real deployment. In `rules.include`.                                 |
+| **fixed**         | Failed, was root-caused to a cdk-nextjs defect, and the defect is fixed.                       |
+| **bug**           | Fails for a cdk-nextjs reason. Not acceptable. Fix it, then add the file.                      |
+| **upstream**      | Fails because of a bug in next.js or its fixture, not reachable from here.                     |
+| **unsupported**   | Fails because of a deliberate, documented product limitation or design choice. Acceptable.     |
+| **CDN-inherent**  | Fails for a reason true of any CDN-fronted deployment. Acceptable.                             |
+| **architectural** | Fails for a reason true of any distributed (multi-instance) cache handler. Acceptable.         |
+| **no signal**     | next.js skips or gates the file itself, or the fixture cannot be built here. Nothing measured. |
+
+"Acceptable" means understood and not worth fixing. Every **bug** should come back
+as a regression test once fixed.
+
+## Status
+
+As of 2026-09-23, against next.js 16.3.5. The screening funnel lives in the
+manifest's `screening` block, regenerated by
+`node scripts/e2e-harness/screen.mjs --next ../next.js --write` (`--check` to
+verify, which every e2e-harness run does in shard 1).
+
+| Of next.js's 1134 e2e files   | Count |
+| ----------------------------- | ----- |
+| edge-free (the hard ceiling)  | 931   |
+| candidates after every screen | **0** |
+| deployed and screened         | 472   |
+| in `rules.include`            | 427   |
+| plus, per-case, in `suites`   | 10    |
+
+The candidate pool is empty: every file is included, included per-case, or
+disqualified by a screen, and every disqualification that is a cdk-nextjs decision
+has a verdict below. The job now is keeping that true as next.js adds files and as
+each scheduled run re-runs what is already included.
+
+| Verdict       | Files                                                                                                                                                                                                                |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| pass          | 427 whole files, plus the passing cases of the 10 `suites` files                                                                                                                                                     |
+| fixed         | the defects in the table below                                                                                                                                                                                       |
+| bug           | none open                                                                                                                                                                                                            |
+| upstream      | 2 — `rewrites-destination-query-array`, `incremental-cache-path-traversal`                                                                                                                                           |
+| unsupported   | 4 whole files (`prerender-encoding`, `middleware-fetches-with-any-http-method`, `revalidate-dynamic`, `proxy-readable-toweb`), plus the skipped cases of `trailingslash`, `revalidate-path-with-rewrites` and the 6 `invalid-static-asset-404-*` files, and 203 files the edge screen disqualifies without deploying |
+| CDN-inherent  | the 4 skipped cases of `dynamic-route-interpolation`                                                                                                                                                                 |
+| architectural | the 2 skipped `resume-data-cache` cases                                                                                                                                                                              |
+| no signal     | 49 — 2 gated by next.js, 29 `skipDeployment` or stubbed in deploy mode, 18 `next-config-ts-native-ts` files that cannot be built here                                                                                |
+
+### Which types the harness proves
+
+The harness runs on all four types: the schedule on `NextjsGlobalFunctions`, the
+other three by `workflow_dispatch` (`nextjs_type`) or by hand, with
+`NextjsRegionalFunctions` behind `scripts/e2e-harness/stage-proxy.mjs`, which puts
+back the stage prefix the harness would otherwise drop. The findings whose
+plumbing differs per deployment type are also back-filled into
+`examples/e2e-tests` (run against `examples/app-playground` on all four types,
+every commit) — the "4-type spec" column of the table under "Fixed". What stays
+harness-only is what cannot coexist with the App Router fixture in one
+`next.config.ts` (`trailingSlash`, `assetPrefix`, `i18n`, the Pages Router) or has
+no per-type divergence (defect 25).
+
+### The 2026-09-29 runs, all four types
+
+The whole manifest, 15 shards per type, after the fixes of 2026-09-28/29:
+
+| Type                       | Result                                                                              |
+| -------------------------- | ----------------------------------------------------------------------------------- |
+| `NextjsRegionalContainers` | 437 / 437, no retries                                                               |
+| `NextjsRegionalFunctions`  | 434 / 435 (2 files in `excludeByType`); the one failure the `next-form` flake below |
+| `NextjsGlobalContainers`   | 411 / 414; all 3 failures and 23 unrun files on one shard, one hung `cdk deploy`    |
+
+What those fixes were, in the order the runs found them: the Global types'
+`NEXT_E2E_TEST_TIMEOUT` raised to 900000 for CloudFront updates; the Regional
+Functions runtime keeping `//` (`hydration`); the harness URL's host lowercased and
+the container health check moved to `/_next/static/` (it had been caught by
+fixtures' dynamic routes); and Global Containers building absolute URLs with the
+viewer's protocol (`action-forward-loop`: CloudFront reaches the ALB over HTTP
+without a certificate, so `x-forwarded-proto` said `http`).
+
+### Running on `NextjsRegionalFunctions`
+
+Run once, on 2026-09-24, behind the local stage proxy (`scripts/e2e-harness/README.md`,
+"Running on `NextjsRegionalFunctions`"): 22 files picked for what differs on that
+type, 17 green, no cdk-nextjs defect. The failures are what to expect on a re-run:
+
+| File                                                | Result  | Why                                                                                                                 |
+| --------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `app-dir/actions-streaming`                         | fails   | The action `fetch`es `location.origin` from the server — `127.0.0.1` from inside the Lambda. Local proxy only.      |
+| `app-dir/app-basepath`                              | 10 / 13 | Action `redirect()` streamed by a server-side fetch of the app's own origin (`ECONNREFUSED 127.0.0.1`). Same cause. |
+| `app-dir/redirect-rewrite-dynamic-basepath`         | 1 / 2   | Same, surfacing as a 500 from the runtime's error path.                                                             |
+| `invalid-static-asset-404-{app,pages}-asset-prefix` | fail    | Nothing serves `assetPrefix` on the regional types; cdk-nextjs warns at synth (`isAssetPrefixUnserved`).            |
+
+Then in CI on 2026-09-28, the whole manifest (437 files) in 10 shards: 428 green,
+8 of them only on retry, mostly `basePath` fixtures (the ~90s stage settle in the
+README). Beyond the table above, the same two causes failed four more files, and
+one failure was a cdk-nextjs defect. Everything but `hydration` is now in the
+manifest's `rules.excludeByType["regional-functions"]`:
+
+| File                                                                  | Result | Why                                                                                                                                                                                            |
+| --------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app-dir/asset-prefix-absolute`, `app-dir/asset-prefix-with-basepath` | fail   | `assetPrefix` is unserved on the regional types, as above; each logs the synth warning.                                                                                                        |
+| `next-form/default/app-dir`                                           | fails  | The action `redirect()`s, streamed by a server-side fetch of the app's own origin. Same cause as `app-basepath`.                                                                               |
+| `app-dir/action-forward-loop`                                         | fails  | Action forwarding fetches the request's own origin (`createForwardedActionResponse`, from `initURL`) — `127.0.0.1`. Same cause.                                                                |
+| `hydration`                                                           | 1 / 3  | **Defect, fixed:** API Gateway collapses `//` to `/` in `event.path`, so Next.js never redirected it and the page failed to hydrate at `//`. `apiGatewayRequestPath` now restores the slashes. |
+
+## Passing — in `rules.include`
+
+The list is the manifest's `rules.include`; it is not duplicated here. Notes worth
+having when one of them goes red:
+
+- **Retry passes.** `app-dir/router-autoscroll`, `app-dir/bfcache-regression` and
+  `app-dir/third-parties` each failed attempt 0 once on their own scroll or embed
+  assertions, with no cdk-nextjs error, and passed on retry 1. The harness runs
+  `--retries 1`. Suspect these first if a run goes red for no other reason.
+- **Slowest file:** `instrumentation-client-hook`, ~677s.
+- **Weakest coverage:** the three `chrome-devtools-workspace` files assert only
+  `status: 404` in deploy mode (the dev-only endpoint must not be reachable in
+  production). Real, but thin.
+- **Collapsed families:** `app-dir/next-config-ts/*` (21 files) and
+  `app-dir/next-config-ts-native-mts/*` (18) — each a distinct `next build` whose
+  resolved config the adapter reads back out of `required-server-files.json`; and
+  `app-dir/scss/*` (29 files), which on our side all test one thing: the emitted
+  stylesheet reaching the browser from S3. The only Sass coverage in the project.
+- **`handle-non-hoisted-swc-helpers`** is the one fixture pinning
+  `packageManager: npm`. Deploy mode sets `skipInstall`, so its non-hoisted
+  `node_modules` layout is never exercised — green means it builds and serves. See
+  "npm-pinned fixtures" under Debugging.
+- **`deprecation-warnings`** was once red on a harness bug: `scripts/e2e-logs.sh`
+  printed more than next.js treats as build logs. Its output _is_ `next.cliOutput`.
+- **`test-utils-tests/basic`** tests `nextTestSetup` itself — the harness contract,
+  not the adapter.
+
+## Passing in part — in `suites`
+
+A `suites` file is included with the cases in its `failed` array skipped
+(next.js's `test/get-test-filter.js` turns them into a negative
+`--testNamePattern`, so names must be full jest names, `describe` title included).
+Use this instead of dropping a whole file when the residual failures have a
+verdict below.
+
+| File                                                               | Cases      | Skipped, and why                                                                                |
+| ------------------------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------- |
+| `app-dir/trailingslash`                                            | 6 / 8      | 2 `should revalidate a page with generated static params` — unsupported (async invalidation)    |
+| `app-dir/resume-data-cache`                                        | 3 / 5      | 2 `should have consistent data between static and dynamic renders` — architectural              |
+| `dynamic-route-interpolation`                                      | 3 / 7      | 4 requesting unencoded `[`/`]` — CDN-inherent                                                   |
+| `app-dir/revalidate-path-with-rewrites`                            | 1 / 2      | `static page` — unsupported (async invalidation)                                                |
+| `invalid-static-asset-404-app` (+ `-asset-prefix`, `-base-path`)   | 2 / 3 each | `should return 404 with plain text when fetching invalid asset path` — S3's XML 404, unsupported |
+| `invalid-static-asset-404-pages` (+ `-asset-prefix`, `-base-path`) | 2 / 3 each | Same case, same reason                                                                          |
+| `next-form/default/app-dir`                                        | 13 / 14    | `flakey`: `should soft-navigate on submit and show the prefetched loading state` — timing        |
+
+The `next-form` case submits right after the page loads and waits for the loading
+state the router prefetched; where the prefetch has not landed, `#loading` never
+renders. It failed both attempts on Regional Functions and on both Containers
+types at least once in the 2026-09-28/29 runs, and passed on each of them in
+another, with no cdk-nextjs error.
+
+## Fixed
+
+`#` labels a row for the rest of this doc. **23**, **37** and **38** were found by
+the four-type suite (`examples/e2e-tests`) rather than the harness: 23 is under
+"Stale-while-revalidate after a tag revalidation", 37 and 38 follow the table.
+There is no **28**: the number was skipped, not withdrawn. So 34 of the 37 fixed
+defects came from the harness and 3 from the four-type suite.
+
+"4-type spec" names the `examples/e2e-tests/src/*.test.ts` file guarding it on all
+four deployment types; `—` means harness or unit tests only.
+
+| #   | Symptom (as a test sees it)                                                                                  | Root cause                                                                                                                          | Fix / guard                                                                                                           | 4-type spec                                                    |
+| --- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| 1   | Every POST with a body (server actions) → `403 InvalidSignatureException`                                    | `patchFetchInClientJs` ran inside `runNextBuild()`, so `skipBuild: true` shipped an unpatched client with no `x-amz-content-sha256` | Call moved to the `NextjsBuild` constructor, marker-guarded against double wrap. The harness is the `skipBuild` guard | `request-methods` (in-page POST ok, raw POST 403)              |
+| 2   | RSC responses labeled `text/html`; navigation duration `NaN`; action `redirect()` with no head               | Seeded the HTML prerender's `initialHeaders` (`content-type`, `vary`, `x-nextjs-prerender`/`-postponed`) into `APP_PAGE` entries    | `appPageCacheHeaders`, `src/adapter/cache-utils.ts`                                                                   | `rsc-navigation`                                               |
+| 3   | Empty streamed response: Function URL drops the prelude (bare `200 octet-stream`), API Gateway `502`         | `RESPONSE_STREAM` with zero bytes after the prelude delimiter                                                                       | `ResponseSink.padEmptyBody` (one space byte), `src/runtime/http/sink.test.ts`                                         | `response-bodies`, `request-methods`, `server-action-redirect` |
+| 4   | Client navigation to `/` → 404, `x-nextjs-cache: HIT`, empty body                                            | `groupPrerenders` rebuilt `${route}.rsc`; the root's payload is `/index.rsc`                                                        | `groupPrerenders`, `src/adapter/cache-utils.ts`                                                                       | `rsc-navigation`                                               |
+| 5   | `[id]/[id2]`: second param is the first's value plus `2`                                                     | `@next/routing` substitutes `$nxtP*` placeholders in insertion order, so a prefixing name is mangled                                | `repairRouteParamQuery`, `src/runtime/dispatch.ts`                                                                    | `routing-params`                                               |
+| 6   | `trailingSlash: true` — every canonical `/a/` URL 404s                                                       | Output pathnames never carry the slash; `@next/routing` matches exactly                                                             | `withTrailingSlashVariants`, `Dispatcher.normalizePathname`                                                           | —                                                              |
+| 7   | `next build` fails: "encountered uncached or runtime data during prerendering" (`cacheComponents` + handler) | Build-time cache handler was write-only; the final prerender pass re-issued fetches                                                 | `LocalFileCacheHandler.get`; `cache-handler.test.ts`                                                                  | —                                                              |
+| 8   | `revalidateTag` never reaches a build-time prerender; tagged entries evicted right after storing             | Handler read a `tags` array only runtime `set` writes, not `x-next-cache-tags`; mapping rows stamped `revalidatedAt = now`          | `entryTags`, `checkIfRevalidated`, per-tag marker row — `src/adapter/s3-cache-handler.ts`                             | —                                                              |
+| 9   | Origin re-renders after `revalidatePath`, browser still gets the old page (`x-cache: Hit from cloudfront`)   | Invalidation paths came only from tag mapping rows, which build-time prerenders lack                                                | `implicitTagPath`/`invalidationVariants`; the build's tag manifest (s3-cache-handler)                          | —                                                              |
+| 10  | Fixture _n+1_ serves fixture _n_'s pages (another app's `/_not-found`)                                       | With `NEXT_DEPLOYMENT_ID` set, next's `BUILD_ID` is the constant `build-TfctsWXpff2fKS`; our cache is partitioned by build id       | `NextjsBuild.buildId` suffixes the manifest's `deploymentId` (`src/nextjs-build/nextjs-build.ts`)                     | —                                                              |
+| 11  | Unmatched optional catchall renders a segment `"undefined"`                                                  | `@next/routing` reports an unfilled param as a present key with value `undefined`                                                   | `repairRouteParamQuery` second pass; `dispatch.test.ts`                                                               | `routing-params`                                               |
+| 12  | `robots.txt`, `sitemap.xml`, `manifest.webmanifest` served as `application/octet-stream`                     | Static metadata staged as `<route>.body`; `send` types by extension                                                                 | `setBodyFileContentType`, `src/runtime/static-files.ts`                                                               | `metadata-routes`                                              |
+| 13  | Root-params app (no `app/layout.tsx`) 404s at every URL                                                      | next gates the `dynamicRoutes` rule on draft cookies; concrete prerenders were not registered                                       | `addPrerenderPathnames`, `src/adapter/build-outputs.ts`                                                               | `draft-mode`, `cookies` (cookie half only)                     |
+| 14  | PPR fallback shell rendered per request (`(runtime)` where `(buildtime)` expected)                           | Seeding loop skipped every prerender group whose pathname contains `[`                                                              | Prerender-group loop in `writeInitCache`, `src/adapter/init-cache.ts`; `init-cache.test.ts`                           | —                                                              |
+| 15  | Custom `pages/404` replaced by the built-in 404                                                              | `statusTarget` tried `/_error` before an invocable `/404`                                                                           | `statusTarget`; `dispatch.test.ts` "prefers an invocable custom /404 over /\_error"                                   | —                                                              |
+| 16  | Path-style `assetPrefix` — every bundle 404s                                                                 | No CloudFront behavior for `<prefix>/_next/static*`; Next applies `assetPrefix` on top of `basePath`                                | `relativeAssetPrefix`, `NextjsDistribution.addAssetPrefixBehavior` (CF function); regional types warn at synth        | —                                                              |
+| 17  | Pages Router home page `/` 404s (many unrelated-looking symptoms)                                            | `normalizePagePath("/")` is `/index`; nothing registered `/`                                                                        | `routablePathnames`, `src/adapter/build-outputs.ts`                                                                   | —                                                              |
+| 18  | Space in a `public/` filename fails synth: "Invalid CloudFront Distribution Cache Behavior Path Pattern"     | Characters outside CloudFront's path-pattern alphabet threw                                                                         | `toPathPattern` (`src/nextjs-distribution.ts`); `NextjsApi` warns and skips on Regional Functions. See 37             | `static-assets` (asserts 404 on Regional Functions)            |
+| 19  | A throw answers plain-text 500, never the app's error page                                                   | No error-page ladder; one `failWith` wrote a bare 500                                                                               | `resolveErrorTarget` (dispatch.ts) + `NextjsRuntime.sendError`, `no-store`                                            | `status-codes` (App Router side)                               |
+| 20  | Every i18n app answers `/` with a 308 to `/en-US`                                                            | `@next/routing` builds `/${locale}/`, which the trailing-slash 308 then matches                                                     | `Dispatcher.withRootLocale`, `normalizeRedirectLocation`                                                              | —                                                              |
+| 21  | Static `getStaticProps` data route 404s, so client navigation into it full-reloads                           | Without middleware, next emits no rule for it; the concrete prerender was skipped                                                   | `addPrerenderPathnames` registers concrete `/_next/data/…json` when no ungated rule matches                           | —                                                              |
+| 22  | Absolute `assetPrefix` with a path — every bundle 404s                                                       | The prefix's path was reduced to `""`, so no behavior was added                                                                     | `assetPrefixPath`, `src/utils/base-path.ts`                                                                           | —                                                              |
+| 24  | `/_next/image` 400s for a `public/` file whose name needs percent-encoding                                   | `fetchFromS3` used the still-encoded href as the S3 key                                                                             | Tolerant percent-decode in `fetchFromS3`, `src/runtime/image-utils.ts`                                                | `static-assets` (asserts `image/webp`)                         |
+| 25  | A web worker never starts (assertion times out on placeholder text)                                          | `patch-fetch.js` was prepended to `turbopack-worker-*.js` and read `window`                                                         | `patch-fetch.js` uses `globalThis`; worker-scope block in `patch-fetch.test.ts`                                       | —                                                              |
+| 26  | Large init cache only partly seeded (`MISS`, postponed shell); deploy reported success                       | `BucketDeployment` Lambda hit `ENOSPC` in 512 MiB `/tmp`; `--hotswap` ignores a custom resource's `FAILED`                          | `sizeDeploymentLambda`, `src/nextjs-cache.ts`                                                                         | —                                                              |
+| 27  | A 1 MB segment prefetch takes ~5s                                                                            | Buffers serialized as JSON integer arrays and parsed with a reviver                                                                 | Base64 in `serializeCacheValue`/`parseCacheValue` (old format still readable)                                         | —                                                              |
+| 29  | A `beforeFiles` rewrite that matches its own output is applied twice                                         | `RouteModule.prepare` re-runs `handleRewrites` on the already-rewritten `req.url`                                                   | `src/runtime/core.ts` hands `requestMeta.query` the resolved query                                                    | `config-routing`                                               |
+| 30  | `//` → 500, `/api//json` → 404, instead of a 308                                                             | `resolveRoutes` does not collapse repeated slashes; `new URL("//")` reads a host                                                    | Collapse + 308 in `src/runtime/core.ts`, ahead of any parsing                                                         | `url-normalization`                                            |
+| 31  | On Global Functions, `//` paths → `403 InvalidSignatureException`                                            | OAC signs the raw path, the Function URL canonicalizes before verifying                                                             | Viewer-request function, `createDynamicCloudFrontFunctionAssociations`                                                | `url-normalization` (`FunctionGeneratedResponse`)              |
+| 32  | Build-time `notFound: true` served as `200` with the 404 body                                                | Seeded a `PAGES` entry holding `404.html`; the Pages HIT path ignores `value.status`                                                | `writeInitCache` skips a `PAGES` prerender whose `initialStatus` ≠ 200; `init-cache.test.ts`                          | `status-codes` (App Router half)                               |
+| 33  | `res.revalidate()` fails (`{revalidated:false}`), reason reports `stale`                                     | No `routerServerContext.revalidate` supplied: "missing internal router-server-methods"                                              | `requestMeta.revalidate` in `src/runtime/core.ts`; `core.test.ts`                                                     | —                                                              |
+| 34  | Untagged `force-cache` fetch is never evicted by `revalidatePath`/`revalidateTag`                            | Fetch entries were checked against their stored tags, not the request's `ctx.tags` + `ctx.softTags`                                 | `isFetchCacheGet` split in `S3CacheHandler.get`                                                                       | —                                                              |
+| 35  | Catch-all capture containing `%2F` → 500 ("Requested and resolved page mismatch")                            | The `nxtP` query contract decodes twice and splits on `/`                                                                           | `outOfBandRouteParams` (dispatch.ts) passes `requestMeta.params`. Verified offline; the file is upstream              | —                                                              |
+| 36  | Regional Functions: every redirect drops the stage prefix, following it → 403                                | API Gateway strips the stage before invoking the Lambda                                                                             | `src/runtime/api-gateway-path.ts` uses `requestContext.path` when `basePath` starts with the stage                    | `url-normalization` (where it was found)                       |
+
+Found by the four-type suite:
+
+- **37** — defect 18's first fix wrote one `?` per _percent-encoded_ character.
+  CloudFront URL-decodes the path before matching and `?` matches one byte of the
+  decoded path, so `toPathPattern` writes one `?` per UTF-8 byte. A top-level
+  `public/` name with no character CloudFront can spell would become a pattern of
+  wildcards alone that captures unrelated app routes, so it gets **no behavior**
+  and a synth warning; its files reach the server, which reads them from S3.
+  Don't go back to per-encoded-character
+  patterns: they synthesize, deploy, and never match. The harness's
+  `next-image-legacy/unicode` could not catch it — the image optimizer reads S3
+  directly — `static-assets.test.ts` did.
+- **38** — `NextjsRegionalContainers` served no `public/` file (the adapter API
+  lists `public/` in `staticFiles` only for `output: "export"`). The container
+  runtime now lists `public/` off disk at cold start the way `next start` does
+  (`src/runtime/public-files.ts`), ahead of app routes; the Lambda types have no
+  `public/` in the package and rely on the distribution routing it to S3.
+
+## Upstream — a fixture that cannot pass as written
+
+### `incremental-cache-path-traversal` asserts a 200 for a param shape that throws
+
+1 of 1. Filed as [vercel/next.js#99154](https://github.com/vercel/next.js/issues/99154).
+The file requests `/_next/data/<buildId>/pages-cache/..%2F..%2Fserver-reference-manifest.json`
+and, in its `isNextDeploy && isAdapterTest` branch, asserts status 200 _together
+with_ `pageProps.rest` equal to `['..', '..', 'server-reference-manifest']`. That
+array is exactly the shape `normalizePagePath` rejects (`Requested and resolved
+page mismatch`), and `cacheKey` is passed to `handleResponse` regardless of minimal
+mode, so the two assertions cannot both hold on 16.3.5. The runtime 500 behind it
+is fixed (defect 35: we now answer 200, byte-identical to `next start`). Its
+`describe.skip` is conditional on `__NEXT_CACHE_COMPONENTS`, which the harness does
+not set, so the screen does not remove it. **Recheck:** when #99154 lands, run it
+offline first (`scripts/e2e-offline.sh incremental-cache-path-traversal`).
+
+## Upstream — a bug in the adapter routing library
+
+### A rewrite destination's repeated query key is collapsed to its last value
+
+`rewrites-destination-query-array` (1 of 1). Filed as
+[vercel/next.js#99155](https://github.com/vercel/next.js/issues/99155). A rewrite
+to `/?items=1&items=2` reaches the page as `items: "2"`, so
+`props.query.items.join(',')` throws and we answer 500 where `next start` renders
+`1,2`. The loss is two `URLSearchParams#set` calls (should be `append`) in
+`@next/routing@16.3.5`:
+
+```
+packages/next-routing/src/destination.ts:63      newUrl.searchParams.set(key, value)
+packages/next-routing/src/resolve-routes.ts:312  mergedUrl.searchParams.set(key, value)
+```
+
+`next start` uses its in-tree `router-server` and is unaffected. By the time
+`resolveRoutes` returns one value is gone; our `formatTarget` round-trips repeated
+keys fine. No patch point — the library is a published dependency of `next`.
+**Recheck:** `scripts/e2e-offline.sh rewrites-destination-query-array` (500 vs 200
+off the same build today); requeue when the fix ships.
+
+## Unsupported — a product limitation
+
+### `dynamicParams = false`
+
+`app-dir/prerender-encoding` (1 of 1). Not an encoding bug — dispatch resolves
+`/sticks%20%26%20stones` to `nxtPid = "sticks & stones"` correctly. With
+`export const dynamicParams = false`, Next.js gates the route's
+`routing.dynamicRoutes` entries behind the preview cookies (`__prerender_bypass`,
+`__next_preview_data`), expecting the platform to serve concrete prerendered paths
+off the CDN and 404 everything else. cdk-nextjs registers only dynamic templates
+(`addPrerenderTemplates`, `src/adapter/build-outputs.ts`), so every param 404s —
+`/plain` too. Removing the flag from a copy of the fixture makes both resolve.
+
+Supporting it means routing concrete prerendered paths to the owning entrypoint
+while still supplying the template's `nxtP*` params, which done naively makes
+`/isr/1` resolve to itself and lose `nxtPid` (see `addPrerenderTemplates`'s
+comment). A design change; do it if a user asks. Defects 13 and 21 register
+concrete pathnames in narrower cases (gated-only, and data routes with no ungated
+rule). Side note: an unencoded `&` in a path parses as a query separator
+(`/a&b` → `{nxtPid: "a", b: ""}`), matching Vercel.
+
+## Unsupported — the edge runtime
+
+cdk-nextjs refuses at build time to deploy any output whose runtime is not
+`nodejs` (`assertNodeRuntimes`, `src/adapter/build-outputs.ts`): the edge runtime
+is deprecated, and cdk-nextjs supports the Node-runtime `proxy.ts` instead of
+legacy edge `middleware.ts`. The check throws during `next build`, so a fixture
+with _any_ edge route or legacy middleware fails wholesale and `suites` cannot
+rescue it. Both spellings count: `export const runtime = 'edge'` and
+`export const config = { runtime: 'experimental-edge' }` — screening only the first
+undercounts. 203 of 1134 files are disqualified this way.
+
+| File                                      | Why                                                                                                                                               |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app-dir/app-static`                      | ~10 `*-edge` routes. Worth mining for individual cases to port: the densest ISR/caching coverage upstream.                                        |
+| `app-dir/actions/app-action`              | Ships a legacy edge `middleware.js`.                                                                                                              |
+| `middleware-rewrites/test/index`          | Ships a legacy edge `middleware.js`.                                                                                                              |
+| `middleware-fetches-with-any-http-method` | Writes its edge middleware inline via `nextTestSetup({ files })`, so `screen.mjs`'s on-disk grep missed it; failed in 7s on `assertNodeRuntimes`. |
+
+The `middleware` screen's count is a floor: an inline-`files` fixture only shows up
+as a ~7s build failure naming `assertNodeRuntimes`.
+
+## Unsupported — a design choice
+
+### A missing `/_next/static/*` is a 404 from S3, not from Next.js
+
+The 6 `invalid-static-asset-404-*` files, 1 of 3 cases each (via `suites`). The
+case wants a `404` with body exactly `Not Found` for a nonexistent static asset.
+S3 behind Origin Access Control answers the `404` itself (the OAC principal has
+`s3:ListBucket`, so S3 may say a key is absent) with its XML `NoSuchKey` body.
+Matching the body would take a Lambda@Edge origin-response rewrite for one
+assertion. Not done. Real-app cost: none beyond the body. The two passing cases
+(valid asset → 200, invalid non-asset path → the app's 404 page) show Next.js's
+own handling is intact.
+
+### A `POST` body from a non-browser client needs a payload hash
+
+`proxy-readable-toweb` (2 of 2, excluded outright). Both cases `POST` JSON from
+the jest process and get `403 InvalidSignatureException`. CloudFront's OAC signs
+the origin request to a Lambda Function URL but supplies only the empty-body hash,
+so the viewer must send `x-amz-content-sha256` (defect 1's root cause from the
+other side). Measured: with the header the request reaches the origin; without it, 403. cdk-nextjs covers the browser (`src/nextjs-build/patch-fetch.js` in the client
+bundle); `next.fetch` is plain Node `fetch` in an unmodified next.js checkout. The
+README's Limitations states it: on `NextjsGlobalFunctions` a non-browser caller
+must hash a `POST`/`PUT` body. The Node-runtime proxy itself is covered by four
+`proxy-*` files in `rules.include`.
+
+### Revalidation re-requested about a second later
+
+`app-dir/revalidate-dynamic` (2 of 2, excluded outright),
+`app-dir/revalidate-path-with-rewrites` (`static page`) and `app-dir/trailingslash`
+(2 of 8), the latter two via `suites`. Each loads a prerendered page, revalidates
+via a route handler (which returns `revalidated: true`), refreshes, and expects new
+content. The refresh is served from the edge — prerendered pages come back
+`cache-control: s-maxage=31536000` and the second request reports
+`x-cache: Hit from cloudfront`. cdk-nextjs does invalidate (defect 9, including
+build-time prerenders), but `CreateInvalidation` is fire-and-forget with no bounded
+completion time. The discriminator is how long the case waits: next.js's `retry()`
+(`test/lib/next-test-utils.ts`) defaults to 3000ms; `segment-cache/prefetch-inlining`
+passes 15000 and is green, these take the default or re-request immediately.
+Vercel purges its CDN synchronously, which is why upstream does not gate these.
+Making them pass would mean blocking every revalidation on an invalidation.
+
+**Tell for a real regression instead:** the _same_ random value across every
+attempt, on a case with no prerender to invalidate. That was defect 34 — the
+`dynamic page` case of `revalidate-path-with-rewrites` had passed once by luck.
+
+### A test's `env` reaches `next build`, not the deployed app
+
+Per-test `env` from `nextTestSetup({ env })` is set for `next build`, so values
+inlined at build time work, but not on the deployed function or task: a
+request-time read of a non-inlined `process.env` value returns `undefined`.
+next-deploy.ts hands the deploy script the test's `env` merged into the runner's
+whole environment, so the script can't tell them apart, and forwarding it all
+would also forward the runner's AWS credentials. No file in the manifest hits this.
+
+## CDN-inherent — excluded, acceptable
+
+### CloudFront rejects unencoded `[` and `]` in a path
+
+`dynamic-route-interpolation`, 4 of 7 (the other 3 via `suites`). The four request
+literal brackets (`/blog/[slug]`, `/api/dynamic/[abc]`) and CloudFront answers
+before the Lambda:
+
+```
+$ curl -sg --path-as-is -D - -o /dev/null 'https://…/blog/[slug]'
+HTTP/2 400
+content-length: 0
+x-cache: Error from cloudfront
+```
+
+Percent-encoded (`/blog/%5Bslug%5D`) the same routes render correctly. `[`/`]`
+are `gen-delims` and not legal in a path, so CloudFront is conformant.
+
+## Architectural — excluded, acceptable
+
+### Stale-while-revalidate after a tag revalidation
+
+`app-dir/resume-data-cache`, 2 of 5 (the `it.each` "should have consistent data
+between static and dynamic renders" cases; the other 3 via `suites`). Each
+revalidates a tag and asserts the next dynamic RSC request still returns the
+**stale** value once. cdk-nextjs is _too fresh_. Next.js tracks tag staleness in
+`tagsManifest`, an in-process `Map`
+(`packages/next/src/server/lib/incremental-cache/tags-manifest.external.ts`), and a
+cache handler has no channel for "stale, serve it anyway": `lastModified: -1`
+forces a blocking render. Fixing it needs Next.js to expose tag staleness to the
+handler interface.
+
+Don't "fix" it by returning `null` instead: on a PPR route with a `fallback` a hard
+miss is answered from the fallback shell — uncacheable, never upgraded — which was
+defect 23. Our handler returns `{ lastModified: -1, value }` for every tag-expired
+response entry, and still deletes/returns `null` for a fetch entry.
+
+The "fetch cache" case would also fail on its own: it prefetches the same URL with
+the same `_rsc` hash as the "use cache" case, and CloudFront returns the earlier
+payload — the problem next.js's `cdn-cache-busting` gates out itself.
+
+## No signal — next.js skips these itself
+
+| File                                                                    | Why                                                                                                          |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `app-dir/segment-cache/refresh`                                         | `describe.skip` upstream ("Disabled because too flaky"). "Passes" in ~5s without deploying.                  |
+| `app-dir/segment-cache/cdn-cache-busting`                               | next.js skips it under `isNextDeploy` — deploy mode gating out what cannot work behind a CDN.                |
+| `app-dir/app-fetch-deduping`                                            | Branches on `isNextStart`/`isNextDev` only; deploy mode gets `it('should skip other scenarios')`. 4s.        |
+| `cpu-profiling/cpu-profiling-dev`                                       | `if (!isNextDev) { it('skip…'); return }` _after_ `nextTestSetup` — a full 187s deploy that asserts nothing. |
+| `invalid-server-options`                                                | Calls `next()` in-process and asserts on option-validation errors. Nothing built or deployed. 3.5s.          |
+| `next-dynamic-lazy-compilation`                                         | Returns early under `shouldUseTurbopack()`, and the harness sets `IS_TURBOPACK_TEST=1`. Webpack-only. 5.1s.  |
+| `skipDeployment: true` files (manifest key `skipDeployment, 236 files`) | See "The `skipDeployment` traps" below.                                                                      |
+
+## No signal — the fixture cannot be built here
+
+### `next-config-ts-native-ts/**` needs a `next build` flag the harness does not pass
+
+All 18 files fail in `next build` with `ERR_REQUIRE_ASYNC_MODULE` or
+`ReferenceError: await is not defined`. Every fixture uses top-level `await` in
+`next.config.ts`, which only Node's native TS loader handles; that loader is gated
+on `__NEXT_NODE_NATIVE_TS_LOADER_ENABLED`, set only by
+`next build --experimental-next-config-strip-types`. A plain `next build` of a copy
+with no adapter fails identically; with the flag it succeeds.
+
+Adding the flag to `scripts/e2e-deploy.sh` would apply to the whole run and move
+the 21 green `next-config-ts/*` files off the swc-transpile path they exist to
+cover; the harness cannot set per-fixture build flags. The one question these files
+ask cdk-nextjs — does `modifyConfig` still apply through the native loader? — is
+asserted on every PR by `scripts/zero-config-build.mjs`. `next-config-ts-native-mts/**`
+needs no flag (`.mts` is ESM either way) and is green.
+
+## Debugging a harness failure
+
+### Reading a harness log
+
+- **Wholesale failure at ~120s or ~240s** with
+  `Exceeded timeout of … ms for a hook` in `beforeAll`: the deploy outran jest's
+  hook timeout (`NEXT_E2E_TEST_TIMEOUT`); nothing was asserted. Read the retry, not
+  attempt 0, and read durations, not case names — a file can report 8 of 8
+  "routing" cases failing when none ran. A deploy that suddenly takes a full
+  CloudFormation update (~110s+) instead of a hotswap (~50s) is the usual cause —
+  e.g. churning bucket `Tags` once did this; see the README. On the Global
+  types, `rejected changes: DistributionConfig` in the log means a CloudFront
+  update, which takes 8-10 minutes; if the next file logs `an earlier cdk deploy
+  … is still running; waiting`, it is waiting on that update, not failing on its
+  own. A wait that ends in `outlived 600s; stopping it` means the earlier deploy
+  hung: that file failed on it, and this one starts from a clean slate.
+- **A pass in under ~10s deployed nothing.** A real file spends 100s+ on
+  `next build` plus a hotswap. `run-tests.js --timings` prints per-file duration —
+  the only signal for a passing file, since output prints on failure only.
+- **But a slow pass can still be empty:** check for an early `return` after
+  `nextTestSetup` (`cpu-profiling-dev`) alongside the timing, not instead of it.
+- **Playwright traces** land in `test/traces/` (`run-tests.js` sets
+  `TRACE_PLAYWRIGHT=true`). The `0-trace.network` entry shows every request's real
+  status and headers — this is how defect 1's 403s were found while the Lambda's own
+  logs were clean, and how defect 23's fallback shell was spotted.
+- **Server logs:** `scripts/e2e-logs.sh` output _is_ `next.cliOutput`; anything
+  extra it prints can fail log-asserting fixtures (`deprecation-warnings`).
+
+### The `skipDeployment` traps
+
+- `nextTestSetup({ skipDeployment: true })` replaces the file with
+  `it.only('should skip next deploy')` (`test/lib/e2e-utils/index.ts`): a ~4s pass,
+  nothing deployed. Two files once sat in `rules.include` on such a pass.
+  `screen.mjs` disqualifies it.
+- **It is not always in the test file.** It can be in a sibling `shared.util.ts`, or
+  the test is a two-line `require('./client.test')` wrapper
+  (`app-dir/cache-components-errors/*`). `screen.mjs` follows relative
+  imports two levels deep for this screen only; mode-gate screens stay
+  test-file-only, since a helper's `isNextDev` branch may cover only some cases.
+- **`skipDeployment: !isAdapterTest` is different.** Ten files gate on
+  `NEXT_ENABLE_ADAPTER === '1'`; unset, they take the skip path (how
+  `partial-fallback-shell-upgrade` "passed" in 5.4s once). The harness exports
+  `NEXT_ENABLE_ADAPTER=1`, and `screen.mjs` deliberately does not disqualify these.
+- **Mode gates after `nextTestSetup`** cost a full deploy and prove nothing, and
+  the `mode-gated` screen cannot see them.
+
+### `NEXT_PRIVATE_TEST_MODE` is what makes a PPR response splittable
+
+PPR tests split the body on `<!-- PPR_BOUNDARY_SENTINEL -->`
+(`splitResponseWithPPRSentinel`, `test/lib/e2e-utils/ppr.ts`). The sentinel is
+emitted only under `process.env.__NEXT_TEST_MODE`, a build-time constant inlined by
+`define-env.ts`; the harness's `next.config` snippet aliases
+`NEXT_PRIVATE_TEST_MODE` → `__NEXT_TEST_MODE`, and `scripts/e2e-deploy.sh` exports
+it. Without it everything lands in `static$` and every "dynamic part not in the
+static part" assertion fails — a missing env var, not a defect. It once masked
+defect 14: after the var was set, `sub-shell-generation` still failed 6 of 7 but on
+a _different_ assertion. **If the shape of a failure changes after an environment
+fix, there is a second problem.**
+
+### Reproduce offline against `next start` on the same build
+
+`scripts/e2e-offline.sh <fixture>` builds the fixture through the adapter and
+serves it twice — our container shell and `next start` — so a disagreement is one
+`diff` of two responses (see the README, "Debugging one failing file without
+deploying"). Defects 11, 13, 14, 15, 20, 21, 22, 33 and 35 and both upstream
+verdicts were settled this way. Limits:
+
+- The runtime cache reads S3 only, so a fully-prerendered route answers
+  `invariant: cache entry required but not generated` offline. Read the seed
+  directory (`.next/cdk-nextjs-init-cache`) instead — it is how defect 14's missing
+  shells were found (the seeding loop had no jest coverage then).
+- **Offline agreement only rules out the request path, not the deploy.** Seeding
+  happens in the `BucketDeployment`, so an offline app has no seeded cache. Defect
+  32 agreed offline (both 404) and was a seeding bug.
+- For a question below the HTTP layer, call the library directly: defect 11 ran
+  `resolveRoutes` from a shell; defect 35 fed candidate param shapes to next's built
+  `dist` to find which one `_getPathname` accepts.
+- An oracle `next start` also settles "is this ours?" for deployed-type runs: the
+  Regional Functions back-fill ran `next start` on the same build with the same
+  `basePath` (`NEXTJS_BASE_PATH=/prod`) and found two failures that were the test's
+  own bug, one wrong expectation, and one real defect (36).
+
+### Who answered? Reading response headers
+
+| You see                                                                           | It means                                                                                                                                        |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `x-cache: Hit from cloudfront`                                                    | Edge cache served it; the origin never saw the request (stale content after a revalidate: invalidation timing).                                 |
+| `x-cache: Error from cloudfront`, `400`, `content-length: 0`                      | CloudFront rejected the request itself (e.g. literal `[`/`]`).                                                                                  |
+| A `400` with no `x-amzn-*` headers                                                | CloudFront answered — says nothing about _why_, and not that a function cannot run (defect 31's bare `//`).                                     |
+| `x-cache: FunctionGeneratedResponse from cloudfront`                              | A viewer-request CloudFront Function answered (defect 31's 308). Assert as a prefix.                                                            |
+| `403`, `x-amzn-errortype: InvalidSignatureException`                              | Lambda Function URL rejected OAC's signature: an unhashed body (1, `proxy-readable-toweb`) or a path the URL canonicalizes (31).                |
+| `403` for a static asset                                                          | S3 via OAC for a missing key (no `ListBucket`), or API Gateway for a path outside the stage (36).                                               |
+| `accept-ranges: bytes`, `last-modified: … 1980`, weak `etag`                      | `send` served a file off disk — a `static-file` dispatch, typed by file extension (defect 12).                                                  |
+| `x-nextjs-cache: HIT`/`MISS`/`STALE`                                              | The Next.js cache path. `HIT` with a wrong body/status → look at what was seeded (4, 32); `MISS` where a prerender should exist → seeding (26). |
+| `cache-control: private, no-store` + `x-nextjs-postponed: 1`, no `x-nextjs-cache` | Answered from a PPR fallback shell, not a cache entry (defect 23).                                                                              |
+
+Useful probes: `curl -sI '…/?_rsc=probe' -H 'RSC: 1' -H 'Next-Router-Prefetch: 1'
+-H 'Next-Router-Segment-Prefetch: /__PAGE__'` for a segment prefetch; call it twice
+to see edge caching. `curl -g --path-as-is` keeps literal brackets and `//` on the
+wire (a browser or Playwright `APIRequestContext` cannot send a `\` at all — WHATWG
+parsing turns it into `/`). In Playwright, read duplicate headers with
+`headersArray()`; `headers()` folds two `vary`s into one string.
+
+### Symptom patterns worth recognizing
+
+- **Unrelated-looking failures sharing one URL.** Defect 17's eleven files failed on
+  empty text, `JSON.parse('')`, a `naturalWidth` of `null` — every failing case
+  requested `/`, every passing one did not. Group failures by URL before by assertion.
+- **A 404 page still hydrates.** A built-in 404 is a Next.js document; the browser
+  logs a single "Failed to load resource: 404" and the test times out on a selector
+  (defects 13, 17). Probe the page URL directly before debugging hydration.
+- **jest misattributes un-awaited rejections.** A fixture's `bundles.forEach(async …)`
+  reports its failure against whichever test is running (defect 16).
+- **A route returning 200 can still have failed.** A fixture that catches and
+  returns `{revalidated: false}` passes its status assertion; read the body and the
+  server log (defect 33).
+- **Worker errors do not reach the page console.** They fire on the worker's
+  `error` event, which fixtures rarely listen for (defect 25).
+- **Wrong `content-type` on RSC breaks things far away:** a `NaN` navigation
+  duration, or an action `redirect()` with no head (next fetches the target and
+  cancels it unless it is `text/x-component`) (defect 2).
+- **`JSON.stringify` hides `undefined`-valued keys**, so logging a query object can
+  lie; inspect with a debugger or `Object.keys` (defect 11).
+- **Races need more than one measurement.** Re-run a suspected defect several
+  times before filing it: a server-action redirect that looked like a third
+  instance of defect 36 was a pre-hydration click (native form POST), fixed by
+  waiting for the client router.
+- **Instrument before guessing.** Defect 3 survived three plausible theories; one
+  run with `[probe]` logs in the deployed function settled it.
+- **For slowness, split the time.** Compare Lambda duration with end-to-end, repeat
+  with `Accept-Encoding: identity` to rule out gzip/CDN, and look at the stored
+  S3 object's size and shape (defect 27: an 11.6 MiB entry for a ~1 MiB page).
+
+### Deploy-side traps
+
+- **`cdk deploy --hotswap` does not check custom resources.** It invokes them with
+  placeholder response URLs and prints success even when they send `FAILED`. If a
+  cache looks partly seeded, count objects in the cache bucket against the seed
+  directory and read the `BucketDeployment` Lambda's log (defect 26).
+- **Hotswap never runs CloudFormation**, so the post-deploy custom resource does
+  not fire between fixtures — anything it does (e.g. pruning the previous build) is not
+  under harness coverage.
+- **`NEXT_DEPLOYMENT_ID` makes every build id the same constant**; if one fixture
+  serves another's content, check for one cache prefix shared across builds
+  (defect 10).
+- **npm-pinned fixtures** (`packageManager: npm@…`): npm with `--prefer-offline`
+  treats a stale cached packument as final (`ETARGET … No matching version found for
+next@16.3.5`), so `e2e-deploy.sh` drops the flag for npm; and pnpm refuses to run
+  the hardcoded `pnpm post-build` in a project pinned to npm, so `e2e-deploy.sh`
+  exports `npm_config_package_manager_strict=false`.
+
+### Keeping verdicts durable
+
+`screen.mjs`'s **verdict** screen keeps a file out of `candidates` only if its
+`excluded-notes` key is the file path, or a directory ending in `/**`. A verdict written
+under a prose key ("revalidation behind the CDN, two files") is not matched, and
+the file gets re-offered and re-deployed. Key new verdicts by path.
+
+[harness]: https://nextjs.org/docs/app/api-reference/adapters/testing-adapters