From e2ba09adb42ea9c81c81e3df28028265eb193a0d Mon Sep 17 00:00:00 2001 From: JD Davis Date: Sun, 12 Jul 2026 16:18:23 +0000 Subject: [PATCH] Extract memory injection mode policy (#1986) ## Description Extracts memory-injection mode resolution from `helpers.py` into `headroom.proxy.memory_injection_mode_policy`. The proxy still reads `HEADROOM_MEMORY_INJECTION_MODE` at request time, while the allowed values/default/error contract is now pure and directly tested. Closes # ## 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 - [x] Code refactoring (no functional changes) ## Changes Made - Added `memory_injection_mode_policy.py` with the allowed mode type, env name/default, and resolver. - Kept `helpers.get_memory_injection_mode` as the request-time env reader and compatibility entry point. - Added direct policy tests for defaults, accepted values, normalization, and invalid mode rejection. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text python -m pytest tests\test_memory_injection_mode_policy.py tests\test_proxy_system_prompt_immutable.py 10 passed in 14.60s python -m ruff check . All checks passed! python -m ruff format --check . 1069 files already formatted python -m mypy headroom --ignore-missing-imports Success: no issues found in 410 source files gitleaks protect --staged --no-banner --redact no leaks found ``` ## Real Behavior Proof - Environment: Windows, Python 3.13.13, branch `jd/architecture-slice-33`. - Exact command / steps: ran new memory injection mode policy tests, existing system-prompt immutability tests, ruff, ruff format check, mypy, and staged gitleaks scan. - Observed result: memory injection mode behavior remains covered and local lint/type/security checks pass. - Not tested: live proxy request; existing helper entry point remains intact. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A ## Additional Notes Documentation and changelog updates are N/A for this internal architecture-only refactor. The push reported existing default-branch Dependabot alerts; no staged secret leaks were found for this PR. --------- Co-authored-by: Tejas Chopra --- headroom/proxy/helpers.py | 16 +++++-------- .../proxy/memory_injection_mode_policy.py | 22 +++++++++++++++++ tests/test_memory_injection_mode_policy.py | 24 +++++++++++++++++++ 3 files changed, 52 insertions(+), 10 deletions(-) create mode 100644 headroom/proxy/memory_injection_mode_policy.py create mode 100644 tests/test_memory_injection_mode_policy.py diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py index ce3c93a8b..94d0768f3 100644 --- a/headroom/proxy/helpers.py +++ b/headroom/proxy/helpers.py @@ -26,6 +26,7 @@ from headroom import paths as _paths from headroom._subprocess import run from headroom.proxy import ( diagnostic_decode_policy, + memory_injection_mode_policy, query_log_policy, request_limit_policy, sse_byte_buffer_policy, @@ -232,9 +233,9 @@ def capture_codex_wire_debug( # Configurable via HEADROOM_MEMORY_INJECTION_MODE env var. There is no # "system_prompt" option — that path is permanently retired by I2 (cache hot # zone never modified). See REALIGNMENT/02-architecture.md §2.2. -_MEMORY_INJECTION_MODE_ENV = "HEADROOM_MEMORY_INJECTION_MODE" -_MEMORY_INJECTION_MODE_DEFAULT: Literal["live_zone_tail", "disabled"] = "live_zone_tail" -MemoryInjectionMode = Literal["live_zone_tail", "disabled"] +_MEMORY_INJECTION_MODE_ENV = memory_injection_mode_policy.MEMORY_INJECTION_MODE_ENV +_MEMORY_INJECTION_MODE_DEFAULT = memory_injection_mode_policy.MEMORY_INJECTION_MODE_DEFAULT +MemoryInjectionMode = memory_injection_mode_policy.MemoryInjectionMode def get_memory_injection_mode() -> MemoryInjectionMode: @@ -243,13 +244,8 @@ def get_memory_injection_mode() -> MemoryInjectionMode: Read at request time so the env var can be flipped without restart for smoke tests. Unknown values are rejected loudly (no silent fallback). """ - raw = os.environ.get(_MEMORY_INJECTION_MODE_ENV, "").strip().lower() - if not raw: - return _MEMORY_INJECTION_MODE_DEFAULT - if raw in ("live_zone_tail", "disabled"): - return cast(MemoryInjectionMode, raw) - raise ValueError( - f"Invalid {_MEMORY_INJECTION_MODE_ENV}={raw!r}; expected 'live_zone_tail' or 'disabled'" + return memory_injection_mode_policy.resolve_memory_injection_mode( + os.environ.get(_MEMORY_INJECTION_MODE_ENV) ) diff --git a/headroom/proxy/memory_injection_mode_policy.py b/headroom/proxy/memory_injection_mode_policy.py new file mode 100644 index 000000000..016312198 --- /dev/null +++ b/headroom/proxy/memory_injection_mode_policy.py @@ -0,0 +1,22 @@ +"""Memory-injection mode resolution policy.""" + +from __future__ import annotations + +from typing import Literal, cast + +MEMORY_INJECTION_MODE_ENV = "HEADROOM_MEMORY_INJECTION_MODE" +MEMORY_INJECTION_MODE_DEFAULT: Literal["live_zone_tail", "disabled"] = "live_zone_tail" +MemoryInjectionMode = Literal["live_zone_tail", "disabled"] + + +def resolve_memory_injection_mode(raw: str | None) -> MemoryInjectionMode: + """Resolve the active memory-injection routing mode from an optional value.""" + normalized = (raw or "").strip().lower() + if not normalized: + return MEMORY_INJECTION_MODE_DEFAULT + if normalized in ("live_zone_tail", "disabled"): + return cast(MemoryInjectionMode, normalized) + raise ValueError( + f"Invalid {MEMORY_INJECTION_MODE_ENV}={normalized!r}; " + "expected 'live_zone_tail' or 'disabled'" + ) diff --git a/tests/test_memory_injection_mode_policy.py b/tests/test_memory_injection_mode_policy.py new file mode 100644 index 000000000..a0d5661b6 --- /dev/null +++ b/tests/test_memory_injection_mode_policy.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +import pytest + +from headroom.proxy.memory_injection_mode_policy import ( + MEMORY_INJECTION_MODE_DEFAULT, + resolve_memory_injection_mode, +) + + +def test_resolve_memory_injection_mode_defaults_for_missing_value() -> None: + assert resolve_memory_injection_mode(None) == MEMORY_INJECTION_MODE_DEFAULT + assert resolve_memory_injection_mode("") == MEMORY_INJECTION_MODE_DEFAULT + assert resolve_memory_injection_mode(" ") == MEMORY_INJECTION_MODE_DEFAULT + + +def test_resolve_memory_injection_mode_accepts_known_values_case_insensitively() -> None: + assert resolve_memory_injection_mode("live_zone_tail") == "live_zone_tail" + assert resolve_memory_injection_mode(" DISABLED ") == "disabled" + + +def test_resolve_memory_injection_mode_rejects_unknown_values() -> None: + with pytest.raises(ValueError, match="HEADROOM_MEMORY_INJECTION_MODE"): + resolve_memory_injection_mode("system_prompt")