every turn persists its decision record, and the reversal is written down (V-629)

internal/decision kept a 25-turn ring and persisted nothing, on the argument
that a turn record is read minutes later or never. The owner reversed that on
06-08-2026: the routing heads cannot be fitted or calibrated without real
utterances, and V-631 measured that 9 of the 31 modes have no seed example at
all. docs/plans/21-persisting-the-routing-trace.md carries the reversal, and
CLAUDE.md now says which of its own sentences stopped being true.

cmd/mavend/routingtrace.go is a second sink beside the ring, which did not move:
the ring is still what /trace reads and still what a test with no store gets. A
failed insert is logged and swallowed, because a trace must never change what he
hears. traceSink keeps a nil store out of the interface, since a typed nil
pointer there would pass the nil check and die on the first turn.

Four fields the ring never carried: which reach the turn arrived on, whether
stage 0 answered before the classifier was consulted, which encoder body was
live (the same EmbedderID string the vector marker uses), and what the action
stage actually did.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117tgnmbgZpHVV3XSNw8Qua

cmd/mavend/routingtrace.go

@@ -0,0 +1,105 @@
+// mavend/routingtrace.go — persisting the per-turn decision record (V-629).
+//
+// internal/decision keeps a 25-turn in-memory ring and persisted nothing, on the
+// argument that a turn record is read minutes later or never. The owner reversed
+// that on 06-08-2026, because the routing heads (V-546) cannot be fitted or
+// calibrated without real utterances and there is no other source of them. The
+// reversal is written down in docs/plans/21-persisting-the-routing-trace.md.
+//
+// The ring stays. It is what /trace reads, it is fast, and it is what a test that
+// wired no store still gets. This file is the second sink beside it, and it is
+// nil unless the daemon has a database — no store, no trace, no error.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"strings"
+
+	"github.com/kami/maven/internal/decision"
+	"github.com/kami/maven/internal/store"
+)
+
+// traceWriter is the seam the handler persists through. store.Store satisfies
+// it. nil ⇒ the ring is the only sink, which is the pre-V-629 behaviour exactly.
+type traceWriter interface {
+	WriteRoutingTrace(ctx context.Context, tr store.RoutingTrace) (int64, error)
+}
+
+// traceSink wraps the store, or returns nil when there is none. A typed nil
+// pointer assigned straight into the interface would be non-nil and would panic
+// on the first turn, which is the classic shape of this bug.
+func traceSink(s *store.Store) traceWriter {
+	if s == nil {
+		return nil
+	}
+	return s
+}
+
+// persistDecision writes one finished record. It takes the same *decision.Record
+// the ring takes, so the two sinks cannot disagree about what the turn did.
+//
+// Errors are logged and swallowed. A trace is diagnostic and training data, and
+// a failed insert must never change what the owner hears.
+func (h *reactiveHandler) persistDecision(ctx context.Context, rec *decision.Record, src turnSource) {
+	if h.traces == nil || rec == nil || strings.TrimSpace(rec.Utterance) == "" {
+		return
+	}
+	claims, err := json.Marshal(rec.Claims)
+	if err != nil {
+		log.Printf("routing trace: marshal claims: %v", err)
+		return
+	}
+	tr := store.RoutingTrace{
+		Ts:                rec.Ts,
+		Utterance:         rec.Utterance,
+		Source:            string(src),
+		Winner:            rec.Winner,
+		Intent:            wonIntent(rec),
+		ClaimedBeforeHead: claimedBeforeHead(rec),
+		EncoderID:         h.encoderID,
+		Outcome:           wonAt(rec, decision.StageAction),
+		Claims:            claims,
+	}
+	if _, err := h.traces.WriteRoutingTrace(ctx, tr); err != nil {
+		log.Printf("routing trace: write: %v", err)
+	}
+}
+
+// wonIntent — what the winning claimant made the turn. Read from the claim
+// rather than from the route, because a pre-route resolver wins without routing
+// and its intent is the honest answer to "what was this turn".
+func wonIntent(rec *decision.Record) string {
+	for _, c := range rec.Claims {
+		if c.Outcome == decision.Won && c.Intent != "" {
+			return c.Intent
+		}
+	}
+	return ""
+}
+
+// wonAt — the claimant that won at one stage. The action stage is what actually
+// produced the reply, which is a different question from what was routed: a
+// route that reached a gap and a route that ran are not the same turn.
+func wonAt(rec *decision.Record, stage string) string {
+	for _, c := range rec.Claims {
+		if c.Stage == stage && c.Outcome == decision.Won {
+			return c.Claimant
+		}
+	}
+	return ""
+}
+
+// claimedBeforeHead — a pre-route resolver or a stage-0 grammar answered, so the
+// turn teaches nothing about the classifier. Those are a large share of real
+// traffic, and fitting a head on them would fit it to the grammars rather than
+// to him. Recorded per turn rather than filtered on write, because which share
+// that is happens to be the number V-632 needs to know.
+func claimedBeforeHead(rec *decision.Record) bool {
+	stage, _, ok := strings.Cut(rec.Winner, ":")
+	if !ok {
+		return false
+	}
+	return stage == decision.StagePreRoute || stage == decision.StageZero
+}

