motedb-python 0.14.0__tar.gz → 0.15.0__tar.gz

motedb_python-0.15.0/.github/workflows/node-publish.yml

@@ -0,0 +1,185 @@
+name: Node SDK publish (npm)
+
+# Multi-platform prebuilt napi binaries → npm optional packages:
+#   motedb (main) + motedb-darwin-arm64 / -darwin-x64 /
+#   motedb-linux-x64-gnu / -linux-arm64-gnu / -win32-x64-msvc
+# Triggers on v* tags (publish) and PRs touching the binding (build-only).
+
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+    paths:
+      - "bindings/node/**"
+      - ".github/workflows/node-publish.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: node-publish-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-latest # arm64
+            target: aarch64-apple-darwin
+          - os: macos-13 # x64
+            target: x86_64-apple-darwin
+          - os: ubuntu-latest # x64 gnu
+            target: x86_64-unknown-linux-gnu
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: bindings/node
+          key: ${{ matrix.target }}
+
+      - name: Install napi CLI
+        working-directory: bindings/node
+        run: npm install --no-save @napi-rs/cli@3.10.8
+
+      - name: Build (napi layout)
+        working-directory: bindings/node
+        shell: bash
+        run: |
+          set -e
+          ARGS=(--release --platform --target ${{ matrix.target }} --js false --dts false)
+          if [[ "${{ matrix.target }}" == x86_64-unknown-linux-gnu ]]; then
+            # musl-free runners: keep default gnu toolchain
+            ARGS+=(--cargo-flags="--features jemalloc")
+          fi
+          npx napi build "${ARGS[@]}"
+
+      - name: Smoke (JS loader)
+        if: matrix.target == 'aarch64-apple-darwin' || matrix.target == 'x86_64-unknown-linux-gnu'
+        working-directory: bindings/node
+        shell: bash
+        run: |
+          cat > /tmp/smoke.js <<'JS'
+          const Database = require('../bindings/node');
+          const os = require('node:os'), path = require('node:path'), fs = require('node:fs');
+          const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'motedb-ci-'));
+          const db = new Database(path.join(dir, 't.mote'));
+          db.execute('CREATE TABLE t (id INT PRIMARY KEY, emb VECTOR(2), data BLOB)');
+          for (let i = 0; i < 10; i++) {
+            db.execute('INSERT INTO t VALUES (?, ?, ?)',
+              [i, [i, -i], Buffer.from([1, 2, i])]);
+          }
+          const nn = db.query('SELECT id FROM t ORDER BY emb <-> [5, -5] LIMIT 1');
+          if (nn[0].id !== 5) throw new Error('knn ' + JSON.stringify(nn));
+          db.checkpoint();
+          const again = new Database(path.join(dir, 't.mote'));
+          if (again.query('SELECT COUNT(*) AS n FROM t')[0].n !== 10) throw new Error('reopen');
+          again.close();
+          fs.rmSync(dir, { recursive: true, force: true });
+          console.log('smoke OK');
+          JS
+          node /tmp/smoke.js
+
+      - name: Upload binding artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: bindings-${{ matrix.target }}
+          path: bindings/node/*.node
+          if-no-files-found: error
+
+  package:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install napi CLI
+        working-directory: bindings/node
+        run: npm install --no-save @napi-rs/cli@3.10.8
+      - name: Create npm dirs
+        working-directory: bindings/node
+        run: npx napi create-npm-dirs
+      - uses: actions/download-artifact@v4
+        with:
+          path: bindings/node/artifacts
+      - name: Place binaries into npm dirs
+        working-directory: bindings/node
+        shell: bash
+        run: |
+          set -e
+          for d in artifacts/bindings-*; do
+            target="${d#artifacts/bindings-}"
+            npx napi artifacts "$d" --target "$target"
+          done
+          ls -R npm | head -40
+      - name: Dry-run publish (structure validation only)
+        if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
+        working-directory: bindings/node
+        shell: bash
+        run: |
+          set -e
+          # pre-publish performs REAL npm publishes, so staging (PRs) only
+          # validates each platform package with npm publish --dry-run.
+          for d in npm/*/; do
+            (cd "$d" && npm publish --dry-run --access public) || exit 1
+          done
+          npm pack --dry-run
+
+  publish:
+    needs: [build, package]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - name: Install napi CLI
+        working-directory: bindings/node
+        run: npm install --no-save @napi-rs/cli@3.10.8
+      - name: Create npm dirs
+        working-directory: bindings/node
+        run: npx napi create-npm-dirs
+      - uses: actions/download-artifact@v4
+        with:
+          path: bindings/node/artifacts
+      - name: Place binaries into npm dirs
+        working-directory: bindings/node
+        shell: bash
+        run: |
+          set -e
+          for d in artifacts/bindings-*; do
+            target="${d#artifacts/bindings-}"
+            npx napi artifacts "$d" --target "$target"
+          done
+      - name: Publish platform packages + root
+        # 🔑 napi pre-publish IS the publish command: it validates all
+        # platform packages, then runs `npm publish` for each + the root.
+        # Requires the NPM_TOKEN secret (automation token, npmjs.com →
+        # motedb → Access Tokens → Generate). Without it this job fails
+        # with ENEEDAUTH.
+        working-directory: bindings/node
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: ./node_modules/.bin/napi pre-publish -p npm

