trace-id propagation through /v1/iterate (multi-call observability)

Closes J's 2026-05-02 multi-call observability gap: a single
/v1/iterate session with N retries used to surface in Langfuse as
N+1 disconnected traces (one per /v1/chat hop + one for the iterate
request itself), with no parent/child linkage. Operators couldn't
scroll the retry chain in one trace tree to spot where grounding
failed.

## Wire-level change

- New header constant `shared.TraceIDHeader = "X-Lakehouse-Trace-Id"`
- `langfuseMiddleware` honors the header on inbound requests: if
  set, reuses that trace id instead of minting a new one. Stashes
  the trace id on the request context so handlers can attach
  application-level child spans.
- `validatord.chatCaller` forwards the header to chatd. Every chat
  hop in an iterate session lands as a child of the parent trace.

## Application-level spans

- `validator.IterateConfig` gains `Tracer` (optional callback).
  When wired, each iteration attempt emits one Langfuse span
  via `validator.AttemptSpan`:
    Name: iterate.attempt[N]
    Input: { iteration, model, provider, prompt }
    Output: { verdict, raw, error }
    Level: WARNING when verdict != accepted
- `validatord.iterTracer` is the production hook — bridges
  `validator.Tracer` → `langfuse.Client.Span`.
- `IterateRequest`/`IterateResponse`/`IterateFailure` gain
  `TraceID`; each `IterateAttempt` gains `SpanID`. The /v1/iterate
  caller can pivot from the JSON response straight into the
  Langfuse trace tree.

## What an operator sees post-cutover

  GET /v1/iterate {kind=fill, prompt=...} → Trace TR-1
    ├─ http.request span (from middleware)
    ├─ iterate.attempt[0] span (validator.Iterate emit)
    │     input: prompt+model
    │     output: { verdict: validation_failed, error: ..., raw }
    ├─ chatd /v1/chat call (X-Lakehouse-Trace-Id: TR-1)
    │     ├─ http.request span (chatd middleware)
    │     └─ chatd-internal spans (existing)
    ├─ iterate.attempt[1] span
    └─ ...

All in one Langfuse trace tree, not N+1 separate traces.

## Hallucinated-worker safety net is unchanged

The /v1/iterate flow's hard correctness gate is still
FillValidator + WorkerLookup. Phantom candidate IDs raise
ValidationError::Consistency which 422s and forces the iteration
loop to retry. The trace-id propagation is the OBSERVABILITY layer
on top — it makes the existing safety net's outcomes visible per-call,
not a replacement for it.

## Verification

- internal/validator: 4 new tests
  - TestIterate_TracerEmitsSpanPerAttempt — span/attempt count + SpanID
  - TestIterate_NoTraceIDSkipsTracer — no orphan spans without trace_id
  - TestIterate_ChatCallerReceivesTraceID — propagation contract
  - (existing iterate tests updated for new ChatCaller signature)
- internal/shared: 1 new test
  - TestLangfuseMiddleware_HonorsTraceIDHeader — cross-service linkage
- cmd/validatord: existing HTTP tests still PASS via the dual-shape
  UnmarshalJSON contract.
- validatord_smoke.sh: 5/5 PASS through gateway :3110 (unchanged).
- Full go test ./... green across 33 packages.

## Architecture invariant added

STATE_OF_PLAY "DO NOT RELITIGATE" gains a paragraph documenting
the X-Lakehouse-Trace-Id header contract + the iterate.attempt[N]
span emission. Future-Claude won't re-propose "wire trace-id
propagation" — the header IS the wiring.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/validator/iterate_test.go

@@ -3,6 +3,7 @@ package validator
 import (
 	"context"
 	"errors"
+	"fmt"
 	"testing"
 )
 
