chore: migrate footprinter to zod v4

[DPS0340]

Summary

• require zod@^4 and circuit-json@^0.0.455 as peers so composed schemas use one Zod major
• migrate record, transform-default, and error APIs while preserving generated Circuit JSON
• add Zod v4 regressions and document the peer-dependency requirement

Dependency order

This is intentionally a draft until circuit-json PR #661 merges and its release workflow publishes circuit-json@0.0.455. The coordinated rollout is circuit-json, footprinter, @tscircuit/props, then core. The exact 0.0.455 range prevents a Zod 3 circuit-json schema from being composed with this package.

Verification

• bun test
• bunx tsc --noEmit
• bun run build
• biome formatting check
• npm pack --dry-run
• byte-for-byte Circuit JSON comparison against the Zod 3 baseline for representative footprints

[DPS0340]

The failed build job did not reach the build step: bun install failed while sharp downloaded libvips with a GitHub 504 Gateway Time-out. The same branch passes bun run build locally, and the PR test/format checks are green. I attempted to rerun only the failed job, but GitHub requires repository-admin permissions for that action.

[DPS0340]

Dependency coordination update: commit 123b945 now requires circuit-json@^0.0.455, the Zod 4 release emitted after circuit-json PR #661 merges. The branch is intentionally stacked, so registry-only CI cannot install that version until then. Local Zod 4 validation remains green: bun test, bunx tsc --noEmit, and bun run build.

[DPS0340]

Now green and ready for review — circuit-json@0.0.455 is published, so the earlier install failure is resolved.

Verified on the current head:

• bun install resolves cleanly
• bun run build succeeds
• bun test → 463 pass / 0 fail (208 files)

CI on this branch is passing (Build, Bun Test, Format Check). This is the footprinter half of the Zod v4 migration tracked in tscircuit/core#2810.

[DPS0340]

Note on the red checks here: this is blocked upstream, not by anything in this PR.

The published circuit-json@0.0.455 still ships Zod v3-shaped types (z.ZodEffects, 5-parameter ZodObject), which don't exist in Zod v4. Any package composing those schemas under v4 fails type-check no matter what this PR does.

Unblocked by tscircuit/circuit-json#661, which is green and ready — once that merges and publishes, I'll refresh this branch and the checks should go green.

Happy to close this and reopen after the circuit-json release if you'd rather not have a red PR sitting in the queue.

[DPS0340]

Same blocker as tscircuit/props#752, re-verified today.

The failing CI here predates circuit-json@0.0.455 being published (run at 16:33 UTC, publish at 21:23 UTC), so the recorded No version matching "^0.0.455" error is stale — install succeeds now.

The real blocker is unchanged: the published 0.0.455 build still ships v3-shaped types.

$ grep -c "ZodEffects" node_modules/circuit-json/dist/index.d.mts
2813

ZodEffects doesn't exist in Zod v4, so type-check fails here no matter what this diff contains.

tscircuit/circuit-json#661 must merge and publish first. It's MERGEABLE/CLEAN, self-contained, and blocks both this and props#752.

Happy to close and reopen after that lands if a red check is unhelpful in the meantime.

[DPS0340]

Pushed 7c3d968, which should clear the one red check.

What was failing and why. Only Format code was red — build, test and format-check were all green. The failure wasn't formatting at all, it was the install step:

npm error Found: zod@4.4.3
npm error Could not resolve dependency:
npm error peer zod@"3" from @tscircuit/circuit-json-util@0.0.89

The split is that formatbot.yml installs biome with npm, while bun-formatcheck.yml uses bun. npm enforces peer ranges and bun doesn't, so the same tree installs fine in three workflows and hard-fails in the fourth. Once this PR moves the repo to zod@^4.0.0, @tscircuit/circuit-json-util's "zod": "3" peer becomes unsatisfiable under npm.

Worth noting the pin isn't something a version bump escapes — I checked 0.0.90, 0.0.95, 0.0.100 and 0.0.101 (latest) and every one still declares "zod": "3".

Fix is a five-line overrides entry rather than touching any source:

"overrides": { "@tscircuit/circuit-json-util": { "zod": "^4.0.0" } }

That's accurate rather than a suppression: circuit-json-util is only used in tests, and only for transformPcbElements — tests/fixtures/compareFootprinterVsKicad.ts and tests/kicad-parity/diodes/diode_kicad_parity.test.ts, no runtime import. @tscircuit/soup-util already declares "zod": "*", so it needs nothing.

Verified both package managers and the full suite, since an override that fixes npm could easily break bun:

npm install @biomejs/biome@1.9.4   added 252 packages   (failed before)
bun install                        173 packages, clean
bun test                           463 pass / 0 fail
bunx biome format .                352 files, no fixes applied
bun run build                      ESM + DTS success

I also confirmed this is specific to the branch and not pre-existing: the same npm install succeeds on main (where zod is ^3.23.8) and fails on this branch without the override.

One sequencing note for the chain: this PR is downstream of circuit-json#661. circuit-json@0.0.455 still ships v3-shaped declarations (import { z } from 'zod', 688 ZodEnum<[...]> occurrences), so the full chain is circuit-json#661 → props#752 → this. This one's checks pass independently, but the ecosystem is only coherent once #661 publishes.