# SQLAlchemy Metadata Isolation

**Updated:** 2026-07-09  
**Workplan:** `HUB-WP-0003-T03`

---

## Rule

`hub_core.models.base.Base` owns metadata for **shared primitive tables only**
(domains, managed_repos, agent_messages, progress_events, capability_*, tpsc_*).

Each host runtime keeps its own declarative base for host-specific tables:

| Host | Base module | Session style |
| --- | --- | --- |
| `state-hub` | `api.models.base.Base` | Sync |
| `core-hub` | `core_hub.db.Base` | Async |

Router factories never import host models from hub-core. Hosts inject models at
mount time:

```python
from hub_core.routers.domains import create_domains_router

app.include_router(create_domains_router(get_session, domain_model=Domain, ...))
```

---

## Why separate metadata

- Migration ownership stays with the host that runs the database.
- core-hub framework tables (`hubs`, `widgets`, …) must not appear in hub-core.
- state-hub dev-hub tables (workplans, tasks, …) must not appear in hub-core.
- Async and sync engines can coexist without forcing one base class.

See `the-custodian/docs/hub-ecosystem-architecture.md` for the full stack model.