Document graph explorer operations

2026-05-18 20:18:56 +02:00
parent 004e3cb976
commit 229191c802
3 changed files with 182 additions and 4 deletions
--- a/docs/graph-explorer-operations.md
+++ b/docs/graph-explorer-operations.md
@@ -0,0 +1,177 @@
+# 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.