@taladb/react-native 0.8.3 → 0.9.0

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,3 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
 </manifest>

package/android/src/main/java/com/taladb/TalaDBModule.kt

@@ -51,7 +51,8 @@ class TalaDBModule(private val reactContext: ReactApplicationContext) :
      * JSI runtime identified by [jsContextNativePtr].
      * Called once from [initialize].
      */
-    private external fun nativeInstall(jsContextNativePtr: Long, dbPath: String, configJson: String?)
+    private external fun nativeInstall(jsContextNativePtr: Long, dbPath: String, configJson: String?): String?
+    private external fun nativeClose(jsContextNativePtr: Long)
 
     // -----------------------------------------------------------------------
     // TurboModule: initialize(dbName, configJson?) → Promise<void>
@@ -59,16 +60,33 @@ class TalaDBModule(private val reactContext: ReactApplicationContext) :
 
     override fun initialize(dbName: String, configJson: String?, promise: Promise) {
         try {
-            val dbPath = reactContext.filesDir.absolutePath + "/$dbName"
+            // Private app storage excluded from Android Auto Backup. The OS
+            // file-based-encryption layer protects it while the device is locked.
+            val dbFile = java.io.File(reactContext.noBackupFilesDir, dbName)
+            val legacyFile = java.io.File(reactContext.filesDir, dbName)
+            if (!dbFile.exists() && legacyFile.exists() && !legacyFile.renameTo(dbFile)) {
+                throw java.io.IOException("failed to migrate TalaDB into no-backup storage")
+            }
+            val legacySalt = java.io.File(legacyFile.absolutePath + ".taladb-salt")
+            val saltFile = java.io.File(dbFile.absolutePath + ".taladb-salt")
+            if (!saltFile.exists() && legacySalt.exists() && !legacySalt.renameTo(saltFile)) {
+                throw java.io.IOException("failed to migrate TalaDB encryption salt")
+            }
+            val dbPath = dbFile.absolutePath
 
             // javaScriptContextHolder.get() returns the raw jsi::Runtime* pointer.
             val jsContextPtr = reactContext.javaScriptContextHolder!!.get()
+            if (jsContextPtr == 0L) {
+                promise.reject("TALADB_NO_RUNTIME", "JSI runtime is not available")
+                return
+            }
 
             // Install on the JS thread
             reactContext.runOnJSQueueThread {
                 try {
-                    nativeInstall(jsContextPtr, dbPath, configJson)
-                    promise.resolve(null)
+                    val error = nativeInstall(jsContextPtr, dbPath, configJson)
+                    if (error == null) promise.resolve(null)
+                    else promise.reject("TALADB_INSTALL_ERROR", error)
                 } catch (e: Exception) {
                     promise.reject("TALADB_INSTALL_ERROR", e.message, e)
                 }
@@ -89,11 +107,8 @@ class TalaDBModule(private val reactContext: ReactApplicationContext) :
         try {
             reactContext.runOnJSQueueThread {
                 try {
-                    reactContext.javaScriptContextHolder?.let { holder ->
-                        // Setting the property to undefined lets the JSI
-                        // HostObject destructor run (Hermes GC permitting).
-                        // For an immediate close, call nativeClose() instead.
-                    }
+                    val ptr = reactContext.javaScriptContextHolder?.get() ?: 0L
+                    if (ptr != 0L) nativeClose(ptr)
                     promise.resolve(null)
                 } catch (e: Exception) {
                     promise.reject("TALADB_CLOSE_ERROR", e.message, e)

package/cpp/TalaDBHostObject.cpp

@@ -38,6 +38,7 @@ TalaDBHostObject::TalaDBHostObject(TalaDbHandle *db) : db_(db) {}
 
 TalaDBHostObject::~TalaDBHostObject() {
     if (db_) {
+        taladb_sync_flush(db_, 5000);
         taladb_close(db_);
         db_ = nullptr;
     }
@@ -244,12 +245,16 @@ std::vector<PropNameID> TalaDBHostObject::getPropertyNames(Runtime &rt) {
         "updateOne", "updateMany",
         "deleteOne", "deleteMany",
         "count",
+        "aggregate",
+        "exportChanges", "importChanges", "listCollectionNames",
         "createIndex", "dropIndex",
+        "createCompoundIndex", "dropCompoundIndex",
         "createFtsIndex", "dropFtsIndex",
         "createVectorIndex", "dropVectorIndex", "upgradeVectorIndex",
         "findNearest", "findNearestAsync",
         "findAsync",
         "compact",
+        "syncStatus", "flushSync",
         "close",
     };
     std::vector<PropNameID> result;
@@ -425,6 +430,69 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // aggregate(collection: string, pipeline: object[]): object[]
+    // ------------------------------------------------------------------
+    if (name == "aggregate") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "aggregate"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "aggregate requires 2 arguments");
+                auto col          = args[0].getString(rt).utf8(rt);
+                auto pipelineJson = stringify(rt, args[1]);
+                char *result      = taladb_aggregate(db_, col.c_str(), pipelineJson.c_str());
+                if (!result) throw JSError(rt, "taladb_aggregate failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // Bidirectional sync — exportChanges / importChanges / listCollectionNames
+    // (back JS db.sync(); the runtime-agnostic loop lives in taladb/src/sync.ts)
+    // ------------------------------------------------------------------
+    if (name == "exportChanges") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "exportChanges"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "exportChanges requires 2 arguments");
+                auto collectionsJson = stringify(rt, args[0]);   // string[] → JSON array
+                double sinceMs       = args[1].getNumber();
+                char *result = taladb_export_changes(db_, collectionsJson.c_str(), sinceMs);
+                if (!result) throw JSError(rt, "taladb_export_changes failed");
+                std::string json(result);
+                taladb_free_string(result);
+                // Return the changeset as an opaque string (not parsed) — the
+                // JS sync adapter passes it straight to the transport.
+                return String::createFromUtf8(rt, json);
+            });
+    }
+
+    if (name == "importChanges") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "importChanges"), 1,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "importChanges requires 1 argument");
+                auto changeset = args[0].getString(rt).utf8(rt);
+                int32_t n = taladb_import_changes(db_, changeset.c_str());
+                if (n < 0) throw JSError(rt, "taladb_import_changes failed");
+                return Value(static_cast<double>(n));
+            });
+    }
+
+    if (name == "listCollectionNames") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "listCollectionNames"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                char *result = taladb_list_collection_names(db_);
+                if (!result) throw JSError(rt, "taladb_list_collection_names failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);  // JSON array → JS string[]
+            });
+    }
+
     // ------------------------------------------------------------------
     // createIndex / dropIndex / createFtsIndex / dropFtsIndex
     // ------------------------------------------------------------------
