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,
|
Return an opaque, filename-safe string. Use SHA-256 over a versioned,
|
||||||
unambiguous encoding; the precise encoding is an internal implementation choice
|
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
|
hasher in linear time in the message count and role/text bytes, without building
|
||||||
another complete serialized message buffer. Existing framing helpers can be
|
another complete serialized message buffer. Existing framing helpers can be
|
||||||
reused where suitable without changing the existing hash.
|
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
|
## Work Needed
|
||||||
|
|
||||||
- Add the value to the internal and public prepared representations and carry
|
- 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,
|
boundary sensitivity, excluded-metadata invariance, rendered inputs,
|
||||||
appended messages, and captured history. Verify availability before model
|
appended messages, and captured history. Verify availability before model
|
||||||
execution and preservation of the existing rendered hash and snapshot
|
execution and preservation of the existing rendered hash and snapshot
|
||||||
ownership behavior. Once compatibility is settled, protect the selected
|
ownership behavior. Protect the selected scheme's cross-release stability
|
||||||
scheme with proportionate reference-vector coverage.
|
with proportionate reference-vector coverage.
|
||||||
- Add exact semantics and compatibility language to public GoDoc when
|
- Add exact semantics and compatibility language to public GoDoc when
|
||||||
implemented. Update the consumer guide with a short example of reading the
|
implemented. Update the consumer guide with a short example of reading the
|
||||||
field after preparation, independent of any application use. Update 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
|
This work does not add storage, response reuse, domain validation, application
|
||||||
acceptance rules, or application-specific hash consumers. Preparation retains
|
acceptance rules, or application-specific hash consumers. Preparation retains
|
||||||
its existing validation and resource-loading behavior.
|
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