feat: add hub runtime and extension contract

docs/runtime.md

@@ -0,0 +1,88 @@
+# 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.
+
+## Processes
+
+The `runtime` dependency extra installs one `hub-core` command with three
+process modes:
+
+```bash
+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://...
+```
+
+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`. T04 ships
+`InMemoryPortStore` for deterministic tests and local contract smokes. It is
+ephemeral and is not a production authority.
+
+`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:
+
+```text
+HUB_CORE_ENV=production
+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
+`HUB_CORE_ALLOW_EPHEMERAL=1`.
+
+## 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.
+
+```bash
+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`.