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

docs: align absorption plan with hub-core
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 3s
Details

Browse source
This commit is contained in:
tegwick 2026-08-21 10:59:39 +02:00
parent 4a9df801c3
commit 4a2d4fa981
3 changed files with 46 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

2
STATE.md
View file

@ -68,7 +68,7 @@ curl -fsS https://hub.coulomb.social/readyz
- `CORE-WP-0011` is finished but has no State Hub UUID; the registrar warning is - `CORE-WP-0011` is finished but has no State Hub UUID; the registrar warning is
retained rather than inventing an identifier. retained rather than inventing an identifier.
- `.custodian-brief.md` is generated and may lag file-backed workplan truth. - `.custodian-brief.md` is generated and may lag file-backed workplan truth.
- Hub-core T01–T05 are complete in its workplan and State Hub, but Slice 0 must - Hub-core T01–T06 are complete in its workplan and State Hub, but Slice 0 must
pin a committed source revision and immutable image before implementation. pin a committed source revision and immutable image before implementation.
- `make lint` currently reports seven baseline style findings in unchanged - `make lint` currently reports seven baseline style findings in unchanged
Python files (two import-order findings and five long lines); `make test` Python files (two import-order findings and five long lines); `make test`

62
docs/specs/runtime-absorption-plan.md
View file

