ADR-0001: Ship the primary runtime image from hub-core

Status: Accepted Date: 2026-08-21 Workplan: HUB-WP-0004-T03 Architecture: SHR-ARCH-HUB-0001

Context

Hub-core currently publishes only the importable hub_core Python package. Core-hub supplies the deployable FastAPI application, /api/v2 compatibility, PostgreSQL drivers and migrations, OCI build, health endpoints, and operator surfaces. Its image vendors a hub-core source checkout through a Docker build context, so a production release spans two repositories and two version boundaries.

The State Hub retirement architecture makes hub-core the surviving framework and runtime and archives core-hub after compatibility cutover. We therefore need a durable packaging boundary before implementing ports or designing the dual-run.

Decision

Hub-core will ship the primary HelixForge hub runtime OCI image from this repository. The hub_core Python package remains a supported, independently importable SDK/library surface. Both artifacts share one source revision and release version.

The packaging contract is:

The base wheel keeps reusable models, schemas, router factories, contracts, utilities, and MCP composition importable without starting a service.
Runtime-only dependencies such as the ASGI server, PostgreSQL driver, and migration tooling belong to a declared runtime dependency group/extra and are installed in the image.
Hub-core owns the application factory, health/readiness endpoints, runtime configuration contract, packaged migrations, image definition, and compatibility route composition.
One image may expose separate commands for API serving, MCP serving, and migration jobs. Kubernetes may run those as separate processes or workloads for scaling and privilege isolation; “one primary image” does not require a monolithic process.
Deployment declarations, secret references, rollout policy, and live smoke evidence remain in the rapp/platform repositories. They consume the hub-core image rather than defining a permanent Python host.
Core-hub remains a temporary rollback runtime during dual-run. Its routes, contracts, migrations, and fixtures move in governed slices; hub-core must not retain a steady-state dependency on the core_hub package or repository.
The runtime keeps domain data, Git/work-record authority, authorization decisions, credential custody, and schedule execution behind the ports assigned by SHR-ARCH-HUB-0001.

The initial command names and module layout are implementation details for HUB-WP-0004-T04, but they must provide equivalent surfaces for:

starting the HTTP API;
starting or composing the MCP surface;
running schema migrations without application auto-create in production;
probing liveness and readiness.

Migration constraints

/api/v2 compatibility moves by route/data slice with core-hub retained as rollback until consumer smokes and row/provenance comparisons pass.
Hub-core and core-hub SQLAlchemy metadata remain isolated during dual-run; model/migration absorption is explicit rather than cross-imported.
The wheel and image report the same semantic version and source revision so evidence can identify the exact contract/runtime pair.
Contract fixtures and OpenAPI snapshots move with the implementing slice and remain usable without a live deployment.
Production image coordinates and deployment ownership change only through the joint HUB-WP-0004-T06 / CORE-WP-0010 cutover plan.

Alternatives considered

Keep a permanent thin host repository

Rejected. It preserves two release units, prevents core-hub archival, and makes contract/runtime compatibility a cross-repository pinning problem. A temporary compatibility host during migration is allowed but has an explicit retirement gate.

Publish a second Python runtime distribution

Rejected for the initial consolidation. One distribution with a runtime extra keeps contracts, application composition, and migrations version-aligned. This can be revisited only if dependency or release evidence shows a material need.

Run API and MCP in one mandatory process

Rejected as a packaging requirement. They share the image and contract version, but deployments may separate processes to preserve scaling, failure, and access boundaries.

Consequences

Hub-core gains operational artifact ownership and must test both wheel and image entry surfaces.
Library-only consumers keep an import path without runtime startup.
Core-hub absorption can converge on one release rather than another permanent wrapper.
T04 owns the minimal application/command/image scaffold alongside the core ports; T06 owns dual-run and production transition details.

4.7 KiB Raw Blame History