generated from coulomb/repo-seed
500 lines
14 KiB
Markdown
500 lines
14 KiB
Markdown
---
|
|
id: HF-WP-0001
|
|
type: workplan
|
|
title: "Establish ops-hub as the First Inter-Hub Extension"
|
|
domain: helix_forge
|
|
repo: helix-forge
|
|
status: active
|
|
owner: worsch
|
|
created: "2026-05-16"
|
|
updated: "2026-05-16"
|
|
planning_priority: high
|
|
planning_order: 1
|
|
related_repos:
|
|
- inter-hub
|
|
- railiance-infra
|
|
- railiance-cluster
|
|
- railiance-platform
|
|
- railiance-apps
|
|
state_hub_workstream_id: "48d91935-197e-4ad4-be07-7bbcd535847c"
|
|
---
|
|
|
|
# Establish ops-hub as the First Inter-Hub Extension
|
|
|
|
## Goal
|
|
|
|
Create `ops-hub` as the first practical domain extension of the Interaction Hub
|
|
Framework, focused on professionalizing Railiance operations while the current
|
|
CoulombCore environment transitions toward the future ThreePhoenix production
|
|
setup.
|
|
|
|
The first increment should not replace State Hub or require a separate
|
|
`ops-hub` repository immediately. It should establish the operational model,
|
|
the hub vocabulary, and the smallest governed integration with Inter-Hub. A
|
|
separate implementation repository can be created once the shape of the hub is
|
|
stable and the Inter-Hub extension bootstrap API is less manual.
|
|
|
|
## Context
|
|
|
|
Current operational reality:
|
|
|
|
- `coulombcore` / `92.205.130.254` is the live production-like server. It runs
|
|
the current Gitea deployment and other hands-on experimental services.
|
|
- The local workstation still hosts important services such as State Hub and
|
|
local build/runtime pieces.
|
|
- `railiance01` / `92.205.62.239` is the first server of the intended future
|
|
ThreePhoenix production environment.
|
|
- The Railiance repo stack already separates operational responsibility:
|
|
`railiance-infra` (S1), `railiance-cluster` (S2), `railiance-platform` (S3),
|
|
`railiance-enablement` (S4), and `railiance-apps` (S5).
|
|
|
|
`ops-hub` should become the operational truth surface across those realities:
|
|
environments, hosts, clusters, services, releases, endpoints, backups,
|
|
readiness gates, incidents, risks, and migration waves.
|
|
|
|
## Inter-Hub API Findings
|
|
|
|
Checked live and local Inter-Hub evidence on 2026-05-16.
|
|
|
|
Live API:
|
|
|
|
- `https://hub.coulomb.social/api/v2/openapi.json` is available.
|
|
- `https://hub.coulomb.social/api/v2/docs` is available.
|
|
- Public UI route `https://hub.coulomb.social/Hubs` redirects to
|
|
`/NewSession`, so hub creation is currently an authenticated UI flow.
|
|
|
|
Live OpenAPI paths:
|
|
|
|
- `/widgets`, `/widgets/{id}`
|
|
- `/interaction-events`
|
|
- `/annotations`
|
|
- `/requirement-candidates`, `/requirement-candidates/{id}`
|
|
- `/decision-records`, `/decision-records/{id}`
|
|
- `/deployment-records`, `/deployment-records/{id}`
|
|
- `/outcome-signals`, `/outcome-signals/{id}`
|
|
- `/widget-types`, `/event-types`, `/annotation-categories`
|
|
- `/hub-registry`, `/hub-registry/{hubId}`
|
|
- `/widget-patterns`, `/widget-patterns/{id}`, `/widget-patterns/{id}/adopt`
|
|
- `/token`
|
|
|
|
Useful local Inter-Hub docs:
|
|
|
|
- `inter-hub/docs/domain-hub-extension-guide.md`
|
|
- `inter-hub/docs/new-hub-quickstart.md`
|
|
- `inter-hub/contracts/extensions/hub-capability-manifest-v1.md`
|
|
- `inter-hub/contracts/functional/interaction-reporting-v1.md`
|
|
|
|
Assessment:
|
|
|
|
- Inter-Hub provides enough guidance to start `ops-hub` as an API consumer
|
|
pattern or as a manually registered domain hub.
|
|
- Inter-Hub does not yet provide enough API surface to fully automate first hub
|
|
bootstrap. Hub creation, capability manifest creation/activation, API
|
|
consumer creation, API key issuance, and widget creation are primarily UI or
|
|
internal-controller workflows.
|
|
- The quickstart mentions `POST /api/v2/hubs` and `POST /api/v2/widgets`, but
|
|
the live OpenAPI and local routes do not expose those create endpoints. Treat
|
|
the quickstart as aspirational for bootstrap automation until Inter-Hub is
|
|
hardened.
|
|
|
|
## Architectural Decision
|
|
|
|
Start with **Pattern A: API Consumer Hub**, plus a manual or migration-backed
|
|
Inter-Hub registration:
|
|
|
|
1. Register `ops-hub` as a domain hub in Inter-Hub.
|
|
2. Activate a `HubCapabilityManifest` for its operational vocabulary.
|
|
3. Create an `ApiConsumer` and API key for `ops-hub`.
|
|
4. Seed a small set of governed widgets representing operational surfaces.
|
|
5. Emit interaction events and annotations from lightweight scripts or a
|
|
prototype UI.
|
|
|
|
Do not create a separate `ops-hub` repository until the first inventory,
|
|
readiness, and migration workflows have proven their data model.
|
|
|
|
## Initial ops-hub Vocabulary
|
|
|
|
Suggested manifest values:
|
|
|
|
### Widget Types
|
|
|
|
```json
|
|
[
|
|
"ops-environment",
|
|
"ops-host",
|
|
"ops-cluster",
|
|
"ops-service",
|
|
"ops-endpoint",
|
|
"ops-release",
|
|
"ops-backup-set",
|
|
"ops-runbook",
|
|
"ops-incident",
|
|
"ops-readiness-gate",
|
|
"ops-migration-wave",
|
|
"ops-risk"
|
|
]
|
|
```
|
|
|
|
### Event Types
|
|
|
|
```json
|
|
[
|
|
"ops-inventory-registered",
|
|
"ops-health-checked",
|
|
"ops-release-observed",
|
|
"ops-endpoint-verified",
|
|
"ops-backup-verified",
|
|
"ops-restore-tested",
|
|
"ops-runbook-executed",
|
|
"ops-risk-raised",
|
|
"ops-risk-accepted",
|
|
"ops-migration-gate-passed",
|
|
"ops-migration-gate-failed"
|
|
]
|
|
```
|
|
|
|
### Annotation Categories
|
|
|
|
```json
|
|
[
|
|
"ops-drift",
|
|
"ops-backup-gap",
|
|
"ops-security-gap",
|
|
"ops-routing-gap",
|
|
"ops-secret-gap",
|
|
"ops-readiness-blocker",
|
|
"ops-migration-risk",
|
|
"ops-observability-gap",
|
|
"ops-recovery-gap"
|
|
]
|
|
```
|
|
|
|
### Policy Scopes
|
|
|
|
```json
|
|
[
|
|
"ops-local",
|
|
"ops-transitional-prod",
|
|
"ops-production",
|
|
"ops-threephoenix",
|
|
"ops-registry",
|
|
"ops-secrets",
|
|
"ops-backup-retention"
|
|
]
|
|
```
|
|
|
|
## Initial Operational Inventory
|
|
|
|
The first ops-hub inventory should cover:
|
|
|
|
| Environment | Role | Current notes |
|
|
|---|---|---|
|
|
| `local` | Workstation services and development runtime | State Hub and local build/runtime pieces currently live here. |
|
|
| `coulombcore` | Live transitional production | Public IP `92.205.130.254`; hosts current Gitea and hand-built experimental production services. |
|
|
| `railiance01` | Future production foundation | Public IP `92.205.62.239`; first server of the intended ThreePhoenix setup. |
|
|
| `threephoenix-prod` | Target production topology | Future three-node Railiance production environment. |
|
|
|
|
The first services to model:
|
|
|
|
- Gitea / container registry
|
|
- State Hub and underlying services
|
|
- Inter-Hub itself
|
|
- PostgreSQL/CNPG services used by Gitea and State Hub
|
|
- Ingress/DNS/TLS endpoints for the above
|
|
- Backup and restore coverage for each persistent data store
|
|
|
|
## Tasks
|
|
|
|
### T01 — Confirm Inter-Hub extension bootstrap path
|
|
|
|
```task
|
|
id: HF-WP-0001-T01
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "2587a3b8-3b9b-4948-acaf-1547644e4563"
|
|
```
|
|
|
|
Confirm whether `ops-hub` should be registered through the Inter-Hub UI,
|
|
through a migration, or through new API endpoints.
|
|
|
|
Checks:
|
|
|
|
- Confirm the active Inter-Hub deployment URL and authentication path.
|
|
- Confirm whether `/Hubs/new`, `/HubCapabilityManifests`, `/ApiConsumers`, and
|
|
`/ApiKeys` are accessible to the operator.
|
|
- Confirm whether direct DB migration is acceptable for initial bootstrap.
|
|
- Record the chosen bootstrap path in this workplan.
|
|
|
|
Done when: there is a concrete, repeatable path to create the `ops-hub` row,
|
|
manifest, API consumer, and API key.
|
|
|
|
---
|
|
|
|
### T02 — Register ops-hub in Inter-Hub
|
|
|
|
```task
|
|
id: HF-WP-0001-T02
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "8e9bd9b2-54fc-49a4-8bb8-11c8577be48d"
|
|
```
|
|
|
|
Create the Hub row:
|
|
|
|
- `name`: `Ops Hub`
|
|
- `slug`: `ops-hub`
|
|
- `domain`: `ops.coulomb.social` or another explicit domain chosen by the
|
|
operator
|
|
- `hub_kind`: `domain`
|
|
|
|
Done when: `ops-hub` appears in `/Hubs` and `/api/v2/hub-registry` after
|
|
authentication.
|
|
|
|
---
|
|
|
|
### T03 — Activate the ops-hub capability manifest
|
|
|
|
```task
|
|
id: HF-WP-0001-T03
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "55f5aeed-21c3-4a83-bc78-f90f92c7d597"
|
|
```
|
|
|
|
Create and activate a `HubCapabilityManifest` for `ops-hub` using the
|
|
vocabulary in this workplan.
|
|
|
|
Validation:
|
|
|
|
- Declared widget types appear in `/api/v2/widget-types`.
|
|
- Declared event types appear in `/api/v2/event-types`.
|
|
- Declared annotation categories appear in `/api/v2/annotation-categories`.
|
|
- Policy scopes are visible in the Inter-Hub registry UI or DB, even though the
|
|
public v2 API currently lacks `/policy-scopes`.
|
|
|
|
Done when: the manifest status is `active` and no type conflicts remain.
|
|
|
|
---
|
|
|
|
### T04 — Create ops-hub API consumer and key
|
|
|
|
```task
|
|
id: HF-WP-0001-T04
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "ad08e729-8562-4a02-8bf6-dcdfebe430c8"
|
|
```
|
|
|
|
Create an `ApiConsumer` associated with the active `ops-hub` manifest, then
|
|
create a static API key with at least:
|
|
|
|
- `framework:read`
|
|
- `hub:ops-hub:read`
|
|
- `hub:ops-hub:write`
|
|
|
|
Store the key only in the operator secret store or local env file, never in Git.
|
|
|
|
Done when: `POST /api/v2/token` can exchange the static key for a short-lived
|
|
access token and `GET /api/v2/hub-registry` works with that token.
|
|
|
|
---
|
|
|
|
### T05 — Seed first governed ops widgets
|
|
|
|
```task
|
|
id: HF-WP-0001-T05
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "d303884d-d1f6-4fd0-a4ec-97afe6162164"
|
|
```
|
|
|
|
Create initial widgets for the operational surfaces:
|
|
|
|
- `ops-env-local`
|
|
- `ops-env-coulombcore`
|
|
- `ops-env-railiance01`
|
|
- `ops-env-threephoenix-prod`
|
|
- `ops-service-gitea`
|
|
- `ops-service-state-hub`
|
|
- `ops-service-inter-hub`
|
|
- `ops-readiness-gitea-registry`
|
|
- `ops-readiness-state-hub-cluster-deploy`
|
|
- `ops-migration-coulombcore-to-threephoenix`
|
|
|
|
If Inter-Hub still lacks a widget creation API, seed these through the UI or a
|
|
migration and record that as an API gap.
|
|
|
|
Done when: the widgets appear under `ops-hub` and can accept interaction events
|
|
and annotations.
|
|
|
|
---
|
|
|
|
### T06 — Build the first ops inventory artifact
|
|
|
|
```task
|
|
id: HF-WP-0001-T06
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "2a0b2f69-5a3d-433c-9cbd-85fd868b63d8"
|
|
```
|
|
|
|
Create an ops inventory document in `helix-forge` that expresses the current
|
|
state of:
|
|
|
|
- environments
|
|
- hosts
|
|
- clusters
|
|
- services
|
|
- endpoints
|
|
- storage and backup coverage
|
|
- migration readiness gates
|
|
|
|
Use this as the working model before creating a separate `ops-hub` repository.
|
|
|
|
Done when: a human can see the CoulombCore, local, railiance01, and
|
|
ThreePhoenix relationship without reading multiple repo workplans.
|
|
|
|
---
|
|
|
|
### T07 — Instrument the current Gitea registry work as the first ops-hub signal
|
|
|
|
```task
|
|
id: HF-WP-0001-T07
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "ed3e0396-b16d-40c2-9519-e755ad6241eb"
|
|
```
|
|
|
|
Use the recently fixed Gitea `/v2` route as the first real operational signal.
|
|
|
|
Suggested event:
|
|
|
|
```json
|
|
{
|
|
"widgetId": "<ops-readiness-gitea-registry-widget-id>",
|
|
"eventType": "ops-endpoint-verified",
|
|
"viewContext": "railiance-apps/workplans/RAIL-AP-WP-0001",
|
|
"metadata": {
|
|
"endpoint": "https://gitea.coulomb.social/v2/",
|
|
"expectedStatus": 401,
|
|
"observedHeader": "Docker-Distribution-Api-Version: registry/2.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
Done when: the Gitea registry readiness event is visible in Inter-Hub and
|
|
traceable back to the Railiance workplan.
|
|
|
|
---
|
|
|
|
### T08 — Define the ops-hub readiness gate model for ThreePhoenix migration
|
|
|
|
```task
|
|
id: HF-WP-0001-T08
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "72a58622-c3ac-4765-8026-5c2489af2058"
|
|
```
|
|
|
|
Define readiness gates that must be green before moving production
|
|
responsibility from CoulombCore to ThreePhoenix:
|
|
|
|
- DNS and TLS are codified.
|
|
- Git hosting and container registry are reproducible.
|
|
- Persistent data stores have backup and restore evidence.
|
|
- Secrets and SOPS/age keys are available through governed operator paths.
|
|
- Cluster runtime and platform services are recreated through Railiance repos.
|
|
- Rollback path is documented.
|
|
- Operator runbooks exist for deploy, restore, rotate, and incident response.
|
|
|
|
Done when: each gate has an owner repo, evidence requirement, and status.
|
|
|
|
---
|
|
|
|
### T09 — Decide whether to create a separate ops-hub repository
|
|
|
|
```task
|
|
id: HF-WP-0001-T09
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "0e5842fd-1d33-4e2a-9701-07f623a2b901"
|
|
```
|
|
|
|
Make the repository decision after T05-T08.
|
|
|
|
Create a separate repo when at least one of these is true:
|
|
|
|
- `ops-hub` needs its own UI beyond Inter-Hub's generic hub dashboards.
|
|
- `ops-hub` needs collectors, adapters, or scheduled probes.
|
|
- `ops-hub` needs its own release lifecycle.
|
|
- The ops vocabulary stabilizes enough to deserve reusable code.
|
|
|
|
Until then, keep the model in `helix-forge` and register state in Inter-Hub.
|
|
|
|
Done when: the decision is recorded with rationale and a repo boundary if
|
|
needed.
|
|
|
|
---
|
|
|
|
### T10 — Inter-Hub API hardening for extension bootstrap
|
|
|
|
```task
|
|
id: HF-WP-0001-T10
|
|
status: todo
|
|
priority: high
|
|
target_repo: inter-hub
|
|
state_hub_task_id: "7fa54508-7add-4885-8913-12edaadc4d92"
|
|
```
|
|
|
|
Create or link an `inter-hub` workplan to make domain hub bootstrapping
|
|
machine-repeatable.
|
|
|
|
Recommended Inter-Hub improvements:
|
|
|
|
1. Add `POST /api/v2/hubs` and include it in OpenAPI.
|
|
2. Add `POST /api/v2/widgets` and include it in OpenAPI.
|
|
3. Add API endpoints for `HubCapabilityManifest` draft creation, update, and
|
|
activation.
|
|
4. Add API endpoints for `ApiConsumer` and API key creation, or a clearly
|
|
documented admin-only bootstrap command if API key creation remains UI-only.
|
|
5. Add `/api/v2/policy-scopes` to match the policy scope registry already used
|
|
by manifests.
|
|
6. Add distinct OpenAPI request schemas for create requests instead of reusing
|
|
response schemas.
|
|
7. Align `docs/new-hub-quickstart.md` with the actual live API until the create
|
|
endpoints exist.
|
|
8. Fix `Web.Controller.Api.V2.InteractionEvents` so manifest-declared event
|
|
types are actually decoded and enforced.
|
|
9. Fix webhook dispatch so it uses the submitted event type instead of the
|
|
hard-coded `"clicked"` event name.
|
|
10. Decide whether event `metadata` is part of the v2 create contract; if yes,
|
|
persist it in the controller and test it.
|
|
|
|
Done when: the next domain hub can be created from a script using documented
|
|
API calls and without direct DB access.
|
|
|
|
## Initial Acceptance Criteria
|
|
|
|
This workplan is complete when:
|
|
|
|
1. `ops-hub` is registered in Inter-Hub.
|
|
2. Its capability manifest is active.
|
|
3. It has an API consumer and key.
|
|
4. Initial ops widgets exist for environments, services, readiness gates, and
|
|
migration waves.
|
|
5. At least one real operational event has been submitted.
|
|
6. The CoulombCore-to-ThreePhoenix readiness model is documented.
|
|
7. A decision has been made whether to create a separate `ops-hub` repository.
|
|
8. Inter-Hub bootstrap API gaps are either fixed or tracked in an Inter-Hub
|
|
workplan.
|
|
|
|
## Notes
|
|
|
|
`ops-hub` should complement State Hub during the transition:
|
|
|
|
- State Hub continues to track workstreams, decisions, and progress events.
|
|
- `ops-hub` tracks operational reality and readiness evidence.
|
|
- `coo-hub` can later become the coordination/workstream successor once the
|
|
broader hub constellation is established.
|
|
|