fix(assembly): regression in link-time symbol resolution involving quoted path components (#2627)

* test: add regression test for linking items with quoted path components

This test fails due to some subtle issues around how symbols and paths
are handled during parsing, semantic analysis, and linking/assembly.

* fix(assembly): unquote quoted path components when converting to str

This ensures that converting a path component to an identifier/str, then
pushing that identifier/str as a path component produces an identical
path.

While we want to preserve quotes in the underlying buffer of
Path/PathBuf, we don't want to surface quotes in strings produced by the
Path/PathBuf APIs. This is consistent with how Ident internally
represents symbols (i.e. unquoted).

Instead, we rely on the builder/constructor methods of `PathBuf` to
restore quotes as-needed.

Note that it is possible to construct a path involving quoted components
that don't actually need to be quoted. In a future commit,
canonicalization will be added so that you can always obtain a canonical
form from a possible non-canonical path.

* fix(assembly): ensure PathComponent::requires_quoting considers whether
a string is a valid identifier, not just whether it contains `::`

* fix(assembly): distinguish path join semantics for paths vs components

Previously, `Path::join` required the item to be joined to implement
`AsRef<Path>`, and implementations for this exist for both `str` and
`Path`/`PathBuf` - thus, it always treated the item to be joined as a
full path.

The problem is that we are frequently obtaining a path component as a
string, and then constructing new paths with `Path::join`. When these
strings are produced, they are produced unquoted - consequently, if
those paths happened to contain `::` delimiters, `Path::join` would
produce a path 

Fundamentally, the issue is that the semantics of `Path::join` differ
depending on whether you are joining a `Path`-like item, or a
`PathComponent`-like item. We are always joining strings to a path as a
single component, never as a multi-component path; while we always join
paths to a path as multi-component paths.

This commit reworks `Path::join` to distinguish between the two use
cases. It provides a way to be explicit about what behavior you want
from `join`, while still providing the ergonomics from before. There is
still a subtle edge case where mistakes could be made, if someone is
attempting to join a multi-component path in string form (it will now be
treated as a single quoted component) - but we have no such uses in our
code base, and this is now documented clearly to warn those who might do
such a thing.

* fix(assembly): simplify path handling in grammar

* Properly handle quoted path components
* Remove unnecessary grammar rules

* fix(build): broken Makefile targets

* test(assembly): add test for intra-kernel library linking

* fix(assembly): implement path canonicalization and fix issues uncovered

This commit introduces two main features:

* Automatic canonicalization of paths when constructed via PathBuf
* Explicit canonicalization of Path via `Path::canonicalize`
* Tests were added for joining and canonicalization

It also addresses the following issues:

* We no longer treat $kernel/$exec specially during component parsing
  and in certain Path methods like `is_absolute`, instead, these paths
  are canonicalized to absolute and then treated like any other path.
* Some of the TryFrom/From conversions were not using the semantically
  correct method when constructing a PathBuf
* Ident::requires_quoting was unused as a method, but has value as a
  static function, and has been converted to one. It was also updated to
  properly consider whether an identifier containing $ requires escaping
  based on whether it is recognized as a reserved symbol, e.g. $kernel
* Deserialization of paths was requiring that the input be a borrowed
  str, due to reusing the deserializer for Path, this is unnecessarily
  limiting, and caused deserialization errors when the input string did
  not have a lifetime sufficient to allow the input to be borrowed.
  Instead, we now deserialize via PathBuf, and PathBufs deserialization
  code was improved to allow deserializing from both borrowed and owned
  strings, and to provide better error feedback

Author: bitwalker

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.20.5 (TBD)
+
+- Fixed issue with deserialization of Paths due to lifetime restrictions [#2627](https://github.com/0xMiden/miden-vm/pull/2627)
+- Implemented path canonicalization and modified Path/PathBuf APIs to canonicalize paths during construction. This also addressed some issues uncovered during testing where some APIs were not canonicalizing paths, or path-related functions were inconsistent in their behavior due to special-casing that was previously needed [#2627](https://github.com/0xMiden/miden-vm/pull/2627)
+
+
 ## 0.20.4 (2026-01-30)
 
 - Fixed issue with handling of quoted components in `PathBuf` [#2618](https://github.com/0xMiden/miden-vm/pull/2618)

Makefile

@@ -14,7 +14,7 @@ help:
 	@printf "  make test-assembly               # Test assembly crate\n"
 	@printf "  make test-assembly-syntax        # Test assembly-syntax crate\n"
 	@printf "  make test-core                   # Test core crate\n"
-	@printf "  make test-miden-vm               # Test miden-vm crate\n"
+	@printf "  make test-vm                     # Test miden-vm crate\n"
 	@printf "  make test-processor              # Test processor crate\n"
 	@printf "  make test-prover                 # Test prover crate\n"
 	@printf "  make test-core-lib               # Test core-lib crate\n"
@@ -48,10 +48,11 @@ FEATURES_air             := testing
 FEATURES_assembly        := testing
 FEATURES_assembly-syntax := testing,serde
 FEATURES_core            :=
-FEATURES_miden-vm        := concurrent,executable,metal,internal
+FEATURES_vm              := concurrent,executable,metal,internal
 FEATURES_processor       := concurrent,testing,bus-debugger
 FEATURES_prover          := concurrent,metal
-FEATURES_core-lib        :=FEATURES_verifier        :=
+FEATURES_core-lib        :=
+FEATURES_verifier        :=
 
 # -- linting --------------------------------------------------------------------------------------
 

crates/assembly-syntax/src/ast/ident.rs

@@ -135,8 +135,13 @@ impl Ident {
     }
 
     /// Returns true if this identifier must be quoted in Miden Assembly syntax
-    pub fn requires_quoting(&self) -> bool {
-        !self.name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '$')
+    pub fn requires_quoting(ident: impl AsRef<str>) -> bool {
+        match ident.as_ref() {
+            crate::Path::KERNEL_PATH
+            | crate::Path::EXEC_PATH
+            | crate::ast::ProcedureName::MAIN_PROC_NAME => false,
+            ident => !ident.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'),
+        }
     }
 
     /// Applies the default [Ident] validation rules to `source`.

crates/assembly-syntax/src/ast/path/components.rs

@@ -22,31 +22,33 @@ pub enum PathComponent<'a> {
 
 impl<'a> PathComponent<'a> {
     /// Get this component as a [prim@str]
-    #[inline(always)]
+    ///
+    /// NOTE: If the component is quoted, the resulting string does _not_ contain quotes. Depending
+    /// on how the resulting string is used, you may need to ensure quotes are added manually. In
+    /// general, the `Path`/`PathBuf` APIs handle this for you.
     pub fn as_str(&self) -> &'a str {
         match self {
             Self::Root => "::",
+            Self::Normal(id) if id.starts_with('"') && id.ends_with('"') => &id[1..(id.len() - 1)],
             Self::Normal(id) => id,
         }
     }
 
     /// Get this component as an [Ident], if it represents an identifier
     #[inline]
     pub fn to_ident(&self) -> Option<Ident> {
-        match self {
-            Self::Root => None,
-            Self::Normal(id) => Some(Ident::from_raw_parts(Span::unknown(Arc::from(
-                id.to_string().into_boxed_str(),
-            )))),
+        if matches!(self, Self::Root) {
+            None
+        } else {
+            Some(Ident::from_raw_parts(Span::unknown(Arc::from(
+                self.as_str().to_string().into_boxed_str(),
+            ))))
         }
     }
 
     /// Get the size in [prim@char]s of this component when printed
     pub fn char_len(&self) -> usize {
-        match self {
-            Self::Root => 2,
-            Self::Normal(id) => id.chars().count(),
-        }
+        self.as_str().chars().count()
     }
 
     /// Returns true if this path component is a quoted string
@@ -56,7 +58,16 @@ impl<'a> PathComponent<'a> {
 
     /// Returns true if this path component requires quoting when displayed/stored as a string
     pub fn requires_quoting(&self) -> bool {
-        matches!(self, Self::Normal(component) if component.contains("::"))
+        match self {
+            Self::Root => false,
+            Self::Normal(Path::KERNEL_PATH | Path::EXEC_PATH) => false,
+            Self::Normal(component)
+                if component.contains("::") || Ident::requires_quoting(component) =>
+            {
+                true
+            },
+            Self::Normal(_) => false,
+        }
     }
 }
 
@@ -132,8 +143,8 @@ impl<'a> Iterator for Iter<'a> {
 
     fn next(&mut self) -> Option<Self::Item> {
         match self.components.next() {
-            Some(Ok(PathComponent::Normal(component)))
-                if component.len() > Path::MAX_COMPONENT_LENGTH =>
+            Some(Ok(component @ PathComponent::Normal(_)))
+                if component.as_str().chars().count() > Path::MAX_COMPONENT_LENGTH =>
             {
                 Some(Err(PathError::InvalidComponent(crate::ast::IdentError::InvalidLength {
                     max: Path::MAX_COMPONENT_LENGTH,
@@ -147,8 +158,8 @@ impl<'a> Iterator for Iter<'a> {
 impl<'a> DoubleEndedIterator for Iter<'a> {
     fn next_back(&mut self) -> Option<Self::Item> {
         match self.components.next_back() {
-            Some(Ok(PathComponent::Normal(component)))
-                if component.len() > Path::MAX_COMPONENT_LENGTH =>
+            Some(Ok(component @ PathComponent::Normal(_)))
+                if component.as_str().chars().count() > Path::MAX_COMPONENT_LENGTH =>
             {
                 Some(Err(PathError::InvalidComponent(crate::ast::IdentError::InvalidLength {
                     max: Path::MAX_COMPONENT_LENGTH,
@@ -215,12 +226,6 @@ impl<'a> Iterator for Components<'a> {
                         self.front_pos += 2;
                         return Some(Ok(PathComponent::Root));
                     },
-                    None if self.path.starts_with(Path::KERNEL_PATH)
-                        || self.path.starts_with(Path::EXEC_PATH) =>
-                    {
-                        self.front = State::Body;
-                        return Some(Ok(PathComponent::Root));
-                    },
                     None => {
                         self.front = State::Body;
                     },
@@ -342,12 +347,7 @@ impl<'a> DoubleEndedIterator for Components<'a> {
                             return Some(Ok(PathComponent::Root));
                         },
                         other => {
-                            assert!(
-                                other.starts_with(Path::KERNEL_PATH)
-                                    || other.starts_with(Path::EXEC_PATH),
-                                "expected path in start state to be a valid path prefix, got '{other}'"
-                            );
-                            return Some(Ok(PathComponent::Root));
+                            return Some(Ok(PathComponent::Normal(other)));
                         },
                     }
                 },
@@ -385,13 +385,7 @@ impl<'a> DoubleEndedIterator for Components<'a> {
                         None => {
                             self.back = State::Start;
                             let component = self.path;
-                            if component.starts_with(Path::KERNEL_PATH)
-                                || component.starts_with(Path::EXEC_PATH)
-                            {
-                                self.path = "::";
-                            } else {
-                                self.path = "";
-                            }
+                            self.path = "";
                             self.back_pos = 0;
                             if let Err(err) =
                                 Ident::validate(component).map_err(PathError::InvalidComponent)
@@ -557,6 +551,10 @@ mod tests {
     #[test]
     fn special_path() {
         let mut components = Iter::new("$kernel");
+        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("$kernel"))));
+        assert_matches!(components.next(), None);
+
+        let mut components = Iter::new("::$kernel");
         assert_matches!(components.next(), Some(Ok(PathComponent::Root)));
         assert_matches!(components.next(), Some(Ok(PathComponent::Normal("$kernel"))));
         assert_matches!(components.next(), None);
@@ -566,13 +564,22 @@ mod tests {
     fn special_path_back() {
         let mut components = Iter::new("$kernel");
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("$kernel"))));
+        assert_matches!(components.next_back(), None);
+
+        let mut components = Iter::new("::$kernel");
+        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("$kernel"))));
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Root)));
         assert_matches!(components.next_back(), None);
     }
 
     #[test]
     fn special_nested_path() {
         let mut components = Iter::new("$kernel::bar");
+        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("$kernel"))));
+        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("bar"))));
+        assert_matches!(components.next(), None);
+
+        let mut components = Iter::new("::$kernel::bar");
         assert_matches!(components.next(), Some(Ok(PathComponent::Root)));
         assert_matches!(components.next(), Some(Ok(PathComponent::Normal("$kernel"))));
         assert_matches!(components.next(), Some(Ok(PathComponent::Normal("bar"))));
@@ -584,6 +591,11 @@ mod tests {
         let mut components = Iter::new("$kernel::bar");
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("bar"))));
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("$kernel"))));
+        assert_matches!(components.next_back(), None);
+
+        let mut components = Iter::new("::$kernel::bar");
+        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("bar"))));
+        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("$kernel"))));
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Root)));
         assert_matches!(components.next_back(), None);
     }