[finding] `apps/docs/middleware.ts` uses the Next 16 deprecated `middleware` convention; every docs dev boot warns

[claude]

What

Every pnpm docs:dev boot on Next 16.3.1 prints:

⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.

 To migrate automatically, run:
 npx @next/codemod@canary middleware-to-proxy .

 Learn more: https://nextjs.org/docs/messages/middleware-to-proxy

Observed on origin/main @ 01c50322a1, on two independent boots.

apps/docs/middleware.ts is tracked and is the docs app's i18n locale negotiator
(FD_LOCALE cookie, Negotiator, i18n.languages). No apps/docs/proxy.ts exists. Next
already reports the timing under the new name — request log lines read proxy.ts: 91ms —
so the runtime has renamed the slot while the repo still spells the file the old way.

Why it may be worth a card

A deprecated file convention becomes a removed one at some Next major. The migration is a
rename plus whatever the codemod adjusts: cheap now, forced later.

It also removes a recurring warning from every docs dev boot. That is the kind of standing
noise that trains readers to skim boot output — and boot output is exactly where the
Generated AGENTS.md and CLAUDE.md line behind #10249 was sitting.

Found while working on #10249; out of that card's file surface.

---

Generated by Claude Code

[huangyiirene]

Triage (finding round): promoted → pm:queue, type Task, S-tier mechanical — rename to the proxy convention (the runtime already logs it under that name), via the vendor codemod or by hand, and verify the locale negotiation still fires on a dev boot plus whatever docs build CI runs. Cheap now, forced at a future Next major, and it removes standing boot noise of the kind that buried the #10249 generated-files line.

---

Generated by Claude Code

[claude]

Claim: /pm-dispatch domain:devx execution seat.
Session: session_01DdCnBGcHeufjrq7drTD3wt · Branch: claude/issue-10782-next-proxy-convention · Worktree: objectstack-issue-10782
Container & model: S, mode:subagent, model: opus
File surface: apps/docs/middleware.ts → apps/docs/proxy.ts, plus whatever the rename touches.

Triage graded this S-tier mechanical: rename to the proxy convention (the Next runtime already logs it under that name — request lines read proxy.ts: 91ms), via the vendor codemod or by hand. ⭐ Verification is the whole job here, not the rename: prove the i18n locale negotiation still fires (FD_LOCALE cookie, Negotiator, i18n.languages) on a real dev boot, and that the deprecation warning is gone. A rename that silently stops running is exactly the failure this card's shape invites.

Standing constraints

