# Cross-file reference resolution
Design for Phase 13 (0.8.0): resolve fully-qualified relationship endpoints across multiple loaded contracts.
## Index key
Contracts are indexed by root **`id`** (stable contract identifier). Filename stems are not used for resolution.
Duplicate `id` values within a loaded set produce a load-time validation error (`odcs:invalid-schema`).
## FQN grammar
Reuse the existing regex in `src/validation/references.rs` (`fully_qualified_reference_regex`).
Canonical resolved form:
```text
{contractId}/{schemaObject}/{property}
```
Optional URL prefix (e.g. `https://example.com/contracts/foo.yaml#`) is accepted for format validation but ignored during resolution — only path segments after optional `#` or leading `/` are used.
Shorthand references (`table.column`) continue to resolve within the **primary** contract only.
## Load order
When building a `ContractSet`:
1. Primary contract (CLI path argument or library primary path)
2. Explicit `--dep` paths in command order
3. Registry dependency paths from `--registry` (all indexed contracts except primary, sorted by path)
4. Files from `--include` directory: non-recursive scan of `*.yaml`, `*.yml`, `*.json`, sorted lexicographically by filename
The primary contract is always validated; dependencies are indexed for reference resolution only (their own validation diagnostics are merged into the set report).
## Single-document behavior
When no dependencies are loaded, validation behavior is unchanged from 0.7.0. FQN strings that match the regex but cannot be resolved emit `odcs:unresolved-reference` with remediation to include the referenced contract.
## CLI
```bash
odcs validate contract.yaml --dep other.yaml --include ./contracts/
odcs validate contract.yaml --registry ./contracts/
```
- `--dep <path>` — repeatable; explicit dependency files
- `--include <dir>` — non-recursive directory scan
- `--registry <dir>` — load `<dir>/.odcs/registry.json` (requires prior `odcs registry index`)
## Out of scope (0.8.0+)
- Remote URL fetching
- HTTP remote registry server
- Workspace manifest files