# SCOPE — hub-core

**Updated:** 2026-06-16

---

## One-liner

Reusable Python package of FastAPI router factories, SQLAlchemy models, Pydantic
schemas, MCP tooling, and migration scaffolds for FOS hub services.

---

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

---

## 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)
- **Documentation** — `README.md`, `INTENT.md`, `SCOPE.md`, pointer to
  extraction boundary in `the-custodian`

---

## Out of scope

- Long-running hub service, Docker image, or production URL for hub-core itself
- Dev-hub tables: topics, workstreams, tasks, decisions, dependencies, SBOM,
  token accounting, kaizen agents
- 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.)

---

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

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

---

## 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`
- **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

---

## Current state

| Item | Value |
|---|---|
| Package version | `0.1.0` (`hub_core.__version__`) |
| Python | `>=3.12` |
| Dependencies | FastAPI, FastMCP, SQLAlchemy, Pydantic, httpx |
| 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) |

---

## Repository layout

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

---

## Boundaries with sibling repos

| Repo | Boundary |
|---|---|
| `state-hub` | Host dev-hub; imports hub-core factories; keeps workstream/task/decision logic |
| `the-custodian` | Owns extraction boundary doc and CUST-WP-0025 workplan |
| `reuse-surface` | Federation hub for capability indexes; not a runtime dependency of hub-core |
| `ops-hub` | Future consumer; operations-specific tables stay local |

---

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

---

## Getting oriented

- Product intent: `INTENT.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)