Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(knowledge): make in-place file replacement race-safe

wizardchen079e96ae64b7
diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.go
index 16f148b7e..2e4ef0252 100644
--- a/internal/application/service/knowledge.go
+++ b/internal/application/service/knowledge.go
@@ -424,6 +424,32 @@ func (s *knowledgeService) isKnowledgeAborted(
return false, knowledge.ParseStatus
}
+// isKnowledgeSourceReplaced reports whether the stored source file no longer
+// matches the in-memory knowledge this worker loaded. ReplaceKnowledgeFile
+// changes file_path under a still-running ProcessDocument; the stale worker
+// must not Save() the old path back or write chunks from the replaced file.
+func (s *knowledgeService) isKnowledgeSourceReplaced(ctx context.Context, knowledge *types.Knowledge) bool {
+ if knowledge == nil || knowledge.ID == "" || knowledge.FilePath == "" {
+ return false
+ }
+ current, err := s.repo.GetKnowledgeByID(ctx, knowledge.TenantID, knowledge.ID)
+ if err != nil || current == nil {
+ return false
+ }
+ return current.FilePath != "" && current.FilePath != knowledge.FilePath
+}
+
+// updateKnowledgeUnlessSourceReplaced persists processing state only when this
+// worker still owns the source file. A no-op skip is preferred over rolling
+// file_path back to a blob ReplaceKnowledgeFile may already have deleted.
+func (s *knowledgeService) updateKnowledgeUnlessSourceReplaced(ctx context.Context, knowledge *types.Knowledge) error {
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Skip knowledge update for %s: source file was replaced", knowledge.ID)
+ return nil
+ }
+ return s.repo.UpdateKnowledge(ctx, knowledge)
+}
+
// checkStorageEngineConfigured verifies that the knowledge base has a storage engine configured
// (either at the KB level or via the tenant default).
//
diff --git a/internal/application/service/knowledge_process.go b/internal/application/service/knowledge_process.go
index 04e2210fb..7c028f007 100644
--- a/internal/application/service/knowledge_process.go
+++ b/internal/application/service/knowledge_process.go
@@ -314,6 +314,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,
logger.Infof(ctx, "Knowledge aborted (%s), skipping chunk processing: %s", status, knowledge.ID)
return
}
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Knowledge source replaced, skipping chunk processing: %s", knowledge.ID)
+ return
+ }
// Get embedding model for vectorization — only needed when vector/keyword indexing is enabled
var embeddingModel embedding.Embedder
@@ -525,6 +529,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,
logger.Infof(ctx, "Knowledge aborted (%s), skipping chunk write: %s", status, knowledge.ID)
return
}
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Knowledge source replaced, skipping chunk write: %s", knowledge.ID)
+ return
+ }
// Save chunks to database — ALWAYS, regardless of indexing strategy.
// Chunks are needed for wiki generation, graph extraction, and summary generation
@@ -609,6 +617,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,
// Check again before batch indexing (heavy operation).
// deleting → row is going away anyway, drop the chunks we just wrote.
// cancelled → user wants to keep what was already persisted, just stop.
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Knowledge source replaced, skipping indexing: %s", knowledge.ID)
+ return
+ }
if aborted, status := s.isKnowledgeAborted(ctx, knowledge.TenantID, knowledge.ID); aborted {
logger.Infof(ctx, "Knowledge aborted (%s) before indexing: %s", status, knowledge.ID)
if status == types.ParseStatusDeleting {
@@ -657,6 +669,10 @@ func (s *knowledgeService) processChunks(ctx context.Context,
// deleting → drop chunks+index we just wrote.
// cancelled → keep persisted data; the row stays in cancelled status
// and downstream stages skip via the entry guards.
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Knowledge source replaced, skipping completion: %s", knowledge.ID)
+ return
+ }
if aborted, status := s.isKnowledgeAborted(ctx, knowledge.TenantID, knowledge.ID); aborted {
logger.Infof(ctx, "Knowledge aborted (%s) after indexing: %s", status, knowledge.ID)
if status == types.ParseStatusDeleting {
@@ -689,7 +705,7 @@ func (s *knowledgeService) processChunks(ctx context.Context,
now,
)
- if err := s.repo.UpdateKnowledge(ctx, knowledge); err != nil {
+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {
logger.GetLogger(ctx).WithField("error", err).Errorf("processChunks update knowledge failed")
}
@@ -3346,11 +3362,23 @@ func (s *knowledgeService) ProcessDocument(ctx context.Context, t *asynq.Task) e
logger.Infof(ctx, "Knowledge aborted (%s) before marking processing: %s", status, knowledge.ID)
return nil
}
+ if payload.FilePath != "" && knowledge.FilePath != "" && payload.FilePath != knowledge.FilePath {
+ logger.Infof(ctx, "Document source replaced, skipping stale process task: %s", payload.KnowledgeID)
+ return nil
+ }
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Document source replaced, skipping stale process task: %s", payload.KnowledgeID)
+ return nil
+ }
markKnowledgeProcessing(knowledge, time.Now())
- if err := s.repo.UpdateKnowledge(ctx, knowledge); err != nil {
+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {
logger.Errorf(ctx, "failed to update knowledge status to processing: %v", err)
return nil
}
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Document source replaced, aborting after status update: %s", payload.KnowledgeID)
+ return nil
+ }
// Resolve the attempt for span tracking. The enqueue site sets
// payload.Attempt to a fresh number for the initial parse and to
@@ -3811,7 +3839,9 @@ func (s *knowledgeService) convert(
knowledge.ParseStatus = "failed"
knowledge.ErrorMessage = result.Error
knowledge.UpdatedAt = time.Now()
- s.repo.UpdateKnowledge(ctx, knowledge)
+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {
+ logger.Errorf(ctx, "failed to persist parser error for %s: %v", knowledge.ID, err)
+ }
s.failStage(ctx, knowledge.ID, types.StageDocReader,
werrors.ErrCodeDocReaderParseFailed, result.Error, nil)
return nil, nil
@@ -3910,11 +3940,17 @@ func (s *knowledgeService) failKnowledge(
args ...interface{},
) (*types.ReadResult, error) {
errMsg := fmt.Sprintf(format, args...)
+ if s.isKnowledgeSourceReplaced(ctx, knowledge) {
+ logger.Infof(ctx, "Skip failing knowledge %s: source file was replaced", knowledge.ID)
+ return nil, nil
+ }
if isLastRetry {
knowledge.ParseStatus = "failed"
knowledge.ErrorMessage = errMsg
knowledge.UpdatedAt = time.Now()
- s.repo.UpdateKnowledge(ctx, knowledge)
+ if err := s.updateKnowledgeUnlessSourceReplaced(ctx, knowledge); err != nil {
+ logger.Errorf(ctx, "failed to persist knowledge failure for %s: %v", knowledge.ID, err)
+ }
}
return nil, fmt.Errorf(format, args...)
}
diff --git a/internal/application/service/knowledge_replace.go b/internal/application/service/knowledge_replace.go
index fe99569f8..ca20ef9f3 100644
--- a/internal/application/service/knowledge_replace.go
+++ b/internal/application/service/knowledge_replace.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"mime/multipart"
+ "strings"
"time"
werrors "github.com/Tencent/WeKnora/internal/errors"
@@ -21,18 +22,22 @@ import (
// Object storage is not transactional, so the steps are ordered to keep the
// row pointing at a file that exists:
// 1. save the new file under a fresh storage path;
-// 2. point the row at it with a single UPDATE of the source columns;
-// 3. ReparseKnowledge cleans the old chunks/index/graph and enqueues parsing;
-// 4. only after that succeeds, delete the old file.
+// 2. dequeue any in-flight parse of the previous source;
+// 3. point the row at the new file and mark it pending in one UPDATE;
+// 4. ReparseKnowledge cleans the old chunks/index/graph and enqueues parsing;
+// 5. only after that succeeds, delete the old file.
//
-// If step 2 fails the new file is discarded. If step 3 fails the previous
-// source columns are restored (marked failed, since cleanup may already have
-// removed the old index) and the new file is discarded. A file is never
-// deleted while the row may still reference it.
+// If step 3 fails the new file is discarded, unless a re-read shows the write
+// committed despite the error — in that case reparse continues so the row is
+// not left completed against a new file. If step 4 fails the previous source
+// columns are restored (marked failed, since cleanup may already have removed
+// the old index) and the new file is discarded. A file is never deleted while
+// the row may still reference it.
//
// Identical content under the same name and folder is not re-parsed: changed
-// metadata is persisted and a DuplicateKnowledgeError carrying the knowledge
-// is returned, mirroring CreateKnowledgeFromFile's duplicate contract.
+// metadata is persisted and a DuplicateKnowledgeError carrying this knowledge
+// is returned. Unlike CreateKnowledgeFromFile, this does not treat another
+// knowledge's hash as a duplicate — path identity is what connectors need.
func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
knowledgeID string, file *multipart.FileHeader, customFileName string, metadata map[string]string,
) (*types.Knowledge, error) {
@@ -43,6 +48,9 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
if err != nil {
return nil, err
}
+ if kb != nil && kb.Type == types.KnowledgeBaseTypeFAQ {
+ return nil, werrors.NewBadRequestError("FAQ 知识库不支持文件上传,请使用 FAQ 导入功能")
+ }
if existing.Type != "file" || existing.FilePath == "" {
return nil, werrors.NewBadRequestError("only file knowledge can have its file replaced")
}
@@ -53,13 +61,18 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
return nil, err
}
- // Same naming rules as CreateKnowledgeFromFile: a path-qualified custom name
- // places the knowledge in that folder; without one the folder is kept.
fileName, folderPath := file.Filename, existing.FolderPath
if customFileName != "" {
- folderPath, fileName = types.SplitKnowledgeRelativePath(customFileName)
- if fileName == "" {
- fileName = file.Filename
+ customFolder, customName := types.SplitKnowledgeRelativePath(customFileName)
+ if customName == "" {
+ customName = file.Filename
+ }
+ fileName = customName
+ // A path-qualified name relocates the knowledge. A bare filename
+ // keeps the existing folder so callers can pass file.Filename as
+ // customFileName without moving the document to the KB root.
+ if knowledgeCustomNameRelocates(customFileName) {
+ folderPath = customFolder
}
}
safeFileName, ok := secutils.ValidateInput(fileName)
@@ -108,11 +121,6 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
return existing, types.NewDuplicateFileError(existing)
}
- if tenant, _ := ctx.Value(types.TenantInfoContextKey).(*types.Tenant); tenant != nil &&
- tenant.StorageQuota > 0 && tenant.StorageUsed >= tenant.StorageQuota {
- return nil, types.NewStorageQuotaExceededError()
- }
-
fileSvc := s.resolveFileService(ctx, kb)
newPath, err := fileSvc.SaveFile(ctx, file, existing.TenantID, existing.ID)
if err != nil {
@@ -131,20 +139,35 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
if len(previousMetadata) == 0 {
previousMetadata = types.JSON("{}") // metadata is NOT NULL; an empty JSON writes NULL
}
- if err := s.repo.UpdateKnowledgeColumns(ctx, existing.ID, map[string]interface{}{
- "title": title,
- "file_name": safeFileName,
- "folder_path": folderPath,
- "file_type": fileType,
- "file_size": file.Size,
- "file_hash": hash,
- "file_path": newPath,
- "metadata": newMetadata,
- "updated_at": time.Now(),
- }); err != nil {
- logger.Errorf(ctx, "Failed to point knowledge %s at its replacement file: %v", existing.ID, err)
- s.discardReplacementFile(cleanupCtx, fileSvc, existing.TenantID, existing.ID, newPath)
- return nil, err
+
+ // Drop queued parse tasks of the previous source before the row
+ // points at the new file. The new TypeDocumentProcess task is
+ // enqueued later by ReparseKnowledge.
+ s.dequeueKnowledgeTasks(cleanupCtx, existing.ID)
+
+ sourceColumns := map[string]interface{}{
+ "title": title,
+ "file_name": safeFileName,
+ "folder_path": folderPath,
+ "file_type": fileType,
+ "file_size": file.Size,
+ "file_hash": hash,
+ "file_path": newPath,
+ "metadata": newMetadata,
+ "parse_status": types.ParseStatusPending,
+ "enable_status": "disabled",
+ "error_message": "",
+ "updated_at": time.Now(),
+ }
+ if err := s.repo.UpdateKnowledgeColumns(ctx, existing.ID, sourceColumns); err != nil {
+ current, readErr := s.repo.GetKnowledgeByID(cleanupCtx, existing.TenantID, existing.ID)
+ if readErr != nil || current == nil || current.FilePath != newPath {
+ logger.Errorf(ctx, "Failed to point knowledge %s at its replacement file: %v", existing.ID, err)
+ s.discardReplacementFile(cleanupCtx, fileSvc, existing.TenantID, existing.ID, newPath)
+ return nil, err
+ }
+ logger.Warnf(ctx, "Source update for knowledge %s reported an error after committing; continuing reparse: %v",
+ existing.ID, err)
}
reparsed, err := s.ReparseKnowledge(ctx, existing.ID, nil)
@@ -171,7 +194,8 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
}
if existing.FilePath != newPath {
- if err := fileSvc.DeleteFile(cleanupCtx, existing.FilePath); err != nil {
+ oldFileSvc := s.resolveFileServiceForPath(cleanupCtx, kb, existing.FilePath)
+ if err := oldFileSvc.DeleteFile(cleanupCtx, existing.FilePath); err != nil {
logger.Warnf(ctx, "Failed to delete replaced file %s of knowledge %s: %v",
existing.FilePath, existing.ID, err)
}
@@ -184,6 +208,10 @@ func (s *knowledgeService) ReplaceKnowledgeFile(ctx context.Context,
return reparsed, nil
}
+func knowledgeCustomNameRelocates(customFileName string) bool {
+ return strings.Contains(strings.ReplaceAll(customFileName, "\\", "/"), "/")
+}
+
// discardReplacementFile deletes a replacement file that did not become the
// knowledge's source. It re-reads the row first: a write reported as failed
// may still have committed, and a knowledge pointing at a deleted file is
diff --git a/internal/application/service/knowledge_replace_test.go b/internal/application/service/knowledge_replace_test.go
index 8ecf283bb..f802cc853 100644
--- a/internal/application/service/knowledge_replace_test.go
+++ b/internal/application/service/knowledge_replace_test.go
@@ -76,6 +76,8 @@ func (r *replaceFileRepo) apply(values map[string]interface{}) {
r.row.Metadata = value.(types.JSON)
case "parse_status":
r.row.ParseStatus = value.(string)
+ case "enable_status":
+ r.row.EnableStatus = value.(string)
case "error_message":
r.row.ErrorMessage = value.(string)
}
@@ -144,6 +146,16 @@ type replaceFileGraph struct {
func (replaceFileGraph) DelGraph(context.Context, []types.NameSpace) error { return nil }
+type replaceFileInspector struct {
+ fakeTaskInspector
+ events *[]string
+}
+
+func (i *replaceFileInspector) CancelTasksForKnowledge(_ context.Context, knowledgeID string) (int, int, error) {
+ *i.events = append(*i.events, "dequeue:"+knowledgeID)
+ return 1, 0, nil
+}
+
type replaceFileHarness struct {
svc *knowledgeService
repo *replaceFileRepo
@@ -180,13 +192,14 @@ func newReplaceFileHarness(t *testing.T) *replaceFileHarness {
h.store = &replaceFileStore{events: &h.events}
h.tasks = &replaceFileEnqueuer{events: &h.events}
h.svc = &knowledgeService{
- repo: h.repo,
- kbService: &reparseFailureKBService{kb: kb},
- fileSvc: h.store,
- task: h.tasks,
- chunkService: replaceFileChunkService{},
- chunkRepo: replaceFileChunks{},
- graphEngine: replaceFileGraph{},
+ repo: h.repo,
+ kbService: &reparseFailureKBService{kb: kb},
+ fileSvc: h.store,
+ task: h.tasks,
+ taskInspector: &replaceFileInspector{events: &h.events},
+ chunkService: replaceFileChunkService{},
+ chunkRepo: replaceFileChunks{},
+ graphEngine: replaceFileGraph{},
}
ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(7))
ctx = context.WithValue(ctx, types.TenantInfoContextKey, &types.Tenant{ID: 7})
@@ -200,7 +213,14 @@ func (h *replaceFileHarness) replace(
t *testing.T, content, customFileName string, metadata map[string]string,
) (*types.Knowledge, error) {
t.Helper()
- fh, err := bytesToFileHeader([]byte(content), "upload.md")
+ return h.replaceNamed(t, content, "upload.md", customFileName, metadata)
+}
+
+func (h *replaceFileHarness) replaceNamed(
+ t *testing.T, content, filename, customFileName string, metadata map[string]string,
+) (*types.Knowledge, error) {
+ t.Helper()
+ fh, err := bytesToFileHeader([]byte(content), filename)
require.NoError(t, err)
return h.svc.ReplaceKnowledgeFile(h.ctx, h.original.ID, fh, customFileName, metadata)
}
@@ -236,8 +256,8 @@ func TestReplaceKnowledgeFilePreservesIDAndReparsesNewContent(t *testing.T) {
require.Len(t, h.tasks.payloads, 1)
assert.Equal(t, h.original.ID, h.tasks.payloads[0].KnowledgeID)
assert.Equal(t, "new/file.md", h.tasks.payloads[0].FilePath)
- assert.Equal(t, []string{"save", "enqueue", "delete:old/file.md"}, h.events,
- "the old file is deleted only after the reparse was submitted")
+ assert.Equal(t, []string{"save", "dequeue:knowledge-1", "enqueue", "delete:old/file.md"}, h.events,
+ "queued parse tasks are dropped before reparse; the old file is deleted only after enqueue")
}
func TestReplaceKnowledgeFileUnchangedContentSkipsReparse(t *testing.T) {
@@ -280,16 +300,19 @@ func TestReplaceKnowledgeFileSourceUpdateFailureDiscardsNewFile(t *testing.T) {
assert.Empty(t, h.tasks.payloads)
}
-func TestReplaceKnowledgeFileCommittedUpdateReportedAsFailedKeepsNewFile(t *testing.T) {
+func TestReplaceKnowledgeFileCommittedUpdateReportedAsFailedContinuesReparse(t *testing.T) {
h := newReplaceFileHarness(t)
h.repo.failColumnsCall = 1
h.repo.commitThenFail = true
- _, err := h.replace(t, "# new body", "notes/a.md", nil)
+ got, err := h.replace(t, "# new body", "notes/a.md", nil)
- require.Error(t, err)
+ require.NoError(t, err)
+ require.Equal(t, h.original.ID, got.ID)
assert.Equal(t, "new/file.md", h.repo.row.FilePath)
- assert.Empty(t, h.store.deleted, "a file the row references must not be deleted")
+ assert.Equal(t, types.ParseStatusPending, h.repo.row.ParseStatus)
+ assert.Equal(t, []string{"old/file.md"}, h.store.deleted)
+ require.Len(t, h.tasks.payloads, 1)
}
func TestReplaceKnowledgeFileReparseFailureRestoresPreviousSource(t *testing.T) {
@@ -343,3 +366,81 @@ func TestReplaceKnowledgeFileRejectsUnsupportedFileType(t *testing.T) {
assert.Zero(t, h.store.saved)
assert.Equal(t, h.original, h.repo.row)
}
+
+func TestReplaceKnowledgeFileEmptyCustomNameKeepsFolder(t *testing.T) {
+ h := newReplaceFileHarness(t)
+
+ _, err := h.replaceNamed(t, "# new body", "a.md", "", nil)
+
+ require.NoError(t, err)
+ assert.Equal(t, "notes", h.repo.row.FolderPath)
+ assert.Equal(t, "a.md", h.repo.row.FileName)
+}
+
+func TestReplaceKnowledgeFileBareCustomNameKeepsFolder(t *testing.T) {
+ h := newReplaceFileHarness(t)
+
+ _, err := h.replace(t, "# new body", "b.md", nil)
+
+ require.NoError(t, err)
+ assert.Equal(t, "notes", h.repo.row.FolderPath, "a basename must not move the document to the KB root")
+ assert.Equal(t, "b.md", h.repo.row.FileName)
+}
+
+func TestReplaceKnowledgeFileIgnoresStorageQuota(t *testing.T) {
+ h := newReplaceFileHarness(t)
+ h.ctx = context.WithValue(h.ctx, types.TenantInfoContextKey, &types.Tenant{
+ ID: 7, StorageQuota: 1, StorageUsed: 1,
+ })
+
+ got, err := h.replace(t, "# new body", "notes/a.md", nil)
+
+ require.NoError(t, err)
+ require.Equal(t, h.original.ID, got.ID)
+ assert.Equal(t, types.ParseStatusPending, h.repo.row.ParseStatus)
+}
+
+func TestReplaceKnowledgeFileDequeuesInProgressParse(t *testing.T) {
+ h := newReplaceFileHarness(t)
+ h.repo.row.ParseStatus = types.ParseStatusProcessing
+
+ got, err := h.replace(t, "# new body", "notes/a.md", nil)
+
+ require.NoError(t, err)
+ require.Equal(t, h.original.ID, got.ID)
+ assert.Contains(t, h.events, "dequeue:knowledge-1")
+ assert.Equal(t, types.ParseStatusPending, h.repo.row.ParseStatus)
+ assert.Equal(t, "disabled", h.repo.row.EnableStatus)
+}
+
+func TestReplaceKnowledgeFileRejectsFAQKnowledgeBase(t *testing.T) {
+ h := newReplaceFileHarness(t)
+ h.svc.kbService = &reparseFailureKBService{kb: &types.KnowledgeBase{
+ ID: "kb-1", TenantID: 7, Type: types.KnowledgeBaseTypeFAQ,
+ }}
+
+ _, err := h.replace(t, "# new body", "notes/a.md", nil)
+
+ require.Error(t, err)
+ assert.Zero(t, h.store.saved)
+}
+
+func TestIsKnowledgeSourceReplaced(t *testing.T) {
+ h := newReplaceFileHarness(t)
+ loaded := h.original
+ assert.False(t, h.svc.isKnowledgeSourceReplaced(h.ctx, &loaded))
+
+ h.repo.row.FilePath = "new/file.md"
+ assert.True(t, h.svc.isKnowledgeSourceReplaced(h.ctx, &loaded))
+}
+
+func TestUpdateKnowledgeUnlessSourceReplacedSkipsStaleSave(t *testing.T) {
+ h := newReplaceFileHarness(t)
+ stale := h.original
+ stale.ParseStatus = types.ParseStatusFailed
+ h.repo.row.FilePath = "new/file.md"
+
+ require.NoError(t, h.svc.updateKnowledgeUnlessSourceReplaced(h.ctx, &stale))
+ assert.Equal(t, "new/file.md", h.repo.row.FilePath)
+ assert.NotEqual(t, types.ParseStatusFailed, h.repo.row.ParseStatus)
+}
diff --git a/internal/types/interfaces/knowledge.go b/internal/types/interfaces/knowledge.go
index 0ed7b91a4..27c01a3ae 100644
--- a/internal/types/interfaces/knowledge.go
+++ b/internal/types/interfaces/knowledge.go
@@ -130,8 +130,9 @@ type KnowledgeService interface {
) (*types.Knowledge, error)
// ReplaceKnowledgeFile replaces the source file of an existing file knowledge
// while preserving its ID, then re-parses it. A path-qualified customFileName
- // also sets the folder; metadata entries are merged into the stored metadata.
- // Identical content returns a DuplicateKnowledgeError without re-parsing.
+ // also sets the folder; a bare filename keeps the current folder. Metadata
+ // entries are merged into the stored metadata. Identical content on this
+ // same path returns a DuplicateKnowledgeError without re-parsing.
ReplaceKnowledgeFile(
ctx context.Context,
knowledgeID string,