llmt-cli 0.2.0__py3-none-any.whl

llmt/layout.py

@@ -0,0 +1,676 @@
+"""Seeding-layout mapper / link-farm planner (WP-14.2b).
+
+SHA-256 identity proves a file *is* the right bytes, but a BitTorrent client
+will not seed those bytes unless they are presented at the exact path the
+torrent expects, under the torrent's root folder. The user's model already
+lives somewhere on disk (``/models/qwen3-30b/model.gguf``); the torrent wants
+``qwen3-30b-a3b-q4-k-m/Qwen3-30B-A3B-Q4_K_M.gguf`` under some save path. This
+module *plans* how to present the user's existing file to the client WITHOUT
+moving or copying it — by choosing a save path, or by building a small tree of
+hard/symbolic links (a "link farm") that mirrors the expected layout and points
+back at the real file. Your model folder stays your model folder: model
+weights are never re-downloaded. (One honest caveat, M5: when a multi-file
+torrent is only partially present, missing license/README-class companion
+files up to 10 MiB total per container may be fetched by the client, with an
+explicit notice; larger missing files are marked do-not-download instead.)
+
+The engine is split into pure policy (sanitising untrusted server paths, the
+link-type decision matrix, direct-use path matching, Windows drive logic) and
+the thin syscall layer (``apply_plan``). The pure parts are fully unit-testable
+on any OS with no filesystem and no network.
+
+Contract note for WP-14.4-S: the ``LayoutPlan`` / ``PlanAction`` dataclasses and
+``plan_layout`` / ``apply_plan`` signatures below are the frozen public API the
+scan flow builds on. Consumers must branch on ``plan.mode`` to find the
+client-visible path: for ``link-farm`` it is the last action's ``target`` under
+``save_path``; for ``direct-use`` it is ``source_file`` itself, with
+``save_path`` being its containing directory.
+"""
+
+from __future__ import annotations
+
+import ntpath
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from .errors import (
+    LayoutApplyError,
+    LayoutError,
+    LayoutSafetyError,
+    LayoutSourceError,
+)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+#: Default root for generated link farms.
+DEFAULT_BASE_DIR = os.path.join("~", ".llmt", "seeding-layouts")
+
+MAX_SEGMENT = 255  # per-path-component length ceiling (POSIX/NTFS practical max)
+
+# Windows reserved device names (case-insensitive, with or without extension).
+_RESERVED = {"CON", "PRN", "AUX", "NUL"} | {f"COM{i}" for i in range(1, 10)} | {
+    f"LPT{i}" for i in range(1, 10)
+}
+
+LINK_NONE = "none"
+LINK_HARDLINK = "hardlink"
+LINK_SYMLINK = "symlink"
+
+MODE_DIRECT = "direct-use"
+MODE_LINKFARM = "link-farm"
+
+# M5 size-aware sibling policy (Pat's decision, size-aware Option C,
+# 2026-07-13): when a multi-file container is only PARTIALLY present locally,
+# a missing sibling file may be auto-fetched by the torrent client (with an
+# explicit notice) ONLY if it is metadata-class tiny: its own size is
+# <= M5_AUTO_FETCH_MAX_BYTES AND the cumulative size of every auto-fetched
+# file for that container stays <= M5_AUTO_FETCH_MAX_BYTES. Anything larger
+# (model weights/shards) is NEVER downloaded on the user's behalf: it must be
+# marked do-not-download in the client BEFORE any resume, with a warning that
+# the torrent will seed only what the user has and will show as incomplete.
+M5_AUTO_FETCH_MAX_BYTES = 10 * 1024 * 1024
+
+
+def classify_missing_files(
+    missing: "list[tuple[str, Optional[int]]]",
+    *,
+    max_bytes: int = M5_AUTO_FETCH_MAX_BYTES,
+) -> "tuple[list[tuple[str, Optional[int]]], list[tuple[str, Optional[int]]]]":
+    """Pure M5 classifier: split a container's missing files into
+    ``(fetch, skip)``.
+
+    ``missing`` is ``[(in_torrent_path, size_bytes_or_None), ...]``.
+
+    A file goes into ``fetch`` (auto-fetch with a notice) iff its size is
+    KNOWN, ``<= max_bytes``, and the running total of everything already in
+    ``fetch`` stays ``<= max_bytes``. Budget is assigned smallest-first so
+    genuinely tiny metadata files (license/readme) win over mid-size ones;
+    ties break on path for determinism. A file with UNKNOWN size can never
+    be proven tiny, so it fails closed into ``skip`` (do-not-download).
+    Everything else lands in ``skip``.
+    """
+    eligible = sorted(
+        (
+            (path, size) for path, size in missing
+            if isinstance(size, int) and not isinstance(size, bool)
+            and 0 <= size <= max_bytes
+        ),
+        key=lambda ps: (ps[1], ps[0]),
+    )
+    fetch: list[tuple[str, Optional[int]]] = []
+    fetched_paths: set = set()
+    total = 0
+    for path, size in eligible:
+        if total + size <= max_bytes:
+            fetch.append((path, size))
+            fetched_paths.add(path)
+            total += size
+    skip = [(path, size) for path, size in missing
+            if path not in fetched_paths]
+    return fetch, skip
+
+
+#: Documented per-client link-following behaviour. ``True`` = verified in the
+#: client's docs/behaviour; ``"conservative"`` = unverified, warn the user.
+CLIENT_LINK_SUPPORT: dict[str, dict[str, Any]] = {
+    "qbittorrent": {"hardlink": True, "symlink": True},
+    "transmission": {"hardlink": True, "symlink": True},
+    "deluge": {"hardlink": True, "symlink": True},
+    "rtorrent": {"hardlink": True, "symlink": True},
+    "generic": {"hardlink": True, "symlink": "conservative"},
+}
+
+# qBittorrent "add + recheck, seed from existing bytes, never redownload" recipe.
+# WP-14.4-S implements the WebUI calls; this is the contract it targets.
+QBITTORRENT_ADD_RECIPE: dict[str, Any] = {
+    "endpoint": "/api/v2/torrents/add",
+    "savepath": "<LayoutPlan.save_path>",
+    "autoTMM": False,          # do NOT let the client relocate/manage the path
+    "paused": True,            # add paused so we control the recheck order
+    "skip_checking": False,    # MUST hash-check so it discovers the linked bytes
+    "then": [
+        "POST /api/v2/torrents/recheck  (client hashes the linked files -> 100%)",
+        "POST /api/v2/torrents/resume   (start seeding once verified 100%)",
+    ],
+    "notes": (
+        "With autoTMM off and savepath == plan.save_path, the client resolves "
+        "each in-torrent path under savepath, follows the link farm to the real "
+        "file, verifies SHA/piece hashes, and seeds. Model weights are never "
+        "re-downloaded; at most, small missing companion files (M5: license/"
+        "README-class, <=10 MiB total per container, announced with a notice) "
+        "are fetched -- any larger missing file is marked do-not-download "
+        "(priority 0 / files-unwanted) BEFORE the torrent is resumed."
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses (FROZEN public contract for WP-14.4-S)
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class PlanAction:
+    """One step in a plan.
+
+    kind:      "mkdir" | "hardlink" | "symlink" | "none"
+    target:    absolute path the action creates (dir, or link path)
+    source:    absolute real path of the user's file (link kinds); None otherwise
+    rationale: why this action exists
+    """
+
+    kind: str
+    target: str
+    source: Optional[str]
+    rationale: str
+
+
+@dataclass
+class LayoutPlan:
+    """A pure data description of how to present a file for seeding.
+
+    mode:             "direct-use" | "link-farm"
+    save_path:        absolute path to hand the client as its save/download path
+    link_type:        "none" | "hardlink" | "symlink"
+    actions:          ordered PlanAction list (mkdir before link)
+    warnings:         human-readable caveats (platform / client / collision)
+    torrent_root:     sanitised torrent root folder ("" for single-file torrents)
+    in_torrent_path:  sanitised POSIX relative path inside the torrent
+    source_file:      resolved absolute real path of the user's artifact
+    requires_recheck: client must force-recheck to reach 100% (always True)
+    """
+
+    mode: str
+    save_path: str
+    link_type: str
+    actions: list[PlanAction]
+    warnings: list[str] = field(default_factory=list)
+    torrent_root: str = ""
+    in_torrent_path: str = ""
+    source_file: str = ""
+    requires_recheck: bool = True
+
+    def describe(self) -> str:
+        """Human-readable multi-line summary (used by dry-run / CLI later)."""
+        lines = [
+            f"mode={self.mode}  link_type={self.link_type}",
+            f"save_path: {self.save_path}",
+            f"in_torrent_path: {self.in_torrent_path or '(single file)'}",
+        ]
+        for a in self.actions:
+            arrow = f" -> {a.source}" if a.source else ""
+            lines.append(f"  [{a.kind}] {a.target}{arrow}  # {a.rationale}")
+        for w in self.warnings:
+            lines.append(f"  ! {w}")
+        if self.requires_recheck:
+            lines.append("  (client must force-recheck to reach 100%)")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers: OS + path sanitising
+# ---------------------------------------------------------------------------
+
+def normalize_os(os_name: Optional[str]) -> str:
+    """Map to canonical 'posix' | 'windows'. None -> the current interpreter."""
+    if os_name is None:
+        return "windows" if os.name == "nt" else "posix"
+    o = os_name.strip().lower()
+    if o in ("windows", "win", "win32", "nt"):
+        return "windows"
+    if o in ("posix", "linux", "mac", "macos", "darwin", "unix"):
+        return "posix"
+    raise LayoutError(f"unknown os hint {os_name!r}")
+
+
+def _validate_segment(seg: str) -> None:
+    if seg == "..":
+        raise LayoutSafetyError("path traversal segment '..' rejected")
+    if "\x00" in seg:
+        raise LayoutSafetyError("embedded null byte in path segment")
+    if any(ord(c) < 32 for c in seg):
+        raise LayoutSafetyError(f"control character in path segment {seg!r}")
+    if ":" in seg:
+        # kills drive letters (C:) and NTFS alternate data streams (file:stream)
+        raise LayoutSafetyError(f"illegal ':' in path segment {seg!r}")
+    if len(seg) > MAX_SEGMENT:
+        raise LayoutSafetyError(
+            f"path segment too long ({len(seg)} > {MAX_SEGMENT}): {seg[:32]!r}..."
+        )
+    # Windows silently strips trailing dots/spaces when resolving names, so
+    # "CON " or "NUL." still hits the device. Strip them BEFORE the reserved
+    # compare, and reject a segment that strips to nothing.
+    stripped = seg.rstrip(" .")
+    if not stripped:
+        raise LayoutSafetyError(
+            f"path segment {seg!r} is empty after stripping trailing dots/spaces"
+        )
+    stem = stripped.split(".", 1)[0].upper()
+    if stem in _RESERVED:
+        raise LayoutSafetyError(f"reserved device name in path: {seg!r}")
+
+
+def sanitize_relpath(raw: Optional[str]) -> list[str]:
+    """Turn an untrusted server-supplied in-torrent path into safe segments.
+
+    Splits on BOTH separators (a hostile server could send backslashes), drops
+    empty and ``.`` segments, and rejects anything dangerous. Returns the clean
+    ordered segment list (never empty). Absolute inputs are neutralised into a
+    relative path (their leading separator is simply dropped).
+    """
+    if raw is None:
+        raise LayoutSafetyError("in-torrent path is empty")
+    if "\x00" in raw:
+        raise LayoutSafetyError("embedded null byte in path")
+    parts = re.split(r"[\\/]+", raw.strip())
+    segments: list[str] = []
+    for seg in parts:
+        if seg in ("", "."):
+            continue
+        _validate_segment(seg)
+        segments.append(seg)
+    if not segments:
+        raise LayoutSafetyError(f"path {raw!r} has no usable segments")
+    return segments
+
+
+def safe_join(base_abs: str, segments: list[str]) -> str:
+    """Join sanitised segments under ``base_abs`` and prove no escape.
+
+    Belt-and-suspenders on top of :func:`sanitize_relpath`: normalises and
+    verifies the result still lives under ``base_abs`` via ``commonpath``.
+    """
+    base_norm = os.path.normpath(base_abs)
+    joined = os.path.normpath(os.path.join(base_norm, *segments))
+    try:
+        common = os.path.commonpath([base_norm, joined])
+    except ValueError:  # different drives on Windows
+        raise LayoutSafetyError(f"link path {joined!r} escapes base {base_norm!r}")
+    if os.path.normcase(common) != os.path.normcase(base_norm):
+        raise LayoutSafetyError(f"link path {joined!r} escapes base {base_norm!r}")
+    return joined
+
+
+def directory_for_direct_use(
+    local_abspath: str,
+    in_torrent_segments: list[str],
+    *,
+    sep: str = os.sep,
+    case_sensitive: bool = True,
+) -> Optional[str]:
+    """If the file already sits at ``D/<in-torrent path>``, return ``D``.
+
+    Pure: matches the trailing segments of ``local_abspath`` against the
+    expected in-torrent segments. Returns the directory ``D`` (the save path
+    for the direct-use case) or None when the layout does not already match.
+    """
+    parts = [p for p in local_abspath.split(sep) if p != ""]
+    n = len(in_torrent_segments)
+    if n == 0 or len(parts) < n:
+        return None
+    tail = parts[-n:]
+    if case_sensitive:
+        if tail != in_torrent_segments:
+            return None
+    else:
+        if [t.lower() for t in tail] != [s.lower() for s in in_torrent_segments]:
+            return None
+    lead = parts[:-n]
+    if local_abspath.startswith(sep):
+        return sep + sep.join(lead) if lead else sep
+    return sep.join(lead) if lead else "."
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers: link-type decision matrix
+# ---------------------------------------------------------------------------
+
+def decide_link_type(
+    os_name: str,
+    same_volume: bool,
+    client: str = "qbittorrent",
+) -> tuple[str, list[str]]:
+    """The link-type decision matrix (pure, exhaustively unit-tested).
+
+    Rule of thumb: prefer a hardlink whenever the file and the farm live on the
+    same volume — hardlinks are invisible to the client, need no privileges, and
+    every client follows them. A symlink is the labelled cross-volume fallback.
+
+        POSIX  same volume  -> hardlink
+        POSIX  cross volume -> symlink   (hardlink impossible across filesystems)
+        Win    same volume  -> hardlink  (same drive, no admin needed)
+        Win    cross volume -> symlink   (junctions redirect DIRS only, not files;
+                                          symlink needs Admin / Developer Mode)
+    """
+    warnings: list[str] = []
+    client = (client or "generic").lower()
+    caps = CLIENT_LINK_SUPPORT.get(client, CLIENT_LINK_SUPPORT["generic"])
+
+    if same_volume:
+        return LINK_HARDLINK, warnings
+
+    if os_name == "windows":
+        warnings.append(
+            "Cross-volume on Windows: hardlinks cannot span volumes, and NTFS "
+            "junctions redirect DIRECTORIES only (not individual files), so the "
+            "only option for a file is a symbolic link, which requires "
+            "Administrator privileges or Windows Developer Mode."
+        )
+    else:
+        warnings.append(
+            "Cross-filesystem: hardlinks cannot span filesystems; using a "
+            "symbolic link instead."
+        )
+    if caps.get("symlink") is not True:
+        warnings.append(
+            f"Client '{client}' symlink-following is unverified; qBittorrent "
+            f"follows symlinks — confirm your client does before relying on it."
+        )
+    return LINK_SYMLINK, warnings
+
+
+def _same_drive_windows(a: str, b: str) -> bool:
+    """Heuristic: same Windows volume == same drive letter / UNC share.
+
+    We compare ``os.path.splitdrive`` prefixes case-insensitively. This is a
+    heuristic — mounted volume GUIDs and NTFS mount points can defeat drive-
+    letter comparison — so cross-volume mis-detection degrades safely toward the
+    symlink fallback, never toward a hardlink that would fail at apply time.
+    """
+    # ntpath (not os.path) so the Windows heuristic is correct even when the
+    # planner runs on a POSIX host planning for a Windows client.
+    da = ntpath.splitdrive(a)[0].upper()
+    db = ntpath.splitdrive(b)[0].upper()
+    return da == db
+
+
+def _nearest_existing(path: str) -> str:
+    p = os.path.abspath(path)
+    while p and not os.path.exists(p):
+        parent = os.path.dirname(p)
+        if parent == p:
+            break
+        p = parent
+    return p
+
+
+def detect_same_volume(source_real: str, dest_base: str, os_name: str) -> bool:
+    """Are the user's file and the (maybe-not-yet-existing) farm co-located?
+
+    POSIX: compare ``st_dev`` of the source and the nearest existing ancestor of
+    the farm base. Windows: compare drive letters (documented heuristic above).
+    """
+    if os_name == "windows":
+        return _same_drive_windows(source_real, dest_base)
+    src_dev = os.stat(source_real).st_dev
+    dst_dev = os.stat(_nearest_existing(dest_base)).st_dev
+    return src_dev == dst_dev
+
+
+# ---------------------------------------------------------------------------
+# Planner
+# ---------------------------------------------------------------------------
+
+def _container_path(container: dict[str, Any]) -> str:
+    raw = container.get("path") or container.get("file_name")
+    if not raw:
+        raise LayoutError(
+            "container has neither 'path' nor 'file_name' to map a layout from"
+        )
+    return raw
+
+
+def plan_layout(
+    local_file: str,
+    container: dict[str, Any],
+    *,
+    base_dir: Optional[str] = None,
+    client: str = "qbittorrent",
+    os_name: Optional[str] = None,
+    same_device: Optional[bool] = None,
+) -> LayoutPlan:
+    """Plan how to present ``local_file`` for seeding ``container``.
+
+    Args:
+        local_file:  absolute path to the user's SHA-verified artifact.
+        container:   a WP-14.2 container object (uses ``path`` / ``file_name``).
+        base_dir:    link-farm root (default ``~/.llmt/seeding-layouts``).
+        client:      client hint for the symlink-caveat table.
+        os_name:     "posix" | "windows" | None (current interpreter).
+        same_device: override device-colocation detection (mainly for tests).
+
+    Returns a :class:`LayoutPlan`. Does not touch the filesystem except to stat
+    the source (existence / regular-file / device) — no dirs or links created.
+    """
+    os_name = normalize_os(os_name)
+
+    # 1. Validate the source. We resolve symlinks so a symlinked input still
+    #    yields a correct link to the underlying regular file; we require the
+    #    RESOLVED path to be an existing regular file.
+    src = os.path.abspath(os.path.expanduser(local_file))
+    real = os.path.realpath(src)
+    if not os.path.lexists(src):
+        raise LayoutSourceError(f"source file does not exist: {local_file}")
+    if not os.path.exists(real):
+        raise LayoutSourceError(
+            f"source is a broken symlink (resolves to a missing target): {local_file}"
+        )
+    if not os.path.isfile(real):
+        raise LayoutSourceError(
+            f"source is not a regular file (dir/device/socket?): {local_file}"
+        )
+
+    # 2. Sanitise the untrusted in-torrent path.
+    segments = sanitize_relpath(_container_path(container))
+    torrent_root = segments[0] if len(segments) > 1 else ""
+    in_torrent_path = "/".join(segments)
+
+    # 3. Direct-use: the file already sits at D/<in-torrent path>.
+    case_sensitive = os_name != "windows"
+    d = directory_for_direct_use(
+        real, segments, sep=os.sep, case_sensitive=case_sensitive
+    )
+    if d is not None:
+        return LayoutPlan(
+            mode=MODE_DIRECT,
+            save_path=os.path.normpath(d),
+            link_type=LINK_NONE,
+            actions=[PlanAction(
+                kind="none", target=real, source=None,
+                rationale="file already at the exact expected relative path; "
+                          "add the torrent with this save path, no links needed",
+            )],
+            warnings=[],
+            torrent_root=torrent_root,
+            in_torrent_path=in_torrent_path,
+            source_file=real,
+        )
+
+    # 4. Link-farm.
+    base = base_dir if base_dir is not None else DEFAULT_BASE_DIR
+    base_abs = os.path.normpath(os.path.abspath(os.path.expanduser(base)))
+    link_path = safe_join(base_abs, segments)
+    dest_parent = os.path.dirname(link_path)
+
+    if same_device is None:
+        same_device = detect_same_volume(real, base_abs, os_name)
+    link_type, warnings = decide_link_type(os_name, same_device, client)
+
+    actions = [
+        PlanAction(
+            kind="mkdir", target=dest_parent, source=None,
+            rationale="create the link-farm directory mirroring the torrent root",
+        ),
+        PlanAction(
+            kind=link_type, target=link_path, source=real,
+            rationale=(
+                f"{link_type} the expected in-torrent path to the user's real "
+                f"file (no copy, no move)"
+            ),
+        ),
+    ]
+
+    if torrent_root == "":
+        warnings = warnings + [
+            "Single-file torrent (no root folder): the link lives directly under "
+            "the layouts base and could collide with another single-file "
+            "torrent's file of the same name — use a per-torrent base_dir if you "
+            "seed several single-file torrents."
+        ]
+
+    return LayoutPlan(
+        mode=MODE_LINKFARM,
+        save_path=base_abs,
+        link_type=link_type,
+        actions=actions,
+        warnings=warnings,
+        torrent_root=torrent_root,
+        in_torrent_path=in_torrent_path,
+        source_file=real,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Executor
+# ---------------------------------------------------------------------------
+
+def _assert_farm_path_safe(base: str, path: str) -> None:
+    """F1 defense: refuse to write through symlinked components under the farm.
+
+    ``safe_join``'s containment is lexical-only; once the real filesystem is
+    involved, a pre-planted symlink at ``<base>/<root>`` (or any intermediate
+    component) would redirect mkdir/link through it to an arbitrary location
+    outside the farm. Before any write we (a) walk every path component below
+    ``realpath(base)`` and reject symlinks, and (b) verify the realpath of the
+    destination still resolves inside the real base.
+    """
+    base_norm = os.path.normpath(os.path.abspath(base))
+    base_real = os.path.realpath(base_norm)
+    path_norm = os.path.normpath(os.path.abspath(path))
+    rel = os.path.relpath(path_norm, base_norm)
+    if rel == os.curdir:
+        return
+    if rel == os.pardir or rel.startswith(os.pardir + os.sep) or os.path.isabs(rel):
+        raise LayoutSafetyError(
+            f"farm path {path_norm!r} escapes base {base_norm!r}"
+        )
+    cur = base_real
+    for seg in rel.split(os.sep):
+        if seg in ("", os.curdir):
+            continue
+        cur = os.path.join(cur, seg)
+        if os.path.islink(cur):
+            raise LayoutSafetyError(
+                f"refusing to write through symlinked farm component: {cur!r}"
+            )
+    real = os.path.realpath(path_norm)
+    try:
+        common = os.path.commonpath([base_real, real])
+    except ValueError:
+        raise LayoutSafetyError(
+            f"farm path {path_norm!r} resolves outside base {base_real!r}"
+        )
+    if os.path.normcase(common) != os.path.normcase(base_real):
+        raise LayoutSafetyError(
+            f"farm path {path_norm!r} resolves to {real!r}, outside base {base_real!r}"
+        )
+
+
+def _existing_target_status(action: PlanAction) -> str:
+    """'absent' | 'ok' (idempotent match) | 'wrong' (points elsewhere)."""
+    t = action.target
+    if not os.path.lexists(t):
+        return "absent"
+    if action.kind == LINK_HARDLINK:
+        try:
+            if os.path.exists(t) and os.path.samefile(t, action.source):
+                return "ok"
+        except OSError:
+            return "wrong"
+        return "wrong"
+    if action.kind == LINK_SYMLINK:
+        if os.path.islink(t):
+            try:
+                if os.path.realpath(t) == os.path.realpath(action.source):
+                    return "ok"
+                if os.readlink(t) == action.source:
+                    return "ok"
+            except OSError:
+                return "wrong"
+        return "wrong"
+    return "absent"
+
+
+def apply_plan(plan: LayoutPlan, *, dry_run: bool = False) -> list[str]:
+    """Execute (or, with ``dry_run``, describe) a plan. Idempotent.
+
+    Re-applying a plan is a series of no-ops. An existing link that already
+    points at the right file is left alone; an existing path that points at the
+    WRONG target raises :class:`LayoutApplyError` — we NEVER silently replace it.
+    Returns a human-readable action log.
+    """
+    log: list[str] = []
+
+    # F1: validate every write destination against planted-symlink redirection
+    # BEFORE executing anything (also in dry-run — a poisoned farm is an error).
+    if plan.mode == MODE_LINKFARM:
+        for act in plan.actions:
+            if act.kind == "mkdir":
+                _assert_farm_path_safe(plan.save_path, act.target)
+            elif act.kind in (LINK_HARDLINK, LINK_SYMLINK):
+                _assert_farm_path_safe(plan.save_path, os.path.dirname(act.target))
+
+    for act in plan.actions:
+        if act.kind == "none":
+            log.append(f"ok (direct-use): {act.target} already in place")
+            continue
+
+        if act.kind == "mkdir":
+            if dry_run:
+                log.append(f"mkdir -p {act.target}")
+            else:
+                os.makedirs(act.target, exist_ok=True)
+                log.append(f"mkdir -p {act.target}  [done]")
+            continue
+
+        if act.kind in (LINK_HARDLINK, LINK_SYMLINK):
+            status = _existing_target_status(act)
+            if status == "ok":
+                log.append(f"ok (exists): {act.kind} {act.target} -> {act.source}")
+                continue
+            if status == "wrong":
+                raise LayoutApplyError(
+                    f"refusing to replace {act.target!r}: it already exists and "
+                    f"does NOT point at {act.source!r}",
+                    hint="remove or fix the existing path by hand, then re-apply",
+                )
+            # absent -> create
+            if dry_run:
+                log.append(f"{act.kind} {act.target} -> {act.source}")
+                continue
+            try:
+                if act.kind == LINK_HARDLINK:
+                    os.link(act.source, act.target)
+                else:
+                    os.symlink(act.source, act.target)
+            except OSError as e:
+                hint = (
+                    "hardlinks require the same filesystem/volume; if the file "
+                    "and the layouts dir are on different volumes, re-plan for a "
+                    "symlink"
+                    if act.kind == LINK_HARDLINK
+                    else "symlinks may need elevated privileges (Windows Admin / "
+                    "Developer Mode)"
+                )
+                raise LayoutApplyError(
+                    f"{act.kind} failed for {act.target!r}: {e}", hint=hint
+                )
+            log.append(f"{act.kind} {act.target} -> {act.source}  [done]")
+            continue
+
+        raise LayoutApplyError(f"unknown action kind: {act.kind!r}")
+
+    return log