feat(retrieval): in-memory LRU replay store + retrieval.replay config

LRUReplayStore is a thin facade over pkg/cache.LRU that maps trace
tokens to ReplayEntry values (DocumentID + Query + Model +
SelectedIDs + raw ResponseJSON bytes + CreatedAt). The store is
safe for concurrent Put/Get, bounds itself by MaxEntries (default
1024) and expires entries past TTL (default 24h).

ReplayEntry.ResponseJSON is the literal bytes of the original
response — replay returns these verbatim so the byte-exact
guarantee holds regardless of how the response is constructed.
Go's encoding/json already sorts map keys lexicographically, but
storing raw bytes removes any future doubt about determinism.

retrieval.replay config block ships with Enabled=true: replay is
the moat versus stateless vector RAG and should be on by default.
Operators can opt out via retrieval.replay.enabled=false or
VLE_RETRIEVAL_REPLAY_ENABLED=false. Capacity / TTL tune via
VLE_RETRIEVAL_REPLAY_MAX_ENTRIES and VLE_RETRIEVAL_REPLAY_TTL_SECONDS.

Tests cover Put/Get, miss, empty-token safety, LRU eviction at
capacity, TTL expiry, in-place update, byte-exactness on tricky
payloads (whitespace + unicode), default-TTL non-zero, and a
parallel hammer that surfaces races under go test -race.

Not durable across process restarts — Phase 3.2 will replace this
with persistent storage + per-document versioning. The interface
abstraction (ReplayStore) lets that swap happen without touching
handlers.

Author: hallelx2

pkg/config/config.go

@@ -205,6 +205,31 @@ type RetrievalConfig struct {
 	Answer      AnswerBlock      `yaml:"answer"`
 	Planning    PlanningBlock    `yaml:"planning"`
 	ReRank      ReRankBlock      `yaml:"rerank"`
+	Replay      ReplayBlock      `yaml:"replay"`
+}
+
+// ReplayBlock configures the Phase 3.1 replay-trace store.
+//
+// When enabled, every /v1/query and /v1/answer response is stamped
+// with a deterministic trace_token and the response body is stored
+// in an in-memory LRU. Callers can POST /v1/replay with the token
+// (plus the original query + document_id) to retrieve the byte-
+// identical response.
+//
+// The store is opt-out — replay is a moat versus stateless vector
+// RAG and should ship on by default. Disable to free the memory
+// budget when audit/replay isn't part of the operator's flow.
+type ReplayBlock struct {
+	// Enabled turns the replay store on. Default: true.
+	Enabled bool `yaml:"enabled"`
+
+	// MaxEntries bounds the in-memory LRU. Default: 1024.
+	MaxEntries int `yaml:"max_entries"`
+
+	// TTLSeconds is how long a replay entry remains valid. Default:
+	// 86400 (24h). Long-running audit flows may want to bump this;
+	// short-TTL deployments save memory.
+	TTLSeconds int `yaml:"ttl_seconds"`
 }
 
 // ReRankBlock configures the Phase 2.3 content-aware re-rank pass.
@@ -411,6 +436,11 @@ func Default() Config {
 				MaxContentChars: 2000,
 				TopK:            0,
 			},
+			Replay: ReplayBlock{
+				Enabled:    true,
+				MaxEntries: 1024,
+				TTLSeconds: 86400,
+			},
 		},
 		Ingest: IngestConfig{
 			GlobalLLMConcurrency: 12,
@@ -620,6 +650,24 @@ func applyEnvOverrides(c *Config) {
 			c.Retrieval.ReRank.TopK = n
 		}
 	}
+	if v := os.Getenv("VLE_RETRIEVAL_REPLAY_ENABLED"); v != "" {
+		switch strings.ToLower(strings.TrimSpace(v)) {
+		case "1", "true", "yes", "on":
+			c.Retrieval.Replay.Enabled = true
+		case "0", "false", "no", "off":
+			c.Retrieval.Replay.Enabled = false
+		}
+	}
+	if v := os.Getenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			c.Retrieval.Replay.MaxEntries = n
+		}
+	}
+	if v := os.Getenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			c.Retrieval.Replay.TTLSeconds = n
+		}
+	}
 }
 
 // Validate checks that required fields for the selected drivers are set.
