pi-vault-mind 0.14.2 → 0.16.3

package/dist/src/lance.js

@@ -4,7 +4,8 @@ import * as lancedb from "@lancedb/lancedb";
 import { LanceSchema, TextEmbeddingFunction } from "@lancedb/lancedb/embedding";
 import * as arrow from "apache-arrow";
 import { EmbeddingCoalescer } from "./embed-queue.js";
-import { createModalClient, namespacedTableName, resolveDim, resolveModel, } from "./modal-config.js";
+import { createProvider } from "./embedding-providers.js";
+import { namespacedTableName, resolveDim, resolveModel } from "./modal-config.js";
 let db = null;
 // ── Connection ──────────────────────────────────────────────────────────────
 export const connect = async (dataDir) => {
@@ -22,151 +23,46 @@ export const resetConnection = () => {
     modalTableCache.clear();
     modalTableInFlight.clear();
     nativeDimCache.clear();
+    providerCache.clear();
     void disposeCoalescers();
 };
-// ── Embedding Functions ─────────────────────────────────────────────────────
+// ── Lance Adapter ───────────────────────────────────────────────────────────
+// `TextEmbeddingFunction` is LanceDB's store-specific contract. The
+// store-agnostic `EmbeddingProvider` (see src/embedding-providers.ts) is
+// the source of truth; this adapter is the only place that knows both
+// interfaces. Adding a new vector store (Qdrant, Pinecone, pgvector, …)
+// means writing a new adapter here; the provider code does not change.
 /**
- * OpenAI-compatible embedding function that POSTs to /v1/embeddings.
- * Works with any OpenAI-compatible endpoint (Ollama, Modal, cloud providers).
+ * Wraps a store-agnostic `EmbeddingProvider` into LanceDB's
+ * `TextEmbeddingFunction`. The provider supplies `embed()`; the adapter
+ * supplies the schema helpers (`sourceField`, `vectorField`,
+ * `embeddingDataType`) and the task-routed convenience methods
+ * (`computeSourceEmbeddings` for the storage path, `computeQueryEmbeddings`
+ * for the search path).
  */
-class OpenAICompatibleEmbeddingFunction extends TextEmbeddingFunction {
-    url;
-    model;
-    apiKey;
-    ndimsValue;
-    constructor(options) {
+class LanceEmbeddingAdapter extends TextEmbeddingFunction {
+    provider;
+    constructor(provider) {
         super();
-        this.url = options.url;
-        this.model = options.model;
-        this.apiKey = options.apiKey;
-        this.ndimsValue = options.dims;
+        this.provider = provider;
     }
     ndims() {
-        return this.ndimsValue;
+        return this.provider.dim();
     }
     embeddingDataType() {
         return new arrow.Float32();
     }
-    async init() {
-        // Best-effort connectivity check
-        try {
-            const baseUrl = this.url.replace(/\/v1\/embeddings\/?$/, "").replace(/\/+$/, "");
-            const headers = {};
-            if (this.apiKey)
-                headers.Authorization = `Bearer ${this.apiKey}`;
-            await fetch(`${baseUrl}/v1/models`, { headers });
-        }
-        catch (err) {
-            console.warn(`[pi-vault-mind] Cannot reach embedding endpoint at ${this.url}: ${err}`);
-        }
-    }
-    async generateEmbeddings(texts) {
-        const endpoint = this.url.endsWith("/v1/embeddings")
-            ? this.url
-            : `${this.url.replace(/\/+$/, "")}/v1/embeddings`;
-        const headers = { "Content-Type": "application/json" };
-        if (this.apiKey)
-            headers.Authorization = `Bearer ${this.apiKey}`;
-        const resp = await fetch(endpoint, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ model: this.model, input: texts }),
-        });
-        if (!resp.ok) {
-            const body = await resp.text().catch(() => "");
-            throw new Error(`Embed failed: ${resp.status} ${body}`);
-        }
-        const data = (await resp.json());
-        if (!data.data || !Array.isArray(data.data)) {
-            throw new Error("Invalid embedding response");
-        }
-        return data.data.map((d) => d.embedding);
-    }
-}
-/**
- * Transformers.js fallback — fully offline, works on any Node.js.
- */
-class TransformersEmbeddingFunction extends TextEmbeddingFunction {
-    extractor = null;
-    initPromise = null;
-    ndims() {
-        return 384;
-    }
-    embeddingDataType() {
-        return new arrow.Float32();
-    }
-    async init() {
-        if (!this.initPromise) {
-            this.initPromise = (async () => {
-                const { pipeline } = await import("@xenova/transformers");
-                this.extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
-            })();
-        }
-        return this.initPromise;
-    }
-    async generateEmbeddings(texts) {
-        await this.init();
-        const embeddings = [];
-        for (const text of texts) {
-            const result = await this.extractor(text, { pooling: "mean", normalize: true });
-            embeddings.push(Array.from(result.data));
-        }
-        return embeddings;
-    }
-}
-// ── Modal Provider ──────────────────────────────────────────────────────────
-/**
- * Embedding function backed by the Modal `/embed` endpoint (see
- * `src/modal-client.ts`). Used two ways:
- *
- *  1. As a `TextEmbeddingFunction` for graph tables that still auto-embed via
- *     `sourceField` (document task for storage, query task for search).
- *  2. As the `embedFn` wrapped by the `EmbeddingCoalescer` for the main
- *     collection path, where append/ingest is debounced + batched and search
- *     bypasses the debounce via `embedImmediate`.
- *
- * The main collection path does NOT auto-embed — it inserts precomputed
- * vectors into namespaced `col_{collection}__{model}__{dim}` tables (see
- * `upsertEntry`/`searchHybrid` below and ADR-3). One canonical model owns the
- * vector space; a single query never mixes `model__dim` spaces.
- */
-class ModalEmbeddingFunction extends TextEmbeddingFunction {
-    cfg;
-    collection;
-    ndimsValue;
-    constructor(cfg, collection, ndimsValue) {
-        super();
-        this.cfg = cfg;
-        this.collection = collection;
-        this.ndimsValue = ndimsValue;
-    }
-    ndims() {
-        return this.ndimsValue;
-    }
-    embeddingDataType() {
-        return new arrow.Float32();
-    }
-    /** Batched embed against `/embed`. `task` selects query vs document. */
+    /** Batched embed. `task` selects query vs document. */
     async generateEmbeddings(texts, task = "document") {
-        const client = createModalClient(this.cfg);
-        if (!client)
-            throw new Error("Modal provider not configured (missing baseUrl or token).");
-        const res = await client.embed(texts, {
-            model: resolveModel(this.cfg, this.collection),
-            dim: resolveDim(this.cfg, this.collection),
-            task,
-        });
-        // Cache the model's effective output dim for table resolution.
-        rememberNativeDim(resolveModel(this.cfg, this.collection), res.dim);
-        return res.vectors;
-    }
-    // Storage path (LanceDB auto-embed via sourceField) → document task.
+        return this.provider.embed(texts, task);
+    }
+    /** Storage path (LanceDB auto-embed via `sourceField`) → document task. */
     async computeSourceEmbeddings(texts) {
-        return this.generateEmbeddings(texts, "document");
+        return this.provider.embed(texts, "document");
     }
