update

docs/architecture/runtime.md

@@ -21,6 +21,42 @@ deployments predictable.
 - API server responsibilities: query/command intake, validation, response shaping
 - Concurrency model between daemon and API server
 
+## Engine Runtime Flow (Draft)
+
+### Turn Daemon Loop
+
+- The turn daemon runs as a single-threaded loop.
+- The daemon engine uses in-memory state as the primary working set.
+- The daemon waits on two conditions during the event loop.
+  - Query/command requests from the external API server.
+  - The scheduled start time of the next turn.
+- External requests are processed until the next turn start time is reached.
+  - If no requests arrive, the daemon waits until the next turn start time.
+  - When the next turn start time arrives, the daemon starts turn processing
+    immediately even if requests remain queued.
+- While the daemon is resolving a turn, the API server queues incoming requests.
+
+### API Server Flow
+
+- The API server validates queries/commands and writes them to Redis Streams.
+- After a request is processed, the API server returns the result to clients.
+- Read-only queries may access the DBMS directly.
+
+### Queue and Rate Limits
+
+- API server requests are delivered to the daemon via Redis Streams.
+- Redis Stream mutation requests are rate-limited per user.
+  - Each user can have up to 30 pending mutation requests.
+  - Additional requests are rejected once the limit is exceeded.
+
+### In-Memory and DBMS Flush
+
+- The daemon processes actions against in-memory state by default.
+- DBMS writes are flushed in bulk after turn processing completes.
+- Frequently changing "next-turn intent" data is stored separately.
+  - The API server persists this data in the DBMS.
+  - The daemon loads only this data when the next turn begins.
+
 ## Turn Daemon vs API Query Priority (Outline)
 
 - Expected priority order under load
@@ -37,3 +73,24 @@ deployments predictable.
 
 - Metrics and logs required to validate scheduling and flush behavior
 - Suggested test scenarios for concurrency and consistency
+
+## Game Logic Testing (Draft)
+
+### Deterministic Inputs
+
+- RNG seed composition (hidden server seed, turn info, general info).
+- Scenario selection and scenario data.
+- Trigger set inputs: nation, general, and city state.
+- Game time and tick schedule.
+
+### Recommended Unit Test Flow
+
+- Prepare a deterministic test fixture (mock DB or in-memory state snapshot).
+- Execute game logic unit tests with fixed inputs and seeds.
+- Compare expected outputs against the pre-flush change set that would be
+  written to the DBMS.
+
+### Notes
+
+- Deterministic RNG makes output comparison stable and repeatable.
+- Prefer snapshotting inputs/outputs so regressions are easy to track.