GeezerVison

Follow-up work stacked on the iterator-performance branch (targets that branch, not master). It fixes two correctness/contract issues in the new iterator/stream code, adds the missing unit/integration coverage for the gh-269 helpers, and tidies a few related items. All changes are additive or self-contained; the design decisions on the branch (see "Deliberately left open" below) are untouched.

Fixes

1. Reverse prefix iteration silently drops rows when the prefix ends in 0xFF

BufferProxy.incrementLeastSignificantByte computed the "prefix successor" by incrementing the least-significant non-0xFF byte but keeping the trailing 0xFF bytes — e.g. {0x01,0xFF} → {0x02,0xFF} instead of the tight {0x02}.

In LmdbPrefixReversedIterator/LmdbPrefixReversedSpliterator the successor is used to MDB_SET_RANGE past the prefix range and step back. When it over-shoots, an unrelated higher key that sorts between the last prefix match and the over-shot successor is landed on, the containsPrefix check fails, and iteration wrongly yields nothing.

• Reproduced by LmdbPrefixReversedSuccessorTest (keys {0x01,0xFF}, {0x01,0xFF,0x05}, {0x02,0x00}; reverse-prefix {0x01,0xFF} returned [] before the fix).
• Fixed by truncating trailing 0xFF (tight successor) across all four proxies' big-endian byte-string branch (ByteArray, ByteBuffer, DirectBuffer, Netty). The little-endian/integer-key branch is left as-is — prefix scans operate on big-endian byte strings.

2. LmdbStream Spliterator advertised SORTED with a null comparator

createEntryComparator/createReversedEntryComparator returned null (real body commented out), yet every spliterator reported ORDERED | DISTINCT | SORTED | NONNULL and getComparator() returned that null. A SORTED spliterator with a null comparator implies natural ordering, but KeyVal is not Comparable.

• Dropped SORTED and DISTINCT (DUPSORT can repeat keys) → ORDERED | NONNULL.
• getComparator() now throws IllegalStateException, as required for a non-sorted spliterator.
• Removed the dead entryComparator plumbing (also clears the "useless rangeComparator parameter" scan alerts).
• Note: a real Comparator<KeyVal<T>> + SORTED isn't safe without first emitting per-element snapshots, because the spliterator emits a single reused KeyVal (collect(toList()) returns one aliased instance for every row). That's a larger design change and is left to the maintainers.

3. KeyRange.getType() returned null for builder-created ranges

The private constructors used by KeyRange.builder() never set type, so getType() returned null and would NPE the legacy CursorIterable path. Builder/empty ranges now derive the equivalent KeyRangeType. Prefix ranges still have no KeyRangeType (documented) as they are only consumed by the new iterators.

Tidy-ups

• Dbi.stream()/newIterate() javadoc now warns that entries are a single reused KeyVal holder (so collect/sorted/distinct observe aliased entries) and that the stream is ORDERED but not SORTED.
• Dbi.getNameAsString(Charset): removed a dead try/catch and misleading "assume UTF8" comment (new String(byte[], Charset) never throws).
• Fixed a stale javadoc link CursorIterable.JavaRangeComparator → JavaRangeComparator.

New/updated tests

• BufferProxyPrefixTest — containsPrefix + incrementLeastSignificantByte across all four proxies, incl. edge cases (empty/oversized prefix, unsigned bytes, trailing-0xFF truncation, all-0xFF → null).
• CompareAsIntegerKeysTest — length-mismatch guard + non-4/8-byte lexicographic fallback for the integer-key comparators.
• KeyRangeBuilderTest — builder/prefix/inclusive accessors + derived KeyRangeType.
• LmdbStreamCharacteristicsTest — locks in the corrected spliterator contract.
• DbiIterateApiTest — newIterate(EntryConsumer) overloads, ranged stream, LmdbIterable single-use, getNameAsString, toString.
• LmdbPrefixReversedSuccessorTest — the reverse-prefix regression above.

Verification

Full test suite (excluding the pre-existing, environment-flaky TestLmdbStreamBenchmark, which fails at Env.open unrelated to these changes): 1687 tests, 0 failures. mvn fmt:check is clean for all touched files. Java 8 source level unchanged.

Deliberately left open (branch decisions, not addressed here)

These came up while reviewing the branch and are for the maintainers, not this PR:

• Approach approval; renaming the placeholder newIterate(...) and retiring/adapting CursorIterable for API compatibility.
• Whether to split the bundled FlagSet / DbiBuilder / ByteUnit / The new MDB_UNSIGNEDKEY DbiFlag should probably be the default behaviour #249 / CursorIterable used with BACKWARD_AT_LEAST and BACKWARD_CLOSED is not returning expected ranges of results when using DUPSORT #267 work from the iterator perf change.
• Rebasing onto current master; squashing WIP history and purging the accidentally-committed native binaries (src/main/resources/org/lmdbjava/*.so|*.dll) that live in branch history.
• Codecov gate (new Env/Dbi/Cursor methods still thinly covered) and the remaining code-scanning alerts (deprecated Env.openDbi in tests, NumberFormatException in CSV parsing, field shadowing) — some intentionally not touched here as they live in branch-owned test helpers.
• The KeyVal-snapshot redesign that would let SORTED + a real comparator return.

🤖 Generated with Claude Code