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:

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

Open the map:

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

Useful supporting endpoints:

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:

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

Refresh the known local Railiance repos:

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:

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:

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

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

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:

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:

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.