static_embeddings 0.1.1 → 0.1.2

data/ext/static_embeddings/se_format.c

@@ -14,6 +14,8 @@
 #ifndef O_CLOEXEC
 #define O_CLOEXEC 0
 #endif
+#else
+#include <windows.h>
 #endif
 
 void se_error_clear(se_error_t *err) {
@@ -278,6 +280,68 @@ static se_status_t parse_trie(se_trie_t *trie, const uint8_t *base, struct secti
     return SE_OK;
 }
 
+static int valid_unicode_codepoint(uint32_t cp) {
+    return cp <= 0x10FFFFu && !(cp >= 0xD800u && cp <= 0xDFFFu);
+}
+
+static se_status_t validate_norm_map(const se_map_entry_t *entries, uint32_t count,
+                                     const char *name, se_error_t *err) {
+    uint32_t prev = 0;
+
+    for (uint32_t i = 0; i < count; i++) {
+        const se_map_entry_t *entry = &entries[i];
+        if (entry->len > SE_ARRAY_LEN(entry->out)) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "%s map entry %u has len %u", name, i,
+                         entry->len);
+            return SE_ERR_INVALID_FORMAT;
+        }
+        if (!valid_unicode_codepoint(entry->cp)) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "%s map entry %u has invalid codepoint", name,
+                         i);
+            return SE_ERR_INVALID_FORMAT;
+        }
+        for (uint32_t k = 0; k < entry->len; k++) {
+            if (!valid_unicode_codepoint(entry->out[k])) {
+                se_error_set(err, SE_ERR_INVALID_FORMAT,
+                             "%s map entry %u output %u is not a valid codepoint", name, i, k);
+                return SE_ERR_INVALID_FORMAT;
+            }
+        }
+        if (i && entry->cp <= prev) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "%s map is not strictly sorted", name);
+            return SE_ERR_INVALID_FORMAT;
+        }
+        prev = entry->cp;
+    }
+
+    return SE_OK;
+}
+
+static se_status_t validate_norm_ranges(const se_range_t *ranges, uint32_t count, const char *name,
+                                        se_error_t *err) {
+    uint32_t prev_hi = 0;
+
+    for (uint32_t i = 0; i < count; i++) {
+        const se_range_t *range = &ranges[i];
+        if (!valid_unicode_codepoint(range->hi)) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "%s range %u exceeds the Unicode range", name,
+                         i);
+            return SE_ERR_INVALID_FORMAT;
+        }
+        if (range->lo > range->hi) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "%s range %u is inverted", name, i);
+            return SE_ERR_INVALID_FORMAT;
+        }
+        if (i && range->lo <= prev_hi) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "%s ranges overlap or are unsorted", name);
+            return SE_ERR_INVALID_FORMAT;
+        }
+        prev_hi = range->hi;
+    }
+
+    return SE_OK;
+}
+
 static se_status_t parse_norm_tables(se_model_t *model, const uint8_t *base, struct section sec,
                                      se_error_t *err) {
     memset(&model->norm, 0, sizeof(model->norm));
@@ -338,66 +402,112 @@ static se_status_t parse_norm_tables(se_model_t *model, const uint8_t *base, str
     model->norm.whitespace = (const se_range_t *)cursor;
     model->norm.whitespace_count = n_ws;
 
-    const se_map_entry_t *maps[] = {model->norm.lower, model->norm.nfd};
-    const uint32_t map_counts[] = {model->norm.lower_count, model->norm.nfd_count};
-    const char *map_names[] = {"lower", "nfd"};
-    for (size_t table = 0; table < 2; table++) {
-        uint32_t prev = 0;
-        for (uint32_t i = 0; i < map_counts[table]; i++) {
-            const se_map_entry_t *entry = &maps[table][i];
-            if (entry->len > 4) {
-                se_error_set(err, SE_ERR_INVALID_FORMAT, "%s map entry %u has len %u",
-                             map_names[table], i, entry->len);
-                return SE_ERR_INVALID_FORMAT;
-            }
-            if (entry->cp > 0x10FFFFu || (entry->cp >= 0xD800u && entry->cp <= 0xDFFFu)) {
-                se_error_set(err, SE_ERR_INVALID_FORMAT, "%s map entry %u has invalid codepoint",
-                             map_names[table], i);
-                return SE_ERR_INVALID_FORMAT;
-            }
-            for (uint32_t k = 0; k < entry->len; k++) {
-                uint32_t out_cp = entry->out[k];
-                if (out_cp > 0x10FFFFu || (out_cp >= 0xD800u && out_cp <= 0xDFFFu)) {
-                    se_error_set(err, SE_ERR_INVALID_FORMAT,
-                                 "%s map entry %u output %u is not a valid codepoint",
-                                 map_names[table], i, k);
-                    return SE_ERR_INVALID_FORMAT;
-                }
-            }
-            if (i && entry->cp <= prev) {
-                se_error_set(err, SE_ERR_INVALID_FORMAT, "%s map is not strictly sorted",
-                             map_names[table]);
-                return SE_ERR_INVALID_FORMAT;
-            }
-            prev = entry->cp;
+    se_status_t rc = validate_norm_map(model->norm.lower, model->norm.lower_count, "lower", err);
+    if (rc != SE_OK)
+        return rc;
+    rc = validate_norm_map(model->norm.nfd, model->norm.nfd_count, "nfd", err);
+    if (rc != SE_OK)
+        return rc;
+    rc = validate_norm_ranges(model->norm.mn, model->norm.mn_count, "mn", err);
+    if (rc != SE_OK)
+        return rc;
+    rc = validate_norm_ranges(model->norm.punct, model->norm.punct_count, "punct", err);
+    if (rc != SE_OK)
+        return rc;
+    rc = validate_norm_ranges(model->norm.control, model->norm.control_count, "control", err);
+    if (rc != SE_OK)
+        return rc;
+    return validate_norm_ranges(model->norm.whitespace, model->norm.whitespace_count, "whitespace",
+                                err);
+}
+
+static se_status_t validate_vocab_hash(const se_model_t *model, struct section vocab_strings,
+                                       se_error_t *err) {
+    const se_meta_t *m = &model->meta;
+    size_t bitset_size = ((size_t)m->vocab_size + 7u) / 8u;
+    size_t seen_bytes = 0;
+    uint32_t filled = 0;
+    se_status_t rc = SE_OK;
+
+    if (!se_alloc_bytes(bitset_size, 1u, &seen_bytes)) {
+        se_error_set(err, SE_ERR_INVALID_FORMAT, "vocabulary size is too large");
+        return SE_ERR_INVALID_FORMAT;
+    }
+
+    uint8_t *seen = (uint8_t *)se_calloc(SE_ALLOC_FORMAT_VALIDATE, 1, seen_bytes);
+    if (!seen) {
+        se_error_set(err, SE_ERR_OOM, "out of memory while validating vocabulary hash");
+        return SE_ERR_OOM;
+    }
+
+    for (uint32_t i = 0; i < m->hash_table_size; i++) {
+        const se_vocab_slot_t *slot = &model->vocab_hash[i];
+        if (slot->token_id == SE_SLOT_EMPTY)
+            continue;
+        if (slot->token_id >= m->vocab_size) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "slot %u has token id out of range", i);
+            rc = SE_ERR_INVALID_FORMAT;
+            goto done;
         }
+        if ((uint64_t)slot->str_off + slot->str_len > vocab_strings.size) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT, "slot %u points outside the string blob", i);
+            rc = SE_ERR_INVALID_FORMAT;
+            goto done;
+        }
+
+        uint8_t mask = (uint8_t)(1u << (slot->token_id & 7u));
+        uint8_t *byte = &seen[slot->token_id >> 3];
+        if (*byte & mask) {
+            se_error_set(err, SE_ERR_INVALID_FORMAT,
+                         "token id %u appears more than once in hash table", slot->token_id);
+            rc = SE_ERR_INVALID_FORMAT;
+            goto done;
+        }
+
+        *byte |= mask;
+        filled++;
     }
 
