Start graph explorer contract

2026-05-18 14:08:01 +02:00
parent ae4f567a2b
commit eec7e2a9f6
10 changed files with 1429 additions and 4 deletions
--- a/docs/graph-explorer-contract.md
+++ b/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