Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Bound RAG scope retirement by folder identity, not by the clock (#10561)

Daniel Han13622ed01ff1
diff --git a/studio/backend/core/rag/folder_sync.py b/studio/backend/core/rag/folder_sync.py
index 13229b81dae..7d9cbdba972 100644
--- a/studio/backend/core/rag/folder_sync.py
+++ b/studio/backend/core/rag/folder_sync.py
@@ -72,11 +72,6 @@ def _now() -> str:
return datetime.now(timezone.utc).isoformat()
-def now_iso() -> str:
- """The timestamp format linked-folder rows are written and compared with."""
- return _now()
-
-
def _hash_file(path: str) -> str:
digest = hashlib.sha256()
with open(path, "rb") as source:
@@ -564,42 +559,82 @@ def _metadata_table_exists(conn, table: str) -> bool:
)
+# SQLite's default host-parameter cap is 999, so a bound id list is applied in chunks.
+_ID_CHUNK = 500
+
+
+def _id_chunks(folder_ids: list[str]) -> list[list[str]]:
+ unique = list(dict.fromkeys(folder_ids))
+ return [unique[start : start + _ID_CHUNK] for start in range(0, len(unique), _ID_CHUNK)]
+
+
+def linked_folder_ids(scope: str) -> list[str]:
+ """The folders a scope owns right now, for bounding a later retirement to them.
+
+ Metadata connection, like retirement itself: the delete path has to finish even when the
+ vector extension cannot load.
+ """
+ with closing(rag_db.get_metadata_connection()) as conn:
+ if not _metadata_table_exists(conn, "linked_folders"):
+ return []
+ return [
+ row["id"]
+ for row in conn.execute("SELECT id FROM linked_folders WHERE scope=?", (scope,))
+ ]
+
+
def _retire_scope_rows(
conn,
scope: str,
- linked_before: str | None = None,
+ folder_ids: list[str] | None = None,
+ rows: bool = True,
) -> None:
- folders_exist = _metadata_table_exists(conn, "linked_folders")
+ folders_exist = rows and _metadata_table_exists(conn, "linked_folders")
jobs_exist = folders_exist and _metadata_table_exists(conn, "linked_folder_sync_jobs")
conn.execute(
"INSERT OR IGNORE INTO linked_folder_retired_scopes(scope, retired_at) VALUES(?, ?)",
(scope, _now()),
)
- # the ownership check and this write cannot share a transaction across two databases
- bound = "" if linked_before is None else " AND created_at<=?"
- params = () if linked_before is None else (linked_before,)
- if folders_exist:
- conn.execute(
- "UPDATE linked_folders SET auto_sync=0, status='retired', "
- f"last_error='Owning scope was removed', updated_at=? WHERE scope=?{bound}",
- (_now(), scope, *params),
- )
- if jobs_exist:
- conn.execute(
- "UPDATE linked_folder_sync_jobs SET status='failed', stage='error', "
- "error='Owning scope was removed', successor_kind=NULL, completed_at=? "
- "WHERE folder_id IN (SELECT id FROM linked_folders WHERE scope=?"
- f"{bound}) AND (status IN ('pending','running') OR successor_kind IS NOT NULL)",
- (_now(), scope, *params),
- )
+ # The ownership check and this write cannot share a transaction across two databases, so the
+ # caller bounds the write to the folders it saw. Identity, not created_at: Windows reads its
+ # clock in ~15.6ms steps, so a folder linked just after the check carries the check's own
+ # timestamp, and retiring it disables RAG for a project recreated with the same id, for good.
+ # None means no bound at all; an empty list means the caller saw no folders.
+ batches = [None] if folder_ids is None else _id_chunks(folder_ids)
+ for batch in batches:
+ bound = "" if batch is None else f" AND id IN ({','.join('?' * len(batch))})"
+ params = () if batch is None else tuple(batch)
+ if folders_exist:
+ conn.execute(
+ "UPDATE linked_folders SET auto_sync=0, status='retired', "
+ f"last_error='Owning scope was removed', updated_at=? WHERE scope=?{bound}",
+ (_now(), scope, *params),
+ )
+ if jobs_exist:
+ conn.execute(
+ "UPDATE linked_folder_sync_jobs SET status='failed', stage='error', "
+ "error='Owning scope was removed', successor_kind=NULL, completed_at=? "
+ "WHERE folder_id IN (SELECT id FROM linked_folders WHERE scope=?"
+ f"{bound}) AND (status IN ('pending','running') OR successor_kind IS NOT NULL)",
+ (_now(), scope, *params),
+ )
+
+def retire_scope(
+ scope: str,
+ folder_ids: list[str] | None = None,
+ rows: bool = True,
+) -> None:
+ """Stop all future work, even when the vector extension cannot load.
-def retire_scope(scope: str, linked_before: str | None = None) -> None:
- """Stop all future work, even when the vector extension cannot load."""
+ `rows = False` writes only the tombstone: enough on its own to stop new links and uploads,
+ and the only half a caller can take back, since the folder and job updates overwrite state
+ nobody recorded. A caller whose ownership check can still go stale takes it first.
+ """
conn = _retirement_connection()
try:
conn.execute("BEGIN IMMEDIATE")
- _retire_scope_rows(conn, scope, linked_before)
+ _retire_scope_rows(conn, scope, folder_ids, rows)
conn.commit()
except Exception:
conn.rollback()
@@ -741,10 +776,10 @@ def reconcile_retired_scopes(project_exists) -> dict[str, list[str]]:
# rechecked inside the lock create_folder takes: a project recreated with the same id must not have
# its new folders retired
with _scope_lock(scope):
- checked_at = _now()
+ owned = linked_folder_ids(scope)
if project_exists(project_id):
continue
- retire_scope(scope, checked_at)
+ retire_scope(scope, owned)
retired_scopes.add(scope)
retired.append(scope)
except Exception:
diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index 77a7befb2bc..752829b9c3d 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -1143,12 +1143,21 @@ def _delete_project_rag_sources(project_id: str) -> None:
# a project id is reusable, and the tombstone outlives the scope, so retiring one that
# another client already recreated would permanently disable RAG for the new project
with folder_sync.scope_lock(scope):
- checked_at = folder_sync.now_iso()
+ owned = folder_sync.linked_folder_ids(scope)
if get_chat_project(project_id) is not None:
return
- folder_sync.retire_scope(scope, checked_at)
- if rag_db.rag_available():
- folder_sync.delete_retired_scope(scope)
+ # Tombstone first, rows after one more look: the tombstone already stops new links and
+ # uploads and is the only half `unretire_scope` can take back, while a retired row
+ # keeps auto_sync off and makes create_folder refuse that path for good.
+ folder_sync.retire_scope(scope, owned, rows = False)
+ if get_chat_project(project_id) is not None:
+ folder_sync.unretire_scope(scope)
+ return
+ folder_sync.retire_scope(scope, owned)
+ # The purge takes the whole scope, `owned` or not, so bounding retirement buys nothing
+ # unless the purge is skipped too.
+ if rag_db.rag_available():
+ folder_sync.delete_retired_scope(scope)
@router.delete("/projects/{project_id}", response_model = ChatProjectDeleted)
diff --git a/studio/backend/tests/test_rag_linked_folders.py b/studio/backend/tests/test_rag_linked_folders.py
index 7873f827a50..ae11912a57c 100644
--- a/studio/backend/tests/test_rag_linked_folders.py
+++ b/studio/backend/tests/test_rag_linked_folders.py
@@ -2323,6 +2323,46 @@ def test_a_project_recreated_during_delete_keeps_its_rag_scope(rag_home, monkeyp
assert folder_sync.scope_retired(scope) is False
+@requires_sqlite_vec
+def test_the_purge_is_skipped_for_a_project_recreated_after_the_ownership_check(
+ rag_home, monkeypatch
+):
+ """A recreated project must be left exactly as the delete found it, not merely unpurged.
+
+ The reconciler already refuses to purge a scope whose owner exists; this is the same guard
+ on the delete route, which reached the purge unconditionally. Aborting has to put back
+ everything the pass did, which is why only the tombstone is written before this recheck.
+ """
+ from routes import chat_history
+
+ scope = store.project_scope("p1")
+ source = rag_home / "relinked-by-the-new-project"
+ source.mkdir()
+ seen = {"checks": 0}
+
+ def recreated_after_the_check(project_id):
+ # gone for the check that decides to retire, back by the time the purge asks
+ seen["checks"] += 1
+ return None if seen["checks"] == 1 else {"id": project_id}
+
+ folder = folder_sync.create_folder(scope_type = "project", scope_id = "p1", path = str(source))
+ monkeypatch.setattr(chat_history, "get_chat_project", recreated_after_the_check)
+
+ chat_history._delete_project_rag_sources("p1")
+
+ survivor = folder_sync.get_folder(folder["id"])
+ assert survivor is not None
+ # untouched, not just undeleted: a retired row left behind is not an abort
+ assert (survivor["status"], survivor["auto_sync"], survivor["last_error"]) == (
+ folder["status"],
+ folder["auto_sync"],
+ None,
+ )
+ assert seen["checks"] == 2
+ # and the scope is usable again immediately, not once the reconciler next runs
+ assert folder_sync.scope_retired(scope) is False
+
+
@requires_sqlite_vec
def test_reconciliation_restores_a_scope_whose_project_came_back(rag_home):
scope = store.project_scope("p1")
@@ -2374,16 +2414,99 @@ def test_retirement_leaves_a_folder_linked_after_the_ownership_check(rag_home):
source = rag_home / "before-check"
source.mkdir()
existing = folder_sync.create_folder(scope_type = "project", scope_id = "p1", path = str(source))
- checked_at = folder_sync.now_iso()
+ owned = folder_sync.linked_folder_ids(scope)
# a second backend process links this one after the check and before the write
later = rag_home / "after-check"
later.mkdir()
fresh = folder_sync.create_folder(scope_type = "project", scope_id = "p1", path = str(later))
- folder_sync.retire_scope(scope, checked_at)
+ folder_sync.retire_scope(scope, owned)
assert folder_sync.get_folder(existing["id"])["status"] == "retired"
survivor = folder_sync.get_folder(fresh["id"])
assert survivor["status"] == fresh["status"]
assert survivor["auto_sync"] == fresh["auto_sync"]
assert survivor["last_error"] is None
+
+
+@requires_sqlite_vec
+def test_the_ownership_bound_survives_a_clock_that_cannot_separate_the_two(rag_home, monkeypatch):
+ """Windows reads its clock in ~15.6ms steps, so both links can share one timestamp.
+
+ Freezing `_now` is that quantisation at its limit: any clock-derived bound has to guess,
+ and guessing wrong retires the folders of a project recreated with the same id, for good.
+ """
+ scope = store.project_scope("p1")
+ monkeypatch.setattr(folder_sync, "_now", lambda: "2026-01-01T00:00:00+00:00")
+ for name in ("before-check", "after-check"):
+ (rag_home / name).mkdir()
+ existing = folder_sync.create_folder(
+ scope_type = "project", scope_id = "p1", path = str(rag_home / "before-check")
+ )
+ owned = folder_sync.linked_folder_ids(scope)
+ fresh = folder_sync.create_folder(
+ scope_type = "project", scope_id = "p1", path = str(rag_home / "after-check")
+ )
+ assert existing["created_at"] == fresh["created_at"]
+
+ folder_sync.retire_scope(scope, owned)
+
+ assert folder_sync.get_folder(existing["id"])["status"] == "retired"
+ assert folder_sync.get_folder(fresh["id"])["status"] == fresh["status"]
+
+
+@requires_sqlite_vec
+def test_an_empty_ownership_snapshot_retires_nothing_but_still_tombstones(rag_home):
+ """`None` means no bound; `[]` means the check saw no folders, and is not the same thing."""
+ scope = store.project_scope("p1")
+ (rag_home / "linked-late").mkdir()
+ fresh = folder_sync.create_folder(
+ scope_type = "project", scope_id = "p1", path = str(rag_home / "linked-late")
+ )
+
+ folder_sync.retire_scope(scope, [])
+
+ assert folder_sync.scope_retired(scope) is True
+ assert folder_sync.get_folder(fresh["id"])["status"] == fresh["status"]
+
+
+@requires_sqlite_vec
+def test_the_ownership_bound_is_applied_past_the_sqlite_parameter_cap(rag_home, monkeypatch):
+ """A scope with more folders than SQLite takes host parameters still retires all of them."""
+ scope = store.project_scope("p1")
+ monkeypatch.setattr(folder_sync, "_ID_CHUNK", 3)
+ folders = []
+ for index in range(7):
+ source = rag_home / f"folder-{index}"
+ source.mkdir()
+ folders.append(
+ folder_sync.create_folder(scope_type = "project", scope_id = "p1", path = str(source))
+ )
+ owned = folder_sync.linked_folder_ids(scope)
+ assert len(owned) == len(folders)
+
+ folder_sync.retire_scope(scope, owned)
+
+ assert [folder_sync.get_folder(f["id"])["status"] for f in folders] == ["retired"] * 7
+
+
+@requires_sqlite_vec
+def test_the_ownership_snapshot_survives_an_unloadable_vector_extension(rag_home, monkeypatch):
+ """Retirement already runs without sqlite-vec loaded, so the snapshot must too."""
+ scope = store.project_scope("p1")
+ source = rag_home / "linked"
+ source.mkdir()
+ folder = folder_sync.create_folder(scope_type = "project", scope_id = "p1", path = str(source))
+
+ def unavailable():
+ raise sqlite3.OperationalError("cannot load sqlite-vec")
+
+ # scoped, not monkeypatch.undo(): rag_home patches through the same fixture, so undoing
+ # here would restore the database path before the assertions read it
+ with monkeypatch.context() as no_vec:
+ no_vec.setattr(folder_sync.rag_db, "get_connection", unavailable)
+ owned = folder_sync.linked_folder_ids(scope)
+ folder_sync.retire_scope(scope, owned)
+
+ assert owned == [folder["id"]]
+ assert folder_sync.get_folder(folder["id"])["status"] == "retired"