feat(retrieval): replay trace tokens stamped by every strategy

Every CostStrategy result now carries a deterministic trace token —
sha256(doc_id | doc_version | model | system_prompt_version |
sorted(selected_ids)) hex-encoded. Same inputs always produce the
same 64-char hex string, regardless of reasoning path; permuted ID
order is invariant.

ComputeTraceToken is the canonical helper. SinglePass, ChunkedTree,
and AgenticStrategy each call it before returning. The Cached
wrapper re-derives the token on cache hits so the trace survives
the cache layer (the token is a pure function of cached inputs).

SystemPromptVersion ("v1") is bumped whenever a retrieval system
prompt changes in a way that should invalidate replay; the constant
is asserted in tests so the bump is a deliberate decision.

A future phase will replace the placeholder doc_version "1" with
real per-document versioning — the parameter is in the signature
already so that's a one-line change.

Author: hallelx2

pkg/retrieval/agentic.go

@@ -184,6 +184,7 @@ func (a *AgenticStrategy) SelectWithCost(ctx context.Context, t *tree.Tree, quer
 				ModelUsed:   model,
 				Usage:       totalUsage,
 				HopsTaken:   hopsTaken,
+				TraceToken:  ComputeTraceToken(t.DocumentID, traceDocVersionV1, model, finalIDs),
 			}, nil
 
 		case actionOutline:
@@ -243,6 +244,7 @@ func (a *AgenticStrategy) SelectWithCost(ctx context.Context, t *tree.Tree, quer
 		ModelUsed:   model,
 		Usage:       totalUsage,
 		HopsTaken:   hopsTaken,
+		TraceToken:  ComputeTraceToken(t.DocumentID, traceDocVersionV1, model, finalIDs),
 	}, nil
 }
 

pkg/retrieval/cached.go

