refactor(downgrader): slim the converters down to what oRPC and schema libraries emit

[dinwwwh]

The downgrader exists so oRPC can generate 3.1 and 3.0 documents: it builds every document as 3.2 and runs downgradeSpecV32ToV31, then downgradeSpecV31ToV30. oRPC users also hand-write parts of that document, in base and in per-operation spec overrides, so the downgrader has to cover what people commonly write, not just what oRPC generates.

The package had grown machinery for constructs almost no one writes, which made it large and hard to follow, and slower than needed on ordinary documents. This drops that machinery. An audit then checked the result against hand-written and real-world documents, and this PR fixes the gaps it found.

	main	This PR
Source	1,952 lines	1,097 lines
Build	50.2 kB	30 kB
Tests	41 files, 6,149 lines	4 files, about 1,200 lines, plus a generated oRPC fixture

Engine

shared.ts goes from 1,058 to 227 lines.

• One table-driven convertObject with a per-table memo, so a shared object is converted once and a cycle ends. clone keeps cycles in copied values the same way.
• A per-conversion cache holds resolved $refs.
• inline replaces a $ref by its converted target and cuts recursion with {}.
• Any object JSON sees as one is read as one, including null-prototype and other-realm objects, such as the documents oRPC's generate() returns.
• Removed:
  • $id/$anchor base resolution
  • exact-reuse tracing and its work budget
  • alias-chain handling
  • the fixpoint that re-ran the conversion until no reference newly dangled

Behavior changes

No longer handled. The README lists each of these under the step's limitations.

Step	Edge case
3.2 → 3.1	Schema $refs into removed parts (components.mediaTypes), keeping $ids unique when inlining, pruning Links and mapping values into removed parts, dropping a parameter left without content
3.1 → 3.0	Multipart application/octet-stream and RFC6570 inference, pruning Links and mapping values into removed parts, $id-relative $refs, percent-encoded removed-part pointers, readOnly with writeOnly, deduplicating required, forcing required: true on path parameters

Kept, in a smaller form. In 3.1 → 3.0, a schema that lost a restricting keyword is marked loose. A not over it is removed, and a oneOf with a loose branch becomes anyOf, so neither rejects values the original accepts. Keywords that restrict nothing, such as zod's propertyNames: { type: 'string' }, and exactly converted tuples don't count, so a zod discriminated union keeps oneOf.

Added or fixed after the audit. The audit used hand-written documents plus 24 real 3.1/3.2 descriptions: GitHub, OpenAI, Discord, Adyen, Train Travel, Airflow, Meilisearch and others.

• nullable: a 3.0-style nullable: true beside a single type in a 3.1/3.2 document is kept in 3.0. Before, the output rejected null.
• Unknown keywords: keywords 3.0 doesn't define, such as zod .meta() keys or Pydantic extras, become x- extensions. Before, they made the whole 3.0 document invalid.
• unevaluatedProperties: it becomes additionalProperties when nothing else evaluates properties.
• Security scopes: scopes on apiKey/http requirements become [], as 3.0 requires.
• Parameters with content: they lose style, explode and allowReserved, which oRPC's queryStyles: 'json' emits.
• Summaries: Tag and Info summaries fill a missing description.
• Tuples: items: false becomes maxItems. prefixItems becomes items matching any item schema, instead of items: {}.
• Strings: a string with a contentSchema no longer becomes format: binary, and contentEncoding: binary becomes format: binary.
• Empty enum: an empty enum becomes allOf: [{ not: {} }] instead of invalid 3.0.
• definitions: it's read as $defs.
• Missing targets: a $ref into a removed part whose target is missing stays as written.

