feat(telemetry): emit adapter-function prepare/activate/deactivate spans from a tracing plugin

[planetf1]

Pull Request

Issue

Progresses #1466 (partial: lifecycle spans only — see "Where this fits" below for why this isn't Fixes).

Summary

Adapter functions — the LoRA/aLoRA models Mellea uses for RAG checks, safety checks, and core capability checks (answerability, requirement_check, etc.) — go through a five-phase lifecycle: prepare (download weights), activate, generate, parse, deactivate. None of it is observable today. If an adapter fails to download, activation hangs, or a deployment intermittently can't load a specific adapter, there is currently no trace showing where the time went or what failed — only a counter that says an invocation happened, with no way to see its shape.

This PR closes that gap for three of the five phases: prepare, activate, deactivate. It adds the missing ADAPTER_FUNCTION_*_START hooks (the family previously had only *_COMPLETE members, so no plugin had an event to open a span on — the structural reason #1454's earlier attempt had to open spans inline instead), fires them from the real call sites, and adds a tracing plugin that turns the hook pairs into a proper adapter_function → adapter_function.<phase> span tree. generate/parse are excluded on purpose — they need real generation running inside adapter_scope, which is #1465's job, in progress in parallel right now.

This landed in two passes, both in this PR: an initial implementation, then an independent 3-reviewer pass (run before any human looked at it) that found two real ordering/guarding bugs and four untested error paths. Both are described below, with the bugs fixed and verified against the pre-fix code, not just against the fixed code.

Where this fits — Epic #929, Phase 2

Per the epic's phase tracker, #1466 is one of six issues in the current parallel batch (#1142, #1516, #1465, #385, #1528, and this lifecycle-span slice of #1466), started 2026-08-18. Specifically:

• Blocked by refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465 for the generate/parse spans only — that issue wires real generation through AdapterMixin.adapter_scope, which these two spans need. The lifecycle spans in this PR (prepare/activate/deactivate) don't depend on it and can land independently.
• Blocks refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144 (last in the epic chain — shim removal + tutorial rewrite), which needs all of Phase 2 merged, including generate/parse from a follow-up to this PR.
• Not blocked by and doesn't block feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142, refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516, bug: broken aLora example after intrinsics refactor #385, or refactor(backends): release() leaves the adapter registered; is a binding reusable after release? (Epic #929) #1528 — those are independent axes in the same batch.
• Settles nothing new on span/metric naming or the hook→plugin rule — both were already fixed by earlier epic decisions (documented on Epic: Fix Adapter Function Lifecycle & Consistency in Mellea #929) and this PR follows them, it doesn't relitigate them.

What this PR deliberately does not include, so reviewers don't file findings against its absence:

• adapter_function.generate / adapter_function.parse spans and their MELLEA_TRACES_CONTENT content-capture wiring — both need refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465.
• A span or hook for the release phase — WeightsBinding.release() runs outside any invocation, unlike the other four phases; see "Acceptance criteria" below for how the phase Literal still accounts for it.
• Exemplar linkage between mellea.adapter_function.phase_duration and these spans — a known, documented gap; see "Two deliberate deviations" below.

What changed

Area	Change
mellea/plugins/types.py, mellea/plugins/hooks/adapter_function.py	New ADAPTER_FUNCTION_INVOCATION_START / ADAPTER_FUNCTION_PHASE_START hooks, paired with the existing *_COMPLETE hooks; new invocation_id correlation field on all four payloads; release added to the phase Literal
mellea/backends/adapters/adapter.py	AdapterMixin.adapter_scope() fires the new start hooks around activate/deactivate, correlated by a per-scope invocation_id
mellea/backends/adapters/_core.py	LocalFileBinding.prepare() fires its own invocation-start/complete pair around its phase-start/complete pair, since it runs outside adapter_scope — this also guarantees invocation-complete always fires (even if prepare() raises), which the phase-complete hook's success-only contract can't
mellea/telemetry/tracing.py	New start_/finish_adapter_function_span and start_/finish_adapter_function_phase_span helpers, on the mellea.backend tracer
mellea/telemetry/tracing_plugins.py	New AdapterFunctionTracingPlugin, turning the hooks above into the adapter_function span tree
docs/docs/observability/tracing.md	New adapter_function span section: schema, tracer-scope rationale, both deviations below. Replaces docs/dev/adapter_observability.md, which #1483/#1548 already deleted and folded into published docs and code
test/telemetry/test_tracing_adapter_function.py (new), test/backends/test_adapters/*, test/telemetry/test_metrics_plugins.py	Unit + integration coverage: hook firing, span nesting, registry drain on both success and failure, resolved-revision recording

Two deliberate deviations from the existing tracing conventions

1. Explicit span parenting, not ambient-context attach. Every other span family in this codebase nests via ambient OTel context attach, which needs Python 3.12+ (_CONTEXT_ATTACH_SUPPORTED). That mechanism can't work here: ADAPTER_FUNCTION_*_START/_COMPLETE fire from synchronous code (adapter_scope, prepare()) via _run_async_in_thread, which runs each hook as an independent task seeded from a fresh contextvars snapshot of the calling thread — an attach inside one hook's task is invisible to the next hook's snapshot. adapter_function.<phase> instead parents explicitly via trace.set_span_in_context, looked up by invocation_id. This works identically on Python 3.11 and 3.12+, so no version gating applies to this family — verified unconditionally with InMemorySpanExporter.
2. No exemplar linkage to mellea.adapter_function.phase_duration. Because no span in this family is ever ambiently attached, the pre-existing AdapterFunctionMetricsPlugin (a separate plugin subscribed to the same hooks) never has the right span current when it records — at best it samples an enclosing application span, never the adapter-function span the metric is about. This is a known, documented gap (in the plugin's docstring and in the tracing docs), not a silent one. Fixing it needs the metric recorded from inside the tracing plugin itself, a larger change left for a follow-up.

Independent review: two bugs found and fixed

Before this went to a human reviewer, three independent reviewer passes (escalated to the strongest available model, given the tracing/async domain) ran against the initial implementation. All three converged on the same two real bugs, each reproduced empirically:

1. Hook-ordering inversion in prepare(). adapter_function_invocation_complete fired before adapter_function_phase_complete on the success path — the phase-complete call sat outside the with block, after the invocation-complete call in the finally inside it. This silently made the tracing plugin's defensive dangling-child-span cleanup (documented as the failure-only path) the only path that ever closed adapter_function.prepare's span, and inverted the order adapter_scope uses for the same pair. Fixed by firing phase-complete from an else: clause, before the finally.
2. Unguarded payload construction in _fire_phase_start_hook. It built its hook payload outside its own try, so a non-str .revision on a duck-typed (non-LocalFileBinding) weights binding raised a pydantic.ValidationError that escaped adapter_scope entirely, aborting before activate() ever ran — exactly the failure the function's own docstring says it prevents. The sibling implementation in _core.py already guarded this correctly; adapter.py's now matches it. Fixed.

Both fixes are verified with a regression test each, and each test was confirmed to fail against the pre-fix code (reverted, observed the failure, restored) before being trusted — not just confirmed to pass on the fixed code. The same pass also flagged four adapter-function error paths with no test coverage at all (a failing prepare(), a failing invocation-start hook dispatch); all four are covered now. A handful of lower-severity cleanups from the same review — a dead attach_context parameter that could never be used correctly, a dict-iteration atomicity issue in the span-cleanup sweep, a stale docstring on adapter_scope still claiming "no start hook exists" (the exact gap this PR closes) — are folded in as well.

One finding was considered and deliberately deferred rather than actioned: renaming invocation_id to adapter_function_invocation_id to match the family-prefixed naming convention every sibling hook payload uses (tool_invocation_id, validation_id, etc.). It's a real, correctly-identified deviation, but nothing outside this PR constructs these payloads yet, and a broad rename late in this pass carried more regression risk than the naming inconsistency itself. Tracked here rather than silently dropped, for whoever picks it up.

Acceptance criteria

From #1466, honestly reflecting the lifecycle-only scope:

• ADAPTER_FUNCTION_* has a start hook to pair with each completion hook
• No telemetry.tracing import exists under mellea/backends/
• Spans are emitted by a plugin; the tracer scope choice is stated with its rationale — in docs/docs/observability/tracing.md, not docs/dev/adapter_observability.md, which no longer exists (see "Where this fits")
• adapter_function.prepare, .activate, .deactivate emitted as children of the adapter_function parent span — .parse needs refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465, not in this PR
• adapter_function.prepare records the resolved Hugging Face SHA as mellea.adapter_function.revision, not "main"
• MELLEA_TRACES_CONTENT=1 produces content-capture events — not applicable yet: no phase in this PR's scope carries adapter input/output content; that's generate/parse, via refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465
• No span name or attribute introduced here departs from the adapter_function / mellea.adapter_function.* convention
• release appears in the phase Literal, with a documented reason it has no firing site (WeightsBinding.release() runs outside any invocation)
• Parent/child edges asserted with InMemorySpanExporter — unconditionally, not version-gated, since explicit parenting (deviation 1 above) doesn't depend on _CONTEXT_ATTACH_SUPPORTED
• Exemplar linkage — documented as a structural gap instead (deviation 2 above), not covered by a test, since there's nothing for a test to observe
• The in-flight span registry drains to zero after a lifecycle, on both success and failure
• uv run pytest test/ -m "not qualitative" passes

Testing

uv run pytest test/ -m "not qualitative" — 3963 passed, 21 skipped (hardware-gated), 0 failures. ruff format --check / ruff check / mypy . clean. npx markdownlint-cli2 "docs/docs/observability/tracing.md" — 0 issues. Docstring quality gate (tooling/docs-autogen/audit_coverage.py --quality --fail-on-quality --threshold 100) — 100% coverage, 0 issues. git grep -n "telemetry.tracing" -- 'mellea/stdlib/*' 'mellea/backends/*' — exactly one hit, mellea/stdlib/session.py, the documented exception.

Assisted-by: Claude Code