Deprecate all mutable methods on RenameMap (#2444)

* Add renamemap.MutableRenameMap which includes these methods without
  deprecation
* Deprecate Stringly typed RenameMap APIs which were accidentally
  undeprecated a while ago

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

13 files changed, 293 insertions, 96 deletions

diff --git a/src/main/scala/firrtl/RenameMap.scala b/src/main/scala/firrtl/RenameMap.scala
index d39d8106..1f05fa5a 100644
--- a/src/main/scala/firrtl/RenameMap.scala
+++ b/src/main/scala/firrtl/RenameMap.scala
@@ -7,21 +7,15 @@ import firrtl.RenameMap.IllegalRenameException
 import firrtl.analyses.InstanceKeyGraph
 import firrtl.annotations.TargetToken.{Field, Index, Instance, OfModule}
 import TargetUtils.{instKeyPathToTarget, unfoldInstanceTargets}
+import firrtl.renamemap._
 
 import scala.collection.mutable
+import scala.annotation.nowarn
 
 object RenameMap {
-  def apply(map: collection.Map[Named, Seq[Named]]): RenameMap = {
-    val rm = new RenameMap
-    rm.addMap(map)
-    rm
-  }
+  def apply(map: collection.Map[Named, Seq[Named]]): RenameMap = MutableRenameMap.fromNamed(map)
 
-  def create(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): RenameMap = {
-    val rm = new RenameMap
-    rm.recordAll(map)
-    rm
-  }
+  def create(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): RenameMap = MutableRenameMap(map)
 
   /** RenameMap factory for simple renaming of instances
     *
@@ -72,16 +66,11 @@ object RenameMap {
         underlying(fromx) = List(tox)
       }
     }
-    new RenameMap(underlying)
+    new MutableRenameMap(underlying)
   }
 
   /** Initialize a new RenameMap */
-  def apply(): RenameMap = new RenameMap
-
-  // This is a private internal API for transforms where the .distinct operation is very expensive
-  // (eg. LowerTypes). The onus is on the user of this API to be very careful and not inject
-  // duplicates. This is a bad, hacky API that no one should use
-  private[firrtl] def noDistinct(): RenameMap = new RenameMap(doDistinct = false)
+  def apply(): RenameMap = new MutableRenameMap
 
   abstract class RenameTargetException(reason: String) extends Exception(reason)
   case class IllegalRenameException(reason: String) extends RenameTargetException(reason)
@@ -96,14 +85,22 @@ object RenameMap {
   * @define noteDistinct @note Rename to/tos will be made distinct
   */
 // TODO This should probably be refactored into immutable and mutable versions
-final class RenameMap private (
-  val underlying: mutable.HashMap[CompleteTarget, Seq[CompleteTarget]] =
-    mutable.HashMap[CompleteTarget, Seq[CompleteTarget]](),
-  val chained: Option[RenameMap] = None,
+sealed trait RenameMap {
+
+  protected def _underlying: mutable.HashMap[CompleteTarget, Seq[CompleteTarget]]
+
+  protected def _chained: Option[RenameMap]
+
   // This is a private internal API for transforms where the .distinct operation is very expensive
   // (eg. LowerTypes). The onus is on the user of this API to be very careful and not inject
   // duplicates. This is a bad, hacky API that no one should use
-  doDistinct: Boolean = true) {
+  protected def doDistinct: Boolean
+
+  @deprecated("This should never have been public", "FIRRTL 1.5")
+  def underlying: mutable.HashMap[CompleteTarget, Seq[CompleteTarget]] = _underlying
+
+  @deprecated("This should never have been public", "FIRRTL 1.5")
+  def chained: Option[RenameMap] = _chained
 
   /** Chain a [[RenameMap]] with this [[RenameMap]]
     * @param next the map to chain with this map
@@ -111,10 +108,10 @@ final class RenameMap private (
     * $noteDistinct
     */
   def andThen(next: RenameMap): RenameMap = {
-    if (next.chained.isEmpty) {
-      new RenameMap(next.underlying, chained = Some(this))
+    if (next._chained.isEmpty) {
+      new MutableRenameMap(next._underlying, Some(this))
     } else {
-      new RenameMap(next.underlying, chained = next.chained.map(this.andThen(_)))
+      new MutableRenameMap(next._underlying, next._chained.map(this.andThen(_)))
     }
   }
 
@@ -125,6 +122,7 @@ final class RenameMap private (
     * $noteSelfRename
     * $noteDistinct
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def record(from: CircuitTarget, to: CircuitTarget): Unit = completeRename(from, Seq(to))
 
   /** Record that the from [[firrtl.annotations.CircuitTarget CircuitTarget]] is renamed to another sequence of
@@ -134,6 +132,7 @@ final class RenameMap private (
     * $noteSelfRename
     * $noteDistinct
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def record(from: CircuitTarget, tos: Seq[CircuitTarget]): Unit = completeRename(from, tos)
 
   /** Record that the from [[firrtl.annotations.IsMember Member]] is renamed to another [[firrtl.annotations.IsMember
@@ -143,6 +142,7 @@ final class RenameMap private (
     * $noteSelfRename
     * $noteDistinct
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def record(from: IsMember, to: IsMember): Unit = completeRename(from, Seq(to))
 
   /** Record that the from [[firrtl.annotations.IsMember IsMember]] is renamed to another sequence of
@@ -152,6 +152,7 @@ final class RenameMap private (
     * $noteSelfRename
     * $noteDistinct
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def record(from: IsMember, tos: Seq[IsMember]): Unit = completeRename(from, tos)
 
   /** Records that the keys in map are also renamed to their corresponding value seqs. Only
@@ -162,7 +163,10 @@ final class RenameMap private (
     * $noteSelfRename
     * $noteDistinct
     */
-  def recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit =
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
+  def recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit = _recordAll(map)
+
+  protected def _recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit =
     map.foreach {
       case (from: IsComponent, tos: Seq[_]) => completeRename(from, tos)
       case (from: IsModule, tos: Seq[_]) => completeRename(from, tos)
@@ -173,7 +177,8 @@ final class RenameMap private (
   /** Records that a [[firrtl.annotations.CompleteTarget CompleteTarget]] is deleted
     * @param name
     */
-  def delete(name: CompleteTarget): Unit = underlying(name) = Seq.empty
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
+  def delete(name: CompleteTarget): Unit = _underlying(name) = Seq.empty
 
   /** Renames a [[firrtl.annotations.CompleteTarget CompleteTarget]]
     * @param t target to rename
@@ -204,33 +209,38 @@ final class RenameMap private (
     * @return
     */
   def ++(renameMap: RenameMap): RenameMap = {
-    val newChained = if (chained.nonEmpty && renameMap.chained.nonEmpty) {
-      Some(chained.get ++ renameMap.chained.get)
+    val newChained = if (_chained.nonEmpty && renameMap._chained.nonEmpty) {
+      Some(_chained.get ++ renameMap._chained.get)
     } else {
-      chained.map(_.copy())
+      _chained.map(_._copy())
     }
-    new RenameMap(underlying = underlying ++ renameMap.getUnderlying, chained = newChained)
+    new MutableRenameMap(_underlying ++ renameMap._underlying, newChained)
   }
 
   /** Creates a deep copy of this [[RenameMap]]
     */
-  def copy(chained: Option[RenameMap] = chained): RenameMap = {
-    val ret = new RenameMap(chained = chained.map(_.copy()))
-    ret.recordAll(underlying)
+  @deprecated("RenameMap is becoming more function-like, this shouldn't be necessary", "FIRRTL 1.5")
+  def copy(chained: Option[RenameMap] = _chained): RenameMap = _copy(chained)
+
+  private def _copy(chained: Option[RenameMap] = _chained): RenameMap = {
+    val ret = new MutableRenameMap(_chained = _chained.map(_._copy()))
+    ret.recordAll(_underlying)
     ret
   }
 
   /** Returns the underlying map of rename information
     * @return
     */
-  def getUnderlying: collection.Map[CompleteTarget, Seq[CompleteTarget]] = underlying
+  @deprecated("This should never have been public", "FIRRTL 1.5")
+  def getUnderlying: collection.Map[CompleteTarget, Seq[CompleteTarget]] = _underlying
 
   /** @return Whether this [[RenameMap]] has collected any changes */
-  def hasChanges: Boolean = underlying.nonEmpty
+  def hasChanges: Boolean = _underlying.nonEmpty
 
+  @deprecated("RenameMap is becoming more function-like and is not invertible", "FIRRTL 1.5")
   def getReverseRenameMap: RenameMap = {
     val reverseMap = mutable.HashMap[CompleteTarget, Seq[CompleteTarget]]()
-    underlying.keysIterator.foreach { key =>
+    _underlying.keysIterator.foreach { key =>
       apply(key).foreach { v =>
         reverseMap(v) = key +: reverseMap.getOrElse(v, Nil)
       }
@@ -238,12 +248,12 @@ final class RenameMap private (
     RenameMap.create(reverseMap)
   }
 
-  def keys: Iterator[CompleteTarget] = underlying.keysIterator
+  @deprecated("This should never have been public", "FIRRTL 1.5")
+  def keys: Iterator[CompleteTarget] = _underlying.keysIterator
 
-  /** Serialize the underlying remapping of keys to new targets
-    * @return
+  /** Visualize the [[RenameMap]]
     */
-  def serialize: String = underlying.map {
+  def serialize: String = _underlying.map {
     case (k, v) =>
       k.serialize + "=>" + v.map(_.serialize).mkString(", ")
   }.mkString("\n")
@@ -280,8 +290,8 @@ final class RenameMap private (
     * @return Optionally return sequence of targets that key remaps to
     */
   private def completeGet(key: CompleteTarget): Option[Seq[CompleteTarget]] = {
-    if (chained.nonEmpty) {
-      val chainedRet = chained.get.completeGet(key).getOrElse(Seq(key))
+    if (_chained.nonEmpty) {
+      val chainedRet = _chained.get.completeGet(key).getOrElse(Seq(key))
       if (chainedRet.isEmpty) {
         Some(chainedRet)
       } else {
@@ -329,8 +339,8 @@ final class RenameMap private (
   private def referenceGet(errors: mutable.ArrayBuffer[String])(key: ReferenceTarget): Option[Seq[IsComponent]] = {
     def traverseTokens(key: ReferenceTarget): Option[Seq[IsComponent]] = traverseTokensCache.getOrElseUpdate(
       key, {
-        if (underlying.contains(key)) {
-          Some(underlying(key).flatMap {
+        if (_underlying.contains(key)) {
+          Some(_underlying(key).flatMap {
             case comp: IsComponent => Some(comp)
             case other =>
               errors += s"reference ${key.targetParent} cannot be renamed to a non-component ${other}"
@@ -402,7 +412,7 @@ final class RenameMap private (
   private def instanceGet(errors: mutable.ArrayBuffer[String])(key: InstanceTarget): Option[Seq[IsModule]] = {
     def traverseLeft(key: InstanceTarget): Option[Seq[IsModule]] = traverseLeftCache.getOrElseUpdate(
       key, {
-        val getOpt = underlying.get(key)
+        val getOpt = _underlying.get(key)
 
         if (getOpt.nonEmpty) {
           getOpt.map(_.flatMap {
@@ -447,7 +457,7 @@ final class RenameMap private (
   }
 
   private def circuitGet(errors: mutable.ArrayBuffer[String])(key: CircuitTarget): Seq[CircuitTarget] = {
-    underlying
+    _underlying
       .get(key)
       .map(_.flatMap {
         case c: CircuitTarget => Some(c)
@@ -459,7 +469,7 @@ final class RenameMap private (
   }
 
   private def moduleGet(errors: mutable.ArrayBuffer[String])(key: ModuleTarget): Option[Seq[IsModule]] = {
-    underlying
+    _underlying
       .get(key)
       .map(_.flatMap {
         case mod: IsModule => Some(mod)
@@ -668,14 +678,14 @@ final class RenameMap private (
     * @param from
     * @param tos
     */
-  private def completeRename(from: CompleteTarget, tos: Seq[CompleteTarget]): Unit = {
+  protected def completeRename(from: CompleteTarget, tos: Seq[CompleteTarget]): Unit = {
     tos.foreach { recordSensitivity(from, _) }
-    val existing = underlying.getOrElse(from, Vector.empty)
+    val existing = _underlying.getOrElse(from, Vector.empty)
     val updated = {
       val all = (existing ++ tos)
       if (doDistinct) all.distinct else all
     }
-    underlying(from) = updated
+    _underlying(from) = updated
     traverseTokensCache.clear()
     traverseHierarchyCache.clear()
     traverseLeftCache.clear()
@@ -684,20 +694,28 @@ final class RenameMap private (
 
   /* DEPRECATED ACCESSOR/SETTOR METHODS WITH [[firrtl.ir.Named Named]] */
 
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def rename(from: Named, to: Named): Unit = rename(from, Seq(to))
 
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def rename(from: Named, tos: Seq[Named]): Unit = recordAll(Map(from.toTarget -> tos.map(_.toTarget)))
 
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def rename(from: ComponentName, to: ComponentName): Unit = record(from, to)
 
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def rename(from: ComponentName, tos: Seq[ComponentName]): Unit = record(from, tos.map(_.toTarget))
 
-  def delete(name: CircuitName): Unit = underlying(name) = Seq.empty
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
+  def delete(name: CircuitName): Unit = _underlying(name) = Seq.empty
 
-  def delete(name: ModuleName): Unit = underlying(name) = Seq.empty
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
+  def delete(name: ModuleName): Unit = _underlying(name) = Seq.empty
 
-  def delete(name: ComponentName): Unit = underlying(name) = Seq.empty
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
+  def delete(name: ComponentName): Unit = _underlying(name) = Seq.empty
 
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def addMap(map: collection.Map[Named, Seq[Named]]): Unit =
     recordAll(map.map {
       case (key, values) => (Target.convertNamed2Target(key), values.map(Target.convertNamed2Target))
@@ -727,17 +745,20 @@ final class RenameMap private (
   /** Sets mutable state to record current module we are visiting
     * @param module
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def setModule(module: String): Unit = moduleName = module
 
   /** Sets mutable state to record current circuit we are visiting
     * @param circuit
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def setCircuit(circuit: String): Unit = circuitName = circuit
 
   /** Records how a reference maps to a new reference
     * @param from
     * @param to
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def rename(from: String, to: String): Unit = rename(from, Seq(to))
 
   /** Records how a reference maps to a new reference
@@ -745,6 +766,7 @@ final class RenameMap private (
     * @param from
     * @param tos
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def rename(from: String, tos: Seq[String]): Unit = {
     val mn = ModuleName(moduleName, CircuitName(circuitName))
     val fromName = ComponentName(from, mn).toTarget
@@ -756,6 +778,7 @@ final class RenameMap private (
     * The reference's root module and circuit are determined by whomever called setModule or setCircuit last
     * @param name
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def delete(name: String): Unit = {
     Target(Some(circuitName), Some(moduleName), AnnotationUtils.toSubComponents(name)).getComplete match {
       case Some(t: CircuitTarget) => delete(t)
@@ -768,5 +791,92 @@ final class RenameMap private (
     * The reference's root module and circuit are determined by whomever called setModule or setCircuit last
     * @param names
     */
+  @deprecated("Use firrtl.renamemap.MutableRenameMap for recording renames", "FIRRTL 1.5")
   def delete(names: Seq[String]): Unit = names.foreach(delete(_))
 }
+
+// This must be in same file as RenameMap because RenameMap is sealed
+package object renamemap {
+  object MutableRenameMap {
+    def fromNamed(map: collection.Map[Named, Seq[Named]]): MutableRenameMap = {
+      val rm = new MutableRenameMap
+      rm.addMap(map)
+      rm
+    }
+
+    def apply(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): MutableRenameMap = {
+      val rm = new MutableRenameMap
+      rm.recordAll(map)
+      rm
+    }
+
+    /** Initialize a new RenameMap */
+    def apply(): MutableRenameMap = new MutableRenameMap
+
+    // This is a private internal API for transforms where the .distinct operation is very expensive
+    // (eg. LowerTypes). The onus is on the user of this API to be very careful and not inject
+    // duplicates. This is a bad, hacky API that no one should use
+    private[firrtl] def noDistinct(): MutableRenameMap = new MutableRenameMap(doDistinct = false)
+  }
+
+  // Override deprecated methods so they aren't deprecated when using this class
+  final class MutableRenameMap private[firrtl] (
+    protected val _underlying: mutable.HashMap[CompleteTarget, Seq[CompleteTarget]] =
+      mutable.HashMap[CompleteTarget, Seq[CompleteTarget]](),
+    protected val _chained:   Option[RenameMap] = None,
+    protected val doDistinct: Boolean = true)
+      extends RenameMap {
+
+    override def record(from: CircuitTarget, to: CircuitTarget): Unit = completeRename(from, Seq(to))
+
+    override def record(from: CircuitTarget, tos: Seq[CircuitTarget]): Unit = completeRename(from, tos)
+
+    override def record(from: IsMember, to: IsMember): Unit = completeRename(from, Seq(to))
+
+    override def record(from: IsMember, tos: Seq[IsMember]): Unit = completeRename(from, tos)
+
+    override def recordAll(map: collection.Map[CompleteTarget, Seq[CompleteTarget]]): Unit =
+      super._recordAll(map)
+
+    override def delete(name: CompleteTarget): Unit = _underlying(name) = Seq.empty
+
+    override def rename(from: Named, to: Named): Unit = rename(from, Seq(to))
+
+    override def rename(from: Named, tos: Seq[Named]): Unit = recordAll(Map(from.toTarget -> tos.map(_.toTarget)))
+
+    override def rename(from: ComponentName, to: ComponentName): Unit = record(from, to)
+
+    override def rename(from: ComponentName, tos: Seq[ComponentName]): Unit = record(from, tos.map(_.toTarget))
+
+    override def delete(name: CircuitName): Unit = _underlying(name) = Seq.empty
+
+    override def delete(name: ModuleName): Unit = _underlying(name) = Seq.empty
+
+    override def delete(name: ComponentName): Unit = _underlying(name) = Seq.empty
+
+    override def addMap(map: collection.Map[Named, Seq[Named]]): Unit =
+      recordAll(map.map {
+        case (key, values) => (Target.convertNamed2Target(key), values.map(Target.convertNamed2Target))
+      })
+
+    // These are overridden to change the deprecation warning
+
+    @deprecated("Use type-safe rename methods instead", "FIRRTL 1.5")
+    override def setModule(module: String): Unit = super.setModule(module)
+
+    @deprecated("Use type-safe rename methods instead", "FIRRTL 1.5")
+    override def setCircuit(circuit: String): Unit = super.setCircuit(circuit)
+
+    @deprecated("Use type-safe rename methods instead", "FIRRTL 1.5")
+    override def rename(from: String, to: String): Unit = super.rename(from, to)
+
+    @deprecated("Use type-safe rename methods instead", "FIRRTL 1.5")
+    override def rename(from: String, tos: Seq[String]): Unit = super.rename(from, tos)
+
+    @deprecated("Use type-safe delete methods instead", "FIRRTL 1.5")
+    override def delete(name: String): Unit = super.delete(name)
+
+    @deprecated("Use type-safe delete methods instead", "FIRRTL 1.5")
+    override def delete(names: Seq[String]): Unit = super.delete(names)
+  }
+}
diff --git a/src/main/scala/firrtl/annotations/transforms/CleanupNamedTargets.scala b/src/main/scala/firrtl/annotations/transforms/CleanupNamedTargets.scala
index 28f50993..8635d9ed 100644
--- a/src/main/scala/firrtl/annotations/transforms/CleanupNamedTargets.scala
+++ b/src/main/scala/firrtl/annotations/transforms/CleanupNamedTargets.scala
@@ -7,6 +7,7 @@ import firrtl.annotations.{CircuitTarget, ModuleTarget, MultiTargetAnnotation, R
 import firrtl.ir
 import firrtl.options.{Dependency, PreservesAll}
 import firrtl.traversals.Foreachers._
+import firrtl.renamemap.MutableRenameMap
 
 import scala.collection.immutable.{Set => ISet}
 
@@ -31,7 +32,7 @@ class CleanupNamedTargets extends Transform with DependencyAPIMigration {
     statement: ir.Statement
   )(
     implicit references: ISet[ReferenceTarget],
-    renameMap:           RenameMap,
+    renameMap:           MutableRenameMap,
     module:              ModuleTarget
   ): Unit = statement match {
     case ir.DefInstance(_, a, b, _) if references(module.instOf(a, b).asReference) =>
@@ -43,7 +44,7 @@ class CleanupNamedTargets extends Transform with DependencyAPIMigration {
     module: ir.DefModule
   )(
     implicit references: ISet[ReferenceTarget],
-    renameMap:           RenameMap,
+    renameMap:           MutableRenameMap,
     circuit:             CircuitTarget
   ): Unit = {
     implicit val mTarget = circuit.module(module.name)
@@ -60,7 +61,7 @@ class CleanupNamedTargets extends Transform with DependencyAPIMigration {
       case a: ReferenceTarget => a
     }.toSet
 
-    implicit val renameMap = RenameMap()
+    implicit val renameMap = MutableRenameMap()
 
     implicit val cTarget = CircuitTarget(state.circuit.main)
 
diff --git a/src/main/scala/firrtl/annotations/transforms/EliminateTargetPaths.scala b/src/main/scala/firrtl/annotations/transforms/EliminateTargetPaths.scala
index 104aafc3..83bea253 100644
--- a/src/main/scala/firrtl/annotations/transforms/EliminateTargetPaths.scala
+++ b/src/main/scala/firrtl/annotations/transforms/EliminateTargetPaths.scala
@@ -10,6 +10,7 @@ import firrtl.annotations.analysis.DuplicationHelper
 import firrtl.annotations._
 import firrtl.ir._
 import firrtl.{AnnotationSeq, CircuitState, DependencyAPIMigration, FirrtlInternalException, RenameMap, Transform}
+import firrtl.renamemap.MutableRenameMap
 import firrtl.stage.Forms
 import firrtl.transforms.DedupedResult
 import firrtl.transforms.DedupAnnotationsTransform
@@ -45,7 +46,12 @@ case class NoSuchTargetException(message: String) extends FirrtlInternalExceptio
 
 object EliminateTargetPaths {
 
-  def renameModules(c: Circuit, toRename: Map[String, String], renameMap: RenameMap): Circuit = {
+  @deprecated("Use version that accepts renamemap.MutableRenameMap", "FIRRTL 1.5")
+  def renameModules(c: Circuit, toRename: Map[String, String], renameMap: RenameMap): Circuit =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only subclass
+    renameModules(c, toRename, renameMap.asInstanceOf[MutableRenameMap])
+
+  def renameModules(c: Circuit, toRename: Map[String, String], renameMap: MutableRenameMap): Circuit = {
     val ct = CircuitTarget(c.main)
     val cx = if (toRename.contains(c.main)) {
       renameMap.record(ct, CircuitTarget(toRename(c.main)))
@@ -159,7 +165,7 @@ class EliminateTargetPaths extends Transform with DependencyAPIMigration {
     lazy val finalModuleSet = finalModuleList.map { case a: DefModule => a.name }.toSet
 
     // Records how targets have been renamed
-    val renameMap = RenameMap()
+    val renameMap = MutableRenameMap()
 
     /* Foreach target, calculate the pathless version and only rename targets that are instantiated. Additionally, rename
      * module targets
@@ -264,7 +270,7 @@ class EliminateTargetPaths extends Transform with DependencyAPIMigration {
       val cache = mutable.Map.empty[String, Boolean]
       mod => cache.getOrElseUpdate(mod, iGraph.findInstancesInHierarchy(mod).size == 1)
     }
-    val firstRenameMap = RenameMap()
+    val firstRenameMap = MutableRenameMap()
     val nonSingletonTargets = targets.foldRight(Seq.empty[IsMember]) {
       case (t: IsComponent, acc) if t.asPath.nonEmpty =>
         val origPath = t.asPath
@@ -298,11 +304,13 @@ class EliminateTargetPaths extends Transform with DependencyAPIMigration {
 
     val (newCircuit, nextRenameMap, newAnnos) = run(state.circuit, nonSingletonTargets, iGraph)
 
-    val renameMap =
+    val renameMap: MutableRenameMap =
       if (firstRenameMap.hasChanges) {
-        firstRenameMap.andThen(nextRenameMap)
+        // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only subclass
+        firstRenameMap.andThen(nextRenameMap).asInstanceOf[MutableRenameMap]
       } else {
-        nextRenameMap
+        // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only subclass
+        nextRenameMap.asInstanceOf[MutableRenameMap]
       }
 
     val iGraphx = InstanceKeyGraph(newCircuit)
diff --git a/src/main/scala/firrtl/backends/experimental/smt/StutteringClockTransform.scala b/src/main/scala/firrtl/backends/experimental/smt/StutteringClockTransform.scala
index 5db39ac9..534db217 100644
--- a/src/main/scala/firrtl/backends/experimental/smt/StutteringClockTransform.scala
+++ b/src/main/scala/firrtl/backends/experimental/smt/StutteringClockTransform.scala
@@ -11,6 +11,7 @@ import firrtl.passes.PassException
 import firrtl.stage.Forms
 import firrtl.stage.TransformManager.TransformDependency
 import firrtl.transforms.PropagatePresetAnnotations
+import firrtl.renamemap.MutableRenameMap
 
 import scala.collection.mutable
 
@@ -94,7 +95,7 @@ class StutteringClockTransform extends Transform with DependencyAPIMigration {
 
     // rename clocks to clock enable signals
     val mRef = CircuitTarget(state.circuit.main).module(main.name)
-    val renameMap = RenameMap()
+    val renameMap = MutableRenameMap()
     scan.clockToEnable.foreach {
       case (clk, en) =>
         renameMap.record(mRef.ref(clk), mRef.ref(en.name))
diff --git a/src/main/scala/firrtl/passes/Inline.scala b/src/main/scala/firrtl/passes/Inline.scala
index 85eb7b51..e2105ff2 100644
--- a/src/main/scala/firrtl/passes/Inline.scala
+++ b/src/main/scala/firrtl/passes/Inline.scala
@@ -11,6 +11,7 @@ import firrtl.analyses.InstanceKeyGraph
 import firrtl.graph.{DiGraph, MutableDiGraph}
 import firrtl.stage.{Forms, RunFirrtlTransformAnnotation}
 import firrtl.options.{RegisteredTransform, ShellOption}
+import firrtl.renamemap.MutableRenameMap
 
 // Datastructures
 import scala.collection.mutable
@@ -184,7 +185,7 @@ class InlineInstances extends Transform with DependencyAPIMigration with Registe
       prefix:        String,
       ns:            Namespace,
       renames:       mutable.HashMap[String, String],
-      renameMap:     RenameMap
+      renameMap:     MutableRenameMap
     )(s:             Statement
     ): Statement = {
       def onName(ofModuleOpt: Option[String])(name: String): String = {
@@ -276,10 +277,10 @@ class InlineInstances extends Transform with DependencyAPIMigration with Registe
 
       indexMap match {
         case a if a.isEmpty =>
-          (Map.empty[(OfModule, Instance), RenameMap], Seq.empty[RenameMap])
+          (Map.empty[(OfModule, Instance), MutableRenameMap], Seq.empty[MutableRenameMap])
         case a =>
           val maxIdx = indexMap.values.max
-          val resultSeq = Seq.fill(maxIdx + 1)(RenameMap())
+          val resultSeq = Seq.fill(maxIdx + 1)(MutableRenameMap())
           val resultMap = indexMap.mapValues(idx => resultSeq(maxIdx - idx))
           (resultMap, resultSeq)
       }
@@ -367,7 +368,8 @@ class InlineInstances extends Transform with DependencyAPIMigration with Registe
         Some(m.map(onStmt(ModuleName(m.name, CircuitName(c.main)))))
     })
 
-    val renames = renamesSeq.reduceLeftOption(_ andThen _)
+    // Upcast so reduce works (andThen returns RenameMap)
+    val renames = (renamesSeq: Seq[RenameMap]).reduceLeftOption(_ andThen _)
 
     val cleanedAnnos = annos.filterNot {
       case InlineAnnotation(_) => true
diff --git a/src/main/scala/firrtl/passes/LowerTypes.scala b/src/main/scala/firrtl/passes/LowerTypes.scala
index 7ba320d0..976741fd 100644
--- a/src/main/scala/firrtl/passes/LowerTypes.scala
+++ b/src/main/scala/firrtl/passes/LowerTypes.scala
@@ -28,6 +28,7 @@ import firrtl.{
 import firrtl.ir._
 import firrtl.options.Dependency
 import firrtl.stage.TransformManager.TransformDependency
+import firrtl.renamemap.MutableRenameMap
 
 import scala.annotation.tailrec
 import scala.collection.mutable
@@ -80,7 +81,7 @@ object LowerTypes extends Transform with DependencyAPIMigration {
     // writers. Unfortunately, when you have lots of renames, this is very expensive
     // performance-wise. We use a private internal API that does not run .distinct to improve
     // performance, but we must be careful to not insert any duplicates.
-    val refRenameMap = RenameMap.noDistinct()
+    val refRenameMap = MutableRenameMap.noDistinct()
     val resultAndRenames =
       state.circuit.modules.map(m => onModule(c, m, memInitByModule.getOrElse(m.name, Seq()), refRenameMap))
     val result = state.circuit.copy(modules = resultAndRenames.map(_._1))
@@ -100,7 +101,7 @@ object LowerTypes extends Transform with DependencyAPIMigration {
     c:          CircuitTarget,
     m:          DefModule,
     memoryInit: Seq[MemoryInitAnnotation],
-    renameMap:  RenameMap
+    renameMap:  MutableRenameMap
   ): (DefModule, Map[Instance, Instance], Seq[MemoryInitAnnotation]) = {
     val ref = c.module(m.name)
 
@@ -123,7 +124,7 @@ object LowerTypes extends Transform with DependencyAPIMigration {
   private def lowerPorts(
     ref:       ModuleTarget,
     m:         DefModule,
-    renameMap: RenameMap
+    renameMap: MutableRenameMap
   ): (DefModule, Seq[(String, Seq[Reference])]) = {
     val namespace = mutable.HashSet[String]() ++ m.ports.map(_.name)
     val loweredPortsAndRefs = m.ports.flatMap { p =>
@@ -225,7 +226,7 @@ private class LoweringSymbolTable extends SymbolTable {
 // Lowers types and keeps track of references to lowered types.
 private class LoweringTable(
   table:           LoweringSymbolTable,
-  renameMap:       RenameMap,
+  renameMap:       MutableRenameMap,
   m:               ModuleTarget,
   portNameToExprs: Seq[(String, Seq[Reference])]) {
   private val portNames: Set[String] = portNameToExprs.map(_._2.head.name).toSet
@@ -284,7 +285,7 @@ private object DestructTypes {
     m:         ModuleTarget,
     ref:       Field,
     namespace: Namespace,
-    renameMap: RenameMap,
+    renameMap: MutableRenameMap,
     reserved:  Set[String]
   ): Seq[(Field, String)] = {
     // field renames (uniquify) are computed bottom up
@@ -349,7 +350,7 @@ private object DestructTypes {
     m:         ModuleTarget,
     mem:       DefMemory,
     namespace: Namespace,
-    renameMap: RenameMap,
+    renameMap: MutableRenameMap,
     reserved:  Set[String]
   ): (Seq[DefMemory], Seq[(String, SubField)]) = {
     // Uniquify the lowered memory names: When memories get split up into ground types, the access order is changes.
@@ -425,7 +426,7 @@ private object DestructTypes {
 
   private def recordRenames(
     fieldToRefs: Seq[(Field, Seq[ReferenceTarget])],
-    renameMap:   RenameMap,
+    renameMap:   MutableRenameMap,
     parent:      ParentRef
   ): Unit = {
     // TODO: if we group by ReferenceTarget, we could reduce the number of calls to `record`. Is it worth it?
diff --git a/src/main/scala/firrtl/passes/RemoveCHIRRTL.scala b/src/main/scala/firrtl/passes/RemoveCHIRRTL.scala
index f8511820..d181e6ac 100644
--- a/src/main/scala/firrtl/passes/RemoveCHIRRTL.scala
+++ b/src/main/scala/firrtl/passes/RemoveCHIRRTL.scala
@@ -9,6 +9,7 @@ import firrtl.ir._
 import firrtl.Utils._
 import firrtl.Mappers._
 import firrtl.options.Dependency
+import firrtl.renamemap.MutableRenameMap
 
 case class MPort(name: String, clk: Expression)
 case class MPorts(readers: ArrayBuffer[MPort], writers: ArrayBuffer[MPort], readwriters: ArrayBuffer[MPort])
@@ -78,6 +79,7 @@ object RemoveCHIRRTL extends Transform with DependencyAPIMigration {
     s.map(collect_smems_and_mports(mports, smems))
   }
 
+  @deprecated("This should never have been public", "FIRRTL 1.5")
   def collect_refs(
     mports:  MPortMap,
     smems:   SeqMemSet,
@@ -86,6 +88,18 @@ object RemoveCHIRRTL extends Transform with DependencyAPIMigration {
     raddrs:  AddrMap,
     renames: RenameMap
   )(s:       Statement
+  ): Statement =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only subclass
+    collect_refs(mports, smems, types, refs, raddrs, renames.asInstanceOf[MutableRenameMap])(s)
+
+  private def collect_refs(
+    mports:  MPortMap,
+    smems:   SeqMemSet,
+    types:   MPortTypeMap,
+    refs:    DataRefMap,
+    raddrs:  AddrMap,
+    renames: MutableRenameMap
+  )(s:       Statement
   ): Statement = s match {
     case sx: CDefMemory =>
       types(sx.name) = sx.tpe
@@ -285,7 +299,12 @@ object RemoveCHIRRTL extends Transform with DependencyAPIMigration {
     }
   }
 
-  def remove_chirrtl_m(renames: RenameMap)(m: DefModule): DefModule = {
+  @deprecated("This should never have been public", "FIRRTL 1.5")
+  def remove_chirrtl_m(renames: RenameMap)(m: DefModule): DefModule =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only subclass
+    remove_chirrtl_m(renames.asInstanceOf[MutableRenameMap])(m)
+
+  private def remove_chirrtl_m(renames: MutableRenameMap)(m: DefModule): DefModule = {
     val mports = new MPortMap
     val smems = new SeqMemSet
     val types = new MPortTypeMap
@@ -299,7 +318,7 @@ object RemoveCHIRRTL extends Transform with DependencyAPIMigration {
 
   def execute(state: CircuitState): CircuitState = {
     val c = state.circuit
-    val renames = RenameMap()
+    val renames = MutableRenameMap()
     renames.setCircuit(c.main)
     val result = c.copy(modules = c.modules.map(remove_chirrtl_m(renames)))
     state.copy(circuit = result, renames = Some(renames))
diff --git a/src/main/scala/firrtl/passes/ZeroWidth.scala b/src/main/scala/firrtl/passes/ZeroWidth.scala
index 80eeab12..ab1cf7bb 100644
--- a/src/main/scala/firrtl/passes/ZeroWidth.scala
+++ b/src/main/scala/firrtl/passes/ZeroWidth.scala
@@ -5,6 +5,7 @@ package firrtl.passes
 import firrtl.PrimOps._
 import firrtl.ir._
 import firrtl._
+import firrtl.renamemap.MutableRenameMap
 import firrtl.Mappers._
 import firrtl.options.Dependency
 
@@ -143,7 +144,7 @@ object ZeroWidth extends Transform with DependencyAPIMigration {
         case _                        => e.map(onExp)
       }
   }
-  private def onStmt(renames: RenameMap)(s: Statement): Statement = s match {
+  private def onStmt(renames: MutableRenameMap)(s: Statement): Statement = s match {
     case d @ DefWire(info, name, tpe) =>
       renames.delete(getRemoved(d))
       removeZero(tpe) match {
@@ -181,7 +182,7 @@ object ZeroWidth extends Transform with DependencyAPIMigration {
       }
     case sx => sx.map(onStmt(renames)).map(onExp)
   }
-  private def onModule(renames: RenameMap)(m: DefModule): DefModule = {
+  private def onModule(renames: MutableRenameMap)(m: DefModule): DefModule = {
     renames.setModule(m.name)
     // For each port, record deleted subcomponents
     m.ports.foreach { p => renames.delete(getRemoved(p)) }
@@ -200,7 +201,7 @@ object ZeroWidth extends Transform with DependencyAPIMigration {
     // run executeEmptyMemStmt first to remove zero-width memories
     // then run InferTypes to update widths for addr, en, clk, etc
     val c = InferTypes.run(executeEmptyMemStmt(state).circuit)
-    val renames = RenameMap()
+    val renames = MutableRenameMap()
     renames.setCircuit(c.main)
     val result = c.copy(modules = c.modules.map(onModule(renames)))
     CircuitState(result, outputForm, state.annotations, Some(renames))
diff --git a/src/main/scala/firrtl/passes/memlib/ReplaceMemMacros.scala b/src/main/scala/firrtl/passes/memlib/ReplaceMemMacros.scala
index 35a765f8..cb824996 100644
--- a/src/main/scala/firrtl/passes/memlib/ReplaceMemMacros.scala
+++ b/src/main/scala/firrtl/passes/memlib/ReplaceMemMacros.scala
@@ -12,6 +12,7 @@ import firrtl.passes.MemPortUtils.{MemPortMap, Modules}
 import firrtl.passes.memlib.MemTransformUtils._
 import firrtl.passes.wiring._
 import firrtl.stage.Forms
+import firrtl.renamemap.MutableRenameMap
 
 import scala.collection.mutable.ListBuffer
 
@@ -244,7 +245,7 @@ class ReplaceMemMacros extends Transform with DependencyAPIMigration {
     memPortMap:              MemPortMap,
     memMods:                 Modules,
     annotatedMemoriesBuffer: ListBuffer[DefAnnotatedMemory],
-    renameMap:               RenameMap,
+    renameMap:               MutableRenameMap,
     circuit:                 String
   )(s:                       Statement
   ): Statement = s match {
@@ -282,7 +283,7 @@ class ReplaceMemMacros extends Transform with DependencyAPIMigration {
     nameMap:                 NameMap,
     memMods:                 Modules,
     annotatedMemoriesBuffer: ListBuffer[DefAnnotatedMemory],
-    renameMap:               RenameMap,
+    renameMap:               MutableRenameMap,
     circuit:                 String
   )(m:                       DefModule
   ) = {
@@ -299,7 +300,7 @@ class ReplaceMemMacros extends Transform with DependencyAPIMigration {
     val memMods = new Modules
     val nameMap = new NameMap
     c.modules.map(m => m.map(constructNameMap(namespace, nameMap, m.name)))
-    val renameMap = RenameMap()
+    val renameMap = MutableRenameMap()
     val modules = c.modules.map(updateMemMods(namespace, nameMap, memMods, annotatedMemoriesBuffer, renameMap, c.main))
     state.copy(
       circuit = c.copy(modules = modules ++ memMods),
diff --git a/src/main/scala/firrtl/transforms/DeadCodeElimination.scala b/src/main/scala/firrtl/transforms/DeadCodeElimination.scala
index 41ffd2be..a622feb4 100644
--- a/src/main/scala/firrtl/transforms/DeadCodeElimination.scala
+++ b/src/main/scala/firrtl/transforms/DeadCodeElimination.scala
@@ -11,6 +11,7 @@ import firrtl.analyses.InstanceKeyGraph
 import firrtl.Mappers._
 import firrtl.Utils.{kind, throwInternalError}
 import firrtl.MemoizedHash._
+import firrtl.renamemap.MutableRenameMap
 import firrtl.backends.experimental.smt.random.DefRandom
 import firrtl.options.{Dependency, RegisteredTransform, ShellOption}
 
@@ -213,7 +214,7 @@ class DeadCodeElimination extends Transform with RegisteredTransform with Depend
     instMap:        collection.Map[String, String],
     deadNodes:      collection.Set[LogicNode],
     moduleMap:      collection.Map[String, DefModule],
-    renames:        RenameMap,
+    renames:        MutableRenameMap,
     topName:        String,
     doTouchExtMods: Set[String]
   )(mod:            DefModule
@@ -346,7 +347,7 @@ class DeadCodeElimination extends Transform with RegisteredTransform with Depend
 
     val liveNodes = depGraph.reachableFrom(circuitSink) + circuitSink
     val deadNodes = depGraph.getVertices -- liveNodes
-    val renames = RenameMap()
+    val renames = MutableRenameMap()
     renames.setCircuit(c.main)
 
     // As we delete deadCode, we will delete ports from Modules and somtimes complete modules
diff --git a/src/main/scala/firrtl/transforms/Dedup.scala b/src/main/scala/firrtl/transforms/Dedup.scala
index 2fb98224..373066c8 100644
--- a/src/main/scala/firrtl/transforms/Dedup.scala
+++ b/src/main/scala/firrtl/transforms/Dedup.scala
@@ -13,6 +13,7 @@ import firrtl.Utils.{kind, splitRef, throwInternalError}
 import firrtl.annotations.transforms.DupedResult
 import firrtl.annotations.TargetToken.{Instance, OfModule}
 import firrtl.options.{HasShellOptions, ShellOption}
+import firrtl.renamemap.MutableRenameMap
 import logger.LazyLogging
 
 import scala.annotation.tailrec
@@ -123,7 +124,7 @@ class DedupModules extends Transform with DependencyAPIMigration {
   ): (Circuit, RenameMap, AnnotationSeq) = {
 
     // RenameMap
-    val componentRenameMap = RenameMap()
+    val componentRenameMap = MutableRenameMap()
     componentRenameMap.setCircuit(c.main)
 
     // Maps module name to corresponding dedup module
@@ -161,12 +162,12 @@ class DedupModules extends Transform with DependencyAPIMigration {
         logger.debug(s"[Dedup] $from -> ${to.name}")
         ct.module(from).asInstanceOf[CompleteTarget] -> Seq(ct.module(to.name))
     }
-    val moduleRenameMap = RenameMap()
+    val moduleRenameMap = MutableRenameMap()
     moduleRenameMap.recordAll(map)
 
     // Build instanceify renaming map
     val instanceGraph = InstanceKeyGraph(c)
-    val instanceify = RenameMap()
+    val instanceify = MutableRenameMap()
     val moduleName2Index = c.modules
       .map(_.name)
       .zipWithIndex
@@ -337,6 +338,18 @@ object DedupModules extends LazyLogging {
     module.map(onPort).map(onStmt)
   }
 
+  @deprecated("Use version that accepts renamemap.MutableRenameMap", "FIRRTL 1.5")
+  def dedupInstances(
+    top:            CircuitTarget,
+    originalModule: String,
+    moduleMap:      Map[String, DefModule],
+    name2name:      Map[String, String],
+    renameMap:      RenameMap
+  ): DefModule =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only concrete class that
+    // can be instantiated
+    dedupInstances(top, originalModule, moduleMap, name2name, renameMap.asInstanceOf[MutableRenameMap])
+
   /** Dedup a module's instances based on dedup map
     *
     * Will fixes up module if deduped instance's ports are differently named
@@ -353,7 +366,7 @@ object DedupModules extends LazyLogging {
     originalModule: String,
     moduleMap:      Map[String, DefModule],
     name2name:      Map[String, String],
-    renameMap:      RenameMap
+    renameMap:      MutableRenameMap
   ): DefModule = {
     val module = moduleMap(originalModule)
 
@@ -481,11 +494,22 @@ object DedupModules extends LazyLogging {
     }
 
     val tag2all = hashToNames.map { case (hash, names) => hashToTag(hash) -> names.toSet }
-    val tagMap = RenameMap()
+    val tagMap = MutableRenameMap()
     moduleNameToTag.foreach { case (name, tag) => tagMap.record(top.module(name), top.module(tag)) }
     (tag2all, tagMap)
   }
 
+  @deprecated("Use version that accepts renamemap.MutableRenameMap", "FIRRTL 1.5")
+  def deduplicate(
+    circuit:            Circuit,
+    noDedups:           Set[String],
+    previousDupResults: Map[String, String],
+    renameMap:          RenameMap
+  ): Map[String, DefModule] =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only concrete class that
+    // can be instantiated
+    deduplicate(circuit, noDedups, previousDupResults, renameMap.asInstanceOf[MutableRenameMap])
+
   /** Deduplicate
     * @param circuit Circuit
     * @param noDedups list of modules to not dedup
@@ -496,7 +520,7 @@ object DedupModules extends LazyLogging {
     circuit:            Circuit,
     noDedups:           Set[String],
     previousDupResults: Map[String, String],
-    renameMap:          RenameMap
+    renameMap:          MutableRenameMap
   ): Map[String, DefModule] = {
 
     val (moduleMap, moduleLinearization) = {
@@ -587,10 +611,20 @@ object DedupModules extends LazyLogging {
     refs.toIndexedSeq
   }
 
+  @deprecated("Use version that accepts renamemap.MutableRenameMap", "FIRRTL 1.5")
   def computeRenameMap(
     originalNames: IndexedSeq[ReferenceTarget],
     dedupedNames:  IndexedSeq[ReferenceTarget],
     renameMap:     RenameMap
+  ): Unit =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only concrete class that
+    // can be instantiated
+    computeRenameMap(originalNames, dedupedNames, renameMap.asInstanceOf[MutableRenameMap])
+
+  def computeRenameMap(
+    originalNames: IndexedSeq[ReferenceTarget],
+    dedupedNames:  IndexedSeq[ReferenceTarget],
+    renameMap:     MutableRenameMap
   ): Unit = {
 
     originalNames.zip(dedupedNames).foreach {
diff --git a/src/main/scala/firrtl/transforms/ManipulateNames.scala b/src/main/scala/firrtl/transforms/ManipulateNames.scala
index 4a796e58..3596b7e6 100644
--- a/src/main/scala/firrtl/transforms/ManipulateNames.scala
+++ b/src/main/scala/firrtl/transforms/ManipulateNames.scala
@@ -5,6 +5,7 @@ package firrtl.transforms
 import firrtl._
 import firrtl.analyses.InstanceKeyGraph
 import firrtl.Mappers._
+import firrtl.renamemap.MutableRenameMap
 
 import firrtl.annotations.{
   CircuitTarget,
@@ -24,6 +25,7 @@ import scala.collection.mutable
 import scala.reflect.ClassTag
 
 /** Base trait for annotations that control the behavior of transforms that sub-class ManipulateNames
+  *
   * @see [[ManipulateNamesBlocklistAnnotation]]
   * @see [[ManipulateNamesAllowlistAnnotation]]
   * @define noteLocalTargets All targets must be local. Name modification in a non-local target (e.g., a node in a
@@ -141,7 +143,7 @@ case class ManipulateNamesAllowlistResultAnnotation[A <: ManipulateNames[_]](
   */
 private class RenameDataStructure(
   circuit:     ir.Circuit,
-  val renames: RenameMap,
+  val renames: MutableRenameMap,
   val block:   Target => Boolean,
   val allow:   Target => Boolean) {
 
@@ -399,6 +401,16 @@ abstract class ManipulateNames[A <: ManipulateNames[_]: ClassTag] extends Transf
         .map(onStatement(_: ir.Statement, r, moduleTarget))
   }
 
+  @deprecated("Use version that accepts renamemap.MutableRenameMap", "FIRRTL 1.5")
+  def run(
+    c:       ir.Circuit,
+    renames: RenameMap,
+    block:   Target => Boolean,
+    allow:   Target => Boolean
+  ): ir.Circuit =
+    // Cast is safe because RenameMap is sealed trait, MutableRenameMap is only subclass
+    run(c, renames.asInstanceOf[MutableRenameMap], block, allow)
+
   /** Manipulate all names in a circuit
     *
     * @param c an input circuit
@@ -409,7 +421,7 @@ abstract class ManipulateNames[A <: ManipulateNames[_]: ClassTag] extends Transf
     */
   def run(
     c:       ir.Circuit,
-    renames: RenameMap,
+    renames: MutableRenameMap,
     block:   Target => Boolean,
     allow:   Target => Boolean
   ): ir.Circuit = {
@@ -485,7 +497,7 @@ abstract class ManipulateNames[A <: ManipulateNames[_]: ClassTag] extends Transf
       }
     }
 
-    val renames = RenameMap()
+    val renames = MutableRenameMap()
     val circuitx = run(state.circuit, renames, block, allow)
 
     val annotationsx = state.annotations.flatMap {
diff --git a/src/main/scala/firrtl/transforms/SimplifyMems.scala b/src/main/scala/firrtl/transforms/SimplifyMems.scala
index 92e19f7e..90c26efc 100644
--- a/src/main/scala/firrtl/transforms/SimplifyMems.scala
+++ b/src/main/scala/firrtl/transforms/SimplifyMems.scala
@@ -10,6 +10,7 @@ import firrtl.options.Dependency
 import firrtl.passes._
 import firrtl.passes.memlib._
 import firrtl.stage.Forms
+import firrtl.renamemap.MutableRenameMap
 import scala.collection.mutable
 
 import AnalysisUtils._
@@ -29,7 +30,12 @@ class SimplifyMems extends Transform with DependencyAPIMigration {
     case _          => false
   }
 
-  def onModule(c: Circuit, renames: RenameMap)(m: DefModule): DefModule = {
+  @deprecated("Use version that accepts renamemap.MutableRenameMap", "FIRRTL 1.5")
+  def onModule(c: Circuit, renames: RenameMap)(m: DefModule): DefModule =
+    // Cast is safe because RenameMap is sealed trait and MutableRenameMap is only subclass
+    onModule(c, renames.asInstanceOf[MutableRenameMap])(m)
+
+  def onModule(c: Circuit, renames: MutableRenameMap)(m: DefModule): DefModule = {
     val moduleNS = Namespace(m)
     val connects = getConnects(m)
     val memAdapters = new mutable.LinkedHashMap[String, DefWire]
@@ -86,7 +92,7 @@ class SimplifyMems extends Transform with DependencyAPIMigration {
 
   override def execute(state: CircuitState): CircuitState = {
     val c = state.circuit
-    val renames = RenameMap()
+    val renames = MutableRenameMap()
     state.copy(circuit = c.map(onModule(c, renames)), renames = Some(renames))
   }
 }