generated from coulomb/repo-seed
Add hub-core package, docs, and State Hub integration scaffold
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.
This commit is contained in:
152
SCOPE.md
Normal file
152
SCOPE.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user