From 4a2d4fa98110331c09c8294c839b2b6a79ea128b Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 21 Aug 2026 10:59:39 +0200 Subject: [PATCH] docs: align absorption plan with hub-core --- STATE.md | 2 +- docs/specs/runtime-absorption-plan.md | 62 ++++++++++++------- ...-WP-0010-runtime-absorption-and-archive.md | 9 ++- 3 files changed, 46 insertions(+), 27 deletions(-) diff --git a/STATE.md b/STATE.md index 60f8198..2542e59 100644 --- a/STATE.md +++ b/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` diff --git a/docs/specs/runtime-absorption-plan.md b/docs/specs/runtime-absorption-plan.md index 8324f7b..bc8d031 100644 --- a/docs/specs/runtime-absorption-plan.md +++ b/docs/specs/runtime-absorption-plan.md @@ -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. diff --git a/workplans/CORE-WP-0010-runtime-absorption-and-archive.md b/workplans/CORE-WP-0010-runtime-absorption-and-archive.md index bdccc51..f6e4859 100644 --- a/workplans/CORE-WP-0010-runtime-absorption-and-archive.md +++ b/workplans/CORE-WP-0010-runtime-absorption-and-archive.md @@ -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