motedb-python 0.12.8__tar.gz → 0.12.9__tar.gz

{motedb_python-0.12.8 → motedb_python-0.12.9}/.gitignore

@@ -33,3 +33,4 @@ benchmark_results/
 __pycache__/
 *.pyc
 bindings/python/dist/
+_native.abi3.so

{motedb_python-0.12.8 → motedb_python-0.12.9}/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [0.12.9] — 2026-10-10
+
+- **🔑 崩溃恢复审计三连修(0.12.8 stale 检测的边界补全)**:
+  - **重建不清空旧索引 → 统计膨胀**: 恢复重建在已加载的(可能滞后的)
+    索引上**追加**而非重置 —— `batch_insert` 不幂等(total_docs 无条件
+    自增、`PostingList::add` 对已有 doc 抬 TF), 一次重建即 total_docs
+    翻倍 + 词频加倍(BM25 静默漂移, MATCH 成员正确所以压测没抓到)。
+    修复: 重建前硬重置(删除 text_{name}.fts.d 与 dict.d 目录、新建空
+    索引, 与 load 路径同构), 重建后 total_docs 精确等于活行探针实测
+    80/80。回归: tests/test_fts_recovery_staleness.rs(UPDATE/DELETE/
+    NULL 混合 + 标记契约 + 恢复幂等)
+  - **NULL 文本行 → 每次全量重建**: NULL 不入索引是常态, 但 0.12.8 的
+    `indexed < table_rows` 谓词把含 NULL 的表判为永久 stale → 每次
+    open 全量重建(且触发上面的追加膨胀)。修复: 引入**干净关闭标记**
+    `fts_indexes.fresh` —— Drop 时 flush 全部文本索引(有界锁等待,
+    builder 卡死则跳过标记而非卡死 Drop)并原子写标记; open 起始消费
+    标记, 标记在位 → 干净重开零校验零重建, 标记缺失(崩溃证据)→ 才
+    跑计数校验。干净重开实测零重建
+  - **墓碑丢失方向 → MATCH 幻影**: crash 前 DELETE 的内存 tombstone
+    未落盘 → 磁盘索引 total_docs **大于**表行数, 旧 `<` 谓词不触发
+    重建 → posting 残留已删行, `COUNT(*) WHERE MATCH` 快路径按索引
+    计数会多计。修复: 谓词改 `indexed != table_rows`(双向); 实证中
+    干净关闭/WAL 回放通常兜底此窗口, `!=` 为纵深防御。回归:
+    test_crash_recovery.py 扩展奇数轮 kill@DELCKPT(删除后 checkpoint
+    即杀), 断言 MATCH 与活行精确一致
+- 详查结论: UPDATE 后多 segment 无同 key 双活(重建计数精确); 文本
+  索引磁盘产物全部位于 fts.d/dict.d 两目录(重置完整)
+- **WAL 截断点 durability 对齐(纵深防御)**: checkpoint_impl 与 vacuum
+  在 `wal.checkpoint_all()` 截断前新增有界(2s try-write)FTS flush。
+  原理: UPDATE 的 term 级墓碑(deleted_term_docs)纯内存, 计数谓词
+  (total_docs 净变化为零)天然看不见内容级漂移; 截断 WAL 会移除本可
+  回放重放的索引变更。实测该窗口被 WAL 回放兜住(不 flush 崩溃结果
+  也正确), 此为原理性对齐而非实测缺陷修复; 锁竞争时跳过(不劣于
+  修复前)
+- **🔑 在线 backup 竞态修复(全套件并行实抓, 上项改动的连带暴露)**:
+  backup 拷贝与"已 in-flight 的段交换"竞态时 NotFound 只重试 3×50ms
+  — 全套件并行负载下逃逸(backup_to 报 Io NotFound)。且 auto-checkpoint
+  持 is_flushing 的临界区因上面的 FTS flush 变长, backup 的 CAS 冲突
+  从"立即报错"概率上升。修复: 拷贝重试 3×50ms → 10×100ms; is_flushing
+  CAS 冲突内部重试 ~2.5s 后才上抛 "retry backup"。因果验证: 去 FTS
+  flush 的全套件 exit 0, 带上后 2/2 失败, 加宽重试后收敛
+- **标记契约加固(二轮自查)**:
+  - **重置顺序(Windows 关键)**: `TextFTSIndex::new` 是 create-or-OPEN,
+    会加载残留文件; 旧索引对象持着 fts.d 内文件句柄时 Windows 删除目录
+    因共享冲突失败 → new() 会加载旧状态、追加膨胀复活。修复: 先从 map
+    移除旧条目(释放句柄)再删目录再新建(macOS 上不可测, 代码序保证)
+  - **盖章归属与僵尸句柄**: close() 释放 flock 后对象可存活到 GC ——
+    僵尸 Drop 在新实例 open 之后再盖章 = 给新会话中途状态谎报"干净"。
+    修复: close() 在**持锁期间**(release_lock 之前)盖章(Python 主路径
+    即时生效, 不依赖 GC); Drop 路径仅在仍持锁(从未 close)时盖章
+  - **标记持久化**: fsync 文件 + rename + unix 目录 fsync, 标记严格
+    排在被 flush 的索引数据之后(断电不出现"标记在、数据不在")
+
 ## [0.12.8] — 2026-10-09
 
 - **🔑 kill -9 崩溃后全文索引静默滞后修复(PyPI 包压测实抓)**: 崩溃发生在

