hub-core/docs/conformance.md

Hub-extension conformance

hub_core.conformance is the reusable Tier 2/3 harness scaffold for contract version 0.1.0. It drives only public HTTP ports, so a FastAPI TestClient, an httpx.Client, or another compatible target can be used without importing the runtime implementation.

The harness mutates its target. Run it against a disposable instance or a dedicated test namespace:

hub-core api --host 127.0.0.1 --port 8010
hub-core conformance --base-url http://127.0.0.1:8010
hub-core conformance --base-url http://127.0.0.1:8010 --json

Implemented profile

ID	Tier	Automated evidence
C1	2	Packaged descriptor, manifest, and catalog validate against Draft 2020-12 schemas
C3	2	Runtime health probe returns healthy
C4	2	Repeated manifest registration is reported as a duplicate
C5	2	Cataloged progress/interaction events are accepted; wrong-family and unknown events are rejected
C6	2	Contract and scenario fixtures reject secret-shaped keys, credentialed database URLs, and private keys
C7	2	Disabled compatibility groups (/api/v2/hubs, /console) deny access without needing fixture credentials
C8	2	Registry response propagates the request correlation identifier
C9	2	/readyz reports each dependency (database, port.repo projection, workload projection, authorization) individually, only degrading when a configured dependency is unavailable or stale
C10	2	A registration whose contract_version_min/contract_version_max excludes the runtime's contract version is rejected with an explicit incompatibility error
C2	2	GET /ports/registry/registrations/{hub_slug} resolves missing (404) and ambiguous (two hub_slugs sharing one reuse_surface_id) registrations, and GET .../audit returns queryable registration history
F2	3	Progress and interaction fixture events appear only in their respective projections
F3	3	Authority fixtures appear in projections with declared rebuild sources and provenance hashes

The projection scenario is shipped in the wheel as fixtures/projection-rebuild.json. Correlation and time fields are generated per run, allowing the harness to identify its own evidence without relying on global row counts.

Deliberately open checks

F1 registry audit history at framework scale (beyond the per-hub_slug audit trail above), F4 /api/v2 consumer smokes, F5 MCP projection binding, F6 policy fail-closed behavior beyond the raw-port group check above, F7 telemetry rejection, and F8 migration metadata isolation require ports or absorption slices that are not part of the T04 minimal vertical. Tenant isolation also remains open because the 0.1 runtime has no tenant identity or authorization context yet. These gaps must not be interpreted as passing; the harness reports only the implemented profile above.

Access enforcement and CI gates

make ci-check runs the test suite, checks the reviewed access inventory for source drift, builds distributions and validates an installed wheel outside the checkout's import path. The wheel check uses a fresh environment and refreshes the Hub package so rebuilding the same version cannot reuse an older installation. Forgejo runs these gates for main pushes and manual runs, using the full commit SHA and a unique temporary checkout. CI installs the locked development and runtime dependencies first. Individual gates are make test, make inventory-check and make package-check.

tests/test_enforced_conformance.py runs all twelve existing Tier 2/3 checks through an explicitly enforced runtime using a real signed IAM JWT and synthetic owner facts, policy and audit. It verifies event attribution against authorization records. Additional journeys establish valid state, deny both reads and writes for anonymous/invalid credentials, revoked entitlement, policy denial and policy/audit outages, then independently read back unchanged stored messages. These tests run in the ordinary suite; they need no external owner checkout.

The installed-wheel gate validates runtime/security imports, packaged action and browser route coverage, contract fixtures/schemas and the migration template. It makes no owner requests and starts no service. The separate optional Audit Core interoperability suite still requires HUB_CORE_AUDIT_CORE_SOURCE and is not silently represented as covered by ordinary CI. Local CI-equivalent success is not a deployed Forgejo receipt or live owner/platform acceptance.