auu

docs/shared-world-complete.md

@@ -0,0 +1,34 @@
+# Shared world runtime
+
+The runtime shares board definitions, solved states, first-solver identity, world expansion, and clear notifications.
+
+Transient WebSocket state includes nearby cursors, viewport subscriptions, board claims, reactions, and clear notifications. Transient state is not written to the shared-world file.
+
+Player-specific persistent state includes the player name, earned score ledger, purchases, and equipped cursor state on the client. Purchases are validated against the server-authoritative store inventory and price.
+
+Difficulty-adjustment field items and shared field-placement APIs are not part of the current runtime.
+
+## HTTP endpoints
+
+- `POST /api/cloud/session`
+- `POST /api/cloud/profile`
+- `GET /api/cloud/status`
+- `GET /api/cloud/pull`
+- `POST /api/cloud/push`
+- `GET /api/player/state`
+- `POST /api/player/purchase`
+- `POST /api/player/generation-bonus`
+
+## Realtime messages
+
+- `viewport`
+- `cursor`
+- `cursor-hide`
+- `claim`
+- `release`
+- `reaction`
+- `board-cleared`
+
+## Authority model
+
+The server validates solved routes, reconstructs rewards and stores, records the first solver, grants bounded adjacent expansion, tracks each player's earned and spent score, and rejects arbitrary board insertion.