Proposal: Define a Graph Determinism Contract to address recurring layout & handle inconsistencies

[Muawiya-contact]

Feature Details

Hi @AgniveshChaubey , I’ve been going through several recent graph-related issues and PRs, and I’m noticing a recurring pattern around:

• layout inconsistencies
• handle positioning issues
• stale graph state after updates

It seems like many of these are symptoms of the same underlying problem rather than isolated bugs.

Instead of addressing them individually, I wanted to propose defining a small “graph determinism contract” to make the graph pipeline more predictable and consistent.

A rough outline could include:

• stable node/edge identity rules
• clear triggers for layout + collision recomputation
• consistent handle anchoring (especially around $ref and $defs chains)

The idea would be to first align on these invariants, and then implement fixes against this shared contract rather than patching issues case-by-case.

If this direction sounds reasonable, I can:

• draft a short RFC / design note
• identify affected areas in the current pipeline
• follow up with small, focused PRs

Would really appreciate feedback on whether this aligns with the intended direction for the graph system.

Good First Issue

• I believe this issue is a good first issue for new contributors.

Contribution

• I am willing to work on this feature.

[AgniveshChaubey]

layout inconsistencies
handle positioning issues
stale graph state after updates

I'm aware of handle positioning issue, but can you please share an example of where you noticed the other two points?

[Muawiya-contact]

Hi @AgniveshChaubey,

Here are specific examples I've identified:

Layout Inconsistencies & Stale State Examples:

1. Stale Dagre Graph Instance (#199)

• Symptom: When switching between schemas with different property counts, node positions don't recalculate cleanly
• Root Cause: Dagre graph is a module-level singleton that retains nodes from previous schema compilations
• Status: PR Bug: Edge highlights persist after deselection #306 has a fix ready (moving graph instantiation to function scope)

2. Handle Position Determinism (#201)

• Symptom: Handle positions are inconsistent across schema recompiles
• Trigger: Especially problematic with $ref and $defs chains where handles should anchor predictably
• Impact: Makes edge connections appear to "shift" unexpectedly

3. Search State Invalidation (#244)

• Symptom: When schema changes, search results still reference old node positions
• Trigger: Search state isn't invalidated when graph re-layouts
• Impact: Clicking search results navigates to stale positions

4. Collision Resolution Inconsistency (#247)

• Symptom: Collision physics trigger unpredictably during graph updates
• Root Cause: No clear signal for when collision recomputation should run
• Impact: Nodes sometimes overlap, sometimes spread inconsistently

Proposed Contract Invariants:

1. Layout Stability: Each schema compilation gets a fresh graph instance
2. Handle Determinism: Handles anchor consistently based on property path (not coordinate drift)
3. State Invalidation: Search, collision, and position state clear on schema change
4. Identity Consistency: Node IDs remain same across compilations if property path unchanged

Would this align with the direction you're thinking?

[Muawiya-contact]

@AgniveshChaubey any direction for me? Should i start work on it?