Unchanged on purpose. { type: 'null' } stays { enum: [null] }, without nullable, as decided in a34a9b9 (#20).

For reviewers

• oRPC output: compared with the published 0.1.0, it differs only in tuple items, summaries filling descriptions, key order, and the nullable that a34a9b9 (fix(downgrader): stop emitting nullable without type in 3.1 to 3.0 #20) already removed on main.
• Cycles: an input with object cycles produces the same cycle in the output.
• Memo trade-off: a $defs target first converted inside a recursion cut is reused with that cut wherever else it's referenced. The README lists this.

Testing

• Tests:
  • one test file per step;
  • the official corpus, for each step and chained;
  • orpc-document.ts, generated by @orpc/openapi@2.0.0-beta.41 with Zod, validated as 3.1 and 3.0 and snapshotted;
  • a regression test for every audit and review finding.
• Real-world documents: every collected 3.1/3.2 description whose input validates converts to a valid 3.0 document with no new dangling refs.
• Real oRPC run: generate() for 3.2.0, 3.1.0, 3.1.1, 3.0.0, 3.0.3 and 3.0.4 validates with this build, and so does downgrading generate()'s own 3.2 output directly.
• Benchmarks: every bench is faster than main. For example, 3.1→3.0 on the generated 100-resource API runs at about 63 ops/s against 20, and the chained official corpus at about 855 against 318. CodSpeed has the authoritative numbers.
• Checks: pnpm test (190), pnpm lint and pnpm type:check pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PhK4SwK1yxF8aWvPBsNzVH

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will improve performance by ×2.5

⚡ 18 improved benchmarks
✅ 1 untouched benchmark
🆕 1 new benchmark

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	cyclic callback graph in a removed operation, 8 path items	6,435.4 µs	101.3 µs	×64
⚡	reference diamond into removed media types, 64 levels	3,265.6 µs	97.8 µs	×33
⚡	cyclic callback graph in removed webhooks, 8 path items	4.7 ms	1.3 ms	×3.5
⚡	property schema	138 µs	44.6 µs	×3.1
⚡	generated api, 100 resources	223.6 ms	97.3 ms	×2.3
⚡	generated api, 10 resources	20.8 ms	9.1 ms	×2.3
⚡	path item $ref chain in removed components, 200 hops	13.5 ms	6.8 ms	×2
⚡	generated api, 100 resources	385.3 ms	205.6 ms	+87.38%
⚡	order schema with $defs	886.3 µs	549 µs	+61.45%
⚡	generated api, 10 resources	12.2 ms	8.3 ms	+46.44%
⚡	property schema	176.1 µs	124.5 µs	+41.41%
⚡	generated api, 100 resources	136.7 ms	97.7 ms	+39.81%
⚡	reference diamond into removed webhooks, 64 levels	4 ms	2.9 ms	+38.45%
⚡	official corpus	5.9 ms	4.3 ms	+36.45%
⚡	dereferenced diamond, 64 levels	943.8 µs	720.5 µs	+31%
⚡	official corpus	10.9 ms	8.4 ms	+30.16%
⚡	order schema with $defs	1.5 ms	1.1 ms	+29.23%
⚡	official corpus	6.1 ms	5 ms	+23.05%
🆕	oRPC document	N/A	4.5 ms	N/A

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/loving-mayer-07ts69 (4dc47e2) with main (c4640c6)}

[pullfrog]

Caution

Two behavior regressions survive the refactor even though all 176 tests pass: a cyclic value in a copied position now throws RangeError, and dropping the loosening tracker makes not/oneOf unsatisfiable on valid input. Both are things the base converter handled.

Reviewed changes

• Minimal Context — root/targets/seen/inlining replace the location, resource, inlining, copy-tracking, and exact-reuse state; the fixpoint downgrade driver and its dangles/alias machinery are gone.
• Simpler core — clone lost its memo, convertObject caches by (fields map, source object) and returns the in-progress object for cycles, Finish mutates in place and returns void, map/list reworked.
• Converters rebuilt — $id/anchor/external ref resolution and loosening tracking removed; $defs and removed parts are inlined by local JSON Pointer; Path Item $ref merging, tuple rewriting, and multi-type handling rewritten in v3.1→3.0.
• Tests replaced — granular spec/schema suites deleted and consolidated into snapshot-backed v3.1-to-v3.0.test.ts / v3.2-to-v3.1.test.ts, plus a new oRPC integration test.

⚠️ This changes behavior, not just structure

The PR body frames this as a refactor that "maintains backward compatibility of the public API", but the resource/$id resolution and the loosening tracker are removed, so documents the base converter turned into safe (looser) schemas now yield unsatisfiable schemas or throw on cycles — the two inline findings below. The README intro still leads with "loses detail, never meaning" while its new Limitations section says a not/oneOf "can then reject values the original accepts"; the deleted granular tests were the only thing pinning the old guarantee. Please confirm the guarantee is intentionally dropped for published consumers (oRPC) and reword the intro, rather than presenting this as behavior-preserving.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• clone keeps cycles in copied values. clone now delegates to a memoizing copy, which records each container's output before recursing, so a cyclic value reached through a copied position — an unlisted keyword, default, example, an x- extension, or a non-converted map entry — is reproduced as a cycle instead of overflowing the stack.
• Regression tests added. One per converter, asserting a self-referential example/default round-trips as a cycle while converted and copied positions both stay within their own graph. Both fail on the previous commit and pass now.

pnpm test (178 pass) and pnpm lint are clean. This is submitted as a comment rather than an approval only because the earlier not/oneOf loosening thread is still open; the new commit does not touch that code, so it introduces no new concerns.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Restored not/oneOf loosening tracking. v3.1-to-v3.0.ts now defines RESTRICTING_KEYWORDS and a module-level LOOSE WeakSet; a converted schema is marked loose when it lost a restricting keyword, holds a loose subschema, or is a $defs target cut at recursion, and finishSchema deletes an enclosing not and lowers a oneOf with a loose branch to anyOf.
• Updated the README. Added not/oneOf rows to the removal table and narrowed the step's limitation to the $ref-kept case.
• Added regression tests. Cover not removal (direct, through properties, and through the recursion cut), the oneOf→anyOf rewrite, and the case that stays not.

This addresses the prior review's loosening finding: the new tracker is smaller than main's and its only remaining gap is the documented kept-$ref case. pnpm test (181), pnpm lint, and pnpm type:check pass; snapshots are unchanged.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Important

The bdc2da3 loosening refinement is sound on its own, but the refactor dropped the guards (and the tests) that kept a contradictory const / type: "null" schema from being treated as exact, so an enclosing not / oneOf now rejects values the 3.1 source accepted. main handled both cases and pinned them in the deleted tests/v3.1-to-v3.0/schema/loosening.test.ts; the consolidated suite does not cover them.

Reviewed changes

• 3.0-only schema keywords — unknown keywords are renamed to x- extensions, an empty enum becomes allOf: [{ not: {} }], and a 3.0-style nullable is kept beside a single type (and marks the schema loose).
• Sharper loosening detection — losesRestriction no longer counts propertyNames: { type: "string" }, an exactly-converted tuple, or unevaluatedProperties already expressed as additionalProperties; convertTuple returns whether the conversion is exact and maps items: false to maxItems.
• unevaluatedProperties → additionalProperties — converted when no in-place applicator evaluates properties.
• Document-level niceties — a 3.1 info.summary and a 3.2 tag.summary fill a missing description; a parameter with content also drops style, explode, and allowReserved; scopes on apiKey / http security requirements are emptied.
• JSON-like inputs — isRecord accepts null-prototype and other-realm objects (oRPC documents) and excludes arrays.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

This run reviewed e1a1eb6, the fix commit that resolves the prior review's inline findings.

• Deduplicated tuple item schemas by source — convertTuple keys variants by the item's source schema (jsonKey(item)) and returns the tuple as inexact when the retained item is loose, so a loosened item can no longer hide behind an equal one.
• Preserved an x- extension holding null — the unknown-keyword renamer uses Object.hasOwn in place of ??=, so an existing x- key valued null is not overwritten.
• Closed the const / type: "null" inversions — a const outside the enum beside it now marks the schema loose, and type: "null" with an enum that lacks null stays unsatisfiable via allOf: [{ not: {} }] (an enum containing null becomes [null] exactly).
• Tightened isRecord for inherited keys — a null-prototype parent with own keys is no longer read as a JSON object, so keys an object would inherit are ignored as JSON ignores them.
• Read definitions as $defs — added to the removed-keyword set and the inline check, so $refs into it are inlined instead of left dangling; README updated.

Verified: pnpm test (190 pass), pnpm lint, and pnpm type:check are clean. A differential Ajv 2020-12 fuzz over the new const/enum/type: "null"/prefixItems paths (269 schemas × 16 instances, ~3.8k checks) found no value the 3.1 source accepts that the 3.0 output rejects.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

This run covered 4dc47e2, a test-only commit layered on the e1a1eb6 fixes.

• Added unusual-combination coverage — $ref with siblings plus a type array and anyOf, type: "null" with allOf, empty enum with allOf, a multi-type array, a single-element type array, and a maximum/exclusiveMaximum conflict, each pinned to an exact output.
• Added own-__proto__ coverage — __proto__ keys in properties and in a copied example survive as data keys without touching the prototype.
• Added a cyclic tuple-item test — two prefixItems entries sharing one cyclic schema deduplicate and the cycle is reproduced in the output.
• Added $ref-resolution boundaries — external and percent-invalid refs stay as written, and securitySchemes self-refs terminate.
• Added malformed pass-through coverage — non-array security/parameters/responses and non-record properties/allOf are cloned through without throwing.

Every added assertion is an exact .toEqual or identity check that would fail if the pinned behavior regressed, so none is theatre. pnpm test (197 pass), pnpm lint, and pnpm type:check are clean.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}