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