@@ -69,7 +70,7 @@ func TestExtractJSON_TopLevelArrayReturnsFirstInnerObject(t *testing.T) {
 
 func scriptedChat(responses ...string) (ChatCaller, *int) {
 	idx := 0
-	return func(_ context.Context, _, _ string, _, _ string, _ *float64, _ int) (string, error) {
+	return func(_ context.Context, _, _ string, _, _ string, _ *float64, _ int, _ string) (string, error) {
 		if idx >= len(responses) {
 			return "", errors.New("scripted chat exhausted")
 		}
@@ -175,8 +176,96 @@ func TestIterate_MaxIterationsExhaustedReturnsFailure(t *testing.T) {
 	}
 }
 
+// TestIterate_TracerEmitsSpanPerAttempt locks the per-attempt
+// observability contract: when a Tracer is wired AND a TraceID is
+// present, every retry produces exactly one span and the SpanID
+// lands on the IterateAttempt history row.
+func TestIterate_TracerEmitsSpanPerAttempt(t *testing.T) {
+	chat, _ := scriptedChat(
+		"no json",
+		`{"k":"v"}`,
+	)
+	validate := func(_ string, _ map[string]any) (Report, error) { return Report{}, nil }
+
+	var spans []AttemptSpan
+	tracer := func(s AttemptSpan) string {
+		spans = append(spans, s)
+		return fmt.Sprintf("span-%d", s.Iteration)
+	}
+
+	resp, _, err := Iterate(context.Background(),
+		IterateRequest{Kind: "playbook", Prompt: "X", Provider: "ollama", Model: "qwen", TraceID: "trace-abc"},
+		IterateConfig{Tracer: tracer}, chat, validate)
+	if err != nil {
+		t.Fatalf("Iterate: %v", err)
+	}
+	if resp.TraceID != "trace-abc" {
+		t.Errorf("TraceID echo: got %q, want trace-abc", resp.TraceID)
+	}
+	if len(spans) != 2 {
+		t.Fatalf("expected 2 emitted spans, got %d", len(spans))
+	}
+	if spans[0].Verdict.Kind != "no_json" || spans[1].Verdict.Kind != "accepted" {
+		t.Errorf("verdict propagation: %+v", spans)
+	}
+	if resp.History[0].SpanID != "span-0" || resp.History[1].SpanID != "span-1" {
+		t.Errorf("SpanID stamping: %+v", resp.History)
+	}
+	if spans[0].TraceID != "trace-abc" {
+		t.Errorf("TraceID didn't reach the tracer: %q", spans[0].TraceID)
+	}
+}
+
+// TestIterate_NoTraceIDSkipsTracer guards the "Langfuse not configured"
+// path: tracer is non-nil but trace_id is empty → we MUST NOT emit
+// orphan spans.
+func TestIterate_NoTraceIDSkipsTracer(t *testing.T) {
+	chat, _ := scriptedChat(`{"k":"v"}`)
+	validate := func(_ string, _ map[string]any) (Report, error) { return Report{}, nil }
+	called := 0
+	tracer := func(_ AttemptSpan) string {
+		called++
+		return "should-not-be-used"
+	}
+	resp, _, err := Iterate(context.Background(),
+		IterateRequest{Kind: "playbook", Prompt: "X", Provider: "ollama", Model: "qwen"}, // no TraceID
+		IterateConfig{Tracer: tracer}, chat, validate)
+	if err != nil {
+		t.Fatalf("Iterate: %v", err)
+	}
+	if called != 0 {
+		t.Errorf("tracer should not fire without a trace_id; called=%d", called)
+	}
+	if resp.History[0].SpanID != "" {
+		t.Errorf("SpanID should be empty when no trace_id: %q", resp.History[0].SpanID)
+	}
+}
+
+// TestIterate_ChatCallerReceivesTraceID confirms the trace_id is
+// forwarded into the ChatCaller signature so HTTP transports can set
+// the X-Lakehouse-Trace-Id header. Without this, chatd's Langfuse
+// emit would create an orphan trace per retry instead of nesting
+// under the iterate parent.
+func TestIterate_ChatCallerReceivesTraceID(t *testing.T) {
+	var observedTrace string
+	chat := func(_ context.Context, _, _ string, _, _ string, _ *float64, _ int, traceID string) (string, error) {
+		observedTrace = traceID
+		return `{"k":"v"}`, nil
+	}
+	validate := func(_ string, _ map[string]any) (Report, error) { return Report{}, nil }
+	_, _, err := Iterate(context.Background(),
+		IterateRequest{Kind: "playbook", Prompt: "X", Provider: "ollama", Model: "x", TraceID: "trace-xyz"},
+		IterateConfig{}, chat, validate)
+	if err != nil {
+		t.Fatalf("Iterate: %v", err)
+	}
+	if observedTrace != "trace-xyz" {
+		t.Errorf("ChatCaller should receive trace_id; got %q", observedTrace)
+	}
+}
+
 func TestIterate_PropagatesChatInfraError(t *testing.T) {
-	chat := func(_ context.Context, _, _ string, _, _ string, _ *float64, _ int) (string, error) {
+	chat := func(_ context.Context, _, _ string, _, _ string, _ *float64, _ int, _ string) (string, error) {
 		return "", errors.New("connection refused")
 	}
 	validate := func(_ string, _ map[string]any) (Report, error) { return Report{}, nil }