diff --git a/docs/roadmap/message-content-hash.md b/docs/roadmap/message-content-hash.md index db56a3d..272bf32 100644 --- a/docs/roadmap/message-content-hash.md +++ b/docs/roadmap/message-content-hash.md @@ -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.