coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
the-custodian/docs/hub-ecosystem-architecture.md
codex aab187937b
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 5s
Details
docs(ecosystem): complete hub stack consolidation (CUST-WP-0057) 
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.
2026-07-11 01:26:53 +02:00

4.8 KiB
Raw Blame History

Hub Ecosystem Architecture

Updated: 2026-07-09
Workplan: CUST-WP-0057
Status: Active decision record

Purpose

Define how hub-core, state-hub, and core-hub compose into one FOS hub stack. This document resolves naming confusion and entity ownership without merging repositories.

Three-layer model

Layer Repo Role Production URL
Library hub-core Shared models, schemas, router factories, MCP wrapper, utils None — pip/uv import only
Dev coordination state-hub File-first workplans, tasks, decisions, consistency sync, dev MCP Local / operator (127.0.0.1:8000)
Production framework core-hub Inter-Hub successor: hubs, manifests, widgets, /api/v2, operator console hub.coulomb.social 
                    ┌─────────────────┐
                    │    core-hub     │  Production framework (/api/v2)
                    │  (async service)│
                    └────────┬────────┘
                             │ imports utils; HTTP bridge to dev data (future)
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
       ┌────────────┐  ┌────────────┐  ┌────────────┐
       │  hub-core  │◄─│ state-hub  │  │  ops-hub   │
       │  (library) │  │ (dev host) │  │ (consumer) │
       └────────────┘  └────────────┘  └────────────┘

Naming glossary

Name What it is What it is not
hub-core Python package hub_core — library boundary A running hub service
core-hub Production interaction framework service The shared library
state-hub Dev coordination host (State Hub / dev-hub) The Inter-Hub /api/v2 framework

Mnemonic: hub-core = core primitives; core-hub = core framework runtime.

Canonical entity ownership

Entity family Canonical owner Notes
domains, managed_repos (registry) hub-core models; state-hub host core-hub uses hubs table — see capability bridge doc
agent_messages hub-core + state-hub core-hub does not duplicate; reads via State Hub API when needed
progress_events hub-core + state-hub Dev coordination audit trail
interaction_events core-hub Widget-scoped ops evidence (/api/v2/interaction-events)
capability_catalog, capability_requests hub-core + state-hub Maturity and workflow lane
hub_capability_manifests core-hub Inter-Hub manifest contract
hubs, widgets, api_consumers, api_keys core-hub Framework registry only
workplans, tasks, decisions state-hub File-first authority; core-hub may index later
tpsc_*, policy documents hub-core + state-hub core-hub references evidence, does not reimplement
Slug/pagination/path utils hub-core All hosts import; no local duplicates

Governing decisions

  1. Compose, do not merge — three repos remain; shared code moves into hub-core.
  2. hub-core stays a library — no uvicorn entrypoint, no K8s manifests.
  3. core-hub owns /api/v2 — Inter-Hub compatibility is non-negotiable for ops-hub and activity-core.
  4. state-hub owns dev coordination — workplan files remain source of truth until a recorded ADR says otherwise.
  5. Separate SQLAlchemy metadata — each runtime keeps its own Base; router factories inject host models.
  6. Incremental adoption — core-hub adopts hub-core utilities first; framework models stay local.

Integration contracts

From To Mechanism Status
state-hub hub-core Editable package import Done (CUST-WP-0048)
core-hub hub-core Editable package import (utils) In progress (CORE-WP-0009)
core-hub state-hub HTTP read APIs for progress/messages Deferred (STATE-WP-0070)
ops-hub core-hub /api/v2 bootstrap Production
Agents state-hub dev-hub MCP Production
Operators core-hub Operator CLI + console Production

See also:

  • hub-ecosystem-event-mapping.md — progress vs interaction events
  • hub-ecosystem-capability-bridge.md — catalog vs manifest IDs
  • hub-core-extraction-boundary.md — library extraction history

Non-goals

  • Renaming hub-core or core-hub repositories
  • Moving State Hub workplan tables into core-hub in this lane
  • Replacing core-hub /api/v2 with state-hub routes
  • Publishing hub-core to public PyPI (path/editable deps remain fine)