core-hub/docs/specs/data-model.md

Data Model Spec

Purpose

Define the initial Core Hub entity model and the migration stance from State Hub and Inter-Hub.

Initial Entity Families

Coordination:

• repositories
• workstreams
• workplans
• tasks
• progress events
• messages
• decisions

Framework:

• hubs
• hub capability manifests
• API consumers
• API keys or key references
• widgets
• widget types
• interaction events
• annotations and annotation threads
• requirements
• decision records
• deployment records
• outcome signals
• policy scopes
• registry facts

Operations:

• request logs
• auth audit metadata
• migration batches
• compatibility fixtures
• import/export runs

Initial Persisted Framework Tables

The first replacement slice persists the framework resources that current Inter-Hub consumers need during bootstrap and smoke testing:

• hubs
• hub_capability_manifests
• api_consumers
• api_keys with hash and prefix only, never full key material
• widgets
• interaction_events
• migration_runs for import summaries, bundle hashes, counts, and diagnostics

Migration Posture

• Import Inter-Hub schema facts through explicit migrations or import tools, not ad hoc SQL editing.
• Preserve identifiers where consumers or historical references depend on them.
• Treat API key full values as non-recoverable unless an approved custody path says otherwise.
• Store only hashes, prefixes, labels, and non-secret lifecycle metadata.
• Record row counts, relationship checks, and fixture replays for every migration batch.

Open Questions

• Whether Core Hub owns the canonical workplan task tables or continues reading from State Hub until cutover.
• Whether Inter-Hub admin-only entities should be migrated as historical records or redesigned as Core Hub-native resources.