@@ -713,5 +761,12 @@ func (c Config) Validate() error {
 		return fmt.Errorf("retrieval.rerank.top_k must be >= 0, got %d", c.Retrieval.ReRank.TopK)
 	}
 
+	if c.Retrieval.Replay.MaxEntries < 0 {
+		return fmt.Errorf("retrieval.replay.max_entries must be >= 0, got %d", c.Retrieval.Replay.MaxEntries)
+	}
+	if c.Retrieval.Replay.TTLSeconds < 0 {
+		return fmt.Errorf("retrieval.replay.ttl_seconds must be >= 0, got %d", c.Retrieval.Replay.TTLSeconds)
+	}
+
 	return nil
 }

pkg/config/config_test.go

@@ -55,11 +55,110 @@ func TestDefaultValues(t *testing.T) {
 	if cfg.Retrieval.ReRank.TopK != 0 {
 		t.Errorf("retrieval.rerank.top_k = %d, want 0 (keep all)", cfg.Retrieval.ReRank.TopK)
 	}
+	if !cfg.Retrieval.Replay.Enabled {
+		t.Error("retrieval.replay.enabled should default to true (opt-out)")
+	}
+	if cfg.Retrieval.Replay.MaxEntries != 1024 {
+		t.Errorf("retrieval.replay.max_entries = %d, want 1024", cfg.Retrieval.Replay.MaxEntries)
+	}
+	if cfg.Retrieval.Replay.TTLSeconds != 86400 {
+		t.Errorf("retrieval.replay.ttl_seconds = %d, want 86400 (24h)", cfg.Retrieval.Replay.TTLSeconds)
+	}
 	if cfg.Log.Level != "info" {
 		t.Errorf("log.level = %q, want info", cfg.Log.Level)
 	}
 }
 
