feat(sse_client): implement issue #1 contract via TDD

Implements docs/contracts/issues/1.contract.md. Four entry points
(stream_turn, reconnect_turn, cancel_turn, _parse_sse_id) + nine
typed Event variants + ten domain exceptions. 37 tests covering
every TESTS: entry verbatim, plus the boundary smoke test still
passes.

Tracer-bullet ordering per the contract's per-FN tracer tags:
_parse_sse_id (foundation; happy_simple) → stream_turn
(happy_one_text_done) → reconnect_turn (happy_resume_from_seq_3) →
cancel_turn (happy_cancel). Each FN's tracer went RED then GREEN
before its other tests landed.

Shared SSE-iteration logic (INV-002 sse_id presence + INV-003
turn_id stability + terminal-break) lives in private _iter_events
helper. expected_turn_id=None gives stream_turn's "establish from
first event" semantics; expected_turn_id=N gives reconnect_turn's
"first event is already a flip-candidate" semantics — the
two-entry-point distinction Volva surfaced during the paraphrase
round.

A few implementation choices worth recording:

- _parse_sse_id uses a `^-?\\d+$` regex pre-check to reject any
  whitespace before int() is called. Python's `int(" 3 ")` silently
  strips, which would have made the trailing_whitespace adversarial
  test pass for the wrong reason.

- The connection_drop test uses a custom httpx.AsyncByteStream
  subclass (_DropAfter) that yields chunks then raises
  RemoteProtocolError mid-stream. respx alone can't simulate
  mid-stream HTTP errors.

- ToolResult.result and ToolStart.arguments are typed as Any
  because the server's tool wire shape varies per tool; the spec
  doesn't pin a generic schema.

- Boundary smoke test (no core.* / worldtree.* imports under
  src/ratatoskr/) still GREEN — INV-005 holds.

Also: one E501 line-length fix in test_no_worldtree_imports.py
that ruff flagged once the new tests pulled it into scope.
This commit is contained in:
vh
2026-05-20 21:25:20 -07:00
parent 1526f0bc8e
commit 02f2a04b37
4 changed files with 1049 additions and 7 deletions
+3 -1
View File
@@ -36,7 +36,9 @@ def test_no_worldtree_imports() -> None:
line = text[: match.start()].count("\n") + 1
violations.append((path, f"line {line}: {match.group(0).strip()}"))
if violations:
report = "\n".join(f" {p.relative_to(_SRC_ROOT.parent.parent)}: {v}" for p, v in violations)
report = "\n".join(
f" {p.relative_to(_SRC_ROOT.parent.parent)}: {v}" for p, v in violations
)
raise AssertionError(
"Ratatoskr must not import from Worldtree source. Violations:\n"
f"{report}\n\n"