Merge pull request #31 from comet-ml/aswynz/fix-span-id-uuidv7-timestamp

fix: embed the transcript timestamp in span ids so Opik accepts them

Author: aswynz

src/main.go

@@ -323,7 +323,13 @@ func onSubagentStop() {
 		}
 	}
 
-	parentSpanID := toV7(parentUUID)
+	// Must produce the same id processTranscriptEntries gave the Task span,
+	// so use the Task entry's own transcript timestamp.
+	parentTimestamp := entryTimestamp(input.TranscriptPath, parentUUID)
+	if parentTimestamp == "" {
+		debugLog("subagent_stop: no transcript timestamp for parent %s, span id will not match", parentUUID)
+	}
+	parentSpanID := toV7(parentUUID, parentTimestamp)
 	debugLog("processing subagent with parent=%s", parentSpanID)
 
 	spans := processTranscript(state.TraceID, input.AgentTranscriptPath, 0, parentSpanID)
@@ -562,7 +568,7 @@ func processTranscriptEntries(traceID string, entries []TranscriptEntry, parentS
 		}
 
 		span := Span{
-			ID:          toV7(p.UUID),
+			ID:          toV7(p.UUID, p.Timestamp),
 			TraceID:     traceID,
 			StartTime:   p.Timestamp,
 			EndTime:     endTime,
@@ -772,6 +778,21 @@ func countLines(path string) int {
 	return count
 }
 
+// entryTimestamp returns the transcript timestamp of the entry with the given
+// UUID, or "" when the transcript cannot be read or has no such entry.
+func entryTimestamp(path, uuid string) string {
+	entries, err := ReadTranscript(path, 0)
+	if err != nil {
+		return ""
+	}
+	for _, e := range entries {
+		if e.UUID == uuid {
+			return e.Timestamp
+		}
+	}
+	return ""
+}
+
 func isoNow() string {
 	return time.Now().UTC().Format("2006-01-02T15:04:05.000Z")
 }

src/uuid.go

@@ -45,12 +45,31 @@ func uuid7() string {
 		randHex[7:19])
 }
 
-// toV7 converts any UUID to a deterministic UUIDv7 using MD5 hash
-// This enables idempotent upserts by generating consistent IDs from transcript UUIDs
-func toV7(uuid string) string {
+// toV7 derives a deterministic UUIDv7 from a transcript UUID and the entry's
+// timestamp.
+//
+// Determinism matters: the same spans are re-sent on every flush (PostToolUse,
+// Stop, SessionEnd) and Opik upserts them by id, so a given transcript entry
+// must always map to the same span id.
+//
+// The first 48 bits must be a real millisecond timestamp. Opik validates that
+// a v7 id's embedded timestamp falls inside its ingestion window (24h around
+// now) and rejects the whole batch otherwise. The previous implementation put
+// MD5 hash bytes there, which decoded to timestamps centuries away and made
+// every span batch fail with "Invalid UUID for id". Only the remaining 74 bits
+// are derived from the hash now.
+//
+// timestamp is the transcript entry's RFC 3339 timestamp. If it is empty or
+// unparseable the current time is used, which keeps the id valid but not
+// deterministic across flushes; callers should pass the entry timestamp.
+func toV7(uuid, timestamp string) string {
+	ms := timestampMillis(timestamp)
 	hash := md5.Sum([]byte(uuid))
 	h := hex.EncodeToString(hash[:])
 
+	// First 48 bits: unix milliseconds
+	tsHex := fmt.Sprintf("%012x", ms&0xFFFFFFFFFFFF)
+
 	// Set version to 7 (0111) in byte 6
 	b6 := (hash[6] & 0x0F) | 0x70
 	b6Hex := fmt.Sprintf("%02x", b6)
@@ -60,11 +79,22 @@ func toV7(uuid string) string {
 	b8Hex := fmt.Sprintf("%02x", b8)
 
 	return fmt.Sprintf("%s-%s-%s%s-%s%s-%s",
-		h[0:8],
-		h[8:12],
+		tsHex[0:8],
+		tsHex[8:12],
 		b6Hex,
 		h[14:16],
 		b8Hex,
 		h[18:20],
 		h[20:32])
 }
+
+// timestampMillis parses a transcript RFC 3339 timestamp into unix
+// milliseconds, falling back to now when it is missing or malformed.
+func timestampMillis(timestamp string) int64 {
+	if timestamp != "" {
+		if t, err := time.Parse(time.RFC3339Nano, timestamp); err == nil {
+			return t.UnixMilli()
+		}
+	}
+	return time.Now().UnixMilli()
+}

src/uuid_test.go

@@ -0,0 +1,72 @@
+package main
+
+import (
+	"regexp"
+	"strconv"
+	"testing"
+	"time"
+)
+
+var uuidV7Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
+
+// embeddedMillis decodes the 48-bit UUIDv7 timestamp prefix.
+func embeddedMillis(t *testing.T, id string) int64 {
+	t.Helper()
+	ms, err := strconv.ParseInt(id[0:8]+id[9:13], 16, 64)
+	if err != nil {
+		t.Fatalf("cannot parse timestamp bits of %s: %v", id, err)
+	}
+	return ms
+}
+
+func TestToV7IsDeterministic(t *testing.T) {
+	a := toV7("8b1d7f2e-1111-4c3a-9c1e-000000000001", "2026-09-11T14:54:43.966Z")
+	b := toV7("8b1d7f2e-1111-4c3a-9c1e-000000000001", "2026-09-11T14:54:43.966Z")
+	if a != b {
+		t.Fatalf("same inputs produced different ids: %s vs %s", a, b)
+	}
+	c := toV7("8b1d7f2e-1111-4c3a-9c1e-000000000002", "2026-09-11T14:54:43.966Z")
+	if a == c {
+		t.Fatalf("different transcript uuids produced the same id: %s", a)
+	}
+}
+
+func TestToV7EmbedsEntryTimestamp(t *testing.T) {
+	ts := "2026-09-11T14:54:43.966Z"
+	want, _ := time.Parse(time.RFC3339Nano, ts)
+	id := toV7("8b1d7f2e-1111-4c3a-9c1e-000000000001", ts)
+	if !uuidV7Pattern.MatchString(id) {
+		t.Fatalf("not a well-formed UUIDv7: %s", id)
+	}
+	if got := embeddedMillis(t, id); got != want.UnixMilli() {
+		t.Fatalf("embedded timestamp %d, want %d (%s)", got, want.UnixMilli(), id)
+	}
+}
+
+func TestToV7FallsBackToNowWithoutTimestamp(t *testing.T) {
+	for _, ts := range []string{"", "not-a-timestamp"} {
+		before := time.Now().UnixMilli()
+		id := toV7("8b1d7f2e-1111-4c3a-9c1e-000000000001", ts)
+		after := time.Now().UnixMilli()
+		if !uuidV7Pattern.MatchString(id) {
+			t.Fatalf("not a well-formed UUIDv7: %s", id)
+		}
+		got := embeddedMillis(t, id)
+		if got < before || got > after {
+			t.Fatalf("timestamp %q: embedded %d not within [%d, %d]", ts, got, before, after)
+		}
+	}
+}
+
+func TestUuid7EmbedsNow(t *testing.T) {
+	before := time.Now().UnixMilli()
+	id := uuid7()
+	after := time.Now().UnixMilli()
+	if !uuidV7Pattern.MatchString(id) {
+		t.Fatalf("not a well-formed UUIDv7: %s", id)
+	}
+	got := embeddedMillis(t, id)
+	if got < before || got > after {
+		t.Fatalf("embedded %d not within [%d, %d]", got, before, after)
+	}
+}