deeptutor-knowledge 1.7.0__py3-none-any.whl

deeptutor/services/web_source/sync.py

@@ -0,0 +1,253 @@
+"""Sync logic: crawl a doc site and ingest pages into a KB.
+
+``sync_source()`` mirrors the GitHub-source sync flow:
+1. Crawl the site from the configured base URL.
+2. Compare page hashes with those stored in metadata.
+3. Write new/changed pages to the KB ``raw/`` directory as ``.md`` files.
+4. Remove pages that were present before but are no longer on the site.
+5. Feed changed files through ``add_documents()`` for indexing.
+6. Persist updated page hashes + sync status to ``metadata.json``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import logging
+from pathlib import Path
+from typing import Any
+
+from deeptutor.knowledge.add_documents import DEFAULT_BASE_DIR
+from deeptutor.services.web_source.crawler import _contained_path, crawl_and_diff
+
+logger = logging.getLogger(__name__)
+
+WEB_SYNC_INTERVAL_HOURS = 24
+
+
+@dataclass
+class WebSyncResult:
+    """Outcome of a single ``sync_source()`` invocation."""
+
+    ok: bool
+    pages_added: int = 0
+    pages_updated: int = 0
+    pages_removed: int = 0
+    pages_unchanged: int = 0
+    error: str = ""
+    bilingual_pairs_count: int = 0
+
+    @property
+    def total_changes(self) -> int:
+        return self.pages_added + self.pages_updated + self.pages_removed
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _url_to_filename(url: str, base_path_prefix: str) -> str:
+    """Stable ``.md`` filename derived from a page URL."""
+    from deeptutor.services.web_source.crawler import _to_filename
+
+    return _to_filename(url, base_path_prefix)
+
+
+def _record_sync_failure(
+    kb_name: str,
+    source_id: str,
+    base_dir: str,
+    error: str,
+) -> None:
+    """Persist a visible error without advancing hashes past failed indexing."""
+    from deeptutor.knowledge.manager import KnowledgeBaseManager
+
+    try:
+        KnowledgeBaseManager(base_dir=base_dir).update_web_source_state(
+            kb_name=kb_name,
+            source_id=source_id,
+            last_synced_at=_utcnow_iso(),
+            last_sync_status="error",
+            last_sync_error=error,
+        )
+    except Exception:
+        logger.exception("Failed to persist web-source sync failure state")
+
+
+async def _rebuild_index_after_removal(
+    kb_name: str,
+    raw_dir: Path,
+    base_dir: str,
+) -> int:
+    """Rebuild the bound provider so removed pages cannot remain retrievable."""
+    from deeptutor.services.rag.service import RAGService
+    from deeptutor.utils.file_types import FileTypeRouter
+
+    files = FileTypeRouter.collect_supported_files(raw_dir, recursive=True)
+    if not files:
+        raise RuntimeError("No source files remain after removing deleted web pages")
+    success = await RAGService(kb_base_dir=base_dir).initialize(
+        kb_name=kb_name,
+        file_paths=[str(path) for path in files],
+    )
+    if not success:
+        raise RuntimeError("The knowledge-base index rebuild produced no documents")
+    return len(files)
+
+
+async def sync_source(
+    kb_name: str,
+    source: dict[str, Any],
+    *,
+    base_dir: str = DEFAULT_BASE_DIR,
+    max_depth: int | None = None,
+    max_pages: int | None = None,
+) -> WebSyncResult:
+    """Crawl and sync one web source into the named KB (legacy per-file path).
+
+    Uses :func:`crawl_and_diff` for the shared crawl-write-diff pipeline,
+    then indexes changed files individually via ``add_documents``.
+
+    This is the bounded, on-demand sync path used by the API and CLI.
+    """
+    kb_dir = Path(base_dir) / kb_name
+    raw_dir = kb_dir / "raw"
+    raw_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        diff = await crawl_and_diff(
+            source,
+            raw_dir,
+            max_depth=max_depth,
+            max_pages=max_pages,
+        )
+    except Exception as exc:
+        logger.exception("Crawl failed for %s", source["url"])
+        error = str(exc)
+        _record_sync_failure(kb_name, source["id"], base_dir, error)
+        return WebSyncResult(ok=False, error=error)
+    if not diff.ok:
+        _record_sync_failure(kb_name, source["id"], base_dir, diff.error)
+        return WebSyncResult(ok=False, error=diff.error)
+
+    # Remove deleted raw pages and their file-hash records first. A full
+    # provider rebuild below is required because most providers do not expose
+    # a reliable per-document vector deletion operation.
+    removed_count = 0
+    removal_errors: list[str] = []
+    for fname in diff.pages_removed:
+        target = _contained_path(raw_dir, fname)
+        if target is None:
+            removal_errors.append(f"{fname}: path escapes the knowledge base")
+            continue
+        try:
+            from deeptutor.knowledge.add_documents import remove_raw_document
+
+            remove_raw_document(kb_dir, target)
+            removed_count += 1
+        except Exception as exc:
+            logger.warning("Failed to remove %s: %s", fname, exc)
+            removal_errors.append(f"{fname}: {exc}")
+
+    if removal_errors:
+        error = "Failed to remove deleted pages: " + "; ".join(removal_errors)
+        _record_sync_failure(kb_name, source["id"], base_dir, error)
+        return WebSyncResult(ok=False, error=error)
+
+    indexed = 0
+    try:
+        if diff.pages_removed:
+            indexed = await _rebuild_index_after_removal(kb_name, raw_dir, base_dir)
+        elif diff.changed_paths:
+            from deeptutor.knowledge.add_documents import add_documents
+
+            indexed = await add_documents(
+                kb_name=kb_name,
+                source_files=diff.changed_paths,
+                base_dir=base_dir,
+                allow_duplicates=False,
+            )
+    except Exception as exc:
+        logger.warning("Indexing failed for web source files: %s", exc)
+        error = f"Indexing failed: {exc}"
+        _record_sync_failure(kb_name, source["id"], base_dir, error)
+        return WebSyncResult(ok=False, error=error)
+
+    # Persist sync state.
+    from deeptutor.knowledge.manager import KnowledgeBaseManager
+
+    manager = KnowledgeBaseManager(base_dir=base_dir)
+    manager.update_web_source_state(
+        kb_name=kb_name,
+        source_id=source["id"],
+        page_hashes=diff.page_hashes,
+        page_count=diff.page_count,
+        last_synced_at=_utcnow_iso(),
+        last_sync_status="success",
+        last_sync_error=None,
+        navigation=diff.navigation,
+        bilingual_pairings=diff.pairings,
+    )
+
+    try:
+        from deeptutor.multi_user.context import get_current_user
+        from deeptutor.services.web_source.scheduler import get_web_source_sync_scheduler
+
+        user = get_current_user()
+        scheduler = get_web_source_sync_scheduler()
+        scheduler.repo.record_pairings(
+            owner_id=user.id,
+            kb_name=kb_name,
+            source_id=source["id"],
+            pairings=diff.pairings,
+        )
+    except Exception:
+        logger.debug("Failed to record pairings in SQLite repo", exc_info=True)
+
+    logger.info(
+        "Web sync %s: +%d ~%d -%d (%d unchanged), %d indexed, %d bilingual pairs",
+        diff.url,
+        len(diff.pages_added),
+        len(diff.pages_updated),
+        removed_count,
+        len(diff.pages_unchanged),
+        indexed,
+        len(diff.pairings),
+    )
+
+    return WebSyncResult(
+        ok=True,
+        pages_added=len(diff.pages_added),
+        pages_updated=len(diff.pages_updated),
+        pages_removed=removed_count,
+        pages_unchanged=len(diff.pages_unchanged),
+        bilingual_pairs_count=len(diff.pairings),
+    )
+
+
+# Navigation helpers live in navigation.py now.
+# These aliases keep backward compatibility for existing imports/tests.
+from deeptutor.services.web_source.navigation import (  # noqa: F401, E402
+    build_navigation_manifest as _build_navigation_manifest_impl,
+)
+from deeptutor.services.web_source.navigation import (
+    flat_to_tree as _flat_to_tree_impl,
+)
+
+
+def _build_navigation_manifest(
+    nav_links: list[dict],
+    nav_kind: str,
+    page_urls: dict[str, str],
+    base_path_prefix: str = "",
+) -> dict:
+    """Backward-compatible wrapper around navigation.build_navigation_manifest."""
+    return _build_navigation_manifest_impl(nav_links, nav_kind, page_urls)
+
+
+def _flat_to_tree(
+    links: list[dict],
+    url_to_file: dict[str, str],
+) -> list[dict]:
+    """Backward-compatible alias for navigation.flat_to_tree."""
+    return _flat_to_tree_impl(links, url_to_file)

deeptutor/services/workspace/kb_move.py

@@ -0,0 +1,446 @@
+"""Move one owned knowledge base between account-local storage roots.
+
+The index and raw documents are copied as a unit. The source remains intact
+until the destination, catalog entries, and redirects have been published.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+from typing import Any, cast
+import uuid
+
+from deeptutor.knowledge.kb_types import MARGINNOTE4_KB_TYPE, is_connected_kb
+from deeptutor.multi_user.context import get_current_user
+from deeptutor.services.file_io import atomic_write_json
+from deeptutor.services.path_service import get_path_service
+from deeptutor.services.rag.factory import has_ready_provider_index
+from deeptutor.services.workspace.activity import data_activity
+from deeptutor.services.workspace.context import workspace_context
+from deeptutor.services.workspace.data_migration import (
+    _files,
+    _snapshot,
+    assert_no_pending_recovery,
+)
+from deeptutor.services.workspace.knowledge import (
+    _move_aliases_path,
+    canonical_kb_id,
+    move_aliases,
+    parse_kb_id,
+    qualified_kb_id,
+    resolve_qualified,
+)
+from deeptutor.services.workspace.models import WorkspaceError
+
+
+def _config(root: Path) -> dict:
+    path = root / "kb_config.json"
+    if path.is_symlink():
+        raise WorkspaceError("Knowledge configuration cannot be a symbolic link.")
+    if not path.exists():
+        return {"knowledge_bases": {}}
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict) or not isinstance(value.get("knowledge_bases"), dict):
+        raise WorkspaceError("Knowledge configuration is damaged.")
+    return value
+
+
+def _root(workspace_id: str) -> tuple[Path, bool]:
+    with workspace_context(workspace_id) as scope:
+        return get_path_service().get_knowledge_bases_root(), scope.archived
+
+
+def _shared_grants(name: str) -> list[str]:
+    from deeptutor.services.auth import AUTH_ENABLED
+
+    if not AUTH_ENABLED or not get_current_user().is_admin:
+        return []
+    from deeptutor.multi_user.grants import load_grant
+    from deeptutor.multi_user.identity import list_user_info
+
+    return [
+        user["id"]
+        for user in list_user_info()
+        if user.get("role") != "admin"
+        and any(
+            str(item.get("name") or item.get("kb_name") or "") == name
+            or str(item.get("resource_id") or item.get("id") or "") == f"admin:kb:{name}"
+            for item in load_grant(user["id"]).get("knowledge_bases", []) or []
+        )
+    ]
+
+
+def _legacy_account_id(name: str) -> str:
+    # Historical general-chat selections used a role-specific prefix. Keep
+    # that alias only for the owning account; custom workspaces can have
+    # same-name KBs, so their legacy IDs cannot be redirected globally.
+    role = "admin" if get_current_user().is_admin else "user"
+    return f"{role}:kb:{name}"
+
+
+def preview_kb_move(source_id: str, target_workspace_id: str) -> dict:
+    """Return a collision and assignment preview without changing either store."""
+    from deeptutor.services.workspace import get_content_workspace_service
+
+    source_id = canonical_kb_id(str(source_id or ""))
+    parsed = parse_kb_id(source_id)
+    if parsed is None or not parsed[1]:
+        raise WorkspaceError("Choose a knowledge base from the library.")
+    source_workspace_id, name = parsed
+    target_workspace_id = str(target_workspace_id or "")
+    # Move is a library operation. Chat selection is a read ceiling for turns,
+    # not an ownership check for managing a different stored KB.
+    resolve_qualified(source_id, require_write=True)
+    source_root, source_archived = _root(source_workspace_id)
+    target_root, target_archived = _root(target_workspace_id)
+    source_config = _config(source_root)
+    target_config = _config(target_root)
+    entry = source_config["knowledge_bases"].get(name)
+    source_dir = source_root / name
+    target_dir = target_root / name
+    blockers: list[str] = []
+    if source_workspace_id == target_workspace_id or source_root == target_root:
+        blockers.append("Choose a different storage workspace.")
+    if source_archived or target_archived:
+        blockers.append("Restore the workspace before moving its knowledge base.")
+    if not isinstance(entry, dict):
+        blockers.append("The source knowledge base is missing from its configuration.")
+    elif entry.get("type") == MARGINNOTE4_KB_TYPE:
+        blockers.append(
+            "MarginNote 4 stores its synced database outside the knowledge-base folder. "
+            "Move is unavailable until that database can be transferred safely."
+        )
+    elif not is_connected_kb(entry):
+        if entry.get("path", name) != name:
+            blockers.append(
+                "This knowledge base has a nonstandard storage path and cannot be moved safely."
+            )
+        if not source_dir.is_dir() or source_dir.is_symlink():
+            blockers.append("The source knowledge base directory is unavailable.")
+        if str(entry.get("status") or "ready") not in {"ready", "error", "needs_reindex"}:
+            blockers.append("Wait for this knowledge base to finish processing before moving it.")
+    if name in target_config["knowledge_bases"] or target_dir.exists() or target_dir.is_symlink():
+        blockers.append(f"Destination already contains a knowledge base named '{name}'.")
+    target_id = qualified_kb_id(name, target_workspace_id)
+    if target_id in move_aliases():
+        blockers.append("Destination ID is reserved by an earlier knowledge-base move.")
+    if not source_workspace_id and _shared_grants(name):
+        blockers.append(
+            "This knowledge base is shared with other accounts. Remove those grants before moving it."
+        )
+    if source_dir.is_dir() and not source_dir.is_symlink():
+        try:
+            files = list(_files(source_dir))
+            file_count = len(files)
+            byte_count = sum(path.stat().st_size for path in files)
+        except (OSError, WorkspaceError) as exc:
+            blockers.append(str(exc))
+            file_count = byte_count = 0
+    else:
+        file_count = byte_count = 0
+    aliases = move_aliases()
+    old_ids = {source_id, *(key for key in aliases if canonical_kb_id(key) == source_id)}
+    if not source_workspace_id:
+        old_ids.add(_legacy_account_id(name))
+    assignments = [
+        {"workspace_id": row["workspace_id"], "display_name": row["display_name"]}
+        for row in get_content_workspace_service()._catalog()
+        if any(ref in old_ids for ref in (row.get("resources") or {}).get("knowledge_bases") or [])
+    ]
+    return {
+        "source_id": source_id,
+        "target_id": target_id,
+        "source_workspace_id": source_workspace_id,
+        "target_workspace_id": target_workspace_id,
+        "name": name,
+        "files": file_count,
+        "bytes": byte_count,
+        "assignments": assignments,
+        "blockers": blockers,
+    }
+
+
+def _rewrite_assignments(old_ids: set[str], target_id: str) -> None:
+    from deeptutor.services.workspace import get_content_workspace_service
+
+    service = get_content_workspace_service()
+    owner = get_current_user().scope.user_id
+    with service._catalog_connection() as conn:
+        conn.execute("BEGIN IMMEDIATE")
+        for workspace_id, payload in conn.execute("SELECT id,payload FROM workspaces"):
+            row = json.loads(payload)
+            if row.get("owner_id") != owner:
+                continue
+            resources = row.get("resources") or {}
+            selected = resources.get("knowledge_bases")
+            if not isinstance(selected, list) or not any(ref in old_ids for ref in selected):
+                continue
+            resources["knowledge_bases"] = list(
+                dict.fromkeys(target_id if ref in old_ids else ref for ref in selected)
+            )
+            row["resources"] = resources
+            conn.execute(
+                "UPDATE workspaces SET payload = ? WHERE id = ?",
+                (json.dumps(row, ensure_ascii=False), workspace_id),
+            )
+
+
+def _restore_assignments(previous: dict[str, dict]) -> None:
+    from deeptutor.services.workspace import get_content_workspace_service
+
+    service = get_content_workspace_service()
+    owner = get_current_user().scope.user_id
+    with service._catalog_connection() as conn:
+        conn.execute("BEGIN IMMEDIATE")
+        for workspace_id, resources in previous.items():
+            record = conn.execute(
+                "SELECT payload FROM workspaces WHERE id = ?", (workspace_id,)
+            ).fetchone()
+            if record is None:
+                continue
+            row = json.loads(record[0])
+            if row.get("owner_id") != owner:
+                continue
+            row["resources"] = resources
+            conn.execute(
+                "UPDATE workspaces SET payload = ? WHERE id = ?",
+                (json.dumps(row, ensure_ascii=False), workspace_id),
+            )
+
+
+def _copy_kb(source: Path, destination: Path) -> None:
+    destination.mkdir(parents=True)
+    # _snapshot verifies every byte and backs up SQLite with WAL state.
+    _snapshot(source, destination)
+    for directory, dirs, _ in os.walk(source, followlinks=False):
+        for name in dirs:
+            candidate = Path(directory) / name
+            if candidate.is_symlink():
+                raise WorkspaceError("Knowledge base contains a symbolic link.")
+            (destination / candidate.relative_to(source)).mkdir(parents=True, exist_ok=True)
+
+
+def _parse_cache_root(workspace_id: str) -> Path:
+    with workspace_context(workspace_id):
+        return get_path_service().get_parse_cache_root()
+
+
+def _rebase_llamaindex_paths(
+    stage: Path, source: Path, target: Path, source_cache_root: Path
+) -> None:
+    """Rebase persisted citations and keep indexed parse-cache images with the KB.
+
+    FAISS vector files are binary and contain no paths. LlamaIndex stores node
+    paths in docstore JSON and, for older simple indexes, vector-store JSON.
+    BM25 sidecars can contain serialized nodes, so discard them; retrieval
+    rebuilds BM25 from the corrected docstore when needed.
+    """
+    copied_images: dict[str, str] = {}
+    source_prefix = str(source) + os.sep
+    cache_root = source_cache_root.resolve()
+
+    def rewrite_path(value: str, key: str) -> str:
+        if value.startswith(source_prefix):
+            relative = Path(value).relative_to(source)
+            if not (stage / relative).is_file():
+                raise WorkspaceError(f"Indexed source is missing: {relative}")
+            return str(target / relative)
+        if key != "image_path" or not Path(value).is_absolute():
+            return value
+        if value in copied_images:
+            return copied_images[value]
+        image = Path(value)
+        try:
+            resolved = image.resolve(strict=True)
+            relative = resolved.relative_to(cache_root)
+        except (OSError, ValueError) as exc:
+            raise WorkspaceError(
+                "An indexed image is outside the movable knowledge base and parse cache."
+            ) from exc
+        path_parts = [image, *list(image.parents)[: len(image.parts) - len(cache_root.parts)]]
+        if (
+            resolved != image
+            or not image.is_file()
+            or any(part.is_symlink() for part in path_parts)
+        ):
+            raise WorkspaceError("An indexed image cannot be copied safely.")
+        digest = hashlib.sha256(value.encode("utf-8")).hexdigest()
+        asset = Path(".index_assets") / digest / image.name
+        _snapshot(image, stage / asset.parent)
+        copied_images[value] = str(target / asset)
+        return copied_images[value]
+
+    def rewrite(value: object, key: str = "") -> tuple[object, bool]:
+        if isinstance(value, dict):
+            changed = False
+            result = {}
+            for child_key, child_value in value.items():
+                result[child_key], child_changed = rewrite(child_value, child_key)
+                changed |= child_changed
+            return result, changed
+        if isinstance(value, list):
+            children = [rewrite(child) for child in value]
+            return [child for child, _ in children], any(changed for _, changed in children)
+        if isinstance(value, str):
+            if value.startswith(source_prefix) or key == "image_path":
+                updated = rewrite_path(value, key)
+                return updated, updated != value
+            # Some LlamaIndex stores embed node objects as serialized JSON.
+            if key == "__data__" and value.startswith("{") and source_prefix in value:
+                parsed = json.loads(value)
+                rebased_data, changed = rewrite(parsed)
+                if changed:
+                    return json.dumps(rebased_data, ensure_ascii=False), True
+        return value, False
+
+    for docstore in list(stage.rglob("docstore.json")):
+        relative = docstore.relative_to(stage)
+        if relative.parts[0] != "llamaindex_storage" and not (
+            relative.parts[0].startswith("version-") or relative.parts[0] == "index_versions"
+        ):
+            continue
+        storage = docstore.parent
+        if not (storage / "index_store.json").is_file():
+            continue
+        for path in (docstore, *storage.glob("*vector_store.json")):
+            # The FAISS store keeps binary bytes under a .json filename.
+            if path != docstore:
+                with path.open("rb") as handle:
+                    if handle.read(1) != b"{":
+                        continue
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+                updated, changed = rewrite(payload)
+            except (ValueError, UnicodeError) as exc:
+                raise WorkspaceError(f"Cannot rebase LlamaIndex paths in {path.name}.") from exc
+            if changed:
+                atomic_write_json(path, cast(dict[str, Any], updated))
+        shutil.rmtree(storage / "bm25_retriever", ignore_errors=True)
+
+
+def move_kb(source_id: str, target_workspace_id: str) -> dict:
+    """Publish one verified KB copy and preserve qualified saved references."""
+    with data_activity(exclusive=True):
+        assert_no_pending_recovery(reject_unreadable=True)
+        plan = preview_kb_move(source_id, target_workspace_id)
+        if plan["blockers"]:
+            raise WorkspaceError(" ".join(plan["blockers"]))
+        name = plan["name"]
+        source_root, _ = _root(plan["source_workspace_id"])
+        target_root, _ = _root(plan["target_workspace_id"])
+        source_path = source_root / name
+        target_path = target_root / name
+        source_before = _config(source_root)
+        target_before = _config(target_root)
+        aliases_before = move_aliases()
+        aliases_path = _move_aliases_path()
+        aliases_existed = aliases_path.exists()
+        source_config_path = source_root / "kb_config.json"
+        target_config_path = target_root / "kb_config.json"
+        source_config_existed = source_config_path.exists()
+        target_config_existed = target_config_path.exists()
+        old_ids = {
+            plan["source_id"],
+            *(key for key in aliases_before if canonical_kb_id(key) == plan["source_id"]),
+        }
+        if not plan["source_workspace_id"]:
+            old_ids.add(_legacy_account_id(name))
+        stage = target_root / f".kb-move-{uuid.uuid4().hex}"
+        published = False
+        source_hidden = None
+        from deeptutor.services.workspace import get_content_workspace_service
+
+        catalog = get_content_workspace_service()
+        assignment_before = {
+            row["workspace_id"]: deepcopy(row.get("resources") or {})
+            for row in catalog._catalog()
+            if any(
+                ref in old_ids for ref in (row.get("resources") or {}).get("knowledge_bases") or []
+            )
+        }
+        try:
+            if source_path.is_dir():
+                _copy_kb(source_path, stage)
+                entry = source_before["knowledge_bases"][name]
+                provider = entry.get("rag_provider")
+                if provider in {None, "", "llamaindex"}:
+                    _rebase_llamaindex_paths(
+                        stage,
+                        source_path,
+                        target_path,
+                        _parse_cache_root(plan["source_workspace_id"]),
+                    )
+                if (
+                    not is_connected_kb(entry)
+                    and has_ready_provider_index(source_path, provider)
+                    and not has_ready_provider_index(stage, provider)
+                ):
+                    raise WorkspaceError(
+                        "The copied index did not pass its provider readiness check."
+                    )
+                if target_path.exists():
+                    raise WorkspaceError(
+                        f"Destination already contains a knowledge base named '{name}'."
+                    )
+                stage.rename(target_path)
+                published = True
+            target_next = deepcopy(target_before)
+            target_next["knowledge_bases"][name] = deepcopy(source_before["knowledge_bases"][name])
+            source_next = deepcopy(source_before)
+            del source_next["knowledge_bases"][name]
+            source_defaults = source_next.get("defaults") or {}
+            if source_defaults.get("default_kb") == name:
+                source_defaults["default_kb"] = None
+                source_next["defaults"] = source_defaults
+                target_defaults = target_next.setdefault("defaults", {})
+                if not target_defaults.get("default_kb"):
+                    target_defaults["default_kb"] = name
+            atomic_write_json(target_config_path, target_next)
+            _rewrite_assignments(old_ids, plan["target_id"])
+            aliases_next = {
+                key: (plan["target_id"] if value in old_ids else value)
+                for key, value in aliases_before.items()
+            }
+            aliases_next[plan["source_id"]] = plan["target_id"]
+            if not plan["source_workspace_id"]:
+                aliases_next[_legacy_account_id(name)] = plan["target_id"]
+            atomic_write_json(aliases_path, aliases_next)
+            atomic_write_json(source_config_path, source_next)
+            if source_path.is_dir():
+                source_hidden = source_root / f".kb-moved-{uuid.uuid4().hex}"
+                source_path.rename(source_hidden)
+        except BaseException:
+            if source_hidden is not None and source_hidden.exists():
+                source_hidden.rename(source_path)
+            if source_config_existed:
+                atomic_write_json(source_config_path, source_before)
+            else:
+                source_config_path.unlink(missing_ok=True)
+            if target_config_existed:
+                atomic_write_json(target_config_path, target_before)
+            else:
+                target_config_path.unlink(missing_ok=True)
+            _restore_assignments(assignment_before)
+            if aliases_existed:
+                atomic_write_json(aliases_path, aliases_before)
+            else:
+                aliases_path.unlink(missing_ok=True)
+            if published:
+                shutil.rmtree(target_path)
+            if stage.exists():
+                shutil.rmtree(stage)
+            raise
+        if source_hidden is not None:
+            try:
+                shutil.rmtree(source_hidden)
+            except OSError:
+                # The hidden original remains available for manual recovery;
+                # it does not appear as an active knowledge base.
+                plan["cleanup_path"] = str(source_hidden)
+        plan["status"] = "moved"
+        return plan