Cooperative embedding

[jshook]

This includes some changes we need to make the embedding surface more robust around shared resource usage and scoping. I've shared it here for visibility and will move it from draft status once our integrated testing bears fruit.

This is now rebased on top of Aaron's compaction improvement fixes, so testing of this branch is all-inclusive of both

Synopsis

Make the on-disk graph compactor embeddable (cooperative resource sharing). The shape of the interfaces types provided here were carefully selected to be useful and compatible with an embedding system like Cassandra or OpenSearch, without being overly specific to any. They were also chosen to be compatible with Java 11 onward.

Purpose

OnDiskGraphIndexCompactor currently runs on its own thread pool, is invisible while it works, and always writes to its own file. This PR adds a few small, optional extension points so a host system (e.g. a database's compaction pipeline) can drive the merge cooperatively — on the host's own threads, under the host's observation and throttling, writing straight into the host's own file. Everything is additive and @experimental; with nothing supplied, behavior and output are unchanged.

Key elements

• Bring-your-own executor. The compactor now takes any Executor plus an explicit taskWindowSize instead of requiring a ForkJoinPool. Passing a caller-runs executor (Runnable::run) runs the whole merge on the calling thread, so a host reuses its existing compaction threads with no extra pool.
• Progress + throttling (ProgressLimiter). One small SPI the host installs to (a) observe merge progress and (b) block/pace the bytes the merge writes against a shared budget — without jvector knowing anything about the host's limiter. Ships with two ready-made, composable implementations:
  • a leaky-bucket rate meter
  • a logging wrapper
• No-copy output (CompactionDestination / compact(Path, startOffset)). Write the compacted graph body directly into the host's container file after a reserved header — with a commit-on-success / discard-on-failure lifecycle — instead of writing a temp file and copying it. SeekableSink is the small primitive used to address that file region.

Tests and docs/compaction.md cover the new surface.

[github-actions]

Before you submit for review:

• Does your PR follow guidelines from CONTRIBUTIONS.md?
• Did you summarize what this PR does clearly and concisely?
• Did you include performance data for changes which may be performance impacting?
• Did you include useful docs for any user-facing changes or features?
• Did you include useful javadocs for developer oriented changes, explaining new concepts or key changes?
• Did you rebase your branch onto the latest main for regression testing and PR submission?
• Did you trigger regression testing via Run Bench Main and review results?
• Did you adhere to the code formatting guidelines (TBD)
• Did you group your changes for easy review, providing meaningful descriptions for each commit?
• Did you ensure that all files contain the correct copyright header?
• Did you add documentation for this feature to the release notes directory?

If you did not complete any of these, then please explain below.