refactor(cam): rename read-noise path to read-pass-through and reorganize test module structure

- Rename `read_noise` scenarios and noise_mode to `read_pass_through` across
  run_cam_correctness.py, test_run_cam_correctness.py, and Makefiles
- Update RTL comment in match_engine_pipeline.sv to reflect pass-through behavior
- Move unit-level cocotb tests from `tests.test_*` flat namespace to
  `tests.modules.*` and `tests.top.*` subdirectory layout, matching actual
  Makefile paths (hw/sim/tests/modules/..., hw/sim/tests/top/...)
- Remove redundant dual-noise subtarget from read_noise/Makefile
- Update help text and docs to reflect read-path pass-through semantics
- Add .codegraph to .gitignore

.gitignore

@@ -218,6 +218,7 @@ outputs/
 .sisyphus
 .claude/settings.local.json
 openspec/changes/
+.codegraph/
 .logs/
 docs/superpowers
 

.justfile

@@ -79,7 +79,7 @@ cam-test-retrieval-no-noise:
     just remote "make -C hw/sim clean && make -C hw/sim test-benchmark-retrieval TOPK_K=5 WRITE_NOISE_EN=0"
 
 # Run CAM retrieval benchmark with write noise enabled (Phase 2: read noise removed)
-cam-test-retrieval-read-noise:
+cam-test-retrieval-write-noise:
     just remote "make -C hw/sim clean && make -C hw/sim test-benchmark-retrieval TOPK_K=5 WRITE_NOISE_EN=1 WRITE_NOISE_RATE_NUM=1 WRITE_NOISE_RATE_DEN=100"
 
 # Prepare CIFAR10 hash artifact for CAM retrieval smoke benchmark
@@ -95,5 +95,5 @@ cam-test-retrieval-artifact DATASET_PATH NUM_ROWS="4096":
     just remote "make -C hw/sim clean && make -C hw/sim test-benchmark-retrieval TOPK_K=5 NUM_ROWS={{NUM_ROWS}} WRITE_NOISE_EN=0 CAM_RETRIEVAL_DATASET={{ DATASET_PATH }}"
 
 # Run CAM retrieval benchmark on a prepared artifact with write noise enabled (Phase 2: read noise removed)
-cam-test-retrieval-artifact-read-noise DATASET_PATH NUM_ROWS="4096":
+cam-test-retrieval-artifact-write-noise DATASET_PATH NUM_ROWS="4096":
     just remote "make -C hw/sim clean && make -C hw/sim test-benchmark-retrieval TOPK_K=5 NUM_ROWS={{NUM_ROWS}} WRITE_NOISE_EN=1 WRITE_NOISE_RATE_NUM=1 WRITE_NOISE_RATE_DEN=100 CAM_RETRIEVAL_DATASET={{ DATASET_PATH }}"

docs/experiments.md

@@ -157,7 +157,7 @@
   - `HASH_BITS`
   - `LANES`
   - `WRITE_NOISE_*`
-  - `READ_NOISE_*`
+  - 读取路径 pass-through 验证（读阶段不再注入噪声）
 - `.justfile` 已封装远程 Verilator/Cocotb 执行命令。
 
 ### 还需补齐

hw/rtl/core/match_engine_pipeline.sv