{motedb_python-0.12.8 → motedb_python-0.12.9}/Cargo.lock

@@ -800,7 +800,7 @@ dependencies = [
 
 [[package]]
 name = "motedb"
-version = "0.12.8"
+version = "0.12.9"
 dependencies = [
  "arc-swap",
  "bincode",

{motedb_python-0.12.8 → motedb_python-0.12.9}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "motedb"
-version = "0.12.8"
+version = "0.12.9"
 edition = "2021"
 rust-version = "1.87"
 description = "AI-native embedded multimodal database for embodied intelligence (robots, AR glasses, industrial arms)."

{motedb_python-0.12.8 → motedb_python-0.12.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: motedb-python
-Version: 0.12.8
+Version: 0.12.9
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research

{motedb_python-0.12.8 → motedb_python-0.12.9}/bindings/python/Cargo.lock

@@ -403,7 +403,7 @@ dependencies = [
 
 [[package]]
 name = "motedb"
-version = "0.12.8"
+version = "0.12.9"
 dependencies = [
  "arc-swap",
  "bincode",
@@ -430,7 +430,7 @@ dependencies = [
 
 [[package]]
 name = "motedb-python"
-version = "0.12.8"
+version = "0.12.9"
 dependencies = [
  "motedb",
  "pyo3",

{motedb_python-0.12.8 → motedb_python-0.12.9}/bindings/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "motedb-python"
-version = "0.12.8"
+version = "0.12.9"
 edition = "2021"
 description = "Python bindings for MoteDB — AI-native embedded multimodal database."
 license = "MIT"

{motedb_python-0.12.8 → motedb_python-0.12.9}/bindings/python/tests/test_crash_recovery.py

@@ -1,8 +1,13 @@
 #!/usr/bin/env python3
-"""kill -9 崩溃恢复回归: 表数据连续无缺口 + FTS 完整。
-v0.12.8 修复前: 已 checkpoint 的表崩溃后无 WAL 回放 → 文本索引的内存
+"""kill -9 崩溃恢复回归: 表数据连续无缺口 + FTS 完整(双向)。
+v0.12.8 修复: 已 checkpoint 的表崩溃后无 WAL 回放 → 文本索引的内存
 pending 丢失且无人重建 → MATCH 静默缺行(实测 198/300, doctor 仍 PASS)。
-修复: open 时检测 index total_docs < 表行数 → 走既有重建通道。"""
+v0.12.9 修复两个残余缺口:
+  (a) 重建在旧索引上追加而非重置 → total_docs/TF 膨胀(BM25 漂移);
+  (b) 墓碑丢失方向: crash 前 DELETE 的内存 tombstone 未落盘 → 磁盘索引
+      total_docs > 表行数, 旧 `<` 谓词不触发重建 → MATCH 幻影多计。
+偶数轮 kill@CKPT 打插入丢失窗口, 奇数轮 kill@DELCKPT 打墓碑丢失窗口;
+两方向都断言 MATCH 计数与活行精确一致。"""
 import os
 import shutil
 import subprocess
@@ -25,6 +30,8 @@ WRITER = textwrap.dedent("""
         db.execute("INSERT INTO c VALUES (?, ?)", params=[i, f"post {i}"])
         if i % 50 == 0:
             db.checkpoint(); print(f"CKPT{i}", flush=True)
+    db.execute("DELETE FROM c WHERE id >= 400")
+    db.checkpoint(); print("DELCKPT", flush=True)
 """)
 
 
@@ -32,7 +39,7 @@ def main():
     tmp = tempfile.mkdtemp()
     path = os.path.join(tmp, "crash.mote")
     fails = 0
-    trials = int(sys.argv[1]) if len(sys.argv) > 1 else 5
+    trials = int(sys.argv[1]) if len(sys.argv) > 1 else 6
     try:
         for t in range(trials):
             if os.path.isdir(path):
@@ -42,12 +49,17 @@ def main():
             proc = subprocess.Popen(
                 [sys.executable, "-c", WRITER, path],
                 stdout=subprocess.PIPE, text=True)
+            # Even trials: kill in the post-checkpoint INSERT window
+            # (index behind). Odd trials: kill right after the post-DELETE
+            # checkpoint (tombstones still memory-only → index ahead).
+            want = "DELCKPT" if t % 2 else "CKPT"
             killed = None
             for line in proc.stdout:
-                if line.strip().startswith("CKPT"):
-                    proc.kill()
-                    killed = line.strip()
-                    break
+                s = line.strip()
+                if s.startswith("CKPT") and want == "CKPT":
+                    proc.kill(); killed = s; break
+                if s == "DELCKPT" and want == "DELCKPT":
+                    proc.kill(); killed = s; break
             proc.wait()
             db = motedb.Database(path)
             n = db.execute("SELECT COUNT(*) AS n FROM c")[0]["n"]
@@ -55,10 +67,16 @@ def main():
             cnt = db.execute("SELECT COUNT(DISTINCT id) AS d FROM c")[0]["d"]
             fts = db.execute(
                 "SELECT COUNT(*) AS n FROM c WHERE MATCH(v, 'common')")[0]["n"]
+            post_live = db.execute(
+                "SELECT COUNT(*) AS n FROM c WHERE id >= 300")[0]["n"]
+            post_fts = db.execute(
+                "SELECT COUNT(*) AS n FROM c WHERE MATCH(v, 'post')")[0]["n"]
             db.close()
-            ok = cnt == mx + 1 and fts == 300
+            ok = (cnt == mx + 1 and fts == 300
+                  and post_fts == post_live)  # exact: no missing, no phantoms
             print(f"{'ok  ' if ok else 'FAIL'} trial{t} kill@{killed} "
-                  f"rows={n} contiguous={cnt == mx + 1} fts={fts}/300")
+                  f"rows={n} contiguous={cnt == mx + 1} fts={fts}/300 "
+                  f"post fts={post_fts}/live{post_live}")
             if not ok:
                 fails += 1
     finally:

{motedb_python-0.12.8 → motedb_python-0.12.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "motedb-python"
-version = "0.12.8"
+version = "0.12.9"
 description = "AI-native embedded multimodal database — SQL, vectors, full-text, spatial and time-series in one ACID engine, with edge presets for robots and edge devices."
 readme = "README.md"
 requires-python = ">=3.9"

{motedb_python-0.12.8 → motedb_python-0.12.9}/src/api.rs

@@ -533,6 +533,15 @@ impl Database {
         self.inner
             .is_closed
             .store(true, std::sync::atomic::Ordering::Release);
+        // 🔒 v0.12.9: stamp the FTS freshness marker while we still hold the
+        // exclusive lock (release_lock is below). Stamping here — not only in
+        // MoteDB::Drop — makes the marker prompt for explicit close() users
+        // (the Python binding's primary path; Drop may wait for GC), and the
+        // lock ordering guarantees no NEW instance can have opened yet, so
+        // the marker can never attest freshness for someone else's session.
+        if result.is_ok() {
+            self.inner.stamp_fts_freshness_marker("[close]");
+        }
         // Release the exclusive flock so a subsequent open() on the same
         // directory (or another process) can acquire it. Without this, the
         // lock is held until the MoteDB is dropped — which may be much later

{motedb_python-0.12.8 → motedb_python-0.12.9}/src/database/core.rs

@@ -891,6 +891,14 @@ impl MoteDB {
         // 🔒 Acquire exclusive file lock to prevent concurrent opens
         let lock_file = Self::acquire_lock(&db_path)?;
 
+        // 🔒 Crash-evidence gate (v0.12.9): a clean Drop flushes the FTS
+        // indexes and stamps this marker. Its absence ⇒ index durability is
+        // suspect (crash / kill -9) ⇒ the stale-count check in the rebuild
+        // loop below runs and rebuilds on mismatch. Captured BEFORE removal
+        // (a crash mid-open must never leave a stale marker behind).
+        let clean_close = db_path.join("fts_indexes.fresh").exists();
+        let _ = std::fs::remove_file(db_path.join("fts_indexes.fresh"));
+
         // 🎯 统一目录结构：从 {name}.mote/ 目录读取
         let wal_path = db_path.join("wal");
         let lsm_dir = db_path.join("lsm");
@@ -1862,15 +1870,25 @@ impl MoteDB {
             for name in txt_idx {
                 if let Some((table, column)) = db.index_registry.resolve_index_name(&name) {
                     let corrupt = corrupt_loaded.iter().any(|n| n == &name);
-                    // 🔒 Stale-index detection (kill -9 recovery audit, v0.12.8):
-                    // a crash between table-data durability and text-index
-                    // flush leaves the index VALID but BEHIND (pending posting
-                    // lists are memory-only). No WAL replay happens for
-                    // already-checkpointed tables, so the v1 rebuild trigger
-                    // (replayed/corrupt only) skipped them — MATCH silently
-                    // missed rows (measured 198/300 after kill, doctor PASS).
-                    // Rebuild whenever the index's doc count trails the table.
-                    let stale = {
+                    // 🔒 Stale-index detection (kill -9 recovery audit,
+                    // v0.12.8/v0.12.9): a crash between table-data durability
+                    // and text-index flush leaves the index VALID but WRONG in
+                    // EITHER direction — pending posting lists are memory-only
+                    // (index BEHIND: MATCH silently missed rows, measured
+                    // 198/300 after kill) and in-memory tombstones are equally
+                    // volatile (index AHEAD: postings still reference deleted
+                    // rows, phantom MATCH hits / COUNT overcount). No WAL
+                    // replay happens for already-checkpointed tables, so the
+                    // v1 trigger (replayed/corrupt only) skipped both classes.
+                    // Rebuild on ANY count mismatch. NULL texts are legitimately
+                    // unindexed, so mismatched-but-clean tables (NULL-bearing)
+                    // also rebuild here — that is crash-path-only work: a clean
+                    // Drop stamps `fts_indexes.fresh`, and open skips this
+                    // check entirely when the marker was present (marker is
+                    // consumed at open start, above). Replayed/corrupt triggers
+                    // stay live regardless of the marker — they carry their own
+                    // evidence.
+                    let stale = !clean_close && {
                         // NOTE: this runs BEFORE table_row_count is
                         // initialized in open() — count live rows straight
                         // from the segment store (the authoritative source
@@ -1885,11 +1903,51 @@ impl MoteDB {
                             .get(&name)
                             .map(|i| i.read().stats().total_docs)
                             .unwrap_or(0);
-                        table_rows > 0 && indexed < table_rows
+                        indexed != table_rows
                     };
                     if !replayed_tables.contains(&table) && !corrupt && !stale {
                         continue;
                     }
+                    // 🔒 v0.12.9: HARD RESET before rebuilding. The rebuild
+                    // used to APPEND into the loaded (possibly stale) index:
+                    // batch_insert is not idempotent — total_docs += n
+                    // unconditionally and PostingList::add bumps TF for
+                    // already-present docs — so a rebuild over surviving state
+                    // inflated total_docs (~2×) and doubled term frequencies
+                    // (silent BM25 drift, permanent until a full reset).
+                    // Mirror the load path's reset (drop both on-disk dirs,
+                    // start a fresh index) so rebuilt == exactly the live
+                    // rows. Re-resetting an already-fresh index (replayed /
+                    // corrupt paths reset during load) is harmless.
+                    //
+                    // 🔒 ORDER MATTERS (Windows): TextFTSIndex::new is
+                    // create-OR-OPEN — it loads whatever files still exist.
+                    // The map entry is therefore removed FIRST so the last
+                    // Arc (and its open handles into text_*.fts.d) drops
+                    // BEFORE remove_dir_all: with the loaded index still
+                    // alive, Windows sharing violations make the removal
+                    // fail and new() would re-load the stale state, silently
+                    // reviving the append bug. (The builder pipeline starts
+                    // only after this loop, so the map is the sole holder.)
+                    db.text_indexes.remove(&name);
+                    let fts_dir = indexes_dir.join(format!("text_{}.fts.d", name));
+                    let dict_dir = indexes_dir.join(format!("text_{}.dict.d", name));
+                    let _ = std::fs::remove_dir_all(&fts_dir);
+                    let _ = std::fs::remove_dir_all(&dict_dir);
+                    match TextFTSIndex::new(indexes_dir.join(format!("text_{}", name))) {
+                        Ok(fresh) => {
+                            db.text_indexes.insert(
+                                name.clone(),
+                                std::sync::Arc::new(parking_lot::RwLock::new(fresh)),
+                            );
+                        }
+                        Err(e) => warn_log!(
+                            "[Recovery] ⚠️ text index '{}' reset failed ({:?}) — \
+                             index left absent; queries on it error until re-created",
+                            name,
+                            e
+                        ),
+                    }
                     if let Ok(schema) = db.table_registry.get_table(&table) {
                         if let Some(col_def) = schema.columns.iter().find(|c| c.name == column) {
                             let pos = col_def.position;
@@ -3074,9 +3132,69 @@ impl Drop for MoteDB {
             warn_log!("[Drop] Final checkpoint failed: {:?}", e);
             warn_log!("[Drop] WAL files may not be cleaned up");
         } else {
+            // 🔒 v0.12.9 clean-close marker (Drop path — covers handles that
+            // were never explicitly closed). Gated on the exclusive flock:
+            // close() releases the lock but the object may stay alive until
+            // GC — a zombie Drop stamping AFTER a new instance opened would
+            // fake freshness for that new session's mid-flight state.
+            // close() itself stamps under the lock before releasing it.
+            if self.holds_exclusive_lock() {
+                self.stamp_fts_freshness_marker("[MoteDB::Drop]");
+            }
             debug_log!("[MoteDB::Drop] ✅ Final checkpoint complete, WAL cleaned");
         }
 
         debug_log!("[MoteDB::Drop] 👋 Database closed cleanly");
     }
 }
+
+impl MoteDB {
+    /// True while this instance still owns the exclusive directory lock,
+    /// i.e. `close()` has not run (`release_lock` takes the File).
+    fn holds_exclusive_lock(&self) -> bool {
+        self._lock_file
+            .lock()
+            .map(|guard| guard.is_some())
+            .unwrap_or(false)
+    }
+
+    /// 🔒 v0.12.9 clean-close marker: flush the FTS indexes (bounded — never
+    /// hang the caller on a wedged index write lock; skipping the marker
+    /// just means the next open pays the crash-verify path) and durably
+    /// stamp `fts_indexes.fresh`. CALLER MUST HOLD THE EXCLUSIVE LOCK — see
+    /// `holds_exclusive_lock`.
+    pub(crate) fn stamp_fts_freshness_marker(&self, who: &str) {
+        if !self.try_flush_text_indexes_bounded(std::time::Duration::from_secs(2)) {
+            warn_log!(
+                "{who} ⚠️ FTS flush not confirmed — skipping fts_indexes.fresh stamp \
+                 (next open pays crash-verify)"
+            );
+            return;
+        }
+        // Durable stamp (fs::write alone is page-cache only): fsync the
+        // file, rename, then fsync the dir (unix-only — Windows opens on
+        // directories return Access Denied, v0.12.6). This orders the marker
+        // STRICTLY AFTER the flushed index data so a power loss can never
+        // leave the marker claiming freshness for postings that didn't
+        // survive.
+        let marker = self.path.join("fts_indexes.fresh");
+        let tmp = self.path.join(".fts_indexes.fresh.tmp");
+        let stamped = (|| -> std::io::Result<()> {
+            use std::io::Write;
+            let mut f = std::fs::File::create(&tmp)?;
+            f.write_all(b"v1")?;
+            f.sync_all()?;
+            drop(f);
+            std::fs::rename(&tmp, &marker)?;
+            #[cfg(unix)]
+            std::fs::File::open(&self.path)?.sync_all()?;
+            Ok(())
+        })();
+        match stamped {
+            Ok(()) => debug_log!("{who} ✅ FTS flushed, freshness marker stamped"),
+            Err(e) => warn_log!(
+                "{who} ⚠️ fts_indexes.fresh stamp failed ({e:?}) — next open pays crash-verify"
+            ),
+        }
+    }
+}

{motedb_python-0.12.8 → motedb_python-0.12.9}/src/database/indexes/text.rs

@@ -358,4 +358,26 @@ impl MoteDB {
 
         Ok(())
     }
+
+    /// 🔒 Drop-path bounded flush (v0.12.9): the index-builder thread was
+    /// asked to stop before this runs, but a wedged sub-thread could still
+    /// hold an index write lock (join timeout edge). A blocking `write()`
+    /// here could hang Drop forever; try-bounded instead and report whether
+    /// EVERY index flushed — the caller only stamps the clean-close marker
+    /// on `true` (no marker ⇒ next open runs the crash-verify path, which
+    /// is correct, merely slower).
+    pub fn try_flush_text_indexes_bounded(&self, timeout: std::time::Duration) -> bool {
+        let mut all_flushed = true;
+        for entry in self.text_indexes.iter() {
+            match entry.value().try_write_for(timeout) {
+                Some(mut index) => {
+                    if index.flush().is_err() {
+                        all_flushed = false;
+                    }
+                }
+                None => all_flushed = false,
+            }
+        }
+        all_flushed
+    }
 }

{motedb_python-0.12.8 → motedb_python-0.12.9}/src/database/persistence.rs

@@ -112,11 +112,26 @@ impl MoteDB {
         // Same discipline as flush(): CAS the reentrancy flag, then hold
         // checkpoint_mutex so auto-checkpoint/compaction can't rewrite
         // segment files mid-copy.
-        if self
-            .is_flushing
-            .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
-            .is_err()
-        {
+        // 🔒 v0.12.9: auto-checkpoint holds this flag for its whole run
+        // (index flush + WAL truncation + segment compaction — seconds under
+        // load). Erroring on first collision made concurrent backup+checkpoint
+        // flaky at full-suite parallelism; retry the CAS briefly before
+        // surfacing the "retry backup" contract error.
+        let mut acquired = false;
+        for attempt in 0..6 {
+            if self
+                .is_flushing
+                .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
+                .is_ok()
+            {
+                acquired = true;
+                break;
+            }
+            if attempt < 5 {
+                std::thread::sleep(std::time::Duration::from_millis(250));
+            }
+        }
+        if !acquired {
             return Err(StorageError::InvalidData(
                 "a flush/checkpoint is in progress — retry backup".into(),
             ));
@@ -164,9 +179,16 @@ impl MoteDB {
         let result = match flush_result {
             Ok(()) => {
                 let mut out = Ok(());
-                for attempt in 0..3 {
+                // 🔒 The copy can race a writer whose flush_buffer (or a
+                // background lsm-flush) was ALREADY in flight when the write
+                // stripes were taken: it finishes during the copy, atomically
+                // swapping segment files. NotFound is transient by
+                // construction — retry with enough patience to ride out a
+                // loaded runner (3×50ms escaped under full-suite parallelism;
+                // 10×100ms measured sufficient with margin).
+                for attempt in 0..10 {
                     if attempt > 0 {
-                        std::thread::sleep(std::time::Duration::from_millis(50));
+                        std::thread::sleep(std::time::Duration::from_millis(100));
                         let _ = std::fs::remove_dir_all(&dest);
                     }
                     match Self::copy_dir_durable(&self.path, &dest) {
@@ -457,6 +479,16 @@ impl MoteDB {
             for entry in self.col_segment_stores.iter() {
                 let _ = entry.flush_buffer();
             }
+            // 🔒 v0.12.9: same FTS-before-truncation discipline as
+            // checkpoint_impl — UPDATE-class text staleness is invisible to
+            // count-based recovery checks, so it must never outlive the WAL
+            // records that could replay it.
+            if !self.try_flush_text_indexes_bounded(std::time::Duration::from_secs(2)) {
+                warn_log!(
+                    "[VACUUM] FTS flush skipped (index lock contention) — \
+                     text index may lag until close"
+                );
+            }
             if let Err(e) = self.wal.checkpoint_all() {
                 warn_log!("[VACUUM] WAL truncation failed (non-fatal): {}", e);
             }
@@ -562,6 +594,20 @@ impl MoteDB {
             warn_log!("[Flush] Columnar store flush failed: {}", e);
         }
 
+        // 🔒 v0.12.9: persist FTS in-memory state (tombstones + pending
+        // postings) BEFORE the WAL truncation below. The truncation removes
+        // the replay that would otherwise re-apply text mutations on reopen,
+        // and an UPDATE changes total_docs by ZERO — the open-time count
+        // predicate cannot see the lost tombstone/re-post. Bounded try-write
+        // past the drain wait above: if the builder still holds a lock, skip
+        // — same exposure as before this fix, never worse.
+        if !self.try_flush_text_indexes_bounded(std::time::Duration::from_secs(2)) {
+            warn_log!(
+                "[checkpoint] FTS flush skipped (index lock contention) — \
+                 text index may lag until close"
+            );
+        }
+
         let checkpoint_done = if immutable_queue_len == 0 || !self.col_segment_stores.is_empty() {
             // All data has been flushed:
             // - LSM memtables are empty (immutable_queue is 0), OR

motedb_python-0.12.9/tests/repro_multirow_update_fts.rs

@@ -0,0 +1,41 @@
+//! Multi-row UPDATE × FTS: only rows the UPDATE touched may change their
+//! match sets. Rows 0..149 become "gamma delta"; rows 150..299 keep
+//! "alpha beta {i}". A stale index (lost term tombstones) would return
+//! alpha=300 (phantoms) or gamma<150 (missing).
+use motedb::{DBConfig, Database};
+use tempfile::TempDir;
+
+fn n(db: &Database, sql: &str) -> i64 {
+    let r = db.execute(sql).unwrap().materialize().unwrap();
+    let (_, rows) = r.select_rows().unwrap();
+    match &rows[0][0] {
+        motedb::types::Value::Integer(i) => *i,
+        other => panic!("{other:?}"),
+    }
+}
+
+#[test]
+fn multirow_update_fts_exact_matches() {
+    let dir = TempDir::new().unwrap();
+    let mut config = DBConfig::for_testing();
+    config.auto_checkpoint = None;
+    let db = Database::create_with_config(dir.path().join("x.mote"), config).unwrap();
+    db.execute("CREATE TABLE c (id INTEGER PRIMARY KEY, v TEXT)").unwrap();
+    db.execute("CREATE TEXT INDEX ci ON c(v)").unwrap();
+    for i in 0..300 {
+        db.execute(&format!("INSERT INTO c VALUES ({i}, 'alpha beta {i}')"))
+            .unwrap();
+    }
+    // Checkpoint so the auto-flush threshold fires for the insert postings.
+    db.checkpoint().unwrap();
+    let pre = n(&db, "SELECT COUNT(*) FROM c WHERE MATCH(v, 'alpha')");
+    assert_eq!(pre, 300, "pre-update sanity");
+
+    db.execute("UPDATE c SET v = 'gamma delta' WHERE id < 150").unwrap();
+
+    let post = n(&db, "SELECT COUNT(*) FROM c WHERE MATCH(v, 'alpha')");
+    let gamma = n(&db, "SELECT COUNT(*) FROM c WHERE MATCH(v, 'gamma')");
+    println!("post-update: alpha={post} (want 150) gamma={gamma} (want 150)");
+    assert_eq!(gamma, 150, "updated rows must match the new text");
+    assert_eq!(post, 150, "only untouched rows may still match the old text");
+}