Repository navigation
design: adapter output-schema versioning (deferred from #929) #1111
Description
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:
- Pin HF revision — caller specifies
revision="..."to lock to a known-good version of the adapter weights. - 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
AdapterSchemaMismatchErrorafter 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
AdapterSchemaMismatchErrorunder Jake req 4)
Activity
docs: resolve §17 Q3 + Q4; defer schema_version to generative-computi…
planetf1 commentedon Jun 11, 2026
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:
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 commentedon Jul 22, 2026
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
_DictContractto 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.
planetf1 commentedon Sep 3, 2026
Removed from epic #929's formal tracking (2026-09-03) — the team decided this isn't needed right now (pin-and-raise via
AdapterSchemaMismatchErrorremains sufficient; none of the trigger conditions listed above have occurred). Left open as standalone backlog per the issue's own "When to revisit" section — no change to the design questions or scope, just no longer a dependency of #929's closure.