[giaBaoJS]

Fixes #1612, fixes #1511, fixes #1546

All three issues throw the same error from toJsonSchema when refs are in use:

type({ a: "string" }).or("null").toJsonSchema({ useRefs: true })
// Error: Unexpected JSON Schema input for structure: {}

With useRefs, toJsonSchema resolved every root in this.references into $defs. When a union is discriminated, the case nodes it builds are merged into referencesById too. They never show up in the output, and a case can be an intersection with no basis (here { a: string } with the object domain pruned off), so resolving it on its own hits the structure fallthrough and throws. The cyclic issue (#1546) is the same thing, since cyclic types turn useRefs on.

The fix records roots as toJsonSchemaRecurse emits a $ref to them and only resolves those. Iterating the Map also picks up roots first referenced from another definition. One side effect: unreferenced defs no longer show up in the output, which is why union7 drops out of the existing cyclic snapshot (nothing in that schema points to it).

I saw that the featherduster draft (#1685) does the same thing in ark/sets/toJsonSchema.ts. This is the smaller version for the current code, in case it helps before that lands.

Tests: added a useRefs block to ark/type/__tests__/toJsonSchema.test.ts with the repro from each issue. Each test checks that every $ref points to a def and every def is referenced. Without the source change, all three throw the error above. pnpm test passes (1790, up from 1787), and so do pnpm typecheckRepo and lint.

[pullfrog]

✅ No new issues found.

Reviewed changes

• ark/schema/roots/root.ts — toJsonSchema now allocates a ctx.refs Map when refs are in use and resolves only the roots actually reached via $ref, instead of every root in this.references. toJsonSchemaRecurse registers each $ref'd root into that Map, and the live Map iteration picks up roots first reached from another definition.
• ark/schema/shared/toJsonSchema.ts — adds the optional refs?: Map<string, BaseRoot> field to ToJsonSchema.Context.
• ark/type/__tests__/toJsonSchema.test.ts — new useRefs block with the repro from each linked issue plus an invariant helper asserting every $ref points at a def and every def is referenced.
• ark/schema/__tests__/jsonSchema.test.ts — drops the now-unreferenced union7 from the cyclic snapshot.

The fix is sound by construction: $ref is only emitted at root.ts:193, immediately after ctx.refs.set(this.id, this), so every emitted reference is guaranteed a definition, and only referenced roots are resolved. I confirmed the three new tests fail with Unexpected JSON Schema input for structure: {} against the base root.ts, and that pnpm test (1790 passing), pnpm typecheckRepo, and pnpm lint all pass on the head. The union7 drop is correct — nothing in the emitted schema references it.

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

[ssalbdivad]

thanks @giaBaoJS, love a PR that closes three issues at once! rebased it onto main (restored a flatMorph import #1694 started using) and merged