@@ -444,6 +512,24 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // createCompoundIndex / dropCompoundIndex(collection, fields: string[]): void
+    // ------------------------------------------------------------------
+    if (name == "createCompoundIndex" || name == "dropCompoundIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forUtf8(rt, name), 2,
+            [this, name](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto fieldsJson = stringify(rt, args[1]);   // string[] → JSON array
+                if (name == "createCompoundIndex")
+                    taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                else
+                    taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                return Value::undefined();
+            });
+    }
+
     // ------------------------------------------------------------------
     // createVectorIndex(collection, field, dimensions, opts?): void
     //   opts: { metric?: 'cosine'|'dot'|'euclidean', hnsw?: HnswOptions }
@@ -604,6 +690,26 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    if (name == "syncStatus") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "syncStatus"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                char *raw = taladb_sync_status(db_);
+                if (!raw) throw ffiError(rt, "taladb_sync_status failed");
+                std::string json(raw); taladb_free_string(raw);
+                return parse(rt, json);
+            });
+    }
+
+    if (name == "flushSync") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "flushSync"), 1,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                uint64_t timeout = count && args[0].isNumber() ? (uint64_t)args[0].getNumber() : 5000;
+                return Value(taladb_sync_flush(db_, timeout) == 1);
+            });
+    }
+
     // ------------------------------------------------------------------
     // close(): void  (synchronous — the destructor does the real work)
     // ------------------------------------------------------------------
