zexus 1.7.1 → 1.7.2

package/src/zexus/strategy_recovery.py

@@ -54,6 +54,8 @@ class ErrorRecoveryEngine:
             return 'missing_parenthesis'
         elif "missing }" in error_msg or "brace" in error_msg:
             return 'missing_brace'
+        elif "finally" in error_msg:
+            return 'expected_catch'
         else:
             return 'syntax_error'
 
@@ -160,8 +162,8 @@ class ErrorRecoveryEngine:
 
         # Look for catch blocks in current block or parent blocks
         for block_id, block in blocks.items():
-            if block.get('subtype') == 'try_catch':
-                if block.get('catch_section'):
+            if block.get('subtype') in ('try_catch', 'try_catch_statement'):
+                if block.get('catch_section') or block.get('finally_section'):
                     return block
             # Check nested blocks
             for nested in block.get('nested_blocks', []):
@@ -195,7 +197,8 @@ class ErrorRecoveryEngine:
         return TryCatchStatement(
             try_block=BlockStatement(),
             error_variable=Identifier("error"),
-            catch_block=BlockStatement()
+            catch_block=BlockStatement(),
+            finally_block=None
         )
 
     def _create_synthetic_catch_block(self):

package/src/zexus/type_checker.py

@@ -0,0 +1,423 @@
+"""
+Static Type Checker for Zexus
+=============================
+
+Performs a single AST-walking pass **before** evaluation to detect type
+errors at authoring time.  The checker intentionally operates on
+*annotations only* — it will never execute user code.
+
+Usage::
+
+    from zexus.type_checker import StaticTypeChecker
+    checker = StaticTypeChecker()
+    diagnostics = checker.check(program_ast)
+    for d in diagnostics:
+        print(d)
+
+Each diagnostic is a ``TypeDiagnostic`` named-tuple with ``level``
+(``"error"`` or ``"warning"``), ``message``, and an optional ``node``
+reference.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+from .type_system import BaseType, TypeSpec, STANDARD_TYPES, parse_type_annotation
+from . import zexus_ast as ast
+
+
+# ---------------------------------------------------------------------------
+# Diagnostic container
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TypeDiagnostic:
+    level: str  # "error" | "warning"
+    message: str
+    node: Optional[ast.Node] = None
+
+    def __str__(self) -> str:
+        prefix = "TypeError" if self.level == "error" else "TypeWarning"
+        return f"[{prefix}] {self.message}"
+
+
+# ---------------------------------------------------------------------------
+# Scope (symbol table for one lexical scope)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class _Scope:
+    """Tracks declared names -> TypeSpec in a single lexical scope."""
+    parent: Optional["_Scope"] = None
+    symbols: Dict[str, TypeSpec] = field(default_factory=dict)
+    # Actions/functions: name -> (param_types, return_type)
+    callables: Dict[str, Tuple[List[Tuple[str, Optional[TypeSpec]]], Optional[TypeSpec]]] = field(
+        default_factory=dict
+    )
+
+    def define(self, name: str, ts: Optional[TypeSpec]):
+        self.symbols[name] = ts  # type: ignore[assignment]
+
+    def lookup(self, name: str) -> Optional[TypeSpec]:
+        if name in self.symbols:
+            return self.symbols[name]
+        if self.parent:
+            return self.parent.lookup(name)
+        return None
+
+    def define_callable(
+        self,
+        name: str,
+        params: List[Tuple[str, Optional[TypeSpec]]],
+        return_type: Optional[TypeSpec],
+    ):
+        self.callables[name] = (params, return_type)
+
+    def lookup_callable(
+        self, name: str
+    ) -> Optional[Tuple[List[Tuple[str, Optional[TypeSpec]]], Optional[TypeSpec]]]:
+        if name in self.callables:
+            return self.callables[name]
+        if self.parent:
+            return self.parent.lookup_callable(name)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Type inference helpers
+# ---------------------------------------------------------------------------
+
+_LITERAL_TYPE_MAP = {
+    ast.IntegerLiteral: BaseType.INT,
+    ast.FloatLiteral: BaseType.FLOAT,
+    ast.StringLiteral: BaseType.STRING,
+    ast.Boolean: BaseType.BOOL,
+}
+
+
+def _resolve_annotation(annotation) -> Optional[TypeSpec]:
+    """Convert a string or ``Identifier`` annotation to ``TypeSpec``,
+    returning *None* when the annotation is absent or un-parseable."""
+    if annotation is None:
+        return None
+    # Handle both raw strings and Identifier AST nodes
+    if isinstance(annotation, ast.Identifier):
+        annotation = annotation.value
+    if not isinstance(annotation, str):
+        annotation = str(annotation)
+    return parse_type_annotation(annotation)
+
+
+def _infer_expr_type(node: ast.Expression, scope: _Scope) -> Optional[TypeSpec]:
+    """Best-effort inference of the static type of *node*.
+
+    Returns ``None`` when the type cannot be determined statically.
+    """
+    node_cls = type(node)
+
+    # Literals
+    base = _LITERAL_TYPE_MAP.get(node_cls)
+    if base is not None:
+        return TypeSpec(base)
+
+    # Array/List literal
+    if isinstance(node, ast.ListLiteral):
+        if node.elements:
+            elem_type = _infer_expr_type(node.elements[0], scope)
+            return TypeSpec(BaseType.ARRAY, array_of=elem_type)
+        return TypeSpec(BaseType.ARRAY, array_of=TypeSpec(BaseType.ANY))
+
+    # Map literal
+    if isinstance(node, ast.MapLiteral):
+        return TypeSpec(BaseType.OBJECT)
+
+    # Identifier — look up in scope
+    if isinstance(node, ast.Identifier):
+        return scope.lookup(node.value)
+
+    # Infix — numeric ops yield numeric types
+    if isinstance(node, ast.InfixExpression):
+        if node.operator in ("+", "-", "*", "/", "%", "**"):
+            left = _infer_expr_type(node.left, scope)
+            right = _infer_expr_type(node.right, scope)
+            if left and right:
+                if left.base_type == BaseType.FLOAT or right.base_type == BaseType.FLOAT:
+                    return TypeSpec(BaseType.FLOAT)
+                if left.base_type == BaseType.INT and right.base_type == BaseType.INT:
+                    if node.operator == "/":
+                        return TypeSpec(BaseType.FLOAT)
+                    return TypeSpec(BaseType.INT)
+                # String concatenation
+                if node.operator == "+" and left.base_type == BaseType.STRING:
+                    return TypeSpec(BaseType.STRING)
+            return None
+        if node.operator in ("==", "!=", "<", ">", "<=", ">=", "&&", "||", "and", "or"):
+            return TypeSpec(BaseType.BOOL)
+
+    # Prefix — `!` => bool, `-` => numeric
+    if isinstance(node, ast.PrefixExpression):
+        if node.operator == "!":
+            return TypeSpec(BaseType.BOOL)
+        if node.operator == "-":
+            return _infer_expr_type(node.right, scope)
+
+    # Call expression — look up return type
+    if isinstance(node, ast.CallExpression):
+        fn_name = None
+        if isinstance(node.function, ast.Identifier):
+            fn_name = node.function.value
+        if fn_name:
+            sig = scope.lookup_callable(fn_name)
+            if sig:
+                _, ret = sig
+                return ret
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Compatibility check
+# ---------------------------------------------------------------------------
+
+def _is_compatible(declared: TypeSpec, actual: TypeSpec) -> bool:
+    """Check whether *actual* can be assigned to a slot of type *declared*."""
+    if declared.base_type == BaseType.ANY or actual.base_type == BaseType.ANY:
+        return True
+    # number promotion: int -> float
+    if declared.base_type == BaseType.FLOAT and actual.base_type == BaseType.INT:
+        return True
+    if declared.base_type != actual.base_type:
+        return False
+    # Array element types
+    if declared.array_of and actual.array_of:
+        return _is_compatible(declared.array_of, actual.array_of)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Main checker
+# ---------------------------------------------------------------------------
+
+class StaticTypeChecker:
+    """Walk an AST ``Program`` and collect type diagnostics."""
+
+    def __init__(self) -> None:
+        self.diagnostics: List[TypeDiagnostic] = []
+        self._scope: _Scope = _Scope()  # global scope
+
+    # -- public API ---------------------------------------------------------
+
+    def check(self, program: ast.Program) -> List[TypeDiagnostic]:
+        """Run the checker on *program* and return all diagnostics."""
+        self.diagnostics = []
+        self._scope = _Scope()
+        for stmt in program.statements:
+            self._check_statement(stmt)
+        return list(self.diagnostics)
+
+    # -- helpers ------------------------------------------------------------
+
+    def _error(self, msg: str, node: Optional[ast.Node] = None):
+        self.diagnostics.append(TypeDiagnostic("error", msg, node))
+
+    def _warning(self, msg: str, node: Optional[ast.Node] = None):
+        self.diagnostics.append(TypeDiagnostic("warning", msg, node))
+
+    def _push_scope(self) -> _Scope:
+        self._scope = _Scope(parent=self._scope)
+        return self._scope
+
+    def _pop_scope(self):
+        if self._scope.parent:
+            self._scope = self._scope.parent
+
+    # -- statement visitors -------------------------------------------------
+
+    def _check_statement(self, stmt: ast.Statement):
+        handler = getattr(self, f"_check_{type(stmt).__name__}", None)
+        if handler:
+            handler(stmt)
+
+    def _check_LetStatement(self, stmt: ast.LetStatement):
+        ann = _resolve_annotation(getattr(stmt, "type_annotation", None))
+        if stmt.value is not None:
+            self._check_expression(stmt.value)
+            actual = _infer_expr_type(stmt.value, self._scope)
+            if ann and actual and not _is_compatible(ann, actual):
+                self._error(
+                    f"Cannot assign {actual.base_type.value} to "
+                    f"'{stmt.name}' declared as {ann.base_type.value}",
+                    stmt,
+                )
+        name = stmt.name.value if isinstance(stmt.name, ast.Identifier) else None
+        if name:
+            self._scope.define(name, ann)
+
+    def _check_ConstStatement(self, stmt: ast.ConstStatement):
+        ann = _resolve_annotation(getattr(stmt, "type_annotation", None))
+        if stmt.value is not None:
+            self._check_expression(stmt.value)
+            actual = _infer_expr_type(stmt.value, self._scope)
+            if ann and actual and not _is_compatible(ann, actual):
+                self._error(
+                    f"Cannot assign {actual.base_type.value} to "
+                    f"const '{stmt.name}' declared as {ann.base_type.value}",
+                    stmt,
+                )
+        name = stmt.name.value if isinstance(stmt.name, ast.Identifier) else None
+        if name:
+            self._scope.define(name, ann)
+
+    def _check_ActionStatement(self, stmt: ast.ActionStatement):
+        name = stmt.name if isinstance(stmt.name, str) else getattr(stmt.name, "value", None)
+        param_types: List[Tuple[str, Optional[TypeSpec]]] = []
+        for p in stmt.parameters or []:
+            ann_str = getattr(p, "type_annotation", None)
+            ts = _resolve_annotation(ann_str)
+            param_types.append((p.value, ts))
+        ret_ts = _resolve_annotation(stmt.return_type)
+        if name:
+            self._scope.define_callable(name, param_types, ret_ts)
+            self._scope.define(name, TypeSpec(BaseType.ACTION))
+
+        # Check body in a nested scope
+        self._push_scope()
+        for pname, pts in param_types:
+            self._scope.define(pname, pts)
+        if stmt.body:
+            self._check_block(stmt.body, ret_ts)
+        self._pop_scope()
+
+    def _check_FunctionStatement(self, stmt: ast.FunctionStatement):
+        # Reuse action logic
+        name = stmt.name if isinstance(stmt.name, str) else getattr(stmt.name, "value", None)
+        param_types: List[Tuple[str, Optional[TypeSpec]]] = []
+        for p in stmt.parameters or []:
+            ann_str = getattr(p, "type_annotation", None)
+            ts = _resolve_annotation(ann_str)
+            param_types.append((p.value, ts))
+        ret_ts = _resolve_annotation(getattr(stmt, "return_type", None))
+        if name:
+            self._scope.define_callable(name, param_types, ret_ts)
+            self._scope.define(name, TypeSpec(BaseType.ACTION))
+
+        self._push_scope()
+        for pname, pts in param_types:
+            self._scope.define(pname, pts)
+        if stmt.body:
+            self._check_block(stmt.body, ret_ts)
+        self._pop_scope()
+
+    def _check_ReturnStatement(self, stmt: ast.ReturnStatement):
+        # Return type validation is handled during block check
+        pass
+
+    def _check_ExpressionStatement(self, stmt: ast.ExpressionStatement):
+        if stmt.expression:
+            self._check_expression(stmt.expression)
+
+    def _check_IfStatement(self, stmt):
+        if hasattr(stmt, "condition") and stmt.condition:
+            self._check_expression(stmt.condition)
+        if hasattr(stmt, "consequence") and stmt.consequence:
+            self._check_block(stmt.consequence)
+        if hasattr(stmt, "alternative") and stmt.alternative:
+            self._check_block(stmt.alternative)
+
+    def _check_WhileStatement(self, stmt):
+        if hasattr(stmt, "condition") and stmt.condition:
+            self._check_expression(stmt.condition)
+        if hasattr(stmt, "body") and stmt.body:
+            self._check_block(stmt.body)
+
+    def _check_ForStatement(self, stmt):
+        if hasattr(stmt, "body") and stmt.body:
+            self._check_block(stmt.body)
+
+    # -- block / body visitor -----------------------------------------------
+
+    def _check_block(self, block, expected_return: Optional[TypeSpec] = None):
+        stmts = getattr(block, "statements", None)
+        if not stmts:
+            return
+        for s in stmts:
+            self._check_statement(s)
+            # Check return type
+            if expected_return and isinstance(s, ast.ReturnStatement):
+                if s.return_value:
+                    actual = _infer_expr_type(s.return_value, self._scope)
+                    if actual and not _is_compatible(expected_return, actual):
+                        self._error(
+                            f"Return type {actual.base_type.value} is incompatible "
+                            f"with declared return type {expected_return.base_type.value}",
+                            s,
+                        )
+
+    # -- expression visitors ------------------------------------------------
+
+    def _check_expression(self, expr: ast.Expression):
+        if isinstance(expr, ast.CallExpression):
+            self._check_call(expr)
+        elif isinstance(expr, ast.InfixExpression):
+            if expr.left:
+                self._check_expression(expr.left)
+            if expr.right:
+                self._check_expression(expr.right)
+            self._check_infix_types(expr)
+        elif isinstance(expr, ast.PrefixExpression):
+            if expr.right:
+                self._check_expression(expr.right)
+
+    def _check_call(self, call: ast.CallExpression):
+        fn_name = None
+        if isinstance(call.function, ast.Identifier):
+            fn_name = call.function.value
+        if not fn_name:
+            return
+        sig = self._scope.lookup_callable(fn_name)
+        if sig is None:
+            return  # unknown function — skip
+        params, _ = sig
+        args = call.arguments or []
+
+        # Arity check
+        expected = len(params)
+        got = len(args)
+        if got != expected:
+            self._error(
+                f"'{fn_name}' expects {expected} argument(s) but got {got}",
+                call,
+            )
+
+        # Per-argument type check
+        for i, (pname, pts) in enumerate(params):
+            if i >= len(args):
+                break
+            if pts is None:
+                continue
+            actual = _infer_expr_type(args[i], self._scope)
+            if actual and not _is_compatible(pts, actual):
+                self._error(
+                    f"Argument '{pname}' of '{fn_name}' expects "
+                    f"{pts.base_type.value} but got {actual.base_type.value}",
+                    call,
+                )
+
+    def _check_infix_types(self, expr: ast.InfixExpression):
+        """Warn on obviously wrong infix operations."""
+        if expr.operator in ("+", "-", "*", "/", "%", "**"):
+            left = _infer_expr_type(expr.left, self._scope)
+            right = _infer_expr_type(expr.right, self._scope)
+            if left and right:
+                # String + Number is fine (concatenation). But Number - String isn't.
+                if expr.operator != "+" and (
+                    (left.base_type == BaseType.STRING and right.base_type in (BaseType.INT, BaseType.FLOAT))
+                    or (right.base_type == BaseType.STRING and left.base_type in (BaseType.INT, BaseType.FLOAT))
+                ):
+                    self._warning(
+                        f"Suspicious operation: {left.base_type.value} "
+                        f"{expr.operator} {right.base_type.value}",
+                        expr,
+                    )

package/src/zexus/virtual_filesystem.py

@@ -1,7 +1,7 @@
 """
 Virtual filesystem and memory layer for sandboxed execution.
 
