# 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.

## Resolved decisions (2026-07-09, CUST-WP-0057)

- **Workplan/task tables:** State Hub remains canonical. Core Hub may index and
  display workplan data via HTTP ingestion later; it does not fork tables in
  this consolidation lane. See `the-custodian/docs/hub-ecosystem-architecture.md`.
- **Inter-Hub admin entities:** Migrated as historical records where consumers
  depend on identifiers; deferred protected surfaces stay empty compatibility
  collections until a consumer requires them.

## Open questions

- Whether Core Hub adds a read-model ingestion path from State Hub progress/messages
  (`STATE-WP-0074`) or remains framework-only for coordination data.