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:

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:

python3 -m compileall hub_core
A minimal import test that imports every model, schema, and router module.
SQLAlchemy metadata inspection proving the initial core tables are registered.
A FastAPI smoke app that mounts the extracted routers with an injected get_session dependency.
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.

5.0 KiB Raw Blame History