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

Sources may be **local filesystem paths** or **remote HTTP(S) URLs** (git raw
endpoints, published index artifacts, etc.). Remote indexes are cached under
`registry/federation/cache/` for offline reuse and faster compose.

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

  - repo: sibling-repo
    url: https://git.example.com/org/sibling-repo/raw/main/registry/indexes/capabilities.yaml
    enabled: false
    required: false
    cache_ttl_seconds: 86400
    auth_env: FEDERATION_TOKEN
    auth_header: Authorization
```

Schema: `schemas/federation.schema.yaml`

### Source fields

| Field | Meaning |
|---|---|
| `repo` | Source repository slug |
| `index` | Local path to `capabilities.yaml` (repo-relative or `~/...`) |
| `url` | Remote HTTP(S) URL to a `capabilities.yaml` index |
| `enabled` | Include this source in compose |
| `required` | Fail compose if index missing or remote fetch fails with no cache |
| `domain` | Optional domain label |
| `cache_ttl_seconds` | Reuse cached remote index for this many seconds (`0` = always refetch) |
| `auth_env` | Environment variable holding token or full header value for `url` sources |
| `auth_header` | HTTP header for `auth_env` (default `Authorization`) |

Each source must specify **either** `index` **or** `url`, not both.

Sibling repos (`state-hub`, `feature-control`, `identity-canon`) are listed as
disabled local placeholders until they publish registry indexes. A disabled
`example-remote` URL source illustrates HTTP federation.

## Compose workflow

```bash
reuse-surface federation compose
reuse-surface federation compose --refresh   # bypass remote cache
```

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

- Merged `capabilities` from all enabled sources
- `source_repo` and `source_index` on every row
- `source_url` when the row came from a remote source
- `collision_policy` and per-source counts

### Remote cache

Fetched URL indexes are stored at `registry/federation/cache/<repo>.yaml` with
metadata in `<repo>.meta.yaml`. The cache directory is gitignored; only
`.gitkeep` is tracked.

When a refetch fails, compose reuses a stale cache and emits a warning. Required
remote sources without cache fail compose with a clear error.

### 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; follow
   `source_url` / `source_index` when remote.
4. Run `reuse-surface graph --check` before relying on relation navigation.

### Cross-repo discovery without local checkout

Enable a `url` source pointing at a published raw index (Gitea, GitHub, static
host). Set `auth_env` when the endpoint requires a token. Agents on machines
without sibling repo clones can still compose a federated view from HTTP sources
plus the local `reuse-surface` index.

## 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 --fail-on-warnings
reuse-surface federation compose
reuse-surface catalog
reuse-surface graph --check --fail-on-warnings
pytest -q
```

CI uses local sources only (remote examples are disabled). Warnings on missing
optional sibling indexes do not fail CI; schema validation errors do.