galaxy-game/rtmanager/docs/README.md

Runtime Manager — Service-Local Documentation

This directory hosts the service-local documentation for Runtime Manager. The top-level ../README.md describes the current-state contract (purpose, scope, lifecycles, surfaces, configuration, observability); the documents below complement it with focused content docs and design-rationale records.

Content docs

• Runtime and components — process diagram, listeners, workers, lifecycle services, stream offsets, configuration groups, runtime invariants.
• Flows — mermaid sequence diagrams for the lifecycle and observability flows.
• Operator runbook — startup, readiness, shutdown, and recovery scenarios.
• Configuration and contract examples — .env, REST request bodies, stream payloads, storage inspection snippets.

Design rationale

• PostgreSQL schema decisions — the schema decision record consolidating the persistence-layer agreements (tables, indexes, CAS shape, created_at preservation, jsonb round-trip, schema/role provisioning split).
• Domain and ports — string-typed enums, the four allowed runtime transitions, why Inspect splits into InspectImage / InspectContainer, why LobbyGameRecord is minimal, and other domain-layer choices.
• Adapters — Docker SDK adapter, Lobby internal HTTP client, the three Redis publishers, the mockgen convention for wide ports, and the unit-test strategy for HTTP-backed adapters.
• Lifecycle services — per-game lease semantics, the Result-shaped contract, failure-mode tables, the lease-bypass Run method on inner services, the X-Galaxy-Caller header convention, and the canonical error code → HTTP status mapping.
• Background workers — single-ownership table per event_type, container_disappeared suppression rules, probe hysteresis, the events listener reconnect policy, the reconciler's per-game lease and three drift kinds.
• Service-local integration suite — the integration build tag, the in-process app.NewRuntime choice, the Lobby HTTP stub, and the test isolation strategy.