Describe prepared message-content hashing

This commit is contained in:
2026-11-20 03:41:51 +00:00
parent 804a4d32b2
commit ffce326dd7

View File

@@ -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.