-    // Query path (LanceDB nearestTo via embedding function) → query task.
+    /** Query path (LanceDB `nearestTo`) → query task. */
     async computeQueryEmbeddings(data) {
-        const vecs = await this.generateEmbeddings([data], "query");
+        const vecs = await this.provider.embed([data], "query");
         return vecs[0];
     }
 }
@@ -196,14 +92,31 @@ const effectiveDim = (cfg, collection) => {
  * `cfg.embedding.coalesce` (Q6).
  */
 const coalescerCache = new Map();
+/** Provider promise cache — `createProvider` is async; we memoize by key. */
+const providerCache = new Map();
 const coalesceKey = (cfg, collection) => `modal:${resolveModel(cfg, collection)}:${resolveDim(cfg, collection) ?? "native"}`;
+const getProvider = (cfg, collection) => {
+    const key = coalesceKey(cfg, collection);
+    let p = providerCache.get(key);
+    if (!p) {
+        p = createProvider(cfg, { collection });
+        providerCache.set(key, p);
+    }
+    return p;
+};
 const getCoalescer = (cfg, collection) => {
     const key = coalesceKey(cfg, collection);
     const existing = coalescerCache.get(key);
     if (existing)
         return existing;
-    const fn = new ModalEmbeddingFunction(cfg, collection);
-    const embedFn = (texts, task) => fn.generateEmbeddings(texts, task);
+    // createProvider is async; the coalescer's embedFn closure fires after
+    // the provider is ready. If the provider rejects at init(), the first
+    // embed call surfaces that error to the caller.
+    let provider;
+    const providerPromise = getProvider(cfg, collection).then((p) => {
+        provider = p;
+    });
+    const embedFn = (texts, task) => providerPromise.then(() => provider.embed(texts, task));
     const co = cfg.embedding.coalesce ?? {};
     const coalescer = new EmbeddingCoalescer({
         embedFn,
@@ -341,10 +254,7 @@ const modalFtsFallback = async (dataDir, collection, model, query, limit, identi
  * null when no same-space fallback is available, so the caller degrades to FTS.
  */
 const fallbackQueryEmbed = async (cfg, collection, text) => {
-    const fb = cfg.embedding.modal?.fallback;
-    if (fb?.enabled === false)
-        return null;
-    if (fb?.provider !== "openai-compatible")
+    if (cfg.embedding.fallback?.enabled === false)
         return null;
     if (!cfg.embedding.localUrl)
         return null;
@@ -352,13 +262,8 @@ const fallbackQueryEmbed = async (cfg, collection, text) => {
     if ((cfg.embedding.model || "embeddinggemma") !== canonical)
         return null;
     try {
-        const fn = new OpenAICompatibleEmbeddingFunction({
-            url: cfg.embedding.localUrl,
-            model: cfg.embedding.model || "embeddinggemma",
-            apiKey: cfg.embedding.apiKey,
-        });
-        await fn.init();
-        const vecs = await fn.generateEmbeddings([text]);
+        const fn = await createProvider(cfg, { collection });
+        const vecs = await fn.embed([text], "query");
         return vecs[0];
     }
     catch (err) {
@@ -381,42 +286,11 @@ const disposeCoalescers = async () => {
 };
 // ── Embedding Provider Factory ──────────────────────────────────────────────
 const getEmbeddingFunction = async (cfg) => {
-    if (cfg.embedding.remoteUrl) {
-        const dim = effectiveDim(cfg);
-        return new ModalEmbeddingFunction(cfg, undefined, dim);
-    }
-    if (cfg.embedding.localUrl) {
-        const fn = new OpenAICompatibleEmbeddingFunction({
-            url: cfg.embedding.localUrl,
-            model: cfg.embedding.model || "embeddinggemma",
-            apiKey: cfg.embedding.apiKey,
-        });
-        await fn.init();
-        return fn;
-    }
-    if (cfg.embedding.useTransformers !== false) {
-        const fn = new TransformersEmbeddingFunction();
-        await fn.init();
-        return fn;
-    }
-    throw new Error("No embedding provider configured. Set remoteUrl, localUrl, or useTransformers: true.");
+    const dims = effectiveDim(cfg);
+    const provider = await createProvider(cfg, { dims });
+    return new LanceEmbeddingAdapter(provider);
 };
 // ── Schema Builders ─────────────────────────────────────────────────────────
-function makeCollectionSchema(embeddingFn) {
-    return LanceSchema({
-        id: new arrow.Utf8(),
-        domain: new arrow.Utf8(),
-        source: new arrow.Utf8(),
-        fact: embeddingFn.sourceField(),
-        tag: new arrow.Utf8(),
-        artifact: new arrow.Utf8(),
-        created_at: new arrow.Utf8(),
-        origin_identity: new arrow.Utf8(),
-        visibility: new arrow.Utf8(),
-        identity: new arrow.Utf8(),
-        vector: embeddingFn.vectorField(),
-    });
-}
 /**
  * Backwards-compat: ensure the `identity` column exists on tables created before
  * this field was added. The column is nullable so old rows remain readable.
@@ -440,6 +314,12 @@ function makeEntitySchema(embeddingFn) {
         vector: embeddingFn.vectorField(),
     });
 }
+async function assertPlainCollectionSchema(table, tableName) {
+    const schema = await table.schema();
+    if (schema.metadata?.has("embedding_functions")) {
+        throw new Error(`Old-format LanceDB table "${tableName}" uses embedded LanceSchema metadata. Run /vm index --reembed to migrate it to the explicit-vector schema.`);
+    }
+}
 function makeRelationSchema(embeddingFn) {
     return LanceSchema({
         id: new arrow.Utf8(),
@@ -456,20 +336,23 @@ function makeRelationSchema(embeddingFn) {
     });
 }
 let tables = {};
-const getCollectionTable = async (dataDir, collectionName, cfg) => {
+const getCollectionTable = async (dataDir, collectionName, cfg, vectorDim) => {
     const conn = await connect(dataDir);
     const tableName = `collection_${collectionName}`;
     if (tables[tableName])
         return tables[tableName];
-    const embeddingFn = await getEmbeddingFunction(cfg);
-    const schema = makeCollectionSchema(embeddingFn);
     const existing = await conn.tableNames();
     if (existing.includes(tableName)) {
         tables[tableName] = await conn.openTable(tableName);
+        await assertPlainCollectionSchema(tables[tableName], tableName);
         await ensureIdentityColumn(tables[tableName]);
         return tables[tableName];
     }
-    tables[tableName] = await conn.createEmptyTable(tableName, schema);
+    const dim = vectorDim ?? effectiveDim(cfg, collectionName);
+    if (dim == null) {
+        throw new Error(`Collection "${collectionName}" needs a known embedding dimension. Set vaultMind.embedding.dim, or embed a row first.`);
+    }
+    tables[tableName] = await conn.createEmptyTable(tableName, makeModalCollectionSchema(dim));
     if (cfg.ftsEnabled !== false) {
         try {
             await tables[tableName].createIndex("fact", { config: lancedb.Index.fts() });
@@ -492,7 +375,7 @@ const assertGraphDim = (cfg, kind) => {
         throw new Error(`Graph ${kind} table needs a known embedding dimension. Set vaultMind.embedding.dim, or run an embed/sync first so the native dim is cached.`);
     }
 };
-const getEntityTable = async (dataDir, cfg) => {
+const _getEntityTable = async (dataDir, cfg) => {
     const conn = await connect(dataDir);
     const tableName = "entities";
     if (tables[tableName])
@@ -508,7 +391,7 @@ const getEntityTable = async (dataDir, cfg) => {
     tables[tableName] = await conn.createEmptyTable(tableName, schema);
     return tables[tableName];
 };
-const getRelationTable = async (dataDir, cfg) => {
+const _getRelationTable = async (dataDir, cfg) => {
     const conn = await connect(dataDir);
     const tableName = "relations";
     if (tables[tableName])
@@ -525,11 +408,14 @@ const getRelationTable = async (dataDir, cfg) => {
     return tables[tableName];
 };
 // ── Public API ──────────────────────────────────────────────────────────────
-const isModal = (cfg) => !!cfg.embedding.remoteUrl && !!cfg.embedding.modal;
+const isModal = (cfg) => !!cfg.embedding.remoteUrl;
 export const upsertEntry = async (dataDir, collectionName, entry, cfg, identity) => {
     if (isModal(cfg))
         return upsertEntryModal(dataDir, collectionName, entry, cfg, identity);
-    const table = await getCollectionTable(dataDir, collectionName, cfg);
+    const embeddingFn = await getEmbeddingFunction(cfg);
+    const text = entry.fact || "";
+    const vectors = await embeddingFn.computeSourceEmbeddings([text]);
+    const table = await getCollectionTable(dataDir, collectionName, cfg, vectors[0]?.length);
     const row = {
         id: entry.id || crypto.randomUUID(),
         domain: entry.domain || "",
@@ -541,6 +427,7 @@ export const upsertEntry = async (dataDir, collectionName, entry, cfg, identity)
         origin_identity: identity?.id || "",
         visibility: identity?.visibility || "vault",
         identity: entry.identity || identity?.id || "",
+        vector: vectors[0],
     };
     await table.add([row]);
 };
@@ -590,10 +477,7 @@ const upsertEntryModal = async (dataDir, collectionName, entry, cfg, identity) =
 };
 /** Offline fallback embed for a document (storage). Same-space local only. */
 const fallbackDocumentEmbed = async (cfg, collection, text) => {
-    const fb = cfg.embedding.modal?.fallback;
-    if (fb?.enabled === false)
-        return null;
-    if (fb?.provider !== "openai-compatible")
+    if (cfg.embedding.fallback?.enabled === false)
         return null;
     if (!cfg.embedding.localUrl)
         return null;
@@ -601,13 +485,8 @@ const fallbackDocumentEmbed = async (cfg, collection, text) => {
     if ((cfg.embedding.model || "embeddinggemma") !== canonical)
         return null;
     try {
-        const fn = new OpenAICompatibleEmbeddingFunction({
-            url: cfg.embedding.localUrl,
-            model: cfg.embedding.model || "embeddinggemma",
-            apiKey: cfg.embedding.apiKey,
-        });
-        await fn.init();
-        const vecs = await fn.generateEmbeddings([text]);
+        const fn = await createProvider(cfg, { collection });
+        const vecs = await fn.embed([text], "document");
         return vecs[0];
     }
     catch (err) {
@@ -646,13 +525,22 @@ export const upsertPrecomputed = async (dataDir, collectionName, model, dim, row
     });
     await table.mergeInsert(["id"]).whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(mapped);
 };
-/** Filter results by visibility: show public entries + entries owned by the reader. No identity = no filter (backward compat). */
-function filterByVisibility(results, identity) {
+function isVisibilityRecord(value) {
+    return value !== null && typeof value === "object";
+}
+/** Filter results by visibility: show public entries + entries owned by the reader. No identity = no filter (backward compat).
+ * Records without visibility/origin_identity fields (e.g. graph entities/relations) are treated as public. */
+export function filterByVisibility(results, identity) {
     if (!identity)
         return results;
     return results.filter((r) => {
+        if (!isVisibilityRecord(r))
+            return true;
         const vis = r.visibility;
         const origin = r.origin_identity;
+        // Graph entities/relations have no visibility fields; they are already gated at upsert time.
+        if (vis === undefined && origin === undefined)
+            return true;
         return vis === "public" || origin === identity.id;
     });
 }
@@ -700,10 +588,19 @@ export const queryCollection = async (collectionPath, schema, query, filters, li
 export const searchHybrid = async (dataDir, collectionName, query, limit, cfg, identity) => {
     if (isModal(cfg))
         return searchHybridModal(dataDir, collectionName, query, limit, cfg, identity);
+    const tableName = `collection_${collectionName}`;
+    const conn = await connect(dataDir);
+    if (!tables[tableName] && !(await conn.tableNames()).includes(tableName))
+        return [];
     const table = await getCollectionTable(dataDir, collectionName, cfg);
     const embeddingFn = await getEmbeddingFunction(cfg);
     const queryVector = await embeddingFn.generateEmbeddings([query]);
-    const results = await table.query().nearestTo(queryVector[0]).limit(limit).toArray();
+    const results = await table
+        .query()
+        .nearestTo(queryVector[0])
+        .column("vector")
+        .limit(limit)
+        .toArray();
     return filterByVisibility(results, identity);
 };
 /**
@@ -736,7 +633,12 @@ const searchHybridModal = async (dataDir, collectionName, query, limit, cfg, ide
         return modalFtsFallback(dataDir, collectionName, model, query, limit, identity);
     }
     try {
-        const results = await found.table.query().nearestTo(queryVector).limit(limit).toArray();
+        const results = await found.table
+            .query()
+            .nearestTo(queryVector)
+            .column("vector")
+            .limit(limit)
+            .toArray();
         return filterByVisibility(results, identity);
     }
     catch (err) {
@@ -752,17 +654,55 @@ export const searchFts = async (dataDir, collectionName, query, limit, cfg, iden
         if (!found)
             return [];
         try {
-            const results = await found.table.search(query).limit(limit).toArray();
+            const results = await found.table
+                .query()
+                .nearestToText(query, ["fact"])
+                .limit(limit)
+                .toArray();
             return filterByVisibility(results, identity);
         }
         catch {
             return [];
         }
     }
+    const tableName = `collection_${collectionName}`;
+    const conn = await connect(dataDir);
+    if (!tables[tableName] && !(await conn.tableNames()).includes(tableName))
+        return [];
     const table = await getCollectionTable(dataDir, collectionName, cfg);
-    const results = await table.search(query).limit(limit).toArray();
+    const results = await table.query().nearestToText(query, ["fact"]).limit(limit).toArray();
     return filterByVisibility(results, identity);
 };
+/**
+ * Rank-merge vector and FTS results: vector hits score higher, deduplicated by
+ * id or fact. Each result is tagged with `_source: "vector" | "fts"`. Falls
+ * back gracefully — if either path fails, the other still contributes.
+ */
+export const searchHybridRanked = async (dataDir, collectionName, query, limit, cfg, identity) => {
+    const [vectorResults, ftsResults] = await Promise.all([
+        searchHybrid(dataDir, collectionName, query, limit, cfg, identity).catch(() => []),
+        searchFts(dataDir, collectionName, query, limit, cfg, identity).catch(() => []),
+    ]);
+    const seen = new Set();
+    const merged = [];
+    for (const r of vectorResults) {
+        const row = r;
+        const key = (row.id ?? row.fact ?? JSON.stringify(row));
+        if (!seen.has(key)) {
+            seen.add(key);
+            merged.push({ ...row, _source: "vector" });
+        }
+    }
+    for (const r of ftsResults) {
+        const row = r;
+        const key = (row.id ?? row.fact ?? JSON.stringify(row));
+        if (!seen.has(key)) {
+            seen.add(key);
+            merged.push({ ...row, _source: "fts" });
+        }
+    }
+    return merged.slice(0, limit);
+};
 export const getStatus = async (dataDir) => {
     const conn = await connect(dataDir);
     const names = await conn.tableNames();

package/dist/src/modal-client.d.ts

@@ -183,4 +183,20 @@ export declare class ModalEmbeddingClient {
         since?: number;
         limit?: number;
     }): Promise<number>;
+    /**
+     * Submit bulk embedding jobs for multiple collections, wait for all to
+     * complete, and return per-collection results. Used by the /vm/reindex
+     * endpoint to trigger a full remote reindex from the status tab.
+     */
+    reindexAll(jobs: Array<{
+        collection: string;
+        records: JobRecord[];
+    }>, opts?: {
+        model?: string;
+        dim?: number;
+    }): Promise<Array<{
+        collection: string;
+        job: JobSubmitResult;
+        status: JobStatus;
+    }>>;
 }

package/dist/src/modal-client.js

@@ -187,4 +187,20 @@ export class ModalEmbeddingClient {
                 return watermark;
         }
     }
+    /**
+     * Submit bulk embedding jobs for multiple collections, wait for all to
+     * complete, and return per-collection results. Used by the /vm/reindex
+     * endpoint to trigger a full remote reindex from the status tab.
+     */
+    async reindexAll(jobs, opts = {}) {
+        const results = [];
+        for (const { collection, records } of jobs) {
+            if (records.length === 0)
+                continue;
+            const submitted = await this.submitJob(collection, records, opts);
+            const status = await this.waitForJob(submitted.job_id);
+            results.push({ collection, job: submitted, status });
+        }
+        return results;
+    }
 }

package/dist/src/modal-config.d.ts

@@ -10,23 +10,29 @@
  */
 import { ModalEmbeddingClient } from "./modal-client.js";
 import type { VaultMindConfig } from "./types.js";
-/** Env var name for the Modal bearer token (preferred over config). */
-export declare const MODAL_TOKEN_ENV = "PVM_API_TOKEN";
+/** Env var name for the unscoped remote embedding API key (preferred over config). */
+export declare const MODAL_TOKEN_ENV = "PVM_REMOTE_EMBEDDING_API_KEY";
 /** Env var name for the read-scoped Modal token (search/export). */
 export declare const MODAL_READ_TOKEN_ENV = "PVM_MODAL_READ_TOKEN";
 /** Env var name for the write-scoped Modal token (embed/reindex). */
 export declare const MODAL_WRITE_TOKEN_ENV = "PVM_MODAL_WRITE_TOKEN";
-/** Dotenv-style fallback path for the Modal token. */
-export declare const MODAL_TOKEN_ENV_PATH: string;
+/**
+ * Dotenv fallback path for the Modal token, resolved from the vault cwd:
+ * `<vault>/.vault-mind/vault-mind.env`. Lazy so tests can override cwd.
+ */
+export declare const modalTokenEnvPath: (cwd?: string) => string;
 /** Canonical deployed Modal app name. */
 export declare const MODAL_APP_NAME = "pi-vault-mind-embed";
 /** Derive the Modal service URL from a workspace slug and canonical app name. */
 export declare const modalUrl: (workspace: string) => string;
 /**
- * Resolve the Modal API token. Resolution order:
- * 1. `PVM_API_TOKEN` env var
- * 2. `~/.pi/agent/vault-mind.env`
- * 3. `vaultMind.embedding.modal.apiToken` in config
+ * Resolve the unscoped remote embedding API token. Resolution order:
+ * 1. `PVM_REMOTE_EMBEDDING_API_KEY` env var
+ * 2. `<vault>/.vault-mind/vault-mind.env`
+ * 3. `vaultMind.embedding.remoteApiKey` in config
+ *
+ * `PVM_API_TOKEN` is intentionally not consulted — it is reserved for the
+ * extension's bridge authentication.
  *
  * Never log the resolved token.
  */
@@ -35,14 +41,17 @@ export declare const resolveModalToken: (cfg: VaultMindConfig) => string | undef
  * Resolve a scoped Modal token for the requested operation.
  * Resolution order:
  * 1. `PVM_MODAL_{READ|WRITE}_TOKEN` env var
- * 2. `~/.pi/agent/vault-mind.env`
- * 3. `vaultMind.embedding.modal.{readToken|writeToken}` in config
- * 4. Fallback to the unscoped `apiToken` (env, dotenv, then config)
+ * 2. `<vault>/.vault-mind/vault-mind.env`
+ * 3. `vaultMind.embedding.remoteReadApiKey` / `remoteWriteApiKey` in config
+ * 4. Fallback to the unscoped `PVM_REMOTE_EMBEDDING_API_KEY` (env, dotenv, then config)
+ *
+ * `PVM_API_TOKEN` is intentionally not consulted — it is reserved for the
+ * extension's bridge authentication.
  *
  * Never log the resolved token.
  */
 export declare const getModalToken: (cfg: VaultMindConfig, operation: "read" | "write") => string | undefined;
-/** Resolve the explicit baseUrl or derive it from workspace. */
+/** Derive the remote URL from the top-level `remoteUrl` or the `workspace` shortcut. */
 export declare const resolveBaseUrl: (cfg: VaultMindConfig) => string | undefined;
 /** Resolve the configured workspace slug, if any. */
 export declare const resolveWorkspace: (cfg: VaultMindConfig) => string | undefined;
@@ -62,9 +71,23 @@ export declare const createModalClient: (cfg: VaultMindConfig) => ModalEmbedding
 export declare const resolveModel: (cfg: VaultMindConfig, collection?: string) => string;
 /**
  * The configured output dimension for a collection, if known. Per-collection
- * overrides win; otherwise the global Modal config `dim`. Returns undefined
- * when unset — callers resolve the native dim lazily via `/models`.
+ * overrides win; otherwise the top-level `dim` on `EmbeddingConfig`.
+ * Returns undefined when unset — callers resolve the native dim lazily via `/models`.
  */
 export declare const resolveDim: (cfg: VaultMindConfig, collection?: string) => number | undefined;
 /** Namespaced local table name mirroring the server's ADR-3 scheme. */
 export declare const namespacedTableName: (collection: string, model: string, dim: number) => string;
+/**
+ * Resolve the server-side (Modal) collection table prefix for cross-vault
+ * isolation on a shared Modal deployment. Unset or `"auto"` derives it from
+ * the vault slug. The result is normalized (no `__`, no leading/trailing `_`)
+ * so it is safe for the server's `col_(.+)__(.+)__(\d+)$` parse.
+ *
+ * Applies ONLY to remote table names — local LanceDB tables stay unprefixed.
+ */
+export declare const resolveCollectionPrefix: (cfg: VaultMindConfig, vaultPath: string) => string | undefined;
+/**
+ * Prepend the collection prefix to a collection name for server-side table
+ * identity. When `prefix` is undefined, returns the collection name unchanged.
+ */
+export declare const serverCollectionName: (prefix: string | undefined, collection: string) => string;