feat(schema): add MCP 2026 JSON Schema projections

[bokelley]

Summary

• generate compact, self-contained JSON Schema 2020-12 input/output artifacts for every canonical AdCP tool under the MCP 2026-07-28 projection path
• preserve v3 draft-07 validation semantics while enforcing local-reference integrity and AdCP-defined defensive depth, object-count, and compact-byte bounds
• enter Changesets beta pre-mode for 3.2.0-beta.0 and document the 3.2 projection / 4.0 canonical migration boundary
• keep MCP projection artifacts out of the legacy draft-07 SDK validation overlay

Why

MCP 2026-07-28 defaults embedded tool schemas to JSON Schema 2020-12, requires implementations to support that dialect, and recommends its use; explicit alternative dialects remain allowed. AdCP v3 remains canonically draft-07. This projection provides MCP-compatible discovery artifacts without changing the v3 payload contract or prematurely introducing 4.0 contract tightening.

The artifacts are downloadable and opt-in for server tools/list registration; publishing them does not alter runtime tool registration automatically.

Validation

• schema build: 65 tools, 130 projected schemas, 10.32 MiB compact total, 866 KiB largest
• MCP projection tests: 9/9, including 672 real storyboard fixtures across 58 schemas (659 accepted, 13 rejected) plus 102 generated invalid mutations
• schema validation: 20/20 across 658 schemas
• composed-schema validation: 139/139
• schema build regressions: 27/27
• pre-commit repo tests: 1,025/1,025
• pre-commit server tests: 4,630 passed, 30 skipped
• current and released 3.0 storyboard matrices: all tenant floors passed
• Changesets resolves the prerelease to 3.2.0-beta.0

Expert review

Reviewed by MCP protocol, deep implementation, and Node.js test/release experts. Their findings on artifact size, runtime claims, draft-07 $ref sibling semantics, full-document bounds, source-dialect drift, JSON Pointer rewriting, and SDK cache isolation were addressed; no merge blockers remain.

Local environment note

The existing typecheck currently reports server/src/utils/otel-logs.ts(92,5) against the installed dependency graph; this branch does not modify that file or package-lock.json. PR CI remains authoritative.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated paths touched without required approval.

This PR adds a semantics-preserving JSON Schema 2020-12 MCP tool-schema projection (new scripts/mcp-schema-projection.cjs, wired into build:schemas), plus docs, a minor changeset, and a full-suite test. The transformer work is careful and unit-tested, and the reviewer surfaced no critical/high findings.

However, gated_paths is true and review_decision is REVIEW_REQUIRED (not APPROVED), so the hard approval gate (decision rule row 2) forces escalation regardless of how clean the diff is.

Escalation reasons

• .changeset/pre.json (added) and static/schemas/source/core/forecast-dimension-geo.json (modified) are under the hard approval gate (## Gated Paths). Human/CODEOWNERS review is required — review_decision is REVIEW_REQUIRED, not APPROVED.

Medium findings (non-blocking)

• tests/mcp-schema-projection.test.cjs:290 — Parity test barely validates the anti-tightening guarantee (nearly a no-op for schemas without top-level examples). Worth strengthening but not blocking.

The forecast-dimension-geo.json required-sibling removal was reviewed as semantics-preserving (necessitated by the fail-closed $ref-validation-sibling guard). Once a human/CODEOWNERS approval lands, this can proceed through the normal decision table.

Medium findings

• tests/mcp-schema-projection.test.cjs:290 — Parity test barely validates the anti-tightening guarantee

Why human review

• Touches gated paths .changeset/pre.json (added) and static/schemas/source/core/forecast-dimension-geo.json (modified) while review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required before merge.
• This PR touches a path under a hard, non-overridable approval gate (.changeset/pre.json (added) matches .changeset/pre.json; static/schemas/source/core/forecast-dimension-geo.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated path requires human/CODEOWNERS approval.

This PR modifies static/schemas/source/core/forecast-dimension-geo.json, which sits under the hard, path-based approval gate (static/schemas/source/**). gated_paths is true and review_decision is not APPROVED (unknown/none), so decision-table row 2 fires: Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

The reviewer found no blocking, High, or Medium code-correctness defects in the current delta: schema surface is fail-closed and const-discriminated, schema↔docs coherence holds, all new schemas are registered in index.json, all $ref targets resolve, and changesets are present and correctly scoped. The prior run's single medium finding (tests/mcp-schema-projection.test.cjs:290) targets a file absent from the current delta and is out of scope. On the merits the diff is clean — but the gate is deterministic and not overridable by a clean review.

Escalation reasons

• Modifies static/schemas/source/core/forecast-dimension-geo.json (matches gated glob static/schemas/source/**) while review_decision is not APPROVED — human/CODEOWNERS approval required before merge.

Why human review

• Modifies static/schemas/source/core/forecast-dimension-geo.json (matches gated path static/schemas/source/**) while review_decision is not APPROVED — human/CODEOWNERS approval required before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/forecast-dimension-geo.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — hard approval gate on gated paths not yet satisfied.

This PR modifies files under a hard, non-overridable approval gate:

• static/schemas/source/core/forecast-dimension-geo.json (matches gated path static/schemas/source/**)
• .github/workflows/build-check.yml (matches gated path .github/workflows/**)

gated_paths is true and review_decision is unknown/none (not APPROVED), so decision-table row 2 fires: the outcome must be escalate until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

Reviewer findings: none. The delta since the prior pass is a CI step correctly wired to the existing test:mcp-schema-projection npm script and test-only hardening (draft-07 vs 2020-12 validation parity from storyboard fixtures, mutation cases, count ratchets). No critical/high/medium findings. On the merits the diff is clean — but the gate is deterministic and lifts only on a real APPROVED review.

Escalation reasons (see below). Once a human/CODEOWNERS approval is recorded, this PR can fall through to a normal approve.

Why human review

• Touches static/schemas/source/core/forecast-dimension-geo.json (matches gated path static/schemas/source/**) and .github/workflows/build-check.yml (matches gated path .github/workflows/**) while review_decision is not APPROVED — human/CODEOWNERS approval required before merge.
• Prior decision was escalate for the same gated-path reason; the gate remains unsatisfied (review_decision still not APPROVED).
• This PR touches a path under a hard, non-overridable approval gate (.github/workflows/build-check.yml (modified) matches .github/workflows/**; static/schemas/source/core/forecast-dimension-geo.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.