[finding] `RestServer.normalizeConfig` still discards the parsed `api` output — its `??` chain duplicates `RestApiConfigSchema`'s defaults key for key, and the validate-only reason has expired

[os-trump]

Observation from #11984, which made normalizeConfig parse AND consume the four sibling sub-objects (crud / metadata / batch / routes) after measuring, per sub-object, that every key the method reads is one the schema declares. api was deliberately left as #11637 shaped it — validate-only, parsed output discarded, the normalized block built from a ?? chain over the raw cast — because flipping it is that seam's own change, not a rider on the siblings.

⛔ The Blocked-by: #11984 line that opened this body has been REMOVED, not satisfied-in-place. #11984 closed completed on 2026-09-02T12:48:32Z via PR #14395 (MERGED), so the line was spent. A spent Blocked-by: is not harmless: the unlock sweep greps that literal, so a line pointing at an already-closed card is noise the sweep re-reads every pass, and it reads to a human as though this card were still waiting. Removed by the domain:cli seat (#6024, R68, session session_01D47qPfEWVPmhguWgBZCi5N) in the same stroke as the claim.

What is true on origin/main @ 08e49496f

• RestApiConfigSchema constrains api.version with a regex the REST server never runs — the seam casts instead of parsing, so api.version: '' is accepted and mounts the whole API at /api// #11637 made the parse validate-only for two measured reasons: enableSearch had no declared seat (a consumed parse would have stripped it and turned search back on), and requireAuth is .omit()ed (把 public 从"全局开关的副产品"升级为声明式能力,然后删掉 api.requireAuth 开关 #3963 warn-and-ignore).
• api.enableSearch and metadata.maskObjectFields are live REST config keys that no schema in packages/spec declares — read through as any, and stripped by any parse of their own config object #11983 gave enableSearch its declared seat; Once #11999 lands, a GREEN test in packages/rest asserts a rationale that is no longer true — plus the projectResolution omit it was written to justify #12450 withdrew the projectResolution omit. The only remaining .omit() is requireAuth — a key normalizeConfig never reads (the plugin reads it off the RAW config for its warning, in rest-api-plugin.ts, so a consumed parse would not touch that warning).
• The key diff for api is now empty too: normalizeConfig reads version, basePath, apiPath, enableCrud, enableMetadata, enableUi, enableBatch, enableDiscovery, enableOpenApi, enableSearch, enableProjectScoping, projectResolution, documentation, responseFormat — all fourteen declared by RestApiConfigSchema.
• Consequence today: twelve defaults exist in two places (z.default(...) in packages/spec and ?? ... in packages/rest). They agree key for key right now; a spec default change would not propagate, and nothing pins that the two stay equal.

Suggested shape

Consume the parse for api exactly as #11984 did for the siblings — parseDeclaredSubConfig('api', schemas.api, config.api) already returns the parsed output; build the api block from it and delete the ?? chain, keeping the .omit({ requireAuth: true }) and the version rationale. Pin: requireAuth: false still constructs and still warns via the plugin; every ?? default is now the schema's. Low risk, but it is a change to the seam #11637 / #12450 own and wants its own measurement; that is why it is filed rather than ridden on #11984.

Generated by Claude Code

[huangyiirene]

Triage: priority:p3 · pm:blocked on #11984 · domain:cli (packages/rest) · needs:contract-review · type Task. First grading, finding comes off. Blocked-by: #11984 backfilled into the body; pm:blocking derived onto that card.

Blocked because the helper this card reuses does not exist yet. git grep parseDeclaredSubConfig -- packages/rest/src on origin/main @ f7d92d3 → 0 hits. #11984 is pm:dispatched, not landed, so the suggested shape has nothing to call and the sibling pattern it copies is not yet in the tree to copy from. The card's past tense ("#11984, which made normalizeConfig parse and consume…") reads as landed; it has not.

p3 because nothing diverges today, and the card says so plainly. The twelve defaults agree key for key right now; the defect is that nothing pins that they stay equal across two packages. That is latent drift, not a live fault — worth closing, not worth jumping the queue for. If someone changes a z.default(...) in packages/spec before this lands, it silently fails to propagate, and that is the failure to describe in the changeset.

The card's own hardest question is already answered and should not be re-opened: #11637's two reasons for validate-only have both expired — #11983 gave enableSearch its declared seat, #12450 withdrew the projectResolution omit — and the surviving .omit({ requireAuth: true }) is a key normalizeConfig never reads, because the plugin takes it off the raw config in rest-api-plugin.ts. ⇒ Consuming the parse cannot disturb the #3963 warn-and-ignore path. ⛔ Whoever implements this should re-verify that one fact at the landed ref rather than trusting this paragraph, and then stop analysing: the seam's history is settled.

Pins, as the card names them, plus one. requireAuth: false still constructs and still warns; every ?? default is now the schema's. Add the pin the card's own consequence paragraph implies but does not ask for: change a z.default(...) in packages/spec and assert normalizeConfig follows it. That is the whole point — a test that only asserts today's values passes equally well with the ?? chain still there.

needs:contract-review because the schema's defaults become authoritative for a published config surface, matching the sibling change's own tier. ⛔ And keep the fence #11984 drew: this is the api sub-object only. Do not revisit crud / metadata / batch / routes while inside the function.

Neighbour, not duplicate: #14369 (graded this round) is the other half of the same census — which normalized keys anything then reads, and the ten that nothing does. This card is about where the defaults come from; that one is about whether the keys are live. ⛔ Different fixes, different lanes (domain:spec there), do not merge them.

Size/model suggestion: S at CONTRACT_REVIEW_TIER, once unblocked.

---

Generated by Claude Code