@delali/narsil-react-native 0.0.0-stage → 0.3.1-next.146

package/cpp/core/src/quantize.c

@@ -0,0 +1,226 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <math.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+#define OSQ_LAMBDA 0.1
+#define OSQ_REFINE_ROUNDS 5
+#define OSQ_REFINE_TOLERANCE 1e-8
+#define OSQ_GRID_ONE_BIT 0.798
+#define OSQ_GRID_TWO_BITS 1.493
+#define OSQ_GRID_FOUR_BITS 2.514
+#define OSQ_GRID_EIGHT_BITS 3.922
+#define NARROW_CODE_QUERY_BITS 4
+#define NIBBLE_CODE_BITS 4U
+#define ROUND_HALF_UP 0.5
+
+typedef struct {
+  const double *centred;
+  uint32_t dimension;
+  double steps;
+  double norm;
+} refinement;
+
+typedef struct {
+  double correction;
+  double total;
+  double minimum;
+  double maximum;
+} centred_summary;
+
+uint32_t code_bytes_of(uint32_t dimension, uint32_t bits) {
+  return ((dimension * bits) + (BITS_PER_BYTE - 1)) / BITS_PER_BYTE;
+}
+
+uint32_t narsil_record_bytes(uint32_t dimension, uint32_t bits) {
+  if (bits == 0) { return 0; }
+  return code_bytes_of(dimension, bits) + NARSIL_OSQ_TRAILER_BYTES;
+}
+
+uint32_t query_bits_of(uint32_t bits) { return bits == BITS_PER_BYTE ? BITS_PER_BYTE : NARROW_CODE_QUERY_BITS; }
+
+static double steps_of(uint32_t bits) { return (double)((1U << bits) - 1); }
+
+static double grid_of(uint32_t bits) {
+  switch (bits) {
+    case 1:
+      return OSQ_GRID_ONE_BIT;
+    case 2:
+      return OSQ_GRID_TWO_BITS;
+    case 4:
+      return OSQ_GRID_FOUR_BITS;
+    default:
+      return OSQ_GRID_EIGHT_BITS;
+  }
+}
+
+static double clamp(double value, level_range range) {
+  double raised = value > range.lower ? value : range.lower;
+  return raised < range.upper ? raised : range.upper;
+}
+
+static double level_of(double value, level_range range, double steps) {
+  if (range.upper == range.lower) { return 0; }
+  return floor((((clamp(value, range) - range.lower) * steps) / (range.upper - range.lower)) + ROUND_HALF_UP);
+}
+
+static double loss_of(const refinement *problem, level_range range) {
+  const double *centred = problem->centred;
+  double projected_error = 0;
+  double squared_error = 0;
+  double width = (range.upper - range.lower) / problem->steps;
+  for (uint32_t i = 0; i < problem->dimension; i++) {
+    double reconstructed = range.lower + (width * level_of(centred[i], range, problem->steps));
+    projected_error += centred[i] * (centred[i] - reconstructed);
+    squared_error += (centred[i] - reconstructed) * (centred[i] - reconstructed);
+  }
+  return (((1 - OSQ_LAMBDA) * projected_error * projected_error) / problem->norm) + (OSQ_LAMBDA * squared_error);
+}
+
+static level_range refine(refinement problem, level_range start) {
+  level_range range = start;
+  const double *centred = problem.centred;
+  for (uint32_t i = 0; i < problem.dimension; i++) { problem.norm += centred[i] * centred[i]; }
+  if (problem.norm == 0 || range.upper == range.lower) { return range; }
+  double best = loss_of(&problem, range);
+  for (int round = 0; round < OSQ_REFINE_ROUNDS; round++) {
+    double daa = 0;
+    double dab = 0;
+    double dbb = 0;
+    double dax = 0;
+    double dbx = 0;
+    for (uint32_t i = 0; i < problem.dimension; i++) {
+      double fraction = level_of(centred[i], range, problem.steps) / problem.steps;
+      daa += (1 - fraction) * (1 - fraction);
+      dab += (1 - fraction) * fraction;
+      dbb += fraction * fraction;
+      dax += centred[i] * (1 - fraction);
+      dbx += centred[i] * fraction;
+    }
+    double gram_aa = (((1 - OSQ_LAMBDA) * dax * dax) / problem.norm) + (OSQ_LAMBDA * daa);
+    double gram_ab = (((1 - OSQ_LAMBDA) * dax * dbx) / problem.norm) + (OSQ_LAMBDA * dab);
+    double gram_bb = (((1 - OSQ_LAMBDA) * dbx * dbx) / problem.norm) + (OSQ_LAMBDA * dbb);
+    double determinant = (gram_aa * gram_bb) - (gram_ab * gram_ab);
+    if (determinant == 0) { break; }
+    level_range next = {((gram_bb * dax) - (gram_ab * dbx)) / determinant,
+                        ((gram_aa * dbx) - (gram_ab * dax)) / determinant};
+    if (fabs(next.lower - range.lower) < OSQ_REFINE_TOLERANCE &&
+        fabs(next.upper - range.upper) < OSQ_REFINE_TOLERANCE) {
+      break;
+    }
+    double candidate = loss_of(&problem, next);
+    if (candidate > best) { break; }
+    range = next;
+    best = candidate;
+  }
+  return range;
+}
+
+void normalise_into(double *normalised, const float *vector, uint32_t dimension) {
+  double squares = 0;
+  for (uint32_t i = 0; i < dimension; i++) { squares += (double)vector[i] * (double)vector[i]; }
+  double length = sqrt(squares);
+  for (uint32_t i = 0; i < dimension; i++) {
+    normalised[i] = length == 0 ? (double)vector[i] : (double)vector[i] / length;
+  }
+}
+
+static centred_summary centre_into(const narsil_store *store, narsil_metric metric, const double *normalised,
+                                   double *centred) {
+  centred_summary summary = {0, 0, HUGE_VAL, -HUGE_VAL};
+  for (uint32_t i = 0; i < store->dimension; i++) {
+    double centre = (double)store->centroid[i];
+    centred[i] = normalised[i] - centre;
+    summary.correction += metric == NARSIL_METRIC_EUCLIDEAN ? centred[i] * centred[i] : normalised[i] * centre;
+    summary.total += centred[i];
+    if (centred[i] < summary.minimum) { summary.minimum = centred[i]; }
+    if (centred[i] > summary.maximum) { summary.maximum = centred[i]; }
+  }
+  return summary;
+}
+
+static level_range initial_range(const narsil_store *store, const double *centred, centred_summary summary,
+                                 uint32_t query_bits) {
+  uint32_t dimension = store->dimension;
+  double mean = summary.total / dimension;
+  double spread = 0;
+  for (uint32_t i = 0; i < dimension; i++) { spread += (centred[i] - mean) * (centred[i] - mean); }
+  double deviation = sqrt(spread / dimension);
+  level_range observed = {summary.minimum, summary.maximum};
+  level_range start = {clamp(mean - (grid_of(query_bits) * deviation), observed),
+                       clamp(mean + (grid_of(query_bits) * deviation), observed)};
+  refinement problem = {centred, dimension, steps_of(query_bits), 0};
+  return refine(problem, start);
+}
+
+static void fill_levels(const narsil_store *store, const double *centred, prepared_code *code) {
+  uint32_t dimension = store->dimension;
+  uint32_t document_bits = store->bits;
+  uint32_t per_byte = document_bits == 1 || document_bits == 2 ? BITS_PER_BYTE / document_bits : 0;
+  uint32_t plane_bytes = per_byte == 0 ? 0 : code_bytes_of(dimension, document_bits);
+  uint32_t pairs = (dimension + 1) / 2;
+  double steps = steps_of(code->bits);
+  memset(code->low_levels, 0, pairs);
+  memset(code->high_levels, 0, pairs);
+  memset(code->planes, 0, (size_t)QUERY_PLANES * plane_bytes);
+  double sum = 0;
+  for (uint32_t i = 0; i < dimension; i++) {
+    uint8_t level = (uint8_t)level_of(centred[i], code->range, steps);
+    code->levels[i] = level;
+    sum += level;
+    if ((i & 1) == 0) {
+      code->low_levels[i >> 1] = level;
+    } else {
+      code->high_levels[i >> 1] = level;
+    }
+    if (per_byte == 0 || level == 0) { continue; }
+    uint8_t bit = (uint8_t)(1U << ((i % per_byte) * document_bits));
+    for (uint32_t plane = 0; plane < QUERY_PLANES; plane++) {
+      if (((level >> plane) & 1) != 0) { code->planes[((size_t)plane * plane_bytes) + (i / per_byte)] |= bit; }
+    }
+  }
+  code->sum = sum;
+}
+
+void quantise_vector(narsil_workspace *workspace, const narsil_store *store, narsil_metric metric, const float *vector,
+                     uint32_t bits, quantised_vector *quantised) {
+  double *normalised = workspace->normalised;
+  double *centred = workspace->centred;
+  if (metric == NARSIL_METRIC_COSINE) {
+    normalise_into(normalised, vector, store->dimension);
+  } else {
+    for (uint32_t i = 0; i < store->dimension; i++) { normalised[i] = (double)vector[i]; }
+  }
+  centred_summary summary = centre_into(store, metric, normalised, centred);
+  quantised->range = initial_range(store, centred, summary, bits);
+  quantised->correction = summary.correction;
+  quantised->centred = centred;
+}
+
+double quantised_level(double value, level_range range, uint32_t bits) {
+  return level_of(value, range, steps_of(bits));
+}
+
+uint32_t placement_query_bits_of(uint32_t bits) {
+  return bits == NIBBLE_CODE_BITS ? BITS_PER_BYTE : query_bits_of(bits);
+}
+
+void prepare_code(narsil_workspace *workspace, const narsil_store *store, narsil_metric metric, const float *vector,
+                  prepared_code *code) {
+  prepare_code_with_bits(workspace, store, metric, vector, query_bits_of(store->bits), code);
+}
+
+void prepare_code_with_bits(narsil_workspace *workspace, const narsil_store *store, narsil_metric metric,
+                            const float *vector, uint32_t query_bits, prepared_code *code) {
+  quantised_vector quantised;
+  *code = workspace->code;
+  code->bits = query_bits;
+  quantise_vector(workspace, store, metric, vector, code->bits, &quantised);
+  code->range = quantised.range;
+  code->correction = quantised.correction;
+  fill_levels(store, quantised.centred, code);
+}

