Zod v4 breaks AI MCP schema emission

Context

The dependency update on origin/dev moved zod to ^4.4.3, removed the direct zod-to-json-schema dependency from package.json, and moved js-yaml to 5.2.0. The AI MCP validation and tool-listing path still carries Zod 3-era assumptions.

Live latest-open sweep: checked the latest 20 open issues immediately before filing; no equivalent Zod v4 / AI MCP schema compatibility ticket found. A2A in-flight sweep: checked the latest 30 all-state messages immediately before filing; no overlapping [lane-claim] / [lane-intent] found.

The Problem

V-B-A found two concrete failures on the updated origin/dev dependency set:

1. zod-to-json-schema emits {} for Zod v4 schemas. Direct probe:

   • zodToJsonSchema(z.object({a:z.string()}), {target:'openApi3',$refStrategy:'none'}) -> {}
   • z.toJSONSchema(z.object({a:z.string()})) -> object schema with properties, required, and additionalProperties:false
   • z.toJSONSchema(z.array(z.unknown())) -> array schema with items:{}

2. js-yaml@5.2.0 no longer provides a default ESM export. Direct probe:

   • import * as yaml from 'js-yaml' works and exposes yaml.load
   • import yaml from 'js-yaml' throws SyntaxError: The requested module 'js-yaml' does not provide an export named 'default'

The existing targeted unit suite currently fails before its assertions with that js-yaml import error.

The Architectural Reality

The affected runtime surface is the AI MCP tool-shape compiler:

• ai/mcp/ToolService.mjs imports yaml as a default and imports zodToJsonSchema from zod-to-json-schema to publish inputSchema / outputSchema for tools/list.
• ai/mcp/validation/openApiValidator.mjs builds the Zod schemas consumed by ToolService.
• ai/services.mjs also imports yaml as a default for OpenAPI-backed service validation.
• Several AI services and unit tests import js-yaml as a default and must be compatible with js-yaml@5 ESM exports.
• test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs imports zod-to-json-schema directly and encodes Zod 3-era converter behavior.

The Fix

• Replace direct runtime use of zod-to-json-schema in ai/ with Zod v4's built-in JSON Schema emitter (z.toJSONSchema(...) or equivalent local helper).
• Preserve the OpenAPI/MCP schema semantics currently required by clients: object strictness for inputs, passthrough/open output objects where intended, array items:{} for unknown arrays, and no hollow {} schemas in tools/list.
• Replace default js-yaml imports in ai/ and targeted AI unit tests with namespace imports that work under js-yaml@5.
• Update targeted tests away from zod-to-json-schema expectations and toward Zod v4's built-in emitter.

Contract Ledger Matrix

Decision Record impact

none

Acceptance Criteria

• All ai/ runtime imports of js-yaml are compatible with js-yaml@5.2.0 ESM exports.
• ai/mcp/ToolService.mjs no longer depends on zod-to-json-schema for runtime schema emission.
• Zod v4 JSON Schema emission preserves MCP schema requirements covered by the existing OpenAPI validator compliance tests.
• Targeted AI Zod/OpenAPI unit tests pass under zod@4.4.3.
• A source sweep over ai/ finds no remaining runtime zod-to-json-schema import.

Out of Scope

• No broad package update or audit fix; dependency versions are already updated on origin/dev.
• No changes outside the AI Zod/OpenAPI/YAML compatibility path unless a targeted test proves they are required.
• No redesign of the OpenAPI-to-Zod bridge beyond the minimum needed for Zod v4 compatibility.

Avoided Traps

• Do not keep using zod-to-json-schema just because it remains hoisted transitively; it is no longer a direct dependency and emits hollow schemas for Zod v4.
• Do not file or patch from package-name assumptions alone; this ticket is grounded in runtime probes against the updated dependency set.

Related

• Dependency update landed on origin/dev before this ticket.

Origin Session ID: b36a73d4-b659-4cd0-8c21-3c497b99857c

Handoff Retrieval Hint: "Zod v4 breaks AI MCP schema emission js-yaml default import zod-to-json-schema emits empty object"