hub-core/INTENT.md

# INTENT — hub-core

**Project:** `hub-core`  
**Domain:** `infotech`  
**Status:** Active — production hub framework and runtime
**Updated:** 2026-08-22

---

## One-line intent

`hub-core` provides the contracts, reusable primitives, and surviving runtime
for HelixForge hubs without absorbing domain authorities or repository-owned
work records.

---

## Ecosystem position

`hub-core` is the **surviving framework and runtime** in the consolidating
three-repo hub stack:

| Repo | Role |
| --- | --- |
| `hub-core` | Shared Python package plus target framework/runtime — this repo |
| `state-hub` | Legacy coordination host; capabilities move or retire incrementally |
| `core-hub` | Previous `/api/v2` runtime; retained temporarily as rollback before archive |

Canon: `/home/worsch/the-custodian/docs/hub-ecosystem-architecture.md`

**Transition naming:** `hub-core` is the surviving product name. `core-hub`
names the current service being absorbed; keep the distinction only while the
compatibility and cutover work remains.

---

## 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 the framework and runtime substrate, not a domain hub or a
> repository authority.**

Today it ships models, schemas, router factories, migration scaffolds,
utilities, and an optional FastMCP base server. Under
`SHR-ARCH-HUB-0001`, those importable surfaces remain while hub-core grows into
the surviving runtime. `ADR-0001` selects a primary OCI image built from this
repository while keeping the wheel importable; that packaging must not move
domain authority into hub-core.

`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 workplan 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 and target runtime** for HelixForge
hub composition.

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 |
| `contracts/` | Packaged hub-extension, repository-navigation, and workload-projection schemas, OpenAPI, fixtures, compatibility |
| `migrations/` | Alembic core/runtime scaffold plus durable repository and workload projection migrations |
| `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 |
|---|---|
| Repository-owned workplans, tasks, decisions, and consistency | `repo-manager` over Git authority |
| Repository classification validation and repository projection | `repo-manager` over `.repo-classification.yaml` authority |
| Domain-specific business data and APIs | Domain hubs and specialized services |
| 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` | Compatibility source during incremental capability cutover |
| `core-hub` | Rollback source during stabilization; archive after CORE-WP-0010 closes |
| `ops-hub`, `fin-hub`, future hubs | Domain/aspect extensions using versioned hub-core ports and manifests |

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
- the surviving runtime exposes versioned `helixforge.hub-extension` ports and projections
- schema changes to shared primitives are versioned through hub-core migrations, not ad hoc forks
- repository work authority and domain-specific business models never migrate into hub-core
- cross-domain navigation is rebuilt from versioned owner projections with provenance

---

## 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
- Owning Git mutation, work-record reconciliation, authorization decisions, secrets, or scheduling

---

## Working mantra

> Centralize the hub contract; keep every authority with the component or
> domain that owns it.