core-hub/docs/specs/README.md

Core Hub Specs

This directory is the specification map for Core Hub. The specs are intentionally ahead of implementation so the framework contract stays stable while the runtime is rebuilt.

Spec Set

• Architecture - component model and boundaries
• Contract and IR - canonical framework contract, schemas, fixtures, and adapter rules
• API v2 Compatibility - Inter-Hub compatibility surface to preserve during transition
• Inter-Hub Legacy Inventory - initial route/data/consumer inventory for migration
• Contract Governance - how contract changes are reviewed and recorded
• Data Model - initial entity model and migration posture
• Event and Registry Model - event catalogs, manifests, widgets, and capability registries
• Auth, Access, and Custody - API auth semantics and secret routing rules
• Workplan Coordination - file-first workplans, tasks, progress, messages, decisions
• UI and Operator Console - whynot-design aligned UI direction
• Testing, Release, and Migration - verification, deployment, and cutover gates

Contract Artifacts

Implementation-neutral artifacts live in contracts/:

• contracts/schemas/
• contracts/catalogs/
• contracts/fixtures/
• contracts/openapi/

Contract Rule

The implementation may change. The contract changes only through a workplan and a compatibility note.

Any route, schema, event type, or manifest field used by existing consumers must have one of:

• preserved behavior;
• documented replacement and migration path;
• explicit cancellation decision with affected consumers listed.