hub-core/SCOPE.md

SCOPE — hub-core

Updated: 2026-08-22

---

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
• 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

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 — accepted contract; ingestion, query/MCP, and A5 cutover remain in HUB-WP-0006
• 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 and HUB-WP-0005 finished; HUB-WP-0006 active

---

Repository layout

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)