S03 spec: observability readiness model and internal listener

Context

Spawned by the narrowing of S03 to logging-only on !56 (merged). The dependency-aware readiness model and the internal listener (which hosts /-/metrics, /debug/pprof/*, and /debug/vars) were cut from S03 to keep the narrowing focused. This issue tracks the follow-up spec that picks them up.

Scope

Define:

  • The readiness wrapper: critical vs non-critical dependencies, the srv.AddReadinessCheck registration model, the readiness_check_up gauge, per-check timeouts, the shutdown self-check, and the no-startup-probe decision.
  • The MVP critical and non-critical check set: database, object storage, shutdown, Redis (when configured).
  • The Kubernetes probe defaults (interval, per-check timeout, failure threshold, initialDelaySeconds).
  • The internal listener: binding semantics, the two-port pattern, the routing for /-/metrics, /debug/pprof/*, and /debug/vars.
  • The InternalServerConfig proto message, defaults (:8081), and LabKit v2 mapping.
  • The /-/readiness extension to S01 (response-body shape, dual-listener registration).

Source material

The pre-narrowing version of S03 at commit 5592b76, specifically:

  • Lines 737-820: ### Health checks (liveness, readiness with critical/non-critical wrapper, startup decision).
  • Lines 821-865: ### Internal server (two-listener pattern, debug-port layout).
  • Lines 874-895: ### GET /-/readiness extension.
  • Lines 897-931: ### GET /-/metrics, ### GET /debug/pprof/*, ### GET /debug/vars API contracts (the metrics endpoint is also referenced in the metrics follow-up; this spec owns the listener and routing, the metrics spec owns the exposition format).
  • Lines 1061-1076: the InternalServerConfig proto block.

Author treats those sections as starting material, not a frozen contract. Reviewer feedback on the original sections is in !56 (merged)'s history.

Related

  • S01: HTTP server and routing carries cross-references to the cut S03 readiness sections at lines 139, 251, 297, 304, 347, 389, and 706-714. Those references are knowingly stale during the narrowing window. They will be repaired when this spec ships and S01 is updated to point here.
  • Sister follow-ups: metrics framework, tracing framework.
  • !56 (merged) (the narrowing MR).

Closure criterion

The framework spec ships and replaces the placeholder reference to this issue in:

  • docs/specs/S03-observability.md Summary and Out of Scope.
  • docs/dev/observability.md catalog header.

Once shipped, S01 cross-references should be repointed at this spec in a follow-up commit on S01.