Add REUSE-WP-0011: federation hub on railiance01 and hub CLI

Propose hosted registry hub service with repo register/update API and reuse-surface hub CLI client. Record as gap analysis priority 17.
2026-06-15 07:40:36 +02:00
parent e8797b2e91
commit d99c8e627b
2 changed files with 236 additions and 1 deletions
--- a/docs/IntentScopeGapAnalysis.md
+++ b/docs/IntentScopeGapAnalysis.md
@@ -278,6 +278,12 @@ core commands. Individual registered capabilities may carry their own evidence
 | 15 | Network federation | HTTP URL sources + cache in `federation compose` | Closed (WP-0010) |
 | 16 | Graph UI | `docs/graph/index.html` explorer | Closed (WP-0008) |

+### Proposed next work
+
+| Priority | Gap | Suggested outcome | Status |
+|---|---|---|---|
+| 17 | Hosted federation hub | Hub service on `railiance01` + `reuse-surface hub` CLI | Proposed (WP-0011) |
+
 ---

 ## 9. Document Maintenance Rules
@@ -302,4 +308,5 @@ core commands. Individual registered capabilities may carry their own evidence
 | 2026-06-15 | REUSE-WP-0007 closed priority 13 (searchable catalog UI) |
 | 2026-06-15 | REUSE-WP-0008 closed priority 16 (graph explorer) |
 | 2026-06-15 | REUSE-WP-0009 added pytest suite and CI fail-on-warnings; vector R3 |
