103 lines
4.7 KiB
Markdown
103 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
1. The base wheel keeps reusable models, schemas, router factories, contracts,
|
|
utilities, and MCP composition importable without starting a service.
|
|
2. 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.
|
|
3. Hub-core owns the application factory, health/readiness endpoints, runtime
|
|
configuration contract, packaged migrations, image definition, and
|
|
compatibility route composition.
|
|
4. 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.
|
|
5. 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.
|
|
6. 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.
|
|
7. 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.
|