265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
---
|
|
id: HUB-WP-0004
|
|
type: workplan
|
|
title: "Runtime consolidation and extension contract"
|
|
domain: infotech
|
|
repo: hub-core
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: custodian
|
|
created: "2026-08-09"
|
|
updated: "2026-08-21"
|
|
parent_project: prj-state-hub-retirement
|
|
parent_workplan: SHR-WP-0001
|
|
related:
|
|
- HUB-WP-0003
|
|
- CORE-WP-0010
|
|
- SHR-ARCH-HUB-0001
|
|
- SHR-ARCH-IA-0001
|
|
state_hub_workstream_id: "4a17907c-7382-453b-92a0-5f770ab4877f"
|
|
---
|
|
|
|
# Runtime consolidation and extension contract
|
|
|
|
## Goal
|
|
|
|
Evolve hub-core from library-only into the **surviving HelixForge hub framework
|
|
and runtime**, shipping `helixforge.hub-extension` Tier 1 artefacts and a clear
|
|
path to absorb core-hub production traffic.
|
|
|
|
Coordinated by `prj-state-hub-retirement` (SHR-WP-0001). Architecture:
|
|
`prj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.md`
|
|
(the path is project-relative; hub-core has no `architecture/` directory).
|
|
|
|
## Adopt project architecture freeze
|
|
|
|
```task
|
|
id: HUB-WP-0004-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "47b879ac-bfb4-48c2-8fd8-c29045df6900"
|
|
```
|
|
|
|
Review and accept SHR-ARCH-IA-0001 and SHR-ARCH-HUB-0001 as the vocabulary for
|
|
ports, kinds, and extension packages. Record gaps as tasks, not silent drift.
|
|
|
|
Completed 2026-08-21. Hub-core accepts the two project artefacts as the
|
|
normative v0.1 vocabulary for this workplan:
|
|
|
|
- authority and projection remain distinct; repository work stays authoritative
|
|
in Git and is reached through repo-manager;
|
|
- messages/conversations, progress events, interaction events, telemetry, and
|
|
domain events remain distinct information families joined by correlation;
|
|
- hub-core is the surviving framework/runtime and owns the named `port.*`
|
|
contracts, while domain hubs, functional components, and authoritative
|
|
services retain the boundaries defined by `SHR-ARCH-HUB-0001`;
|
|
- `helixforge.hub-extension` descriptors, manifests, event catalogs, fixtures,
|
|
and compatibility rules are the Tier 1 contract target.
|
|
|
|
The accepted freeze is reflected in `INTENT.md` and `SCOPE.md`. Open questions
|
|
are assigned rather than silently deferred:
|
|
|
|
| Gap / decision | Owning task |
|
|
| --- | --- |
|
|
| Descriptor, manifest authority, widgets/operator surfaces | T02 |
|
|
| Primary image vs permanent thin host; MCP packaging | T03 |
|
|
| Named port implementations, conversation support, missing interaction/projection surfaces | T04 |
|
|
| Tenant isolation and Tier 2/3 enforcement | T05 |
|
|
| Topic/work boundary and `/api/v2` migration order | T06 with CORE-WP-0010 |
|
|
|
|
## Ship extension contract Tier 1 artefacts
|
|
|
|
```task
|
|
id: HUB-WP-0004-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "eac82a0b-48b9-4097-afa6-a9e730de7789"
|
|
```
|
|
|
|
Publish versioned hub descriptor schema, manifest schema, event-type catalog
|
|
schema, and port OpenAPI fragments for `helixforge.hub-extension` 0.1+, plus a
|
|
sample hub fixture. Align with `hub-extension-contract_v0.1.yaml`.
|
|
|
|
Completed 2026-08-21. The wheel now packages
|
|
`hub_core.contracts.helixforge_hub_extension.v0_1_0` with:
|
|
|
|
- Draft 2020-12 hub descriptor, manifest, and event-type catalog schemas;
|
|
- OpenAPI 3.1 fragments covering all 11 named `port.*` interfaces;
|
|
- an initial four-family event catalog and non-secret ops-hub fixture;
|
|
- an explicit 0.1.0 compatibility matrix, including the temporary Core Hub
|
|
manifest adapter; and
|
|
- automated schema, catalog, fixture, port-coverage, compatibility, and
|
|
secret-field checks in `tests/test_contracts.py`.
|
|
|
|
Focused validation passed (8 tests), and a built `hub_core-0.2.0` wheel was
|
|
inspected to confirm every contract artefact is shipped.
|
|
|
|
## Define runtime packaging decision
|
|
|
|
```task
|
|
id: HUB-WP-0004-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "f149096d-74f2-4c5a-8907-f81cba8e3edb"
|
|
```
|
|
|
|
Record whether hub-core ships a primary runtime image (recommended) with the
|
|
library remaining importable, vs library + permanent thin host. Decision before
|
|
absorbing core-hub routes.
|
|
|
|
Completed 2026-08-21. `docs/adr/ADR-0001-runtime-packaging.md` selects one
|
|
hub-core release lineage with an importable Python wheel and a primary runtime
|
|
OCI image built from this repository. API, MCP, and migration jobs may be
|
|
separate processes from that image. A permanent thin-host repository is
|
|
rejected; core-hub remains only as the dual-run rollback runtime until its
|
|
routes, data, contracts, and fixtures are absorbed.
|
|
|
|
## Implement core ports (minimal vertical)
|
|
|
|
```task
|
|
id: HUB-WP-0004-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "fa4db2f7-0e86-4a41-8469-a8704d9c2a46"
|
|
```
|
|
|
|
Expose minimal working surfaces for `port.registry`, `port.messaging`,
|
|
`port.events.progress`, `port.events.interaction`, and `port.projection.query`
|
|
sufficient for dual-run and conformance scaffolding.
|
|
|
|
Implement the minimal application factory, runtime dependency group, process
|
|
commands, health/readiness surface, and primary image scaffold selected by
|
|
ADR-0001 alongside these ports.
|
|
|
|
Completed 2026-08-21. `hub_core.runtime` now provides an injectable FastAPI
|
|
application and `PortStore` boundary with a deterministic in-memory conformance
|
|
backend. The vertical implements contract-valid, idempotent registry writes;
|
|
addressed messages/conversations; catalog-enforced and physically separate
|
|
progress and interaction event sinks; and provenance-bearing projections.
|
|
|
|
The `hub-core` console entrypoint starts API and MCP processes or packaged
|
|
Alembic migrations. The runtime extra is locked in `uv.lock`. `Containerfile`
|
|
builds that frozen dependency set, runs as UID/GID 10001, labels version and
|
|
revision, and defaults to fail-closed readiness while only the ephemeral store
|
|
exists. `docs/runtime.md` records the boundary and commands.
|
|
|
|
Validation evidence:
|
|
|
|
- focused contract/runtime tests pass;
|
|
- local API and MCP process smokes pass;
|
|
- packaged migration head resolves as `0001_core_schema`;
|
|
- the locked OCI image builds and passes health, opted-in readiness, and
|
|
ops-hub contract registration; and
|
|
- production-mode memory readiness returns 503 unless explicitly allowed.
|
|
|
|
## Conformance harness scaffold
|
|
|
|
```task
|
|
id: HUB-WP-0004-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "6f8fb0e8-8b9b-4c37-ae62-0748dd0e5975"
|
|
```
|
|
|
|
Scaffold Tier 2/3 automated checks (schema validate, no-secrets, event family
|
|
separation, projection rebuild fixture). Full green suite may continue under
|
|
follow-on WPs.
|
|
|
|
Completed 2026-08-21. `hub_core.conformance` now drives a public HTTP target
|
|
through an implementation-neutral client protocol. The initial green profile
|
|
automates Tier 2 checks C1, C3, C4, C5, C6, and C8 plus Tier 3 checks F2 and F3.
|
|
It validates the packaged schemas and catalog, rejects secret-shaped fixture
|
|
material, exercises health and idempotent activation with correlation
|
|
propagation, rejects wrong-family/uncataloged events, proves family separation,
|
|
and verifies authority-derived projections with rebuild-source declarations and
|
|
provenance hashes.
|
|
|
|
The wheel ships `fixtures/projection-rebuild.json`; `hub-core conformance`
|
|
supports human-readable or JSON results against an isolated remote runtime.
|
|
`docs/conformance.md` explicitly records uncovered requirements and tenant
|
|
isolation as open rather than treating absent checks as passing. The reference
|
|
runtime passes all eight implemented checks over a live HTTP process.
|
|
|
|
## Absorption plan with core-hub
|
|
|
|
```task
|
|
id: HUB-WP-0004-T06
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "b35fff11-ac5a-4d70-9f54-416331baea87"
|
|
```
|
|
|
|
With CORE-WP-0010, document route/module move order for `/api/v2`, dual-run, and
|
|
cutover criteria. No big-bang.
|
|
|
|
Completed 2026-08-21. `docs/core-hub-absorption-plan.md` reconciles Core Hub's
|
|
finished runtime inventory, its current railiance01 production/rollback state,
|
|
all 22 checked-in OpenAPI paths, seven durable tables, both production
|
|
consumers, and the project retirement gates.
|
|
|
|
The accepted plan uses six governed capability slices after a durable-runtime
|
|
foundation. It requires isolated legacy/candidate schemas, exactly one writer
|
|
per route group, read-only shadow comparison, per-slice count/hash/provenance
|
|
and authorization evidence, ops-hub and activity-core smokes, reverse-delta
|
|
rollback rehearsal, explicit operator approval for production writer changes,
|
|
and a seven-day final stabilization window before Core Hub retirement. The
|
|
compatibility credential shim and empty collection adapters receive explicit
|
|
residual gates rather than becoming silent permanent authorities.
|
|
|
|
State Hub decision `12514947-6cc0-42a0-98ca-9aacc9d875b0` records the
|
|
single-writer slice design. Message `819d5af0-959f-4b0d-9f52-87514d99b480`
|
|
hands the plan to `core-hub` for the file-backed CORE-WP-0010-T02 transition.
|
|
|
|
## Readiness review (2026-08-20)
|
|
|
|
Reviewed against current repo state at the request of `STATE-WP-0079`, which is
|
|
blocked on this plan. **Nothing structurally prevents `ready`** — the plan has
|
|
sat at `proposed` since it was drafted on 2026-08-09 without a review, rather
|
|
than because it is blocked.
|
|
|
|
**Why this matters now.** Wave B of the State Hub cutover slice plan
|
|
(`state-hub/docs/retirement-cutover-slice-plan.md`) is **125 inventory items**
|
|
across catalogs, messaging, telemetry, projections and hub UI, and none of it
|
|
can start until this plan leaves `proposed`. It is currently the single largest
|
|
gate in the retirement program.
|
|
|
|
**Referenced artefacts all exist** in `prj-state-hub-retirement/architecture/`:
|
|
|
|
| Artefact | ID |
|
|
| --- | --- |
|
|
| `information-model_v0.1.md` | SHR-ARCH-IA-0001 |
|
|
| `hub-extension-architecture_v0.1.md` | SHR-ARCH-HUB-0001 |
|
|
| `hub-extension-contract_v0.1.yaml` | — (T02 input) |
|
|
| `retirement-gates_v0.1.md` | gate definitions |
|
|
|
|
**Current hub-core surface**, relevant to T04's minimal vertical:
|
|
|
|
| Requested port | Plausible existing basis |
|
|
| --- | --- |
|
|
| `port.registry` | `routers/repos.py`, `routers/domains.py`, `routers/capabilities.py` |
|
|
| `port.messaging` | `routers/messages.py` |
|
|
| `port.events.progress` | `routers/progress.py` |
|
|
| `port.events.interaction` | none obvious |
|
|
| `port.projection.query` | none obvious |
|
|
|
|
Mapping needs owner confirmation — `port.*` appears nowhere in hub-core outside
|
|
this workplan, so the vocabulary has not landed yet. That is T01's job, and T01
|
|
is a review task with its inputs already available, so it can start immediately.
|
|
|
|
**Suggested sequencing:** T01 (inputs ready) → T03 (packaging decision, unblocks
|
|
T04's shape) → T02 and T04 in parallel → T05 → T06 with CORE-WP-0010.
|
|
|
|
Two of the five ports have no existing basis, so T04's "minimal vertical" is
|
|
partly greenfield; worth sizing before committing to it.
|
|
|
|
*Review by Claude Code from the state-hub session; status left at `proposed` for
|
|
the owner to flip.*
|
|
|
|
## Acceptance
|
|
|
|
- [x] Architecture freeze acknowledged in INTENT/SCOPE
|
|
- [x] Tier 1 contract artefacts published and versioned
|
|
- [x] Runtime packaging decision recorded
|
|
- [x] Core ports have a minimal implementable surface
|
|
- [x] Conformance harness scaffold exists
|
|
- [x] Absorption plan linked to CORE-WP-0010
|