+func TestReplayEnvOverride(t *testing.T) {
+	// Not parallel — mutates env. Restore on exit.
+	prevEnabled := os.Getenv("VLE_RETRIEVAL_REPLAY_ENABLED")
+	prevMax := os.Getenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES")
+	prevTTL := os.Getenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS")
+	defer func() {
+		os.Setenv("VLE_RETRIEVAL_REPLAY_ENABLED", prevEnabled)
+		os.Setenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES", prevMax)
+		os.Setenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS", prevTTL)
+	}()
+
+	os.Setenv("VLE_RETRIEVAL_REPLAY_ENABLED", "false")
+	os.Setenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES", "256")
+	os.Setenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS", "3600")
+
+	cfg := Default()
+	applyEnvOverrides(&cfg)
+
+	if cfg.Retrieval.Replay.Enabled {
+		t.Error("VLE_RETRIEVAL_REPLAY_ENABLED=false should disable replay")
+	}
+	if cfg.Retrieval.Replay.MaxEntries != 256 {
+		t.Errorf("replay max_entries = %d, want 256", cfg.Retrieval.Replay.MaxEntries)
+	}
+	if cfg.Retrieval.Replay.TTLSeconds != 3600 {
+		t.Errorf("replay ttl_seconds = %d, want 3600", cfg.Retrieval.Replay.TTLSeconds)
+	}
+}
+
+func TestReplayEnvOverrideEnable(t *testing.T) {
+	// Toggle on via env from an explicitly-disabled starting state.
+	prev := os.Getenv("VLE_RETRIEVAL_REPLAY_ENABLED")
+	defer os.Setenv("VLE_RETRIEVAL_REPLAY_ENABLED", prev)
+
+	cfg := Default()
+	cfg.Retrieval.Replay.Enabled = false
+	os.Setenv("VLE_RETRIEVAL_REPLAY_ENABLED", "true")
+	applyEnvOverrides(&cfg)
+	if !cfg.Retrieval.Replay.Enabled {
+		t.Error("VLE_RETRIEVAL_REPLAY_ENABLED=true should enable replay even when disabled in YAML")
+	}
+}
+
+func TestReplayEnvOverrideRejectsBad(t *testing.T) {
+	prevMax := os.Getenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES")
+	prevTTL := os.Getenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS")
+	defer func() {
+		os.Setenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES", prevMax)
+		os.Setenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS", prevTTL)
+	}()
+
+	os.Setenv("VLE_RETRIEVAL_REPLAY_MAX_ENTRIES", "not-a-number")
+	os.Setenv("VLE_RETRIEVAL_REPLAY_TTL_SECONDS", "wat")
+
+	cfg := Default()
+	applyEnvOverrides(&cfg)
+	if cfg.Retrieval.Replay.MaxEntries != 1024 {
+		t.Errorf("bad max_entries env should preserve default, got %d", cfg.Retrieval.Replay.MaxEntries)
+	}
+	if cfg.Retrieval.Replay.TTLSeconds != 86400 {
+		t.Errorf("bad ttl_seconds env should preserve default, got %d", cfg.Retrieval.Replay.TTLSeconds)
+	}
+}
+
+func TestValidateReplayNegatives(t *testing.T) {
+	t.Parallel()
+
+	cfg := Default()
+	cfg.Database.URL = "postgres://localhost/test"
+	cfg.Retrieval.Replay.MaxEntries = -1
+	if err := cfg.Validate(); err == nil {
+		t.Error("negative replay max_entries should fail validation")
+	}
+
+	cfg2 := Default()
+	cfg2.Database.URL = "postgres://localhost/test"
+	cfg2.Retrieval.Replay.TTLSeconds = -1
+	if err := cfg2.Validate(); err == nil {
+		t.Error("negative replay ttl_seconds should fail validation")
+	}
+
+	cfg3 := Default()
+	cfg3.Database.URL = "postgres://localhost/test"
+	cfg3.Retrieval.Replay.MaxEntries = 0
+	cfg3.Retrieval.Replay.TTLSeconds = 0
+	if err := cfg3.Validate(); err != nil {
+		t.Errorf("zero replay values should pass validation (use defaults at runtime): %v", err)
+	}
+}
+
 func TestReRankEnvOverride(t *testing.T) {
 	// Not parallel — mutates env. Restore on exit.
 	prevEnabled := os.Getenv("VLE_RETRIEVAL_RERANK_ENABLED")

pkg/retrieval/replay.go

@@ -0,0 +1,152 @@
+package retrieval
+
+import (
+	"sync"
+	"time"
+
+	"github.com/hallelx2/vectorless-engine/pkg/cache"
+	"github.com/hallelx2/vectorless-engine/pkg/tree"
+)
+
+// ReplayStore is the persistence interface for replay-trace entries.
+// Implementations MUST be safe for concurrent use; the HTTP layer
+// writes from /v1/query and /v1/answer handlers and reads from
+// /v1/replay handlers at the same time.
+type ReplayStore interface {
+	// Get retrieves a stored replay entry by trace token. Returns
+	// (zero, false) when the token is unknown or the entry has been
+	// evicted (LRU pressure or TTL).
+	Get(token string) (ReplayEntry, bool)
+
+	// Put stores a replay entry under the given trace token. If the
+	// token is already present, the entry replaces it.
+	Put(token string, entry ReplayEntry)
+}
+
+// ReplayEntry is what /v1/replay needs to reproduce a prior response
+// byte-for-byte. ResponseJSON is the literal bytes of the original
+// HTTP response — storing the marshalled response (not the underlying
+// Go struct) is what guarantees byte-exact replay. Go's
+// encoding/json sorts map keys lexicographically, so re-encoding the
+// same map would already be deterministic, but persisting raw bytes
+// removes any future doubt: it doesn't matter how the response is
+// constructed, only what was actually returned.
+//
+// The remaining fields exist so the replay handler can validate the
+// caller's claim — body.query and body.document_id must match
+// entry.Query and entry.DocumentID, otherwise the engine returns 409
+// with a specific reason.
+type ReplayEntry struct {
+	// DocumentID is the document the original request targeted.
+	DocumentID tree.DocumentID
+
+	// Query is the user query the original request carried.
+	Query string
+
+	// Model is the resolved LLM model name (after defaults). Stored
+	// so future versions can validate model claims; today the trace
+	// token already encodes the model, so a mismatch surfaces as
+	// "trace_token not found" rather than a 409.
+	Model string
+
+	// SelectedIDs is the set of section IDs the strategy picked.
+	// Stored for debugging and observability; not used by the replay
+	// handler today (the response bytes already contain the IDs).
+	SelectedIDs []tree.SectionID
+
+	// ResponseJSON is the literal response body sent over the wire.
+	// The replay handler writes this back verbatim with
+	// Content-Type: application/json.
+	ResponseJSON []byte
+
+	// CreatedAt is when this entry was stored. Surfaced in logs.
+	CreatedAt time.Time
+}
+
+// LRUReplayStore is an in-memory, TTL-aware, size-bounded replay
+// store. It is a thin facade over pkg/cache.LRU: that cache is
+// general-purpose (stores any) and concurrency-safe, so wrapping it
+// avoids a duplicate LRU implementation. The facade enforces the
+// ReplayEntry value type so callers cannot accidentally store the
+// wrong shape.
+//
+// Capacity and TTL are configured at construction. Default capacity
+// is 1024 entries, default TTL is 24h — sufficient for any realistic
+// replay flow (audit, regression, debugging) while preventing
+// unbounded memory growth.
+//
+// LRUReplayStore is NOT durable across process restarts. This is an
+// intentional v1 limitation — the Phase 3.2 plan calls out persistent
+// storage (Postgres-backed replay log + document versioning) as the
+// next step.
+type LRUReplayStore struct {
+	// mu guards ttl; the underlying cache is already lock-free for
+	// callers because pkg/cache.LRU has its own internal mutex.
+	mu  sync.RWMutex
+	ttl time.Duration
+
+	c *cache.LRU
+}
+
+// Compile-time interface check.
+var _ ReplayStore = (*LRUReplayStore)(nil)
+
+// LRUReplayConfig is the configuration for an LRUReplayStore.
+type LRUReplayConfig struct {
+	// MaxEntries bounds the number of stored replay entries. Zero
+	// defaults to 1024.
+	MaxEntries int
+
+	// TTL is how long an entry remains valid. Zero defaults to 24
+	// hours.
+	TTL time.Duration
+}
+
+// NewLRUReplayStore constructs an in-memory replay store with the
+// given capacity and TTL. Zero values fall back to defaults.
+func NewLRUReplayStore(cfg LRUReplayConfig) *LRUReplayStore {
+	ttl := cfg.TTL
+	if ttl <= 0 {
+		ttl = 24 * time.Hour
+	}
+	return &LRUReplayStore{
+		ttl: ttl,
+		c:   cache.NewLRU(cfg.MaxEntries),
+	}
+}
+
+// Get implements ReplayStore.
+func (s *LRUReplayStore) Get(token string) (ReplayEntry, bool) {
+	if token == "" {
+		return ReplayEntry{}, false
+	}
+	v, ok := s.c.Get(token)
+	if !ok {
+		return ReplayEntry{}, false
+	}
+	entry, ok := v.(ReplayEntry)
+	if !ok {
+		// Defensive: should never happen because Put only stores
+		// ReplayEntry, but a corrupt entry shouldn't panic the
+		// handler. Treat as a miss.
+		return ReplayEntry{}, false
+	}
+	return entry, true
+}
+
+// Put implements ReplayStore.
+func (s *LRUReplayStore) Put(token string, entry ReplayEntry) {
+	if token == "" {
+		return
+	}
+	s.mu.RLock()
+	ttl := s.ttl
+	s.mu.RUnlock()
+	s.c.Set(token, entry, ttl)
+}
+
+// Len reports the current number of entries (including expired-but-
+// not-yet-evicted entries). Primarily for tests and metrics.
+func (s *LRUReplayStore) Len() int {
+	return s.c.Len()
+}