{motedb_python-0.14.0 → motedb_python-0.15.0}/CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## [0.15.0] — 2026-10-17
+
+### 存储文件布局收敛 (docs/design/2026-10-file-layout{,-plan}.md, P1~P4)
+
+- **P1 惰性文件创建 + 死文件清理**: WAL 分区文件首写物化、CHECKPOINT
+  由截断改为删除(缺失=空语义); 纯 Standard 库不再创建空 `columnar/`;
+  LSM blob 首写物化; `indexes/timestamp.idx` 惰性化(LazyTsIndex, 无
+  TIMESTAMP 列的库不建 `indexes/`); `fts_indexes.fresh` → `.clean_close`
+  (旧名一次性兼容)。空库固定文件 11→4, 零写入库常驻 fd 6→1
+- **P2 全局单一 MANIFEST**: v2 记录携带 table_id + DropTable;
+  全库一个 `columnar_ms/MANIFEST` — 每表 -1 文件 -1 常驻 fd, fd 不再随
+  表数线性增长(50 表实测进程 fd<40, 原为 56+)。v0.14 旧布局打开即
+  自动迁移(先写后删 + 重入幂等); manifest 尾损坏孤儿领养语义不变
+- **P3 meta.bin 四合一**: catalog/index 元数据/LSN/干净关闭旗标并入
+  单个分节容器(每节 CRC32 + header flags), 任一节更新整文件原子重写;
+  旧三文件字节透明采纳后清理。🔒 catalog 节损坏/魔数不识别 → fail-fast
+  硬错误(对齐旧 corrupt catalog 行为, 杜绝空注册表覆盖备份)
+- **P4 EXPORT/IMPORT 单文件快照 (MOTESNAP)**: `EXPORT DB TO 'snap.mote'
+  [COMPRESSED]` — 数据库的"运输形态": 顺序流式条目 + 每文件 CRC32 +
+  逐文件 zstd, 1MiB 缓冲内存有界; 静默纪律复用 backup_to 全套
+  (CAS+checkpoint_mutex+全写条纹+WAL 截断)。导入: 路径穿越防护 +
+  逐条校验 + 截断检测, 产物即 P3 布局。Rust API/FFI/Python/Node/Go
+  全接线(`export_snapshot`/`open_snapshot`/`export_to`/
+  `import_snapshot`/`ExportSnapshot`/`ImportSnapshot`)
+- **总账**: 库固定文件 11→4(.lock/meta.bin/MANIFEST/数据段); 文件
+  3+表数+索引数; fd 恒定个位数; 断电语义未动(temp+rename/孤儿领养/
+  per-segment mmap); 每阶段旧格式读兼容。测试: test_file_layout 5/5 ·
+  test_global_manifest 8/8 · test_snapshot 5/5 · corruption 4/4 ·
+  全量回归零 FAILED · 同机 A/B(file_layout_bench) 吞吐零回退
+- **F1 性能修复(布局收敛审查发现)**: 全局 MANIFEST 增量内存状态 — 打开
+  时解析一次(原每 store 全量重解析, N 表 = N 次); manifest compaction —
+  文件超过 max(64KB, 4×活跃态)时最简重写(AddSegment×active + Retired×
+  文件仍在的退役 id + DropTable), 退役 id 按段文件存在性裁剪(段 id 单调
+  不复用, 文件已删者彻底遗忘) → churn 下有界常量。实测 50 表×60 轮:
+  manifest 210KB→17KB, 打开 77ms→17.6ms(4.4×); 修复 ever_seen 多重集
+  计数膨胀 2-3× 导致阈值永不触发的 bug。恢复扫描 Vec→HashSet
+- **F2 checkpoint 成本优化(纯省略型, 零持久化语义变化)**: 分解发现脏
+  checkpoint ~28ms 中三项是"写没变的数据" — ① AUTO_INCREMENT 计数器
+  未变也全量重写 catalog 节 → registry 脏标记(写方持锁置位/快照持锁
+  清除, 无丢更新窗口), 干净则零 fsync; ② LSN 节与 catalog 节两次整文件
+  重写 → update_sections 合并为单次原子重写; ③ manifest 无新记录也
+  fsync → append/sync 脏标记, 空转跳过。noop checkpoint 0.05ms 不变;
+  实测脏 checkpoint: 1 表 28→24.5ms, 50 表 42→24.6ms (表数平坦化,
+  每表边际成本 ~0.3ms→~0)。剩余固定成本: legacy 双写缓冲 ~5ms(方案 E
+  范畴)、WAL 截断 3.3ms 与 meta LSN 重写 4.1ms(均为真耐久性开销)。
+  新增 examples/probe_ckpt.rs
+- **BLOB 缺口完全修复 (v0.13 已知缺口关闭)**: WHERE <int 列> <op> <
+  字面量> 路由的 scan_i64_filtered_limit 两处缺陷 — ① 文本段装载门只
+  匹配 ColumnTypeTag::Text(Blob 列不装载) ② 输出臂缺 ColumnType::Blob
+  — 修复后 int 过滤查询下 blob 列(裸投影/LENGTH/混合列/ORDER BY/重开)
+  全部正确。隔离单测 + SQL 级回归 test_blob_type 5/5
+- **🔑 方案 E: TimeSeries 引擎统一 (v0.15 最大结构清理)**: TIMESERIES(ts)
+  表改由统一的 ColSegmentStore 服务 — 与标准表同一条写/读/恢复路径,
+  旧 ColumnarStore 引擎退出运行时 (仅保留只读迁移用途)。写路径:
+  get_or_create 放开 + INSERT 统一准备路径 + API 快解析去 TS 绕行;
+  读路径: 移除 executor 10 处 TS 专属路由/优化臂 (latest_by/order_limit/
+  simple_aggregate/columnar_select/窗口源等, 死代码 ~600 行删除),
+  LATEST BY/ORDER BY/聚合走通用路径; 恢复: WAL 回放并入标准 by_table
+  重放; 迁移: 打开时 .mcdb → 段存储一次性拷贝(幂等) + next_row_id
+  推进(修复迁移后新插入覆盖同号迁移行 — 探针实测发现); TTL/DELETE
+  时间窗重写为段存储 tombstone 版 (gc_timeseries)。顺带修复两个被旧
+  路径掩盖的存量 bug: ① TableRowStreamingInner Columnar 解码缺
+  TIMESTAMP 臂(物化路径读 ts 变 Integer) ② BTree superblock 内联页偏移
+  表超 4096 保留区 — 任何 10 万行 ts-first 表 close 即炸("SuperBlock
+  too large"), v3 64KB 保留 + >2M 键降级重建阀。实测: TS 与标准表
+  checkpoint 同价 (18.2ms vs 18.3ms, legacy flush 退出); 迁移探针全绿
+  (3000 行 .mcdb → 段存储 → 新插入/LATEST BY/重开无重复无丢失);
+  TS 语义 13+18、columnar/crash/backup 全绿
+- **🔑 容器模式 (只读快照直开)**: `Database::open_readonly('snap.mote')`
+  及 `open()` 自动路由(命中 MOTESNAP 魔数的文件) — 部署形态落地: 固件
+  预置库一个文件分发, 打开即查。实现: 容器幂等解包到系统临时目录的
+  per-container 缓存(FNV 路径哈希 + size/mtime 新鲜度戳, 容器变更自动
+  重解包); 引擎级只读门 — 全部写语句拒绝(SQL 快路径+executor 双入口+
+  insert_rows 直写 API), checkpoint/vacuum/backup/export 禁用, 不取
+  flock(多读者共存), 后台写线程不启动, 关闭免盖章; trusted-clean 跳过
+  崩溃校验(容器导出时已静默+checkpoint)。源容器文件字节级不变(验收
+  断言)。回归 test_snapshot 6/6(查询正确性含 BLOB/TS/FTS、八类写拒绝、
+  字节不变、自动路由、双句柄共存、非容器报错)
+- **发布前审计修复 ×4**: ① BTree read_superblock 对 <64KB 文件 read_exact
+  EOF — v2 升级路径与零页 v3 文件(空表建索引)重开即炸; 改 EOF-容忍读+
+  零填充 ② execute_prepared/many 走 execute_streaming_ref — 绕过容器
+  只读门, 补门 ③ Python/Node 构造器 create-or-open 启发式绕过 open()
+  容器自动路由 — Python 补魔数检测, Node/Go 经 api::open 已覆盖(FFI
+  直连) ④ create+read_only 组合显式拒绝。bindings 全面复验(方案 E 后
+  首次): Python e2e×3 + TS/容器冒烟、Node 冒烟×2、Go 测试×7 全过;
+  e2e time_bucket 断言适配通用 GROUP BY 哈希序
+- **发布前审计轮 2 (升级路径专项) ×3**:
+  - 🔴 BTree v3 版本检查曾把存量 v2 索引文件静默重置为空 — 干净关闭的库
+    无 WAL 重放 → 索引重建被跳过 → 所有列索引升级即丢(索引驱动查询
+    悄悄返回空)。改为 v2 保持可读(序列化布局未变, 仅写侧保留区扩大),
+    仅 v1 重建、更新版本硬错误。回归: 索引版本字节改 2 后重开查询正确
+  - 🔴 方案 E 迁移曾位于 WAL 回放之后 — 崩溃升级(旧库带未 checkpoint
+    的 WAL)时回放先填 store → '非空即跳过迁移' → .mcdb 已 checkpoint
+    行丢失; 且即便迁移, 其版本时间戳高于回放行, 旧行会错误胜出。迁移
+    移到回放前(空 store 判定成立 + 回放行 newest-wins 正确覆盖), 计数
+    播种加守卫(有重放的表不播, COUNT 走扫描保正确)。回归: TS 崩溃恢复
+    (300 行不 checkpoint 丢句柄重开全量可见)
+  - 🟡 多进程同时首开同一容器: 解包竞争落败方曾直接报错 — 改私有临时
+    目录 + 戳最后写入 + 原子 rename 舞步(胜者采纳/陈旧替换)。回归:
+    并发 open_readonly 双成功
+- **发布前审计轮 3 (派生数据自愈链) ×3**:
+  - 🔴 列索引静默空泛化修复: BTree 降级阀(>2M 键, 偏移表被丢弃 → 打开
+    重置为空)及任何未来'索引载入为空'路径, 在干净关闭(无 WAL 重放)下
+    永不重建 — 索引驱动查询悄悄返空。重建门扩展为 total_row_ids==0
+    也触发(空表上重建为廉价 no-op, 自愈)。回归: 手工置空索引文件 →
+    重开 → 查询正确
+  - 🟡 容器陈旧替换链验证: 同路径容器被替换(重新导出)后, size/mtime
+    戳不匹配 → 自动重解包 → 新数据可见(新增回归测试)
+  - 🟡 孤儿 legacy 目录清扫: DROP 过的表在 columnar/<table_id>/ 的
+    .mcdb 数据永占空间(迁移只走 registry 表) — 打开时按 registry
+    id 集清扫。doctor 确认只读安全
+- 遗留可选: —
+
+### SDK cycle
+
+- **🔑 Node.js SDK(bindings/node, napi-rs v3)**: Database 类 —
+  create-or-open / execute(mutations, ?-params) / query(行对象) /
+  checkpoint / backupTo / close / doctor。值映射: number↔Integer/Float ·
+  number[]↔VECTOR · Buffer 参数↔BLOB · BLOB 结果=base64 ·
+  TIMESTAMP↔µs。napi 3.14 适配: build.rs 注入 -undefined
+  dynamic_lookup(macOS) · Null::from_napi_value 不校验类型 → null 探针
+  必须放链尾(smoke 实抓全变 NULL)。JS 冒烟 debug+release 全过
+- **🔑 Go SDK(bindings/go, cgo)**: Database — Open/Close/Exec/Query/
+  Checkpoint/BackupTo, 经扩展的 C ABI(motedb_db_open/db_exec JSON
+  参数化/last_error/checkpoint/backup)。值映射: int/int64/float64 ·
+  string · bool · nil · []float64↔VECTOR · []byte↔BLOB(JSON 边界对称
+  {"$blob": base64}, 出入一致) · time.Time↔TIMESTAMP。go test 5 项:
+  CRUD/类型往返/向量 KNN/重开耐久/EPISODES/ASOF/backup 快照
+- **npm 预构建流水线(.github/workflows/node-publish.yml)**:
+  五平台矩阵(macOS arm64/x64 · Linux x64/arm64-gnu · Windows x64)
+  napi build --platform → artifact 上传; PR staging = 每平台
+  npm publish --dry-run 结构校验(pre-publish 含真实发布, PR 严禁);
+  tag 触发 = napi pre-publish 逐包发布 + 根包。
+  本地验证: napi 布局 optionalDependencies 装载 ALL OK(修 index.js
+  suffix 丢连字符)、五平台 dry-run 全过、根包 files 白名单修正
+  (*.node 曾把 8.8MB 开发副本打进根包 tarball)。
+  ⚠️ npm 发布需配置 NPM_TOKEN secret
+- C ABI 扩展(src/ffi.rs): motedb_db_open/db_exec(JSON 参数化, 统一
+  execute+query 出 {"columns","rows","affectedRows"})/
+  db_checkpoint/db_backup/db_free_string/motedb_last_error; 句柄切
+  高层 api::Database
+
 ## [0.14.0] — 2026-10-12
 
 - **🔑 ASOF JOIN(W8, v0.14)**: 机器人帧↔状态对齐原语

{motedb_python-0.14.0 → motedb_python-0.15.0}/Cargo.lock

@@ -112,6 +112,12 @@ version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
 [[package]]
 name = "bimap"
 version = "0.6.3"
@@ -921,9 +927,10 @@ dependencies = [
 
 [[package]]
 name = "motedb"
-version = "0.14.0"
+version = "0.15.0"
 dependencies = [
  "arc-swap",
+ "base64",
  "bincode",
  "clap",
  "crc32fast",

{motedb_python-0.14.0 → motedb_python-0.15.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "motedb"
-version = "0.14.0"
+version = "0.15.0"
 edition = "2021"
 rust-version = "1.87"
 description = "AI-native embedded multimodal database for embodied intelligence (robots, AR glasses, industrial arms)."
@@ -65,6 +65,7 @@ roaring = "0.10"
 serde = { version = "1.0", features = ["derive"] }
 bincode = "1.3"  # Binary serialization for indexes and storage
 serde_json = "1.0"  # JSON for manifest and metadata
+base64 = "0.22"
 
 # Error handling (used throughout)
 thiserror = "1.0"

{motedb_python-0.14.0 → motedb_python-0.15.0}/PKG-INFO

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

{motedb_python-0.14.0 → motedb_python-0.15.0}/README.md

@@ -270,6 +270,15 @@ Every push runs through three CI workflows:
 | **Perf Gate** | Query-shape latency *ratios* vs a full-scan baseline — machine-independent budgets that catch complexity-class regressions (e.g. an O(N²) path that slipped through once) |
 | **Fuzz** (daily) | 5 min × 2 targets (`fuzz_sql_parser`, `fuzz_wal_recover`) under AddressSanitizer — found and fixed a parser stack-overflow on day one |
 
+### Multi-language SDKs
+
+| Language | Package | Status |
+|---|---|---|
+| Rust | `motedb` (crates.io) | stable |
+| Python | `motedb-python` (PyPI) | stable |
+| Node.js | `motedb` (npm, bindings/node, napi-rs v3) | preview (linux-gnu builds; musl not yet) |
+| Go | `bindings/go` (cgo) | preview |
+
 ## Installation
 
 ```bash

motedb_python-0.15.0/RELEASE_NOTES.md

@@ -0,0 +1,99 @@
+# MoteDB v0.15.0
+
+四条主线:**多语言 SDK 生态**(Node.js / Go + npm 五平台预构建流水线)、
+**存储文件布局收敛**(P1~P4 + 只读容器模式)、**TimeSeries 引擎统一**
+(方案 E)、以及 **F1/F2 性能战役与三轮发布前审计**(共 10 项修复)。
+核心 crate / Python / Node 版本对齐 0.15.0。
+
+## 一、存储文件布局收敛 — "采集是目录, 运输是一个文件"
+
+具身智能数据生命周期(采集→运输→训练→部署)对磁盘形态的要求不同:采集期
+要断电安全与高性能(目录形态的强项),运输期要单文件可拷贝/校验/续传,
+部署期要只读打开。本版按此定位收敛运行时布局,并补齐运输与部署形态。
+
+### 数字总账(v0.14 → v0.15)
+
+| 指标 | v0.14 | v0.15 |
+|---|---|---|
+| 空库固定文件 | 11 | **4**(.lock / meta.bin / columnar_ms/MANIFEST) |
+| 50 表库文件 | ~111 | ~55(= 3+表数+索引数) |
+| 50 表运行时 fd | 56+ | **个位数**(50 表进程总 fd 实测 <40) |
+| 打开耗时(50 表×60 轮 churn) | 77ms,随历史线性恶化 | **17.6ms**,有界常量(F1) |
+| manifest 体积 | 无上限线性增长 | **有界常量**(F1 compaction) |
+| 脏 checkpoint 50 表 | ~42ms | **24.6ms 平坦**(F2) |
+| 运输形态 | 目录拷贝 | **单文件 .mote 快照**(可压缩/校验) |
+| 部署形态 | 无 | **open('snap.mote') 只读直开** |
+| 断电语义 | — | 未动(temp+rename/孤儿领养/mmap) |
+| 旧库升级 | — | 打开即自动迁移(每阶段前向兼容) |
+
+- **P1 惰性创建**: WAL 分区首写物化、CHECKPOINT 删文件替代截断、
+  columnar//LSM blob/timestamp.idx 全部按需 — 零字节残留消失
+- **P2 全局单一 MANIFEST**: 记录携带 table_id,全库一个文件 — fd 线性项
+  消除;旧 per-table 布局打开即迁移(崩溃安全幂等)
+- **P3 meta.bin 四合一**: catalog/index 元数据/LSN/关闭旗标并入分节容器
+  (每节 CRC32);catalog 节损坏 fail-fast 硬错误
+- **P4 EXPORT DB TO 单文件快照 (MOTESNAP)**: 流式条目+每文件 CRC32+
+  逐文件 zstd;静默纪律复用 backup_to 全套;五语言接线
+- **只读容器模式**: `Database::open_readonly('snap.mote')` 及 open()
+  自动路由 — 幂等解包缓存(多进程竞争安全)、引擎级只读门(全部写路径
+  拒绝)、多读者共存、源容器字节不变
+
+## 二、TimeSeries 引擎统一 (方案 E)
+
+TIMESERIES(ts) 表与标准表同一条写/读/恢复路径,旧 ColumnarStore 引擎
+退出运行时(仅留只读迁移):executor 10 处 TS 专属路由臂删除(净 -1226
+行),WAL 回放并入标准路径,.mcdb 数据打开时一次性迁移(崩溃升级窗口
+经审计修复:迁移先于回放+next_row_id 推进),TTL/DELETE 时间窗重写为
+段存储 tombstone 版。实测 TS 与标准表 checkpoint 同价(18.2ms)。
+
+顺带修复两个被旧路径掩盖的存量 bug:物化读回 TIMESTAMP 变 Integer;
+**BTree superblock 内联页偏移表超 4096 保留区 — 任何 10 万行 ts-first
+表 close 即炸**(v3: 64KB 保留 + 降级阀 + 空载自愈)。
+
+## 三、性能战役 (F1/F2)
+
+- **F1 全局 MANIFEST 增量状态 + 有界 compaction**: 打开时解析一次(原
+  每表全量重解析);文件超阈值最简重写;退役 id 按段文件存在性裁剪 —
+  打开 77ms→17.6ms(4.4×),manifest 210KB→17KB
+- **F2 checkpoint 三项省略型优化**: 计数器脏标记/LSN+catalog 合并单
+  重写/manifest 空转跳 fsync — 50 表 42→24.6ms 表数平坦化,零持久化
+  语义变化
+
+## 四、v0.13 已知缺口关闭
+
+BLOB 在 int 过滤查询下的双缺陷(装载门只匹配 Text tag + 输出臂缺 Blob)
+— 修复后裸投影/LENGTH/混合列/重开/ORDER BY 全部正确。
+
+## 五、三轮发布前审计(10 项修复)
+
+- **轮 1(新代码自身)**: BTree read_superblock EOF 容忍;execute_prepared
+  绕过只读门;Python 构造器绕过容器自动路由;create+read_only 拒绝
+- **轮 2(升级/并发窗口)**: v2 索引读兼容(曾升级即静默清空全部列索引);
+  崩溃升级迁移序(曾丢 .mcdb 已 checkpoint 行);容器解包竞争(原子
+  rename 舞步 + 同进程临时目录唯一化)
+- **轮 3(派生数据自愈)**: 空载列索引打开时从源重建(降级阀/未来静默
+  空路径自愈);容器陈旧替换链;孤儿 legacy 目录清扫
+
+## 六、SDK cycle
+
+- **Node.js SDK**(napi-rs v3): execute(?-params)/query/checkpoint/
+  backupTo/exportSnapshot/openSnapshot/openReadonly/close/doctor
+- **Go SDK**(cgo): Open/Exec/Query/Checkpoint/BackupTo/ExportSnapshot/
+  ImportSnapshot;go test 7 项
+- **Python**: export_to/import_snapshot + 构造器容器自动路由;e2e×3
+- **npm 预构建流水线**: 五平台矩阵,tag 触发发布(需 NPM_TOKEN)
+- **C ABI**: db_open/db_exec(JSON 参数化)/checkpoint/backup/db_export/
+  db_import/last_error
+
+## 升级与兼容
+
+- 老库(v0.12~v0.14)直接打开:惰性迁移自动完成,无需停机;v2 索引文件
+  保持可读,空/损坏索引自动从源重建
+- `backup_to`(目录快照)与 `EXPORT DB`(单文件)并存;容器模式覆盖
+  部署形态
+
+## 已知限制
+
+- npm 发布流水线待 NPM_TOKEN 配置后重跑
+- timestamp 索引覆盖 ts 首列表;非首列 ts 的 query_timestamp_range
+  走扫描(与 v0.14 相同)

motedb_python-0.15.0/bindings/go/README.md

@@ -0,0 +1,44 @@
+# motedb (Go)
+
+AI-native embedded multimodal database — Go bindings via the C ABI
+(`src/ffi.rs`).
+
+## Build
+
+Requires the MoteDB static library (built at the repo root):
+
+```bash
+cargo build --release          # → target/release/libmotedb.a
+cd bindings/go && go test ./...
+```
+
+The cgo directives default to repo-relative paths; override with
+`CGO_CFLAGS` / `CGO_LDFLAGS` for prebuilt libraries elsewhere.
+
+## Usage
+
+```go
+import motedb "github.com/motedb/motedb/bindings/go"
+
+db, err := motedb.Open("/data/robot.mote") // creates when missing
+_, err = db.Exec("INSERT INTO frames VALUES (?, ?, ?)",
+    "f1", time.Now(), []byte{0xde, 0xad})          // []byte → BLOB
+rows, err := db.Query(
+    "SELECT name FROM robots ORDER BY emb <-> ? LIMIT 1",
+    []float64{0.1, 0.9, 0.2})                       // []float64 → VECTOR
+db.Checkpoint()
+db.BackupTo("/data/snap.mote")
+db.Close()
+```
+
+## Value mapping
+
+| SQL type | Go param | Go result |
+|---|---|---|
+| INTEGER / FLOAT | `int` / `int64` / `float64` | `float64` |
+| TEXT | `string` | `string` |
+| BOOLEAN | `bool` | `bool` |
+| NULL | `nil` | `nil` |
+| VECTOR(n) | `[]float64` | `[]any` (numbers) |
+| BLOB | `[]byte` | `[]byte` (base64 over the JSON boundary) |
+| TIMESTAMP | `time.Time` | `int64` µs-since-epoch |

motedb_python-0.15.0/bindings/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/motedb/motedb/bindings/go
+
+go 1.22