Refinement

A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass:

const pool = index.on(executor);
pool.insert(keys, vectors, { expansionFactor: 32 });
while (pool.refine({ expansionFactor: 128 }).changed > vectors.rows / 100) {}

Each call answers a DenseRefineReport: the entries re-selected and changed, the islands found and reconnected, and the closing reachability audit.

Refinement is a build step rather than a repair. It adds and removes nothing, and searches may run throughout.

§ Absorbing & Splitting

Bigger indexes come from absorbing, never mutating: absorb appends every donor in turn, keeping its graph and linking it in across the appended part, and a donor the library consumed refuses every later verb with Status.Uninitialized. A donor it did not absorb, like one of another scalar refused with Status.ConfigMismatch, stays a live index you still own, though its entries may already have moved. A deferred absorb holds its donors until it is final, so meanwhile they refuse every verb and no other absorb can name them.

index.on(executor).absorb([shard]);

split is the inverse: it hands graph-local parts of the index to empty receivers of the same configuration, one part each, keeping their edges and leaving the index empty but live. Both answer the closing refines’ report, as refine does.

index.on(executor).split([left, right], { seed: 42 });