Surfaced by the isolated at-tier clause-② review of PR #19005 (card #18670, item 2's third arm) as its NON-BLOCKING finding 2. Filed by the domain:spec seat 3 because a reviewer, like a dev, does not POST issues. finding only — no domain:*, no type, no priority:*.
Class
(b) — violates a declared contract. The contract is a docblock claim, and the measurement contradicts it.
PR #19005 routes the generator and the detector through ONE shared helper, projectPublishedJsonSchema, so that the dropped-refinements override cannot be dropped on one side. That is sound, and the review confirmed it: the publication path went from 4 direct z.toJSONSchema( calls at base to 0 in build-schemas.ts and 0 in dropped-refinements.ts.
But the helper's own docblock describes itself as the ONE call anywhere the published projection is produced, and that is wider than what was measured. packages/spec/scripts/build-openapi.ts:95 is a second, override-less z.toJSONSchema path, and it writes packages/spec/json-schema/openapi.json — a file in the same published directory, exported from the package as ./openapi.json.
⇒ the choke point is real for the surfaces the ledger covers, and the docblock claims a scope the choke point does not have.
Why it is NOT urgent, stated so nobody prices it as a live bug
Measured at PR #19005's head: openapi.json is byte-identical base to head, and embeds 0 SSLConfig, 0 dialect, 0 \S, 0 dependentRequired. So no declared arm is affected today — the second path currently produces nothing the override would have changed. The defect is that nothing prevents that from changing: the ledger does not read that population, so a future refinement reaching openapi.json would be projected wide and silently, which is exactly the failure class #18670 exists to close.
The two candidate shapes, neither of them chosen here
- Route
build-openapi.ts through projectPublishedJsonSchema too, and widen the ledger's population to cover openapi.json.
- Narrow the docblock to the population the choke point actually governs, and record
openapi.json as deliberately outside it.
⚠️ These are not equivalent: (1) changes what gets published if any refinement ever reaches that file; (2) changes only prose. ⛔ Do not treat this as a mechanical tidy — whichever is right, the choice is about how wide the published projection guarantee is meant to be, which is #18670's own subject.
Evidence limits
Everything above is from the reviewer's reading at head 6007a484a50cf8a985390a795cb69832f3df6af3, and this seat has re-derived none of it independently. The load-bearing readings to re-take before pricing: that build-openapi.ts:95 really does call z.toJSONSchema without the override, and that openapi.json really embeds none of the declared arms. Both are cheap greps; neither was done by me.
Dedup words
build-openapi second toJSONSchema · projectPublishedJsonSchema choke point scope · openapi.json override-less projection · published projection population ledger · json-schema openapi wide refinement
Dedup was run before filing: a semantic search including closed cards returned 13 results whose only same-family hit was #18670 itself, this card's parent. Limit: the words are the vocabulary of the generator, so a card filed from the consumer side ("the OpenAPI document accepts metadata the runtime refuses") would share none of them.
Generated by Claude Code
Surfaced by the isolated at-tier clause-② review of PR #19005 (card #18670, item 2's third arm) as its NON-BLOCKING finding 2. Filed by the
domain:specseat 3 because a reviewer, like a dev, does not POST issues.findingonly — nodomain:*, notype, nopriority:*.Class
(b) — violates a declared contract. The contract is a docblock claim, and the measurement contradicts it.
PR #19005 routes the generator and the detector through ONE shared helper,
projectPublishedJsonSchema, so that the dropped-refinements override cannot be dropped on one side. That is sound, and the review confirmed it: the publication path went from 4 directz.toJSONSchema(calls at base to 0 inbuild-schemas.tsand 0 indropped-refinements.ts.But the helper's own docblock describes itself as the ONE call anywhere the published projection is produced, and that is wider than what was measured.
packages/spec/scripts/build-openapi.ts:95is a second, override-lessz.toJSONSchemapath, and it writespackages/spec/json-schema/openapi.json— a file in the same published directory, exported from the package as./openapi.json.⇒ the choke point is real for the surfaces the ledger covers, and the docblock claims a scope the choke point does not have.
Why it is NOT urgent, stated so nobody prices it as a live bug
Measured at PR #19005's head:
openapi.jsonis byte-identical base to head, and embeds 0SSLConfig, 0dialect, 0\S, 0dependentRequired. So no declared arm is affected today — the second path currently produces nothing the override would have changed. The defect is that nothing prevents that from changing: the ledger does not read that population, so a future refinement reachingopenapi.jsonwould be projected wide and silently, which is exactly the failure class #18670 exists to close.The two candidate shapes, neither of them chosen here
build-openapi.tsthroughprojectPublishedJsonSchematoo, and widen the ledger's population to coveropenapi.json.openapi.jsonas deliberately outside it.Evidence limits
Everything above is from the reviewer's reading at head
6007a484a50cf8a985390a795cb69832f3df6af3, and this seat has re-derived none of it independently. The load-bearing readings to re-take before pricing: thatbuild-openapi.ts:95really does callz.toJSONSchemawithout the override, and thatopenapi.jsonreally embeds none of the declared arms. Both are cheap greps; neither was done by me.Dedup words
build-openapi second toJSONSchema·projectPublishedJsonSchema choke point scope·openapi.json override-less projection·published projection population ledger·json-schema openapi wide refinementDedup was run before filing: a semantic search including closed cards returned 13 results whose only same-family hit was #18670 itself, this card's parent. Limit: the words are the vocabulary of the generator, so a card filed from the consumer side ("the OpenAPI document accepts metadata the runtime refuses") would share none of them.
Generated by Claude Code