# Runtime Manager — Service-Local Documentation

This directory hosts the service-local documentation for `Runtime
Manager`. The top-level [`../README.md`](../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](runtime.md) — process diagram, listeners,
  workers, lifecycle services, stream offsets, configuration groups,
  runtime invariants.
- [Flows](flows.md) — mermaid sequence diagrams for the lifecycle and
  observability flows.
- [Operator runbook](runbook.md) — startup, readiness, shutdown, and
  recovery scenarios.
- [Configuration and contract examples](examples.md) — `.env`,
  REST request bodies, stream payloads, storage inspection snippets.

## Design rationale

- [PostgreSQL schema decisions](postgres-migration.md) — 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](domain-and-ports.md) — string-typed enums, the
  four allowed runtime transitions, why `Inspect` splits into
  `InspectImage` / `InspectContainer`, why `LobbyGameRecord` is
  minimal, and other domain-layer choices.
- [Adapters](adapters.md) — 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](services.md) — 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](workers.md) — 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](integration-tests.md) — the
  `integration` build tag, the in-process `app.NewRuntime` choice,
  the Lobby HTTP stub, and the test isolation strategy.