feat: add hub runtime and extension contract

SCOPE.md

@@ -1,22 +1,25 @@
 # SCOPE — hub-core
 
-**Updated:** 2026-06-16
+**Updated:** 2026-08-21
 
 ---
 
 ## One-liner
 
-Reusable Python package of FastAPI router factories, SQLAlchemy models, Pydantic
-schemas, MCP tooling, and migration scaffolds for FOS hub services.
+Importable Python package and target runtime for versioned HelixForge hub
+contracts, ports, projections, MCP tooling, and compatibility surfaces.
 
 ---
 
 ## Core idea
 
-`hub-core` is a **library boundary** between shared hub infrastructure and
-host-specific hub implementations. Host repositories depend on `hub-core` as an
-editable or published package; they run the actual HTTP/MCP service, own
-deployment, and add domain tables and workflows on top.
+`hub-core` preserves its **library boundary** while growing into the surviving
+hub framework and runtime defined by `SHR-ARCH-HUB-0001`. Domain hubs depend on
+its versioned contracts and ports while retaining their own data and APIs.
+Repository work remains authoritative in Git and is reached through
+repo-manager ports. `ADR-0001` selects a primary OCI image from this repository,
+with API, MCP, and migration processes sharing the image and contract version;
+the Python package remains independently importable.
 
 ---
 
@@ -31,6 +34,10 @@ deployment, and add domain tables and workflows on top.
 - **Package metadata** — `pyproject.toml`, hatchling wheel build
 - **Capability registry scaffold** — `registry/` per helix_forge federation
   contract (entries added when reusable behaviors are registered)
+- **Hub-extension contracts and conformance** — descriptors, manifests, event
+  catalogs, port APIs, fixtures, and compatibility matrices
+- **Surviving runtime surfaces** — registry, messaging, progress and
+  interaction events, projections, telemetry, `/api/v2` compatibility, and MCP
 - **Documentation** — `README.md`, `INTENT.md`, `SCOPE.md`, pointer to
   extraction boundary in `the-custodian`
 
@@ -38,13 +45,13 @@ deployment, and add domain tables and workflows on top.
 
 ## Out of scope
 
-- Long-running hub service, Docker image, or production URL for hub-core itself
-- Dev-hub tables: topics, workplans, tasks, decisions, dependencies, SBOM,
-  token accounting, kaizen agents
+- Repository-owned work records, Git write authority, and consistency logic
+- Domain-specific business tables and APIs belonging to domain hubs
 - State Hub dashboard UI, consistency sync scripts, and workplan file authority
 - Custodian canon content and constitution maintenance
 - Plaintext secrets, environment-specific connection strings committed to git
 - Replacing or wrapping non-hub application domains (feature-control, reuse-surface, etc.)
+- Authorization decisions, credential custody, and schedule execution
 
 ---
 
@@ -58,6 +65,10 @@ After the CUST-WP-0025 first slice (2026-06-06 — 2026-06-07):
 | Import core models and schemas | `hub_core.models`, `hub_core.schemas` |
 | Mount generic routers in a host FastAPI app | `hub_core.routers.create_*_router` |
 | Run generic MCP tools via `HubCoreMCPServer` | `hub_core.mcp` |
+| Load versioned hub-extension contracts from the wheel | `hub_core.contracts.extension_contract_root()` |
+| Run the minimal named-port HTTP runtime | `hub-core api` / `hub_core.runtime.create_app` |
+| Run API, MCP, and packaged migration processes | `hub-core api`, `hub-core mcp`, `hub-core migrate` |
+| Build the primary locked non-root OCI image | `make container-build` |
 | Apply core-schema migration template | `hub_core/migrations/versions/0001_core_schema.py` |
 | Adopt shared slug/pagination/path utilities | `hub_core.utils` |
 | Expose risk/alert progress read views | `/progress/risks`, `/progress/alerts` patterns |
@@ -74,11 +85,10 @@ python3 -m venv .venv && .venv/bin/pip install -e .
 ## What is not possible yet
 
 - **Published PyPI package** — consumed via editable path or private index only
