fix(#5542): de-brittle SSE-contract RFC anchors — cite by symbol, not line number

[nesquena-hermes]

Summary

De-brittles the session-SSE-contract RFC's source anchors so a api/routes.py line-shift can never again break an unrelated PR's CI.

The problem (#5542): the RFC (docs/rfcs/session-sse-contract-v1.md, merged via #5513) pinned source anchors as api/routes.py:NNNN line numbers, and tests/test_issue4812_session_sse_contract_rfc.py asserted those exact lines contain the cited symbols. Any PR that inserts/removes lines above a pinned anchor shifts the numbers and red-fails the RFC test on a branch that's otherwise clean — confirmed collateral on #5534 (CORS, +16 lines) and again on #5553 (the #5532 P0 fix, +46 lines). Line numbers on this codebase drift constantly (release-driven), so this recurred on essentially every routes.py PR.

The fix (root cause): cite by symbol / route name, verified by existence, never by line number.

• The RFC now references the route string /api/sessions/events, the handler _handle_session_events_stream, and the run-journal symbols (_parse_run_journal_event_id, _parse_run_journal_after_seq, _runner_event_id, _replay_run_journal, _sse_with_id) by name — no *.py:NNNN anchors remain (0 left, verified).
• test_rfc_cites_current_global_endpoint_source and test_rfc_run_journal_anchors_land_on_real_source now assert each cited symbol (a) still exists in api/routes.py and (b) is named in the RFC prose — a real accuracy check that's immune to line-shifts.
• New regression guard test_rfc_uses_no_hardcoded_routes_line_numbers: fails if anyone ever re-introduces a *.py:<line> anchor into the RFC, so the brittleness can't come back.

This preserves the original tests' intent (the RFC's source references must be accurate, not rotted) while removing the line-number coupling that caused the churn.

Tests

tests/test_issue4812_session_sse_contract_rfc.py — 34 pass. The two former line-anchor tests are now symbol-based; the anti-regression guard confirms the RFC carries zero hardcoded source line numbers.

Note on ordering vs #5553

#5553 (the #5532 P0 fix) currently realigns these same RFC line numbers to survive its +46-line shift. Whichever merges first: if this lands first, #5553 should drop its now-obsolete RFC-anchor realignment (the anchors no longer exist); if #5553 lands first, this cleanly removes the line numbers it realigned. No code conflict either way — both only touch the RFC's citation style.

Closes #5542.

[greptile-apps]

Greptile Summary

This PR de-brittles the session-SSE-contract RFC by replacing hardcoded *.py:NNNN line-number anchors with symbol-based references, and updates the contract tests to assert symbol existence rather than line-number accuracy.

• RFC changes: All api/routes.py:NNNN and api/streaming.py:NNNN-NNNN citations replaced with prose-form "in api/routes.py" / "in api/streaming.py", with the rationale explicitly documented in the RFC itself.
• Test refactors: test_rfc_cites_current_global_endpoint_source and test_rfc_run_journal_anchors_land_on_real_source now probe source symbols via substring match on the full file text; a new test_rfc_uses_no_hardcoded_routes_line_numbers regression guard rejects any future *.py:<line> reintroduction.

Confidence Score: 5/5

Safe to merge — changes are documentation and test-only, with no runtime code modified.

Both changed files are a Markdown RFC and its contract test suite. The RFC substitutions are straightforward text edits replacing line-number citations with symbol names. The test refactor correctly validates symbol existence by substring match, and the new regression guard regex reliably catches any future reintroduction of line-number anchors. No application logic, API surface, or data path is touched.

No files require special attention.

Important Files Changed

Filename	Overview
docs/rfcs/session-sse-contract-v1.md	All line-number anchors removed and replaced with symbol/file-level references; the rationale is self-documenting in the updated prose.
tests/test_issue4812_session_sse_contract_rfc.py	Two tests refactored to symbol-based probes; new regression guard test added to prevent line-number reintroduction; logic is correct and the regex guard covers all cited file types.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[RFC cites symbol/route name] --> B{Symbol exists in api/routes.py?}
    B -- yes --> C{RFC prose names the symbol?}
    B -- no --> FAIL1[Test FAIL: symbol removed from source]
    C -- yes --> D{Any *.py:line anchors in RFC?}
    C -- no --> FAIL2[Test FAIL: RFC dropped symbol name]
    D -- none --> PASS[All 3 tests PASS]
    D -- found --> FAIL3[Regression guard FAIL: line number re-introduced]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[RFC cites symbol/route name] --> B{Symbol exists in api/routes.py?}
    B -- yes --> C{RFC prose names the symbol?}
    B -- no --> FAIL1[Test FAIL: symbol removed from source]
    C -- yes --> D{Any *.py:line anchors in RFC?}
    C -- no --> FAIL2[Test FAIL: RFC dropped symbol name]
    D -- none --> PASS[All 3 tests PASS]
    D -- found --> FAIL3[Regression guard FAIL: line number re-introduced]

Loading

_{Reviews (2): Last reviewed commit: "Merge remote-tracking branch 'origin/mas..." | Re-trigger Greptile}

[greptile-apps]

_sse_with_id probe is inconsistent with the other four checks

The four sibling entries all use "def <symbol>" as source_probe, so they verify a definition exists in api/routes.py. The _sse_with_id entry uses just "_sse_with_id", which also matches call sites, string literals, or comments — meaning the check still passes if the helper is removed but its name survives in a comment or import string. If this is intentional (e.g., _sse_with_id is defined elsewhere and only called from routes.py), a brief inline comment explaining that would prevent future maintainers from "fixing" it to "def _sse_with_id" and introducing a spurious failure.