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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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