runtime: publish the vector index instead of guarding it

The crash (SIGTRAP in engram_activate -> eg_vindex_sync -> vindex_insert -> _realloc) had three read paths mutating five process-global statics. engram_activate, eg_knn_for_node (whose own comment says "No writes.") and engram_geo_reify_run_json all called eg_vindex_sync, which frees the index, reallocs the seen-map and inserts — on a read. Three moves, in decreasing order of how much they dissolve: 1. Misfiled scratch is not shared state. visited/visit_epoch/visited_cap were never owned by the index; they are one traversal's local, hoisted into struct VIndex as an allocation optimisation. They want neither a lock nor a capability nor a pool — just to go back in the call frame. Two concurrent READS stomped each other purely because of this. 2. const IS the capability. Once the scratch leaves the struct, search reads and nothing else, so vindex_search takes a const VIndex*. That is exactly what a capability-pointer ABI would have bought — a read path physically cannot call vindex_insert, enforced by the compiler on every future caller — for one qualifier instead of an ABI swept across hundreds of builtins. 3. What survives is publication, not ownership. HNSW insert is NOT an append: it rewires the neighbour links of already-existing elements and reallocs elems[], so the store's append-only property does not transfer to the index derived from it. eg_vindex_sync therefore splits into eg_vindex_maintain (exclusive, sole mutator) and eg_vindex_view (shared, returns const VIndex*). A read path may demand that a current snapshot exist — a request to the owner, not a mutation by the reader. Write-side owner: eg_vindex_note_embedded hooks the embedding-ASSIGNMENT sites rather than the append sites, because a node with no embedding cannot be in a vector index — embedding assignment is the event that owns index membership. One O(log n) insert, no O(node_count) presence scan. This also retires the "STALENESS (honest tradeoff)" note where a lazily-embedded older node stayed invisible to route_nearest/autoconnect until a full rebuild (the embed-gap #20 shape). Evidence. The existing harness conflated two hazards, which is why fixing half of it read as failure. Split into four: single (3000 vec, ASan+UBSan) clean -> clean readers (4 readers, no writer, TSan) RACE -> clean unsynchronized (writer+reader, bare) race -> race, expected forever published (owner + 4 readers) n/a -> clean, 3000/3000 landed RESULT: PASS. recall@10 = 0.9365 at ef_search=128 (gate >= 0.90); determinism byte-identical across two independent builds. The unsynchronized half is now permanently expected to race, deliberately: it is the executable proof that the boundary must live above the data structure, not inside it. fb32d15's guard is KEPT, correcting this design's own section 5. Measured, it guards TWO structures and only one was converted here: g->nodes/g->edges are realloc'd in place (el_runtime.c:7618,7629) and engram_activate_inner's embed-backfill writes n->emb through exactly such a borrowed pointer. Deleting the guard reintroduces a measured 11171->9579 edge loss. Its comment is narrowed to the RAM graph and the deletion precondition named. That corrects the ordering claim too: the residual is not one ABI that dissolves everything at once, it is a PROPERTY applied per structure. Residues evaporate in the order the property is applied, and a residue whose structure has not been converted must be left standing.
2026-08-16 11:29:12 -05:00
parent e99a4640e2
commit 8e9d88fc01
8 changed files with 609 additions and 112 deletions
@@ -1627,7 +1627,21 @@ static pthread_mutex_t g_engram_req_lock = PTHREAD_MUTEX_INITIALIZER;
 * inside an http_worker that already holds it (depth > 0) is a no-op, so there is
 * no self-deadlock on this NON-recursive mutex. Depth is a plain counter, never a
 * recursive-mutex count, which preserves engram_self_reify_beat_json's contract of
- * really releasing the lock mid-beat (see engram_req_unlock at the reify beat). */
+ * really releasing the lock mid-beat (see engram_req_unlock at the reify beat).
+ *
+ * SCOPE NARROWED (2026-08-16, vindex publication boundary): this guard originally
+ * covered TWO hazards — the RAM graph AND the process-global _eg_vindex. The vindex
+ * half is retired: the index now has its own publication boundary (_eg_vindex_rw),
+ * search takes a `const VIndex*`, and no read path can mutate the index at all.
+ *
+ * What REMAINS load-bearing here is the RAM graph alone, and it is a genuine,
+ * measured hazard independent of the index: g->nodes / g->edges are realloc'd in
+ * place (el_runtime.c:7618, 7629), so an awareness-thread reader holding
+ * `EngramNode* n = &g->nodes[i]` across a concurrent append from an http_worker
+ * holds a dangling pointer — and engram_activate_inner's embed-backfill WRITES
+ * n->emb through exactly such a pointer. That is a separate residue with its own
+ * fix (the resident graph wants the same publication treatment the index just got);
+ * until it lands, this guard stays. Do NOT delete it as "the fb32d15 vindex lock". */
 static __thread int _eg_req_depth = 0;
 void engram_req_unlock(void){ if(_eg_req_depth > 0) _eg_req_depth--; pthread_mutex_unlock(&g_engram_req_lock); }
 void engram_req_lock(void){ pthread_mutex_lock(&g_engram_req_lock); _eg_req_depth++; }
@@ -9606,6 +9620,35 @@ static double engram_goal_bias(const EngramNode* n, const char* query) {
 * the exact O(n) argmax scan tops up any seed slot the ANN leaves unfilled.
 * Single-threaded, matching the adjacent query-embedding cache (no lock).
 * Returns NULL when no index is available → caller falls back to the O(n) scan. */
+/* ── VINDEX PUBLICATION BOUNDARY (2026-08-16) ────────────────────────────────
+ * The index is DERIVED GEOMETRY: a projection of the store's embeddings. The
+ * store is append-only and superseding, so a reader must be able to project
+ * against geometry that does not move under it.
+ *
+ * The HNSW index is NOT itself append-only: vindex_insert rewires the neighbour
+ * lists of ALREADY-EXISTING elements and reallocs elems[]. So "extend" is a
+ * mutation of the whole structure, and a reader holding element pointers across
+ * one is unsafe no matter how pure search itself is (measured: TSan reports the
+ * elems[] race even after the visited set moved to the call frame).
+ *
+ * Hence a publication boundary rather than an ownership discipline:
+ *
+ *   - eg_vindex_maintain() is the ONLY mutator of the five statics below. It
+ *     takes _eg_vindex_rw EXCLUSIVELY, so it never runs beside a reader.
+ *   - eg_vindex_view() hands back a `const VIndex*` with the boundary held for
+ *     READ. N readers project concurrently; none can mutate, because search
+ *     takes a const index and the compiler enforces it.
+ *
+ * A read path may DEMAND that a current snapshot exist — that is a request to
+ * the owner, not a mutation by the reader. What it may not do is mutate the
+ * geometry it is projecting against. eg_vindex_view/eg_vindex_maintain is
+ * exactly that split.
+ *
+ * Lock ordering: request-outer -> vindex -> store-inner. The vindex boundary is
+ * never held across a call that can re-enter eg_vindex_view/maintain (verified:
+ * the four read regions each acquire, search, release without nesting). */
+static pthread_rwlock_t _eg_vindex_rw = PTHREAD_RWLOCK_INITIALIZER;
+
 static VIndex*  _eg_vindex          = NULL;
 static int32_t  _eg_vindex_dim      = 0;
 static int64_t  _eg_vindex_built_nc = 0;   /* g->node_count at last (re)build */
@@ -9625,8 +9668,10 @@ static int eg_vindex_seen_ensure(int64_t need) {
    return 0;
 }

-static VIndex* eg_vindex_sync(EngramStore* g, int32_t dim) {
-    if (!g || dim <= 0) return _eg_vindex;
+/* THE OWNER. The only function that mutates _eg_vindex* — must be called with
+ * _eg_vindex_rw held EXCLUSIVELY (see eg_vindex_maintain, the sole caller). */
+static void eg_vindex_publish_locked(EngramStore* g, int32_t dim) {
+    if (!g || dim <= 0) return;
    /* Drop a stale index: embedder dim changed, or the resident array shrank
     * (indices may have been reused/reordered → cached node_ids unsafe). */
    if (_eg_vindex && (_eg_vindex_dim != dim || g->node_count < _eg_vindex_built_nc)) {
@@ -9636,8 +9681,8 @@ static VIndex* eg_vindex_sync(EngramStore* g, int32_t dim) {
    }
    if (!_eg_vindex) {
        VIndex* idx = vindex_create((int)dim, 0, 0);
-        if (!idx) return NULL;
-        if (eg_vindex_seen_ensure(g->node_count)) { vindex_free(idx); return NULL; }
+        if (!idx) return;
+        if (eg_vindex_seen_ensure(g->node_count)) { vindex_free(idx); return; }
        for (int64_t i = 0; i < g->node_count; i++) {
            EngramNode* n = &g->nodes[i];
            if (n->emb && n->emb_dim == dim && vindex_insert(idx, (uint64_t)i, n->emb) == 0)
@@ -9661,8 +9706,62 @@ static VIndex* eg_vindex_sync(EngramStore* g, int32_t dim) {
        }
        _eg_vindex_built_nc = g->node_count;
    }
+}
+
+/* Owner-mediated publish. Takes the boundary EXCLUSIVELY, so it can never run
+ * beside a reader. Cheap no-op when the published snapshot is already current. */
+static void eg_vindex_maintain(EngramStore* g, int32_t dim) {
+    if (!g || dim <= 0) return;
+    pthread_rwlock_wrlock(&_eg_vindex_rw);
+    eg_vindex_publish_locked(g, dim);
+    pthread_rwlock_unlock(&_eg_vindex_rw);
+}
+
+/* READ SIDE. Returns the published snapshot as an IMMUTABLE view, with the
+ * boundary held for READ — the caller MUST pair every call with exactly one
+ * eg_vindex_view_release(), on every path including error returns.
+ *
+ * The returned pointer is `const`: a read path physically cannot call
+ * vindex_insert on it. That is the compile-time constraint, and it is why this
+ * replaces eg_vindex_sync rather than wrapping it. May return NULL (no index
+ * available -> caller falls back to the exact O(n) scan); the boundary is still
+ * held and still must be released. */
+static const VIndex* eg_vindex_view(EngramStore* g, int32_t dim) {
+    if (g && dim > 0) {
+        /* Fast path: snapshot already current, take it read-only and go. */
+        pthread_rwlock_rdlock(&_eg_vindex_rw);
+        if (_eg_vindex && _eg_vindex_dim == dim && _eg_vindex_built_nc == g->node_count)
+            return _eg_vindex;
+        /* Stale or absent. Drop to no lock, ask the owner to publish, re-acquire.
+         * NEVER upgrade rdlock->wrlock in place: that self-deadlocks. */
+        pthread_rwlock_unlock(&_eg_vindex_rw);
+        eg_vindex_maintain(g, dim);
+    }
+    pthread_rwlock_rdlock(&_eg_vindex_rw);
    return _eg_vindex;
 }
+static void eg_vindex_view_release(void) {
+    pthread_rwlock_unlock(&_eg_vindex_rw);
+}
+
+/* WRITE-SIDE MAINTENANCE HOOK. Call after an embedding becomes present on a
+ * resident ordinal. A node without an embedding cannot be in a vector index at
+ * all, so embedding-assignment — not node append — is the event that owns index
+ * membership. Cheap: one O(log n) HNSW insert, no O(node_count) presence scan.
+ * A no-op before the first publish (the cold build picks the node up) and on a
+ * dim mismatch. */
+static void eg_vindex_note_embedded(EngramStore* g, int64_t ordinal) {
+    if (!g || ordinal < 0 || ordinal >= g->node_count) return;
+    EngramNode* n = &g->nodes[ordinal];
+    if (!n->emb || n->emb_dim <= 0) return;
+    pthread_rwlock_wrlock(&_eg_vindex_rw);
+    if (_eg_vindex && _eg_vindex_dim == n->emb_dim &&
+        eg_vindex_seen_ensure(g->node_count) == 0 && !_eg_vindex_seen[ordinal]) {
+        if (vindex_insert(_eg_vindex, (uint64_t)ordinal, n->emb) == 0)
+            _eg_vindex_seen[ordinal] = 1;
+    }
+    pthread_rwlock_unlock(&_eg_vindex_rw);
+}

 /* ── M9 GEOMETRY PRIMING (ENGRAM_GEOMETRY_PRIMING, default OFF) ──────────────
 * Opt-in wiring of the centered relational-neighborhood geometry (engram_geometry.c)
@@ -9812,6 +9911,12 @@ static el_val_t engram_activate_inner(el_val_t query, el_val_t depth) {
            float* v = eg_embed_fetch(n->content, &d);
            if (!v) break; /* embedder down / breaker open — stop this call */
            n->emb = v; n->emb_dim = d;
+            /* Write-side index maintenance: an embedding just became present on
+             * ordinal i, so the index's owner publishes it now. This is what
+             * retires the "STALENESS (honest tradeoff)" note above — a lazily
+             * embedded OLDER node no longer waits for a full rebuild to become
+             * visible to route_nearest / autoconnect. */
+            eg_vindex_note_embedded(g, i);
            backfilled++;
        }
    }
@@ -10010,7 +10115,9 @@ static el_val_t engram_activate_inner(el_val_t query, el_val_t depth) {
         * same budget as the exact scan's retry `guard` — so dedup/threshold
         * rejects still leave enough distinct seeds. */
        {
-            VIndex* vx = eg_vindex_sync(g, q_dim);
+            /* Immutable view: the boundary is held for READ across the whole
+             * search + harvest, and released at the end of this block. */
+            const VIndex* vx = eg_vindex_view(g, q_dim);
            if (vx && (int64_t)vindex_size(vx) >= ENGRAM_EMBED_SEED_K) {
                const float* seed_qv = e_eff ? e_eff : q_emb;
                int kreq = ENGRAM_EMBED_SEED_K * 8;
@@ -10054,6 +10161,7 @@ static el_val_t engram_activate_inner(el_val_t query, el_val_t depth) {
                }
                free(aid); free(ad);
            }
+            eg_vindex_view_release();
        }

        /* Exact O(n) argmax fallback / top-up (pre-M8 selection, verbatim).
@@ -10140,9 +10248,11 @@ static el_val_t engram_activate_inner(el_val_t query, el_val_t depth) {
                    char** vids = malloc((size_t)g->node_count * sizeof(char*));
                    if (gmean && vids) {
                        for (int64_t i = 0; i < g->node_count; i++) vids[i] = g->nodes[i].id;
+                        const VIndex* gvx = eg_vindex_view(g, q_dim);
                        geo = engram_geometry_descriptor(
-                            g_engram_store, _eg_vindex, vids, (int)g->node_count,
+                            g_engram_store, gvx, vids, (int)g->node_count,
                            seed_ids, (size_t)nsel, NULL, gmean);
+                        eg_vindex_view_release();
                    }
                    free(vids);
                    if (geo && geo->n_members > 0) {
@@ -13292,13 +13402,16 @@ static int eg_knn_for_node(EngramStore* g, int64_t self, int want, uint64_t* out
    if(self < 0 || self >= g->node_count) return 0;
    EngramNode* n = &g->nodes[self];
    if(!n->emb || n->emb_dim <= 0) return 0;
-    VIndex* vx = eg_vindex_sync(g, n->emb_dim);
-    if(!vx) return 0;
+    /* Immutable view held for READ across the search; the harvest below reads
+     * only g->nodes, so the boundary is released as soon as the search returns. */
+    const VIndex* vx = eg_vindex_view(g, n->emb_dim);
+    if(!vx){ eg_vindex_view_release(); return 0; }
    int K = want + 8;
    uint64_t* ids = (uint64_t*)malloc(sizeof(uint64_t)*(size_t)K);
    float* dist = (float*)malloc(sizeof(float)*(size_t)K);
-    if(!ids || !dist){ free(ids); free(dist); return 0; }
+    if(!ids || !dist){ eg_vindex_view_release(); free(ids); free(dist); return 0; }
    int m = vindex_search(vx, n->emb, K, 0, ids, dist);
+    eg_vindex_view_release();
    int c = 0;
    for(int j=0; j<m && c<want; j++){
        int64_t bi = (int64_t)ids[j];
@@ -13329,7 +13442,8 @@ el_val_t engram_autoconnect_node(el_val_t id_v, el_val_t k_v, el_val_t minsim_v)
    EngramNode* n = &g->nodes[self];
    if((!n->emb || n->emb_dim <= 0) && n->content && eg_embed_eligible(n)){
        int32_t d = 0; float* v = eg_embed_fetch(n->content, &d);
-        if(v && d > 0){ n->emb = v; n->emb_dim = d; if(engram_store_enabled()) eg_store_put_node(n); }
+        if(v && d > 0){ n->emb = v; n->emb_dim = d; if(engram_store_enabled()) eg_store_put_node(n);
+                        eg_vindex_note_embedded(g, self); }
        else free(v);
    }
    if(!n->emb || n->emb_dim <= 0){ jb_puts(&b, "{\"connected\":0,\"reason\":\"unembedded\"}"); return el_wrap_str(b.buf); }
@@ -13464,8 +13578,10 @@ static GeoDescriptor* eg_geo_build_desc(const char* csv) {
    char** vids = malloc((size_t)g->node_count * sizeof(char*));
    if (gmean && vids) {
        for (int64_t i = 0; i < g->node_count; i++) vids[i] = g->nodes[i].id;
-        geo = engram_geometry_descriptor(g_engram_store, _eg_vindex, vids, (int)g->node_count,
+        const VIndex* gvx = eg_vindex_view(g, dim);
+        geo = engram_geometry_descriptor(g_engram_store, gvx, vids, (int)g->node_count,
                                         (const char* const*)ids, (size_t)ns, NULL, gmean);
+        eg_vindex_view_release();
    }
    free(vids);
    for (int i = 0; i < ns; i++) free(ids[i]);
@@ -13502,12 +13618,16 @@ el_val_t engram_geo_reify_run_json(void){
    int32_t dim = 0;
    for(int64_t i = 0; i < g->node_count && dim == 0; i++)
        if(g->nodes[i].emb && g->nodes[i].emb_dim > 0) dim = g->nodes[i].emb_dim;
-    VIndex* vx = (dim > 0) ? eg_vindex_sync(g, dim) : NULL;
    char** vids = malloc((size_t)g->node_count * sizeof(char*));
    if(!vids) return eg_geo_err("reify oom");
    for(int64_t i = 0; i < g->node_count; i++) vids[i] = g->nodes[i].id;
+    /* Held for READ across the whole reify pass: it only searches the index.
+     * (The multi-second SELF-reify beat below builds a PRIVATE index instead and
+     * never touches this boundary at all.) */
+    const VIndex* vx = eg_vindex_view(g, dim);
    int persisted = engram_geo_reify_store(g_engram_store, vx, vids,
                                           (int)g->node_count, NULL);
+    eg_vindex_view_release();
    free(vids);
    int nested = 0;
    if(persisted >= 0){
@@ -14231,9 +14351,13 @@ el_val_t engram_neighbors_json(el_val_t node_id, el_val_t max_depth, el_val_t di
 }

 /* Public activation entry point. Serializes against the http_worker threads that
- * share g->nodes/g->edges and the global _eg_vindex — this is the guard the
- * awareness main thread (soul.el: awareness_run) was missing entirely. Nested
- * calls from a worker that already holds the lock pass straight through. */
+ * share g->nodes/g->edges — this is the guard the awareness main thread
+ * (soul.el: awareness_run) was missing entirely. Nested calls from a worker that
+ * already holds the lock pass straight through.
+ *
+ * It no longer guards _eg_vindex: the index has its own publication boundary
+ * (eg_vindex_view / eg_vindex_maintain) and search cannot mutate it. This guard is
+ * now about the RAM graph's realloc-in-place ONLY. See the note at eg_guard_enter. */
 el_val_t engram_activate(el_val_t query, el_val_t depth) {
    int owned = eg_guard_enter();
    el_val_t r = engram_activate_inner(query, depth);
@@ -15017,6 +15141,7 @@ el_val_t engram_embed_backfill(el_val_t count) {
        float* v = eg_embed_fetch(n->content, &d);
        if (!v) break; /* embedder down / breaker open — stop this call */
        n->emb = v; n->emb_dim = d;
+        eg_vindex_note_embedded(g, i);   /* write-side index maintenance */
        done++;
    }
    int64_t total = 0;
@@ -222,7 +222,7 @@ static double eff_w(double weight, double hebb){
 }

 GeoDescriptor* engram_geometry_descriptor(
-    EngramPagedStore* store, VIndex* vindex,
+    EngramPagedStore* store, const VIndex* vindex,
    char** vids, int n_vids,
    const char* const* seed_ids, size_t n_seeds,
    const GeoParams* params,
@@ -1401,7 +1401,7 @@ static double geo_weighted_degree(EngramPagedStore* st, const char* id, double e
    return deg;
 }

-int engram_geo_reify_store(EngramPagedStore* store, VIndex* vindex,
+int engram_geo_reify_store(EngramPagedStore* store, const VIndex* vindex,
                           char** vids, int n_vids,
                           const GeoReifyParams* params){
    if(!store) return -1;
@@ -150,7 +150,7 @@ void engram_geo_mean_free(GeoMeanCache* c);
 * Returns a malloc'd descriptor (free with engram_geo_free), or NULL on error
 * (no seeds resolvable, OOM). */
 GeoDescriptor* engram_geometry_descriptor(
-    EngramPagedStore* store, VIndex* vindex,
+    EngramPagedStore* store, const VIndex* vindex,
    char** vids, int n_vids,
    const char* const* seed_ids, size_t n_seeds,
    const GeoParams* params,
@@ -375,7 +375,7 @@ void engram_geo_reify_default_params(GeoReifyParams* p);
 * neighborhood (+ member edges), superseding any prior same-hub record with
 * provenance. Read-then-write over `store`. Returns #neighborhoods persisted, or <0.
 * Skips existing Neighborhood/GeoMeanFrame nodes when detecting (idempotent re-reify). */
-int engram_geo_reify_store(EngramPagedStore* store, VIndex* vindex,
+int engram_geo_reify_store(EngramPagedStore* store, const VIndex* vindex,
                           char** vids, int n_vids,
                           const GeoReifyParams* params);

@@ -74,11 +74,6 @@ struct VIndex {

    int      entry;         /* entry-point element index, -1 if empty */
    int      max_level;     /* current top layer */
-
-    /* scratch: version-stamped visited set (O(1) reset). */
-    uint32_t* visited;
-    uint32_t  visit_epoch;
-    size_t    visited_cap;
 };

 /* ── small helpers ────────────────────────────────────────────────────────── */
@@ -166,37 +161,63 @@ static Pair heap_pop(Heap* h, int is_max){
    return top;
 }

-/* ── visited set ──────────────────────────────────────────────────────────── */
-static int visited_ensure(VIndex* ix){
-    if (ix->visited_cap >= ix->cap && ix->visited) return 0;
-    size_t nc = ix->cap ? ix->cap : 16;
-    uint32_t* nv = (uint32_t*)realloc(ix->visited, nc*sizeof(uint32_t));
-    if (!nv) return -1;
-    if (nc > ix->visited_cap) memset(nv + ix->visited_cap, 0, (nc-ix->visited_cap)*sizeof(uint32_t));
-    ix->visited = nv; ix->visited_cap = nc;
+/* ── visited set — owned by the CALL FRAME, never by the index ──────────────
+ * This buffer is per-TRAVERSAL scratch. It used to live in struct VIndex as an
+ * allocation optimisation, which made every traversal a write to shared state:
+ * two concurrent vindex_search calls stamped each other's epoch and then walked
+ * each other's marks, so even two pure READS corrupted the traversal (measured
+ * 2026-08-16: TSan data race at visited_reset, reached from vindex_search on one
+ * thread and vindex_insert on another; downstream SIGSEGV dereferencing a bogus
+ * element index).
+ *
+ * It is not an ownership problem and it does not want a lock or a capability —
+ * it was simply misfiled. A pure function's scratch belongs to the call. Moving
+ * it here is what lets vindex_search take a `const VIndex*`, which is in turn
+ * what makes "search does not mutate the index" a COMPILE-TIME property instead
+ * of a review comment.
+ *
+ * Cost: one calloc/free of cap*4 bytes per traversal (~55 KB at the live store's
+ * 13,820 elements), against thousands of dim-768 dot products in the same call.
+ * Deliberately NOT __thread: http_worker is a thread per connection, so a
+ * thread-local buffer would retain ~55 KB per connection for the process life. */
+typedef struct {
+    uint32_t* mark;      /* per-element epoch stamp */
+    uint32_t  epoch;     /* current traversal's stamp; 0 == "no traversal yet" */
+    size_t    cap;
+} VVisit;
+
+/* calloc leaves every stamp 0 and epoch 0; the first visit_reset moves to
+ * epoch 1, so no element reads as visited before it is marked. */
+static int visit_init(VVisit* v, size_t cap){
+    size_t nc = cap ? cap : 16;
+    v->mark = (uint32_t*)calloc(nc, sizeof(uint32_t));
+    if (!v->mark) return -1;
+    v->cap = nc; v->epoch = 0;
    return 0;
 }
-static inline void visited_reset(VIndex* ix){
-    if (++ix->visit_epoch == 0){                 /* wrapped: clear all */
-        memset(ix->visited, 0, ix->visited_cap*sizeof(uint32_t));
-        ix->visit_epoch = 1;
+static void visit_dispose(VVisit* v){ free(v->mark); v->mark = NULL; v->cap = 0; }
+static inline void visit_reset(VVisit* v){
+    if (++v->epoch == 0){                        /* wrapped: clear all */
+        memset(v->mark, 0, v->cap*sizeof(uint32_t));
+        v->epoch = 1;
    }
 }
-static inline int is_visited(VIndex* ix, int e){ return ix->visited[e]==ix->visit_epoch; }
-static inline void mark_visited(VIndex* ix, int e){ ix->visited[e]=ix->visit_epoch; }
+static inline int is_visited(const VVisit* v, int e){ return v->mark[e]==v->epoch; }
+static inline void mark_visited(VVisit* v, int e){ v->mark[e]=v->epoch; }

 /* ── search one layer (Algorithm 2): best-first, ef-bounded ───────────────── */
 /* Returns results as an unsorted Heap (max-heap on distance, size<=ef). Caller
 * owns res->a. `q` is a normalised query. */
-static int search_layer(VIndex* ix, const float* q, const int* eps, int neps,
+static int search_layer(const VIndex* ix, VVisit* vis, const float* q,
+                        const int* eps, int neps,
                        int ef, int layer, Heap* res /*out, max-heap*/){
    Heap cand = {0,0,0};                          /* min-heap: nearest to expand */
    res->a=NULL; res->n=0; res->cap=0;
-    visited_reset(ix);
+    visit_reset(vis);
    for (int i=0;i<neps;i++){
        int e = eps[i];
-        if (is_visited(ix,e)) continue;
-        mark_visited(ix,e);
+        if (is_visited(vis,e)) continue;
+        mark_visited(vis,e);
        float d = vdist(ix, q, ix->elems[e].vec);
        Pair p = { d, e };
        if (heap_push(&cand,p,0) || heap_push(res,p,1)){ free(cand.a); return -1; }
@@ -212,8 +233,8 @@ static int search_layer(VIndex* ix, const float* q, const int* eps, int neps,
            NeighList* nl = &ce->links[layer];
            for (int i=0;i<nl->count;i++){
                int e = nl->ids[i];
-                if (is_visited(ix,e)) continue;
-                mark_visited(ix,e);
+                if (is_visited(vis,e)) continue;
+                mark_visited(vis,e);
                float d = vdist(ix, q, ix->elems[e].vec);
                if (res->n < ef || d < res->a[0].d){
                    Pair p = { d, e };
@@ -232,7 +253,7 @@ static int search_layer(VIndex* ix, const float* q, const int* eps, int neps,
 * Keep c only if it is nearer to q than to every already-chosen neighbour;
 * backfill from the pruned set (nearest first) to reach M for connectivity.
 * Writes chosen element indices into out[], returns the count. */
-static int select_neighbors(VIndex* ix, const float* q, Pair* W, int nW, int M, int* out){
+static int select_neighbors(const VIndex* ix, const float* q, Pair* W, int nW, int M, int* out){
    (void)q;   /* q's distances are precomputed in W[].d; kept for call-site clarity */
    /* sort W ascending by (dist,elem) — deterministic. */
    for (int i=1;i<nW;i++){                        /* insertion sort (nW small) */
@@ -281,7 +302,7 @@ static int elems_reserve(VIndex* ix){
    Elem* ne = (Elem*)realloc(ix->elems, nc*sizeof(Elem));
    if (!ne) return -1;
    ix->elems = ne; ix->cap = nc;
-    return visited_ensure(ix);
+    return 0;
 }

 int vindex_insert(VIndex* ix, uint64_t node_id, const float* vec){
@@ -307,13 +328,19 @@ int vindex_insert(VIndex* ix, uint64_t node_id, const float* vec){
        return 0;
    }

+    /* This call frame owns its traversal scratch for the whole insert. ix->cap
+     * already covers `cur` (elems_reserve ran above), so every reachable element
+     * index is in range. */
+    VVisit vis;
+    if (visit_init(&vis, ix->cap)) return -1;
+
    int ep = ix->entry;
    int L = ix->max_level;
    /* greedy descent through layers above `level` to refine the entry point. */
    for (int lc = L; lc > level; lc--){
        Heap r = {0,0,0};
        int eps1[1] = { ep };
-        if (search_layer(ix, el->vec, eps1, 1, 1, lc, &r)){ return -1; }
+        if (search_layer(ix, &vis, el->vec, eps1, 1, 1, lc, &r)){ visit_dispose(&vis); return -1; }
        if (r.n){ ep = r.a[0].e; float bd=r.a[0].d;
            for (int i=1;i<r.n;i++) if (r.a[i].d<bd){bd=r.a[i].d; ep=r.a[i].e;} }
        free(r.a);
@@ -329,7 +356,7 @@ int vindex_insert(VIndex* ix, uint64_t node_id, const float* vec){
    for (int lc = start; lc >= 0; lc--){
        int Mmax = (lc==0) ? ix->M0 : ix->M;
        Heap W = {0,0,0};
-        if (search_layer(ix, el->vec, eps, neps, ix->ef_construction, lc, &W)){ rc=-1; break; }
+        if (search_layer(ix, &vis, el->vec, eps, neps, ix->ef_construction, lc, &W)){ rc=-1; break; }
        int* chosen = (int*)malloc((size_t)(W.n?W.n:1)*sizeof(int));
        if (!chosen){ free(W.a); rc=-1; break; }
        int nc = select_neighbors(ix, el->vec, W.a, W.n, Mmax, chosen);
@@ -357,13 +384,17 @@ int vindex_insert(VIndex* ix, uint64_t node_id, const float* vec){
    }
 done:
    free(eps_owned);
+    visit_dispose(&vis);
    if (rc) return -1;
    if (level > ix->max_level){ ix->max_level = level; ix->entry = cur; }
    return 0;
 }

 /* ── search ───────────────────────────────────────────────────────────────── */
-int vindex_search(VIndex* ix, const float* query, int k, int ef_search,
+/* `ix` is const: search is pure with respect to the index. That is enforced by
+ * the compiler, not by convention — it is the whole point of moving the visited
+ * set into the frame below. */
+int vindex_search(const VIndex* ix, const float* query, int k, int ef_search,
                  uint64_t* node_id_out, float* dist_out){
    if (!ix || !query || k <= 0) return -1;
    if (ix->entry < 0) return 0;
@@ -373,11 +404,15 @@ int vindex_search(VIndex* ix, const float* query, int k, int ef_search,
    float* q = vec_normalise_copy(query, ix->dim);
    if (!q) return -1;

+    /* This call frame owns its traversal scratch. */
+    VVisit vis;
+    if (visit_init(&vis, ix->cap)){ free(q); return -1; }
+
    int ep = ix->entry;
    for (int lc = ix->max_level; lc > 0; lc--){
        Heap r = {0,0,0};
        int eps[1] = { ep };
-        if (search_layer(ix, q, eps, 1, 1, lc, &r)){ free(q); return -1; }
+        if (search_layer(ix, &vis, q, eps, 1, 1, lc, &r)){ visit_dispose(&vis); free(q); return -1; }
        if (r.n){ int b=r.a[0].e; float bd=r.a[0].d;
            for (int i=1;i<r.n;i++) if (r.a[i].d<bd){bd=r.a[i].d; b=r.a[i].e;}
            ep = b; }
@@ -385,7 +420,8 @@ int vindex_search(VIndex* ix, const float* query, int k, int ef_search,
    }
    Heap res = {0,0,0};
    int eps[1] = { ep };
-    if (search_layer(ix, q, eps, 1, ef_search, 0, &res)){ free(res.a); free(q); return -1; }
+    if (search_layer(ix, &vis, q, eps, 1, ef_search, 0, &res)){ visit_dispose(&vis); free(res.a); free(q); return -1; }
+    visit_dispose(&vis);
    free(q);

    /* res is a max-heap of size<=ef; pop into ascending order, keep nearest k. */
@@ -419,7 +455,6 @@ VIndex* vindex_create(int dim, int M, int ef_construction){
    ix->mL = 1.0 / log((double)M > 1.0 ? (double)M : 2.0);
    ix->entry = -1;
    ix->max_level = 0;
-    ix->visit_epoch = 0;
    return ix;
 }

@@ -432,7 +467,6 @@ void vindex_free(VIndex* ix){
        free(e->vec);
    }
    free(ix->elems);
-    free(ix->visited);
    free(ix);
 }

@@ -53,8 +53,15 @@ int vindex_insert(VIndex* idx, uint64_t node_id, const float* vec);
 * first (ascending distance). Either out array may be NULL to skip it.
 *   ef_search — search-time candidate width; larger == higher recall, slower.
 *               Pass <=0 for VINDEX_DEFAULT_EF_SEARCH. Internally clamped to >=k.
- * Returns the number of results written, or <0 on error. */
-int vindex_search(VIndex* idx, const float* query, int k, int ef_search,
+ * Returns the number of results written, or <0 on error.
+ *
+ * `idx` is const BY CONTRACT AND BY TYPE: search does not mutate the index. The
+ * traversal's visited set is owned by the call frame, so N threads may search one
+ * index concurrently. Concurrent search against a vindex_insert on the same index
+ * is still unsafe — insert rewires existing elements' neighbour lists and reallocs
+ * elems[] — so the index's owner must not extend a published index under a live
+ * reader. See eg_vindex_view / eg_vindex_maintain in el_runtime.c. */
+int vindex_search(const VIndex* idx, const float* query, int k, int ef_search,
                  uint64_t* node_id_out, float* dist_out);

 /* Number of vectors currently indexed. */