Document prepared message content hashes

This commit is contained in:
2026-11-20 04:22:33 +00:00
parent 718cd05043
commit 019e077ba9
8 changed files with 82 additions and 35 deletions

View File

@@ -45,6 +45,9 @@ boundary and constraints that framework work must preserve.
## Release Guidance
The [v0.24.0 release notes](docs/releases/v0.24.0.md) describe the prepared
message-content hash and its compatibility considerations.
The [v0.23.3 release notes](docs/releases/v0.23.3.md) cover HTTP operation-timeout
attribution, custom caller cancellation causes, and response-read error identity.

View File

@@ -559,12 +559,17 @@ if err != nil {
defer preparedExecution.Discard()
details := preparedExecution.Details()
messageContentHash := details.MessageContentHash
_ = messageContentHash // An opaque value available before model execution.
// Inspect or persist an application-selected safe subset of details.
result, err := engine.RunPrepared(ctx, preparedExecution)
```
Preparation does not call the model or reserve backend capacity.
`MessageContentHash` compares the ordered message roles and text, whereas
`RenderedPromptHash` also includes the session and cache-control hints. See
the [`PreparedRun` GoDoc](../../types.go) for their contracts and compatibility.
`RunPrepared` executes from the retained snapshot rather than reloading
consumer sources. The handle is opaque in-process state, while `Details`
contains rendered content and remains subject to the application's data

View File

@@ -144,7 +144,7 @@ profile, or backend:
3. render messages and the prompt-defined session;
4. apply any direct session ID, then compose captured history, rendered
definition messages, and already-normalized request messages in that order;
5. hash the effective rendered prompt; and
5. hash the effective rendered prompt and its ordered message content; and
6. construct the prepared value and preparation timing.
`Prepare` runs both phases consecutively and never performs capacity admission.
@@ -185,6 +185,12 @@ sequence. The rendered-prompt hash uses a versioned, length-framed SHA-256
encoding of that session, every role and content value, and cache-control
presence and values; its hexadecimal value is opaque.
The separate message-content hash is computed once after that same composition.
It streams a versioned prefix, message count, and length-framed role and text
bytes into SHA-256, excluding session and cache metadata. Fixed reference
vectors protect the selected v1 scheme across refactors; the public
[`PreparedRun` GoDoc](../../types.go) owns its compatibility contract.
The configuration snapshot is read-only after engine construction. Concurrent
`Prepare` and `Run` calls use detached captured targets and keep invocation
state local.

20
docs/releases/v0.24.0.md Normal file
View File

@@ -0,0 +1,20 @@
# Promptkit v0.24.0
This feature release adds an opaque message-content hash to prepared results.
It identifies the ordered prepared message roles and exact text independently
of session identity, cache hints, and other metadata. The existing rendered
prompt hash is unchanged. See the [prepared-result GoDoc](../../types.go) and
[consumer guide](../consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later).
## Compatibility And Upgrade
Prepared-result JSON now includes `message_content_hash`; older JSON without it
decodes with an empty value. The new Go struct field is additive, though callers
using positional `PreparedRun` literals may need to adjust them. No configuration
migration is required. The Go consumer minimum and dependencies are unchanged.
```sh
go get go.maximumdirect.net/promptkit@v0.24.0
```
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/oss/attribution.md)

View File

@@ -187,6 +187,8 @@ in the feature roadmap has proportionate coverage at its owning boundary.
## Stage 4 — Document, Demonstrate, And Validate The End State
Status: complete.
Update these existing documentation owners:
- `docs/consumers/pkg-promptkit.md`: explain the narrower hash versus

View File

@@ -13,15 +13,16 @@ import (
)
type summary struct {
PromptID string `json:"prompt_id"`
SelectedProfile string `json:"selected_profile"`
Model string `json:"model"`
MessageCount int `json:"message_count"`
ProfileTimeout int `json:"profile_timeout_seconds"`
Namespaces []string `json:"namespaces"`
Collections []collectionSummary `json:"collections"`
ScopedPrompts []string `json:"scoped_prompts"`
ReviewPrompts []string `json:"review_prompts"`
PromptID string `json:"prompt_id"`
SelectedProfile string `json:"selected_profile"`
Model string `json:"model"`
MessageCount int `json:"message_count"`
MessageContentHash string `json:"message_content_hash"`
ProfileTimeout int `json:"profile_timeout_seconds"`
Namespaces []string `json:"namespaces"`
Collections []collectionSummary `json:"collections"`
ScopedPrompts []string `json:"scoped_prompts"`
ReviewPrompts []string `json:"review_prompts"`
}
type collectionSummary struct {
@@ -152,14 +153,15 @@ func run(ctx context.Context, exampleDir string, out io.Writer) error {
encoder := json.NewEncoder(out)
encoder.SetIndent("", " ")
return encoder.Encode(summary{
PromptID: prepared.PromptID,
SelectedProfile: prepared.SelectedProfileID,
Model: prepared.EffectiveModelParams.Model,
MessageCount: len(prepared.Messages),
ProfileTimeout: *profile.TimeoutSeconds,
Namespaces: namespaces,
Collections: collectionSummaries,
ScopedPrompts: scopedPromptIDs,
ReviewPrompts: reviewPromptIDs,
PromptID: prepared.PromptID,
SelectedProfile: prepared.SelectedProfileID,
Model: prepared.EffectiveModelParams.Model,
MessageCount: len(prepared.Messages),
MessageContentHash: prepared.MessageContentHash,
ProfileTimeout: *profile.TimeoutSeconds,
Namespaces: namespaces,
Collections: collectionSummaries,
ScopedPrompts: scopedPromptIDs,
ReviewPrompts: reviewPromptIDs,
})
}

View File

@@ -13,21 +13,22 @@ func TestPrepareExample(t *testing.T) {
t.Fatal(err)
}
var got struct {
PromptID string `json:"prompt_id"`
Profile string `json:"selected_profile"`
Model string `json:"model"`
MessageCount int `json:"message_count"`
Timeout int `json:"profile_timeout_seconds"`
Namespaces []string `json:"namespaces"`
Collections []map[string]json.RawMessage `json:"collections"`
ScopedPrompts []string `json:"scoped_prompts"`
ReviewPrompts []string `json:"review_prompts"`
PromptID string `json:"prompt_id"`
Profile string `json:"selected_profile"`
Model string `json:"model"`
MessageCount int `json:"message_count"`
MessageContentHash string `json:"message_content_hash"`
Timeout int `json:"profile_timeout_seconds"`
Namespaces []string `json:"namespaces"`
Collections []map[string]json.RawMessage `json:"collections"`
ScopedPrompts []string `json:"scoped_prompts"`
ReviewPrompts []string `json:"review_prompts"`
}
if err := json.Unmarshal(output.Bytes(), &got); err != nil {
t.Fatal(err)
}
if got.PromptID != "support/prepare" || got.Profile != "support/fast" || got.Model != "offline-model" ||
got.MessageCount <= 0 || got.Timeout != 30 || !reflect.DeepEqual(got.Namespaces, []string{"review", "support"}) ||
got.MessageCount <= 0 || got.MessageContentHash == "" || got.Timeout != 30 || !reflect.DeepEqual(got.Namespaces, []string{"review", "support"}) ||
!reflect.DeepEqual(got.ScopedPrompts, []string{"support/prepare"}) || !reflect.DeepEqual(got.ReviewPrompts, []string{"review/check"}) || len(got.Collections) != 2 {
t.Fatalf("unexpected preparation summary: %+v", got)
}

View File

@@ -17,7 +17,7 @@ func contentHashEngine(t *testing.T, promptID, profileID, backendID, content str
}
config := promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: configkit.Mapping("hash test", map[string]any{
"backends": []any{map[string]any{"id": backendID, "endpoint": "https://example.test/v1"}},
"profiles": []any{map[string]any{"id": profileID, "backend": backendID, "model": "model-" + profileID}},
"profiles": []any{map[string]any{"id": profileID, "backend": backendID, "model": "model"}},
"prompts": []any{map[string]any{"id": promptID, "default_profile": profileID, "inputs": []any{map[string]any{"name": "input", "required": false}}, "messages": []any{message}, "output": output}},
})}}}
engine, err := promptkit.NewEngine(config, opts...)
@@ -44,15 +44,23 @@ func TestMessageContentHashIgnoresPreparationMetadata(t *testing.T) {
baseEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, false)
base := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
repeated := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
other := contentHashEngine(t, "second", "beta", "two", "same", textOutput, false)
otherPrepared := prepareContentHash(t, other, promptkit.RunRequest{PromptID: "second", APIKey: "synthetic-key", Execution: &promptkit.ExecutionTargetOverride{Model: "other-model"}})
otherPrompt := contentHashEngine(t, "second", "alpha", "one", "same", textOutput, false)
otherProfile := contentHashEngine(t, "first", "beta", "one", "same", textOutput, false)
otherBackend := contentHashEngine(t, "first", "alpha", "two", "same", textOutput, false)
credential := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", APIKey: "synthetic-key"})
settings := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", Execution: &promptkit.ExecutionTargetOverride{Model: "other-model"}})
session := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", SessionID: "other-session"})
cacheEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, true)
cached := prepareContentHash(t, cacheEngine, promptkit.RunRequest{PromptID: "first"})
schemas := fstest.MapFS{"schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)}}
schemaEngine := contentHashEngine(t, "first", "alpha", "one", "same", map[string]any{"format": "json", "validation_mode": "json_schema", "schema_path": "schema.json"}, false, promptkit.WithSchemaFS(schemas, "."))
schema := prepareContentHash(t, schemaEngine, promptkit.RunRequest{PromptID: "first"})
for name, prepared := range map[string]*promptkit.PreparedRun{"repeat": repeated, "identifiers and model": otherPrepared, "session": session, "cache": cached, "schema": schema} {
for name, prepared := range map[string]*promptkit.PreparedRun{
"repeat": repeated, "prompt": prepareContentHash(t, otherPrompt, promptkit.RunRequest{PromptID: "second"}),
"profile": prepareContentHash(t, otherProfile, promptkit.RunRequest{PromptID: "first"}),
"backend": prepareContentHash(t, otherBackend, promptkit.RunRequest{PromptID: "first"}),
"credential": credential, "settings": settings, "session": session, "cache": cached, "schema": schema,
} {
if prepared.MessageContentHash != base.MessageContentHash {
t.Errorf("%s changed content hash", name)
}
@@ -65,10 +73,10 @@ func TestMessageContentHashIgnoresPreparationMetadata(t *testing.T) {
func TestMessageContentHashUsesRenderedInputBytes(t *testing.T) {
reader := &mutablePreparedArtifactReader{body: "body", hash: "first-hash"}
engine := contentHashEngine(t, "prompt", "profile", "backend", `{{input "input"}} {{.label}}`, map[string]any{"format": "text", "validation_mode": "none"}, false, promptkit.WithArtifactReader(reader))
request := promptkit.RunRequest{PromptID: "prompt", Inputs: map[string]promptkit.ArtifactRef{"input": promptkit.Inline("first")}, Vars: map[string]string{"label": "label", "unused": "first"}}
request := promptkit.RunRequest{PromptID: "prompt", Inputs: map[string]promptkit.ArtifactRef{"input": promptkit.File("first")}, Vars: map[string]string{"label": "label", "unused": "first"}}
base := prepareContentHash(t, engine, request)
reader.set("body", "other-hash")
request.Inputs["input"] = promptkit.Inline("other")
request.Inputs["input"] = promptkit.File("other")
request.Vars["unused"] = "other"
unchanged := prepareContentHash(t, engine, request)
if unchanged.MessageContentHash != base.MessageContentHash {