-Provides isolated file access and memory quotas for plugins.
+Provides isolated file access, memory quotas, and a read cache for plugins.
 Each plugin operates in a restricted filesystem namespace.
 """
 
@@ -11,6 +11,8 @@ from pathlib import Path
 from enum import Enum
 import os
 import sys
+import threading
+import time
 
 
 class FileAccessMode(Enum):
@@ -166,12 +168,174 @@ class SandboxFileSystem:
         """Get filesystem access log."""
         return self.access_log.copy()
 
+    # ------------------------------------------------------------------
+    # Actual I/O operations (sandboxed)
+    # ------------------------------------------------------------------
+
+    def read_file(self, virtual_path: str) -> str:
+        """Read file contents through VFS access control.
+
+        Raises PermissionError or FileNotFoundError on failure.
+        """
+        result = self.resolve_path(virtual_path)
+        if result is None:
+            self.log_access("read", virtual_path, False, "path not mounted")
+            raise PermissionError(f"Path not accessible: {virtual_path}")
+        real_path, mode = result
+        if mode not in (FileAccessMode.READ, FileAccessMode.READ_WRITE):
+            self.log_access("read", virtual_path, False, "no read permission")
+            raise PermissionError(f"Read access denied: {virtual_path}")
+        self.log_access("read", virtual_path, True)
+        with open(real_path, "r") as f:
+            return f.read()
+
+    def write_file(self, virtual_path: str, content: str) -> None:
+        """Write file contents through VFS access control."""
+        result = self.resolve_path(virtual_path)
+        if result is None:
+            self.log_access("write", virtual_path, False, "path not mounted")
+            raise PermissionError(f"Path not accessible: {virtual_path}")
+        real_path, mode = result
+        if mode not in (FileAccessMode.WRITE, FileAccessMode.READ_WRITE):
+            self.log_access("write", virtual_path, False, "no write permission")
+            raise PermissionError(f"Write access denied: {virtual_path}")
+        self.log_access("write", virtual_path, True)
+        os.makedirs(os.path.dirname(real_path), exist_ok=True)
+        with open(real_path, "w") as f:
+            f.write(content)
+
+    def append_file(self, virtual_path: str, content: str) -> None:
+        """Append to a file through VFS access control."""
+        result = self.resolve_path(virtual_path)
+        if result is None:
+            self.log_access("append", virtual_path, False, "path not mounted")
+            raise PermissionError(f"Path not accessible: {virtual_path}")
+        real_path, mode = result
+        if mode not in (FileAccessMode.WRITE, FileAccessMode.READ_WRITE):
+            self.log_access("append", virtual_path, False, "no write permission")
+            raise PermissionError(f"Append access denied: {virtual_path}")
+        self.log_access("append", virtual_path, True)
+        with open(real_path, "a") as f:
+            f.write(content)
+
+    def file_exists(self, virtual_path: str) -> bool:
+        """Check if a virtual path references an existing file."""
+        result = self.resolve_path(virtual_path)
+        if result is None:
+            return False
+        return os.path.exists(result[0])
+
+    def list_dir(self, virtual_path: str) -> List[str]:
+        """List directory contents through VFS."""
+        result = self.resolve_path(virtual_path)
+        if result is None:
+            raise PermissionError(f"Path not accessible: {virtual_path}")
+        real_path, mode = result
+        if mode not in (FileAccessMode.READ, FileAccessMode.READ_WRITE):
+            raise PermissionError(f"Read access denied for directory: {virtual_path}")
+        return os.listdir(real_path)
+
+
+# ---------------------------------------------------------------------------
+# File content cache — avoids repeated disk reads for hot paths
+# ---------------------------------------------------------------------------
+
+class FileContentCache:
+    """Thread-safe LRU-ish read cache for file contents.
+
+    Speeds up repeated reads to the same path (e.g. ``use "utils.zx"``
+    imported by many modules).  Cached entries are invalidated when the
+    file's mtime changes.
+    """
+
+    def __init__(self, max_entries: int = 256, max_bytes: int = 32 * 1024 * 1024):
+        self._lock = threading.Lock()
+        self._max_entries = max_entries
+        self._max_bytes = max_bytes
+        self._current_bytes = 0
+        # path -> (content, mtime, size)
+        self._cache: Dict[str, Tuple[str, float, int]] = {}
+        self._hits = 0
+        self._misses = 0
+
+    def get(self, real_path: str) -> Optional[str]:
+        """Return cached content if still valid, else None."""
+        with self._lock:
+            entry = self._cache.get(real_path)
+            if entry is None:
+                self._misses += 1
+                return None
+            content, cached_mtime, size = entry
+            try:
+                current_mtime = os.path.getmtime(real_path)
+            except OSError:
+                # File gone — evict
+                self._evict(real_path)
+                self._misses += 1
+                return None
+            if current_mtime != cached_mtime:
+                self._evict(real_path)
+                self._misses += 1
+                return None
+            self._hits += 1
+            return content
+
+    def put(self, real_path: str, content: str) -> None:
+        """Store file content in cache."""
+        size = len(content.encode("utf-8", errors="replace"))
+        if size > self._max_bytes // 2:
+            return  # Don't cache files larger than half the budget
+        with self._lock:
+            # Evict old entry if present
+            self._evict(real_path)
+            # Evict LRU entries if over budget
+            while (len(self._cache) >= self._max_entries
+                   or self._current_bytes + size > self._max_bytes) and self._cache:
+                oldest_key = next(iter(self._cache))
+                self._evict(oldest_key)
+            try:
+                mtime = os.path.getmtime(real_path)
+            except OSError:
+                return
+            self._cache[real_path] = (content, mtime, size)
+            self._current_bytes += size
+
+    def invalidate(self, real_path: str) -> None:
+        """Remove a specific path from cache (e.g. after write)."""
+        with self._lock:
+            self._evict(real_path)
+
+    def clear(self) -> None:
+        """Flush the entire cache."""
+        with self._lock:
+            self._cache.clear()
+            self._current_bytes = 0
+
+    def stats(self) -> Dict[str, Any]:
+        """Return cache statistics."""
+        with self._lock:
+            total = self._hits + self._misses
+            return {
+                "entries": len(self._cache),
+                "bytes": self._current_bytes,
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate": self._hits / total if total else 0.0,
+            }
+
+    # internal
+    def _evict(self, key: str):
+        entry = self._cache.pop(key, None)
+        if entry:
+            self._current_bytes -= entry[2]
+
 
 class VirtualFileSystemManager:
     """
     Manages virtual filesystems for multiple sandboxes.
     
