diff --git a/docs/roadmap/message-content-hash.md b/docs/roadmap/message-content-hash.md new file mode 100644 index 0000000..db56a3d --- /dev/null +++ b/docs/roadmap/message-content-hash.md @@ -0,0 +1,118 @@ +# 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](../../types.go) 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](../../internal/usecase/runner.go), with a summary in the +[internal runner document](../internal/runner.md). + +`Prepare` returns public prepared details. `PrepareExecution` retains a snapshot +whose [Details method](../../prepared_execution.go) 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](../policy/release.md). 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.