registered repo with state hub

2026-05-16 02:10:51 +02:00
parent 66f535d07a
commit 9c565cd68d
3 changed files with 835 additions and 0 deletions
--- a/workplans/HF-WP-0001-establish-ops-hub-first-extension.md
+++ b/workplans/HF-WP-0001-establish-ops-hub-first-extension.md
@@ -0,0 +1,499 @@
+---
+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.
+