-- **Standalone `hub-core serve`** — no CLI entrypoint; hosts own `uvicorn`
+- **Production durable port store** — T04 ships only the fail-closed ephemeral conformance backend
 - **Complete State Hub decoupling** — dev-hub routes and models still live in `state-hub`
 - **ops-hub / fin-hub adoption** — planned; not verified in this repo
 - **Capability registry entries** — scaffold only (`capabilities: []`); no registered reusable behaviors yet
-- **Gitea federation publish** — repo not yet on Gitea; blocks T01 in reuse-surface WP-0015
 
 ---
 
@@ -86,13 +96,15 @@ python3 -m venv .venv && .venv/bin/pip install -e .
 
 | Item | Value |
 |---|---|
-| Package version | `0.1.0` (`hub_core.__version__`) |
+| Package version | `0.2.0` (`hub_core.__version__`) |
 | Python | `>=3.12` |
-| Dependencies | FastAPI, FastMCP, SQLAlchemy, Pydantic, httpx |
+| Dependencies | FastAPI, FastMCP, SQLAlchemy, Pydantic, httpx, JSON Schema; runtime extra adds ASGI/PostgreSQL/Alembic |
 | Tests | pytest under `tests/` |
 | Registry | Empty capability index; federation scaffold present |
 | Primary consumer | `state-hub` (editable dependency, router/schema import in progress) |
 | Extraction workplan | `CUST-WP-0025` (custodian domain) |
+| Target architecture | `SHR-ARCH-IA-0001` + `SHR-ARCH-HUB-0001` |
+| Runtime workplan | `HUB-WP-0004` |
 
 ---
 
@@ -109,6 +121,8 @@ hub-core/
 │   ├── schemas/
 │   ├── routers/
 │   ├── mcp/
+│   ├── runtime/
+│   ├── contracts/
 │   ├── migrations/
 │   ├── utils/
 │   ├── database.py
@@ -125,8 +139,9 @@ hub-core/
 
 | Repo | Boundary |
 |---|---|
-| `state-hub` | Primary host — mounts router factories and MCP composition; owns workplans/tasks |
-| `core-hub` | Secondary consumer — imports utils/schemas; owns `/api/v2` framework tables locally |
+| `state-hub` | Temporary compatibility source; no new permanent authorities |
+| `core-hub` | `/api/v2` runtime and route source to absorb, then archive |
+| `repo-manager` | Owns repository representation, work index, consistency, and governed Git mutations |
 | `the-custodian` | Owns ecosystem architecture (`hub-ecosystem-architecture.md`) and extraction boundary |
 | `reuse-surface` | Federation hub for capability indexes; not a runtime dependency of hub-core |
 | `ops-hub` | Consumer of core-hub `/api/v2`; operations tables stay local |
@@ -135,19 +150,18 @@ hub-core/
 
 ## Workplan convention
 
-Hub-core extraction and package work is tracked under **custodian** workplans
-(for example `CUST-WP-0025`). Host adoption milestones are tracked in
-`state-hub` workplans (for example `CUST-WP-0048`).
-
-When hub-core gains repo-local workplans, prefer a stable prefix agreed with
-custodian operators (for example `HUBCORE-WP-####`).
+Repo-local work uses the `HUB-WP-####` prefix. Cross-repository consolidation
+is coordinated by `prj-state-hub-retirement`; owner repositories keep their
+own workplan files authoritative.
 
 ---
 
 ## Getting oriented
 
 - Product intent: `INTENT.md`
+- Target architecture: `/home/worsch/prj-state-hub-retirement/architecture/hub-extension-architecture_v0.1.md`
+- Information model: `/home/worsch/prj-state-hub-retirement/architecture/information-model_v0.1.md`
 - Extraction boundary: `/home/worsch/the-custodian/docs/hub-core-extraction-boundary.md`
 - Package entry: `hub_core/__init__.py`, `hub_core/routers/__init__.py`
 - Consumer example: `/home/worsch/state-hub` (editable `hub-core` dependency)
-- Federation registry: `registry/README.md` (reuse-surface contract)
+- Federation registry: `registry/README.md` (reuse-surface contract)