Files

ci / validate-registry (push) Has been cancelled

Details

Complete REUSE-WP-0005: registry federation and relation graphs

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.

2026-06-15 01:43:02 +02:00

2.3 KiB

Raw Blame History

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:

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

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

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

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
reuse-surface federation compose

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

2.3 KiB Raw Blame History