@h-ai/vecdb 0.1.0-alpha.66 → 0.1.0-alpha.68

package/dist/index.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { core, ok, err } from '@h-ai/core';
+import { core, err, ok } from '@h-ai/core';
+import process from 'process';
 import { spawn } from 'child_process';
-import { setTimeout } from 'timers/promises';
+import { setTimeout as setTimeout$1 } from 'timers/promises';
 import { createRequire } from 'module';
 import { createHash } from 'crypto';
 
@@ -20,6 +21,11 @@ var en_US_default = {
   vecdb_connectionFailed: "Failed to connect to vector database: {error}",
   vecdb_collectionNotFound: "Collection not found: {name}",
   vecdb_collectionAlreadyExists: "Collection already exists: {name}",
+  vecdb_invalidCollectionSchema: "Collection has no valid persisted vector dimension or distance metric: {name}",
+  vecdb_atomicUpsertUnavailable: "LanceDB collection or driver lacks safe atomic merge primary-key support; no writes were performed. Rebuild the collection or use a supported driver",
+  vecdb_duplicateDocumentIds: "Vector document IDs must be unique within a batch; no writes were performed",
+  vecdb_jsonMetadataRequired: "LanceDB collection requires native JSON metadata; rebuild legacy string metadata collections before writing or filtering",
+  vecdb_invalidMetadataFilter: "LanceDB metadata filter must be a plain object of top-level string, finite number, boolean or null values; nested objects, arrays and undefined are unsupported",
   vecdb_dimensionMismatch: "Vector dimension mismatch: expected {expected}, actual {actual}",
   vecdb_insertFailed: "Failed to insert vectors: {error}",
   vecdb_deleteFailed: "Failed to delete vectors: {error}",
@@ -29,7 +35,43 @@ var en_US_default = {
   vecdb_serializationFailed: "Serialization/deserialization failed: {error}",
   vecdb_invalidDimension: "Invalid vector dimension: {dimension}, must be a positive integer",
   vecdb_configPathRequired: "Database storage path is required",
-  vecdb_configDatabaseRequired: "Database name is required"
+  vecdb_configDatabaseRequired: "Database name is required",
+  vecdb_sharedBackendRequired: "Production mode requires a shared backend; local files and memory backends are for development or explicit end-to-end tests.",
+  vecdb_chromaEndpointInvalid: "Chroma requires an HTTP(S) root endpoint without credentials, path prefix, query or fragment",
+  vecdb_chromaTokenInvalid: "Chroma Bearer token must contain only printable ASCII characters without whitespace"
+};
+
+// messages/ja-JP.json
+var ja_JP_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  vecdb_notInitialized: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u304C\u521D\u671F\u5316\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u5148\u306Bvecdb.init()\u3092\u547C\u3073\u51FA\u3057\u3066\u304F\u3060\u3055\u3044",
+  vecdb_initFailed: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u521D\u671F\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_closeFailed: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u7D42\u4E86\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_configError: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u8A2D\u5B9A\u306E\u691C\u8A3C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_initInProgress: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u521D\u671F\u5316\u306F\u65E2\u306B\u5B9F\u884C\u4E2D\u3067\u3059",
+  vecdb_unsupportedType: "\u672A\u5BFE\u5FDC\u306E\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u7A2E\u985E\u3067\u3059: {type}",
+  vecdb_driverNotFound: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u30C9\u30E9\u30A4\u30D0\u30FC\u304C\u30A4\u30F3\u30B9\u30C8\u30FC\u30EB\u3055\u308C\u3066\u3044\u307E\u305B\u3093: {driver}\u3002pnpm add {driver}\u3092\u5B9F\u884C\u3057\u3066\u304F\u3060\u3055\u3044",
+  vecdb_connectionFailed: "\u30D9\u30AF\u30C8\u30EB\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u3078\u306E\u63A5\u7D9A\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_collectionNotFound: "\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093: {name}",
+  vecdb_collectionAlreadyExists: "\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u306F\u65E2\u306B\u5B58\u5728\u3057\u307E\u3059: {name}",
+  vecdb_invalidCollectionSchema: "\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u306B\u6709\u52B9\u306A\u6C38\u7D9A\u5316\u6E08\u307F\u306E\u30D9\u30AF\u30C8\u30EB\u6B21\u5143\u307E\u305F\u306F\u8DDD\u96E2\u30E1\u30C8\u30EA\u30C3\u30AF\u304C\u3042\u308A\u307E\u305B\u3093\uFF1A{name}",
+  vecdb_atomicUpsertUnavailable: "LanceDB \u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u307E\u305F\u306F\u30C9\u30E9\u30A4\u30D0\u30FC\u306B\u5B89\u5168\u306A\u4E3B\u30AD\u30FC\u306B\u3088\u308B\u30A2\u30C8\u30DF\u30C3\u30AF\u306A merge \u6A5F\u80FD\u304C\u3042\u308A\u307E\u305B\u3093\u3002\u66F8\u304D\u8FBC\u307F\u306F\u884C\u3063\u3066\u3044\u307E\u305B\u3093\u3002\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u3092\u518D\u4F5C\u6210\u3059\u308B\u304B\u3001\u5BFE\u5FDC\u30C9\u30E9\u30A4\u30D0\u30FC\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044",
+  vecdb_duplicateDocumentIds: "\u540C\u4E00\u30D0\u30C3\u30C1\u306E\u30D9\u30AF\u30C8\u30EB\u6587\u66F8 ID \u306F\u4E00\u610F\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059\u3002\u66F8\u304D\u8FBC\u307F\u306F\u884C\u3063\u3066\u3044\u307E\u305B\u3093",
+  vecdb_jsonMetadataRequired: "LanceDB \u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u306B\u306F\u30CD\u30A4\u30C6\u30A3\u30D6 JSON \u30E1\u30BF\u30C7\u30FC\u30BF\u304C\u5FC5\u8981\u3067\u3059\u3002\u65E7\u5F62\u5F0F\u306E\u6587\u5B57\u5217\u30E1\u30BF\u30C7\u30FC\u30BF\u3092\u4F7F\u7528\u3059\u308B\u30B3\u30EC\u30AF\u30B7\u30E7\u30F3\u306F\u3001\u66F8\u304D\u8FBC\u307F\u3084\u30D5\u30A3\u30EB\u30BF\u30FC\u51E6\u7406\u306E\u524D\u306B\u518D\u4F5C\u6210\u3057\u3066\u304F\u3060\u3055\u3044",
+  vecdb_invalidMetadataFilter: "LanceDB \u30E1\u30BF\u30C7\u30FC\u30BF\u30D5\u30A3\u30EB\u30BF\u30FC\u306F\u901A\u5E38\u306E\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u3068\u3057\u3001\u6700\u4E0A\u4F4D\u306E\u5024\u306B\u306F\u6587\u5B57\u5217\u3001\u6709\u9650\u6570\u3001\u771F\u507D\u5024\u3001null \u306E\u307F\u6307\u5B9A\u3067\u304D\u307E\u3059\u3002\u5165\u308C\u5B50\u306E\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u3001\u914D\u5217\u3001undefined \u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093",
+  vecdb_dimensionMismatch: "\u30D9\u30AF\u30C8\u30EB\u306E\u6B21\u5143\u304C\u4E00\u81F4\u3057\u307E\u305B\u3093: \u671F\u5F85\u5024{expected}\u3001\u5B9F\u969B\u306E\u5024{actual}",
+  vecdb_insertFailed: "\u30D9\u30AF\u30C8\u30EB\u306E\u633F\u5165\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_deleteFailed: "\u30D9\u30AF\u30C8\u30EB\u306E\u524A\u9664\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_updateFailed: "\u30D9\u30AF\u30C8\u30EB\u306E\u66F4\u65B0\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_queryFailed: "\u30D9\u30AF\u30C8\u30EB\u306E\u691C\u7D22\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_indexBuildFailed: "\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u306E\u69CB\u7BC9\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_serializationFailed: "\u30B7\u30EA\u30A2\u30E9\u30A4\u30BA\u307E\u305F\u306F\u30C7\u30B7\u30EA\u30A2\u30E9\u30A4\u30BA\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  vecdb_invalidDimension: "\u30D9\u30AF\u30C8\u30EB\u306E\u6B21\u5143\u304C\u7121\u52B9\u3067\u3059: {dimension}\u3002\u6B63\u306E\u6574\u6570\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044",
+  vecdb_configPathRequired: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u4FDD\u5B58\u30D1\u30B9\u306F\u5FC5\u9808\u3067\u3059",
+  vecdb_configDatabaseRequired: "\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u540D\u306F\u5FC5\u9808\u3067\u3059",
+  vecdb_sharedBackendRequired: "\u672C\u756A\u74B0\u5883\u306B\u306F\u5171\u6709\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u304C\u5FC5\u8981\u3067\u3059\u3002\u30ED\u30FC\u30AB\u30EB\u30D5\u30A1\u30A4\u30EB\u3068\u30E1\u30E2\u30EA\u30FC\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u306F\u958B\u767A\u74B0\u5883\u307E\u305F\u306F\u660E\u793A\u7684\u306A E2E \u30C6\u30B9\u30C8\u3067\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059\u3002",
+  vecdb_chromaEndpointInvalid: "Chroma \u306B\u306F HTTP(S) \u306E\u30EB\u30FC\u30C8\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u8A8D\u8A3C\u60C5\u5831\u3001\u30D1\u30B9\u30D7\u30EC\u30D5\u30A3\u30C3\u30AF\u30B9\u3001\u30AF\u30A8\u30EA\u3001\u30D5\u30E9\u30B0\u30E1\u30F3\u30C8\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093",
+  vecdb_chromaTokenInvalid: "Chroma Bearer \u30C8\u30FC\u30AF\u30F3\u306B\u306F\u7A7A\u767D\u3092\u542B\u307E\u306A\u3044\u8868\u793A\u53EF\u80FD\u306A ASCII \u6587\u5B57\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059"
 };
 
 // messages/zh-CN.json
