# Graph Explorer Operations And Extraction

This note closes the operational side of the interactive Fabric map. It records
how to launch and refresh the current registry-backed explorer, what has been
verified, and how to extract the shared engine once the second adapter is ready.

## Launch

Start the registry against the local SQLite database:

```bash
railiance-fabric-registry --db .railiance-fabric/registry.sqlite3 --port 8765
```

Open the map:

```text
http://127.0.0.1:8765/ui/graph-explorer
```

Useful supporting endpoints:

```text
GET /exports/graph-explorer/manifest
GET /exports/graph-explorer
GET /status
```

The Fabric manifest currently declares `profile_persistence: local`. Saved map
views are stored in browser `localStorage`, URL query parameters carry normal
filter state, and copied state URLs include a state blob so manual overrides can
be shared without a profile service.

## Refresh

Refresh this checkout into the running registry:

```bash
railiance-fabric registry sync \
  --registry-url http://127.0.0.1:8765 \
  --repo-slug railiance-fabric \
  .
```

Refresh the known local Railiance repos:

```bash
railiance-fabric registry sync-manifest \
  registry/railiance-repos.yaml \
  --registry-url http://127.0.0.1:8765
```

Refresh every locally available active State Hub repo:

```bash
railiance-fabric registry sync-manifest \
  registry/local-repos.yaml \
  --registry-url http://127.0.0.1:8765
```

Repos without Fabric declarations remain registered-only. The graph explorer
intentionally shows them as onboarding gaps instead of hiding them.

## Verification

The automated coverage for this slice lives in `tests/test_graph_explorer.py`:

- manifest and payload schema validation
- registered-only repo projection
- `railiance-fabric export --format graph-explorer`
- registry API routes for manifest, payload, and UI
- static UI wiring for profile controls, orientation text, and shared-state
  support

Manual smoke checks for a local registry:

```bash
python3 -m pytest
python3 -m railiance_fabric.cli validate .
```

Extract and syntax-check the embedded JavaScript when the UI changes:

```bash
python3 -c "from railiance_fabric.graph_explorer_ui import graph_explorer_page; from pathlib import Path; page=graph_explorer_page(); script=page.split(chr(60)+'script'+chr(62))[1].split(chr(60)+'/script'+chr(62))[0]; Path('/tmp/graph-ui-script.js').write_text(script, encoding='utf-8')"
node --check /tmp/graph-ui-script.js
```

With the registry running, confirm that the served manifest reports local
profiles:

```bash
curl -s http://127.0.0.1:8765/exports/graph-explorer/manifest
```

## Extraction Decision

Recommendation: keep the shell in `railiance-fabric` until the repo-scoping
adapter is implemented against the same manifest and payload schemas. Extract
after two hosts are proven:

- Fabric registry map
- repo-scoping dependency graph

Recommended repository name: `graph-explorer-engine`.

The extracted repository should own:

- `GraphExplorerManifest` and `GraphExplorerPayload` schemas
- static graph explorer assets and mount/bootstrap code
- display-state evaluation helpers for hosts that want client-side rules
- browser-local profile handling, URL state, copied state blobs, and profile UI
- Cytoscape rendering, layouts, hover popups, detail panels, focus modes, and
  manual override controls
- conformance fixtures proving Fabric and repo-scoping payloads both load

Host repositories should keep:

- graph projection and domain metadata enrichment
- host-side profile persistence, when shared/team profiles are required
- authentication, authorization, and deployment
- domain-specific modes and deep links
- registry or analysis service APIs

Suggested public API:

```ts
type GraphExplorerManifest = unknown;
type GraphExplorerPayload = unknown;

mountGraphExplorer({
  container,
  manifestUrl,
  graphUrl,
  initialState,
}: {
  container: HTMLElement;
  manifestUrl: string;
  graphUrl?: string;
  initialState?: Record<string, unknown>;
}): Promise<{ destroy(): void }>;
```

Schema ownership should move to `graph-explorer-engine` at extraction time.
Fabric should then pin an engine schema version and keep its projection tests as
adapter conformance tests.

## Repo-Scoping Adapter Parity Checklist

Before extraction, repo-scoping should prove that the shared shell can consume
its RREG-WP-0010/RREG-WP-0011 behavior:

- expose a manifest with repo-scoping layers, filter fields, modes, and profile
  endpoint capabilities
- preserve existing stable keys for facts, evidence, features, capabilities,
  abilities, scopes, and edges
- map `dependencyType` to `edgeType`
- carry display states of `show`, `blur`, and `hide`
- retain confidence sizing, edge strength sizing, same-layer hints, and review
  state
- preserve manual overrides and hidden/orphaned override recovery semantics
- support profile create, update, duplicate, delete, and latest-default loading
  through host endpoints
- keep hover popups, selection details, selected-path, and neighborhood focus
- add adapter fixtures that validate against the shared schemas

## Migration Steps

1. Add a repo-scoping manifest endpoint or static manifest fixture.
2. Add shared conformance fixtures for one Fabric graph and one repo-scoping
   graph.
3. Move the static UI shell and schemas into `graph-explorer-engine`.
4. Replace Fabric's local HTML generator with an engine asset route plus Fabric
   manifest/payload URLs.
5. Replace repo-scoping's bespoke shell with the same engine mount.
6. Keep both host test suites validating their projections against the engine
   schemas.