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:

GET /ui/graph-explorer
GET /exports/graph-explorer/manifest
GET /exports/graph-explorer

The local CLI can emit the same payload for repo-local inspection:

railiance-fabric export --format 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.

Fabric currently declares profile_persistence: local. That means the shell stores named map views in browser localStorage, supports duplicate/delete inside that browser, and can copy a URL with the current query parameters and a state blob. Local profile ids can be reopened in the same browser profile; the copied state blob is the portable sharing path until a host-backed profile API is added.

The payload is compatible with Cytoscape-style element arrays:

{
  "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.

Edges may include layout hints used by the client-side layout engine: sameRepo, sourceRepo, targetRepo, layoutAffinity, layoutIdealLength, and layoutElasticity. Fabric uses these hints to keep same-repo entities closer than cross-repo dependencies. Deployment-to-server edges are intentionally shortest and most elastic; deployment-to-repo edges are longer and looser so infrastructure placement does not collapse into the repo node.

Display State Ownership

The contract allows either the host service or the engine to evaluate display state.

The precedence rule is fixed:

Default element state is show.
Rules are applied in list order; later matching rules override earlier matching rules.
Manual overrides win last.
Edges connected to hidden nodes are hidden.
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.
`server`	Endpoint hosts inferred from registered interface URLs.
`deployment`	Service deployment instances per declared environment.
`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
browser-local profiles, URL state, and copied state blobs
schema definitions and compatibility tests

Host repos should own:

graph projection and metadata enrichment
host-side profile persistence, when a repo needs shared/team profiles
authentication and authorization
domain-specific graph modes
deep links back to source systems

5.7 KiB Raw Blame History