diff --git a/README.md b/README.md index 1d59623..d35a808 100644 --- a/README.md +++ b/README.md @@ -105,5 +105,6 @@ loop. The graph explorer export is the first executable slice of the interactive Fabric map. See `docs/graph-explorer-transfer-review.md` for the repo-scoping -transfer review and `docs/graph-explorer-contract.md` for the shared manifest -and payload contract. +transfer review, `docs/graph-explorer-contract.md` for the shared manifest and +payload contract, and `docs/graph-explorer-operations.md` for launch, refresh, +verification, and extraction guidance. diff --git a/docs/graph-explorer-operations.md b/docs/graph-explorer-operations.md new file mode 100644 index 0000000..ea9d4ee --- /dev/null +++ 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; +}): 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. diff --git a/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md b/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md index 93a1f9b..6012562 100644 --- a/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md +++ b/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md @@ -4,7 +4,7 @@ type: workplan title: "Interactive Fabric Map" domain: railiance repo: railiance-fabric -status: active +status: finished owner: codex topic_slug: railiance planning_priority: high @@ -248,7 +248,7 @@ Acceptance notes: ```task id: RAIL-FAB-WP-0008-T06 -status: todo +status: done priority: medium state_hub_task_id: "d5567337-efe7-4fe6-8379-9e5505e25f6f" ```