-| 2026-06-15 | REUSE-WP-0010 closed priority 15 (HTTP remote federation + cache) |
+| 2026-06-15 | REUSE-WP-0010 closed priority 15 (HTTP remote federation + cache) |
+| 2026-06-15 | REUSE-WP-0011 proposed for priority 17 (hosted hub on railiance01) |
--- a/workplans/REUSE-WP-0011-federation-hub-on-railiance01.md
+++ b/workplans/REUSE-WP-0011-federation-hub-on-railiance01.md
@@ -0,0 +1,228 @@
+---
+id: REUSE-WP-0011
+type: workplan
+title: "Federation hub service on railiance01 and hub CLI"
+domain: helix_forge
+repo: reuse-surface
+status: proposed
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+---
+
+# Federation hub service on railiance01 and hub CLI
+
+Close the next federation gap: a **hosted registry hub** on production cluster
+node `railiance01` (`92.205.130.254`) that records which repositories publish
+capability indexes, plus a **CLI client** for registering and updating those
+records without hand-editing `registry/federation/sources.yaml` on every machine.
+
+This extends WP-0010 (HTTP fetch) and WP-0005 (federation compose) from
+pull-only client workflows to a central coordination surface agents and repos
+can target.
+
+## Problem
+
+Today each consumer must:
+
+1. Know sibling repo raw index URLs or local checkout paths.
+2. Maintain `registry/federation/sources.yaml` locally.
+3. Run `reuse-surface federation compose` to materialize `federated.yaml`.
+
+There is no shared source of truth for **which repos are registered** in the
+helix_forge federation, and no stable HTTP endpoint on Railiance infrastructure
+for discovery without cloning every repo.
+
+## Target outcome
+
+| Surface | Deliverable |
+|---|---|
+| Hosted service | HTTP API on `railiance01` storing repo registrations and serving a composed federated index |
+| CLI client | `reuse-surface hub register`, `update`, `list`, `status` against the hub API |
+| Operations | Container image, deployment manifests, TLS ingress, documented runbook |
+| Dogfood | `reuse-surface` and at least one sibling repo registered via the hub |
+
+**Proposed public URL (confirm in T05):** `https://reuse-hub.whywhynot.de`
+
+## Design decisions (draft)
+
+- **Hub role:** Federation **coordinator**, not capability host. Stores repo
+  metadata and index URLs; does not ingest or edit individual capability entry
+  Markdown files.
+- **Registration model:** Mirror federation source fields (`repo`, `url` or
+  `index`, `domain`, `enabled`, `required`, `cache_ttl_seconds`, `description`).
+  Hub is authoritative for cross-repo membership; local `sources.yaml` may
+  optionally sync from hub or point at hub-composed output only.
+- **Compose strategy:** Hub periodically or on-demand fetches enabled remote
+  `url` sources (reuse WP-0010 fetch/cache logic) and merges into
+  `GET /v1/federated` output. Local-only `index` paths are **not** valid hub
+  registrations unless expressed as published raw URLs.
+- **Auth (MVP):** Token-based write access via `REUSE_SURFACE_HUB_TOKEN` /
+  `Authorization: Bearer`; read endpoints public for agent discovery.
+- **Persistence (MVP):** SQLite on a PVC inside the hub container. Postgres
+  via cnpg is a follow-up if multi-replica or backup requirements emerge.
+- **Availability target:** Promote `capability.registry.register` toward **A4**
+  (service API) for hub register/update flows once deployed and tested.
+
+## Placement and cross-repo coordination
+
+| Concern | Owner repo | Coordination |
+|---|---|---|
+| Hub service code, API schema, CLI | `reuse-surface` | This workplan |
+| Container image build and push | `reuse-surface` + `railiance-forge` | OCI registry on `gitea.coulomb.social` |
+| Helm release on `railiance01` | `railiance-apps` | Capability request or companion task |
+| Ingress / TLS / DNS | `railiance-apps` + DNS owner | T05 — human confirmation for hostname |
+| Traefik / cert-manager primitives | `railiance-cluster` / `railiance-platform` | Reuse existing stack |
+| Secrets (hub token, TLS) | Operator | SOPS / sealed secrets; never commit plaintext |
+
+Reference deployment pattern:
+`railiance-apps/workplans/railiance-apps-WP-0002-vergabe-teilnahme-on-railiance01.md`
+(Traefik ingress, cert-manager `letsencrypt-prod`, Helm values SOPS).
+
+## API sketch (T01 refines)
+
+```text
+GET  /health
+GET  /v1/repos                     # list registrations
+POST /v1/repos                     # register repo (auth required)
+GET  /v1/repos/{repo}              # get one registration
+PATCH /v1/repos/{repo}             # update registration (auth required)
+DELETE /v1/repos/{repo}            # deregister (auth required, optional MVP)
+GET  /v1/federated                 # composed federated index (YAML or JSON)
+POST /v1/federated/compose         # trigger refresh (auth required, optional MVP)
+```
+
+Registration body aligns with `schemas/federation.schema.yaml` `$defs/source`,
+plus hub metadata (`registered_at`, `updated_at`, `registered_by`).
+
+## CLI sketch (T03 refines)
+
+```bash
+# Configure hub endpoint (env REUSE_SURFACE_HUB_URL or --hub-url)
+reuse-surface hub status
+reuse-surface hub list
+reuse-surface hub register --repo state-hub \
+  --url https://gitea.coulomb.social/coulomb/state-hub/raw/main/registry/indexes/capabilities.yaml \
+  --domain helix_forge
+reuse-surface hub update --repo state-hub --enabled true
+reuse-surface hub show --repo state-hub
+```
+
+Local federation manifest sync (optional stretch): `reuse-surface hub sync`
+writes `registry/federation/sources.yaml` from hub state for offline compose.
+
+## Safety contract
+
+- Do not commit hub tokens, TLS private keys, or decrypted Helm values.
+- Do not store capability entry bodies on the hub — URLs and metadata only.
+- Fail closed on schema validation errors when composing federated output.
+- Require human approval before irreversible DNS or production cutover steps.
+
+---
+
+## Define Hub API And Registration Schema
+
+```task
+id: REUSE-WP-0011-T01
+status: todo
+priority: high
+```
+
+Author `specs/FederationHubAPI.md` and `schemas/hub-registration.schema.yaml`
+defining repo registration records, API request/response shapes, auth model, and
+error codes. Reuse federation source fields where possible. Record decision in
+hub workplan design section or `docs/decisions/` if scope warrants.
+
+## Implement Hub Service
+
+```task
+id: REUSE-WP-0011-T02
+status: todo
+priority: high
+```
+
+Add a deployable hub service under `reuse_surface/` (e.g. `hub/` package or
+`hub_service/` entrypoint):
+
+- FastAPI application exposing T01 endpoints
+- SQLite persistence for registrations
+- Integrate WP-0010 remote fetch/cache for `url` sources when composing federated
+  output
+- `GET /v1/federated` returns merged index with `source_repo` attribution
+- Health check suitable for k8s probes
+
+## Implement Hub CLI Client
+
+```task
+id: REUSE-WP-0011-T03
+status: todo
+priority: high
+```
+
+Extend `reuse-surface` CLI with `hub` subcommands:
+
+- `register`, `update`, `show`, `list`, `status`
+- `--hub-url` flag and `REUSE_SURFACE_HUB_URL` env support
+- `REUSE_SURFACE_HUB_TOKEN` for authenticated writes
+- Document in `tools/README.md` and `AGENTS.md`
+
+## Containerize And Publish Deployment Artifacts
+
+```task
+id: REUSE-WP-0011-T04
+status: todo
+priority: medium
+```
+
+Provide:
+
+- `Dockerfile` for the hub service
+- Example k8s manifests or Helm values template under `deploy/` or `docs/deploy/`
+- Image naming convention: `gitea.coulomb.social/coulomb/reuse-surface-hub:<tag>`
+- CI job or documented build/push steps (coordinate with `railiance-forge`
+  registry guidance)
+
+## Deploy Hub To railiance01
+
+```task
+id: REUSE-WP-0011-T05
+status: wait
+priority: medium
+```
+
+Deploy the hub as a governed release on `railiance01`:
+
+- Confirm hostname (default `reuse-hub.whywhynot.de`) and DNS A record
+- Traefik ingress + cert-manager TLS
+- PVC for SQLite data
+- Inject hub write token via SOPS/sealed secret
+- Verify `GET /health` and `GET /v1/federated` from workstation and from cluster
+
+**Blocked on:** DNS decision, operator secret provisioning, and
+`railiance-apps` Helm release slot (may need companion workplan task there).
+
+## Document Operations And Dogfood Registrations
+
+```task
+id: REUSE-WP-0011-T06
+status: todo
+priority: medium
+```
+
+Update `docs/RegistryFederation.md` with hub-centric workflow. Register
+`reuse-surface` index URL via CLI. Document how agents discover
+`GET /v1/federated` without local `sources.yaml` maintenance. Update
+`SCOPE.md` and `docs/IntentScopeGapAnalysis.md` when hub is live.
+
+## Add Tests And CI Coverage
+
+```task
+id: REUSE-WP-0011-T07
+status: todo
+priority: medium
+```
+
+Add pytest coverage for hub API handlers and CLI client (use TestClient and
+mock HTTP). Extend CI to run hub tests. Hub deployment smoke test documented
+as a manual or post-deploy check in T05.