121 lines
5.0 KiB
Markdown
121 lines
5.0 KiB
Markdown
# Hub-Core Extraction Boundary
|
|
|
|
Last reviewed: 2026-06-06
|
|
|
|
## Purpose
|
|
|
|
This note starts `CUST-WP-0025-T05` by translating the original hub-core idea
|
|
into a current implementation boundary. The State Hub implementation no longer
|
|
lives under `the-custodian/state-hub`; the authoritative source checkout is
|
|
`/home/worsch/state-hub`, and the planned package target is
|
|
`/home/worsch/hub-core`.
|
|
|
|
The extraction must preserve a clean FOS split:
|
|
|
|
- `hub-core` owns reusable hub primitives.
|
|
- `state-hub` becomes the first dev-hub implementation and keeps development
|
|
coordination concepts such as topics, workstreams, tasks, decisions,
|
|
dependencies, SBOM, token accounting, and kaizen agents.
|
|
- Future hubs such as ops-hub and fin-hub depend on `hub-core` without pulling
|
|
in dev-hub coordination tables.
|
|
|
|
## First Package Slice
|
|
|
|
Create `/home/worsch/hub-core` as a uv-managed Python package with this initial
|
|
layout:
|
|
|
|
```text
|
|
hub_core/
|
|
__init__.py
|
|
database.py
|
|
models/
|
|
__init__.py
|
|
base.py
|
|
domain.py
|
|
managed_repo.py
|
|
agent_message.py
|
|
tpsc.py
|
|
schemas/
|
|
__init__.py
|
|
domain.py
|
|
managed_repo.py
|
|
agent_message.py
|
|
tpsc.py
|
|
routers/
|
|
__init__.py
|
|
domains.py
|
|
repos.py
|
|
messages.py
|
|
tpsc.py
|
|
policy.py
|
|
```
|
|
|
|
This slice avoids the models that currently carry dev-hub foreign keys. It is
|
|
large enough to prove packaging, import style, SQLAlchemy metadata ownership,
|
|
router dependency injection, and State Hub compatibility before the more
|
|
entangled surfaces move.
|
|
|
|
## Extract Now
|
|
|
|
These State Hub files are suitable for the first extraction after import-path
|
|
rewriting and small router seams:
|
|
|
|
| Source in `/home/worsch/state-hub` | Target role |
|
|
| --- | --- |
|
|
| `api/models/base.py` | Declarative base, timestamps, UUID helper. |
|
|
| `api/models/domain.py` | Core domain identity; remove relationships to dev-hub-only models from core. |
|
|
| `api/models/managed_repo.py` | Core repo registry; make `topic_id`, SBOM, and sync timestamps extension fields or keep them in dev-hub until a second pass. |
|
|
| `api/models/agent_message.py` | Generic agent inbox and thread model. |
|
|
| `api/models/tpsc.py` | Third-party service catalog/snapshot primitives. |
|
|
| `api/schemas/domain.py` | Core domain schemas; split dev-hub counts from generic read models. |
|
|
| `api/schemas/managed_repo.py` | Core repo schemas; keep dispatch/scope-health schemas in dev-hub. |
|
|
| `api/schemas/agent_message.py` | Generic message schemas. |
|
|
| `api/schemas/tpsc.py` | Generic TPSC schemas. |
|
|
| `api/routers/messages.py` | Mostly self-contained generic router. |
|
|
| `api/routers/tpsc.py` | Generic catalog and GDPR report router. |
|
|
| `api/routers/policy.py` | Generic policy document router if policy roots become configurable. |
|
|
|
|
## Needs An Adapter Seam
|
|
|
|
These are still part of the target architecture, but the current State Hub
|
|
implementation is coupled to dev-hub concepts:
|
|
|
|
| Surface | Coupling to resolve |
|
|
| --- | --- |
|
|
| `Domain` and `domains.py` detail views | Counts topics, workstreams, extension points, and technical debt. Hub-core should expose a domain summary hook that dev-hub can implement. |
|
|
| `ManagedRepo` | Contains `topic_id`, SBOM fields, and state-sync timestamps. Keep minimal repo identity in core, then add dev-hub extensions. |
|
|
| `CapabilityRequest` | Points at workstreams and tasks. Hub-core needs generic context fields or optional extension references before extraction. |
|
|
| `ProgressEvent` | Points at topics, workstreams, tasks, and decisions. Hub-core should define event identity, type, summary, detail, author, and timestamps, with hub-specific subject references added by each hub. |
|
|
| MCP tools in `mcp_server/server.py` | Generic tools are mixed into a single dev-hub server module. T06 should create a base registration class that receives API client/config dependencies and lets dev-hub add its own tools. |
|
|
|
|
## Keep In Dev-Hub
|
|
|
|
The following State Hub areas should not move into hub-core during T05:
|
|
|
|
- Topics, workstreams, tasks, decisions, dependencies, and flow state.
|
|
- Extension points, technical debt, interface changes, SBOM, token events, and
|
|
contribution accounting.
|
|
- Dashboard-specific loaders and Observable views.
|
|
- Workplan-file parsing and consistency reconciliation.
|
|
- Kaizen agents, scope health, dispatch views, and recently-on-scope reports.
|
|
|
|
## Verification Plan
|
|
|
|
The first hub-core commit should pass these checks before State Hub is refactored
|
|
to import it:
|
|
|
|
1. `python3 -m compileall hub_core`
|
|
2. A minimal import test that imports every model, schema, and router module.
|
|
3. SQLAlchemy metadata inspection proving the initial core tables are registered.
|
|
4. A FastAPI smoke app that mounts the extracted routers with an injected
|
|
`get_session` dependency.
|
|
5. `cd /home/worsch/state-hub && make test` remains green before and after the
|
|
editable `hub-core` dependency is introduced.
|
|
|
|
## Next Step
|
|
|
|
Create the `/home/worsch/hub-core` package with only the first package slice,
|
|
commit that seed independently, then return to `/home/worsch/state-hub` for the
|
|
first import-based refactor. Do not rename State Hub to dev-hub until T05-T08
|
|
prove the shared package boundary.
|