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

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

The refined rule panel is also browser-local. Rules target either nodes or
edges, optionally narrow by type and by attributes present on the currently
available elements, and then apply one of five modifiers:

- `show`, `hide`, and `blur` are visibility states.
- `highlight` keeps an element visible and adds visual emphasis.
- `remove` hides matching elements and excludes them from the next layout run.

Rules are applied top to bottom. Later matching rules refine earlier matching
rules. Manual overrides win after rules except for `remove`, which is treated as
stronger because it changes the layout membership. Edges connected to hidden
nodes are hidden; edges connected to removed nodes are removed.

## 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, rule 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 and rule evaluation helpers for hosts that want client-side
  rules, including `show`, `hide`, `blur`, `highlight`, and `remove`
- 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 vocabulary and manifest labels for node types, edge types, rule fields,
  modes, and orientation terms
- 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

## Adapter Readiness Notes

The refined shell is closer to extraction, but these Fabric-specific assumptions
should be made manifest-driven or host-adapted before `graph-explorer-engine`
becomes a separate repo:

- The shell still expects the internal element type field to be named `layer`.
  User-facing text now says nodes and node types, but the shared contract should
  either rename this to `nodeType` or declare the field through
  `manifest.identity`.
- Node shapes are hardcoded against Fabric node type ids such as `repository`,
  `service`, `deployment`, `server`, `capability`, `interface`, `dependency`,
  `binding`, and `library`.
- Rule-builder attributes are derived from a fixed allowlist. Repo-scoping can
  use the model, but the allowlist should move to manifest filter fields so a
  host can expose facts, evidence, confidence, freshness, scope, ability, or
  other domain attributes without changing engine code.
- Mode behavior is hardcoded for Fabric's `onboarding-gaps`, `unresolved`,
  `selected-path`, and `neighborhood` semantics. The reusable engine should
  either provide generic selectors or let hosts define mode predicates.
- The orientation panel still contains Fabric-specific renderers for
  repositories, services, interfaces, dependencies, and capabilities. This
  should stay host-owned or become a manifest-provided details adapter.
- The default detail rows know about `source`, `target`, `edgeType`, `strength`,
  deep links, and source references. That is acceptable as a shared baseline,
  but host-specific row ordering should be manifest-driven.

The current rule-panel data model is compatible with repo-scoping if repo-scoping
maps its graph elements into the same basic shape:

```json
{
  "target": "node",
  "type": "fact",
  "attribute": "reviewState",
  "value": "candidate",
  "action": "blur"
}
```

For extraction, prefer repo-scoping adapter parity as the next workplan. One
more Fabric-side polish pass is still useful for orientation workflows, but it
does not need to block proving the second host.

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.