[Proposal] Java compatibility fixtures and PoC selection matrix for the Rust modernization groundwork

Start with LongEncoding and its LongEncodingTest, then inspect the current Java 8 test-resource layout and build configuration. Define the candidate matrix, add the line-based LongEncoding corpus and JUnit 4 replay test, and document the stated edge cases, errors, invariants, and length limits. Done means the matrix is reviewed and the corpus and replay test run in the normal suite.

Follow-up to the discussion in #3110. @imbajin confirmed the testing and validation groundwork can start before any Rust decision, so this issue tracks the Java-only part: a selection matrix for the first PoC candidate and golden compatibility fixtures for the codec classes.

Scope

Three deliverables, all plain Java against the current build:

1. A selection matrix for PoC candidates (first cut below, to be refined in this thread).
2. A golden fixture corpus for LongEncoding plus a replay test that runs it against the current implementation.
3. Short written notes on the behavioral contract the fixtures lock down (edge cases, error behavior, invariants).

Non-goals

No Rust, no JNI, no Cargo, no packaging changes, no new Maven modules, no runtime wiring. Those wait for the component decision, a mentor, and a design review with contributors who have deeper Rust experience, as discussed in #3110.

Selection matrix

Criteria: an existing test oracle, enough call sites to matter, work per call big enough to survive a JNI crossing, and, following the maintainer feedback in #3110, keeping the Java implementation alive has to stay cheap: graceful fallback is the maintainer-preferred direction, which this matrix adopts as a selection criterion.

With the fallback criterion the concurrent structures and the serializer drop out of round one. LongEncoding is the first fixture target. That is a choice about where to write fixtures first, not a decision that it becomes the Rust PoC.

Fixture shape

Plain ASCII, line-based (TSV with \uXXXX escapes for non-ASCII), checked into test resources so it needs no extra dependency to read. It covers: round trips across the full value range including Long.MIN_VALUE/MAX_VALUE (the encoding does intentional wrapping arithmetic), arbitrary UTF-16 input on the decode side (valid inputs are ASCII, invalid ones are not), the error cases (IllegalArgumentException vs NumberFormatException vs NPE on null), and the length limits.

The replay test is JUnit 4 and compiles at the Java 8 level, since that is the current hugegraph-commons baseline. Root is Java 11. Java 17 / commons Java 11 from #3117 are treated as declared targets, not assumptions.

Acceptance

• matrix reviewed in this thread
• corpus + replay test merged and running in the normal test suite
• contract notes written up here or in the PR

Future PoC evaluation (outside the current implementation scope)

The following diagram illustrates a later evaluation step. No Rust component is selected here; any future PoC should compare compatibility and end-to-end costs, including JNI and data conversion, against the Java baseline.

References

Annotated references and suggested practices: SQLite, Parquet, Arrow, Protobuf, Go, Insta, Wycheproof, encoding test vectors, and Java/Rust integration examples.