the-custodian/workplans/CUST-WP-0048-hub-core-state-hub-import-refactor.md

---
id: CUST-WP-0048
type: workplan
title: "Hub-Core State Hub Import Refactor"
domain: infotech
repo: the-custodian
status: finished
owner: custodian
topic_slug: custodian
created: "2026-06-07"
updated: "2026-06-22"
state_hub_workstream_id: "dd53bd50-641d-4c67-a143-10e39321e1d6"
---

# Hub-Core State Hub Import Refactor

## Goal

Complete the CUST-WP-0025 T08 migration as its own tracked workplan: refactor
the standalone `/home/worsch/state-hub` codebase to import reusable generic
models, schemas, routers, and MCP surfaces from `/home/worsch/hub-core` while
keeping dev-hub-specific coordination behavior local.

This is a child workplan of `CUST-WP-0025` Phase 2. The umbrella task
`CUST-WP-0025-T08` remains in progress until this workplan reaches `finished`.

## Scope Boundary

`hub-core` should own reusable hub primitives and factory-based router/MCP
surfaces. `state-hub` should keep development coordination concepts such as
topics, workplans, tasks, decisions, dependencies, consistency checks, SBOM,
dashboard loaders, and workflow side effects.

The migration should proceed by narrow seams:

- Prefer schema re-exports before router replacement.
- Prefer router factories with host-model and host-schema injection.
- Keep State Hub callbacks for dev-hub behavior such as counts, validation,
  notifications, flow transitions, and task-unblock side effects.
- Keep test coverage focused per slice, with full regression at the end.

## Completed History

- 2026-06-07: Added `/home/worsch/hub-core` as an editable dependency of
  `/home/worsch/state-hub`, synced `uv.lock`, and converted message and DoI
  response schemas into compatibility re-exports from `hub_core.schemas`.
  Verification: full State Hub pytest passed with 349 tests.
- 2026-06-07: Aligned hub-core TPSC schemas and GDPR report payload with State
  Hub, then re-exported `api.schemas.tpsc` from `hub_core.schemas.tpsc`.
  Verification: hub-core pytest passed with 15 tests; focused State Hub tests
  passed, and the lone full-run flake passed on rerun.
- 2026-06-07: Converted base domain schemas (`DomainCreate`, `DomainRead`,
  `DomainRename`, `DomainUpdate`) to imports from `hub_core.schemas.domain`.
  Verification: State Hub import/core-router focused tests passed with 58 tests.
- 2026-06-07: Added host-model injection to the hub-core messages router and
  replaced State Hub's local messages router with the hub-core factory.
  Verification: hub-core pytest passed with 16 tests; focused State Hub tests
  passed with 70 tests.
- 2026-06-07: Extended the hub-core policy router with an optional update
  callback and replaced State Hub's policy router with the hub-core factory
  plus local path validation/read/write callbacks. Verification: hub-core
  pytest passed with 17 tests; State Hub focused tests passed when split to
  avoid live API test-DB contention.
- 2026-06-07: Added host-model injection to the hub-core TPSC router and
  replaced State Hub's TPSC router with the hub-core factory. Verification:
  hub-core pytest passed with 18 tests; focused State Hub tests passed with 17
  and 54 tests.
- 2026-06-07: Added host-model/schema injection to the hub-core progress router
  and replaced State Hub's progress router while preserving topic/workplan/task
  filters and shared risk/alert views. Verification: hub-core pytest passed with
  19 tests; State Hub focused tests passed with 71 tests.
- 2026-06-07: Added host-model/schema injection, optional update-route
  registration, and detail/archive callbacks to the hub-core domains router,
  then replaced State Hub's domains router. Verification: hub-core pytest passed
  with 20 tests; State Hub focused tests passed with 102 tests.
- 2026-06-07: Converted generic capability catalog schemas, capability request
  status/dispute schemas, and repo path registration schema to hub-core imports.
  State Hub repo create/read schemas now extend hub-core contracts. Verification:
  State Hub focused tests passed with 100 tests.
- 2026-06-07: Added `create_capability_catalog_router` with host model
  injection and replaced State Hub's capability catalog CRUD routes. Verification:
  hub-core pytest passed with 21 tests; State Hub focused tests passed with 95
  tests.
- 2026-06-07: Added `create_capability_request_read_router` with host
  domain/request model and response-schema injection, then replaced State Hub's
  capability request list/detail routes. Verification: hub-core compile checks
  passed, hub-core pytest passed with 22 tests, the post-format import slice
  passed with 14 tests, State Hub compile checks passed, and State Hub focused
  tests passed with 95 tests.
- 2026-06-07: Added configurable host-model/schema injection and route grouping
  to `hub_core.routers.repos.create_repos_router`, then replaced State Hub's
  generic repo registry routes with the hub-core factory. State Hub keeps
  onboarding, DoI, scope-health, dispatch, archive, and consistency-sync routes
  local. Verification: hub-core compile checks passed, hub-core import tests
  passed with 16 tests, full hub-core pytest passed with 24 tests, State Hub
  compile checks passed, and State Hub repo/import/MCP focused tests passed with
  81 tests.
