hub-core/SCOPE.md

# SCOPE — hub-core

**Updated:** 2026-08-23

---

## One-liner

Importable Python package and target runtime for versioned HelixForge hub
contracts, ports, projections, MCP tooling, and compatibility surfaces.

---

## Core idea

`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.

---

## In scope

- **`hub_core` Python package** — models, schemas, routers, MCP server wrapper,
  utilities, events, database helpers
- **Router factories** with host-injected sessions, models, and callbacks
  (domains, repos, messages, progress, capabilities, TPSC, policy)
- **Alembic migration scaffold** for core tables adopters extend
- **Tests** under `tests/` proving import seams and MCP behavior
- **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
- **Cross-domain navigation projections** — rebuildable aggregation of Repo
  Manager's validated repository classifications without classification write
  authority
- **Authoritative workload transport** — rebuildable normalized distribution
  and exact resolution of Repo Manager's workload index without semantic or
  declaration authority
- **Documentation** — `README.md`, `INTENT.md`, `SCOPE.md`, pointer to
  extraction boundary in `the-custodian`

---

## Out of scope

- 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

---

## What is possible now

After the CUST-WP-0025 first slice (2026-06-06 — 2026-06-07):

| Capability | Status |
|---|---|
| Install as editable package | `pip install -e .` / uv equivalent |
| 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 |
| State Hub incremental adoption | Schemas, messages, policy, TPSC, progress, domains, capability catalog routers imported |
| Query repository classification navigation | `port.projection.query` HTTP routes plus MCP facets |
| Transport and resolve workload references | GET-only workload projection routes plus MCP exact resolution |

```bash
cd ~/hub-core
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/pytest -q
```

---

## What remains

- **Published PyPI package** — consumed via editable path or private index only
- **Complete State Hub decoupling** — dev-hub routes and models still live in `state-hub`
- **Repository classification navigation cutover** — contract, ingestion, and
  query/MCP are complete; A5 production handoff remains in `HUB-WP-0006-T06`
- **Workload projection production adoption** — transport/query capability is
  complete; production hosts must inject the Repo Manager workload reader and
  apply migration `0004_workload_projection`
- **fin-hub adoption** — planned; not verified in this repo
- **Capability registry entries** — scaffold only (`capabilities: []`); no registered reusable behaviors yet

---

## Current state

| Item | Value |
|---|---|
| Package version | `0.2.0` (`hub_core.__version__`) |
| Python | `>=3.12` |
| 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 workplans | `HUB-WP-0004`, `HUB-WP-0005`, and `HUB-WP-0007` finished; `HUB-WP-0006-T06` waits on cutover gates |

---

## Repository layout

```text
hub-core/
├── INTENT.md
├── SCOPE.md
├── README.md
├── pyproject.toml
├── hub_core/
│   ├── models/
│   ├── schemas/
│   ├── routers/
│   ├── mcp/
│   ├── runtime/
│   ├── contracts/
│   ├── migrations/
│   ├── utils/
│   ├── database.py
│   └── events.py
├── registry/
│   ├── capabilities/
│   └── indexes/capabilities.yaml
└── tests/
```

---

## Boundaries with sibling repos

| Repo | Boundary |
|---|---|
| `state-hub` | Temporary compatibility source; no new permanent authorities |
| `core-hub` | Previous `/api/v2` runtime retained as rollback through stabilization, then archive |
| `repo-manager` | Owns repository representation, classification validation/projection, 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` | Verified consumer of hub-core `/api/v2`; operations tables stay local |

---

## Workplan convention

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)