coulomb/core-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: reconcile core hub state and intent
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details

Browse source
This commit is contained in:
tegwick 2026-08-21 08:49:15 +02:00
parent a7adc40c2f
commit c7b1ebb560
7 changed files with 239 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

16
INTENT.md
View file

@ -52,4 +52,18 @@ Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`
## Current State
Production serves Core Hub at `hub.coulomb.social` since 2026-07-03. Haskell Inter-Hub is retired (`CORE-WP-0007`). Ecosystem consolidation with hub-core and state-hub is tracked under `CUST-WP-0057` / `CORE-WP-0009`.
Core Hub is the verified production `/api/v2` runtime at
`hub.coulomb.social`, now running on railiance01 through the `rapp-core-hub`
package. The 2026-08-21 relocation preserved the public contract and durable
data, reverified ops-hub and activity-core consumers, and retired the active
CoulombCore runtimes and obsolete tunnel. Haskell Inter-Hub remains retired
(`CORE-WP-0007`).
This delivers the practical Gen3 production reset, but not the whole product
intent. Messaging, progress/work projections, several durable evidence and
decision resources, and a single extension runtime remain outside Core Hub or
only partially represented. `CORE-WP-0010` tracks absorption into hub-core and
repository archive; it is blocked on the runtime packaging, minimal-port, and
joint-plan decisions in `HUB-WP-0004`. The healthy service remains the
production and rollback authority until dual-run consumer gates prove a
replacement. See `STATE.md` for current operational truth.

12
README.md
View file

@ -33,6 +33,7 @@ It carries forward the lessons from State Hub and Inter-Hub: workplans and progr
## Key Documentation
- [INTENT.md](INTENT.md) - purpose, lineage, principles, and platform direction
- [STATE.md](STATE.md) - current production truth, open work, and known conditions
- [SCOPE.md](SCOPE.md) - repo boundary
- [Research artifact](docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md) - what we learned from State Hub, Inter-Hub, Haskell/IHP, and whynot-design
- [Specs index](docs/specs/README.md) - contract and implementation specification map
@ -40,9 +41,8 @@ It carries forward the lessons from State Hub and Inter-Hub: workplans and progr
## Current Work
The contract, FastAPI/Postgres foundation, Inter-Hub migration, production
cutover, and Haskell/IHP retirement are complete. The immediate continuity
work is to relocate the existing Core Hub service from CoulombCore to
railiance01 before CoulombCore is decommissioned (`CORE-WP-0011`). Future
runtime absorption into hub-core remains a separate architecture proposal
(`CORE-WP-0010`).
The contract, FastAPI/Postgres foundation, Inter-Hub migration, Haskell/IHP
retirement, and relocation from CoulombCore to railiance01 are complete.
`CORE-WP-0011` is finished. The only open local workplan is runtime absorption
and eventual archive (`CORE-WP-0010`); it is blocked on hub-core's runtime
packaging, minimal-port, and joint-plan decisions in `HUB-WP-0004`.

76
STATE.md Normal file
View file

@ -0,0 +1,76 @@
# STATE — core-hub
**Updated:** 2026-08-21
**Domain:** infotech · **Repo:** core-hub · **Owner:** codex
## One-line posture
**Core Hub is the verified production `/api/v2` runtime on railiance01; the
CoulombCore APIs are stopped, and future absorption into hub-core is blocked on
hub-core's still-proposed runtime contract.**
## Production truth
| Surface | Current state |
| --- | --- |
| Public endpoint | `https://hub.coulomb.social` → `92.205.62.239` |
| Runtime | railiance01, Helm revision 4, chart `0.3.2` |
| Package | `rapp-core-hub`, verified and bound to `reef-railiance` |
| Image | Forgejo digest `sha256:0db6f7c646c6d4c1fbc844dc266fcf883584637e1c1f47802efe1c6a98558d3c` |
| Database | railiance01 `platform-pg`, database `core_hub`, schema `core_hub` |
| TLS | Let's Encrypt certificate Ready through 2026-11-18 |
| Consumers | ops-hub gate and activity-core resolver/evidence sink verified |
| Source fallback | CoulombCore production and staging Deployments at zero replicas; source DB read-only |
The relocation and retirement evidence is in
[`docs/evidence/core-hub-railiance01-stabilization-2026-08-21.md`](docs/evidence/core-hub-railiance01-stabilization-2026-08-21.md).
Deployment packaging and rollout truth lives in the `rapp-core-hub` repository.
## Workplans
| Workplan | Status | Result / next gate |
| --- | --- | --- |
| `CORE-WP-0001`–`CORE-WP-0009` | finished / archived | Gen3 runtime, contracts, persistence, consumer gates, and hardening delivered |
| `CORE-WP-0011` | finished | Production relocated to railiance01 and active CoulombCore runtime retired |
| `CORE-WP-0010` | blocked | Runtime absorption and archive wait on `HUB-WP-0004` |
### Open work
| Task | Status | Dependency |
| --- | --- | --- |
| `CORE-WP-0010-T01` inventory | done | Inventory recorded in `docs/specs/runtime-absorption-inventory.md` |
| `CORE-WP-0010-T02` dual-run design | wait | `HUB-WP-0004-T03` runtime packaging and `T06` joint plan |
| `CORE-WP-0010-T03` absorption slices | wait | Approved dual-run design and `HUB-WP-0004-T04` ports |
| `CORE-WP-0010-T04` production cutover | wait | Absorption evidence and operator approval |
| `CORE-WP-0010-T05` archive | wait | Cutover complete and residual ownership recorded |
## Intent position
The operational reset promised by `INTENT.md` is real: the service is small,
containerized, contract-tested, credential-safe, observable, and deployed on
ordinary Kubernetes/PostgreSQL infrastructure. The larger Gen3 product intent
is only partly realized. Core Hub does not yet own the fleet's messaging,
progress/work projections, durable decision/deployment/outcome resources, or a
single extension runtime. Those gaps are not a reason to disturb the healthy
production runtime; they are inputs to the hub-core consolidation decision.
## Verify
```bash
make test
make lint
curl -fsS https://hub.coulomb.social/healthz
curl -fsS https://hub.coulomb.social/readyz
```
## Known conditions
- `CORE-WP-0011` is finished but has no State Hub UUID; the registrar warning is
retained rather than inventing an identifier.
- `.custodian-brief.md` is generated and may lag file-backed workplan truth.
- `make lint` currently reports seven baseline style findings in unchanged
Python files (two import-order findings and five long lines); `make test`
passes all 24 tests.
- The stopped CoulombCore workloads and read-only source database are retained
only as controlled fallback evidence.
- Do not archive this repository before `CORE-WP-0010` completes.

