init: seed Ratatoskr from corviduo-project-template + ship v0 scaffold
Worldtree Conversation API debug TUI. Multi-pane observability dashboard: chat transcript + persona/Vili affect log + tool events + admin events + Bifrost state + tool inventory + (opt-in) raw server log. Design locked at docs/design-brief.md (originated as brokkr-smithy/docs/ratatoskr-design-brief.md). Operator-locked decisions: - Textual application-shell framework (multi-pane dashboard, not REPL). - Separate repo + separate dev team (no Worldtree-source imports). - httpx-sse for SSE consumption (reference Python SSE-resume impl). - Triple version-skew mitigation: spec-pin in pyproject.toml + recorded SSE snapshot tests + conformance smoke. Initial pin: Worldtree v0.19.0 at 55101e909abcd2219833266b6f905c5bc956e0f0. - Persona pane: label-don't-refuse PII posture. - Server-log pane: opt-in via --server-log <path>. - Two-stage Ctrl-C (cancel then exit). - Markdown rendering default-on; --raw opt-out. In the box: - docs/design-brief.md — the locked design with full rationale. - docs/SPEC-PIN.md — Worldtree spec pin + bump procedure. - docs/conversation-api-spec.md + docs/conversation_api.contract.md — vendored Worldtree spec snapshots at the pinned SHA. - pyproject.toml — Python 3.12, hatchling, uv-managed, deps locked. - src/ratatoskr/ — stub package (cli.py raises NotImplementedError). - tests/test_no_worldtree_imports.py — boundary smoke test PASSING. - tests/snapshots/README.md — recording convention for SSE snapshot tests. Not in the box yet: - Gitea remote (operator/infra-ops to register at vh/ratatoskr). - Implementation — the dev team owns this; design brief is the spec. Origin: althing thread 01KS3R34XD3N6HMK91VXESHGW7 (worldtree-dev → brokkr-smithy-dev, 2026-05-20). Volva consulted via thread 01KS3VF6W33N3V5FNMGQ91YNVD.
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# SSE snapshot tests
|
||||
|
||||
Recorded SSE transcripts from a live Worldtree at the pinned spec SHA.
|
||||
Replayed in CI to catch event-shape drift.
|
||||
|
||||
## Recording
|
||||
|
||||
```bash
|
||||
# Boot Worldtree at the pinned SHA
|
||||
( cd ~/development/Worldtree && python -m core.conversation_api ) &
|
||||
|
||||
# Record (harness TBD by dev team — likely respx + httpx-sse fixtures)
|
||||
uv run pytest --record-snapshots tests/snapshots/
|
||||
```
|
||||
|
||||
## Replay
|
||||
|
||||
The default `uv run pytest` reads the recorded files and replays them
|
||||
against the Ratatoskr SSE consumer. Re-record on every spec-pin bump
|
||||
(see `docs/SPEC-PIN.md`).
|
||||
|
||||
## What to capture
|
||||
|
||||
At minimum:
|
||||
- One-turn happy path (`text` + `done`).
|
||||
- Tool-using turn (`text` + `tool_start` + `tool_result` + `text` + `done`).
|
||||
- Thinking-enabled turn (`thinking` + `text` + `done`).
|
||||
- Cancelled turn (`text` + `cancelled` with `reason: "user_cancel"`).
|
||||
- Errored turn (`text` + `error`).
|
||||
- `worker_phase` event sequence across `BuildingPrompt` → `CallingLLM` → `ProcessingTools` → `Streaming` → `Finishing`.
|
||||
|
||||
Capture also the `id:` and `event:` lines, not just `data:` — those
|
||||
are load-bearing for SSE resume and easy to forget.
|
||||
@@ -0,0 +1,45 @@
|
||||
"""Boundary smoke test: Ratatoskr must not import from a Worldtree checkout.
|
||||
|
||||
The boundary rule (docs/design-brief.md §2): Ratatoskr depends on the
|
||||
*published Conversation API spec* — vendored at `docs/conversation-api-spec.md`
|
||||
at a pinned SHA — and NOT on any Worldtree source code. This test fails
|
||||
loud if any file under `src/ratatoskr/` imports from `core.*`, `worldtree.*`,
|
||||
or any other identifiable Worldtree module path.
|
||||
|
||||
If you find yourself wanting to import from Worldtree: stop. The right
|
||||
move is one of:
|
||||
- Re-derive the type from the vendored spec.
|
||||
- File a question to worldtree-dev via althing (the spec is unclear).
|
||||
- Bump the spec pin (`docs/SPEC-PIN.md`) and re-vendor if the spec moved.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import pathlib
|
||||
import re
|
||||
|
||||
_FORBIDDEN_IMPORT_PATTERNS = [
|
||||
re.compile(r"^\s*import\s+core(\.|\s|$)", re.MULTILINE),
|
||||
re.compile(r"^\s*from\s+core(\.|\s+import)", re.MULTILINE),
|
||||
re.compile(r"^\s*import\s+worldtree(\.|\s|$)", re.MULTILINE),
|
||||
re.compile(r"^\s*from\s+worldtree(\.|\s+import)", re.MULTILINE),
|
||||
]
|
||||
|
||||
_SRC_ROOT = pathlib.Path(__file__).parent.parent / "src" / "ratatoskr"
|
||||
|
||||
|
||||
def test_no_worldtree_imports() -> None:
|
||||
violations: list[tuple[pathlib.Path, str]] = []
|
||||
for path in _SRC_ROOT.rglob("*.py"):
|
||||
text = path.read_text(encoding="utf-8")
|
||||
for pattern in _FORBIDDEN_IMPORT_PATTERNS:
|
||||
for match in pattern.finditer(text):
|
||||
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)
|
||||
raise AssertionError(
|
||||
"Ratatoskr must not import from Worldtree source. Violations:\n"
|
||||
f"{report}\n\n"
|
||||
"See docs/design-brief.md §2 (boundary rule) and "
|
||||
"docs/SPEC-PIN.md (spec-pin discipline)."
|
||||
)
|
||||
Reference in New Issue
Block a user