Tuple: support custom update seeds, and check seed hashes - #785

Summary

Java tuple sketches always hashed with the default seed. They wrote a fixed seed hash and never checked the seed hash, either when reading an image or when combining sketches. As a result, Java accepted images created with any seed, and set operations could silently mix sketches built with different seeds. The C++, Go and Rust tuple sketches support custom seeds and reject mismatches. This PR brings Java in line with them, and with Java theta.

API: all changes are additive overloads

No existing signature changes. The new methods and constructors are:

• UpdatableTupleSketchBuilder.setSeed(long), and a seed constructor on UpdatableTupleSketch.
• Seed constructors on DoubleTupleSketch, IntegerTupleSketch, ArrayOfStringsTupleSketch and FdtSketch.
• TupleUnion(nomEntries, summarySetOps, seed), TupleIntersection(summarySetOps, seed) and TupleAnotB(seed).
• Seed overloads of the two static TupleAnotB.aNotB methods and of the 8 tuple JaccardSimilarity methods. The Jaccard overloads match what Align theta and tuple JaccardSimilarity; check theta seeds in tuple set operations #782 added for theta.
• TupleSketch.heapifySketch(seg, deserializer, seed) and a public TupleSketch.getSeedHash(), as on ThetaSketch since Align theta and tuple JaccardSimilarity; check theta seeds in tuple set operations #782.

Behavior

• Writing: compact images record the sketch's seed hash. Empty images record zero, as in theta. Images written with the default seed are byte-for-byte unchanged.
• Reading: reading a non-empty compact image checks its seed hash against the expected seed. That is the default seed unless the new overload is used. Legacy images (serial versions 1 and 2) were always written with the default seed.
• Set operations: union, intersection, A-not-B and Jaccard check the seed hash of every non-empty tuple or theta input. Their results carry the operation's seed hash.
• Updatable form: the deprecated updatable serialized form has no seed hash, so it is always read as the default seed. Serializing an updatable sketch built with a custom seed throws SketchesStateException. Call compact() first. C++ doesn't serialize updatable tuple sketches at all.

For default-seed users nothing changes. The only new exceptions are seed mismatches, which used to produce wrong results silently.

Verification

• mvn verify passes, including javadoc and style checks.
• The cross-language checks (check_java_files, check_cpp_files and check_go_files) pass for TupleCrossLanguageTest. Java still reads the C++ and Go tuple_int_* images, now with their seed hash checked.
• The new test file is TupleCustomSeedTest. It covers:
  • seed hashes through copy(), compact() and serialization;
  • that the default-seed image still carries 37836, as C++ does;
  • the empty-image handling;
  • reading compact images with a matching and with a mismatched seed;
  • the updatable-form behavior;
  • the stateful and stateless union, intersection and A-not-B, with both tuple and theta inputs;
  • Jaccard and Filter;
  • the derived sketches, including FdtSketch.

🤖 Generated with Claude Code