Project repo-family relations from local declarations

workplans/RAIL-FAB-WP-0026-repo-family-relation-projection.md

@@ -0,0 +1,112 @@
+---
+id: RAIL-FAB-WP-0026
+type: workplan
+title: "Project repo-family relations from repo-local declarations"
+domain: financials
+repo: railiance-fabric
+status: finished
+owner: codex
+topic_slug: railiance
+created: "2026-07-26"
+updated: "2026-07-26"
+state_hub_workstream_id: "13c95134-8a29-4b0a-a227-aa791f902517"
+---
+
+# RAIL-FAB-WP-0026 - Project repo-family relations from repo-local declarations
+
+## Goal
+
+Make the first `rail-*`, `rapp-*`, and `reef-*` repos visible in Fabric as a
+minimal relation topology instead of only as isolated registered repositories.
+
+## Boundaries
+
+This workplan may:
+
+- persist repo checkout and declaration-location hints in the registry
+- project repo-family relations from repo-local declaration files
+- update graph-explorer and registry docs to surface the new relation path
+
+It must not:
+
+- redesign the broader Fabric graph model
+- invent repo-family relations from registry metadata alone when source-backed
+  declaration files are available
+- claim runtime placement or governance beyond what the repo-local files state
+
+## T01 - Persist local repo path context in repository records
+
+```task
+id: RAIL-FAB-WP-0026-T01
+status: done
+priority: high
+state_hub_task_id: "e87f1771-718b-4b4f-9688-3673081dec67"
+```
+
+Store enough local checkout context in Fabric repository records so later graph
+projection can reopen the relevant repo-local declarations.
+
+Acceptance:
+
+- repository records retain the checkout path when onboarding locally
+- repository records retain declaration-path hints when they are provided
+- the stored shape remains backward compatible for repos that only register by
+  slug and remote URL
+
+2026-07-26: Extended Fabric repository records to persist the local checkout
+`path` and any provided `declaration_paths`, updated the registry schema
+compatibly, and carried those fields through direct sync and manifest sync.
+
+## T02 - Project repo-family relations from repo-local files
+
+```task
+id: RAIL-FAB-WP-0026-T02
+status: done
+priority: high
+state_hub_task_id: "d45a0de0-f7b3-46c0-9ee8-e306826863af"
+```
+
+Project the minimum repo-family relation topology from repo-local declaration
+files instead of relying only on registry metadata.
+
+Acceptance:
+
+- Fabric can project `governed_by` from repo-local `rail`, `rapp`, and `reef`
+  declarations
+- Fabric can project `supports_rail` from `rapp` declarations
+- Fabric can project `hosts_rail` and `binds_rapp` from `reef` files
+- the resulting relations appear in registry-backed exports
+
+2026-07-26: Added declaration-backed repo-family projection in the registry
+combined graph. Fabric now projects `governed_by` from the first-wave `rail`,
+`rapp`, and `reef` declarations, `supports_rail` from `rapp` declarations, and
+`hosts_rail`/`binds_rapp` from the reef binding files with declaration
+fallbacks. The graph explorer now preserves repository declaration references
+for those projected repo nodes.
+
+## T03 - Verify the first-wave relation path end to end
+
+```task
+id: RAIL-FAB-WP-0026-T03
+status: done
+priority: medium
+state_hub_task_id: "847cf1e9-8e29-4501-817b-b305e88302d9"
+```
+
+Verify that the current first-wave repos expose queryable repo-family relations
+through the live Fabric registry/export path.
+
+Acceptance:
+
+- focused tests cover the new projection path
+- the live registry export shows the first-wave ownership and rail-host/support
+  relations
+- docs point operators at the declaration-backed projection path
+
+2026-07-26: Verified the projection with focused tests
+(`tests/test_registry.py`, `tests/test_graph_explorer.py`, and
+`tests/test_canon.py`) and reran them with local HTTP binding enabled. Restarted
+the local registry, resynced `registry/railiance-repos.yaml`, and confirmed the
+live export now emits `governed_by` for `rail-kubernetes`, `rapp-openbao`, and
+`reef-railiance`, plus `supports_rail` for `rapp-openbao` and `hosts_rail` for
+`reef-railiance`.