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

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

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)

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard. It does not contact the hub, alter workplan statuses, or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.