@ -1,14 +1,17 @@
# Core Hub to hub-core absorption plan # Core Hub to hub-core absorption plan
**Status:** recorded for `CORE-WP-0010-T02`; joint artifact for `HUB-WP-0004-T06` **Status:** accepted for `CORE-WP-0010-T02` / `HUB-WP-0004-T06`
**Reviewed:** 2026-08-21 **Reviewed:** 2026-08-21
**Strategy:** route-group migration with Core Hub retained as rollback; no **Strategy:** route-group migration with Core Hub retained as rollback; no
client dual-write and no big-bang cutover client dual-write and no big-bang cutover
This plan turns the inventory in `runtime-absorption-inventory.md` into ordered, This Core Hub record is aligned with the canonical joint plan at
testable migration slices. Hub-core owns the surviving runtime selected by its `hub-core/docs/core-hub-absorption-plan.md` and State Hub decision
ADR-0001. Core Hub remains the public `/api/v2` authority until each route group `12514947-6cc0-42a0-98ca-9aacc9d875b0`. It turns the inventory in
passes its own data, contract, consumer, and rollback gates. `runtime-absorption-inventory.md` into ordered, testable migration slices.
Hub-core owns the surviving runtime selected by its ADR-0001. Core Hub remains
the public `/api/v2` authority until each route group passes its own data,
contract, consumer, and rollback gates.
## Decisions ## Decisions
@ -34,6 +37,16 @@ passes its own data, contract, consumer, and rollback gates.
7. **Archive last.** Core Hub stays deployable until the final stabilization 7. **Archive last.** Core Hub stays deployable until the final stabilization
gate, reverse-delta requirement, and residual ownership record are closed. gate, reverse-delta requirement, and residual ownership record are closed.
## Runtime and database shape
The candidate uses a distinct hub-core-owned schema, provisionally
`hub_runtime`, beside retained legacy schema `core_hub` in the existing
platform PostgreSQL allocation. This does not consume another application
database slot. The target adds its own audit ledger and migration lineage;
Core Hub models and migrations are not imported. Deployment remains owned by
`rapp-core-hub` during dual-run, with final package naming/ownership recorded
before this repository is archived.
## Entry gates ## Entry gates
Absorption implementation does not begin until all of these are evidenced: Absorption implementation does not begin until all of these are evidenced:
@ -42,8 +55,9 @@ Absorption implementation does not begin until all of these are evidenced:
- a hub-core wheel and OCI image identify the same revision and version; - a hub-core wheel and OCI image identify the same revision and version;
- `rapp-core-hub` can deploy a second, cluster-internal candidate without - `rapp-core-hub` can deploy a second, cluster-internal candidate without
changing `hub.coulomb.social`; changing `hub.coulomb.social`;
- hub-core has a production PostgreSQL `PortStore`/compatibility store and - hub-core has a production PostgreSQL `PortStore`/compatibility store, audit
fails readiness when durable storage is unavailable; ledger, and migrations, and fails readiness when durable storage or its
authorization dependency is unavailable;
- the existing operator token and copied API-key hashes authenticate through - the existing operator token and copied API-key hashes authenticate through
the candidate without exposing credential values; the candidate without exposing credential values;
- Core Hub export, hub-core import, row-count, canonical-digest, and delta - Core Hub export, hub-core import, row-count, canonical-digest, and delta
@ -59,18 +73,17 @@ gate and must not be bypassed.
| Slice | Surface | Move condition | Consumer gate | | Slice | Surface | Move condition | Consumer gate |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| 0 — candidate foundation | image, API/MCP processes, migrations, durable store, auth adapter, health/readiness | All entry gates above; no public route | hub-core conformance plus Core Hub contract suite | | S0 — candidate foundation | image, API/MCP processes, migrations, durable store/audit, auth adapter, group controls, health/readiness | All entry gates above; all seven source tables representable; no public route | hub-core conformance plus Core Hub contract suite |
| 1 — stateless compatibility | widget/event/annotation/policy catalogs; empty annotation, requirement, decision, deployment, and outcome collections; compatibility OpenAPI/docs | Response status, headers, and canonical JSON match; unprefixed OpenAPI aliases retained | unauthenticated catalog and OpenAPI probes | | S1 — system/discovery | health/readiness; widget/event/annotation/policy catalogs; compatibility OpenAPI/docs and aliases | Response status, headers, and canonical JSON match; dependency-aware readiness | public probes, ops-hub public gate, activity-core resolver |
| 2 — protected bootstrap | hubs, capability manifests and activation, API consumers/key issuance, widgets, hub registry | IDs/FKs preserved; source and target counts/digests match; copied key hashes authenticate; isolated create/read fixture passes | complete ops-hub bootstrap/gate probe | | S2 — registry/manifests | hubs, capability manifests/activation, hub registry | IDs and legacy serialization preserved; counts/digests match; activation audited | ops-hub can resolve/update its manifest; reverse delta proven |
| 3 — interaction evidence | interaction-event append/list and mapping to `port.events.interaction` | Historical IDs/timestamps retained; adapter mapping is reversible; append/readback fixture passes | activity-core resolver and evidence-sink probe | | S3 — consumers/credentials | API consumers, key issuance, `/token` | Hashes/prefixes only; auth deny cases and custody separation pass; rate/quota residual explicit | existing ops-hub and activity-core credentials; reverse key-hash delta proven |
| 4 — operator surface | `/console`, readiness summary, compatibility redirects and remaining aliases | Console reads target projections; no source-only API calls remain | operator CLI, protected console, visual smoke | | S4 — widgets/interaction | widgets; interaction-event append/list mapped to `port.events.interaction` | Historical IDs/timestamps retained; event families remain separate; projection/reverse replay pass | ops-hub and activity-core correlated append/readback |
| 5 — public authority | all `/api/v2`, health/readiness, API/MCP entrypoints | Earlier slices stable; rollback and residual-owner evidence current | ops-hub and activity-core gates together | | S5 — deferred/console | empty annotation, requirement, decision, deployment and outcome collections; `/console` | Exact empty/error behavior; residual disposition per collection; console has no source-schema reads | operator CLI, protected console, visual smoke |
| S6 — whole-host authority | all `/api/v2`, API/MCP entrypoints and remaining traffic | Final backup/delta has zero unexplained drift; operator approves; seven consecutive stable days before retirement | hub-core conformance and Core Hub, ops-hub, activity-core gates together |
Slice 2 is intentionally atomic at the traffic boundary. The ops-hub bootstrap Related calls within a slice move as one traffic group. In particular, public
creates records whose identifiers cross hubs, manifests, consumers, keys, and traffic must not mix old and new authorities inside registry, credential, or
widgets; splitting those calls across two authorities would manufacture widget/interaction workflows whose identifiers cross resource boundaries.
referential drift. Its code and data migration may still land in smaller
reviewable commits before the route group switches.
## Compatibility adapters ## Compatibility adapters
@ -115,9 +128,12 @@ credentials, Authorization headers, or copied Kubernetes Secrets.
## Traffic controls and rollback ## Traffic controls and rollback
`rapp-core-hub` owns one logical switch per slice with the states `source`, `rapp-core-hub` owns one logical switch per slice with the states `legacy`,
`shadow-read`, and `target`. The concrete gateway or Helm key names are a `shadow`, and `candidate`, plus independently observable legacy/candidate
deployment implementation detail, but every rendered release must reveal the write-group sets. The concrete carrier may use the joint plan's
`HUB_CORE_V2_GROUPS`, `HUB_CORE_V2_WRITE_GROUPS`, and
`CORE_HUB_V2_WRITE_GROUPS` or equivalent Helm values. Configuration must
reject overlapping writer sets, and every rendered release must reveal the
selected state as non-secret evidence. selected state as non-secret evidence.
Rollback remains possible while a slice is target-owned: Rollback remains possible while a slice is target-owned:
@ -158,11 +174,11 @@ keeps public authority on Core Hub.
| railiance-platform / rapp-postgres | PostgreSQL, credential delivery, backup/restore readiness | | railiance-platform / rapp-postgres | PostgreSQL, credential delivery, backup/restore readiness |
| ops-hub | bootstrap and registry consumer gate | | ops-hub | bootstrap and registry consumer gate |
| activity-core | interaction resolver, append, and readback gate | | activity-core | interaction resolver, append, and readback gate |
| operator | approval for Slice 5 public-authority cutover and later repository archive | | operator | approval for every production writer change, S6 public authority, and later repository archive |
## Next executable work ## Next executable work
After hub-core publishes its completed T01–T05 revision, start Slice 0. The After hub-core publishes its completed T01–T06 revision, start S0. The
first implementation commit should add the durable PostgreSQL boundary and first implementation commit should add the durable PostgreSQL boundary and
legacy auth/health compatibility in hub-core, plus a candidate deployment mode legacy auth/health compatibility in hub-core, plus a candidate deployment mode
in `rapp-core-hub`. It must not change public DNS or ingress. in `rapp-core-hub`. It must not change public DNS or ingress.

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

