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.