Add caller-supplied invocation metadata (proposal 0034)

[chris-colinsky]

Summary

Implements observability §3.4 + §5.6 + §8.4.1/§8.4.2 (proposal 0034): callers pass invoke(metadata={...}) and the framework propagates the entries to every observability backend uniformly. OTel emits each entry as a cross-cutting openarmature.user.<key> span attribute on every span; Langfuse merges each entry as a top-level key into trace.metadata and every observation.metadata.

Public surface

• compiled.invoke(metadata=...) — optional dict[str, AttributeValue] mapping per the spec's OTel-AnyValue-compatible value contract (str / int / float / bool / homogeneous arrays).
• openarmature.observability.set_invocation_metadata(**entries) — public augmentation helper; additive merge.
• openarmature.observability.current_invocation_metadata() — public reader; returns empty MappingProxyType outside an invocation.
• Synchronous boundary validation: keys under openarmature.* / gen_ai.* raise ValueError BEFORE any work begins; non-OTel-compatible value types raise the same.

Engine internals

• New module src/openarmature/observability/metadata.py owns the ContextVar, validation, and lifecycle helpers. Engine drives _set_invocation_metadata / _reset_invocation_metadata around the outermost invoke().
• NodeEvent.caller_invocation_metadata and LlmEventPayload.caller_invocation_metadata carry dispatch-time snapshots. Observers read from the snapshot rather than the live ContextVar because the deliver_loop task's Context is frozen at invoke time and would NOT reflect mid-invocation augmentations made by node bodies running in the main engine task.

Conformance fixtures

• 026-otel-caller-supplied-metadata — verifies openarmature.user.* on every span. Activated.
• 027-langfuse-caller-supplied-metadata — verifies trace + every observation propagation. Activated.
• 028-caller-metadata-namespace-rejection — verifies the API boundary rejects reserved-namespace keys before any work begins. Activated via a dedicated _run_fixture_028 runner that attaches both observers and asserts ValueError + no spans + no Langfuse traces.
• 029-caller-metadata-fan-out-per-instance and 030-caller-metadata-parallel-branches-per-branch — deferred: they need a new augment_metadata_from_field harness primitive that calls set_invocation_metadata per fan-out instance / per parallel branch. The augmentation surface itself is already exercised by unit tests; the conformance fixtures un-defer in a follow-up.

Test plan

• 25 new unit tests in tests/unit/test_observability_metadata.py covering boundary validation, ContextVar lifecycle, augmentation merge/overwrite, reserved-namespace rejection, invoke()-boundary rejection, mid-invocation augmentation persisting to subsequent nodes, openarmature.user.* emission on every OTel span, Langfuse top-level merge on trace + every observation.
• Full unit + conformance suite — 910 passed, 120 skipped.
• ruff check / ruff format --check clean.
• pyright clean across changed files.
• 029 / 030 un-defer once the augment_metadata_from_field harness primitive lands.

[Copilot]

Pull request overview

Implements proposal 0034 (observability §3.4 + §5.6 + §8.4.1/§8.4.2): callers may pass metadata={...} to invoke(), and the framework propagates each entry uniformly to OTel (as openarmature.user.<key> span attributes) and Langfuse (top-level trace.metadata and every observation.metadata). The metadata flows via a ContextVar with per-async-context COW semantics; observers read dispatch-time snapshots stashed on NodeEvent / LlmEventPayload because the deliver_loop task's Context is frozen at invoke time.

Changes:

• New observability/metadata.py module: ContextVar, synchronous boundary validation (reserved-prefix and OTel-AnyValue-compatible types), and engine-internal lifecycle helpers; wired into CompiledGraph.invoke with a metadata= kwarg.
• OTel and Langfuse observers apply caller metadata at every span / observation emission site; NodeEvent and LlmEventPayload gain a caller_invocation_metadata snapshot field.
• New unit tests + activated conformance fixtures 026/027/028 (029/030 deferred awaiting an augment_metadata_from_field harness primitive).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/openarmature/observability/metadata.py	New module: ContextVar, validators, public reader/augmenter, engine lifecycle helpers.
src/openarmature/observability/init.py	Re-exports the two public helpers.
src/openarmature/graph/events.py	NodeEvent gains caller_invocation_metadata snapshot field.
src/openarmature/graph/compiled.py	invoke() validates & seeds the ContextVar; dispatch sites pass the snapshot.
src/openarmature/observability/llm_event.py	LlmEventPayload gains the dispatch-time snapshot field.
src/openarmature/llm/providers/openai.py	LLM provider captures the snapshot when building the event.
src/openarmature/observability/otel/observer.py	Emits openarmature.user.<key> on every span.
src/openarmature/observability/langfuse/observer.py	Merges entries into trace + every observation metadata.
tests/unit/test_observability_metadata.py	New 25-test suite for validation, lifecycle, augmentation, and observer emission.
tests/conformance/test_observability.py	Activates fixtures 026 & 028; adds dedicated _run_fixture_028 rejection runner; multi-node LLM-fixture support.
tests/conformance/test_observability_langfuse.py	Activates fixture 027; threads metadata= into invoke.
tests/conformance/test_fixture_parsing.py	Updates skip rationales for 027/028/029/030.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.