Keep edited-file read views and bounded retries consistent

cmd/gortex/wire_contract_test.go

@@ -123,16 +123,16 @@ func wireContractGolden(name string) string {
 		// ProjectID, were added.
 		return "a600bd906c9e09ffa0828427f5d6622acd5fe244798a61d5712c151053be5dac"
 	case "graph.Edge":
-		// Bumped when NameOnly was added — the marker on a synthesized
-		// name-only candidate row (a call site that named the symbol but
-		// never bound to it, projected onto it by find_usages /
-		// get_callers under min_tier:"text_matched"). Set only on the
-		// in-memory projection, so a persisted edge always carries it
-		// false; not part of the edge identity / dedup key.
-		// (Previously bumped when Alias — the renamed name carried by a
-		// per-binding import or re-export edge — then Via, ReturnUsage,
+		// Bumped when Provisional was added — the marker on a stored call
+		// edge carried onto an overlay that re-parsed its file before
+		// relations were rebuilt. Set only on the in-memory overlay, so a
+		// persisted edge always carries it false; not part of the edge
+		// identity / dedup key.
+		// (Previously bumped when NameOnly — the marker on a synthesized
+		// name-only candidate row projected by find_usages / get_callers
+		// under min_tier:"text_matched" — then Alias, Via, ReturnUsage,
 		// Context, and Tier, were added.)
-		return "d27d737c6c164243e2d55b4ca265a46d658e9617546f20306e9357e17aa46603"
+		return "fb8425eff2fe4f2b17d665fd182a48b6f5f5b832c90dc750ca4f933b639cee2c"
 	default:
 		panic(fmt.Sprintf("no golden fingerprint for %s", name))
 	}

internal/graph/delta_writer_payload.go

@@ -84,6 +84,7 @@ func deltaEdgeRender(e *Edge) string {
 	c.Via = ""
 	c.Alias = ""
 	c.NameOnly = false
+	c.Provisional = false
 	return fmt.Sprintf("%+v", c)
 }
 
@@ -145,10 +146,10 @@ func deltaEdgeContentEqual(a, b *Edge) bool {
 }
 
 // deltaEdgeFieldsCompared is the number of Edge fields deltaEdgeContentEqual
-// accounts for (the ten it compares, Meta, and the five that are not
+// accounts for (the ten it compares, Meta, and the six that are not
 // persisted). An Edge with another field falls back to the rendered
 // comparison until the comparison learns it.
-const deltaEdgeFieldsCompared = 16
+const deltaEdgeFieldsCompared = 17
 
 var deltaEdgeFields = reflect.TypeOf(Edge{}).NumField()
 

internal/graph/edge.go