12
WORK-RECORDS.md
View file

@ -15,7 +15,7 @@
| workplan | CORE-WP-0006 | finished | — | workplans/CORE-WP-0006-operator-console-and-whynot-ui.md |
| workplan | CORE-WP-0008 | finished | — | workplans/CORE-WP-0008-api-first-ops-evidence-continuation.md |
| workplan | CORE-WP-0009 | finished | — | workplans/CORE-WP-0009-hub-core-adoption-and-integration.md |
| workplan | CORE-WP-0010 | proposed | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| workplan | CORE-WP-0010 | blocked | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| workplan | CORE-WP-0011 | finished | — | workplans/CORE-WP-0011-railiance01-production-relocation.md |
| task | CORE-WP-0001-T01 | done | — | workplans/CORE-WP-0001-statehub-bootstrap.md |
| task | CORE-WP-0001-T02 | done | — | workplans/CORE-WP-0001-statehub-bootstrap.md |
@ -49,11 +49,11 @@
| task | CORE-WP-0009-T04 | done | — | workplans/CORE-WP-0009-hub-core-adoption-and-integration.md |
| task | CORE-WP-0009-T05 | done | — | workplans/CORE-WP-0009-hub-core-adoption-and-integration.md |
| task | CORE-WP-0009-T06 | done | — | workplans/CORE-WP-0009-hub-core-adoption-and-integration.md |
| task | CORE-WP-0010-T01 | todo | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T02 | todo | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T03 | todo | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T04 | todo | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T05 | todo | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T01 | done | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T02 | wait | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T03 | wait | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T04 | wait | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0010-T05 | wait | — | workplans/CORE-WP-0010-runtime-absorption-and-archive.md |
| task | CORE-WP-0011-T01 | done | — | workplans/CORE-WP-0011-railiance01-production-relocation.md |
| task | CORE-WP-0011-T02 | done | — | workplans/CORE-WP-0011-railiance01-production-relocation.md |
| task | CORE-WP-0011-T03 | done | — | workplans/CORE-WP-0011-railiance01-production-relocation.md |

1
docs/specs/README.md
View file

