Describe prepared message-content hashing
This commit is contained in:
118
docs/roadmap/message-content-hash.md
Normal file
118
docs/roadmap/message-content-hash.md
Normal 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.
|
||||
Reference in New Issue
Block a user