- 2026-06-22: T05–T06 completed via HUB-WP-0002. State Hub mounts
  `create_capability_request_write_router` with dev-hub callbacks; generic MCP
  tools register through `HubCoreMCPServer.attach_to()`.
- 2026-06-22: T07 regression green — hub-core 27 tests, State Hub 426 tests
  (health route fixed to use injected session). Child workplan closed.

## T01 - Establish Editable Dependency And Schema Re-Exports

```task
id: CUST-WP-0048-T01
status: done
priority: high
state_hub_task_id: "2a5c8ef6-f3de-4a01-9fa2-6305e62efae9"
```

Add hub-core as an editable State Hub dependency and convert the low-risk
generic schema modules to compatibility imports or extensions from hub-core.
This includes message, DoI, TPSC, base domain, capability catalog/status/dispute,
and repo path registration schemas.

## T02 - Replace Low-Risk Generic Routers

```task
id: CUST-WP-0048-T02
status: done
priority: high
state_hub_task_id: "e377b5ae-2ab8-4340-930e-1381640e8f4b"
```

Replace State Hub's local generic router implementations with hub-core router
factories where host-model injection or callbacks are already sufficient:
messages, policy, TPSC, progress, and domains.

## T03 - Replace Capability Catalog And Request Read Routes

```task
id: CUST-WP-0048-T03
status: done
priority: high
state_hub_task_id: "b9129286-b218-47e7-964f-6cf24ac8f5a6"
```

Move capability catalog CRUD and read-only capability request list/detail routes
behind hub-core factories. Keep request workflow writes local until their State
Hub flow-transition, notification, reroute, and task-unblock behavior has an
explicit adapter seam.

## T04 - Resolve Repos Router Boundary

```task
id: CUST-WP-0048-T04
status: done
priority: high
state_hub_task_id: "321434ee-152b-436c-becd-4e56a44de716"
```

Review the State Hub repos router and split reusable repo registry behavior
from dev-hub-specific onboarding, dispatch, DoI, scope-health, SBOM, and state
sync behavior. Either replace the reusable subset with a hub-core factory or
document the adapter seam needed before replacement.

Completed (2026-06-07): hub-core now owns the reusable repo registry route
factory for collection, lookup, detail, update, and host-path registration.
State Hub mounts those routes in ordered groups so `/repos/scope-health` and
other fixed local routes cannot be swallowed by `/{slug}`. State Hub keeps the
dev-hub-specific repo surfaces local: onboarding, DoI, scope-health, dispatch,
archive, and consistency sync.

## T05 - Resolve Capability Request Write Workflow Boundary

```task
id: CUST-WP-0048-T05
status: done
priority: high
state_hub_task_id: "669dea12-9ef1-4ab4-83ae-5ee4cf5fd159"
```

Review capability request creation, acceptance, status changes, patching,
dispute, and reroute routes. Decide which write paths can move to hub-core via
callbacks and which require a dev-hub extension table or context mapping for
workplan/task references.

Completed 2026-06-22: all write routes mount from
`create_capability_request_write_router`. Dev-hub keeps `requesting_workplan_id`,
`blocking_task_id`, and `fulfilling_workplan_id` on the State Hub model; side
effects (flow transitions, notifications, task-unblock) live in host callbacks.
Deferred: mapping workplan/task columns into `request_context` JSON.

## T06 - Split Generic MCP Tool Registration

```task
id: CUST-WP-0048-T06
status: done
priority: medium
state_hub_task_id: "8a202c88-8ab6-4b90-a792-d3a25b64fd0e"
```

Replace generic State Hub MCP tool registrations with `HubCoreMCPServer`
composition or inheritance while keeping dev-hub-only tools local.

Completed 2026-06-22: State Hub calls `HubCoreMCPServer.attach_to(mcp,
exclude=_HUB_CORE_MCP_EXCLUDE)` for 18 generic tools. Local overrides remain
for dev-hub orientation, extended repo/capability/TPSC contracts, and all
workplan/task/decision tooling.

## T07 - Run Regression And Coupling Report

```task
id: CUST-WP-0048-T07
status: done
priority: high
state_hub_task_id: "b5a6b9e3-2a4b-443d-82fe-2f156775270d"
```

Run full hub-core and State Hub regression suites after the remaining seams are
resolved. Update `docs/hub-core-extraction-boundary.md` with any remaining
couplings, deferred adapter seams, and the next safe migration step.

Completed 2026-06-22: hub-core 27/27, State Hub 426/426. Boundary doc updated
with write-router and MCP composition seams. Health probe fixed to use injected
session (eliminated full-suite asyncpg teardown flake).

## T08 - Close Child Workplan And Return To Umbrella

```task
id: CUST-WP-0048-T08
status: done
priority: medium
state_hub_task_id: "c34d121c-29f2-4704-9173-1fa2535482b0"
```

When T04-T07 are complete or explicitly deferred, mark this workplan finished
and update `CUST-WP-0025-T08` so the umbrella can proceed to the dev-hub rename
phase.

Completed 2026-06-22: workplan marked `finished`; `CUST-WP-0025-T08` set to
`done`. Phase 2 rename sequence (T09+) is unblocked.