Files
promptkit/docs/roadmap/message-content-hash.md

6.0 KiB

Prepared Message-Content Hash

Purpose And Ownership

Expose a deterministic hash of a prepared request's ordered message roles and exact text. Consumers can obtain this value before model execution without implementing their own message projection and hashing mechanics.

Promptkit owns the hash's inputs, computation, availability, and compatibility semantics. Applications own its interpretation and use. Downstream caching is one motivation, not a Promptkit feature or a requirement on application behavior.

This roadmap defines the target capability and the work needed from the current baseline. It is not a staged implementation plan.

Current Baseline

At v0.23.3, PreparedRun exposes the effective messages and RenderedPromptHash. The existing hash includes session identity and message cache-control metadata as well as roles and text; it does not provide a content-only equality value. Its implementation is in the runner, with a summary in the internal runner document.

Prepare returns public prepared details. PrepareExecution retains a snapshot whose Details method returns a caller-owned copy before execution. These existing preparation and execution boundaries are sufficient for this addition.

Target Public Surface

Add MessageContentHash string to PreparedRun, serialized as message_content_hash. Successful preparation populates it alongside the existing hash. Both Prepare and PreparedExecution.Details() expose the same value for equivalent effective messages under the selected hash scheme.

Compute the value from the captured preparation snapshot, not when a caller reads Details. Reading it does not consume the execution handle or alter its retained state. Preserve existing caller-owned copying and handle lifecycle semantics. Any other existing API that projects that same prepared snapshot, including OnPrepared, carries the new field through the shared conversion.

The addition does not require a standalone public hashing function, request option, observer event, or new execution protocol. Keep RenderedPromptHash and its existing semantics intact.

Hash Inputs And Meaning

Hash the complete effective message sequence in its prepared order: captured conversation history, rendered definition messages, then appended messages. Include each message's prepared role and exact content, with an unambiguous representation of message count, order, and field boundaries.

Apply no additional whitespace trimming, Unicode normalization, or semantic equivalence. The inputs are the already-prepared role/text values, not raw configuration or caller messages before preparation normalizes them.

Exclude session and run identities, timestamps, cache-control hints, model and backend settings, profile and prompt IDs, credentials, input hashes and paths, and output-contract or schema metadata outside the messages. Text rendered from any of these sources participates when it actually appears in a message.

Identical ordered role/text sequences produce identical values across requests, engines, and processes using the same hash scheme. Changes to roles, text, ordering, count, or boundaries change the encoded hash input; hash equality is subject to ordinary collision properties. Changes confined to excluded metadata do not affect the value. The hash identifies message content, not an execution or application outcome.

Return an opaque, filename-safe string. Use SHA-256 over a versioned, unambiguous encoding; the precise encoding is an internal implementation choice subject to the compatibility contract below. Stream the encoding into the hasher in linear time in the message count and role/text bytes, without building another complete serialized message buffer. Existing framing helpers can be reused where suitable without changing the existing hash.

Hash-Value Compatibility Across Releases

Preserve hash values for identical ordered role/text sequences across Promptkit releases while the hash scheme is unchanged. Internal refactoring and unrelated feature changes preserve those values.

A deliberate change to the algorithm, encoding, or included fields is a hash scheme change. Treat it as a compatibility change, document its effect on hash values, and apply the normal release policy. This does not promise one scheme forever or make its encoding a public implementation specification. Consumers continue to treat the string as opaque; no selectable schemes or legacy-computation API is needed for this feature.

Work Needed

  • Add the value to the internal and public prepared representations and carry it through snapshot construction, copying, and public conversion.
  • Compute it in the shared preparation pipeline after the effective message sequence is assembled. Ordinary execution, split preparation, and prepared notification should obtain the value from that same preparation result.
  • Add focused behavioral coverage for deterministic equality, role/text and boundary sensitivity, excluded-metadata invariance, rendered inputs, appended messages, and captured history. Verify availability before model execution and preservation of the existing rendered hash and snapshot ownership behavior. Protect the selected scheme's cross-release stability with proportionate reference-vector coverage.
  • Add exact semantics and compatibility language to public GoDoc when implemented. Update the consumer guide with a short example of reading the field after preparation, independent of any application use. Update the internal runner description and relevant serialization tests.
  • Describe the additive prepared-result field in the next feature release's notes under the existing release policy. No configuration-format change is needed.

This work does not add storage, response reuse, domain validation, application acceptance rules, or application-specific hash consumers. Preparation retains its existing validation and resource-loading behavior.