openmodus 0.0.1__py3-none-any.whl

modus/artifacts_io.py

@@ -0,0 +1,1066 @@
+"""Corruption-tolerant loading of Modus-generated artifacts.
+
+Modus-generated artifacts (evidence bundles, configuration, domain metadata,
+and disposable caches) are machine-written YAML/JSON. A hand-edit, merge accident, or
+interrupted write can leave them malformed. The human review surface is friendly
+Markdown/YAML plus commands, so a malformed artifact must surface as a readable,
+actionable error -- never a raw parser traceback. Disposable caches instead
+self-heal (``tolerant=True``): a corrupt cache is treated as absent and rebuilt.
+
+Two load modes:
+
+* strict (default): malformed content raises :class:`CorruptArtifactError`, whose
+  message names the file, the failure, and how to recover. CLI gate commands
+  turn this into a clean non-zero exit instead of a traceback.
+* tolerant: malformed content returns ``default`` so a regeneration/rebuild path
+  can overwrite the bad file instead of crashing on it.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import stat
+import threading
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Final
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+_HELD_FILE_LOCK_DEPTHS = threading.local()
+_OPEN_FILE_LOCKS: dict[int, object] = {}
+_OPEN_FILE_LOCKS_GUARD = threading.Lock()
+_FILE_LOCK_REGISTRY_PID = os.getpid()
+_LOCK_BIND_ATTEMPTS: Final = 8
+
+
+def _reset_file_lock_registry_after_pid_change() -> None:
+    """Drop copied ownership and close inherited lock descriptors in a fork child."""
+    global _FILE_LOCK_REGISTRY_PID, _OPEN_FILE_LOCKS, _OPEN_FILE_LOCKS_GUARD
+
+    inherited = set(_OPEN_FILE_LOCKS.values())
+    for descriptor in tuple(_OPEN_FILE_LOCKS):
+        try:
+            os.close(descriptor)
+        except OSError:
+            pass
+    _OPEN_FILE_LOCKS = {}
+    _OPEN_FILE_LOCKS_GUARD = threading.Lock()
+    _HELD_FILE_LOCK_DEPTHS.depths = {}
+    _HELD_FILE_LOCK_DEPTHS.required_depths = {}
+    _HELD_FILE_LOCK_DEPTHS.inherited_tokens = inherited
+    _FILE_LOCK_REGISTRY_PID = os.getpid()
+
+
+def _ensure_file_lock_registry_pid() -> None:
+    if _FILE_LOCK_REGISTRY_PID != os.getpid():
+        _reset_file_lock_registry_after_pid_change()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_reset_file_lock_registry_after_pid_change)
+
+
+class CorruptArtifactError(Exception):
+    """A Modus-generated artifact exists but could not be parsed.
+
+    Carries enough structured context for the CLI to print a friendly, actionable
+    message (which file, what kind, how to recover).
+    """
+
+    def __init__(self, path: str | Path, kind: str, detail: str, hint: str | None = None) -> None:
+        self.path = str(path)
+        self.kind = kind
+        self.detail = detail
+        self.hint = hint
+        message = f"{kind} is malformed: {self.path}\n  -> {detail}"
+        if hint:
+            message += f"\n  -> {hint}"
+        super().__init__(message)
+
+
+class FileLockIntegrityError(ValueError):
+    """A writer lock path could not be bound without following links."""
+
+
+class RequiredFileLockUnavailable(RuntimeError):
+    """A correctness-critical writer lock has no safe platform backend."""
+
+
+class AtomicWriteIntegrityError(OSError):
+    """An ``atomic_write_text`` target could not be safely bound or written.
+
+    Raised instead of silently writing through a symlink/special file, or
+    instead of completing a replace whose parent directory was swapped out
+    from under the write. A well-formed, non-adversarial target never raises
+    this -- only a malformed or actively-racing target does.
+    """
+
+
+def _detail(exc: Exception) -> str:
+    return " ".join(str(exc).split())[:300]
+
+
+def safe_load_yaml(
+    path: str | Path,
+    *,
+    kind: str,
+    default: Any = None,
+    tolerant: bool = False,
+    hint: str | None = None,
+) -> Any:
+    """Load a YAML artifact, mapping malformed content to a friendly outcome.
+
+    Returns ``default`` when the file is missing or empty. On malformed YAML:
+    raise :class:`CorruptArtifactError` (strict) or return ``default`` (tolerant).
+    """
+    p = Path(path)
+    if not p.is_file():
+        return default
+    try:
+        data = yaml.safe_load(p.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        if tolerant:
+            return default
+        raise CorruptArtifactError(p, kind, _detail(exc), hint) from exc
+    return default if data is None else data
+
+
+def _lock_directory_flags() -> int:
+    no_follow = getattr(os, "O_NOFOLLOW", None)
+    directory = getattr(os, "O_DIRECTORY", None)
+    if no_follow is None or directory is None:
+        raise FileLockIntegrityError("safe writer locks require O_NOFOLLOW and O_DIRECTORY")
+    return os.O_RDONLY | no_follow | directory | getattr(os, "O_CLOEXEC", 0)
+
+
+def _absolute_lock_path(lock_path: str | Path) -> Path:
+    """Return a lexical absolute path without resolving any filesystem link."""
+    return Path(os.path.abspath(os.fspath(lock_path)))
+
+
+def _assert_lock_parent_binding(parent: Path, descriptor: int) -> None:
+    """Verify every named ancestor and the retained parent descriptor agree."""
+    anchor = Path(parent.anchor)
+    current = anchor
+    try:
+        info = os.stat(anchor, follow_symlinks=False)
+        if not stat.S_ISDIR(info.st_mode):
+            raise FileLockIntegrityError(f"writer lock anchor is not a directory: {anchor}")
+        for part in parent.parts[1:]:
+            current = current / part
+            info = os.stat(current, follow_symlinks=False)
+            if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+                raise FileLockIntegrityError(
+                    f"writer lock parent is not a real directory: {current}"
+                )
+        opened = os.fstat(descriptor)
+    except FileLockIntegrityError:
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise FileLockIntegrityError(
+            f"writer lock parent is unsafe or unavailable: {current}: {exc}"
+        ) from exc
+    if (opened.st_dev, opened.st_ino) != (info.st_dev, info.st_ino):
+        raise FileLockIntegrityError(f"writer lock parent path changed after opening: {parent}")
+
+
+def _open_lock_parent(parent: Path) -> int:
+    """Create/open ``parent`` one component at a time without following links."""
+    flags = _lock_directory_flags()
+    descriptor: int | None = None
+    try:
+        descriptor = os.open(parent.anchor, flags)
+        for part in parent.parts[1:]:
+            if part in {"", ".", ".."}:
+                raise FileLockIntegrityError(f"writer lock parent is not canonical: {parent}")
+            try:
+                os.mkdir(part, mode=0o755, dir_fd=descriptor)
+            except FileExistsError:
+                pass
+            child = os.open(part, flags, dir_fd=descriptor)
+            os.close(descriptor)
+            descriptor = child
+        _assert_lock_parent_binding(parent, descriptor)
+        return descriptor
+    except FileLockIntegrityError:
+        if descriptor is not None:
+            os.close(descriptor)
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        if descriptor is not None:
+            try:
+                os.close(descriptor)
+            except OSError:
+                pass
+        raise FileLockIntegrityError(
+            f"writer lock parent is unsafe or unavailable: {parent}: {exc}"
+        ) from exc
+
+
+def _assert_lock_file_binding(parent_descriptor: int, name: str, descriptor: int) -> None:
+    """Require the lock name to remain bound to the opened regular-file inode."""
+    try:
+        opened = os.fstat(descriptor)
+        named = os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise FileLockIntegrityError(
+            f"writer lock file is unsafe or unavailable: {name}: {exc}"
+        ) from exc
+    if not stat.S_ISREG(opened.st_mode) or not stat.S_ISREG(named.st_mode):
+        raise FileLockIntegrityError(f"writer lock must be a regular file: {name}")
+    if (opened.st_dev, opened.st_ino) != (named.st_dev, named.st_ino):
+        raise FileLockIntegrityError(f"writer lock path changed after opening: {name}")
+
+
+def _open_lock_file(parent_descriptor: int, name: str) -> int:
+    no_follow = getattr(os, "O_NOFOLLOW", None)
+    non_block = getattr(os, "O_NONBLOCK", None)
+    if no_follow is None or non_block is None:
+        raise FileLockIntegrityError("safe writer locks require O_NOFOLLOW and O_NONBLOCK")
+    try:
+        descriptor = os.open(
+            name,
+            os.O_RDWR | os.O_CREAT | no_follow | non_block | getattr(os, "O_CLOEXEC", 0),
+            0o600,
+            dir_fd=parent_descriptor,
+        )
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise FileLockIntegrityError(
+            f"writer lock file is unsafe or unavailable: {name}: {exc}"
+        ) from exc
+    try:
+        _assert_lock_file_binding(parent_descriptor, name, descriptor)
+    except Exception:
+        os.close(descriptor)
+        raise
+    return descriptor
+
+
+def _register_open_file_lock(descriptor: int) -> object:
+    _ensure_file_lock_registry_pid()
+    token = object()
+    with _OPEN_FILE_LOCKS_GUARD:
+        _OPEN_FILE_LOCKS[descriptor] = token
+    return token
+
+
+def _unregister_open_file_lock(descriptor: int, token: object) -> None:
+    _ensure_file_lock_registry_pid()
+    with _OPEN_FILE_LOCKS_GUARD:
+        if _OPEN_FILE_LOCKS.get(descriptor) is token:
+            _OPEN_FILE_LOCKS.pop(descriptor, None)
+
+
+def _file_lock_token_was_inherited(token: object | None) -> bool:
+    if token is None:
+        return False
+    _ensure_file_lock_registry_pid()
+    inherited: set[object] = getattr(_HELD_FILE_LOCK_DEPTHS, "inherited_tokens", set())
+    return token in inherited
+
+
+@dataclass(slots=True)
+class _PosixLockHandle:
+    """Own every descriptor and registry token for one POSIX writer lock."""
+
+    parent_fd: int | None = None
+    lock_fd: int | None = None
+    parent_token: object | None = None
+    lock_token: object | None = None
+    locked: bool = False
+
+    def close(self, fcntl_module: Any, *, preserve_inherited: bool) -> None:
+        """Release registrations and descriptors in dependency order."""
+
+        try:
+            if self.lock_fd is not None:
+                inherited = preserve_inherited and _file_lock_token_was_inherited(self.lock_token)
+                if self.lock_token is not None:
+                    _unregister_open_file_lock(self.lock_fd, self.lock_token)
+                if not inherited:
+                    try:
+                        if self.locked:
+                            fcntl_module.flock(self.lock_fd, fcntl_module.LOCK_UN)
+                    finally:
+                        os.close(self.lock_fd)
+        finally:
+            if self.parent_fd is not None:
+                inherited = preserve_inherited and _file_lock_token_was_inherited(self.parent_token)
+                if self.parent_token is not None:
+                    _unregister_open_file_lock(self.parent_fd, self.parent_token)
+                if not inherited:
+                    os.close(self.parent_fd)
+
+
+def _acquire_posix_lock(path: Path, fcntl_module: Any) -> _PosixLockHandle:
+    """Safely bind and acquire one logical lock, retrying concurrent first use."""
+
+    for attempt in range(_LOCK_BIND_ATTEMPTS):
+        handle = _PosixLockHandle()
+        try:
+            handle.parent_fd = _open_lock_parent(path.parent)
+            handle.parent_token = _register_open_file_lock(handle.parent_fd)
+            handle.lock_fd = _open_lock_file(handle.parent_fd, path.name)
+            handle.lock_token = _register_open_file_lock(handle.lock_fd)
+            fcntl_module.flock(handle.lock_fd, fcntl_module.LOCK_EX)
+            handle.locked = True
+            _assert_lock_parent_binding(path.parent, handle.parent_fd)
+            _assert_lock_file_binding(handle.parent_fd, path.name, handle.lock_fd)
+            return handle
+        except FileLockIntegrityError:
+            handle.close(fcntl_module, preserve_inherited=False)
+            if attempt == _LOCK_BIND_ATTEMPTS - 1:
+                raise
+        except BaseException:
+            handle.close(fcntl_module, preserve_inherited=False)
+            raise
+    raise AssertionError("unreachable lock acquisition state")
+
+
+@contextmanager
+def file_lock(lock_path: str | Path) -> Iterator[None]:
+    """Advisory exclusive lock around a critical section (POSIX ``flock``).
+
+    Serializes concurrent writers (e.g. two initialization-analysis builds, or two
+    ``promote`` runs feeding the same domain) so their read-modify-write never
+    interleaves. Degrades to a no-op where ``fcntl`` is unavailable (non-POSIX):
+    best-effort, never blocks the workflow. The lock file lives wherever the
+    caller points it -- by convention under the disposable cache, never inside an
+    output tree the lock protects.
+    """
+    _ensure_file_lock_registry_pid()
+    try:
+        import fcntl
+    except Exception:  # noqa: BLE001 - non-POSIX: best-effort, no locking
+        yield
+        return
+
+    # Directory creation and the first lock open are intentionally outside any
+    # pre-existing mutex. Concurrent first-use writers can replace a just-made
+    # path component between openat/fstat checks. Retry the complete safe bind;
+    # every attempt still uses O_NOFOLLOW and never relaxes the symlink policy.
+    path = _absolute_lock_path(lock_path)
+    handle = _acquire_posix_lock(path, fcntl)
+    try:
+        yield
+        assert handle.parent_fd is not None and handle.lock_fd is not None
+        _assert_lock_parent_binding(path.parent, handle.parent_fd)
+        _assert_lock_file_binding(handle.parent_fd, path.name, handle.lock_fd)
+    finally:
+        handle.close(fcntl, preserve_inherited=True)
+
+
+def _assert_portable_lock_binding(path: Path, descriptor: int) -> None:
+    """Validate the regular-file binding used by the native Windows backend."""
+    current = Path(path.anchor)
+    try:
+        for part in path.parent.parts[1:]:
+            current = current / part
+            info = os.stat(current, follow_symlinks=False)
+            if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+                raise FileLockIntegrityError(
+                    f"writer lock parent is not a real directory: {current}"
+                )
+        opened = os.fstat(descriptor)
+        named = os.stat(path, follow_symlinks=False)
+    except FileLockIntegrityError:
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise FileLockIntegrityError(
+            f"writer lock is unsafe or unavailable: {path}: {exc}"
+        ) from exc
+    if stat.S_ISLNK(named.st_mode) or not stat.S_ISREG(named.st_mode):
+        raise FileLockIntegrityError(f"writer lock must be a regular file: {path}")
+    if not stat.S_ISREG(opened.st_mode) or (
+        opened.st_dev,
+        opened.st_ino,
+    ) != (named.st_dev, named.st_ino):
+        raise FileLockIntegrityError(f"writer lock path changed after opening: {path}")
+
+
+@contextmanager
+def _windows_required_file_lock(lock_path: str | Path, msvcrt_module: Any) -> Iterator[None]:
+    """Acquire a mandatory one-byte Windows file lock without shell tooling."""
+    path = _absolute_lock_path(lock_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOINHERIT", 0)
+    descriptor = os.open(path, flags, 0o600)
+    locked = False
+    try:
+        _assert_portable_lock_binding(path, descriptor)
+        if os.fstat(descriptor).st_size == 0:
+            os.write(descriptor, b"\0")
+            os.fsync(descriptor)
+        os.lseek(descriptor, 0, os.SEEK_SET)
+        msvcrt_module.locking(descriptor, msvcrt_module.LK_LOCK, 1)
+        locked = True
+        _assert_portable_lock_binding(path, descriptor)
+        yield
+        _assert_portable_lock_binding(path, descriptor)
+    finally:
+        if locked:
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            msvcrt_module.locking(descriptor, msvcrt_module.LK_UNLCK, 1)
+        os.close(descriptor)
+
+
+@contextmanager
+def required_file_lock(lock_path: str | Path) -> Iterator[None]:
+    """Acquire a cross-platform writer lock or fail closed.
+
+    Use this for state transitions whose correctness depends on mutual exclusion
+    (for example knowledge and install writes). Read-only callers may continue to use
+    :func:`file_lock`'s best-effort behavior, but transactional writers must not
+    silently continue without a supported lock backend.
+    """
+    try:
+        import fcntl  # noqa: F401 - capability probe; file_lock owns the handle
+    except Exception:  # noqa: BLE001 - probe the native Windows backend next
+        try:
+            import msvcrt
+        except Exception as exc:  # noqa: BLE001 - fail closed by contract
+            raise RequiredFileLockUnavailable(
+                "required writer locks need either POSIX fcntl or Windows msvcrt"
+            ) from exc
+        logger.debug("acquiring required Windows writer lock", extra={"path": str(lock_path)})
+        with _windows_required_file_lock(lock_path, msvcrt):
+            yield
+        return
+
+    logger.debug("acquiring required POSIX writer lock", extra={"path": str(lock_path)})
+    with file_lock(lock_path):
+        yield
+
+
+@contextmanager
+def required_reentrant_file_lock(lock_path: str | Path) -> Iterator[None]:
+    """Acquire one correctness-critical lock per thread and canonical path."""
+    identity = _file_lock_identity(lock_path)
+    depths = _held_file_lock_depths()
+    required_depths = _held_required_file_lock_depths()
+    if required_depths.get(identity, 0):
+        depths[identity] += 1
+        required_depths[identity] += 1
+        try:
+            yield
+        finally:
+            depths[identity] -= 1
+            required_depths[identity] -= 1
+        return
+
+    if depths.get(identity, 0):
+        # An advisory lock is correctness-equivalent only on POSIX, where
+        # ``file_lock`` necessarily acquired flock. On Windows that same API is
+        # deliberately a no-op, so a nested transaction must still acquire
+        # the native required backend instead of mistaking thread depth for an
+        # operating-system lock.
+        try:
+            import fcntl  # noqa: F401 - capability/ownership distinction
+        except Exception:  # noqa: BLE001 - native required backend acquired below
+            pass
+        else:
+            depths[identity] += 1
+            required_depths[identity] = 1
+            try:
+                yield
+            finally:
+                depths[identity] -= 1
+                required_depths.pop(identity, None)
+            return
+
+    with required_file_lock(lock_path):
+        previous_depth = depths.get(identity, 0)
+        depths[identity] = previous_depth + 1
+        required_depths[identity] = 1
+        try:
+            yield
+        finally:
+            required_depths.pop(identity, None)
+            if previous_depth:
+                depths[identity] = previous_depth
+            else:
+                depths.pop(identity, None)
+
+
+@contextmanager
+def reentrant_file_lock(lock_path: str | Path) -> Iterator[None]:
+    """Acquire one advisory writer lock once per current thread and canonical path."""
+    identity = _file_lock_identity(lock_path)
+    depths = _held_file_lock_depths()
+    if depths.get(identity, 0):
+        depths[identity] += 1
+        try:
+            yield
+        finally:
+            depths[identity] -= 1
+        return
+    with file_lock(lock_path):
+        depths[identity] = 1
+        try:
+            yield
+        finally:
+            depths.pop(identity, None)
+
+
+def _file_lock_identity(lock_path: str | Path) -> str:
+    return os.path.normcase(os.fspath(_absolute_lock_path(lock_path)))
+
+
+def _held_file_lock_depths() -> dict[str, int]:
+    _ensure_file_lock_registry_pid()
+    depths = getattr(_HELD_FILE_LOCK_DEPTHS, "depths", None)
+    if depths is None:
+        depths = {}
+        _HELD_FILE_LOCK_DEPTHS.depths = depths
+    return depths
+
+
+def _held_required_file_lock_depths() -> dict[str, int]:
+    _ensure_file_lock_registry_pid()
+    depths = getattr(_HELD_FILE_LOCK_DEPTHS, "required_depths", None)
+    if depths is None:
+        depths = {}
+        _HELD_FILE_LOCK_DEPTHS.required_depths = depths
+    return depths
+
+
+def _atomic_write_temp_name(name: str) -> str:
+    """A per-attempt temp name: PID *and* a random nonce.
+
+    PID alone collides across a fork boundary or under PID reuse (two
+    concurrent writers can legitimately share a PID). The nonce makes every
+    attempt's temp name unique regardless of PID, so 64 same-PID writers (or
+    genuinely different processes) never contend for one temp path.
+    """
+    return f".{name}.tmp-{os.getpid()}-{secrets.token_hex(8)}"
+
+
+def _reject_unsafe_atomic_write_target(
+    parent_descriptor: int | None, name: str, path: Path
+) -> None:
+    """Fail closed if an existing target is a symlink or special file.
+
+    Checked via ``lstat`` (never following the final component), so this
+    guarantee holds even when ``O_NOFOLLOW`` is unavailable for the open calls
+    below -- the property does not depend on those flags.
+    """
+    try:
+        info = (
+            os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+            if parent_descriptor is not None
+            else path.lstat()
+        )
+    except FileNotFoundError:
+        return
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise AtomicWriteIntegrityError(
+            f"atomic write target is unsafe or unavailable: {path}: {exc}"
+        ) from exc
+    if _is_link_or_reparse(info) or not stat.S_ISREG(info.st_mode):
+        raise AtomicWriteIntegrityError(
+            f"atomic write target must be a regular file or absent, not a "
+            f"symlink/special file: {path}"
+        )
+
+
+def _open_atomic_child(parent_fd: int, name: str, current: Path, flags: int) -> int:
+    """Create/open and inode-bind one directory below an already safe parent."""
+
+    try:
+        os.mkdir(name, mode=0o755, dir_fd=parent_fd)
+    except FileExistsError:
+        pass
+    child = os.open(name, flags, dir_fd=parent_fd)
+    try:
+        named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        opened = os.fstat(child)
+        if (
+            _is_link_or_reparse(named)
+            or not stat.S_ISDIR(named.st_mode)
+            or not stat.S_ISDIR(opened.st_mode)
+            or (named.st_dev, named.st_ino) != (opened.st_dev, opened.st_ino)
+        ):
+            raise AtomicWriteIntegrityError(
+                f"atomic write parent is not a real directory: {current}"
+            )
+        return child
+    except BaseException:
+        os.close(child)
+        raise
+
+
+def _open_atomic_write_parent(parent: Path) -> int:
+    """Create/open every ``parent`` component without following filesystem links.
+
+    A single ``os.open(parent, O_NOFOLLOW | ...)`` call only rejects a symlink
+    at the *final* path component -- the kernel still resolves every
+    intermediate component through ordinary path resolution, so a symlinked
+    grandparent (or higher) would otherwise be silently followed. Opening
+    component-by-component with ``dir_fd`` closes that gap. Missing directories
+    are created relative to an already-bound parent, avoiding the unsafe
+    ``Path.mkdir(parents=True)`` preflight that can traverse an ancestor link.
+    """
+    open_flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0)
+    no_follow = getattr(os, "O_NOFOLLOW", None)
+    if no_follow is not None:
+        open_flags |= no_follow
+    if hasattr(os, "O_DIRECTORY"):
+        open_flags |= os.O_DIRECTORY
+    descriptor: int | None = None
+    transferred = False
+    try:
+        descriptor = os.open(parent.anchor, open_flags)
+        current = Path(parent.anchor)
+        for part in parent.parts[1:]:
+            if part in {"", ".", ".."}:
+                raise AtomicWriteIntegrityError(f"atomic write parent is not canonical: {parent}")
+            current = current / part
+            child = _open_atomic_child(descriptor, part, current, open_flags)
+            os.close(descriptor)
+            descriptor = child
+        _assert_atomic_write_parent_binding(parent, descriptor)
+        transferred = True
+        return descriptor
+    except AtomicWriteIntegrityError:
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise AtomicWriteIntegrityError(
+            f"atomic write parent is unsafe or unavailable: {parent}: {exc}"
+        ) from exc
+    finally:
+        if descriptor is not None and not transferred:
+            try:
+                os.close(descriptor)
+            except OSError:
+                pass
+
+
+def _assert_atomic_write_parent_binding(parent: Path, descriptor: int) -> None:
+    """Verify every named ancestor and the open parent descriptor agree.
+
+    Mirrors ``file_lock``'s ``_assert_lock_parent_binding``: walks the full
+    ancestor chain (not just the immediate parent) with an unresolved
+    ``stat``, then compares the innermost component's identity against the
+    descriptor actually held open. A parent-directory swap anywhere in the
+    chain -- not only the last component -- is therefore detected.
+    """
+    anchor = Path(parent.anchor)
+    current = anchor
+    try:
+        info = os.stat(anchor, follow_symlinks=False)
+        if not stat.S_ISDIR(info.st_mode):
+            raise AtomicWriteIntegrityError(f"atomic write anchor is not a directory: {anchor}")
+        for part in parent.parts[1:]:
+            current = current / part
+            info = os.stat(current, follow_symlinks=False)
+            if _is_link_or_reparse(info) or not stat.S_ISDIR(info.st_mode):
+                raise AtomicWriteIntegrityError(
+                    f"atomic write parent is not a real directory: {current}"
+                )
+        opened = os.fstat(descriptor)
+    except AtomicWriteIntegrityError:
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise AtomicWriteIntegrityError(
+            f"atomic write parent is unsafe or unavailable: {current}: {exc}"
+        ) from exc
+    if (opened.st_dev, opened.st_ino) != (info.st_dev, info.st_ino):
+        raise AtomicWriteIntegrityError(f"atomic write parent path changed after opening: {parent}")
+
+
+def _is_link_or_reparse(info: os.stat_result) -> bool:
+    """Recognize POSIX symlinks and Windows reparse-point indirections."""
+    reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x0400)
+    attributes = getattr(info, "st_file_attributes", 0)
+    return stat.S_ISLNK(info.st_mode) or bool(attributes & reparse_flag)
+
+
+def _portable_lstat(path: Path) -> os.stat_result:
+    """Return unresolved metadata on both POSIX and native Windows Python."""
+    try:
+        return os.stat(path, follow_symlinks=False)
+    except (TypeError, NotImplementedError):  # pragma: no cover - old Windows Python
+        return path.lstat()
+
+
+def _portable_parent_snapshot(parent: Path) -> tuple[tuple[int, int], ...]:
+    """Validate an atomic-write ancestor chain and return stable identities.
+
+    This is the strongest portable fallback available where ``openat`` and
+    ``O_DIRECTORY`` are absent (notably native Windows). Reparse points are
+    rejected explicitly; callers compare the snapshot again immediately before
+    publication to catch ordinary directory replacement races.
+    """
+    absolute = _absolute_lock_path(parent)
+    anchor = Path(absolute.anchor)
+    if not absolute.anchor:
+        raise AtomicWriteIntegrityError(f"atomic write parent must be an absolute path: {parent}")
+    current = anchor
+    identities: list[tuple[int, int]] = []
+    try:
+        info = _portable_lstat(current)
+        if _is_link_or_reparse(info) or not stat.S_ISDIR(info.st_mode):
+            raise AtomicWriteIntegrityError(
+                f"atomic write parent is not a real directory: {current}"
+            )
+        identities.append((info.st_dev, info.st_ino))
+        for part in absolute.parts[1:]:
+            if part in {"", ".", ".."}:
+                raise AtomicWriteIntegrityError(f"atomic write parent is not canonical: {absolute}")
+            current = current / part
+            info = _portable_lstat(current)
+            if _is_link_or_reparse(info) or not stat.S_ISDIR(info.st_mode):
+                raise AtomicWriteIntegrityError(
+                    f"atomic write parent is not a real directory: {current}"
+                )
+            identities.append((info.st_dev, info.st_ino))
+    except (AtomicWriteIntegrityError, FileNotFoundError):
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise AtomicWriteIntegrityError(
+            f"atomic write parent is unsafe or unavailable: {current}: {exc}"
+        ) from exc
+    return tuple(identities)
+
+
+def _assert_portable_atomic_parent(
+    parent: Path, expected: tuple[tuple[int, int], ...] | None = None
+) -> tuple[tuple[int, int], ...]:
+    """Validate portable ancestors and optionally compare their identities."""
+    try:
+        actual = _portable_parent_snapshot(parent)
+    except FileNotFoundError as exc:
+        raise AtomicWriteIntegrityError(
+            f"atomic write parent is unsafe or unavailable: {parent}: {exc}"
+        ) from exc
+    if expected is not None and actual != expected:
+        raise AtomicWriteIntegrityError(
+            f"atomic write parent path changed during publication: {parent}"
+        )
+    return actual
+
+
+def _ensure_portable_atomic_parent(parent: Path) -> tuple[tuple[int, int], ...]:
+    """Create missing fallback directories without traversing a static link."""
+    absolute = _absolute_lock_path(parent)
+    anchor = Path(absolute.anchor)
+    if not absolute.anchor:
+        raise AtomicWriteIntegrityError(f"atomic write parent must be an absolute path: {parent}")
+    current = anchor
+    try:
+        anchor_info = _portable_lstat(anchor)
+        if _is_link_or_reparse(anchor_info) or not stat.S_ISDIR(anchor_info.st_mode):
+            raise AtomicWriteIntegrityError(
+                f"atomic write anchor is not a real directory: {anchor}"
+            )
+        for part in absolute.parts[1:]:
+            if part in {"", ".", ".."}:
+                raise AtomicWriteIntegrityError(f"atomic write parent is not canonical: {absolute}")
+            current = current / part
+            try:
+                info = _portable_lstat(current)
+            except FileNotFoundError:
+                # Re-check every existing ancestor immediately before the
+                # path-based mkdir. Native Windows has no dir_fd equivalent,
+                # so this is intentionally fail-closed against static links
+                # and best-effort against an active swap race.
+                _assert_portable_atomic_parent(current.parent)
+                try:
+                    os.mkdir(current, mode=0o755)
+                except FileExistsError:
+                    # A concurrent benign writer may have won directory
+                    # creation; the unresolved metadata check below decides
+                    # whether that winner is safe.
+                    pass
+                info = _portable_lstat(current)
+            if _is_link_or_reparse(info) or not stat.S_ISDIR(info.st_mode):
+                raise AtomicWriteIntegrityError(
+                    f"atomic write parent is not a real directory: {current}"
+                )
+    except AtomicWriteIntegrityError:
+        raise
+    except (OSError, TypeError, NotImplementedError) as exc:
+        raise AtomicWriteIntegrityError(
+            f"atomic write parent is unsafe or unavailable: {current}: {exc}"
+        ) from exc
+    return _assert_portable_atomic_parent(absolute)
+
+
+def _atomic_write_posix(parent: Path, name: str, data: bytes | Iterable[bytes], path: Path) -> None:
+    """Bind the parent directory, then create-fsync-rename-fsync under it.
+
+    The parent is opened one path component at a time (mirrors ``file_lock``'s
+    ``_open_lock_parent``/``_assert_lock_parent_binding``), so a symlink
+    anywhere in the ancestor chain -- not just the immediate parent -- is
+    rejected; a single multi-component ``os.open(parent, O_NOFOLLOW)`` call
+    would only protect the final component. Before the final rename the whole
+    chain is re-checked against a fresh, unresolved ``stat``, so a parent-
+    directory swap anywhere in that chain between temp-file creation and
+    replace is detected and fails closed instead of silently renaming into the
+    wrong directory.
+    """
+    no_follow = getattr(os, "O_NOFOLLOW", None)
+    parent_descriptor = _open_atomic_write_parent(parent)
+    try:
+        parent_stat = os.fstat(parent_descriptor)
+        if not stat.S_ISDIR(parent_stat.st_mode):
+            raise AtomicWriteIntegrityError(f"atomic write parent is not a directory: {parent}")
+        _reject_unsafe_atomic_write_target(parent_descriptor, name, path)
+
+        tmp_name = _atomic_write_temp_name(name)
+        create_flags = (
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0) | (no_follow or 0)
+        )
+        fd = os.open(tmp_name, create_flags, 0o600, dir_fd=parent_descriptor)
+        try:
+            with os.fdopen(fd, "wb") as handle:
+                for chunk in (data,) if isinstance(data, bytes) else data:
+                    handle.write(chunk)
+                handle.flush()
+                os.fsync(handle.fileno())
+
+            _assert_atomic_write_parent_binding(parent, parent_descriptor)
+            _reject_unsafe_atomic_write_target(parent_descriptor, name, path)
+
+            if os.rename in os.supports_dir_fd:
+                os.rename(
+                    tmp_name, name, src_dir_fd=parent_descriptor, dst_dir_fd=parent_descriptor
+                )
+            else:  # pragma: no cover - exercised only on platforms without renameat
+                os.replace(parent / tmp_name, path)
+        except BaseException:
+            try:
+                if os.unlink in os.supports_dir_fd:
+                    os.unlink(tmp_name, dir_fd=parent_descriptor)
+                else:  # pragma: no cover - exercised only without unlinkat
+                    (parent / tmp_name).unlink()
+            except OSError:
+                pass
+            raise
+
+        try:
+            os.fsync(parent_descriptor)
+        except OSError:  # pragma: no cover - best-effort durability only
+            pass
+
+        # Post-write binding validation: confirm the name we just published
+        # still resolves to a real, regular file (never a symlink/special
+        # file) without following it. A concurrent writer may have already
+        # published its own complete content over ours by the time this
+        # check runs -- that is correct atomic-write interleaving, not
+        # corruption, so this only re-checks *shape*, never our own bytes.
+        verified = os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+        if not stat.S_ISREG(verified.st_mode):
+            raise AtomicWriteIntegrityError(
+                f"atomic write target failed post-write binding validation: {path}"
+            )
+    finally:
+        os.close(parent_descriptor)
+
+
+def _atomic_write_fallback(path: Path, data: bytes | Iterable[bytes]) -> None:
+    """Atomic write fallback with portable ancestor/reparse-point checks.
+
+    Native Windows lacks the POSIX ``dir_fd`` publication primitive. It can
+    still reject every static ancestor reparse point and compare directory
+    identities before and after publication instead of blindly following a
+    linked parent.
+    """
+    path = _absolute_lock_path(path)
+    parent_snapshot = _ensure_portable_atomic_parent(path.parent)
+    _reject_unsafe_atomic_write_target(None, path.name, path)
+    tmp = path.with_name(_atomic_write_temp_name(path.name))
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
+    fd = os.open(tmp, flags, 0o600)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            for chunk in (data,) if isinstance(data, bytes) else data:
+                handle.write(chunk)
+            handle.flush()
+            try:
+                os.fsync(handle.fileno())
+            except OSError:  # pragma: no cover - best-effort durability only
+                pass
+        _assert_portable_atomic_parent(path.parent, parent_snapshot)
+        _reject_unsafe_atomic_write_target(None, path.name, path)
+        os.replace(tmp, path)
+        _assert_portable_atomic_parent(path.parent, parent_snapshot)
+        _reject_unsafe_atomic_write_target(None, path.name, path)
+    except BaseException:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def atomic_write_text(path: str | Path, text: str, *, encoding: str = "utf-8") -> Path:
+    """Write ``text`` to ``path`` atomically (temp file + fsync + rename + fsync).
+
+    A reader either sees the old complete file or the new complete file, never a
+    half-written one -- so a crashed/concurrent write can't leave a torn cache.
+    Hardened beyond plain temp+replace: the temp name carries a random nonce (not
+    just the writer's PID, which can collide across a fork boundary or PID
+    reuse), the temp file is fsynced before the rename and the parent directory
+    is fsynced after it (durability across a crash), a symlink or special file
+    already at the target is rejected rather than written through, and a parent-
+    directory swap between temp-file creation and the final rename is detected
+    and fails closed. None of this changes behavior for a well-formed,
+    non-adversarial write to a regular file or absent path.
+    """
+    p = Path(path)
+    absolute = _absolute_lock_path(p)
+    data = text.encode(encoding)
+    if hasattr(os, "O_DIRECTORY") and hasattr(os, "fdopen"):
+        _atomic_write_posix(absolute.parent, absolute.name, data, absolute)
+    else:  # pragma: no cover - exercised only on platforms without O_DIRECTORY
+        _atomic_write_fallback(absolute, data)
+    return p
+
+
+def atomic_write_chunks(path: str | Path, chunks: Iterable[str]) -> Path:
+    """Stream a large UTF-8 export through the same bound atomic publication.
+
+    Iterator failure leaves the previous complete export untouched. The input
+    need not be copied into a second object or serialized into one giant string.
+    """
+    p = Path(path)
+    absolute = _absolute_lock_path(p)
+    data = (chunk.encode("utf-8") for chunk in chunks)
+    if hasattr(os, "O_DIRECTORY") and hasattr(os, "fdopen"):
+        _atomic_write_posix(absolute.parent, absolute.name, data, absolute)
+    else:
+        _atomic_write_fallback(absolute, data)
+    return p
+
+
+def _atomic_create_posix(parent: Path, name: str, data: bytes, path: Path) -> None:
+    """Publish one fully durable regular file without replacing an existing name."""
+    parent_descriptor = _open_atomic_write_parent(parent)
+    tmp_name = _atomic_write_temp_name(name)
+    temp_exists = False
+    try:
+        _reject_unsafe_atomic_write_target(parent_descriptor, name, path)
+        flags = (
+            os.O_WRONLY
+            | os.O_CREAT
+            | os.O_EXCL
+            | getattr(os, "O_CLOEXEC", 0)
+            | getattr(os, "O_NOFOLLOW", 0)
+        )
+        descriptor = os.open(tmp_name, flags, 0o600, dir_fd=parent_descriptor)
+        temp_exists = True
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+
+        _assert_atomic_write_parent_binding(parent, parent_descriptor)
+        # Hard-link publication is atomic and has no-clobber semantics on both
+        # POSIX and Windows filesystems. The state commit may therefore refer to
+        # either the complete immutable event or no event, never a torn event.
+        if os.link in os.supports_dir_fd:
+            os.link(
+                tmp_name,
+                name,
+                src_dir_fd=parent_descriptor,
+                dst_dir_fd=parent_descriptor,
+            )
+        else:  # pragma: no cover - only platforms without linkat
+            os.link(parent / tmp_name, path)
+
+        if os.unlink in os.supports_dir_fd:
+            os.unlink(tmp_name, dir_fd=parent_descriptor)
+        else:  # pragma: no cover - only platforms without unlinkat
+            (parent / tmp_name).unlink()
+        temp_exists = False
+        try:
+            os.fsync(parent_descriptor)
+        except OSError:  # pragma: no cover - best-effort directory durability
+            pass
+        published = os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+        if not stat.S_ISREG(published.st_mode):
+            raise AtomicWriteIntegrityError(
+                f"atomic create target failed binding validation: {path}"
+            )
+    finally:
+        if temp_exists:
+            try:
+                if os.unlink in os.supports_dir_fd:
+                    os.unlink(tmp_name, dir_fd=parent_descriptor)
+                else:  # pragma: no cover - only platforms without unlinkat
+                    (parent / tmp_name).unlink()
+            except OSError:
+                pass
+        os.close(parent_descriptor)
+
+
+def _atomic_create_fallback(path: Path, data: bytes) -> None:
+    """No-clobber publication with portable ancestor/reparse-point checks."""
+    path = _absolute_lock_path(path)
+    parent_snapshot = _ensure_portable_atomic_parent(path.parent)
+    _reject_unsafe_atomic_write_target(None, path.name, path)
+    tmp = path.with_name(_atomic_write_temp_name(path.name))
+    descriptor = os.open(
+        tmp,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0),
+        0o600,
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            try:
+                os.fsync(handle.fileno())
+            except OSError:  # pragma: no cover - best-effort durability
+                pass
+        _assert_portable_atomic_parent(path.parent, parent_snapshot)
+        _reject_unsafe_atomic_write_target(None, path.name, path)
+        os.link(tmp, path)
+        _assert_portable_atomic_parent(path.parent, parent_snapshot)
+        _reject_unsafe_atomic_write_target(None, path.name, path)
+    finally:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+
+
+def atomic_create_text(path: str | Path, text: str, *, encoding: str = "utf-8") -> Path:
+    """Atomically create an immutable text file and fail if it already exists."""
+    target = Path(path)
+    absolute = _absolute_lock_path(target)
+    data = text.encode(encoding)
+    if hasattr(os, "O_DIRECTORY") and hasattr(os, "fdopen"):
+        _atomic_create_posix(
+            absolute.parent,
+            absolute.name,
+            data,
+            absolute,
+        )
+    else:  # pragma: no cover - exercised on native Windows CI
+        _atomic_create_fallback(absolute, data)
+    return target
+
+
+__all__ = [
+    "AtomicWriteIntegrityError",
+    "CorruptArtifactError",
+    "FileLockIntegrityError",
+    "RequiredFileLockUnavailable",
+    "atomic_create_text",
+    "atomic_write_chunks",
+    "atomic_write_text",
+    "file_lock",
+    "reentrant_file_lock",
+    "required_file_lock",
+    "required_reentrant_file_lock",
+    "safe_load_yaml",
+]