@@ -612,6 +718,7 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             rt, PropNameID::forAscii(rt, "close"), 0,
             [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
                 if (db_) {
+                    taladb_sync_flush(db_, 5000);
                     taladb_close(db_);
                     db_ = nullptr;
                 }

package/cpp/TalaDBJni.cpp

@@ -21,7 +21,7 @@
 
 using namespace facebook::jsi;
 
-extern "C" JNIEXPORT void JNICALL
+extern "C" JNIEXPORT jstring JNICALL
 Java_com_taladb_TalaDBModule_nativeInstall(
         JNIEnv  *env,
         jobject  /* thiz */,
@@ -29,6 +29,10 @@ Java_com_taladb_TalaDBModule_nativeInstall(
         jstring  dbPathJ,
         jstring  configJsonJ)
 {
+    // Release any previous HostObject before reopening the same redb file.
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
+
     // Resolve db path
     const char *dbPathC = env->GetStringUTFChars(dbPathJ, nullptr);
     std::string dbPath(dbPathC);
@@ -43,11 +47,18 @@ Java_com_taladb_TalaDBModule_nativeInstall(
     } else {
         db = taladb_open(dbPath.c_str());
     }
-    if (!db) return; // failed to open — JS will see no __TalaDB__ global
-
-    // Get the JSI runtime from the pointer passed by RN internals
-    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    if (!db) {
+        const char *error = taladb_last_error();
+        return env->NewStringUTF(error ? error : "failed to open TalaDB");
+    }
 
     // Install the JSI HostObject as global.__TalaDB__
     taladb::TalaDBHostObject::install(rt, db);
+    return nullptr;
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_taladb_TalaDBModule_nativeClose(JNIEnv *, jobject, jlong jsContextNativePtr) {
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
 }

package/cpp/taladb.h

@@ -141,6 +141,45 @@ int32_t taladb_count(TalaDbHandle *handle,
                      const char   *collection,
                      const char   *filter_json);
 
+/* -------------------------------------------------------------------------
+ * Aggregate
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Run an aggregation pipeline. pipeline_json is a JSON array of stages.
+ * Returns a JSON array of result documents, or NULL on error.
+ * Caller must free with taladb_free_string().
+ */
+char *taladb_aggregate(TalaDbHandle *handle,
+                       const char   *collection,
+                       const char   *pipeline_json);
+
+/* -------------------------------------------------------------------------
+ * Bidirectional sync — changeset export / import (backs JS db.sync())
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Export a changeset for the collections in collections_json (a JSON array of
+ * names) with changed_at > since_ms. Returns a JSON string, or NULL on error.
+ * Caller must free with taladb_free_string().
+ */
+char *taladb_export_changes(TalaDbHandle *handle,
+                            const char   *collections_json,
+                            double        since_ms);
+
+/**
+ * Merge a JSON changeset (from a remote peer) via Last-Write-Wins.
+ * Returns the number of documents changed, or -1 on error.
+ */
+int32_t taladb_import_changes(TalaDbHandle *handle,
+                              const char   *changeset_json);
+
+/**
+ * User collection names (reserved names excluded) as a JSON array string.
+ * Returns NULL on error. Caller must free with taladb_free_string().
+ */
+char *taladb_list_collection_names(TalaDbHandle *handle);
+
 /* -------------------------------------------------------------------------
  * Index management
  * ---------------------------------------------------------------------- */
@@ -150,6 +189,10 @@ void taladb_drop_index      (TalaDbHandle *handle, const char *collection, const
 void taladb_create_fts_index(TalaDbHandle *handle, const char *collection, const char *field);
 void taladb_drop_fts_index  (TalaDbHandle *handle, const char *collection, const char *field);
 
+/* Compound (multi-field) indexes. fields_json is a JSON array of field names. */
+void taladb_create_compound_index(TalaDbHandle *handle, const char *collection, const char *fields_json);
+void taladb_drop_compound_index  (TalaDbHandle *handle, const char *collection, const char *fields_json);
+
 /* -------------------------------------------------------------------------
  * Vector index management
  *
@@ -186,6 +229,9 @@ char *taladb_find_nearest(TalaDbHandle *handle,
                           size_t        top_k,
                           const char   *filter_json);
 
+char *taladb_sync_status(TalaDbHandle *handle);
+int32_t taladb_sync_flush(TalaDbHandle *handle, uint64_t timeout_ms);
+
 /* -------------------------------------------------------------------------
  * Async job API — run heavy queries on a background thread.
  *
@@ -195,11 +241,7 @@ char *taladb_find_nearest(TalaDbHandle *handle,
  *   while (taladb_job_poll(j) == 0) { } // yield to JS event loop
  *   char *json = taladb_job_take_result(j);         // frees the job
  *
- * Lifetime contract
- * -----------------
- * The handle passed to `*_start` MUST remain valid until the job has been
- * taken (via take_result) or cancelled (via cancel). The C++ HostObject
- * enforces this by not calling taladb_close while jobs are outstanding.
+ * Workers clone the Arc-backed database state and do not borrow the handle.
  * ---------------------------------------------------------------------- */
 
 typedef struct TalaDbJob TalaDbJob;

package/ios/TalaDB.mm

@@ -32,12 +32,6 @@
 
 using namespace facebook::jsi;
 
-// ---------------------------------------------------------------------------
-// Global handle — one database per process
-// ---------------------------------------------------------------------------
-
-static TalaDbHandle *gHandle = nullptr;
-
 // ---------------------------------------------------------------------------
 // TalaDB — Obj-C TurboModule
 // ---------------------------------------------------------------------------
@@ -51,27 +45,26 @@ RCT_EXPORT_MODULE(TalaDB)
 
 // ---- Class method: open DB and install the JSI HostObject ----------------
 
-+ (void)installInRuntime:(facebook::jsi::Runtime &)rt
++ (NSString * _Nullable)installInRuntime:(facebook::jsi::Runtime &)rt
                   dbPath:(NSString *)path
               configJson:(NSString * _Nullable)configJson {
-    if (gHandle) {
-        taladb_close(gHandle);
-        gHandle = nullptr;
-    }
-
+    // Release any previous HostObject before reopening the same redb file.
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
+    TalaDbHandle *handle = nullptr;
     if (configJson != nil) {
-        gHandle = taladb_open_with_config(path.UTF8String, configJson.UTF8String);
+        handle = taladb_open_with_config(path.UTF8String, configJson.UTF8String);
     } else {
-        gHandle = taladb_open(path.UTF8String);
+        handle = taladb_open(path.UTF8String);
     }
 
-    if (!gHandle) {
-        NSLog(@"[TalaDB] Failed to open database at %@", path);
-        return;
+    if (!handle) {
+        const char *raw = taladb_last_error();
+        return raw ? [NSString stringWithUTF8String:raw] : @"failed to open TalaDB";
     }
 
-    taladb::TalaDBHostObject::install(rt, gHandle);
+    taladb::TalaDBHostObject::install(rt, handle);
     NSLog(@"[TalaDB] Installed JSI HostObject — db: %@", path);
+    return nil;
 }
 
 // ---- initialize(dbName) → Promise<void>  ---------------------------------
@@ -81,9 +74,29 @@ RCT_EXPORT_METHOD(initialize:(NSString *)dbName
                   resolve:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject) {
     @try {
-        NSString *docs = [NSSearchPathForDirectoriesInDomains(
+        NSString *support = [NSSearchPathForDirectoriesInDomains(
+            NSApplicationSupportDirectory, NSUserDomainMask, YES) firstObject];
+        [[NSFileManager defaultManager] createDirectoryAtPath:support
+                                  withIntermediateDirectories:YES
+                                                   attributes:@{NSFileProtectionKey: NSFileProtectionCompleteUntilFirstUserAuthentication}
+                                                        error:nil];
+        NSString *dbPath = [support stringByAppendingPathComponent:dbName];
+        NSString *documents = [NSSearchPathForDirectoriesInDomains(
             NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
-        NSString *dbPath = [docs stringByAppendingPathComponent:dbName];
+        NSString *legacyPath = [documents stringByAppendingPathComponent:dbName];
+        if (![[NSFileManager defaultManager] fileExistsAtPath:dbPath] &&
+            [[NSFileManager defaultManager] fileExistsAtPath:legacyPath]) {
+            NSError *migrationError = nil;
+            if (![[NSFileManager defaultManager] moveItemAtPath:legacyPath toPath:dbPath error:&migrationError]) {
+                reject(@"TALADB_MIGRATION_ERROR", migrationError.localizedDescription, migrationError);
+                return;
+            }
+            NSString *legacySalt = [legacyPath stringByAppendingString:@".taladb-salt"];
+            NSString *newSalt = [dbPath stringByAppendingString:@".taladb-salt"];
+            if ([[NSFileManager defaultManager] fileExistsAtPath:legacySalt]) {
+                [[NSFileManager defaultManager] moveItemAtPath:legacySalt toPath:newSalt error:nil];
+            }
+        }
 
         RCTCxxBridge *bridge = (RCTCxxBridge *)[RCTBridge currentBridge];
         if (!bridge || !bridge.runtime) {
@@ -92,12 +105,22 @@ RCT_EXPORT_METHOD(initialize:(NSString *)dbName
         }
 
         // Install the HostObject on the JS thread
-        bridge.jsCallInvoker->invokeAsync([bridge, dbPath, configJson]() {
+        bridge.jsCallInvoker->invokeAsync([bridge, dbPath, configJson, resolve, reject]() {
             auto &rt = *(Runtime *)bridge.runtime;
-            [TalaDB installInRuntime:rt dbPath:dbPath configJson:configJson];
+            NSString *error = [TalaDB installInRuntime:rt dbPath:dbPath configJson:configJson];
+            if (error) reject(@"TALADB_INSTALL_ERROR", error, nil);
+            else {
+                NSDictionary *protection = @{NSFileProtectionKey: NSFileProtectionCompleteUntilFirstUserAuthentication};
+                [[NSFileManager defaultManager] setAttributes:protection ofItemAtPath:dbPath error:nil];
+                NSString *saltPath = [dbPath stringByAppendingString:@".taladb-salt"];
+                [[NSFileManager defaultManager] setAttributes:protection ofItemAtPath:saltPath error:nil];
+                NSURL *dbURL = [NSURL fileURLWithPath:dbPath];
+                [dbURL setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:nil];
+                NSURL *saltURL = [NSURL fileURLWithPath:saltPath];
+                [saltURL setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:nil];
+                resolve(nil);
+            }
         });
-
-        resolve(nil);
     } @catch (NSException *ex) {
         reject(@"TALADB_INIT_ERROR", ex.reason, nil);
     }
@@ -107,11 +130,16 @@ RCT_EXPORT_METHOD(initialize:(NSString *)dbName
 
 RCT_EXPORT_METHOD(close:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject) {
-    if (gHandle) {
-        taladb_close(gHandle);
-        gHandle = nullptr;
+    RCTCxxBridge *bridge = (RCTCxxBridge *)[RCTBridge currentBridge];
+    if (!bridge || !bridge.runtime) {
+        reject(@"TALADB_NO_BRIDGE", @"JSI bridge not available", nil);
+        return;
     }
-    resolve(nil);
+    bridge.jsCallInvoker->invokeAsync([bridge, resolve]() {
+        auto &rt = *(Runtime *)bridge.runtime;
+        rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
+        resolve(nil);
+    });
 }
 
 // ---- Synchronous stubs — all real work goes through the JSI HostObject ---

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/TalaDBHostObject.cpp

@@ -38,6 +38,7 @@ TalaDBHostObject::TalaDBHostObject(TalaDbHandle *db) : db_(db) {}
 
 TalaDBHostObject::~TalaDBHostObject() {
     if (db_) {
+        taladb_sync_flush(db_, 5000);
         taladb_close(db_);
         db_ = nullptr;
     }
@@ -244,12 +245,16 @@ std::vector<PropNameID> TalaDBHostObject::getPropertyNames(Runtime &rt) {
         "updateOne", "updateMany",
         "deleteOne", "deleteMany",
         "count",
+        "aggregate",
+        "exportChanges", "importChanges", "listCollectionNames",
         "createIndex", "dropIndex",
+        "createCompoundIndex", "dropCompoundIndex",
         "createFtsIndex", "dropFtsIndex",
         "createVectorIndex", "dropVectorIndex", "upgradeVectorIndex",
         "findNearest", "findNearestAsync",
         "findAsync",
         "compact",
+        "syncStatus", "flushSync",
         "close",
     };
     std::vector<PropNameID> result;
@@ -425,6 +430,69 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // aggregate(collection: string, pipeline: object[]): object[]
+    // ------------------------------------------------------------------
+    if (name == "aggregate") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "aggregate"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "aggregate requires 2 arguments");
+                auto col          = args[0].getString(rt).utf8(rt);
+                auto pipelineJson = stringify(rt, args[1]);
+                char *result      = taladb_aggregate(db_, col.c_str(), pipelineJson.c_str());
+                if (!result) throw JSError(rt, "taladb_aggregate failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // Bidirectional sync — exportChanges / importChanges / listCollectionNames
+    // (back JS db.sync(); the runtime-agnostic loop lives in taladb/src/sync.ts)
+    // ------------------------------------------------------------------
+    if (name == "exportChanges") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "exportChanges"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "exportChanges requires 2 arguments");
+                auto collectionsJson = stringify(rt, args[0]);   // string[] → JSON array
+                double sinceMs       = args[1].getNumber();
+                char *result = taladb_export_changes(db_, collectionsJson.c_str(), sinceMs);
+                if (!result) throw JSError(rt, "taladb_export_changes failed");
+                std::string json(result);
+                taladb_free_string(result);
+                // Return the changeset as an opaque string (not parsed) — the
+                // JS sync adapter passes it straight to the transport.
+                return String::createFromUtf8(rt, json);
+            });
+    }
+
+    if (name == "importChanges") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "importChanges"), 1,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "importChanges requires 1 argument");
+                auto changeset = args[0].getString(rt).utf8(rt);
+                int32_t n = taladb_import_changes(db_, changeset.c_str());
+                if (n < 0) throw JSError(rt, "taladb_import_changes failed");
+                return Value(static_cast<double>(n));
+            });
+    }
+
+    if (name == "listCollectionNames") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "listCollectionNames"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                char *result = taladb_list_collection_names(db_);
+                if (!result) throw JSError(rt, "taladb_list_collection_names failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);  // JSON array → JS string[]
+            });
+    }
+
     // ------------------------------------------------------------------
     // createIndex / dropIndex / createFtsIndex / dropFtsIndex
     // ------------------------------------------------------------------
@@ -444,6 +512,24 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // createCompoundIndex / dropCompoundIndex(collection, fields: string[]): void
+    // ------------------------------------------------------------------
+    if (name == "createCompoundIndex" || name == "dropCompoundIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forUtf8(rt, name), 2,
+            [this, name](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto fieldsJson = stringify(rt, args[1]);   // string[] → JSON array
+                if (name == "createCompoundIndex")
+                    taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                else
+                    taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                return Value::undefined();
+            });
+    }
+
     // ------------------------------------------------------------------
     // createVectorIndex(collection, field, dimensions, opts?): void
     //   opts: { metric?: 'cosine'|'dot'|'euclidean', hnsw?: HnswOptions }
@@ -604,6 +690,26 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    if (name == "syncStatus") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "syncStatus"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                char *raw = taladb_sync_status(db_);
+                if (!raw) throw ffiError(rt, "taladb_sync_status failed");
+                std::string json(raw); taladb_free_string(raw);
+                return parse(rt, json);
+            });
+    }
+
+    if (name == "flushSync") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "flushSync"), 1,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                uint64_t timeout = count && args[0].isNumber() ? (uint64_t)args[0].getNumber() : 5000;
+                return Value(taladb_sync_flush(db_, timeout) == 1);
+            });
+    }
+
     // ------------------------------------------------------------------
     // close(): void  (synchronous — the destructor does the real work)
     // ------------------------------------------------------------------
