Start graph explorer contract

docs/graph-explorer-transfer-review.md

@@ -0,0 +1,84 @@
+# 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.