# 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 `helixforge.hub-extension` schemas, named-port OpenAPI, catalogs, fixtures, compatibility | | `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 | |---|---| | 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.