@@ -77,15 +77,23 @@ func (c *Cached) Select(ctx context.Context, t *tree.Tree, query string, budget
 // SelectWithCost checks the cache first. On a hit it returns zero usage
 // (no LLM call was made). On a miss it delegates to the inner strategy's
 // SelectWithCost if available, otherwise falls back to Select.
+//
+// The replay trace token is preserved across cache hits: because the
+// token is a pure function of (document_id, doc_version, model, sorted
+// selected_ids) and the cache key already varies with document + model,
+// re-deriving the token from the cached slice produces the same value
+// the original strategy would have stamped.
 func (c *Cached) SelectWithCost(ctx context.Context, t *tree.Tree, query string, budget ContextBudget) (*Result, error) {
 	key := cache.Key(string(t.DocumentID), query, c.inner.Name(), budget.ModelName)
 
 	if v, ok := c.cache.Get(key); ok {
+		ids := v.([]tree.SectionID)
 		return &Result{
-			SelectedIDs: v.([]tree.SectionID),
+			SelectedIDs: ids,
 			Reasoning:   "cached",
 			ModelUsed:   budget.ModelName,
 			Usage:       Usage{}, // zero — no LLM call
+			TraceToken:  ComputeTraceToken(t.DocumentID, traceDocVersionV1, budget.ModelName, ids),
 		}, nil
 	}
 
@@ -101,7 +109,10 @@ func (c *Cached) SelectWithCost(ctx context.Context, t *tree.Tree, query string,
 		if err != nil {
 			return nil, err
 		}
-		result = &Result{SelectedIDs: ids}
+		result = &Result{
+			SelectedIDs: ids,
+			TraceToken:  ComputeTraceToken(t.DocumentID, traceDocVersionV1, budget.ModelName, ids),
+		}
 	}
 
 	c.cache.Set(key, result.SelectedIDs, c.ttl)

pkg/retrieval/chunked_tree.go

@@ -55,6 +55,9 @@ func (c *ChunkedTree) Select(ctx context.Context, t *tree.Tree, query string, bu
 
 // SelectWithCost implements CostStrategy.
 func (c *ChunkedTree) SelectWithCost(ctx context.Context, t *tree.Tree, query string, budget ContextBudget) (*Result, error) {
+	if t == nil || t.Root == nil {
+		return &Result{}, nil
+	}
 	tok := LLMTokenizer{C: c.LLM}
 	slices, err := c.Splitter.Split(ctx, t, budget, tok)
 	if err != nil {
@@ -109,10 +112,12 @@ func (c *ChunkedTree) SelectWithCost(ctx context.Context, t *tree.Tree, query st
 		totalUsage.Add(r.usage)
 	}
 
+	selected := c.Merge.Merge(allIDs)
 	return &Result{
-		SelectedIDs: c.Merge.Merge(allIDs),
+		SelectedIDs: selected,
 		Usage:       totalUsage,
 		HopsTaken:   1,
+		TraceToken:  ComputeTraceToken(t.DocumentID, traceDocVersionV1, budget.ModelName, selected),
 	}, nil
 }
 

pkg/retrieval/retrieval_test.go

@@ -316,3 +316,75 @@ func TestDefaultSplitterFastPath(t *testing.T) {
 		t.Errorf("breadcrumb missing doc title: %q", slices[0].Breadcrumb)
 	}
 }
+
+// TestSinglePassStampsTraceToken verifies that SelectWithCost
+// populates a 64-char hex TraceToken on the returned Result.
+func TestSinglePassStampsTraceToken(t *testing.T) {
+	tr := buildTree()
+	m := &mockLLM{pickIfPresent: []tree.SectionID{"sec_b"}}
+	s := retrieval.NewSinglePass(m)
+
+	res, err := s.SelectWithCost(context.Background(), tr, "q",
+		retrieval.ContextBudget{ModelName: "claude-sonnet-4-5", MaxTokens: 1000})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.TraceToken) != 64 {
+		t.Fatalf("trace_token must be 64 chars, got %d (%q)", len(res.TraceToken), res.TraceToken)
+	}
+	for _, r := range res.TraceToken {
+		if !((r >= '0' && r <= '9') || (r >= 'a' && r <= 'f')) {
+			t.Fatalf("trace_token must be lowercase hex, got %q", res.TraceToken)
+		}
+	}
+
+	// Same inputs → same token.
+	res2, err := s.SelectWithCost(context.Background(), tr, "q",
+		retrieval.ContextBudget{ModelName: "claude-sonnet-4-5", MaxTokens: 1000})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res2.TraceToken != res.TraceToken {
+		t.Errorf("same inputs must produce same trace_token: %q vs %q",
+			res.TraceToken, res2.TraceToken)
+	}
+}
+
+// TestChunkedTreeStampsTraceToken verifies that the chunked-tree
+// strategy populates the trace token on its returned Result.
+func TestChunkedTreeStampsTraceToken(t *testing.T) {
+	tr := buildTree()
+	m := &mockLLM{pickIfPresent: []tree.SectionID{"sec_a", "sec_b"}}
+	s := retrieval.NewChunkedTree(m)
+
+	res, err := s.SelectWithCost(context.Background(), tr, "q", retrieval.ContextBudget{
+		ModelName: "claude-sonnet-4-5", MaxTokens: 100000, MaxParallelCalls: 4,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.TraceToken) != 64 {
+		t.Fatalf("chunked-tree trace_token must be 64 chars, got %d", len(res.TraceToken))
+	}
+}
+
+// TestTraceTokenMatchesExternalComputation ties the strategy output to
+// the canonical ComputeTraceToken helper, so any drift between the
+// helper and the per-strategy plumbing is caught at test time.
+func TestTraceTokenMatchesExternalComputation(t *testing.T) {
+	tr := buildTree()
+	m := &mockLLM{pickIfPresent: []tree.SectionID{"sec_a"}}
+	s := retrieval.NewSinglePass(m)
+	model := "claude-sonnet-4-5"
+
+	res, err := s.SelectWithCost(context.Background(), tr, "q",
+		retrieval.ContextBudget{ModelName: model, MaxTokens: 1000})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := retrieval.ComputeTraceToken(tr.DocumentID, "1", model, res.SelectedIDs)
+	if res.TraceToken != want {
+		t.Errorf("strategy trace_token %q does not match ComputeTraceToken %q",
+			res.TraceToken, want)
+	}
+}

pkg/retrieval/single_pass.go

@@ -65,14 +65,21 @@ func (s *SinglePass) SelectWithCost(ctx context.Context, t *tree.Tree, query str
 		return nil, fmt.Errorf("single-pass llm call: %w", err)
 	}
 
+	selected := FilterKnownIDs(ids, view.Sections)
 	return &Result{
-		SelectedIDs: FilterKnownIDs(ids, view.Sections),
+		SelectedIDs: selected,
 		ModelUsed:   model,
 		Usage:       usage,
 		HopsTaken:   1,
+		TraceToken:  ComputeTraceToken(t.DocumentID, traceDocVersionV1, model, selected),
 	}, nil
 }
 
+// traceDocVersionV1 is the placeholder document version used by every
+// strategy until Phase 3.2 wires real per-document versioning. Defined
+// once so the bump is a one-line change.
+const traceDocVersionV1 = "1"
+
 // defaultSelectionRetries is the number of EXTRA attempts (on top of the first)
 // the selection LLM call gets when its response fails to parse as JSON. Gemini's
 // JSON mode occasionally returns plain text ("The most relevant section is...");

pkg/retrieval/strategy.go

@@ -70,6 +70,14 @@ type Result struct {
 	// strategies (e.g. agentic) set it to the number of tool-using turns
 	// actually consumed, including the terminal "done" turn.
 	HopsTaken int `json:"hops_taken,omitempty"`
+
+	// TraceToken is the replay token computed by ComputeTraceToken over
+	// the inputs that determine selection (document ID + version,
+	// retrieval model, system prompt version, sorted selected IDs).
+	// Two retrieval runs with identical inputs produce the same token,
+	// regardless of reasoning path. Empty when the strategy did not
+	// populate it (e.g. tests, fallback paths).
+	TraceToken string `json:"trace_token,omitempty"`
 }
 
 // Usage is the aggregated token + cost accounting across all LLM calls

pkg/retrieval/trace.go

@@ -0,0 +1,65 @@
+package retrieval
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"sort"
+
+	"github.com/hallelx2/vectorless-engine/pkg/tree"
+)
+
+// SystemPromptVersion is the build-time version stamp folded into every
+// trace token. Bump this whenever selectionSystemPrompt (or any other
+// retrieval system prompt whose change should invalidate replay) is
+// edited so that previously-cached replay entries are no longer
+// considered byte-equivalent.
+//
+// The version is a free-form string; "v1", "v2", … is the established
+// convention. Replay clients should treat it as opaque.
+const SystemPromptVersion = "v1"
+
+// ComputeTraceToken returns the canonical replay trace token for a
+// retrieval result.
+//
+// The token is sha256(doc_id || \0 || doc_version || \0 ||
+// retrieval_model || \0 || system_prompt_version || \0 ||
+// sorted(selected_ids).joined("\0")), hex-encoded lowercase. The output
+// is 64 hex characters.
+//
+// Sorting the IDs lexicographically makes the token order-invariant:
+// two strategies that select the same set of sections — even via
+// different reasoning paths — produce the same token. The NUL separator
+// prevents pathological IDs containing the chosen delimiter from
+// colliding (e.g. "a,b" + "c" vs "a" + "b,c").
+//
+// The doc_version parameter is a caller-controlled string so the engine
+// can layer document versioning on top in a future phase without
+// changing the function signature; today callers pass "1".
+func ComputeTraceToken(docID tree.DocumentID, docVersion, model string, ids []tree.SectionID) string {
+	// Defensive copy: callers reasonably expect ComputeTraceToken not to
+	// mutate the slice they pass in. Sorting in place would be a subtle
+	// foot-gun the next time someone reads selected_ids after computing
+	// the token.
+	sorted := make([]string, len(ids))
+	for i, id := range ids {
+		sorted[i] = string(id)
+	}
+	sort.Strings(sorted)
+
+	h := sha256.New()
+	h.Write([]byte(string(docID)))
+	h.Write([]byte{0})
+	h.Write([]byte(docVersion))
+	h.Write([]byte{0})
+	h.Write([]byte(model))
+	h.Write([]byte{0})
+	h.Write([]byte(SystemPromptVersion))
+	h.Write([]byte{0})
+	for i, id := range sorted {
+		if i > 0 {
+			h.Write([]byte{0})
+		}
+		h.Write([]byte(id))
+	}
+	return hex.EncodeToString(h.Sum(nil))
+}