tegwick
9c1fdd8a4c
STATE-WP-0079 is blocked on this plan: Wave B of the State Hub cutover slice plan is 125 inventory items and none can start while this sits at proposed. It is currently the largest single gate in the retirement program. Reviewed against current repo state -- nothing structurally prevents ready. The plan has been unreviewed since 2026-08-09 rather than blocked. All referenced architecture artefacts exist in prj-state-hub-retirement, and T01 is a review task whose inputs are available, so it can start immediately. Fixes the architecture citation: the path is project-relative, but reads as hub-core-relative and hub-core has no architecture/ directory. Records that port.* appears nowhere in hub-core outside this workplan, and that two of T04's five ports have no existing basis -- the minimal vertical is partly greenfield and worth sizing first. Status left at proposed for the owner to flip. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
---
|
|
id: HUB-WP-0004
|
|
type: workplan
|
|
title: "Runtime consolidation and extension contract"
|
|
domain: infotech
|
|
repo: hub-core
|
|
status: proposed
|
|
owner: codex
|
|
topic_slug: infotech
|
|
created: "2026-08-09"
|
|
updated: "2026-08-20"
|
|
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: todo
|
|
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.
|
|
|
|
## Ship extension contract Tier 1 artefacts
|
|
|
|
```task
|
|
id: HUB-WP-0004-T02
|
|
status: todo
|
|
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`.
|
|
|
|
## Define runtime packaging decision
|
|
|
|
```task
|
|
id: HUB-WP-0004-T03
|
|
status: todo
|
|
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.
|
|
|
|
## Implement core ports (minimal vertical)
|
|
|
|
```task
|
|
id: HUB-WP-0004-T04
|
|
status: todo
|
|
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.
|
|
|
|
## Conformance harness scaffold
|
|
|
|
```task
|
|
id: HUB-WP-0004-T05
|
|
status: todo
|
|
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.
|
|
|
|
## Absorption plan with core-hub
|
|
|
|
```task
|
|
id: HUB-WP-0004-T06
|
|
status: todo
|
|
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.
|
|
|
|
## 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
|
|
|
|
- [ ] Architecture freeze acknowledged in INTENT/SCOPE
|
|
- [ ] Tier 1 contract artefacts published and versioned
|
|
- [ ] Runtime packaging decision recorded
|
|
- [ ] Core ports have a minimal implementable surface
|
|
- [ ] Conformance harness scaffold exists
|
|
- [ ] Absorption plan linked to CORE-WP-0010
|