Refinement

It holds everything the pass needs between calls, so a cancelled usearch_dense_refinement_next continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during usearch_dense_refine. Each call names the index and the executor it was opened with.

It holds everything the pass needs between calls, so a cancelled usearch_geospatial_refinement_next continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during usearch_geospatial_refine. Each call names the index and the executor it was opened with.

It holds everything the pass needs between calls, so a cancelled usearch_sequence_refinement_next continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during usearch_sequence_refine. Each call names the index and the executor it was opened with.

It holds everything the pass needs between calls, so a cancelled usearch_shapes_refinement_next continues where it stopped, and nothing about it stays in the index once it finishes. The index admits no insertion and no save while the handle lives; searches proceed as during usearch_shapes_refine. Each call names the index and the executor it was opened with.

changed never exceeds reselected, and a pass over a settled graph changes nothing. A call that fails before its closing audit reports zeros; one its progress handler stopped still heals, so its report stands beside the usearch_status_cancelled_k it answers.

This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide refine.expansion_factor belongs here rather than in usearch_dense_insert.

Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting a node's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers usearch_status_cancelled_k. The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a usearch_dense_refinement_t instead. A caller loops until the report's changed falls below whatever change rate they consider settled.

Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the diversity judgment still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable.

On a RAM handle searches may run throughout: re-selection publishes one node at a time and never removes a node, so a concurrent walk sees either the old neighbors or the new ones. On a VRAM handle the merge writes neighbors in place, so searches may not overlap. Insertions never overlap: one in flight refuses the call with usearch_status_contended_k, and one arriving meanwhile is refused the same way, as is a VRAM save. A viewed handle refuses with usearch_status_read_only_k, like every other mutating verb.

This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide refine.expansion_factor belongs here rather than in usearch_geospatial_insert. A refined entry keeps its cone winners and the longest of its other candidates, then has its long links drawn again by the insertion's rule, so a refine never leaves an entry without them.

Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting an entry's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers usearch_status_cancelled_k. The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a usearch_geospatial_refinement_t instead.

Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the selection still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable.

Searches may run throughout: re-selection rewrites one entry at a time and never removes one, so a concurrent walk sees either the old neighbors or the new ones. Insertions never overlap: one in flight refuses the call with usearch_status_contended_k, and one arriving meanwhile is refused the same way, as is a save.

This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide refine.expansion_factor belongs here rather than in usearch_sequence_insert. It pays most in this modality, where a single alignment is quadratic and a stingy insertion pass is tempting.

Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting an entry's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers usearch_status_cancelled_k. The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a usearch_sequence_refinement_t instead.

Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the selection still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable.

Searches may run throughout: re-selection rewrites one entry at a time and never removes one, so a concurrent walk sees either the old neighbors or the new ones. Insertions never overlap: one in flight refuses the call with usearch_status_contended_k, and one arriving meanwhile is refused the same way, as is a save.

This is a build step rather than a repair. A cheap insertion pass followed by one refinement reaches a better graph, in less total time, than a single expensive insertion pass - so a wide refine.expansion_factor belongs here rather than in usearch_shapes_insert. It pays most in this modality, where one comparison scores a whole shape against another.

Cancelling is safe, which is what makes a whole-graph sweep affordable. Re-selecting an entry's neighbors is idempotent and claims no identity, so a stopped pass leaves the graph correct and merely less improved: nothing unwinds, and the call answers usearch_status_cancelled_k. The index keeps nothing of a stopped pass, so the next call starts at the first entry again; a caller wanting to continue where a cancel stopped holds a usearch_shapes_refinement_t instead.

Re-selection alone can leave an island, an entry no search reaches, so every call closes by re-linking them: unreachable entries re-select from scratch, and whatever the selection still drops is reconnected to a reachable one. A cancelled call skips the rest of the re-selection but still re-links, so it never leaves entries unreachable.

Searches may run throughout: re-selection rewrites one entry at a time and never removes one, so a concurrent walk sees either the old neighbors or the new ones. Insertions never overlap: one in flight refuses the call with usearch_status_contended_k, and one arriving meanwhile is refused the same way, as is a save.

Donor handles are consumed and must not be used afterwards, not even for usearch_dense_free.

The donors land one after another, each all-or-nothing: its entries append to index shard by shard with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every shard across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of a RAM index may keep searching throughout, since unpublished entries hide behind the watermark, while a VRAM one rewrites neighbors in place and admits no overlapping search, as refinement does. Insertions into index or into a donor arriving meanwhile are refused with usearch_status_contended_k, while searches of a donor run throughout.

A failure leaves the donor it struck and every later one as live handles the caller still owns and must free, and index holding the donors before it; every consumed slot is nulled, so the array itself says which handles survived. The handler reports and cancels the closing refinement alone, exactly as in usearch_dense_refine: a cancel skips the rest of the walks across, still re-links, and answers usearch_status_cancelled_k with every donor consumed. A caller wanting to continue those walks later holds a usearch_dense_refinement_t instead.

usearch_dense_index_t shards[4] = {built_on_socket_0, built_on_socket_1, built_on_socket_2, built_on_socket_3};
usearch_outcome_t outcome = {0};
usearch_dense_absorb(&(usearch_dense_absorb_t){
    .index = index, .executor = executor, .outcome = &outcome, .count = 4, .donors = shards,
    .progress = {report_to_terminal, &ui, 4}});
// Every entry of `shards` is consumed here; none of them may be freed afterwards.

