---
id: HUB-WP-0003
type: workplan
title: "Ecosystem consolidation — library lane"
domain: infotech
repo: hub-core
status: finished
owner: codex
topic_slug: custodian
created: "2026-07-09"
updated: "2026-07-11"
state_hub_workstream_id: "523acbfe-9f47-5242-8e76-af21bedf2ff2"
---

# Ecosystem consolidation — library lane

## Goal

Prepare `hub-core` as the shared library anchor for the three-repo hub stack
defined in `~/the-custodian/workplans/CUST-WP-0057-hub-ecosystem-consolidation.md`.
Extend package seams so `core-hub` can adopt utilities and contracts without
pulling in dev-hub or `/api/v2` framework code.

Parent workplan: `CUST-WP-0057`

## Scope

In scope:

- `hub_core.utils` parity and tests for cross-repo adoption
- SCOPE/INTENT ecosystem position and sibling boundary table
- Capability registry relations to core-hub and state-hub
- Optional async metadata seam evaluation (no breaking sync API changes)
- Version bump when core-hub merges first consumer PR

Out of scope:

- core-hub `/api/v2` routes or framework models
- state-hub workplan/task tables
- MCP tool changes beyond documenting host boundaries

## Task: Add ecosystem position to INTENT and SCOPE

```task
id: HUB-WP-0003-T01
status: done
priority: high
state_hub_task_id: "8f5140cc-6d93-5c8d-96c5-66c0f72044cd"
```

Add an "Ecosystem position" subsection to `INTENT.md` and expand the "Boundaries
with sibling repos" table in `SCOPE.md` to include:

| Repo | Relationship |
| --- | --- |
| `state-hub` | Primary consumer — mounts router factories and MCP composition |
| `core-hub` | Secondary consumer — adopts utils/schemas; does not duplicate framework tables here |
| `the-custodian` | Owns `hub-ecosystem-architecture.md` decision record |

Done when both files reference `CUST-WP-0057` and the three-layer model.

## Task: Utils parity tests for core-hub adoption

```task
id: HUB-WP-0003-T02
status: done
priority: high
state_hub_task_id: "b9086adc-6362-5eaa-bb38-69a9e5bb52d2"
```

Ensure `hub_core.utils.slugs` covers the cases core-hub `api/v2.py` uses
(lowercase, non-alphanumeric folding, empty fallback). Add regression tests in
`tests/test_utils.py` with documented examples from core-hub bootstrap payloads.

Export `slugify` alias if naming alignment helps core-hub import ergonomics.

Done when core-hub can replace local `slugify()` with a tested hub-core import.

## Task: Document SQLAlchemy metadata isolation guidance

```task
id: HUB-WP-0003-T03
status: done
priority: medium
state_hub_task_id: "165fcb2e-8ffd-5f54-b8d9-b705912c766e"
```

Add `docs/metadata-isolation.md` (or a section in README) explaining:

- hub-core `Base` is for shared primitive tables only;
- core-hub and state-hub keep separate metadata for host-specific tables;
- router factories inject host models — core-hub framework models stay in
  `core_hub.models`, not hub-core.

Done when CORE-WP-0009 T04 can link to this doc without ambiguity.

## Task: Evaluate async base seam (spike only)

```task
id: HUB-WP-0003-T04
status: done
priority: low
state_hub_task_id: "323ddeb3-34bc-5876-8c39-5eaf160307e9"
```

Spike whether `hub_core.models.base` can expose an async-compatible declarative
base or mixin without breaking state-hub sync SQLAlchemy usage. Record outcome
in a short decision note under `the-custodian/docs/` or close as "defer — hosts
keep separate async bases."

Done when the spike has a written recommendation; implementation is optional.

## Task: Update capability registry relations

```task
id: HUB-WP-0003-T05
status: done
priority: medium
state_hub_task_id: "77fcc3d1-98b8-5114-b1a2-bf9630aba269"
```

Update `registry/capabilities/capability.infotech.hub-core-library.md`:

```yaml
relations:
  supports:
    - capability.statehub.workstream-coordinate
  related_to:
    - capability.infotech.core-hub
```

Sync `registry/indexes/capabilities.yaml`.

Done when reuse-surface federation reflects hub-core as library under the stack.

## Task: Release note for first core-hub consumer

```task
id: HUB-WP-0003-T06
status: done
priority: medium
state_hub_task_id: "98328977-b259-538d-b479-4a92975c18a1"
```

When `core-hub` merges hub-core utils import (CORE-WP-0009 T02):

- bump `hub_core.__version__` to `0.2.0`;
- add CHANGELOG entry listing utils adoption and ecosystem consolidation;
- verify `uv run pytest -q` still passes.

Done when core-hub CI pins the new hub-core version and both test suites are green.