@ -8,6 +8,7 @@ This directory is the specification map for Core Hub. The specs are intentionall
- [Contract and IR](contract-ir.md) - canonical framework contract, schemas, fixtures, and adapter rules
- [API v2 Compatibility](api-v2-compatibility.md) - Inter-Hub compatibility surface to preserve during transition
- [Inter-Hub Legacy Inventory](interhub-legacy-inventory.md) - initial route/data/consumer inventory for migration
- [Runtime Absorption Inventory](runtime-absorption-inventory.md) - current routes, data, consumers, and ownership that hub-core absorption must preserve
- [Contract Governance](contract-governance.md) - how contract changes are reviewed and recorded
- [Data Model](data-model.md) - initial entity model and migration posture
- [Event and Registry Model](event-and-registry-model.md) - event catalogs, manifests, widgets, and capability registries

103
docs/specs/runtime-absorption-inventory.md Normal file
View file

@ -0,0 +1,103 @@
# Core Hub runtime absorption inventory
**Status:** complete for `CORE-WP-0010-T01`
**Reviewed:** 2026-08-21
This inventory defines the runtime, contract, data, consumer, and deployment
surfaces that a hub-core replacement must preserve. It is an input to the
joint absorption plan in `HUB-WP-0004`; it does not choose hub-core's packaging
or port model.
## Public and operator contract
The checked-in OpenAPI snapshot documents 22 paths:
| Area | Paths / behavior to preserve |
| --- | --- |
| Discovery | `/api/v2/hubs`, `/api/v2/hub-registry`, `/api/v2/manifests`, manifest patch and activation |
| Credentials | `/api/v2/api-consumers`, `/api/v2/api-consumers/{id}/keys`, `/api/v2/token` |
| Interaction | `/api/v2/widgets`, `/api/v2/widget-types`, `/api/v2/interaction-events` |
| Deferred resources | annotation categories/annotations, policy scopes, requirement candidates, decision records, deployment records, outcome signals |
| Operations | `/healthz`, `/readyz`, `/console` |
Compatibility discovery also serves `/api/v2/openapi.json`,
`/api/v2/openapi.yaml`, `/api/v2/docs`, and historical unprefixed aliases.
These must either remain available or have an explicit compatibility gateway.
## Durable data
The production schema contains these application tables:
- `hubs`
- `hub_capability_manifests`
- `api_consumers`
- `api_keys`
- `widgets`
- `interaction_events`
- `migration_runs`
`alembic_version` is migration metadata. Annotation, requirement, decision,
deployment, and outcome routes currently return empty collections and do not
have durable models; absorption must not claim data that does not exist.
## Contract and fixture assets
The `contracts/` tree is portable compatibility evidence and should move with
the runtime or remain versioned as historical fixtures. It includes the
OpenAPI snapshot, JSON schemas, catalogs, and consumer fixtures. Database
migrations and row-count/replay checks remain owned by the runtime migration
slice until hub-core accepts them.
## Consumers and smoke gates
- **ops-hub** depends on protected hub records and the compatibility OpenAPI
paths. Its bootstrap reads or creates hubs, manifests, API consumers, keys,
widgets, and interaction events.
- **activity-core** depends on health/readiness, widget types, protected hub
resolution, and posting then reading back interaction-event evidence.
Both consumer gates must pass against hub-core during dual-run and again after
traffic cutover. Core Hub remains the rollback runtime until those checks and
data comparisons succeed.
## Extension-port mapping
| Gen3 port | Current Core Hub coverage |
| --- | --- |
| Registry | partial: hubs and manifests |
| Addressing | partial: hub identity and protected records |
| Interaction events | partial: durable event sink/readback |
| Projection | partial: operator views and compatibility reads |
| Messaging | absent / external |
| Progress and work | absent / external |
| Repository and schedule | absent / external |
| Telemetry | health/readiness only |
| Policy | names/catalog surface only; authorization remains external |
This mapping prevents a route-for-route move from being mistaken for complete
Gen3 extension absorption.
## Deployment and ownership boundary
- **core-hub** owns application code, contracts, migrations, image contents,
and consumer compatibility evidence.
- **rapp-core-hub** owns Helm values/templates, policy and secret references,
rollout declaration, and live smoke evidence.
- **railiance-platform / rapp-postgres** owns platform PostgreSQL, credential
custody, backups, and restore posture.
The Kubernetes manifests checked into this repository describe the former
CoulombCore deployment and are retained as source/history evidence. They are
not current production deployment truth.
## Move constraints
1. `HUB-WP-0004-T03` must decide whether hub-core ships the primary runtime
image or a library with a permanently owned host.
2. `HUB-WP-0004-T04` must settle the minimal extension ports before absorption
slices are designed.
3. `HUB-WP-0004-T06` and `CORE-WP-0010-T02` must jointly define dual-run,
traffic shift, rollback, and smoke ownership.
4. Every durable slice needs schema/row-count comparison and fixture replay.
5. Repository archive is last: only after public traffic, consumer gates,
residual ownership, and rollback retirement are evidenced.

