Split the adventures router into a package

`backend/app/routers/adventures.py` held 2353 lines and 35 endpoints. It is now a package of 14 modules, the largest 443 lines. The split moves text rather than rewriting it. An AST comparison against the old file confirms all 86 definitions are identical, and the OpenAPI schema still lists the same 35 operations. Names a test replaces now live in `turns.py` only, and other modules reach them as `turns.<name>`. Rebinding a re-exported alias changes the alias and leaves every caller reading the original, so the package root does not re-export them. A patch aimed at the old target raises `AttributeError` instead of passing while doing nothing. Tests and the fixtures in `backend/tools/` say `adventures.turns.<name>`. The same rule keeps the turn lock working. One module owns `_active_turns`, so one lock guards one set. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Dix4oGV3njgWRdu7P9t6r
2026-08-29 01:05:50 +05:30
parent 32cd7c1077
commit 2fa812c056
34 changed files with 2667 additions and 2393 deletions
@@ -0,0 +1,58 @@
+"""The adventure endpoints, split across one module per group of routes.
+
+Importing this package registers every route, because each endpoint module
+decorates its handlers with the shared `router` from `deps`. The import order
+below is the order FastAPI matches paths in. No two routes here shadow each
+other, so the order is for reading rather than for correctness.
+
+Read the modules in this order to follow a turn from end to end:
+
+    deps           the router and the ownership check every endpoint runs
+    paging         reading a window of actions and numbering its attempts
+    nodes          moving around the story tree
+    turns          playing a turn, and the lock that allows only one at a time
+    takes          retries and the attempts that collect at one coordinate
+    branches       where a story splits
+
+What this package re-exports, and what it deliberately does not:
+
+Pure helpers and handlers are re-exported below, so `adventures.ACTION_PAGE` and
+`adventures.undo_turn` keep working. The names a test replaces are not, and you
+must reach those as `adventures.turns.<name>`. Rebinding a re-exported alias
+changes only the alias, so patching `adventures.generate_turn` would leave every
+caller reading the original. Leaving those names off raises `AttributeError`
+instead, which is the failure you want.
+"""
+from .deps import router
+
+# Imported for the side effect of registering routes. The names are unused here.
+from . import (  # noqa: F401
+    crud,
+    turns,
+    takes,
+    branches,
+    bundle_io,
+    scripts,
+    refresh,
+    insights,
+    memories,
+    actions,
+)
+from ... import limits  # noqa: F401  `adventures.limits` is patched by tests.
+from .crud import SNIPPET_MAX, _snippet
+from .paging import ACTION_PAGE
+from .takes import retry_action, undo_turn
+from .turns import SSE_HEADERS, sse, world_delta_of
+
+__all__ = [
+    "ACTION_PAGE",
+    "SNIPPET_MAX",
+    "SSE_HEADERS",
+    "_snippet",
+    "limits",
+    "retry_action",
+    "router",
+    "sse",
+    "undo_turn",
+    "world_delta_of",
+]