aab187937b
Publish ecosystem architecture, event mapping, capability bridge, and async-base decision docs; add cross-repo regression script; update extraction boundary and bootstrap status; archive WP-0058 touch-ups.
317 lines
No EOL
14 KiB
Markdown
317 lines
No EOL
14 KiB
Markdown
---
|
||
id: CUST-WP-0057
|
||
type: workplan
|
||
title: "Hub ecosystem consolidation — hub-core, core-hub, state-hub alignment"
|
||
domain: infotech
|
||
repo: the-custodian
|
||
status: finished
|
||
owner: codex
|
||
topic_slug: custodian
|
||
created: "2026-07-09"
|
||
updated: "2026-07-11"
|
||
state_hub_workstream_id: "3a829663-1a36-4a48-a09e-aaf6cf26aaee"
|
||
---
|
||
|
||
# CUST-WP-0057 — Hub Ecosystem Consolidation
|
||
|
||
## Goal
|
||
|
||
Align `hub-core`, `core-hub`, and `state-hub` into a coherent three-layer hub
|
||
stack with explicit boundaries, shared library reuse where it reduces drift, and
|
||
documented integration contracts — without collapsing distinct runtime roles or
|
||
breaking Core Hub production `/api/v2` consumers.
|
||
|
||
This workplan supersedes ad hoc overlap between the Phase 2 library extraction
|
||
(`hub-core`, `CUST-WP-0048`) and Phase 3 production framework (`core-hub`,
|
||
`CUST-WP-0052`). It does **not** merge repos; it defines how they compose.
|
||
|
||
## Overlap Map (current state)
|
||
|
||
### Target layer model
|
||
|
||
| Layer | Repo | Role | Runs in production? |
|
||
| --- | --- | --- | --- |
|
||
| Library | `hub-core` | Reusable models, schemas, router factories, MCP wrapper, migration scaffolds | No — imported by hosts |
|
||
| Dev coordination | `state-hub` | File-first workplans, tasks, decisions, consistency sync, dashboard, dev MCP | Yes — local/operator dev hub |
|
||
| Production framework | `core-hub` | Inter-Hub successor: hubs, manifests, widgets, interaction events, operator console, `/api/v2` | Yes — `hub.coulomb.social` |
|
||
|
||
### Entity overlap matrix
|
||
|
||
| Concern | hub-core | state-hub | core-hub | Overlap type | Consolidation stance |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| Domains / managed repos | `Domain`, `ManagedRepo` + router factories | Extended models + dev counts/onboarding | Not modeled (hub registry uses `Hub` entity) | Partial — registry vs framework hub | Keep hub-core primitives; map `Hub` ↔ domain/repo in integration doc |
|
||
| Agent messages | `AgentMessage` + factory | Uses hub-core factory | Not implemented | Library-only today | core-hub ingests via State Hub API or future read-model bridge; do not duplicate table |
|
||
| Progress events | `ProgressEvent` + `subject_refs` JSON | FK-extended model + hub-core factory | `InteractionEvent` (widget-scoped, different shape) | **Semantic** — both are append-only evidence | Treat as distinct event families; document mapping rules |
|
||
| Capability catalog / requests | `CapabilityCatalog`, `CapabilityRequest` + factories | Dev workflow columns + hub-core factories | `HubCapabilityManifest` (Inter-Hub manifest contract) | **Conceptual** — catalog vs manifest | core-hub keeps manifest tables; state-hub keeps maturity catalog; link via capability IDs in integration contract |
|
||
| TPSC / service catalog | Full models + router | hub-core factory | Not implemented | Library-only | state-hub remains host; core-hub references via HTTP/evidence, not reimplementation |
|
||
| Policy lookup | Router factory + schemas | hub-core factory + local paths | `policy-scopes` catalog (static seed) | Partial | Share catalog YAML source or hub-core policy router where paths align |
|
||
| Workplans / tasks / decisions | Out of scope (by design) | Canonical implementation | Spec-only (`workplan-coordination.md`); not persisted yet | **Boundary tension** | state-hub remains canonical until ADR records cutover; core-hub indexes/displays, does not fork tables |
|
||
| Hubs / manifests / widgets / API consumers | Out of scope | Out of scope | Canonical (`/api/v2`) | None — core-hub exclusive | Do not move into hub-core |
|
||
| MCP agent tools | `HubCoreMCPServer` (HTTP client to host API) | Composes hub-core + dev-hub tools | Operator CLI only | Partial | core-hub CLI for ops; agent MCP stays on state-hub for dev coordination |
|
||
| Slug/pagination/utils | `hub_core.utils.*` | Uses hub-core | Local `slugify()` in `api/v2.py` | **Code duplication** | core-hub should import hub-core utils |
|
||
| SQLAlchemy base / timestamps | `hub_core.models.base` | Mixed — some local, some via hub-core | `core_hub.db.Base` (separate metadata) | **Technical** — two bases | Document metadata isolation; optional shared base module in hub-core |
|
||
| Auth / API keys | Out of scope | State Hub auth | `ApiConsumer`, `ApiKey` (hash/prefix only) | core-hub exclusive | No extraction to hub-core unless multi-hub auth factory is needed |
|
||
|
||
### Drift risks (why consolidation is needed)
|
||
|
||
1. **Parallel Python stacks** — core-hub rebuilt FastAPI/SQLAlchemy without depending on
|
||
hub-core, so shared concepts (slugs, pagination, message/progress shapes) can diverge.
|
||
2. **Naming collision** — `hub-core` vs `core-hub` confuses agents and operators.
|
||
3. **Unset coordination cutover** — core-hub `data-model.md` still asks whether workplan
|
||
tables move to Core Hub; without a decision, both repos may grow competing models.
|
||
4. **Missing capability relations** — reuse-surface entries do not cross-link the three
|
||
repos, so federation discovery hides the intended stack.
|
||
5. **Domain metadata mismatch** — hub-core INTENT says `inter_hub`; classifications say
|
||
`infotech`; core-hub is `infotech` interaction-framework.
|
||
|
||
## Governing decisions (to lock in T01)
|
||
|
||
- **hub-core stays a library** — no service entrypoint, no K8s, no production URL.
|
||
- **core-hub stays the Inter-Hub production framework** — owns `/api/v2` compatibility.
|
||
- **state-hub stays the dev coordination host** — owns workplan file authority and
|
||
consistency sync until an explicit ADR migrates that role.
|
||
- **Consolidation means compose, not merge** — shared code moves into hub-core;
|
||
integration contracts define HTTP/MCP boundaries between runtimes.
|
||
- **No big-bang cutover** — adopt hub-core in core-hub incrementally behind compatibility
|
||
tests; State Hub regression must stay green throughout.
|
||
|
||
## Child / companion workplans
|
||
|
||
| Repo | Workplan | Scope |
|
||
| --- | --- | --- |
|
||
| `hub-core` | `HUB-WP-0003-ecosystem-consolidation-library-lane.md` | Library extensions, utils export, capability relations, async base seam |
|
||
| `core-hub` | `CORE-WP-0009-hub-core-adoption-and-integration.md` (create in T02) | hub-core dependency, utils adoption, integration contract implementation |
|
||
| `state-hub` | `STATE-WP-0074-hub-ecosystem-boundary-alignment.md` (create in T03) | Boundary docs, cross-hub progress/message export APIs if needed |
|
||
|
||
## Task: Publish ecosystem architecture decision
|
||
|
||
```task
|
||
id: CUST-WP-0057-T01
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "e84851b3-5f22-4a6f-83a1-76c4148839d9"
|
||
```
|
||
|
||
Write `the-custodian/docs/hub-ecosystem-architecture.md` capturing:
|
||
|
||
- the three-layer model above;
|
||
- entity ownership table (canonical owner per table family);
|
||
- event-family mapping (`ProgressEvent` vs `InteractionEvent`);
|
||
- capability catalog vs hub-capability-manifest relationship;
|
||
- explicit non-goals (no repo merge, no State Hub retirement in this workplan).
|
||
|
||
Update `hub-core/INTENT.md`, `hub-core/SCOPE.md`, `core-hub/INTENT.md`,
|
||
`core-hub/SCOPE.md`, and `state-hub/SCOPE.md` with a short "Ecosystem
|
||
position" section pointing to the decision doc.
|
||
|
||
Done when all three repos reference the same layer diagram and ownership table.
|
||
|
||
## Task: Normalize domain and naming metadata
|
||
|
||
```task
|
||
id: CUST-WP-0057-T02
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "7d80dd25-7273-4cc9-aca8-77065f513c23"
|
||
```
|
||
|
||
Align repo identity metadata:
|
||
|
||
- hub-core domain slug → `infotech` (library under FOS infra), with `inter_hub`
|
||
topic only where historical workplan IDs require it;
|
||
- add a naming glossary (`hub-core` = library, `core-hub` = production framework,
|
||
`state-hub` = dev coordination) to each repo README;
|
||
- update `.repo-classification.yaml` notes in hub-core and core-hub to reference
|
||
`CUST-WP-0057` and list sibling repos in `relations`.
|
||
|
||
Done when agent instructions in all three repos use the glossary consistently.
|
||
|
||
## Task: Wire reuse-surface capability relations
|
||
|
||
```task
|
||
id: CUST-WP-0057-T03
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "868ba93c-8e69-48e9-8626-98a39b0688e8"
|
||
```
|
||
|
||
Update capability registry entries:
|
||
|
||
- `capability.infotech.hub-core-library` → `supports` state-hub, `related_to` core-hub;
|
||
- `capability.infotech.core-hub` → `depends_on` hub-core-library (utils/contracts),
|
||
`related_to` state-hub workstream-coordinate;
|
||
- add `state-hub` capability entry if missing, with `depends_on` hub-core-library.
|
||
|
||
Sync `registry/indexes/capabilities.yaml` in each repo and run reuse-surface
|
||
federation publish when the operator lane is available.
|
||
|
||
Done when `warden route find "hub ecosystem"` or reuse-surface search surfaces
|
||
the three-repo stack as an intentional composition.
|
||
|
||
## Task: Seed core-hub adoption workplan
|
||
|
||
```task
|
||
id: CUST-WP-0057-T04
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "c8638725-85e9-4bf7-9ba0-245859df299d"
|
||
```
|
||
|
||
Create `core-hub/workplans/CORE-WP-0009-hub-core-adoption-and-integration.md`
|
||
with tasks for:
|
||
|
||
1. Add editable `hub-core` dependency to `pyproject.toml`.
|
||
2. Replace local `slugify()` with `hub_core.utils.slugs`.
|
||
3. Evaluate `hub_core.utils.pagination` for `/api/v2` list endpoints.
|
||
4. Document metadata isolation (separate SQLAlchemy bases) in core-hub architecture spec.
|
||
5. Add contract test proving core-hub + hub-core versions pin together in CI.
|
||
|
||
Done when CORE-WP-0009 exists with `status: ready` and T01–T02 scoped.
|
||
|
||
## Task: Seed state-hub boundary workplan
|
||
|
||
```task
|
||
id: CUST-WP-0057-T05
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "a37b8c2b-7a97-48a9-93f9-21e66c832317"
|
||
```
|
||
|
||
Create `state-hub/workplans/STATE-WP-0074-hub-ecosystem-boundary-alignment.md`
|
||
with tasks for:
|
||
|
||
1. Document which routes are dev-hub-only vs hub-core-factory (audit `api/main.py`).
|
||
2. Define optional read APIs for core-hub to ingest progress/messages without
|
||
duplicating tables (or record deferral with rationale).
|
||
3. Add cross-repo smoke: state-hub progress POST visible to core-hub operator
|
||
evidence contract (if HTTP bridge is chosen).
|
||
4. Confirm State Hub does not grow `/api/v2` Inter-Hub surfaces (core-hub owns those).
|
||
|
||
Done when STATE-WP-0074 exists with `status: ready`.
|
||
|
||
## Task: Shared contract — progress and evidence mapping
|
||
|
||
```task
|
||
id: CUST-WP-0057-T06
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "74a9c81d-867a-4ae9-83cc-5e7beda78fbf"
|
||
```
|
||
|
||
Add `the-custodian/docs/hub-ecosystem-event-mapping.md` defining:
|
||
|
||
- when to emit `ProgressEvent` (state-hub / dev coordination);
|
||
- when to emit `InteractionEvent` (core-hub / widget ops evidence);
|
||
- correlation fields (`subject_refs`, widget_id, hub_slug, workplan_id);
|
||
- activity-core sink expectations for each family.
|
||
|
||
Add fixture examples under `core-hub/contracts/fixtures/` and
|
||
`hub-core/tests/fixtures/` (or custodian docs only if fixtures are premature).
|
||
|
||
Done when ops-hub and activity-core owners can trace an event from dev action →
|
||
production evidence without ambiguous dual-writes.
|
||
|
||
## Task: Shared contract — capability identity bridge
|
||
|
||
```task
|
||
id: CUST-WP-0057-T07
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "69c7db28-5bc8-4f3c-a2ac-84d27133864c"
|
||
```
|
||
|
||
Document how reuse-surface capability IDs (`capability.<domain>.<name>`) map to:
|
||
|
||
- State Hub `capability_catalog` rows;
|
||
- Core Hub `hub_capability_manifests` bodies;
|
||
- reuse-surface registry entries.
|
||
|
||
Deliverable: `the-custodian/docs/hub-ecosystem-capability-bridge.md` plus a
|
||
worked example using `capability.infotech.hub-core-library` and
|
||
`capability.infotech.core-hub`.
|
||
|
||
Done when manifest activation in core-hub can reference a reuse-surface ID
|
||
without inventing a parallel naming scheme.
|
||
|
||
## Task: hub-core library extensions (delegate HUB-WP-0003)
|
||
|
||
```task
|
||
id: CUST-WP-0057-T08
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "64847fc3-9d79-4f6c-8e32-2973f3ce1286"
|
||
```
|
||
|
||
Execute `hub-core/workplans/HUB-WP-0003-ecosystem-consolidation-library-lane.md`:
|
||
|
||
- optional async-friendly base/timestamp re-export seam for core-hub evaluators;
|
||
- `hub_core.utils` coverage for slug/pagination parity tests;
|
||
- `SCOPE.md` "Boundaries with sibling repos" table includes core-hub with
|
||
explicit "framework-only" vs "library" split;
|
||
- bump package version minor when first core-hub consumer merges.
|
||
|
||
Done when HUB-WP-0003 reaches `finished` and core-hub CI imports at least one
|
||
hub-core utility module.
|
||
|
||
## Task: Cross-repo CI pin and regression gate
|
||
|
||
```task
|
||
id: CUST-WP-0057-T09
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "d9dad241-2f3d-4715-873c-7deeac308764"
|
||
```
|
||
|
||
Add a custodian-orchestrated smoke script (or documented Make target chain):
|
||
|
||
```bash
|
||
cd ~/hub-core && uv run pytest -q
|
||
cd ~/state-hub && uv run pytest -q
|
||
cd ~/core-hub && uv run pytest -q
|
||
```
|
||
|
||
Record expected test counts and enforce after each consolidation PR. Optionally
|
||
add a Forgejo workflow matrix that checks out sibling repos as path dependencies.
|
||
|
||
Done when a single documented command sequence is the merge gate for
|
||
CUST-WP-0057 changes.
|
||
|
||
## Task: Closeout — update extraction boundary and bootstrap status
|
||
|
||
```task
|
||
id: CUST-WP-0057-T10
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "4817f404-02a6-4f09-9499-bfb39c7a40f7"
|
||
```
|
||
|
||
Update:
|
||
|
||
- `the-custodian/docs/hub-core-extraction-boundary.md` — add "Ecosystem composition"
|
||
section referencing core-hub framework exclusives;
|
||
- `the-custodian/docs/fos-hub-bootstrap-sequence-status.md` — add consolidation
|
||
lane status under CUST-WP-0057;
|
||
- mark open questions in `core-hub/docs/specs/data-model.md` resolved or explicitly
|
||
deferred with ADR links.
|
||
|
||
Done when a new agent orienting from custodian docs sees hub-core, state-hub,
|
||
and core-hub as one stack, not competing alternatives.
|
||
|
||
## Success criteria
|
||
|
||
- hub-core, core-hub, and state-hub each have a clear one-paragraph ecosystem
|
||
position in INTENT/SCOPE.
|
||
- core-hub depends on hub-core for at least shared utilities; no new duplicate
|
||
slug/pagination helpers without justification.
|
||
- Canonical owners are documented for workplans, `/api/v2` framework entities,
|
||
and dev coordination tables.
|
||
- Capability registry relations link the three repos.
|
||
- Full pytest regression passes in all three repos after each consolidation slice.
|
||
|
||
## Non-goals
|
||
|
||
- Merging repos or renaming `hub-core` / `core-hub` (glossary only).
|
||
- Moving State Hub workplan tables into core-hub.
|
||
- Replacing core-hub `/api/v2` with state-hub routes.
|
||
- Publishing hub-core to PyPI (editable/path dependency remains fine).
|
||
- Absorbing core-hub operator console into hub-core. |