Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

51.9 KB
Raw Blame
from __future__ import annotations

import errno
import multiprocessing
import os
import stat
import sys
import threading
import time
import tracemalloc
from collections.abc import Callable, Iterator
from contextlib import contextmanager
from multiprocessing.synchronize import Event
from pathlib import Path
from types import ModuleType
from typing import ClassVar, final
from uuid import UUID

import pytest

from local_deep_research.database import rekey_lock as rekey_lock_module
from local_deep_research.database.rekey_lock import (
    RekeyEpochState,
    RekeyLockContentionError,
    RekeyRecoveryRequiredError,
    _acquire_windows_lock,
    _release_windows_lock,
    acquire_rekey_lock,
    begin_rekey_epoch,
    clear_pending_rekey_epoch,
    commit_rekey_epoch,
    read_rekey_epoch_state,
)


def _hold_rekey_lock(
    db_path: str,
    acquired: Event,
    release: Event,
) -> None:
    with acquire_rekey_lock(Path(db_path)):
        acquired.set()
        if not release.wait(timeout=10):
            raise RuntimeError("parent did not release rekey-lock worker")


def _assert_sidecar_io_error(
    error: rekey_lock_module.RekeySidecarIOError,
    db_path: Path,
    operation: rekey_lock_module.RekeySidecarOperation,
) -> None:
    assert error.db_path == db_path
    assert error.operation is operation
    assert error.errno == errno.EIO
    assert error.__context__ is None
    assert str(db_path) not in str(error)
    assert "sensitive raw OS text" not in str(error)


class _ProtectedBodyError(Exception):
    pass


def test_rekey_lock_contends_across_processes(tmp_path: Path) -> None:
    # Given a separate process holding this database's sidecar lock
    db_path = tmp_path / "user.db"
    context = multiprocessing.get_context("spawn")
    acquired = context.Event()
    release = context.Event()
    process = context.Process(
        target=_hold_rekey_lock,
        args=(str(db_path), acquired, release),
    )
    process.start()

    try:
        assert acquired.wait(timeout=10), "child did not acquire the rekey lock"

        # When this process attempts the same nonblocking lock
        with pytest.raises(RekeyLockContentionError):
            with acquire_rekey_lock(db_path):
                pytest.fail("contended rekey lock was acquired")
    finally:
        release.set()
        process.join(timeout=10)
        if process.is_alive():
            process.terminate()
            process.join(timeout=5)

    # Then only the child acquired it and exited cleanly
    assert process.exitcode == 0


def _os_lock_attempt_name() -> str:
    return "_acquire_windows_lock" if os.name == "nt" else "_acquire_posix_lock"


