Epic: Fix Adapter Function Lifecycle & Consistency in Mellea #929

Resolve systemic issues with how adapter functions are loaded, invoked, and configured across backends. We should finalize a design for the below points and then create issues for that finalized implementation.

Initial implementation of EmbeddedIntrinsicAdapters in: #881
Initial removal of OpenAI adapters: #543

1. Adapter Loading & Unloading
   a. Clean up divergent control flow between EmbeddedAdapters and regular adapter function loading.
   b. Fix bug where obtain_lora is always called during call_intrinsic when embedded_adapters=False, which masks the real error from users and conflicts with different loading methods.
   c. Address that adapter loading/unloading is both backend-specific and adapter-type-specific — design a coherent abstraction for this.

2. Model Option Handling
   a. Fix adapter function rewriters overwriting model options unconditionally.
   b. Decide and document how adapter functions should interact with model options.
   c. There's a larger question of hierarchy with model options as well. Model options can technically be defined in all the following places: hf base model defaults in generation_config.json, adapter defaults in generation_config.json, io.yaml defaults, io.yaml values specified in the Mellea adapter function, mellea model options.

3. Naming Consistency
   a. Resolve whether adapter name must equal adapter.intrinsic_name or can differ (open issue).
   b. Standardize usage of "adapter name", "adapter function name", and "qualified name" across the codebase.
   c. refactor(intrinsics): decouple capability registry from catalog entry names (Epic #929 Phase 0) #1186 Decouple the capability registry from catalog entry names — Phase 0 follow-up. The role→capability rename is merged in feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1134 (PR feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1158); the catalog-side decoupling is next in sequence once fix(intrinsics): pin catalogue entries to HF revision SHAs + deduplicate requirement_check (#1135) #1157 (fix(intrinsics): pin catalogue entries to HF revision SHAs + deduplicate requirement_check entries (Epic #929 Phase 0) #1135) and feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1158 (feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1134) merge.
   d. fix(adapters): correct IntriniscsCatalogEntry class name typo (Epic #929 Naming) #1268 Fix IntriniscsCatalogEntry class name misspelling (Intriniscs → Intrinsics) — mechanical rename across 5 files; do after chore(terminology): adopt agreed Granite Switch / Mellea glossary (#1192) #1256 and refactor(adapters): decouple KNOWN_CAPABILITIES from catalog entry names (#1186) #1266 merge.

4. Output Parsing & Generic Adapter Function Contracts
   a. Address the problem where top-level call_intrinsics helpers assume a single output structure (e.g., result_json["answerability"] vs result_json["answerability_likelihood"]). We likely need to work with the Granite Switch team here to set common assumptions.
   b. Determine whether all adapters of a given type must conform to a standard output schema (e.g., a single output field, required keys) or whether parsing should be adapter-specific.
   c. This also encompasses "versioning" of adapter functions. The same adapter function may be updated / changed to have a different expected output format and our top-level call_intrinsic functions only allow one version.

5. OpenAI Backend Support
   a. Add OpenAIAdapters back — requires discussion on the logic for pulling/registering these. EmbeddedIntrinsicAdapters should technically inherit from these.

6. Cleanup
   a. Remove or repurpose the catalog. We shouldn't mandate all adapter functions be part of the known catalog.

Settled design decisions

• Adapter API: one lifecycle, or two shapes? #1486 — "Adapter API: one lifecycle, or two shapes?" (closed as resolved
  2026-08-11). Outcome: neither. One shape, two jobs, varying on different axes —
  request reformatting comes from io_contract (varies by capability, identical
  across backends), activation goes on the binding as apply_activation (varies by
  deployment). Adapter keeps its three fields; nothing new is added.
  render_controls and set_request_adapter have no job left and are removed in
  feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142. Discharged into refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516 (contract axis) and a rescoped feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142
  (activation axis) — independent axes, so both can proceed in parallel. add support for granite-switch / embedded adapters on our huggingface backend #1018 is
  the acceptance test. This supersedes item 5a's "EmbeddedIntrinsicAdapters should
  technically inherit from these" — the answer is composition plus one binding per
  deployment, not an inheritance chain.
• Span and metric naming is fixed and not up for reinvention. adapter_function
  parent, adapter_function.<phase> children, mellea.adapter_function.* attributes
  and instruments, content gated on MELLEA_TRACES_CONTENT. Established by refactor(backends): AdapterMixin verb rename/narrow + resolve_model_options + IntrinsicMetricsPlugin (Epic #929 Phase 2) #1140 /
  PR refactor(backends)!: narrow AdapterMixin verbs, centralize option resolution, add AdapterFunctionMetricsPlugin skeleton #1422, documented in docs/dev/adapter_observability.md. Several issues in this
  epic previously specified an invented intrinsic.* / MELLEA_TRACE_CONTENT scheme
  that never existed in the codebase; corrected across feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141, feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142, refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144 and feat(telemetry): add complete adapter-function lifecycle observability #1466
  on 2026-08-11.
• Spans are produced by plugins, never inline in mellea/backends/. The source
  guidance is sufficient; docs(telemetry): document the hook/plugin span-production rule and enforce it (Epic #929) #1464 was intentionally closed after PR docs(telemetry): document hook/plugin span-production rule and enforce it #1545 review rather
  than adding a standalone import guard.
• design: adapter output-schema versioning (deferred from #929) #1111 removed from formal tracking (2026-09-03). Team decided output-schema
  versioning isn't needed now; unlinked as a sub-issue of this epic, left open as
  standalone backlog. See design: adapter output-schema versioning (deferred from #929) #1111 for the design questions and trigger conditions for
  revisiting.

Phase Tracker

Statuses and the "Depends on" column were reconciled against live issue, pull-request, and formal-dependency state on 2026-09-03. #1560, #1562, and #1574 all have approved PRs (#1609, #1607, #1608) finishing CI/merge queue — no code work left, just merge. #1111 has been unlinked from this epic (see Settled design decisions) and no longer appears in this tracker. #1144 is now the epic's only remaining active item — its scope was corrected today after research showed neither backend accepts a composed Adapter directly yet, so it's genuinely the epic's last unbuilt piece, not cleanup.

"⬜ Open, unclaimed" means no PR exists yet, not that the issue is unassigned.

Current status (reconciled 2026-09-03)

#1018 is merged. #1560, #1562, and #1574 are approved and finishing CI/merge queue — nothing left to do but merge. #1144 is now the epic's sole remaining active work: rewritten with a full stacked-PR spec (PR1 builds the composed-Adapter-direct path both backends currently lack, plus tests/docs/tutorials/CLI-template updates; PR2, stacked on PR1, deletes the three deprecated shim classes once nothing references them). #1111 removed from formal tracking, left open standalone. #1466 was already removed from formal tracking (2026-08-27, confirmed unlinked both directions) and isn't part of this epic.

Suggested order

1. Merge fix(backends): fire adapter_function_invocation_complete for embedded adapter calls #1609, fix(backends): serialize resolve_adapter() registration under the activation lock #1607, test(backends): add real-model GPU e2e for intrinsic adapter_scope routing #1608 (all approved, finishing CI).
2. Execute refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144's PR1 (additive), then PR2 (deletion, stacked) — see refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144 for the full spec.
3. Once refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144/PR2 merges, this epic's numbered scope is structurally complete; close Epic: Fix Adapter Function Lifecycle & Consistency in Mellea #929.