Skip to content

schema: major-version migration to top-level kind discriminator for FallowOutput #413

@BartWaardenburg

Description

@BartWaardenburg

Blocked on next major version bump. Filing now so the prose promise in crates/cli/src/output_envelope.rs:1083-1086 and docs/backwards-compatibility.md:23 exists as a tracked issue rather than only as inline commentary that risks evaporating.

Today

FallowOutput is #[serde(untagged)] so consumers must variant-narrow by checking unique-field presence (e.g. summary.total_issues for check, health_score for health, etc.). This is documented in docs/backwards-compatibility.md and works correctly today, but every consumer pays the field-presence-test tax on every payload.

Plan

  1. Add #[serde(tag = "kind")] to FallowOutput, switching to internally-tagged untagged-fallback semantics so payloads carry a unique top-level kind: "<command>" field.
  2. Ship one minor cycle with a --legacy-envelope opt-out flag that re-emits the untagged form for consumers that need a deprecation grace period.
  3. Remove --legacy-envelope in N+1.

Impact

  • AI agents and MCP consumers get O(1) variant narrowing.
  • Schema-validating clients can drop their unique-field-presence rules.
  • This is a wire-shape change so it must bump schema_version and ride the next major bump.

Acceptance

  • FallowOutput carries #[serde(tag = "kind")] in crates/cli/src/output_envelope.rs.
  • docs/backwards-compatibility.md documents the new discriminator and the --legacy-envelope deprecation timeline.
  • CodeClimateOutput stays an untagged sibling (the array shape cannot carry an internal tag); discriminate against it via root-level "is it an array" first.
  • The inline doc comment on FallowOutput is updated to reflect the new shape.

Refs #384 (this completes the typed-root work that #391 started).

Metadata

Metadata

Labels

area:schemaJSON schema and output contract surfacesenhancementNew feature or requestpriority:lowDeferred cleanup, blocked dependency work, or nice-to-haverustPull requests that update rust codestatus:major-versionRequires a major-version or breaking-contract window
No fields configured for Feature.

Projects

Status
Done

Relationships

None yet

Development

No branches or pull requests

Issue actions