deps: eradicate Zod 3 and align Zod on npm — three Zod instances coexist and npm peers requiring ^4.0.0 resolve to 3.25.76

[rickylabs]

Type soundness is a primary selling point (#1278). Right now the dependency graph quietly holds three different Zod module instances, and packages that require Zod 4 are being handed Zod 3.

Measured on origin/main

deno info npm:@modelcontextprotocol/sdk
  peer zod@^4.0.0: resolved to 3.25.76      ← violated constraint, not a preference
  npm:/zod@3.25.76
deno info npm:@anthropic-ai/sdk   → peer zod@^4.0.0: resolved to 3.25.76
deno info npm:openai              → peer zod@^4.0.0: resolved to 3.25.76  (×2 paths)

The three instances in one lock:

Instance	Who binds to it
jsr:@zod/zod@4.4.3	18 workspace deno.json files — all of our own code
npm:zod@4.4.3	better-call@1.3.6 (better-auth path)
npm:zod@3.25.76	@anthropic-ai/sdk, @modelcontextprotocol/sdk, openai, @tanstack/ai-mcp, zod-to-json-schema

Most of the cluster does not pin v3 — but two paths do (corrected 2026-08-05)

Every package in that v3 cluster already accepts Zod 4:

Package	peerDependencies.zod
@anthropic-ai/sdk	^3.25.0 || ^4.0.0
@modelcontextprotocol/sdk	^3.25 || ^4.0
openai	^3.25 || ^4.0
zod-to-json-schema (3.25.2, latest)	^3.25.28 || ^4

So there is no upstream blocker to remove — this is ours to fix. The npm subgraph has no npm-side Zod 4 to dedupe onto because our own code supplies Zod from JSR, so Deno resolves those peers independently and lands on 3.25.76.

Why it is a correctness problem, not tidiness

A schema built with jsr:@zod/zod is a different module instance from npm:zod@4.4.3 and from npm:zod@3.25.76. Across that boundary instanceof fails, brand/nominal checks fail, and structurally-identical types stop being assignable — the class of failure that produced #1250 (Zod-3 plugin against Zod-4 scaffolds, every numeric query param 400ing) and #1249. It also means an AI-plugin path can hand a v4 schema to an SDK holding v3.

Also: the catalog is npm-only (AGENTS.md), so while Zod comes from JSR it cannot live in the catalog — there is no single source of version truth for the repo's most cross-cutting dependency.

Acceptance (rescoped 2026-08-05 — see the correction comment)

The original "exactly one Zod instance" bar is not reachable in 0.0.5: @ag-ui/core@0.0.52
hard-depends on zod: ^3.22.4 with no || ^4, and jsr:@olli/kvdex@3.6.7 (latest) also
materialises Zod 3. Collapsing to one instance needs either a TanStack AI 0.39→0.43 cluster
upgrade — which currently drags in a canary AG-UI build — or replacing/forking/removing
kvdex. Neither belongs in a release we are about to cut.

Scoped to what is real and verifiable now:

• The AI/MCP peer cluster (@anthropic-ai/sdk, @modelcontextprotocol/sdk, openai,
  zod-to-json-schema) resolves onto npm Zod 4 — no peer zod@^4.0.0: resolved to 3.x
  line survives for any of them in deno info
• Workspace Zod expressed once in the root catalog rather than repeated across 18
  deno.json files
• A guard test fails CI on a split Zod graph, so the boundary can never regress silently
• @orpc/zod usage is on the v4 surface throughout (consistent with the service: ZodSmartCoercionPlugin imported from @orpc/zod (Zod 3) while scaffolds use Zod 4 — coercion silently no-ops, every numeric query param 400s #1250 fix)
• The remaining two-instance boundary is documented with its exact blocking dependencies
  (@ag-ui/core hard ^3.22.4, jsr:@olli/kvdex@3.6.7) rather than left implicit
• publish:dry-run and deno doc --lint stay clean across the 18-package change

Collapsing to a single instance moves to 0.0.6, gated on AG-UI accepting Zod 4 or a kvdex
decision. Filed separately so it is tracked rather than forgotten.

[rickylabs]

Correction to my own issue body, and a rescope decision for you.

I wrote: "Nothing pins v3 on purpose — every package in that v3 cluster already accepts Zod 4." That is wrong. I sampled four packages (@anthropic-ai/sdk, @modelcontextprotocol/sdk, openai, zod-to-json-schema), found they all accept ^4, and generalised to the whole cluster. The slice used deno why npm:zod@3.25.76 — the right instrument — and found two hard ^3 paths I never checked:

• @ag-ui/core@0.0.52 hard-depends on zod: ^3.22.4 — no || ^4, so it cannot be satisfied by Zod 4 at all.
• jsr:@olli/kvdex@3.6.7 also materialises Zod 3, and 3.6.7 is the latest release.

So the AI/MCP peer cluster does dedupe cleanly onto npm Zod 4 — that part of the measurement held — but the "exactly one instance" acceptance criterion cannot be met today without one of:

1. TanStack AI cluster upgrade (0.39 → 0.43 with all adapters coordinated). Complication: 0.43 currently pulls a canary AG-UI version, so this trades a Zod split for a pre-release dependency.
2. kvdex: replace, fork, remove, or accept an explicit compatibility override.

The slice stopped and escalated rather than forcing Zod 4 through packages declaring hard ^3, or weakening the guard to make the criterion pass. Both would have been false greens, and stopping was correct.

What I propose landing now regardless of that decision: the guard test it already built (test(deps): make split zod graphs fail CI). It makes the split visible and prevents silent regression, which is worth having whether or not we can collapse to one instance yet. The acceptance criterion "exactly one Zod instance" then stays honestly unticked until the AG-UI/kvdex path is decided.

Your call on 1 vs 2 vs accepting a documented two-instance boundary for 0.0.5. I would not take option 1 as stated — swapping a type-identity split for a canary dependency in a release we are about to cut is a worse trade.

[github-actions]

Acceptance evidence mirrored from #1315.

• "The AI/MCP peer cluster (@anthropic-ai/sdk, @modelcontextprotocol/sdk, openai," — Pinned adapter deno-info graphs for Anthropic, MCP, OpenAI, and zod-to-json-schema resolve zod@4.4.3 with no peer-to-3 warning; live graph guard enforces this
• "Workspace Zod expressed once in the root catalog rather than repeated across 18" — deno.json owns zod ^4.4.3 once; 19 discovered workspace consumers use catalog: and the guard rejects local/JSR specifiers
• "A guard test fails CI on a split Zod graph, so the boundary can never regress silently" — .llm/tools/deps/check-zod-alignment_test.ts has six controls and deps:check runs the live guard; unknown v3 parents and split AI/MCP paths fail
• "@orpc/zod usage is on the v4 surface throughout (consistent with the service: ZodSmartCoercionPlugin imported from @orpc/zod (Zod 3) while scaffolds use Zod 4 — coercion silently no-ops, every numeric query param 400s #1250 fix)" — packages/sdk/src/openapi/helpers.ts imports @orpc/zod/zod4; guard scans workspace source and rejects the compatibility root surface
• "The remaining two-instance boundary is documented with its exact blocking dependencies" — docs/architecture/zod-dependency-boundary.md names @ag-ui/core hard ^3.22.4 and jsr:@olli/kvdex@3.6.7 plus deps: collapse to a single Zod instance — blocked on @ag-ui/core hard ^3 and kvdex #1320 watch signals; guard permits exactly those parents
• "publish:dry-run and deno doc --lint stay clean across the 18-package change" — Full workspace publish:dry-run passed; deno doc --lint passed every export across all 19 affected package/plugin roots

Provenance: updatedAt=2026-08-05T09:42:56Z; bodySha256=d3e5b95a73f8cb9f05bfeb891c90470aa3967dbff912cb72ee0819f799a5030e