@@ -375,8 +375,8 @@ module match_engine_pipeline (
 
                 S_ISSUE_READ: begin
                     // Emit rd_valid_o for exactly one cycle (combinational), then
-                    // transition to S_WAIT_READ_RESP. This ensures the read-noise
+                    // transition to S_WAIT_READ_RESP. This keeps one logical read
-                    // PRNG in cam_read_noise only advances once per batch issue.
+                    // request per batch issue before waiting for the response path.
                     state_q <= S_WAIT_READ_RESP;
                 end
 

hw/sim/Makefile

@@ -7,11 +7,11 @@ TOP_CONFIGS := no_noise write_noise read_noise
 help:
 	@echo "Available hw/sim targets:"
 	@echo "  make test-model"
-	@echo "  make test-top             # 默认运行所有顶层噪声配置"
+	@echo "  make test-top             # 默认运行所有顶层配置"
-	@echo "  make test-top-all         # 运行所有顶层噪声配置"
+	@echo "  make test-top-all         # 运行所有顶层配置"
 	@echo "  make test-top-no_noise    # 无噪声集成测试"
 	@echo "  make test-top-write_noise # 写入噪声集成测试"
-	@echo "  make test-top-read_noise  # 读取噪声集成测试"
+	@echo "  make test-top-read_noise  # 读取路径 pass-through 集成测试"
 	@echo "  make test-module MODULE=cam_core_banked"
 	@echo "  make test-modules"
 	@echo "  make test-perf"

hw/sim/tests/modules/cam_read_noise/test_cam_read_noise.py

@@ -52,7 +52,7 @@ async def read_noise_disabled_forwards_hashes_after_one_stage(dut):
 
 @cocotb.test()
 async def read_noise_enabled_still_forwards_hashes_unmodified(dut):
-    """With READ_NOISE_EN=1, the pass-through still forwards hashes unmodified."""
+    """The read path pass-through forwards hashes unmodified."""
     cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
     await reset_read_noise(dut)
 

hw/sim/tests/top/read_noise/Makefile

@@ -6,17 +6,10 @@ TOPLEVEL := cam_top
 COCOTB_TEST_MODULES := tests.top.read_noise.test_read_noise
 VERILOG_SOURCES := $(RTL_CAM_TOP)
 
-# 读取噪声开启（Phase 2 后为 pass-through），写入噪声默认关闭
+# 读取路径 pass-through 配置，写入噪声默认关闭
 WRITE_NOISE_EN := 0
 
 include $(SIM_ROOT)/mk/cocotb-common.mk
 
-# ── 写入+读取双重噪声子目标 ─────────────────────────────────────────
-.PHONY: test-with-write-noise
-
-test-with-write-noise:
-	$(MAKE) -B -f Makefile results.xml WRITE_NOISE_EN=1 \
-	  COCOTB_TEST_FILTER=read_noise_model_match
-
 clean::
 	rm -rf sim_build

scripts/run_cam_correctness.py

@@ -80,18 +80,18 @@ default_scenarios: list[Scenario] = [
         expected="bit_flip_injected",
     ),
     Scenario(
-        name="cam_top_read_noise",
+        name="cam_top_read_path",
         kind="cocotb",
         module="tests.top.read_noise.test_read_noise",
         testcase=None,
         params={},
-        noise_mode="read_noise",
+        noise_mode="read_pass_through",
-        expected="read_perturbed",
+        expected="pure_matching",
     ),
     Scenario(
         name="cam_core_banked",
         kind="cocotb",
-        module="tests.test_cam_core_banked",
+        module="tests.modules.cam_core_banked.test_cam_core_banked",
         testcase=None,
         params={},
         noise_mode="none",
@@ -100,7 +100,7 @@ default_scenarios: list[Scenario] = [
     Scenario(
         name="match_engine_pipeline",
         kind="cocotb",
-        module="tests.test_match_engine_pipeline",
+        module="tests.modules.match_engine_pipeline.test_match_engine_pipeline",
         testcase=None,
         params={},
         noise_mode="none",
@@ -109,20 +109,20 @@ default_scenarios: list[Scenario] = [
     Scenario(
         name="cam_write_noise",
         kind="cocotb",
-        module="tests.test_cam_write_noise",
+        module="tests.modules.cam_write_noise.test_cam_write_noise",
         testcase=None,
         params={},
         noise_mode="write_noise",
         expected="bit_flip_injected",
     ),
     Scenario(
-        name="cam_read_noise",
+        name="cam_read_path",
         kind="cocotb",
-        module="tests.test_cam_read_noise",
+        module="tests.modules.cam_read_noise.test_cam_read_noise",
         testcase=None,
         params={},
-        noise_mode="read_noise",
+        noise_mode="read_pass_through",
-        expected="read_perturbed",
+        expected="pass_through",
     ),
     Scenario(
         name="ref_model_noise",
@@ -145,11 +145,11 @@ default_scenarios: list[Scenario] = [
 _MAKE_DIR: dict[str, str] = {
     "cam_top_basic": "top/no_noise",
     "cam_top_write_noise": "top/write_noise",
-    "cam_top_read_noise": "top/read_noise",
+    "cam_top_read_path": "top/read_noise",
     "cam_core_banked": "modules/cam_core_banked",
     "match_engine_pipeline": "modules/match_engine_pipeline",
     "cam_write_noise": "modules/cam_write_noise",
-    "cam_read_noise": "modules/cam_read_noise",
+    "cam_read_path": "modules/cam_read_noise",
 }
 
 
@@ -493,8 +493,8 @@ def write_summary_md(
     lines.append("")
     lines.append(
         "- **cam_top**: 通过 `cam_top_basic`、`cam_top_write_noise`、"
-        "`cam_top_read_noise` 三个场景覆盖顶层 CAM 模块的基本功能、"
+        "`cam_top_read_path` 三个场景覆盖顶层 CAM 模块的基本功能、"
-        "写入噪声注入和读取噪声注入路径"
+        "写入噪声注入和读取路径 pass-through"
     )
     lines.append(
         "- **cam_core_banked**: 通过 `cam_core_banked` 场景覆盖"
@@ -513,8 +513,8 @@ def write_summary_md(
         "写入噪声注入路径"
     )
     lines.append(
-        "- **cam_read_noise**: 通过 `cam_read_noise` 场景独立覆盖"
+        "- **cam_read_noise**: 通过 `cam_read_path` 场景独立覆盖"
-        "读取噪声注入路径"
+        "读取路径 pass-through"
     )
     lines.append("")
     lines.append("## 论文可引用结论草稿")

tests/test_run_cam_correctness.py

@@ -92,11 +92,11 @@ class TestRunnerContract:
         assert names == [
             "cam_top_basic",
             "cam_top_write_noise",
-            "cam_top_read_noise",
+            "cam_top_read_path",
             "cam_core_banked",
             "match_engine_pipeline",
             "cam_write_noise",
-            "cam_read_noise",
+            "cam_read_path",
             "ref_model_noise",
         ]
 
@@ -106,7 +106,7 @@ class TestRunnerContract:
         s = sc["cam_top_basic"]
         assert s.name == "cam_top_basic"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_cam_basic"
+        assert s.module == "tests.top.no_noise.test_no_noise"
         assert s.testcase is None
         assert s.params == {}
         assert s.noise_mode == "none"
@@ -116,37 +116,27 @@ class TestRunnerContract:
         s = sc["cam_top_write_noise"]
         assert s.name == "cam_top_write_noise"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_cam_basic"
+        assert s.module == "tests.top.write_noise.test_write_noise"
         assert s.testcase is None
-        assert s.params == {
+        assert s.params == {}
-            "WRITE_NOISE_EN": "1",
-            "WRITE_NOISE_RATE_NUM": "1",
-            "WRITE_NOISE_RATE_DEN": "100",
-            "READ_NOISE_EN": "0",
-        }
         assert s.noise_mode == "write_noise"
         assert s.expected == "bit_flip_injected"
 
-        # --- cam_top_read_noise ---
+        # --- cam_top_read_path ---
-        s = sc["cam_top_read_noise"]
+        s = sc["cam_top_read_path"]
-        assert s.name == "cam_top_read_noise"
+        assert s.name == "cam_top_read_path"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_cam_basic"
+        assert s.module == "tests.top.read_noise.test_read_noise"
         assert s.testcase is None
-        assert s.params == {
+        assert s.params == {}
-            "WRITE_NOISE_EN": "0",
+        assert s.noise_mode == "read_pass_through"
-            "READ_NOISE_EN": "1",
+        assert s.expected == "pure_matching"
-            "READ_NOISE_RATE_NUM": "1",
-            "READ_NOISE_RATE_DEN": "100",
-        }
-        assert s.noise_mode == "read_noise"
-        assert s.expected == "read_perturbed"
 
         # --- cam_core_banked ---
         s = sc["cam_core_banked"]
         assert s.name == "cam_core_banked"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_cam_core_banked"
+        assert s.module == "tests.modules.cam_core_banked.test_cam_core_banked"
         assert s.testcase is None
         assert s.params == {}
         assert s.noise_mode == "none"
@@ -156,7 +146,7 @@ class TestRunnerContract:
         s = sc["match_engine_pipeline"]
         assert s.name == "match_engine_pipeline"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_match_engine_pipeline"
+        assert s.module == "tests.modules.match_engine_pipeline.test_match_engine_pipeline"
         assert s.testcase is None
         assert s.params == {}
         assert s.noise_mode == "none"
@@ -166,21 +156,21 @@ class TestRunnerContract:
         s = sc["cam_write_noise"]
         assert s.name == "cam_write_noise"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_cam_write_noise"
+        assert s.module == "tests.modules.cam_write_noise.test_cam_write_noise"
         assert s.testcase is None
         assert s.params == {}
         assert s.noise_mode == "write_noise"
         assert s.expected == "bit_flip_injected"
 
-        # --- cam_read_noise ---
+        # --- cam_read_path ---
-        s = sc["cam_read_noise"]
+        s = sc["cam_read_path"]
-        assert s.name == "cam_read_noise"
+        assert s.name == "cam_read_path"
         assert s.kind == "cocotb"
-        assert s.module == "tests.test_cam_read_noise"
+        assert s.module == "tests.modules.cam_read_noise.test_cam_read_noise"
         assert s.testcase is None
         assert s.params == {}
-        assert s.noise_mode == "read_noise"
+        assert s.noise_mode == "read_pass_through"
-        assert s.expected == "read_perturbed"
+        assert s.expected == "pass_through"
 
         # --- ref_model_noise ---
         s = sc["ref_model_noise"]
@@ -207,7 +197,7 @@ class TestRunnerContract:
         assert cmd == [
             "make",
             "-C",
-            "hw/sim",
+            "hw/sim/tests/top/write_noise",
             "NUM_ROWS=512",
             "HASH_BITS=512",
             "LANES=8",
@@ -217,32 +207,35 @@ class TestRunnerContract:
             "WRITE_NOISE_RATE_NUM=1",
         ]
 
-    def test_build_cocotb_command_includes_toplevel_for_unit_scenarios(self):
+    def test_build_cocotb_command_uses_correct_make_directory(self):
-        """Unit-level cocotb scenarios get explicit TOPLEVEL override matching scenario name."""
+        """Unit-level cocotb scenarios build in hw/sim/tests/modules/...,
+        top-level scenarios in hw/sim/tests/top/..."""
         runner = load_runner()
         sc = {s.name: s for s in runner.default_scenarios}
 
-        # Unit scenarios should get TOPLEVEL override matching their scenario name
+        # Unit scenarios — make -C hw/sim/tests/modules/<subpath>
-        unit_names = [
+        for name, subpath in [
-            "cam_core_banked",
+            ("cam_core_banked", "modules/cam_core_banked"),
-            "match_engine_pipeline",
+            ("match_engine_pipeline", "modules/match_engine_pipeline"),
-            "cam_write_noise",
+            ("cam_write_noise", "modules/cam_write_noise"),
-            "cam_read_noise",
+            ("cam_read_path", "modules/cam_read_noise"),
-        ]
+        ]:
-        for name in unit_names:
             cmd = runner.build_scenario_command(sc[name])
-            toplevel_kvp = f"TOPLEVEL={name}"
+            c_flag = cmd[cmd.index("-C") + 1]
-            assert toplevel_kvp in cmd, (
+            assert c_flag == f"hw/sim/tests/{subpath}", (
-                f"Expected {toplevel_kvp!r} in command for {name!r}, got {cmd}"
+                f"Expected -C hw/sim/tests/{subpath} for {name!r}, got -C {c_flag}"
             )
 
-        # cam_top_* scenarios should NOT get explicit TOPLEVEL (use Makefile default)
+        # Top-level scenarios — make -C hw/sim/tests/top/<subpath>
-        top_names = ["cam_top_basic", "cam_top_write_noise", "cam_top_read_noise"]
+        for name, subpath in [
-        for name in top_names:
+            ("cam_top_basic", "top/no_noise"),
+            ("cam_top_write_noise", "top/write_noise"),
+            ("cam_top_read_path", "top/read_noise"),
+        ]:
             cmd = runner.build_scenario_command(sc[name])
-            toplevel_flags = [arg for arg in cmd if arg.startswith("TOPLEVEL=")]
+            c_flag = cmd[cmd.index("-C") + 1]
-            assert len(toplevel_flags) == 0, (
+            assert c_flag == f"hw/sim/tests/{subpath}", (
-                f"Unexpected TOPLEVEL override in command for {name!r}: {cmd}"
+                f"Expected -C hw/sim/tests/{subpath} for {name!r}, got -C {c_flag}"
             )
 
     def test_build_pytest_command_uses_reference_model_test(self):
@@ -261,7 +254,7 @@ class TestRunnerContract:
             "uv",
             "run",
             "pytest",
-            "hw/sim/tests/test_ref_model_noise.py",
+            "hw/sim/tests/model/test_ref_model_noise.py",
             "-q",
         ]