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 Adapter Function 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)

[planetf1]

This issue uses vocabulary that has been superseded by the agreed Epic #929 glossary. Please use the following terms in any new work related to this issue:

Old term	Preferred term
intrinsic / intrinsic function	adapter function
activated-LoRA / Activated LoRA	aLoRA
Project Granite Switch	Granite Switch
cache rewrite (re: aLoRA)	cache hit / cache miss

The canonical definitions are now in the project glossary and were established as part of #1192. Python symbol names (IntrinsicAdapter, fetch_intrinsic_metadata, etc.) keep their current names until Phase 1 (#1136) and Phase 4 (#1144).

[planetf1]

Still sensible to keep this parked. Both deferral mechanisms are in place and holding: AdapterSchemaMismatchError (mellea/backends/adapters/_core.py) and revision pinning (catalog.py/adapter.py). None of the promotion triggers listed above have fired.

The stronger reason to wait, though, is that the substrate this design would sit on is mid-refactor. Output-schema versioning has to build on the adapter output-contract representation, which is being reshaped right now in Epic #929 Phase 2 — notably #1412 (promote _DictContract to a shared module and collapse guardian's factuality contracts onto it), plus #1140 (AdapterMixin verb rename/narrow) and #1141. Designing versioning before those settle means designing against a moving API.

Suggest revisiting once Phase 2 and #1412 merge: at that point the contract type is stable, and the open design questions (where the version field lives, parser dispatch keying, deprecation path, the granite-common conversation) can be answered against a fixed substrate.