package/cpp/core/src/records.c

@@ -0,0 +1,97 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <stdatomic.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+static narsil_status begin_record_work(narsil_workspace *workspace, const narsil_store *store,
+                                       const narsil_ordinals_request *request) {
+  if (workspace == NULL || store == NULL || request == NULL) { return NARSIL_INVALID_ARGUMENT; }
+  if (request->count > 0 && request->ordinals == NULL) { return NARSIL_INVALID_ARGUMENT; }
+  if (!store_is_complete(store) || !is_metric(request->metric) || store->dimension == 0) {
+    return NARSIL_INVALID_ARGUMENT;
+  }
+  if (store->bits == 0 || !is_code_width(store->bits) || store->records_per_block == 0) {
+    return NARSIL_INVALID_ARGUMENT;
+  }
+  return workspace_reserve_dimension(workspace, store->dimension);
+}
+
+narsil_status narsil_measure(narsil_workspace *workspace, const narsil_store *store,
+                             const narsil_ordinals_request *request, double *totals) {
+  if (totals == NULL) { return NARSIL_INVALID_ARGUMENT; }
+  narsil_status status = begin_record_work(workspace, store, request);
+  if (status != NARSIL_OK) { return status; }
+  double squared_lengths = totals[store->dimension];
+  for (uint32_t i = 0; i < request->count; i++) {
+    const float *vector = stored_vector(store, request->ordinals[i], workspace->stored_vector);
+    if (vector == NULL) { continue; }
+    if (request->metric == NARSIL_METRIC_COSINE) {
+      normalise_into(workspace->normalised, vector, store->dimension);
+      for (uint32_t axis = 0; axis < store->dimension; axis++) {
+        totals[axis] += workspace->normalised[axis];
+        squared_lengths += workspace->normalised[axis] * workspace->normalised[axis];
+      }
+    } else {
+      for (uint32_t axis = 0; axis < store->dimension; axis++) {
+        double value = (double)vector[axis];
+        totals[axis] += value;
+        squared_lengths += value * value;
+      }
+    }
+    totals[store->dimension + 1] += 1;
+  }
+  totals[store->dimension] = squared_lengths;
+  return NARSIL_OK;
+}
+
+static uint32_t pack_levels(const narsil_store *store, const quantised_vector *quantised, uint8_t *record) {
+  uint32_t bits = store->bits;
+  uint32_t per_byte = BITS_PER_BYTE / bits;
+  uint32_t sum = 0;
+  memset(record, 0, code_bytes_of(store->dimension, bits));
+  for (uint32_t i = 0; i < store->dimension; i++) {
+    uint32_t level = (uint32_t)quantised_level(quantised->centred[i], quantised->range, bits);
+    sum += level;
+    record[i / per_byte] |= (uint8_t)(level << ((i % per_byte) * bits));
+  }
+  return sum;
+}
+
+static void write_record(const narsil_store *store, const quantised_vector *quantised, uint8_t *record) {
+  uint32_t sum = pack_levels(store, quantised, record);
+  uint8_t *trailer = record + code_bytes_of(store->dimension, store->bits);
+  float lower = (float)quantised->range.lower;
+  float upper = (float)quantised->range.upper;
+  float correction = (float)quantised->correction;
+  memcpy(trailer + TRAILER_LOWER, &lower, sizeof lower);
+  memcpy(trailer + TRAILER_UPPER, &upper, sizeof upper);
+  memcpy(trailer + TRAILER_CORRECTION, &correction, sizeof correction);
+  memcpy(trailer + TRAILER_SUM, &sum, sizeof sum);
+}
+
+narsil_status narsil_quantise(narsil_workspace *workspace, const narsil_store *store,
+                              const narsil_ordinals_request *request) {
+  narsil_status status = begin_record_work(workspace, store, request);
+  if (status != NARSIL_OK) { return status; }
+  if (load_word(store->header, NARSIL_STORE_WORD_CALIBRATED) != 1) { return NARSIL_INVALID_ARGUMENT; }
+  for (uint32_t i = 0; i < request->count; i++) {
+    int32_t ordinal = request->ordinals[i];
+    const float *vector = stored_vector(store, ordinal, workspace->stored_vector);
+    uint8_t *record = stored_record(store, ordinal);
+    if (vector == NULL) { continue; }
+    if (record == NULL) { return NARSIL_NEEDS_ROOM; }
+    quantised_vector quantised;
+    quantise_vector(workspace, store, (narsil_metric)request->metric, vector, store->bits, &quantised);
+    write_record(store, &quantised, record);
+    _Atomic(uint8_t) *holds_a_record = atomic_byte(store->code_present, (uint32_t)ordinal);
+    if (atomic_load(holds_a_record) == 0) {
+      atomic_fetch_add(atomic_word(store->header, NARSIL_STORE_WORD_CODE_COUNT), 1);
+      atomic_store(holds_a_record, 1);
+    }
+  }
+  return NARSIL_OK;
+}

