feat: RFC 0008 environment wrap actions with EXPR runtime parity Implement the WRAP_ACTIONS extension (RFC 0008) in the v0 session, with EXPR (RFC 0007) runtime parity with openjd-rs: - Wrap-hook dispatch: an environment's onWrapEnvEnter / onWrapTaskRun / onWrapEnvExit runs in place of an inner environment's onEnter/onExit or a step's onRun, with WrappedAction.Command/Args/Environment/ Timeout/Cancelation.* and WrappedEnv.Name/WrappedStep.Name injected. At most one wrap-defining environment may be active (enforced at enter time). - Two strictly separated scopes (openjd-rs #277 parity): the wrapped action's values resolve against the INNER entity's own scope (its script-level let bindings and embedded files, materialized in runner order: paths, lets, contents); the hook script resolves against the wrap environment's own scope (its lets, evaluated by the runner) plus the WrappedAction.* overlay. Same-named lets on the two sides each resolve to their own value. - WrappedAction.Environment carries every session-defined variable: openjd_env definitions and entered environments' declarative variables: maps; host-inherited variables are excluded. - EXPR runtime: runner-evaluated script-level let bindings ordered around embedded-file materialization (paths before lets, contents after), typed symbol tables, enter_environment(extra_let_bindings=...) so a step's environments see the step-level lets. - Cancelation: WrappedAction.Cancelation.Mode/NotifyPeriodInSeconds resolved through the enforcement path, with Template Schemas 5.3.2 defaults (120s task onRun / 30s otherwise).

Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>

Author: leongdl

.gitignore

@@ -23,3 +23,6 @@ __pycache__/
 /dist
 _version.py
 *.log
+
+# Local one-off helper scripts (not part of the project)
+/tmp/

src/openjd/sessions/_embedded_files.py