@@ -612,6 +718,7 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             rt, PropNameID::forAscii(rt, "close"), 0,
             [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
                 if (db_) {
+                    taladb_sync_flush(db_, 5000);
                     taladb_close(db_);
                     db_ = nullptr;
                 }

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/TalaDBJni.cpp

@@ -21,7 +21,7 @@
 
 using namespace facebook::jsi;
 
-extern "C" JNIEXPORT void JNICALL
+extern "C" JNIEXPORT jstring JNICALL
 Java_com_taladb_TalaDBModule_nativeInstall(
         JNIEnv  *env,
         jobject  /* thiz */,
@@ -29,6 +29,10 @@ Java_com_taladb_TalaDBModule_nativeInstall(
         jstring  dbPathJ,
         jstring  configJsonJ)
 {
+    // Release any previous HostObject before reopening the same redb file.
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
+
     // Resolve db path
     const char *dbPathC = env->GetStringUTFChars(dbPathJ, nullptr);
     std::string dbPath(dbPathC);
@@ -43,11 +47,18 @@ Java_com_taladb_TalaDBModule_nativeInstall(
     } else {
         db = taladb_open(dbPath.c_str());
     }
-    if (!db) return; // failed to open — JS will see no __TalaDB__ global
-
-    // Get the JSI runtime from the pointer passed by RN internals
-    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    if (!db) {
+        const char *error = taladb_last_error();
+        return env->NewStringUTF(error ? error : "failed to open TalaDB");
+    }
 
     // Install the JSI HostObject as global.__TalaDB__
     taladb::TalaDBHostObject::install(rt, db);
+    return nullptr;
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_taladb_TalaDBModule_nativeClose(JNIEnv *, jobject, jlong jsContextNativePtr) {
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
 }

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/taladb.h

@@ -141,6 +141,45 @@ int32_t taladb_count(TalaDbHandle *handle,
                      const char   *collection,
                      const char   *filter_json);
 
+/* -------------------------------------------------------------------------
+ * Aggregate
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Run an aggregation pipeline. pipeline_json is a JSON array of stages.
+ * Returns a JSON array of result documents, or NULL on error.
+ * Caller must free with taladb_free_string().
+ */
+char *taladb_aggregate(TalaDbHandle *handle,
+                       const char   *collection,
+                       const char   *pipeline_json);
+
+/* -------------------------------------------------------------------------
+ * Bidirectional sync — changeset export / import (backs JS db.sync())
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Export a changeset for the collections in collections_json (a JSON array of
+ * names) with changed_at > since_ms. Returns a JSON string, or NULL on error.
+ * Caller must free with taladb_free_string().
+ */
+char *taladb_export_changes(TalaDbHandle *handle,
+                            const char   *collections_json,
+                            double        since_ms);
+
+/**
+ * Merge a JSON changeset (from a remote peer) via Last-Write-Wins.
+ * Returns the number of documents changed, or -1 on error.
+ */
+int32_t taladb_import_changes(TalaDbHandle *handle,
+                              const char   *changeset_json);
+
+/**
+ * User collection names (reserved names excluded) as a JSON array string.
+ * Returns NULL on error. Caller must free with taladb_free_string().
+ */
+char *taladb_list_collection_names(TalaDbHandle *handle);
+
 /* -------------------------------------------------------------------------
  * Index management
  * ---------------------------------------------------------------------- */
@@ -150,6 +189,10 @@ void taladb_drop_index      (TalaDbHandle *handle, const char *collection, const
 void taladb_create_fts_index(TalaDbHandle *handle, const char *collection, const char *field);
 void taladb_drop_fts_index  (TalaDbHandle *handle, const char *collection, const char *field);
 
+/* Compound (multi-field) indexes. fields_json is a JSON array of field names. */
+void taladb_create_compound_index(TalaDbHandle *handle, const char *collection, const char *fields_json);
+void taladb_drop_compound_index  (TalaDbHandle *handle, const char *collection, const char *fields_json);
+
 /* -------------------------------------------------------------------------
  * Vector index management
  *
@@ -186,6 +229,9 @@ char *taladb_find_nearest(TalaDbHandle *handle,
                           size_t        top_k,
                           const char   *filter_json);
 
+char *taladb_sync_status(TalaDbHandle *handle);
+int32_t taladb_sync_flush(TalaDbHandle *handle, uint64_t timeout_ms);
+
 /* -------------------------------------------------------------------------
  * Async job API — run heavy queries on a background thread.
  *
@@ -195,11 +241,7 @@ char *taladb_find_nearest(TalaDbHandle *handle,
  *   while (taladb_job_poll(j) == 0) { } // yield to JS event loop
  *   char *json = taladb_job_take_result(j);         // frees the job
  *
- * Lifetime contract
- * -----------------
- * The handle passed to `*_start` MUST remain valid until the job has been
- * taken (via take_result) or cancelled (via cancel). The C++ HostObject
- * enforces this by not calling taladb_close while jobs are outstanding.
+ * Workers clone the Arc-backed database state and do not borrow the handle.
  * ---------------------------------------------------------------------- */
 
 typedef struct TalaDbJob TalaDbJob;

package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/Headers/TalaDBHostObject.cpp

@@ -38,6 +38,7 @@ TalaDBHostObject::TalaDBHostObject(TalaDbHandle *db) : db_(db) {}
 
 TalaDBHostObject::~TalaDBHostObject() {
     if (db_) {
+        taladb_sync_flush(db_, 5000);
         taladb_close(db_);
         db_ = nullptr;
     }
@@ -244,12 +245,16 @@ std::vector<PropNameID> TalaDBHostObject::getPropertyNames(Runtime &rt) {
         "updateOne", "updateMany",
         "deleteOne", "deleteMany",
         "count",
+        "aggregate",
+        "exportChanges", "importChanges", "listCollectionNames",
         "createIndex", "dropIndex",
+        "createCompoundIndex", "dropCompoundIndex",
         "createFtsIndex", "dropFtsIndex",
         "createVectorIndex", "dropVectorIndex", "upgradeVectorIndex",
         "findNearest", "findNearestAsync",
         "findAsync",
         "compact",
+        "syncStatus", "flushSync",
         "close",
     };
     std::vector<PropNameID> result;
@@ -425,6 +430,69 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // aggregate(collection: string, pipeline: object[]): object[]
+    // ------------------------------------------------------------------
+    if (name == "aggregate") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "aggregate"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "aggregate requires 2 arguments");
+                auto col          = args[0].getString(rt).utf8(rt);
+                auto pipelineJson = stringify(rt, args[1]);
+                char *result      = taladb_aggregate(db_, col.c_str(), pipelineJson.c_str());
+                if (!result) throw JSError(rt, "taladb_aggregate failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // Bidirectional sync — exportChanges / importChanges / listCollectionNames
+    // (back JS db.sync(); the runtime-agnostic loop lives in taladb/src/sync.ts)
+    // ------------------------------------------------------------------
+    if (name == "exportChanges") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "exportChanges"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "exportChanges requires 2 arguments");
+                auto collectionsJson = stringify(rt, args[0]);   // string[] → JSON array
+                double sinceMs       = args[1].getNumber();
+                char *result = taladb_export_changes(db_, collectionsJson.c_str(), sinceMs);
+                if (!result) throw JSError(rt, "taladb_export_changes failed");
+                std::string json(result);
+                taladb_free_string(result);
+                // Return the changeset as an opaque string (not parsed) — the
+                // JS sync adapter passes it straight to the transport.
+                return String::createFromUtf8(rt, json);
+            });
+    }
+
+    if (name == "importChanges") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "importChanges"), 1,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "importChanges requires 1 argument");
+                auto changeset = args[0].getString(rt).utf8(rt);
+                int32_t n = taladb_import_changes(db_, changeset.c_str());
+                if (n < 0) throw JSError(rt, "taladb_import_changes failed");
+                return Value(static_cast<double>(n));
+            });
+    }
+
+    if (name == "listCollectionNames") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "listCollectionNames"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                char *result = taladb_list_collection_names(db_);
+                if (!result) throw JSError(rt, "taladb_list_collection_names failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);  // JSON array → JS string[]
+            });
+    }
+
     // ------------------------------------------------------------------
     // createIndex / dropIndex / createFtsIndex / dropFtsIndex
     // ------------------------------------------------------------------
