7.5 KiB
Notarius Request: Message-Content Hashing
Status: Requested by the Notarius consumer; proposed capability, not an implemented API or an approved PromptKit implementation plan.
Reviewed baseline: PromptKit v0.23.3.
Requested Capability
Expose a deterministic hash of a prepared request's ordered message roles and
exact text, available before model execution. MessageContentHash is the
suggested name. This would let consumers reuse an accepted answer to the same
message content without implementing their own message-hashing policy.
A field on PreparedRun, available through ordinary preparation and
PreparedExecution.Details(), appears sufficient. The exact public API is for
PromptKit to select; Notarius needs the value at the preparation boundary, not
only after execution or through an execution observer.
Consumer Need
Notarius runs pipelines whose stages depend on artifacts from earlier stages. If a later stage fails, an operator should be able to fix the problem and rerun without paying for successful earlier model work again. Notarius is replacing its checkpoint machinery with a small accepted-artifact cache.
The cached value is an accepted answer to the original task. Notarius will
prepare the initial request, obtain its message-content hash, and look for
cache/<hash>.json. A hit loads the accepted domain artifact directly. A miss
executes the full application operation, including domain interpretation,
validation, and any application-directed correction passes. Only the final
accepted artifact is stored, under the original request's hash.
This is intentionally a convenient reuse policy, not proof that every execution setting, validation policy, or application implementation is identical. A change to model settings alone should not invalidate an otherwise reusable answer. Operators can bypass or refresh the application cache when they want fresh work.
Hash Semantics
Hash the complete effective message sequence exposed by native preparation: rendered definition messages, appended messages, and captured conversation history when present. Include each message's role and exact content, preserving message order and boundaries.
| Included | Excluded |
|---|---|
| Ordered message roles and exact text | Session, run, and parent-run identity; timestamps and timings |
| Message boundaries and sequence length | Provider cache-control hints and other non-content message metadata |
| Any input, instruction, or schema text actually rendered into messages | Model, backend, profile, credentials, generation settings, timeouts, budgets, and retry/repair settings |
| Prompt ID, definition hash, input hashes/paths, and schema/output-contract metadata outside message text |
No whitespace trimming, Unicode normalization, or semantic equivalence is requested: hash the exact prepared text. Different roles, ordering, boundaries, or text should produce different hashes, subject to ordinary hash collision properties. Identical role/text sequences should produce the same value across requests, engines, and process invocations regardless of excluded metadata. For example, changing a prompt ID while retaining identical messages should preserve the hash. Changing settings that also changes rendered text should change it because the text changed.
Return an opaque, filename-safe value suitable for a persisted cache key. PromptKit should own and document the hashing semantics and compatibility behavior. A deterministic, unambiguous encoding and a standard hash such as SHA-256 would suffice; the precise encoding is an upstream implementation choice. No general fingerprint configuration or selectable hashing-policy framework is needed for this request.
Existing APIs And The Gap
PreparedRun already exposes messages and
RenderedPromptHash. The latter includes session identity and message cache
hints, as described in the runner documentation.
Hashing the entire prepared value would additionally capture settings and
volatile preparation metadata. Neither supplies the requested content-only key.
Keep the existing hash's semantics intact and add the narrower capability. Notarius could manually project and hash message fields, but that would preserve the duplicated library mechanics this migration aims to remove.
Native split preparation and execution
already provides the needed execution boundary. Preparation makes no model call
and reserves no backend capacity. On a miss, RunPrepared can execute the retained
snapshot. On a hit, the application can discard the handle. No new execution
protocol is requested.
Intended Application Flow
The following is conceptual pseudocode, not an existing hash API:
prepared = engine.PrepareExecution(initialRequest)
initialKey = prepared.Details().MessageContentHash // proposed addition
if cache contains a usable accepted artifact for initialKey:
discard prepared handle
return cached artifact
result = engine.RunPrepared(prepared)
artifact = interpret, validate, and correct through the Notarius operation
if the operation produces a final accepted artifact:
save artifact to cache under initialKey
return application outcome
Notarius retains the initial key even when acceptance requires several correction
turns. It stores the final domain artifact, not a raw intermediate response,
RunResult, exchange, or prepared handle. Failed, rejected, and
validation-incomplete work is not saved. A hit requires ordinary decoding and
usability checks; it does not replay model work or claim fresh domain validation.
Ownership And Scope
PromptKit owns everything within a native request execution, including structural response validation, transport retries, and internal repair attempts. Notarius consumes the public response or terminal failure and then owns domain acceptance. Those internal attempts are not inputs to the cache's eligibility policy.
This request is solely for reusable message-content hashing. It does not request PromptKit-owned cache storage, a cache-hit execution result, cached-response injection, validation replay, exchange restoration, or a write-through response cache. Debug observations do not change this boundary. Notarius owns cache lookup, final acceptance, persistence, and reuse/bypass/refresh controls.
Suggested Verification
- Repeated preparation in separate engines produces the same hash for identical role/text sequences despite different preparation timing or session identity.
- Changing a role, text (including whitespace), order, message count, or boundary changes the hash; ambiguous concatenations do not collapse to the same input.
- Settings-only, prompt-ID-only, and cache-hint-only changes preserve the hash when the effective role/text sequence is unchanged.
- Rendered inputs, appended messages, and captured history participate in the hash when they contribute to the effective messages.
- The hash is available before model execution, and reading it does not consume the prepared handle or alter its retained snapshot.
- Existing
RenderedPromptHashbehavior remains intact. Document the new value in public GoDoc and add a short consumer example of lookup before execution.
Notarius will verify its own cache behavior separately: hits make no model calls, only accepted artifacts are saved, and corrected answers remain keyed to the initial task. The supplying PromptKit release will be selected during Notarius roadmap incorporation; this request does not assign a release number.