generated from coulomb/repo-seed
40 lines
1.3 KiB
Markdown
40 lines
1.3 KiB
Markdown
# 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.
|