hub-core/README.md

Hub Core

Contracts, reusable Python primitives, and the surviving runtime for HelixForge hubs.

Hub stack glossary

Name	Role
hub-core	This repo — importable package plus target primary runtime image
state-hub	Legacy coordination host being replaced capability by capability
core-hub	Previous /api/v2 runtime retained temporarily as live rollback

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

Runtime packaging is fixed by docs/adr/ADR-0001-runtime-packaging.md: the wheel remains importable, while this repository will also own the primary OCI image. API, MCP, and migration workloads may run separately from that same image. Core-hub is not a permanent thin host.

hub-core is being extracted from the standalone State Hub repository as part of CUST-WP-0025. The initial package slice contains only the generic database models and schemas that can move without importing dev-hub concepts such as topics, workplans, tasks, decisions, SBOM, or token accounting.

Source boundary notes live in:

/home/worsch/the-custodian/docs/hub-core-extraction-boundary.md

Extension contract

The wheel includes helixforge.hub-extension 0.1.0 under hub_core.contracts. Use extension_contract_root() to locate the packaged descriptor and manifest schemas, event catalog schema and seed, named-port OpenAPI fragments, ops-hub fixture, and compatibility matrix.

from hub_core.contracts import CONTRACT_VERSION, extension_contract_root

contract_root = extension_contract_root()

The wheel also includes the frozen helixforge.repository-navigation 1.0.0 receiving and query contract. Its packaged schemas, fixtures, compatibility matrix, and read-only OpenAPI surface are located with repository_navigation_contract_root(); normative rebuild and cursor rules are in docs/repository-navigation-contract.md.

helixforge.workload-projection 1.0.0 transports Repo Manager's authoritative workload index through a separate injected port.repo reader. The runtime offers GET-only list and exact-reference resolution at /ports/projections/workloads, plus matching MCP tools, without importing Repo Manager internals or inferring workload identity.

Runtime scaffold

Install the runtime extra and start the API, MCP, or migration process through the shared console entrypoint:

uv sync --extra runtime
hub-core api
hub-core mcp --api-base http://127.0.0.1:8010
hub-core migrate head --database-url postgresql+asyncpg://...
hub-core migration validate core-hub-export.json
hub-core migration import core-hub-export.json --database-url postgresql+asyncpg://...

The runtime exposes registry, messaging, progress-event, interaction-event, and projection-query ports, plus the governed Core Hub /api/v2 compatibility surface. Its PostgreSQL backend includes migrations, audit, and idempotent seven-table migration tooling. The memory backend remains for local/conformance use and fails production readiness unless explicitly enabled. See docs/runtime.md.

The reusable Tier 2/3 scaffold is documented in docs/conformance.md and runs against any compatible HTTP target with hub-core conformance --base-url <url>.

The staged Core Hub transition is defined in docs/core-hub-absorption-plan.md; it keeps one writer per capability and retains Core Hub as rollback until data, consumer, and stabilization gates close.

Production authority moved to hub-core on 2026-08-21. The public compatibility surface runs the immutable 055cf49 image while Core Hub remains deployed with an empty writer set through the seven-day stabilization window ending no earlier than 2026-08-28T20:49:50+02:00.

Repository classification remains authoritative in each repository and is validated/projected by Repo Manager. Hub-core consumes that versioned projection for cross-domain navigation under docs/adr/ADR-0002-repository-classification-projections.md; it does not own a mutable topic or classification write surface. Implementation and A5 handoff are tracked in HUB-WP-0006.

First Slice

• SQLAlchemy base metadata and timestamp helpers.
• Domain and managed-repository registry primitives.
• Agent message inbox primitives.
• Progress-event and capability-request primitives with generic JSON context fields for hub-specific references.
• Third-party service catalog and snapshot primitives.
• Matching Pydantic schemas for those primitives.
• Generic DoI report and summary schemas used by the MCP DoI tools.
• Router factory functions for domains, repos, messages, policy lookup, and progress, capability, and TPSC catalog/snapshot/report endpoints.
• Canonical FOS §10 risk and alert event types with /progress/risks and /progress/alerts read views.
• Shared utility helpers for slugs, pagination, repo path resolution, and trailing-slash path normalization.
• Alembic templates plus an initial core-schema migration for hub adopters.
• FastMCP base-server wrapper for generic orientation, messaging, capability, repo, DoI, TPSC/GDPR, risk/alert, and progress tools.
• Packaged helixforge.hub-extension 0.1.0 Tier 1 schemas, OpenAPI port fragments, event catalog, compatibility matrix, and ops-hub fixture.
• Packaged helixforge.repository-navigation 1.0.0 schemas, fixtures, compatibility policy, and read-only projection query contract.
• Injectable primary runtime scaffold with five named ports, health/readiness, API/MCP/migration commands, and a locked non-root OCI image.

Domain-specific MCP tools follow in each hub package.