Skip to content

Make the schema source Zod 4 and prove the exports are unchanged - #663

Draft
kvz wants to merge 5 commits into
mainfrom
zod4-source
Draft

kvz wants to merge 5 commits into
mainfrom
zod4-source

Conversation

@kvz

@kvz kvz commented Nov 17, 2026

Copy link
Copy Markdown
Member

Why

Zod 3 has no fix for GHSA-mrhx-c7xc-m3w5 (high: memory exhaustion while validating oversized constrained collections); the fix exists only in Zod 4.6.6 and later. Our schemas are still written in Zod 3, and @transloadit/zod/v4 is derived from them by text rewrites. To move the schema source to Zod 4 without breaking anyone, we first need to turn that direction around and prove that nothing consumers receive changes.

Draft: opened so CI can confirm the result. It is one step of a larger Zod 4 migration whose plan is still being reviewed, and it has not been through review rounds yet.

What

  • @transloadit/zod and @transloadit/mcp-server require zod ^4.6.7 (first commit, on its own so its effect can be measured separately).
  • The schema source is now Zod 4, in packages/zod/alphalib/. It was produced by a re-runnable codemod (yarn workspace @transloadit/zod codemod:v4) that takes input and output directories, so the same conversion can be applied to the upstream schema tree later.
  • The Zod 3 export (@transloadit/zod/v3) and the SDK's Zod 3 schema copy (packages/node/src/alphalib) are generated from that source. yarn lint:zod-source, part of check and verify, fails when the two drift apart and names the command that fixes it.
  • Spots that cannot be derived mechanically (the interpolation helpers, a few type annotations) are kept as paired, marked Zod 3 / Zod 4 regions; the generator throws when a marker is missing.
  • All 922 optionalWithV3Semantics wrappers are kept. Idiomatic Zod 4 .optional() would fill in defaults that Zod 3 leaves out at 125 sites, so narrowing them is a separate, later change.

@transloadit/node, transloadit and @transloadit/types do not change: they stay on Zod 3 and their builds are byte-identical.

Proof

node scripts/prove-zod-exports.ts --base <ref> builds the base ref and the working tree from scratch and compares them. Any difference that is not in the checked-in allowlist (currently empty) fails the run.

Base = the dependency-bump commit, head = this branch: exit 0.

Area Compared Identical
packages/zod/src/v3 142 142
packages/zod/src/v4 143 143
packages/zod/dist 855 855
packages/types/src/generated 133 133
packages/types/dist 268 268
packages/node/dist 836 836
npm pack of packages/node 1053 1053
npm pack of packages/transloadit 1053 1053

Runtime layer, also identical: structural fingerprints of 1084 Zod 3 and 1084 Zod 4 exports, 26,828 parse probes (omitted, undefined and null at every optional site, plus minimal steps per Robot), and 1294 z.toJSONSchema documents.

Negative control: changing one .min(1) to .min(2) in the source makes the same run exit 1 with 148 runtime differences.

Base = main: 865 differences, exactly the set the dependency bump alone produces, all inside the Zod 4 export:

  • 8 declaration files: Zod 4.6 spells some classes differently, for example ZodInstanceOf<URL> instead of ZodCustom<URL, URL>.
  • 606 Zod 4 schema fingerprints (Zod internals).
  • 250 JSON Schema documents, for example type: ["string", "null"] instead of anyOf.

Parse results, the Zod 3 export, the generated types and both SDK packages are identical to main.

Staying checks: a round-trip unit test (regenerating the Zod 4 source from the generated Zod 3 tree reproduces it byte for byte), and runtime-parity.test.ts now covers every optional site around defaults.

Known, unchanged

toolCallPartBaseSchema.input (z.unknown()) may be omitted in the Zod 3 export and is required in the Zod 4 export. This difference exists on main and the proof shows it is the same before and after.

Checks

yarn check and yarn verify:full pass locally. The e2e tests need API credentials and were not run. No behavioral red test: this change is meant to change no behavior, and the proof and its negative control are the executed evidence for that.

No linked issue: the migration is tracked outside this repository.

🤖 Claimed by kvz on framework1/node-sdk since 2026-11-17 · resume: claude --resume d38be187-7c9b-4ff3-9d1a-6a15c9743991

kvz added 5 commits November 17, 2026 13:09
zod < 4.6.6 is affected by GHSA-mrhx-c7xc-m3w5. Raise the range in
@transloadit/zod and @transloadit/mcp-server to ^4.6.7. The SDK packages
keep zod 3.25.76.
The schemas that @transloadit/zod publishes now live as Zod 4 source in
packages/zod/alphalib. sync-v4 exports them (dropping Zod 3-only regions
and layout hints), and sync-v3 generates the Zod 3 tree from them.

- scripts/zod4-codemod.ts converts a Zod 3 alphalib tree into that source.
  It takes input and output directories so it can be run on a larger
  alphalib tree, fails when a patch anchor is missing or a construct would
  not round-trip, and records the parts that cannot be derived as paired
  `@zod-v4-only` / `@zod-v3-only` regions.
- optionalWithV3Semantics stays on every former `.optional()` site.
  Whitespace that preceded `.optional()` stays inside the wrapper, and
  `z.record(z.string(), …)` calls written that way in Zod 3 carry a hint,
  so the Zod 3 export reproduces the original text byte for byte.
- The SDK keeps compiling and publishing its tracked Zod 3 copy in
  packages/node/src/alphalib. `yarn lint:zod-source` fails when that copy
  and the Zod 4 source disagree.
- The ai-chat `.refine` rewrite no longer matched anything and is gone.
The parity fixtures never reached the optional sites whose inner schema
supplies a default, prefault or optional union. Walk every exported
schema pair and parse each such site omitted, as undefined and as null in
both versions.
…nged

scripts/prove-zod-exports.ts materializes a base ref and the working
tree (or a second ref) into temporary directories without git worktrees,
installs and builds each with its own scripts, and compares sha256
manifests of the generated Zod trees, the zod, types and node builds and
the npm pack contents of @transloadit/node and transloadit. Its runtime
probe compares schema fingerprints, a shared parse corpus and
z.toJSONSchema output. Differences fail unless the checked-in allowlist
explains them.
Describe the Zod 4 source, its generators and the export proof, and say
what the zod 4.6.7 requirement changes in the Zod 4 declarations and JSON
Schema output.
@kvz kvz self-assigned this Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant