docs(schema): rewrite generator-unfriendly unions

[somus]

Pull Request

Summary

• Add canonical recursive jsonValue for explicit open-value sites.
• Rewrite tool_call, tool_call_aborted, and capability_change schema shapes into generator-friendly direct unions.
• Add focused invalid fixture for tool_call.truncated: true without args_size.

Related Issue

• None.

Public Impact

• No public contract change
• Spec or schema change
• Public package API change
• CLI behavior change
• Public URL or docs behavior change

Impact description:

• v0.1.0 schema representation changes preserve intended validation semantics and improve generated SDK type fidelity. No version bump.

Verification

• jq empty schema/*.json fixtures/validation/*.json passed.
• mise exec -- ajv compile --spec=draft2020 --strict=false --validate-formats=false -s schema/draft.json passed.
• mise exec -- ajv compile --spec=draft2020 --strict=false --validate-formats=false -s schema/v0.1.0.json passed.
• node scripts/check-schema-descriptions.mjs passed.
• Old/new schema comparison: schema validity unchanged for 459 fixture records.
• Targeted Ajv samples passed for truncation, abort scope, capability multi-delta, and jsonValue extension value.
• mise run check passed with sandbox cache warnings from mise.
• cmp -s schema/draft.json schema/v0.1.0.json passed.

Reviewer Notes

• Review focus: direct union shape for generators and preservation of existing validation semantics.

---

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4716dcab-279d-4c09-994b-ab72fe3e1e14

📥 Commits

Reviewing files that changed from the base of the PR and between e44f3f0 and bba72c2.

📒 Files selected for processing (5)

• fixtures/validation/README.md
• fixtures/validation/invalid-schema/tool-call-truncated-missing-args-size.trail.jsonl
• fixtures/validation/manifest.json
• schema/draft.json
• schema/v0.1.0.json

---

📝 Walkthrough

Summary by CodeRabbit

• Tests
  • Added validation test fixtures and configurations for edge case scenarios in tool call handling with truncated payloads and missing arguments.

Walkthrough

This PR adds a new validation test fixture for a tool call marked as truncated with missing arguments. It includes the fixture data file, the expected validation results and diagnostics in the manifest, and documentation of the scenario in the conformance manifest README.

Changes

Validation fixture for truncated tool call

Layer / File(s)	Summary
Fixture definition fixtures/validation/invalid-schema/tool-call-truncated-missing-args-size.trail.jsonl, fixtures/validation/manifest.json, fixtures/validation/README.md	A new fixture test case is added with a session event followed by a truncated tool call event. The manifest specifies the expected unmatched_tool_call_at_eof diagnostic at /id on line 2 under both strict and tolerant validation modes, tagged with classes W, R1, and R2. The scenario is documented in the manifest README.

🎯 1 (Trivial) | ⏱️ ~4 minutes

🐰 A truncated tool call hops into the test suite,
With missing args and diagnostics quite acute,
The fixture now validates this edge case true,
From session seed to warning, all the way through!

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch somus/schema-generator-friendly-unions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

Running ultrareview automatically — This PR rewrites core schema shapes (tool_call, tool_call_aborted, capability_change) into generator-friendly direct unions and adds a canonical recursive jsonValue type, affecting 5,073 lines across schema definitions and validation fixtures — a schema-level change with broad blast radius.... I'll post findings when complete.

[stage-review]

Ready to review this PR? Stage has broken it down into 7 individual chapters for you:

	Title
1	Define canonical recursive jsonValue type
2	Apply jsonValue to metadata and capability fields
3	Extract tool call argument definitions
4	Rewrite tool_call as direct union
5	Rewrite tool_call_aborted as direct union
6	Rewrite capability_change as direct union
7	Add validation fixture for truncated tool calls

_{Chapters generated by Stage for commit bba72c2 on Jun 13, 2026 10:29am UTC.}