[dinwwwh]

Requested by dinwwwh · project thread

What

Simplifies the cycle handling that #309, #316 and #317 added, following the request for the simplest approach with minimal logic: when there is a choice, drop a restriction rather than add logic.

The problem those PRs solved: around a cycle, a not or oneOf can read a schema before its conversion is done, so it does not know yet whether that schema lost a restriction. They fixed it by recording what each read saw, then converting the whole input again (#309), following alias chains and object cycles to find those outputs (#316), and skipping the second pass when it could not change anything (#317).

This PR replaces all of that with one rule: a schema met again before its conversion is done counts as loose.

• A $ref kept as written whose target is still being converted (inline returns DROP for a target that exists) is loosened.
• An object met again before finishSchema marked it done (new DONE set, read in revisitSchema) is loosened.

Removed: keptStrict, refOutputs, looseTargets, revisits, looseInputs, sharedOutput, aliasRef, markLooseTargets and the second-pass loop. The revisit callback in convertObject now gets only the output. Net: +27/−118 lines.

README: the not row now says a recursive schema counts too, and the performance note drops the second pass.

Tests

One expectation changed: a oneOf over a $ref into a pure $ref cycle (A → B → A) now becomes anyOf. The cycle tests from #309 and #316 pass unchanged. pnpm check, pnpm test and coverage (100%) pass.

Tradeoffs

• Output. Every recursive schema now counts as loose, also one that loses nothing, such as a plain tree component. A not over one is removed, and a oneOf with one as a branch becomes anyOf unless its branches are told apart by type or by a required tag. A recursive schema through $defs already counted as loose before this, since recursion there is cut to {}. Code generators model anyOf as a different union type than oneOf.
• Speed. No second pass at all now. Under callgrind with CodSpeed's V8 flags, one warmed conversion of the order schema goes from 1,356,928 to 1,328,874 instructions (−2%), and the 10-resource generated API from 17,622,930 to 17,878,067 (+1.4%, one WeakSet add per schema).

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will degrade performance by 59.36%

2 warnings

⚠️ 1 benchmark is dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 4 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

❌ 4 regressed benchmarks
✅ 25 untouched benchmarks
⏩ 2 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	property schema	127.4 µs	1,030.8 µs	-87.64%
❌	dereferenced diamond, 64 levels	958.5 µs	1,875.6 µs	-48.9%
❌	order schema with $defs	1.4 ms	2.3 ms	-39.59%
❌	reference diamond into removed webhooks, 64 levels	2.3 ms	3.2 ms	-28.52%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/project-thread-h3q238 (6de99ef) with main (e663c22)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[pullfrog]

✅ No new issues found.

Reviewed changes — the whole net diff of this PR against main, verifying the single-pass cycle rule replaces the old fixpoint without under-marking any schema as loose.

• v3.1-to-v3.0.ts — new mid-cycle rule. Added DONE (WeakSet of converted outputs); finishSchema marks an output done at the end, and revisitSchema(out) adds any output met again before that to LOOSE. The kept-$ref path now returns isLoose(converted) || (converted === DROP && target !== undefined) — a DROP from inline with an existing target is a cycle (ctx.inlining), so it is loosened; a dangling target === undefined is not.
• v3.1-to-v3.0.ts — fixpoint removed. downgradeV30 runs the conversion once; keptStrict, refOutputs, looseTargets, revisits, looseInputs, sharedOutput, aliasRef, markLooseTargets and the second-pass loop are gone, and aliasRef is inlined into convertSchema. finally clears only the remaining per-pass state.
• shared.ts — convertObject's revisit callback now takes only the output ((out) => void) rather than (value, out).
• Tests / README — the oneOf over a pure $ref cycle (A → B → A) now expects anyOf; the README not row and performance note are updated for the removal of the second pass.

I traced the soundness direction (over-marking drops a not / widens oneOf to anyOf; under-marking is what breaks the contract) and found no under-marking: any read of an in-progress output goes through convertObject's memoized-hit branch into revisitSchema, so the removed per-target propagation is subsumed in one pass; reads of a finished output have final looseness. isLoose is consumed only by loosen, convertTuple's exactness, and convertSchemaRef propagation, all of which stay on the safe side. No stale references to the removed identifiers remain. oxlint/oxfmt/tsc are clean and v3.1-to-v3.0.test.ts passes 130/130.

The one thing worth remembering for follow-ups is the deliberate widening called out in the PR body: every recursive schema now counts as loose, including ones that lose nothing, so a not over a recursive tree is dropped and a oneOf with a recursive branch becomes anyOf unless its branches are told apart. That is consistent with the converter's established "loses detail, never meaning" contract and is documented in the README.

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

[dinwwwh]

On the CodSpeed result: all four flagged benchmarks carry CodSpeed's own "ran on different hardware" warning, and the numbers do not reproduce. Measured locally the way the CodSpeed plugin does (CodSpeed's V8 flags, 7 warm-up calls, gc(), then one call counted under callgrind), in instructions, main vs this head:

Benchmark	main	head
property schema	101,656	100,741
order schema with $defs	2,141,505	2,190,336
dereferenced diamond, 64 levels	1,734,036	1,776,566
reference diamond into removed webhooks, 64 levels	4,328,979	4,359,230

That is −1% to +2.5%, from the one WeakSet add per schema, against the −28% to −88% CodSpeed reports.

---

Generated by Claude Code