# Registry Federation

**Repository:** `reuse-surface`  
**Audience:** Architects and agents composing multi-repo capability indexes

---

## Purpose

helix_forge capabilities may be registered in multiple repositories. Federation
composes capability indexes from configured sources into a single discovery
surface without silently merging duplicate IDs.

## Manifest

`registry/federation/sources.yaml` lists index sources:

```yaml
version: 1
domain: helix_forge
collision_policy: warn
sources:
  - repo: reuse-surface
    index: registry/indexes/capabilities.yaml
    enabled: true
    required: true
```

Schema: `schemas/federation.schema.yaml`

### Source fields

| Field | Meaning |
|---|---|
| `repo` | Source repository slug |
| `index` | Path to `capabilities.yaml` (repo-relative or `~/...`) |
| `enabled` | Include this source in compose |
| `required` | Fail compose if index missing when enabled |
| `domain` | Optional domain label |

Sibling repos (`state-hub`, `feature-control`, `identity-canon`) are listed as
disabled placeholders until they publish registry indexes.

## Compose workflow

```bash
reuse-surface federation compose
```

Writes `registry/indexes/federated.yaml` with:

- Merged `capabilities` from all enabled sources
- `source_repo` and `source_index` on every row
- `collision_policy` and per-source counts

### Collision policy

`warn` (default): duplicate IDs across sources are kept but reported as
warnings. Consumers must inspect `source_repo` before choosing an entry.

## Agent query pattern

1. Run `reuse-surface federation compose` after manifest or sibling index changes.
2. Read `registry/indexes/federated.yaml` for cross-repo discovery.
3. Open `path` in the source repo for full entry detail when local.
4. Run `reuse-surface graph --check` before relying on relation navigation.

## Relation graphs

```bash
reuse-surface graph
reuse-surface graph --check
reuse-surface graph --stdout
```

Generates `docs/graph/capability-graph.mmd` from local entry `relations`.
`--check` reports `depends_on` cycles and broken relation targets against the
federated ID set.

## CI integration

Gitea CI runs:

```bash
reuse-surface validate --relations
reuse-surface federation compose
```

Warnings on broken relations or missing optional sibling indexes do not fail CI;
schema validation errors do.