RFC 0002: graph visualization export (export --format graph-json + omnigraph viz)#337
RFC 0002: graph visualization export (export --format graph-json + omnigraph viz)#337ssharma-dbx wants to merge 1 commit into
export --format graph-json + omnigraph viz)#337Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | | | | ||
| |---|---| | ||
| | **Status** | Proposed | | ||
| | **Author(s)** | Shreya Sharma (@shreya-sharma_data) | |
There was a problem hiding this comment.
@shreya-sharma_data will render as a GitHub user mention
The @shreya-sharma_data handle in the author field is not in a code span, so GitHub will resolve it as a user mention. If that handle belongs to a different account than ssharma-dbx (the PR filer), it notifies an unintended person; if it doesn't exist on GitHub at all, it silently becomes dead text. RFC 0001 uses a bare name (Ragnor Comerford) with no handle, which is the safer pattern here. Either wrap the handle in a backtick (`@shreya-sharma_data`) or replace it with the filing account (@ssharma-dbx) to keep attribution unambiguous.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| ``` | ||
|
|
||
| `export` reads schema from a `_schema.pg` sidecar that `init` does not write, so | ||
| export is unusable out of the box unless the operator manually drops the schema | ||
| file next to the datasets. The schema already lives in the catalog/`__manifest`; | ||
| the read path proposed here reconstructs types from there, removing the sidecar | ||
| dependency (see Reference-level design). This is the originating pain point. | ||
|
|
There was a problem hiding this comment.
The _schema.pg regression makes export unusable out of the box today — that's a real, independent defect. The project's guidelines (AGENTS.md §12) require bug fixes to land as a test-first, self-contained commit with a regression test that demonstrably goes red → green. Bundling the fix inside this RFC means the repair can't ship until the RFC is accepted, and an accepted RFC isn't the same as a landed, tested fix. The RFC's own unresolved questions section raises this directly ("Should the sidecar-removal … ship independently?").
Given the urgency (every fresh init + load hits this) the cleaner path is to open a standalone bug-fix PR first — with a test that reproduces the Object not found (os error 2) failure — and reference it from this RFC rather than conditioning it on acceptance. The RFC can still describe the catalog read path as the forward design, but the fix doesn't need to wait for the full visualization story to land.
Proposes a read-only way to see a graph: `export --format graph-json`
(a stable {nodes, edges, schema} interchange shape) and `omnigraph viz`
(a self-contained, dependency-free interactive node-link HTML — filter by
type, hover to highlight a neighborhood, click for a node's relationships).
Addresses through the existing snapshot/branch read path and Cedar `read`
gate; no on-disk, wire, or substrate change. Also motivates fixing the
`export` `_schema.pg` sidecar gap that breaks export on freshly init'd
graphs by reading schema from the catalog/__manifest instead.
Status: Proposed. Opened on the public RFC track (open to external
contributors per docs/rfcs/README.md); acceptance is a maintainer merge.
Co-authored-by: Isaac
ssharma-dbx
force-pushed
the
rfc/graph-visualization
branch
from
01229d0 to
7fe724d
Compare
1 participant
What
Adds RFC 0002: Graph visualization export (
docs/rfcs/0002-graph-visualization.md, Status: Proposed).It proposes a read-only way to see a graph:
export --format graph-json— a stable, versioned{ nodes, edges, schema }interchange shape that external tools (Cytoscape, Gephi, D3/Sigma) or the bundled renderer can consume without re-deriving node/edge structure.omnigraph viz— a convenience that renders that into a single self-contained, dependency-free, offline interactive node-link HTML: nodes colored by type + sized by degree, click-to-filter a type, hover to highlight a node's neighborhood, click for its properties and every relationship in/out. Works on any--branch/--snapshotand honors the Cedarreadgate.Why
There's currently no way to look at a graph —
exportonly streams row-oriented JSONL, so comprehension means hand-writing a converter and wiring an external tool every time. It's a universal day-one need for a knowledge-graph product, and the graph's own semantics (typed nodes, directed edges, branches) never make it into the view.The RFC also motivates fixing a real sharp edge found while prototyping:
omnigraph exportfails out of the box on a freshlyinit+load'd graph because it reads schema from a_schema.pgsidecar thatinitnever writes —The proposed read path reconstructs types from the catalog/
__manifestinstead, removing the sidecar dependency.Prototype
Backed by a working proof-of-concept: a ~25 KB self-contained HTML renderer fed by
exportoutput, exercised on a 27-node / 46-edge "company-brain" graph (People, Teams, Projects, Technologies, Documents, Decisions). It renders fully offline (no CDN), runs a vanilla-JS/SVG force layout, and does the hover-neighborhood + click-relationships + type-filter interactions described in the RFC. This PR proposes folding that into the CLI as a supported, tested surface.Scope / invariants
readgate. No Hard Invariant is weakened (see the RFC's Invariants & deny-list check).Process
Opened on the public RFC track (
docs/rfcs/), which perCONTRIBUTING.md/docs/rfcs/README.mdis open to external contributors and is the one PR type that doesn't require a pre-accepted issue — acceptance is a maintainer merge. Happy to move the discussion to a GitHub Discussion first if that's preferred, or to split theexportsidecar bug fix out as its own change.This pull request and its description were written by Isaac.
Greptile Summary
This PR adds RFC 0002, a design-doc-only proposal for
export --format graph-jsonandomnigraph viz, giving operators a first-class, read-only way to visualize a graph as a self-contained HTML file. No code is changed.export --format graph-jsonproposes a stable{ nodes, edges, schema }interchange shape consumed by external tools (Cytoscape, Gephi, D3/Sigma) or the bundled renderer; schema types would be reconstructed from the__manifestcatalog rather than a_schema.pgsidecar thatinitnever writes.omnigraph vizwould render that output into a single, CDN-free, offline HTML file addressable against any--branchor--snapshot.read, butPOST /graphs/{id}/exportalready requires the distinctexportaction; this needs correction so policy authors don't write under-privileged bundles.Confidence Score: 4/5
Design-doc only PR; the Cedar action misidentification in the Invariants section needs correction before acceptance so policy authors are not misled.
The RFC contains a concrete inaccuracy in the Invariants section: it asserts viz/graph-json go through the Cedar read gate, but the existing /export HTTP endpoint uses the distinct export action. An operator authoring a least-privilege policy bundle from this RFC would configure a read-only grant and be surprised when omnigraph viz --server fails authorization. The rest of the RFC is well-reasoned and follows the project RFC template.
docs/rfcs/0002-graph-visualization.md — Invariants section Cedar action claim and Reversibility section need correction.
Important Files Changed
Reviews (2): Last reviewed commit: "docs(rfc): add RFC 0002 — graph visualiz..." | Re-trigger Greptile
Context used: