feat: enhance build variant ID generation and regression environment setup

- Added timestamp normalization to  function in , allowing for optional timestamp input.
- Updated command-line interface to accept a timestamp argument for generating deterministic build variant IDs.
- Modified  in  to include a build timestamp in the environment variables.
- Introduced a new test suite in  to validate the pin-map generator, including tests for duplicate pads and invalid entries.
- Added a test for ensuring the regression runner uses a consistent build timestamp.
- Created a new SystemVerilog testbench for the APB4 interface bridge to verify correct signal crossing.

tests/rtl/apb4_if_bridge_tb.sv

@@ -0,0 +1,44 @@
+`timescale 1ns / 1ps
+
+module apb4_if_bridge_tb;
+  logic pclk = 1'b0;
+  logic presetn = 1'b0;
+  apb4_pure_if apb_pure ();
+  apb4_if apb_timed (
+      .pclk   (pclk),
+      .presetn(presetn)
+  );
+
+  apb4_if_bridge u_apb4_if_bridge (
+      .apb_pure(apb_pure),
+      .timed   (apb_timed)
+  );
+
+  initial begin
+    apb_pure.paddr    = 32'h1234_5678;
+    apb_pure.pprot    = 3'b101;
+    apb_pure.psel     = 1'b1;
+    apb_pure.penable  = 1'b1;
+    apb_pure.pwrite   = 1'b1;
+    apb_pure.pwdata   = 32'hCAFE_BABE;
+    apb_pure.pstrb    = 4'b1101;
+    apb_timed.pready  = 1'b1;
+    apb_timed.prdata  = 32'hDEAD_BEEF;
+    apb_timed.pslverr = 1'b0;
+    #1;
+
+    if ({apb_timed.paddr, apb_timed.pprot, apb_timed.psel, apb_timed.penable,
+         apb_timed.pwrite, apb_timed.pwdata, apb_timed.pstrb} !==
+        {apb_pure.paddr, apb_pure.pprot, apb_pure.psel, apb_pure.penable,
+         apb_pure.pwrite, apb_pure.pwdata, apb_pure.pstrb}) begin
+      $fatal(1, "APB request fields did not cross the bridge");
+    end
+    if ({apb_pure.pready, apb_pure.prdata, apb_pure.pslverr} !==
+        {apb_timed.pready, apb_timed.prdata, apb_timed.pslverr}) begin
+      $fatal(1, "APB response fields did not cross the bridge");
+    end
+
+    $display("apb4 interface bridge test passed");
+    $finish;
+  end
+endmodule

tests/test_pin_map.py

@@ -0,0 +1,149 @@
+"""Tests for the canonical Mini SoC pin-map generator."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+GENERATOR = ROOT / "rtl/mini/pin_map/generate_pin_map.py"
+PIN_MAP = ROOT / "rtl/mini/pin_map/pin_map.json"
+FPGA_TOP = ROOT / "fpga/mini/retrosoc_top.sv"
+FPGA_XDC = ROOT / "fpga/mini/starrysky_v2.xdc"
+
+
+def generate(output_dir: Path) -> None:
+    subprocess.run(
+        [
+            sys.executable,
+            str(GENERATOR),
+            "--map",
+            str(PIN_MAP),
+            "--output-dir",
+            str(output_dir),
+        ],
+        check=True,
+    )
+
+
+def validate(map_path: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(GENERATOR), "--map", str(map_path), "--check"],
+        text=True,
+        capture_output=True,
+    )
+
+
+def test_pin_map_generates_asic_and_platform_bindings(tmp_path: Path) -> None:
+    generate(tmp_path)
+
+    ports = (tmp_path / "rtl/retrosoc_asic_ports.svh").read_text(encoding="utf-8")
+    pads = (tmp_path / "rtl/retrosoc_asic_pad_bindings.svh").read_text(encoding="utf-8")
+    fpga = (tmp_path / "rtl/retrosoc_asic_fpga_mini_bindings.svh").read_text(
+        encoding="utf-8"
+    )
+    testbench = (tmp_path / "rtl/retrosoc_asic_tb_bindings.svh").read_text(
+        encoding="utf-8"
+    )
+
+    assert "inout extclk_i_pad," in ports
+    assert "input xi_i_pad," in ports
+    assert "inout sdram_dq15_io_pad" in ports
+    assert "u_gpio_31_io_pad" in pads
+    assert "u_sdram_dq15_io_pad" in pads
+    assert ".gpio_30_io_pad(gpio_io30)" in fpga
+    assert ".gpio_15_io_pad()" in fpga
+    assert ".gpio_24_io_pad(s_psram_dat1)" in testbench
+    assert testbench.count(".gpio_24_io_pad(") == 1
+
+
+def test_pin_map_rejects_duplicate_pads(tmp_path: Path) -> None:
+    document = json.loads(PIN_MAP.read_text(encoding="utf-8"))
+    document["pads"][0]["ports"].append(
+        {"name": "extclk_i_pad", "signal": "s_duplicate_clock"}
+    )
+    invalid_map = tmp_path / "duplicate.json"
+    invalid_map.write_text(json.dumps(document), encoding="utf-8")
+
+    result = validate(invalid_map)
+
+    assert result.returncode != 0
+    assert "pad names must be unique" in result.stderr
+
+
+def test_pin_map_rejects_non_object_port_entry(tmp_path: Path) -> None:
+    document = json.loads(PIN_MAP.read_text(encoding="utf-8"))
+    document["pads"][0]["ports"].append("extclk_i_pad")
+    invalid_map = tmp_path / "invalid-port.json"
+    invalid_map.write_text(json.dumps(document), encoding="utf-8")
+
+    result = validate(invalid_map)
+
+    assert result.returncode != 0
+    assert "ports entries must be objects" in result.stderr
+
+
+def test_pin_map_rejects_unknown_profile_pad(tmp_path: Path) -> None:
+    document = json.loads(PIN_MAP.read_text(encoding="utf-8"))
+    document["profiles"]["tb"]["bindings"]["unknown_pad"] = "s_unknown"
+    invalid_map = tmp_path / "unknown.json"
+    invalid_map.write_text(json.dumps(document), encoding="utf-8")
+
+    result = validate(invalid_map)
+
+    assert result.returncode != 0
+    assert "unknown pad" in result.stderr
+
+
+def test_fpga_constraints_reference_declared_top_ports() -> None:
+    top_ports = set(re.findall(r"^\s*(?:input|output|inout)\s+([A-Za-z_][A-Za-z0-9_]*)", FPGA_TOP.read_text(encoding="utf-8"), re.MULTILINE))
+    xdc_ports = set(re.findall(r"\[get_ports\s+([A-Za-z_][A-Za-z0-9_]*)\]", FPGA_XDC.read_text(encoding="utf-8")))
+
+    assert xdc_ports
+    assert xdc_ports <= top_ports
+
+
+def test_apb4_interface_bridge(tmp_path: Path) -> None:
+    iverilog = shutil.which("iverilog")
+    sv2v = shutil.which("sv2v")
+    vvp = shutil.which("vvp")
+    if iverilog is None or sv2v is None or vvp is None:
+        return
+    source_list = tmp_path / "apb4_if_bridge.fl"
+    source_list.write_text(
+        "\n".join(
+            [
+                str(ROOT / "rtl/managed/clusterip/common/rtl/interface/apb4_if.sv"),
+                str(ROOT / "rtl/managed/clusterip/common/rtl/interface/apb4_pure_if.sv"),
+                str(ROOT / "rtl/mini/top/apb4_if_bridge.sv"),
+                str(ROOT / "tests/rtl/apb4_if_bridge_tb.sv"),
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    converted = tmp_path / "apb4_if_bridge_tb.v"
+    subprocess.run(
+        [
+            sys.executable,
+            str(ROOT / "rtl/mini/script/convt_sv2v.py"),
+            "-f",
+            str(source_list),
+            "--output",
+            str(converted),
+        ],
+        check=True,
+    )
+    simulation = tmp_path / "apb4_if_bridge_tb"
+    subprocess.run(
+        [iverilog, "-g2012", "-s", "apb4_if_bridge_tb", "-o", str(simulation), str(converted)],
+        check=True,
+    )
+    result = subprocess.run([vvp, str(simulation)], text=True, capture_output=True, check=True)
+
+    assert "apb4 interface bridge test passed" in result.stdout

tests/test_script_tools.py

@@ -25,6 +25,7 @@ from scripts.analyze_warnings import normalize  # noqa: E402
 from scripts.check_c_warnings import self_owned_warnings  # noqa: E402
 from scripts.dependency_lock import LockError, load_lock  # noqa: E402
 from scripts.install_toolchain import safe_extract  # noqa: E402
+from scripts.regress import regression_environment  # noqa: E402
 from scripts.setup_helpers import download_file, ensure_git_repo  # noqa: E402
 
 
@@ -190,7 +191,7 @@ def test_make_dry_run_and_validation_do_not_write_filelists() -> None:
     assert "Invalid SIMU='UNKNOWN'" in invalid.stderr
 
 
-def test_dependency_lock_and_config_key_are_deterministic(tmp_path: Path) -> None:
+def test_dependency_lock_and_config_key_include_a_fixed_timestamp(tmp_path: Path) -> None:
     lock = load_lock(ROOT / "config/dependencies.lock.json")
     assert lock["schema_version"] == 1
     assert len(lock["sources"]["mpw"]["revision"]) == 40
@@ -202,6 +203,8 @@ def test_dependency_lock_and_config_key_are_deterministic(tmp_path: Path) -> Non
         str(ROOT / "config/dependencies.lock.json"),
         "--profile",
         "unit",
+        "--timestamp",
+        "2026-07-21-10-39",
         "--value",
         "CORE=HAZARD3",
         "--value",
@@ -210,7 +213,15 @@ def test_dependency_lock_and_config_key_are_deterministic(tmp_path: Path) -> Non
     first = run(*command).stdout.strip()
     second = run(*command).stdout.strip()
     assert first == second
-    assert first.startswith("unit-")
+    assert re.fullmatch(r"unit-2026-07-21-10-39-[0-9a-f]{12}", first)
+
+    invalid_timestamp = subprocess.run(
+        [*command, "--timestamp", "2026-07-21-10-99"],
+        text=True,
+        capture_output=True,
+    )
+    assert invalid_timestamp.returncode != 0
+    assert "timestamp must use %Y-%m-%d-%H-%M" in invalid_timestamp.stderr
 
     broken = tmp_path / "broken.json"
     broken.write_text('{"schema_version": 1}\n', encoding="utf-8")
@@ -222,6 +233,17 @@ def test_dependency_lock_and_config_key_are_deterministic(tmp_path: Path) -> Non
         raise AssertionError("invalid dependency lock was accepted")
 
 
+def test_regression_runner_uses_one_build_timestamp(monkeypatch) -> None:
+    monkeypatch.setenv("BUILD_TIMESTAMP", "2026-07-21-10-39")
+    assert regression_environment()["BUILD_TIMESTAMP"] == "2026-07-21-10-39"
+
+    monkeypatch.delenv("BUILD_TIMESTAMP")
+    assert re.fullmatch(
+        r"[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{2}",
+        regression_environment()["BUILD_TIMESTAMP"],
+    )
+
+
 def test_run_flow_writes_structured_result(tmp_path: Path) -> None:
     log = tmp_path / "flow.log"
     result = tmp_path / "result.json"