@@ -209,6 +209,23 @@ def __init__(
         self._user = user
 
     def materialize(self, files: EmbeddedFilesListType, symtab: SymbolTable) -> None:
+        records = self.allocate_file_paths(files, symtab)
+        self.write_file_contents(records, symtab)
+
+    def allocate_file_paths(
+        self, files: EmbeddedFilesListType, symtab: SymbolTable
+    ) -> list[_FileRecord]:
+        """Allocate the on-disk paths for the embedded files and define their
+        ``Env.File.*``/``Task.File.*`` symbols in ``symtab``, without writing
+        the file contents.
+
+        Splitting allocation from :meth:`write_file_contents` lets the runner
+        evaluate EXPR ``let`` bindings between the two phases (RFC 0007): a
+        file's *path* never depends on ``let`` values (``filename`` is a plain
+        string), so the ``Env.File.*``/``Task.File.*`` symbols are available
+        to the bindings, while a file's ``data`` is written afterwards so it
+        can reference let-bound values. Mirrors the openjd-rs runners.
+        """
         if self._scope == EmbeddedFilesScope.ENV:
             self._logger.info("Writing embedded files for Environment to disk.")
         else:
@@ -222,17 +239,28 @@ def materialize(self, files: EmbeddedFilesListType, symtab: SymbolTable) -> None
                 symbol, filename = self._get_symtab_entry(file)
                 records.append(_FileRecord(symbol=symbol, filename=filename, file=file))
 
-            # Add symbols to the symbol table
+            # Add symbols to the symbol table. For EXPR evaluation the
+            # Env.File.*/Task.File.* symbols are host-format path values
+            # (property access like `.parent` works), matching openjd-rs;
+            # the legacy (non-EXPR) interpolation path ignores the type and
+            # keeps the string form.
             for record in records:
                 symtab[record.symbol] = str(record.filename)
+                symtab.expr_types[record.symbol] = "PATH"
                 self._logger.info(
                     f"Mapping: {record.symbol} -> {record.filename}",
                     extra=LogExtraInfo(
                         openjd_log_content=LogContent.FILE_PATH | LogContent.PARAMETER_INFO
                     ),
                 )
+            return records
+        except (OSError, ValueError) as err:
+            raise RuntimeError(f"Could not write embedded file: {err}")
 
-            # Write the files to disk.
+    def write_file_contents(self, records: list["_FileRecord"], symtab: SymbolTable) -> None:
+        """Resolve each allocated file's ``data`` against ``symtab`` and write
+        it to disk. See :meth:`allocate_file_paths`."""
+        try:
             for record in records:
                 # Raises: OSError
                 self._materialize_file(record.filename, record.file, symtab)

src/openjd/sessions/_path_mapping.py

@@ -4,27 +4,43 @@
 from enum import Enum
 from os import name as os_name
 from pathlib import PurePath, PurePosixPath, PureWindowsPath
+from typing import Optional, Union
 
 
 class PathFormat(str, Enum):
     POSIX = "POSIX"
     WINDOWS = "WINDOWS"
+    # RFC 0006 §2.3.2 (EXPR extension): URI-form source paths
+    # (e.g. "s3://bucket/prefix") that map to local filesystem paths.
+    URI = "URI"
 
 
 @dataclass(frozen=True)
 class PathMappingRule:
     source_path_format: PathFormat
-    source_path: PurePath
+    # URI-format rules keep the source as the raw string: URIs are not
+    # filesystem paths, and PurePath normalization would corrupt the
+    # "scheme://" separator.
+    source_path: Union[PurePath, str]
     destination_path: PurePath
 
     def __init__(
-        self, *, source_path_format: PathFormat, source_path: PurePath, destination_path: PurePath
+        self,
+        *,
+        source_path_format: PathFormat,
+        source_path: Union[PurePath, str],
+        destination_path: PurePath,
     ):
         if source_path_format == PathFormat.POSIX:
             if not isinstance(source_path, PurePosixPath):
                 raise ValueError(
                     "Path mapping rule source_path_format does not match source_path type"
                 )
+        elif source_path_format == PathFormat.URI:
+            if not isinstance(source_path, str):
+                raise ValueError(
+                    "Path mapping rule source_path must be a string for the URI source_path_format"
+                )
         else:
             if not isinstance(source_path, PureWindowsPath):
                 raise ValueError(
@@ -49,9 +65,12 @@ def from_dict(rule: dict[str, str]) -> "PathMappingRule":
                 raise ValueError(f"Path mapping rule requires the following fields: {field_names}")
 
         source_path_format = PathFormat(rule["source_path_format"].upper())
-        source_path: PurePath
+        source_path: Union[PurePath, str]
         if source_path_format == PathFormat.POSIX:
             source_path = PurePosixPath(rule["source_path"])
+        elif source_path_format == PathFormat.URI:
+            # Keep URIs verbatim; PurePath would collapse "scheme://".
+            source_path = rule["source_path"]
         else:
             source_path = PureWindowsPath(rule["source_path"])
         destination_path = PurePath(rule["destination_path"])
@@ -76,25 +95,90 @@ def to_dict(self) -> dict[str, str]:
             "destination_path": str(self.destination_path),
         }
 
+    @staticmethod
+    def _uri_path_start(uri: str) -> Optional[int]:
+        """Byte offset where the path component begins in a URI (after
+        ``scheme://authority``), or None when there is no ``://`` separator.
+        Mirrors openjd-rs's ``uri_path_start``."""
+        scheme_sep = uri.find("://")
+        if scheme_sep == -1:
+            return None
+        authority_start = scheme_sep + 3
+        slash = uri.find("/", authority_start)
+        return len(uri) if slash == -1 else slash
+
+    def _apply_uri(self, path: str) -> tuple[bool, str]:
+        """Apply a URI-format rule, mirroring openjd-rs's ``apply_uri``.
+
+        Per RFC 3986 the scheme and authority match case-insensitively while
+        the path portion matches case-sensitively, on whole path components.
+        The result is a local path in the host's format.
+        """
+        sep = "/" if os_name == "posix" else "\\"
+        source = str(self.source_path)
+        src_path_start = self._uri_path_start(source)
+        src_path_start = 0 if src_path_start is None else src_path_start
+        inp_path_start = self._uri_path_start(path)
+        inp_path_start = 0 if inp_path_start is None else inp_path_start
+
+        # Scheme+authority must match case-insensitively.
+        if path[:inp_path_start].lower() != source[:src_path_start].lower():
+            return False, path
+        # Path portion must match case-sensitively, on a component boundary.
+        src_path = source[src_path_start:]
+        inp_path = path[inp_path_start:]
+        if not inp_path.startswith(src_path):
+            return False, path
+        remainder = inp_path[len(src_path) :]
+        if remainder and not remainder.startswith("/"):
+            return False, path
+
+        child_parts = remainder[1:].split("/") if remainder else []
+        result = str(self.destination_path)
+        for part in child_parts:
+            result += sep + part
+        if path.endswith("/") and not result.endswith(sep):
+            result += sep
+        return True, result
+
+    def source_path_component_count(self) -> int:
+        """Number of components in the source path, used to order rules from
+        most to least specific. For URI sources the ``scheme://authority``
+        counts as one component plus one per path segment."""
+        if isinstance(self.source_path, PurePath):
+            return len(self.source_path.parts)
+        source = str(self.source_path)
+        path_start = self._uri_path_start(source)
+        if path_start is None:
+            return 1
+        path_portion = source[path_start:].strip("/")
+        return 1 + (len(path_portion.split("/")) if path_portion else 0)
+
     def apply(self, *, path: str) -> tuple[bool, str]:
         """Applies the path mapping rule on the given path, if it matches the rule.
         Does not collapse ".." since symbolic paths could be used.
 
         Returns: tuple[bool, str] - indicating if the path matched the rule and the resulting
         mapped path. If it doesn't match, then it returns the original path unmodified.
         """
+        if self.source_path_format == PathFormat.URI:
+            return self._apply_uri(path)
+        source_path = self.source_path
+        if not isinstance(source_path, PurePath):
+            # The constructor guarantees non-URI rules carry PurePath sources.
+            raise TypeError(
+                "Path mapping rule source_path must be a PurePath for filesystem source formats"
+            )
         pure_path: PurePath
         if self.source_path_format == PathFormat.POSIX:
             pure_path = PurePosixPath(path)
         else:
             pure_path = PureWindowsPath(path)
 
-        if not pure_path.is_relative_to(self.source_path):
+        if not pure_path.is_relative_to(source_path):
             return False, path
 
-        remapped_parts = (
-            self.destination_path.parts + pure_path.parts[len(self.source_path.parts) :]
-        )
+        remapped_parts = self.destination_path.parts + pure_path.parts[len(source_path.parts) :]
         if os_name == "posix":
             result = str(PurePosixPath(*remapped_parts))
             if self._has_trailing_slash(self.source_path_format, path):