[mosatch]

Description

OutcomeSnapshot is the one public seam a pipeline extension gets at OUTCOME_OBSERVED, but it says nothing about whose request it measured. An extension that wants to split what it observes (an exporter, a chargeback job, a budget alert) cannot tell projects, clients or conversations apart without patching core. This adds four read-only fields and fills them from values emit_request_outcome already has:

• attribution: {dimension: label}. For now project and client, from the same values the savings tracker books, and only when known.
• conversation_key: the handler's key, already on RequestOutcome.
• original_tokens: the pre-compression size, on the same tokenizer as tokens_saved.
• output_tokens_saved: the output-shaping estimate this request booked.

attribution is frozen into a read-only dict subclass (FrozenLabels) in __post_init__. The dataclass is already frozen, but a frozen field can still hold a mutable dict, so without this one extension could rewrite the labels the next one reads. A dict subclass rather than a MappingProxyType keeps the snapshot hashable, picklable and safe for dataclasses.asdict, copy.deepcopy and json.dumps, as it was before.

It also adds PipelineExtensionManager.add(). A proxy extension (headroom.proxy_extension) that also wants lifecycle events is installed after the manager exists, so it cannot be passed to the constructor. Adding the same object twice is a no-op.

This is PR 1 of the split proposed in #4676 (generic attribution labels). It stands on its own, and the later PRs only widen what goes into attribution.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• headroom/pipeline.py: OutcomeSnapshot.attribution, conversation_key, original_tokens, output_tokens_saved, and PipelineExtensionManager.add(). All new fields have defaults, so existing constructors are unchanged.
• headroom/proxy/outcome.py: emit_request_outcome fills the new fields.
• Tests: the fields and their immutability, add() (late attach, no duplicates) in tests/test_pipeline_outcome_stage.py, and end-to-end through emit_request_outcome in tests/test_proxy/test_conversation_savings.py.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

$ pytest tests/test_proxy tests/test_pipeline.py tests/test_pipeline_outcome_stage.py tests/test_5xx_accounting_all_providers.py
615 passed, 7 warnings in 62.72s          # upstream/main at bb8d18a5: 608 passed

$ ruff check <changed files> && ruff format --check <changed files>     # ruff 0.17.3
All checks passed!
4 files already formatted

$ mypy headroom
No errors in the changed files. The 12 errors reported are in ccr/mcp_server.py,
memory/mcp_server.py, memory/adapters/embedders.py and providers/model_metadata.py,
identical on upstream/main, from local mcp/library versions.

Real Behavior Proof

• Environment: macOS, a Headroom proxy serving as a LAN gateway for three machines.
• Exact command / steps: a superset of this change (the full RFC: one label set for request attribution (project, client, host, …) instead of one axis per dimension #4676 proposal) has run there since 2026-11-06 with an OUTCOME_OBSERVED extension reading these fields.
• Observed result: the extension reads per-request project, client and conversation from the snapshot with no core patch.
• Not tested: this exact subset was not deployed on its own; it is covered by the unit tests above.

Runtime Rollout Safety

• Rollout-managed feature(s): none
• Minimum rollout channel: n/a
• Stable/default behavior changed: no. The fields are new and additive, and nothing reads them unless an extension is enabled.
• Kill switch / disable path: n/a (extensions are already opt-in)
• Unsafe override required: no
• Qualification impact: none
• Rollback path: revert

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I did not edit CHANGELOG.md — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this)

Screenshots (if applicable)

N/A

Additional Notes

• No docs change here: the fields are documented on the dataclass. User-facing attribution docs come with PR 2 of RFC: one label set for request attribution (project, client, host, …) instead of one axis per dimension #4676.
• attribution uses a mapping rather than more scalar fields so that later dimensions (host, team, …) need no further change to this contract.

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[devin-ai-integration]

Devin Review found 1 potential issue.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 72.00000% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
headroom/pipeline.py	72.00%	7 Missing ⚠️

📢 Thoughts on this report? Let us know!

[JerrettDavis]

Reviewed exact head 4896d5404dadcd0f7e4d4e06d37c4c3b7760158e, containing current upstream main bb8d18a56abb07ca7e811235c86ea6b626eb1f8b, and the author/Devin discussion. Outcome snapshots gain a defensive read-only label copy and the conversation/input/output-savings fields without losing ordinary serialization, copying, pickling or hashing. Identity-based extension registration avoids duplicate delivery for the same object. No correctness blocker found in this scope.

All 23 pipeline/outcome-stage tests pass. The serialization regressions fail against the preceding mapping-proxy implementation and pass on this head, addressing Devin's compatibility finding for both empty and populated labels. The outcome funnel passes the fields already resolved by the existing project/client paths; this source approval does not qualify the separate configurable attribution feature in #4699.

All upstream CI, Rust, Security, Merge Conflicts, Changelog Guard and latest governance runs succeeded; the older cancelled governance run is superseded. Ready for independent human merge review. Nothing merged.