coulomb/hub-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hub-core/README.md
tegwick 6288ba3d7d
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details
docs: accept repository classification boundary 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49
2026-08-22 00:12:03 +02:00

4.7 KiB
Raw Blame History

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()

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.
  • 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.