42
workplans/CORE-WP-0010-runtime-absorption-and-archive.md
View file

@ -4,11 +4,11 @@ type: workplan
title: "Runtime absorption into hub-core and archive"
domain: infotech
repo: core-hub
status: proposed
status: blocked
owner: codex
topic_slug: infotech
created: "2026-08-09"
updated: "2026-08-09"
updated: "2026-08-21"
parent_project: prj-state-hub-retirement
parent_workplan: SHR-WP-0001
related:
@ -34,15 +34,25 @@ Parent project: `prj-state-hub-retirement`. Depends on **HUB-WP-0004**.
The CoulombCore decommission does not force the unresolved hub-core
library-vs-thin-host decision. Production continuity is decoupled through
`CORE-WP-0011`, which moves the existing Core Hub service to railiance01
first. This workplan remains proposed until `HUB-WP-0004` settles the durable
runtime boundary; absorption must not sit on the critical path for leaving
first. The absorption work cannot proceed until `HUB-WP-0004` settles the
durable runtime boundary; it must not sit on the critical path for leaving
CoulombCore.
## Readiness and blocker review — 2026-08-21
`CORE-WP-0011` is finished: production now runs on railiance01 and the active
CoulombCore runtimes are stopped. The runtime surface inventory is complete in
`docs/specs/runtime-absorption-inventory.md`. The remaining work is blocked,
not merely unstarted: `HUB-WP-0004` is still proposed and its runtime packaging
(`T03`), minimal ports (`T04`), and joint absorption plan (`T06`) determine the
shape of every subsequent task here. This workplan can return to `active` when
those decisions are owned and ready for joint execution.
## Inventory runtime surfaces to absorb
```task
id: CORE-WP-0010-T01
status: todo
status: done
priority: high
state_hub_task_id: "ce21c47f-ad66-4cd1-bd8b-c8fb92da3075"
```
@ -51,11 +61,15 @@ List routes, models, widgets, manifests, consumer smokes, and deploy assets that
must move or remain as historical fixtures. Cross-check Inter-Hub inventory and
ops-hub bootstrap.
Completed 2026-08-21. The inventory records public/operator routes, durable
models, fixtures, consumer gates, extension-port coverage, deploy ownership,
and move constraints.
## Dual-run design
```task
id: CORE-WP-0010-T02
status: todo
status: wait
priority: high
state_hub_task_id: "d2679b41-01e9-477c-9d8a-0b1ddc8847cf"
```
@ -64,11 +78,13 @@ Define how hub-core serves equivalent `/api/v2` (or compatible gateway) while
core-hub remains rollback. Include feature flags, traffic shift, and smoke
ownership.
Waiting on `HUB-WP-0004-T03` and `HUB-WP-0004-T06`.
## Execute absorption slices
```task
id: CORE-WP-0010-T03
status: todo
status: wait
priority: high
state_hub_task_id: "c01ddec1-5737-4115-ac73-c402ffb5bdc5"
```
@ -76,11 +92,13 @@ state_hub_task_id: "c01ddec1-5737-4115-ac73-c402ffb5bdc5"
Migrate in slices with consumer smokes (ops-hub, activity-core) after each.
Record row counts and fixture replays per slice.
Waiting on the approved dual-run design and `HUB-WP-0004-T04`.
## Cutover production traffic
```task
id: CORE-WP-0010-T04
status: todo
status: wait
priority: high
state_hub_task_id: "dc414053-a896-4bf0-af05-944b7a7cf750"
```
@ -88,11 +106,13 @@ state_hub_task_id: "dc414053-a896-4bf0-af05-944b7a7cf750"
With operator approval, point production at hub-core runtime; verify consumer
smokes and interaction evidence path.
Waiting on completed absorption evidence and explicit operator approval.
## Archive repository
```task
id: CORE-WP-0010-T05
status: todo
status: wait
priority: medium
state_hub_task_id: "16525001-f85e-4dae-9dc4-d36cb1eb4fbe"
```
@ -100,9 +120,11 @@ state_hub_task_id: "16525001-f85e-4dae-9dc4-d36cb1eb4fbe"
Write completion record (revisions, PRs, residual owners), set read-only archive
on forge, and hand residual work as live records outside this repo.
Waiting on production cutover and recorded residual ownership.
## Acceptance
- [ ] Absorption inventory complete
- [x] Absorption inventory complete
- [ ] Dual-run design approved/recorded
- [ ] Consumer smokes pass on hub-core host
- [ ] Production traffic cut over with evidence