docs: clarify ADR-0003 selects only two Merkle hash operations - #339
docs: clarify ADR-0003 selects only two Merkle hash operations#339SnehD wants to merge 1 commit into
Conversation
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>
845215a to
e31b585
Compare
|
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, 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 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. |
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:
No conformance test IDs are affected.
Test plan
git diff --checkpasses (no whitespace errors)DCO