the-custodian/workplans/CUST-WP-0057-hub-ecosystem-consolidation.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CUST-WP-0057	workplan	Hub ecosystem consolidation — hub-core, core-hub, state-hub alignment	infotech	the-custodian	finished	codex	custodian	2026-07-09	2026-07-11	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

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

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

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

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

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

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

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)

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

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):

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

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.