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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	parent_project	parent_workplan	related	state_hub_workstream_id
HUB-WP-0004	workplan	Runtime consolidation and extension contract	infotech	hub-core	finished	codex	custodian	2026-08-09	2026-08-21	prj-state-hub-retirement	SHR-WP-0001	HUB-WP-0003 CORE-WP-0010 SHR-ARCH-HUB-0001 SHR-ARCH-IA-0001	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

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

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

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)

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

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

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

• 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