225 lines
13 KiB
Markdown
225 lines
13 KiB
Markdown
# Message-Content Hash Implementation Plan
|
|
|
|
## Objective And Authority
|
|
|
|
Implement the target in [message-content-hash.md](message-content-hash.md).
|
|
That roadmap owns scope, hash semantics, and the accepted cross-release
|
|
compatibility decision. The [Notarius request](notarius-request.md) is background;
|
|
its application workflow does not add Promptkit requirements.
|
|
|
|
This is one end-to-end sprint, divided into four sequential, single-prompt
|
|
stages sized for a Luna coding agent. Intermediate stages need not compile or
|
|
leave a releasable repository. There are no intermediate human-review or
|
|
external-publication gates. The final stage verifies the assembled result.
|
|
Do not introduce temporary public APIs or compatibility shims just to make an
|
|
intermediate stage compile.
|
|
|
|
Start with [development.md](../development.md) and its applicable policies:
|
|
[agents](../policy/agents.md), [architecture](../policy/architecture.md),
|
|
[testing](../policy/testing.md), and [documentation](../policy/documentation.md).
|
|
Use the [release policy](../policy/release.md) when preparing release notes.
|
|
Follow repository commit policy for completed units; commits are not approval
|
|
gates between stages.
|
|
|
|
## Baseline And Fixed Design Choices
|
|
|
|
The reviewed baseline is Promptkit v0.23.3 plus the accepted roadmap commits.
|
|
|
|
- `internal/usecase/runner.go` assembles the final message sequence in
|
|
`completePreparationWithStructuredOutput`, then builds `domain.PreparedRun`.
|
|
`hashRenderedPrompt` includes session and cache metadata and stays unchanged.
|
|
- `internal/usecase/prepared_execution.go` shares the prepared snapshot between
|
|
retained details and execution payload. Public `Details` detaches through
|
|
`fromDomainPreparedRun` in `convert.go`; `OnPrepared` uses that conversion too.
|
|
- `PreparedRun` in `types.go` is a public data value with stable JSON field names.
|
|
Its JSON marshaler in `json.go` uses the defined type
|
|
`preparedRunJSONFields PreparedRun`, not a separately maintained field list.
|
|
|
|
Select these concrete implementation details for this sprint:
|
|
|
|
1. Add `MessageContentHash string` to internal and public `PreparedRun`.
|
|
The public tag is `json:"message_content_hash"`, without `omitempty`.
|
|
Zero/manual values retain the ordinary empty string; preparation populates
|
|
the field. JSON decoding stores the supplied field rather than recomputing
|
|
it or validating caller-owned message/hash consistency. Older JSON that
|
|
omits the field decodes with the ordinary zero value.
|
|
2. Compute the value once from the final prepared messages using the v1 scheme
|
|
below. Carry the string through existing snapshot and conversion paths.
|
|
Reading details does not rehash caller-modified copies or claim a handle.
|
|
3. Keep the existing rendered hash and all its values unchanged. Do not add the
|
|
new field to `RunResult`, `Exchange`, model requests, HTTP payloads, or
|
|
metadata observer events merely for symmetry. Existing `OnPrepared` values
|
|
include it because they are `PreparedRun` values.
|
|
4. Add no hashing option, standalone public hash function, dependency, timer,
|
|
storage feature, or application-specific interpretation. Preparation and
|
|
execution retain their existing validation, ownership, and lifecycle rules.
|
|
|
|
## Stage 1 — Implement The Versioned Hash And Reference Tests
|
|
|
|
Status: complete.
|
|
|
|
Work in `internal/usecase`, using a focused `message_content_hash.go` and
|
|
`message_content_hash_test.go`. Implement the unexported helper
|
|
`hashMessageContent(messages []domain.RenderedMessage) string`.
|
|
|
|
The exact v1 preimage is the concatenation of:
|
|
|
|
1. The literal ASCII prefix `promptkit/message-content/v1` followed by one NUL
|
|
byte, expressed in Go as `"promptkit/message-content/v1\x00"`.
|
|
2. The message count as an unsigned 64-bit big-endian integer.
|
|
3. For each message in order: the role byte length as an unsigned 64-bit
|
|
big-endian integer, the role bytes, then the content byte length in the same
|
|
format and the content bytes. String lengths are Go `len(string)` byte
|
|
counts, not Unicode code-point counts.
|
|
|
|
Hash that preimage with SHA-256 and return lowercase hexadecimal. This is an
|
|
internal scheme specification, not a public format callers should parse.
|
|
Include no session, cache-control, or other fields. Do not normalize strings
|
|
or add validation to this helper; preparation already owns input validity.
|
|
|
|
Stream the prefix and fields into the hasher. Reuse the existing
|
|
`writeRenderedPromptHashLength` and `writeRenderedPromptHashString` helpers
|
|
without renaming or changing their behavior. A second linear hash traversal
|
|
is sufficient; do not refactor the existing hash into a generic policy engine
|
|
or build an aggregate serialized message buffer.
|
|
|
|
Protect the v1 scheme with these independently calculated fixed vectors:
|
|
|
|
| Messages, with strings in Go-style escaped notation | Expected hash |
|
|
| --- | --- |
|
|
| Empty slice | `4b3d27f1ccb333598f041ab4c079f285ba65b095066dda9064e23e0de57116c7` |
|
|
| `[("user", "hello")]` | `34e867fb7cfe57c68d3a25ce6f007751230b3c41915d927492d96158c6cb0f04` |
|
|
| `[("system", "a\x00b"), ("user", "café\n")]` | `38bcd39c878e656be34449951e24db771a5fb14d809d54b918b0c18b79c1925f` |
|
|
|
|
Use literal expected digests, not expectations generated by the production
|
|
helper. The empty-vector case tests framing only; it does not authorize empty
|
|
prompt definitions. Add a compact relational table covering role, text,
|
|
whitespace, order, count, and boundary changes, plus cache-control invariance.
|
|
Include a one-message/two-message ambiguous-concatenation pair. Nil and empty
|
|
slices both encode a zero count. Do not add subprocess tests just to prove a
|
|
deterministic pure function; fixed vectors protect cross-process stability.
|
|
|
|
Validation: run the new helper tests and the existing `TestHashRenderedPrompt`
|
|
tests in `internal/usecase`. Completion means the v1 vectors and semantic
|
|
relations pass without changing existing rendered-hash expectations.
|
|
|
|
## Stage 2 — Wire Prepared Values And Snapshot Lifecycle
|
|
|
|
Status: complete.
|
|
|
|
Update `internal/domain/domain.go`, `types.go`, `internal/usecase/runner.go`,
|
|
and `convert.go`:
|
|
|
|
- Add the internal/public field beside `RenderedPromptHash` and document its
|
|
public semantics in GoDoc. Cover role/text inputs, excluded metadata,
|
|
opaque filename-safe output, preparation-time computation, and the accepted
|
|
cross-release compatibility rule. Do not promise a permanently fixed scheme.
|
|
- Populate it in `completePreparationWithStructuredOutput` from
|
|
`effectivePrompt.Messages`, after history, rendered messages, and appended
|
|
messages have been assembled. Do not hash raw definitions or an intermediate
|
|
suffix, and do not add another preparation or source-loading pass.
|
|
- Copy it in `fromDomainPreparedRun`. Check the existing snapshot path rather
|
|
than creating another metadata snapshot, getter computation, or locking layer.
|
|
`Prepare`, `Details`, ordinary/prepared `OnPrepared`, and ordinary execution's
|
|
shared preparation should all use this captured value.
|
|
|
|
Update `json_contract_test.go`: populate the field in
|
|
`fullyPopulatedPreparedRun`, assert the `message_content_hash` member in its
|
|
round-trip test, and check empty-string encoding on a zero value and zero-value
|
|
decoding when the member is absent. The defined-type JSON projection should
|
|
inherit the field; do not create a new serialization DTO just for this change.
|
|
|
|
Extend the relevant tests in `prepared_execution_contract_test.go` and
|
|
`prepared_notification_contract_test.go`, or add a small focused external-package
|
|
test file. Verify:
|
|
|
|
- Successful `Prepare` and `PrepareExecution(...).Details()` agree for identical
|
|
effective messages and expose a nonempty value before any model call.
|
|
- Mutating the returned details' messages and hash does not alter later details
|
|
or execution. Reading the field does not consume a handle, and retained details
|
|
still expose it after execution or discard under the existing lifecycle.
|
|
- `OnPrepared` receives the same captured hash on ordinary and split execution,
|
|
with no additional preparation/notification call introduced for hashing.
|
|
|
|
Reuse existing recording clients and ownership fixtures. Do not duplicate their
|
|
complete lifecycle, concurrency, credential, or repair test inventories.
|
|
|
|
Validation: run the focused prepared-value, notification, and JSON contract
|
|
tests. Completion means the value survives all supported prepared projections
|
|
and existing handle ownership remains intact.
|
|
|
|
## Stage 3 — Verify Public Content Semantics And Exclusions
|
|
|
|
Add focused `promptkit_test` coverage, preferably in
|
|
`message_content_hash_contract_test.go`, using real engines with small synthetic
|
|
definitions and an injected model client only where history or execution is
|
|
needed. Keep cases grouped by distinct risks rather than building a Cartesian
|
|
product of every setting and API.
|
|
|
|
1. **Equality and exclusions:** prepare the same role/text sequence repeatedly
|
|
and in separate engines. Vary session ID and cache hints and verify the new
|
|
hash stays equal while the existing rendered hash changes. Independently
|
|
vary prompt/profile/backend identifiers, effective model/settings, direct
|
|
synthetic credentials, and output/schema metadata outside message text;
|
|
verify unchanged prepared role/text yields the same new hash. Use a valid
|
|
in-memory schema where necessary. Avoid sleeps merely to vary timing.
|
|
2. **Rendered contributions:** use a template with a variable and input text.
|
|
Changes to rendered bytes change the hash; changes to unused variables or
|
|
artifact URI/hash metadata alone do not when rendered messages are unchanged.
|
|
Reuse existing input helper syntax and in-memory artifact fixtures.
|
|
3. **Composition:** exercise appended messages and a captured exchange. Compare
|
|
against a separately prepared explicit sequence with identical roles/text
|
|
and no history identity; hashes agree. Changing a history/appended role or
|
|
text changes the value. This proves the complete effective sequence is hashed,
|
|
not just the newly rendered definition. Initial history capture may execute
|
|
a fake client; preparation itself must not execute it.
|
|
|
|
Assert semantic equality/difference rather than duplicating the hash algorithm
|
|
in facade tests. Stage 1 owns exact v1 bytes; facade tests own message selection
|
|
and preparation integration. Retain existing rendered-hash tests unchanged.
|
|
Do not test or implement any application use of the hash.
|
|
|
|
Validation: run the new contract tests alongside existing appended-message and
|
|
exchange/preparation tests. Completion means every included/excluded category
|
|
in the feature roadmap has proportionate coverage at its owning boundary.
|
|
|
|
## Stage 4 — Document, Demonstrate, And Validate The End State
|
|
|
|
Update these existing documentation owners:
|
|
|
|
- `docs/consumers/pkg-promptkit.md`: explain the narrower hash versus
|
|
`RenderedPromptHash`, and show reading `details.MessageContentHash` after
|
|
`PrepareExecution` with ordinary error handling and deferred `Discard`.
|
|
Keep the example neutral about application interpretation.
|
|
- `docs/internal/runner.md`: describe the preparation point, content-only
|
|
preimage, streaming computation, and v1 scheme stability/reference tests.
|
|
Public GoDoc remains the exact API contract owner.
|
|
- `examples/go-library/prepare/main.go` and its test: include the new hash in
|
|
the existing preparation summary and assert it is nonempty. Do not hard-code
|
|
an example digest or introduce an application workflow or another example
|
|
project. Existing offline preparation behavior remains unchanged.
|
|
- Prepare `docs/releases/v0.24.0.md` for this new feature and link it from the
|
|
README. Describe the new prepared-result JSON member, no configuration
|
|
migration, and the additive Go struct field (positional literals may require
|
|
adjustment). Use the normal licensing footer. Do not edit published notes,
|
|
tag, push, or deliver a release as part of this implementation sprint.
|
|
|
|
Use the newest installed Go toolchain following `docs/development.md`, with
|
|
`GOTOOLCHAIN=local` and `GOWORK=off`. Keep dependency versions and the consumer
|
|
minimum unchanged for this feature. Format changed Go files, run
|
|
`go test -race ./...`, `go vet ./...`, and `git diff --check`. The complete Go
|
|
suite includes maintained example tests; do not add a separate repeated example
|
|
gate. If `/tmp` is still full, select an isolated writable `TMPDIR` and build
|
|
cache on a filesystem with space rather than deleting unrelated files.
|
|
|
|
Review the final diff against the feature roadmap: both hashes have their
|
|
distinct semantics, all prepared projections carry the new value, no new model
|
|
request field or application behavior has appeared, and reference vectors retain
|
|
the selected scheme. Check new local documentation links. Use focused reruns
|
|
while fixing failures and finish with validation appropriate to the final code.
|
|
No upstream dependency publication or consumer-project changes are needed.
|
|
|
|
Completion is the implemented and documented hash, successful final validation,
|
|
and reviewed commits under repository policy. Retire the completed planning
|
|
documents during normal release preparation, not as an extra execution gate.
|