--- id: CUST-WP-0048 type: workplan title: "Hub-Core State Hub Import Refactor" domain: custodian repo: the-custodian status: active owner: custodian topic_slug: custodian created: "2026-06-07" updated: "2026-06-07" 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, workstreams, 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/workstream/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. ## 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: todo 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 workstream/task references. ## T06 - Split Generic MCP Tool Registration ```task id: CUST-WP-0048-T06 status: todo 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. ## T07 - Run Regression And Coupling Report ```task id: CUST-WP-0048-T07 status: todo 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. ## T08 - Close Child Workplan And Return To Umbrella ```task id: CUST-WP-0048-T08 status: todo 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.