@@ -444,6 +512,24 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // createCompoundIndex / dropCompoundIndex(collection, fields: string[]): void
+    // ------------------------------------------------------------------
+    if (name == "createCompoundIndex" || name == "dropCompoundIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forUtf8(rt, name), 2,
+            [this, name](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto fieldsJson = stringify(rt, args[1]);   // string[] → JSON array
+                if (name == "createCompoundIndex")
+                    taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                else
+                    taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                return Value::undefined();
+            });
+    }
+
     // ------------------------------------------------------------------
     // createVectorIndex(collection, field, dimensions, opts?): void
     //   opts: { metric?: 'cosine'|'dot'|'euclidean', hnsw?: HnswOptions }
@@ -604,6 +690,26 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    if (name == "syncStatus") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "syncStatus"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                char *raw = taladb_sync_status(db_);
+                if (!raw) throw ffiError(rt, "taladb_sync_status failed");
+                std::string json(raw); taladb_free_string(raw);
+                return parse(rt, json);
+            });
+    }
+
+    if (name == "flushSync") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "flushSync"), 1,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                uint64_t timeout = count && args[0].isNumber() ? (uint64_t)args[0].getNumber() : 5000;
+                return Value(taladb_sync_flush(db_, timeout) == 1);
+            });
+    }
+
     // ------------------------------------------------------------------
     // close(): void  (synchronous — the destructor does the real work)
     // ------------------------------------------------------------------
