[opt] Use a structural fingerprint to break ties in ReassociationPass

xls/passes/BUILD

@@ -2207,6 +2207,7 @@ xls_pass(
         ":lazy_dag_cache",
         ":lazy_node_info",
         ":lazy_ternary_query_engine",
+        ":node_fingerprint_analysis",
         ":optimization_pass",
         ":pass_base",
         ":query_engine",
@@ -3558,6 +3559,7 @@ cc_test(
         "//xls/common/fuzzing:fuzztest",
         "//xls/common/status:matchers",
         "//xls/common/status:status_macros",
+        "//xls/dev_tools:remove_identifiers",
         "//xls/fuzzer/ir_fuzzer:ir_fuzz_domain",
         "//xls/fuzzer/ir_fuzzer:ir_fuzz_test_library",
         "//xls/ir",
@@ -4806,6 +4808,24 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "node_fingerprint_analysis",
+    srcs = ["node_fingerprint_analysis.cc"],
+    hdrs = ["node_fingerprint_analysis.h"],
+    deps = [
+        ":lazy_dag_cache",
+        ":lazy_node_data",
+        "//xls/ir",
+        "//xls/ir:op",
+        "//xls/ir:type",
+        "@com_google_absl//absl/hash",
+        "@com_google_absl//absl/log:check",
+        "@com_google_absl//absl/status",
+        "@com_google_absl//absl/status:statusor",
+        "@com_google_absl//absl/types:span",
+    ],
+)
+
 cc_test(
     name = "visibility_expr_builder_test",
     srcs = ["visibility_expr_builder_test.cc"],
@@ -4872,3 +4892,20 @@ cc_test(
         "@googletest//:gtest",
     ],
 )
+
+cc_test(
+    name = "node_fingerprint_analysis_test",
+    srcs = ["node_fingerprint_analysis_test.cc"],
+    deps = [
+        ":node_fingerprint_analysis",
+        "//xls/common:xls_gunit_main",
+        "//xls/common/status:matchers",
+        "//xls/ir",
+        "//xls/ir:bits",
+        "//xls/ir:function_builder",
+        "//xls/ir:ir_test_base",
+        "//xls/ir:value",
+        "@com_google_absl//absl/status:statusor",
+        "@googletest//:gtest",
+    ],
+)

xls/passes/node_fingerprint_analysis.cc

@@ -0,0 +1,66 @@
+// Copyright 2026 The XLS Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "xls/passes/node_fingerprint_analysis.h"
+
+#include <cstdint>
+#include <vector>
+
+#include "absl/hash/hash.h"
+#include "absl/log/check.h"
+#include "absl/status/statusor.h"
+#include "absl/types/span.h"
+#include "xls/ir/function_base.h"
+#include "xls/ir/node.h"
+#include "xls/ir/nodes.h"
+#include "xls/ir/op.h"
+#include "xls/ir/type.h"
+
+namespace xls {
+
+uint64_t NodeFingerprintAnalysis::ComputeInfo(
+    Node* node, absl::Span<const uint64_t* const> operand_fingerprints) const {
+  std::vector<uint64_t> operands;
+  operands.reserve(operand_fingerprints.size());
+  for (const uint64_t* f : operand_fingerprints) {
+    operands.push_back(*f);
+  }
+
+  Op op = node->op();
+  Type* type = node->GetType();
+
+  if (node->Is<Literal>()) {
+    return absl::HashOf(op, type, operands, node->As<Literal>()->value());
+  }
+  if (node->Is<BitSlice>()) {
+    return absl::HashOf(op, type, operands, node->As<BitSlice>()->start());
+  }
+  if (node->Is<TupleIndex>()) {
+    return absl::HashOf(op, type, operands, node->As<TupleIndex>()->index());
+  }
+  if (node->Is<ChannelNode>()) {
+    return absl::HashOf(op, type, operands,
+                        node->As<ChannelNode>()->channel_name());
+  }
+  if (node->Is<Param>()) {
+    absl::StatusOr<int64_t> param_index =
+        node->function_base()->GetParamIndex(node->As<Param>());
+    CHECK_OK(param_index);
+    return absl::HashOf(op, type, operands, *param_index);
+  }
+
+  return absl::HashOf(op, type, operands);
+}
+
+}  // namespace xls

xls/passes/node_fingerprint_analysis.h

@@ -0,0 +1,53 @@
+// Copyright 2026 The XLS Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef XLS_PASSES_NODE_FINGERPRINT_ANALYSIS_H_
+#define XLS_PASSES_NODE_FINGERPRINT_ANALYSIS_H_
+
+#include <cstdint>
+
+#include "absl/status/status.h"
+#include "absl/types/span.h"
+#include "xls/ir/node.h"
+#include "xls/passes/lazy_dag_cache.h"
+#include "xls/passes/lazy_node_data.h"
+
+namespace xls {
+
+// An analysis that computes a structural fingerprint for each node.
+// This fingerprint is intended to be stable across optimization passes that
+// rename nodes or change their IDs, as long as the underlying expression tree
+// remains identical.
+class NodeFingerprintAnalysis : public LazyNodeData<uint64_t> {
+ public:
+  NodeFingerprintAnalysis()
+      : LazyNodeData<uint64_t>(DagCacheInvalidateDirection::kInvalidatesUsers) {
+  }
+
+  uint64_t GetFingerprint(Node* node) const { return *GetInfo(node); }
+
+ protected:
+  uint64_t ComputeInfo(
+      Node* node,
+      absl::Span<const uint64_t* const> operand_fingerprints) const override;
+
+  absl::Status MergeWithGiven(uint64_t& info,
+                              const uint64_t& given) const override {
+    return absl::InternalError("Cannot merge fingerprints");
+  }
+};
+
+}  // namespace xls
+
+#endif  // XLS_PASSES_NODE_FINGERPRINT_ANALYSIS_H_

xls/passes/node_fingerprint_analysis_test.cc

@@ -0,0 +1,111 @@
+// Copyright 2026 The XLS Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "xls/passes/node_fingerprint_analysis.h"
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include "gtest/gtest.h"
+#include "absl/status/statusor.h"
+#include "xls/common/status/matchers.h"
+#include "xls/ir/bits.h"
+#include "xls/ir/function_builder.h"
+#include "xls/ir/ir_test_base.h"
+#include "xls/ir/package.h"
+#include "xls/ir/value.h"
+
+namespace xls {
+namespace {
+
+class NodeFingerprintAnalysisTest : public IrTestBase {};
+
+TEST_F(NodeFingerprintAnalysisTest, SimpleFingerprints) {
+  auto p = CreatePackage();
+  FunctionBuilder fb(TestName(), p.get());
+  auto x = fb.Param("x", p->GetBitsType(32));
+  auto y = fb.Param("y", p->GetBitsType(32));
+  auto add1 = fb.Add(x, y);
+  auto add2 = fb.Add(x, y);
+  auto sub = fb.Subtract(x, y);
+
+  XLS_ASSERT_OK_AND_ASSIGN(auto f, fb.Build());
+
+  NodeFingerprintAnalysis analysis;
+  XLS_ASSERT_OK(analysis.Attach(f).status());
+
+  uint64_t fp_x = analysis.GetFingerprint(x.node());
+  uint64_t fp_y = analysis.GetFingerprint(y.node());
+  uint64_t fp_add1 = analysis.GetFingerprint(add1.node());
+  uint64_t fp_add2 = analysis.GetFingerprint(add2.node());
+  uint64_t fp_sub = analysis.GetFingerprint(sub.node());
+
+  EXPECT_NE(fp_x, fp_y);
+  EXPECT_EQ(fp_add1, fp_add2);
+  EXPECT_NE(fp_add1, fp_sub);
+}
+
+TEST_F(NodeFingerprintAnalysisTest, IdenticalTreesDifferentNames) {
+  auto p = CreatePackage();
+
+  auto build_func = [&](std::string name) -> absl::StatusOr<Function*> {
+    FunctionBuilder fb(name, p.get());
+    auto x = fb.Param("x", p->GetBitsType(32));
+    fb.Add(x, fb.Literal(Value(UBits(1, 32))));
+    return fb.Build();
+  };
+
+  XLS_ASSERT_OK_AND_ASSIGN(auto f1, build_func("f1"));
+  XLS_ASSERT_OK_AND_ASSIGN(auto f2, build_func("f2"));
+
+  NodeFingerprintAnalysis analysis;
+  XLS_ASSERT_OK(analysis.Attach(f1).status());
+  uint64_t fp1 = analysis.GetFingerprint(f1->return_value());
+
+  XLS_ASSERT_OK(analysis.Attach(f2).status());
+  uint64_t fp2 = analysis.GetFingerprint(f2->return_value());
+
+  EXPECT_EQ(fp1, fp2);
+}
+
+TEST_F(NodeFingerprintAnalysisTest, ParametersTrackedByPosition) {
+  auto p = CreatePackage();
+
+  FunctionBuilder fb1("f1", p.get());
+  auto x1 = fb1.Param("x", p->GetBitsType(32));
+  auto y1 = fb1.Param("y", p->GetBitsType(32));
+  fb1.Add(x1, y1);
+  XLS_ASSERT_OK_AND_ASSIGN(auto f1, fb1.Build());
+
+  FunctionBuilder fb2("f2", p.get());
+  auto y2 = fb2.Param("y", p->GetBitsType(32));
+  auto x2 = fb2.Param("x", p->GetBitsType(32));
+  fb2.Add(y2, x2);
+  XLS_ASSERT_OK_AND_ASSIGN(auto f2, fb2.Build());
+
+  NodeFingerprintAnalysis analysis;
+  XLS_ASSERT_OK(analysis.Attach(f1).status());
+  uint64_t fp1 = analysis.GetFingerprint(f1->return_value());
+
+  XLS_ASSERT_OK(analysis.Attach(f2).status());
+  uint64_t fp2 = analysis.GetFingerprint(f2->return_value());
+
+  // These should be equal because (Param0 + Param1) is structurally same in
+  // both functions.
+  EXPECT_EQ(fp1, fp2);
+}
+
+}  // namespace
+}  // namespace xls