Observability renderer: host loopback port overrides that survive a re-render - #290

Scope

• What this PR changes:
  • observability/backends/configure.py gains --port-overrides FILE.
  • A new test file, tests/test_observability_backends_configure.py.
  • Docs in observability/backends/README.md and, with a single-line "changed after v2026.09.25.2" marker, in adoption/platforms/linux-wsl2.md (Listeners and ports).
  • Hash re-registration in manifests/evidence.json.
• Why: all WSL 2 distributions share one network namespace, so the workstation moved five scraped services off their template ports: collector 18889→28889 and 18888→28888, Qdrant 16333→26333, vLLM 8231→18231, and the 14333 HTTP check →24333. The renderer had no input for that, so the live config was hand-adapted, and a re-render would reset those ports. Record the #284 host rollout on the WSL workstation and the early expiry of silence 87eabf8a #287 recorded this gap: Paper alert: scrape only registered adaptive-paper exporters, and alert only on a registered silent one #284's rollout had to be applied surgically.

Behaviour

• --port-overrides FILE takes a JSON object {"template port": host port}. It rewrites every 127.0.0.1:<template port> address in the rendered configs and the five unit texts in one regex pass, with no chaining, so a swap works.
• The map is kept as <config-root>/port-overrides.json, and later renders reuse it without the flag. Deleting that file returns to the template ports.
• Fails closed: the map is validated against the full render before any file is written. It exits 2 and writes nothing when:
  • an override matches no rendered address (a stale entry);
  • the port also appears outside a 127.0.0.1:<port> address, such as Grafana's http_port or Loki's listen ports, which the override does not rewrite;
  • the host port is already a rendered address that is not itself overridden;
  • the input is invalid: not an object, a non-digit key, a non-int or bool value, out of range, the same port, or two template ports mapped to one host port.
• Without overrides the output is unchanged: same files and same content. Only the write order moved after rendering.

Evidence

• Tests (local, WSL2): the new test_observability_backends_configure.py covers no overrides, overrides with persistence and a byte-identical re-render, the swap, and 9 refusal cases. Together with the other backend tests and the docs-consistency, contract and release-pin tests: 85 passed, 1 skipped. scripts/validate.py passed.
• Native check on the workstation, read-only: main plus this change was rendered with the workstation's map into a scratch root, and the paths were substituted. The result was compared with the live files, using only an allowlist of the template outputs plus the five units; the Grafana credential file was never read.
  • 14 of 15 files were byte-identical, including the rules file with 14333→24333 and all five units.
  • ecosystem-prometheus.yml was equal as parsed YAML; the live file was re-serialized with different formatting.
  • The scratch render was deleted afterwards.
• After merge: write the workstation's map to its <config-root>/port-overrides.json (host-local), so the next re-render keeps the ports.
• Review: an independent read-only reviewer (Sonnet) is reviewing this commit. Its findings will be addressed or answered here before merge.

🤖 Generated with Claude Code