# Ops Hub Service Inventory

Date: 2026-06-05

## Purpose

The first ops-hub "now view" should answer one practical question:

> What service is running where, who owns it, how is it reached, and what
> evidence says it is alive?

The lowest-effort path is a small read model, not a full new application. The
read model starts as `ops/service-inventory.yml`, can be surfaced through
Inter-Hub ops widgets, and can later be ingested by the standalone `ops-hub`
repo planned in `CUST-WP-0025`.

## Operating Model

- Git owns the declared inventory.
- Inter-Hub widgets expose the visible ops entities.
- Interaction events provide timestamped operational evidence.
- activity-core runs repeatable probes and writes evidence.
- State Hub continues to own workstreams, tasks, decisions, and progress. It is
  not the service catalog.

## Minimal Record Shape

Each service record should include:

- `id`: stable lowercase service id, for example `state-hub`.
- `name`: human-readable name.
- `lifecycle_state`: `observed`, `planned`, `target`, or `retired`.
- `health_status`: `unknown`, `observed_ok`, `degraded`, `down`, or `planned`.
- `environment`: environment id where the service currently belongs.
- `owner_repos`: repos that own desired state, runtime code, or runbooks.
- `runtime`: runtime kind and location details, such as `local-process`,
  `k3s`, `systemd`, `external`, or `bridge`.
- `endpoints`: public, local, cluster, or tunnel endpoints with expected
  non-secret checks.
- `backing_stores`: databases, PVCs, object stores, or external stores that
  must be backed up with the service.
- `access_paths`: non-secret descriptions of SSH, Kubernetes, HTTP, or tunnel
  paths.
- `evidence`: links to docs, progress events, probe results, or workplans.
- `gaps`: missing evidence or operating controls.

The schema lives at `schemas/ops-service-inventory.schema.json`.

## First View

The initial ops-hub view can be a dense table:

| Column | Meaning |
|---|---|
| Service | `name` plus `id` |
| Where | environment, host, cluster, namespace |
| Owner | owner repo and desired state source |
| Endpoint | primary endpoint and expected check |
| Health | latest health status and last evidence timestamp |
| Data | backing stores and backup gap summary |
| Access | access path status |
| Gaps | highest-priority missing operating evidence |

This is enough to make scattered operational reality visible without waiting
for a full incident system, runbook executor, or custom database.

The repo-native version is rendered to `docs/ops-hub-service-catalog.md`:

```bash
make ops-inventory-view
```

## Evidence Events

Use a small event vocabulary first:

- `ops-service-observed`: service/runtime object was observed.
- `ops-endpoint-verified`: endpoint responded as expected.
- `ops-access-path-checked`: access path was checked without storing secrets.
- `ops-backup-verified`: backup and restore evidence exists.
- `ops-inventory-drift`: observed state differs from declared inventory.

Event metadata should reference the stable inventory id and include non-secret
probe output only.

## Promotion Path

1. Keep `ops/service-inventory.yml` as the source artifact.
2. Seed or update Inter-Hub widgets from the inventory ids.
3. Let activity-core run probes and submit evidence events.
4. Build the first ops-hub view from inventory plus latest evidence.
5. When the standalone `ops-hub` repo exists, ingest the same inventory and
   evidence events into the proper Service, AccessPath, Runbook, and Incident
   models from `CUST-WP-0025`.