feat: add hub runtime and extension contract

README.md

@@ -1,17 +1,23 @@
 # Hub Core
 
-Reusable FastAPI, SQLAlchemy, and MCP primitives for FOS hubs.
+Contracts, reusable Python primitives, and the surviving runtime for
+HelixForge hubs.
 
 ## Hub stack glossary
 
 | Name | Role |
 | --- | --- |
-| **hub-core** | This repo — shared Python library (`hub_core`) |
-| **state-hub** | Dev coordination host (workplans, MCP) |
-| **core-hub** | Production framework (`/api/v2`, operator console) |
+| **hub-core** | This repo — importable package plus target primary runtime image |
+| **state-hub** | Legacy coordination host being replaced capability by capability |
+| **core-hub** | Current `/api/v2` runtime retained temporarily for absorption rollback |
 
 Ecosystem architecture: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`
 
+Runtime packaging is fixed by `docs/adr/ADR-0001-runtime-packaging.md`: the
+wheel remains importable, while this repository will also own the primary OCI
+image. API, MCP, and migration workloads may run separately from that same
+image. Core-hub is not a permanent thin host.
+
 `hub-core` is being extracted from the standalone State Hub repository as part
 of `CUST-WP-0025`. The initial package slice contains only the generic database
 models and schemas that can move without importing dev-hub concepts such as
@@ -23,6 +29,45 @@ Source boundary notes live in:
 /home/worsch/the-custodian/docs/hub-core-extraction-boundary.md
 ```
 
+## Extension contract
+
+The wheel includes `helixforge.hub-extension` 0.1.0 under
+`hub_core.contracts`. Use `extension_contract_root()` to locate the packaged
+descriptor and manifest schemas, event catalog schema and seed, named-port
+OpenAPI fragments, ops-hub fixture, and compatibility matrix.
+
+```python
+from hub_core.contracts import CONTRACT_VERSION, extension_contract_root
+
+contract_root = extension_contract_root()
+```
+
+## Runtime scaffold
+
+Install the runtime extra and start the API, MCP, or migration process through
+the shared console entrypoint:
+
+```bash
+uv sync --extra runtime
+hub-core api
+hub-core mcp --api-base http://127.0.0.1:8010
+hub-core migrate head --database-url postgresql+asyncpg://...
+```
+
+The initial runtime exposes registry, messaging, progress-event,
+interaction-event, and projection-query ports. Its included memory backend is
+for local/conformance use and fails production readiness unless explicitly
+enabled. See `docs/runtime.md`.
+
+The reusable Tier 2/3 scaffold is documented in `docs/conformance.md` and runs
+against any compatible HTTP target with
+`hub-core conformance --base-url <url>`.
+
+The staged Core Hub transition is defined in
+`docs/core-hub-absorption-plan.md`; it keeps one writer per capability and
+retains Core Hub as rollback until data, consumer, and stabilization gates
+close.
+
 ## First Slice
 
 - SQLAlchemy base metadata and timestamp helpers.
@@ -42,5 +87,9 @@ Source boundary notes live in:
 - Alembic templates plus an initial core-schema migration for hub adopters.
 - FastMCP base-server wrapper for generic orientation, messaging, capability,
   repo, DoI, TPSC/GDPR, risk/alert, and progress tools.
+- Packaged `helixforge.hub-extension` 0.1.0 Tier 1 schemas, OpenAPI port
+  fragments, event catalog, compatibility matrix, and ops-hub fixture.
+- Injectable primary runtime scaffold with five named ports, health/readiness,
+  API/MCP/migration commands, and a locked non-root OCI image.
 
 Domain-specific MCP tools follow in each hub package.