@@ -612,6 +718,7 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             rt, PropNameID::forAscii(rt, "close"), 0,
             [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
                 if (db_) {
+                    taladb_sync_flush(db_, 5000);
                     taladb_close(db_);
                     db_ = nullptr;
                 }

package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/Headers/TalaDBJni.cpp

@@ -21,7 +21,7 @@
 
 using namespace facebook::jsi;
 
-extern "C" JNIEXPORT void JNICALL
+extern "C" JNIEXPORT jstring JNICALL
 Java_com_taladb_TalaDBModule_nativeInstall(
         JNIEnv  *env,
         jobject  /* thiz */,
@@ -29,6 +29,10 @@ Java_com_taladb_TalaDBModule_nativeInstall(
         jstring  dbPathJ,
         jstring  configJsonJ)
 {
+    // Release any previous HostObject before reopening the same redb file.
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
+
     // Resolve db path
     const char *dbPathC = env->GetStringUTFChars(dbPathJ, nullptr);
     std::string dbPath(dbPathC);
@@ -43,11 +47,18 @@ Java_com_taladb_TalaDBModule_nativeInstall(
     } else {
         db = taladb_open(dbPath.c_str());
     }
-    if (!db) return; // failed to open — JS will see no __TalaDB__ global
-
-    // Get the JSI runtime from the pointer passed by RN internals
-    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    if (!db) {
+        const char *error = taladb_last_error();
+        return env->NewStringUTF(error ? error : "failed to open TalaDB");
+    }
 
     // Install the JSI HostObject as global.__TalaDB__
     taladb::TalaDBHostObject::install(rt, db);
+    return nullptr;
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_taladb_TalaDBModule_nativeClose(JNIEnv *, jobject, jlong jsContextNativePtr) {
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+    rt.global().setProperty(rt, "__TalaDB__", Value::undefined());
 }

package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/Headers/taladb.h

@@ -141,6 +141,45 @@ int32_t taladb_count(TalaDbHandle *handle,
                      const char   *collection,
                      const char   *filter_json);
 
+/* -------------------------------------------------------------------------
+ * Aggregate
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Run an aggregation pipeline. pipeline_json is a JSON array of stages.
+ * Returns a JSON array of result documents, or NULL on error.
+ * Caller must free with taladb_free_string().
+ */
+char *taladb_aggregate(TalaDbHandle *handle,
+                       const char   *collection,
+                       const char   *pipeline_json);
+
+/* -------------------------------------------------------------------------
+ * Bidirectional sync — changeset export / import (backs JS db.sync())
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Export a changeset for the collections in collections_json (a JSON array of
+ * names) with changed_at > since_ms. Returns a JSON string, or NULL on error.
+ * Caller must free with taladb_free_string().
+ */
+char *taladb_export_changes(TalaDbHandle *handle,
+                            const char   *collections_json,
+                            double        since_ms);
+
+/**
+ * Merge a JSON changeset (from a remote peer) via Last-Write-Wins.
+ * Returns the number of documents changed, or -1 on error.
+ */
+int32_t taladb_import_changes(TalaDbHandle *handle,
+                              const char   *changeset_json);
+
+/**
+ * User collection names (reserved names excluded) as a JSON array string.
+ * Returns NULL on error. Caller must free with taladb_free_string().
+ */
+char *taladb_list_collection_names(TalaDbHandle *handle);
+
 /* -------------------------------------------------------------------------
  * Index management
  * ---------------------------------------------------------------------- */
@@ -150,6 +189,10 @@ void taladb_drop_index      (TalaDbHandle *handle, const char *collection, const
 void taladb_create_fts_index(TalaDbHandle *handle, const char *collection, const char *field);
 void taladb_drop_fts_index  (TalaDbHandle *handle, const char *collection, const char *field);
 
+/* Compound (multi-field) indexes. fields_json is a JSON array of field names. */
+void taladb_create_compound_index(TalaDbHandle *handle, const char *collection, const char *fields_json);
+void taladb_drop_compound_index  (TalaDbHandle *handle, const char *collection, const char *fields_json);
+
 /* -------------------------------------------------------------------------
  * Vector index management
  *
@@ -186,6 +229,9 @@ char *taladb_find_nearest(TalaDbHandle *handle,
                           size_t        top_k,
                           const char   *filter_json);
 
+char *taladb_sync_status(TalaDbHandle *handle);
+int32_t taladb_sync_flush(TalaDbHandle *handle, uint64_t timeout_ms);
+
 /* -------------------------------------------------------------------------
  * Async job API — run heavy queries on a background thread.
  *
@@ -195,11 +241,7 @@ char *taladb_find_nearest(TalaDbHandle *handle,
  *   while (taladb_job_poll(j) == 0) { } // yield to JS event loop
  *   char *json = taladb_job_take_result(j);         // frees the job
  *
- * Lifetime contract
- * -----------------
- * The handle passed to `*_start` MUST remain valid until the job has been
- * taken (via take_result) or cancelled (via cancel). The C++ HostObject
- * enforces this by not calling taladb_close while jobs are outstanding.
+ * Workers clone the Arc-backed database state and do not borrow the handle.
  * ---------------------------------------------------------------------- */
 
 typedef struct TalaDbJob TalaDbJob;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/react-native",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "TalaDB React Native module — document and vector database via JSI HostObject",
   "main": "src/index",
   "types": "src/index.tsx",
@@ -24,7 +24,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/thinkgrid-labs/taladb.git",
-    "directory": "packages/taladb-react-native"
+    "directory": "packages/bindings/react-native"
   },
   "homepage": "https://thinkgrid-labs.github.io/taladb/guide/react-native",
   "bugs": {

package/src/index.tsx

@@ -35,6 +35,10 @@ export const TalaDBModule = {
     NativeTalaDB.initialize(dbName, configJson),
   /** Close the database gracefully. */
   close: () => NativeTalaDB.close(),
+  /** HTTP push events dropped by backpressure or failed after retries. */
+  syncStatus: () => native().syncStatus(),
+  /** Wait for HTTP push work accepted before this call. */
+  flushSync: (timeoutMs = 5000) => native().flushSync(timeoutMs),
 };
 
 // ---------------------------------------------------------------------------
@@ -67,9 +71,35 @@ export interface Collection<T extends Document = Document> {
 
 export interface DB {
   collection<T extends Document = Document>(name: string): Collection<T>;
+  syncStatus(): { dropped: number; failed: number };
+  flushSync(timeoutMs?: number): boolean;
   close(): Promise<void>;
 }
 
+interface JsiTalaDB {
+  insert(collection: string, doc: Object): string;
+  insertMany(collection: string, docs: Object[]): string[];
+  find(collection: string, filter: Object | null): Object[];
+  findOne(collection: string, filter: Object | null): Object | null;
+  updateOne(collection: string, filter: Object, update: Object): boolean;
+  updateMany(collection: string, filter: Object, update: Object): number;
+  deleteOne(collection: string, filter: Object): boolean;
+  deleteMany(collection: string, filter: Object): number;
+  count(collection: string, filter: Object | null): number;
+  createIndex(collection: string, field: string): void;
+  dropIndex(collection: string, field: string): void;
+  createFtsIndex(collection: string, field: string): void;
+  dropFtsIndex(collection: string, field: string): void;
+  syncStatus(): { dropped: number; failed: number };
+  flushSync(timeoutMs?: number): boolean;
+}
+
+function native(): JsiTalaDB {
+  const host = (globalThis as { __TalaDB__?: JsiTalaDB }).__TalaDB__;
+  if (!host) throw new Error('TalaDB is not initialized; await TalaDBModule.initialize() first');
+  return host;
+}
+
 // ---------------------------------------------------------------------------
 // openDB — synchronous DB handle (after initialize() has been called)
 // ---------------------------------------------------------------------------
@@ -82,25 +112,27 @@ export interface DB {
  */
 function collection<T extends Document>(colName: string): Collection<T> {
   return {
-    insert: (doc) => NativeTalaDB.insert(colName, doc as Object),
-    insertMany: (docs) => NativeTalaDB.insertMany(colName, docs as Object[]),
-    find: (filter?) => NativeTalaDB.find(colName, filter ?? null) as T[],
-    findOne: (filter) => NativeTalaDB.findOne(colName, filter) as T | null,
-    updateOne: (filter, update) => NativeTalaDB.updateOne(colName, filter, update),
-    updateMany: (filter, update) => NativeTalaDB.updateMany(colName, filter, update),
-    deleteOne: (filter) => NativeTalaDB.deleteOne(colName, filter),
-    deleteMany: (filter) => NativeTalaDB.deleteMany(colName, filter),
-    count: (filter?) => NativeTalaDB.count(colName, filter ?? null),
-    createIndex: (field) => NativeTalaDB.createIndex(colName, field),
-    dropIndex: (field) => NativeTalaDB.dropIndex(colName, field),
-    createFtsIndex: (field) => NativeTalaDB.createFtsIndex(colName, field),
-    dropFtsIndex: (field) => NativeTalaDB.dropFtsIndex(colName, field),
+    insert: (doc) => native().insert(colName, doc as Object),
+    insertMany: (docs) => native().insertMany(colName, docs as Object[]),
+    find: (filter?) => native().find(colName, filter ?? null) as T[],
+    findOne: (filter) => native().findOne(colName, filter) as T | null,
+    updateOne: (filter, update) => native().updateOne(colName, filter, update),
+    updateMany: (filter, update) => native().updateMany(colName, filter, update),
+    deleteOne: (filter) => native().deleteOne(colName, filter),
+    deleteMany: (filter) => native().deleteMany(colName, filter),
+    count: (filter?) => native().count(colName, filter ?? null),
+    createIndex: (field) => native().createIndex(colName, field),
+    dropIndex: (field) => native().dropIndex(colName, field),
+    createFtsIndex: (field) => native().createFtsIndex(colName, field),
+    dropFtsIndex: (field) => native().dropFtsIndex(colName, field),
   };
 }
 
 export function openDB(_dbName: string): DB {
   return {
     collection,
+    syncStatus: () => native().syncStatus(),
+    flushSync: (timeoutMs = 5000) => native().flushSync(timeoutMs),
     close: () => NativeTalaDB.close(),
   };
 }