# 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.