hub-core/workplans/HUB-WP-0004-runtime-and-extension-contract.md

---
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