From dd40171c01236bed657901135ace4541d6a99ab3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 04:16:50 +0000 Subject: [PATCH] Expose content hashes on prepared runs --- convert.go | 1 + docs/roadmap/implementation.md | 2 ++ internal/domain/domain.go | 1 + internal/usecase/runner.go | 1 + json_contract_test.go | 9 +++++++++ prepared_execution_contract_test.go | 13 ++++++++++++- prepared_notification_contract_test.go | 9 ++++++++- types.go | 7 +++++++ 8 files changed, 41 insertions(+), 2 deletions(-) diff --git a/convert.go b/convert.go index 12ed053..30938bb 100644 --- a/convert.go +++ b/convert.go @@ -100,6 +100,7 @@ func fromDomainPreparedRun(prepared *domain.PreparedRun) *PreparedRun { InputHashes: copyStringMap(prepared.InputHashes), SessionID: prepared.SessionID, RenderedPromptHash: prepared.RenderedPromptHash, + MessageContentHash: prepared.MessageContentHash, Messages: fromDomainRenderedMessages(prepared.Messages), StartTime: prepared.StartTime, EndTime: prepared.EndTime, diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index a3945a5..12e5d6f 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -105,6 +105,8 @@ relations pass without changing existing rendered-hash expectations. ## Stage 2 — Wire Prepared Values And Snapshot Lifecycle +Status: complete. + Update `internal/domain/domain.go`, `types.go`, `internal/usecase/runner.go`, and `convert.go`: diff --git a/internal/domain/domain.go b/internal/domain/domain.go index a37ef14..0b513f3 100644 --- a/internal/domain/domain.go +++ b/internal/domain/domain.go @@ -118,6 +118,7 @@ type PreparedRun struct { InputHashes map[string]string SessionID string RenderedPromptHash string + MessageContentHash string Messages []RenderedMessage StartTime time.Time EndTime time.Time diff --git a/internal/usecase/runner.go b/internal/usecase/runner.go index f049df5..ac50749 100644 --- a/internal/usecase/runner.go +++ b/internal/usecase/runner.go @@ -511,6 +511,7 @@ func (r *Runner) completePreparationWithStructuredOutput( InputHashes: inputHashes, SessionID: effectivePrompt.SessionID, RenderedPromptHash: hashRenderedPrompt(effectivePrompt), + MessageContentHash: hashMessageContent(effectivePrompt.Messages), Messages: effectivePrompt.Messages, StartTime: state.start, EndTime: end, diff --git a/json_contract_test.go b/json_contract_test.go index b5e1810..e1ea2ac 100644 --- a/json_contract_test.go +++ b/json_contract_test.go @@ -91,6 +91,7 @@ func TestPreparedRunJSONContractRoundTripsAllFields(t *testing.T) { "input_hashes", "session_id", "rendered_prompt_hash", + "message_content_hash", "messages", "start_time", "end_time", @@ -124,6 +125,13 @@ func TestPreparedRunJSONContractRoundTripsAllFields(t *testing.T) { t.Fatalf("marshal zero PreparedRun: %v", err) } zeroObject := decodeJSONObject(t, zeroPayload) + if string(zeroObject["message_content_hash"]) != `""` { + t.Fatalf("zero message content hash missing or nonempty: %s", zeroPayload) + } + var legacy promptkit.PreparedRun + if err := json.Unmarshal([]byte(`{"messages":[]}`), &legacy); err != nil || legacy.MessageContentHash != "" { + t.Fatalf("legacy prepared run = %+v, %v", legacy, err) + } for _, field := range []string{ "prompt_version", "prompt_hash", @@ -271,6 +279,7 @@ func fullyPopulatedPreparedRun() promptkit.PreparedRun { InputHashes: map[string]string{"first": "hash-1", "second": "hash-2"}, SessionID: "session-prepared", RenderedPromptHash: "rendered-hash", + MessageContentHash: "content-hash", Messages: []promptkit.RenderedMessage{ { Role: "system", diff --git a/prepared_execution_contract_test.go b/prepared_execution_contract_test.go index 6bdfba2..c575573 100644 --- a/prepared_execution_contract_test.go +++ b/prepared_execution_contract_test.go @@ -112,12 +112,20 @@ func TestPreparedExecutionFreezesSourcesAndReturnsIndependentDetails(t *testing. reader.set("changed artifact", "changed-input-hash") first := prepared.Details() + originalContentHash := first.MessageContentHash + if originalContentHash == "" { + t.Fatal("prepared content hash is empty") + } + first.MessageContentHash = "changed hash" first.Messages[2].Content = "changed details" first.InputHashes["input"] = "changed-details-hash" first.EffectiveModelParams.ExtraParams["nested"].(map[string]any)["source"] = "changed details" first.StructuredOutput.JSONSchema.Schema.(map[string]any)["title"] = "changed details" second := prepared.Details() + if second.MessageContentHash != originalContentHash { + t.Fatal("details content hash changed") + } if second.Messages[2].Content != "Input=original artifact Label=original variable" { t.Fatalf("details message changed: %q", second.Messages[2].Content) } @@ -144,7 +152,7 @@ func TestPreparedExecutionFreezesSourcesAndReturnsIndependentDetails(t *testing. if reader.callCount() != 1 { t.Fatalf("execution reopened artifact source: calls=%d", reader.callCount()) } - if notified == nil || prepared.Details().Messages[2].Content != second.Messages[2].Content || prepared.Details().Messages[3].CacheControl.Type != promptkit.CacheControlEphemeral || !reflect.DeepEqual(initial.Exchange.Details(), initialDetails) || result.Exchange.Details().Messages[0].Content != "history" || prepared.Details().StructuredOutput.JSONSchema.Schema.(map[string]any)["title"] != "original root" { + if notified == nil || notified.MessageContentHash != originalContentHash || prepared.Details().MessageContentHash != originalContentHash || prepared.Details().Messages[2].Content != second.Messages[2].Content || prepared.Details().Messages[3].CacheControl.Type != promptkit.CacheControlEphemeral || !reflect.DeepEqual(initial.Exchange.Details(), initialDetails) || result.Exchange.Details().Messages[0].Content != "history" || prepared.Details().StructuredOutput.JSONSchema.Schema.(map[string]any)["title"] != "original root" { t.Fatal("notification changed prepared state") } @@ -680,6 +688,9 @@ func TestPreparedExecutionDiscardAndFormattingDoNotExposePrivateState(t *testing t.Fatalf("prepare execution for discard: %v", err) } discardedDetails := discarded.Details() + if discardedDetails.MessageContentHash == "" { + t.Fatal("discarded handle has no content hash") + } discarded.Discard() discarded.Discard() result, lifecycleErr := engine.RunPrepared(context.Background(), discarded) diff --git a/prepared_notification_contract_test.go b/prepared_notification_contract_test.go index 9cac8ba..8d14753 100644 --- a/prepared_notification_contract_test.go +++ b/prepared_notification_contract_test.go @@ -22,9 +22,13 @@ func TestPreparedNotificationSelectionAndOrdering(t *testing.T) { } return &promptkit.GenerateResponse{Content: "ok"}, nil })) + expected, err := engine.Prepare(context.Background(), promptkit.RunRequest{PromptID: "prompt"}) + if err != nil || expected.MessageContentHash == "" { + t.Fatalf("preparation = %+v, %v", expected, err) + } req := promptkit.RunRequest{PromptID: "prompt", OnPrepared: func(_ context.Context, details promptkit.PreparedRun) { calls++ - if details.PromptID != "prompt" || len(details.Messages) == 0 { + if details.PromptID != "prompt" || len(details.Messages) == 0 || details.MessageContentHash != expected.MessageContentHash { t.Fatalf("details=%+v", details) } }} @@ -36,6 +40,9 @@ func TestPreparedNotificationSelectionAndOrdering(t *testing.T) { if calls != 0 { t.Fatal("preparation notified") } + if handle.Details().MessageContentHash != expected.MessageContentHash { + t.Fatal("prepared handle content hash differs") + } req.OnPrepared = func(context.Context, promptkit.PreparedRun) { t.Fatal("selection changed") } _, err = engine.RunPrepared(context.Background(), handle) if err != nil { diff --git a/types.go b/types.go index b3507b7..d03008a 100644 --- a/types.go +++ b/types.go @@ -226,6 +226,13 @@ type PreparedRun struct { SessionID string `json:"session_id,omitempty"` // RenderedPromptHash is an opaque equality value for SessionID and Messages. RenderedPromptHash string `json:"rendered_prompt_hash"` + // MessageContentHash is an opaque, filename-safe equality value computed + // during preparation from the ordered roles and exact text of Messages. + // It excludes session identity, cache hints, and other metadata outside the + // messages. Identical role/text sequences retain the same value across + // releases while the hash scheme is unchanged. A scheme change is a + // compatibility change and will be documented; no scheme is permanent. + MessageContentHash string `json:"message_content_hash"` // Messages are the complete effective messages that Run or RunPrepared passes // to the LLM client: captured history, if any, followed by definition // messages and RunRequest.AppendedMessages in caller order.