taladb 0.11.2 → 0.11.4

package/dist/index.browser.mjs

@@ -1,3 +1,89 @@
+// src/vector-client.ts
+function integer(value, name, min = 0, max = 4294967295) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${name} must be an integer between ${min} and ${max}`);
+}
+function vectorValues(vector) {
+  const values = Array.from(vector);
+  if (values.length === 0 || values.some((v) => !Number.isFinite(v))) throw new Error("vector must contain finite numbers");
+  return values;
+}
+function queryOptions(options) {
+  if (options.efSearch !== void 0) integer(options.efSearch, "efSearch", 1);
+  if (options.offset !== void 0) integer(options.offset, "offset");
+  if (options.groupSize !== void 0) integer(options.groupSize, "groupSize", 1);
+  if (options.oversampling !== void 0) integer(options.oversampling, "oversampling", 1, 100);
+  if (options.scoreThreshold !== void 0 && !Number.isFinite(options.scoreThreshold)) throw new Error("scoreThreshold must be finite");
+  return options;
+}
+function abortError() {
+  const error = new Error("Vector index rebuild cancelled");
+  error.name = "AbortError";
+  return error;
+}
+function createVectorClient(send) {
+  const client = {
+    searchVectors: async (field, vector, topK, filter, options = {}) => {
+      integer(topK, "topK");
+      return send({ op: "search", field, query: vectorValues(vector), topK, filter, options: queryOptions(options) });
+    },
+    findWithin: (field, vector, scoreThreshold, filter) => client.searchVectors(field, vector, 4294967295, filter, { mode: "exact", scoreThreshold }),
+    vectorIndexStatus: (field) => send({ op: "status", field }),
+    beginVectorBuild: (field, options) => send({ op: "beginBuild", field, options }),
+    stepVectorBuild: async (field, id, batchSize = 32) => {
+      integer(batchSize, "batchSize", 1, 1024);
+      return send({ op: "stepBuild", field, id, batchSize });
+    },
+    cancelVectorBuild: (field, id) => send({ op: "cancelBuild", field, id }),
+    rebuildVectorIndex: async (field, options = {}) => {
+      const { signal, onProgress, batchSize = 32, ...graphOptions } = options;
+      integer(batchSize, "batchSize", 1, 1024);
+      if (signal?.aborted) throw abortError();
+      let progress = await client.beginVectorBuild(field, Object.keys(graphOptions).length ? graphOptions : void 0);
+      try {
+        onProgress?.(progress);
+        while (progress.state === "building") {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          if (signal?.aborted) throw abortError();
+          progress = await client.stepVectorBuild(field, progress.id, batchSize);
+          onProgress?.(progress);
+        }
+        if (progress.state === "failed") throw new Error(progress.error ?? "Vector rebuild failed");
+        if (progress.state === "cancelled") throw abortError();
+        return progress;
+      } catch (error) {
+        if (progress.state === "building") await client.cancelVectorBuild(field, progress.id);
+        throw error;
+      }
+    },
+    measureVectorRecall: async (field, queries, topK, filter, options = {}) => {
+      integer(topK, "topK", 1);
+      return send({ op: "recall", field, queries: queries.map(vectorValues), topK, filter, options: queryOptions(options) });
+    }
+  };
+  return client;
+}
+function vectorIndexRequest(field, options) {
+  integer(options.dimensions, "dimensions", 1);
+  if (options.metric && !["cosine", "dot", "euclidean"].includes(options.metric)) throw new Error("invalid vector metric");
+  if (options.indexType && !["flat", "hnsw"].includes(options.indexType)) throw new Error("invalid vector indexType");
+  if (options.quantization && options.quantization !== "none" && options.indexType !== "hnsw") throw new Error("quantization requires an HNSW index");
+  if (options.indexType === "hnsw") {
+    const m = options.hnswM ?? 32;
+    const efConstruction = options.hnswEfConstruction ?? 200;
+    integer(m, "hnswM", 2, 128);
+    integer(efConstruction, "hnswEfConstruction", m, 1e5);
+    if (options.metric === "dot") throw new Error("HNSW requires cosine or euclidean");
+    if (options.quantization === "binary" && options.metric && options.metric !== "cosine") throw new Error("binary quantization requires cosine");
+  }
+  return {
+    op: "create",
+    field,
+    dimensions: options.dimensions,
+    metric: options.metric,
+    options: options.indexType === "hnsw" ? { m: options.hnswM ?? 32, efConstruction: options.hnswEfConstruction ?? 200, quantization: options.quantization ?? "none" } : null
+  };
+}
+
 // src/config.browser.ts
 var ENDPOINT_FIELDS = [
   "endpoint",
@@ -710,7 +796,9 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   }
   function wrapCollection(name, opts) {
     const s = JSON.stringify;
+    const vectorCommand = async (request) => JSON.parse(await proxy.send("vectorCommand", { collection: name, requestJson: JSON.stringify(request) }));
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -762,25 +850,21 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       dropCompoundIndex: (fields) => proxy.send("dropCompoundIndex", { collection: name, fieldsJson: JSON.stringify(fields) }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
       dropFtsIndex: (field) => proxy.send("dropFtsIndex", { collection: name, field }),
-      createVectorIndex: (field, options) => {
-        if (options.indexType === "hnsw") return Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native."));
-        return proxy.send("createVectorIndex", {
-          collection: name,
-          field,
-          dimensions: options.dimensions,
-          metric: options.metric,
-          indexType: null,
-          hnswM: null,
-          hnswEfConstruction: null
-        });
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
-      upgradeVectorIndex: (_field) => Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native.")),
+      upgradeVectorIndex: async (field) => {
+        await createVectorClient(vectorCommand).rebuildVectorIndex(field);
+      },
       listIndexes: async () => {
         const json = await proxy.send("listIndexes", { collection: name });
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const json = await proxy.send("findNearest", {
           collection: name,
           field,
@@ -838,7 +922,7 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   function nudgedPoller(collection, fetchJson, callback, onError) {
     let active = true;
     let lastJson = "";
-    let lastGeneration = -1;
+    let lastGeneration = null;
     let generationSupported = true;
     let timer = null;
     let running = false;
@@ -903,6 +987,7 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       await proxy.send("flush");
     },
     isPrimary: () => proxy.send("isPrimary"),
+    storageInfo: () => proxy.send("capabilities"),
     close: async () => {
       channel?.close();
       try {
@@ -915,14 +1000,16 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
     listCollectionNames: async () => JSON.parse(await proxy.send("listCollections"))
   };
   if (migrations?.length) {
-    await runMigrations(
-      handle,
-      async () => proxy.send("userVersion"),
-      async (v) => {
-        await proxy.send("setUserVersion", { version: v });
-      },
-      migrations
-    );
+    await navigator.locks.request(`taladb:migrations:${dbName}`, async () => {
+      await runMigrations(
+        handle,
+        async () => proxy.send("userVersion"),
+        async (v) => {
+          await proxy.send("setUserVersion", { version: v });
+        },
+        migrations
+      );
+    });
   }
   return handle;
 }
@@ -938,7 +1025,9 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
   const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
   function wrapCollection(name, opts) {
     const col = db.collection(name);
+    const vectorCommand = async (request) => col.vectorCommandAsync ? col.vectorCommandAsync(request) : col.vectorCommand(request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => col.insertAsync ? col.insertAsync(doc) : col.insert(doc),
       insertMany: async (docs) => col.insertManyAsync ? col.insertManyAsync(docs) : col.insertMany(docs),
       find: async (filter) => col.findAsync ? col.findAsync(filter ?? null) : col.find(filter ?? null),
@@ -955,14 +1044,19 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
       dropCompoundIndex: async (fields) => col.dropCompoundIndex(fields),
       createFtsIndex: async (field) => col.createFtsIndex(field),
       dropFtsIndex: async (field) => col.dropFtsIndex(field),
-      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null, options.indexType ?? null, options.hnswM ?? null, options.hnswEfConstruction ?? null),
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
+      },
       dropVectorIndex: async (field) => col.dropVectorIndex(field),
       upgradeVectorIndex: async (field) => col.upgradeVectorIndex(field),
       listIndexes: async () => {
         const json = col.listIndexes();
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1010,78 +1104,109 @@ async function createNativeDB(_dbName, webhook, migrations) {
     );
   }
   const native = maybeNative;
+  let nativeQueue = Promise.resolve();
+  let queued = 0;
+  let closed = false;
+  const call = (op, ...args) => {
+    if (queued >= 128) return Promise.reject(new Error("TalaDB native request queue is full"));
+    queued++;
+    const result = nativeQueue.then(async () => {
+      if (closed) throw new Error("TalaDB database is closed");
+      if (op === "close") {
+        closed = true;
+        native.close();
+        return;
+      }
+      if (op === "findNearest" && native.findNearestAsync) {
+        return native.findNearestAsync(...args);
+      }
+      if (native.callAsync) return native.callAsync(op, args);
+      if (op === "find" && native.findAsync) {
+        return native.findAsync(...args);
+      }
+      const method = native[op];
+      if (!method) throw new Error(`${op} requires a newer @taladb/react-native binary; rebuild the native module`);
+      return method(...args);
+    });
+    nativeQueue = result.catch(() => {
+    }).finally(() => {
+      queued--;
+    });
+    return result;
+  };
   function wrapCollection(name, opts) {
+    const vectorCommand = async (request) => call("vectorCommand", name, request);
     const wrapped = {
-      insert: async (doc) => native.insert(name, doc),
-      insertMany: async (docs) => native.insertMany(name, docs),
-      find: async (filter) => native.find(name, filter ?? {}),
-      findOne: async (filter) => native.findOne(name, filter ?? {}),
-      updateOne: async (filter, update) => native.updateOne(name, filter, update),
-      updateMany: async (filter, update) => native.updateMany(name, filter, update),
-      deleteOne: async (filter) => native.deleteOne(name, filter),
-      deleteMany: async (filter) => native.deleteMany(name, filter),
-      count: async (filter) => native.count(name, filter ?? {}),
-      aggregate: async (pipeline) => native.aggregate(name, pipeline),
-      createIndex: async (field) => native.createIndex(name, field),
-      dropIndex: async (field) => native.dropIndex(name, field),
-      createCompoundIndex: async (fields) => native.createCompoundIndex(name, fields),
-      dropCompoundIndex: async (fields) => native.dropCompoundIndex(name, fields),
-      createFtsIndex: async (field) => native.createFtsIndex(name, field),
-      dropFtsIndex: async (field) => native.dropFtsIndex(name, field),
+      ...createVectorClient(vectorCommand),
+      insert: async (doc) => await call("insert", name, doc),
+      insertMany: async (docs) => await call("insertMany", name, docs),
+      find: async (filter) => await call("find", name, filter ?? {}),
+      findOne: async (filter) => await call("findOne", name, filter ?? {}),
+      updateOne: async (filter, update) => await call("updateOne", name, filter, update),
+      updateMany: async (filter, update) => await call("updateMany", name, filter, update),
+      deleteOne: async (filter) => await call("deleteOne", name, filter),
+      deleteMany: async (filter) => await call("deleteMany", name, filter),
+      count: async (filter) => await call("count", name, filter ?? {}),
+      aggregate: async (pipeline) => await call("aggregate", name, pipeline),
+      createIndex: async (field) => await call("createIndex", name, field),
+      dropIndex: async (field) => await call("dropIndex", name, field),
+      createCompoundIndex: async (fields) => await call("createCompoundIndex", name, fields),
+      dropCompoundIndex: async (fields) => await call("dropCompoundIndex", name, fields),
+      createFtsIndex: async (field) => await call("createFtsIndex", name, field),
+      dropFtsIndex: async (field) => await call("dropFtsIndex", name, field),
       createVectorIndex: async (field, options) => {
-        const opts2 = {};
-        if (options.metric) opts2.metric = options.metric;
-        if (options.hnswM || options.hnswEfConstruction) {
-          opts2.hnsw = { m: options.hnswM, efConstruction: options.hnswEfConstruction };
-        }
-        return native.createVectorIndex(name, field, options.dimensions, opts2);
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
-      dropVectorIndex: async (field) => native.dropVectorIndex(name, field),
-      upgradeVectorIndex: async (field) => native.upgradeVectorIndex(name, field),
-      // The JSI HostObject does not expose index introspection yet; return a
-      // correctly-shaped empty result rather than `{}` cast to the interface.
-      listIndexes: async () => ({ btree: [], fts: [], vector: [] }),
-      findNearest: async (field, vector, topK, filter) => {
-        const raw = native.findNearest(name, field, vector, topK, filter ?? null);
+      dropVectorIndex: async (field) => await call("dropVectorIndex", name, field),
+      upgradeVectorIndex: async (field) => await call("upgradeVectorIndex", name, field),
+      listIndexes: async () => call("listIndexes", name),
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
+        const raw = await call("findNearest", name, field, vector, topK, filter ?? null);
         return raw;
       },
       searchText: async (field, query, topK, filter, options) => {
-        if (!native.searchText) {
+        if (!native.callAsync && !native.searchText) {
           throw new Error("searchText requires @taladb/react-native \u2265 0.10 \u2014 rebuild the native module");
         }
-        return native.searchText(name, field, query, topK, filter ?? null, options ?? null);
+        return await call("searchText", name, field, query, topK, filter ?? null, options ?? null);
       },
       hybridSearch: async (text, vector, topK, filter, options) => {
-        if (!native.hybridSearch) {
+        if (!native.callAsync && !native.hybridSearch) {
           throw new Error("hybridSearch requires @taladb/react-native \u2265 0.10 \u2014 rebuild the native module");
         }
-        return native.hybridSearch(name, text.textField, text.text, vector.vectorField, vector.vector, topK, filter ?? null, options ?? null);
+        return await call("hybridSearch", name, text.textField, text.text, vector.vectorField, vector.vector, topK, filter ?? null, options ?? null);
       },
-      subscribe: (filter, callback, onError) => makePoller(async () => native.find(name, filter ?? {}), callback, onError),
-      subscribeAggregate: (pipeline, callback, onError) => makePoller(async () => native.aggregate(name, pipeline), callback, onError)
+      subscribe: (filter, callback, onError) => makePoller(async () => await call("find", name, filter ?? {}), callback, onError),
+      subscribeAggregate: (pipeline, callback, onError) => makePoller(async () => await call("aggregate", name, pipeline), callback, onError)
     };
     return decorateCollection(wrapped, name, opts, webhook);
   }
   const handle = {
     collection: (name, opts) => wrapCollection(name, opts),
-    compact: async () => native.compact(),
-    close: async () => native.close(),
-    flush: native.flush ? async () => {
-      native.flush();
+    compact: async () => await call("compact"),
+    close: async () => await call("close"),
+    flush: native.callAsync || native.flush ? async () => {
+      await call("flush");
+    } : void 0,
+    rebuildVectorIndexes: native.callAsync || native.rebuildVectorIndexes ? async () => {
+      await call("rebuildVectorIndexes");
     } : void 0,
     // One process owns the file — there is no other tab to defer to.
     isPrimary: async () => true
   };
   if (migrations?.length) {
-    if (typeof native.userVersion !== "function" || typeof native.setUserVersion !== "function") {
+    if (!native.callAsync && (typeof native.userVersion !== "function" || typeof native.setUserVersion !== "function")) {
       throw new Error(
         "openDB({ migrations }) is not available on this @taladb/react-native binary yet (the JSI HostObject does not expose userVersion/setUserVersion). Update the native module."
       );
     }
     await runMigrations(
       handle,
-      async () => native.userVersion(),
-      async (v) => native.setUserVersion(v),
+      async () => call("userVersion"),
+      async (v) => call("setUserVersion", v),
       migrations
     );
   }
@@ -1156,6 +1281,7 @@ function attachWebhook(db, webhook) {
 export {
   TalaDbValidationError,
   applySchema,
+  createVectorClient,
   createWebhookDispatcher,
   decorateCollection,
   deriveDocId,

package/dist/index.d.mts

@@ -1,3 +1,81 @@
+/** Shared vector API for Node, browser workers, and the React Native job executor. */
+type VectorQuantization = 'none' | 'scalar' | 'binary';
+interface VectorGraphOptions {
+    m?: number;
+    efConstruction?: number;
+    quantization?: VectorQuantization;
+}
+interface VectorQueryOptions {
+    mode?: 'auto' | 'exact' | 'ann';
+    efSearch?: number;
+    scoreThreshold?: number;
+    offset?: number;
+    groupBy?: string;
+    groupSize?: number;
+    oversampling?: number;
+}
+interface VectorBuildProgress {
+    id: string;
+    state: 'building' | 'ready' | 'cancelled' | 'failed';
+    processed: number;
+    total: number;
+    revision: number;
+    error: string | null;
+}
+interface VectorRebuildOptions extends VectorGraphOptions {
+    /** Insertions per native/worker call (1–1024); defaults to 32 for mobile responsiveness. */
+    batchSize?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: VectorBuildProgress) => void;
+}
+interface VectorIndexStatus {
+    field: string;
+    state: 'flat' | 'ready' | 'stale' | 'rebuildRequired';
+    persistent: boolean;
+    indexedVectors: number;
+    totalVectors: number;
+    deletedNodes: number;
+    revision: number;
+    indexRevision: number | null;
+    options: Required<VectorGraphOptions> | null;
+    build: VectorBuildProgress | null;
+}
+interface VectorQueryResult<T> {
+    hits: {
+        document: T;
+        score: number;
+    }[];
+    execution: {
+        path: 'exact' | 'hnsw';
+        reason: string;
+        revision: number;
+        efSearch: number | null;
+        distanceComputations: number;
+    };
+    /** Offset pagination uses live snapshots. Writes between pages can change ordering. */
+    nextOffset: number | null;
+}
+interface VectorRecall {
+    recallAtK: number;
+    queries: number;
+    topK: number;
+    exactMs: number;
+    annMs: number;
+}
+interface VectorClient<T> {
+    searchVectors(field: string, vector: ArrayLike<number>, topK: number, filter?: Record<string, unknown>, options?: VectorQueryOptions): Promise<VectorQueryResult<T>>;
+    /** Exact range search. Returns every matching document above the score threshold. */
+    findWithin(field: string, vector: ArrayLike<number>, scoreThreshold: number, filter?: Record<string, unknown>): Promise<VectorQueryResult<T>>;
+    vectorIndexStatus(field: string): Promise<VectorIndexStatus>;
+    rebuildVectorIndex(field: string, options?: VectorRebuildOptions): Promise<VectorBuildProgress>;
+    beginVectorBuild(field: string, options?: VectorGraphOptions): Promise<VectorBuildProgress>;
+    stepVectorBuild(field: string, id: string, batchSize?: number): Promise<VectorBuildProgress>;
+    cancelVectorBuild(field: string, id: string): Promise<VectorBuildProgress>;
+    measureVectorRecall(field: string, queries: ArrayLike<number>[], topK: number, filter?: Record<string, unknown>, options?: VectorQueryOptions): Promise<VectorRecall>;
+}
+/** Binding adapter used by TalaDB's Node, browser, and React Native packages. */
+declare function createVectorClient<T>(send: (request: Record<string, unknown>) => Promise<any>): VectorClient<T>;
+
 /** The three mutation kinds a webhook reports, and the verb each one uses. */
 type WebhookOp = 'insert' | 'update' | 'delete';
 interface WebhookConfig {
@@ -105,13 +183,15 @@ interface VectorIndexOptions {
      * Index algorithm. Defaults to `"flat"` (exact brute-force).
      * Use `"hnsw"` for approximate nearest-neighbour search — much faster on
      * large collections at the cost of occasional missed results.
-     * Requires the `vector-hnsw` feature to be compiled in.
+     * Supported on browser, Node.js and React Native.
      */
     indexType?: 'flat' | 'hnsw';
-    /** HNSW connectivity parameter M (default 16). Higher = better recall, more memory. */
+    /** HNSW connectivity parameter M. Supported range is 2–128; defaults to 32. */
     hnswM?: number;
     /** HNSW build-time quality parameter ef_construction (default 200). */
     hnswEfConstruction?: number;
+    /** Graph compression; originals remain available for exact rescoring. */
+    quantization?: VectorQuantization;
 }
 /** Describes the indexes that exist on a collection. */
 interface CollectionIndexInfo {
@@ -482,7 +562,7 @@ type AggregatePipeline<T extends Document = Document> = AggregateStage<T>[];
 type InsertDoc<T extends Document> = Omit<T, '_id'> & {
     _id?: string;
 };
-interface Collection<T extends Document = Document> {
+interface Collection<T extends Document = Document> extends VectorClient<T> {
     insert(doc: InsertDoc<T>): Promise<string>;
     insertMany(docs: InsertDoc<T>[]): Promise<string[]>;
     find(filter?: Filter<T>): Promise<T[]>;
@@ -600,7 +680,7 @@ interface Collection<T extends Document = Document> {
      *
      * After calling this, `findNearest` uses approximate nearest-neighbour
      * search which is significantly faster on large collections.
-     * Requires the `vector-hnsw` feature to be compiled in; no-op otherwise.
+     * Promotes flat/legacy indexes and compacts persistent graphs.
      */
     upgradeVectorIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     /**
@@ -620,7 +700,7 @@ interface Collection<T extends Document = Document> {
      *   locale: 'en',
      * });
      */
-    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>): Promise<VectorSearchResult<T>[]>;
+    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>, options?: VectorQueryOptions): Promise<VectorSearchResult<T>[]>;
     /**
      * Subscribe to live query results. The callback receives a full snapshot of
      * matching documents immediately and again after every write that could
@@ -681,33 +761,26 @@ interface TalaDB {
      */
     flush?(): Promise<void>;
     /**
-     * Whether this tab's writes land authoritatively, without being forwarded to
-     * another tab.
-     *
-     * **Browser only.** The first tab to open a database becomes the primary and
-     * owns the storage; later tabs run an in-memory copy and forward their writes
-     * to it over BroadcastChannel. Both the OPFS owner and — where OPFS is
-     * unavailable — the tab that publishes the IndexedDB snapshot report `true`.
-     *
-     * Use it for work that must not run in more than one tab at a time, or that
-     * depends on reading its own writes back immediately: a background queue
-     * drainer, a scheduled cleanup pass, an outbound sync loop. A secondary tab
-     * sees other tabs' writes up to ~500 ms late, and its own writes only once
-     * the primary has applied them.
-     *
-     * Primary status changes during a session — closing the owning tab promotes
-     * another — so re-check it rather than caching the answer.
-     *
-     * Always `true` on Node.js and React Native, where a single process owns the
-     * database. May be absent on older `@taladb/web` builds — treat absence as
-     * `true`.
-     *
-     * @example
-     * if (await db.isPrimary?.() ?? true) {
-     *   await drainOutbox();
-     * }
+     * Rebuild all configured HNSW graphs for maintenance. Graphs persist across
+     * restarts; startup rebuilding is unnecessary. Prefer per-collection
+     * rebuildVectorIndex for bounded batches, progress and cancellation.
+     */
+    rebuildVectorIndexes?(): Promise<void>;
+    /**
+     * Whether this browser tab owns the database storage. All tabs execute reads
+     * and writes through that owner and await its result. Ownership can change
+     * after the owning tab closes. Node.js and React Native return true.
      */
     isPrimary?(): Promise<boolean>;
+    /** Actual browser storage/durability capabilities, including fallback errors. */
+    storageInfo?(): Promise<{
+        storage: 'opfs' | 'indexeddb';
+        durableWrites: boolean;
+        maxSnapshotBytes: number | null;
+        storageError: string | null;
+        hnsw: boolean;
+        owner: boolean;
+    }>;
     /**
      * Change-webhook delivery counters, when the webhook is enabled. All zero
      * (and `pending: 0`) when it is not.
@@ -945,4 +1018,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, type HybridSearchOptions, type HybridSearchResult, type InsertDoc, type Migration, type OpenDBOptions, type Schema, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, type WebhookConfig, type WebhookDispatcher, type WebhookEvent, type WebhookOp, type WebhookStats, applySchema, createWebhookDispatcher, decorateCollection, deriveDocId, isDocId, openDB, runMigrations, validateWebhookConfig };
+export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, type HybridSearchOptions, type HybridSearchResult, type InsertDoc, type Migration, type OpenDBOptions, type Schema, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorBuildProgress, type VectorClient, type VectorGraphOptions, type VectorIndexOptions, type VectorIndexStatus, type VectorMetric, type VectorQuantization, type VectorQueryOptions, type VectorQueryResult, type VectorRebuildOptions, type VectorRecall, type VectorSearchResult, type WebhookConfig, type WebhookDispatcher, type WebhookEvent, type WebhookOp, type WebhookStats, applySchema, createVectorClient, createWebhookDispatcher, decorateCollection, deriveDocId, isDocId, openDB, runMigrations, validateWebhookConfig };