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
• Runtime Absorption Inventory - current routes, data, consumers, and ownership that hub-core absorption must preserve
• Runtime Absorption Plan - ordered dual-run route groups, migration gates, traffic control, and rollback
• 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
• Ops Evidence Contract - runtime evidence resources, event vocabulary, read-model gaps, and non-secret mapping rules
• 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
• Operator UI Rebuild Backlog - gated first-screen backlog after API/CLI proof
• whynot UI Adapter - design-system consumption and adapter rules
• Testing, Release, and Migration - verification, deployment, and cutover gates
• Pagination adoption - hub-core utils deferral and adoption trigger

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.