railiance-fabric/docs/graph-explorer-transfer-review.md

Graph Explorer Transfer Review

This note closes the first implementation step for RAIL-FAB-WP-0008-T01. It reviews the repo-scoping dependency graph work from RREG-WP-0010 and RREG-WP-0011 and turns the transferable parts into Fabric requirements.

Source Implementation

Repo-scoping already has a useful graph explorer shape:

• docs/adr-dependency-graph-visualization-framework.md chooses Cytoscape.js because the required interaction model is graph-native: pan, zoom, selection, layouts, styling, filtering, and path exploration.
• docs/dependency-visualization-exploration.md defines layered graph data, show / blur / hide display states, deterministic filters, manual overrides, and saved view profiles.
• src/repo_scoping/core/service.py emits Cytoscape-compatible payloads with stable keys, metadata-rich node and edge data, visibility state, hidden elements, profile application, confidence sizing, and edge strength sizing.
• src/repo_scoping/web_ui/views.py provides the first UI shell: profile controls, structured filters, manual overrides, focus depth, hover popups, selection details, and a layered layout.
• tests/test_web_api.py verifies graph endpoints, ad hoc filters, profile creation, duplicate profiles, latest-profile defaulting, and UI wiring.

Reusable Behaviors

Fabric should carry these behaviors into the shared graph explorer contract:

• Cytoscape-compatible element arrays with data and optional classes.
• Stable element keys that survive refreshes, so layout state, profile rules, and deep links do not churn.
• Metadata-rich nodes and edges rather than UI-only labels.
• Explicit layer, kind, reviewState, freshnessState, and displayState fields.
• Visibility actions of show, blur, and hide, with later rules overriding earlier rules and manual overrides winning last.
• Hidden element reporting, so over-filtered views are recoverable.
• Edge treatment for context-muted nodes.
• View profiles that can persist filter rules and manual overrides when a host provides profile endpoints.
• Hover popups for compact inspection and selection panels for full detail.
• Layout modes for full graph, impact or filtered graph, selected path, and neighborhood focus.
• Visual hints for confidence, strength, same-layer edges, stale or unresolved state, and review state.

Adapter-Owned Semantics

These repo-scoping concepts should remain in the repo-scoping adapter and not be hard-coded into the engine:

• Layer names of fact, evidence, feature, capability, ability, and scope.
• Candidate graph approval semantics.
• Dependency impact analysis over base and target analysis runs.
• Document fact normalization and README/SCOPE de-duplication.
• Scope curation recommendations.

Fabric has its own adapter semantics:

• Layer names of repository, service, capability, interface, dependency, binding, and library.
• Registered-only repositories without accepted graph snapshots.
• State Hub repo ids, workplan links, and registry endpoints as deep links.
• Unresolved dependencies where provider bindings are missing or disputed.
• Blast-radius and provider-chain exploration across accepted Fabric declarations.

Extraction Recommendation

Start in railiance-fabric with a host-neutral manifest and payload contract, plus a Fabric registry projection. The first UI shell can live locally while the contract is still moving.

Extract into a separate repository only after two host adapters are proven:

1. Fabric registry map adapter.
2. Repo-scoping dependency graph adapter.

The likely extracted repository is graph-explorer-engine. It should own the static interaction shell, schema definitions, layout/filter/profile client logic, and adapter manifest contract. Host repos should keep graph projection, profile persistence, authentication, and domain-specific deep links.