package/cpp/core/src/remove.c

@@ -0,0 +1,205 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <math.h>
+#include <stdatomic.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+static void begin_graph_write(walk_context *context, const narsil_graph *graph, uint32_t thread_slot) {
+  memset(context, 0, sizeof *context);
+  context->graph = graph;
+  context->thread_slot = thread_slot;
+  int32_t slots = load_word(graph->header, NARSIL_GRAPH_WORD_SLOTS);
+  context->slots = slots < 0 ? 0 : (uint32_t)slots;
+}
+
+narsil_status narsil_remove(const narsil_graph *graph, const narsil_remove_request *request) {
+  if (graph == NULL || request == NULL || !graph_is_complete(graph) || request->thread_slot >= graph->thread_slots) {
+    return NARSIL_INVALID_ARGUMENT;
+  }
+  int32_t ordinal = request->ordinal;
+  graph_lock_shared(graph, request->thread_slot);
+  walk_context context;
+  begin_graph_write(&context, graph, request->thread_slot);
+  narsil_status status = NARSIL_OK;
+  if (ordinal < 0 || (uint32_t)ordinal >= context.slots) {
+    status = NARSIL_INVALID_ARGUMENT;
+  } else if (node_top_layer(&context, ordinal) >= 0) {
+    uint8_t live = 0;
+    if (atomic_compare_exchange_strong(atomic_byte(graph->tombstones, (uint32_t)ordinal), &live, 1)) {
+      atomic_fetch_add(atomic_word(graph->header, NARSIL_GRAPH_WORD_TOMBSTONE_COUNT), 1);
+    }
+  }
+  graph_unlock_shared(graph, request->thread_slot);
+  return status;
+}
+
+static uint32_t copy_list(const walk_context *context, node_layer position, int32_t *out) {
+  uint32_t capacity = 0;
+  const int32_t *list = list_at(context, position, &capacity);
+  if (list == NULL || list[0] < 0) { return 0; }
+  uint32_t count = (uint32_t)list[0] > capacity ? capacity : (uint32_t)list[0];
+  memcpy(out, list + 1, (size_t)count * sizeof *out);
+  return count;
+}
+
+static void offer(const walk_context *context, int32_t node, int32_t candidate) {
+  scored_list *candidates = &context->workspace->repair_candidates;
+  for (uint32_t i = 0; i < candidates->count; i++) {
+    if (candidates->ordinals[i] == candidate) { return; }
+  }
+  candidates->ordinals[candidates->count] = candidate;
+  candidates->distances[candidates->count] = pair_distance(context, node, candidate);
+  candidates->count += 1;
+}
+
+static void drop_unreachable_candidates(const walk_context *context, node_layer position, held_links held) {
+  scored_list *candidates = &context->workspace->repair_candidates;
+  uint32_t kept = 0;
+  for (uint32_t i = 0; i < candidates->count; i++) {
+    if (candidates->distances[i] == HUGE_VAL) {
+      if (position.layer == 0 && list_holds(held, candidates->ordinals[i])) {
+        note_unlinked(context, candidates->ordinals[i]);
+      }
+      continue;
+    }
+    candidates->ordinals[kept] = candidates->ordinals[i];
+    candidates->distances[kept] = candidates->distances[i];
+    kept += 1;
+  }
+  candidates->count = kept;
+}
+
+static int leaves_with_this_compaction(const walk_context *context, int32_t ordinal) {
+  return node_top_layer(context, ordinal) < 0 || is_tombstoned(context, ordinal);
+}
+
+static held_links gather_repair_candidates(const walk_context *context, node_layer position, removed_node removed) {
+  narsil_workspace *workspace = context->workspace;
+  workspace->repair_candidates.count = 0;
+  held_links held = {workspace->neighbours, copy_list(context, position, workspace->neighbours), 0};
+  for (uint32_t i = 0; i < held.count; i++) { offer(context, position.ordinal, workspace->neighbours[i]); }
+  for (uint32_t i = 0; i < removed.former_count; i++) {
+    int32_t other = workspace->former[i];
+    if (other == position.ordinal || other == removed.ordinal || leaves_with_this_compaction(context, other)) {
+      continue;
+    }
+    offer(context, position.ordinal, other);
+  }
+  drop_unreachable_candidates(context, position, held);
+  return held;
+}
+
+static void relink(const walk_context *context, node_layer position, uint32_t selected) {
+  const narsil_workspace *workspace = context->workspace;
+  for (uint32_t i = 0; i < selected; i++) {
+    node_layer other = {workspace->repaired[i], position.layer};
+    if (position.layer > node_top_layer(context, other.ordinal)) { continue; }
+    node_lock(context, other.ordinal);
+    list_add(context, other, position.ordinal);
+    list_prune(context, other);
+    node_unlock(context, other.ordinal);
+  }
+}
+
+static void repair_neighbour(const walk_context *context, node_layer position, removed_node removed) {
+  narsil_workspace *workspace = context->workspace;
+  uint32_t limit = list_limit(context->graph, position.layer);
+  uint32_t capacity = 0;
+  const int32_t *list = list_at(context, position, &capacity);
+  if (list == NULL || list[0] >= (int32_t)limit) { return; }
+  held_links held = gather_repair_candidates(context, position, removed);
+  uint32_t selected = select_neighbours(context, &workspace->repair_candidates, limit, workspace->repaired);
+  node_lock(context, position.ordinal);
+  if (position.layer == 0) {
+    selected = write_keeping_last_links(context, position.ordinal, &workspace->repair_candidates, workspace->repaired,
+                                        selected, held);
+  } else {
+    list_replace(context, position, workspace->repaired, selected);
+  }
+  node_unlock(context, position.ordinal);
+  relink(context, position, selected);
+}
+
+static void unlink_layer(const walk_context *context, node_layer layer_of_the_removed) {
+  narsil_workspace *workspace = context->workspace;
+  int32_t layer = layer_of_the_removed.layer;
+  removed_node removed = {layer_of_the_removed.ordinal, copy_list(context, layer_of_the_removed, workspace->former)};
+  for (uint32_t i = 0; i < removed.former_count; i++) {
+    node_layer position = {workspace->former[i], layer};
+    if (layer > node_top_layer(context, position.ordinal)) { continue; }
+    node_lock(context, position.ordinal);
+    list_take_out(context, position, removed.ordinal);
+    node_unlock(context, position.ordinal);
+  }
+  for (uint32_t i = 0; i < removed.former_count; i++) {
+    node_layer position = {workspace->former[i], layer};
+    if (layer > node_top_layer(context, position.ordinal)) { continue; }
+    repair_neighbour(context, position, removed);
+  }
+}
+
+static void move_entry_after_removal(const walk_context *context, int32_t removed) {
+  if (load_word(context->graph->header, NARSIL_GRAPH_WORD_ENTRY_POINT) != removed) { return; }
+  entry_lock(context);
+  int32_t next = NO_NODE;
+  if (load_word(context->graph->header, NARSIL_GRAPH_WORD_NODE_COUNT) > 0) {
+    next = highest_node(context, 0);
+    if (next == NO_NODE) { next = highest_node(context, 1); }
+  }
+  store_entry_point(context, next);
+  entry_unlock(context);
+}
+
+static void take_node_out(const walk_context *context, int32_t ordinal) {
+  const narsil_graph *graph = context->graph;
+  int32_t top_layer = node_top_layer(context, ordinal);
+  for (int32_t layer = 0; layer <= top_layer; layer++) {
+    node_layer removed = {ordinal, layer};
+    unlink_layer(context, removed);
+  }
+  int32_t *former_base = context->workspace->former;
+  node_layer base = {ordinal, 0};
+  uint32_t former_base_count = copy_list(context, base, former_base);
+  for (uint32_t i = 0; i < former_base_count; i++) { note_unlinked(context, former_base[i]); }
+  node_lock(context, ordinal);
+  atomic_store(atomic_byte(graph->node_levels, (uint32_t)ordinal), 0);
+  graph->upper_base[ordinal] = 0;
+  graph->level0[(size_t)ordinal * ((size_t)list_limit(graph, 0) + NARSIL_LIST_WORDS_OVER_NEIGHBOURS)] = 0;
+  atomic_store(atomic_word(graph->incoming, (uint32_t)ordinal), 0);
+  atomic_store(atomic_byte(graph->nearest_link_due, (uint32_t)ordinal), 0);
+  node_unlock(context, ordinal);
+  atomic_fetch_sub(atomic_word(graph->header, NARSIL_GRAPH_WORD_NODE_COUNT), 1);
+  uint8_t tombstoned = 1;
+  if (atomic_compare_exchange_strong(atomic_byte(graph->tombstones, (uint32_t)ordinal), &tombstoned, 0)) {
+    atomic_fetch_sub(atomic_word(graph->header, NARSIL_GRAPH_WORD_TOMBSTONE_COUNT), 1);
+  }
+  move_entry_after_removal(context, ordinal);
+}
+
+narsil_status narsil_compact(narsil_workspace *workspace, const narsil_graph *graph, const narsil_store *store,
+                             const narsil_compact_request *request) {
+  if (request == NULL) { return NARSIL_INVALID_ARGUMENT; }
+  walk_context context;
+  narsil_status status = begin_walk(&context, workspace, graph, store, request->metric);
+  if (status != NARSIL_OK) { return status; }
+  if (request->thread_slot >= graph->thread_slots) { return NARSIL_INVALID_ARGUMENT; }
+  if (load_word(graph->header, NARSIL_GRAPH_WORD_LOCK) != NARSIL_GRAPH_HELD_ALONE) {
+    return NARSIL_GRAPH_NOT_HELD_ALONE;
+  }
+  context.thread_slot = request->thread_slot;
+  status = read_graph_extent(&context);
+  if (status == NARSIL_OK) { status = list_reserve(&workspace->repair_candidates, MAX_REPAIR_CANDIDATES); }
+  if (status == NARSIL_OK) { status = list_reserve(&workspace->link_candidates, MAX_NEIGHBOURS_PER_LIST); }
+  if (status == NARSIL_OK) { status = reserve_last_links(workspace); }
+  if (status != NARSIL_OK) { return status; }
+  if (load_word(graph->header, NARSIL_GRAPH_WORD_TOMBSTONE_COUNT) == 0) { return NARSIL_OK; }
+  for (uint32_t ordinal = 0; ordinal < context.slots; ordinal++) {
+    if (node_top_layer(&context, (int32_t)ordinal) < 0 || !is_tombstoned(&context, (int32_t)ordinal)) { continue; }
+    take_node_out(&context, (int32_t)ordinal);
+  }
+  return NARSIL_OK;
+}

