core-hub/docs/specs/contract-ir.md

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.