@@ -621,6 +621,13 @@ type Edge struct {
 	// only on the in-memory projection under min_tier:"text_matched";
 	// never persisted, never part of the edge identity / dedup key.
 	NameOnly bool `json:"name_only,omitempty"`
+	// Provisional marks a stored relation carried onto an overlay that
+	// re-parsed its file before relations were rebuilt: the new content
+	// still references the same target from the same source, so the edge
+	// is served at the reference's new line until the reindex confirms
+	// it. Set only on the in-memory overlay; never persisted, never part
+	// of the edge identity / dedup key.
+	Provisional bool `json:"provisional,omitempty"`
 	// Meta is intentionally excluded from JSON. It holds internal
 	// instrumentation (semantic_source, provider hints, etc.) that agents
 	// don't consume but that adds measurable bytes to every edge in

internal/graph/file_editing_context.go

@@ -11,7 +11,7 @@ import "sort"
 //
 // Every read is a batched Reader call, so a reader wrapper that narrows
 // adjacency gets the same fixed round-trip count with its own edge semantics.
-func FileEditingContextOf(r Reader, filePath string, kinds []NodeKind) *FileEditingContextResult {
+func FileEditingContextOf(r FileEditingContextRows, filePath string, kinds []NodeKind) *FileEditingContextResult {
 	if filePath == "" {
 		return nil
 	}

internal/graph/file_editing_context_context.go

@@ -0,0 +1,162 @@
+package graph
+
+import (
+	"context"
+	"errors"
+)
+
+var ErrFileEditingContextUnsupported = errors.New("cancellable editing context unsupported")
+
+// FileEditingContextRows is the full-field input to the editing-context bundle.
+// It deliberately exposes no mutation, scan, transaction or unrelated graph API.
+type FileEditingContextRows interface {
+	GetFileNodes(string) []*Node
+	GetNode(string) *Node
+	GetOutEdges(string) []*Edge
+	GetNodesByIDs([]string) map[string]*Node
+	GetOutEdgesByNodeIDs([]string) map[string][]*Edge
+	GetInEdgesByNodeIDs([]string) map[string][]*Edge
+}
+
+// FileEditingContextReadScope lends a reader only for the synchronous bundle
+// callback. The callback may use only the five reads in FileEditingContextOf
+// (and GetNode for overlay endpoint visibility). It must not retain the reader.
+// Implementations reject cancellation, partial rows and changed revisions after
+// the callback; a callback result is usable only when this method returns nil.
+// This narrow scope is not a general Reader transaction API.
+type FileEditingContextReadScope interface {
+	WithFileEditingContextReader(context.Context, func(context.Context, FileEditingContextRows) error) error
+}
+
+type FileEditingContextLayerScope interface {
+	WithFileEditingContextLayer(context.Context, func(context.Context, OverlayLayerReader) error) error
+}
+
+func WithFileEditingContextReader(ctx context.Context, r Reader, fn func(context.Context, FileEditingContextRows) error) error {
+	if ctx == nil {
+		return ErrFileEditingContextUnsupported
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	scoped, ok := r.(FileEditingContextReadScope)
+	if !ok {
+		return ErrFileEditingContextUnsupported
+	}
+	return scoped.WithFileEditingContextReader(ctx, fn)
+}
+
+func (v *OverlaidView) WithFileEditingContextReader(ctx context.Context, fn func(context.Context, FileEditingContextRows) error) error {
+	if ctx == nil {
+		return ErrFileEditingContextUnsupported
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	withLayer := func(ctx context.Context, base FileEditingContextRows) error {
+		if v.layer == nil {
+			return fn(ctx, NewOverlaidViewWithLayer(editingContextReaderOf(base), nil))
+		}
+		layer, ok := v.layer.(FileEditingContextLayerScope)
+		if !ok {
+			return ErrFileEditingContextUnsupported
+		}
+		return layer.WithFileEditingContextLayer(ctx, func(ctx context.Context, l OverlayLayerReader) error {
+			return fn(ctx, &editingContextView{NewOverlaidViewWithLayer(editingContextReaderOf(base), l)})
+		})
+	}
+	if v.base == nil {
+		return withLayer(ctx, nil)
+	}
+	return WithFileEditingContextReader(ctx, v.base, withLayer)
+}
+
+func (g *Graph) WithFileEditingContextReader(ctx context.Context, fn func(context.Context, FileEditingContextRows) error) error {
+	if ctx == nil {
+		return ErrFileEditingContextUnsupported
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	revision := g.MutationRevision()
+	if err := fn(ctx, g); err != nil {
+		return err
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if revision != g.MutationRevision() {
+		return ErrContractProjectionStale
+	}
+	return nil
+}
+func (l *OverlayLayer) WithFileEditingContextLayer(ctx context.Context, fn func(context.Context, OverlayLayerReader) error) error {
+	if ctx == nil {
+		return ErrFileEditingContextUnsupported
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if err := fn(ctx, l); err != nil {
+		return err
+	}
+	return ctx.Err()
+}
+
+// The ephemeral composition only invokes the six bundle reads. A nil embedded
+// Reader makes any accidental expansion fail rather than reach a live backend.
+type editingContextReader struct {
+	Reader
+	FileEditingContextRows
+}
+
+func editingContextReaderOf(rows FileEditingContextRows) Reader {
+	if rows == nil {
+		return nil
+	}
+	return &editingContextReader{FileEditingContextRows: rows}
+}
+func (r *editingContextReader) GetFileNodes(path string) []*Node {
+	return r.FileEditingContextRows.GetFileNodes(path)
+}
+func (r *editingContextReader) GetNode(id string) *Node { return r.FileEditingContextRows.GetNode(id) }
+func (r *editingContextReader) GetOutEdges(id string) []*Edge {
+	return r.FileEditingContextRows.GetOutEdges(id)
+}
+func (r *editingContextReader) GetNodesByIDs(ids []string) map[string]*Node {
+	return r.FileEditingContextRows.GetNodesByIDs(ids)
+}
+func (r *editingContextReader) GetOutEdgesByNodeIDs(ids []string) map[string][]*Edge {
+	return r.FileEditingContextRows.GetOutEdgesByNodeIDs(ids)
+}
+func (r *editingContextReader) GetInEdgesByNodeIDs(ids []string) map[string][]*Edge {
+	return r.FileEditingContextRows.GetInEdgesByNodeIDs(ids)
+}
+
+// Keep durable incoming reads batched without advertising the unrelated
+// OverlayLayerProjectionReader scans on the narrow borrowed layer.
+type editingContextLayerIncoming interface {
+	FileEditingContextInEdgesByNodeIDs([]string) map[string][]*Edge
+}
+type editingContextView struct{ *OverlaidView }
+
+func (v *editingContextView) GetInEdgesByNodeIDs(ids []string) map[string][]*Edge {
+	layer, ok := v.layer.(editingContextLayerIncoming)
+	if !ok {
+		return v.OverlaidView.GetInEdgesByNodeIDs(ids)
+	}
+	out := make(map[string][]*Edge, len(ids))
+	if v.base != nil {
+		for id, edges := range v.base.GetInEdgesByNodeIDs(ids) {
+			for _, edge := range edges {
+				if v.baseEdgeVisible(edge) {
+					out[id] = append(out[id], edge)
+				}
+			}
+		}
+	}
+	for id, edges := range layer.FileEditingContextInEdgesByNodeIDs(ids) {
+		out[id] = append(out[id], edges...)
+	}
+	return out
+}

internal/graph/file_editing_context_context_test.go

@@ -0,0 +1,43 @@
+package graph
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// The old contextual node capability must not be mistaken for a safe bundle
+// layer: OverlaidView's legacy batch refetch still calls layer.NodeByID.
+type editingContextUnsafeLayer struct{ OverlayLayerReader }
+
+func (l *editingContextUnsafeLayer) NodeByID(string) *Node { panic("contextless physical node lookup") }
+func (l *editingContextUnsafeLayer) GetNodesByIDsContext(context.Context, []string) (map[string]*Node, error) {
+	return nil, nil
+}
+
+func TestEditingContextScopeRejectsContextualLookingLegacyLayer(t *testing.T) {
+	layer := NewOverlayLayer()
+	layer.MarkFile("a.go", false)
+	view := NewOverlaidViewWithLayer(New(), &editingContextUnsafeLayer{layer})
+	called := false
+	err := WithFileEditingContextReader(t.Context(), view, func(context.Context, FileEditingContextRows) error { called = true; return nil })
+	require.ErrorIs(t, err, ErrFileEditingContextUnsupported)
+	require.False(t, called)
+}
+
+func TestEditingContextScopeMemoryOwnershipParity(t *testing.T) {
+	base := New()
+	base.AddNode(&Node{ID: "a.go::f", Kind: KindFunction, FilePath: "a.go", Meta: map[string]any{"signature": "base"}})
+	base.AddNode(&Node{ID: "b.go::g", Kind: KindFunction, FilePath: "b.go", Meta: map[string]any{"full": "neighbor"}})
+	base.AddEdge(&Edge{From: "b.go::g", To: "a.go::f", Kind: EdgeCalls, FilePath: "b.go"})
+	layer := NewOverlayLayer()
+	layer.MarkFile("a.go", false)
+	layer.AddNode("a.go", &Node{ID: "a.go::f", Kind: KindFunction, FilePath: "a.go", Meta: map[string]any{"signature": "selected"}})
+	view := NewOverlaidView(base, layer)
+	want := FileEditingContextOf(view, "a.go", []NodeKind{KindFunction})
+	require.NoError(t, WithFileEditingContextReader(t.Context(), view, func(_ context.Context, rows FileEditingContextRows) error {
+		require.Equal(t, want, FileEditingContextOf(rows, "a.go", []NodeKind{KindFunction}))
+		return nil
+	}))
+}

internal/graph/overlay.go

@@ -304,6 +304,95 @@ func (l *OverlayLayer) RebuildInEdges() {
 	}
 }
 
+// CarryBaseEdges returns provisional copies of the call edges base recorded in
+// file that layerEdges, the file's re-parse, still make. A layer that covers a
+// file hides every base edge recorded there, while the re-parse holds its calls
+// as unresolved references until relations are rebuilt, so an edited function
+// would otherwise lose its callees and drop out of its callees' callers. A base
+// call is carried when the re-parse has an unresolved call from the same
+// source to the target's name; the copy takes that call's line. Repeated calls
+// pair up in line order, and a call the re-parse no longer makes is dropped.
+func CarryBaseEdges(base Reader, file string, layerEdges []*Edge) []*Edge {
+	type site struct{ from, name string }
+	refs := make(map[site][]*Edge)
+	for _, e := range layerEdges {
+		if e == nil || e.Kind != EdgeCalls || !IsUnresolvedTarget(e.To) || IsFnValuePlaceholder(e.To) {
+			continue
+		}
+		key := site{e.From, unresolvedCallName(e.To)}
+		refs[key] = append(refs[key], e)
+	}
+	if base == nil || len(refs) == 0 {
+		return nil
+	}
+	for _, at := range refs {
+		sortEdgesByLine(at)
+	}
+	var ids []string
+	for _, n := range base.GetFileNodes(file) {
+		ids = append(ids, n.ID)
+	}
+	var recorded []*Edge
+	var targets []string
+	for _, edges := range base.GetOutEdgesByNodeIDs(ids) {
+		for _, e := range edges {
+			if e != nil && e.Kind == EdgeCalls && e.FilePath == file && !IsUnresolvedTarget(e.To) {
+				recorded = append(recorded, e)
+				targets = append(targets, e.To)
+			}
+		}
+	}
+	sortEdgesByLine(recorded)
+	names := base.GetNodesByIDs(targets)
+	used := make(map[site]int, len(refs))
+	var carried []*Edge
+	for _, e := range recorded {
+		target := names[e.To]
+		if target == nil {
+			continue
+		}
+		key := site{e.From, target.Name}
+		at := refs[key]
+		if used[key] >= len(at) {
+			continue
+		}
+		c := *e
+		c.Line = at[used[key]].Line
+		c.Provisional = true
+		used[key]++
+		carried = append(carried, &c)
+	}
+	return carried
+}
+
+// unresolvedCallName is the bare callee name of an unresolved call target:
+// `unresolved::Name`, `unresolved::*.name` and qualified forms all name their
+// last segment.
+func unresolvedCallName(id string) string {
+	name := UnresolvedName(id)
+	if i := strings.LastIndex(name, "::"); i >= 0 {
+		name = name[i+2:]
+	}
+	if i := strings.LastIndexByte(name, '.'); i >= 0 {
+		name = name[i+1:]
+	}
+	return name
+}
+
+// sortEdgesByLine orders edges by source, line and target.
+func sortEdgesByLine(edges []*Edge) {
+	sort.Slice(edges, func(i, j int) bool {
+		a, b := edges[i], edges[j]
+		if a.From != b.From {
+			return a.From < b.From
+		}
+		if a.Line != b.Line {
+			return a.Line < b.Line
+		}
+		return a.To < b.To
+	})
+}
+
 // OverlaidView composes an immutable base Reader with a per-session
 // overlay layer. Every read path consults the layer first for paths
 // the overlay covers; falls through to base otherwise. The base is