coulomb/hub-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: add durable Core Hub absorption runtime
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details

Browse source
This commit is contained in:
tegwick 2026-08-21 16:16:42 +02:00
parent 7e1ec03f0c
commit 8ab1d0c09a
20 changed files with 2423 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/runtime.md
View file

@ -1,8 +1,9 @@
# Hub Core runtime
The initial runtime scaffold implements the packaging decision in ADR-0001 and
the minimal vertical in `HUB-WP-0004-T04`. It is a conformance and absorption
base, not yet the production replacement for Core Hub.
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
@ -14,6 +15,9 @@ 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
@ -36,9 +40,10 @@ submitted through each other's endpoint.
## Backend boundary and readiness
The app is created with an injected `PortStore`. T04 ships
`InMemoryPortStore` for deterministic tests and local contract smokes. It is
ephemeral and is not a production authority.
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
@ -51,10 +56,24 @@ HUB_CORE_BACKEND=memory
HUB_CORE_ALLOW_EPHEMERAL=0
```
Therefore the image is deliberately not production-ready until a durable
backend lands in an absorption slice. A local image smoke may opt in with
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