feat: add hub runtime and extension contract

docs/adr/ADR-0001-runtime-packaging.md

@@ -0,0 +1,103 @@
+# 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.