Prepare State Hub retirement baseline

docs/ops-run-read-projection.md

@@ -0,0 +1,56 @@
+# Ops run read projection
+
+State Hub projects activity-core `ops_run` queue health for fleet visibility.
+Activity-core remains the authority for run creation, claims, leases,
+completion, failure, and expiry under ACT-ADR-005 and ACTIVITY-WP-0026.
+
+## V1 contract
+
+V1 is a cached **pull** projection. State Hub reads activity-core:
+
+```text
+GET {ACTIVITY_CORE_URL}/ops-runs?limit=200
+X-Worker-Token: ${ACTIVITY_CORE_WORKER_TOKEN}
+```
+
+The credential is owned by the OpenBao/railiance-platform path and must be
+injected at runtime. State Hub never persists or returns it.
+
+The upstream fields consumed are:
+
+| Upstream field | Projection field |
+| --- | --- |
+| `id` | `id` |
+| `activity_definition_id` | `definition` |
+| `target_repo` | `target_repo` |
+| `state` | `state` |
+| `claim_owner`, `lease_until`, `attempt` | `lease` |
+| `updated_at` | `updated_at` |
+| `result.error` or `last_error` | `last_error` |
+
+State Hub exposes:
+
+- `GET /ops-runs/summary`
+- `/state/summary` field `ops_runs`
+
+Both provide `open`, `claimed`, `failed_24h`, `stuck_open_or_claimed`, and a
+bounded list of open/claimed/failed rows. There are deliberately no claim,
+heartbeat, complete, fail, or expiry endpoints in State Hub.
+
+## Cache and failure behavior
+
+`OPS_RUN_PROJECTION_TTL_SECONDS` defaults to 15 seconds. A refresh failure
+serves the last successful projection with `stale: true` and an `error` field.
+Before the first successful read, the projection returns `available: false`;
+State Hub summary and work-record APIs remain healthy.
+
+`OPS_RUN_SLA_HOURS` defaults to 1 hour and classifies open or claimed runs older
+than the threshold as stuck. This is an operator signal, not a state transition.
+
+## Railiance and coulombcore boundary
+
+Claims happen against activity-core on Railiance. State Hub on coulombcore only
+pulls visibility through the configured private activity-core endpoint. If the
+edge/tunnel path is unavailable, visibility may lag and the projection is marked
+stale; operators should alert on stale/unavailable projection state rather than
+moving claim authority into State Hub.