@@ -45,6 +87,11 @@ var zh_CN_default = {
   vecdb_connectionFailed: "\u8FDE\u63A5\u5411\u91CF\u6570\u636E\u5E93\u5931\u8D25: {error}",
   vecdb_collectionNotFound: "\u96C6\u5408\u4E0D\u5B58\u5728: {name}",
   vecdb_collectionAlreadyExists: "\u96C6\u5408\u5DF2\u5B58\u5728: {name}",
+  vecdb_invalidCollectionSchema: "\u96C6\u5408\u7F3A\u5C11\u6709\u6548\u7684\u6301\u4E45\u5316\u5411\u91CF\u7EF4\u5EA6\u6216\u8DDD\u79BB\u5EA6\u91CF\u5B9A\u4E49: {name}",
+  vecdb_atomicUpsertUnavailable: "LanceDB \u96C6\u5408\u6216\u9A71\u52A8\u7F3A\u5C11\u5B89\u5168\u7684\u539F\u5B50 merge \u4E3B\u952E\u80FD\u529B\uFF0C\u672A\u6267\u884C\u5199\u5165\uFF0C\u8BF7\u91CD\u5EFA\u96C6\u5408\u6216\u4F7F\u7528\u53D7\u652F\u6301\u7684\u9A71\u52A8",
+  vecdb_duplicateDocumentIds: "\u540C\u4E00\u6279\u5411\u91CF\u6587\u6863\u7684 ID \u4E0D\u5F97\u91CD\u590D\uFF0C\u672A\u6267\u884C\u5199\u5165",
+  vecdb_jsonMetadataRequired: "LanceDB \u96C6\u5408\u987B\u4F7F\u7528\u539F\u751F JSON \u5143\u6570\u636E\uFF0C\u65E7\u5B57\u7B26\u4E32\u5143\u6570\u636E\u96C6\u5408\u9700\u91CD\u5EFA\u540E\u624D\u80FD\u5199\u5165\u6216\u8FC7\u6EE4",
+  vecdb_invalidMetadataFilter: "LanceDB \u5143\u6570\u636E\u8FC7\u6EE4\u987B\u4E3A\u666E\u901A\u5BF9\u8C61\uFF0C\u503C\u4EC5\u652F\u6301\u9876\u5C42\u5B57\u7B26\u4E32\u3001\u6709\u9650\u6570\u503C\u3001\u5E03\u5C14\u6216 null\uFF1B\u4E0D\u652F\u6301\u5D4C\u5957\u5BF9\u8C61\u3001\u6570\u7EC4\u548C undefined",
   vecdb_dimensionMismatch: "\u5411\u91CF\u7EF4\u5EA6\u4E0D\u5339\u914D: \u671F\u671B {expected}\uFF0C\u5B9E\u9645 {actual}",
   vecdb_insertFailed: "\u63D2\u5165\u5411\u91CF\u5931\u8D25: {error}",
   vecdb_deleteFailed: "\u5220\u9664\u5411\u91CF\u5931\u8D25: {error}",
@@ -54,13 +101,17 @@ var zh_CN_default = {
   vecdb_serializationFailed: "\u5E8F\u5217\u5316/\u53CD\u5E8F\u5217\u5316\u5931\u8D25: {error}",
   vecdb_invalidDimension: "\u65E0\u6548\u7684\u5411\u91CF\u7EF4\u5EA6: {dimension}\uFF0C\u5FC5\u987B\u4E3A\u6B63\u6574\u6570",
   vecdb_configPathRequired: "\u6570\u636E\u5E93\u5B58\u50A8\u8DEF\u5F84\u4E0D\u80FD\u4E3A\u7A7A",
-  vecdb_configDatabaseRequired: "\u6570\u636E\u5E93\u540D\u79F0\u4E0D\u80FD\u4E3A\u7A7A"
+  vecdb_configDatabaseRequired: "\u6570\u636E\u5E93\u540D\u79F0\u4E0D\u80FD\u4E3A\u7A7A",
+  vecdb_sharedBackendRequired: "\u751F\u4EA7\u6A21\u5F0F\u9700\u8981\u8DE8\u8282\u70B9\u5171\u4EAB\u540E\u7AEF\uFF1B\u672C\u673A\u6587\u4EF6\u6216\u5185\u5B58\u540E\u7AEF\u4EC5\u7528\u4E8E\u5F00\u53D1\u548C\u663E\u5F0F\u7AEF\u5230\u7AEF\u6D4B\u8BD5\u3002",
+  vecdb_chromaEndpointInvalid: "Chroma \u4EC5\u652F\u6301 HTTP(S) \u6839\u7AEF\u70B9\uFF0C\u4E0D\u5F97\u5305\u542B\u51ED\u636E\u3001\u8DEF\u5F84\u524D\u7F00\u3001query \u6216 fragment",
+  vecdb_chromaTokenInvalid: "Chroma Bearer token \u4EC5\u652F\u6301\u65E0\u7A7A\u767D\u7684\u53EF\u6253\u5370 ASCII \u5B57\u7B26"
 };
 
 // src/vecdb-i18n.ts
 var vecdbM = core.i18n.createMessageGetter({
   "zh-CN": zh_CN_default,
-  "en-US": en_US_default
+  "en-US": en_US_default,
+  "ja-JP": ja_JP_default
 });
 
 // src/vecdb-config.ts
@@ -76,9 +127,9 @@ var OperationLogConfigFieldSchema = {
 };
 var LancedbConfigSchema = z.object({
   type: z.literal("lancedb"),
-  /** 数据库存储路径（本地目录） */
+  /** 持久化本地目录；独立节点的同名路径不会自动共享，分布式部署优先使用服务端后端。 */
   path: z.string().min(1, vecdbM("vecdb_configPathRequired")),
-  /** 距离度量（默认 cosine） */
+  /** 新建集合的默认距离度量；已有集合使用 Arrow schema 中的持久定义。 */
   metric: DistanceMetricSchema.optional(),
   ...OperationLogConfigFieldSchema
 });
@@ -119,14 +170,21 @@ var ChromaConfigSchema = z.object({
   type: z.literal("chroma"),
   /** 本地持久化路径（嵌入式模式：提供且无 url 时自动拉起本地服务） */
   path: z.string().optional(),
-  /** 已有 Chroma 服务 URL（提供时直连，不自动拉起进程） */
-  url: z.string().url().optional(),
+  /** Chroma HTTP(S) 根端点；不可包含凭据、路径前缀、query 或 fragment；提供时优先于 host/port。 */
+  url: z.string().url().refine((value) => {
+    try {
+      const endpoint = new URL(value);
+      return ["http:", "https:"].includes(endpoint.protocol) && !endpoint.username && !endpoint.password && endpoint.pathname === "/" && !endpoint.search && !endpoint.hash;
+    } catch {
+      return false;
+    }
+  }, { error: () => vecdbM("vecdb_chromaEndpointInvalid") }).optional(),
   /** 主机（默认 localhost） */
   host: z.string().default("localhost"),
   /** 端口（默认 8000） */
   port: z.number().int().min(1).max(65535).default(8e3),
-  /** API Key（可选，连接受保护的 Chroma 服务时使用） */
-  apiKey: z.string().optional(),
+  /** 可选 Bearer token，发送 Authorization 请求头；用于采用此协议的自托管服务/网关，不是 Chroma Cloud 配置。空串表示未配置。 */
+  apiKey: z.string().regex(/^[\x21-\x7E]*$/, { error: () => vecdbM("vecdb_chromaTokenInvalid") }).optional(),
   /** 拉起本地服务的可执行命令（默认 'chroma'，可指定绝对路径） */
   serverCommand: z.string().default("chroma"),
   /** 拉起本地服务的就绪等待超时（毫秒，默认 30000） */
@@ -365,14 +423,15 @@ function buildWhere(filter) {
   const entries = Object.entries(filter);
   if (entries.length === 0)
     return void 0;
-  if (entries.length === 1)
-    return { [entries[0][0]]: entries[0][1] };
-  return { $and: entries.map(([key, value]) => ({ [key]: value })) };
+  const where = entries.length === 1 ? { [entries[0][0]]: entries[0][1] } : { $and: entries.map(([key, value]) => ({ [key]: value })) };
+  return where;
 }
 function createChromaProvider() {
   let client = null;
   let config = null;
   let serverProcess = null;
+  let spawnFailed = false;
+  let closing = null;
   function isMissingModuleError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.includes("chromadb");
@@ -394,24 +453,93 @@ function createChromaProvider() {
       throw error;
     }
   }
-  function startEmbeddedServer(chromaConfig) {
+  async function startEmbeddedServer(chromaConfig) {
     const args = ["run", "--path", chromaConfig.path ?? "./data/chroma", "--host", chromaConfig.host, "--port", String(chromaConfig.port)];
     logger.info("Starting embedded Chroma server", { command: chromaConfig.serverCommand, host: chromaConfig.host, port: chromaConfig.port });
+    spawnFailed = false;
     const proc = spawn(chromaConfig.serverCommand, args, { stdio: "ignore" });
     proc.on("error", (error) => {
+      spawnFailed = proc.pid === void 0;
       logger.error("Chroma server process error", { error: error.message });
     });
     serverProcess = proc;
+    await new Promise((resolve, reject) => {
+      proc.once("spawn", resolve);
+      proc.once("error", reject);
+    });
   }
-  function stopEmbeddedServer() {
-    if (!serverProcess)
+  async function stopEmbeddedServer() {
+    const owned = serverProcess;
+    if (!owned)
       return;
-    try {
-      serverProcess.kill();
-    } catch (error) {
-      logger.warn("Failed to stop Chroma server", { error: error instanceof Error ? error.message : String(error) });
+    const hasExited = () => owned.exitCode !== null || owned.signalCode !== null || spawnFailed && owned.pid === void 0;
+    if (!hasExited()) {
+      const child = owned;
+      await new Promise((resolve, reject) => {
+        let timer;
+        let settled = false;
+        function cleanup() {
+          clearTimeout(timer);
+          child.removeListener("exit", exited);
+          child.removeListener("error", failed);
+        }
+        function exited() {
+          if (settled)
+            return;
+          settled = true;
+          cleanup();
+          resolve();
+        }
+        function failed(cause) {
+          if (settled)
+            return;
+          if (hasExited()) {
+            exited();
+            return;
+          }
+          settled = true;
+          cleanup();
+          reject(cause);
+        }
+        function signal(name) {
+          try {
+            if (!child.kill(name))
+              failed(new Error("Chroma child termination signal was rejected"));
+          } catch (cause) {
+            failed(cause instanceof Error ? cause : new Error(String(cause)));
+          }
+        }
+        child.once("exit", exited);
+        child.once("error", failed);
+        timer = setTimeout(() => {
+          timer = setTimeout(() => failed(new Error("Chroma child exit was not confirmed")), 1500);
+          signal("SIGKILL");
+        }, 1500);
+        if (hasExited())
+          exited();
+        else signal("SIGTERM");
+      });
     }
-    serverProcess = null;
+    if (serverProcess === owned)
+      serverProcess = null;
+  }
+  async function closeResources() {
+    if (!closing) {
+      client = null;
+      config = null;
+      closing = (async () => {
+        try {
+          await stopEmbeddedServer();
+          logger.info("Chroma connection closed");
+          return ok(void 0);
+        } catch (cause) {
+          return err({ ...HaiVecdbError.CONNECTION_FAILED, message: vecdbM("vecdb_closeFailed", { params: { error: cause instanceof Error ? cause.message : String(cause) } }), cause, ext: { cleanupPending: true } });
+        }
+      })().finally(() => {
+        closing = null;
+      });
+    }
+    return await closing;
   }
   async function waitForHeartbeat(chromaClient, timeout) {
     const deadline = Date.now() + timeout;
@@ -422,7 +550,7 @@ function createChromaProvider() {
         return;
       } catch (error) {
         lastError = error;
-        await setTimeout(HEARTBEAT_POLL_INTERVAL);
+        await setTimeout$1(HEARTBEAT_POLL_INTERVAL);
       }
     }
     throw new Error(`Chroma heartbeat timed out after ${timeout}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
@@ -447,7 +575,7 @@ function createChromaProvider() {
     async create(name, options) {
       logger.debug("Creating collection", { name, dimension: options.dimension, metric: options.metric });
       const existing = await client.listCollections();
-      const exists = existing.some((item) => (typeof item === "string" ? item : item.name) === name);
+      const exists = existing.some((item) => item.name === name);
       if (exists)
         return err(HaiVecdbError.COLLECTION_ALREADY_EXISTS, vecdbM("vecdb_collectionAlreadyExists", { params: { name } }));
       const metric = options.metric ?? config?.metric ?? "cosine";
@@ -462,7 +590,7 @@ function createChromaProvider() {
     async drop(name) {
       logger.debug("Dropping collection", { name });
       const existing = await client.listCollections();
-      const exists = existing.some((item) => (typeof item === "string" ? item : item.name) === name);
+      const exists = existing.some((item) => item.name === name);
       if (!exists)
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
       await client.deleteCollection({ name });
@@ -472,12 +600,12 @@ function createChromaProvider() {
     async exists(name) {
       logger.debug("Checking collection exists", { name });
       const existing = await client.listCollections();
-      return ok(existing.some((item) => (typeof item === "string" ? item : item.name) === name));
+      return ok(existing.some((item) => item.name === name));
     },
     async info(name) {
       logger.debug("Getting collection info", { name });
       const existing = await client.listCollections();
-      if (!existing.some((item) => (typeof item === "string" ? item : item.name) === name))
+      if (!existing.some((item) => item.name === name))
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
       const collection = await getCollection(name);
       const count = await collection.count();
@@ -491,14 +619,16 @@ function createChromaProvider() {
     async list() {
       logger.debug("Listing collections");
       const existing = await client.listCollections();
-      return ok(existing.map((item) => typeof item === "string" ? item : item.name));
+      return ok(existing.map((item) => item.name));
     }
   };
   function toWriteParams(documents) {
     return {
       ids: documents.map((doc) => doc.id),
       embeddings: documents.map((doc) => doc.vector),
-      documents: documents.map((doc) => doc.content ?? null),
+      documents: documents.map((doc) => doc.content ?? ""),
+      // 统一 API 的 metadata 更宽；SDK 在 add/upsert 中先执行 validateMetadata，再发送请求。
+      // 使用上游 Metadata 类型跨越此边界，避免复制其标量、数组及稀疏向量规则；原生拒绝会由 base 转为 HaiResult。
       metadatas: documents.map((doc) => ({ ...doc.metadata, _content: doc.content ?? "" }))
     };
   }
@@ -577,35 +707,49 @@ function createChromaProvider() {
     async connect(cfg) {
       if (cfg.type !== "chroma")
         return err(HaiVecdbError.UNSUPPORTED_TYPE, vecdbM("vecdb_unsupportedType", { params: { type: cfg.type } }));
+      if (serverProcess || client || closing) {
+        const cleaned = await closeResources();
+        if (!cleaned.success)
+          return cleaned;
+      }
       const chromaConfig = cfg;
       const embedded = !!chromaConfig.path && !chromaConfig.url;
       const loadResult = await loadChromaModule();
       if (!loadResult.success)
         return loadResult;
+      const startupAbort = new AbortController();
+      const startupTimeout = embedded ? chromaConfig.startupTimeout : 5e3;
+      const startupTimer = setTimeout(() => startupAbort.abort(), startupTimeout);
       try {
         if (embedded)
-          startEmbeddedServer(chromaConfig);
-        const clientParams = chromaConfig.url ? { path: chromaConfig.url } : { host: chromaConfig.host, port: chromaConfig.port };
+          await startEmbeddedServer(chromaConfig);
+        const endpoint = chromaConfig.url ? new URL(chromaConfig.url) : void 0;
+        const clientParams = endpoint ? { host: endpoint.hostname, port: Number(endpoint.port || (endpoint.protocol === "https:" ? 443 : 80)), ssl: endpoint.protocol === "https:" } : { host: chromaConfig.host, port: chromaConfig.port, ssl: false };
         if (chromaConfig.apiKey)
-          clientParams.auth = { provider: "token", credentials: chromaConfig.apiKey, tokenHeaderType: "AUTHORIZATION" };
+          clientParams.headers = { Authorization: `Bearer ${chromaConfig.apiKey}` };
+        clientParams.fetchOptions = { signal: startupAbort.signal };
         const chromaClient = new loadResult.data.ChromaClient(clientParams);
-        await waitForHeartbeat(chromaClient, embedded ? chromaConfig.startupTimeout : 5e3);
+        await waitForHeartbeat(chromaClient, startupTimeout);
+        await chromaClient.countCollections();
+        startupAbort.signal.throwIfAborted();
+        if (embedded && (spawnFailed || !serverProcess || serverProcess.exitCode !== null || serverProcess.signalCode !== null))
+          throw new Error("Chroma child exited before readiness was confirmed");
         client = chromaClient;
         config = chromaConfig;
-        logger.info("Chroma connected", { embedded, host: chromaConfig.host, port: chromaConfig.port });
+        logger.info("Chroma connected", { embedded, host: clientParams.host, port: clientParams.port, ssl: clientParams.ssl });
         return ok(void 0);
       } catch (error) {
-        stopEmbeddedServer();
+        startupAbort.abort();
+        const cleanup = await closeResources();
         logger.error("Failed to connect to Chroma", { error: error instanceof Error ? error.message : String(error) });
-        return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: String(error) } }), error);
+        const failure = err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: String(error) } }), error);
+        return !failure.success && !cleanup.success ? err({ ...failure.error, ext: { cleanupPending: true, cleanupError: cleanup.error } }) : failure;
+      } finally {
+        clearTimeout(startupTimer);
       }
     },
     async close() {
-      stopEmbeddedServer();
-      client = null;
-      config = null;
-      logger.info("Chroma connection closed");
-      return ok(void 0);
+      return await closeResources();
     },
     isConnected() {
       return client !== null;
@@ -616,16 +760,29 @@ function createChromaProvider() {
 }
 var require2 = createRequire(import.meta.url);
 var logger2 = core.logger.child({ module: "vecdb", scope: "lancedb" });
-function escapeLanceFilterValue(value) {
-  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "\\%").replace(/_/g, "\\_");
-}
+var COLLECTION_METRIC_KEY = "hai.vecdb.metric";
+var PRIMARY_KEY_FLAG = "lance-schema:unenforced-primary-key";
+var PRIMARY_KEY_POSITION = "lance-schema:unenforced-primary-key:position";
 function escapeLanceSqlValue(value) {
   return value.replace(/'/g, "''");
 }
+function buildMetadataPredicate(filter) {
+  if (typeof filter !== "object" || filter === null || Array.isArray(filter) || ![Object.prototype, null].includes(Object.getPrototypeOf(filter)) || Reflect.ownKeys(filter).some((key) => typeof key !== "string")) {
+    return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_invalidMetadataFilter"));
+  }
+  const predicates = [];
+  for (const [key, value] of Object.entries(filter)) {
+    if (value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value))) {
+      return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_invalidMetadataFilter"));
+    }
+    const extracted = `json_extract(json_get(metadata, '${escapeLanceSqlValue(key)}'), '$')`;
+    predicates.push(typeof value === "number" ? `TRY_CAST(${extracted} AS DOUBLE) = CAST(${value} AS DOUBLE)` : `${extracted} = '${escapeLanceSqlValue(JSON.stringify(value))}'`);
+  }
+  return ok(predicates.join(" AND "));
+}
 function createLancedbProvider() {
   let connection = null;
   let config = null;
-  const collectionMetas = /* @__PURE__ */ new Map();
   function loadLancedb() {
     try {
       const mod = require2("@lancedb/lancedb");
@@ -635,22 +792,30 @@ function createLancedbProvider() {
       return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "@lancedb/lancedb" } }), error);
     }
   }
-  async function openTable(name) {
-    if (!connection)
-      return null;
+  async function withCollection(name, action) {
+    if (!(await connection.tableNames()).includes(name))
+      return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
+    const table = await connection.openTable(name);
     try {
-      const tableNames = await connection.tableNames();
-      if (tableNames.includes(name)) {
-        return await connection.openTable(name);
-      }
-      return null;
-    } catch {
-      return null;
+      const schema = await table.schema();
+      const vectorType = schema.fields.find((field) => field.name === "vector")?.type;
+      const metric = DistanceMetricSchema.safeParse(schema.metadata.get(COLLECTION_METRIC_KEY) ?? null);
+      if (!vectorType || !("listSize" in vectorType) || typeof vectorType.listSize !== "number" || !Number.isInteger(vectorType.listSize) || vectorType.listSize <= 0 || !metric.success) {
+        return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_invalidCollectionSchema", { params: { name } }));
+      }
+      const primaryKeys = schema.fields.filter((field) => field.metadata.has(PRIMARY_KEY_POSITION) || ["true", "1", "yes"].includes(field.metadata.get(PRIMARY_KEY_FLAG)?.toLowerCase() ?? ""));
+      const idField = primaryKeys[0];
+      const atomicWrites = primaryKeys.length === 1 && idField.name === "id" && !idField.nullable && ["true", "1", "yes"].includes(idField.metadata.get(PRIMARY_KEY_FLAG)?.toLowerCase() ?? "") && idField.metadata.get(PRIMARY_KEY_POSITION) === "1" && typeof table.mergeInsert === "function";
+      const driver = loadLancedb();
+      if (!driver.success)
+        return driver;
+      const jsonMetadata = schema.fields.find((field) => field.name === "metadata")?.metadata.get("ARROW:extension:name") === "lance.json";
+      const inputSchema = jsonMetadata ? schema.assign([driver.data.makeJsonField("metadata", false)]) : void 0;
+      return await action(table, { dimension: vectorType.listSize, metric: metric.data, atomicWrites, inputSchema });
+    } finally {
+      table.close();
     }
   }
-  function getCollectionDimension(name) {
-    return collectionMetas.get(name)?.dimension ?? null;
-  }
   function createDimensionMismatchResult(expected, actual) {
     return err(
       HaiVecdbError.DIMENSION_MISMATCH,
@@ -659,18 +824,13 @@ function createLancedbProvider() {
       })
     );
   }
-  function validateVectorDimension(collection, vector) {
-    const expected = getCollectionDimension(collection);
-    if (expected === null || vector.length === expected) {
+  function validateVectorDimension(expected, vector) {
+    if (vector.length === expected) {
       return null;
     }
     return createDimensionMismatchResult(expected, vector.length);
   }
-  function validateDocumentsDimension(collection, documents) {
-    const expected = getCollectionDimension(collection);
-    if (expected === null) {
-      return null;
-    }
+  function validateDocumentsDimension(expected, documents) {
     for (const document of documents) {
       if (document.vector.length !== expected) {
         return createDimensionMismatchResult(expected, document.vector.length);
@@ -678,6 +838,15 @@ function createLancedbProvider() {
     }
     return null;
   }
+  function validateAtomicWrite(meta, documents) {
+    if (!meta.inputSchema)
+      return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_jsonMetadataRequired"));
+    if (!meta.atomicWrites)
+      return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_atomicUpsertUnavailable"));
+    if (new Set(documents.map((document) => document.id)).size !== documents.length)
+      return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_duplicateDocumentIds"));
+    return null;
+  }
   const ctx = { isConnected: () => connection !== null, logger: logger2, operationLog: () => config?.operationLog };
   const collectionDriver = {
     async create(name, options) {
@@ -687,16 +856,22 @@ function createLancedbProvider() {
         return err(HaiVecdbError.COLLECTION_ALREADY_EXISTS, vecdbM("vecdb_collectionAlreadyExists", { params: { name } }));
       }
       const dimension = options.dimension;
-      const metric = options.metric ?? config?.metric ?? "cosine";
-      const initRecord = {
-        id: "__init__",
+      const parsedMetric = DistanceMetricSchema.safeParse(options.metric ?? config?.metric);
+      if (!parsedMetric.success)
+        return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_invalidCollectionSchema", { params: { name } }));
+      const metric = parsedMetric.data;
+      const driver = loadLancedb();
+      if (!driver.success)
+        return driver;
+      const inferred = driver.data.makeArrowTable([{
+        id: "",
         vector: Array.from({ length: dimension }).fill(0),
         content: "",
         metadata: "{}"
-      };
-      const table = await connection.createTable(name, [initRecord]);
-      await table.delete("id = '__init__'");
-      collectionMetas.set(name, { dimension, metric });
+      }], {}, /* @__PURE__ */ new Map([[COLLECTION_METRIC_KEY, metric]])).schema;
+      const schema = inferred.assign(inferred.fields.map((field) => field.name === "id" ? field.clone({ nullable: false, metadata: new Map([...field.metadata, [PRIMARY_KEY_FLAG, "true"], [PRIMARY_KEY_POSITION, "1"]]) }) : field.name === "metadata" ? driver.data.makeJsonField("metadata", false) : field));
+      const table = await connection.createEmptyTable(name, schema);
+      table.close();
       logger2.info("Collection created", { name, dimension, metric });
       return ok(void 0);
     },
@@ -707,7 +882,6 @@ function createLancedbProvider() {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
       }
       await connection.dropTable(name);
-      collectionMetas.delete(name);
       logger2.info("Collection dropped", { name });
       return ok(void 0);
     },
@@ -718,18 +892,7 @@ function createLancedbProvider() {
     },
     async info(name) {
       logger2.debug("Getting collection info", { name });
-      const table = await openTable(name);
-      if (!table) {
-        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
-      }
-      const count = await table.countRows();
-      const meta = collectionMetas.get(name);
-      return ok({
-        name,
-        dimension: meta?.dimension ?? 0,
-        metric: meta?.metric ?? config?.metric ?? "cosine",
-        count
-      });
+      return withCollection(name, async (table, meta) => ok({ name, dimension: meta.dimension, metric: meta.metric, count: await table.countRows() }));
     },
     async list() {
       logger2.debug("Listing collections");
@@ -740,105 +903,100 @@ function createLancedbProvider() {
   const vectorDriver = {
     async insert(collection, documents) {
       logger2.debug("Inserting vectors", { collection, count: documents.length });
-      const table = await openTable(collection);
-      if (!table) {
-        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
-      }
-      const dimensionValidation = validateDocumentsDimension(collection, documents);
-      if (dimensionValidation) {
-        return dimensionValidation;
-      }
-      const records = documents.map((doc) => ({
-        id: doc.id,
-        vector: doc.vector,
-        content: doc.content ?? "",
-        metadata: JSON.stringify(doc.metadata ?? {})
-      }));
-      await table.add(records);
-      logger2.info("Vectors inserted", { collection, count: documents.length });
-      return ok(void 0);
+      return withCollection(collection, async (table, meta) => {
+        const atomicValidation = validateAtomicWrite(meta, documents);
+        if (atomicValidation)
+          return atomicValidation;
+        const dimensionValidation = validateDocumentsDimension(meta.dimension, documents);
+        if (dimensionValidation) {
+          return dimensionValidation;
+        }
+        const records = documents.map((doc) => ({
+          id: doc.id,
+          vector: doc.vector,
+          content: doc.content ?? "",
+          metadata: JSON.stringify(doc.metadata ?? {})
+        }));
+        const driver = loadLancedb();
+        if (!driver.success)
+          return driver;
+        await table.mergeInsert("id").whenNotMatchedInsertAll().execute(driver.data.makeArrowTable(records, { schema: meta.inputSchema }));
+        logger2.info("Vectors inserted", { collection, count: documents.length });
+        return ok(void 0);
+      });
     },
     async upsert(collection, documents) {
       logger2.debug("Upserting vectors", { collection, count: documents.length });
-      const table = await openTable(collection);
-      if (!table) {
-        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
-      }
-      const dimensionValidation = validateDocumentsDimension(collection, documents);
-      if (dimensionValidation) {
-        return dimensionValidation;
-      }
-      const records = documents.map((doc) => ({
-        id: doc.id,
-        vector: doc.vector,
-        content: doc.content ?? "",
-        metadata: JSON.stringify(doc.metadata ?? {})
-      }));
-      if (typeof table.mergeInsert === "function") {
-        await table.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(records);
-      } else {
-        logger2.warn("LanceDB mergeInsert is unavailable, falling back to delete/add upsert");
-        const ids = documents.map((d) => `'${escapeLanceSqlValue(d.id)}'`).join(", ");
-        await table.delete(`id IN (${ids})`);
-        await table.add(records);
-      }
-      logger2.info("Vectors upserted", { collection, count: documents.length });
-      return ok(void 0);
+      return withCollection(collection, async (table, meta) => {
+        const atomicValidation = validateAtomicWrite(meta, documents);
+        if (atomicValidation)
+          return atomicValidation;
+        const dimensionValidation = validateDocumentsDimension(meta.dimension, documents);
+        if (dimensionValidation) {
+          return dimensionValidation;
+        }
+        const records = documents.map((doc) => ({
+          id: doc.id,
+          vector: doc.vector,
+          content: doc.content ?? "",
+          metadata: JSON.stringify(doc.metadata ?? {})
+        }));
+        const driver = loadLancedb();
+        if (!driver.success)
+          return driver;
+        await table.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(driver.data.makeArrowTable(records, { schema: meta.inputSchema }));
+        logger2.info("Vectors upserted", { collection, count: documents.length });
+        return ok(void 0);
+      });
     },
     async delete(collection, ids) {
       logger2.debug("Deleting vectors", { collection, count: ids.length });
-      const table = await openTable(collection);
-      if (!table) {
-        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
-      }
-      const idList = ids.map((id) => `'${escapeLanceSqlValue(id)}'`).join(", ");
-      await table.delete(`id IN (${idList})`);
-      logger2.info("Vectors deleted", { collection, count: ids.length });
-      return ok(void 0);
+      return withCollection(collection, async (table) => {
+        const idList = ids.map((id) => `'${escapeLanceSqlValue(id)}'`).join(", ");
+        await table.delete(`id IN (${idList})`);
+        logger2.info("Vectors deleted", { collection, count: ids.length });
+        return ok(void 0);
+      });
     },
     async search(collection, vector, options) {
       logger2.debug("Searching vectors", { collection, topK: options?.topK, hasFilter: !!options?.filter });
-      const table = await openTable(collection);
-      if (!table) {
-        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
-      }
-      const dimensionValidation = validateVectorDimension(collection, vector);
-      if (dimensionValidation) {
-        return dimensionValidation;
-      }
-      const topK = options?.topK ?? 10;
-      const minScore = options?.minScore ?? 0;
-      let query = table.search(vector).limit(topK);
-      if (options?.filter) {
-        const filterParts = [];
-        for (const [key, value] of Object.entries(options.filter)) {
-          filterParts.push(`metadata LIKE '%"${escapeLanceFilterValue(key)}":"${escapeLanceFilterValue(String(value))}"%'`);
+      return withCollection(collection, async (table, meta) => {
+        const dimensionValidation = validateVectorDimension(meta.dimension, vector);
+        if (dimensionValidation) {
+          return dimensionValidation;
         }
-        if (filterParts.length > 0) {
-          query = query.where(filterParts.join(" AND "));
+        const topK = options?.topK ?? 10;
+        const minScore = options?.minScore ?? 0;
+        let query = table.vectorSearch(vector).distanceType(meta.metric === "euclidean" ? "l2" : meta.metric).limit(topK);
+        if (options?.filter !== void 0) {
+          if (!meta.inputSchema)
+            return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_jsonMetadataRequired"));
+          const predicate = buildMetadataPredicate(options.filter);
+          if (!predicate.success)
+            return predicate;
+          if (predicate.data)
+            query = query.where(predicate.data);
         }
-      }
-      const results = await query.toArray();
-      const searchResults = results.map((row) => {
-        const distance = row._distance ?? 0;
-        const score = 1 / (1 + distance);
-        return {
-          id: row.id,
-          score,
-          content: row.content || void 0,
-          metadata: row.metadata ? JSON.parse(row.metadata) : void 0
-        };
-      }).filter((r) => r.score >= minScore);
-      return ok(searchResults);
+        const results = await query.toArray();
+        const searchResults = results.map((row) => {
+          const distance = row._distance ?? 0;
+          const score = meta.metric === "cosine" ? Math.max(0, Math.min(1, 1 - distance / 2)) : meta.metric === "dot" ? 1 / (1 + Math.exp(distance - 1)) : 1 / (1 + Math.max(0, distance));
+          return {
+            id: row.id,
+            score,
+            content: row.content || void 0,
+            metadata: row.metadata ? JSON.parse(row.metadata) : void 0
+          };
+        }).filter((r) => r.score >= minScore);
+        return ok(searchResults);
+      });
     },
     async count(collection) {
       logger2.debug("Counting vectors", { collection });
-      const table = await openTable(collection);
-      if (!table) {
-        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
-      }
-      const count = await table.countRows();
-      return ok(count);
+      return withCollection(collection, async (table) => {
+        const count = await table.countRows();
+        return ok(count);
+      });
     }
   };
   return {
@@ -853,36 +1011,22 @@ function createLancedbProvider() {
         return loadResult;
       const lancedb = loadResult.data;
       try {
-        connection = await lancedb.connect(lanceConfig.path);
+        connection = await lancedb.connect(lanceConfig.path, { readConsistencyInterval: 0 });
         config = lanceConfig;
-        const tableNames = await connection.tableNames();
-        await Promise.allSettled(tableNames.map(async (name) => {
-          try {
-            const table = await connection.openTable(name);
-            const count = await table.countRows();
-            if (count === 0)
-              return;
-            const rows = await table.search(Array.from({ length: 1 }).fill(0)).limit(1).toArray();
-            if (rows.length > 0 && rows[0].vector) {
-              collectionMetas.set(name, {
-                dimension: rows[0].vector.length,
-                metric: lanceConfig.metric ?? "cosine"
-              });
-            }
-          } catch {
-          }
-        }));
         logger2.info("LanceDB connected", { path: lanceConfig.path });
         return ok(void 0);
       } catch (error) {
+        connection?.close();
+        connection = null;
+        config = null;
         logger2.error("Failed to connect to LanceDB", { error });
         return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: String(error) } }), error);
       }
     },
     async close() {
+      connection?.close();
       connection = null;
       config = null;
-      collectionMetas.clear();
       logger2.info("LanceDB connection closed");
       return ok(void 0);
     },
@@ -1257,18 +1401,6 @@ function createPgvectorProvider() {
     vector: createBaseVectorOps(ctx, vectorDriver)
   };
 }
-function sanitizeUrl(url) {
-  try {
-    const parsed = new URL(url);
-    if (parsed.username)
-      parsed.username = "***";
-    if (parsed.password)
-      parsed.password = "***";
-    return parsed.toString();
-  } catch {
-    return "(invalid url)";
-  }
-}
 var logger4 = core.logger.child({ module: "vecdb", scope: "qdrant" });
 function isQdrantModule(value) {
   if (typeof value !== "object" || value === null) {
@@ -1289,8 +1421,6 @@ function toQdrantDistance(metric) {
       return "Euclid";
     case "dot":
       return "Dot";
-    default:
-      return "Cosine";
   }
 }
 function createQdrantProvider() {
@@ -1318,12 +1448,7 @@ function createQdrantProvider() {
     }
   }
   function isQdrantNotFoundError(error) {
-    const getCollectionErrorCtor = client?.getCollection.Error;
-    if (getCollectionErrorCtor && error instanceof getCollectionErrorCtor) {
-      return error.getActualType?.().status === 404;
-    }
-    const maybeError = error;
-    return maybeError.status === 404 || maybeError.response?.status === 404 || maybeError.$metadata?.httpStatusCode === 404;
+    return typeof error === "object" && error !== null && "status" in error && error.status === 404;
   }
   async function getCollectionInfo(name) {
     try {
@@ -1335,12 +1460,22 @@ function createQdrantProvider() {
       throw error;
     }
   }
+  function readVectorDefinition(info) {
+    const vectors = info.config.params.vectors;
+    if (!vectors || !("size" in vectors) || typeof vectors.size !== "number" || !Number.isSafeInteger(vectors.size) || vectors.size <= 0)
+      return void 0;
+    if (!("distance" in vectors))
+      return void 0;
+    const metric = vectors.distance === "Cosine" ? "cosine" : vectors.distance === "Euclid" ? "euclidean" : vectors.distance === "Dot" ? "dot" : void 0;
+    return metric ? { dimension: vectors.size, metric } : void 0;
+  }
   async function getCollectionDimension(name) {
     const infoResult = await getCollectionInfo(name);
     if (!infoResult.success) {
       return infoResult;
     }
-    return ok(infoResult.data.config?.params?.vectors?.size ?? 0);
+    const definition = readVectorDefinition(infoResult.data);
+    return definition ? ok(definition.dimension) : err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_invalidCollectionSchema", { params: { name } }));
   }
   function validateVectorDimension(expected, actual) {
     if (expected === actual) {
@@ -1401,14 +1536,12 @@ function createQdrantProvider() {
         return infoResult;
       }
       const collectionInfo = infoResult.data;
-      const vectorsConfig = collectionInfo.config?.params?.vectors;
-      const dimension = vectorsConfig?.size ?? 0;
-      const qdrantDistance = vectorsConfig?.distance ?? "Cosine";
-      const metric = qdrantDistance === "Euclid" ? "euclidean" : qdrantDistance === "Dot" ? "dot" : "cosine";
+      const definition = readVectorDefinition(collectionInfo);
+      if (!definition)
+        return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_invalidCollectionSchema", { params: { name } }));
       return ok({
         name,
-        dimension,
-        metric,
+        ...definition,
         count: collectionInfo.points_count ?? 0
       });
     },
@@ -1441,7 +1574,7 @@ function createQdrantProvider() {
           _content: doc.content ?? ""
         }
       }));
-      await client.upsert(collection, { points });
+      await client.upsert(collection, { points, wait: true });
       logger4.info("Vectors inserted", { collection, count: documents.length });
       return ok(void 0);
     },
@@ -1466,14 +1599,14 @@ function createQdrantProvider() {
           _content: doc.content ?? ""
         }
       }));
-      await client.upsert(collection, { points });
+      await client.upsert(collection, { points, wait: true });
       logger4.info("Vectors upserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async delete(collection, ids) {
       logger4.debug("Deleting vectors", { collection, count: ids.length });
       const uuids = ids.map(hashToUuid);
-      await client.delete(collection, { points: uuids });
+      await client.delete(collection, { points: uuids, wait: true });
       logger4.info("Vectors deleted", { collection, count: ids.length });
       return ok(void 0);
     },
@@ -1508,9 +1641,9 @@ function createQdrantProvider() {
         const payload = point.payload ?? {};
         const { _id, _content, ...metadata } = payload;
         return {
-          id: _id ?? "",
+          id: typeof _id === "string" ? _id : "",
           score: point.score,
-          content: _content || void 0,
+          content: typeof _content === "string" && _content.length > 0 ? _content : void 0,
           metadata: Object.keys(metadata).length > 0 ? metadata : void 0
         };
       });
@@ -1518,11 +1651,8 @@ function createQdrantProvider() {
     },
     async count(collection) {
       logger4.debug("Counting vectors", { collection });
-      const infoResult = await getCollectionInfo(collection);
-      if (!infoResult.success) {
-        return infoResult;
-      }
-      return ok(infoResult.data.points_count ?? 0);
+      const count = await client.count(collection, { exact: true });
+      return ok(count.count);
     }
   };
   return {
@@ -1545,7 +1675,7 @@ function createQdrantProvider() {
         await qdrantClient.getCollections();
         client = qdrantClient;
         config = qdrantConfig;
-        logger4.info("Qdrant connected", { url: sanitizeUrl(qdrantConfig.url) });
+        logger4.info("Qdrant connected", { url: core.sanitize.sanitizeUrl(qdrantConfig.url) });
         return ok(void 0);
       } catch (error) {
         logger4.error("Failed to connect to Qdrant", { error: error instanceof Error ? error.message : String(error) });
@@ -1571,6 +1701,38 @@ var logger5 = core.logger.child({ module: "vecdb", scope: "main" });
 var currentProvider = null;
 var currentConfig = null;
 var initInProgress = false;
+var pendingProvider = null;
+var initCompletion = null;
+var closingPromise = null;
+async function closeOwnedProvider() {
+  if (currentProvider) {
+    pendingProvider = currentProvider;
+    currentProvider = null;
+  }
+  currentConfig = null;
+  if (!pendingProvider)
+    return ok(void 0);
+  try {
+    const result = await pendingProvider.close();
+    if (!result.success)
+      return err({ ...result.error, ext: { ...result.error.ext, cleanupPending: true } });
+    pendingProvider = null;
+    return result;
+  } catch (cause) {
+    return err({ ...HaiVecdbError.CONNECTION_FAILED, message: vecdbM("vecdb_closeFailed", { params: { error: cause instanceof Error ? cause.message : String(cause) } }), cause, ext: { cleanupPending: true } });
+  }
+}
+async function failInitialization(result) {
+  const cleanup = await closeOwnedProvider();
+  if (result.success)
+    return result;
+  if (!cleanup.success)
+    return err({ ...result.error, ext: { ...result.error.ext, cleanupPending: true, cleanupError: cleanup.error } });
+  const ext = { ...result.error.ext };
+  delete ext.cleanupPending;
+  delete ext.cleanupError;
+  return err({ ...result.error, ext: Object.keys(ext).length ? ext : void 0 });
+}
 function createProvider(config) {
   switch (config.type) {
     case "lancedb":
@@ -1589,6 +1751,20 @@ var notInitialized = core.module.createNotInitializedKit(
 );
 var notInitializedCollection = notInitialized.proxy();
 var notInitializedVector = notInitialized.proxy();
+var collectionOps = {
+  create: (name, options) => currentProvider && !closingPromise ? currentProvider.collection.create(name, options) : notInitializedCollection.create(name, options),
+  drop: (name) => currentProvider && !closingPromise ? currentProvider.collection.drop(name) : notInitializedCollection.drop(name),
+  exists: (name) => currentProvider && !closingPromise ? currentProvider.collection.exists(name) : notInitializedCollection.exists(name),
+  info: (name) => currentProvider && !closingPromise ? currentProvider.collection.info(name) : notInitializedCollection.info(name),
+  list: () => currentProvider && !closingPromise ? currentProvider.collection.list() : notInitializedCollection.list()
+};
+var vectorOps = {
+  insert: (collection, documents) => currentProvider && !closingPromise ? currentProvider.vector.insert(collection, documents) : notInitializedVector.insert(collection, documents),
+  upsert: (collection, documents) => currentProvider && !closingPromise ? currentProvider.vector.upsert(collection, documents) : notInitializedVector.upsert(collection, documents),
+  delete: (collection, ids) => currentProvider && !closingPromise ? currentProvider.vector.delete(collection, ids) : notInitializedVector.delete(collection, ids),
+  search: (collection, vector, options) => currentProvider && !closingPromise ? currentProvider.vector.search(collection, vector, options) : notInitializedVector.search(collection, vector, options),
+  count: (collection) => currentProvider && !closingPromise ? currentProvider.vector.count(collection) : notInitializedVector.count(collection)
+};
 var vecdb = {
   /**
    * 初始化向量数据库连接
@@ -1597,19 +1773,19 @@ var vecdb = {
    * @returns 初始化结果，失败时包含错误信息
    */
   async init(config) {
-    if (initInProgress) {
+    if (initInProgress || closingPromise) {
       logger5.warn("Vecdb init already in progress, skipping concurrent call");
       return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_initInProgress"));
     }
     initInProgress = true;
+    let resolveInit;
+    initCompletion = new Promise((resolve) => {
+      resolveInit = resolve;
+    });
     try {
-      if (currentProvider) {
-        logger5.warn("Vecdb module is already initialized, reinitializing");
-        const closeResult = await vecdb.close();
-        if (!closeResult.success) {
-          return closeResult;
-        }
-      }
+      const cleanup = await closeOwnedProvider();
+      if (!cleanup.success)
+        return cleanup;
       logger5.info("Initializing vecdb module");
       const parseResult = VecdbConfigSchema.safeParse(config);
       if (!parseResult.success) {
@@ -1617,26 +1793,32 @@ var vecdb = {
         return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_configError", { params: { error: parseResult.error.message } }), parseResult.error);
       }
       const parsed = parseResult.data;
+      if (core.module.requiresSharedState(process.env) && (parsed.type === "lancedb" || parsed.type === "chroma" && !!parsed.path && !parsed.url))
+        return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_sharedBackendRequired"));
       try {
         const provider = createProvider(parsed);
+        pendingProvider = provider;
         const connectResult = await provider.connect(parsed);
         if (!connectResult.success) {
           logger5.error("Vecdb module initialization failed", {
             code: connectResult.error.code,
             message: connectResult.error.message
           });
-          return connectResult;
+          return await failInitialization(connectResult);
         }
+        pendingProvider = null;
         currentProvider = provider;
         currentConfig = parsed;
         logger5.info("Vecdb module initialized", { type: parsed.type });
         return ok(void 0);
       } catch (error) {
         logger5.error("Vecdb module initialization failed", { error });
-        return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_initFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
+        return await failInitialization(err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_initFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error));
       }
     } finally {
       initInProgress = false;
+      initCompletion = null;
+      resolveInit();
     }
   },
   /**
@@ -1645,7 +1827,7 @@ var vecdb = {
    * 未初始化时返回占位对象（所有调用返回 NOT_INITIALIZED）。
    */
   get collection() {
-    return currentProvider?.collection ?? notInitializedCollection;
+    return collectionOps;
   },
   /**
    * 获取向量操作接口
@@ -1653,15 +1835,15 @@ var vecdb = {
    * 未初始化时返回占位对象（所有调用返回 NOT_INITIALIZED）。
    */
   get vector() {
-    return currentProvider?.vector ?? notInitializedVector;
+    return vectorOps;
   },
   /** 获取当前脱敏配置快照（未初始化时为 null） */
   get config() {
-    return currentConfig ? core.sanitize.sanitizeSensitiveFields(currentConfig) : null;
+    return currentConfig && !closingPromise ? core.sanitize.sanitizeSensitiveFields(currentConfig) : null;
   },
   /** 获取底层后端的原始连接信息（含凭证，未初始化时为 null；仅供同进程内集成使用） */
   get rawConnection() {
-    if (!currentConfig)
+    if (!currentConfig || closingPromise)
       return null;
     if (currentConfig.type === "qdrant")
       return { type: "qdrant", url: currentConfig.url, apiKey: currentConfig.apiKey };
@@ -1690,7 +1872,7 @@ var vecdb = {
   },
   /** 检查是否已初始化 */
   get isInitialized() {
-    return currentProvider !== null && currentProvider.isConnected();
+    return currentProvider !== null && !closingPromise && currentProvider.isConnected();
   },
   /**
    * 关闭向量数据库连接
@@ -1698,27 +1880,16 @@ var vecdb = {
    * 多次调用安全，未初始化时直接返回。
    */
   async close() {
-    if (!currentProvider) {
-      currentConfig = null;
-      logger5.info("Vecdb module already closed, skipping");
-      return ok(void 0);
-    }
-    logger5.info("Closing vecdb module");
-    try {
-      const closeResult = await currentProvider.close();
-      if (!closeResult.success) {
-        logger5.error("Vecdb module close failed", { code: closeResult.error.code, message: closeResult.error.message });
-        return closeResult;
-      }
-      logger5.info("Vecdb module closed");
-      return ok(void 0);
-    } catch (error) {
-      logger5.error("Vecdb module close failed", { error });
-      return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_closeFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
-    } finally {
-      currentProvider = null;
-      currentConfig = null;
+    if (!closingPromise) {
+      closingPromise = (async () => {
+        if (initCompletion)
+          await initCompletion;
+        return closeOwnedProvider();
+      })().finally(() => {
+        closingPromise = null;
+      });
     }
+    return await closingPromise;
   }
 };