File size: 5,565 Bytes
ecad52f | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | # 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::<normalized text>::<YYYY-MM-DD>::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.
|