the-custodian/docs/hub-core-extraction-boundary.md

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
    capability_catalog.py
    capability_request.py
    progress_event.py
    tpsc.py
  schemas/
    __init__.py
    domain.py
    managed_repo.py
    agent_message.py
    capability.py
    progress_event.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.

Current implementation status:

• 2026-06-06: /home/worsch/hub-core was created and committed with base, domain, managed repo, agent message, capability catalog, and TPSC models plus matching schemas.
• 2026-06-06: router factory functions were added for domains, repos, messages, TPSC, and policy lookup. These factories accept host-supplied dependencies instead of importing State Hub globals.
• 2026-06-06: shared utilities and migration scaffold were added: slug normalization, pagination, repo path resolution, trailing-slash path normalization, Alembic templates, and an initial core-schema migration.
• 2026-06-06: progress event and capability request adapter seams were added. Hub-core uses generic JSON context fields where State Hub currently has dev-specific workstream/task/topic/decision foreign keys.
• 2026-06-07: progress and capability REST router factories were added. T05 now has the package-side models, schemas, routers, migration scaffold, and shared utilities needed before T06/T08.
• 2026-06-07: HubCoreMCPServer was added as the first T06 slice. It wraps the generic REST endpoints with FastMCP tools and keeps the MCP layer stateless.
• 2026-06-07: T06/T07 completed in hub-core with orientation and DoI MCP tools, canonical FOS §10 risk/alert event types, /progress/risks and /progress/alerts REST views, and matching MCP read tools.
• 2026-06-07: T08 started in State Hub. hub-core is now an editable dependency, and State Hub re-exports message and DoI response schemas from hub_core.schemas with full pytest coverage passing.
• 2026-06-07: T08 schema imports expanded. Hub-core's TPSC schema/report contract now matches State Hub, and State Hub re-exports api.schemas.tpsc from hub_core.schemas.tpsc.
• 2026-06-07: T08 domain schema imports started. State Hub now imports base domain schemas from hub_core.schemas.domain while keeping dev-hub-specific domain detail and summary schemas local.
• 2026-06-07: T08 router imports started. State Hub now mounts the hub-core messages router factory with State Hub's own AgentMessage model injected, proving the router seam can avoid cross-metadata SQLAlchemy model imports.

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/progress.py	Generic progress-event router once dev-hub foreign keys move behind subject_refs or extension mapping.
api/routers/capability_requests.py	Generic capability catalog/request router once dev-hub flow side effects and task unblocking stay in dev-hub.
api/routers/tpsc.py	Generic catalog and GDPR report router.
api/routers/policy.py	Generic policy document router if policy roots become configurable.

The first committed router seam is factory-based rather than global:

from hub_core.routers import create_domains_router

app.include_router(create_domains_router(get_session))

That shape lets each hub keep its own database session configuration and mount only the generic routers it wants.

Shared Utilities

The initial utility set is intentionally small and dependency-light:

Module	Purpose
hub_core.utils.slugs	Convert user-facing names into stable lowercase slugs.
hub_core.utils.pagination	Shared limit/offset bounds and SQLAlchemy pagination.
hub_core.utils.paths	Resolve repo paths from host_paths before falling back to local_path.
hub_core.utils.routing	Normalize a path or URL path component while preserving query strings and fragments.

Migration Scaffold

/home/worsch/hub-core now carries Alembic template files under hub_core/migrations/ plus versions/0001_core_schema.py. The first migration covers only the currently extracted core tables:

• domains
• managed_repos
• agent_messages
• capability_catalog
• capability_requests
• progress_events
• tpsc_catalog
• tpsc_snapshots
• tpsc_entries

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	Adapter seam implemented with generic request_context and fulfillment_context; State Hub still needs a later refactor to map workstream/task references into those fields or a dev-hub extension table.
ProgressEvent	Adapter seam implemented with generic subject_refs; State Hub still needs a later refactor to map topic/workstream/task/decision foreign keys into that field or a dev-hub extension table.
MCP tools in mcp_server/server.py	Generic tools are still mixed into the State Hub server module. T08 should begin replacing those registrations with HubCoreMCPServer inheritance or composition while dev-hub keeps its own tools.

The first two adapter seams are now implemented in hub-core:

• ProgressEvent.subject_refs: generic JSON references for hub-local subjects.
• CapabilityRequest.request_context and fulfillment_context: generic JSON context for hub-local workstreams, tasks, incidents, services, budgets, or other future hub entities.

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

Continue T08 by applying the host-model injection pattern to the next lowest-risk generic routers. Repos, domains, TPSC, progress, and capability requests each need a small dependency-injection review before replacement. Do not rename State Hub to dev-hub until T05-T08 prove the shared package boundary.