docs: align absorption plan with hub-core
This commit is contained in:
parent
4a9df801c3
commit
4a2d4fa981
3 changed files with 46 additions and 27 deletions
2
STATE.md
2
STATE.md
|
|
@ -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
|
||||
retained rather than inventing an identifier.
|
||||
- `.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.
|
||||
- `make lint` currently reports seven baseline style findings in unchanged
|
||||
Python files (two import-order findings and five long lines); `make test`
|
||||
|
|
|
|||
|
|
@ -1,14 +1,17 @@
|
|||
# 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
|
||||
**Strategy:** route-group migration with Core Hub retained as rollback; no
|
||||
client dual-write and no big-bang cutover
|
||||
|
||||
This plan turns the inventory in `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.
|
||||
This Core Hub record is aligned with the canonical joint plan at
|
||||
`hub-core/docs/core-hub-absorption-plan.md` and State Hub decision
|
||||
`12514947-6cc0-42a0-98ca-9aacc9d875b0`. It turns the inventory in
|
||||
`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
|
||||
|
||||
|
|
@ -34,6 +37,16 @@ passes its own data, contract, consumer, and rollback gates.
|
|||
7. **Archive last.** Core Hub stays deployable until the final stabilization
|
||||
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
|
||||
|
||||
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;
|
||||
- `rapp-core-hub` can deploy a second, cluster-internal candidate without
|
||||
changing `hub.coulomb.social`;
|
||||
- hub-core has a production PostgreSQL `PortStore`/compatibility store and
|
||||
fails readiness when durable storage is unavailable;
|
||||
- hub-core has a production PostgreSQL `PortStore`/compatibility store, audit
|
||||
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 candidate without exposing credential values;
|
||||
- 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 |
|
||||
| --- | --- | --- | --- |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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
|
||||
creates records whose identifiers cross hubs, manifests, consumers, keys, and
|
||||
widgets; splitting those calls across two authorities would manufacture
|
||||
referential drift. Its code and data migration may still land in smaller
|
||||
reviewable commits before the route group switches.
|
||||
Related calls within a slice move as one traffic group. In particular, public
|
||||
traffic must not mix old and new authorities inside registry, credential, or
|
||||
widget/interaction workflows whose identifiers cross resource boundaries.
|
||||
|
||||
## Compatibility adapters
|
||||
|
||||
|
|
@ -115,9 +128,12 @@ credentials, Authorization headers, or copied Kubernetes Secrets.
|
|||
|
||||
## Traffic controls and rollback
|
||||
|
||||
`rapp-core-hub` owns one logical switch per slice with the states `source`,
|
||||
`shadow-read`, and `target`. The concrete gateway or Helm key names are a
|
||||
deployment implementation detail, but every rendered release must reveal the
|
||||
`rapp-core-hub` owns one logical switch per slice with the states `legacy`,
|
||||
`shadow`, and `candidate`, plus independently observable legacy/candidate
|
||||
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.
|
||||
|
||||
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 |
|
||||
| ops-hub | bootstrap and registry consumer 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
|
||||
|
||||
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
|
||||
legacy auth/health compatibility in hub-core, plus a candidate deployment mode
|
||||
in `rapp-core-hub`. It must not change public DNS or ingress.
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
and initial conformance harness now exist. The paired design is recorded in
|
||||
`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
|
||||
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
|
||||
route-group order, one-writer rule, data/delta checks, compatibility adapters,
|
||||
consumer gates, traffic controls, rollback, evidence, and ownership. Hub-core
|
||||
must link the joint plan to close `HUB-WP-0004-T06`.
|
||||
consumer gates, traffic controls, rollback, evidence, and ownership. It is
|
||||
aligned with hub-core's accepted canonical plan; `HUB-WP-0004-T06` is done.
|
||||
|
||||
## Execute absorption slices
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue