# Matrix checksum format: bodul-matrix-v1 Status: frozen compatibility specification, published 2026-11-03. Reference implementation: Matrix Core 3.6.0-OMEGA, Apache-2.0. Changes to this document may clarify examples but MUST NOT silently change the v1 byte sequence. ## Inputs and normalization The payload is a non-empty sequence of Unicode scalar values. Encode with strict UTF-8, without adding a byte order mark. An existing U+FEFF in input is data. Lone UTF-16 surrogates are invalid. The reference entry points impose a limit of 1,048,576 raw UTF-8 bytes BEFORE normalization; oversized input receives no seal. Normalization profile **bodul-whitespace-v1** uses exactly these 29 code points: ```text 0009 000A 000B 000C 000D 001C 001D 001E 001F 0020 0085 00A0 1680 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 200A 2028 2029 202F 205F 3000 ``` Replace each maximal run with one U+0020, then remove leading and trailing U+0020. Reject an empty result. No NFC, NFKC, case folding, punctuation changes, locale rules, or future Unicode property lookup applies. U+180E, U+200B, U+2060, and U+FEFF remain data. Visually similar text may intentionally have different checksums. This table preserves the legacy Python 3.12 whitespace behavior without depending on future Unicode databases. ## UTC date and exact message bytes Convert an explicitly supplied aware datetime to UTC FIRST. Select its date in the proleptic Gregorian calendar, years 0001 through 9999 inclusive. Format the date as ten ASCII characters `YYYY-MM-DD`, including leading zeroes. Concatenate exactly, without quotes, BOM, terminal newline, or NUL terminator: ```text BODUL_MATRIX::::::OMEGA_FLOW ``` Encode as strict UTF-8 and apply SHA-256 as specified by [FIPS 180-4](https://csrc.nist.gov/pubs/fips/180-4/upd1/final). Return 64 lowercase hexadecimal characters, preserving leading zeroes. The suffix is not a parser for recovering text: verification uses the supplied payload and date. Literal `::` in the payload is ordinary data. There are no secret keys. The engine version, full timestamp, and response labels are NOT part of the hash input. ## Timestamp interchange grammar The portable JSON/CLI boundary accepts only ASCII: ```text YYYY-MM-DDTHH:MM:SS[.ffffff](Z|+HH:MM|-HH:MM) ``` Fractional seconds, when present, have 1 through 6 digits. Offset hours are 00..23; offset minutes are 00..59. Calendar validity is checked. `-00:00` denotes an unknown offset and is rejected. Leap seconds, offsets containing seconds, week dates, compact dates, spaces instead of `T`, and missing offsets are rejected. Results use a UTC `+00:00` offset; nonzero microseconds use six digits. UTC conversion outside 0001..9999 is rejected. This deliberately narrow grammar prevents a future parser expansion from changing accepted input implicitly. The Python datetime API also accepts aware datetime objects; archive replay uses the stricter text interchange grammar. With no `now`, the Python core captures UTC once. Offline CLI replay requires `--at` explicitly. ## Output and historical verification Success includes `valid: true`, normalized `input_payload`, `seal_date`, `matrix_verification_seal`, `timestamp`, `engine_version`, `checksum_format`, `normalization_profile`, and `hash_algorithm`. An invalid payload includes `valid: false`, an error code and metadata, with NO seal. Machine schema: `schemas/matrix-result-v1.json`; independent fixtures: `test_vectors.json`. `verify_result` verifies the consistency of a successful exported result. It requires the exact field set, supported format/profile/hash identifiers, canonical normalized input, a timestamp matching the UTC date, and the correct seal. Original unlabeled **3.5.1-OMEGA** records remain readable. Other unlabeled records and unknown future formats fail closed. Invalid-input records cannot be verified as successful checksums. Existing valid 3.5.1 checksums remain unchanged. Version 3.6 adds explicit format metadata and controlled Unicode/size errors; clients comparing complete objects must account for the additional fields and engine version. The full result repeats only when text, time and engine metadata also match. The seal repeats for matching normalized text and UTC date. Metadata may be edited without changing a same-day seal; verification does not authenticate that metadata, authorship, original acquisition time, or external truth. ## Future migrations Never redefine v1 or infer the format from digest length alone. If a new hash, normalization profile or message layout is needed, publish a NEW format ID, domain-separated bytes, independent vectors, reader and migration notes. Keep the old reader for historical checks. Store original source text, old result, new result, migration date and source revision together; do not overwrite the only historical record. Rehashing does not prove when the original existed. SHA-256 security is not guaranteed for a century. Review cryptographic guidance periodically. Archive manifests include SHA-256 and SHA-512 for byte comparison; neither is a signature, and both belong to the SHA-2 family. ## References - [Python whitespace behavior](https://docs.python.org/3/library/stdtypes.html#str.isspace) - [NIST Secure Hash Standard](https://csrc.nist.gov/pubs/fips/180-4/upd1/final) - [RFC 3339 timestamp conventions](https://www.rfc-editor.org/rfc/rfc3339) These links explain current conventions. The explicit rules and bundled fixtures above are the preservation contract if the websites disappear.