---
id: REUSE-WP-0005
type: workplan
title: "Registry federation and relation graphs"
domain: infotech
repo: reuse-surface
status: finished
owner: codex
topic_slug: helix-forge
created: "2026-06-15"
updated: "2026-06-15"
state_hub_workstream_id: "df6a3b58-2c32-4893-8771-87a822c12aa5"
---

# Registry federation and relation graphs

Follow-up to `docs/IntentScopeGapAnalysis.md` open priorities 12 and 14.
Extend the registry beyond a single-repo index by composing federated indexes
from configured sources and generating relation graphs for architects (UC-RS-016).

## Design decisions

- **Federation scope (MVP):** Filesystem-local index composition only. A manifest
  lists index files from this repo and sibling helix_forge checkouts; no network
  fetch or runtime federation service.
- **Source attribution:** Federated entries carry `source_repo` and
  `source_index` so ID collisions are visible, not silently merged.
- **Graph output:** Mermaid diagram derived from entry `relations` fields;
  suitable for docs and PR review, not interactive visualization yet.
- **Cycle policy:** `depends_on` cycles are reported as warnings during graph
  generation and federation compose validation.

## Define Federation Manifest And Schema

```task
id: REUSE-WP-0005-T01
status: done
priority: high
state_hub_task_id: "9a9732ea-c546-49fe-bf61-0f3bdf94406a"
```

Create `schemas/federation.schema.yaml` and
`registry/federation/sources.yaml` describing federation sources for
helix_forge. The manifest must support:

- Local primary index (`registry/indexes/capabilities.yaml`)
- Optional sibling repo indexes via absolute or home-relative paths
- Per-source `enabled`, `domain`, and `repo` metadata
- Documented collision policy (`warn`, not auto-merge)

Include commented placeholders for `state-hub`, `feature-control`, and
`identity-canon` indexes to federate when those repos publish them.

## Add Federation Compose Command

```task
id: REUSE-WP-0005-T02
status: done
priority: high
state_hub_task_id: "9539c609-ac44-40a7-90bc-6f294fe085b9"
```

Add `reuse-surface federation compose` that reads `registry/federation/sources.yaml`
and writes `registry/indexes/federated.yaml`. Requirements:

- Merge capability rows from all enabled sources
- Preserve `source_repo`, `source_index`, and original `path` per entry
- Warn on duplicate IDs across sources
- Skip missing optional external indexes with a clear warning (not a hard fail)
- Document command in `tools/README.md` and `AGENTS.md`

## Add Relation Graph Command

```task
id: REUSE-WP-0005-T03
status: done
priority: medium
state_hub_task_id: "4f7e85a5-c73a-49b6-a044-ba1fabc54d8a"
```

Add `reuse-surface graph` that emits a Mermaid `graph LR` diagram from capability
entry relations. Requirements:

- Include all relation types present in entries
- Write `docs/graph/capability-graph.mmd` by default; support `--stdout`
- Nodes labeled with capability ID and compact vector from the index
- Document regeneration in `registry/README.md`

## Add Cycle And Broken-Reference Checks

```task
id: REUSE-WP-0005-T04
status: done
priority: medium
state_hub_task_id: "6f7e2913-9634-4ebb-841f-9024b35961ef"
```

Extend validation or graph generation to report:

- `depends_on` cycles within the registered graph
- Relation targets that reference unknown capability IDs in the composed index
- Output as warnings via `reuse-surface graph --check` or `validate --relations`

## Document Federation And Refresh Gap Analysis

```task
id: REUSE-WP-0005-T05
status: done
priority: medium
state_hub_task_id: "8d69121b-9961-41c2-8802-d9c5b5d94c69"
```

Create `docs/RegistryFederation.md` covering manifest format, compose workflow,
collision handling, and how agents should query federated indexes. Update
`SCOPE.md`, `docs/IntentScopeGapAnalysis.md`, and CI if federation compose
should run in the validate pipeline.