design: adapter output-schema versioning (deferred from #929)

[planetf1]

Problem

Adapter outputs from granite-common (io.yaml) carry no version field today. Mellea has no mechanism for spanning v1 and v2 output shapes from a single helper without revision pinning.

This is fine for now. The lifecycle refactor (#929 / PR #1080) handles breaking output-schema changes via two mechanisms:

1. Pin HF revision — caller specifies revision="..." to lock to a known-good version of the adapter weights.
2. Raise AdapterSchemaMismatchError — helpers raise when parse cannot yield the declared output contract. Forward-compatible additions (an extra optional field) are tolerated; contract-breaking deltas are not.

PR #1008 demonstrated that silent schema drift is a real failure mode; the AdapterSchemaMismatchError mechanism would have surfaced it loudly.

Why this issue exists

Deferred from epic #929 / PR #1080 §17 Q4, agreed by Jake (planetf1/mellea#1080 comment 2026-05-20) and the proposal author. Pinning + raise-on-mismatch is sufficient until the cost of breaking changes proves otherwise; we explicitly chose not to bake versioning into the lifecycle refactor.

When to revisit

Promote to in-progress when one of these is true:

• granite-common ships repeated breaking output-schema changes within a short window
• callers regularly hit AdapterSchemaMismatchError after upstream weight pushes
• a customer needs to span both v1 and v2 output shapes simultaneously without revision pinning
• a customer asks for graceful upgrade paths that pinning alone cannot give

Open design questions (for when this is picked up)

• Where would a version field live — io.yaml, granite-common metadata, or Mellea-side?
• Parser-dispatch shape: keyed by (name, schema_version), or something else?
• Deprecation strategy for prior schemas
• Cross-team conversation with granite-common maintainers

Out of scope (today)

• Implementation
• Choosing between the design options above (premature until the trigger conditions hit)

Related

• Epic Epic: Fix Intrinsic Adapter Lifecycle & Consistency in Mellea #929 — adapter lifecycle refactor (parent)
• PR docs: design proposal for adapter lifecycle (#929) — review channel, do not merge #1080 — design proposal; deferral recorded in §17 Q4
• PR fix: move test_huggingface.py to granite4.1; and small rag intrinsic … #1008 — worked example: silent schema drift (would have surfaced as AdapterSchemaMismatchError under Jake req 4)