package/cpp/core/src/vectors.c

@@ -0,0 +1,139 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <math.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+#define CACHE_LINE_BYTES 64
+#define PREFETCH_FOR_READ 0
+#define PREFETCH_KEEP_IN_ALL_CACHES 3
+
+int is_metric(uint32_t metric) {
+  return metric == NARSIL_METRIC_COSINE || metric == NARSIL_METRIC_DOT_PRODUCT || metric == NARSIL_METRIC_EUCLIDEAN;
+}
+
+int is_code_width(uint32_t bits) {
+  switch (bits) {
+    case 0:
+    case 1:
+    case 2:
+    case 4:
+    case BITS_PER_BYTE:
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+int store_is_complete(const narsil_store *store) {
+  return store->header != NULL && store->code_present != NULL && store->centroid != NULL && store->magnitudes != NULL &&
+         store->present != NULL && (store->code_block_count == 0 || store->code_blocks != NULL) &&
+         (store->vector_block_count == 0 || store->vector_blocks != NULL) &&
+         (store->file_count == 0 ||
+          (store->files != NULL && store->vector_file != NULL && store->vector_offset != NULL));
+}
+
+static int holds_a_live_vector(const narsil_store *store, int32_t ordinal) {
+  if (ordinal < 0) { return 0; }
+  if ((uint32_t)ordinal >= (uint32_t)load_word(store->header, NARSIL_STORE_WORD_SLOTS)) { return 0; }
+  return store->present[ordinal] == 1;
+}
+
+static const float *vector_in_a_file(const narsil_store *store, int32_t ordinal, float *scratch) {
+  uint32_t position = (uint32_t)store->vector_file[ordinal];
+  if (position >= store->file_count) { return NULL; }
+  const narsil_vector_file *file = &store->files[position];
+  uint64_t offset = store->vector_offset[ordinal];
+  uint64_t bytes = (uint64_t)store->dimension * sizeof(float);
+  if (file->bytes == NULL || offset + bytes > file->length) { return NULL; }
+  memcpy(scratch, file->bytes + offset, (size_t)bytes);
+  return scratch;
+}
+
+static const float *vector_in_a_block(const narsil_store *store, int32_t ordinal) {
+  if (store->vectors_per_block == 0) { return NULL; }
+  uint32_t block = (uint32_t)ordinal / store->vectors_per_block;
+  if (block >= store->vector_block_count || store->vector_blocks[block] == NULL) { return NULL; }
+  size_t entry = (size_t)((uint32_t)ordinal % store->vectors_per_block);
+  return store->vector_blocks[block] + (entry * store->vector_stride_floats);
+}
+
+const float *stored_vector(const narsil_store *store, int32_t ordinal, float *scratch) {
+  if (!holds_a_live_vector(store, ordinal)) { return NULL; }
+  if (store->vector_file != NULL && store->vector_file[ordinal] >= 0) {
+    return vector_in_a_file(store, ordinal, scratch);
+  }
+  return vector_in_a_block(store, ordinal);
+}
+
+uint8_t *stored_record(const narsil_store *store, int32_t ordinal) {
+  if (ordinal < 0 || store->records_per_block == 0 || store->bits == 0) { return NULL; }
+  if ((uint32_t)ordinal >= (uint32_t)load_word(store->header, NARSIL_STORE_WORD_SLOTS)) { return NULL; }
+  uint32_t block = (uint32_t)ordinal / store->records_per_block;
+  if (block >= store->code_block_count || store->code_blocks[block] == NULL) { return NULL; }
+  size_t entry = (size_t)((uint32_t)ordinal % store->records_per_block);
+  return store->code_blocks[block] + (entry * narsil_record_bytes(store->dimension, store->bits));
+}
+
+static double metric_distance(const walk_context *context, float_query query, const float *vector, double magnitude) {
+  uint32_t dimension = context->store->dimension;
+  if (context->metric == NARSIL_METRIC_EUCLIDEAN) {
+    return sqrt((double)kernel_squared_distance(query.values, vector, dimension));
+  }
+  double dot = (double)kernel_dot(query.values, vector, dimension);
+  if (context->metric == NARSIL_METRIC_DOT_PRODUCT) { return -dot; }
+  if (query.magnitude == 0 || magnitude == 0) { return 1; }
+  return 1 - (dot / (query.magnitude * magnitude));
+}
+
+double float_distance(const walk_context *context, float_query query, int32_t ordinal) {
+  const float *vector = stored_vector(context->store, ordinal, context->workspace->stored_vector);
+  if (vector == NULL) { return HUGE_VAL; }
+  return metric_distance(context, query, vector, context->store->magnitudes[ordinal]);
+}
+
+static double vector_pair_distance(const walk_context *context, int32_t first, int32_t second) {
+  const narsil_store *store = context->store;
+  const float *first_vector = stored_vector(store, first, context->workspace->other_vector);
+  if (first_vector == NULL) { return HUGE_VAL; }
+  float_query query = {first_vector, store->magnitudes[first]};
+  return float_distance(context, query, second);
+}
+
+double pair_distance(const walk_context *context, int32_t first, int32_t second) {
+  if (context->pairs_use_codes) {
+    const narsil_store *store = context->store;
+    const uint8_t *first_record = stored_record(store, first);
+    const uint8_t *second_record = stored_record(store, second);
+    if (first_record != NULL && second_record != NULL && store->code_present[first] == 1 &&
+        store->code_present[second] == 1) {
+      return estimate_pair_distance(context, first_record, second_record);
+    }
+  }
+  return vector_pair_distance(context, first, second);
+}
+
+void prefetch_for_walk(const walk_context *context, int32_t ordinal) {
+#if defined(__GNUC__) || defined(__clang__)
+  const uint8_t *bytes = NULL;
+  size_t length = 0;
+  if (context->uses_codes) {
+    bytes = stored_record(context->store, ordinal);
+    length = context->record_bytes;
+  } else if (context->store->file_count == 0 && ordinal >= 0 && (uint32_t)ordinal < context->store_slots) {
+    bytes = (const uint8_t *)vector_in_a_block(context->store, ordinal);
+    length = (size_t)context->store->dimension * sizeof(float);
+  }
+  if (bytes == NULL || length == 0) { return; }
+  for (size_t at = 0; at < length; at += CACHE_LINE_BYTES) {
+    __builtin_prefetch(bytes + at, PREFETCH_FOR_READ, PREFETCH_KEEP_IN_ALL_CACHES);
+  }
+  __builtin_prefetch(bytes + length - 1, PREFETCH_FOR_READ, PREFETCH_KEEP_IN_ALL_CACHES);
+#else
+  (void)context;
+  (void)ordinal;
+#endif
+}