Settle message hash compatibility across releases
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user