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.

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:

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, rule 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 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:

{
  "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:

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.