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:

```text
/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.

```python
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:

```bash
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.
- Explicit, attributable legacy message identity aliases that preserve the
  canonical message row and never guess malformed references.
- 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.