Hub Core runtime

The runtime implements the packaging decision in ADR-0001, the minimal vertical in HUB-WP-0004-T04, and the durable Core Hub absorption boundary in HUB-WP-0005. Public authority still moves only through the gated deployment slices in the accepted absorption plan.

Processes

The runtime dependency extra installs one hub-core command with three process modes:

uv sync --extra runtime
hub-core api --host 127.0.0.1 --port 8010
hub-core mcp --host 127.0.0.1 --port 8011 --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://...
hub-core migration export --database-url postgresql+asyncpg://... --output reverse-delta.json

The migration command converts the async PostgreSQL URL for the packaged synchronous Alembic environment. Production must run migrations explicitly; the API does not auto-create tables.

Runtime ports

Port	Initial path	Behavior
`port.registry`	`POST /ports/registry/registrations`	Validates and idempotently records a descriptor/manifest package
`port.messaging`	`GET/POST /ports/messaging/messages`	Addressed messages with optional conversation identity
`port.events.progress`	`POST /ports/events/progress`	Accepts only cataloged progress-family events
`port.events.interaction`	`POST /ports/events/interaction`	Accepts only cataloged interaction-family events
`port.projection.query`	`GET /ports/projections/{id}`	Rebuildable registry/message/event projections with provenance

Available projection ids are hub_registry, messages, progress_events, and interaction_events. The two event families use distinct stores and cannot be submitted through each other's endpoint.

Backend boundary and readiness

The app is created with an injected PortStore. InMemoryPortStore remains available for deterministic tests and local contract smokes. Production uses PostgresPortStore, whose registration, messaging, progress, interaction, compatibility, import-lineage, and audit records are transactionally durable.

GET /healthz proves the process is alive. GET /readyz fails with HTTP 503 when the active backend does not match HUB_CORE_BACKEND, or when the memory backend is used without explicit permission. Development and test permit it by default; the OCI image sets production-safe defaults:

HUB_CORE_ENV=production
HUB_CORE_BACKEND=memory
HUB_CORE_ALLOW_EPHEMERAL=0

Set HUB_CORE_BACKEND=postgresql and HUB_CORE_DATABASE_URL in production. Readiness checks the database and continues to fail closed if the selected backend is unavailable. A local image smoke may opt in to memory with HUB_CORE_ALLOW_EPHEMERAL=1.

The compatibility adapter is enabled by coherent route groups in HUB_CORE_V2_GROUPS; writes require the corresponding value in HUB_CORE_V2_WRITE_GROUPS. Startup rejects overlap with CORE_HUB_V2_WRITE_GROUPS. Supported groups are system, registry, credentials, interaction, and deferred. Static operator authentication uses HUB_CORE_API_TOKEN; imported consumer keys are verified by hash.

Migration bundles cover all seven Core Hub source tables. They preserve stable IDs and timestamps, reject secret-shaped material and digest drift, record counts/identity sets/canonical hashes, and return the original import-run ID when the same bundle is replayed. Reverse export contains prefixes and hashes, never raw keys.

OCI image

The Containerfile uses uv.lock with uv sync --frozen, installs the runtime extra, runs as UID/GID 10001, includes OCI version/revision labels, and exposes API port 8010 plus MCP port 8011.

docker build -f Containerfile \
  --build-arg VERSION=0.2.0 \
  --build-arg VCS_REF="$(git rev-parse HEAD)" \
  -t hub-core:dev .

docker run --rm -p 8010:8010 \
  -e HUB_CORE_ALLOW_EPHEMERAL=1 \
  hub-core:dev

Deployment charts, secrets, rollout policy, and live evidence remain owned by the rapp/platform repositories. /api/v2 data and compatibility routes remain on Core Hub until the T06/CORE-WP-0010 dual-run slices move them.

Conformance

The public-port Tier 2/3 scaffold is documented in docs/conformance.md. Run it against an isolated runtime with hub-core conformance --base-url <url>.

Core Hub absorption

docs/core-hub-absorption-plan.md defines the capability-sized /api/v2 route and data move order, single-writer dual-run controls, evidence gates, rollback, and final cutover criteria shared with CORE-WP-0010.

4.6 KiB Raw Blame History