uro-server 0.2.0__tar.gz

uro_server-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.python-version.local
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Deployment config holds credential references — commit uro.example.toml instead (docs/14)
+uro.toml
+.env
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Stray local data dumps — never commit (a PII file named `data` was found here once)
+/data

uro_server-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cupskeee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uro_server-0.2.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: uro-server
+Version: 0.2.0
+Summary: Uro Engine headless server — thin FastAPI shell over uro-core (REST + WebSocket)
+Project-URL: Homepage, https://github.com/cupskeee/uro
+Project-URL: Repository, https://github.com/cupskeee/uro
+Project-URL: Issues, https://github.com/cupskeee/uro/issues
+Author: cupskeee
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uro-core[llm,postgres]==0.2.0
+Requires-Dist: uvicorn[standard]>=0.51.0
+Description-Content-Type: text/markdown
+
+# uro-server
+
+**The Uro Engine headless server — a thin FastAPI shell over [`uro-core`](https://pypi.org/project/uro-core/).**
+
+`uro-server` exposes the engine as a REST + WebSocket API. It is transport and session wiring
+only — no engine logic. It runs the WebSocket play channel (broadcast fan-out, token auth) and
+the Chronicler outcome endpoint over a testable dependency seam.
+
+## Install
+
+```sh
+pip install uro-server
+```
+
+## Runtime
+
+The server drives the engine, which requires **PostgreSQL 17 + pgvector** and (for live play) an
+LLM provider — both pulled via `uro-core`'s extras. The reference way to run a server is
+`uro serve` from [`uro-cli`](https://pypi.org/project/uro-cli/), which builds the dependencies.
+
+## Links
+
+- Source and docs (see `docs/08-api-and-sessions.md`): https://github.com/cupskeee/uro
+- License: MIT

uro_server-0.2.0/README.md

@@ -0,0 +1,24 @@
+# uro-server
+
+**The Uro Engine headless server — a thin FastAPI shell over [`uro-core`](https://pypi.org/project/uro-core/).**
+
+`uro-server` exposes the engine as a REST + WebSocket API. It is transport and session wiring
+only — no engine logic. It runs the WebSocket play channel (broadcast fan-out, token auth) and
+the Chronicler outcome endpoint over a testable dependency seam.
+
+## Install
+
+```sh
+pip install uro-server
+```
+
+## Runtime
+
+The server drives the engine, which requires **PostgreSQL 17 + pgvector** and (for live play) an
+LLM provider — both pulled via `uro-core`'s extras. The reference way to run a server is
+`uro serve` from [`uro-cli`](https://pypi.org/project/uro-cli/), which builds the dependencies.
+
+## Links
+
+- Source and docs (see `docs/08-api-and-sessions.md`): https://github.com/cupskeee/uro
+- License: MIT

uro_server-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "uro-server"
+version = "0.2.0"
+description = "Uro Engine headless server — thin FastAPI shell over uro-core (REST + WebSocket)"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "cupskeee" }]
+requires-python = ">=3.12"
+# The transport shell imports no adapter itself, but a deployed play server needs the store
+# and a provider at runtime, so it pulls both uro-core extras (D-43). uro-core is pinned to the
+# exact lockstep version (single-versioned workspace) so a partial upgrade can't mismatch them;
+# `just release` bumps all three together and `{workspace = true}` fails `uv sync` on a drift.
+dependencies = [
+    "uro-core[postgres,llm]==0.2.0",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.51.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cupskeee/uro"
+Repository = "https://github.com/cupskeee/uro"
+Issues = "https://github.com/cupskeee/uro/issues"
+
+[tool.uv.sources]
+uro-core = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["uro_server"]

uro_server-0.2.0/tests/test_server.py

@@ -0,0 +1,497 @@
+"""Phase 5 inc 5.1: the transport shell — token auth + broadcast-shaped WS play channel (docs/08).
+
+The acceptance's leg (a): two clients (two tokens) attached to one campaign both receive the
+SAME streamed beats. Tested with fake deps so the transport is exercised without a live DB/model
+(the engine path is tested in uro-core).
+"""
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+import pytest
+from starlette.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
+from uro_server.app import ServerDeps, create_app
+from uro_server.sessions import SessionHub
+
+_TOKENS = {"tok-a": "player-1", "tok-b": "player-2"}
+
+
+def _fake_deps() -> ServerDeps:
+    async def campaign_exists(campaign_id: str) -> bool:
+        return campaign_id == "camp-1"
+
+    async def run_beat(campaign_id: str, participant: str, text: str) -> AsyncIterator[str]:
+        for word in ("A ", "grim ", "tide ", "rises."):
+            yield word
+
+    return ServerDeps(
+        resolve_participant=lambda token: _TOKENS.get(token),
+        campaign_exists=campaign_exists,
+        run_beat=run_beat,
+    )
+
+
+def _recv_until(ws: Any, target: str, cap: int = 25) -> list[dict[str, Any]]:
+    msgs: list[dict[str, Any]] = []
+    for _ in range(cap):
+        m = ws.receive_json()
+        msgs.append(m)
+        if m.get("type") == target:
+            return msgs
+    raise AssertionError(f"never received {target!r}: {[m.get('type') for m in msgs]}")
+
+
+# --- broadcast fan-out (the multiplayer seam) ---
+
+
+async def test_session_hub_fans_out_to_all_subscribers() -> None:
+    hub = SessionHub()
+    a, b = hub.subscribe("c"), hub.subscribe("c")
+    other = hub.subscribe("d")
+    await hub.publish("c", {"type": "beat_committed"})
+    assert a.get_nowait()["type"] == "beat_committed"
+    assert b.get_nowait()["type"] == "beat_committed"  # both connections got the SAME message
+    assert other.empty()  # a different campaign is isolated
+    assert hub.connections("c") == 2
+    hub.unsubscribe("c", a)
+    hub.unsubscribe("c", b)
+    assert hub.connections("c") == 0
+
+
+# --- the acceptance leg: two clients, one campaign, same beats ---
+
+
+def test_two_clients_receive_the_same_beat() -> None:
+    client = TestClient(create_app(_fake_deps()))
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,
+    ):
+        a.send_json({"type": "intent", "text": "I scan the drowned pier"})
+        msgs_a = _recv_until(a, "beat_committed")
+        msgs_b = _recv_until(b, "beat_committed")
+
+    def committed(msgs: list[dict[str, Any]]) -> dict[str, Any]:
+        return next(m for m in msgs if m["type"] == "beat_committed")
+
+    # BOTH clients saw the same committed beat — narration and the acting participant
+    assert committed(msgs_a)["narration"] == "A grim tide rises."
+    assert committed(msgs_b)["narration"] == "A grim tide rises."
+    assert committed(msgs_b)["participant_id"] == "player-1"  # b sees a's beat (broadcast)
+    # and both streamed the narration chunk-by-chunk
+    assert [m for m in msgs_b if m["type"] == "narration_chunk"]
+
+
+def test_healthz() -> None:
+    assert TestClient(create_app(_fake_deps())).get("/healthz").json() == {"status": "ok"}
+
+
+def test_bad_token_is_rejected_before_accept() -> None:
+    client = TestClient(create_app(_fake_deps()))
+    with (
+        pytest.raises(WebSocketDisconnect) as excinfo,
+        client.websocket_connect("/campaigns/camp-1/play?token=nope"),
+    ):
+        pass
+    assert excinfo.value.code == 4401  # unauthorized, closed before accept
+
+
+def test_unknown_campaign_is_rejected() -> None:
+    client = TestClient(create_app(_fake_deps()))
+    with (
+        pytest.raises(WebSocketDisconnect) as excinfo,
+        client.websocket_connect("/campaigns/nope/play?token=tok-a"),
+    ):
+        pass
+    assert excinfo.value.code == 4404  # no such campaign
+
+
+# --- Chronicler mode: the outcome-bundle endpoint (D-25) ---
+
+
+def test_outcome_endpoint_distills_the_bundle() -> None:
+    recorded: dict[str, Any] = {}
+
+    async def report_outcome(campaign_id: str, bundle: dict[str, Any]) -> dict[str, Any]:
+        recorded["campaign"], recorded["bundle"] = campaign_id, bundle
+        return {"committed_events": 4, "commit_id": "c:abc"}
+
+    deps = _fake_deps()
+    deps.report_outcome = report_outcome
+    resp = TestClient(create_app(deps)).post(
+        "/campaigns/camp-1/encounters/e:battle-7/outcome?token=tok-a",
+        json={
+            "feats": [{"actor": "a:hero", "description": "split the champion"}],
+            "witnesses": ["a:raider1"],
+        },
+    )
+    assert resp.status_code == 200
+    assert resp.json()["committed_events"] == 4
+    assert recorded["bundle"]["encounter_id"] == "e:battle-7"  # path param injected into the bundle
+
+
+def test_outcome_endpoint_rejects_a_token_scoped_to_another_campaign() -> None:
+    # D-41: the outcome endpoint mutates the timeline, so a campaign-scoped minted token (D-39) must
+    # be enforced HERE too, not just on the WS play channel. A static token (campaign None) is
+    # server-wide and passes.
+    hit: dict[str, bool] = {}
+
+    async def report_outcome(campaign_id: str, bundle: dict[str, Any]) -> dict[str, Any]:
+        hit["reached"] = True
+        return {"committed_events": 0, "commit_id": "c", "receipt": []}
+
+    deps = _fake_deps()
+    deps.report_outcome = report_outcome
+    deps.token_campaign = lambda t: "camp-1" if t == "tok-a" else None  # tok-a minted for camp-1
+    client = TestClient(create_app(deps))
+    blocked = client.post("/campaigns/camp-2/encounters/e/outcome?token=tok-a", json={})
+    assert blocked.status_code == 403 and "reached" not in hit  # never reached the distiller
+    own = client.post("/campaigns/camp-1/encounters/e/outcome?token=tok-a", json={})
+    assert own.status_code == 200  # …but tok-a works on its OWN campaign
+    static = client.post("/campaigns/camp-2/encounters/e/outcome?token=tok-b", json={})
+    assert static.status_code == 200  # …and tok-b (unscoped/static) is server-wide
+
+
+def test_outcome_endpoint_rejects_a_bad_token() -> None:
+    resp = TestClient(create_app(_fake_deps())).post(
+        "/campaigns/camp-1/encounters/e/outcome?token=nope", json={}
+    )
+    assert resp.status_code == 401  # an external resolver mutates state → must be authed
+
+
+def test_outcome_endpoint_501_when_chronicler_disabled() -> None:
+    resp = TestClient(create_app(_fake_deps())).post(  # authed, but report_outcome=None
+        "/campaigns/camp-1/encounters/e/outcome?token=tok-a", json={}
+    )
+    assert resp.status_code == 501
+
+
+# --- Phase 6 (D-30) cross-phase seam (P6 x P5): per-campaign ruleset pin vs one-Engine server ---
+
+
+def test_beat_failure_is_broadcast_not_a_ws_crash() -> None:
+    # A beat that raises (e.g. a ruleset mismatch, a provider error) must degrade to a graceful
+    # 'beat_failed' broadcast, keeping the session alive — not crash the WS connection.
+    async def boom(campaign_id: str, participant: str, text: str):  # type: ignore[no-untyped-def]
+        raise RuntimeError("kaboom")
+        yield ""  # pragma: no cover — makes this an async generator
+
+    async def campaign_exists(campaign_id: str) -> bool:
+        return campaign_id == "camp-1"
+
+    deps = ServerDeps(
+        resolve_participant=lambda t: _TOKENS.get(t),
+        campaign_exists=campaign_exists,
+        run_beat=boom,
+    )
+    with TestClient(create_app(deps)).websocket_connect("/campaigns/camp-1/play?token=tok-a") as ws:
+        _recv_until(ws, "participant_joined")
+        ws.send_json({"type": "intent", "text": "I swing"})
+        msgs = _recv_until(ws, "beat_failed")
+        failed = msgs[-1]
+        assert failed["error"] == "kaboom" and failed["intent"] == "I swing"
+        # the connection is still alive — another intent still gets a fresh beat_failed
+        ws.send_json({"type": "intent", "text": "again"})
+        assert _recv_until(ws, "beat_failed")[-1]["intent"] == "again"
+
+
+async def test_engine_deps_rejects_a_ruleset_mismatch_with_a_clear_error() -> None:
+    # engine_deps.run_beat must reject a campaign pinned to a DIFFERENT ruleset than the server's
+    # single Engine holds — with a diagnostic naming both, not a raw ValidationError from deep in
+    # sheet validation (P6 per-campaign pin x P5 one-ruleset server).
+    from uro_core.pipeline.engine import Engine
+    from uro_core.providers.adapters.stub import StubProvider
+    from uro_core.providers.router import ProviderRouter
+    from uro_core.rulesets.uro_basic import UroBasic
+    from uro_core.timeline.models import Campaign
+    from uro_server.app import engine_deps
+
+    class _FakeStore:
+        async def get_campaign(self, campaign_id: str) -> Campaign:
+            return Campaign(
+                campaign_id=campaign_id,
+                world_id="w",
+                branch_id="b",
+                ruleset_id="uro-pbta",  # pinned to the alien ruleset
+                ruleset_version=">=0",
+            )
+
+    store = _FakeStore()
+    engine = Engine(store, ProviderRouter(bindings={}, default=StubProvider()), ruleset=UroBasic())
+    deps = engine_deps(store, engine, _TOKENS)  # type: ignore[arg-type]
+
+    with pytest.raises(ValueError, match="uro-pbta"):
+        async for _ in deps.run_beat("camp-1", "player-1", "I seize the vein"):
+            pass
+
+
+# --- Phase 7 (OQ-7 → D-31): PartyArbiter round-robin over the WS play channel ---
+
+
+def test_party_arbiter_round_robin_over_the_ws_channel() -> None:
+    # Two connected participants share one campaign; free-roam turns rotate round-robin. The
+    # holder's intent runs; an out-of-turn intent is told NOT_YOUR_TURN (not rejected); the token
+    # rotates on beat_committed. Read all broadcasts off ONE socket (fan-out reaches both).
+    from uro_core.session import PartyArbiter
+
+    app = create_app(_fake_deps(), arbiter=PartyArbiter())
+    client = TestClient(app)
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,  # player-1 joins first
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,  # player-2 second
+    ):
+        _recv_until(a, "participant_joined")  # a sees its own join
+        _recv_until(a, "participant_joined")  # ...and player-2's join → roster [player-1, player-2]
+
+        # player-2 acts out of turn (player-1 holds) → NOT_YOUR_TURN, no beat
+        b.send_json({"type": "intent", "text": "me first"})
+        nyt = _recv_until(a, "not_your_turn")[-1]
+        assert nyt["participant_id"] == "player-2"
+
+        # player-1 (the holder) acts → a beat commits, and the token rotates to player-2
+        a.send_json({"type": "intent", "text": "my turn"})
+        assert _recv_until(a, "beat_committed")[-1]["participant_id"] == "player-1"
+
+        # now player-2 holds → their intent runs
+        b.send_json({"type": "intent", "text": "now me"})
+        assert _recv_until(a, "beat_committed")[-1]["participant_id"] == "player-2"
+
+
+# --- D-38 (#9): arbiter shapes beyond round-robin — non-canon lane + proposal-window + vote ---
+
+
+def test_table_talk_fans_out_without_ever_committing_a_beat() -> None:
+    # INC-1: the non-canon coordination lane broadcasts to the whole session and NEVER calls
+    # run_beat — the SOLE path to append_beat. That run_beat is untouched IS the structural
+    # non-canon guarantee (no branch-head move, no event, no commit can happen).
+    calls: list[str] = []
+
+    async def run_beat(campaign_id: str, participant: str, text: str):  # type: ignore[no-untyped-def]
+        calls.append(text)
+        yield "narr"
+
+    async def campaign_exists(campaign_id: str) -> bool:
+        return campaign_id == "camp-1"
+
+    deps = ServerDeps(
+        resolve_participant=lambda t: _TOKENS.get(t),
+        campaign_exists=campaign_exists,
+        run_beat=run_beat,
+    )
+    client = TestClient(create_app(deps))
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,
+    ):
+        _recv_until(a, "participant_joined")
+        a.send_json({"type": "table_talk", "text": "we should split up"})
+        tt = _recv_until(b, "table_talk")[-1]  # the OTHER client received it (broadcast fan-out)
+        assert tt["participant_id"] == "player-1" and tt["text"] == "we should split up"
+    assert calls == []  # run_beat NEVER ran → no beat, no append_beat, no commit (structural)
+
+
+def test_proposal_window_surfaces_a_non_holder_intent_as_a_proposal() -> None:
+    # INC-2 (G-10): a non-holder's intent becomes a first-class PROPOSAL (not a silent
+    # not_your_turn, not a rejection, and NOT a beat); the holder enacts it as an ordinary beat.
+    from uro_core.session import ProposalWindowArbiter
+
+    client = TestClient(create_app(_fake_deps(), arbiter=ProposalWindowArbiter()))
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,  # player-1 holds
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,  # player-2
+    ):
+        _recv_until(a, "participant_joined")
+        _recv_until(a, "participant_joined")  # roster [player-1, player-2]
+        b.send_json({"type": "intent", "text": "we should bribe the guard"})
+        msgs = _recv_until(a, "proposal_opened")
+        pr = msgs[-1]
+        assert pr["participant_id"] == "player-2" and pr["text"] == "we should bribe the guard"
+        assert not any(m["type"] == "beat_started" for m in msgs)  # a proposal is NOT a beat
+        # the holder enacts → an ordinary beat commits, the token rotates
+        a.send_json({"type": "intent", "text": "I bribe the guard"})
+        assert _recv_until(a, "beat_committed")[-1]["participant_id"] == "player-1"
+        # now player-2 holds → their intent runs as a real beat (proposal-window keeps round-robin)
+        b.send_json({"type": "intent", "text": "now me"})
+        assert _recv_until(a, "beat_committed")[-1]["participant_id"] == "player-2"
+
+
+def test_vote_tallies_on_the_lane_and_decides_without_burning_a_beat() -> None:
+    # INC-3 (G-11): votes ride the non-canon lane; the tally is server-side (session-only); a
+    # decided vote is announced but NOT auto-enacted (take_pending deferred) — no beat is burned.
+    from uro_core.session import VoteArbiter
+
+    client = TestClient(create_app(_fake_deps(), arbiter=VoteArbiter()))
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,
+    ):
+        _recv_until(a, "participant_joined")
+        _recv_until(a, "participant_joined")  # roster [player-1, player-2]
+        a.send_json({"type": "vote", "choice": "go loud"})
+        assert _recv_until(a, "vote_tally")[-1]["tally"] == {"go loud": 1}  # 1/2, no decision yet
+        b.send_json({"type": "vote", "choice": "go loud"})
+        msgs = _recv_until(a, "vote_decided")
+        assert msgs[-1]["choice"] == "go loud"  # 2-0 → decided
+        assert not any(m["type"] == "beat_started" for m in msgs)  # no vote burned a beat
+
+
+def test_vote_on_a_non_vote_arbiter_gets_feedback_not_silence() -> None:
+    # Review fix: the CLI advertises /vote unconditionally, but a non-VoteCoordinator arbiter (the
+    # default party) can't tally — the server must say so, not silently swallow the frame.
+    from uro_core.session import PartyArbiter
+
+    client = TestClient(create_app(_fake_deps(), arbiter=PartyArbiter()))
+    with client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a:
+        _recv_until(a, "participant_joined")
+        a.send_json({"type": "vote", "choice": "go loud"})
+        assert _recv_until(a, "vote_unsupported")[-1]["participant_id"] == "player-1"
+
+
+def test_vote_resolves_when_the_last_holdout_disconnects() -> None:
+    # Review liveness fix: two of three vote the same, the third leaves without voting → the round
+    # is now complete; the server recomputes on disconnect (resolve_pending) and broadcasts the
+    # decision, instead of the round silently never resolving.
+    from uro_core.session import VoteArbiter
+
+    _THREE = {"tok-a": "player-1", "tok-b": "player-2", "tok-c": "player-3"}
+
+    async def campaign_exists(campaign_id: str) -> bool:
+        return campaign_id == "camp-1"
+
+    async def run_beat(campaign_id: str, participant: str, text: str):  # type: ignore[no-untyped-def]
+        yield "narr"
+
+    deps = ServerDeps(
+        resolve_participant=lambda t: _THREE.get(t),
+        campaign_exists=campaign_exists,
+        run_beat=run_beat,
+    )
+    client = TestClient(create_app(deps, arbiter=VoteArbiter()))
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-c") as c,
+    ):
+        for _ in range(3):
+            _recv_until(a, "participant_joined")  # roster [player-1, player-2, player-3]
+        a.send_json({"type": "vote", "choice": "flee"})
+        _recv_until(a, "vote_tally")
+        b.send_json({"type": "vote", "choice": "flee"})
+        _recv_until(a, "vote_tally")  # 2/3 — undecided, waiting on player-3
+        c.close()  # the last holdout leaves without voting → the round is now 2/2 complete
+        assert _recv_until(a, "vote_decided")[-1]["choice"] == "flee"
+
+
+# --- D-39 (#10): the runtime token registry (durable, hashed, revocable, off the branch axis) ---
+
+
+class _FakeTokenStore:
+    """In-memory SessionTokenStore for the registry unit test — mirrors the durable 018 table."""
+
+    def __init__(self) -> None:
+        self.rows: dict[str, tuple[str, str, bool]] = {}  # hash → (participant, campaign, revoked)
+
+    async def mint_token(self, token_hash: str, participant_id: str, campaign_id: str) -> None:
+        self.rows[token_hash] = (participant_id, campaign_id, False)
+
+    async def revoke_token(self, token_hash: str) -> bool:
+        row = self.rows.get(token_hash)
+        if row is not None and not row[2]:
+            self.rows[token_hash] = (row[0], row[1], True)
+            return True
+        return False
+
+    async def list_session_tokens(self) -> list[tuple[str, str, str]]:
+        return [(h, p, c) for h, (p, c, revoked) in self.rows.items() if not revoked]
+
+
+async def test_token_registry_mint_resolve_revoke_and_scope() -> None:
+    from uro_server.sessions import TokenRegistry
+
+    # "op" is the operator (admin) tier; "pleb" is a plain player token — NOT admin (D-39 review)
+    reg = TokenRegistry(_FakeTokenStore(), {"op": "gm", "pleb": "carol"}, admin_tokens={"op"})
+    assert reg.resolve("op") == "gm" and reg.is_admin("op")
+    assert reg.resolve("pleb") == "carol" and not reg.is_admin("pleb")  # a plain peer is not admin
+    tok = await reg.mint("bob", "camp-1")
+    assert reg.resolve(tok) == "bob" and not reg.is_admin(tok)  # minted → resolves, NOT admin
+    assert reg.campaign_of(tok) == "camp-1"  # minted tokens are campaign-scoped
+    assert reg.campaign_of("op") is None  # a static/operator token is server-wide (unscoped)
+    assert await reg.revoke(tok) is True
+    assert reg.resolve(tok) is None  # revoked → denied
+
+
+async def test_token_registry_stores_only_the_hash_and_survives_a_restart() -> None:
+    import hashlib
+
+    from uro_server.sessions import TokenRegistry
+
+    store = _FakeTokenStore()
+    tok = await TokenRegistry(store, {}).mint("bob", "camp-1")
+    # only sha256(token) is persisted — never the plaintext
+    assert list(store.rows.keys()) == [hashlib.sha256(tok.encode()).hexdigest()]
+    # a FRESH registry (a server restart) with a cold cache hydrates from the store and resolves it
+    reg2 = TokenRegistry(store, {})
+    assert reg2.resolve(tok) is None  # cold before hydrate
+    await reg2.hydrate()
+    assert reg2.resolve(tok) == "bob"  # durable across a restart
+
+
+def test_ws_rejects_a_token_scoped_to_another_campaign() -> None:
+    # D-39 review: a MINTED token is campaign-scoped; using it on ANOTHER campaign's play channel is
+    # rejected before accept (cross-campaign PC hijack). A static/operator token (token_campaign
+    # None) is intentionally server-wide and unaffected.
+    async def campaign_exists(campaign_id: str) -> bool:
+        return campaign_id in ("camp-1", "camp-2")
+
+    async def run_beat(campaign_id: str, participant: str, text: str):  # type: ignore[no-untyped-def]
+        yield "x"
+
+    deps = ServerDeps(
+        resolve_participant=lambda t: "bob" if t == "bob-tok" else None,
+        campaign_exists=campaign_exists,
+        run_beat=run_beat,
+        token_campaign=lambda t: "camp-1" if t == "bob-tok" else None,  # bob-tok minted for camp-1
+    )
+    client = TestClient(create_app(deps))
+    with client.websocket_connect("/campaigns/camp-1/play?token=bob-tok") as ws:
+        _recv_until(ws, "participant_joined")  # works on its OWN campaign
+    with (
+        pytest.raises(WebSocketDisconnect) as exc,
+        client.websocket_connect("/campaigns/camp-2/play?token=bob-tok"),
+    ):
+        pass
+    assert exc.value.code == 4403  # rejected on a DIFFERENT campaign, before accept
+
+
+def test_a_failed_beat_still_rotates_the_party_token() -> None:
+    # cross-phase review: a deterministically-failing turn-holder must NOT wedge the party — the
+    # token still rotates on beat_failed, so the next participant can act.
+    from uro_core.session import PartyArbiter
+
+    async def always_fail(campaign_id: str, participant: str, text: str):  # type: ignore[no-untyped-def]
+        raise RuntimeError("boom")
+        yield ""  # pragma: no cover — makes this an async generator
+
+    async def campaign_exists(campaign_id: str) -> bool:
+        return campaign_id == "camp-1"
+
+    deps = ServerDeps(
+        resolve_participant=lambda t: _TOKENS.get(t),
+        campaign_exists=campaign_exists,
+        run_beat=always_fail,
+    )
+    app = create_app(deps, arbiter=PartyArbiter())
+    client = TestClient(app)
+    with (
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-a") as a,  # player-1 (holder)
+        client.websocket_connect("/campaigns/camp-1/play?token=tok-b") as b,  # player-2
+    ):
+        _recv_until(a, "participant_joined")
+        _recv_until(a, "participant_joined")
+        # player-1 (holder) submits → beat FAILS; the token must rotate to player-2 anyway
+        a.send_json({"type": "intent", "text": "boom"})
+        assert _recv_until(a, "beat_failed")[-1]["participant_id"] == "player-1"
+        # player-2 now holds → their intent runs (also fails) — NOT a not_your_turn (rotation held)
+        b.send_json({"type": "intent", "text": "boom"})
+        assert _recv_until(a, "beat_failed")[-1]["participant_id"] == "player-2"

uro_server-0.2.0/tests/test_server_scaffold.py

@@ -0,0 +1,5 @@
+import uro_server
+
+
+def test_server_imports() -> None:
+    assert uro_server.__version__

uro_server-0.2.0/uro_server/__init__.py

@@ -0,0 +1,8 @@
+"""Uro Engine server: transport, sessions, wiring — no engine logic. Governing doc: 08."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("uro-server")
+except PackageNotFoundError:  # pragma: no cover - source checkout without an install
+    __version__ = "0.0.0+unknown"