114 lines
6.0 KiB
Markdown
114 lines
6.0 KiB
Markdown
# 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. The [implementation plan](implementation.md) owns staged execution.
|
|
|
|
## 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 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](../policy/release.md). 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](../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.
|