diff --git a/INTENT.md b/INTENT.md index 9623dac..4cd2c51 100644 --- a/INTENT.md +++ b/INTENT.md @@ -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. diff --git a/README.md b/README.md index 71b9e11..4955116 100644 --- a/README.md +++ b/README.md @@ -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`. diff --git a/STATE.md b/STATE.md new file mode 100644 index 0000000..69ab650 --- /dev/null +++ b/STATE.md @@ -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. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index d80ec7a..4054652 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -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 | diff --git a/docs/specs/README.md b/docs/specs/README.md index 2525204..3a14e09 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -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 diff --git a/docs/specs/runtime-absorption-inventory.md b/docs/specs/runtime-absorption-inventory.md new file mode 100644 index 0000000..0db1a37 --- /dev/null +++ b/docs/specs/runtime-absorption-inventory.md @@ -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. diff --git a/workplans/CORE-WP-0010-runtime-absorption-and-archive.md b/workplans/CORE-WP-0010-runtime-absorption-and-archive.md index 5ae695f..d75aca4 100644 --- a/workplans/CORE-WP-0010-runtime-absorption-and-archive.md +++ b/workplans/CORE-WP-0010-runtime-absorption-and-archive.md @@ -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