generated from coulomb/repo-seed
tegwick
40ab8dded0
Some checks failed
ci / validate-registry (push) Has been cancelled
Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
90 lines
2.3 KiB
Markdown
90 lines
2.3 KiB
Markdown
# 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. |