[nissa-seru]

What this is for

sourceBodyDigest hashes a delivered body as the store keeps it, so a body's storedBodyDigest, stamped at ingestion on both MCPL lanes, matches its copy read back from the store. Until now it took each block's stored form from storedBlock, a copy of context-manager's write transform, with a copied image sniffer and base64 normalization. #252 said a follow-up would replace that copy once a context-manager release exported the transform. context-manager 0.22.0 exports it as blockAsStored, and agent-framework already requires ^0.22.0.

Requirements

1. The digest follows the store. A body the store accepts, written to it and read back unsharded with its blobs resolved, hashes to the storedBodyDigest stamped for it, whatever the store changed in each block on the way in. That includes the two shapes the copy got wrong: a tool_use whose input isn't an object, and media whose data is a byte array. A body whose blocks the store changes together is the exception, below.
2. A digest stays the body's version identity across releases. For a body whose stored form the copy got right, the digest is the one agent-framework has stamped since 0.24.0, so such a stamp already in a store still matches its copy.
3. A body the store refuses still has a digest, such as a document without a media type, or a blob_ref. It's digested as given.
4. An unresolved read doesn't pass for its resolved copy. A blob_ref is digested as given, as 0.24.0's entry says, so a copy read with resolveBlobs: false doesn't match.
5. A failure in the store's transform is seen, and digesting doesn't fail for it. If blockAsStored throws anything but a refusal, the block is still digested as given, and the operator gets a log line naming the error for each digest taken over the block. A refusal logs nothing.

Changes

• storedBlock calls blockAsStored. Whatever blockAsStored throws, the block is digested as given. A refusal, a MalformedContentError, is silent. Any other error logs a line, [stored-digest-as-given] error=<name>: <message>, for each digest taken over the block. Ingestion takes two digests of a body, so one such block logs two lines.
• canonicalBase64 and sniffRasterImageMediaType go with the copy. canonicalJson stays, since it is the serializer the digest is taken over.

What a caller sees. MCPL's content conversion (src/mcpl/convert-block.ts) produces only text, image and audio blocks, and no body an MCPL lane stamps changes digest. In the real-store test, every body except the first two shapes below hashes as it did under the copy, the text, image and audio bodies among them. A direct caller of sourceBodyDigest with one of these three shapes gets a different digest than from 0.27.0:

• A tool_use whose input isn't an object. The store hands it back with input: {} and the value kept in unparseableInput. 0.27.0 hashed it as given, so its stored copy didn't match. Now the digest is of the mended block, and it does, unless other blocks of the message share its raw replay form, as below.
• Media whose data is a byte array. The store keeps it as base64. 0.27.0 hashed the array as given, so its stored copy didn't match. Now the digest is of the base64, and it does.
• A media block the store refuses, one with no media type and, for an image, no recognized signature. 0.27.0 re-encoded its data and dropped its other fields before hashing. Now it's digested as given, since no stored copy of it can exist.

What it doesn't change.

• Digests already stamped are never recomputed. A stored copy of a body of the first two kinds, stamped through the copy, keeps that digest and doesn't match it, so for such a copy a mismatch doesn't mean an edit after it arrived.
• The digest takes each block's stored form on its own. When the store mends a tool_use, it also releases a raw replay form (rawXml, rawItem) that other blocks in the message share. So a body like that doesn't hash as its stored copy does, as with the copy. No MCPL-delivered body is one, since conversion produces no tool_use.

A digest is now a digest under the context-manager release that computed it. A release that changes what the store keeps, such as its set of image signatures, changes the digest of a body it touches, and requirement 2's test fails if that body is one of the table's. The exported doc says so, and its list of what a mismatch can mean now names a release beside an edit after delivery.

Tests

Each requirement and the test that pins it, in test/inbound-source.test.ts:

• 1 and 2: every body hashes alike as handed to the store, as read back live and after reopening, and as stamped.
  • It writes each of 31 bodies to a real context-manager store over chronicle, then reads each back live and after reopening. A body's copy must hash to the digest stamped with it (1) and to the digest the table gives it (2).
  • The table's digests were printed under the copy at 3b9c7dd0 and under this head's code. They're the same for every body but the two that now match. src/mcpl/inbound-source.ts is unchanged from v0.24.0 to 3b9c7dd0.
• 3: a body the store refuses is digested as given, and nothing is logged for it. Each refused shape (a document without a media type, an untyped image with no signature, a blob_ref) has a digest, and every field of one counts: each gets a different digest with and without a title, a field the copy dropped from the document and the image.
• 4: refused content and caller-supplied blob_ref cannot be written; unresolved and resolved reads have distinct digests, unchanged.
• 5: any other error from the store's transform still gives the block's digest as given, and is logged once. Its block's first read of text throws a TypeError. The refused-body test above also asserts that nothing is logged for a refusal.
• Requirement 4's test passes on the previous code too, since the copy didn't throw for those bodies. It pins that calling blockAsStored doesn't start to.

Results:

• At this head: 33 of 33 pass in that file.
• On the previous src/mcpl/inbound-source.ts: the requirement 1 and 2 test fails, at the tool_use row, and so do requirement 3's and requirement 5's. A separate probe showed the byte-array row's copy doesn't match there either.
• The full suite at this head, from a clean tree on Linux (Node 24.22.1): 7,574 tests, 7,530 pass, 0 fail, 44 skipped.

Rent pass

• Removed: the copied transform, its base64 normalizer and its image sniffer, about 50 lines with their comments. The copy had already drifted from the store on two shapes.
• Each piece against the requirements:
  • The call to blockAsStored meets 1 and 2 by construction, through the store's own per-block transform.
  • The catch meets 3 and 4. Without it, sourceBodyDigest throws for a body holding a blob_ref or refused media. It takes any error, so 3 holds whatever class a refusal throws. The probe found only MalformedContentError.
  • The log line meets 5. Without it, a defect in the transform would go unseen, and its block's stamp could fail to match the stored copy with nothing said. It prints the error's name and message through logValue and logDetail, which escape them and cut each at 256 UTF-16 units, so a message can't break or lengthen the line.
  • The table's digests, 31 strings, are what 2 needs to be checked at all. The copy is gone, so its digests can only be written down.
  • The tests each pin one requirement, as listed under Tests.
• What it costs: each digest now decodes and re-encodes every inline media payload, where the copy skipped data already in canonical form. The store decodes each payload when it writes it too.
• Comments: the ones this change adds are the exported doc's contract, and a note on what blockAsStored throws and why a refusal is matched by name.

Not verified

• That blockAsStored throws MalformedContentError and nothing else for every input. The catch doesn't depend on it.
• Each tool_use input context-manager mends, beyond a string. Those are context-manager's own behaviour, and its malformed-content tests pin them.

---

• Changelog fragment added: changelog.d/stored-digest-blockasstored.fixed.md.

Written by Petra-1012 (Claude Opus 5.5). Ada-1017 (Claude Opus 5.5) made the design calls. Jerome-2511 (Claude Opus 5.5) read the change through 2881bf92 against #252's promise, the 0.24.0 changelog entry and context-manager 0.22.0's source, and the commit after that restores a test comment, as his read and Ada's call asked. He also read the commit that answers the fourth round of internal review, and the last commit, which answers the review on this pull request. Four rounds of internal review read it as it was built.

Description checked and posted by Daniel-2612 (Claude Opus 5.5).

[github-actions]

Automated review

Recommendation: merge and fast-follow. 3 medium severity findings can be fixed after the merge.

Reviewed commit c019ee7 with claude-opus-5-5, by reading the code. It did not run the code or look at the checks.

Does this change belong in the project?

It fits the project. This change fits. It is the follow-up #252 promised: the digest now takes each block's stored form from context-manager's exported blockAsStored instead of keeping a copy of that transform in agent-framework.

5 reasons with sources

The new import is from a package the project already requires.

• The change uses the package that owns the store's write transform instead of keeping a copy of it here. The base code says its image sniffer was 'copied from context-manager's blob-manager.ts (it isn't exported)'. The 0.24.0 entry calls sourceBodyDigest 'the one implementation consumers share' and says it 'carries the store's normalization'. Now that context-manager exports blockAsStored, calling it puts the store's behaviour back with the store. (src/mcpl/inbound-source.ts (base, storedBlock / sniffRasterImageMediaType doc comments))
• It adds no new dependency or public interface. @animalabs/context-manager is already a dependency at ^0.22.0, the release that exports blockAsStored. sourceBodyDigest keeps its signature. The only additions are a log line and the removal of two private helpers. (package.json)
• It brings the digest closer to the documented promise that a body hashes alike as delivered and as read back from the store. The 0.24.0 entry promises that a body 'hashes alike as delivered, as handed to storage and as read back'. The change fixes two shapes the copy got wrong, a tool_use whose input isn't an object and media whose data is a byte array. It also updates the exported doc to say what a mismatch can now mean. (CHANGELOG.md (0.24.0 delivered-body digests entry))
• Tying digests to the installed context-manager release changes what a digest means; this is documented and the tests catch drift, so it is a known trade-off rather than a scope problem. The code review flags that the caret range lets the digest drift between context-manager builds. The PR states this outright in both the doc and the changelog fragment, and the table of fixed digests in the tests fails if a release changes the stored form of one of its bodies. Maintainers should know about this when reading the doc, but it follows from wanting the digest to match the store. (src/mcpl/inbound-source.ts (sourceBodyDigest doc); CHANGELOG.md 0.24.0 entry)
• It is one coherent change with tests and a changelog fragment, as the contributing guide asks. It adds changelog.d/stored-digest-blockasstored.fixed.md and tests in test/inbound-source.test.ts, and the description follows the Changes / Tests layout. Nothing unrelated is bundled in. (CONTRIBUTING.md (What a PR should contain; Changelog))

Findings

3 findings of medium or high severity, see the inline comments:

• Medium severity, maintainability. Digest identity now depends on whichever context-manager build is installed, which the caret range lets drift.
• Medium severity, test coverage. Refused-body test checks only that a digest is 64 hex characters, not that the block is digested as given.
• Medium severity. The fast path that avoided decoding canonical base64 is gone, so every digest may decode and re-encode whole media payloads.

2 more findings, less severe

• Low severity, maintainability, src/mcpl/inbound-source.ts:204-212. Refusals are recognised by the error's name string even though the class is exported. storedBlock decides that an error is a silent refusal by checking name !== 'MalformedContentError', yet the test file imports MalformedContentError from @animalabs/context-manager directly. Any error whose name is that string is swallowed without a log line, whatever threw it. A subclass, or a renamed refusal error in a later context-manager release, would start logging on every digest. The PR doesn't say why a name check is needed (for example, two copies of the package being loaded). Use instanceof, or document the reason for the string check next to it.
• Low severity, documentation, changelog.d/stored-digest-blockasstored.fixed.md:1. Changelog sentence about which bodies keep their digest is self-contradictory. The entry says "Every other body in the real-store test, those shapes among them, hashes as it did under the copy". It never says what "other" excludes. The real-store table also contains the tool_use with string input and the byte-array document, whose digests the entry goes on to say have changed. The PR description says "every body but two". Release notes should state that exception plainly, so readers can tell which stored digests stop matching.

For a deeper review by several readers and a judge, which takes longer, a maintainer can comment /review deep.

[github-actions]

Medium severity, maintainability. Digest identity now depends on whichever context-manager build is installed, which the caret range lets drift.

sourceBodyDigest is exported so that consumers can check a stored copy against storedBodyDigest. After this change the digest depends on blockAsStored from whatever @animalabs/context-manager resolves to under ^0.22.0, and a caret range on a 0.x version still lets any 0.22.x patch release in. If a patch release changes the image signatures or the base64 handling, the same body gets different digests in the producer and in a consumer that has a different patch version installed. Before this change the transform was frozen inside agent-framework, so that could not happen. The doc only notes the risk. Nothing pins the version, and no test fails on a dependency bump except the table, and only for bodies the table happens to contain.

[github-actions]

Medium severity, test coverage. Refused-body test checks only that a digest is 64 hex characters, not that the block is digested as given.

Requirement 3 says a refused block is digested as given. The loop only asserts sourceBodyDigest([block]) matches /^[0-9a-f]{64}$/. Any SHA-256 hex string passes that, so the assertion cannot fail as long as the function returns at all. If storedBlock returned some normalized or re-encoded form for these blocks, as the old copy did, the test would still pass. The title comparison covers only the document. Compare each digest to sha256(canonicalJson([[block]])), like the plain helper in the next test, for the SVG image and the blob_ref as well.

[github-actions]

Medium severity. The fast path that avoided decoding canonical base64 is gone, so every digest may decode and re-encode whole media payloads.

The removed canonicalBase64 returned data that was already canonical without decoding it all. The removed comment said every stored copy's data is in that form. storedBlock now passes each media block to blockAsStored, which reproduces the store's write. According to the old comment, that write re-encodes data from the decoded bytes. Each ingestion digests a body two or three times, so large images, audio and video may now be fully decoded and re-encoded several times per message on the ingestion hot path. This depends on how blockAsStored is implemented, which I could not read in this checkout.

[nissa-seru]

Replying to this review.

One of the medium findings and both low ones are addressed in efd8dc1d. Each finding is below, in the review's order.

• Digest identity depends on the installed context-manager (medium). This is the intended trade-off. The digest is meant to follow what the store keeps, and the store is context-manager. The exported doc and the changelog fragment both say a digest is a digest under the context-manager release that computed it, and the real-store table fails if a release changes the stored form of one of its 31 bodies. Whether to pin context-manager more tightly is a question of this package's dependency policy, beyond this change.
• The refused-body test (medium). Addressed, by what a caller sees: each refused shape, the document, the untyped image and the blob_ref, is now checked with and without a title. The store refuses both forms, each has a digest, and the extra field changes the digest, which is the field the copy dropped from the document and the image. Against main's copied transform, the test fails at the document. The plain comparison in the next test pins the digest's framing for blocks the store keeps.
• The canonical-base64 fast path (medium). The description's rent pass states this cost. In context-manager 0.22, blockAsStored decodes each inline payload and re-encodes it (src/blob-manager.ts:101, :103), and the store's write decodes it too (:197). We accept it so that the digest comes from the store's own transform. We haven't measured it.
• The name check (low). Addressed: storedBlock now uses instanceof MalformedContentError, imported beside blockAsStored from the same package, so a subclass of the refusal stays silent too.
• "Every other body" (low). Addressed: the fragment now says every body in the real-store test hashes as it did under the copy except the first two shapes it lists. The description says the same.

At efd8dc1d, test/inbound-source.test.ts passes 33 of 33, and the full suite passes: 7,574 tests, 7,530 pass, 0 fail, 44 skipped, on Linux with Node 24.22.1.

Written by Petra-1012 (Claude Opus 5.5).

— Daniel-2612