local-llm-rn 1.0.2 → 1.0.3

package/android/src/main/cpp/LocalLLM.cpp

@@ -10,6 +10,7 @@
 #include <android/log.h>
 
 #include <string>
+#include <memory>
 #include <unordered_map>
 #include <mutex>
 #include <atomic>
@@ -51,6 +52,12 @@ static std::unordered_map<std::string, hilum_context *> g_contexts;
 static std::unordered_map<std::string, hilum_mtmd *> g_mtmd_contexts;
 static std::unordered_map<std::string, hilum_emb_ctx *> g_emb_contexts;
 
+using ModelOwner = std::shared_ptr<hilum_model>;
+static std::unordered_map<std::string, ModelOwner> g_model_owners;
+static std::unordered_map<std::string, std::vector<ModelOwner>> g_context_model_owners;
+static std::unordered_map<std::string, ModelOwner> g_mtmd_model_owners;
+static std::unordered_map<std::string, ModelOwner> g_emb_model_owners;
+
 // ── Log state ────────────────────────────────────────────────────────────────
 
 static std::atomic<bool> g_log_events_enabled{false};
@@ -60,6 +67,29 @@ static std::mutex g_log_mutex;
 
 // ── JNI helpers ──────────────────────────────────────────────────────────────
 
+static JNIEnv *get_jni_env(JavaVM *jvm, bool &detach) {
+    detach = false;
+    if (!jvm) {
+        LOGE("Cannot access JNI environment: JavaVM is null");
+        return nullptr;
+    }
+
+    JNIEnv *env = nullptr;
+    const jint status = jvm->GetEnv(reinterpret_cast<void **>(&env), JNI_VERSION_1_6);
+    if (status == JNI_OK) return env;
+    if (status != JNI_EDETACHED) {
+        LOGE("Cannot access JNI environment: GetEnv returned %d", status);
+        return nullptr;
+    }
+    if (jvm->AttachCurrentThread(&env, nullptr) != JNI_OK) {
+        LOGE("Cannot access JNI environment: AttachCurrentThread failed");
+        return nullptr;
+    }
+
+    detach = true;
+    return env;
+}
+
 static std::string jstring_to_std(JNIEnv *env, jstring jstr) {
     if (!jstr) return "";
     const char *chars = env->GetStringUTFChars(jstr, nullptr);
@@ -339,6 +369,7 @@ JNI_FN(nativeLoadModel)(JNIEnv *env, jobject thiz, jstring path, jobject options
     {
         std::lock_guard<std::mutex> lock(g_mutex);
         g_models[modelId] = model;
+        g_model_owners[modelId] = ModelOwner(model, hilum_model_free);
     }
     LOGI("Model loaded: %s", modelId.c_str());
     return std_to_jstring(env, modelId);
@@ -356,11 +387,15 @@ JNI_FN(nativeGetModelSize)(JNIEnv *env, jobject thiz, jstring modelId) {
 JNIEXPORT void JNICALL
 JNI_FN(nativeFreeModel)(JNIEnv *env, jobject thiz, jstring modelId) {
     std::string id = jstring_to_std(env, modelId);
-    std::lock_guard<std::mutex> lock(g_mutex);
-    auto it = g_models.find(id);
-    if (it != g_models.end()) {
-        hilum_model_free(it->second);
-        g_models.erase(it);
+    ModelOwner owner;
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        g_models.erase(id);
+        auto it = g_model_owners.find(id);
+        if (it != g_model_owners.end()) {
+            owner = std::move(it->second);
+            g_model_owners.erase(it);
+        }
     }
 }
 
@@ -373,6 +408,7 @@ JNI_FN(nativeCreateContext)(JNIEnv *env, jobject thiz, jstring modelId, jobject
     auto it = g_models.find(mid);
     if (it == g_models.end()) return std_to_jstring(env, "");
 
+    std::vector<ModelOwner> owners{g_model_owners[mid]};
     hilum_context_params params = hilum_context_default_params();
     if (options) {
         params.n_ctx        = (uint32_t)get_int_from_map(env, options, "n_ctx", params.n_ctx);
@@ -386,7 +422,10 @@ JNI_FN(nativeCreateContext)(JNIEnv *env, jobject thiz, jstring modelId, jobject
         std::string draftId = get_string_from_map(env, options, "draft_model_id");
         if (!draftId.empty()) {
             auto dit = g_models.find(draftId);
-            if (dit != g_models.end()) params.draft_model = dit->second;
+            if (dit != g_models.end()) {
+                params.draft_model = dit->second;
+                owners.push_back(g_model_owners[draftId]);
+            }
         }
     }
 
@@ -396,6 +435,7 @@ JNI_FN(nativeCreateContext)(JNIEnv *env, jobject thiz, jstring modelId, jobject
 
     std::string ctxId = generate_uuid();
     g_contexts[ctxId] = ctx;
+    g_context_model_owners[ctxId] = std::move(owners);
     return std_to_jstring(env, ctxId);
 }
 
@@ -411,12 +451,22 @@ JNI_FN(nativeGetContextSize)(JNIEnv *env, jobject thiz, jstring contextId) {
 JNIEXPORT void JNICALL
 JNI_FN(nativeFreeContext)(JNIEnv *env, jobject thiz, jstring contextId) {
     std::string id = jstring_to_std(env, contextId);
-    std::lock_guard<std::mutex> lock(g_mutex);
-    auto it = g_contexts.find(id);
-    if (it != g_contexts.end()) {
-        hilum_context_free(it->second);
-        g_contexts.erase(it);
+    hilum_context *context = nullptr;
+    std::vector<ModelOwner> owners;
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        auto it = g_contexts.find(id);
+        if (it != g_contexts.end()) {
+            context = it->second;
+            g_contexts.erase(it);
+        }
+        auto owner = g_context_model_owners.find(id);
+        if (owner != g_context_model_owners.end()) {
+            owners = std::move(owner->second);
+            g_context_model_owners.erase(owner);
+        }
     }
+    if (context) hilum_context_free(context);
 }
 
 // ── Warmup ───────────────────────────────────────────────────────────────────
@@ -638,12 +688,9 @@ JNI_FN(nativeStartStream)(JNIEnv *env, jobject thiz, jstring modelId, jstring co
         [](const char *token, int32_t token_len, void *ud) -> bool {
             auto *s = static_cast<StreamState *>(ud);
 
-            JNIEnv *env;
             bool detach = false;
-            if (s->jvm->GetEnv((void **)&env, JNI_VERSION_1_6) == JNI_EDETACHED) {
-                s->jvm->AttachCurrentThread(&env, nullptr);
-                detach = true;
-            }
+            JNIEnv *env = get_jni_env(s->jvm, detach);
+            if (!env) return false;
 
             jclass cls = env->GetObjectClass(s->moduleRef);
             jmethodID emitMethod = env->GetMethodID(cls, "emitToken",
@@ -823,6 +870,7 @@ JNI_FN(nativeLoadProjector)(JNIEnv *env, jobject thiz, jstring modelId,
 
     std::string mtmdId = generate_uuid();
     g_mtmd_contexts[mtmdId] = mtmd;
+    g_mtmd_model_owners[mtmdId] = g_model_owners[mid];
     return std_to_jstring(env, mtmdId);
 }
 
@@ -838,12 +886,22 @@ JNI_FN(nativeSupportVision)(JNIEnv *env, jobject thiz, jstring mtmdId) {
 JNIEXPORT void JNICALL
 JNI_FN(nativeFreeMtmdContext)(JNIEnv *env, jobject thiz, jstring mtmdId) {
     std::string id = jstring_to_std(env, mtmdId);
-    std::lock_guard<std::mutex> lock(g_mutex);
-    auto it = g_mtmd_contexts.find(id);
-    if (it != g_mtmd_contexts.end()) {
-        hilum_mtmd_free(it->second);
-        g_mtmd_contexts.erase(it);
+    hilum_mtmd *mtmd = nullptr;
+    ModelOwner owner;
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        auto it = g_mtmd_contexts.find(id);
+        if (it != g_mtmd_contexts.end()) {
+            mtmd = it->second;
+            g_mtmd_contexts.erase(it);
+        }
+        auto modelOwner = g_mtmd_model_owners.find(id);
+        if (modelOwner != g_mtmd_model_owners.end()) {
+            owner = std::move(modelOwner->second);
+            g_mtmd_model_owners.erase(modelOwner);
+        }
     }
+    if (mtmd) hilum_mtmd_free(mtmd);
 }
 
 JNIEXPORT jstring JNICALL
@@ -960,12 +1018,9 @@ JNI_FN(nativeStartStreamVision)(JNIEnv *env, jobject thiz, jstring modelId,
         [](const char *token, int32_t token_len, void *ud) -> bool {
             auto *s = static_cast<StreamState *>(ud);
 
-            JNIEnv *env;
             bool detach = false;
-            if (s->jvm->GetEnv((void **)&env, JNI_VERSION_1_6) == JNI_EDETACHED) {
-                s->jvm->AttachCurrentThread(&env, nullptr);
-                detach = true;
-            }
+            JNIEnv *env = get_jni_env(s->jvm, detach);
+            if (!env) return false;
 
             jclass cls = env->GetObjectClass(s->moduleRef);
             jmethodID emitMethod = env->GetMethodID(cls, "emitToken",
@@ -1043,9 +1098,31 @@ JNI_FN(nativeCreateEmbeddingContext)(JNIEnv *env, jobject thiz, jstring modelId,
 
     std::string ctxId = generate_uuid();
     g_emb_contexts[ctxId] = ectx;
+    g_emb_model_owners[ctxId] = g_model_owners[mid];
     return std_to_jstring(env, ctxId);
 }
 
+JNIEXPORT void JNICALL
+JNI_FN(nativeFreeEmbeddingContext)(JNIEnv *env, jobject thiz, jstring contextId) {
+    std::string id = jstring_to_std(env, contextId);
+    hilum_emb_ctx *context = nullptr;
+    ModelOwner owner;
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        auto it = g_emb_contexts.find(id);
+        if (it != g_emb_contexts.end()) {
+            context = it->second;
+            g_emb_contexts.erase(it);
+        }
+        auto modelOwner = g_emb_model_owners.find(id);
+        if (modelOwner != g_emb_model_owners.end()) {
+            owner = std::move(modelOwner->second);
+            g_emb_model_owners.erase(modelOwner);
+        }
+    }
+    if (context) hilum_emb_context_free(context);
+}
+
 JNIEXPORT jobject JNICALL
 JNI_FN(nativeEmbed)(JNIEnv *env, jobject thiz, jstring contextId, jstring modelId,
                      jobject tokens) {
@@ -1174,10 +1251,10 @@ JNI_FN(nativeStartBatch)(JNIEnv *env, jobject thiz, jstring modelId, jstring con
         if (mi == g_models.end() || ci == g_contexts.end()) {
             jclass cls = env->GetObjectClass(thiz);
             jmethodID emitMethod = env->GetMethodID(cls, "emitBatchToken",
-                "(Ljava/lang/String;ILjava/lang/String;ZLjava/lang/String;)V");
+                "(Ljava/lang/String;ILjava/lang/String;ZLjava/lang/String;Ljava/lang/String;)V");
             jstring jcid = std_to_jstring(env, cid);
             jstring jerr = env->NewStringUTF("Not found");
-            env->CallVoidMethod(thiz, emitMethod, jcid, -1, nullptr, JNI_TRUE, jerr);
+            env->CallVoidMethod(thiz, emitMethod, jcid, -1, nullptr, JNI_TRUE, nullptr, jerr);
             env->DeleteLocalRef(jcid);
             env->DeleteLocalRef(jerr);
             env->DeleteLocalRef(cls);
@@ -1208,32 +1285,29 @@ JNI_FN(nativeStartBatch)(JNIEnv *env, jobject thiz, jstring modelId, jstring con
     };
     BatchState *state = new BatchState{moduleRef, cid, g_jvm};
 
-    hilum_generate_batch(model, ctx, prompt_ptrs.data(), n_seqs, gc.params,
+    hilum_error batchErr = hilum_generate_batch(model, ctx, prompt_ptrs.data(), n_seqs, gc.params,
         [](hilum_batch_event event, void *ud) -> bool {
             auto *s = static_cast<BatchState *>(ud);
 
-            JNIEnv *env;
             bool detach = false;
-            if (s->jvm->GetEnv((void **)&env, JNI_VERSION_1_6) == JNI_EDETACHED) {
-                s->jvm->AttachCurrentThread(&env, nullptr);
-                detach = true;
-            }
+            JNIEnv *env = get_jni_env(s->jvm, detach);
+            if (!env) return false;
 
             jclass cls = env->GetObjectClass(s->moduleRef);
             jmethodID emitMethod = env->GetMethodID(cls, "emitBatchToken",
-                "(Ljava/lang/String;ILjava/lang/String;ZLjava/lang/String;)V");
+                "(Ljava/lang/String;ILjava/lang/String;ZLjava/lang/String;Ljava/lang/String;)V");
             jstring jcid = env->NewStringUTF(s->ctxId.c_str());
 
             if (event.done) {
                 jstring reason = event.finish_reason
                     ? env->NewStringUTF(event.finish_reason) : env->NewStringUTF("stop");
                 env->CallVoidMethod(s->moduleRef, emitMethod, jcid, event.seq_index,
-                    nullptr, JNI_TRUE, reason);
+                    nullptr, JNI_TRUE, reason, nullptr);
                 env->DeleteLocalRef(reason);
             } else {
                 jstring jtok = env->NewStringUTF(std::string(event.token, event.token_len).c_str());
                 env->CallVoidMethod(s->moduleRef, emitMethod, jcid, event.seq_index,
-                    jtok, JNI_FALSE, nullptr);
+                    jtok, JNI_FALSE, nullptr, nullptr);
                 env->DeleteLocalRef(jtok);
             }
             env->DeleteLocalRef(jcid);
@@ -1242,6 +1316,17 @@ JNI_FN(nativeStartBatch)(JNIEnv *env, jobject thiz, jstring modelId, jstring con
             if (detach) s->jvm->DetachCurrentThread();
             return true;
         }, state);
+    if (batchErr != HILUM_OK) {
+        jclass cls = env->GetObjectClass(thiz);
+        jmethodID emitMethod = env->GetMethodID(cls, "emitBatchToken",
+            "(Ljava/lang/String;ILjava/lang/String;ZLjava/lang/String;Ljava/lang/String;)V");
+        jstring jcid = std_to_jstring(env, cid);
+        jstring jerr = env->NewStringUTF(hilum_error_str(batchErr));
+        env->CallVoidMethod(thiz, emitMethod, jcid, -1, nullptr, JNI_TRUE, nullptr, jerr);
+        env->DeleteLocalRef(jcid);
+        env->DeleteLocalRef(jerr);
+        env->DeleteLocalRef(cls);
+    }
     env->DeleteGlobalRef(moduleRef);
     delete state;
 }
@@ -1297,12 +1382,9 @@ JNI_FN(nativeEnableLogEvents)(JNIEnv *env, jobject thiz, jboolean enabled) {
         hilum_log_set([](hilum_log_level level, const char *text, void *) {
             if (!g_log_events_enabled.load(std::memory_order_relaxed)) return;
 
-            JNIEnv *env;
             bool detach = false;
-            if (g_jvm->GetEnv((void **)&env, JNI_VERSION_1_6) == JNI_EDETACHED) {
-                g_jvm->AttachCurrentThread(&env, nullptr);
-                detach = true;
-            }
+            JNIEnv *env = get_jni_env(g_jvm, detach);
+            if (!env) return;
 
             std::lock_guard<std::mutex> lock(g_log_mutex);
             if (g_module_ref) {
@@ -1327,16 +1409,4 @@ JNI_FN(nativeEnableLogEvents)(JNIEnv *env, jobject thiz, jboolean enabled) {
     }
 }
 
-// ── Downloads (handled in Kotlin, JNI just provides storage path) ────────────
-
-JNIEXPORT jstring JNICALL
-JNI_FN(nativeGetModelStoragePath)(JNIEnv *env, jobject thiz, jstring filesDir) {
-    std::string dir = jstring_to_std(env, filesDir);
-    std::string path = dir + "/local-llm/models";
-    // Create directory if needed
-    std::string cmd = "mkdir -p " + path;
-    system(cmd.c_str());
-    return std_to_jstring(env, path);
-}
-
 } // extern "C"

package/android/src/main/java/com/hilum/localllm/LocalLLMModule.kt

@@ -21,12 +21,16 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
 
     /** Allowed root for file I/O — prevents reading/writing arbitrary paths. */
     private val allowedStorageRoot: String by lazy {
-        File(reactApplicationContext.filesDir, "local-llm").absolutePath
+        File(reactApplicationContext.filesDir, "local-llm").canonicalPath
     }
 
     private fun isPathAllowed(path: String): Boolean {
-        val resolved = File(path).canonicalPath
-        return resolved.startsWith(allowedStorageRoot)
+        return try {
+            val resolved = File(path).canonicalPath
+            resolved == allowedStorageRoot || resolved.startsWith(allowedStorageRoot + File.separator)
+        } catch (_: Exception) {
+            false
+        }
     }
 
     init {
@@ -50,13 +54,14 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
 
     @Suppress("unused")
     fun emitBatchToken(contextId: String, seqIndex: Int, token: String?,
-                       done: Boolean, finishReason: String?) {
+                       done: Boolean, finishReason: String?, error: String?) {
         val params = Arguments.createMap().apply {
             putString("contextId", contextId)
             putInt("seqIndex", seqIndex)
             putBoolean("done", done)
             if (token != null) putString("token", token)
             if (finishReason != null) putString("finishReason", finishReason)
+            if (error != null) putString("error", error)
         }
         sendEvent("onBatchToken", params)
     }
@@ -155,7 +160,9 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     override fun getModelSize(modelId: String): Double = nativeGetModelSize(modelId)
 
     @ReactMethod
-    override fun freeModel(modelId: String) { nativeFreeModel(modelId) }
+    override fun freeModel(modelId: String) {
+        executor.execute { nativeFreeModel(modelId) }
+    }
 
     // ── Context lifecycle ───────────────────────────────────────────────────
 
@@ -167,7 +174,9 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     override fun getContextSize(contextId: String): Double = nativeGetContextSize(contextId).toDouble()
 
     @ReactMethod
-    override fun freeContext(contextId: String) { nativeFreeContext(contextId) }
+    override fun freeContext(contextId: String) {
+        executor.execute { nativeFreeContext(contextId) }
+    }
 
     // ── Warmup ──────────────────────────────────────────────────────────────
 
@@ -298,7 +307,9 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     override fun supportVision(mtmdId: String): Boolean = nativeSupportVision(mtmdId)
 
     @ReactMethod
-    override fun freeMtmdContext(mtmdId: String) { nativeFreeMtmdContext(mtmdId) }
+    override fun freeMtmdContext(mtmdId: String) {
+        executor.execute { nativeFreeMtmdContext(mtmdId) }
+    }
 
     @ReactMethod
     override fun generateVision(modelId: String, contextId: String, mtmdId: String,
@@ -340,6 +351,11 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     override fun createEmbeddingContext(modelId: String, options: ReadableMap): String =
         nativeCreateEmbeddingContext(modelId, options.toHashMap())
 
+    @ReactMethod
+    override fun freeEmbeddingContext(contextId: String) {
+        executor.execute { nativeFreeEmbeddingContext(contextId) }
+    }
+
     @ReactMethod(isBlockingSynchronousMethod = true)
     override fun embed(contextId: String, modelId: String, tokens: ReadableArray): WritableArray {
         val tokenList = ArrayList<Int>()
@@ -402,6 +418,10 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     private val activeDownloads = java.util.concurrent.ConcurrentHashMap<String, Thread>()
 
     private fun executeDownload(url: String, destPath: String, resumeFrom: Long) {
+        if (!isPathAllowed(destPath)) {
+            emitDownloadError(url, "Destination is outside local-llm storage", false)
+            return
+        }
         val thread = Thread {
             try {
                 val destFile = File(destPath)
@@ -472,6 +492,10 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
 
     @ReactMethod
     override fun resumeDownload(url: String, destPath: String) {
+        if (!isPathAllowed(destPath)) {
+            emitDownloadError(url, "Destination is outside local-llm storage", false)
+            return
+        }
         val destFile = File(destPath)
         val existingBytes = if (destFile.exists()) destFile.length() else 0L
         executeDownload(url, destPath, existingBytes)
@@ -512,10 +536,11 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     }
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun fileExists(path: String): Boolean = File(path).exists()
+    override fun fileExists(path: String): Boolean = isPathAllowed(path) && File(path).exists()
 
     @ReactMethod(isBlockingSynchronousMethod = true)
-    override fun getFileSize(path: String): Double = File(path).length().toDouble()
+    override fun getFileSize(path: String): Double =
+        if (isPathAllowed(path)) File(path).length().toDouble() else 0.0
 
     @ReactMethod(isBlockingSynchronousMethod = true)
     override fun readTextFile(path: String): String? {
@@ -546,6 +571,10 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     override fun sha256File(path: String, promise: Promise) {
         executor.execute {
             try {
+                if (!isPathAllowed(path)) {
+                    promise.reject("E_INVALID_PATH", "Path is outside local-llm storage: $path")
+                    return@execute
+                }
                 val file = File(path)
                 if (!file.exists()) {
                     promise.reject("E_FILE_NOT_FOUND", "File not found: $path")
@@ -612,6 +641,7 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
     private external fun nativeGetEmbeddingDimension(modelId: String): Int
     private external fun nativeCreateEmbeddingContext(modelId: String,
                                                       options: HashMap<String, Any?>): String
+    private external fun nativeFreeEmbeddingContext(contextId: String)
     private external fun nativeEmbed(contextId: String, modelId: String,
                                       tokens: ArrayList<Int>): List<Any>
     private external fun nativeEmbedBatch(contextId: String, modelId: String,
@@ -623,5 +653,4 @@ class LocalLLMModule(reactContext: ReactApplicationContext) :
                                          options: HashMap<String, Any?>)
     private external fun nativeSetLogLevel(level: Int)
     private external fun nativeEnableLogEvents(enabled: Boolean)
-    private external fun nativeGetModelStoragePath(filesDir: String): String
 }

package/cpp/hilum/hilum_llm.cpp

@@ -313,14 +313,25 @@ static void evict_sampler_cache(llama_context * ctx) {
 
 /* ── Logging ───────────────────────────────────────────────────────────────── */
 
+static std::mutex         g_log_mutex;
+static std::mutex         g_log_set_mutex;
 static hilum_log_callback g_log_cb = nullptr;
 static void *             g_log_ud = nullptr;
 static std::atomic<int>   g_log_min_level{0};
 
 static void native_log_callback(enum ggml_log_level level, const char * text, void * /*ud*/) {
-    if (!g_log_cb) return;
     if (static_cast<int>(level) < g_log_min_level.load(std::memory_order_relaxed)) return;
-    g_log_cb(static_cast<hilum_log_level>(level), text, g_log_ud);
+
+    hilum_log_callback callback;
+    void * user_data;
+    {
+        std::lock_guard<std::mutex> lock(g_log_mutex);
+        callback = g_log_cb;
+        user_data = g_log_ud;
+    }
+    if (callback) {
+        callback(static_cast<hilum_log_level>(level), text, user_data);
+    }
 }
 
 /* ── Helpers ───────────────────────────────────────────────────────────────── */
@@ -391,8 +402,15 @@ HILUM_API const char * hilum_backend_info(void) {
     return llama_print_system_info();
 }
 
+#define HILUM_STRINGIFY_INNER(value) #value
+#define HILUM_STRINGIFY(value) HILUM_STRINGIFY_INNER(value)
+
 HILUM_API const char * hilum_backend_version(void) {
-    return "hilum-llm v1.0.0 (hilum-local-llm-engine)";
+    return "hilum-llm v"
+        HILUM_STRINGIFY(HILUM_API_VERSION_MAJOR) "."
+        HILUM_STRINGIFY(HILUM_API_VERSION_MINOR) "."
+        HILUM_STRINGIFY(HILUM_API_VERSION_PATCH)
+        " (hilum-local-llm-engine)";
 }
 
 HILUM_API uint32_t hilum_api_version(void) {
@@ -1725,6 +1743,7 @@ HILUM_API hilum_error hilum_generate_batch(
 
     // 2. Create one sampler per sequence
     std::vector<llama_sampler *> samplers(n_prompts);
+    std::vector<llama_token> first_tokens(n_prompts, LLAMA_TOKEN_NULL);
     const SamplerParams batch_sampler_params = to_sampler_params(params);
     for (int32_t i = 0; i < n_prompts; i++) {
         samplers[i] = create_sampler(
@@ -1754,6 +1773,7 @@ HILUM_API hilum_error hilum_generate_batch(
         for (size_t offset = 0; offset < entries.size(); offset += n_batch_size) {
             size_t chunk_end = std::min(entries.size(), offset + static_cast<size_t>(n_batch_size));
             int32_t chunk_size = static_cast<int32_t>(chunk_end - offset);
+            std::vector<std::pair<int32_t, int32_t>> logit_entries;
 
             llama_batch batch = llama_batch_init(chunk_size, 0, n_prompts);
             for (int32_t i = 0; i < chunk_size; i++) {
@@ -1763,24 +1783,28 @@ HILUM_API hilum_error hilum_generate_batch(
                 batch.n_seq_id[i]  = 1;
                 batch.seq_id[i][0] = e.seq_id;
 
+                batch.logits[i] = e.logits ? 1 : 0;
                 if (e.logits) {
-                    bool is_last = true;
-                    for (size_t j = offset + i + 1; j < entries.size(); j++) {
-                        if (entries[j].seq_id == e.seq_id) { is_last = false; break; }
-                    }
-                    batch.logits[i] = is_last ? 1 : 0;
-                } else {
-                    batch.logits[i] = 0;
+                    logit_entries.emplace_back(static_cast<int32_t>(e.seq_id), i);
                 }
             }
             batch.n_tokens = chunk_size;
 
             int32_t ret = llama_decode(ctx->llm, batch);
-            llama_batch_free(batch);
             if (ret != 0) {
+                llama_batch_free(batch);
                 for (auto * s : samplers) llama_sampler_free(s);
                 return HILUM_ERR_DECODE_FAILED;
             }
+
+            // llama_decode only retains logits from the most recent call. Sample
+            // every sequence whose terminal prompt token was decoded in this
+            // chunk before a later chunk can replace those output rows.
+            for (const auto & [seq, batch_index] : logit_entries) {
+                first_tokens[seq] = llama_sampler_sample(
+                    samplers[seq], ctx->llm, batch_index);
+            }
+            llama_batch_free(batch);
         }
     }
 
@@ -1791,7 +1815,11 @@ HILUM_API hilum_error hilum_generate_batch(
 
     // First token for each sequence
     for (int32_t s = 0; s < n_prompts; s++) {
-        llama_token token = llama_sampler_sample(samplers[s], ctx->llm, -1);
+        llama_token token = first_tokens[s];
+        if (token == LLAMA_TOKEN_NULL) {
+            for (auto * sampler : samplers) llama_sampler_free(sampler);
+            return HILUM_ERR_DECODE_FAILED;
+        }
         if (token == eos) {
             seq_done[s] = true;
             n_active--;
@@ -1813,6 +1841,11 @@ HILUM_API hilum_error hilum_generate_batch(
             n_active--;
             hilum_batch_event done_ev{s, nullptr, 0, true, "cancelled"};
             callback(done_ev, user_data);
+        } else if (seq_generated[s] >= params.max_tokens) {
+            seq_done[s] = true;
+            n_active--;
+            hilum_batch_event done_ev{s, nullptr, 0, true, "length"};
+            callback(done_ev, user_data);
         }
     }
 
@@ -1839,7 +1872,10 @@ HILUM_API hilum_error hilum_generate_batch(
 
         int32_t ret = llama_decode(ctx->llm, batch);
         llama_batch_free(batch);
-        if (ret != 0) break;
+        if (ret != 0) {
+            for (auto * sampler : samplers) llama_sampler_free(sampler);
+            return HILUM_ERR_DECODE_FAILED;
+        }
 
         for (int32_t i = 0; i < batch_count; i++) {
             int32_t s = active_seqs[i];
@@ -1939,14 +1975,13 @@ HILUM_API hilum_error hilum_quantize(
 /* ── Logging ───────────────────────────────────────────────────────────────── */
 
 HILUM_API void hilum_log_set(hilum_log_callback callback, void * user_data) {
-    if (g_log_cb) {
-        llama_log_set(nullptr, nullptr);
-    }
-    g_log_cb = callback;
-    g_log_ud = user_data;
-    if (callback) {
-        llama_log_set(native_log_callback, nullptr);
+    std::lock_guard<std::mutex> set_lock(g_log_set_mutex);
+    {
+        std::lock_guard<std::mutex> lock(g_log_mutex);
+        g_log_cb = callback;
+        g_log_ud = user_data;
     }
+    llama_log_set(callback ? native_log_callback : nullptr, nullptr);
 }
 
 HILUM_API void hilum_log_set_level(hilum_log_level min_level) {

package/cpp/hilum/hilum_llm.h

@@ -30,7 +30,7 @@
  */
 #define HILUM_API_VERSION_MAJOR 1
 #define HILUM_API_VERSION_MINOR 0
-#define HILUM_API_VERSION_PATCH 0
+#define HILUM_API_VERSION_PATCH 1
 #define HILUM_API_VERSION \
     ((uint32_t)(((HILUM_API_VERSION_MAJOR) << 16) | ((HILUM_API_VERSION_MINOR) << 8) | (HILUM_API_VERSION_PATCH)))
 
@@ -38,14 +38,16 @@
 #include <stdbool.h>
 #include <stddef.h>
 
-#ifdef _WIN32
-#  ifdef HILUM_BUILD
+#if defined(_WIN32) && defined(HILUM_SHARED)
+#  if defined(HILUM_BUILD)
 #    define HILUM_API __declspec(dllexport)
 #  else
 #    define HILUM_API __declspec(dllimport)
 #  endif
-#else
+#elif !defined(_WIN32)
 #  define HILUM_API __attribute__((visibility("default")))
+#else
+#  define HILUM_API
 #endif
 
 #ifdef __cplusplus

package/ios/LocalLLM.mm

@@ -16,6 +16,7 @@
 
 #include <string>
 #include <unordered_map>
+#include <memory>
 #include <mutex>
 #include <atomic>
 
@@ -25,10 +26,6 @@
 #import <os/proc.h>
 #import <CommonCrypto/CommonDigest.h>
 
-#ifdef RCT_NEW_ARCH_ENABLED
-#import <memory>
-#endif
-
 // ── UUID generation ──────────────────────────────────────────────────────────
 
 static NSString *generateUUID() {
@@ -50,9 +47,11 @@ static NSString *allowedStorageRoot() {
 /// Returns YES if the path is under the allowed storage root (Application Support/local-llm/).
 /// This prevents callers from reading/writing arbitrary filesystem locations.
 static BOOL isPathAllowed(NSString *path) {
-  NSString *resolved = [path stringByStandardizingPath];
-  NSString *root = [allowedStorageRoot() stringByStandardizingPath];
-  return [resolved hasPrefix:root];
+  NSString *resolved = [[path stringByStandardizingPath] stringByResolvingSymlinksInPath];
+  NSString *root = [[allowedStorageRoot() stringByStandardizingPath]
+      stringByResolvingSymlinksInPath];
+  NSString *rootPrefix = [root stringByAppendingString:@"/"];
+  return [resolved isEqualToString:root] || [resolved hasPrefix:rootPrefix];
 }
 
 // ── Handle maps ──────────────────────────────────────────────────────────────
@@ -64,6 +63,12 @@ static std::unordered_map<std::string, hilum_context *> g_contexts;
 static std::unordered_map<std::string, hilum_mtmd *> g_mtmd_contexts;
 static std::unordered_map<std::string, hilum_emb_ctx *> g_emb_contexts;
 
+using ModelOwner = std::shared_ptr<hilum_model>;
+static std::unordered_map<std::string, ModelOwner> g_model_owners;
+static std::unordered_map<std::string, std::vector<ModelOwner>> g_context_model_owners;
+static std::unordered_map<std::string, ModelOwner> g_mtmd_model_owners;
+static std::unordered_map<std::string, ModelOwner> g_emb_model_owners;
+
 // ── Log state ────────────────────────────────────────────────────────────────
 
 static std::atomic<bool> g_log_events_enabled{false};
@@ -303,7 +308,9 @@ RCT_EXPORT_METHOD(loadModel:(NSString *)path
     NSString *modelId = generateUUID();
     {
       std::lock_guard<std::mutex> lock(g_mutex);
-      g_models[[modelId UTF8String]] = model;
+      const std::string id = [modelId UTF8String];
+      g_models[id] = model;
+      g_model_owners[id] = ModelOwner(model, hilum_model_free);
     }
     resolve(modelId);
   });
@@ -317,12 +324,19 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getModelSize:(NSString *)modelId) {
 }
 
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(freeModel:(NSString *)modelId) {
-  std::lock_guard<std::mutex> lock(g_mutex);
-  auto it = g_models.find([modelId UTF8String]);
-  if (it != g_models.end()) {
-    hilum_model_free(it->second);
-    g_models.erase(it);
-  }
+  dispatch_async(inference_queue(), ^{
+    ModelOwner owner;
+    {
+      std::lock_guard<std::mutex> lock(g_mutex);
+      const std::string id = [modelId UTF8String];
+      g_models.erase(id);
+      auto it = g_model_owners.find(id);
+      if (it != g_model_owners.end()) {
+        owner = std::move(it->second);
+        g_model_owners.erase(it);
+      }
+    }
+  });
   return nil;
 }
 
@@ -354,7 +368,15 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(createContext:(NSString *)modelId
   if (err != HILUM_OK) return @"";
 
   NSString *ctxId = generateUUID();
-  g_contexts[[ctxId UTF8String]] = ctx;
+  const std::string contextKey = [ctxId UTF8String];
+  g_contexts[contextKey] = ctx;
+  auto & owners = g_context_model_owners[contextKey];
+  owners.push_back(g_model_owners[[modelId UTF8String]]);
+  if (options[@"draft_model_id"]) {
+    const std::string draftKey = [options[@"draft_model_id"] UTF8String];
+    auto owner = g_model_owners.find(draftKey);
+    if (owner != g_model_owners.end()) owners.push_back(owner->second);
+  }
   return ctxId;
 }
 
@@ -366,12 +388,27 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getContextSize:(NSString *)contextId) {
 }
 
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(freeContext:(NSString *)contextId) {
-  std::lock_guard<std::mutex> lock(g_mutex);
-  auto it = g_contexts.find([contextId UTF8String]);
-  if (it != g_contexts.end()) {
-    hilum_context_free(it->second);
-    g_contexts.erase(it);
-  }
+  dispatch_async(inference_queue(), ^{
+    hilum_context *context = nullptr;
+    std::vector<ModelOwner> owners;
+    {
+      std::lock_guard<std::mutex> lock(g_mutex);
+      const std::string id = [contextId UTF8String];
+      auto it = g_contexts.find(id);
+      if (it != g_contexts.end()) {
+        context = it->second;
+        g_contexts.erase(it);
+      }
+      auto owner = g_context_model_owners.find(id);
+      if (owner != g_context_model_owners.end()) {
+        owners = std::move(owner->second);
+        g_context_model_owners.erase(owner);
+      }
+    }
+    if (context) {
+      hilum_context_free(context);
+    }
+  });
   return nil;
 }
 
@@ -663,7 +700,9 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(loadProjector:(NSString *)modelId
   if (err != HILUM_OK) return @"";
 
   NSString *mtmdId = generateUUID();
-  g_mtmd_contexts[[mtmdId UTF8String]] = mtmd;
+  const std::string mtmdKey = [mtmdId UTF8String];
+  g_mtmd_contexts[mtmdKey] = mtmd;
+  g_mtmd_model_owners[mtmdKey] = g_model_owners[[modelId UTF8String]];
   return mtmdId;
 }
 
@@ -675,12 +714,27 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(supportVision:(NSString *)mtmdId) {
 }
 
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(freeMtmdContext:(NSString *)mtmdId) {
-  std::lock_guard<std::mutex> lock(g_mutex);
-  auto it = g_mtmd_contexts.find([mtmdId UTF8String]);
-  if (it != g_mtmd_contexts.end()) {
-    hilum_mtmd_free(it->second);
-    g_mtmd_contexts.erase(it);
-  }
+  dispatch_async(inference_queue(), ^{
+    hilum_mtmd *mtmd = nullptr;
+    ModelOwner owner;
+    {
+      std::lock_guard<std::mutex> lock(g_mutex);
+      const std::string id = [mtmdId UTF8String];
+      auto it = g_mtmd_contexts.find(id);
+      if (it != g_mtmd_contexts.end()) {
+        mtmd = it->second;
+        g_mtmd_contexts.erase(it);
+      }
+      auto modelOwner = g_mtmd_model_owners.find(id);
+      if (modelOwner != g_mtmd_model_owners.end()) {
+        owner = std::move(modelOwner->second);
+        g_mtmd_model_owners.erase(modelOwner);
+      }
+    }
+    if (mtmd) {
+      hilum_mtmd_free(mtmd);
+    }
+  });
   return nil;
 }
 
@@ -848,10 +902,37 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(createEmbeddingContext:(NSString *)modelI
   if (err != HILUM_OK) return @"";
 
   NSString *ctxId = generateUUID();
-  g_emb_contexts[[ctxId UTF8String]] = ectx;
+  const std::string contextKey = [ctxId UTF8String];
+  g_emb_contexts[contextKey] = ectx;
+  g_emb_model_owners[contextKey] = g_model_owners[[modelId UTF8String]];
   return ctxId;
 }
 
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(freeEmbeddingContext:(NSString *)contextId) {
+  dispatch_async(inference_queue(), ^{
+    hilum_emb_ctx *context = nullptr;
+    ModelOwner owner;
+    {
+      std::lock_guard<std::mutex> lock(g_mutex);
+      const std::string id = [contextId UTF8String];
+      auto it = g_emb_contexts.find(id);
+      if (it != g_emb_contexts.end()) {
+        context = it->second;
+        g_emb_contexts.erase(it);
+      }
+      auto modelOwner = g_emb_model_owners.find(id);
+      if (modelOwner != g_emb_model_owners.end()) {
+        owner = std::move(modelOwner->second);
+        g_emb_model_owners.erase(modelOwner);
+      }
+    }
+    if (context) {
+      hilum_emb_context_free(context);
+    }
+  });
+  return nil;
+}
+
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(embed:(NSString *)contextId
                                       modelId:(NSString *)modelId
                                        tokens:(NSArray<NSNumber *> *)tokens) {
@@ -957,7 +1038,7 @@ RCT_EXPORT_METHOD(startBatch:(NSString *)modelId
     };
     BatchState state = { self, contextId };
 
-    hilum_generate_batch(model, ctx, prompt_ptrs.data(), n_seqs, gc.params,
+    hilum_error batchError = hilum_generate_batch(model, ctx, prompt_ptrs.data(), n_seqs, gc.params,
       [](hilum_batch_event event, void *ud) -> bool {
         auto *s = static_cast<BatchState *>(ud);
         if (event.done) {
@@ -977,6 +1058,12 @@ RCT_EXPORT_METHOD(startBatch:(NSString *)modelId
         }
         return true;
       }, &state);
+    if (batchError != HILUM_OK) {
+      [self sendEventWithName:@"onBatchToken" body:@{
+        @"contextId": contextId, @"done": @YES, @"error": @(hilum_error_str(batchError)),
+        @"seqIndex": @(-1)
+      }];
+    }
   });
 }
 
@@ -1033,6 +1120,12 @@ RCT_EXPORT_METHOD(enableLogEvents:(BOOL)enabled) {
 // ── Downloads ────────────────────────────────────────────────────────────────
 
 RCT_EXPORT_METHOD(downloadModel:(NSString *)url destPath:(NSString *)destPath) {
+  if (!isPathAllowed(destPath)) {
+    [self sendEventWithName:@"onDownloadError" body:@{
+      @"url": url ?: @"", @"error": @"Destination is outside local-llm storage", @"resumable": @NO
+    }];
+    return;
+  }
   NSURL *nsUrl = [NSURL URLWithString:url];
   if (!nsUrl) return;
   _downloadDelegate.destPaths[url] = destPath;
@@ -1041,6 +1134,12 @@ RCT_EXPORT_METHOD(downloadModel:(NSString *)url destPath:(NSString *)destPath) {
 }
 
 RCT_EXPORT_METHOD(resumeDownload:(NSString *)url destPath:(NSString *)destPath) {
+  if (!isPathAllowed(destPath)) {
+    [self sendEventWithName:@"onDownloadError" body:@{
+      @"url": url ?: @"", @"error": @"Destination is outside local-llm storage", @"resumable": @NO
+    }];
+    return;
+  }
   NSData *data = _downloadDelegate.resumeData[url];
   _downloadDelegate.destPaths[url] = destPath;
   if (data) {
@@ -1118,10 +1217,12 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getModelStoragePath) {
 }
 
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(fileExists:(NSString *)path) {
+  if (!isPathAllowed(path)) return @(NO);
   return @([[NSFileManager defaultManager] fileExistsAtPath:path]);
 }
 
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getFileSize:(NSString *)path) {
+  if (!isPathAllowed(path)) return @0;
   NSDictionary *attrs = [[NSFileManager defaultManager] attributesOfItemAtPath:path error:nil];
   NSNumber *size = attrs[NSFileSize];
   return size ?: @0;
@@ -1159,6 +1260,10 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(removePath:(NSString *)path) {
 RCT_EXPORT_METHOD(sha256File:(NSString *)path
                       resolve:(RCTPromiseResolveBlock)resolve
                        reject:(RCTPromiseRejectBlock)reject) {
+  if (!isPathAllowed(path)) {
+    reject(@"E_INVALID_PATH", @"Path is outside local-llm storage", nil);
+    return;
+  }
   dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
     NSInputStream *stream = [NSInputStream inputStreamWithFileAtPath:path];
     if (!stream) {

package/local-llm-rn.podspec

@@ -1,11 +1,15 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
 Pod::Spec.new do |s|
   s.name         = "local-llm-rn"
-  s.version      = "0.1.0"
+  s.version      = package["version"]
   s.summary      = "Local LLM inference for React Native"
   s.homepage     = "https://github.com/hilum-labs/local-llm-rn"
   s.license      = { :type => "MIT", :file => "LICENSE" }
   s.author       = "Hilum Labs"
-  s.source       = { :git => "https://github.com/hilum-labs/local-llm-rn.git", :tag => s.version.to_s }
+  s.source       = { :git => "https://github.com/hilum-labs/local-llm-rn.git", :tag => "v#{s.version}" }
   s.platforms    = { :ios => "16.0" }
 
   # Only the RN bridge (ios/) needs ARC; ggml Metal .m files use manual retain/release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-llm-rn",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "packageManager": "pnpm@10.29.2",
   "description": "On-device LLM inference for React Native with Metal (iOS) and Vulkan (Android) GPU acceleration",
   "main": "src/index.ts",
@@ -20,6 +20,8 @@
   ],
   "scripts": {
     "smoke:native-bridge": "vitest run tests/native-contract.test.ts tests/native-bridge.test.ts tests/local-llm.test.ts tests/vision.test.ts && bash scripts/verify-vendoring.sh",
+    "verify:core-version": "node scripts/verify-core-version.mjs",
+    "verify:release": "node scripts/validate-release.mjs",
     "verify:vendoring": "bash scripts/verify-vendoring.sh",
     "prepare": "bash scripts/prepare.sh",
     "prepack": "bash scripts/prepack.sh",
@@ -32,14 +34,32 @@
     "react-native": ">=0.76"
   },
   "dependencies": {
-    "local-llm-js-core": "0.2.1"
+    "local-llm-js-core": "0.3.0"
   },
   "devDependencies": {
     "@types/react": "^18.0.0",
     "react": "^18.0.0",
     "react-native": "^0.76.0",
     "typescript": "^5.5.0",
-    "vitest": "^4.0.18"
+    "vite": "7.3.5",
+    "vitest": "^4.1.10"
+  },
+  "pnpm": {
+    "overrides": {
+      "@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4": "7.29.7",
+      "@babel/core@<7.29.6": "7.29.7",
+      "brace-expansion@<2": "1.1.16",
+      "esbuild@<0.28.1": "0.28.1",
+      "js-yaml@<4": "3.15.0",
+      "node-forge@<=1.3.3": "1.4.0",
+      "picomatch@<3": "2.3.2",
+      "picomatch@>=4 <4.0.5": "4.0.5",
+      "shell-quote@<=1.8.3": "1.10.0",
+      "postcss@<8.5.10": "8.5.19",
+      "vite@>=7 <7.3.5": "7.3.5",
+      "ws@>=6 <7": "6.2.5",
+      "ws@>=7 <8": "7.5.12"
+    }
   },
   "codegenConfig": {
     "name": "LocalLLMSpec",

package/src/NativeLocalLLM.ts

@@ -57,6 +57,7 @@ export interface Spec extends TurboModule {
 
   getEmbeddingDimension(modelId: string): number;
   createEmbeddingContext(modelId: string, options: Object): string;
+  freeEmbeddingContext(contextId: string): void;
   embed(contextId: string, modelId: string, tokens: number[]): number[];
   embedBatch(contextId: string, modelId: string, tokenArrays: number[][]): number[][];
 

package/src/cache.ts

@@ -16,6 +16,25 @@ function joinPath(...parts: string[]): string {
     .join('/');
 }
 
+function normalizePath(path: string): string {
+  const absolute = path.startsWith('/');
+  const segments: string[] = [];
+
+  for (const segment of path.replace(/\\/g, '/').split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') {
+      if (segments.length === 0) {
+        throw new LocalLLMError(LocalLLMErrorCode.INVALID_PATH, `Path "${path}" escapes its root`);
+      }
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+
+  return `${absolute ? '/' : ''}${segments.join('/')}` || (absolute ? '/' : '.');
+}
+
 export class ModelCache implements ModelRegistry {
   readonly cacheDir: string;
   private indexPath: string;
@@ -27,8 +46,9 @@ export class ModelCache implements ModelRegistry {
 
   /** Ensure a path is within the cache directory to prevent path traversal. */
   private assertSafePath(path: string): void {
-    const normalized = path.replace(/\/+/g, '/').replace(/\/\.\.\//g, '/');
-    if (!normalized.startsWith(this.cacheDir)) {
+    const normalized = normalizePath(path);
+    const cacheRoot = normalizePath(this.cacheDir).replace(/\/$/, '');
+    if (normalized !== cacheRoot && !normalized.startsWith(`${cacheRoot}/`)) {
       throw new LocalLLMError(
         LocalLLMErrorCode.INVALID_PATH,
         `Path "${path}" is outside the cache directory "${this.cacheDir}"`,

package/src/model-manager.ts

@@ -35,7 +35,19 @@ export class ModelManager {
   async downloadModel(url: string, options?: DownloadOptions): Promise<string> {
     const resolvedUrl = resolveModelUrl(url);
     const cached = await this.cache.getCachedModel(resolvedUrl);
-    if (cached) return cached.path;
+    if (cached) {
+      const actualSize = NativeLocalLLM.getFileSize(cached.path);
+      const expectedSize = options?.expectedSize ?? cached.size;
+      const sizeMatches = actualSize > 0 && actualSize === expectedSize;
+      const hashMatches = !options?.expectedSha256
+        || await NativeLocalLLM.sha256File(cached.path) === options.expectedSha256.toLowerCase();
+
+      if (sizeMatches && hashMatches) return cached.path;
+
+      // Never return a cache entry whose bytes no longer match its recorded or
+      // caller-provided integrity metadata. Remove it and perform a clean download.
+      await this.cache.removeModel(resolvedUrl);
+    }
 
     const targetPath = this.cache.targetPath(resolvedUrl);
     await this.downloader.download(resolvedUrl, targetPath, options?.onProgress);
@@ -48,7 +60,7 @@ export class ModelManager {
         `Downloaded file is empty: ${resolvedUrl}`,
       );
     }
-    if (options?.expectedSize && size !== options.expectedSize) {
+    if (options?.expectedSize !== undefined && size !== options.expectedSize) {
       NativeLocalLLM.removePath(targetPath);
       throw new LocalLLMError(
         LocalLLMErrorCode.DOWNLOAD_INTEGRITY_MISMATCH,

package/src/native-bridge.ts

@@ -1,6 +1,12 @@
 import NativeLocalLLM from './NativeLocalLLM';
 import { NativeEventEmitter, NativeModules } from 'react-native';
-import type { NativeAddon, NativeModel, NativeContext, NativeMtmdContext } from 'local-llm-js-core/native';
+import type {
+  NativeAddon,
+  NativeModel,
+  NativeContext,
+  NativeEmbeddingContext,
+  NativeMtmdContext,
+} from 'local-llm-js-core/native';
 import { getDeviceCapabilities } from './device';
 import { LocalLLMError, LocalLLMErrorCode } from './errors';
 
@@ -134,13 +140,20 @@ export function createReactNativeAddon(): NativeAddon {
 
     inferStream: (model, ctx, prompt, options, callback) => {
       const ctxId = unwrapId(ctx);
+      let settled = false;
       const sub = emitter.addListener('onToken', (event) => {
-        if (event.contextId !== ctxId) return;
-        if (event.error) { callback(new LocalLLMError(LocalLLMErrorCode.STREAM_FAILED, event.error), null); sub.remove(); return; }
-        if (event.done) { callback(null, null); sub.remove(); return; }
+        if (event.contextId !== ctxId || settled) return;
+        if (event.error) { settled = true; sub.remove(); callback(new LocalLLMError(LocalLLMErrorCode.STREAM_FAILED, event.error), null); return; }
+        if (event.done) { settled = true; sub.remove(); callback(null, null); return; }
         callback(null, event.token);
       });
-      NativeLocalLLM.startStream(unwrapId(model), ctxId, prompt, options ?? {});
+      try {
+        NativeLocalLLM.startStream(unwrapId(model), ctxId, prompt, options ?? {});
+      } catch (error) {
+        settled = true;
+        sub.remove();
+        callback(error instanceof Error ? error : new Error(String(error)), null);
+      }
     },
 
     createMtmdContext: (model, projectorPath, options) => {
@@ -160,15 +173,22 @@ export function createReactNativeAddon(): NativeAddon {
     inferStreamVision: (model, ctx, mtmdCtx, prompt, imageBuffers, options, callback) => {
       const ctxId = unwrapId(ctx);
       const base64s = imageBuffers.map((buf) => toBase64(buf));
+      let settled = false;
       const sub = emitter.addListener('onToken', (event) => {
-        if (event.contextId !== ctxId) return;
-        if (event.error) { callback(new LocalLLMError(LocalLLMErrorCode.VISION_FAILED, event.error), null); sub.remove(); return; }
-        if (event.done) { callback(null, null); sub.remove(); return; }
+        if (event.contextId !== ctxId || settled) return;
+        if (event.error) { settled = true; sub.remove(); callback(new LocalLLMError(LocalLLMErrorCode.VISION_FAILED, event.error), null); return; }
+        if (event.done) { settled = true; sub.remove(); callback(null, null); return; }
         callback(null, event.token);
       });
-      NativeLocalLLM.startStreamVision(
-        unwrapId(model), ctxId, unwrapId(mtmdCtx), prompt, base64s, options ?? {},
-      );
+      try {
+        NativeLocalLLM.startStreamVision(
+          unwrapId(model), ctxId, unwrapId(mtmdCtx), prompt, base64s, options ?? {},
+        );
+      } catch (error) {
+        settled = true;
+        sub.remove();
+        callback(error instanceof Error ? error : new Error(String(error)), null);
+      }
     },
 
     jsonSchemaToGrammar: (schemaJson) => NativeLocalLLM.jsonSchemaToGrammar(schemaJson),
@@ -176,8 +196,9 @@ export function createReactNativeAddon(): NativeAddon {
     getEmbeddingDimension: (model) => NativeLocalLLM.getEmbeddingDimension(unwrapId(model)),
     createEmbeddingContext: (model, options) => {
       const id = NativeLocalLLM.createEmbeddingContext(unwrapId(model), options ?? {});
-      return wrapId(id, 'NativeContext') as NativeContext;
+      return wrapId(id, 'NativeEmbeddingContext') as NativeEmbeddingContext;
     },
+    freeEmbeddingContext: (ctx) => NativeLocalLLM.freeEmbeddingContext(unwrapId(ctx)),
     embed: (ctx, model, tokens) => {
       const plain = tokens instanceof Int32Array ? Array.from(tokens) : tokens;
       return new Float32Array(NativeLocalLLM.embed(unwrapId(ctx), unwrapId(model), plain));
@@ -190,19 +211,34 @@ export function createReactNativeAddon(): NativeAddon {
 
     inferBatch: (model, ctx, prompts, options, callback) => {
       const ctxId = unwrapId(ctx);
-      let completedCount = 0;
+      const completedSequences = new Set<number>();
+      let settled = false;
       const sub = emitter.addListener('onBatchToken', (event) => {
-        if (event.contextId !== ctxId) return;
-        if (event.error) { callback(new LocalLLMError(LocalLLMErrorCode.INFERENCE_FAILED, event.error), null, event.seqIndex, null); return; }
+        if (event.contextId !== ctxId || settled) return;
+        if (event.error) {
+          settled = true;
+          sub.remove();
+          callback(new LocalLLMError(LocalLLMErrorCode.INFERENCE_FAILED, event.error), null, event.seqIndex, null);
+          return;
+        }
         if (event.done) {
+          completedSequences.add(event.seqIndex);
+          if (completedSequences.size >= prompts.length) {
+            settled = true;
+            sub.remove();
+          }
           callback(null, null, event.seqIndex, event.finishReason ?? null);
-          completedCount++;
-          if (completedCount >= prompts.length) sub.remove();
           return;
         }
         callback(null, event.token, event.seqIndex, null);
       });
-      NativeLocalLLM.startBatch(unwrapId(model), ctxId, prompts, options as any);
+      try {
+        NativeLocalLLM.startBatch(unwrapId(model), ctxId, prompts, options as any);
+      } catch (error) {
+        settled = true;
+        sub.remove();
+        callback(error instanceof Error ? error : new Error(String(error)), null, -1, null);
+      }
     },
 
     quantize: (inputPath, outputPath, options, callback) => {
@@ -210,7 +246,12 @@ export function createReactNativeAddon(): NativeAddon {
         sub.remove();
         callback(event.error ? new LocalLLMError(LocalLLMErrorCode.QUANTIZE_FAILED, event.error) : null);
       });
-      NativeLocalLLM.quantize(inputPath, outputPath, options);
+      try {
+        NativeLocalLLM.quantize(inputPath, outputPath, options);
+      } catch (error) {
+        sub.remove();
+        callback(error instanceof Error ? error : new Error(String(error)));
+      }
     },
 
     setLogCallback: (() => {

package/src/rn-downloader.ts

@@ -33,11 +33,16 @@ export function createNativeDownloader(): DownloadAdapter {
           }),
         ];
 
-        if (resumableUrls.has(url)) {
-          resumableUrls.delete(url);
-          NativeLocalLLM.resumeDownload(url, destPath);
-        } else {
-          NativeLocalLLM.downloadModel(url, destPath);
+        try {
+          if (resumableUrls.has(url)) {
+            resumableUrls.delete(url);
+            NativeLocalLLM.resumeDownload(url, destPath);
+          } else {
+            NativeLocalLLM.downloadModel(url, destPath);
+          }
+        } catch (error) {
+          subs.forEach((s) => s.remove());
+          reject(error instanceof Error ? error : new Error(String(error)));
         }
       });
     },