Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(core): add the install identity migration engine (#571)

Ruben Lütke06b8539ce011
diff --git a/jarvis/core/identity_migration.py b/jarvis/core/identity_migration.py
new file mode 100644
index 0000000000..551a4c6f96
--- /dev/null
+++ b/jarvis/core/identity_migration.py
@@ -0,0 +1,955 @@
+"""Carry an installation's persistent identity from a legacy name to the current one.
+
+A persistent identifier (``jarvis.core.branding``) names things an existing
+installation already owns: its data directory, its install directory, the
+credential-store service its keys are filed under. Changing such a name is only
+safe together with a migration that keeps every file and every credential
+reachable, under the old name as well as the new one. This module is that
+migration. It is inert on its own: nothing here runs until a caller hands it a
+legacy name and a current name.
+
+The rules it enforces:
+
+* **A legacy directory wins while it still holds the data.** A process that only
+ needs to know where its files live calls :func:`resolve_directory` and never
+ moves anything. Helper processes only ever resolve.
+* **A directory moves by one atomic rename, or not at all.** Nothing is ever
+ copied and deleted, merged or overwritten. When the rename is refused (a file
+ is open, the target is on another volume, access is denied) everything stays
+ where it was, and running from the legacy location is a permanently valid
+ state, not a degraded one.
+* **The legacy path keeps working.** After the rename a link is left at the
+ legacy path (a directory junction on Windows, which needs no privilege; a
+ symlink elsewhere), so code that still spells the old name reads and writes
+ the same files.
+* **One migrator at a time.** The move is serialized by an OS lock on a small
+ journal file that sits *beside* the current directory, so it is outside both
+ directories and unaffected by the rename.
+* **The journal is the memory of a move.** The migrator records which
+ directory it moves, by filesystem identity, and that the rename went through.
+ While that journal exists, a directory at the current path with that identity
+ is proof it came from the legacy path: a crash between the rename and the
+ link is finished on the next start, a fresh install is never mistaken for
+ one, and a directory that something recreates at the legacy path afterwards
+ cannot hide the moved data.
+* **Credentials are copied, never moved.** :func:`migrate_keyring` copies each
+ known entry to the current service unless that already holds a value, leaves
+ every legacy entry in place as the way back, and records a marker so it runs
+ once.
+
+Standard library only and no ``jarvis`` import: the frozen runtime hook has to
+load this file by path before anything from the package exists. For the same
+reason there is no ``from __future__ import annotations``: with string
+annotations ``dataclasses`` looks the module up in ``sys.modules``, where a file
+loaded by path need not be.
+"""
+
+import enum
+import errno
+import json
+import logging
+import os
+import stat
+import sys
+import time
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+log = logging.getLogger(__name__)
+
+PathLike = str | os.PathLike[str]
+
+_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+# IO_REPARSE_TAG_MOUNT_POINT (a junction) and IO_REPARSE_TAG_SYMLINK. Every
+# other reparse tag (cloud-sync placeholder, deduplicated volume) marks an
+# ordinary directory that merely carries a reparse point.
+_LINK_REPARSE_TAGS = frozenset({0xA0000003, 0xA000000C})
+_WINDOWS_PATH_PREFIXES = ("\\\\?\\", "\\??\\")
+# ERROR_NOT_SAME_DEVICE; ERROR_ACCESS_DENIED, ERROR_SHARING_VIOLATION,
+# ERROR_LOCK_VIOLATION.
+_WINERROR_CROSS_DEVICE = 17
+_WINERRORS_IN_USE = frozenset({5, 32, 33})
+
+# Pauses before another try when a step is refused because something else has
+# the directory open. A virus scanner or an indexer looking at files an
+# installer has just written lets go within moments; a real lock outlasts this
+# and the legacy directory simply stays in use.
+TRANSIENT_RETRY_DELAYS: tuple[float, ...] = (0.05, 0.15, 0.3)
+
+_JOURNAL_MAX_BYTES = 65536
+_LOCK_OPEN_ATTEMPTS = 3
+_LOCK_POLL_SECONDS = 0.05
+
+
+# ----------------------------------------------------------------------
+# Directory resolution
+# ----------------------------------------------------------------------
+
+
+class LegacyState(enum.Enum):
+ """What sits at a legacy path, seen from the current path."""
+
+ ABSENT = "absent"
+ REAL_DIRECTORY = "real_directory"
+ LINK_TO_CURRENT = "link_to_current"
+ # A live link to some other directory: the user redirected their data
+ # themselves, so the legacy path is still where it is reached from.
+ FOREIGN_LINK = "foreign_link"
+ DANGLING_LINK = "dangling_link"
+ NOT_A_DIRECTORY = "not_a_directory"
+ # Something is there but cannot be looked at (access denied, I/O error).
+ # It is never taken for absent: starting on an empty directory while the
+ # data sits behind a momentary error would split the installation in two.
+ UNREADABLE = "unreadable"
+
+
+def _strip_windows_prefix(path: str) -> str:
+ if sys.platform == "win32":
+ for prefix in _WINDOWS_PATH_PREFIXES:
+ if path.startswith(prefix):
+ return path[len(prefix) :]
+ return path
+
+
+def _normalized(path: PathLike) -> str:
+ text = _strip_windows_prefix(os.fspath(path))
+ return os.path.normcase(os.path.normpath(os.path.abspath(text)))
+
+
+def _is_link(metadata: os.stat_result) -> bool:
+ if stat.S_ISLNK(metadata.st_mode):
+ return True
+ if not getattr(metadata, "st_file_attributes", 0) & _REPARSE_POINT:
+ return False
+ return getattr(metadata, "st_reparse_tag", 0) in _LINK_REPARSE_TAGS
+
+
+def _exists(path: PathLike) -> bool:
+ """True unless the path is provably free. An unreadable path counts as taken."""
+ try:
+ os.lstat(path)
+ except (FileNotFoundError, NotADirectoryError):
+ # Nothing there, which is what the caller hopes for.
+ return False
+ except OSError as exc:
+ log.warning("Path %s cannot be inspected (%s); treating it as occupied.", path, exc)
+ return True
+
+
+def _link_points_at(link: str, target: str) -> bool:
+ try:
+ raw = _strip_windows_prefix(os.readlink(link))
+ except OSError:
+ # An unreadable link target is not provably ours, so it is not ours.
+ return False
+ if not os.path.isabs(raw):
+ raw = os.path.join(os.path.dirname(os.path.abspath(link)), raw)
+ if _normalized(raw) == _normalized(target):
+ return True
+ try:
+ # Catches a differently spelled route to the same directory (case,
+ # short names, a relative hop) that the text comparison cannot see.
+ return os.path.samefile(link, target)
+ except OSError:
+ # One side is missing; the text comparison above already settled it.
+ return False
+
+
+def inspect_legacy(legacy: PathLike, current: PathLike) -> LegacyState:
+ """Classify ``legacy`` relative to ``current``. Reads only, never raises."""
+ legacy_text = os.fspath(legacy)
+ try:
+ metadata = os.lstat(legacy_text)
+ except (FileNotFoundError, NotADirectoryError):
+ # Nothing there: the ordinary state of a fresh install.
+ return LegacyState.ABSENT
+ except OSError as exc:
+ log.warning("Legacy path %s cannot be inspected (%s).", legacy_text, exc)
+ return LegacyState.UNREADABLE
+ if _is_link(metadata):
+ if _link_points_at(legacy_text, os.fspath(current)):
+ return LegacyState.LINK_TO_CURRENT
+ if os.path.isdir(legacy_text):
+ return LegacyState.FOREIGN_LINK
+ if os.path.exists(legacy_text):
+ return LegacyState.NOT_A_DIRECTORY
+ return LegacyState.DANGLING_LINK
+ if stat.S_ISDIR(metadata.st_mode):
+ return LegacyState.REAL_DIRECTORY
+ return LegacyState.NOT_A_DIRECTORY
+
+
+def default_lock_path(current: PathLike) -> Path:
+ """The journal and lock file for migrations into ``current``.
+
+ A sibling of the current directory: outside the directory that moves and
+ outside the one it becomes, so the rename cannot carry it away, and derived
+ from the current path alone so every process agrees on it.
+ """
+ current_path = Path(os.path.abspath(current))
+ return current_path.with_name(f".{current_path.name.lstrip('.')}.identity-migration")
+
+
+def _parse_journal(raw: bytes, source: PathLike) -> dict[str, object] | None:
+ if not raw.strip():
+ return None
+ try:
+ journal = json.loads(raw.decode("utf-8"))
+ except (UnicodeDecodeError, ValueError) as exc:
+ log.warning("Ignoring an unreadable migration journal at %s (%s).", source, exc)
+ return None
+ return journal if isinstance(journal, dict) else None
+
+
+def _peek_journal(path: PathLike) -> dict[str, object] | None:
+ """Read the journal without the lock, for a process that only resolves."""
+ try:
+ with open(path, "rb") as handle:
+ raw = handle.read(_JOURNAL_MAX_BYTES)
+ except OSError:
+ # No journal, which is the normal case, or a migrator holds it this
+ # instant and Windows keeps other readers out of a locked file.
+ return None
+ return _parse_journal(raw, path)
+
+
+def _names_pair(journal: dict[str, object] | None, legacy: PathLike, current: PathLike) -> bool:
+ if journal is None:
+ return False
+ return _normalized(str(journal.get("legacy", ""))) == _normalized(legacy) and _normalized(
+ str(journal.get("current", ""))
+ ) == _normalized(current)
+
+
+def _proves_move(journal: dict[str, object] | None, legacy: PathLike, current: PathLike) -> bool:
+ """True when the journal shows that ``current`` is the directory moved from ``legacy``.
+
+ Two facts together: the migrator recorded that its rename went through, and
+ the directory now at the current path still has the filesystem identity
+ that was recorded before it. The identity alone is not enough, because a
+ filesystem hands a freed identity to the next directory it creates. A
+ filesystem without stable identities proves nothing, and nothing is then
+ assumed.
+ """
+ if journal is None or not _names_pair(journal, legacy, current):
+ return False
+ if journal.get("renamed") is not True:
+ return False
+ try:
+ metadata = os.lstat(current)
+ except OSError:
+ # No readable directory at the current path, so nothing is proven.
+ return False
+ if not stat.S_ISDIR(metadata.st_mode) or _is_link(metadata):
+ return False
+ inode = journal.get("inode")
+ return bool(inode) and (metadata.st_dev, metadata.st_ino) == (journal.get("device"), inode)
+
+
+def resolve_directory(
+ current: PathLike,
+ legacy_paths: Sequence[PathLike] = (),
+ *,
+ lock_path: PathLike | None = None,
+) -> Path:
+ """Return the directory to use: the first legacy path that still holds the data.
+
+ A legacy path wins while it is a real directory (or the user's own link to
+ one, or something that cannot be inspected). A legacy path that is absent,
+ dangling, or already a link to ``current`` loses, and ``current`` is
+ returned. The one exception is a directory that appeared at the legacy path
+ *after* the data was moved away from it, which the migration journal
+ proves; ``lock_path`` names that journal when the migrator was given one.
+
+ It reads the filesystem and changes nothing, so any process may call it at
+ any time.
+ """
+ for legacy in legacy_paths:
+ state = inspect_legacy(legacy, current)
+ if state in (LegacyState.FOREIGN_LINK, LegacyState.UNREADABLE):
+ return Path(legacy)
+ if state is LegacyState.REAL_DIRECTORY:
+ journal_path = default_lock_path(current) if lock_path is None else lock_path
+ if not _proves_move(_peek_journal(journal_path), legacy, current):
+ return Path(legacy)
+ return Path(current)
+
+
+# ----------------------------------------------------------------------
+# Directory migration
+# ----------------------------------------------------------------------
+
+
+class DirectoryOutcome(enum.Enum):
+ """What :func:`migrate_directory` did. Every value is a valid end state."""
+
+ # No legacy directory: a fresh install, or the two paths are the same.
+ NOTHING_TO_MIGRATE = "nothing_to_migrate"
+ # The legacy path already is a link to the current directory.
+ ALREADY_LINKED = "already_linked"
+ # Renamed, and a link now stands at the legacy path.
+ MIGRATED = "migrated"
+ # Renamed, but no link could be left at the legacy path. The data is at
+ # the current path; the link is attempted again on the next call.
+ MIGRATED_WITHOUT_LINK = "migrated_without_link"
+ # An earlier call renamed and never left the link; this call created it.
+ LINK_RESTORED = "link_restored"
+ # An earlier call renamed, and something has since created a directory with
+ # content at the legacy path. The moved data at the current path stays in
+ # use; the newer directory is left exactly as it is.
+ LEGACY_RECREATED = "legacy_recreated"
+ # Something already exists at the current path. Nothing is merged or
+ # overwritten; the legacy directory stays in use.
+ BOTH_EXIST = "both_exist"
+ # The legacy path is a foreign link, a dangling link or a file.
+ LEGACY_NOT_A_DIRECTORY = "legacy_not_a_directory"
+ # The legacy path cannot be inspected. Nothing moved; it stays in use.
+ LEGACY_UNREADABLE = "legacy_unreadable"
+ # The rename was refused. Nothing moved; the legacy directory stays in use.
+ RENAME_FAILED = "rename_failed"
+ # Another process is migrating right now. This one only resolves, and what
+ # it resolved is a snapshot taken while that migration was under way.
+ LOCK_BUSY = "lock_busy"
+ # The journal file could not be opened, locked, read or written. Nothing
+ # moved.
+ LOCK_UNAVAILABLE = "lock_unavailable"
+
+
+class RenameFailure(enum.Enum):
+ """Why a rename was refused."""
+
+ IN_USE_OR_DENIED = "in_use_or_denied"
+ CROSS_DEVICE = "cross_device"
+ DESTINATION_EXISTS = "destination_exists"
+ OTHER = "other"
+
+
+@dataclass(frozen=True, slots=True)
+class DirectoryMigration:
+ """The full account of one :func:`migrate_directory` call."""
+
+ outcome: DirectoryOutcome
+ legacy: Path
+ current: Path
+ # The directory to use from here on, as resolve_directory() gives it.
+ effective: Path
+ # What stands at the legacy path after the call.
+ legacy_state: LegacyState
+ rename_failure: RenameFailure | None = None
+ # The underlying error text, when there was one.
+ detail: str = ""
+
+
+def create_directory_link(link: PathLike, target: PathLike) -> None:
+ """Make ``link`` an alias of the directory ``target``. Raises ``OSError``.
+
+ Windows gets a directory junction, the one link an unprivileged account may
+ create; it is made in-process, so no console flashes and no path has to
+ survive a command line. Every other OS gets a symlink. Either way the link
+ appears at ``link`` in one step and never replaces anything.
+ """
+ link_text = os.path.abspath(link)
+ target_text = os.path.abspath(target)
+ if os.path.lexists(link_text):
+ raise FileExistsError(errno.EEXIST, "a link cannot replace an existing path", link_text)
+ if sys.platform != "win32":
+ os.symlink(target_text, link_text, target_is_directory=True)
+ return
+ try:
+ import _winapi # noqa: PLC0415 - CPython-internal, Windows-only
+
+ create_junction = _winapi.CreateJunction
+ except (ImportError, AttributeError) as exc:
+ raise OSError(errno.ENOSYS, "this Python cannot create a directory junction") from exc
+ # A junction is a directory first and a link second. Made in place, the
+ # link path would for a moment be an empty real directory, which outranks
+ # the current one. It is built under a staging name and renamed instead.
+ name = os.path.basename(link_text).lstrip(".")
+ staging = os.path.join(os.path.dirname(link_text), f".{name}.identity-link")
+ _remove_staged_link(staging)
+ try:
+ create_junction(target_text, staging)
+ os.rename(staging, link_text)
+ except OSError:
+ _remove_staged_link(staging)
+ raise
+
+
+def _remove_staged_link(staging: str) -> None:
+ """Drop a leftover staging junction. rmdir cannot remove anything that holds data."""
+ try:
+ os.rmdir(staging)
+ except FileNotFoundError:
+ # Nothing was left behind, which is the usual case.
+ return
+ except OSError as exc:
+ log.debug("Staging link %s not removed (%s).", staging, exc)
+
+
+def _try_lock(fd: int) -> bool:
+ try:
+ if sys.platform == "win32":
+ import msvcrt # noqa: PLC0415 - Windows-only
+
+ os.lseek(fd, 0, os.SEEK_SET)
+ msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+ else:
+ import fcntl # noqa: PLC0415 - POSIX-only
+
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ except OSError as exc:
+ contended = isinstance(exc, BlockingIOError | PermissionError)
+ if contended or exc.errno in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+ # Expected contention: another process holds the lock.
+ return False
+ raise
+ return True
+
+
+def _unlock(fd: int) -> None:
+ """Release explicitly on Windows, which may otherwise unlock a while after close."""
+ if sys.platform != "win32":
+ # POSIX: closing the descriptor releases the lock at once.
+ return
+ try:
+ import msvcrt # noqa: PLC0415 - Windows-only
+
+ os.lseek(fd, 0, os.SEEK_SET)
+ msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+ except OSError as exc:
+ log.debug("Explicit unlock of the migration journal failed (%s).", exc)
+
+
+def _unlink(path: str) -> bool:
+ try:
+ os.unlink(path)
+ except FileNotFoundError:
+ # Already gone, which is the state that was asked for.
+ return True
+ except OSError as exc:
+ # Windows refuses to delete a file that is open, ours included. The
+ # caller tries once more after closing it; a file that then stays
+ # belongs to a process that opened it in between.
+ log.debug("Journal %s not removed yet (%s).", path, exc)
+ return False
+ return True
+
+
+def _open_journal(path: str) -> int:
+ flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0)
+ for delay in (*TRANSIENT_RETRY_DELAYS, None):
+ try:
+ return os.open(path, flags, 0o600)
+ except PermissionError:
+ # Windows: a journal that was deleted while a scanner still had it
+ # open lingers, unopenable, until that handle closes. A journal
+ # that does not exist and cannot be created is a real refusal.
+ if delay is None or not os.path.lexists(path):
+ raise
+ time.sleep(delay)
+ raise AssertionError("unreachable: the last attempt returns or raises")
+
+
+class _MigrationLock:
+ """The held OS lock on the journal file, and the journal it guards.
+
+ The lock belongs to the open descriptor, so a crashed holder releases it.
+ Only the holder writes the journal.
+ """
+
+ def __init__(self, path: str, fd: int) -> None:
+ self._path = path
+ self._fd = fd
+
+ @classmethod
+ def acquire(cls, path: PathLike) -> "_MigrationLock | None":
+ """Take the lock without waiting. ``None`` when another process holds it."""
+ text = os.fspath(path)
+ os.makedirs(os.path.dirname(text), exist_ok=True)
+ for _ in range(_LOCK_OPEN_ATTEMPTS):
+ fd = _open_journal(text)
+ try:
+ if not _try_lock(fd):
+ os.close(fd)
+ return None
+ # A finished migrator deletes the journal. If that happened
+ # after this open, the lock is on a file nobody else can see
+ # and guards nothing: take the one that is published now.
+ published = os.path.samestat(os.fstat(fd), os.stat(text))
+ except FileNotFoundError:
+ # The journal was deleted under this descriptor: open it anew.
+ published = False
+ except BaseException:
+ os.close(fd)
+ raise
+ if published:
+ return cls(text, fd)
+ os.close(fd)
+ # Other migrators kept finishing in between, which is contention.
+ return None
+
+ def read_journal(self) -> dict[str, object] | None:
+ os.lseek(self._fd, 0, os.SEEK_SET)
+ return _parse_journal(os.read(self._fd, _JOURNAL_MAX_BYTES), self._path)
+
+ def write_journal(self, journal: dict[str, object]) -> None:
+ os.lseek(self._fd, 0, os.SEEK_SET)
+ os.ftruncate(self._fd, 0)
+ os.write(self._fd, json.dumps(journal).encode("utf-8"))
+ os.fsync(self._fd)
+
+ def release(self, *, remove: bool) -> None:
+ fd, self._fd = self._fd, -1
+ removed = False
+ if remove:
+ try:
+ # Emptied first: Windows cannot delete the file while a process
+ # that just lost the lock still has it open, and a journal that
+ # outlives the move must not read as an unfinished one.
+ os.ftruncate(fd, 0)
+ except OSError as exc:
+ log.debug("Migration journal %s not emptied (%s).", self._path, exc)
+ # POSIX deletes the journal while the lock is still held, so nobody
+ # can take over a file that is about to vanish.
+ removed = _unlink(self._path)
+ _unlock(fd)
+ try:
+ os.close(fd)
+ except OSError as exc:
+ log.debug("Closing the migration journal %s failed (%s).", self._path, exc)
+ if remove and not removed:
+ _unlink(self._path)
+
+
+def _acquire(path: Path, wait_seconds: float) -> _MigrationLock | None:
+ deadline = time.monotonic() + max(0.0, wait_seconds)
+ while True:
+ lock = _MigrationLock.acquire(path)
+ if lock is not None or time.monotonic() >= deadline:
+ return lock
+ time.sleep(_LOCK_POLL_SECONDS)
+
+
+def _remove_if_empty(legacy: Path, current: Path) -> bool:
+ """Take back an empty directory that appeared at the legacy path."""
+ if inspect_legacy(legacy, current) is not LegacyState.REAL_DIRECTORY:
+ return False
+ try:
+ os.rmdir(legacy)
+ except OSError:
+ # Not empty, so it holds data and stays; nothing was removed.
+ return False
+ return True
+
+
+def _retrying(step: Callable[[], None], retry_delays: Sequence[float]) -> None:
+ """Run ``step``; try again after each delay while the refusal looks transient."""
+ for delay in (*retry_delays, None):
+ try:
+ step()
+ return
+ except OSError as exc:
+ transient = _classify_rename_failure(exc) is RenameFailure.IN_USE_OR_DENIED
+ if delay is None or not transient:
+ raise
+ log.debug("Refused (%s); trying again in %.2f s.", exc, delay)
+ time.sleep(delay)
+
+
+def _classify_rename_failure(exc: OSError) -> RenameFailure:
+ winerror = getattr(exc, "winerror", None)
+ if exc.errno == errno.EXDEV or winerror == _WINERROR_CROSS_DEVICE:
+ return RenameFailure.CROSS_DEVICE
+ if isinstance(exc, FileExistsError) or exc.errno in (errno.EEXIST, errno.ENOTEMPTY):
+ return RenameFailure.DESTINATION_EXISTS
+ in_use = exc.errno in (errno.EACCES, errno.EPERM, errno.EBUSY)
+ if isinstance(exc, PermissionError) or in_use or winerror in _WINERRORS_IN_USE:
+ return RenameFailure.IN_USE_OR_DENIED
+ return RenameFailure.OTHER
+
+
+def _settled_outcome(state: LegacyState, current_exists: bool) -> DirectoryOutcome | None:
+ """The outcome a state already implies, or ``None`` when a move is due."""
+ if state is LegacyState.ABSENT:
+ return DirectoryOutcome.NOTHING_TO_MIGRATE
+ if state is LegacyState.LINK_TO_CURRENT:
+ return DirectoryOutcome.ALREADY_LINKED
+ if state is LegacyState.UNREADABLE:
+ return DirectoryOutcome.LEGACY_UNREADABLE
+ if state is not LegacyState.REAL_DIRECTORY:
+ return DirectoryOutcome.LEGACY_NOT_A_DIRECTORY
+ return DirectoryOutcome.BOTH_EXIST if current_exists else None
+
+
+@dataclass(frozen=True, slots=True)
+class _Step:
+ """One locked pass: its outcome and whether the journal may be deleted."""
+
+ outcome: DirectoryOutcome
+ remove_journal: bool
+ rename_failure: RenameFailure | None = None
+ detail: str = ""
+
+
+def _leave_link(
+ legacy: Path,
+ current: Path,
+ make_link: Callable[[Path, Path], None],
+ retry_delays: Sequence[float],
+ *,
+ linked: DirectoryOutcome,
+) -> _Step:
+ """Put the link at the legacy path. The journal stays until it stands."""
+ error = ""
+ for attempt in range(2):
+ try:
+ _retrying(lambda: make_link(legacy, current), retry_delays)
+ except OSError as exc:
+ # Kept for the result and logged below, once the state is known.
+ error = f"{type(exc).__name__}: {exc}"
+ if inspect_legacy(legacy, current) is LegacyState.LINK_TO_CURRENT:
+ return _Step(linked, remove_journal=True)
+ # A process that resolved a moment before the rename may have created
+ # the legacy directory afresh. While it is still empty it can make way.
+ if attempt == 0 and _remove_if_empty(legacy, current):
+ continue
+ break
+ detail = error or "the link was created but does not lead to the current directory"
+ log.warning(
+ "Moved %s to %s but could not leave a link at the old path (%s).", legacy, current, detail
+ )
+ return _Step(DirectoryOutcome.MIGRATED_WITHOUT_LINK, remove_journal=False, detail=detail)
+
+
+def _migrate_locked(
+ lock: _MigrationLock,
+ legacy: Path,
+ current: Path,
+ rename: Callable[[Path, Path], None],
+ make_link: Callable[[Path, Path], None],
+ retry_delays: Sequence[float],
+) -> _Step:
+ # Everything is read again under the lock: the state seen before taking it
+ # may be the one another migrator has just finished changing.
+ state = inspect_legacy(legacy, current)
+ try:
+ journal = lock.read_journal()
+ except OSError as exc:
+ log.warning("Migration journal for %s cannot be read (%s).", current, exc)
+ return _Step(DirectoryOutcome.LOCK_UNAVAILABLE, remove_journal=False, detail=str(exc))
+ # An earlier call renamed this very directory and did not finish.
+ moved = _proves_move(journal, legacy, current)
+ # A journal for another legacy path is that migration's to finish.
+ disposable = journal is None or _names_pair(journal, legacy, current)
+
+ if state is LegacyState.UNREADABLE:
+ return _Step(DirectoryOutcome.LEGACY_UNREADABLE, remove_journal=journal is None)
+ if moved and state is LegacyState.ABSENT:
+ return _leave_link(
+ legacy, current, make_link, retry_delays, linked=DirectoryOutcome.LINK_RESTORED
+ )
+ if moved and state is LegacyState.REAL_DIRECTORY:
+ if _remove_if_empty(legacy, current):
+ return _leave_link(
+ legacy, current, make_link, retry_delays, linked=DirectoryOutcome.LINK_RESTORED
+ )
+ # The journal is the only record that the data is at the current path
+ # and not in this newer directory, so it stays.
+ return _Step(DirectoryOutcome.LEGACY_RECREATED, remove_journal=False)
+ settled = _settled_outcome(state, _exists(current))
+ if settled is not None:
+ return _Step(settled, remove_journal=disposable)
+
+ # Nothing exists at the current path, so whatever the journal still says
+ # describes a move that never happened; this one replaces it.
+ try:
+ moving = os.lstat(legacy)
+ intent: dict[str, object] = {
+ "legacy": os.fspath(legacy),
+ "current": os.fspath(current),
+ "device": moving.st_dev,
+ "inode": moving.st_ino,
+ }
+ lock.write_journal(intent)
+ except OSError as exc:
+ # Without a journal a crash after the rename could not be finished, so
+ # the rename is not attempted.
+ log.warning("Migration journal for %s could not be written (%s).", current, exc)
+ return _Step(DirectoryOutcome.LOCK_UNAVAILABLE, remove_journal=True, detail=str(exc))
+ renamed = intent | {"renamed": True}
+ try:
+ _retrying(lambda: rename(legacy, current), retry_delays)
+ except OSError as exc:
+ # A network filesystem can report a failure for a rename that went
+ # through. The directory itself is asked before anything is concluded.
+ if not _proves_move(renamed, legacy, current):
+ failure = _classify_rename_failure(exc)
+ log.warning(
+ "Could not rename %s to %s (%s: %s); it stays in use where it is.",
+ legacy,
+ current,
+ failure.value,
+ exc,
+ )
+ return _Step(
+ DirectoryOutcome.RENAME_FAILED,
+ remove_journal=True,
+ rename_failure=failure,
+ detail=f"{type(exc).__name__}: {exc}",
+ )
+ log.info("Renamed %s to %s.", legacy, current)
+ try:
+ lock.write_journal(renamed)
+ except OSError as exc:
+ # The link is still attempted below. Only a later start can no longer
+ # tell that this directory was moved, and will leave it without one.
+ log.warning("Migration journal for %s could not record the rename (%s).", current, exc)
+ return _leave_link(legacy, current, make_link, retry_delays, linked=DirectoryOutcome.MIGRATED)
+
+
+def migrate_directory(
+ legacy: PathLike,
+ current: PathLike,
+ *,
+ lock_path: PathLike | None = None,
+ wait_seconds: float = 0.0,
+ retry_delays: Sequence[float] = TRANSIENT_RETRY_DELAYS,
+ rename: Callable[[Path, Path], None] = os.rename,
+ make_link: Callable[[Path, Path], None] = create_directory_link,
+) -> DirectoryMigration:
+ """Move ``legacy`` to ``current`` and leave a link behind. Never loses data.
+
+ Only the primary instance calls this, once, before anything opens a file in
+ either directory. It renames when ``legacy`` is a real directory and nothing
+ exists at ``current``; in every other case it changes nothing and says why.
+ A refused rename leaves the legacy directory in use, for good if need be.
+
+ ``wait_seconds`` is how long to wait for another migrator instead of
+ returning ``LOCK_BUSY`` at once; a caller that goes on to create
+ directories should wait, so it never resolves in the instant between that
+ migrator's rename and its link. ``retry_delays`` are the pauses before a
+ step that was refused as "in use" is tried again; pass ``()`` for a single
+ attempt. ``rename`` and ``make_link`` are seams for the two filesystem
+ steps; both must raise ``OSError`` on failure.
+ """
+ legacy_path = Path(os.path.abspath(legacy))
+ current_path = Path(os.path.abspath(current))
+ if lock_path is None:
+ journal_path = default_lock_path(current_path)
+ else:
+ journal_path = Path(os.path.abspath(lock_path))
+
+ def report(
+ outcome: DirectoryOutcome,
+ *,
+ rename_failure: RenameFailure | None = None,
+ detail: str = "",
+ ) -> DirectoryMigration:
+ effective = resolve_directory(current_path, [legacy_path], lock_path=journal_path)
+ if outcome in (DirectoryOutcome.MIGRATED_WITHOUT_LINK, DirectoryOutcome.LEGACY_RECREATED):
+ # This call knows where the data is, whatever stands at the legacy
+ # path and whether or not the filesystem can prove it later.
+ effective = current_path
+ return DirectoryMigration(
+ outcome=outcome,
+ legacy=legacy_path,
+ current=current_path,
+ effective=effective,
+ legacy_state=inspect_legacy(legacy_path, current_path),
+ rename_failure=rename_failure,
+ detail=detail,
+ )
+
+ if _normalized(legacy_path) == _normalized(current_path):
+ return report(DirectoryOutcome.NOTHING_TO_MIGRATE, detail="legacy and current are one path")
+
+ # The common start: nothing to move and no unfinished move on record. It
+ # costs a few stat calls and never creates the journal. The reads are not
+ # one snapshot, so the answer only counts when no migrator can have been
+ # at work in between: the current path is read before the legacy one, no
+ # journal exists, and the legacy path still looks the same afterwards.
+ current_exists = _exists(current_path)
+ state = inspect_legacy(legacy_path, current_path)
+ settled = _settled_outcome(state, current_exists)
+ quiet = not os.path.lexists(journal_path)
+ if settled is not None and quiet and inspect_legacy(legacy_path, current_path) is state:
+ return report(settled)
+
+ try:
+ lock = _acquire(journal_path, wait_seconds)
+ except OSError as exc:
+ log.warning("Migration journal %s is unavailable (%s).", journal_path, exc)
+ return report(DirectoryOutcome.LOCK_UNAVAILABLE, detail=f"{type(exc).__name__}: {exc}")
+ if lock is None:
+ # Whatever was seen above was seen while another migrator was at work,
+ # so it is not reported as settled.
+ return report(DirectoryOutcome.LOCK_BUSY)
+
+ # An exception that escapes the locked pass is treated like a crash: the
+ # journal stays, so the next call can finish what this one started.
+ remove_journal = False
+ try:
+ step = _migrate_locked(lock, legacy_path, current_path, rename, make_link, retry_delays)
+ remove_journal = step.remove_journal
+ finally:
+ lock.release(remove=remove_journal)
+ return report(step.outcome, rename_failure=step.rename_failure, detail=step.detail)
+
+
+# ----------------------------------------------------------------------
+# Keyring migration
+# ----------------------------------------------------------------------
+
+
+class KeyringBackend(Protocol):
+ """The credential-store calls the migration needs.
+
+ The names match the ``keyring`` package and the arguments are positional,
+ so that module, one of its backends, or a wrapper around either satisfies
+ it as is. ``delete_password`` is never called here (legacy entries are the
+ way back); it is part of the shape because the uninstall path clears both
+ services through it.
+ """
+
+ def get_password(self, service: str, key: str, /) -> str | None: ...
+
+ def set_password(self, service: str, key: str, value: str, /) -> None: ...
+
+ def delete_password(self, service: str, key: str, /) -> None: ...
+
+
+class KeyringOutcome(enum.Enum):
+ """What :func:`migrate_keyring` did."""
+
+ # Every present legacy entry is now reachable under the current service.
+ MIGRATED = "migrated"
+ # The marker was already there; nothing else was read.
+ ALREADY_MIGRATED = "already_migrated"
+ # Some entries could not be read, written or read back. No marker: the
+ # next call retries them, and skips the ones that made it.
+ INCOMPLETE = "incomplete"
+ # The credential store did not answer at all. Nothing was changed.
+ UNAVAILABLE = "unavailable"
+ # Legacy and current are the same service.
+ NOT_NEEDED = "not_needed"
+
+
+@dataclass(frozen=True, slots=True)
+class KeyringMigration:
+ """The full account of one :func:`migrate_keyring` call. Key names only."""
+
+ outcome: KeyringOutcome
+ legacy_service: str
+ current_service: str
+ # Copied from the legacy service by this call.
+ copied: tuple[str, ...] = ()
+ # Left alone because the current service already had a value.
+ kept: tuple[str, ...] = ()
+ # Could not be read, written or read back.
+ failed: tuple[str, ...] = ()
+ marker_written: bool = False
+
+
+def keyring_marker_key(legacy_service: str) -> str:
+ """The entry in the current service that says ``legacy_service`` was migrated."""
+ return f"__migrated_from__{legacy_service}"
+
+
+def migrate_keyring(
+ backend: KeyringBackend,
+ *,
+ legacy_service: str,
+ current_service: str,
+ keys: Iterable[str],
+) -> KeyringMigration:
+ """Copy every known legacy credential to the current service, once.
+
+ ``keys`` is the complete list of entries the product ever stores; an entry
+ that is not listed is not migrated, because a credential store cannot be
+ enumerated portably. A value already present under the current service is
+ never overwritten, and no legacy entry is deleted. Every copy is read back,
+ so a store that accepts a write and keeps nothing is not taken for done.
+
+ Error texts from the store never reach a log line or the result: a backend
+ may quote the value it refused.
+ """
+
+ def report(outcome: KeyringOutcome) -> KeyringMigration:
+ return KeyringMigration(outcome, legacy_service, current_service)
+
+ if legacy_service == current_service:
+ return report(KeyringOutcome.NOT_NEEDED)
+ marker = keyring_marker_key(legacy_service)
+ try:
+ if backend.get_password(current_service, marker):
+ return report(KeyringOutcome.ALREADY_MIGRATED)
+ except Exception as exc: # noqa: BLE001 - backend error types are not importable here
+ log.warning(
+ "Credential store unavailable (%s); keys stay under %s.",
+ type(exc).__name__,
+ legacy_service,
+ )
+ return report(KeyringOutcome.UNAVAILABLE)
+
+ copied: list[str] = []
+ kept: list[str] = []
+ failed: list[str] = []
+ for key in dict.fromkeys(keys):
+ try:
+ value = backend.get_password(legacy_service, key)
+ if not value:
+ continue
+ if backend.get_password(current_service, key):
+ kept.append(key)
+ continue
+ backend.set_password(current_service, key, value)
+ persisted = backend.get_password(current_service, key) == value
+ except Exception as exc: # noqa: BLE001 - backend error types are not importable here
+ log.warning("Credential %s was not migrated (%s).", key, type(exc).__name__)
+ failed.append(key)
+ continue
+ if persisted:
+ copied.append(key)
+ else:
+ log.warning("Credential %s did not persist under %s.", key, current_service)
+ failed.append(key)
+
+ marker_written = False
+ if not failed:
+ try:
+ backend.set_password(current_service, marker, "1")
+ marker_written = bool(backend.get_password(current_service, marker))
+ except Exception as exc: # noqa: BLE001 - backend error types are not importable here
+ # Harmless: the next call finds every value in place and only
+ # writes the marker.
+ log.warning("Credential migration marker was not written (%s).", type(exc).__name__)
+ return KeyringMigration(
+ outcome=KeyringOutcome.MIGRATED if marker_written else KeyringOutcome.INCOMPLETE,
+ legacy_service=legacy_service,
+ current_service=current_service,
+ copied=tuple(copied),
+ kept=tuple(kept),
+ failed=tuple(failed),
+ marker_written=marker_written,
+ )
+
+
+__all__ = [
+ "DirectoryMigration",
+ "DirectoryOutcome",
+ "KeyringBackend",
+ "KeyringMigration",
+ "KeyringOutcome",
+ "LegacyState",
+ "RenameFailure",
+ "TRANSIENT_RETRY_DELAYS",
+ "create_directory_link",
+ "default_lock_path",
+ "inspect_legacy",
+ "keyring_marker_key",
+ "migrate_directory",
+ "migrate_keyring",
+ "resolve_directory",
+]
diff --git a/tests/fakes/fake_keyring_backend.py b/tests/fakes/fake_keyring_backend.py
new file mode 100644
index 0000000000..9395d8e18f
--- /dev/null
+++ b/tests/fakes/fake_keyring_backend.py
@@ -0,0 +1,48 @@
+"""A dict-backed credential store with the ``keyring`` call shape.
+
+Entries live under ``(service, key)`` like the real store, so a test can hold
+two services side by side. Failures are scripted per call, and every call is
+recorded, so a test can prove what was *not* touched.
+"""
+
+from __future__ import annotations
+
+
+class FakeKeyringError(RuntimeError):
+ """Stands in for the backend-specific errors a real store raises."""
+
+
+class FakeKeyringBackend:
+ """The ``KeyringBackend`` shape of ``jarvis.core.identity_migration``."""
+
+ def __init__(self, *, unavailable: bool = False, drop_writes: bool = False) -> None:
+ self.entries: dict[tuple[str, str], str] = {}
+ self.unavailable = unavailable
+ # Accept every write and keep nothing, like a null fallback store.
+ self.drop_writes = drop_writes
+ # ``(operation, service, key)`` triples that raise instead of working.
+ self.fail_on: set[tuple[str, str, str]] = set()
+ self.calls: list[tuple[str, str, str]] = []
+
+ def _record(self, operation: str, service: str, key: str, value: str = "") -> None:
+ self.calls.append((operation, service, key))
+ if self.unavailable or (operation, service, key) in self.fail_on:
+ # The error text of a store may quote the value it refused.
+ raise FakeKeyringError(f"{operation} refused for {service}/{key}: {value!r}")
+
+ def get_password(self, service: str, key: str) -> str | None:
+ self._record("get", service, key)
+ return self.entries.get((service, key))
+
+ def set_password(self, service: str, key: str, value: str) -> None:
+ self._record("set", service, key, value)
+ if not self.drop_writes:
+ self.entries[(service, key)] = value
+
+ def delete_password(self, service: str, key: str) -> None:
+ self._record("delete", service, key)
+ self.entries.pop((service, key), None)
+
+ def service(self, service: str) -> dict[str, str]:
+ """Everything stored under one service, as ``key -> value``."""
+ return {key: value for (owner, key), value in self.entries.items() if owner == service}
diff --git a/tests/unit/core/test_identity_migration.py b/tests/unit/core/test_identity_migration.py
new file mode 100644
index 0000000000..421107bfce
--- /dev/null
+++ b/tests/unit/core/test_identity_migration.py
@@ -0,0 +1,1433 @@
+"""``jarvis.core.identity_migration`` — moving an install to a new name without losing it.
+
+Why this file matters: the engine is what will carry a real person's data
+directory, install directory and stored credentials from one product name to
+the next. Every failure mode here is somebody's memory, settings or API keys
+appearing to vanish. The tests run on the real filesystem with a synthetic name
+pair, and inject a failure only where the operating system cannot be made to
+produce it on demand (a cross-volume rename, a crash between two steps).
+"""
+
+from __future__ import annotations
+
+import ast
+import errno
+import json
+import os
+import shutil
+import subprocess
+import sys
+import textwrap
+import threading
+import time
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+import pytest
+
+from jarvis.core import identity_migration as engine
+from jarvis.core.identity_migration import (
+ DirectoryOutcome,
+ KeyringOutcome,
+ LegacyState,
+ RenameFailure,
+ create_directory_link,
+ default_lock_path,
+ inspect_legacy,
+ keyring_marker_key,
+ migrate_directory,
+ migrate_keyring,
+ resolve_directory,
+)
+from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
+from tests.fakes.fake_keyring_backend import FakeKeyringBackend
+
+MODULE_PATH = Path(engine.__file__).resolve()
+
+# A synthetic pair. The legacy name carries a space on purpose: real install
+# and data directories have had one.
+LEGACY_NAME = "Old Name"
+CURRENT_NAME = "NewName"
+
+_FILES = {
+ "settings.toml": b"voice = true\n",
+ "data/store.db": b"\x00\x01binary\xff",
+ "data/nested/deep/note.txt": b"caf\xc3\xa9 \xe2\x98\x83",
+}
+
+
+def _populate(directory: Path) -> dict[str, bytes]:
+ for relative, content in _FILES.items():
+ target = directory / relative
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_bytes(content)
+ return dict(_FILES)
+
+
+def _snapshot(directory: Path) -> dict[str, bytes]:
+ return {
+ path.relative_to(directory).as_posix(): path.read_bytes()
+ for path in sorted(directory.rglob("*"))
+ if path.is_file()
+ }
+
+
+def _names(directory: Path) -> list[str]:
+ return sorted(entry.name for entry in directory.iterdir())
+
+
+def _remove_link(link: Path) -> None:
+ """Drop a link, never its target: a symlink unlinks, a junction is an rmdir."""
+ try:
+ os.unlink(link)
+ except OSError:
+ os.rmdir(link)
+
+
+def home(tmp_path: Path) -> Path:
+ """The parent both directories live in, like a user profile."""
+ root = tmp_path / "home"
+ root.mkdir()
+ return root
+
+
+def legacy(home: Path) -> Path:
+ return home / LEGACY_NAME
+
+
+def current(home: Path) -> Path:
+ return home / CURRENT_NAME
+
+
+def linkable(tmp_path: Path) -> None:
+ """Skip where this account cannot leave a directory link at all."""
+ target = tmp_path / "link-probe-target"
+ link = tmp_path / "link-probe"
+ target.mkdir()
+ try:
+ create_directory_link(link, target)
+ except OSError as exc:
+ pytest.skip(f"this OS account cannot create a directory link: {exc}")
+ _remove_link(link)
+
+
+def symlinkable(tmp_path: Path) -> None:
+ """Skip where the OS refuses an unprivileged directory symlink."""
+ target = tmp_path / "symlink-probe-target"
+ link = tmp_path / "symlink-probe"
+ target.mkdir()
+ try:
+ os.symlink(target, link, target_is_directory=True)
+ except (OSError, NotImplementedError, AttributeError) as exc:
+ pytest.skip(f"this OS account cannot create a directory symlink: {exc}")
+ _remove_link(link)
+
+
+def junction() -> Callable[[Path, Path], None]:
+ """The raw junction call, skipped where the platform has none."""
+ try:
+ import _winapi
+
+ create = _winapi.CreateJunction # type: ignore[attr-defined]
+ except (ImportError, AttributeError):
+ pytest.skip("this platform has no directory junctions")
+
+ def make(link: Path, target: Path) -> None:
+ create(str(target), str(link))
+
+ return make
+
+
+# ----------------------------------------------------------------------
+# Resolution rule
+# ----------------------------------------------------------------------
+
+
+def test_absent_legacy_resolves_to_current(legacy: Path, current: Path) -> None:
+ assert inspect_legacy(legacy, current) is LegacyState.ABSENT
+ assert resolve_directory(current, [legacy]) == current
+
+
+def test_no_legacy_paths_resolves_to_current(current: Path) -> None:
+ assert resolve_directory(current) == current
+
+
[email protected]("current_exists", [False, True])
+def test_real_legacy_directory_wins(legacy: Path, current: Path, current_exists: bool) -> None:
+ _populate(legacy)
+ if current_exists:
+ _populate(current)
+
+ assert inspect_legacy(legacy, current) is LegacyState.REAL_DIRECTORY
+ assert resolve_directory(current, [legacy]) == legacy
+
+
+def test_a_file_at_the_legacy_path_does_not_win(legacy: Path, current: Path) -> None:
+ legacy.write_text("not a directory", encoding="utf-8")
+
+ assert inspect_legacy(legacy, current) is LegacyState.NOT_A_DIRECTORY
+ assert resolve_directory(current, [legacy]) == current
+
+
[email protected]("linkable")
+def test_link_to_current_resolves_to_current(legacy: Path, current: Path) -> None:
+ _populate(current)
+ create_directory_link(legacy, current)
+
+ assert inspect_legacy(legacy, current) is LegacyState.LINK_TO_CURRENT
+ assert resolve_directory(current, [legacy]) == current
+
+
[email protected]("linkable")
+def test_link_to_a_not_yet_created_current_resolves_to_current(legacy: Path, current: Path) -> None:
+ current.mkdir()
+ create_directory_link(legacy, current)
+ current.rmdir()
+
+ assert inspect_legacy(legacy, current) is LegacyState.LINK_TO_CURRENT
+ assert resolve_directory(current, [legacy]) == current
+
+
[email protected]("linkable")
+def test_dangling_link_elsewhere_resolves_to_current(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ gone = home / "gone"
+ gone.mkdir()
+ create_directory_link(legacy, gone)
+ gone.rmdir()
+
+ assert inspect_legacy(legacy, current) is LegacyState.DANGLING_LINK
+ assert resolve_directory(current, [legacy]) == current
+
+
[email protected]("linkable")
+def test_users_own_link_to_another_directory_wins(home: Path, legacy: Path, current: Path) -> None:
+ """A redirect the user set up themselves is where their data is reached."""
+ elsewhere = home / "second-disk"
+ _populate(elsewhere)
+ create_directory_link(legacy, elsewhere)
+
+ assert inspect_legacy(legacy, current) is LegacyState.FOREIGN_LINK
+ assert resolve_directory(current, [legacy]) == legacy
+
+
[email protected]("symlinkable")
[email protected]("relative", [False, True])
+def test_a_symlink_to_current_is_recognized(legacy: Path, current: Path, relative: bool) -> None:
+ current.mkdir()
+ os.symlink(CURRENT_NAME if relative else current, legacy, target_is_directory=True)
+
+ assert inspect_legacy(legacy, current) is LegacyState.LINK_TO_CURRENT
+ assert resolve_directory(current, [legacy]) == current
+
+
+def test_a_junction_to_current_is_recognized(
+ legacy: Path, current: Path, junction: Callable[[Path, Path], None]
+) -> None:
+ current.mkdir()
+ junction(legacy, current)
+
+ assert inspect_legacy(legacy, current) is LegacyState.LINK_TO_CURRENT
+ assert resolve_directory(current, [legacy]) == current
+
+
[email protected]("linkable")
+def test_legacy_paths_are_tried_in_order(home: Path, current: Path) -> None:
+ oldest = home / "Oldest"
+ older = home / "Older"
+ absent = home / "Never Existed"
+ _populate(current)
+ create_directory_link(older, current)
+
+ assert resolve_directory(current, [absent, older]) == current
+ _populate(oldest)
+ assert resolve_directory(current, [absent, older, oldest]) == oldest
+ _remove_link(older)
+ older.mkdir()
+ assert resolve_directory(current, [absent, older, oldest]) == older
+
+
+def test_resolving_changes_nothing_on_disk(home: Path, legacy: Path, current: Path) -> None:
+ _populate(legacy)
+ before = (_names(home), _snapshot(legacy))
+
+ resolve_directory(current, [legacy])
+ inspect_legacy(legacy, current)
+
+ assert (_names(home), _snapshot(legacy)) == before
+
+
+# ----------------------------------------------------------------------
+# Directory migration: the move
+# ----------------------------------------------------------------------
+
+
[email protected]("linkable")
+def test_moves_the_directory_and_leaves_a_link(home: Path, legacy: Path, current: Path) -> None:
+ files = _populate(legacy)
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.MIGRATED
+ assert result.legacy == legacy
+ assert result.current == current
+ assert result.effective == current
+ assert result.legacy_state is LegacyState.LINK_TO_CURRENT
+ assert result.rename_failure is None
+ assert _snapshot(current) == files
+ assert not os.path.islink(current) and current.is_dir()
+ assert os.path.samefile(legacy, current)
+ # Nothing else is left behind: no journal, no lock file, no copy.
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_second_run_does_nothing(home: Path, legacy: Path, current: Path) -> None:
+ files = _populate(legacy)
+ migrate_directory(legacy, current)
+ renames: list[tuple[Path, Path]] = []
+
+ result = migrate_directory(
+ legacy, current, rename=lambda source, target: renames.append((source, target))
+ )
+
+ assert result.outcome is DirectoryOutcome.ALREADY_LINKED
+ assert result.effective == current
+ assert renames == []
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_old_and_new_path_see_the_same_files(legacy: Path, current: Path) -> None:
+ _populate(legacy)
+ migrate_directory(legacy, current)
+
+ # Code that still spells the old name writes; the new name reads it.
+ (legacy / "data" / "written-through-old.txt").write_text("old path", encoding="utf-8")
+ assert (current / "data" / "written-through-old.txt").read_text(encoding="utf-8") == "old path"
+ # And the other way round, including a directory created through the link.
+ (current / "fresh").mkdir()
+ (current / "fresh" / "written-through-new.txt").write_text("new path", encoding="utf-8")
+ assert (legacy / "fresh" / "written-through-new.txt").read_text(encoding="utf-8") == "new path"
+ assert _snapshot(legacy) == _snapshot(current)
+
+
+def test_no_legacy_directory_is_a_no_op(home: Path, legacy: Path, current: Path) -> None:
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert result.effective == current
+ assert _names(home) == []
+
+
+def test_a_fresh_install_is_not_mistaken_for_an_interrupted_move(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ """No legacy directory and no journal: no link may appear at the old name."""
+ files = _populate(current)
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert _names(home) == [CURRENT_NAME]
+ assert _snapshot(current) == files
+
+
+def test_identical_paths_are_a_no_op(home: Path, current: Path) -> None:
+ files = _populate(current)
+
+ result = migrate_directory(current, home / "." / CURRENT_NAME)
+
+ assert result.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert _snapshot(current) == files
+ assert _names(home) == [CURRENT_NAME]
+
+
+# ----------------------------------------------------------------------
+# Directory migration: never merge, never overwrite
+# ----------------------------------------------------------------------
+
+
[email protected]("current_kind", ["populated", "empty", "file"])
+def test_both_existing_is_left_alone(
+ home: Path, legacy: Path, current: Path, current_kind: str
+) -> None:
+ files = _populate(legacy)
+ if current_kind == "populated":
+ current.mkdir()
+ (current / "other.txt").write_text("belongs to the new install", encoding="utf-8")
+ elif current_kind == "empty":
+ current.mkdir()
+ else:
+ current.write_text("a file", encoding="utf-8")
+ current_before = _snapshot(current) if current.is_dir() else current.read_bytes()
+ renames: list[tuple[Path, Path]] = []
+
+ result = migrate_directory(
+ legacy, current, rename=lambda source, target: renames.append((source, target))
+ )
+
+ assert result.outcome is DirectoryOutcome.BOTH_EXIST
+ assert result.effective == legacy
+ assert result.legacy_state is LegacyState.REAL_DIRECTORY
+ assert renames == []
+ assert _snapshot(legacy) == files
+ assert (_snapshot(current) if current.is_dir() else current.read_bytes()) == current_before
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_users_own_link_is_not_migrated(home: Path, legacy: Path, current: Path) -> None:
+ elsewhere = home / "second-disk"
+ files = _populate(elsewhere)
+ create_directory_link(legacy, elsewhere)
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.LEGACY_NOT_A_DIRECTORY
+ assert result.legacy_state is LegacyState.FOREIGN_LINK
+ assert result.effective == legacy
+ assert not current.exists()
+ assert os.path.samefile(legacy, elsewhere)
+ assert _snapshot(elsewhere) == files
+
+
+def test_a_file_at_the_legacy_path_is_not_migrated(legacy: Path, current: Path) -> None:
+ legacy.write_text("not a directory", encoding="utf-8")
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.LEGACY_NOT_A_DIRECTORY
+ assert result.effective == current
+ assert legacy.read_text(encoding="utf-8") == "not a directory"
+ assert not current.exists()
+
+
+def _hide_from_lstat(monkeypatch: pytest.MonkeyPatch, hidden: Path) -> None:
+ """Make one path uninspectable, the way a denied or failing volume does."""
+ real_lstat = os.lstat
+
+ def lstat(path: str | os.PathLike[str], *args: object, **kwargs: object) -> os.stat_result:
+ if os.path.abspath(path) == os.path.abspath(hidden):
+ raise PermissionError(errno.EACCES, "access denied", os.fspath(path))
+ return real_lstat(path, *args, **kwargs) # type: ignore[arg-type]
+
+ monkeypatch.setattr(engine.os, "lstat", lstat)
+
+
+def test_an_uninspectable_legacy_path_is_not_taken_for_absent(
+ monkeypatch: pytest.MonkeyPatch, home: Path, legacy: Path, current: Path
+) -> None:
+ """Starting on an empty directory behind a momentary error would split the install."""
+ files = _populate(legacy)
+ _hide_from_lstat(monkeypatch, legacy)
+
+ assert inspect_legacy(legacy, current) is LegacyState.UNREADABLE
+ assert resolve_directory(current, [legacy]) == legacy
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.LEGACY_UNREADABLE
+ assert result.effective == legacy
+ monkeypatch.undo()
+ assert _snapshot(legacy) == files
+ assert _names(home) == [LEGACY_NAME]
+
+
+def test_an_uninspectable_current_path_counts_as_occupied(
+ monkeypatch: pytest.MonkeyPatch, home: Path, legacy: Path, current: Path
+) -> None:
+ files = _populate(legacy)
+ _hide_from_lstat(monkeypatch, current)
+ renames: list[tuple[Path, Path]] = []
+
+ result = migrate_directory(
+ legacy, current, rename=lambda source, target: renames.append((source, target))
+ )
+
+ assert result.outcome is DirectoryOutcome.BOTH_EXIST
+ assert result.effective == legacy
+ assert renames == []
+ monkeypatch.undo()
+ assert _snapshot(legacy) == files
+ assert _names(home) == [LEGACY_NAME]
+
+
+# ----------------------------------------------------------------------
+# Directory migration: a refused rename
+# ----------------------------------------------------------------------
+
+
+def _refuse(error: OSError) -> Callable[[Path, Path], None]:
+ def rename(source: Path, target: Path) -> None:
+ raise error
+
+ return rename
+
+
+ ("error", "expected"),
+ [
+ (PermissionError(errno.EACCES, "a file inside is open"), RenameFailure.IN_USE_OR_DENIED),
+ (OSError(errno.EBUSY, "device or resource busy"), RenameFailure.IN_USE_OR_DENIED),
+ (OSError(errno.EXDEV, "target is on another volume"), RenameFailure.CROSS_DEVICE),
+ (FileExistsError(errno.EEXIST, "target appeared"), RenameFailure.DESTINATION_EXISTS),
+ (OSError(errno.ENOTEMPTY, "target not empty"), RenameFailure.DESTINATION_EXISTS),
+ (OSError(errno.EIO, "input/output error"), RenameFailure.OTHER),
+ ],
+)
+def test_refused_rename_leaves_everything_untouched(
+ home: Path, legacy: Path, current: Path, error: OSError, expected: RenameFailure
+) -> None:
+ files = _populate(legacy)
+
+ result = migrate_directory(legacy, current, rename=_refuse(error), retry_delays=())
+
+ assert result.outcome is DirectoryOutcome.RENAME_FAILED
+ assert result.rename_failure is expected
+ assert result.detail
+ # The app keeps running at the legacy location: nothing was copied, and
+ # nothing (not even the journal) is left next to it.
+ assert result.effective == legacy
+ assert result.legacy_state is LegacyState.REAL_DIRECTORY
+ assert _snapshot(legacy) == files
+ assert _names(home) == [LEGACY_NAME]
+
+
+class _FlakyRename:
+ """A real rename that is refused a number of times first."""
+
+ def __init__(self, refusals: int, error: OSError) -> None:
+ self.refusals = refusals
+ self.error = error
+ self.calls = 0
+
+ def __call__(self, source: Path, target: Path) -> None:
+ self.calls += 1
+ if self.calls <= self.refusals:
+ raise self.error
+ os.rename(source, target)
+
+
[email protected]("linkable")
+def test_a_momentary_refusal_is_retried_within_the_same_call(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ """A scanner looking at freshly written files lets go within moments."""
+ files = _populate(legacy)
+ rename = _FlakyRename(2, PermissionError(errno.EACCES, "a scanner has it open"))
+
+ result = migrate_directory(legacy, current, rename=rename, retry_delays=(0.0, 0.0))
+
+ assert result.outcome is DirectoryOutcome.MIGRATED
+ assert rename.calls == 3
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
+def test_a_lasting_refusal_gives_up_after_the_retries(legacy: Path, current: Path) -> None:
+ _populate(legacy)
+ rename = _FlakyRename(99, PermissionError(errno.EACCES, "a file inside is open"))
+
+ result = migrate_directory(legacy, current, rename=rename, retry_delays=(0.0, 0.0))
+
+ assert result.outcome is DirectoryOutcome.RENAME_FAILED
+ assert rename.calls == 3
+
+
+def test_another_volume_is_not_retried(legacy: Path, current: Path) -> None:
+ _populate(legacy)
+ rename = _FlakyRename(99, OSError(errno.EXDEV, "target is on another volume"))
+
+ result = migrate_directory(legacy, current, rename=rename)
+
+ assert result.rename_failure is RenameFailure.CROSS_DEVICE
+ assert rename.calls == 1
+
+
[email protected]("linkable")
+def test_a_refused_rename_is_retried_on_the_next_start(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ files = _populate(legacy)
+ refused = migrate_directory(
+ legacy,
+ current,
+ rename=_refuse(PermissionError(errno.EACCES, "a file inside is open")),
+ retry_delays=(),
+ )
+
+ retried = migrate_directory(legacy, current)
+
+ assert refused.outcome is DirectoryOutcome.RENAME_FAILED
+ assert retried.outcome is DirectoryOutcome.MIGRATED
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_an_open_file_refuses_the_real_rename_where_the_os_enforces_it(
+ tmp_path: Path, home: Path, legacy: Path, current: Path
+) -> None:
+ probe = tmp_path / "open-file-probe"
+ probe.mkdir()
+ (probe / "held.txt").write_text("x", encoding="utf-8")
+ with (probe / "held.txt").open(encoding="utf-8"):
+ try:
+ os.rename(probe, tmp_path / "open-file-probe-moved")
+ except OSError:
+ pass # This OS refuses to rename a directory with an open file: test it.
+ else:
+ pytest.skip("this OS renames a directory while a file inside is open")
+ files = _populate(legacy)
+
+ with (legacy / "settings.toml").open("rb"):
+ held = migrate_directory(legacy, current, retry_delays=(0.0,))
+ released = migrate_directory(legacy, current)
+
+ assert held.outcome is DirectoryOutcome.RENAME_FAILED
+ assert held.rename_failure is RenameFailure.IN_USE_OR_DENIED
+ assert held.effective == legacy
+ assert released.outcome is DirectoryOutcome.MIGRATED
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
+# ----------------------------------------------------------------------
+# Directory migration: the link step and crash recovery
+# ----------------------------------------------------------------------
+
+_CHILD = textwrap.dedent(
+ """
+ import importlib.util
+ import os
+ import sys
+ import time
+
+ module_path, mode, legacy, current, go = sys.argv[1:6]
+ # Loaded by path and deliberately not registered in sys.modules: the way a
+ # frozen runtime hook has to load it, before the package can be imported.
+ spec = importlib.util.spec_from_file_location("identity_migration_by_path", module_path)
+ engine = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(engine)
+ if any(name == "jarvis" or name.startswith("jarvis.") for name in sys.modules):
+ sys.exit("the engine imported the jarvis package")
+
+ def crash(source, target):
+ os._exit(70)
+
+ def rename_then_crash(source, target):
+ os.rename(source, target)
+ os._exit(70)
+
+ kwargs = {}
+ if mode == "crash-in-rename":
+ kwargs["rename"] = crash
+ elif mode == "crash-after-rename":
+ kwargs["rename"] = rename_then_crash
+ elif mode == "crash-in-link":
+ kwargs["make_link"] = crash
+ elif mode == "race":
+ open(f"{go}.ready.{os.getpid()}", "w").close()
+ while not os.path.exists(go):
+ time.sleep(0.001)
+ result = engine.migrate_directory(legacy, current, **kwargs)
+ print(result.outcome.value)
+ """
+)
+
+
+def child(tmp_path: Path) -> Iterator[Callable[..., subprocess.Popen[str]]]:
+ """Start a separate Python process that runs one migration."""
+ script = tmp_path / "migrate_child.py"
+ script.write_text(_CHILD, encoding="utf-8")
+ started: list[subprocess.Popen[str]] = []
+
+ def start(mode: str, legacy: Path, current: Path, go: Path | None = None) -> subprocess.Popen:
+ process = subprocess.Popen(
+ # -I: no PYTHONPATH and no working directory on sys.path, so the
+ # child cannot reach the jarvis package even by accident.
+ [
+ sys.executable,
+ "-I",
+ str(script),
+ str(MODULE_PATH),
+ mode,
+ str(legacy),
+ str(current),
+ str(go or tmp_path / "go"),
+ ],
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ text=True,
+ encoding="utf-8",
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ started.append(process)
+ return process
+
+ yield start
+ for process in started:
+ if process.poll() is None:
+ process.kill()
+ process.communicate()
+
+
[email protected]("linkable")
+def test_crash_between_rename_and_link_is_finished_on_the_next_start(
+ home: Path, legacy: Path, current: Path, child: Callable[..., subprocess.Popen[str]]
+) -> None:
+ files = _populate(legacy)
+
+ crashed = child("crash-in-link", legacy, current)
+ _, stderr = crashed.communicate(timeout=60)
+
+ assert crashed.returncode == 70, stderr
+ # The rename is done, the link is not. That alone is a usable state:
+ assert not os.path.lexists(legacy)
+ assert _snapshot(current) == files
+ assert resolve_directory(current, [legacy]) == current
+ assert default_lock_path(current).exists()
+
+ recovered = migrate_directory(legacy, current)
+
+ assert recovered.outcome is DirectoryOutcome.LINK_RESTORED
+ assert recovered.effective == current
+ assert os.path.samefile(legacy, current)
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+ assert migrate_directory(legacy, current).outcome is DirectoryOutcome.ALREADY_LINKED
+
+
[email protected]("linkable")
+def test_crash_before_the_rename_just_migrates_on_the_next_start(
+ home: Path, legacy: Path, current: Path, child: Callable[..., subprocess.Popen[str]]
+) -> None:
+ files = _populate(legacy)
+
+ crashed = child("crash-in-rename", legacy, current)
+ _, stderr = crashed.communicate(timeout=60)
+
+ assert crashed.returncode == 70, stderr
+ assert _snapshot(legacy) == files
+ assert resolve_directory(current, [legacy]) == legacy
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.MIGRATED
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
+def test_crash_before_the_rename_is_recorded_leaves_the_data_without_a_link(
+ home: Path, legacy: Path, current: Path, child: Callable[..., subprocess.Popen[str]]
+) -> None:
+ """The one instant in which a finished rename cannot be told from none.
+
+ The journal learns of the rename right after it. A crash in between leaves
+ the data at the current path with no link, and it stays that way: guessing
+ here would also put a link beside every fresh install that follows an
+ interrupted attempt.
+ """
+ files = _populate(legacy)
+ crashed = child("crash-after-rename", legacy, current)
+ crashed.communicate(timeout=60)
+ assert crashed.returncode == 70
+ assert resolve_directory(current, [legacy]) == current
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert result.effective == current
+ assert _snapshot(current) == files
+ assert _names(home) == [CURRENT_NAME]
+
+
+def test_a_journal_left_before_the_rename_never_links_a_fresh_install(
+ home: Path, legacy: Path, current: Path, child: Callable[..., subprocess.Popen[str]]
+) -> None:
+ """The journal names the pair, but the directory it described never moved."""
+ _populate(legacy)
+ crashed = child("crash-in-rename", legacy, current)
+ crashed.communicate(timeout=60)
+ assert default_lock_path(current).exists()
+ # The user removes the old installation and installs afresh.
+ shutil.rmtree(legacy)
+ fresh = _populate(current)
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert not os.path.lexists(legacy)
+ assert _snapshot(current) == fresh
+ assert _names(home) == [CURRENT_NAME]
+
+
[email protected]("legacy_exists", [False, True])
+def test_a_garbled_journal_is_ignored(
+ home: Path, legacy: Path, current: Path, legacy_exists: bool
+) -> None:
+ default_lock_path(current).write_bytes(b"\xff\x00 not json {")
+ files = _populate(legacy if legacy_exists else current)
+ links: list[tuple[Path, Path]] = []
+
+ result = migrate_directory(
+ legacy, current, make_link=lambda link, target: links.append((link, target))
+ )
+
+ if legacy_exists:
+ # The move itself goes ahead; only the recording link maker stops it
+ # from being called MIGRATED.
+ assert result.outcome is DirectoryOutcome.MIGRATED_WITHOUT_LINK
+ assert links == [(legacy, current)]
+ else:
+ assert result.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert links == []
+ assert _names(home) == [CURRENT_NAME]
+ assert result.effective == current
+ assert _snapshot(current) == files
+
+
[email protected]("linkable")
+def test_a_link_never_replaces_an_existing_path(home: Path, legacy: Path, current: Path) -> None:
+ files = _populate(legacy)
+ current.mkdir()
+
+ with pytest.raises(FileExistsError):
+ create_directory_link(legacy, current)
+
+ assert _snapshot(legacy) == files
+ assert inspect_legacy(legacy, current) is LegacyState.REAL_DIRECTORY
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
+def test_a_leftover_staging_junction_does_not_block_the_link(
+ home: Path, legacy: Path, current: Path, junction: Callable[[Path, Path], None]
+) -> None:
+ """A crash while the junction was being built leaves one under its staging name."""
+ files = _populate(legacy)
+ stale_target = home / "stale-target"
+ stale_target.mkdir()
+ junction(home / f".{LEGACY_NAME}.identity-link", stale_target)
+
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.MIGRATED
+ assert os.path.samefile(legacy, current)
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME, "stale-target"])
+
+
[email protected]("linkable")
+def test_a_refused_link_is_a_valid_end_state_and_is_retried(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ files = _populate(legacy)
+
+ def refuse_link(link: Path, target: Path) -> None:
+ raise PermissionError(errno.EPERM, "links are not permitted here")
+
+ moved = migrate_directory(legacy, current, make_link=refuse_link, retry_delays=())
+
+ assert moved.outcome is DirectoryOutcome.MIGRATED_WITHOUT_LINK
+ assert moved.effective == current
+ assert moved.legacy_state is LegacyState.ABSENT
+ assert "links are not permitted here" in moved.detail
+ assert _snapshot(current) == files
+ assert not os.path.lexists(legacy)
+
+ retried = migrate_directory(legacy, current)
+
+ assert retried.outcome is DirectoryOutcome.LINK_RESTORED
+ assert os.path.samefile(legacy, current)
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_an_empty_directory_recreated_at_the_old_path_makes_way(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ """A process that resolved just before the rename may mkdir the old path."""
+ files = _populate(legacy)
+ calls = 0
+
+ def link_after_a_late_mkdir(link: Path, target: Path) -> None:
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ link.mkdir()
+ create_directory_link(link, target)
+
+ result = migrate_directory(legacy, current, make_link=link_after_a_late_mkdir)
+
+ assert result.outcome is DirectoryOutcome.MIGRATED
+ assert calls == 2
+ assert os.path.samefile(legacy, current)
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_data_recreated_at_the_old_path_is_never_removed(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ files = _populate(legacy)
+
+ def link_after_a_late_write(link: Path, target: Path) -> None:
+ link.mkdir(exist_ok=True)
+ (link / "late.txt").write_text("written by another process", encoding="utf-8")
+ create_directory_link(link, target)
+
+ moved = migrate_directory(legacy, current, make_link=link_after_a_late_write)
+
+ assert moved.outcome is DirectoryOutcome.MIGRATED_WITHOUT_LINK
+ # The newer directory must not hide the moved data, in this call or in any
+ # later one, for the migrator or for a process that only resolves.
+ assert moved.effective == current
+ for _ in range(2):
+ again = migrate_directory(legacy, current)
+ assert again.outcome is DirectoryOutcome.LEGACY_RECREATED
+ assert again.effective == current
+ assert again.legacy_state is LegacyState.REAL_DIRECTORY
+ assert resolve_directory(current, [legacy]) == current
+ assert _snapshot(legacy) == {"late.txt": b"written by another process"}
+ assert _snapshot(current) == files
+ assert default_lock_path(current).exists()
+
+
+def test_a_legacy_directory_beside_an_unrelated_current_still_wins(
+ legacy: Path, current: Path
+) -> None:
+ """Only the journal's proof of a move lets the current directory outrank it."""
+ files = _populate(legacy)
+ current.mkdir()
+ default_lock_path(current).write_text(
+ json.dumps(
+ {
+ "legacy": str(legacy),
+ "current": str(current),
+ "device": 1,
+ "inode": 1,
+ "renamed": True,
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ assert resolve_directory(current, [legacy]) == legacy
+ result = migrate_directory(legacy, current)
+
+ assert result.outcome is DirectoryOutcome.BOTH_EXIST
+ assert result.effective == legacy
+ assert _snapshot(legacy) == files
+ assert not default_lock_path(current).exists()
+
+
[email protected]("linkable")
+def test_a_journal_for_another_legacy_path_is_that_migrations_to_finish(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ other_legacy = home / "Other Old Name"
+ _populate(current)
+ moved = os.lstat(current)
+ journal = default_lock_path(current)
+ journal.write_text(
+ json.dumps(
+ {
+ "legacy": str(other_legacy),
+ "current": str(current),
+ "device": moved.st_dev,
+ "inode": moved.st_ino,
+ "renamed": True,
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ unrelated = migrate_directory(legacy, current)
+
+ assert unrelated.outcome is DirectoryOutcome.NOTHING_TO_MIGRATE
+ assert not os.path.lexists(legacy)
+ assert journal.exists()
+
+ owner = migrate_directory(other_legacy, current)
+
+ assert owner.outcome is DirectoryOutcome.LINK_RESTORED
+ assert os.path.samefile(other_legacy, current)
+ assert not journal.exists()
+
+
+# ----------------------------------------------------------------------
+# Directory migration: one migrator at a time
+# ----------------------------------------------------------------------
+
+
+def test_the_journal_sits_beside_the_current_directory(home: Path, current: Path) -> None:
+ journal = default_lock_path(current)
+
+ assert journal.parent == home
+ assert journal.name == f".{CURRENT_NAME}.identity-migration"
+ assert default_lock_path(home / ".new-data").name == ".new-data.identity-migration"
+
+
+def _assert_tidy_after_the_next_start(home: Path, legacy: Path, current: Path) -> None:
+ """A contender that lost the lock can keep the winner from deleting the journal.
+
+ Windows refuses to delete a file another process still has open. The file
+ that stays is empty, and the next start removes it.
+ """
+ assert migrate_directory(legacy, current).outcome is DirectoryOutcome.ALREADY_LINKED
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
+class _HeldRename:
+ """A real rename that waits inside the locked section until released.
+
+ It counts renames that happened, not attempts: under load a scanner can
+ refuse the first try for a moment, and the engine then tries again.
+ """
+
+ def __init__(self) -> None:
+ self.entered = threading.Event()
+ self.release = threading.Event()
+ self.renamed = 0
+
+ def __call__(self, source: Path, target: Path) -> None:
+ self.entered.set()
+ assert self.release.wait(timeout=30)
+ os.rename(source, target)
+ self.renamed += 1
+
+
[email protected]("linkable")
+def test_a_second_migrator_only_resolves_while_the_first_is_moving(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ files = _populate(legacy)
+ held = _HeldRename()
+ outcomes: list[DirectoryOutcome] = []
+ first = threading.Thread(
+ target=lambda: outcomes.append(migrate_directory(legacy, current, rename=held).outcome)
+ )
+ first.start()
+ try:
+ assert held.entered.wait(timeout=30)
+ second_renames: list[tuple[Path, Path]] = []
+
+ second = migrate_directory(
+ legacy, current, rename=lambda source, target: second_renames.append((source, target))
+ )
+
+ assert second.outcome is DirectoryOutcome.LOCK_BUSY
+ assert second.effective == legacy
+ assert second_renames == []
+ finally:
+ held.release.set()
+ first.join(timeout=30)
+
+ assert outcomes == [DirectoryOutcome.MIGRATED]
+ assert held.renamed == 1
+ assert _snapshot(current) == files
+ assert _names(home) == sorted([LEGACY_NAME, CURRENT_NAME])
+
+
[email protected]("linkable")
+def test_a_waiting_migrator_sees_the_finished_move(legacy: Path, current: Path) -> None:
+ _populate(legacy)
+ held = _HeldRename()
+ outcomes: dict[str, DirectoryOutcome] = {}
+ first = threading.Thread(
+ target=lambda: outcomes.update(
+ first=migrate_directory(legacy, current, rename=held).outcome
+ )
+ )
+ waiter = threading.Thread(
+ target=lambda: outcomes.update(
+ waiter=migrate_directory(legacy, current, wait_seconds=30).outcome
+ )
+ )
+ first.start()
+ try:
+ assert held.entered.wait(timeout=30)
+ waiter.start()
+ finally:
+ held.release.set()
+ first.join(timeout=30)
+ waiter.join(timeout=30)
+
+ assert outcomes == {
+ "first": DirectoryOutcome.MIGRATED,
+ "waiter": DirectoryOutcome.ALREADY_LINKED,
+ }
+ assert held.renamed == 1
+
+
[email protected]("linkable")
+def test_simultaneous_threads_rename_exactly_once(home: Path, legacy: Path, current: Path) -> None:
+ files = _populate(legacy)
+ contenders = 8
+ barrier = threading.Barrier(contenders)
+ guard = threading.Lock()
+ renames: list[tuple[Path, Path]] = []
+ outcomes: list[DirectoryOutcome] = []
+
+ def counting_rename(source: Path, target: Path) -> None:
+ os.rename(source, target)
+ with guard:
+ renames.append((source, target))
+
+ def contend() -> None:
+ barrier.wait(timeout=30)
+ outcome = migrate_directory(legacy, current, rename=counting_rename).outcome
+ with guard:
+ outcomes.append(outcome)
+
+ threads = [threading.Thread(target=contend) for _ in range(contenders)]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join(timeout=60)
+
+ assert len(outcomes) == contenders
+ assert len(renames) == 1
+ assert outcomes.count(DirectoryOutcome.MIGRATED) == 1
+ # Everyone else either lost the lock or arrived after the move.
+ assert set(outcomes) <= {
+ DirectoryOutcome.MIGRATED,
+ DirectoryOutcome.LOCK_BUSY,
+ DirectoryOutcome.ALREADY_LINKED,
+ }
+ assert _snapshot(current) == files
+ assert os.path.samefile(legacy, current)
+ _assert_tidy_after_the_next_start(home, legacy, current)
+
+
[email protected]("linkable")
+def test_simultaneous_processes_rename_exactly_once(
+ tmp_path: Path,
+ home: Path,
+ legacy: Path,
+ current: Path,
+ child: Callable[..., subprocess.Popen[str]],
+) -> None:
+ files = _populate(legacy)
+ go = tmp_path / "go"
+ processes = [child("race", legacy, current, go) for _ in range(4)]
+ # Every contender is up and spinning before any of them may start.
+ deadline = time.monotonic() + 60
+ while len(list(tmp_path.glob("go.ready.*"))) < len(processes):
+ assert time.monotonic() < deadline, "the contenders did not start"
+ time.sleep(0.01)
+
+ go.write_text("go", encoding="utf-8")
+ finished = [process.communicate(timeout=120) for process in processes]
+
+ assert [process.returncode for process in processes] == [0] * len(processes), finished
+ outcomes = [stdout.strip() for stdout, _ in finished]
+ assert outcomes.count(DirectoryOutcome.MIGRATED.value) == 1, outcomes
+ assert set(outcomes) <= {
+ DirectoryOutcome.MIGRATED.value,
+ DirectoryOutcome.LOCK_BUSY.value,
+ DirectoryOutcome.ALREADY_LINKED.value,
+ }
+ assert _snapshot(current) == files
+ assert os.path.samefile(legacy, current)
+ _assert_tidy_after_the_next_start(home, legacy, current)
+
+
+def test_an_unusable_journal_location_moves_nothing(
+ home: Path, legacy: Path, current: Path
+) -> None:
+ files = _populate(legacy)
+ blocker = home / "not-a-directory"
+ blocker.write_text("x", encoding="utf-8")
+ renames: list[tuple[Path, Path]] = []
+
+ result = migrate_directory(
+ legacy,
+ current,
+ lock_path=blocker / "journal",
+ rename=lambda source, target: renames.append((source, target)),
+ )
+
+ assert result.outcome is DirectoryOutcome.LOCK_UNAVAILABLE
+ assert result.effective == legacy
+ assert result.detail
+ assert renames == []
+ assert _snapshot(legacy) == files
+ assert not current.exists()
+
+
+# ----------------------------------------------------------------------
+# Importability
+# ----------------------------------------------------------------------
+
+
+def test_the_engine_imports_only_the_standard_library() -> None:
+ """The frozen runtime hook loads this file before the package exists."""
+ tree = ast.parse(MODULE_PATH.read_text(encoding="utf-8"))
+ imported: set[str] = set()
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import):
+ imported.update(alias.name.split(".")[0] for alias in node.names)
+ elif isinstance(node, ast.ImportFrom):
+ assert node.level == 0, "a relative import needs the package"
+ imported.add((node.module or "").split(".")[0])
+
+ assert imported <= set(sys.stdlib_module_names), imported - set(sys.stdlib_module_names)
+
+
+def test_the_engine_is_not_wired_into_the_runtime() -> None:
+ """Inert until the identity actually changes: nothing in the product imports it.
+
+ The change that switches the persistent identifiers wires the engine in
+ and deletes this test.
+ """
+ package = MODULE_PATH.parents[1]
+ importers = [
+ path.relative_to(package).as_posix()
+ for path in package.rglob("*.py")
+ if path != MODULE_PATH and "identity_migration" in path.read_text(encoding="utf-8")
+ ]
+
+ assert importers == []
+
+
+# ----------------------------------------------------------------------
+# Keyring migration
+# ----------------------------------------------------------------------
+
+LEGACY_SERVICE = "old-name"
+CURRENT_SERVICE = "new-name"
+KNOWN_KEYS = ("alpha_api_key", "beta_api_key", "control_api_key", "gamma_oauth_client_id")
+
+
+def _migrate(backend: FakeKeyringBackend, keys: tuple[str, ...] = KNOWN_KEYS):
+ return migrate_keyring(
+ backend, legacy_service=LEGACY_SERVICE, current_service=CURRENT_SERVICE, keys=keys
+ )
+
+
+def _backend_with(**legacy_entries: str) -> FakeKeyringBackend:
+ backend = FakeKeyringBackend()
+ for key, value in legacy_entries.items():
+ backend.entries[(LEGACY_SERVICE, key)] = value
+ return backend
+
+
+def test_every_known_key_is_copied_and_the_legacy_entries_stay() -> None:
+ secrets = {key: f"value-of-{key}" for key in KNOWN_KEYS}
+ backend = _backend_with(**secrets)
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.MIGRATED
+ assert result.copied == KNOWN_KEYS
+ assert result.kept == ()
+ assert result.failed == ()
+ assert result.marker_written is True
+ marker = keyring_marker_key(LEGACY_SERVICE)
+ assert backend.service(CURRENT_SERVICE) == {**secrets, marker: "1"}
+ # The way back: the legacy service is exactly as it was.
+ assert backend.service(LEGACY_SERVICE) == secrets
+ assert not [call for call in backend.calls if call[0] == "delete"]
+
+
+def test_a_value_already_under_the_current_service_is_not_overwritten() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha", beta_api_key="legacy-beta")
+ backend.entries[(CURRENT_SERVICE, "alpha_api_key")] = "newer-alpha"
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.MIGRATED
+ assert result.copied == ("beta_api_key",)
+ assert result.kept == ("alpha_api_key",)
+ assert backend.entries[(CURRENT_SERVICE, "alpha_api_key")] == "newer-alpha"
+ assert backend.entries[(CURRENT_SERVICE, "beta_api_key")] == "legacy-beta"
+
+
+def test_the_marker_makes_it_run_once() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha")
+ _migrate(backend)
+ # After the migration the user deletes the key in the app, and an old
+ # version writes a different one under the legacy name.
+ del backend.entries[(CURRENT_SERVICE, "alpha_api_key")]
+ backend.entries[(LEGACY_SERVICE, "beta_api_key")] = "written-later"
+ backend.calls.clear()
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.ALREADY_MIGRATED
+ assert result.copied == ()
+ assert backend.service(CURRENT_SERVICE) == {keyring_marker_key(LEGACY_SERVICE): "1"}
+ # One read of the marker and nothing else: no per-key prompt on any OS.
+ assert backend.calls == [("get", CURRENT_SERVICE, keyring_marker_key(LEGACY_SERVICE))]
+
+
+def test_a_key_missing_from_the_list_is_not_migrated() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha", unlisted_key="left-behind")
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.MIGRATED
+ assert result.copied == ("alpha_api_key",)
+ assert (CURRENT_SERVICE, "unlisted_key") not in backend.entries
+ assert backend.entries[(LEGACY_SERVICE, "unlisted_key")] == "left-behind"
+
+
+def test_absent_and_empty_legacy_entries_are_skipped() -> None:
+ backend = _backend_with(alpha_api_key="", beta_api_key="legacy-beta")
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.MIGRATED
+ assert result.copied == ("beta_api_key",)
+ assert set(backend.service(CURRENT_SERVICE)) == {
+ "beta_api_key",
+ keyring_marker_key(LEGACY_SERVICE),
+ }
+
+
+def test_nothing_to_copy_still_writes_the_marker() -> None:
+ backend = FakeKeyringBackend()
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.MIGRATED
+ assert result.copied == ()
+ assert backend.service(CURRENT_SERVICE) == {keyring_marker_key(LEGACY_SERVICE): "1"}
+
+
+def test_a_duplicated_key_is_handled_once() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha")
+
+ result = _migrate(backend, keys=("alpha_api_key", "alpha_api_key"))
+
+ assert result.copied == ("alpha_api_key",)
+
+
+def test_a_failed_key_leaves_no_marker_and_is_retried() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha", beta_api_key="legacy-beta")
+ backend.fail_on.add(("set", CURRENT_SERVICE, "alpha_api_key"))
+
+ first = _migrate(backend)
+
+ assert first.outcome is KeyringOutcome.INCOMPLETE
+ assert first.failed == ("alpha_api_key",)
+ assert first.copied == ("beta_api_key",)
+ assert first.marker_written is False
+ assert keyring_marker_key(LEGACY_SERVICE) not in backend.service(CURRENT_SERVICE)
+
+ backend.fail_on.clear()
+ second = _migrate(backend)
+
+ assert second.outcome is KeyringOutcome.MIGRATED
+ assert second.copied == ("alpha_api_key",)
+ assert second.kept == ("beta_api_key",)
+ assert backend.entries[(CURRENT_SERVICE, "alpha_api_key")] == "legacy-alpha"
+
+
+def test_an_unreadable_legacy_key_counts_as_failed() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha", beta_api_key="legacy-beta")
+ backend.fail_on.add(("get", LEGACY_SERVICE, "alpha_api_key"))
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.INCOMPLETE
+ assert result.failed == ("alpha_api_key",)
+ assert result.copied == ("beta_api_key",)
+
+
+def test_an_unwritten_marker_only_costs_a_second_pass() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha")
+ backend.fail_on.add(("set", CURRENT_SERVICE, keyring_marker_key(LEGACY_SERVICE)))
+
+ first = _migrate(backend)
+ backend.fail_on.clear()
+ second = _migrate(backend)
+
+ assert first.outcome is KeyringOutcome.INCOMPLETE
+ assert first.copied == ("alpha_api_key",)
+ assert second.outcome is KeyringOutcome.MIGRATED
+ assert second.copied == ()
+ assert second.kept == ("alpha_api_key",)
+
+
+def test_a_store_that_keeps_nothing_is_not_taken_for_done() -> None:
+ backend = FakeKeyringBackend(drop_writes=True)
+ backend.entries[(LEGACY_SERVICE, "alpha_api_key")] = "legacy-alpha"
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.INCOMPLETE
+ assert result.failed == ("alpha_api_key",)
+ assert result.copied == ()
+ assert result.marker_written is False
+
+
+def test_an_unwritable_marker_on_an_empty_store_is_not_taken_for_done() -> None:
+ result = _migrate(FakeKeyringBackend(drop_writes=True))
+
+ assert result.outcome is KeyringOutcome.INCOMPLETE
+ assert result.marker_written is False
+
+
+def test_an_unavailable_credential_store_changes_nothing() -> None:
+ backend = FakeKeyringBackend(unavailable=True)
+ backend.entries[(LEGACY_SERVICE, "alpha_api_key")] = "legacy-alpha"
+
+ result = _migrate(backend)
+
+ assert result.outcome is KeyringOutcome.UNAVAILABLE
+ assert backend.entries == {(LEGACY_SERVICE, "alpha_api_key"): "legacy-alpha"}
+
+
+def test_the_same_service_needs_no_migration() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha")
+
+ result = migrate_keyring(
+ backend, legacy_service=LEGACY_SERVICE, current_service=LEGACY_SERVICE, keys=KNOWN_KEYS
+ )
+
+ assert result.outcome is KeyringOutcome.NOT_NEEDED
+ assert backend.calls == []
+
+
+def test_each_legacy_service_has_its_own_marker() -> None:
+ backend = _backend_with(alpha_api_key="legacy-alpha")
+ backend.entries[("older-name", "beta_api_key")] = "older-beta"
+
+ first = _migrate(backend)
+ second = migrate_keyring(
+ backend, legacy_service="older-name", current_service=CURRENT_SERVICE, keys=KNOWN_KEYS
+ )
+
+ assert first.outcome is KeyringOutcome.MIGRATED
+ assert second.outcome is KeyringOutcome.MIGRATED
+ assert second.copied == ("beta_api_key",)
+ assert backend.entries[(CURRENT_SERVICE, "alpha_api_key")] == "legacy-alpha"
+ assert backend.entries[(CURRENT_SERVICE, "beta_api_key")] == "older-beta"
+
+
+def test_no_secret_value_reaches_the_result_or_a_log_line(
+ caplog: pytest.LogCaptureFixture,
+) -> None:
+ """The fake quotes the refused value in its error, as a real store may."""
+ backend = _backend_with(alpha_api_key="sk-very-secret", beta_api_key="sk-also-secret")
+ backend.fail_on.add(("set", CURRENT_SERVICE, "beta_api_key"))
+
+ with caplog.at_level("DEBUG"):
+ result = _migrate(backend)
+
+ assert result.failed == ("beta_api_key",)
+ assert "secret" not in repr(result)
+ assert "secret" not in caplog.text
+ assert "beta_api_key" in caplog.text