railiance-fabric/docs/graph-explorer-contract.md

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.

Fabric hosts should also include deployment overlay fields when available: deploymentEnvironment, deploymentScenario, routingAuthority, accessZone, policyAuthority, exposure, and host. These fields describe where an element runs or is reachable in a concrete deployment scenario. They do not define fabric membership and must remain filter/grouping metadata unless the host explicitly promotes a separate graph relationship with evidence.

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:

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

Zone Overlay Modes

The graph explorer should support zone-oriented modes for Fabric payloads:

Mode	Purpose
fabric	Group by financial responsibility: fabric, subfabric, owner.
environment	Group by dev, test, prod, or other deployment environment.
deployment-scenario	Group by concrete scenario such as bernd-laptop, coulombcore, or railiance01.
routing-authority	Group by loopback launcher, Compose port mapping, ingress controller, reverse proxy, DNS, or equivalent route authority.
access-zone	Group by intended reachability such as private-dev, collaborator-test, early-access, production-public, or production-admin.

Zone modes are diagnostic views. They answer "where does this run or who can reach it here?" without mutating the underlying Fabric responsibility boundary.

Zone boundary overlays are a visual layer over the graph canvas. They should be computed from visible node positions after layout/filtering rather than modeled as graph parent nodes. The overlay should be backed by explicit zone definitions and a resolver so visible nodes are assigned to at most one rendered zone. The default boundary grouping is deploymentEnvironment:

Overlay label	Matching nodes
dev-tegwick	visible nodes with deploymentEnvironment: dev in the private local development overlay
test	visible nodes with deploymentEnvironment: test or legacy staging
prod	visible nodes with deploymentEnvironment: prod

Nodes without deployment overlay data are not enclosed. Edge-only deployment overlay evidence may contribute to zone summaries and warnings, but it should not create a boundary unless at least one visible node belongs to the same zone. When access-zone grouping is selected, boundaries use accessZone values such as private-dev, collaborator-test, production-public, or production-admin.

Zone labels should be rendered as plain text in the upper-left corner of the zone rectangle, without badge frames or white backgrounds. The label may still act as the zone's focus/drag handle as long as it visually reads as text drawn on the zone surface.

Useful warnings for the graph explorer include:

• control surfaces in user-facing access zones;
• production nodes with unrestricted developer access;
• early-access routes without a policy authority;
• services present in production but missing from test;
• local-only surfaces that appear in shared or production scenarios;
• conflicting port or host claims within the same deployment scenario.

Zone resolvers should also expose scoped diagnostics in zone detail panels. The initial diagnostic set includes empty zone seed sets, visible nodes matched by multiple zone definitions, and edges crossing zone boundaries. Attraction diagnostics such as multiple attraction candidates or depth-limit stops belong to the same resolver diagnostic channel when attraction rules are enabled. Display-only context edges, such as repository declares edges, are evidence for where declarations came from. They must not count as zone boundary connectivity, attraction paths, or collapsed-zone boundary edges unless a host explicitly promotes them to canonical graph relationships.

Saved graph profiles should persist zone view state as an explicit nested zone object. The initial fields are visible, grouping, definitionSet, presentation, and containers. URL parameters may continue to expose compatibility aliases such as zoneBoundaries, zoneGrouping, and zoneDefinitionSet, but saved profiles should prefer the nested object so future zone definition sets, presentation preferences, and operator-placed zone surfaces can be restored without another state migration.

Zone containers are view state, not fabric data. A container stores a stable zone surface position and size in graph coordinates. Global graph layout may place unzoned nodes and provide an initial center for new zones, but existing zone containers should keep their operator-chosen positions when the layout algorithm changes. After the global layout pass, each zone may project its assigned visible nodes into local coordinates inside its container. The first local layout may be a deterministic compact layout; later engines can replace that with per-zone Cytoscape or engine-owned algorithms.

Zone collapse is a view-only operation. A collapsed zone should hide its visible member nodes, replace them with a synthetic zone node, and draw synthetic boundary edges from that zone node to visible external neighbors. Internal edges are summarized on the zone node rather than rendered. Expanding the zone removes the synthetic elements and restores the original graph elements without changing the underlying payload.

Zone dragging is also view-only. Dragging a zone handle should translate the currently assigned visible member nodes by the same delta and then recompute the overlay bounds from the new node positions. The operation updates Cytoscape view coordinates only; it does not change Fabric graph data.

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
• deployment overlay extraction from the route/proxy/deployment authority they control