| Safe Haskell | None |
|---|---|
| Language | GHC2024 |
Keiro.DeterministicId
Description
The seed encoding shared by Keiro's deterministic (version-5 UUID) identifiers.
A deterministic id is a pure function of a seed text, so that an
at-least-once writer collapses to exactly one row: the workflow journal's
event ids, sleep timer ids, legacy awakeable ids, and process-manager
command ids are all derived this way. That makes the seed encoding /replay
identity/ — it must yield the same bytes for the same text on every deploy,
forever. The rule is recorded in
docs/adr/0024-deterministic-ids-hash-utf-8-seed-bytes-and-are-frozen-replay-identity.md.
Synopsis
- identitySeedBytes :: Text -> [Word8]
- legacySeedBytes :: Text -> [Word8]
- seedMovedAcrossEncodings :: Text -> Bool
- deterministicIdProbes :: Text -> NonEmpty UUID
Documentation
identitySeedBytes :: Text -> [Word8] Source #
The UTF-8 bytes of a deterministic-id seed, in the [Word8] shape
Data.UUID.V5.generateNamed expects.
UTF-8 rather than the codepoints themselves: the original derivations fed
fromIntegral . fromEnum over Text.unpack into the hash, which truncated
every character to its codepoint modulo 256, so "x0101" and "SOH" (and
countless CJK pairs) hashed identically and could be assigned one id. For
pure-ASCII seeds UTF-8 bytes are the codepoint values, so every id derived
from an ASCII seed is byte-identical to what the truncating encoding
produced; only non-ASCII seeds move, and they move off a collision.
This function is frozen. Changing it renames every deterministic id in every deployment, which no amount of retrying recovers from, so a future change needs an explicit versioned derivation and a migration story rather than an edit here.
legacySeedBytes :: Text -> [Word8] Source #
The pre-0.12 deterministic-id seed encoding.
This deliberately reproduces the historical Char -> Word8 truncation so
deployed identifiers can be probed during the compatibility window. It is a
frozen reader for old identity, not an encoding for new writes.
seedMovedAcrossEncodings :: Text -> Bool Source #
Whether UTF-8 and the historical seed encoding can produce different bytes for this seed. ASCII is byte-identical under both encodings.
deterministicIdProbes :: Text -> NonEmpty UUID Source #
Ordered candidate ids for one deterministic-id seed under the ADR 24 compatibility bridge: the current UTF-8-derived id first, the frozen pre-UTF-8 id second only when the seed's bytes differ across encodings. This is the single source of truth for the dual-probe policy; call sites must not restate the ordering or the moved-seed condition.