cortex-llm 1.0.10__py3-none-any.whl → 1.0.11__py3-none-any.whl

cortex/__init__.py

@@ -5,7 +5,7 @@ A high-performance terminal interface for running Hugging Face LLMs locally
 with exclusive GPU acceleration via Metal Performance Shaders (MPS) and MLX.
 """
 
-__version__ = "1.0.10"
+__version__ = "1.0.11"
 __author__ = "Cortex Development Team"
 __license__ = "MIT"
 

cortex/config.py

@@ -146,18 +146,21 @@ class DeveloperConfig(BaseModel):
 
 class PathsConfig(BaseModel):
     """Path configuration."""
-    claude_md_path: Path = Field(default_factory=lambda: Path("./CLAUDE.md"))
     templates_dir: Path = Field(default_factory=lambda: Path.home() / ".cortex" / "templates")
     plugins_dir: Path = Field(default_factory=lambda: Path.home() / ".cortex" / "plugins")
 
 class Config:
     """Main configuration class for Cortex."""
-    
+
+    # State file for runtime state (not committed to git)
+    STATE_FILE = Path.home() / ".cortex" / "state.yaml"
+
     def __init__(self, config_path: Optional[Path] = None):
         """Initialize configuration."""
         self.config_path = config_path or Path("config.yaml")
         self._raw_config: Dict[str, Any] = {}
-        
+        self._state: Dict[str, Any] = {}
+
         self.gpu: GPUConfig
         self.memory: MemoryConfig
         self.performance: PerformanceConfig
@@ -169,8 +172,9 @@ class Config:
         self.system: SystemConfig
         self.developer: DeveloperConfig
         self.paths: PathsConfig
-        
+
         self.load()
+        self._load_state()
     
     def load(self) -> None:
         """Load configuration from YAML file."""
@@ -273,7 +277,7 @@ class Config:
             
             self.paths = PathsConfig(**self._get_section({
                 k: v for k, v in self._raw_config.items()
-                if k in ["claude_md_path", "templates_dir", "plugins_dir"]
+                if k in ["templates_dir", "plugins_dir"]
             }))
             
         except Exception as e:
@@ -303,26 +307,58 @@ class Config:
     def save(self, path: Optional[Path] = None) -> None:
         """Save configuration to YAML file."""
         save_path = path or self.config_path
-        
+
+        # Keys that belong in state file, not config file
+        state_keys = {"last_used_model"}
+
         # Convert Path objects to strings for YAML serialization
         config_dict = {}
         for section in [self.gpu, self.memory, self.performance, self.inference,
                        self.model, self.ui, self.logging, self.conversation,
                        self.system, self.developer, self.paths]:
             section_dict = section.model_dump()
-            # Convert Path objects to strings
+            # Convert Path objects to strings and exclude state keys
             for key, value in section_dict.items():
+                if key in state_keys:
+                    continue  # Skip state keys - they go in state file
                 if isinstance(value, Path):
                     section_dict[key] = str(value)
+            # Remove state keys from section_dict
+            for key in state_keys:
+                section_dict.pop(key, None)
             config_dict.update(section_dict)
-        
+
         with open(save_path, 'w') as f:
             yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False)
     
+    def _load_state(self) -> None:
+        """Load runtime state from state file."""
+        if self.STATE_FILE.exists():
+            try:
+                with open(self.STATE_FILE, 'r') as f:
+                    self._state = yaml.safe_load(f) or {}
+                # Apply state to model config
+                if "last_used_model" in self._state:
+                    self.model.last_used_model = self._state["last_used_model"]
+            except Exception as e:
+                print(f"Warning: Failed to load state from {self.STATE_FILE}: {e}")
+                self._state = {}
+
+    def _save_state(self) -> None:
+        """Save runtime state to state file."""
+        # Ensure directory exists
+        self.STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(self.STATE_FILE, 'w') as f:
+                yaml.dump(self._state, f, default_flow_style=False)
+        except Exception as e:
+            print(f"Warning: Failed to save state to {self.STATE_FILE}: {e}")
+
     def update_last_used_model(self, model_name: str) -> None:
-        """Update the last used model and save to config file."""
+        """Update the last used model and save to state file."""
         self.model.last_used_model = model_name
-        self.save()
+        self._state["last_used_model"] = model_name
+        self._save_state()
     
     def __repr__(self) -> str:
         """String representation."""

cortex/inference_engine.py

@@ -82,6 +82,62 @@ class GenerationRequest:
         if self.stop_sequences is None:
             self.stop_sequences = []
 
+
+class StreamDeltaNormalizer:
+    """Normalize streaming chunks to deltas, handling cumulative or overlapping output."""
+
+    def __init__(self, max_overlap: int = 4096, min_cumulative_length: int = 32) -> None:
+        self._total_text = ""
+        self._max_overlap = max_overlap
+        self._min_cumulative_length = min_cumulative_length
+        self._cumulative_mode = False
+
+    def normalize(self, chunk: Any) -> str:
+        if chunk is None:
+            return ""
+        if not isinstance(chunk, str):
+            chunk = str(chunk)
+        if not chunk:
+            return ""
+
+        if not self._total_text:
+            self._total_text = chunk
+            return chunk
+
+        if not self._cumulative_mode:
+            if len(chunk) > len(self._total_text) and chunk.startswith(self._total_text):
+                self._cumulative_mode = True
+                delta = chunk[len(self._total_text):]
+                self._total_text = chunk
+                return delta
+            if chunk == self._total_text and len(chunk) >= self._min_cumulative_length:
+                # Likely a cumulative stream repeating the full text; don't re-emit.
+                self._cumulative_mode = True
+                return ""
+            # Default to delta mode to avoid dropping legitimate repeats.
+            self._total_text += chunk
+            return chunk
+
+        # Cumulative mode: emit only new suffix.
+        if chunk.startswith(self._total_text):
+            delta = chunk[len(self._total_text):]
+            self._total_text = chunk
+            return delta
+
+        # Handle partial overlap in cumulative streams.
+        max_overlap = min(len(self._total_text), len(chunk), self._max_overlap)
+        if max_overlap > 0:
+            tail = self._total_text[-max_overlap:]
+            for i in range(max_overlap, 0, -1):
+                if tail[-i:] == chunk[:i]:
+                    delta = chunk[i:]
+                    self._total_text += delta
+                    return delta
+
+        # Fallback: treat as fresh delta to avoid loss.
+        self._total_text += chunk
+        return chunk
+
 class InferenceEngine:
     """GPU-accelerated inference engine."""
     
@@ -243,33 +299,7 @@ class InferenceEngine:
         tokens_generated = 0
         first_token_time = None
         last_metrics_update = time.time()
-        stream_total_text = ""
-        stream_cumulative = False
-
-        def normalize_stream_chunk(chunk: Any) -> str:
-            """Normalize streaming output to delta chunks when backend yields cumulative text."""
-            nonlocal stream_total_text, stream_cumulative
-            if chunk is None:
-                return ""
-            if not isinstance(chunk, str):
-                chunk = str(chunk)
-
-            if stream_cumulative:
-                if chunk.startswith(stream_total_text):
-                    delta = chunk[len(stream_total_text):]
-                    stream_total_text = chunk
-                    return delta
-                stream_total_text += chunk
-                return chunk
-
-            if stream_total_text and len(chunk) > len(stream_total_text) and chunk.startswith(stream_total_text):
-                stream_cumulative = True
-                delta = chunk[len(stream_total_text):]
-                stream_total_text = chunk
-                return delta
-
-            stream_total_text += chunk
-            return chunk
+        normalizer = StreamDeltaNormalizer() if request.stream else None
         
         try:
             # Use MLX accelerator's optimized generation if available
@@ -290,7 +320,7 @@ class InferenceEngine:
                         self.status = InferenceStatus.CANCELLED
                         break
 
-                    delta = normalize_stream_chunk(token) if request.stream else str(token)
+                    delta = normalizer.normalize(token) if normalizer else str(token)
                     if not delta:
                         continue
 
@@ -365,7 +395,7 @@ class InferenceEngine:
                     else:
                         token = str(response)
 
-                    delta = normalize_stream_chunk(token) if request.stream else token
+                    delta = normalizer.normalize(token) if normalizer else token
                     if request.stream and not delta:
                         continue
 
@@ -477,6 +507,7 @@ class InferenceEngine:
                 if request.stream:
                     from transformers import TextIteratorStreamer
                     
+                    normalizer = StreamDeltaNormalizer()
                     streamer = TextIteratorStreamer(
                         tokenizer,
                         skip_prompt=True,
@@ -499,6 +530,10 @@ class InferenceEngine:
                         if self._cancel_event.is_set():
                             self.status = InferenceStatus.CANCELLED
                             break
+
+                        delta = normalizer.normalize(token)
+                        if not delta:
+                            continue
                         
                         if first_token_time is None:
                             first_token_time = time.time() - start_time
@@ -523,7 +558,7 @@ class InferenceEngine:
                             )
                             last_metrics_update = current_time
                         
-                        yield token
+                        yield delta
                         
                         if any(stop in token for stop in request.stop_sequences):
                             break
@@ -603,6 +638,7 @@ class InferenceEngine:
             )
             
             if request.stream:
+                normalizer = StreamDeltaNormalizer()
                 # Stream tokens
                 for chunk in response:
                     if self._cancel_event.is_set():
@@ -610,11 +646,12 @@ class InferenceEngine:
                     
                     if 'choices' in chunk and len(chunk['choices']) > 0:
                         token = chunk['choices'][0].get('text', '')
-                        if token:
+                        delta = normalizer.normalize(token)
+                        if delta:
                             if first_token_time is None:
                                 first_token_time = time.time()
                             tokens_generated += 1
-                            yield token
+                            yield delta
             else:
                 # Return full response
                 if 'choices' in response and len(response['choices']) > 0:

cortex/tools/fs_ops.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import hashlib
 import os
+import re
 import subprocess
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
@@ -20,13 +21,45 @@ class RepoFS:
     def resolve_path(self, path: str) -> Path:
         if not path or not isinstance(path, str):
             raise ValidationError("path must be a non-empty string")
-        raw = Path(path).expanduser()
-        resolved = raw.resolve() if raw.is_absolute() else (self.root / raw).resolve()
+        if "\x00" in path:
+            raise ValidationError("path contains null byte")
+        if path.startswith("~"):
+            raise ValidationError("path must be repo-relative (no ~)")
+        raw = Path(path)
+        if raw.is_absolute():
+            raise ValidationError("path must be repo-relative (no absolute paths)")
+        resolved = (self.root / raw).resolve()
         if not resolved.is_relative_to(self.root):
             raise ValidationError(f"path escapes repo root ({self.root}); use a relative path like '.'")
         return resolved
 
+    def _validate_bool(self, name: str, value: object) -> None:
+        if not isinstance(value, bool):
+            raise ValidationError(f"{name} must be a bool")
+
+    def _validate_int(self, name: str, value: object, minimum: int = 0) -> int:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValidationError(f"{name} must be an int")
+        if value < minimum:
+            raise ValidationError(f"{name} must be >= {minimum}")
+        return value
+
+    def _validate_content(self, content: object) -> None:
+        if not isinstance(content, str):
+            raise ValidationError("content must be a string")
+
+    def _validate_sha256(self, value: object) -> str:
+        if not isinstance(value, str):
+            raise ValidationError("expected_sha256 must be a string")
+        normalized = value.lower()
+        if not re.fullmatch(r"[0-9a-f]{64}", normalized):
+            raise ValidationError("expected_sha256 must be a 64-character hex string")
+        return normalized
+
     def list_dir(self, path: str = ".", recursive: bool = False, max_depth: int = 2, max_entries: int = 200) -> Dict[str, List[str]]:
+        self._validate_bool("recursive", recursive)
+        max_depth = self._validate_int("max_depth", max_depth, minimum=0)
+        max_entries = self._validate_int("max_entries", max_entries, minimum=1)
         target = self.resolve_path(path)
         if not target.is_dir():
             raise ValidationError("path is not a directory")
@@ -59,25 +92,28 @@ class RepoFS:
         return {"entries": entries}
 
     def read_text(self, path: str, start_line: int = 1, end_line: Optional[int] = None, max_bytes: int = 2_000_000) -> Dict[str, object]:
+        start_line = self._validate_int("start_line", start_line, minimum=1)
+        if end_line is not None:
+            end_line = self._validate_int("end_line", end_line, minimum=start_line)
+        max_bytes = self._validate_int("max_bytes", max_bytes, minimum=1)
         target = self.resolve_path(path)
         if not target.is_file():
             raise ValidationError("path is not a file")
         size = target.stat().st_size
         if size > max_bytes and start_line == 1 and end_line is None:
             raise ToolError("file too large; specify a line range")
-        if start_line < 1:
-            raise ValidationError("start_line must be >= 1")
-        if end_line is not None and end_line < start_line:
-            raise ValidationError("end_line must be >= start_line")
 
         lines: List[str] = []
-        with target.open("r", encoding="utf-8") as handle:
-            for idx, line in enumerate(handle, start=1):
-                if idx < start_line:
-                    continue
-                if end_line is not None and idx > end_line:
-                    break
-                lines.append(line.rstrip("\n"))
+        try:
+            with target.open("r", encoding="utf-8") as handle:
+                for idx, line in enumerate(handle, start=1):
+                    if idx < start_line:
+                        continue
+                    if end_line is not None and idx > end_line:
+                        break
+                    lines.append(line.rstrip("\n"))
+        except UnicodeDecodeError as e:
+            raise ToolError(f"file is not valid utf-8: {e}") from e
         content = "\n".join(lines)
         return {"path": str(target.relative_to(self.root)), "content": content, "start_line": start_line, "end_line": end_line}
 
@@ -91,6 +127,9 @@ class RepoFS:
             raise ToolError(f"file is not valid utf-8: {e}") from e
 
     def write_text(self, path: str, content: str, expected_sha256: Optional[str] = None) -> Dict[str, object]:
+        self._validate_content(content)
+        if expected_sha256 is not None:
+            expected_sha256 = self._validate_sha256(expected_sha256)
         target = self.resolve_path(path)
         if not target.exists() or not target.is_file():
             raise ValidationError("path does not exist or is not a file")
@@ -102,7 +141,11 @@ class RepoFS:
         return {"path": str(target.relative_to(self.root)), "sha256": self.sha256_text(content)}
 
     def create_text(self, path: str, content: str, overwrite: bool = False) -> Dict[str, object]:
+        self._validate_content(content)
+        self._validate_bool("overwrite", overwrite)
         target = self.resolve_path(path)
+        if target.exists() and target.is_dir():
+            raise ValidationError("path already exists and is a directory")
         if target.exists() and not overwrite:
             raise ValidationError("path already exists")
         target.parent.mkdir(parents=True, exist_ok=True)
@@ -118,6 +161,10 @@ class RepoFS:
         target.unlink()
         return {"path": str(target.relative_to(self.root)), "deleted": True}
 
+    def is_git_tracked(self, target: Path) -> bool:
+        """Return True if the path is tracked by git."""
+        return self._is_git_tracked(target)
+
     def sha256_text(self, content: str) -> str:
         return hashlib.sha256(content.encode("utf-8")).hexdigest()
 

cortex/tools/search.py

@@ -7,7 +7,7 @@ import re
 import shutil
 import subprocess
 from pathlib import Path
-from typing import Dict, List
+from typing import Dict, List, Optional
 
 from cortex.tools.errors import ToolError, ValidationError
 from cortex.tools.fs_ops import RepoFS
@@ -16,16 +16,37 @@ from cortex.tools.fs_ops import RepoFS
 class RepoSearch:
     """Search helper constrained to a repo root."""
 
+    _DEFAULT_SKIP_DIRS = {
+        ".git",
+        ".cortex",
+        ".eggs",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "venv",
+    }
+
     def __init__(self, repo_fs: RepoFS) -> None:
         self.repo_fs = repo_fs
 
     def search(self, query: str, path: str = ".", use_regex: bool = True, max_results: int = 100) -> Dict[str, List[Dict[str, object]]]:
         if not isinstance(query, str) or not query:
             raise ValidationError("query must be a non-empty string")
+        if isinstance(max_results, bool) or not isinstance(max_results, int):
+            raise ValidationError("max_results must be an int")
         if max_results < 1:
             raise ValidationError("max_results must be >= 1")
-        root = self.repo_fs.root
+        if not isinstance(use_regex, bool):
+            raise ValidationError("use_regex must be a bool")
         target = self.repo_fs.resolve_path(path)
+        if not target.exists():
+            raise ValidationError("path does not exist")
 
         if shutil.which("rg"):
             return {"results": self._rg_search(query, target, use_regex, max_results)}
@@ -51,20 +72,64 @@ class RepoSearch:
         return matches
 
     def _python_search(self, query: str, target: Path, use_regex: bool, max_results: int) -> List[Dict[str, object]]:
-        pattern = re.compile(query) if use_regex else None
+        pattern: Optional[re.Pattern[str]] = None
+        if use_regex:
+            try:
+                pattern = re.compile(query)
+            except re.error as e:
+                raise ValidationError(f"invalid regex: {e}") from e
         results: List[Dict[str, object]] = []
+
+        if target.is_file():
+            if self._looks_binary(target):
+                return results
+            self._scan_file(target, pattern, query, results, max_results)
+            return results
+
+        skip_dirs = set(self._DEFAULT_SKIP_DIRS)
+        if target.name in skip_dirs:
+            skip_dirs.remove(target.name)
+
         for dirpath, dirnames, filenames in os.walk(target):
-            dirnames[:] = [d for d in dirnames if d != ".git"]
+            dirnames[:] = [d for d in dirnames if d not in skip_dirs]
             for name in filenames:
                 path = Path(dirpath) / name
-                try:
-                    text = path.read_text(encoding="utf-8")
-                except Exception:
+                if self._looks_binary(path):
                     continue
-                for idx, line in enumerate(text.splitlines(), start=1):
+                if self._scan_file(path, pattern, query, results, max_results):
+                    return results
+        return results
+
+    def _scan_file(
+        self,
+        path: Path,
+        pattern: Optional[re.Pattern[str]],
+        query: str,
+        results: List[Dict[str, object]],
+        max_results: int,
+    ) -> bool:
+        try:
+            with path.open("r", encoding="utf-8", errors="ignore") as handle:
+                for idx, line in enumerate(handle, start=1):
                     found = bool(pattern.search(line)) if pattern else (query in line)
                     if found:
-                        results.append({"path": str(path.relative_to(self.repo_fs.root)), "line": idx, "text": line})
+                        results.append(
+                            {
+                                "path": str(path.relative_to(self.repo_fs.root)),
+                                "line": idx,
+                                "text": line.rstrip("\n"),
+                            }
+                        )
                         if len(results) >= max_results:
-                            return results
-        return results
+                            return True
+        except OSError:
+            return False
+        return False
+
+    def _looks_binary(self, path: Path, sniff_bytes: int = 4096) -> bool:
+        try:
+            with path.open("rb") as handle:
+                chunk = handle.read(sniff_bytes)
+        except OSError:
+            return True
+        return b"\x00" in chunk

cortex/tools/tool_runner.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import difflib
 import json
+import os
+import re
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
@@ -28,7 +30,7 @@ class ToolRunner:
 
     def tool_spec(self) -> Dict[str, Any]:
         return {
-            "list_dir": {"args": {"path": "string", "recursive": "bool", "max_depth": "int"}},
+            "list_dir": {"args": {"path": "string", "recursive": "bool", "max_depth": "int", "max_entries": "int"}},
             "read_file": {"args": {"path": "string", "start_line": "int", "end_line": "int", "max_bytes": "int"}},
             "search": {"args": {"query": "string", "path": "string", "use_regex": "bool", "max_results": "int"}},
             "write_file": {"args": {"path": "string", "content": "string", "expected_sha256": "string"}},
@@ -43,11 +45,15 @@ class ToolRunner:
         spec = json.dumps(self.tool_spec(), ensure_ascii=True, indent=2)
         repo_root = str(self.fs.root)
         return (
-            "[CORTEX_TOOL_INSTRUCTIONS v2]\n"
-            "You have access to file tools. If a tool is required, respond ONLY with a <tool_calls> JSON block.\n"
+            "[CORTEX_TOOL_INSTRUCTIONS v3]\n"
+            "You have access to repo-scoped file tools.\n"
+            "Use tools ONLY when the user asks for repo file operations or when repo data is required to answer.\n"
+            "Never use tools for general conversation, creative writing, or questions unrelated to the repo.\n"
+            "If a tool is required, respond ONLY with a <tool_calls> JSON block.\n"
             "Do not include any other text when calling tools.\n"
             f"Repo root: {repo_root}\n"
             "All paths must be relative to the repo root (use '.' for root). Do not use absolute paths or ~.\n"
+            "For create/write/replace/insert/delete, paths must be file paths (not '.' or directories).\n"
             "If you are unsure about paths, call list_dir with path '.' first.\n"
             "Format:\n"
             "<tool_calls>{\"calls\":[{\"id\":\"call_1\",\"name\":\"tool_name\",\"arguments\":{...}}]}</tool_calls>\n"
@@ -88,23 +94,36 @@ class ToolRunner:
         return results
 
     def _write_file(self, path: str, content: str, expected_sha256: Optional[str] = None) -> Dict[str, Any]:
+        self._validate_str("content", content)
+        expected_sha256 = self._validate_sha256(expected_sha256)
         before = self.fs.read_full_text(path)
         self._confirm_change(path, before, content, "write")
         return self.fs.write_text(path, content, expected_sha256=expected_sha256)
 
     def _create_file(self, path: str, content: str, overwrite: bool = False) -> Dict[str, Any]:
-        before = ""
+        target = self._validate_create_path(path)
+        self._validate_str("content", content)
+        self._validate_bool("overwrite", overwrite)
+        if target.exists() and not overwrite:
+            raise ValidationError("path already exists")
+        before = self.fs.read_full_text(path) if target.exists() else ""
         self._confirm_change(path, before, content, "create")
         return self.fs.create_text(path, content, overwrite=overwrite)
 
     def _delete_file(self, path: str) -> Dict[str, Any]:
+        target = self.fs.resolve_path(path)
+        if not target.exists() or not target.is_file():
+            raise ValidationError("path does not exist or is not a file")
+        if not self.fs.is_git_tracked(target):
+            raise ToolError("delete blocked: file is not tracked by git")
         before = self.fs.read_full_text(path)
         self._confirm_change(path, before, "", "delete")
         return self.fs.delete_file(path)
 
     def _replace_in_file(self, path: str, old: str, new: str, expected_replacements: int = 1) -> Dict[str, Any]:
-        if not old:
-            raise ValidationError("old must be a non-empty string")
+        self._validate_non_empty_str("old", old)
+        self._validate_str("new", new)
+        expected_replacements = self._validate_int("expected_replacements", expected_replacements, minimum=1)
         content = self.fs.read_full_text(path)
         count = content.count(old)
         if count != expected_replacements:
@@ -114,8 +133,9 @@ class ToolRunner:
         return self.fs.write_text(path, updated)
 
     def _insert_relative(self, path: str, anchor: str, content: str, expected_matches: int = 1, after: bool = True) -> Dict[str, Any]:
-        if not anchor:
-            raise ValidationError("anchor must be a non-empty string")
+        self._validate_non_empty_str("anchor", anchor)
+        self._validate_str("content", content)
+        expected_matches = self._validate_int("expected_matches", expected_matches, minimum=1)
         original = self.fs.read_full_text(path)
         count = original.count(anchor)
         if count != expected_matches:
@@ -142,3 +162,43 @@ class ToolRunner:
         prompt = f"Apply {action} to {path}?\n{diff}\n"
         if not self.confirm_callback(prompt):
             raise ToolError("change declined by user")
+
+    def _validate_str(self, name: str, value: object) -> None:
+        if not isinstance(value, str):
+            raise ValidationError(f"{name} must be a string")
+
+    def _validate_non_empty_str(self, name: str, value: object) -> None:
+        if not isinstance(value, str) or not value:
+            raise ValidationError(f"{name} must be a non-empty string")
+
+    def _validate_bool(self, name: str, value: object) -> None:
+        if not isinstance(value, bool):
+            raise ValidationError(f"{name} must be a bool")
+
+    def _validate_int(self, name: str, value: object, minimum: int = 0) -> int:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValidationError(f"{name} must be an int")
+        if value < minimum:
+            raise ValidationError(f"{name} must be >= {minimum}")
+        return value
+
+    def _validate_sha256(self, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            raise ValidationError("expected_sha256 must be a string")
+        normalized = value.lower()
+        if not re.fullmatch(r"[0-9a-f]{64}", normalized):
+            raise ValidationError("expected_sha256 must be a 64-character hex string")
+        return normalized
+
+    def _validate_create_path(self, path: str) -> Path:
+        self._validate_non_empty_str("path", path)
+        if path in {".", ""}:
+            raise ValidationError("path must be a file path, not a directory")
+        if path.endswith(("/", os.sep)):
+            raise ValidationError("path must be a file path, not a directory")
+        target = self.fs.resolve_path(path)
+        if target.exists() and target.is_dir():
+            raise ValidationError("path already exists and is a directory")
+        return target