-    Coordinates sandbox creation, isolation, and resource cleanup.
+    Coordinates sandbox creation, isolation, resource cleanup, and
+    provides a global file content cache shared across sandboxes.
     """
     
     def __init__(self):
@@ -179,6 +343,7 @@ class VirtualFileSystemManager:
         self.sandboxes: Dict[str, SandboxFileSystem] = {}
         self.memory_quotas: Dict[str, MemoryQuota] = {}
         self.default_memory_quota = 1024 * 1024 * 100  # 100MB default
+        self.file_cache = FileContentCache()
     
     def create_sandbox(self, sandbox_id: str, memory_quota_mb: int = 100) -> SandboxFileSystem:
         """
@@ -245,6 +410,28 @@ class VirtualFileSystemManager:
         """List all active sandboxes."""
         return list(self.sandboxes.keys())
 
+    def get_sandbox_filesystem(self, context: str = "default") -> Optional[SandboxFileSystem]:
+        """Get sandbox filesystem by context name (alias for get_sandbox)."""
+        return self.sandboxes.get(context)
+
+    # ------------------------------------------------------------------
+    # Cached file I/O helpers (used by builtins when no sandbox is active)
+    # ------------------------------------------------------------------
+
+    def cached_read(self, real_path: str) -> str:
+        """Read a file, using the content cache when possible."""
+        content = self.file_cache.get(real_path)
+        if content is not None:
+            return content
+        with open(real_path, "r") as f:
+            content = f.read()
+        self.file_cache.put(real_path, content)
+        return content
+
+    def invalidate_cache(self, real_path: str):
+        """Invalidate cache entry after a write."""
+        self.file_cache.invalidate(real_path)
+
 
 class StandardMounts:
     """Standard filesystem mount configurations."""