helix-forge/workplans/HF-WP-0001-establish-ops-hub-first-extension.md

id, type, title, domain, repo, status, owner, created, updated, planning_priority, planning_order, related_repos, state_hub_workstream_id

id	type	title	domain	repo	status	owner	created	updated	planning_priority	planning_order	related_repos	state_hub_workstream_id
HF-WP-0001	workplan	Establish ops-hub as the First Inter-Hub Extension	helix_forge	helix-forge	active	worsch	2026-05-16	2026-05-16	high	1	inter-hub railiance-infra railiance-cluster railiance-platform railiance-apps	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

[
  "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

[
  "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

[
  "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

[
  "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

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

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

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

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

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

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

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:

{
  "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

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

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

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.