@ -52,7 +52,10 @@ Hub-core has completed `HUB-WP-0004-T01`–`T05` in its file-backed workplan and
State Hub: the primary-image decision, Tier 1 contracts, minimal port runtime, State Hub: the primary-image decision, Tier 1 contracts, minimal port runtime,
and initial conformance harness now exist. The paired design is recorded in and initial conformance harness now exist. The paired design is recorded in
`docs/specs/runtime-absorption-plan.md`, completing this workplan's T02 input `docs/specs/runtime-absorption-plan.md`, completing this workplan's T02 input
and the Core Hub half of `HUB-WP-0004-T06`. and the Core Hub half of `HUB-WP-0004-T06`. Hub-core then completed T06 with
the canonical joint record in `hub-core/docs/core-hub-absorption-plan.md`,
decision `12514947-6cc0-42a0-98ca-9aacc9d875b0`, and coordination message
`819d5af0-959f-4b0d-9f52-87514d99b480`.
Execution remains blocked on publishing the completed hub-core work at an Execution remains blocked on publishing the completed hub-core work at an
immutable source/image revision and replacing its deliberately ephemeral immutable source/image revision and replacing its deliberately ephemeral
@ -91,8 +94,8 @@ ownership.
Completed 2026-08-21. `docs/specs/runtime-absorption-plan.md` defines the Completed 2026-08-21. `docs/specs/runtime-absorption-plan.md` defines the
route-group order, one-writer rule, data/delta checks, compatibility adapters, route-group order, one-writer rule, data/delta checks, compatibility adapters,
consumer gates, traffic controls, rollback, evidence, and ownership. Hub-core consumer gates, traffic controls, rollback, evidence, and ownership. It is
must link the joint plan to close `HUB-WP-0004-T06`. aligned with hub-core's accepted canonical plan; `HUB-WP-0004-T06` is done.
## Execute absorption slices ## Execute absorption slices