Compaction conversion

[jshook]

This PR is for illustrative purposes only. It should not be merged, so I'm setting it as Draft. We'll delete it when we're done with the review of the approach.

Purpose

Convert the general execution paths onto the embedding seams, and document the compactor conversion as an illustration of how the upstream integration robustness APIs might be used.

Stacked PR. This builds on the embedding-seams PR (integration-robustness) and targets that branch, not main. Please review/merge it after the base PR.

Why

The base PR added the embedding seams with no consumers. This PR shows how jvector's operations adopt them. Two categories:

• The general build/quantize paths are converted as real code.
• The compactor's own conversion is captured as a design note, not code: in the current lineage the compactor's seam-wiring is inseparable from the compaction-algorithm work (a single ~1,100-line diff), so this PR documents the target the clean compaction work should hit rather than carrying that algorithm here.

Real code

• GraphIndexBuilder → ParallelExecutor. Build and finalize route through ParallelExecutor (a host pool, or caller-runs so no work escapes to the common pool). Existing ForkJoinPool constructors are preserved — they now wrap ParallelExecutor.forkJoin(pool) — so current callers are unaffected.
• Quantization (PQ/NVQ/BQ) → ParallelExecutor. encode/refine/compute accept a ParallelExecutor; the existing ForkJoinPool entry points remain as delegating overloads. Includes QuantizationCallerRunsTest, which verifies caller-runs output matches the pool-backed path.
• EmbeddedExecutionContext. A single carrier for the execution resources an embedder supplies — a compute ParallelExecutor plus merge/io executors — so the pool is passed once and "no work escapes to the common pool" lives in one place. of(pool) bounds everything to a host pool; callerRuns() runs inline on the calling thread (the memtable-flush case). Build and PQ/NVQ train/refine/encode are wired through it.

Documented — docs/compaction-seam-conversion.md

before/after for each compactor calling convention, using the real integration-lineage signatures:

• execution — an Executor constructor + taskWindowSize bound, defaulting to the shared pool only when none is supplied;
• progress + throttle — setProgressLimiter(...), with onProgress (up) / acquire (down) at phase boundaries doubling as cancellation checkpoints;
• output — compact(CompactionDestination) with the Target open/commit/close lifecycle and host-owned footer via SeekableSink.over(...);
• PQ retrain through the compute executor (closing the historical retrain leak);
• parallel writer via OnDiskParallelGraphIndexWriter.Builder.withExecutor(io);
• compactor-local memory safety — drain-on-unwind and truncate-reused-outputs — that lands with the conversion (the reader-side guard is already in the base PR).

Note on EmbeddedExecutionContext scope

Its compactor/writer/retrain factory methods (newCompactor, newParallelWriter, retrainPQ) are intentionally omitted here — they call converted compactor APIs that don't exist yet — and are shown in the design note instead. The merge/io executor roles are still carried so the note can reference mergeExecutor() / ioExecutor() directly; those methods return as thin wiring once the compactor is converted.

Testing

jvector-base compiles at --release 11; QuantizationCallerRunsTest added and compiles.

Stats: 9 files, +934/−168.

Commits

• graph: convert GraphIndexBuilder to the ParallelExecutor seam
• quantization: accept ParallelExecutor for PQ/NVQ/BQ encode
• graph: EmbeddedExecutionContext as the single execution carrier
• docs: illustrate the compactor's calling-convention conversion

[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.