feat: add hub runtime and extension contract
This commit is contained in:
parent
fce19f193f
commit
7e1ec03f0c
44 changed files with 3875 additions and 84 deletions
|
|
@ -6,7 +6,7 @@ domain: inter_hub
|
|||
repo: hub-core
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: inter_hub
|
||||
topic_slug: custodian
|
||||
created: "2026-06-16"
|
||||
updated: "2026-06-22"
|
||||
state_hub_workstream_id: "4a31e8cd-1a06-40bf-abc9-76ca9ac173f2"
|
||||
|
|
@ -68,4 +68,4 @@ make fix-consistency REPO=hub-core
|
|||
Completed 2026-06-22: seeded
|
||||
`workplans/HUB-WP-0002-import-refactor-adapter-seams.md` to close the
|
||||
remaining CUST-WP-0048 adapter seams (capability request writes, MCP
|
||||
composition, regression handoff).
|
||||
composition, regression handoff).
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ domain: inter_hub
|
|||
repo: hub-core
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: inter_hub
|
||||
topic_slug: custodian
|
||||
created: "2026-06-22"
|
||||
updated: "2026-06-22"
|
||||
state_hub_workstream_id: "439b559b-fcb7-4d21-b831-cfc9c6bbc1a0"
|
||||
|
|
@ -82,4 +82,4 @@ After T01–T02 land (or are explicitly deferred with documented seams):
|
|||
|
||||
Completed 2026-06-22: hub-core 27 tests pass; state-hub capability tests pass
|
||||
(20/20) and full suite 352/353 (one pre-existing health-route flake).
|
||||
Extraction boundary updated.
|
||||
Extraction boundary updated.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ domain: infotech
|
|||
repo: hub-core
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: infotech
|
||||
topic_slug: custodian
|
||||
created: "2026-07-09"
|
||||
updated: "2026-07-11"
|
||||
state_hub_workstream_id: "ee4f1eef-3a26-4af3-b735-f0c1c638656f"
|
||||
|
|
@ -148,4 +148,4 @@ When `core-hub` merges hub-core utils import (CORE-WP-0009 T02):
|
|||
- add CHANGELOG entry listing utils adoption and ecosystem consolidation;
|
||||
- verify `uv run pytest -q` still passes.
|
||||
|
||||
Done when core-hub CI pins the new hub-core version and both test suites are green.
|
||||
Done when core-hub CI pins the new hub-core version and both test suites are green.
|
||||
|
|
|
|||
|
|
@ -4,11 +4,11 @@ type: workplan
|
|||
title: "Runtime consolidation and extension contract"
|
||||
domain: infotech
|
||||
repo: hub-core
|
||||
status: proposed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: infotech
|
||||
topic_slug: custodian
|
||||
created: "2026-08-09"
|
||||
updated: "2026-08-20"
|
||||
updated: "2026-08-21"
|
||||
parent_project: prj-state-hub-retirement
|
||||
parent_workplan: SHR-WP-0001
|
||||
related:
|
||||
|
|
@ -35,7 +35,7 @@ Coordinated by `prj-state-hub-retirement` (SHR-WP-0001). Architecture:
|
|||
|
||||
```task
|
||||
id: HUB-WP-0004-T01
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "47b879ac-bfb4-48c2-8fd8-c29045df6900"
|
||||
```
|
||||
|
|
@ -43,11 +43,35 @@ state_hub_task_id: "47b879ac-bfb4-48c2-8fd8-c29045df6900"
|
|||
Review and accept SHR-ARCH-IA-0001 and SHR-ARCH-HUB-0001 as the vocabulary for
|
||||
ports, kinds, and extension packages. Record gaps as tasks, not silent drift.
|
||||
|
||||
Completed 2026-08-21. Hub-core accepts the two project artefacts as the
|
||||
normative v0.1 vocabulary for this workplan:
|
||||
|
||||
- authority and projection remain distinct; repository work stays authoritative
|
||||
in Git and is reached through repo-manager;
|
||||
- messages/conversations, progress events, interaction events, telemetry, and
|
||||
domain events remain distinct information families joined by correlation;
|
||||
- hub-core is the surviving framework/runtime and owns the named `port.*`
|
||||
contracts, while domain hubs, functional components, and authoritative
|
||||
services retain the boundaries defined by `SHR-ARCH-HUB-0001`;
|
||||
- `helixforge.hub-extension` descriptors, manifests, event catalogs, fixtures,
|
||||
and compatibility rules are the Tier 1 contract target.
|
||||
|
||||
The accepted freeze is reflected in `INTENT.md` and `SCOPE.md`. Open questions
|
||||
are assigned rather than silently deferred:
|
||||
|
||||
| Gap / decision | Owning task |
|
||||
| --- | --- |
|
||||
| Descriptor, manifest authority, widgets/operator surfaces | T02 |
|
||||
| Primary image vs permanent thin host; MCP packaging | T03 |
|
||||
| Named port implementations, conversation support, missing interaction/projection surfaces | T04 |
|
||||
| Tenant isolation and Tier 2/3 enforcement | T05 |
|
||||
| Topic/work boundary and `/api/v2` migration order | T06 with CORE-WP-0010 |
|
||||
|
||||
## Ship extension contract Tier 1 artefacts
|
||||
|
||||
```task
|
||||
id: HUB-WP-0004-T02
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "eac82a0b-48b9-4097-afa6-a9e730de7789"
|
||||
```
|
||||
|
|
@ -56,11 +80,25 @@ Publish versioned hub descriptor schema, manifest schema, event-type catalog
|
|||
schema, and port OpenAPI fragments for `helixforge.hub-extension` 0.1+, plus a
|
||||
sample hub fixture. Align with `hub-extension-contract_v0.1.yaml`.
|
||||
|
||||
Completed 2026-08-21. The wheel now packages
|
||||
`hub_core.contracts.helixforge_hub_extension.v0_1_0` with:
|
||||
|
||||
- Draft 2020-12 hub descriptor, manifest, and event-type catalog schemas;
|
||||
- OpenAPI 3.1 fragments covering all 11 named `port.*` interfaces;
|
||||
- an initial four-family event catalog and non-secret ops-hub fixture;
|
||||
- an explicit 0.1.0 compatibility matrix, including the temporary Core Hub
|
||||
manifest adapter; and
|
||||
- automated schema, catalog, fixture, port-coverage, compatibility, and
|
||||
secret-field checks in `tests/test_contracts.py`.
|
||||
|
||||
Focused validation passed (8 tests), and a built `hub_core-0.2.0` wheel was
|
||||
inspected to confirm every contract artefact is shipped.
|
||||
|
||||
## Define runtime packaging decision
|
||||
|
||||
```task
|
||||
id: HUB-WP-0004-T03
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "f149096d-74f2-4c5a-8907-f81cba8e3edb"
|
||||
```
|
||||
|
|
@ -69,11 +107,18 @@ Record whether hub-core ships a primary runtime image (recommended) with the
|
|||
library remaining importable, vs library + permanent thin host. Decision before
|
||||
absorbing core-hub routes.
|
||||
|
||||
Completed 2026-08-21. `docs/adr/ADR-0001-runtime-packaging.md` selects one
|
||||
hub-core release lineage with an importable Python wheel and a primary runtime
|
||||
OCI image built from this repository. API, MCP, and migration jobs may be
|
||||
separate processes from that image. A permanent thin-host repository is
|
||||
rejected; core-hub remains only as the dual-run rollback runtime until its
|
||||
routes, data, contracts, and fixtures are absorbed.
|
||||
|
||||
## Implement core ports (minimal vertical)
|
||||
|
||||
```task
|
||||
id: HUB-WP-0004-T04
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "fa4db2f7-0e86-4a41-8469-a8704d9c2a46"
|
||||
```
|
||||
|
|
@ -82,11 +127,36 @@ Expose minimal working surfaces for `port.registry`, `port.messaging`,
|
|||
`port.events.progress`, `port.events.interaction`, and `port.projection.query`
|
||||
sufficient for dual-run and conformance scaffolding.
|
||||
|
||||
Implement the minimal application factory, runtime dependency group, process
|
||||
commands, health/readiness surface, and primary image scaffold selected by
|
||||
ADR-0001 alongside these ports.
|
||||
|
||||
Completed 2026-08-21. `hub_core.runtime` now provides an injectable FastAPI
|
||||
application and `PortStore` boundary with a deterministic in-memory conformance
|
||||
backend. The vertical implements contract-valid, idempotent registry writes;
|
||||
addressed messages/conversations; catalog-enforced and physically separate
|
||||
progress and interaction event sinks; and provenance-bearing projections.
|
||||
|
||||
The `hub-core` console entrypoint starts API and MCP processes or packaged
|
||||
Alembic migrations. The runtime extra is locked in `uv.lock`. `Containerfile`
|
||||
builds that frozen dependency set, runs as UID/GID 10001, labels version and
|
||||
revision, and defaults to fail-closed readiness while only the ephemeral store
|
||||
exists. `docs/runtime.md` records the boundary and commands.
|
||||
|
||||
Validation evidence:
|
||||
|
||||
- focused contract/runtime tests pass;
|
||||
- local API and MCP process smokes pass;
|
||||
- packaged migration head resolves as `0001_core_schema`;
|
||||
- the locked OCI image builds and passes health, opted-in readiness, and
|
||||
ops-hub contract registration; and
|
||||
- production-mode memory readiness returns 503 unless explicitly allowed.
|
||||
|
||||
## Conformance harness scaffold
|
||||
|
||||
```task
|
||||
id: HUB-WP-0004-T05
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "6f8fb0e8-8b9b-4c37-ae62-0748dd0e5975"
|
||||
```
|
||||
|
|
@ -95,11 +165,26 @@ Scaffold Tier 2/3 automated checks (schema validate, no-secrets, event family
|
|||
separation, projection rebuild fixture). Full green suite may continue under
|
||||
follow-on WPs.
|
||||
|
||||
Completed 2026-08-21. `hub_core.conformance` now drives a public HTTP target
|
||||
through an implementation-neutral client protocol. The initial green profile
|
||||
automates Tier 2 checks C1, C3, C4, C5, C6, and C8 plus Tier 3 checks F2 and F3.
|
||||
It validates the packaged schemas and catalog, rejects secret-shaped fixture
|
||||
material, exercises health and idempotent activation with correlation
|
||||
propagation, rejects wrong-family/uncataloged events, proves family separation,
|
||||
and verifies authority-derived projections with rebuild-source declarations and
|
||||
provenance hashes.
|
||||
|
||||
The wheel ships `fixtures/projection-rebuild.json`; `hub-core conformance`
|
||||
supports human-readable or JSON results against an isolated remote runtime.
|
||||
`docs/conformance.md` explicitly records uncovered requirements and tenant
|
||||
isolation as open rather than treating absent checks as passing. The reference
|
||||
runtime passes all eight implemented checks over a live HTTP process.
|
||||
|
||||
## Absorption plan with core-hub
|
||||
|
||||
```task
|
||||
id: HUB-WP-0004-T06
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b35fff11-ac5a-4d70-9f54-416331baea87"
|
||||
```
|
||||
|
|
@ -107,6 +192,24 @@ state_hub_task_id: "b35fff11-ac5a-4d70-9f54-416331baea87"
|
|||
With CORE-WP-0010, document route/module move order for `/api/v2`, dual-run, and
|
||||
cutover criteria. No big-bang.
|
||||
|
||||
Completed 2026-08-21. `docs/core-hub-absorption-plan.md` reconciles Core Hub's
|
||||
finished runtime inventory, its current railiance01 production/rollback state,
|
||||
all 22 checked-in OpenAPI paths, seven durable tables, both production
|
||||
consumers, and the project retirement gates.
|
||||
|
||||
The accepted plan uses six governed capability slices after a durable-runtime
|
||||
foundation. It requires isolated legacy/candidate schemas, exactly one writer
|
||||
per route group, read-only shadow comparison, per-slice count/hash/provenance
|
||||
and authorization evidence, ops-hub and activity-core smokes, reverse-delta
|
||||
rollback rehearsal, explicit operator approval for production writer changes,
|
||||
and a seven-day final stabilization window before Core Hub retirement. The
|
||||
compatibility credential shim and empty collection adapters receive explicit
|
||||
residual gates rather than becoming silent permanent authorities.
|
||||
|
||||
State Hub decision `12514947-6cc0-42a0-98ca-9aacc9d875b0` records the
|
||||
single-writer slice design. Message `819d5af0-959f-4b0d-9f52-87514d99b480`
|
||||
hands the plan to `core-hub` for the file-backed CORE-WP-0010-T02 transition.
|
||||
|
||||
## Readiness review (2026-08-20)
|
||||
|
||||
Reviewed against current repo state at the request of `STATE-WP-0079`, which is
|
||||
|
|
@ -154,9 +257,9 @@ the owner to flip.*
|
|||
|
||||
## Acceptance
|
||||
|
||||
- [ ] Architecture freeze acknowledged in INTENT/SCOPE
|
||||
- [ ] Tier 1 contract artefacts published and versioned
|
||||
- [ ] Runtime packaging decision recorded
|
||||
- [ ] Core ports have a minimal implementable surface
|
||||
- [ ] Conformance harness scaffold exists
|
||||
- [ ] Absorption plan linked to CORE-WP-0010
|
||||
- [x] Architecture freeze acknowledged in INTENT/SCOPE
|
||||
- [x] Tier 1 contract artefacts published and versioned
|
||||
- [x] Runtime packaging decision recorded
|
||||
- [x] Core ports have a minimal implementable surface
|
||||
- [x] Conformance harness scaffold exists
|
||||
- [x] Absorption plan linked to CORE-WP-0010
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue