# Contract and IR Spec

## Purpose

The Contract/IR layer is the canonical source of truth for Core Hub behavior. Runtime code, UI adapters, generated clients, and migration tools consume this layer.

## Initial Contract Artifacts

- OpenAPI document for HTTP APIs
- JSON Schemas for manifests, widgets, events, annotations, decisions, deployments, outcomes, and registry facts
- Alembic migrations and SQL schema snapshots
- fixture datasets for compatibility tests
- event type catalog
- widget type catalog
- capability manifest schema
- API auth and error envelope conventions

## Adapter Rule

Adapters may scaffold code or validate drift, but they must not become the contract. A field exists because it is in the Contract/IR, not because a runtime class happens to expose it.

## Compatibility Rule

When migrating from Inter-Hub, capture every preserved route with:

- route and method
- auth requirement
- request schema
- response schema
- error semantics
- known consumers
- fixture examples
- migration status

## Open Questions

- Whether Core Hub should keep SDK download endpoints or move generated clients to package artifacts.
- Which admin UI routes from Inter-Hub need API-compatible successors vs. product redesign.
- Whether State Hub file sync remains external or becomes a first-class Core Hub ingestion mode.