• ⛔ Governed, human-merge-only: docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md — propose wording in the report.
• ⛔ Never edit content/docs/releases/**. ⛔ Never git stash — refs/stash is shared by every worktree of the repo.
• ⚠️ A pipe swallows the exit code. Capture as cmd > log 2>&1; ec=$?.
• ⚠️ ⭐ NEW, measured today ([finding] pnpm --filter <typo> exits 0 with "No projects matched the filters" — a whole verification round can be fictitious and read as green #10853): pnpm --filter <name> with a name that does not exist prints No projects matched the filters and EXITS 0. A whole verification round can be fictitious and read as green. Verify your filter actually matched before trusting any run. (My own briefing carried a wrong package name this morning and a dev caught it.)
• ⚠️ Apply labels additively (POST /issues/N/labels), never a whole-set PUT; read them back after the size labeler runs.

Report back to me; I review against GitHub and land it.

---

Generated by Claude Code

[os-zhuang]

{
 "issue": 10782,
 "status": "done",
 "branch": "claude/issue-10782-next-proxy-convention",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10867",
 "premise_still_valid": true,
 "summary": "Renamed apps/docs/middleware.ts to apps/docs/proxy.ts via the vendor codemod (npx @next/codemod@canary middleware-to-proxy apps/docs), which also renamed the default export from `middleware` to `proxy`; I added one doc-comment fix in the same file. The codemod's entire blast radius was those two paths under apps/docs/ — I scoped it to apps/docs rather than the repo root on purpose, because the unrelated packages/runtime/src/middleware.ts matches the codemod's own /(^|[/\\\\])middleware\\./ path test and would have been rewritten by a root run; it is untouched. The Next 16.3.1 deprecation warning is gone from the docs dev boot and the i18n locale negotiation is proven still live by real requests plus two ablations. skip-changeset applied: apps/docs is private:true with privatePackages.tag=false, so the PR releases nothing, and the site's HTTP behaviour is byte-identical.",
 "tests": "All evidence from real requests against real `next dev` boots on port 43782, each with a cold .next; final HEAD 353cb948e0, tree clean. (1) WARNING GONE: baseline boot with middleware.ts printed '⚠ The \"middleware\" file convention is deprecated. Please use \"proxy\" instead.'; after the rename, grepping the boot log for deprecat/middleware-to-proxy returned GREP_EXIT=1 (absent). (2) BEHAVIOUR UNCHANGED: diffing baseline vs post-rename response matrices (status line, location, set-cookie, x-middleware-rewrite, page title) gave DIFF_EXIT=0, identical. Matrix: GET /en/docs -> 307 location:/docs + set-cookie: FD_LOCALE=en; Path=/; SameSite=lax | GET /docs (Accept-Language: zh-CN, no cookie) -> 200 x-middleware-rewrite:/en/docs, title 'Documentation | ObjectStack' | GET /docs (Cookie: FD_LOCALE=en) -> 200 same rewrite | GET /zz/docs -> 404 x-middleware-rewrite:/en/zz/docs | GET /en -> 307 location:/ + set-cookie | GET /api/search -> 200, no rewrite and NO proxy.ts: timing segment (matcher-excluded, a clean negative control). This exercises the cookie WRITE, i18n.languages membership (/en/docs strips the prefix, /zz/docs does not — the two diverge on exactly i18n.languages.some(...)), and hideLocale:'default-locale'. (3) ABLATIONS — note no dist/build step applies here: apps/docs is a Next dev server consuming its own source, so the ablation-dist-preflight rebuild discipline is not the relevant control; the on-disk mutation proof is, and I did it for every leg rather than trusting an editor exit code. ABLATION A: parked proxy.ts outside the app; mutation confirmed on disk by `grep -rl FD_LOCALE apps/docs --include=*.ts` returning 0 files (not by mv's exit code). Predicted direction: total collapse — observed exactly that: /en/docs 307->200 with NO Set-Cookie, /docs lost x-middleware-rewrite and rendered the landing page (title 'ObjectStack — Apps small enough for AI to hold whole.') instead of the docs index because [lang] captures 'docs', /zz/docs 404->500, /en 307->200; proxy.ts: timing-segment count per boot log baseline=3 after=3 ablationA=0. Restore leg: git diff --quiet HEAD byte-identical. ABLATION B: injected `throw new Error('OS_ABLATION_NEGOTIATOR')` immediately after `const negotiator = new Negotiator({ headers: negotiatorHeaders });`; mutation confirmed on disk by injected-marker count 1 AND anchor count 1 AND git diff dirty. One boot, three-way discrimination: GET /docs without cookie -> 500 with stack `at getPreferredLanguage (proxy.ts:35:9) / at proxy (proxy.ts:87:29)` (the runtime names the renamed file and function); GET /docs WITH Cookie: FD_LOCALE=en -> 200 + rewrite, never reaching the throw, which is positive proof the FD_LOCALE cookie is READ and short-circuits ahead of the negotiator; /en/docs and /en -> still 307 + Set-Cookie, so the pathname-locale branch never calls getPreferredLanguage. Restore leg confirmed --absent: marker count 0, anchor intact, git status clean. (4) GATES: union re-derived by `node scripts/pm/dispatch-gates.mjs` with no paths (it takes its own change set from the merge base) and run on final HEAD 353cb948e0 — it matched exactly two families, both run green, quoting each gate's own verdict line: 'check-nul-bytes: OK (scanned 6271 text file(s) -- 6271 tracked, 0 untracked-not-ignored; skipped 5 binary; no raw ASCII control bytes).' / 'check-test-source-alias OK — 72 packages with tests scanned; 61 registered as still resolving a workspace dep through dist/; 44 published subpath(s) resolved through every alias table.' / 'check-type-source-resolution OK — 76 packages with a tsconfig.json scanned; 51 registered as still resolving a workspace dep's types through dist/.' (5) BUILD/TYPECHECK: dependency closure first, `pnpm --filter '@objectstack/docs^...' build` CLOSURE_BUILD_EXIT=0 (spec gen:schema produced no tracked drift, git status clean afterwards), then `pnpm --filter @objectstack/docs typecheck` (tsc --noEmit) DOCS_TYPECHECK_EXIT=0. Per the dispatch warning I did NOT trust the filter: `pnpm --filter @objectstack/docs exec pwd` printed /home/user/objectstack-issue-10782/apps/docs, proving it matched a real project rather than printing 'No projects matched the filters' and exiting 0. Every exit code above was captured as `cmd > log 2>&1; ec=$?`, never after a pipe — my first probe harness did read curl's status through a pipe to tr and reported exit=0 for six failed connections; I rewrote it to redirect first, which is how the wrong `next` binary path got caught.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #10871: apps/docs declares both `types:check` (fumadocs-mdx && next typegen && tsc --noEmit) and `typecheck` (tsc --noEmit), but `types:check` is invoked by nothing — grep -rn 'types:check' .github/ scripts/ returns no matches — so the docs app is only ever type-checked without next typegen, and since tsconfig.json includes .next/types/**/*.ts its real coverage depends on whether an earlier build happened to populate .next. Measured: with .next deleted, typecheck exits 0. Labelled `finding`, unassigned, no pm:queue."
 ]
}

PR: #10867 (draft, documentation + size/xs + skip-changeset, read back after the size labeler settled).

One thing worth your attention on review: the GitHub body sanitizer ate my first PR description's literal HTML title tags and the whole span between each opening and closing tag, which silently destroyed a table header and two rows. I caught it on read-back and rewrote the body without angle brackets; the current body is verified intact. Worth knowing that the swallow is not limited to short <!-- ... --> markers — a foo//foo tag pair takes everything between them with it, even inside backticks.

CI was not waited on, per the 2026-08-10 ruling — gate status at report time is whatever GitHub shows.

---

Generated by Claude Code