reuse-surface/docs/RegistryFederation.md

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:

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

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

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:

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.