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

# 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:
`architecture/hub-extension-architecture_v0.1.md`.

## Adopt project architecture freeze

```task
id: HUB-WP-0004-T01
status: todo
priority: high
```

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

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

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

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

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

With CORE-WP-0010, document route/module move order for `/api/v2`, dual-run, and
cutover criteria. No big-bang.

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