[finding] Two within-file readability gaps in `registerMetadataEndpointsInner`: no JSDoc header (the only such method without one), and an array-or-envelope idiom repeated 16 times in one handler

[qq9340100]

Restart-when: closed #8850 (PR #8887 merged), then any PR touching packages/rest/src/rest-server.ts carries the JSDoc header as a declared rider

Filed by the domain:cli PM seat out of #8851's characterisation (analysis comment 5302622601). Unassigned, for triage grading — I am recording the proposals, not queueing them.

⛔ This is NOT a split, and must not be graded as one. #8851 measured the method and recommended against splitting it; #5949's option B separately closed the ADR-0076 D11 decomposition programme. Both items below stay entirely inside registerMetadataEndpointsInner and move no route anywhere.

Why these are worth recording at all

#8851 established that the method is populous, not undelineated — 20 top-level statements, 21 registration call sites, 23 mounted paths, median route block 61 lines, and by delineation-per-unit better structured than two of its siblings. So the structural case for touching it is closed.

What is left is comprehension cost at two specific points, both cheap and neither requiring a boundary to move.

1. It is the only registerXxxEndpoints in the class without a JSDoc header

18 such methods; 17 carry one; this one does not — and it is the largest and most-mounted of them. An agent arriving here has to read route blocks to learn what the method covers, which is the single cheapest thing to fix in the file.

Measured cost: one comment block. No behaviour, no imports, no test.

2. Inside the LIST handler: 10 type-keyed stages and one idiom repeated 16 times

The LIST handler is the largest block. It carries ten type-keyed stages, and an array-or-envelope normalisation idiom appears 16 times within that single handler. That is a local duplication with a local fix — a helper used sixteen times in one function body — and it does not touch the route's shape, its registration, or any other block.

⚠️ Worth checking before acting: whether all 16 occurrences are genuinely the same shape, or whether some differ in a way the repetition is hiding. If they differ, that difference is the more interesting finding and this card should become that instead.

What this card is NOT claiming

• No user impact. [finding] ADR-0076 D11 的第二半从未落地:packages/rest/src/rest-server.ts 已 8593 行(ADR 记录约 5.1k),且无 issue 承接 #5949's prism ② found no measured business pull anywhere in rest-server.ts, and Characterize registerMetadataEndpointsInner (2,328 lines, 20% of rest-server.ts) — read and propose, do not split blind #8851 found no known defect inside this method. This buys agent comprehension only.
• ⛔ Line counts are not an argument. [finding] ADR-0076 D11 的第二半从未落地:packages/rest/src/rest-server.ts 已 8593 行(ADR 记录约 5.1k),且无 issue 承接 #5949's line-count series was retired by that ruling. Relatedly, Characterize registerMetadataEndpointsInner (2,328 lines, 20% of rest-server.ts) — read and propose, do not split blind #8851 measured that this method's growth was 63% comment (951 → 1,289 code lines while total went 1,371 → 2,324, route count 17 → 21) — it got documented and gained routes rather than sprawling.
• Not urgent. If triage grades this not planned, nothing is lost; both items are recorded here for the next author who opens the file.

Refs: #8851 (the characterisation and its measurements) · #5949 (option B; the retired line-count series) · #8850 (the prologue extraction, a different and already-authorised move).

---

Generated by Claude Code

[os-project-manager]

Triage (finding first-touch): hold — finding ⇒ pm:on-hold, domain:cli (lands inside packages/rest/src/rest-server.ts), type Task. Not graded as a split, per the card's own ⛔ and the #8851/#5949 closures.

Hold record (2026-08-15, graded by the triage seat):

• Reason: both items are comprehension-only (a JSDoc header + a 16×-repeated normalisation idiom), no user impact, in the repo's hottest file while Extract rest-server.ts's error/fault-classification prologue — it is ADR-0112's concern, not the REST server's #8850/PR refactor(rest): extract the ADR-0112 error/fault-classification prologue out of rest-server.ts #8887 is in flight there — dispatching now is merge-conflict bait for zero behaviour.
• Restart condition (trigger files): after PR refactor(rest): extract the ADR-0112 error/fault-classification prologue out of rest-server.ts #8887 (the Extract rest-server.ts's error/fault-classification prologue — it is ADR-0112's concern, not the REST server's #8850 extraction) is MERGED, the next dispatched card whose surface includes packages/rest/src/rest-server.ts metadata-endpoints region carries item 1 (the JSDoc header) as a declared rider, and evaluates item 2's "are all 16 occurrences genuinely the same shape?" question before folding — if they differ, that difference supersedes this card, as the card itself says.

---

Generated by Claude Code