6.3 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 decision 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.
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. Once compatibility is settled, protect the selected scheme 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.
Open Decisions
Hash-Value Compatibility Across Promptkit Releases
Recommendation: Preserve values across releases while the hash scheme is unchanged, including through internal refactoring. Treat a deliberate scheme change as a compatibility change, document its effect on hash values, and apply the normal release policy. This makes equality useful across process and library upgrades without promising that one algorithm or encoding can never change. Consumers continue to treat the string as opaque; no selectable schemes or legacy-computation API is needed for this feature.
Alternative: Limit the equality contract to a single Promptkit release and allow values to change between releases even when role/text semantics remain unchanged. This gives greater implementation freedom, but weakens the value of a library-owned deterministic hash for comparisons that span upgrades. It would require clearly documenting that narrower compatibility boundary.