`app.domain.hashing`¶

Canonical content hashing for ADR files (sha256-v1).

The digest identifies a content revision only. It is computed from the exact bytes that were fetched or pushed, after this canonicalization:

Decode as strict UTF-8.
Remove one leading U+FEFF (byte order mark).
Replace CRLF with LF, then any remaining lone CR with LF.
Encode as UTF-8 and hash with SHA-256.

No path, ref, commit, project or registration id enters the hash. Bytes that are not valid UTF-8 cannot be canonicalized; they are hashed as-is under the separate sha256-raw-v1 algorithm so the record can still be stored (such records cannot be approved).

Public API:

HASH_VERSION, RAW_HASH_VERSION
canonicalize_text(), canonicalize()
Digest (str(digest) -> "sha256-v1:<hex>"; Digest.parse() for the reverse)
content_digest()

app.domain.hashing.HASH_VERSION = 'sha256-v1'¶: Algorithm label of the canonical digest.

app.domain.hashing.RAW_HASH_VERSION = 'sha256-raw-v1'¶: Algorithm label used for bytes that are not valid UTF-8.

class app.domain.hashing.Digest(algorithm, hex)¶

Bases: object

A content digest together with the algorithm that produced it.

Parameters:

algorithm (str) – HASH_VERSION or RAW_HASH_VERSION.
hex (str) – 64 lowercase hexadecimal characters.

algorithm: str¶

hex: str¶

property is_canonical: bool¶

Tell whether the digest was computed from canonical UTF-8 text.

Returns:: True for sha256-v1, False for the raw fallback.

classmethod parse(value)¶

Parse a digest string produced by __str__().

Parameters:: value (str) – A string such as "sha256-v1:<hex>".
Return type:: Digest
Returns:: The parsed digest.
Raises:: ValueError – If the string is not a known digest.

app.domain.hashing.canonicalize_text(text)¶

Apply the text-level canonicalization steps (BOM, line endings).

Parameters:: text (str) – Already decoded file content.
Return type:: str
Returns:: Text without a leading BOM and with LF line endings only.

app.domain.hashing.canonicalize(raw)¶

Decode and canonicalize raw file bytes.

Parameters:: raw (bytes) – The exact bytes fetched or pushed.
Return type:: str
Returns:: The canonical text that is hashed by content_digest().
Raises:: UnicodeDecodeError – If raw is not valid UTF-8.

app.domain.hashing.content_digest(raw)¶

Compute the content digest of raw file bytes.

Never raises for undecodable input: bytes that are not valid UTF-8 are hashed verbatim under RAW_HASH_VERSION.

Parameters:: raw (bytes) – The exact bytes fetched or pushed.
Return type:: Digest
Returns:: A sha256-v1 digest, or a sha256-raw-v1 digest when raw is not valid UTF-8.

app.domain.hashing¶

`app.domain.hashing`¶