update

docs/architecture/overview.md

@@ -28,3 +28,7 @@ monorepo plan is prepared alongside it.
 This document links to detailed runtime behavior in `docs/architecture/runtime.md`.
 Use that document for turn daemon scheduling, API request handling, and
 persistence sequencing.
+
+## Documentation TODOs
+
+- Pending follow-ups: `docs/architecture/todo.md`.

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.

docs/architecture/todo.md

@@ -0,0 +1,30 @@
+# Architecture TODOs
+
+This list tracks optional extensions and follow-up items for documentation.
+Move items into the main docs once they are finalized.
+
+## Runtime and Operations
+
+- Turn daemon scheduling details and preemption rules
+- Turn daemon vs API server priority policy under load
+- In-memory state lifecycle and DBMS flush checkpoints
+- Recovery behavior after partial flush or crash
+- Observability: metrics, logs, and alerts for turn processing
+
+## Game Logic and Testing
+
+- Input snapshot format (seed, scenario, trigger inputs, game time)
+- Output comparison rules (sorting, tolerances, diff granularity)
+- Unit test vs simulation test split and responsibilities
+- Deterministic RNG test harness guidelines
+
+## Trigger System
+
+- Trigger evaluation order and priority conflicts
+- Composition rules across traits, specials, and scenario effects
+- Example trigger sets per scenario or rule pack
+
+## Data and Profiles
+
+- "Next-turn intent" (예턴) data schema and lifecycle
+- Profile selection workflow and deployment mapping