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:

```text
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:

```bash
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:

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

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 current
local layout choices are compact grid and circle. The selected zone-local
layout algorithm belongs in the nested `zone.layout.algorithm` view state so it
can be restored by saved or copied views without changing the Fabric payload.

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