The shard a bin keeps stays resident with its IDs, every other source shard follows it with its edges rebased and its keys beside it, and only the appended entries walk the target across the parts and link in, then each target shard re-links the islands that leaves, as usearch_dense_refine does. In place, a moved entry's key moves with one atomic store, so lookups and searches of target run throughout and emptied shards stay as idle slots for its next generation. Once the call moved every source, each one but target is freed and nulled, as usearch_dense_absorb frees its donors; a failure frees none, those it consumed left empty and refusing insertions, so every handle in sources stays the caller's to free.

Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from seed without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. A sharded handle splits shard by shard, part p of shard s moving into shard s of receiver p. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; index clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as usearch_dense_refine does. Meanwhile, insertions into index or a receiver are refused with usearch_status_contended_k, while searches of either run throughout.

The handler reports and cancels the closing refinements alone, exactly as in usearch_dense_refine: a cancel skips the rest of the re-selection, still re-links, and answers usearch_status_cancelled_k with every part moved. A caller wanting to continue that re-selection later holds a usearch_dense_refinement_t opened with receivers instead.

Every allocation the refinement needs happens here or in a move, never in a step.

Answers usearch_status_cancelled_k when a later call has more to do; that call continues exactly where this one stopped. The executor is held only for the call.

Every call reaching the refinement writes the running totals, a cancelled or failed one too, so they only grow from one call to the next and changed never exceeds reselected; all stay zero while donors are pending.

A refinement whose donors have not all moved re-links nothing and reports zeros.

A consumed donor handle must not be used afterwards, not even for usearch_geospatial_free.

Every donor is checked and held before the first one enters, so a refusal consumes none. The donors then enter one after another, each all-or-nothing: its entries append to index with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every entry across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of index may keep searching throughout, since unpublished entries hide behind the watermark, while nothing may search a donor. Insertions into index arriving meanwhile are refused with usearch_status_contended_k. A donor's terrain stays with it: the observations already carry the ground they were inserted over.

The handler reports and cancels the closing refinement alone, exactly as in usearch_geospatial_refine: a cancel skips the rest of the walks across, still re-links, and answers usearch_status_cancelled_k with every donor consumed. A caller wanting to continue those walks later holds a usearch_geospatial_refinement_t instead.

Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from seed without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; index clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as usearch_geospatial_refine does. Insertions into index or a receiver arriving meanwhile are refused with usearch_status_contended_k, and nothing may search either until the call is final. A receiver keeps its own terrain: the observations already carry the ground they were inserted over.

The handler reports and cancels the closing refinements alone, exactly as in usearch_geospatial_refine: a cancel skips the rest of the re-selection, still re-links, and answers usearch_status_cancelled_k with every part moved. A caller wanting to continue that re-selection later holds a usearch_geospatial_refinement_t opened with receivers instead.

Every allocation the refinement needs in the index happens here, never in a step.

A refinement whose donors have not all moved re-links nothing and reports zeros.

Donor handles are consumed and must not be used afterwards, not even for usearch_sequence_free.

Every donor is checked and held before the first one enters, so a refusal consumes none. The donors then enter one after another, each all-or-nothing: its entries append to index with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every entry across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of index may keep searching throughout, since unpublished entries hide behind the watermark, while nothing may search a donor. Insertions into index arriving meanwhile are refused with usearch_status_contended_k.

The handler reports and cancels the closing refinement alone, exactly as in usearch_sequence_refine: a cancel skips the rest of the walks across, still re-links, and answers usearch_status_cancelled_k with every donor consumed. A caller wanting to continue those walks later holds a usearch_sequence_refinement_t instead.

Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from seed without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; index clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as usearch_sequence_refine does. Insertions into index or a receiver arriving meanwhile are refused with usearch_status_contended_k, and nothing may search either until the call is final.

The handler reports and cancels the closing refinements alone, exactly as in usearch_sequence_refine: a cancel skips the rest of the re-selection, still re-links, and answers usearch_status_cancelled_k with every part moved. A caller wanting to continue that re-selection later holds a usearch_sequence_refinement_t opened with receivers instead.

Every allocation the refinement needs in the index happens here, never in a step.

A refinement whose donors have not all moved re-links nothing and reports zeros.

Donor handles are consumed and must not be used afterwards, not even for usearch_shapes_free.

Every donor is checked and held before the first one enters, so a refusal consumes none. The donors then enter one after another, each all-or-nothing: its entries append to index with their edges rebased, publish at once, and the donor is consumed, so at most one donor's entries are ever held twice. One refinement then walks every entry across the parts the donors appended, round by round, so a group of donors costs one refinement rather than one per donor. Readers of index may keep searching throughout, since unpublished entries hide behind the watermark, while nothing may search a donor. Insertions into index arriving meanwhile are refused with usearch_status_contended_k.

The handler reports and cancels the closing refinement alone, exactly as in usearch_shapes_refine: a cancel skips the rest of the walks across, still re-links, and answers usearch_status_cancelled_k with every donor consumed. A caller wanting to continue those walks later holds a usearch_shapes_refinement_t instead.

Every receiver is checked and held before the first part moves, so a refusal moves nothing. The part roots are drawn from seed without a scan, and each part grows breadth-first over the links from its root, capped at an equal share of the entries, while entries no root reaches enter the smallest part. Each part then enters its receiver all-or-nothing, its edges rebased, its edges into other parts dropped, and the entries that lost one placed first; index clears once every part moved. Each receiver closes by re-selecting the entries that lost an edge and re-linking the islands that leaves, as usearch_shapes_refine does. Insertions into index or a receiver arriving meanwhile are refused with usearch_status_contended_k, and nothing may search either until the call is final.

The handler reports and cancels the closing refinements alone, exactly as in usearch_shapes_refine: a cancel skips the rest of the re-selection, still re-links, and answers usearch_status_cancelled_k with every part moved. A caller wanting to continue that re-selection later holds a usearch_shapes_refinement_t opened with receivers instead.

Every allocation the refinement needs in the index happens here, never in a step.

A refinement whose donors have not all moved re-links nothing and reports zeros.