Skip to content

docs: clarify ADR-0003 selects only two Merkle hash operations - #339

Closed
SnehD wants to merge 1 commit into
agentrust-io:mainfrom
SnehD:docs/clarify-merkle-adr-337
Closed

docs: clarify ADR-0003 selects only two Merkle hash operations#339
SnehD wants to merge 1 commit into
agentrust-io:mainfrom
SnehD:docs/clarify-merkle-adr-337

Conversation

@SnehD

@SnehD SnehD commented Aug 24, 2026

Copy link
Copy Markdown

What

Clarifies ADR-0003 so it states plainly that only two Merkle hash operations are approved, instead of reading like there might be four.

Why

Fixes #337. The "Alternatives considered" section listed rejected constructions (plain concatenation, BLAKE3, flat hash) right next to the two approved operations without saying they were rejected, so a reader could mistake them for additional supported options. The ADR also carried old leaf-content wording that no longer matches the current specification.

Spec impact

No normative text changed. The ADR now explicitly defers to:

  • Section 4.1.1 — the shared Merkle construction (the two approved hash operations)
  • Section 3.2.3 — tool catalog leaf data and ordering
  • Section 3.2.5.1 — RAG corpus leaf data and ordering

No conformance test IDs are affected.

Test plan

  • Documentation-only change, no code affected
  • git diff --check passes (no whitespace errors)
  • Confirmed the outdated leaf-description wording is removed
  • No Markdown diagnostics on the file

DCO

  • Sign-off not yet added to this commit — will add before merge if required.

@SnehD
SnehD requested a review from a team as a code owner August 24, 2026 18:02
ADR-0003 listed the two approved RFC 9162 Merkle hash operations
(leaf hash and interior-node hash) alongside rejected alternatives
(plain concatenation, BLAKE3, flat hash) without clearly separating
the two. This could be misread as four supported constructions.

Also removed outdated leaf-content wording that no longer matches
the current specification, and pointed readers to spec sections
4.1.1, 3.2.3, and 3.2.5.1 as the source of truth for those details.

Documentation only. No code, hashing, or API changes.

Signed-off-by: Sneha Dalvi <sneha.dalvi2000@gmail.com>
@imran-siddique

Copy link
Copy Markdown
Member

Closing this one, and the reason is not that the idea is wrong. It is that the premise moved.

This diff is byte-identical to the ADR hunk in #338. Same blob transition, 5b9bea6..851f3c4, same eight lines. So it carries no content #338 does not already carry, and merging both would conflict them against each other.

The claim itself is now false. Both PRs say "These are the only two Merkle hash operations selected by this ADR." #335 merged to main yesterday and added a third: the composite policy sub-bundle leaf in Section 3.2.2, which carries the raw digest bytes of each sub-bundle hash rather than a JSON descriptor. That is why both PRs are showing conflicts against docs/adr/0003-rfc9162-merkle-domain-separation.md. The file on main now describes three operations, not two.

Unlike #338, there is no separable correct half here to keep, since the stale sentence is the whole PR.

The part of the hunk worth preserving is the second half, pointing Section 4.1.1 at the shared construction and Sections 3.2.3 and 3.2.5.1 at each artifact's leaf data, and scoping RFC 8785 to where those sections define JSON as an input to a hash. That is a real clarification and it survives the third operation existing. I have asked for it in the #338 review, rewritten against the three operations that are actually there, so the ADR gets touched once rather than twice.

Full detail in the #338 review, which also covers the canonicalization work. Thanks for splitting the docs change out in the first place, that instinct was right; it just happened to be the half that main moved under.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4.1.1 enumerates two Merkle constructions while ADR-0003 now names four

2 participants