the-custodian/docs/ops-hub-service-inventory.md

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:

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.