cmd/mavend/routingtrace_test.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"context"
+	"testing"
+
+	"github.com/kami/maven/internal/decision"
+	"github.com/kami/maven/internal/store"
+)
+
+// A real turn leaves a persisted trace, not only a ring entry. This is the whole
+// of V-629: without one there is nothing to fit the routing heads from.
+func TestTurnPersistsTrace(t *testing.T) {
+	ring := decision.NewRing()
+	h := traceHandler(t, ring)
+	h.traces = traceSink(h.dataStore)
+	h.encoderID = "hash-1024"
+
+	if reply := h.handleText(context.Background(), "web", "сколько сейчас времени"); reply == "" {
+		t.Fatal("turn produced no reply")
+	}
+	got, err := h.dataStore.RecentRoutingTraces(context.Background(), 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("persisted %d traces, want 1", len(got))
+	}
+	tr := got[0]
+	if tr.Utterance != "сколько сейчас времени" {
+		t.Errorf("utterance %q", tr.Utterance)
+	}
+	if tr.Source != string(sourceText) {
+		t.Errorf("source %q, want %q", tr.Source, sourceText)
+	}
+	// A stage-0 clock rule answers this one, so the turn teaches the classifier
+	// nothing and the trace has to say so.
+	if !tr.ClaimedBeforeHead {
+		t.Errorf("claimed_before_head false on winner %q", tr.Winner)
+	}
+	if tr.EncoderID != "hash-1024" {
+		t.Errorf("encoder_id %q", tr.EncoderID)
+	}
+	if len(tr.Claims) < 3 {
+		t.Errorf("claims %s: the losers and the never-asked are the point", tr.Claims)
+	}
+}
+
+// No store, no trace, and no panic. A typed nil pointer in the interface would
+// pass the nil check and die on the first turn.
+func TestNoStoreNoTrace(t *testing.T) {
+	ring := decision.NewRing()
+	h := traceHandler(t, ring)
+	h.traces = traceSink(nil)
+
+	if reply := h.handleText(context.Background(), "web", "сколько сейчас времени"); reply == "" {
+		t.Fatal("turn produced no reply")
+	}
+	if len(ring.Recent(5)) != 1 {
+		t.Error("the ring is still the first sink and must still hold the turn")
+	}
+}
+
+// An empty utterance writes nothing. A blank row carries no label and no
+// diagnosis, and it is his words the retention bound exists for.
+func TestEmptyUtteranceIsNotPersisted(t *testing.T) {
+	h := traceHandler(t, decision.NewRing())
+	h.traces = traceSink(h.dataStore)
+	h.persistDecision(context.Background(), &decision.Record{Utterance: "  "}, sourceText)
+	got, err := h.dataStore.RecentRoutingTraces(context.Background(), 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Fatalf("persisted %d traces for a blank utterance", len(got))
+	}
+}
+
+var _ traceWriter = (*store.Store)(nil)

cmd/mavend/voice.go

@@ -145,6 +145,17 @@ type reactiveHandler struct {
 	// is recorded, which is what a test that did not ask for one gets.
 	decisions *decision.Ring
 
+	// traces persists those same records (V-629, routingtrace.go). The ring is
+	// still what /trace reads; this is the second sink, and it exists because the
+	// routing heads cannot be fitted without real utterances. nil ⇒ the ring
+	// alone, which is the behaviour every box had before 06-08-2026.
+	traces traceWriter
+
+	// encoderID names the encoder body live on this box, stored beside each
+	// trace: a fitted distance means nothing under another body. Empty ⇒ no
+	// embedder, so the classifier was the keyword floor.
+	encoderID string
+
 	// clarifyStore parks the request behind an open question she asked (see
 	// clarify.go). nil ⇒ she falls back to the canned "не поняла" reply.
 	clarifyStore *dialogue.ClarifyStore
@@ -265,7 +276,11 @@ func (h *reactiveHandler) runTurn(ctx context.Context, text string, src turnSour
 		var rec *decision.Record
 		ctx, rec = decision.With(ctx, text)
 		decision.Expect(ctx, decision.StagePreRoute, preRouteLadder)
-		defer func() { h.decisions.Push(rec.Finish(h.now())) }()
+		defer func() {
+			done := rec.Finish(h.now())
+			h.decisions.Push(done)
+			h.persistDecision(ctx, done, src)
+		}()
 	}
 
 	// 0b. the turn's routing, computed at most once and shared (Vikunja #560).

cmd/mavend/voicewire.go

@@ -298,7 +298,13 @@ func wireVoice(cfg *config.Config, coreAPI ipc.CoreAPI, phr phraser.Phraser, mem
 		// Always on (V-564). The record is the instrument the rest of V-558 is
 		// measured with, and one that only runs when a flag is set is not there
 		// on the night the misroute happens.
-		decisions:    decision.NewRing(),
+		decisions: decision.NewRing(),
+		// The second sink (V-629). Same records, persisted, because the routing
+		// heads cannot be fitted from a 25-turn ring. Nil store ⇒ ring only, and
+		// EmbedderID is the same string the vector marker uses, so a trace and a
+		// stored vector name their body the same way.
+		traces:       traceSink(dataStore),
+		encoderID:    router.EmbedderID(emb),
 		clarifyStore: clarifyStore,
 		// 0 here (unset config) ⇒ the dialogue default.
 		clarifyMaxAttempts: cfg.Voice.ClarifyMaxAttempts,