def test_contention_retry_rides_out_a_holder_that_releases_in_the_window(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given another process holding the sidecar lock, which it releases only
    # once this process has already been refused at least once
    db_path = tmp_path / "user.db"
    context = multiprocessing.get_context("spawn")
    acquired = context.Event()
    release = context.Event()
    process = context.Process(
        target=_hold_rekey_lock,
        args=(str(db_path), acquired, release),
    )
    process.start()
    attempt_name = _os_lock_attempt_name()
    real_attempt = getattr(rekey_lock_module, attempt_name)
    refusals = 0

    def attempt_then_release_holder(*args: object, **kwargs: object) -> None:
        nonlocal refusals
        try:
            real_attempt(*args, **kwargs)
        except RekeyLockContentionError:
            refusals += 1
            release.set()
            raise

    monkeypatch.setattr(
        rekey_lock_module, attempt_name, attempt_then_release_holder
    )

    try:
        assert acquired.wait(timeout=10), "child did not acquire the rekey lock"

        # When this process takes the lock with a generous retry window
        with acquire_rekey_lock(db_path, contention_retry=30.0):
            held_here = True
    finally:
        release.set()
        process.join(timeout=10)
        if process.is_alive():
            process.terminate()
            process.join(timeout=5)

    # Then it was refused while the holder lived and acquired once released
    assert held_here
    assert refusals >= 1
    assert process.exitcode == 0


def test_contention_retry_gives_up_on_a_holder_beyond_the_window(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given another process holding the sidecar lock for longer than the window
    db_path = tmp_path / "user.db"
    context = multiprocessing.get_context("spawn")
    acquired = context.Event()
    release = context.Event()
    process = context.Process(
        target=_hold_rekey_lock,
        args=(str(db_path), acquired, release),
    )
    process.start()
    attempt_name = _os_lock_attempt_name()
    real_attempt = getattr(rekey_lock_module, attempt_name)
    attempts = 0

    def counting_attempt(*args: object, **kwargs: object) -> None:
        nonlocal attempts
        attempts += 1
        real_attempt(*args, **kwargs)

    monkeypatch.setattr(rekey_lock_module, attempt_name, counting_attempt)
    window = 0.5

    try:
        assert acquired.wait(timeout=10), "child did not acquire the rekey lock"

        # When this process retries the nonblocking lock for the window
        started = time.monotonic()
        with pytest.raises(RekeyLockContentionError):
            with acquire_rekey_lock(db_path, contention_retry=window):
                pytest.fail("lock held by another process was acquired")
        elapsed = time.monotonic() - started
    finally:
        release.set()
        process.join(timeout=10)
        if process.is_alive():
            process.terminate()
            process.join(timeout=5)

    # Then it kept retrying for the whole window and then failed as contention
    assert elapsed >= window
    assert elapsed < window + 5
    assert attempts > 1
    assert process.exitcode == 0


@contextmanager
def _flock_held_by_another_descriptor(db_path: Path) -> Iterator[None]:
    # A second open file description of the sidecar: flock makes it contend
    # with this process's own descriptor exactly as another process's
    # would, and it never takes this process's gate, like a foreign holder.
    import fcntl

    fd = os.open(
        db_path.with_name(f"{db_path.name}.rekey.lock"),
        os.O_RDWR | os.O_CREAT,
        0o600,
    )
    try:
        fcntl.flock(fd, fcntl.LOCK_EX)
        yield
    finally:
        os.close(fd)


@pytest.mark.skipif(os.name == "nt", reason="POSIX flock required")
def test_timeout_gives_up_on_a_flock_holder_after_the_bound(
    tmp_path: Path,
) -> None:
    # Given a holder that does not release on its own (another process's
    # rekey of a large database, a stopped process, a hung mount)
    db_path = tmp_path / "user.db"
    bound = 0.3
    with _flock_held_by_another_descriptor(db_path):
        # When a request-path caller takes the sidecar with a timeout
        started = time.monotonic()
        with pytest.raises(RekeyLockContentionError):
            with acquire_rekey_lock(db_path, timeout=bound):
                pytest.fail("a flock held elsewhere was acquired")
        elapsed = time.monotonic() - started

    # Then it retried for the whole bound and gave up as typed contention
    assert bound <= elapsed < bound + 5
    # and the same bounded acquisition succeeds once the holder is gone
    with acquire_rekey_lock(db_path, timeout=bound):
        pass


def test_timeout_bounds_the_wait_for_an_in_process_holder(
    tmp_path: Path,
) -> None:
    # Given another thread of this process holding the sidecar, so the
    # in-process gate as well, until the test lets it go
    db_path = tmp_path / "user.db"
    bound = 0.3
    acquired = threading.Event()
    release = threading.Event()

    def hold() -> None:
        with acquire_rekey_lock(db_path):
            acquired.set()
            release.wait(timeout=30)

    holder = threading.Thread(target=hold, daemon=True)
    holder.start()
    try:
        assert acquired.wait(timeout=10), "holder never took the sidecar"
        # When a request-path caller takes the sidecar with a timeout
        started = time.monotonic()
        with pytest.raises(RekeyLockContentionError):
            with acquire_rekey_lock(db_path, timeout=bound):
                pytest.fail("the gate held by another thread was acquired")
        elapsed = time.monotonic() - started
    finally:
        release.set()
        holder.join(timeout=10)

    # Then the gate wait was bounded the same way
    assert not holder.is_alive()
    assert bound <= elapsed < bound + 5


def test_rekey_lock_sidecar_is_persistent_and_owner_only(
    tmp_path: Path,
) -> None:
    # Given a database path without a sidecar
    db_path = tmp_path / "user.db"
    lock_path = tmp_path / "user.db.rekey.lock"

    # When the rekey lock is acquired and released
    with acquire_rekey_lock(db_path):
        assert lock_path.exists()
        original_inode = lock_path.stat().st_ino

    with acquire_rekey_lock(db_path):
        rekey_lock_module.advance_rekey_epoch(db_path)

    # Then the owner-only sidecar remains for future lock acquisitions
    assert lock_path.exists()
    assert lock_path.stat().st_ino == original_inode
    if os.name != "nt":
        assert stat.S_IMODE(lock_path.stat().st_mode) == 0o600


def test_rekey_lock_chmod_failure_is_best_effort(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given a filesystem that rejects permission changes
    db_path = tmp_path / "user.db"

    def fail_chmod(_path_or_fd: str | Path | int, _mode: int) -> None:
        raise OSError(errno.EPERM, "chmod unsupported")

    monkeypatch.setattr(os, "chmod", fail_chmod)
    # The sidecar mode is tightened through its fd (never by path).
    monkeypatch.setattr(os, "fchmod", fail_chmod, raising=False)

    # When the stable lock is acquired, then chmod cannot abort locking
    with acquire_rekey_lock(db_path):
        assert db_path.with_name("user.db.rekey.lock").exists()


@pytest.mark.skipif(
    not hasattr(os, "O_NOFOLLOW"), reason="O_NOFOLLOW unavailable"
)
def test_symlinked_rekey_lock_sidecar_is_refused(tmp_path: Path) -> None:
    # Given a symlink planted at the sidecar name, pointing at another file
    db_path = tmp_path / "user.db"
    target = tmp_path / "unrelated.txt"
    target.write_text("unrelated\n", encoding="utf-8")
    os.chmod(target, 0o644)
    db_path.with_name("user.db.rekey.lock").symlink_to(target)

    # When the stable lock is acquired, then the link is refused, typed
    with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
        with acquire_rekey_lock(db_path):
            pytest.fail("sidecar lock acquired through a symlink")

    # And neither the open nor the permission tightening reached the target
    assert (
        raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
    )
    assert raised.value.errno == errno.ELOOP
    assert "symlink" in str(raised.value)
    assert stat.S_IMODE(target.stat().st_mode) == 0o644
    assert target.read_text(encoding="utf-8") == "unrelated\n"


@pytest.mark.skipif(
    os.name == "nt" or not hasattr(os, "link"),
    reason="POSIX hard links required",
)
def test_hard_linked_sidecar_is_locked_without_touching_its_mode(
    tmp_path: Path,
) -> None:
    # Given a hard link at the sidecar name whose other name is outside the
    # sidecar's directory (a backup or snapshot tool that hard-links the
    # data directory into another one)
    data_dir = tmp_path / "encrypted_databases"
    data_dir.mkdir()
    snapshot_dir = tmp_path / "snapshot"
    snapshot_dir.mkdir()
    db_path = data_dir / "user.db"
    target = snapshot_dir / "unrelated.txt"
    target.write_text("unrelated\n", encoding="utf-8")
    os.chmod(target, 0o644)
    os.link(target, db_path.with_name("user.db.rekey.lock"))

    # When the sidecar is opened for the rekey lock
    entered = False
    with acquire_rekey_lock(db_path):
        entered = True

    # Then the lock is taken (no lockout), and the linked file keeps its
    # mode and content
    assert entered
    assert stat.S_IMODE(target.stat().st_mode) == 0o644
    assert target.read_text(encoding="utf-8") == "unrelated\n"


@pytest.mark.skipif(
    os.name == "nt" or not hasattr(os, "link"),
    reason="POSIX hard links required",
)
def test_hard_linked_sidecar_is_refused_unopened_when_directory_scan_fails(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given an external hard link distinct from the real DB, WAL and shm,
    # so classification must reach the directory scan to rule out aliases.
    data_dir = tmp_path / "encrypted_databases"
    data_dir.mkdir()
    snapshot_dir = tmp_path / "snapshot"
    snapshot_dir.mkdir()
    db_path = data_dir / "user.db"
    database_identities = set()
    for suffix in ("", "-wal", "-shm"):
        path = db_path.with_name(f"user.db{suffix}")
        path.write_bytes(f"database{suffix}".encode())
        status = path.stat()
        database_identities.add((status.st_dev, status.st_ino))
    assert len(database_identities) == 3
    target = snapshot_dir / "unrelated.txt"
    original_bytes = b"unrelated\n"
    target.write_bytes(original_bytes)
    target.chmod(0o644)
    sidecar = db_path.with_name("user.db.rekey.lock")
    os.link(target, sidecar)
    original = target.stat()
    identity = (original.st_dev, original.st_ino)
    original_mode = stat.S_IMODE(original.st_mode)
    assert original.st_nlink >= 2
    assert identity not in database_identities
    linked = sidecar.stat()
    assert (linked.st_dev, linked.st_ino) == identity
    assert linked.st_nlink == original.st_nlink

    real_scandir = os.scandir
    real_open = os.open
    scan_attempts: list[object] = []
    open_attempts: list[str] = []

    def denied_scandir(path):
        scan_attempts.append(path)
        if path == data_dir:
            raise PermissionError(
                errno.EACCES, "synthetic unlistable directory"
            )
        return real_scandir(path)

    def recording_open(path, *args, **kwargs):
        open_attempts.append(os.fspath(path))
        return real_open(path, *args, **kwargs)

    # The authorization-lease sidecar main also covered here was removed
    # with its unused API (#6750); the rekey lock is the only sidecar.
    acquire = acquire_rekey_lock(db_path)
    entered = False
    refusal = None
    # Only the exact lock parent is unlistable; all opens remain real.
    with monkeypatch.context() as scoped:
        scoped.setattr(os, "scandir", denied_scandir)
        scoped.setattr(os, "open", recording_open)
        try:
            with acquire:
                entered = True
        except rekey_lock_module.RekeySidecarIOError as error:
            refusal = error

    # Cleanup and assertions run after restoring filesystem operations.
    assert data_dir in scan_attempts
    assert not entered, "protected body entered despite an unlistable directory"
    assert os.fspath(sidecar) not in open_attempts
    assert os.fspath(target) not in open_attempts
    assert isinstance(refusal, rekey_lock_module.RekeySidecarIOError)
    assert refusal.operation is rekey_lock_module.RekeySidecarOperation.OPEN
    assert refusal.errno == errno.EMLINK
    assert refusal.db_path == db_path
    for path in (sidecar, target):
        status = path.stat()
        assert (status.st_dev, status.st_ino) == identity
        assert status.st_nlink == original.st_nlink
        assert stat.S_IMODE(status.st_mode) == original_mode
        assert path.read_bytes() == original_bytes


@pytest.mark.skipif(
    os.name == "nt" or not hasattr(os, "link"),
    reason="POSIX hard links required",
)
@pytest.mark.parametrize("victim_suffix", ["", "-wal", "-shm"])
def test_sidecar_hard_linked_to_another_users_database_is_refused_unopened(
    tmp_path: Path, victim_suffix: str, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given this user's lock file hard-linked to ANOTHER user's database
    # file in the same directory
    db_path = tmp_path / "ldr_user_attacker.db"
    db_path.write_bytes(b"attacker")
    victim = tmp_path / f"ldr_user_victim.db{victim_suffix}"
    victim.write_bytes(b"victim database")
    lock_path = db_path.with_name(f"{db_path.name}.rekey.lock")
    os.link(victim, lock_path)
    real_open = os.open
    opened: list[str] = []

    def spy_open(path, *args, **kwargs):
        opened.append(os.fspath(path))
        return real_open(path, *args, **kwargs)

    monkeypatch.setattr(rekey_lock_module.os, "open", spy_open)

    # When the rekey lock is taken
    with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
        with acquire_rekey_lock(db_path):
            pytest.fail("sidecar lock acquired through another user's file")

    # Then it is refused, typed, and the victim's inode is never opened
    assert raised.value.errno == errno.EMLINK
    assert (
        raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
    )
    assert os.fspath(lock_path) not in opened
    assert os.fspath(victim) not in opened
    assert victim.read_bytes() == b"victim database"


def test_plain_sidecar_is_locked(tmp_path: Path) -> None:
    # Given an ordinary database directory with no links
    db_path = tmp_path / "user.db"
    db_path.write_bytes(b"database")
    (tmp_path / "other.db").write_bytes(b"other")

    # When the rekey lock is taken twice (created, then reused)
    for _ in range(2):
        with acquire_rekey_lock(db_path):
            pass

    # Then it is a single-link regular file owned by the sidecar name
    status = db_path.with_name("user.db.rekey.lock").stat()
    assert status.st_nlink == 1
    assert stat.S_ISREG(status.st_mode)


@pytest.mark.skipif(
    os.name == "nt" or not hasattr(os, "link"),
    reason="POSIX hard links required",
)
@pytest.mark.parametrize("database_suffix", ["", "-wal", "-shm"])
def test_sidecar_hard_linked_to_the_database_is_refused_unopened(
    tmp_path: Path, database_suffix: str, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given the lock file hard-linked to the database, its WAL or its shm
    db_path = tmp_path / "user.db"
    db_path.write_bytes(b"database")
    target = db_path.with_name(f"user.db{database_suffix}")
    if database_suffix:
        target.write_bytes(b"sidecar")
    lock_path = db_path.with_name("user.db.rekey.lock")
    os.link(target, lock_path)
    real_open = os.open
    opened: list[str] = []

    def spy_open(path, *args, **kwargs):
        opened.append(os.fspath(path))
        return real_open(path, *args, **kwargs)

    monkeypatch.setattr(rekey_lock_module.os, "open", spy_open)

    # When the rekey lock is taken
    with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
        with acquire_rekey_lock(db_path):
            pytest.fail("sidecar lock acquired through a link to the database")

    # Then it is refused, typed, without ever opening (and so closing) a
    # descriptor to the database file
    assert raised.value.errno == errno.EMLINK
    assert (
        raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
    )
    assert os.fspath(lock_path) not in opened


@pytest.mark.skipif(
    os.name == "nt" or not hasattr(os, "mkfifo"),
    reason="POSIX FIFOs required",
)
def test_non_regular_sidecar_is_refused_and_its_fd_closed(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given a FIFO planted at the sidecar name
    db_path = tmp_path / "user.db"
    sidecar = db_path.with_name("user.db.rekey.lock")
    os.mkfifo(sidecar, 0o600)
    opened_fds: list[int] = []
    real_open = os.open

    def recording_open(path, flags, mode=0o777, *args, **kwargs):
        fd = real_open(path, flags, mode, *args, **kwargs)
        if Path(path) == sidecar:
            opened_fds.append(fd)
        return fd

    monkeypatch.setattr(rekey_lock_module.os, "open", recording_open)

    # When the sidecar is opened for the rekey lock
    with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
        with acquire_rekey_lock(db_path):
            pytest.fail("sidecar lock acquired on a FIFO")
    monkeypatch.undo()

    # Then the open is refused, typed, and the fd it opened is closed
    assert (
        raised.value.operation is rekey_lock_module.RekeySidecarOperation.OPEN
    )
    assert raised.value.errno == errno.EINVAL
    assert "non-regular" in str(raised.value)
    assert len(opened_fds) == 1
    with pytest.raises(OSError) as closed:
        os.fstat(opened_fds[0])
    assert closed.value.errno == errno.EBADF
    assert stat.S_ISFIFO(sidecar.lstat().st_mode)


def test_missing_epoch_is_invalid_until_repaired_under_lock(
    tmp_path: Path,
) -> None:
    # Given no durable epoch for an existing database path
    db_path = tmp_path / "user.db"
    assert rekey_lock_module.read_rekey_epoch(db_path) is None

    # When the caller repairs it while holding the stable sidecar lock
    with acquire_rekey_lock(db_path):
        epoch = rekey_lock_module.read_or_initialize_rekey_epoch(db_path)

    # Then the persisted token is a canonical lowercase UUID
    assert str(UUID(epoch)) == epoch
    assert rekey_lock_module.read_rekey_epoch(db_path) == epoch


def test_rekey_epoch_pending_commit_and_cleanup_are_explicit(
    tmp_path: Path,
) -> None:
    # Given a stable committed epoch
    db_path = tmp_path / "user.db"
    with acquire_rekey_lock(db_path):
        committed_epoch = rekey_lock_module.read_or_initialize_rekey_epoch(
            db_path
        )

        # When a candidate is begun but not yet committed
        pending_epoch = begin_rekey_epoch(db_path)
        assert str(UUID(pending_epoch)) == pending_epoch
        if os.name != "nt":
            pending_path = db_path.with_name("user.db.rekey.pending")
            assert stat.S_IMODE(pending_path.stat().st_mode) == 0o600

        # Then cache projection fails closed while full state remains recoverable
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            committed_epoch=committed_epoch,
            pending_epoch=pending_epoch,
        )
        assert rekey_lock_module.read_rekey_epoch(db_path) is None

        # When the candidate is committed, pending metadata remains explicit
        commit_rekey_epoch(db_path, pending_epoch)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            committed_epoch=pending_epoch,
            pending_epoch=pending_epoch,
        )
        assert rekey_lock_module.read_rekey_epoch(db_path) is None

        # When cleanup succeeds, the committed epoch becomes cache-visible
        clear_pending_rekey_epoch(db_path, pending_epoch)

    assert read_rekey_epoch_state(db_path) == RekeyEpochState(
        committed_epoch=pending_epoch,
        pending_epoch=None,
    )
    assert rekey_lock_module.read_rekey_epoch(db_path) == pending_epoch
    if os.name != "nt":
        pending_path = db_path.with_name("user.db.rekey.pending")
        epoch_path = db_path.with_name("user.db.rekey.epoch")
        assert not pending_path.exists()
        assert stat.S_IMODE(epoch_path.stat().st_mode) == 0o600


def test_malformed_epoch_fails_closed_under_lock(
    tmp_path: Path,
) -> None:
    # Given a malformed durable epoch
    db_path = tmp_path / "user.db"
    epoch_path = db_path.with_name("user.db.rekey.epoch")
    epoch_path.write_text("NOT-A-CANONICAL-UUID", encoding="ascii")
    # When the caller attempts to read or repair it under the lock
    with acquire_rekey_lock(db_path):
        with pytest.raises(RekeyRecoveryRequiredError):
            read_rekey_epoch_state(db_path)
        with pytest.raises(RekeyRecoveryRequiredError):
            rekey_lock_module.read_or_initialize_rekey_epoch(db_path)

    # Then malformed content is preserved for explicit operator recovery
    assert rekey_lock_module.read_rekey_epoch(db_path) is None
    assert epoch_path.read_text(encoding="ascii") == "NOT-A-CANONICAL-UUID"


def _commit_first_epoch(db_path: Path) -> str:
    with acquire_rekey_lock(db_path):
        return rekey_lock_module.read_or_initialize_rekey_epoch(db_path)


def _run_bounded(
    call: Callable[[], object], timeout: float = 5.0
) -> tuple[threading.Thread, dict[str, object]]:
    # Runs ``call`` on a daemon thread and waits at most ``timeout``, so a
    # read that hangs fails the test instead of the CI job.
    outcome: dict[str, object] = {}

    def target() -> None:
        try:
            outcome["value"] = call()
        except BaseException as error:  # noqa: BLE001 - handed to the test
            outcome["error"] = error

    worker = threading.Thread(target=target, daemon=True)
    worker.start()
    worker.join(timeout)
    return worker, outcome


def _release_fifo_reader(fifo: Path) -> None:
    # A reader blocked opening the FIFO is released by a writer that opens
    # and closes it; with no reader waiting the open fails (ENXIO) and
    # there is nothing to release.
    try:
        fd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK)
    except OSError:
        return
    os.close(fd)


@pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="POSIX FIFOs required")
@pytest.mark.parametrize("suffix", [".rekey.epoch", ".rekey.pending"])
@pytest.mark.parametrize("planted_kind", ["fifo", "directory"])
def test_a_non_regular_epoch_file_is_refused_without_reading_it(
    tmp_path: Path, suffix: str, planted_kind: str
) -> None:
    # Given a FIFO or a directory planted at an epoch file name
    db_path = tmp_path / "user.db"
    _commit_first_epoch(db_path)
    planted = db_path.with_name(f"user.db{suffix}")
    planted.unlink(missing_ok=True)
    if planted_kind == "fifo":
        os.mkfifo(planted, 0o600)
    else:
        planted.mkdir()

    # When the durable state is read under the sidecar, as every probe does
    def read_under_the_sidecar() -> RekeyEpochState:
        with acquire_rekey_lock(db_path):
            return read_rekey_epoch_state(db_path)

    worker, outcome = _run_bounded(read_under_the_sidecar)
    finished = not worker.is_alive()
    if planted_kind == "fifo":
        _release_fifo_reader(planted)
    worker.join(timeout=10)

    # Then it fails at once as "nothing was read", leaves the file alone
    # and releases the sidecar
    assert finished, "the epoch read waited on a planted FIFO under the flock"
    error = outcome.get("error")
    assert isinstance(error, rekey_lock_module.RekeyEpochUnreadableError), (
        outcome
    )
    assert error.errno == errno.EINVAL
    if planted_kind == "fifo":
        assert stat.S_ISFIFO(planted.lstat().st_mode)
    else:
        assert planted.is_dir()
    with acquire_rekey_lock(db_path):
        pass


@pytest.mark.skipif(os.name == "nt", reason="POSIX symlinks required")
@pytest.mark.parametrize("suffix", [".rekey.epoch", ".rekey.pending"])
def test_a_symlinked_epoch_file_is_refused_not_followed(
    tmp_path: Path, suffix: str
) -> None:
    # Given a link at an epoch file name to a file elsewhere holding the
    # committed token itself, so following the link would vouch for it
    db_path = tmp_path / "user.db"
    committed = _commit_first_epoch(db_path)
    target = tmp_path / "elsewhere" / "token"
    target.parent.mkdir()
    target.write_text(committed, encoding="ascii")
    link = db_path.with_name(f"user.db{suffix}")
    link.unlink(missing_ok=True)
    link.symlink_to(target)

    # When the durable state is read
    with pytest.raises(rekey_lock_module.RekeyEpochUnreadableError) as raised:
        read_rekey_epoch_state(db_path)

    # Then the link is refused (O_NOFOLLOW), and both files are left as found
    assert raised.value.errno == errno.ELOOP
    assert link.is_symlink()
    assert target.read_text(encoding="ascii") == committed


@pytest.mark.parametrize("suffix", [".rekey.epoch", ".rekey.pending"])
def test_an_oversized_epoch_file_is_refused_without_being_read(
    tmp_path: Path, suffix: str
) -> None:
    # Given a regular file far larger than a token at an epoch file name
    db_path = tmp_path / "user.db"
    _commit_first_epoch(db_path)
    size = 8 * 1024 * 1024
    db_path.with_name(f"user.db{suffix}").write_bytes(b"0" * size)

    # When the durable state is read
    was_tracing = tracemalloc.is_tracing()
    if not was_tracing:
        tracemalloc.start()
    try:
        tracemalloc.reset_peak()
        baseline, _ = tracemalloc.get_traced_memory()
        with pytest.raises(RekeyRecoveryRequiredError) as raised:
            read_rekey_epoch_state(db_path)
        _, peak = tracemalloc.get_traced_memory()
    finally:
        if not was_tracing:
            tracemalloc.stop()

    # Then it does not vouch, like any malformed token (it is not an
    # unreadable file), and was refused without being read into memory
    assert not isinstance(
        raised.value, rekey_lock_module.RekeyEpochUnreadableError
    )
    assert peak - baseline < size // 8


@pytest.mark.parametrize(
    ("error_number", "tolerated"),
    [
        pytest.param(errno.EIO, False, id="EIO-real-failure"),
        pytest.param(errno.EINVAL, True, id="EINVAL-unsupported"),
    ],
)
def test_pending_transition_directory_fsync_failure_fails_closed(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
    error_number: int,
    tolerated: bool,
) -> None:
    """A directory-fsync error during pending publication is classified.

    ``_sync_parent_directory`` treats the errnos a filesystem uses to say
    "directory fsync is not supported here" (EINVAL, ENOTSUP/EOPNOTSUPP,
    ENOSYS) as "as durable as this filesystem allows", because treating
    them as fatal made every epoch publication fail on such mounts. A real
    failure (EIO) still propagates. This test originally asserted that
    EINVAL raised; that predates the tolerance and contradicted the
    documented behaviour (and
    ``test_unsupported_directory_fsync_does_not_fail_epoch_publication``),
    so it now pins both sides on the pending transition: the real failure
    fails closed with the visible pending file still fencing caches, and
    the unsupported errno publishes the pending epoch normally.
    """
    if os.name == "nt":
        pytest.skip("directory fsync is skipped entirely on Windows")
    # Given a stable epoch and a filesystem whose directory fsync errors
    db_path = tmp_path / "user.db"
    with acquire_rekey_lock(db_path):
        committed_epoch = rekey_lock_module.read_or_initialize_rekey_epoch(
            db_path
        )
    real_fsync = os.fsync

    def fail_directory_fsync(fd: int) -> None:
        if stat.S_ISDIR(os.fstat(fd).st_mode):
            raise OSError(error_number, "directory fsync error")
        real_fsync(fd)

    monkeypatch.setattr(os, "fsync", fail_directory_fsync)

    # When pending publication cannot synchronize its parent directory
    with acquire_rekey_lock(db_path):
        if tolerated:
            pending_epoch = begin_rekey_epoch(db_path)
        else:
            with pytest.raises(OSError) as raised:
                begin_rekey_epoch(db_path)
            assert raised.value.errno == error_number

    # Then E1 is preserved and the pending file fences caches either way
    state = read_rekey_epoch_state(db_path)
    assert state.committed_epoch == committed_epoch
    assert state.pending_epoch is not None
    if tolerated:
        assert state.pending_epoch == pending_epoch
    assert rekey_lock_module.read_rekey_epoch(db_path) is None


def test_epoch_replace_failure_aborts_without_accepting_partial_state(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given an epoch replacement that the filesystem refuses
    db_path = tmp_path / "user.db"
    epoch_path = db_path.with_name("user.db.rekey.epoch")

    def fail_replace(source: str | Path, _target: str | Path) -> None:
        if os.name != "nt":
            assert stat.S_IMODE(Path(source).stat().st_mode) == 0o600
        raise OSError(errno.EIO, "replace failed")

    monkeypatch.setattr(os, "replace", fail_replace)

    # When repair attempts the atomic replace, then the write failure propagates
    with acquire_rekey_lock(db_path):
        with pytest.raises(OSError, match="replace failed"):
            rekey_lock_module.read_or_initialize_rekey_epoch(db_path)

    assert not epoch_path.exists()


def test_pending_without_committed_epoch_fails_closed(tmp_path: Path) -> None:
    # Given a canonical pending epoch without committed metadata
    db_path = tmp_path / "user.db"
    pending_path = db_path.with_name("user.db.rekey.pending")
    pending_path.write_text(str(UUID(int=1)), encoding="ascii")

    # When state is read, then the contradictory transition requires recovery
    with pytest.raises(RekeyRecoveryRequiredError):
        read_rekey_epoch_state(db_path)
    assert rekey_lock_module.read_rekey_epoch(db_path) is None


def test_posix_noncontention_error_is_typed(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    if os.name == "nt":
        pytest.skip("POSIX backend test")

    # Given flock reports an unrelated I/O error
    import fcntl

    def fail_flock(_fd: int, _operation: int) -> None:
        raise OSError(errno.EIO, "simulated I/O failure")

    monkeypatch.setattr(fcntl, "flock", fail_flock)

    # When the sidecar lock is acquired, then the I/O failure is normalized
    with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
        with acquire_rekey_lock(tmp_path / "user.db"):
            pytest.fail("lock unexpectedly acquired")

    _assert_sidecar_io_error(
        raised.value,
        tmp_path / "user.db",
        rekey_lock_module.RekeySidecarOperation.ACQUIRE,
    )
    assert not isinstance(raised.value, RekeyLockContentionError)


def test_sidecar_open_failure_is_typed(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given sidecar creation fails with raw operating-system text
    db_path = tmp_path / "user.db"

    def fail_open(_path: Path, _flags: int, _mode: int) -> int:
        raise OSError(errno.EIO, "sensitive raw OS text")

    # When the existing rekey lock opens its persistent sidecar
    with monkeypatch.context() as scoped:
        scoped.setattr(os, "open", fail_open)
        with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
            with acquire_rekey_lock(db_path):
                pytest.fail("sidecar unexpectedly opened")

    # Then the failure carries only typed safe diagnostics
    _assert_sidecar_io_error(
        raised.value,
        db_path,
        rekey_lock_module.RekeySidecarOperation.OPEN,
    )


def test_sidecar_acquire_failure_is_typed(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given the platform backend reports a non-contention acquisition failure
    db_path = tmp_path / "user.db"
    acquire_name = (
        "_acquire_windows_lock" if os.name == "nt" else "_acquire_posix_lock"
    )

    def fail_acquire(
        _fd: int,
        _lock_path: Path,
        *,
        blocking: bool = False,
    ) -> None:
        raise OSError(errno.EIO, "sensitive raw OS text")

    # When the existing rekey lock acquires its sidecar
    with monkeypatch.context() as scoped:
        scoped.setattr(rekey_lock_module, acquire_name, fail_acquire)
        with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
            with acquire_rekey_lock(db_path):
                pytest.fail("sidecar lock unexpectedly acquired")

    # Then acquisition exposes only the typed sidecar failure
    _assert_sidecar_io_error(
        raised.value,
        db_path,
        rekey_lock_module.RekeySidecarOperation.ACQUIRE,
    )


def test_sidecar_unlock_failure_is_typed_and_closes_once(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given unlock fails and close calls are observable
    db_path = tmp_path / "user.db"
    release_name = (
        "_release_windows_lock" if os.name == "nt" else "_release_posix_lock"
    )
    real_close = os.close
    close_calls: list[int] = []

    def fail_release(_fd: int) -> None:
        raise OSError(errno.EIO, "sensitive raw OS text")

    def close_once(fd: int) -> None:
        close_calls.append(fd)
        real_close(fd)

    # When the protected body succeeds but unlock fails
    with monkeypatch.context() as scoped:
        scoped.setattr(rekey_lock_module, release_name, fail_release)
        scoped.setattr(os, "close", close_once)
        with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
            with acquire_rekey_lock(db_path):
                pass

    # Then unlock is typed and close was attempted exactly once
    _assert_sidecar_io_error(
        raised.value,
        db_path,
        rekey_lock_module.RekeySidecarOperation.UNLOCK,
    )
    assert len(close_calls) == 1


def test_sidecar_close_failure_is_typed_without_retry(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given close fails after actually closing the descriptor
    db_path = tmp_path / "user.db"
    real_close = os.close
    close_calls: list[int] = []

    def fail_close(fd: int) -> None:
        close_calls.append(fd)
        real_close(fd)
        raise OSError(errno.EIO, "sensitive raw OS text")

    # When cleanup closes the existing rekey sidecar
    with monkeypatch.context() as scoped:
        scoped.setattr(os, "close", fail_close)
        with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
            with acquire_rekey_lock(db_path):
                pass

    # Then close is typed and never retried
    _assert_sidecar_io_error(
        raised.value,
        db_path,
        rekey_lock_module.RekeySidecarOperation.CLOSE,
    )
    assert len(close_calls) == 1


def test_protected_body_error_survives_unlock_and_close_failures(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given both cleanup stages fail with unsafe operating-system text
    db_path = tmp_path / "user.db"
    release_name = (
        "_release_windows_lock" if os.name == "nt" else "_release_posix_lock"
    )
    real_close = os.close
    close_calls: list[int] = []

    def fail_release(_fd: int) -> None:
        raise OSError(errno.EIO, "sensitive raw OS text")

    def fail_close(fd: int) -> None:
        close_calls.append(fd)
        real_close(fd)
        raise OSError(errno.EIO, "sensitive raw OS text")

    # When the protected body raises before cleanup runs
    with monkeypatch.context() as scoped:
        scoped.setattr(rekey_lock_module, release_name, fail_release)
        scoped.setattr(os, "close", fail_close)
        with pytest.raises(_ProtectedBodyError) as raised:
            with acquire_rekey_lock(db_path):
                raise _ProtectedBodyError

    # Then the body error wins and cleanup emits only safe typed notes
    assert len(close_calls) == 1
    assert len(raised.value.__notes__) == 2
    assert all(str(db_path) not in note for note in raised.value.__notes__)
    assert all(
        "sensitive raw OS text" not in note for note in raised.value.__notes__
    )
    assert any("unlock" in note for note in raised.value.__notes__)
    assert any("close" in note for note in raised.value.__notes__)


class _CallerHandledError(Exception):
    """An unrelated exception the caller is handling when it takes the lock."""


def _fail_one_release_stage(
    scoped: pytest.MonkeyPatch, stage: rekey_lock_module.RekeySidecarOperation
) -> list[int]:
    release_name = (
        "_release_windows_lock" if os.name == "nt" else "_release_posix_lock"
    )
    real_close = os.close
    close_calls: list[int] = []

    def fail_release(_fd: int) -> None:
        raise OSError(errno.EIO, "sensitive raw OS text")

    def fail_close(fd: int) -> None:
        close_calls.append(fd)
        real_close(fd)
        raise OSError(errno.EIO, "sensitive raw OS text")

    match stage:
        case rekey_lock_module.RekeySidecarOperation.UNLOCK:
            scoped.setattr(rekey_lock_module, release_name, fail_release)
        case rekey_lock_module.RekeySidecarOperation.CLOSE:
            scoped.setattr(os, "close", fail_close)
        case _:
            raise AssertionError(f"not a release stage: {stage}")
    return close_calls


@pytest.mark.parametrize(
    "stage",
    [
        rekey_lock_module.RekeySidecarOperation.UNLOCK,
        rekey_lock_module.RekeySidecarOperation.CLOSE,
    ],
    ids=["unlock", "close"],
)
def test_release_failure_after_a_clean_body_raises_inside_a_callers_except_block(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
    stage: rekey_lock_module.RekeySidecarOperation,
) -> None:
    # Given a caller that takes the lock while it handles an unrelated
    # exception (a probe made from an error handler), and a release stage
    # that fails
    db_path = tmp_path / "user.db"
    handled = _CallerHandledError("the caller's own error")

    # When the protected body finishes cleanly
    with monkeypatch.context() as scoped:
        close_calls = _fail_one_release_stage(scoped, stage)
        try:
            raise handled
        except _CallerHandledError:
            with pytest.raises(rekey_lock_module.RekeySidecarIOError) as raised:
                with acquire_rekey_lock(db_path):
                    pass

    # Then the release failure is raised, typed and scrubbed, as it is
    # outside an except block. It used to be added as a note to the
    # caller's unrelated exception (the one sys.exception() returned in the
    # lock's cleanup) and never raised, so the caller saw a clean release.
    assert raised.value.operation is stage
    assert raised.value.errno == errno.EIO
    assert str(db_path) not in str(raised.value)
    assert "sensitive raw OS text" not in str(raised.value)
    assert not getattr(handled, "__notes__", None)
    if stage is rekey_lock_module.RekeySidecarOperation.CLOSE:
        assert len(close_calls) == 1


def test_body_error_inside_a_callers_except_block_carries_the_release_note(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given a caller handling an unrelated exception and a failing unlock
    db_path = tmp_path / "user.db"
    handled = _CallerHandledError("the caller's own error")

    # When the protected body itself raises
    with monkeypatch.context() as scoped:
        _fail_one_release_stage(
            scoped, rekey_lock_module.RekeySidecarOperation.UNLOCK
        )
        try:
            raise handled
        except _CallerHandledError:
            with pytest.raises(_ProtectedBodyError) as raised:
                with acquire_rekey_lock(db_path):
                    raise _ProtectedBodyError

    # Then the body's error wins and carries the release failure as a
    # note; the caller's exception is left alone
    assert len(raised.value.__notes__) == 1
    assert "unlock" in raised.value.__notes__[0]
    assert not getattr(handled, "__notes__", None)


@final
class _FakeMsvcrt(ModuleType):
    LK_LOCK: ClassVar[int] = 0
    LK_NBLCK: ClassVar[int] = 1
    LK_UNLCK: ClassVar[int] = 4

    def __init__(self, acquire_error: OSError | None = None) -> None:
        super().__init__("msvcrt")
        self.acquire_error = acquire_error
        self.calls: list[tuple[int, int, int]] = []

    def locking(self, fd: int, mode: int, size: int) -> None:
        self.calls.append((os.lseek(fd, 0, os.SEEK_CUR), mode, size))
        if mode == self.LK_NBLCK and self.acquire_error is not None:
            raise self.acquire_error


def test_windows_backend_locks_one_byte_from_start(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given an empty persistent sidecar and a Windows locking backend
    lock_path = tmp_path / "user.db.rekey.lock"
    fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
    backend = _FakeMsvcrt()
    monkeypatch.setitem(sys.modules, "msvcrt", backend)

    try:
        # When the Windows lock is acquired and released
        _acquire_windows_lock(fd, lock_path)
        _release_windows_lock(fd)
    finally:
        os.close(fd)

    # Then a persistent byte backs both operations at offset zero
    assert lock_path.read_bytes() == b"\0"
    assert backend.calls == [
        (0, backend.LK_NBLCK, 1),
        (0, backend.LK_UNLCK, 1),
    ]


def test_windows_backend_selects_blocking_and_nonblocking_modes(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given a persistent sidecar and a Windows locking backend
    lock_path = tmp_path / "user.db.rekey.lock"
    fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
    backend = _FakeMsvcrt()
    monkeypatch.setitem(sys.modules, "msvcrt", backend)

    try:
        # When nonblocking and blocking exclusive locks are acquired
        _acquire_windows_lock(fd, lock_path)
        _release_windows_lock(fd)
        _acquire_windows_lock(fd, lock_path, blocking=True)
        _release_windows_lock(fd)
    finally:
        os.close(fd)

    # Then Windows uses the non-blocking and blocking write-lock modes
    assert [call[1] for call in backend.calls] == [
        backend.LK_NBLCK,
        backend.LK_UNLCK,
        backend.LK_LOCK,
        backend.LK_UNLCK,
    ]


def test_windows_backend_translates_only_contention(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given the Windows backend reports lock contention
    lock_path = tmp_path / "user.db.rekey.lock"
    fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
    backend = _FakeMsvcrt(OSError(errno.EACCES, "region already locked"))
    monkeypatch.setitem(sys.modules, "msvcrt", backend)

    try:
        # When the one-byte lock is attempted, then contention is typed
        with pytest.raises(RekeyLockContentionError) as raised:
            _acquire_windows_lock(fd, lock_path)
    finally:
        os.close(fd)

    assert raised.value.lock_path == lock_path


def test_windows_backend_preserves_unrelated_io_errors(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given the Windows backend reports an unrelated I/O error
    lock_path = tmp_path / "user.db.rekey.lock"
    fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
    backend = _FakeMsvcrt(OSError(errno.EIO, "simulated I/O failure"))
    monkeypatch.setitem(sys.modules, "msvcrt", backend)

    try:
        # When the one-byte lock is attempted, then the original error propagates
        with pytest.raises(OSError) as raised:
            _acquire_windows_lock(fd, lock_path)
    finally:
        os.close(fd)

    assert raised.value.errno == errno.EIO
    assert not isinstance(raised.value, RekeyLockContentionError)


def test_epoch_token_is_fsynced_before_it_replaces_the_epoch_file(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    # Given a spy on fsync and replace in the epoch writer
    db_path = tmp_path / "user.db"
    events: list[tuple[str, str]] = []
    real_fsync = os.fsync
    real_replace = os.replace

    def spy_fsync(fd: int) -> None:
        status = os.fstat(fd)
        if stat.S_ISREG(status.st_mode):
            events.append(("fsync", os.readlink(f"/proc/self/fd/{fd}")))
        real_fsync(fd)

    def spy_replace(source, target) -> None:
        events.append(("replace", os.fspath(source)))
        real_replace(source, target)

    if not Path("/proc/self/fd").is_dir():
        pytest.skip("needs /proc/self/fd to name the synced file")
    monkeypatch.setattr(rekey_lock_module.os, "fsync", spy_fsync)
    monkeypatch.setattr(rekey_lock_module.os, "replace", spy_replace)

    # When an epoch is published
    with acquire_rekey_lock(db_path):
        rekey_lock_module.read_or_initialize_rekey_epoch(db_path)

    # Then the temporary token file was fsynced before it was renamed over
    # the epoch file
    replaced = [path for kind, path in events if kind == "replace"]
    assert len(replaced) == 1
    synced_before = events[: events.index(("replace", replaced[0]))]
    assert ("fsync", replaced[0]) in synced_before


class TestEpochTransitionGuards:
    """Each epoch transition refuses a state it was not written for."""

    _ONE = str(UUID(int=1))
    _TWO = str(UUID(int=2))
    _THREE = str(UUID(int=3))

    def _state(self, db_path: Path, committed, pending) -> None:
        for suffix, token in (
            (".rekey.epoch", committed),
            (".rekey.pending", pending),
        ):
            path = db_path.with_name(f"{db_path.name}{suffix}")
            if token is None:
                path.unlink(missing_ok=True)
            else:
                path.write_text(token, encoding="ascii")

    def test_begin_refuses_without_a_committed_epoch(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        with pytest.raises(RekeyRecoveryRequiredError):
            begin_rekey_epoch(db_path)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(None, None)

    def test_begin_refuses_while_a_generation_is_pending(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._ONE, self._TWO)
        with pytest.raises(RekeyRecoveryRequiredError):
            begin_rekey_epoch(db_path)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._ONE, self._TWO
        )

    def test_commit_refuses_a_candidate_that_is_not_pending(
        self, tmp_path: Path
    ):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._ONE, self._TWO)
        with pytest.raises(RekeyRecoveryRequiredError):
            commit_rekey_epoch(db_path, self._THREE)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._ONE, self._TWO
        )

    def test_commit_refuses_without_a_pending_generation(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._ONE, None)
        with pytest.raises(RekeyRecoveryRequiredError):
            commit_rekey_epoch(db_path, self._TWO)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._ONE, None
        )

    def test_commit_refuses_a_non_canonical_candidate(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._ONE, self._TWO)
        with pytest.raises(RekeyRecoveryRequiredError):
            commit_rekey_epoch(db_path, self._TWO.replace("-", ""))

    def test_clear_refuses_before_the_pending_generation_is_committed(
        self, tmp_path: Path
    ):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._ONE, self._TWO)
        with pytest.raises(RekeyRecoveryRequiredError):
            clear_pending_rekey_epoch(db_path, self._TWO)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._ONE, self._TWO
        )

    def test_clear_refuses_a_different_pending_generation(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._TWO, self._THREE)
        with pytest.raises(RekeyRecoveryRequiredError):
            clear_pending_rekey_epoch(db_path, self._TWO)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._TWO, self._THREE
        )

    def test_clear_is_idempotent_once_cleared(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._TWO, None)
        clear_pending_rekey_epoch(db_path, self._TWO)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._TWO, None
        )

    def test_clear_removes_a_committed_pending_generation(self, tmp_path: Path):
        db_path = tmp_path / "user.db"
        self._state(db_path, self._TWO, self._TWO)
        clear_pending_rekey_epoch(db_path, self._TWO)
        assert read_rekey_epoch_state(db_path) == RekeyEpochState(
            self._TWO, None
        )


@pytest.mark.skipif(
    os.name == "nt" or not hasattr(os, "link"),
    reason="POSIX hard links required",
)
def test_hard_link_guard_cannot_identify_an_inode_after_its_other_name_is_removed(
    tmp_path: Path,
) -> None:
    """Document the trusted-directory boundary: current names, not history."""
    db_path = tmp_path / "user.db"
    other_path = tmp_path / "other-user.db"
    other_path.write_bytes(b"file whose original name will be removed")
    lock_path = db_path.with_name(f"{db_path.name}.rekey.lock")
    os.link(other_path, lock_path)

    # Control: while the original name is present, the guard refuses it.
    with pytest.raises(rekey_lock_module.RekeySidecarIOError) as refused:
        with acquire_rekey_lock(db_path):
            pytest.fail("a same-directory hard link was accepted")
    assert refused.value.errno == errno.EMLINK

    # Removing that name erases the evidence available to the guard. This
    # is a documented limit, not protection against writers of the data dir.
    other_path.unlink()
    assert lock_path.stat().st_nlink == 1
    with acquire_rekey_lock(db_path):
        assert (
            lock_path.read_bytes()
            == b"file whose original name will be removed"
        )