Start graph explorer contract

docs/graph-explorer-contract.md

@@ -0,0 +1,145 @@
+# Graph Explorer Contract
+
+This note defines the first manifest and payload contract for the interactive
+Fabric map and the possible reusable graph explorer engine.
+
+The contract is intentionally host-neutral. Fabric and repo-scoping should be
+able to use the same interaction shell by exposing a manifest and a graph
+payload with stable fields.
+
+## Files
+
+- `schemas/graph-explorer-manifest.schema.yaml` validates a host manifest.
+- `schemas/graph-explorer-payload.schema.yaml` validates graph payloads.
+- `railiance_fabric.graph_explorer` provides the first Fabric registry
+  manifest and payload projection.
+
+## Registry Endpoints
+
+The registry service exposes the first Fabric projection:
+
+```text
+GET /exports/graph-explorer/manifest
+GET /exports/graph-explorer
+```
+
+The manifest tells a graph shell where to load data, which fields are stable,
+which layers exist, which filter fields are available, and which modes the host
+supports.
+
+The payload is compatible with Cytoscape-style element arrays:
+
+```json
+{
+  "apiVersion": "railiance.fabric/v1alpha1",
+  "kind": "GraphExplorerPayload",
+  "manifest_id": "railiance-fabric.registry-map",
+  "mode": "full",
+  "elements": [
+    {
+      "data": {
+        "id": "repo:railiance-fabric",
+        "stableKey": "repo:railiance-fabric",
+        "kind": "Repository",
+        "layer": "repository",
+        "label": "Railiance Fabric",
+        "displayState": "show"
+      }
+    }
+  ],
+  "hidden_elements": []
+}
+```
+
+## Required Payload Semantics
+
+Every element must include:
+
+- `id`: the current element id used by the graph library.
+- `stableKey`: the durable id used by profile rules, manual overrides, layout
+  state, and deep links.
+- `kind`: host-specific entity kind.
+- `layer`: host-declared layer used for layout, grouping, and color.
+- `displayState`: one of `show`, `blur`, or `hide`.
+
+Edges are ordinary elements whose data also includes:
+
+- `source`
+- `target`
+- `edgeType`
+- `strength`
+- `sameLayer`
+
+Hosts should also include useful optional fields when available: `label`,
+`name`, `description`, `repo`, `domain`, `lifecycle`, `reviewState`,
+`freshnessState`, `confidence`, `visualSize`, `ownership`, `unresolved`,
+`sourceReferences`, and `deepLinks`.
+
+## Display State Ownership
+
+The contract allows either the host service or the engine to evaluate display
+state.
+
+The precedence rule is fixed:
+
+1. Default element state is `show`.
+2. Rules are applied in list order; later matching rules override earlier
+   matching rules.
+3. Manual overrides win last.
+4. Edges connected to hidden nodes are hidden.
+5. Edges connected to blurred nodes may carry a contextual muted class or data
+   hint.
+
+Repo-scoping currently evaluates this host-side. A future extracted engine can
+evaluate it client-side for static exports, but host-provided `displayState`
+must remain valid input.
+
+## Fabric Layers
+
+The first Fabric manifest declares:
+
+| Layer | Purpose |
+|-------|---------|
+| `repository` | Registered source repositories, including registered-only repos. |
+| `service` | Service declarations. |
+| `capability` | Capability declarations. |
+| `interface` | Interface declarations. |
+| `dependency` | Dependency declarations, including unresolved dependency nodes. |
+| `binding` | Binding assertions between consumer dependencies and providers. |
+| `library` | Future library/SBOM inventory nodes. |
+
+## Repo-Scoping Compatibility
+
+Repo-scoping can adapt without a rewrite because its current graph payload
+already exposes most required fields:
+
+- `id`, `stableKey`, `kind`, `layer`, labels, and metadata-rich data objects.
+- `displayState`, `visibilitySource`, and `visibilityReason`.
+- edge `source`, `target`, `dependencyType`, `strength`, `sameLayer`, and
+  visual width.
+- profile data, filter rules, manual overrides, hidden elements, and orphaned
+  overrides.
+
+The main adapter work is manifest generation and small field aliases:
+`dependencyType` can map to `edgeType`, repo-scoping layers become manifest
+layers, and existing profile endpoints can be listed under manifest
+`endpoints.profiles`.
+
+## Extraction Boundary
+
+The extracted `graph-explorer-engine` should own:
+
+- graph rendering and layout controls
+- filter and manual override UI
+- hover popups and selection detail panels
+- profile UI when the host declares profile endpoints
+- URL state and copied state blobs
+- schema definitions and compatibility tests
+
+Host repos should own:
+
+- graph projection and metadata enrichment
+- profile persistence
+- authentication and authorization
+- domain-specific graph modes
+- deep links back to source systems

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.

docs/registry-api.md

@@ -64,4 +64,6 @@ GET /exports/state-hub
 GET /exports/backstage
 GET /exports/xregistry
 GET /exports/libraries/xregistry
+GET /exports/graph-explorer/manifest
+GET /exports/graph-explorer
 ```