state-hub/policies/service-dom.md

Service Definition of Mature (DoM)

A long-running service (an HTTP API, MCP server, worker, or daemon — as opposed to a repository or a workstream) is considered mature when all criteria below are satisfied. This is the service-level companion to the Repository Definition of Integrated (repo-doi.md) and the Workstream Definition of Done (workstream-dod.md).

Criteria are grouped by Service Maturity Level: a service that meets all Core criteria is operable; meeting Standard criteria makes it observable; meeting Full criteria makes it mature.

---

Level 1 — Core (Operable)

The minimum for a service to be run and reasoned about by agents and operators.

• Health endpoint — the service exposes an unauthenticated health route that allows efficient "is the service available?" probing without running business logic. It returns 200 with a small JSON body ({"status": "ok", ...}) when ready, and a non-2xx (e.g. 503) when a hard dependency is unavailable. For the State Hub API this is GET /state/health, which also reports DB connectivity ({"db": "connected"}). Agents should probe this before assuming the service is offline (see the session protocol fallback in CLAUDE.md).

• Start command documented — a single documented command brings the service up from a clean checkout (for the State Hub API: make api, with make db first if Postgres is not running).

• Bound address known — the listen host/port is fixed and documented (State Hub API: http://127.0.0.1:8000; remote via ops-bridge: http://127.0.0.1:18000).

---

Level 2 — Standard (Observable)

The service can be monitored and integrated by other agents and tooling.

• Health route is tested — an automated test asserts the health route returns a success status and the expected shape, so regressions that take the service silently un-probeable are caught.

• Dependencies declared — external service dependencies are declared in tpsc.yaml and ingested (make ingest-tpsc REPO={slug}); an empty services: [] is used when there are none, to make the absence explicit.

• Remote reachability path — if the service is consumed across machines, the tunnel/bridge route is documented (ops-bridge port map) and the health endpoint is reachable over it.

• Graceful dependency failure — when a hard dependency (DB, broker) is down, the service reports it via the health route rather than crashing or hanging callers.

---

Level 3 — Full (Mature)

The service participates safely in the wider ecosystem over time.

• Versioned interface — breaking interface changes are published via the interface-change tracker (publish_interface_change) so consumers are warned.

• Authn/authz boundary documented — which routes are public (e.g. health) versus authenticated is explicit, and credential needs route through the standard channels (credential-routing.md / warden route).

• Recovery documented — the runbook for restart and for restoring a failed dependency is captured (for the State Hub API: make db then make api; consistency repair via make fix-consistency).

• Progress/telemetry on lifecycle — significant lifecycle events (deploys, migrations, outages) are recorded so the hub reflects service state.

---

Maturity Checklist (Quick Reference)

#	Criterion	Level	Verified by
1	Health endpoint	1 · Core	curl -s $BASE/state/health → 200, {"status":"ok"}
2	Start command documented	1 · Core	make api from clean checkout
3	Bound address known	1 · Core	docs / CLAUDE.md
4	Health route is tested	2 · Standard	tests/ asserts health route
5	Dependencies declared	2 · Standard	make ingest-tpsc
6	Remote reachability path	2 · Standard	ops-bridge health probe
7	Graceful dependency failure	2 · Standard	health returns 503 when DB down
8	Versioned interface	3 · Full	publish_interface_change
9	Authn/authz boundary documented	3 · Full	docs review
10	Recovery documented	3 · Full	runbook present
11	Lifecycle telemetry	3 · Full	add_progress_event on lifecycle

---

Notes

• The DoM is enforced by convention, not by automated gates.
• The health endpoint (Core #1) is the load-bearing criterion: it is what lets agents and monitors distinguish "service down" from "service up but the request is wrong," cheaply and without side effects.
• "Service" here means a process exposing an interface over its lifetime — the State Hub API and the FastMCP server each qualify. A one-shot CLI or a migration script is not a service and is out of scope for the DoM.