P0 Master Tracker: Visual Editor MVP + Dataflow Trace + Debugger Bridge

[emil14]

Goal

Ship a practical Visual Editor MVP (readonly-first) for Neva, grounded on one runtime execution truth: Dataflow Trace (aka Graph trace).

This tracker coordinates work across repositories:

• nevalang/neva
• nevalang/neva-lsp
• nevalang/vscode-nevalang

Linked Context

• Implement Visual Editor for Source Code level (AST) Program Representation #970
• Debugger: Design Space & Direction #977
• Log "graph trace" after panic #595
• Runtime trace store/query API for panic, debugger, and errors formatting #1050
• Panic doesn't terminate program with exit code 1 #792
• Design proposal: complete std/errors API for Neva dataflow #1046
• Debugger implementation #36
• Implement visualizer of source code at high-level (not just IR) #827
• Revisit language features in context of visual editor #935

Delivery Defaults

• MVP is readonly visualization + navigation + trace overlay/playback.
• No full visual write-back in first wave.
• DAP is non-blocking for MVP; trace core first, thin adapter later.
• Dataflow Trace is canonical term; Graph trace remains accepted alias.

Phase Checklist

Phase A — Runtime Trace Core (neva)

• Introduce runtime Dataflow Trace model (message identity, ancestry, sent/recv hop events).
• Provide trace query API: path / cause trace / formatted trace.
• Ensure hot-path tracing without stop-the-world default behavior.
• Panic path prints panic: + dataflow cause trace.
• Close panic process-exit semantics (Panic doesn't terminate program with exit code 1 #792).
• Stabilize machine-readable trace event format with explicit versioning.

Phase B — Source Graph Contract (neva)

• Lock source-level GraphDocument/ComponentGraph contract (AST-level, not IR-level).
• Add compiler debug sidecar mapping: SourceEdgeID <-> runtime edges.
• Mark synthetic runtime edges explicitly in sidecar.
• Provide readonly Mermaid rendering from source graph contract.
• Lock stable ID strategy for nodes/ports/edges/anchors.

Phase C — Tooling API (neva-lsp)

• Add endpoints for source graph payload by file/package/component scope.
• Add trace-query endpoint (path/cause/format), backend-agnostic.
• Keep runtime internals outside UI payloads (source IDs + overlays only).

Phase D — VSCode UX MVP (vscode-nevalang)

• Add readonly visual graph preview command with drill-down navigation.
• Add trace overlay/playback on source edges.
• Add minimal debugger bridge using trace-query primitives.

Cross-Session Operating Rules

• Keep this issue as the single status board.
• At end of each session:
  • update checklist status,
  • post a short progress comment (Done / Decisions / Risks / Next 3 Steps / Links),
  • sync contract changes to docs (docs/qna.md and related issue threads).

Validation Targets

• Runtime trace deterministic path reconstruction (linear + fan-in/out + bypass cases).
• Panic output includes cause trace and exits non-zero.
• Source graph projection preserves source semantics (chain/selector/const/fan-in/fan-out/bypass).
• Overlay mapping does not leak synthetic runtime internals into UX.

[emil14]

Visual Editor Session Snapshot

Date

• 2026-05-10

Done

• Added runtime Dataflow Trace core in neva:
  • trace envelope on runtime messages,
  • sent/recv hop recording,
  • path reconstruction API,
  • formatted cause trace output for panic.
• Updated panic signaling semantics:
  • runtime call now tracks and returns program panic errors,
  • generated executable exits with code 1 on panic without duplicate runtime-error line.
• Added machine-readable trace event output v1 in DebugInterceptor (JSON lines).
• Added tests for trace ancestry and panic error semantics in internal/runtime.
• Created P0 master tracker issue: P0 Master Tracker: Visual Editor MVP + Dataflow Trace + Debugger Bridge #1118.
• Updated .agent/plans/visual_node_editor.md with split-repo/LSP-externalized baseline corrections.
• Added snapshot template and updated docs/qna.md terminology (Dataflow Trace as canonical).

Decisions

• Dataflow Trace is canonical term; Graph trace remains alias.
• Runtime trace core is implemented first; DAP remains a later adapter concern.
• Cross-repo execution model is explicit (neva + neva-lsp + vscode-nevalang).

Risks

• Current ancestry model is single-parent lineage; fan-in causality trees need follow-up semantics.
• Source graph contract + compiler sidecar mapping not yet implemented in this session.
• LSP and VSCode tracks are out-of-repo and still pending.

Next 3 Steps

1. Design and implement source-level GraphDocument/ComponentGraph contract in neva with stable IDs.
2. Add compiler debug sidecar mapping SourceEdgeID <-> runtime edges and tests for mapping invariants.
3. Open companion tracker issues in neva-lsp and vscode-nevalang, linked back to P0 Master Tracker: Visual Editor MVP + Dataflow Trace + Debugger Bridge #1118.

Linked Issues / PRs

• P0 Master Tracker: Visual Editor MVP + Dataflow Trace + Debugger Bridge #1118 (master tracker)
• Implement Visual Editor for Source Code level (AST) Program Representation #970
• Debugger: Design Space & Direction #977
• Log "graph trace" after panic #595
• Runtime trace store/query API for panic, debugger, and errors formatting #1050
• Panic doesn't terminate program with exit code 1 #792
• Design proposal: complete std/errors API for Neva dataflow #1046

[emil14]

Cross-session note (problem statement only, no implementation commitment):

Debugging abstraction gap after graph reduction

We need to preserve a debugger-facing mapping between source-level connections (AST graph) and runtime hops (post-reduction execution graph).

Why this matters:

• Breakpoints/watchpoints are naturally set on source connections/components.
• Runtime tracing currently observes actual message hops between runtime funcs.
• After graph reduction, intermediate source connections may not exist as runtime edges.
• Without mapping, users debug a different graph than the one they authored.

Scope for future brainstorming:

• Keep this as a design constraint for debugger/visual editor tracks.
• Do not commit to a concrete storage/protocol now.
• Evaluate options for source<->runtime provenance metadata and synthetic-edge handling later.

Related issues: #977 #1050 #970 #827