tegwick
986ac4d40b
Extract the first reusable slice (models, schemas, routers, MCP, migrations) from state-hub with INTENT/SCOPE, agent instructions, workplan, and aligned inter_hub capability registry index.
5.2 KiB
INTENT — hub-core
Project: hub-core
Domain: inter_hub
Status: Active extraction (CUST-WP-0025)
Updated: 2026-06-16
One-line intent
hub-core provides reusable FastAPI, SQLAlchemy, and MCP primitives so multiple
FOS hub services can share a common foundation without importing each other's
domain-specific coordination models.
Why it exists
Custodian and helix_forge ecosystems need more than one hub-shaped service:
development coordination (state-hub), operations (ops-hub), finance, and
future domain hubs. Those services repeat the same patterns — domain registry,
managed repositories, agent messaging, progress telemetry, capability catalog
surfaces, third-party service catalog (TPSC), policy lookup, and MCP
orientation tools.
Without hub-core, each hub would duplicate SQLAlchemy models, Pydantic
contracts, router mounting, pagination helpers, and MCP wrappers. That leads to
schema drift, incompatible agent tools, and expensive extractions every time a
second hub appears.
hub-core exists to extract the generic hub substrate once and let each hub
package own only its domain-specific tables, workflows, and policies.
Governing principle
Hub-core is a library, not a hub.
It ships models, schemas, router factories, migration scaffolds, utilities, and
an optional FastMCP base server. A consuming repository (for example
state-hub) wires database sessions, auth, host-specific callbacks, and
domain-only routes into those factories.
hub-core should answer:
- What primitives do all FOS hubs share? Domains, repos, messages, progress events, capability catalog/request read paths, TPSC catalog/snapshots, policy lookup, canonical risk/alert event types.
- How do hubs expose them consistently? Factory-based FastAPI routers and matching MCP tools with dependency injection at the host boundary.
- How do hubs evolve schema together? Shared Alembic templates and a documented core-schema migration adopters can extend.
It should not answer dev-hub questions such as which workstream is blocked,
which task needs human review, or how kaizen agents spawn maintenance work. Those
remain in state-hub and other host implementations.
What it is
hub-core is the shared Python package for FOS hub services.
Current package surface (hub_core/):
| Area | Responsibility |
|---|---|
models/ |
SQLAlchemy base, domains, managed repos, agent messages, capability catalog/requests, progress events, TPSC |
schemas/ |
Pydantic contracts matching core models plus DoI report shapes |
routers/ |
Factory functions: domains, repos, messages, progress, capabilities, TPSC, policy |
mcp/ |
HubCoreMCPServer — generic orientation, messaging, capability, repo, DoI, TPSC/GDPR, risk/alert, progress tools |
migrations/ |
Alembic scaffold and 0001_core_schema for adopters |
utils/ |
Slugs, pagination, repo path resolution, trailing-slash routing |
events.py |
Canonical FOS §10 risk and alert event types |
Hosts mount only the routers they need and inject their own Session providers,
models where extended, and workflow callbacks.
What it is not
| Concern | Owner |
|---|---|
| Running production hub deployment | state-hub, ops-hub, future hubs |
| Topics, workstreams, tasks, decisions, SBOM, token accounting | state-hub (dev-hub layer) |
| Custodian canon, constitution, domain charters | the-custodian |
| Event-triggered maintenance task creation | activity-core |
| General issue/task lifecycle outside Custodian workplans | issue-core |
| Capability reuse registry and federation compose | reuse-surface |
| Network tunnels and remote operations | ops-bridge |
hub-core may define generic capability catalog and request read
primitives, but workflow side effects (task unblocking, dispute resolution,
acceptance flows) stay in the host hub.
Primary consumers
| Consumer | Relationship |
|---|---|
state-hub |
First adopter; incremental import of schemas, routers, MCP (CUST-WP-0025 T08+) |
ops-hub |
Planned consumer of shared primitives without dev-hub tables |
| Future FOS hubs | Fin-hub and domain hubs mount subsets of hub-core factories |
Extraction boundary and migration status:
/home/worsch/the-custodian/docs/hub-core-extraction-boundary.md
Success criteria
hub-core succeeds when:
- a new hub can register domains and repos using hub-core routers without copying SQLAlchemy models
- State Hub pytest suite passes with hub-core as an editable dependency
- MCP tools for orientation, messages, progress, and TPSC behave consistently across hosts that opt in
- schema changes to shared primitives are versioned through hub-core migrations, not ad hoc forks
- dev-hub-specific foreign keys never appear in hub-core models (extension via host callbacks or JSON context fields)
Non-goals
- Replacing FastAPI, SQLAlchemy, or FastMCP
- Owning PostgreSQL instance provisioning for any environment
- Becoming a general application framework unrelated to hub-shaped services
- Absorbing reuse-surface capability maturity registry semantics
Working mantra
Extract once what every hub needs; keep domain drama in the hub that owns it.