Settle message hash compatibility across releases

This commit is contained in:
2026-11-20 03:56:18 +00:00
parent ffce326dd7
commit 0f8e0e49b1

View File

@@ -69,11 +69,24 @@ 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
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
@@ -85,8 +98,8 @@ reused where suitable without changing the existing hash.
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.
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
@@ -98,21 +111,3 @@ reused where suitable without changing the existing hash.
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.