[johnnyt]

Refs: uxjv-0tl

What

• README.md in the family recipe: what, why, install (the Maven <dependency> block and the Gradle coordinate for systems.riddler:uxid at 1.0.0), one basic-usage block (compiled and run against the built classes before it went in), Compatibility (Java 17 and later, no dependencies, the module systems.riddler.uxid, thread safety of Monotonic) and Documentation.
• docs/wire-format.md: a short pointer to guides/wire-format.md in uxid-ex at the tag v2.10.0 and to conformance/SOURCE.json.
• Javadoc: UxidOptions.Builder.prefix says a deterministic id refuses a prefix holding an unpaired surrogate and a time-based id keeps it; Uxid.decode says the clock arithmetic wraps silently within about 2^40 ms of Long.MIN_VALUE; Monotonic says the pair of time and random value increases (a fresh seed after a later clock or an overflow can be a smaller random value alone) and that its state grows by one entry for each distinct prefix and random width; isValid and isDeterministic say they are stricter than the Elixir reference's valid? and deterministic?.
• changelog.d/uxjv-5tk.md carries the same two Monotonic caveats.
• CLAUDE.md lists the README and the pointer in the tree paragraph, rewrapped to the file's width.

Tests

• New: UxidGenerateTest.aTimeBasedIdKeepsAPrefixWithNoUtf8EncodingAsGiven pins that the time path never encodes the prefix.
• CorpusHashTest.sourceJsonRecordsTheSameHashAndTheTagItCameFrom now pins the tag to v2.10.0 and the sha to 57235777cb29c70f751552ce7aa20ab5fe71fb74 instead of checking their shape.
• Two sabotage notes corrected after re-running the mutations: DecodeClockTest.theWindowEndIsExclusiveAndItsLastMillisecondRecoversTheGuardCase fails on the END assertion; UxidDecodeTest.eitherCaseDecodesToTheSameValue fails on the decoded() instance check.

Sabotage rows (each mutation applied, run, restored byte-equal)

Test	Mutation	Outcome
DecodeClockTest.theWindowEndIsExclusiveAndItsLastMillisecondRecoversTheGuardCase	time - now > ONE_DAY made >= in Decoder.compactTime	assertion failure at the END assertion
UxidDecodeTest.eitherCaseDecodesToTheSameValue	upper-case folding removed in Base32.value	assertion failure in decoded() (instance check)
UxidGenerateTest.aTimeBasedIdKeepsAPrefixWithNoUtf8EncodingAsGiven	prefix UTF-8 encoded in the time path of Uxid.generate	assertion failure from assertDoesNotThrow
CorpusHashTest.sourceJsonRecordsTheSameHashAndTheTagItCameFrom	SOURCE.json sha changed by one digit, then the tag changed to v2.10.1 (two runs)	assertion failure on the sha, then on the tag

Gate

mise run gate green on the head before the commit (192 tests, JaCoCo check, Javadoc and sources jars with the Javadoc lint at all and warnings failing the build); the commit staged the byte-identical tree. No public type or member is added or changed (Javadoc text only), so the in-turn review tier applies.