-    const se_range_t *ranges[] = {model->norm.mn, model->norm.punct, model->norm.control,
-                                  model->norm.whitespace};
-    const uint32_t range_counts[] = {model->norm.mn_count, model->norm.punct_count,
-                                     model->norm.control_count, model->norm.whitespace_count};
-    const char *range_names[] = {"mn", "punct", "control", "whitespace"};
-    for (size_t table = 0; table < 4; table++) {
-        uint32_t prev_hi = 0;
-        for (uint32_t i = 0; i < range_counts[table]; i++) {
-            const se_range_t *range = &ranges[table][i];
-            if (range->hi > 0x10FFFFu) {
-                se_error_set(err, SE_ERR_INVALID_FORMAT, "%s range %u exceeds the Unicode range",
-                             range_names[table], i);
-                return SE_ERR_INVALID_FORMAT;
-            }
-            if (range->lo > range->hi) {
-                se_error_set(err, SE_ERR_INVALID_FORMAT, "%s range %u is inverted",
-                             range_names[table], i);
-                return SE_ERR_INVALID_FORMAT;
-            }
-            if (i && range->lo <= prev_hi) {
-                se_error_set(err, SE_ERR_INVALID_FORMAT, "%s ranges overlap or are unsorted",
-                             range_names[table]);
+    if (filled != m->vocab_size) {
+        se_error_set(err, SE_ERR_INVALID_FORMAT, "hash table has %u filled slots, expected %u",
+                     filled, m->vocab_size);
+        rc = SE_ERR_INVALID_FORMAT;
+        goto done;
+    }
+
+    uint32_t unk_lookup = 0;
+    if (!se_vocab_lookup(model, (const uint8_t *)"[UNK]", 5, &unk_lookup) ||
+        unk_lookup != m->unk_id) {
+        se_error_set(err, SE_ERR_INVALID_FORMAT,
+                     "[UNK] is not reachable through the vocabulary hash");
+        rc = SE_ERR_INVALID_FORMAT;
+    }
+
+done:
+    se_free(seen);
+    return rc;
+}
+
+static se_status_t validate_hash_probe_limits(const se_model_t *model, se_error_t *err) {
+    const se_meta_t *m = &model->meta;
+    if (m->max_probe == 0)
+        return SE_OK;
+
+    uint32_t mask = m->hash_table_size - 1u;
+    for (uint32_t i = 0; i < m->hash_table_size; i++) {
+        const se_vocab_slot_t *slot = &model->vocab_hash[i];
+        if (slot->token_id == SE_SLOT_EMPTY)
+            continue;
+
+        uint32_t pos = slot->hash & mask;
+        uint32_t probes = 1;
+        while (pos != i) {
+            probes++;
+            pos = (pos + 1u) & mask;
+            if (probes > m->max_probe) {
+                se_error_set(err, SE_ERR_INVALID_FORMAT, "slot %u exceeds recorded max probe", i);
                 return SE_ERR_INVALID_FORMAT;
             }
-            prev_hi = range->hi;
         }
     }
 
@@ -408,6 +518,12 @@ static se_status_t validate(se_model_t *model, se_error_t *err) {
     const uint8_t *base = (const uint8_t *)model->map_base;
     const uint64_t file_size = (uint64_t)model->map_size;
 
+    if (!se_host_is_little_endian()) {
+        se_error_set(err, SE_ERR_UNSUPPORTED_VERSION,
+                     "static_embeddings .semb files require a little-endian host");
+        return SE_ERR_UNSUPPORTED_VERSION;
+    }
+
     if (file_size < SE_HEADER_SIZE) {
         se_error_set(err, SE_ERR_INVALID_FORMAT, "file shorter than header");
         return SE_ERR_INVALID_FORMAT;
@@ -553,8 +669,7 @@ static se_status_t validate(se_model_t *model, se_error_t *err) {
 
     const struct section sections[] = {vocab_strings, vocab_hash, embeddings, norm,
                                        provenance,    root_trie,  cont_trie};
-    se_status_t overlap_status =
-        validate_no_overlaps(sections, sizeof(sections) / sizeof(sections[0]), err);
+    se_status_t overlap_status = validate_no_overlaps(sections, SE_ARRAY_LEN(sections), err);
     if (overlap_status != SE_OK)
         return overlap_status;
 
@@ -585,74 +700,13 @@ static se_status_t validate(se_model_t *model, se_error_t *err) {
     model->provenance = provenance.size ? (const char *)(base + provenance.off) : NULL;
     model->provenance_size = (size_t)provenance.size;
 
-    size_t bitset_size = ((size_t)m->vocab_size + 7u) / 8u;
-    uint8_t *seen = (uint8_t *)calloc(bitset_size ? bitset_size : 1u, 1u);
-    if (!seen) {
-        se_error_set(err, SE_ERR_OOM, "out of memory while validating vocabulary hash");
-        return SE_ERR_OOM;
-    }
-
-    uint32_t filled = 0;
-    for (uint32_t i = 0; i < m->hash_table_size; i++) {
-        const se_vocab_slot_t *slot = &model->vocab_hash[i];
-        if (slot->token_id == SE_SLOT_EMPTY)
-            continue;
-        if (slot->token_id >= m->vocab_size) {
-            free(seen);
-            se_error_set(err, SE_ERR_INVALID_FORMAT, "slot %u has token id out of range", i);
-            return SE_ERR_INVALID_FORMAT;
-        }
-        if ((uint64_t)slot->str_off + slot->str_len > vocab_strings.size) {
-            free(seen);
-            se_error_set(err, SE_ERR_INVALID_FORMAT, "slot %u points outside the string blob", i);
-            return SE_ERR_INVALID_FORMAT;
-        }
-        uint8_t mask = (uint8_t)(1u << (slot->token_id & 7u));
-        uint8_t *byte = &seen[slot->token_id >> 3];
-        if (*byte & mask) {
-            free(seen);
-            se_error_set(err, SE_ERR_INVALID_FORMAT,
-                         "token id %u appears more than once in hash table", slot->token_id);
-            return SE_ERR_INVALID_FORMAT;
-        }
-        *byte |= mask;
-        filled++;
-    }
-    free(seen);
-
-    if (filled != m->vocab_size) {
-        se_error_set(err, SE_ERR_INVALID_FORMAT, "hash table has %u filled slots, expected %u",
-                     filled, m->vocab_size);
-        return SE_ERR_INVALID_FORMAT;
-    }
+    se_status_t hash_status = validate_vocab_hash(model, vocab_strings, err);
+    if (hash_status != SE_OK)
+        return hash_status;
 
-    uint32_t unk_lookup = 0;
-    if (!se_vocab_lookup(model, (const uint8_t *)"[UNK]", 5, &unk_lookup) ||
-        unk_lookup != m->unk_id) {
-        se_error_set(err, SE_ERR_INVALID_FORMAT,
-                     "[UNK] is not reachable through the vocabulary hash");
-        return SE_ERR_INVALID_FORMAT;
-    }
-
-    if (m->max_probe > 0) {
-        uint32_t mask = m->hash_table_size - 1u;
-        for (uint32_t i = 0; i < m->hash_table_size; i++) {
-            const se_vocab_slot_t *slot = &model->vocab_hash[i];
-            if (slot->token_id == SE_SLOT_EMPTY)
-                continue;
-            uint32_t pos = slot->hash & mask;
-            uint32_t probes = 1;
-            while (pos != i) {
-                probes++;
-                pos = (pos + 1u) & mask;
-                if (probes > m->max_probe) {
-                    se_error_set(err, SE_ERR_INVALID_FORMAT, "slot %u exceeds recorded max probe",
-                                 i);
-                    return SE_ERR_INVALID_FORMAT;
-                }
-            }
-        }
-    }
+    se_status_t probe_status = validate_hash_probe_limits(model, err);
+    if (probe_status != SE_OK)
+        return probe_status;
 
     se_status_t trie_status =
         parse_trie(&model->root_trie, base, root_trie, m->vocab_size, "root", err);
@@ -701,35 +755,65 @@ se_status_t se_model_open(se_model_t *model, const char *path, se_error_t *err)
     model->map_size = (size_t)st.st_size;
     model->mapped = 1;
 #else
-    FILE *f = fopen(path, "rb");
-    if (!f) {
+    HANDLE file = CreateFileA(path, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING,
+                              FILE_ATTRIBUTE_NORMAL, NULL);
+    if (file == INVALID_HANDLE_VALUE) {
         se_error_set(err, SE_ERR_IO, "cannot open %s", path);
         return SE_ERR_IO;
     }
-    fseek(f, 0, SEEK_END);
-    long size = ftell(f);
-    fseek(f, 0, SEEK_SET);
-    if (size <= 0) {
-        fclose(f);
-        se_error_set(err, SE_ERR_IO, "empty file %s", path);
+
+    LARGE_INTEGER file_size;
+    if (!GetFileSizeEx(file, &file_size) || file_size.QuadPart <= 0) {
+        CloseHandle(file);
+        se_error_set(err, SE_ERR_IO, "cannot stat %s", path);
         return SE_ERR_IO;
     }
-    void *buf = malloc((size_t)size);
-    if (!buf) {
-        fclose(f);
-        se_error_set(err, SE_ERR_OOM, "out of memory");
-        return SE_ERR_OOM;
-    }
-    if (fread(buf, 1, (size_t)size, f) != (size_t)size) {
-        free(buf);
-        fclose(f);
-        se_error_set(err, SE_ERR_IO, "short read on %s", path);
+
+    if ((uint64_t)file_size.QuadPart > (uint64_t)SIZE_MAX) {
+        CloseHandle(file);
+        se_error_set(err, SE_ERR_IO, "file is too large to map safely");
         return SE_ERR_IO;
     }
-    fclose(f);
-    model->map_base = buf;
-    model->map_size = (size_t)size;
-    model->mapped = 0;
+
+    void *view = NULL;
+    HANDLE mapping = CreateFileMappingA(file, NULL, PAGE_READONLY, 0, 0, NULL);
+    if (mapping) {
+        view = MapViewOfFile(mapping, FILE_MAP_READ, 0, 0, 0);
+        CloseHandle(mapping);
+    }
+
+    if (view) {
+        CloseHandle(file);
+        model->map_base = view;
+        model->map_size = (size_t)file_size.QuadPart;
+        model->mapped = 1;
+    } else {
+        size_t size = (size_t)file_size.QuadPart;
+        void *buf = se_malloc(SE_ALLOC_MODEL_FILE, size);
+        if (!buf) {
+            CloseHandle(file);
+            se_error_set(err, SE_ERR_OOM, "out of memory");
+            return SE_ERR_OOM;
+        }
+
+        size_t got = 0;
+        while (got < size) {
+            DWORD chunk = (DWORD)((size - got) > 0x10000000u ? 0x10000000u : (size - got));
+            DWORD read = 0;
+            if (!ReadFile(file, (uint8_t *)buf + got, chunk, &read, NULL) || read == 0) {
+                se_free(buf);
+                CloseHandle(file);
+                se_error_set(err, SE_ERR_IO, "short read on %s", path);
+                return SE_ERR_IO;
+            }
+            got += read;
+        }
+
+        CloseHandle(file);
+        model->map_base = buf;
+        model->map_size = size;
+        model->mapped = 0;
+    }
 #endif
 
     se_status_t rc = validate(model, err);
@@ -747,9 +831,12 @@ void se_model_close(se_model_t *model) {
     if (model->mapped)
         munmap(model->map_base, model->map_size);
     else
-        free(model->map_base);
+        se_free(model->map_base);
 #else
-    free(model->map_base);
+    if (model->mapped)
+        UnmapViewOfFile(model->map_base);
+    else
+        se_free(model->map_base);
 #endif
     memset(model, 0, sizeof(*model));
 }

data/ext/static_embeddings/se_internal.h

@@ -4,6 +4,7 @@
 #include <stddef.h>
 #include <stdint.h>
 #include <signal.h>
+#include <limits.h>
 
 #define SE_MAGIC          "SEMBv1\0\0"
 #define SE_MAGIC_LEN      8
@@ -26,6 +27,22 @@
 #define SE_EMPTY_RAISE       1u
 
 #define SE_SLOT_EMPTY 0xFFFFFFFFu
+#define SE_SIZE_MAX   ((size_t)-1)
+
+#ifndef SE_ENABLE_ALLOC_STATS
+#define SE_ENABLE_ALLOC_STATS 0
+#endif
+
+#define SE_ARRAY_LEN(a) (sizeof(a) / sizeof((a)[0]))
+
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
+#define SE_STATIC_ASSERT(expr, name) _Static_assert((expr), #name)
+#else
+#define SE_STATIC_ASSERT_JOIN_INNER(a, b) a##b
+#define SE_STATIC_ASSERT_JOIN(a, b)       SE_STATIC_ASSERT_JOIN_INNER(a, b)
+#define SE_STATIC_ASSERT(expr, name) \
+    typedef char SE_STATIC_ASSERT_JOIN(se_static_assertion_, name)[(expr) ? 1 : -1]
+#endif
 
 enum {
     SE_OFF_MAGIC = 0,
@@ -199,6 +216,110 @@ typedef struct {
     char message[256];
 } se_error_t;
 
+typedef enum { SE_VECTOR_FORMAT_F32 = 1, SE_VECTOR_FORMAT_F16 = 2 } se_vector_format_t;
+
+typedef enum {
+    SE_F16_BACKEND_LUT = 0,
+    SE_F16_BACKEND_NEON_FP16 = 1,
+    SE_F16_BACKEND_F16C = 2
+} se_f16_backend_t;
+
+typedef enum {
+    SE_ALLOC_UNKNOWN = 0,
+    SE_ALLOC_SCRATCH,
+    SE_ALLOC_BATCH_INPUT,
+    SE_ALLOC_BATCH_OUTPUT,
+    SE_ALLOC_BATCH_STATS,
+    SE_ALLOC_BATCH_INDEX,
+    SE_ALLOC_TOKEN_IDS,
+    SE_ALLOC_TOPK_QUERY,
+    SE_ALLOC_TOPK_BEST,
+    SE_ALLOC_TOPK_MATRIX_COPY,
+    SE_ALLOC_FORMAT_VALIDATE,
+    SE_ALLOC_MODEL_FILE,
+    SE_ALLOC_CATEGORY_COUNT
+} se_alloc_category_t;
+
+typedef struct {
+    size_t current_bytes;
+    size_t peak_bytes;
+    size_t total_allocated_bytes;
+    size_t total_freed_bytes;
+    size_t alloc_count;
+    size_t realloc_count;
+    size_t free_count;
+} se_alloc_stats_t;
+
+typedef struct {
+    const float *q;
+    const void *m;
+    se_vector_format_t format;
+    size_t dim;
+    size_t rows;
+    long k;
+    size_t *best_idx;
+    float *best_score;
+    int cosine;
+    float inv_query_norm;
+    volatile sig_atomic_t cancelled;
+} se_topk_job_t;
+
+SE_STATIC_ASSERT(sizeof(se_vocab_slot_t) == 16, vocab_slot_size);
+SE_STATIC_ASSERT(sizeof(se_trie_node_t) == 16, trie_node_size);
+SE_STATIC_ASSERT(sizeof(se_trie_edge_t) == 8, trie_edge_size);
+SE_STATIC_ASSERT(sizeof(se_map_entry_t) == 24, map_entry_size);
+SE_STATIC_ASSERT(sizeof(se_range_t) == 8, range_size);
+
+static inline int se_checked_add_size(size_t a, size_t b, size_t *out) {
+    if (a > SE_SIZE_MAX - b)
+        return 0;
+    *out = a + b;
+    return 1;
+}
+
+static inline int se_checked_mul_size(size_t a, size_t b, size_t *out) {
+    if (a != 0 && b > SE_SIZE_MAX / a)
+        return 0;
+    *out = a * b;
+    return 1;
+}
+
+static inline int se_array_bytes(size_t count, size_t elem_size, size_t *out) {
+    return se_checked_mul_size(count, elem_size, out);
+}
+
+static inline size_t se_alloc_count(size_t count) {
+    return count ? count : 1;
+}
+
+static inline int se_alloc_bytes(size_t count, size_t elem_size, size_t *out) {
+    return se_checked_mul_size(se_alloc_count(count), elem_size, out);
+}
+
+static inline int se_next_capacity(size_t current, size_t need, size_t min_capacity, size_t *out) {
+    size_t next = current ? current : min_capacity;
+
+    if (next == 0)
+        next = 1;
+    while (next < need) {
+        if (next > SE_SIZE_MAX / 2)
+            return 0;
+        next *= 2;
+    }
+
+    *out = next;
+    return 1;
+}
+
+static inline int se_size_fits_long(size_t n) {
+    return n <= (size_t)LONG_MAX;
+}
+
+static inline int se_host_is_little_endian(void) {
+    const uint16_t one = 1;
+    return *((const uint8_t *)(const void *)&one) == 1;
+}
+
 #if defined(__GNUC__) || defined(__clang__)
 #define SE_PRINTF_FORMAT(fmt_index, first_arg) __attribute__((format(printf, fmt_index, first_arg)))
 #else
@@ -208,6 +329,28 @@ typedef struct {
 void se_error_clear(se_error_t *err);
 void se_error_set(se_error_t *err, se_status_t status, const char *fmt, ...) SE_PRINTF_FORMAT(3, 4);
 
+const char *se_alloc_category_name(se_alloc_category_t category);
+void se_alloc_stats_reset(void);
+void se_alloc_stats_snapshot(se_alloc_stats_t out[SE_ALLOC_CATEGORY_COUNT]);
+
+#if SE_ENABLE_ALLOC_STATS
+void *se_alloc_stats_malloc(se_alloc_category_t category, size_t bytes);
+void *se_alloc_stats_calloc(se_alloc_category_t category, size_t count, size_t elem_size);
+void *se_alloc_stats_realloc(se_alloc_category_t category, void *ptr, size_t bytes);
+void se_alloc_stats_free(void *ptr);
+
+#define se_malloc(category, bytes) se_alloc_stats_malloc((category), (bytes))
+#define se_calloc(category, count, elem_size) \
+    se_alloc_stats_calloc((category), (count), (elem_size))
+#define se_realloc(category, ptr, bytes) se_alloc_stats_realloc((category), (ptr), (bytes))
+#define se_free(ptr)                     se_alloc_stats_free((ptr))
+#else
+#define se_malloc(category, bytes)            malloc((bytes))
+#define se_calloc(category, count, elem_size) calloc((count), (elem_size))
+#define se_realloc(category, ptr, bytes)      realloc((ptr), (bytes))
+#define se_free(ptr)                          free((ptr))
+#endif
+
 se_status_t se_model_open(se_model_t *model, const char *path, se_error_t *err);
 void se_model_close(se_model_t *model);
 size_t se_model_memsize(const se_model_t *model);
@@ -263,4 +406,20 @@ se_status_t se_embed_ids(const se_model_t *model, se_scratch_t *scratch, const u
 void se_l2_normalize(float *vec, uint32_t dim);
 size_t se_model_warmup(const se_model_t *model);
 
+size_t se_vector_format_element_bytes(se_vector_format_t format);
+uint16_t se_float_to_f16_bits(float value);
+float se_f16_bits_to_float(uint16_t half);
+void se_write_f16le(uint8_t *dst, float value);
+float se_read_f16le(const uint8_t *src);
+void se_encode_f16_from_floats(uint8_t *dst, const float *src, size_t count);
+void se_decode_f16_to_floats(float *dst, const uint8_t *src, size_t count);
+void se_select_f16_backend(void);
+se_f16_backend_t se_current_f16_backend(void);
+
+float se_dot_product_f32(const float *q, const float *row, size_t dim);
+float se_dot_and_row_sq_f32(const float *q, const float *row, size_t dim, float *row_sq_out);
+float se_dot_product_f16(const float *q, const uint8_t *row, size_t dim);
+float se_dot_and_row_sq_f16(const float *q, const uint8_t *row, size_t dim, float *row_sq_out);
+void *se_topk_execute(void *arg);
+
 #endif