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.