docs: hash canonicalization design (A-6 residual survey + v0.5.0 proposal)#9
Merged
Merged
Conversation
…on verification Survey of deployed hashing in coven-threads-core and the coven daemon (BLAKE3 structural commitments, SHA-256 content fingerprints), plus the proposed normative design closing the v0.3.0 A-6 residual: algorithm assignment by role, canonical encodings for ward_hash/diff_hash/entry_hash, hex conventions, cross-implementation verification statement, conformance coverage, and v0.5.0 sequencing behind the threads-vfk §6.3 freeze. Non-normative; RFC text lands separately as a draft minor. Bead: threads-5vn Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a non-normative design/survey document to close out the v0.3.0 “A-6 residual” by specifying a proposed approach for hash algorithm selection and canonical encodings for RFC-0001 §5.6 audit-log hash fields, enabling cross-implementation verification.
Changes:
- Introduces a design doc surveying deployed hashing practices (BLAKE3 vs SHA-256) and identifying inconsistencies (endianness, prefixing, naming collision).
- Proposes a normative design direction (D-1..D-4) for algorithm assignment, canonical byte encodings, and verification requirements.
- Outlines a conformance coverage plan, migration impact, and sequencing toward a v0.5.0 draft minor.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Non-normative design doc closing out the survey/design phase of the v0.3.0 A-6 residual: RFC-0001 §5.6 requires attestation referents to resolve, but hash algorithm and entry canonicalization are unspecified — two independent implementations cannot verify each other's provenance chains.
docs/superpowers/specs/2026-07-22-hash-canonicalization-design.md(follows the approval-tier-compiler design-doc precedent):coven-threads-coreand thecovendaemon: BLAKE3 for domain-tagged structural commitments (ward_hash= weave Merkle root, manifest entry hashes, evidence replay), SHA-256 for content fingerprints (diff_hash= post-writenext_sha256, memory chunks, revision hashes). All claims verified against source.sha256:-prefixed hex site vs bare hex everywhere else;entry_hashname collision (daemon ward-manifest entry vs RFC §5.6 memory entry).HashAlgodiscriminator convention, and a cross-implementation recompute-and-verify MUST.What this is not
No RFC text changes. The normative amendment is a v0.5.0 draft minor sequenced behind: PR #7 merge+tag →
threads-vfk(§6.3 freeze) → v0.5.0. Rationale in the doc's Sequencing section (the A-7 lesson: land version-rule-dependent changes under a previously-ratified rule).Verification
manifest_entry_hash,for_verdict/for_applydiff_hashsemantics,HashAlgotags, schema BLOB/TEXT encodings all re-checked against source at coven-threadsmainand coven daemonmain.Bead:
threads-5vn. Merge authority: Val.