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

1. **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.
2. **How do hubs expose them consistently?** Factory-based FastAPI routers and
   matching MCP tools with dependency injection at the host boundary.
3. **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.