generated from coulomb/repo-seed
tegwick
986ac4d40b
Extract the first reusable slice (models, schemas, routers, MCP, migrations) from state-hub with INTENT/SCOPE, agent instructions, workplan, and aligned inter_hub capability registry index.
152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
# 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) |