# Multiple Sources and Database Targets

Use registry version 2 when one project has multiple source systems, database targets, or schema roles that cannot be uniquely identified by `table_name`.

## Document roles

- `source`: the original contract from an API, file, CRM, ERP, or external database. Preserve source representation.
- `canonical`: the system-independent business entity used for semantic alignment.
- `target`: the physical projection for one database, instance, table, or collection.
- `shared`: reusable enums, types, and imports; never a merged replacement for distinct physical targets.

Keep one target document per database when types, indexes, naming, partitioning, or nullability differ.

## Registry identity

- `systems` lists stable source and database system IDs.
- Every document has a unique, stable `schema_id`, `entity`, and `role`.
- Source and target documents include `system_id`; canonical documents do not bind to a system.
- `derived_from` records source-to-canonical-to-target relationships or an explicit direct mirror.
- `table_name` identifies that document's table, collection, or logical entity; it is not the project-wide unique key.

A useful ID form is `<entity>.<role>.<system?>.<version>`, for example `customer.source.crm.v1`, `customer.canonical.v1`, or `customer.target.primary-postgres.v1`.

When a source changes, inspect downstream documents that derive from it. When canonical changes, inspect every target. A target-specific optimization must not become a universal canonical constraint.

For shared storage, retain `document`, `storage: shared`, `shared_root`, `project_reference`, identity, and derivation metadata in the consuming project's registry. A shared path never replaces the registry.