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

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.

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