From e44700d3216660995601034a01cf7b2fd059009c Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Wed, 29 Apr 2026 22:22:58 +0800
Subject: [PATCH 1/7] feat: prototype fork-based dynamic branch workers

---
 qemu/linux-user/ptc.c                         |  18 ++
 qemu/linux-user/ptc.h                         |   4 +
 .../tools/runnable-lift/CodeGenerator.cpp     | 215 +++++++++++++++---
 runnable/tools/runnable-lift/CodeGenerator.h  |  27 ++-
 .../tools/runnable-lift/JumpTargetManager.cpp |  38 +++-
 .../tools/runnable-lift/JumpTargetManager.h   |   1 +
 runnable/tools/runnable-lift/Main.cpp         |  32 ++-
 .../tools/runnable-lift/ParallelOptions.h     |  22 ++
 8 files changed, 319 insertions(+), 38 deletions(-)
 create mode 100644 runnable/tools/runnable-lift/ParallelOptions.h

diff --git a/qemu/linux-user/ptc.c b/qemu/linux-user/ptc.c
index f1a0f1c7c..28a550fdf 100644
--- a/qemu/linux-user/ptc.c
+++ b/qemu/linux-user/ptc.c
@@ -309,6 +309,8 @@ int ptc_load(void *handle, PTCInterface *output, const char *ptc_filename,
   result.disassemble = &ptc_disassemble;
   result.do_syscall2 = &ptc_do_syscall2;
   result.storeCPUState = &ptc_storeCPUState;
+  result.dropCPUState = &ptc_dropCPUState;
+  result.queueDepth = &ptc_queueDepth;
   result.getBranchCPUeip = &ptc_getBranchCPUeip;
   result.deletCPULINEState = &ptc_deletCPULINEState;
   result.recoverStack = &ptc_recoverStack;
@@ -1444,6 +1446,22 @@ uint32_t ptc_storeCPUState(void) {
   return 1;
 }
 
+uint32_t ptc_dropCPUState(void){
+  BranchState datatmp;
+
+  if(isEmpty())
+    return 0;
+
+  datatmp = deletArchCPUStateQueueLine();
+  free(datatmp.elf_data);
+  free(datatmp.elf_stack);
+  return 1;
+}
+
+uint32_t ptc_queueDepth(void){
+  return numsArchCPUStateQueueLine();
+}
+
 void ptc_recoverStack(void){
   CPUArchState *env = (CPUArchState *)cpu->env_ptr;
   memcpy((void *)env->regs[4],current_stack,elf_start_stack-(abi_ulong)env->regs[4]);
diff --git a/qemu/linux-user/ptc.h b/qemu/linux-user/ptc.h
index b1231f05e..9b4e850ff 100644
--- a/qemu/linux-user/ptc.h
+++ b/qemu/linux-user/ptc.h
@@ -257,6 +257,8 @@ EXPORTED(uint64_t, ptc_run_library, (size_t flag));
 EXPORTED(void, ptc_data_start, (uint64_t start, uint64_t entry));
 EXPORTED(unsigned long, ptc_do_syscall2, (void));
 EXPORTED(uint32_t, ptc_storeCPUState, (void));
+EXPORTED(uint32_t, ptc_dropCPUState, (void));
+EXPORTED(uint32_t, ptc_queueDepth, (void));
 EXPORTED(void, ptc_getBranchCPUeip,(void));
 EXPORTED(uint32_t, ptc_deletCPULINEState,(void));
 EXPORTED(void,ptc_recoverStack,(void));
@@ -290,6 +292,8 @@ typedef struct {
 
   ptc_do_syscall2_ptr_t do_syscall2;
   ptc_storeCPUState_ptr_t storeCPUState;
+  ptc_dropCPUState_ptr_t dropCPUState;
+  ptc_queueDepth_ptr_t queueDepth;
   ptc_getBranchCPUeip_ptr_t getBranchCPUeip;
   ptc_deletCPULINEState_ptr_t deletCPULINEState;
   ptc_recoverStack_ptr_t recoverStack;
diff --git a/runnable/tools/runnable-lift/CodeGenerator.cpp b/runnable/tools/runnable-lift/CodeGenerator.cpp
index 3a9c9c087..e4579a98f 100644
--- a/runnable/tools/runnable-lift/CodeGenerator.cpp
+++ b/runnable/tools/runnable-lift/CodeGenerator.cpp
@@ -14,6 +14,8 @@
 #include <set>
 #include <sstream>
 #include <string>
+#include <sys/wait.h>
+#include <unistd.h>
 #include <utility>
 #include <vector>
 
@@ -64,6 +66,37 @@ using namespace llvm;
 using std::make_pair;
 using std::string;
 
+namespace {
+
+static std::string hexValue(uint64_t Value) {
+  std::ostringstream Stream;
+  Stream << std::hex << Value;
+  return Stream.str();
+}
+
+static std::string findRepoRootFromCwd() {
+  char Buffer[4096];
+  if (getcwd(Buffer, sizeof(Buffer)) == nullptr)
+    return "";
+  std::string Current(Buffer);
+  while (!Current.empty()) {
+    std::string Probe = Current + "/scripts/merge_dynamic_runnable_fragments.py";
+    if (access(Probe.c_str(), F_OK) == 0)
+      return Current;
+    size_t Slash = Current.find_last_of('/');
+    if (Slash == std::string::npos)
+      break;
+    if (Slash == 0) {
+      Current = "/";
+      break;
+    }
+    Current = Current.substr(0, Slash);
+  }
+  return "";
+}
+
+} // namespace
+
 // Register all the arguments
 
 cl::opt<bool> ExeInit("exe-init",
@@ -179,13 +212,15 @@ CodeGenerator::CodeGenerator(BinaryFile &Binary,
                              llvm::LLVMContext &TheContext,
                              std::string Output,
                              std::string Helpers,
-                             std::string EarlyLinked) :
+                             std::string EarlyLinked,
+                             const ParallelOptions &Options) :
   TargetArchitecture(Target),
   Context(TheContext),
   TheModule((new Module("top", Context))),
   OutputPath(Output),
   Debug(new DebugHelper(Output, TheModule.get(), DebugInfo, DebugPath)),
-  Binary(Binary) {
+  Binary(Binary),
+  ParallelConfig(Options) {
   OriginalInstrMDKind = Context.getMDKindID("oi");
   PTCInstrMDKind = Context.getMDKindID("pi");
 
@@ -1015,14 +1050,14 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
     } 
     }////?end if(!JumpTargets.haveBB)
 
-    if(EntryFlag and JumpTargets.haveBB){
+	    if(EntryFlag and JumpTargets.haveBB){
       JumpTargets.handleSuspectDataRegion(SuspectEntryAddr,VirtualAddress);
       SuspectEntryAddr = 0;
       EntryFlag = false;
     }
 
-    // Obtain a new program counter to translate
-    std::tie(VirtualAddress, Entry) = JumpTargets.peek();
+	    // Obtain a new program counter to translate
+	    std::tie(VirtualAddress, Entry) = JumpTargets.peek();
 
     if(*ptc.isCall and BlockBRs){
       if(!JumpTargets.isDataSegmAddr(ptc.regs[R_ESP])){
@@ -1036,7 +1071,7 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
       *ptc.isCall = 0;
     }
 
-    if(!EntryFlag){
+	    if(!EntryFlag){
       if(*ptc.exception_syscall == 0x100){
         if(ExeInit){
           if(ptc.regs[R_EAX]==20){
@@ -1078,9 +1113,12 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
         if(it == JumpTargets.CallBranches.end())
           DynamicVirtualAddress = 0;
       }
+      if(!JumpTargets.haveBB && DynamicVirtualAddress != 0
+         && JumpTargets.isOutOfAddrRange(DynamicVirtualAddress))
+        DynamicVirtualAddress = 0;
     }
 
-    if(traverseFLAG){
+	    if(traverseFLAG){
     //handle invalid address
     if(!JumpTargets.isExecutableAddress(DynamicVirtualAddress) 
        and !JumpTargets.haveBB)
@@ -1092,22 +1130,31 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
    
     }
     
-    // Some branch destination addr is 0 
-    if((JumpTargets.haveBB || DynamicVirtualAddress == 0 ) and
-		    !JumpTargets.BranchTargets.empty())
-    {
-      BlockBRs = nullptr;
-      // if occure a translated BB, traversing next branch
-      std::tie(jtVirtualAddress, srcBB, srcAddr) = JumpTargets.BranchTargets.front();
-      errs()<<"--------------------\n";
-      JumpTargets.BranchTargets.erase(JumpTargets.BranchTargets.begin());
-      ptc.deletCPULINEState();
-      DynamicVirtualAddress = jtVirtualAddress;
-      BaseData.clear();
-    }
-
-    if(DynamicVirtualAddress){
-      auto tmpBB = JumpTargets.registerJT(DynamicVirtualAddress,JTReason::GlobalData);
+	    // Some branch destination addr is 0 
+		    if((JumpTargets.haveBB || DynamicVirtualAddress == 0 ) and
+				    !JumpTargets.BranchTargets.empty())
+	    {
+	      BlockBRs = nullptr;
+	      // if occure a translated BB, traversing next branch
+	      std::tie(jtVirtualAddress, srcBB, srcAddr) = JumpTargets.BranchTargets.front();
+	      errs()<<"--------------------\n";
+              if (trySpawnBranchWorker(jtVirtualAddress, JumpTargets.BranchTargets)) {
+                JumpTargets.haveBB = 0;
+                DynamicVirtualAddress = 0;
+                BaseData.clear();
+              } else if (ParallelConfig.WorkerMode) {
+                DynamicVirtualAddress = jtVirtualAddress;
+                BaseData.clear();
+              } else {
+	        JumpTargets.BranchTargets.erase(JumpTargets.BranchTargets.begin());
+	        ptc.deletCPULINEState();
+	        DynamicVirtualAddress = jtVirtualAddress;
+	        BaseData.clear();
+              }
+	    }
+
+	    if(DynamicVirtualAddress){
+	      auto tmpBB = JumpTargets.registerJT(DynamicVirtualAddress,JTReason::GlobalData);
       //JumpTargets.isContainIndirectInst(DynamicVirtualAddress,tmpVA,tmpBB);
       if(JumpTargets.haveBB){
         // If have translated BB, give Entry an arbitrary value
@@ -1122,14 +1169,14 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
         srcBB = nullptr;
 	JumpTargets.haveBB = 0;
       }
-      if(BlockBRs != nullptr and !EntryFlag){  
-        auto branchLabeledcontent = Translator.branchcontent(); 
-        JumpTargets.harvestbranchBasicBlock(VirtualAddress,
+	      if(BlockBRs != nullptr and !EntryFlag){  
+	        auto branchLabeledcontent = Translator.branchcontent(); 
+	        JumpTargets.harvestbranchBasicBlock(VirtualAddress,
 			           tmpVA,
                                    BlockBRs,
-                                   Translator.branchsize(), 
-                                   branchLabeledcontent);
-      }
+	                                   Translator.branchsize(), 
+	                                   branchLabeledcontent);
+	      }
       std::cerr<<std::hex<<VirtualAddress<<" \n";
     }
 
@@ -1154,8 +1201,9 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
       std::cerr<<std::hex<<VirtualAddress<<" \n";
     }
 
-  } // End translations loop
-  JumpTargets.handleEmbeddedDataAddr(getEmbeddedData());
+	  } // End translations loop
+          waitForForkWorkers();
+	  JumpTargets.handleEmbeddedDataAddr(getEmbeddedData());
   embeddedData();
   JumpTargets.TestSuspectDataRegion(getPath());  
 
@@ -1392,4 +1440,109 @@ void CodeGenerator::serialize() {
     std::ofstream Output(OutputPath);
     Debug->print(Output, false);
   }
+  if (!ParallelConfig.WorkerMode)
+    mergeForkWorkerFragments();
+}
+
+void CodeGenerator::switchToWorkerOutput(uint64_t SeedPC) {
+  if (!ParallelConfig.FragmentDir.empty()) {
+    std::string Command = "mkdir -p \"" + ParallelConfig.FragmentDir + "\"";
+    ::system(Command.c_str());
+  }
+  std::ostringstream Path;
+  Path << ParallelConfig.FragmentDir << "/worker_" << hexValue(SeedPC) << ".ll";
+  OutputPath = Path.str();
+  CoveragePath = OutputPath + ".coverage.csv";
+  BBSummaryPath = OutputPath + ".bbsummary.csv";
+  LinkingInfoPath = OutputPath + ".li.csv";
+  Debug.reset(new DebugHelper(OutputPath, TheModule.get(), DebugInfo, DebugPath));
+}
+
+bool CodeGenerator::trySpawnBranchWorker(
+  uint64_t SeedPC,
+  std::vector<std::tuple<uint64_t, llvm::BasicBlock *, uint64_t>> &BranchTargets) {
+  if (!ParallelConfig.DynamicParallel || ParallelConfig.WorkerMode)
+    return false;
+  if (ParallelConfig.WorkerCount == 0)
+    return false;
+  if (ParallelSpawnedSeeds.count(SeedPC) != 0)
+    return false;
+
+  size_t ActiveWorkers = 0;
+  for (const auto &Worker : ParallelWorkers)
+    if (!Worker.Finished)
+      ActiveWorkers++;
+  if (ActiveWorkers >= ParallelConfig.WorkerCount)
+    return false;
+
+  pid_t PID = fork();
+  runnable_assert(PID >= 0, "failed to fork branch worker");
+  if (PID == 0) {
+    ParallelConfig.WorkerMode = true;
+    switchToWorkerOutput(SeedPC);
+    BranchTargets.erase(BranchTargets.begin());
+    ptc.deletCPULINEState();
+    return false;
+  }
+
+  BranchTargets.erase(BranchTargets.begin());
+  ptc.dropCPUState();
+  ParallelSpawnedSeeds.insert(SeedPC);
+  std::ostringstream WorkerOutput;
+  WorkerOutput << ParallelConfig.FragmentDir << "/worker_" << hexValue(SeedPC) << ".ll";
+  ParallelWorkers.push_back({ static_cast<int>(PID), SeedPC, WorkerOutput.str(), -1, false });
+  ParallelWorkersSpawned++;
+  return true;
+}
+
+void CodeGenerator::waitForForkWorkers() {
+  if (!ParallelConfig.DynamicParallel || ParallelConfig.WorkerMode)
+    return;
+
+  for (auto &Worker : ParallelWorkers) {
+    if (Worker.Finished)
+      continue;
+    int Status = 0;
+    pid_t Waited = waitpid(Worker.Pid, &Status, 0);
+    if (Waited != Worker.Pid)
+      continue;
+    Worker.Finished = true;
+    Worker.ExitCode = WIFEXITED(Status) ? WEXITSTATUS(Status) : -1;
+    if (Worker.ExitCode == 0)
+      ParallelWorkersSucceeded++;
+    else
+      ParallelWorkersFailed++;
+  }
+}
+
+void CodeGenerator::mergeForkWorkerFragments() {
+  if (!ParallelConfig.DynamicParallel || ParallelConfig.WorkerMode)
+    return;
+  if (ParallelWorkersSucceeded == 0)
+    return;
+
+  std::string RepoRoot = findRepoRootFromCwd();
+  if (RepoRoot.empty())
+    return;
+  std::string ScriptPath = RepoRoot + "/scripts/merge_dynamic_runnable_fragments.py";
+  if (access(ScriptPath.c_str(), F_OK) != 0)
+    return;
+
+  std::string TempOutput = OutputPath + ".merged.ll";
+  std::ostringstream EntryPC;
+  EntryPC << "0x" << std::hex << Binary.entryPoint();
+  std::ostringstream Command;
+  Command << "python3 " << ScriptPath
+          << " --output " << TempOutput
+          << " --entry-pc " << EntryPC.str()
+          << " " << OutputPath;
+  for (const auto &Worker : ParallelWorkers) {
+    if (Worker.ExitCode != 0)
+      continue;
+    Command << " " << Worker.OutputPath;
+  }
+  int RC = ::system(Command.str().c_str());
+  if (RC != 0)
+    return;
+  rename(TempOutput.c_str(), OutputPath.c_str());
 }
diff --git a/runnable/tools/runnable-lift/CodeGenerator.h b/runnable/tools/runnable-lift/CodeGenerator.h
index f35665f4b..1cb10099f 100644
--- a/runnable/tools/runnable-lift/CodeGenerator.h
+++ b/runnable/tools/runnable-lift/CodeGenerator.h
@@ -8,7 +8,9 @@
 // Standard includes
 #include <cstdint>
 #include <memory>
+#include <set>
 #include <string>
+#include <vector>
 
 // LLVM includes
 #include "llvm/ADT/ArrayRef.h"
@@ -18,6 +20,7 @@
 
 // Local includes
 #include "BinaryFile.h"
+#include "ParallelOptions.h"
 
 // Forward declarations
 namespace llvm {
@@ -38,6 +41,14 @@ class ObjectFile;
 
 class DebugHelper;
 
+struct ParallelWorkerState {
+  int Pid = -1;
+  uint64_t SeedPC = 0;
+  std::string OutputPath;
+  int ExitCode = -1;
+  bool Finished = false;
+};
+
 /// Translator from binary code to LLVM IR.
 class CodeGenerator {
 public:
@@ -54,7 +65,8 @@ class CodeGenerator {
                 llvm::LLVMContext &TheContext,
                 std::string Output,
                 std::string Helpers,
-                std::string EarlyLinked);
+                std::string EarlyLinked,
+                const ParallelOptions &Options);
 
   ~CodeGenerator();
 
@@ -97,6 +109,12 @@ class CodeGenerator {
   /// \param Name name of the imported function
   llvm::Function *importHelperFunctionDeclaration(llvm::StringRef Name);
 
+  void switchToWorkerOutput(uint64_t SeedPC);
+  bool trySpawnBranchWorker(uint64_t SeedPC,
+                            std::vector<std::tuple<uint64_t, llvm::BasicBlock *, uint64_t>> &BranchTargets);
+  void waitForForkWorkers();
+  void mergeForkWorkerFragments();
+
 private:
   Architecture TargetArchitecture;
   llvm::LLVMContext &Context;
@@ -112,6 +130,13 @@ class CodeGenerator {
   unsigned DbgMDKind;
 
   std::string FunctionListPath;
+  ParallelOptions ParallelConfig;
+  std::vector<ParallelWorkerState> ParallelWorkers;
+  std::set<uint64_t> ParallelSpawnedSeeds;
+  uint64_t ParallelFrontierCandidates = 0;
+  uint64_t ParallelWorkersSpawned = 0;
+  uint64_t ParallelWorkersSucceeded = 0;
+  uint64_t ParallelWorkersFailed = 0;
 };
 
 #endif // CODEGENERATOR_H
diff --git a/runnable/tools/runnable-lift/JumpTargetManager.cpp b/runnable/tools/runnable-lift/JumpTargetManager.cpp
index cf51c65c4..17e519bda 100644
--- a/runnable/tools/runnable-lift/JumpTargetManager.cpp
+++ b/runnable/tools/runnable-lift/JumpTargetManager.cpp
@@ -61,6 +61,20 @@ cl::opt<bool> FAST("fast",
 cl::opt<bool> SUPERFAST("super-fast",
                        cl::desc("fast rewriting"),
                        cl::cat(MainCategory));
+cl::opt<unsigned long long> AddrRangeMin("addr-range-min",
+                                         cl::desc("Lower bound (inclusive) of the address range"
+                                                  " to translate. When non-zero, execution leaving"
+                                                  " [addr-range-min, addr-range-max) is stopped."),
+                                         cl::value_desc("address"),
+                                         cl::init(0),
+                                         cl::cat(MainCategory));
+cl::opt<unsigned long long> AddrRangeMax("addr-range-max",
+                                         cl::desc("Upper bound (exclusive) of the address range"
+                                                  " to translate. Must be set together with"
+                                                  " --addr-range-min."),
+                                         cl::value_desc("address"),
+                                         cl::init(0),
+                                         cl::cat(MainCategory));
 cl::opt<bool> INFO("info",
                        cl::desc("print statistics information"),
                        cl::cat(MainCategory));
@@ -2935,9 +2949,19 @@ bool JumpTargetManager::isIllegalStaticAddr(uint64_t pc){
   //    return true;
   //}
 
+  if(isOutOfAddrRange(pc))
+    return true;
+
   return false;
 }
 
+bool JumpTargetManager::isOutOfAddrRange(uint64_t pc){
+  if(AddrRangeMin == 0 && AddrRangeMax == 0)
+    return false;
+
+  return (pc < AddrRangeMin || pc >= AddrRangeMax);
+}
+
 void JumpTargetManager::harvestNextAddrofBr(){
   // *ptc.CFIAddr represents next block addr. 
   auto BlockNext = *ptc.CFIAddr;  
@@ -3929,7 +3953,7 @@ void JumpTargetManager::harvestBTBasicBlock(llvm::BasicBlock *thisBlock,
     if(std::get<0>(item) == destAddr)
         return;
   }
-  if(!haveTranslatedPC(destAddr, 0)){
+  if(!haveTranslatedPC(destAddr, 0) && !isOutOfAddrRange(destAddr)){
       ptc.storeCPUState();
       /* Recording not execute branch destination relationship with current BasicBlock */
      // thisBlock = nullptr; 
@@ -4675,8 +4699,10 @@ void JumpTargetManager::harvestCallBasicBlock(llvm::BasicBlock *thisBlock,uint64
        * So,this Block will not contain a call instruction, that has been splited
        * but we still record this relationship, because when we backtracking,
        * we will check splited Block. */ 
-      BranchTargets.push_back(std::make_tuple(*ptc.CallNext,thisBlock,thisAddr));
-      errs()<<format_hex(*ptc.CallNext,0)<<" <- Call next target add\n";
+      if(!isOutOfAddrRange(*ptc.CallNext)){
+        BranchTargets.push_back(std::make_tuple(*ptc.CallNext,thisBlock,thisAddr));
+        errs()<<format_hex(*ptc.CallNext,0)<<" <- Call next target add\n";
+      }
     }
   errs()<<"Branch targets total numbers: "<<BranchTargets.size()<<"\n";  
 }
@@ -4746,13 +4772,15 @@ void JumpTargetManager::harvestbranchBasicBlock(uint64_t nextAddr,
 	    runnable_abort("Store memory state failed!\n");
           /* Recording not execute branch destination relationship 
 	   * with current BasicBlock and address */ 
-          BranchTargets.push_back(std::make_tuple(
+          if(!isOutOfAddrRange(destAddrSrcBB.first)){
+            BranchTargets.push_back(std::make_tuple(
 				destAddrSrcBB.first,
 				//destAddrSrcBB.second,
 				thisBlock,
 				thisAddr
 				)); 
-          errs()<<format_hex(destAddrSrcBB.first,0)<<" <- Jmp target add\n";
+            errs()<<format_hex(destAddrSrcBB.first,0)<<" <- Jmp target add\n";
+          }
         }  
       }
     }
diff --git a/runnable/tools/runnable-lift/JumpTargetManager.h b/runnable/tools/runnable-lift/JumpTargetManager.h
index 2d450bb84..2d7fed27f 100644
--- a/runnable/tools/runnable-lift/JumpTargetManager.h
+++ b/runnable/tools/runnable-lift/JumpTargetManager.h
@@ -248,6 +248,7 @@ class JumpTargetManager {
 
   std::vector<uint64_t> IllegalStaticAddrs;
   bool isIllegalStaticAddr(uint64_t pc);
+  bool isOutOfAddrRange(uint64_t pc);
 
   void TestSuspectDataRegion(std::string path);
   StaticAddrsMap SuspectDataRegion;
diff --git a/runnable/tools/runnable-lift/Main.cpp b/runnable/tools/runnable-lift/Main.cpp
index f501dac31..40466c9eb 100644
--- a/runnable/tools/runnable-lift/Main.cpp
+++ b/runnable/tools/runnable-lift/Main.cpp
@@ -38,6 +38,7 @@ extern "C" {
 // Local includes
 #include "BinaryFile.h"
 #include "CodeGenerator.h"
+#include "ParallelOptions.h"
 #include "PTCInterface.h"
 
 PTCInterface ptc = {}; ///< The interface with the PTC library.
@@ -78,6 +79,26 @@ opt<string> OutputPath(Positional, Required, desc("<output path>"));
 
 opt<string> ExecutableArgs("exe-args", value_desc("arguments"), cat(MainCategory));
 
+opt<bool> DynamicParallel("dynamic-parallel",
+                          desc("enable dynamic branch-driven parallel lift"),
+                          cat(MainCategory),
+                          init(false));
+opt<unsigned> ParallelWorkers("parallel-workers",
+                              desc("maximum number of worker subprocesses"),
+                              cat(MainCategory),
+                              init(1));
+opt<bool> ParallelWorkerMode("parallel-worker-mode",
+                             desc("internal worker subprocess mode"),
+                             cat(MainCategory),
+                             init(false));
+opt<unsigned long long> ParallelSeedPC("parallel-seed-pc",
+                                       desc("worker seed PC"),
+                                       cat(MainCategory),
+                                       init(0));
+opt<string> ParallelFragmentDir("parallel-fragment-dir",
+                                desc("fragment output directory"),
+                                cat(MainCategory));
+
 } // namespace
 
 static std::string LibTinycodePath;
@@ -203,12 +224,21 @@ int main(int argc, const char *argv[]) {
   // Translate everything
   Architecture TargetArchitecture;
   llvm::LLVMContext RevambGlobalContext;
+  ParallelOptions Options;
+  Options.DynamicParallel = DynamicParallel;
+  Options.WorkerMode = ParallelWorkerMode;
+  Options.WorkerCount = ParallelWorkers;
+  Options.SeedPC = ParallelSeedPC;
+  Options.FragmentDir = ParallelFragmentDir;
+  Options.InputPath = InputPath;
+  Options.ExecutableArgs = ExecutableArgs;
   CodeGenerator Generator(TheBinary,
                           TargetArchitecture,
                           RevambGlobalContext,
                           std::string(OutputPath),
                           LibHelpersPath,
-                          EarlyLinkedPath);
+                          EarlyLinkedPath,
+                          Options);
 
   Generator.translate(EntryPointAddress);
   Generator.serialize();
diff --git a/runnable/tools/runnable-lift/ParallelOptions.h b/runnable/tools/runnable-lift/ParallelOptions.h
new file mode 100644
index 000000000..02b13488b
--- /dev/null
+++ b/runnable/tools/runnable-lift/ParallelOptions.h
@@ -0,0 +1,22 @@
+#ifndef RUNNABLE_LIFT_PARALLELOPTIONS_H
+#define RUNNABLE_LIFT_PARALLELOPTIONS_H
+
+//
+// This file is distributed under the MIT License. See LICENSE.md for details.
+//
+
+// Standard includes
+#include <cstdint>
+#include <string>
+
+struct ParallelOptions {
+  bool DynamicParallel = false;
+  bool WorkerMode = false;
+  unsigned WorkerCount = 1;
+  uint64_t SeedPC = 0;
+  std::string FragmentDir;
+  std::string InputPath;
+  std::string ExecutableArgs;
+};
+
+#endif // RUNNABLE_LIFT_PARALLELOPTIONS_H

From 88bf9e170aa19ebe3329ae2c816bef9d0bac5821 Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Fri, 1 May 2026 22:03:19 +0800
Subject: [PATCH 2/7] fix: isolate dynamic parallel workers from inherited
 branch state

---
 .../tools/runnable-lift/CodeGenerator.cpp     | 203 ++++++++++++++----
 runnable/tools/runnable-lift/CodeGenerator.h  |   6 +
 .../tools/runnable-lift/JumpTargetManager.cpp |  12 ++
 3 files changed, 185 insertions(+), 36 deletions(-)

diff --git a/runnable/tools/runnable-lift/CodeGenerator.cpp b/runnable/tools/runnable-lift/CodeGenerator.cpp
index e4579a98f..e0f95e1c2 100644
--- a/runnable/tools/runnable-lift/CodeGenerator.cpp
+++ b/runnable/tools/runnable-lift/CodeGenerator.cpp
@@ -7,6 +7,8 @@
 //
 
 // Standard includes
+#include <cstdlib>
+#include <cstdio>
 #include <cstring>
 #include <fstream>
 #include <memory>
@@ -217,6 +219,8 @@ CodeGenerator::CodeGenerator(BinaryFile &Binary,
   TargetArchitecture(Target),
   Context(TheContext),
   TheModule((new Module("top", Context))),
+  HelpersPath(Helpers),
+  EarlyLinkedPath(EarlyLinked),
   OutputPath(Output),
   Debug(new DebugHelper(Output, TheModule.get(), DebugInfo, DebugPath)),
   Binary(Binary),
@@ -224,7 +228,7 @@ CodeGenerator::CodeGenerator(BinaryFile &Binary,
   OriginalInstrMDKind = Context.getMDKindID("oi");
   PTCInstrMDKind = Context.getMDKindID("pi");
 
-  HelpersModule = parseIR(Helpers, Context);
+  HelpersModule = parseIR(HelpersPath, Context);
   for (auto &F : HelpersModule->functions()) {
     // Remove 'optnone' Function attribute from QEMU helpers.
     // QEMU helpers are compiled with -O0 in libtinycode because the LLVM IR
@@ -236,7 +240,7 @@ CodeGenerator::CodeGenerator(BinaryFile &Binary,
     F.removeFnAttr(Attribute::OptimizeNone);
     F.setDSOLocal(false);
   }
-  EarlyLinkedModule = parseIR(EarlyLinked, Context);
+  EarlyLinkedModule = parseIR(EarlyLinkedPath, Context);
 
   if (CoveragePath.size() == 0)
     CoveragePath = Output + ".coverage.csv";
@@ -842,6 +846,10 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
   bool StaticAddrFlag = false;
   uint32_t EntryFlag = 0;
   uint64_t SuspectEntryAddr = 0;
+  bool PreferBranchFrontier = false;
+  uint64_t LastHaveBBVA = 0;
+  size_t RepeatedHaveBBCount = 0;
+  const size_t ParallelHaveBBRepeatLimit = 4096;
   std::vector<uint64_t> BlockPCs1;
   std::vector<uint64_t> &BlockPCs = BlockPCs1;
   std::map<uint32_t, uint64_t> BaseData1;
@@ -850,6 +858,7 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
     jjj++;
     BlockBRs = nullptr;
     BlockPCs.clear();
+    DynamicVirtualAddress = 0;
     if(!JumpTargets.haveBB){
       Builder.SetInsertPoint(Entry);
       BlockBRs = Builder.GetInsertBlock();
@@ -869,6 +878,32 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
     if(traverseFLAG && JumpTargets.haveBB){
       ptc_instruction_list_malloc(InstructionList.get()); 
       errs()<<"Nop execute!\n";
+      if (ParallelConfig.DynamicParallel) {
+        if (LastHaveBBVA == VirtualAddress)
+          RepeatedHaveBBCount++;
+        else {
+          LastHaveBBVA = VirtualAddress;
+          RepeatedHaveBBCount = 1;
+        }
+        if (RepeatedHaveBBCount > ParallelHaveBBRepeatLimit) {
+          if (ParallelConfig.WorkerMode) {
+            errs() << "parallel worker loop guard stop repeated haveBB pc=0x"
+                   << Twine::utohexstr(VirtualAddress)
+                   << " repeats=" << RepeatedHaveBBCount << "\n";
+            break;
+          } else {
+            errs() << "parallel loop guard skip repeated haveBB pc=0x"
+                   << Twine::utohexstr(VirtualAddress)
+                   << " repeats=" << RepeatedHaveBBCount << "\n";
+            JumpTargets.haveBB = 0;
+            DynamicVirtualAddress = 0;
+            Entry = nullptr;
+            PreferBranchFrontier = !JumpTargets.BranchTargets.empty();
+          }
+        }
+      }
+    } else {
+      RepeatedHaveBBCount = 0;
     } 
 
     if(!JumpTargets.haveBB){
@@ -1056,8 +1091,17 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
       EntryFlag = false;
     }
 
-	    // Obtain a new program counter to translate
-	    std::tie(VirtualAddress, Entry) = JumpTargets.peek();
+            // Prefer draining saved branch-frontier states before resuming the
+            // general unexplored/static worklist. This preserves the serial
+            // queue discipline more closely when dynamic workers are active.
+            if (PreferBranchFrontier
+                && !ParallelConfig.WorkerMode
+                && !JumpTargets.BranchTargets.empty()) {
+              VirtualAddress = 0;
+              Entry = nullptr;
+            } else {
+	      std::tie(VirtualAddress, Entry) = JumpTargets.peek();
+            }
 
     if(*ptc.isCall and BlockBRs){
       if(!JumpTargets.isDataSegmAddr(ptc.regs[R_ESP])){
@@ -1068,6 +1112,8 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
       errs()<<*((unsigned long *)ptc.regs[4])<<"<--store callnext\n";
       errs()<<*ptc.CallNext<<"\n";
       JumpTargets.harvestCallBasicBlock(BlockBRs,tmpVA);
+      if (ParallelConfig.WorkerMode)
+        JumpTargets.BranchTargets.clear();
       *ptc.isCall = 0;
     }
 
@@ -1087,9 +1133,16 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
           JumpTargets.haveBB = 0;
           BlockBRs = nullptr;
           std::tie(jtVirtualAddress, srcBB, srcAddr) = JumpTargets.BranchTargets.front();
-          JumpTargets.BranchTargets.erase(JumpTargets.BranchTargets.begin());
-          ptc.deletCPULINEState();
-          DynamicVirtualAddress = jtVirtualAddress;  
+          if (trySpawnBranchWorker(jtVirtualAddress, JumpTargets.BranchTargets)) {
+            DynamicVirtualAddress = 0;
+            BaseData.clear();
+            PreferBranchFrontier = false;
+          } else {
+            JumpTargets.BranchTargets.erase(JumpTargets.BranchTargets.begin());
+            ptc.deletCPULINEState();
+            DynamicVirtualAddress = jtVirtualAddress;
+            PreferBranchFrontier = true;
+          }
           errs()<<"syscall--------------------\n";        
         }
       }
@@ -1142,6 +1195,7 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
                 JumpTargets.haveBB = 0;
                 DynamicVirtualAddress = 0;
                 BaseData.clear();
+                PreferBranchFrontier = false;
               } else if (ParallelConfig.WorkerMode) {
                 DynamicVirtualAddress = jtVirtualAddress;
                 BaseData.clear();
@@ -1150,6 +1204,7 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
 	        ptc.deletCPULINEState();
 	        DynamicVirtualAddress = jtVirtualAddress;
 	        BaseData.clear();
+                PreferBranchFrontier = true;
               }
 	    }
 
@@ -1176,12 +1231,16 @@ void CodeGenerator::translate(uint64_t VirtualAddress) {
                                    BlockBRs,
 	                                   Translator.branchsize(), 
 	                                   branchLabeledcontent);
+                if (ParallelConfig.WorkerMode)
+                  JumpTargets.BranchTargets.clear();
 	      }
       std::cerr<<std::hex<<VirtualAddress<<" \n";
     }
 
-    if(JumpTargets.BranchTargets.empty() and !EntryFlag)
+    if(JumpTargets.BranchTargets.empty() and !EntryFlag) {
       DynamicVirtualAddress = 0;
+      PreferBranchFrontier = false;
+    }
 
     }////?end if(traverseFLAG)
     if(!JumpTargets.haveBB)
@@ -1444,20 +1503,105 @@ void CodeGenerator::serialize() {
     mergeForkWorkerFragments();
 }
 
+std::string CodeGenerator::workerOutputPath(uint64_t SeedPC) const {
+  std::ostringstream Path;
+  if (!ParallelConfig.FragmentDir.empty())
+    Path << ParallelConfig.FragmentDir << "/";
+  Path << "worker_" << hexValue(SeedPC) << ".ll";
+  return Path.str();
+}
+
+void CodeGenerator::configureOutputArtifacts(const std::string &Output) {
+  OutputPath = Output;
+  CoveragePath = OutputPath + ".coverage.csv";
+  BBSummaryPath = OutputPath + ".bbsummary.csv";
+  LinkingInfoPath = OutputPath + ".li.csv";
+}
+
 void CodeGenerator::switchToWorkerOutput(uint64_t SeedPC) {
   if (!ParallelConfig.FragmentDir.empty()) {
     std::string Command = "mkdir -p \"" + ParallelConfig.FragmentDir + "\"";
     ::system(Command.c_str());
   }
-  std::ostringstream Path;
-  Path << ParallelConfig.FragmentDir << "/worker_" << hexValue(SeedPC) << ".ll";
-  OutputPath = Path.str();
-  CoveragePath = OutputPath + ".coverage.csv";
-  BBSummaryPath = OutputPath + ".bbsummary.csv";
-  LinkingInfoPath = OutputPath + ".li.csv";
+  configureOutputArtifacts(workerOutputPath(SeedPC));
   Debug.reset(new DebugHelper(OutputPath, TheModule.get(), DebugInfo, DebugPath));
 }
 
+int CodeGenerator::runFreshBranchWorker(uint64_t SeedPC) {
+  std::string WorkerOutput = workerOutputPath(SeedPC);
+  std::string WorkerStdout = WorkerOutput + ".stdout.log";
+  std::string WorkerStderr = WorkerOutput + ".stderr.log";
+  ::freopen(WorkerStdout.c_str(), "w", stdout);
+  ::freopen(WorkerStderr.c_str(), "w", stderr);
+  ::setenv("RUNNABLE_PARALLEL_WORKER_MODE", "1", 1);
+  uint32_t QueueDepth = ptc.queueDepth();
+  errs() << "parallel worker seed=0x" << Twine::utohexstr(SeedPC)
+         << " inherited-qdepth=" << QueueDepth << "\n";
+  if (QueueDepth != 0) {
+    ptc.deletCPULINEState();
+  } else {
+    errs() << "parallel worker seed=0x" << Twine::utohexstr(SeedPC)
+           << " inherited queue empty, continuing without saved state\n";
+  }
+
+  if (!ParallelConfig.FragmentDir.empty()) {
+    std::string Command = "mkdir -p \"" + ParallelConfig.FragmentDir + "\"";
+    ::system(Command.c_str());
+  }
+
+  CoveragePath = WorkerOutput + ".coverage.csv";
+  BBSummaryPath = WorkerOutput + ".bbsummary.csv";
+  LinkingInfoPath = WorkerOutput + ".li.csv";
+
+  ParallelOptions WorkerOptions = ParallelConfig;
+  WorkerOptions.DynamicParallel = true;
+  WorkerOptions.WorkerMode = true;
+  WorkerOptions.WorkerCount = 0;
+  WorkerOptions.SeedPC = SeedPC;
+
+  BinaryFile WorkerBinary(ParallelConfig.InputPath, Binary.relocate(0));
+  Architecture WorkerTargetArchitecture;
+  llvm::LLVMContext WorkerContext;
+
+  {
+    CodeGenerator WorkerGenerator(WorkerBinary,
+                                  WorkerTargetArchitecture,
+                                  WorkerContext,
+                                  WorkerOutput,
+                                  HelpersPath,
+                                  EarlyLinkedPath,
+                                  WorkerOptions);
+    WorkerGenerator.translate(SeedPC);
+    WorkerGenerator.serialize();
+  }
+
+  return EXIT_SUCCESS;
+}
+
+void CodeGenerator::pollFinishedForkWorkers(bool Block) {
+  if (!ParallelConfig.DynamicParallel || ParallelConfig.WorkerMode)
+    return;
+
+  for (auto &Worker : ParallelWorkers) {
+    if (Worker.Finished)
+      continue;
+
+    int Status = 0;
+    pid_t Waited = waitpid(Worker.Pid, &Status, Block ? 0 : WNOHANG);
+    if (Waited == 0)
+      continue;
+    if (Waited != Worker.Pid)
+      continue;
+
+    Worker.Finished = true;
+    Worker.ExitCode = WIFEXITED(Status) ? WEXITSTATUS(Status) : -1;
+    if (Worker.ExitCode == 0)
+      ParallelWorkersSucceeded++;
+    else
+      ParallelWorkersFailed++;
+  }
+}
+
 bool CodeGenerator::trySpawnBranchWorker(
   uint64_t SeedPC,
   std::vector<std::tuple<uint64_t, llvm::BasicBlock *, uint64_t>> &BranchTargets) {
@@ -1468,6 +1612,8 @@ bool CodeGenerator::trySpawnBranchWorker(
   if (ParallelSpawnedSeeds.count(SeedPC) != 0)
     return false;
 
+  pollFinishedForkWorkers(false);
+
   size_t ActiveWorkers = 0;
   for (const auto &Worker : ParallelWorkers)
     if (!Worker.Finished)
@@ -1478,13 +1624,14 @@ bool CodeGenerator::trySpawnBranchWorker(
   pid_t PID = fork();
   runnable_assert(PID >= 0, "failed to fork branch worker");
   if (PID == 0) {
-    ParallelConfig.WorkerMode = true;
-    switchToWorkerOutput(SeedPC);
-    BranchTargets.erase(BranchTargets.begin());
-    ptc.deletCPULINEState();
-    return false;
+    int Result = runFreshBranchWorker(SeedPC);
+    errs() << "parallel worker seed=0x" << Twine::utohexstr(SeedPC)
+           << " exit=" << Result << "\n";
+    ::_exit(Result);
   }
 
+  errs() << "parallel parent spawn seed=0x" << Twine::utohexstr(SeedPC)
+         << " qdepth-before-drop=" << ptc.queueDepth() << "\n";
   BranchTargets.erase(BranchTargets.begin());
   ptc.dropCPUState();
   ParallelSpawnedSeeds.insert(SeedPC);
@@ -1496,23 +1643,7 @@ bool CodeGenerator::trySpawnBranchWorker(
 }
 
 void CodeGenerator::waitForForkWorkers() {
-  if (!ParallelConfig.DynamicParallel || ParallelConfig.WorkerMode)
-    return;
-
-  for (auto &Worker : ParallelWorkers) {
-    if (Worker.Finished)
-      continue;
-    int Status = 0;
-    pid_t Waited = waitpid(Worker.Pid, &Status, 0);
-    if (Waited != Worker.Pid)
-      continue;
-    Worker.Finished = true;
-    Worker.ExitCode = WIFEXITED(Status) ? WEXITSTATUS(Status) : -1;
-    if (Worker.ExitCode == 0)
-      ParallelWorkersSucceeded++;
-    else
-      ParallelWorkersFailed++;
-  }
+  pollFinishedForkWorkers(true);
 }
 
 void CodeGenerator::mergeForkWorkerFragments() {
diff --git a/runnable/tools/runnable-lift/CodeGenerator.h b/runnable/tools/runnable-lift/CodeGenerator.h
index 1cb10099f..4aee2243c 100644
--- a/runnable/tools/runnable-lift/CodeGenerator.h
+++ b/runnable/tools/runnable-lift/CodeGenerator.h
@@ -109,7 +109,11 @@ class CodeGenerator {
   /// \param Name name of the imported function
   llvm::Function *importHelperFunctionDeclaration(llvm::StringRef Name);
 
+  std::string workerOutputPath(uint64_t SeedPC) const;
+  void configureOutputArtifacts(const std::string &Output);
   void switchToWorkerOutput(uint64_t SeedPC);
+  int runFreshBranchWorker(uint64_t SeedPC);
+  void pollFinishedForkWorkers(bool Block);
   bool trySpawnBranchWorker(uint64_t SeedPC,
                             std::vector<std::tuple<uint64_t, llvm::BasicBlock *, uint64_t>> &BranchTargets);
   void waitForForkWorkers();
@@ -121,6 +125,8 @@ class CodeGenerator {
   std::unique_ptr<llvm::Module> TheModule;
   std::unique_ptr<llvm::Module> HelpersModule;
   std::unique_ptr<llvm::Module> EarlyLinkedModule;
+  std::string HelpersPath;
+  std::string EarlyLinkedPath;
   std::string OutputPath;
   std::unique_ptr<DebugHelper> Debug;
   BinaryFile &Binary;
diff --git a/runnable/tools/runnable-lift/JumpTargetManager.cpp b/runnable/tools/runnable-lift/JumpTargetManager.cpp
index 17e519bda..e55d495fe 100644
--- a/runnable/tools/runnable-lift/JumpTargetManager.cpp
+++ b/runnable/tools/runnable-lift/JumpTargetManager.cpp
@@ -9,6 +9,7 @@
 
 // Standard includes
 #include "runnable/Support/Assert.h"
+#include <cstdlib>
 #include <cstdint>
 #include <fstream>
 #include <queue>
@@ -52,6 +53,11 @@ namespace {
 
 Logger<> JTCountLog("jtcount");
 
+static bool inParallelWorkerMode() {
+  const char *Value = std::getenv("RUNNABLE_PARALLEL_WORKER_MODE");
+  return Value != nullptr && Value[0] == '1';
+}
+
 cl::opt<bool> Statistics("Statistics",
                        cl::desc("Count rewriting information"),
                        cl::cat(MainCategory));
@@ -3949,6 +3955,8 @@ void JumpTargetManager::handleIndirectJmp(llvm::BasicBlock *thisBlock,
 void JumpTargetManager::harvestBTBasicBlock(llvm::BasicBlock *thisBlock,
 		                            uint64_t thisAddr,
 					    uint64_t destAddr){
+  if (inParallelWorkerMode())
+    return;
   for(auto item : BranchTargets){
     if(std::get<0>(item) == destAddr)
         return;
@@ -4675,6 +4683,8 @@ void JumpTargetManager::harvestCallBasicBlock(llvm::BasicBlock *thisBlock,uint64
   }
   if(!haveTranslatedPC(*ptc.CallNext, 0))
       StaticAddrs[*ptc.CallNext] = 2;
+  if (inParallelWorkerMode())
+    return;
   for(auto item : BranchTargets){
     if(std::get<0>(item) == *ptc.CallNext)
         return;
@@ -4750,6 +4760,8 @@ void JumpTargetManager::harvestbranchBasicBlock(uint64_t nextAddr,
 	  CondBranches[thisAddr] = 1;
     }
     for (auto destAddrSrcBB : branchJT){
+      if (inParallelWorkerMode())
+        break;
       if(!haveTranslatedPC(destAddrSrcBB.first, nextAddr) && 
 		      !isIllegalStaticAddr(destAddrSrcBB.first)){
 	bool isRecord = false;

From a5e9e7f56f0adafdf8938a1ba01f34f7c0860a26 Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Fri, 1 May 2026 22:31:53 +0800
Subject: [PATCH 3/7] docs: add dynamic parallel lift prototype usage

---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index b0d0115d1..d9334f77e 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,45 @@ $ runnable-lift hello hello.ll 2>hello.log
 $ runnable translate hello
 ```
 
+## Dynamic Parallel Lift (Prototype)
+
+The `codex/dynamic-parallel-lift` branch adds an experimental dynamic
+branch-driven parallel mode to `runnable-lift`.
+
+User-facing flags:
+
+- `-dynamic-parallel`: enable dynamic branch-driven worker spawning
+- `-parallel-workers=<N>`: cap the number of worker subprocesses
+- `-parallel-fragment-dir=<PATH>`: directory for worker `.ll` fragments and logs
+
+Example:
+
+```
+$ mkdir -p /tmp/runnable-fragments
+$ runnable-lift hello hello.ll \
+    -dynamic-parallel \
+    -parallel-workers=4 \
+    -parallel-fragment-dir=/tmp/runnable-fragments \
+    2>hello.parallel.log
+```
+
+Artifacts:
+
+- coordinator output: `hello.ll`
+- worker fragments: `/tmp/runnable-fragments/worker_<pc>.ll`
+- worker stdout/stderr logs:
+  - `/tmp/runnable-fragments/worker_<pc>.ll.stdout.log`
+  - `/tmp/runnable-fragments/worker_<pc>.ll.stderr.log`
+
+Notes:
+
+- `-parallel-worker-mode` and `-parallel-seed-pc` are internal flags used by
+  worker subprocesses and should not be passed manually.
+- This branch is still a prototype. The worker-fragment auto-merge helper
+  expected by `runnable-lift` is not upstreamed in this repository yet, so a
+  plain checkout of this branch will emit worker fragments but will not
+  automatically merge them back into the final top-level `.ll` output.
+
 
 ## Experimental Evaluation
 

From c70b1c97bf6740c235439581611921f63113ee2f Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Fri, 1 May 2026 23:20:04 +0800
Subject: [PATCH 4/7] feat: upstream dynamic parallel merge helper

---
 README.md                                     |    8 +-
 runnable/CMakeLists.txt                       |    5 +-
 .../scripts/_merge_dynamic_fragments_lib.py   | 1816 +++++++++++++++++
 .../merge_dynamic_runnable_fragments.py       |   99 +
 .../tools/runnable-lift/CodeGenerator.cpp     |   24 +-
 test/test_merge_dynamic_runnable_fragments.py |  110 +
 6 files changed, 2052 insertions(+), 10 deletions(-)
 create mode 100644 runnable/scripts/_merge_dynamic_fragments_lib.py
 create mode 100644 runnable/scripts/merge_dynamic_runnable_fragments.py
 create mode 100644 test/test_merge_dynamic_runnable_fragments.py

diff --git a/README.md b/README.md
index d9334f77e..6de442302 100644
--- a/README.md
+++ b/README.md
@@ -107,10 +107,10 @@ Notes:
 
 - `-parallel-worker-mode` and `-parallel-seed-pc` are internal flags used by
   worker subprocesses and should not be passed manually.
-- This branch is still a prototype. The worker-fragment auto-merge helper
-  expected by `runnable-lift` is not upstreamed in this repository yet, so a
-  plain checkout of this branch will emit worker fragments but will not
-  automatically merge them back into the final top-level `.ll` output.
+- Successful worker fragments are merged back into the final top-level `.ll`
+  output with the repository helper `runnable/scripts/merge_dynamic_runnable_fragments.py`.
+- This branch is still experimental. If fragment merge fails, the coordinator
+  output and worker `.ll` fragments are still left on disk for manual inspection.
 
 
 ## Experimental Evaluation
diff --git a/runnable/CMakeLists.txt b/runnable/CMakeLists.txt
index d72f5fe9c..29f842e62 100644
--- a/runnable/CMakeLists.txt
+++ b/runnable/CMakeLists.txt
@@ -159,10 +159,14 @@ configure_file(include/runnable/Runtime/commonconstants.h "${CMAKE_BINARY_DIR}/c
 configure_file(runtime/early-linked.c "${CMAKE_BINARY_DIR}/early-linked.c" COPYONLY)
 configure_file(scripts/runnable "${CMAKE_BINARY_DIR}/runnable" COPYONLY)
 configure_file(scripts/runnable-merge-dynamic "${CMAKE_BINARY_DIR}/runnable-merge-dynamic" COPYONLY)
+configure_file(scripts/merge_dynamic_runnable_fragments.py "${CMAKE_BINARY_DIR}/merge_dynamic_runnable_fragments.py" COPYONLY)
+configure_file(scripts/_merge_dynamic_fragments_lib.py "${CMAKE_BINARY_DIR}/_merge_dynamic_fragments_lib.py" COPYONLY)
 install(PROGRAMS scripts/runnable scripts/runnable-merge-dynamic DESTINATION bin)
+install(PROGRAMS scripts/merge_dynamic_runnable_fragments.py DESTINATION share/runnable)
 install(FILES runtime/support.c DESTINATION share/runnable)
 install(FILES runtime/support.h DESTINATION share/runnable)
 install(FILES include/runnable/Runtime/commonconstants.h DESTINATION share/runnable)
+install(FILES scripts/_merge_dynamic_fragments_lib.py DESTINATION share/runnable)
 
 # Remove -rdynamic
 set(CMAKE_SHARED_LIBRARY_LINK_C_FLAGS)
@@ -171,4 +175,3 @@ set(CMAKE_SHARED_LIBRARY_LINK_C_FLAGS)
 
 install(EXPORT runnable NAMESPACE runnable:: DESTINATION share/runnable/cmake)
 
-
diff --git a/runnable/scripts/_merge_dynamic_fragments_lib.py b/runnable/scripts/_merge_dynamic_fragments_lib.py
new file mode 100644
index 000000000..e23daee5c
--- /dev/null
+++ b/runnable/scripts/_merge_dynamic_fragments_lib.py
@@ -0,0 +1,1816 @@
+#!/usr/bin/env python3
+
+import argparse
+import csv
+import json
+import os
+import re
+import shlex
+import struct
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import asdict, dataclass
+from pathlib import Path, PurePosixPath
+from typing import Dict, Iterable, List, Optional, Tuple
+
+LL_COMMENT_RE = re.compile(r"^\s*;\s*(0x[0-9a-fA-F]+):(.*)$")
+ROOT_LABEL_RE = re.compile(r"^([A-Za-z$._0-9-]+):")
+ROOT_BLOCK_LABEL_RE = re.compile(r"^bb\.0x([0-9a-fA-F]+)")
+ROOT_SYMBOLIC_BLOCK_RE = re.compile(r"^(bb\.[A-Za-z$._0-9-]+?)(?:\.0x([0-9a-fA-F]+))?(?:$|[._].*)")
+ROOT_CASE_RE = re.compile(r"^\s*i64\s+(\d+),\s+label\s+%([A-Za-z$._0-9-]+)")
+SWITCH_CASE_RE = re.compile(r"^\s*i\d+\s+(-?\d+),\s+label\s+%[A-Za-z$._0-9-]+")
+ANON_BLOCK_LABEL_RE = re.compile(r"^\s*;\s*<label>:(\d+):")
+SET_REGISTER_CASE_RE = re.compile(r"^\s*i32\s+(-?\d+),\s+label\s+%(\d+)")
+DISAM_GLOBAL_RE = re.compile(r"^(@disam_0x[0-9A-Za-z_.]+)\s*=\s*(.*)$")
+DISAM_REF_RE = re.compile(r"@disam_0x[0-9A-Za-z_.]+")
+GLOBAL_DEF_RE = re.compile(r"^(@[A-Za-z$._0-9-]+)\s*=\s*(.*)$")
+GLOBAL_REF_RE = re.compile(r"@[A-Za-z$._0-9-]+")
+I8_ARRAY_GLOBAL_DEF_RE = re.compile(
+    r"^(@[A-Za-z$._0-9-]+)\s*=.*\[(\d+) x i8\]\s+c(?:\"|')"
+)
+I8_ARRAY_GEP_REF_RE = re.compile(
+    r"\[(\d+) x i8\], \[(\d+) x i8\]\* (@[A-Za-z$._0-9-]+)"
+)
+I8_ARRAY_PTR_CAST_RE = re.compile(
+    r"\[(\d+) x i8\]\* (@[A-Za-z$._0-9-]+)(?= to i8\*)"
+)
+LIFTED_STATE_GLOBAL_RE = re.compile(
+    r"@(state_0x[0-9A-Fa-f]+|pc|r(?:ax|bx|cx|dx|bp|sp|si|di|8|9|10|11|12|13|14|15)|"
+    r"cc_(?:op|src|dst)|exception_index|cpu_loop_exiting)\b"
+)
+CPUX86STATE_GEP_RE = re.compile(r"getelementptr(?: inbounds)? %struct\.CPUX86State")
+TYPE_DEF_RE = re.compile(r"^(%[A-Za-z$._0-9-]+)\s*=\s*type\s+(.*)$")
+METADATA_DEF_RE = re.compile(r"^!(\d+)\s*=\s*(.*)$")
+METADATA_REF_RE = re.compile(r"!(\d+)")
+DEBUG_ATTACHMENT_RE = re.compile(r", !dbg !\d+")
+DEBUG_INLINE_RE = re.compile(r"\s*!dbg !\d+")
+ROOT_DROP_METADATA_RE = re.compile(
+    r", !(?:alias\.scope|noalias|oi|pi) !\d+"
+)
+LOCAL_VALUE_RE = re.compile(r"%(\d+)\b")
+DISAM_ADDR_RE = re.compile(r"0x([0-9a-fA-F]+):")
+NEWPC_ADDR_RE = re.compile(r"@newpc\(i64\s+(\d+),")
+PC_STORE_ADDR_RE = re.compile(r"store i64\s+(\d+), i64\* @pc")
+REFERENCE_ENTRY_RE = re.compile(r"entry_0x([0-9a-fA-F]+)")
+ROOT_COMMON_LABELS = {
+    "entrypoint",
+    "dispatcher.entry",
+    "dispatcher.default",
+    "anypc",
+    "unexpectedpc",
+    "serialize_and_jump_out",
+    "return_from_external",
+    "setjmp",
+    "dispatcher.external",
+}
+ROOT_RICH_COMMON_LABELS = {
+    "serialize_and_jump_out",
+    "return_from_external",
+}
+ROOT_COMMON_FEATURE_REFS = (
+    "@pc",
+    "@rax",
+    "@rbx",
+    "@rcx",
+    "@rdx",
+    "@rbp",
+    "@rsp",
+    "@rsi",
+    "@rdi",
+    "@r8",
+    "@r9",
+    "@r10",
+    "@r11",
+    "@r12",
+    "@r13",
+    "@r14",
+    "@r15",
+    "@state_0x8558",
+    "@state_0x8598",
+    "@state_0x85d8",
+    "@state_0x8618",
+    "@state_0x8658",
+    "@state_0x8698",
+    "@state_0x86d8",
+    "@state_0x8718",
+)
+SERIALIZE_GPRS = (
+    ("rax", "@rax"),
+    ("rbx", "@rbx"),
+    ("rcx", "@rcx"),
+    ("rdx", "@rdx"),
+    ("rbp", "@rbp"),
+    ("rsp", "@rsp"),
+    ("rsi", "@rsi"),
+    ("rdi", "@rdi"),
+    ("r8", "@r8"),
+    ("r9", "@r9"),
+    ("r10", "@r10"),
+    ("r11", "@r11"),
+    ("r12", "@r12"),
+    ("r13", "@r13"),
+    ("r14", "@r14"),
+    ("r15", "@r15"),
+)
+XMM_STATE_GLOBALS = (
+    ("xmm0", "@state_0x8558"),
+    ("xmm1", "@state_0x8598"),
+    ("xmm2", "@state_0x85d8"),
+    ("xmm3", "@state_0x8618"),
+    ("xmm4", "@state_0x8658"),
+    ("xmm5", "@state_0x8698"),
+    ("xmm6", "@state_0x86d8"),
+    ("xmm7", "@state_0x8718"),
+)
+RETURN_FROM_EXTERNAL_SLOTS = (
+    ("pc", "@pc", 16),
+    ("rax", "@rax", 13),
+    ("rbx", "@rbx", 11),
+    ("rcx", "@rcx", 14),
+    ("rdx", "@rdx", 12),
+    ("rbp", "@rbp", 10),
+    ("rsp", "@rsp", 15),
+    ("rsi", "@rsi", 9),
+    ("rdi", "@rdi", 8),
+    ("r8", "@r8", 0),
+    ("r9", "@r9", 1),
+    ("r10", "@r10", 2),
+    ("r11", "@r11", 3),
+    ("r12", "@r12", 4),
+    ("r13", "@r13", 5),
+    ("r14", "@r14", 6),
+    ("r15", "@r15", 7),
+)
+
+
+@dataclass(frozen=True)
+class ShardJob:
+    index: int
+    start: int
+    end_inclusive: int
+    name: str
+    range_min: int
+    range_max: int
+    exact_end_exclusive: int
+
+    @property
+    def tag(self) -> str:
+        return f"fn_{self.start:016x}"
+
+
+@dataclass(frozen=True)
+class RootBlockSegment:
+    label: str
+    base_addr: int
+    order_index: int
+    lines: List[str]
+
+
+@dataclass(frozen=True)
+class ParsedRoot:
+    define_line: str
+    entry_label: str
+    entry_allocas: List[str]
+    entry_rest: List[str]
+    dispatcher_prefix: List[str]
+    dispatcher_footer: List[str]
+    dispatcher_cases: Dict[int, str]
+    common_segments: Dict[str, List[str]]
+    translated_segments: List[RootBlockSegment]
+    globals: Dict[str, str]
+    disam_globals: Dict[str, str]
+    metadata_defs: Dict[int, str]
+
+
+@dataclass(frozen=True)
+class ParsedModule:
+    type_defs_by_name: Dict[str, str]
+    globals_by_name: Dict[str, List[str]]
+    functions_by_name: Dict[str, List[str]]
+    function_kinds: Dict[str, str]
+    type_order: List[str]
+    global_order: List[str]
+    function_order: List[str]
+
+
+class Config:
+    def __init__(self, args: argparse.Namespace):
+        self.container_name = args.container_name
+        self.run_dir = args.run_dir.resolve()
+        self.out_dir = args.out_dir.resolve()
+        self.funcs_csv = args.funcs_csv.resolve()
+        self.reference_ll = args.reference_ll.resolve()
+        self.ground_truth_binary = args.ground_truth_binary.resolve()
+        self.run_cmp_eval = args.run_cmp_eval.resolve()
+        self.container_workdir = PurePosixPath(args.container_workdir)
+        self.container_binary = args.container_binary
+        self.runnable_lift = args.runnable_lift
+        self.rebase_base = args.rebase_base
+        self.csv_image_base = args.csv_image_base
+        self.range_margin = args.range_margin
+        self.func_timeout = args.func_timeout
+        self.workers = args.workers
+        self.max_repair_rounds = args.max_repair_rounds
+        self.repair_timeout_multiplier = args.repair_timeout_multiplier
+        self.repair_margin_step = args.repair_margin_step
+        self.limit = args.limit
+        self.super_fast = args.super_fast
+        self.rerun_all_on_metric_gap = args.rerun_all_on_metric_gap
+        self.force = args.force
+        self.keep_raw_on_success = args.keep_raw_on_success
+        self.shards_dir = self.out_dir / "shards"
+        self.raw_dir = self.out_dir / "raw"
+        self.eval_dir = self.out_dir / "eval"
+        self.round_reports_dir = self.out_dir / "round_reports"
+        self.logs_dir = self.out_dir / "logs"
+        self.manifest_json = self.out_dir / "shard_results.json"
+        self.manifest_jsonl = self.out_dir / "shard_results.jsonl"
+        self.status_json = self.out_dir / "status.json"
+        self.merged_ll = self.out_dir / "merged.ll"
+        self.merged_full_ll = self.out_dir / "merged_full.ll"
+        self.delta_json = self.eval_dir / "delta.json"
+        self.parallel_eval_json = self.eval_dir / "parallel.eval.json"
+        self.parallel_eval_txt = self.eval_dir / "parallel.eval.txt"
+        self.reference_eval_json = self.eval_dir / "reference.eval.json"
+        self.reference_eval_txt = self.eval_dir / "reference.eval.txt"
+        self.final_report_json = self.out_dir / "final_report.json"
+        self.final_report_md = self.out_dir / "final_report.md"
+
+        if self.workers < 1 or self.workers > 100:
+            raise ValueError("--workers must be within [1, 100]")
+        if not self.out_dir.is_relative_to(self.run_dir):
+            raise ValueError("--out-dir must live under the mounted run dir")
+
+        rel = self.out_dir.relative_to(self.run_dir)
+        self.container_out_dir = self.container_workdir.joinpath(*rel.parts)
+        self.container_shards_dir = self.container_out_dir / "shards"
+        self.container_raw_dir = self.container_out_dir / "raw"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run the libcrypto address-ranged parallel lift workflow."
+    )
+    parser.add_argument("--container-name", default=DEFAULT_CONTAINER_NAME)
+    parser.add_argument("--run-dir", type=Path, default=DEFAULT_RUN_DIR)
+    parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT_DIR)
+    parser.add_argument("--funcs-csv", type=Path, default=DEFAULT_FUNCS_CSV)
+    parser.add_argument("--reference-ll", type=Path, default=DEFAULT_REFERENCE_LL)
+    parser.add_argument("--ground-truth-binary", type=Path, default=DEFAULT_GROUND_TRUTH)
+    parser.add_argument("--run-cmp-eval", type=Path, default=DEFAULT_RUN_CMP_EVAL)
+    parser.add_argument("--container-workdir", default=DEFAULT_CONTAINER_WORKDIR)
+    parser.add_argument("--container-binary", default=DEFAULT_CONTAINER_BINARY)
+    parser.add_argument("--runnable-lift", default=DEFAULT_RUNNABLE_LIFT)
+    parser.add_argument("--rebase-base", type=lambda v: int(v, 0), default=0x50000000)
+    parser.add_argument("--csv-image-base", type=lambda v: int(v, 0), default=DEFAULT_CSV_IMAGE_BASE)
+    parser.add_argument("--range-margin", type=int, default=0)
+    parser.add_argument("--func-timeout", type=int, default=30)
+    parser.add_argument("--workers", type=int, default=100)
+    parser.add_argument("--max-repair-rounds", type=int, default=5)
+    parser.add_argument("--repair-timeout-multiplier", type=float, default=2.0)
+    parser.add_argument("--repair-margin-step", type=int, default=32)
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--super-fast", dest="super_fast", action="store_true", default=True)
+    parser.add_argument("--no-super-fast", dest="super_fast", action="store_false")
+    parser.add_argument(
+        "--rerun-all-on-metric-gap",
+        dest="rerun_all_on_metric_gap",
+        action="store_true",
+        default=True,
+        help="When metrics are still below reference but no shards explicitly failed, rerun all shards.",
+    )
+    parser.add_argument(
+        "--no-rerun-all-on-metric-gap",
+        dest="rerun_all_on_metric_gap",
+        action="store_false",
+        help="Stop the repair loop when only a metric gap remains and no shards explicitly failed.",
+    )
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--keep-raw-on-success", action="store_true")
+    return parser.parse_args()
+
+
+def log(msg: str) -> None:
+    ts = time.strftime("%F %T")
+    print(f"[{ts}] {msg}", flush=True)
+
+
+def run_cmd(
+    cmd: List[str],
+    *,
+    check: bool = True,
+    capture_output: bool = True,
+    cwd: Optional[Path] = None,
+) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        cmd,
+        check=check,
+        cwd=str(cwd) if cwd else None,
+        text=True,
+        capture_output=capture_output,
+    )
+
+
+def docker_exec(
+    config: Config,
+    shell_command: str,
+    *,
+    check: bool = True,
+    capture_output: bool = True,
+) -> subprocess.CompletedProcess:
+    return run_cmd(
+        ["docker", "exec", config.container_name, "bash", "-lc", shell_command],
+        check=check,
+        capture_output=capture_output,
+    )
+
+
+def ensure_paths(config: Config) -> None:
+    for path in (
+        config.run_dir,
+        config.funcs_csv,
+        config.reference_ll,
+        config.ground_truth_binary,
+        config.run_cmp_eval,
+    ):
+        if not path.exists():
+            raise FileNotFoundError(path)
+    config.out_dir.mkdir(parents=True, exist_ok=True)
+    config.shards_dir.mkdir(parents=True, exist_ok=True)
+    config.raw_dir.mkdir(parents=True, exist_ok=True)
+    config.eval_dir.mkdir(parents=True, exist_ok=True)
+    config.round_reports_dir.mkdir(parents=True, exist_ok=True)
+    config.logs_dir.mkdir(parents=True, exist_ok=True)
+
+
+def require_addr_range_support(config: Config) -> Dict[str, object]:
+    help_result = docker_exec(
+        config,
+        f"{shlex.quote(config.runnable_lift)} --help 2>&1",
+        capture_output=True,
+    )
+    if "addr-range-min" not in help_result.stdout or "addr-range-max" not in help_result.stdout:
+        raise RuntimeError(
+            "runnable-lift does not expose --addr-range-min/max; rebuild the container binary first"
+        )
+    info_result = docker_exec(
+        config,
+        "python3 --version && nproc && "
+        + shlex.quote(config.runnable_lift)
+        + " --help 2>&1 | grep -n 'addr-range'",
+        capture_output=True,
+    )
+    return {
+        "help_lines": [line for line in info_result.stdout.splitlines() if "addr-range" in line],
+        "runtime_info": info_result.stdout.splitlines()[:2],
+    }
+
+
+def load_jobs(config: Config) -> List[ShardJob]:
+    jobs: List[ShardJob] = []
+    with config.funcs_csv.open("r", encoding="utf-8") as handle:
+        reader = csv.DictReader(handle)
+        for index, row in enumerate(reader):
+            start = int(row["addr_hex"], 16)
+            end_inclusive = int(row["end_hex"], 16)
+            if end_inclusive < start:
+                continue
+            if start < config.csv_image_base or end_inclusive < config.csv_image_base:
+                raise ValueError(
+                    f"function address {hex(start)} is below csv image base {hex(config.csv_image_base)}"
+                )
+            exact_end_exclusive = end_inclusive + 1
+            rebased_start = config.rebase_base + (start - config.csv_image_base)
+            rebased_end_exclusive = config.rebase_base + (
+                exact_end_exclusive - config.csv_image_base
+            )
+            jobs.append(
+                ShardJob(
+                    index=index,
+                    start=start,
+                    end_inclusive=end_inclusive,
+                    name=row.get("name", f"sub_{start:x}"),
+                    range_min=rebased_start,
+                    range_max=rebased_end_exclusive + config.range_margin,
+                    exact_end_exclusive=rebased_end_exclusive,
+                )
+            )
+    if config.limit > 0:
+        jobs = jobs[: config.limit]
+    return jobs
+
+
+def load_existing_results(config: Config) -> Dict[str, Dict[str, object]]:
+    if not config.manifest_json.exists():
+        return {}
+    with config.manifest_json.open("r", encoding="utf-8") as handle:
+        items = json.load(handle)
+    return {item["tag"]: item for item in items}
+
+
+def write_manifest(config: Config, items: Iterable[Dict[str, object]]) -> None:
+    ordered = sorted(items, key=lambda item: item["start"])
+    with config.manifest_json.open("w", encoding="utf-8") as handle:
+        json.dump(ordered, handle, indent=2, sort_keys=True)
+
+
+def compact_ll(raw_ll: Path, compact_ll_path: Path, start: int, end_exclusive: int) -> int:
+    last_seen: Dict[int, str] = {}
+    with raw_ll.open("r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            match = LL_COMMENT_RE.match(line)
+            if match is None:
+                continue
+            addr = int(match.group(1), 16)
+            if start <= addr < end_exclusive:
+                last_seen[addr] = line.rstrip("\n")
+    with compact_ll_path.open("w", encoding="utf-8") as handle:
+        for addr in sorted(last_seen):
+            handle.write(last_seen[addr] + "\n")
+    return len(last_seen)
+
+
+def filter_coverage_csv(raw_cov: Path, compact_cov: Path, start: int, end_exclusive: int) -> None:
+    if not raw_cov.exists():
+        return
+    rows: List[str] = []
+    with raw_cov.open("r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            line = line.rstrip("\n")
+            if not line:
+                continue
+            parts = line.split(",")
+            try:
+                addr = int(parts[0], 16)
+            except ValueError:
+                continue
+            if start <= addr < end_exclusive:
+                rows.append(line)
+    compact_cov.write_text("\n".join(rows) + ("\n" if rows else ""), encoding="utf-8")
+
+
+def delete_if_exists(path: Path) -> None:
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        return
+
+
+def container_path(path: PurePosixPath) -> str:
+    return shlex.quote(str(path))
+
+
+def shell_bool(enabled: bool, flag: str) -> str:
+    return flag + " " if enabled else ""
+
+
+def run_shard(
+    config: Config,
+    job: ShardJob,
+    *,
+    timeout_sec: int,
+    range_margin: int,
+    super_fast: bool,
+) -> Dict[str, object]:
+    shard_ll = config.shards_dir / f"{job.tag}.ll"
+    shard_cov = config.shards_dir / f"{job.tag}.ll.coverage.csv"
+    shard_li = config.shards_dir / f"{job.tag}.ll.li.csv"
+    shard_need = config.shards_dir / f"{job.tag}.ll.need.csv"
+    shard_illegal = config.shards_dir / f"{job.tag}.ll.illegalEntry.log"
+    shard_stdout = config.shards_dir / f"{job.tag}.stdout.log"
+    shard_stderr = config.shards_dir / f"{job.tag}.stderr.log"
+
+    raw_ll = config.raw_dir / f"{job.tag}.raw.ll"
+    raw_cov = config.raw_dir / f"{job.tag}.raw.coverage.csv"
+    raw_stdout = config.raw_dir / f"{job.tag}.stdout.log"
+    raw_stderr = config.raw_dir / f"{job.tag}.stderr.log"
+    raw_exit = config.raw_dir / f"{job.tag}.exitcode"
+    raw_li = config.raw_dir / f"{job.tag}.raw.ll.li.csv"
+    raw_need = config.raw_dir / f"{job.tag}.raw.ll.need.csv"
+    raw_illegal = config.raw_dir / f"{job.tag}.raw.ll.illegalEntry.log"
+
+    c_raw_ll = config.container_raw_dir / raw_ll.name
+    c_raw_cov = config.container_raw_dir / raw_cov.name
+    c_raw_stdout = config.container_raw_dir / raw_stdout.name
+    c_raw_stderr = config.container_raw_dir / raw_stderr.name
+    c_raw_exit = config.container_raw_dir / raw_exit.name
+
+    range_max = job.exact_end_exclusive + range_margin
+    shell = (
+        "set +e\n"
+        f"mkdir -p {container_path(config.container_raw_dir)}\n"
+        f"rm -f {container_path(c_raw_ll)} {container_path(c_raw_cov)} "
+        f"{container_path(c_raw_stdout)} {container_path(c_raw_stderr)} {container_path(c_raw_exit)}\n"
+        f"timeout {timeout_sec} {shlex.quote(config.runnable_lift)} "
+        f"{shell_bool(super_fast, '-super-fast')}"
+        f"-entry=0x{job.range_min:x} "
+        f"-addr-range-min 0x{job.range_min:x} "
+        f"-addr-range-max 0x{range_max:x} "
+        f"-coverage-path {container_path(c_raw_cov)} "
+        f"{shlex.quote(config.container_binary)} {container_path(c_raw_ll)} "
+        f"> {container_path(c_raw_stdout)} 2> {container_path(c_raw_stderr)}\n"
+        "rc=$?\n"
+        f"printf '%s' \"$rc\" > {container_path(c_raw_exit)}\n"
+        "exit 0\n"
+    )
+    infra_rc = docker_exec(config, shell, check=False, capture_output=True).returncode
+
+    try:
+        raw_rc = int(raw_exit.read_text(encoding="utf-8").strip())
+    except FileNotFoundError:
+        raw_rc = infra_rc
+
+    if raw_ll.exists():
+        compact_count = compact_ll(raw_ll, shard_ll, job.range_min, range_max)
+    else:
+        compact_count = 0
+        delete_if_exists(shard_ll)
+
+    filter_coverage_csv(raw_cov, shard_cov, job.range_min, range_max)
+
+    if raw_li.exists():
+        raw_li.replace(shard_li)
+    else:
+        delete_if_exists(shard_li)
+    if raw_need.exists():
+        raw_need.replace(shard_need)
+    else:
+        delete_if_exists(shard_need)
+    if raw_illegal.exists():
+        raw_illegal.replace(shard_illegal)
+    else:
+        delete_if_exists(shard_illegal)
+
+    status = "ok"
+    if raw_rc == 124:
+        status = "timeout"
+    elif raw_rc != 0:
+        status = "error"
+    elif compact_count == 0:
+        status = "empty"
+
+    keep_logs = status != "ok"
+    if keep_logs:
+        if raw_stdout.exists():
+            raw_stdout.replace(shard_stdout)
+        if raw_stderr.exists():
+            raw_stderr.replace(shard_stderr)
+    else:
+        delete_if_exists(raw_stdout)
+        delete_if_exists(raw_stderr)
+        delete_if_exists(shard_stdout)
+        delete_if_exists(shard_stderr)
+
+    if status == "ok" and not config.keep_raw_on_success:
+        delete_if_exists(raw_cov)
+        delete_if_exists(raw_exit)
+
+    return {
+        "tag": job.tag,
+        "index": job.index,
+        "name": job.name,
+        "start": job.start,
+        "end_inclusive": job.end_inclusive,
+        "entry_rebased": job.range_min,
+        "range_max_used": range_max,
+        "exact_end_exclusive": job.exact_end_exclusive,
+        "timeout_sec": timeout_sec,
+        "range_margin": range_margin,
+        "super_fast": super_fast,
+        "status": status,
+        "raw_rc": raw_rc,
+        "raw_ll": str(raw_ll) if raw_ll.exists() else None,
+        "compact_instruction_count": compact_count,
+        "shard_ll": str(shard_ll),
+        "coverage_csv": str(shard_cov),
+        "stderr_log": str(shard_stderr) if shard_stderr.exists() else None,
+        "stdout_log": str(shard_stdout) if shard_stdout.exists() else None,
+    }
+
+
+def run_jobs(
+    config: Config,
+    jobs: List[ShardJob],
+    existing: Dict[str, Dict[str, object]],
+    *,
+    timeout_sec: int,
+    range_margin: int,
+    super_fast: bool,
+    force_tags: Optional[set] = None,
+) -> Dict[str, Dict[str, object]]:
+    results = dict(existing)
+    force_tags = force_tags or set()
+    pending: List[ShardJob] = []
+    for job in jobs:
+        if config.force or job.tag in force_tags:
+            pending.append(job)
+            continue
+        cached = results.get(job.tag)
+        if cached is None:
+            pending.append(job)
+            continue
+        if cached.get("status") != "ok":
+            pending.append(job)
+            continue
+        shard_ll = Path(cached["shard_ll"])
+        if not shard_ll.exists():
+            pending.append(job)
+            continue
+
+    total = len(jobs)
+    completed = total - len(pending)
+    count_lock = threading.Lock()
+    if pending:
+        log(f"Launching {len(pending)} shard jobs with {config.workers} workers")
+    else:
+        log("All shard jobs already present; reusing cached results")
+
+    with ThreadPoolExecutor(max_workers=config.workers) as executor:
+        futures = {
+            executor.submit(
+                run_shard,
+                config,
+                job,
+                timeout_sec=timeout_sec,
+                range_margin=range_margin,
+                super_fast=super_fast,
+            ): job
+            for job in pending
+        }
+        for future in as_completed(futures):
+            result = future.result()
+            job = futures[future]
+            results[job.tag] = result
+            with count_lock:
+                completed += 1
+                if completed % 100 == 0 or completed == total:
+                    ok_total = sum(1 for item in results.values() if item.get("status") == "ok")
+                    compact_total = sum(
+                        item.get("compact_instruction_count", 0)
+                        for item in results.values()
+                    )
+                    log(
+                        f"[{completed}/{total}] ok={ok_total} "
+                        f"compact_instructions={compact_total}"
+                    )
+    return results
+
+
+def merge_shards(config: Config, results: Dict[str, Dict[str, object]]) -> Dict[str, object]:
+    merged: Dict[int, str] = {}
+    shard_count = 0
+    for item in sorted(results.values(), key=lambda value: value["start"]):
+        if item["status"] != "ok":
+            continue
+        shard_path = Path(item["shard_ll"])
+        if not shard_path.exists():
+            continue
+        shard_count += 1
+        with shard_path.open("r", encoding="utf-8", errors="ignore") as handle:
+            for line in handle:
+                match = LL_COMMENT_RE.match(line)
+                if match is None:
+                    continue
+                merged[int(match.group(1), 16)] = line.rstrip("\n")
+    with config.merged_ll.open("w", encoding="utf-8") as handle:
+        for addr in sorted(merged):
+            handle.write(merged[addr] + "\n")
+    merge_info = {
+        "merged_ll": str(config.merged_ll),
+        "unique_instruction_count": len(merged),
+        "successful_shards": shard_count,
+    }
+    merge_info.update(merge_full_module(config, results))
+    return merge_info
+
+
+def strip_root_debug_line(line: str) -> Optional[str]:
+    if "@llvm.dbg." in line:
+        return None
+    line = DEBUG_ATTACHMENT_RE.sub("", line)
+    line = DEBUG_INLINE_RE.sub("", line)
+    line = ROOT_DROP_METADATA_RE.sub("", line)
+    return line
+
+
+def root_block_addr(label: str) -> Optional[int]:
+    match = ROOT_BLOCK_LABEL_RE.match(label)
+    if match is None:
+        return None
+    return int(match.group(1), 16)
+
+
+def disam_addr_from_definition(definition: Optional[str]) -> Optional[int]:
+    if definition is None:
+        return None
+    match = DISAM_ADDR_RE.search(definition)
+    if match is None:
+        return None
+    return int(match.group(1), 16)
+
+
+def infer_symbolic_block_addr(
+    label: str,
+    lines: List[str],
+    *,
+    dispatcher_label_addrs: Dict[str, int],
+    disam_globals: Dict[str, str],
+) -> Optional[int]:
+    direct_addr = dispatcher_label_addrs.get(label)
+    if direct_addr is not None:
+        return direct_addr
+
+    if label.startswith("bb."):
+        direct_disam = disam_addr_from_definition(disam_globals.get(f"@disam_{label[3:]}"))
+        if direct_disam is not None:
+            return direct_disam
+
+    symbolic_match = ROOT_SYMBOLIC_BLOCK_RE.match(label)
+    if symbolic_match is not None:
+        root_label = symbolic_match.group(1)
+        offset_hex = symbolic_match.group(2)
+        if offset_hex is not None:
+            root_addr = dispatcher_label_addrs.get(root_label)
+            if root_addr is None and root_label.startswith("bb."):
+                root_addr = disam_addr_from_definition(disam_globals.get(f"@disam_{root_label[3:]}"))
+            if root_addr is not None:
+                return root_addr + int(offset_hex, 16)
+
+    for line in lines:
+        match = NEWPC_ADDR_RE.search(line)
+        if match is not None:
+            return int(match.group(1))
+        match = PC_STORE_ADDR_RE.search(line)
+        if match is not None:
+            return int(match.group(1))
+
+    return None
+
+
+def find_root_bounds(lines: List[str]) -> Tuple[int, int]:
+    start = next(index for index, line in enumerate(lines) if line.startswith("define void @root("))
+    depth = lines[start].count("{") - lines[start].count("}")
+    end = start + 1
+    while end < len(lines):
+        depth += lines[end].count("{") - lines[end].count("}")
+        if depth == 0:
+            end += 1
+            break
+        end += 1
+    return start, end
+
+
+def extract_root(raw_ll: Path) -> ParsedRoot:
+    lines = raw_ll.read_text(encoding="utf-8", errors="ignore").splitlines()
+    globals_by_name: Dict[str, str] = {}
+    disam_globals: Dict[str, str] = {}
+    metadata_defs: Dict[int, str] = {}
+    for line in lines:
+        global_match = GLOBAL_DEF_RE.match(line)
+        if global_match is not None:
+            globals_by_name[global_match.group(1)] = line
+        disam_match = DISAM_GLOBAL_RE.match(line)
+        if disam_match is not None:
+            disam_globals[disam_match.group(1)] = line
+            continue
+        metadata_match = METADATA_DEF_RE.match(line)
+        if metadata_match is not None:
+            metadata_defs[int(metadata_match.group(1))] = metadata_match.group(2)
+
+    root_start, root_end = find_root_bounds(lines)
+    root_lines = lines[root_start:root_end]
+
+    segments: Dict[str, List[str]] = {}
+    segment_order: List[str] = []
+    current_label: Optional[str] = None
+    current_lines: List[str] = []
+
+    for line in root_lines[1:-1]:
+        match = ROOT_LABEL_RE.match(line)
+        if match is not None:
+            if current_label is not None:
+                segments[current_label] = current_lines
+                segment_order.append(current_label)
+            current_label = match.group(1)
+            current_lines = [line]
+            continue
+        if current_label is not None:
+            current_lines.append(line)
+    if current_label is not None:
+        segments[current_label] = current_lines
+        segment_order.append(current_label)
+
+    define_line = strip_root_debug_line(root_lines[0])
+    if define_line is None:
+        raise RuntimeError(f"unexpected dbg-only root definition in {raw_ll}")
+
+    entry_segment = [line for line in (strip_root_debug_line(line) for line in segments["entrypoint"]) if line is not None]
+    entry_label = entry_segment[0]
+    entry_allocas: List[str] = []
+    entry_rest: List[str] = []
+    seen_non_alloca = False
+    for line in entry_segment[1:]:
+        if not seen_non_alloca and " alloca " in line:
+            entry_allocas.append(line)
+            continue
+        seen_non_alloca = True
+        entry_rest.append(line)
+
+    dispatcher_segment = [
+        line
+        for line in (strip_root_debug_line(line) for line in segments["dispatcher.entry"])
+        if line is not None
+    ]
+    switch_index = next(index for index, line in enumerate(dispatcher_segment) if "switch i64 " in line)
+    switch_end = next(
+        index for index in range(switch_index + 1, len(dispatcher_segment))
+        if dispatcher_segment[index].lstrip().startswith("]")
+    )
+    dispatcher_cases: Dict[int, str] = {}
+    for line in dispatcher_segment[switch_index + 1:switch_end]:
+        match = ROOT_CASE_RE.match(line)
+        if match is None:
+            continue
+        dispatcher_cases[int(match.group(1))] = line
+    dispatcher_label_addrs = {
+        ROOT_CASE_RE.match(line).group(2): int(ROOT_CASE_RE.match(line).group(1))
+        for line in dispatcher_cases.values()
+        if ROOT_CASE_RE.match(line) is not None
+    }
+
+    common_segments: Dict[str, List[str]] = {}
+    translated_segments: List[RootBlockSegment] = []
+    translated_order = 0
+    for label in segment_order:
+        if label in {"entrypoint", "dispatcher.entry"}:
+            continue
+        cleaned = [line for line in (strip_root_debug_line(line) for line in segments[label]) if line is not None]
+        if label in ROOT_COMMON_LABELS:
+            common_segments[label] = cleaned
+            continue
+        base_addr = root_block_addr(label)
+        if base_addr is None:
+            base_addr = infer_symbolic_block_addr(
+                label,
+                cleaned,
+                dispatcher_label_addrs=dispatcher_label_addrs,
+                disam_globals=disam_globals,
+            )
+        if base_addr is None:
+            base_addr = (1 << 62) + translated_order
+        translated_segments.append(
+            RootBlockSegment(
+                label=label,
+                base_addr=base_addr,
+                order_index=translated_order,
+                lines=cleaned,
+            )
+        )
+        translated_order += 1
+
+    return ParsedRoot(
+        define_line=define_line,
+        entry_label=entry_label,
+        entry_allocas=entry_allocas,
+        entry_rest=entry_rest,
+        dispatcher_prefix=dispatcher_segment[:switch_index + 1],
+        dispatcher_footer=dispatcher_segment[switch_end:],
+        dispatcher_cases=dispatcher_cases,
+        common_segments=common_segments,
+        translated_segments=translated_segments,
+        globals=globals_by_name,
+        disam_globals=disam_globals,
+        metadata_defs=metadata_defs,
+    )
+
+
+def parse_reference_entry_pc(reference_ll: Path) -> Optional[int]:
+    match = REFERENCE_ENTRY_RE.search(reference_ll.name)
+    if match is None:
+        return None
+    return int(match.group(1), 16)
+
+
+def read_elf_entry_pc(binary_path: Path) -> Optional[int]:
+    try:
+        header = binary_path.read_bytes()[:64]
+    except OSError:
+        return None
+    if len(header) < 24 or header[:4] != b"\x7fELF":
+        return None
+
+    elf_class = header[4]
+    data_encoding = header[5]
+    if data_encoding == 1:
+        endian = "<"
+    elif data_encoding == 2:
+        endian = ">"
+    else:
+        return None
+
+    if elf_class == 1:
+        if len(header) < 28:
+            return None
+        return struct.unpack_from(f"{endian}I", header, 24)[0]
+    if elf_class == 2:
+        if len(header) < 32:
+            return None
+        return struct.unpack_from(f"{endian}Q", header, 24)[0]
+    return None
+
+
+def determine_root_entry_pc(config: object) -> Tuple[Optional[int], str]:
+    explicit_entry_pc = getattr(config, "entry_pc", None)
+    if explicit_entry_pc is not None:
+        return int(explicit_entry_pc), "config.entry_pc"
+
+    reference_ll = getattr(config, "reference_ll", None)
+    if reference_ll:
+        parsed = parse_reference_entry_pc(Path(reference_ll))
+        if parsed is not None:
+            return parsed, "reference_ll"
+
+    ground_truth_binary = getattr(config, "ground_truth_binary", None)
+    if ground_truth_binary:
+        parsed = read_elf_entry_pc(Path(ground_truth_binary))
+        if parsed is not None:
+            return parsed, "ground_truth_binary"
+
+    return None, "base_root"
+
+
+def rewrite_root_entry_rest(entry_rest: List[str], entry_pc: int) -> Tuple[List[str], Optional[int], bool]:
+    rewritten: List[str] = []
+    previous_pc: Optional[int] = None
+    replaced = False
+    for line in entry_rest:
+        if not replaced:
+            match = PC_STORE_ADDR_RE.search(line)
+            if match is not None:
+                previous_pc = int(match.group(1))
+                rewritten.append(
+                    line[:match.start(1)] + str(entry_pc) + line[match.end(1):]
+                )
+                replaced = True
+                continue
+        rewritten.append(line)
+    return rewritten, previous_pc, replaced
+
+
+def common_segment_score(lines: List[str]) -> Tuple[int, int]:
+    text = "\n".join(lines)
+    feature_count = sum(1 for ref in ROOT_COMMON_FEATURE_REFS if ref in text)
+    return feature_count, len(lines)
+
+
+def function_symbol_score(symbol_lines: List[str]) -> Tuple[int, int, int, int]:
+    text = "\n".join(symbol_lines)
+    lifted_state_refs = len(LIFTED_STATE_GLOBAL_RE.findall(text))
+    cpux86state_geps = len(CPUX86STATE_GEP_RE.findall(text))
+    lowered_state_score = 0
+    if "%struct.CPUX86State" in text:
+        lowered_state_score = (lifted_state_refs * 10) - cpux86state_geps
+    return lowered_state_score, switch_case_count(symbol_lines), len(symbol_lines), -cpux86state_geps
+
+
+def find_segment_line(variants: List[List[str]], pattern: str) -> Optional[str]:
+    for lines in variants:
+        for line in lines:
+            if pattern in line:
+                return line
+    return None
+
+
+def build_serialize_and_jump_out_union(
+    variants: List[List[str]],
+    *,
+    available_globals: set,
+) -> Optional[List[str]]:
+    if not variants:
+        return None
+
+    jump_line = find_segment_line(variants, 'jmpq *%r11')
+    unreachable_line = find_segment_line(variants, "unreachable")
+    if jump_line is None or unreachable_line is None:
+        return None
+
+    lines = ["serialize_and_jump_out:"]
+    for reg_name, global_name in SERIALIZE_GPRS:
+        if global_name not in available_globals:
+            continue
+        lines.append(
+            f'  call void asm sideeffect "movq $0, %{reg_name}", '
+            f'"*m,~{{{reg_name}}},~{{dirflag}},~{{fpsr}},~{{flags}}"(i64* {global_name})'
+        )
+    for xmm_name, global_name in XMM_STATE_GLOBALS:
+        if global_name not in available_globals:
+            continue
+        lines.append(
+            f'  call void asm sideeffect "movq $0, %{xmm_name}", '
+            f'"*m,~{{{xmm_name}}},~{{dirflag}},~{{fpsr}},~{{flags}}"(i64* {global_name})'
+        )
+    lines.append(jump_line)
+    lines.append(unreachable_line)
+    return lines
+
+
+def build_return_from_external_union(
+    variants: List[List[str]],
+    *,
+    available_globals: set,
+) -> Optional[List[str]]:
+    if not variants:
+        return None
+
+    br_line = find_segment_line(variants, "br label %dispatcher.entry")
+    if br_line is None:
+        return None
+
+    lines = ["return_from_external:"]
+    for reg_name, global_name, slot in RETURN_FROM_EXTERNAL_SLOTS:
+        if global_name not in available_globals:
+            continue
+        base_name = f"%return_from_external_{reg_name}_base"
+        ptr_name = f"%return_from_external_{reg_name}_ptr"
+        value_name = f"%return_from_external_{reg_name}_value"
+        lines.append(f"  {base_name} = load i64*, i64** @saved_registers")
+        lines.append(f"  {ptr_name} = getelementptr i64, i64* {base_name}, i32 {slot}")
+        lines.append(f"  {value_name} = load i64, i64* {ptr_name}")
+        lines.append(f"  store i64 {value_name}, i64* {global_name}")
+    for xmm_name, global_name in XMM_STATE_GLOBALS:
+        if global_name not in available_globals:
+            continue
+        lines.append(
+            f'  call void asm sideeffect "movq %{xmm_name}, $0", '
+            f'"*m,~{{}},~{{dirflag}},~{{fpsr}},~{{flags}}"(i64* {global_name})'
+        )
+    lines.append(br_line)
+    return lines
+
+
+def import_root_segment_refs(
+    lines: List[str],
+    *,
+    root: ParsedRoot,
+    base_global_names: set,
+    base_disam_names: set,
+    imported_extra_globals: Dict[str, List[str]],
+    imported_disam_globals: Dict[str, str],
+) -> None:
+    segment_text = "\n".join(lines)
+    for disam_ref in DISAM_REF_RE.findall(segment_text):
+        if disam_ref in base_disam_names:
+            continue
+        definition = root.disam_globals.get(disam_ref)
+        if definition is not None:
+            imported_disam_globals[disam_ref] = definition
+    for global_ref in GLOBAL_REF_RE.findall(segment_text):
+        if global_ref in base_global_names or global_ref in imported_disam_globals:
+            continue
+        definition = root.globals.get(global_ref)
+        if definition is not None:
+            imported_extra_globals[global_ref] = sanitize_imported_symbol([definition])
+
+
+def rename_local_values(lines: List[str], prefix: str) -> List[str]:
+    return [LOCAL_VALUE_RE.sub(lambda match: f"%{prefix}_{match.group(1)}", line) for line in lines]
+
+
+def normalize_root_local_values(lines: List[str]) -> List[str]:
+    if not lines:
+        return []
+    define_line = lines[0].replace("@root(i64)", "@root(i64 %root_0)", 1)
+    return [define_line] + rename_local_values(lines[1:], "root")
+
+
+def strip_imported_line(line: str) -> Optional[str]:
+    if "@llvm.dbg." in line:
+        return None
+    line = DEBUG_ATTACHMENT_RE.sub("", line)
+    line = DEBUG_INLINE_RE.sub("", line)
+    line = re.sub(r", ![A-Za-z0-9_.-]+ !\d+", "", line)
+    return line
+
+
+def sanitize_imported_symbol(lines: List[str]) -> List[str]:
+    cleaned = [line for line in (strip_imported_line(line) for line in lines) if line is not None]
+    if cleaned and cleaned[0].startswith("define internal "):
+        cleaned[0] = cleaned[0].replace("define internal ", "define ", 1)
+    return cleaned
+
+
+def collect_i8_array_global_sizes(lines: List[str]) -> Dict[str, int]:
+    sizes: Dict[str, int] = {}
+    for line in lines:
+        match = I8_ARRAY_GLOBAL_DEF_RE.match(line)
+        if match is None:
+            continue
+        sizes[match.group(1)] = int(match.group(2))
+    return sizes
+
+
+def normalize_i8_array_global_refs(lines: List[str]) -> Tuple[List[str], int]:
+    canonical_sizes = collect_i8_array_global_sizes(lines)
+    if not canonical_sizes:
+        return list(lines), 0
+
+    fix_count = 0
+    normalized: List[str] = []
+    for line in lines:
+        def replace_gep(match: re.Match) -> str:
+            nonlocal fix_count
+            symbol = match.group(3)
+            size = canonical_sizes.get(symbol)
+            if size is None:
+                return match.group(0)
+            updated = f"[{size} x i8], [{size} x i8]* {symbol}"
+            if updated != match.group(0):
+                fix_count += 1
+            return updated
+
+        line = I8_ARRAY_GEP_REF_RE.sub(replace_gep, line)
+
+        def replace_ptr_cast(match: re.Match) -> str:
+            nonlocal fix_count
+            symbol = match.group(2)
+            size = canonical_sizes.get(symbol)
+            if size is None:
+                return match.group(0)
+            updated = f"[{size} x i8]* {symbol}"
+            if updated != match.group(0):
+                fix_count += 1
+            return updated
+
+        line = I8_ARRAY_PTR_CAST_RE.sub(replace_ptr_cast, line)
+        normalized.append(line)
+    return normalized, fix_count
+
+
+def parse_module_symbols(raw_ll: Path) -> ParsedModule:
+    lines = raw_ll.read_text(encoding="utf-8", errors="ignore").splitlines()
+    type_defs_by_name: Dict[str, str] = {}
+    globals_by_name: Dict[str, List[str]] = {}
+    functions_by_name: Dict[str, List[str]] = {}
+    function_kinds: Dict[str, str] = {}
+    type_order: List[str] = []
+    global_order: List[str] = []
+    function_order: List[str] = []
+    index = 0
+    top_level_re = re.compile(
+        r"^(?:%[A-Za-z$._0-9-]+\s*=\s*type\b|@|define |declare |attributes #|![A-Za-z0-9_.-]+ =|![0-9]+ =)"
+    )
+
+    while index < len(lines):
+        line = lines[index]
+        type_match = TYPE_DEF_RE.match(line)
+        if type_match is not None:
+            name = type_match.group(1)
+            type_defs_by_name[name] = line
+            type_order.append(name)
+            index += 1
+            continue
+
+        if line.startswith("define "):
+            match = re.search(r"@([^\s(]+)\(", line)
+            if match is None:
+                index += 1
+                continue
+            name = f"@{match.group(1)}"
+            start = index
+            depth = line.count("{") - line.count("}")
+            index += 1
+            while index < len(lines):
+                depth += lines[index].count("{") - lines[index].count("}")
+                if depth == 0:
+                    index += 1
+                    break
+                index += 1
+            functions_by_name[name] = lines[start:index]
+            function_kinds[name] = "define"
+            function_order.append(name)
+            continue
+
+        if line.startswith("declare "):
+            match = re.search(r"@([^\s(]+)\(", line)
+            if match is None:
+                index += 1
+                continue
+            name = f"@{match.group(1)}"
+            functions_by_name[name] = [line]
+            function_kinds[name] = "declare"
+            function_order.append(name)
+            index += 1
+            continue
+
+        global_match = GLOBAL_DEF_RE.match(line)
+        if global_match is not None:
+            name = global_match.group(1)
+            start = index
+            index += 1
+            while index < len(lines) and not top_level_re.match(lines[index]):
+                index += 1
+            globals_by_name[name] = lines[start:index]
+            global_order.append(name)
+            continue
+
+        index += 1
+
+    return ParsedModule(
+        type_defs_by_name=type_defs_by_name,
+        globals_by_name=globals_by_name,
+        functions_by_name=functions_by_name,
+        function_kinds=function_kinds,
+        type_order=type_order,
+        global_order=global_order,
+        function_order=function_order,
+    )
+
+
+def collect_metadata_ids(lines: Iterable[str]) -> List[int]:
+    seen: Dict[int, None] = {}
+    for line in lines:
+        for match in METADATA_REF_RE.finditer(line):
+            seen[int(match.group(1))] = None
+    return list(seen.keys())
+
+
+def collect_metadata_closure(metadata_defs: Dict[int, str], seed_ids: Iterable[int]) -> Dict[int, str]:
+    closure: Dict[int, str] = {}
+    stack = list(seed_ids)
+    while stack:
+        current = stack.pop()
+        if current in closure:
+            continue
+        definition = metadata_defs.get(current)
+        if definition is None:
+            continue
+        closure[current] = definition
+        for match in METADATA_REF_RE.finditer(definition):
+            stack.append(int(match.group(1)))
+    return closure
+
+
+def rewrite_metadata_ids(text: str, mapping: Dict[int, int]) -> str:
+    return METADATA_REF_RE.sub(
+        lambda match: f"!{mapping.get(int(match.group(1)), int(match.group(1)))}",
+        text,
+    )
+
+
+def disam_sort_key(name: str) -> Tuple[int, str]:
+    match = re.search(r"0x([0-9a-fA-F]+)", name)
+    base = int(match.group(1), 16) if match is not None else 0
+    return base, name
+
+
+def switch_case_count(symbol_lines: List[str]) -> int:
+    return len({match.group(1) for line in symbol_lines for match in [SWITCH_CASE_RE.match(line)] if match is not None})
+
+
+def parse_switch_case_blocks(
+    symbol_lines: List[str],
+    *,
+    case_re: re.Pattern[str],
+) -> Tuple[Dict[int, str], Dict[str, List[str]]]:
+    switch_index = next(
+        index for index, line in enumerate(symbol_lines)
+        if line.strip().startswith("switch ")
+    )
+    switch_end = next(
+        index for index in range(switch_index + 1, len(symbol_lines))
+        if symbol_lines[index].strip() == "]"
+    )
+
+    case_labels: Dict[int, str] = {}
+    for line in symbol_lines[switch_index + 1:switch_end]:
+        match = case_re.match(line)
+        if match is None:
+            continue
+        case_labels[int(match.group(1))] = match.group(2)
+
+    blocks: Dict[str, List[str]] = {}
+    current_label: Optional[str] = None
+    current_lines: List[str] = []
+    for line in symbol_lines[switch_end + 1:-1]:
+        match = ANON_BLOCK_LABEL_RE.match(line)
+        if match is not None:
+            if current_label is not None:
+                blocks[current_label] = current_lines
+            current_label = match.group(1)
+            current_lines = []
+            continue
+        if current_label is not None:
+            current_lines.append(line)
+    if current_label is not None:
+        blocks[current_label] = current_lines
+
+    return case_labels, blocks
+
+
+def rewrite_set_register_case_body(case_value: int, body_lines: List[str]) -> List[str]:
+    prefix = f"set_register_case_{case_value}"
+    rewritten: List[str] = []
+    for line in body_lines:
+        if line.strip().startswith(";"):
+            continue
+        updated = re.sub(r"%0\b", "%reg", line)
+        updated = re.sub(r"%1\b", "%value", updated)
+        updated = re.sub(r"label %4\b", "label %set_register.ret", updated)
+        updated = re.sub(
+            r"%(?!0\b|1\b)(\d+)\b",
+            lambda match: f"%{prefix}_{match.group(1)}",
+            updated,
+        )
+        rewritten.append(updated)
+    return rewritten
+
+
+def merge_set_register_definitions(symbol_variants: List[List[str]]) -> Optional[List[str]]:
+    if not symbol_variants:
+        return None
+
+    case_bodies: Dict[int, List[str]] = {}
+    for symbol_lines in sorted(symbol_variants, key=switch_case_count, reverse=True):
+        try:
+            case_labels, blocks = parse_switch_case_blocks(
+                symbol_lines,
+                case_re=SET_REGISTER_CASE_RE,
+            )
+        except StopIteration:
+            continue
+        for case_value, block_label in case_labels.items():
+            if case_value in case_bodies:
+                continue
+            block_lines = blocks.get(block_label)
+            if not block_lines:
+                continue
+            case_bodies[case_value] = rewrite_set_register_case_body(case_value, block_lines)
+
+    if not case_bodies:
+        return None
+
+    merged_lines = [
+        "define void @set_register(i32 %reg, i64 %value) {",
+        "entry:",
+        "  switch i32 %reg, label %set_register.abort [",
+    ]
+    for case_value in sorted(case_bodies):
+        merged_lines.append(f"    i32 {case_value}, label %set_register.case_{case_value}")
+    merged_lines.extend(
+        [
+            "  ]",
+            "",
+            "set_register.abort:",
+            "  call void @abort()",
+            "  unreachable",
+            "",
+            "set_register.ret:",
+            "  ret void",
+        ]
+    )
+
+    for case_value in sorted(case_bodies):
+        merged_lines.append("")
+        merged_lines.append(f"set_register.case_{case_value}:")
+        merged_lines.extend(case_bodies[case_value])
+    merged_lines.append("}")
+    return merged_lines
+
+
+def function_name_from_signature(line: str) -> Optional[str]:
+    if not (line.startswith("define ") or line.startswith("declare ")):
+        return None
+    match = re.search(r"@([^\s(]+)\(", line)
+    if match is None:
+        return None
+    return f"@{match.group(1)}"
+
+
+def append_base_functions_with_replacements(
+    output_lines: List[str],
+    base_lines: List[str],
+    start: int,
+    end: int,
+    replacement_functions: Dict[str, List[str]],
+    emitted_replacements: Dict[str, None],
+) -> None:
+    index = start
+    while index < end:
+        line = base_lines[index]
+        function_name = function_name_from_signature(line)
+        replacement = replacement_functions.get(function_name or "")
+        if function_name is None or replacement is None:
+            output_lines.append(line)
+            index += 1
+            continue
+
+        output_lines.extend(replacement)
+        emitted_replacements[function_name] = None
+        if line.startswith("declare "):
+            index += 1
+            continue
+        depth = line.count("{") - line.count("}")
+        index += 1
+        while index < end:
+            depth += base_lines[index].count("{") - base_lines[index].count("}")
+            index += 1
+            if depth == 0:
+                break
+
+def find_post_root_suffix_start(lines: List[str], start: int) -> int:
+    named_metadata_re = re.compile(r"^![A-Za-z0-9_.-]+\s*=")
+    for index in range(start, len(lines)):
+        line = lines[index]
+        if (
+            line.startswith("attributes #")
+            or line.startswith("uselistorder")
+            or METADATA_DEF_RE.match(line) is not None
+            or named_metadata_re.match(line) is not None
+        ):
+            return index
+    return len(lines)
+
+
+def merge_full_module(config: Config, results: Dict[str, Dict[str, object]]) -> Dict[str, object]:
+    successful = [
+        item for item in sorted(results.values(), key=lambda value: value["start"])
+        if item["status"] == "ok"
+    ]
+    if not successful:
+        delete_if_exists(config.merged_full_ll)
+        return {
+            "merged_full_ll": None,
+            "merged_full_status": "no_successful_shards",
+            "merged_full_block_count": 0,
+            "merged_full_disam_count": 0,
+        }
+
+    missing_raw: List[str] = []
+    resolved_raw: List[Tuple[Dict[str, object], Path]] = []
+    for item in successful:
+        raw_ll = resolve_raw_ll_path(config, item)
+        if raw_ll is None:
+            missing_raw.append(item["tag"])
+            continue
+        resolved_raw.append((item, raw_ll))
+
+    if missing_raw:
+        if config.merged_full_ll.exists():
+            return {
+                "merged_full_ll": str(config.merged_full_ll),
+                "merged_full_status": "reused_existing_artifact_missing_raw",
+                "merged_full_missing_raw_shards": len(missing_raw),
+                "merged_full_block_count": None,
+                "merged_full_disam_count": None,
+            }
+        return {
+            "merged_full_ll": None,
+            "merged_full_status": "skipped_missing_raw",
+            "merged_full_missing_raw_shards": len(missing_raw),
+            "merged_full_block_count": 0,
+            "merged_full_disam_count": 0,
+        }
+
+    base_item, base_raw_ll = resolved_raw[0]
+    base_root = extract_root(base_raw_ll)
+    base_module = parse_module_symbols(base_raw_ll)
+    base_lines = base_raw_ll.read_text(encoding="utf-8", errors="ignore").splitlines()
+    first_definition_index = next(
+        index for index, line in enumerate(base_lines)
+        if line.startswith("@") or line.startswith("define ") or line.startswith("declare ")
+    )
+    root_start, root_end = find_root_bounds(base_lines)
+    first_function_index = next(
+        index for index, line in enumerate(base_lines)
+        if line.startswith("define ") or line.startswith("declare ")
+    )
+    post_root_suffix_start = find_post_root_suffix_start(base_lines, root_end)
+    existing_metadata_ids = [
+        int(match.group(1))
+        for line in base_lines
+        for match in [METADATA_DEF_RE.match(line)]
+        if match is not None
+    ]
+    next_metadata_id = (max(existing_metadata_ids) + 1) if existing_metadata_ids else 0
+
+    merged_cases: Dict[int, str] = {}
+    merged_segments: Dict[str, RootBlockSegment] = {}
+    imported_allocas: List[str] = []
+    imported_type_defs: Dict[str, str] = {}
+    imported_disam_globals: Dict[str, str] = {}
+    imported_extra_globals: Dict[str, List[str]] = {}
+    imported_functions: Dict[str, List[str]] = {}
+    imported_metadata_defs: List[str] = []
+    replacement_functions: Dict[str, List[str]] = {}
+    replacement_function_variants: Dict[str, List[List[str]]] = {}
+    replacement_function_scores: Dict[str, Tuple[int, int]] = {}
+    base_disam_names = set(base_root.disam_globals)
+    base_global_names = set(base_root.globals)
+    base_function_names = set(base_module.functions_by_name)
+    base_type_names = set(base_module.type_defs_by_name)
+    selected_common_segments = dict(base_root.common_segments)
+    selected_common_segment_scores = {
+        label: common_segment_score(lines)
+        for label, lines in base_root.common_segments.items()
+    }
+    common_segment_variants: Dict[str, List[List[str]]] = {
+        label: [lines]
+        for label, lines in base_root.common_segments.items()
+        if label in ROOT_RICH_COMMON_LABELS
+    }
+    merge_prefer_max_case_functions = {"@set_register"}
+    for name in merge_prefer_max_case_functions:
+        if name in base_module.functions_by_name:
+            cleaned = sanitize_imported_symbol(base_module.functions_by_name[name])
+            replacement_functions[name] = cleaned
+            replacement_function_variants.setdefault(name, []).append(cleaned)
+            replacement_function_scores[name] = function_symbol_score(cleaned)
+
+    for item, raw_ll in resolved_raw:
+        root = extract_root(raw_ll)
+        module = parse_module_symbols(raw_ll)
+
+        for name in merge_prefer_max_case_functions:
+            symbol_lines = module.functions_by_name.get(name)
+            if symbol_lines is None:
+                continue
+            cleaned = sanitize_imported_symbol(symbol_lines)
+            replacement_function_variants.setdefault(name, []).append(cleaned)
+            score = function_symbol_score(cleaned)
+            if score > replacement_function_scores.get(name, (-1, -1)):
+                replacement_functions[name] = cleaned
+                replacement_function_scores[name] = score
+
+        selected_cases = dict(root.dispatcher_cases)
+        for addr, line in selected_cases.items():
+            merged_cases[addr] = line
+
+        if item["tag"] == base_item["tag"]:
+            for segment in base_root.translated_segments:
+                merged_segments[segment.label] = segment
+            continue
+
+        selected_segments = list(root.translated_segments)
+
+        for name in module.type_order:
+            if name in base_type_names or name in imported_type_defs:
+                continue
+            imported_type_defs[name] = module.type_defs_by_name[name]
+
+        for name in module.global_order:
+            if name in base_global_names or name in imported_extra_globals or name.startswith("@disam_"):
+                continue
+            imported_extra_globals[name] = sanitize_imported_symbol(module.globals_by_name[name])
+        for name in module.function_order:
+            if name == "@root":
+                continue
+            symbol_lines = module.functions_by_name[name]
+            symbol_kind = module.function_kinds.get(name)
+            cleaned = sanitize_imported_symbol(symbol_lines)
+            if not cleaned:
+                continue
+
+            if name in base_function_names:
+                if symbol_kind == "define":
+                    score = function_symbol_score(cleaned)
+                    if score > replacement_function_scores.get(name, (-1, -1)):
+                        replacement_functions[name] = cleaned
+                        replacement_function_scores[name] = score
+                continue
+
+            if name in imported_functions:
+                if symbol_kind != "define":
+                    continue
+                score = function_symbol_score(cleaned)
+                existing_score = replacement_function_scores.get(
+                    name,
+                    function_symbol_score(imported_functions[name]),
+                )
+                if score > existing_score:
+                    imported_functions[name] = cleaned
+                    replacement_function_scores[name] = score
+                continue
+
+            imported_functions[name] = cleaned
+            if symbol_kind == "define":
+                replacement_function_scores[name] = function_symbol_score(cleaned)
+
+        prefix = item["tag"].replace("-", "_")
+        renamed_allocas = rename_local_values(root.entry_allocas, prefix)
+        renamed_segments = [
+            RootBlockSegment(
+                label=segment.label,
+                base_addr=segment.base_addr,
+                order_index=segment.order_index,
+                lines=rename_local_values(segment.lines, prefix),
+            )
+            for segment in selected_segments
+        ]
+        if not renamed_segments:
+            continue
+
+        metadata_seed = collect_metadata_ids(renamed_allocas)
+        for segment in renamed_segments:
+            metadata_seed.extend(collect_metadata_ids(segment.lines))
+        metadata_closure = collect_metadata_closure(root.metadata_defs, metadata_seed)
+        metadata_map = {
+            old_id: next_metadata_id + offset
+            for offset, old_id in enumerate(sorted(metadata_closure))
+        }
+        next_metadata_id += len(metadata_map)
+
+        renamed_allocas = [rewrite_metadata_ids(line, metadata_map) for line in renamed_allocas]
+        imported_allocas.extend(renamed_allocas)
+
+        for old_id in sorted(metadata_closure):
+            rewritten_definition = rewrite_metadata_ids(metadata_closure[old_id], metadata_map)
+            imported_metadata_defs.append(f"!{metadata_map[old_id]} = {rewritten_definition}")
+            for disam_ref in DISAM_REF_RE.findall(rewritten_definition):
+                if disam_ref in base_disam_names:
+                    continue
+                definition = root.disam_globals.get(disam_ref)
+                if definition is not None:
+                    imported_disam_globals[disam_ref] = definition
+            for global_ref in GLOBAL_REF_RE.findall(rewritten_definition):
+                if global_ref in base_global_names or global_ref in imported_disam_globals:
+                    continue
+                definition = root.globals.get(global_ref)
+                if definition is not None:
+                    imported_extra_globals[global_ref] = sanitize_imported_symbol([definition])
+
+        for segment in renamed_segments:
+            rewritten_lines = [rewrite_metadata_ids(line, metadata_map) for line in segment.lines]
+            merged_segments[segment.label] = RootBlockSegment(
+                label=segment.label,
+                base_addr=segment.base_addr,
+                order_index=segment.order_index,
+                lines=rewritten_lines,
+            )
+            for disam_ref in DISAM_REF_RE.findall("\n".join(rewritten_lines)):
+                if disam_ref in base_disam_names:
+                    continue
+                definition = root.disam_globals.get(disam_ref)
+                if definition is not None:
+                    imported_disam_globals[disam_ref] = definition
+            for global_ref in GLOBAL_REF_RE.findall("\n".join(rewritten_lines)):
+                if global_ref in base_global_names or global_ref in imported_disam_globals:
+                    continue
+                definition = root.globals.get(global_ref)
+                if definition is not None:
+                    imported_extra_globals[global_ref] = sanitize_imported_symbol([definition])
+
+        for label in ROOT_RICH_COMMON_LABELS:
+            segment_lines = root.common_segments.get(label)
+            if segment_lines is None:
+                continue
+            candidate_lines = segment_lines
+            if item["tag"] != base_item["tag"]:
+                candidate_lines = rename_local_values(segment_lines, prefix)
+            common_segment_variants.setdefault(label, []).append(candidate_lines)
+            import_root_segment_refs(
+                candidate_lines,
+                root=root,
+                base_global_names=base_global_names,
+                base_disam_names=base_disam_names,
+                imported_extra_globals=imported_extra_globals,
+                imported_disam_globals=imported_disam_globals,
+            )
+            candidate_score = common_segment_score(candidate_lines)
+            if candidate_score <= selected_common_segment_scores.get(label, (-1, -1)):
+                continue
+            selected_common_segments[label] = candidate_lines
+            selected_common_segment_scores[label] = candidate_score
+
+    available_globals = set(base_global_names) | set(imported_extra_globals)
+    merged_serialize = build_serialize_and_jump_out_union(
+        common_segment_variants.get("serialize_and_jump_out", []),
+        available_globals=available_globals,
+    )
+    if merged_serialize is not None:
+        selected_common_segments["serialize_and_jump_out"] = merged_serialize
+    merged_return_from_external = build_return_from_external_union(
+        common_segment_variants.get("return_from_external", []),
+        available_globals=available_globals,
+    )
+    if merged_return_from_external is not None:
+        selected_common_segments["return_from_external"] = merged_return_from_external
+
+    merged_set_register = merge_set_register_definitions(
+        replacement_function_variants.get("@set_register", [])
+    )
+    if merged_set_register is not None:
+        replacement_functions["@set_register"] = merged_set_register
+
+    requested_entry_pc, entry_pc_source = determine_root_entry_pc(config)
+    effective_entry_pc = requested_entry_pc
+    if effective_entry_pc is not None and effective_entry_pc not in merged_cases:
+        effective_entry_pc = None
+        entry_pc_source = f"{entry_pc_source}:missing_dispatcher_case"
+    rewritten_entry_rest = list(base_root.entry_rest)
+    entry_pc_rewritten = False
+    entry_pc_previous: Optional[int] = None
+    if effective_entry_pc is not None:
+        rewritten_entry_rest, entry_pc_previous, entry_pc_rewritten = rewrite_root_entry_rest(
+            rewritten_entry_rest,
+            effective_entry_pc,
+        )
+
+    merged_root_lines: List[str] = [base_root.define_line, base_root.entry_label]
+    merged_root_lines.extend(base_root.entry_allocas)
+    merged_root_lines.extend(imported_allocas)
+    merged_root_lines.extend(rewritten_entry_rest)
+    merged_root_lines.extend(base_root.dispatcher_prefix)
+    for addr in sorted(merged_cases):
+        merged_root_lines.append(merged_cases[addr])
+    merged_root_lines.extend(base_root.dispatcher_footer)
+    for label in ("dispatcher.default", "anypc", "unexpectedpc"):
+        merged_root_lines.extend(base_root.common_segments[label])
+    for segment in sorted(
+        merged_segments.values(),
+        key=lambda value: (value.base_addr, value.order_index, value.label),
+    ):
+        merged_root_lines.extend(segment.lines)
+    for label in ("serialize_and_jump_out", "return_from_external", "setjmp", "dispatcher.external"):
+        merged_root_lines.extend(selected_common_segments[label])
+    merged_root_lines.append("}")
+    merged_root_lines = normalize_root_local_values(merged_root_lines)
+
+    new_lines: List[str] = []
+    new_lines.extend(base_lines[:first_definition_index])
+    new_lines.extend(imported_type_defs[name] for name in imported_type_defs)
+    new_lines.extend(base_lines[first_definition_index:first_function_index])
+    new_lines.extend(
+        line
+        for name in sorted(imported_extra_globals)
+        for line in imported_extra_globals[name]
+    )
+    new_lines.extend(imported_disam_globals[name] for name in sorted(imported_disam_globals, key=disam_sort_key))
+    emitted_replacements: Dict[str, None] = {}
+    append_base_functions_with_replacements(
+        new_lines,
+        base_lines,
+        first_function_index,
+        root_start,
+        replacement_functions,
+        emitted_replacements,
+    )
+    new_lines.extend(merged_root_lines)
+    append_base_functions_with_replacements(
+        new_lines,
+        base_lines,
+        root_end,
+        post_root_suffix_start,
+        replacement_functions,
+        emitted_replacements,
+    )
+    for name in sorted(replacement_functions):
+        if name not in emitted_replacements:
+            new_lines.extend(replacement_functions[name])
+    for name in sorted(imported_functions):
+        new_lines.extend(imported_functions[name])
+    new_lines.extend(base_lines[post_root_suffix_start:])
+    new_lines.extend(imported_metadata_defs)
+    new_lines, i8_array_ref_fix_count = normalize_i8_array_global_refs(new_lines)
+    config.merged_full_ll.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+
+    return {
+        "merged_full_ll": str(config.merged_full_ll),
+        "merged_full_status": "built",
+        "merged_full_block_count": len(merged_segments),
+        "merged_full_imported_type_count": len(imported_type_defs),
+        "merged_full_extra_global_count": len(imported_extra_globals),
+        "merged_full_imported_function_count": len(imported_functions),
+        "merged_full_disam_count": len(imported_disam_globals) + len(base_root.disam_globals),
+        "merged_full_entry_pc": effective_entry_pc,
+        "merged_full_entry_pc_source": entry_pc_source,
+        "merged_full_entry_pc_rewritten": entry_pc_rewritten,
+        "merged_full_previous_entry_pc": entry_pc_previous,
+        "merged_full_i8_array_ref_fix_count": i8_array_ref_fix_count,
+    }
+
+
+def cleanup_raw_modules(config: Config, results: Dict[str, Dict[str, object]]) -> None:
+    if config.keep_raw_on_success:
+        return
+    for item in results.values():
+        if item.get("status") != "ok":
+            continue
+        raw_ll_path = item.get("raw_ll")
+        if not raw_ll_path:
+            continue
+        delete_if_exists(Path(raw_ll_path))
+
+
+def resolve_raw_ll_path(config: Config, item: Dict[str, object]) -> Optional[Path]:
+    raw_ll_path = item.get("raw_ll")
+    if raw_ll_path:
+        candidate = Path(raw_ll_path)
+        if candidate.exists():
+            return candidate
+    fallback = config.raw_dir / f"{item['tag']}.raw.ll"
+    if fallback.exists():
+        return fallback
+    return None
diff --git a/runnable/scripts/merge_dynamic_runnable_fragments.py b/runnable/scripts/merge_dynamic_runnable_fragments.py
new file mode 100644
index 000000000..88e279091
--- /dev/null
+++ b/runnable/scripts/merge_dynamic_runnable_fragments.py
@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+from _merge_dynamic_fragments_lib import merge_full_module
+
+
+HEX_RE = re.compile(r"0x([0-9a-fA-F]+)")
+WORKER_RE = re.compile(r"worker_([0-9a-fA-F]+)\.ll$")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Merge coordinator and worker runnable-lift full modules."
+    )
+    parser.add_argument("inputs", nargs="+", type=Path, help="Full-module .ll inputs.")
+    parser.add_argument("--output", required=True, type=Path, help="Merged output path.")
+    parser.add_argument(
+        "--entry-pc",
+        required=True,
+        type=lambda value: int(value, 0),
+        help="Coordinator entry PC used as the merged root entry.",
+    )
+    parser.add_argument(
+        "--summary-out",
+        type=Path,
+        help="Optional JSON file for merge metadata.",
+    )
+    return parser.parse_args()
+
+
+def infer_start(path: Path, default_entry_pc: int) -> int:
+    worker_match = WORKER_RE.search(path.name)
+    if worker_match is not None:
+        return int(worker_match.group(1), 16)
+
+    hex_match = HEX_RE.search(path.name)
+    if hex_match is not None:
+        return int(hex_match.group(1), 16)
+
+    with path.open("r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            line = line.strip()
+            if line.startswith("; 0x"):
+                try:
+                    return int(line.split(":")[0].split()[-1], 16)
+                except ValueError:
+                    continue
+
+    return default_entry_pc
+
+
+def main() -> int:
+    args = parse_args()
+
+    output = args.output.resolve()
+    results = {}
+    for index, path in enumerate(args.inputs):
+        ll_path = path.resolve()
+        if not ll_path.exists():
+            raise FileNotFoundError(ll_path)
+        start = infer_start(ll_path, args.entry_pc if index == 0 else 0)
+        tag = "main" if index == 0 else f"worker_{start:016x}_{index}"
+        results[tag] = {
+            "tag": tag,
+            "status": "ok",
+            "start": start,
+            "raw_ll": str(ll_path),
+        }
+
+    config = SimpleNamespace(
+        raw_dir=output.parent,
+        merged_full_ll=output,
+        ground_truth_binary=None,
+        entry_pc=args.entry_pc,
+    )
+    info = merge_full_module(config, results)
+    payload = {
+        "inputs": [str(path.resolve()) for path in args.inputs],
+        "output": str(output),
+        "entry_pc": f"0x{args.entry_pc:x}",
+        "merge_info": info,
+    }
+    if args.summary_out is not None:
+        args.summary_out.resolve().write_text(
+            json.dumps(payload, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/runnable/tools/runnable-lift/CodeGenerator.cpp b/runnable/tools/runnable-lift/CodeGenerator.cpp
index e0f95e1c2..4653f16f2 100644
--- a/runnable/tools/runnable-lift/CodeGenerator.cpp
+++ b/runnable/tools/runnable-lift/CodeGenerator.cpp
@@ -82,7 +82,10 @@ static std::string findRepoRootFromCwd() {
     return "";
   std::string Current(Buffer);
   while (!Current.empty()) {
-    std::string Probe = Current + "/scripts/merge_dynamic_runnable_fragments.py";
+    std::string Probe = Current + "/runnable/scripts/merge_dynamic_runnable_fragments.py";
+    if (access(Probe.c_str(), F_OK) == 0)
+      return Current;
+    Probe = Current + "/scripts/merge_dynamic_runnable_fragments.py";
     if (access(Probe.c_str(), F_OK) == 0)
       return Current;
     size_t Slash = Current.find_last_of('/');
@@ -1652,11 +1655,22 @@ void CodeGenerator::mergeForkWorkerFragments() {
   if (ParallelWorkersSucceeded == 0)
     return;
 
+  std::vector<std::string> CandidateScripts;
   std::string RepoRoot = findRepoRootFromCwd();
-  if (RepoRoot.empty())
-    return;
-  std::string ScriptPath = RepoRoot + "/scripts/merge_dynamic_runnable_fragments.py";
-  if (access(ScriptPath.c_str(), F_OK) != 0)
+  if (!RepoRoot.empty()) {
+    CandidateScripts.push_back(RepoRoot + "/runnable/scripts/merge_dynamic_runnable_fragments.py");
+    CandidateScripts.push_back(RepoRoot + "/scripts/merge_dynamic_runnable_fragments.py");
+  }
+  CandidateScripts.push_back("merge_dynamic_runnable_fragments.py");
+
+  std::string ScriptPath;
+  for (const auto &Candidate : CandidateScripts) {
+    if (access(Candidate.c_str(), F_OK) == 0) {
+      ScriptPath = Candidate;
+      break;
+    }
+  }
+  if (ScriptPath.empty())
     return;
 
   std::string TempOutput = OutputPath + ".merged.ll";
diff --git a/test/test_merge_dynamic_runnable_fragments.py b/test/test_merge_dynamic_runnable_fragments.py
new file mode 100644
index 000000000..606b53ffb
--- /dev/null
+++ b/test/test_merge_dynamic_runnable_fragments.py
@@ -0,0 +1,110 @@
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+MERGE_SCRIPT = REPO_ROOT / "runnable" / "scripts" / "merge_dynamic_runnable_fragments.py"
+CODEGENERATOR = REPO_ROOT / "runnable" / "tools" / "runnable-lift" / "CodeGenerator.cpp"
+
+
+def build_module(entry_pc: int, block_pc: int) -> str:
+    return f"""\
+; ModuleID = 'top'
+source_filename = "top"
+
+@pc = global i64 0
+@saved_registers = global i64* null
+
+define void @root(i64) {{
+entrypoint:
+  %1 = alloca i64
+  store i64 {entry_pc}, i64* @pc
+  switch i8 0, label %dispatcher.entry [
+    i8 1, label %anypc
+    i8 2, label %unexpectedpc
+  ]
+
+dispatcher.entry:
+  %2 = load i64, i64* @pc
+  switch i64 %2, label %dispatcher.external [
+    i64 {block_pc}, label %bb.0x{block_pc:x}
+  ], !dbg !1
+
+dispatcher.default:
+  call void @unknownPC()
+  unreachable
+
+anypc:
+  br label %dispatcher.entry
+
+unexpectedpc:
+  br label %dispatcher.entry
+
+bb.0x{block_pc:x}:
+  ; 0x{block_pc:016x}: nop
+  store i64 {block_pc}, i64* @pc
+  br label %dispatcher.entry
+
+serialize_and_jump_out:
+  call void asm sideeffect "movq $0, %r11; jmpq *%r11", "*m,~{{dirflag}},~{{fpsr}},~{{flags}}"(i64* @pc)
+  unreachable
+
+return_from_external:
+  br label %dispatcher.entry
+
+setjmp:
+  br label %serialize_and_jump_out
+
+dispatcher.external:
+  br label %dispatcher.default
+}}
+
+declare void @unknownPC()
+"""
+
+
+class MergeDynamicRunnableFragmentsTest(unittest.TestCase):
+    def test_codegenerator_looks_for_repo_local_merge_helper(self) -> None:
+        source = CODEGENERATOR.read_text(encoding="utf-8")
+        self.assertIn(
+            "runnable/scripts/merge_dynamic_runnable_fragments.py",
+            source,
+        )
+
+    def test_merge_helper_merges_dispatch_cases_from_multiple_modules(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp = Path(tmpdir)
+            main_ll = tmp / "main.ll"
+            worker_ll = tmp / "worker_401010.ll"
+            output_ll = tmp / "merged.ll"
+            main_ll.write_text(build_module(0x401000, 0x401000), encoding="utf-8")
+            worker_ll.write_text(build_module(0x401000, 0x401010), encoding="utf-8")
+
+            subprocess.run(
+                [
+                    "python3",
+                    str(MERGE_SCRIPT),
+                    "--output",
+                    str(output_ll),
+                    "--entry-pc",
+                    "0x401000",
+                    str(main_ll),
+                    str(worker_ll),
+                ],
+                check=True,
+                cwd=str(REPO_ROOT),
+                capture_output=True,
+                text=True,
+            )
+
+            merged = output_ll.read_text(encoding="utf-8")
+            self.assertIn("i64 4198400, label %bb.0x401000", merged)
+            self.assertIn("i64 4198416, label %bb.0x401010", merged)
+            self.assertIn("bb.0x401000:", merged)
+            self.assertIn("bb.0x401010:", merged)
+
+
+if __name__ == "__main__":
+    unittest.main()

From 70e3e1bc23a17cf3eb3b471057253b896612e8f8 Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Sat, 2 May 2026 01:09:44 +0800
Subject: [PATCH 5/7] docs: update runnable parallel lift skill

---
 .codex/skills/runnable-parallel-lift/SKILL.md | 109 ++++++++++++++++++
 ...9-runnable-lift-dynamic-branch-parallel.md |  93 +++++++++++++++
 .../scripts/_merge_dynamic_fragments_lib.py   |  33 +++++-
 test/test_runnable_parallel_lift_skill.py     |  62 ++++++++++
 4 files changed, 296 insertions(+), 1 deletion(-)
 create mode 100644 .codex/skills/runnable-parallel-lift/SKILL.md
 create mode 100644 docs/superpowers/plans/2026-04-29-runnable-lift-dynamic-branch-parallel.md
 create mode 100644 test/test_runnable_parallel_lift_skill.py

diff --git a/.codex/skills/runnable-parallel-lift/SKILL.md b/.codex/skills/runnable-parallel-lift/SKILL.md
new file mode 100644
index 000000000..2f319fa5f
--- /dev/null
+++ b/.codex/skills/runnable-parallel-lift/SKILL.md
@@ -0,0 +1,109 @@
+---
+name: runnable-parallel-lift
+description: Use when working on runnable parallel lift workflows and deciding whether a task should use the current dynamic branch-driven runnable-lift path or the legacy offline static sharding path.
+---
+
+# Runnable Parallel Lift
+
+## Overview
+
+There are two different parallel lift models in this repository. The default current architecture is the online dynamic branch-driven mode inside `runnable-lift`. The older offline static sharding flow exists only for legacy address-ranged experiments and must not be treated as the current default.
+
+## Default Workflow: Dynamic Branch-Driven `runnable-lift`
+
+Use this when the task is about the current parallel lift architecture.
+
+Entry command:
+
+```bash
+runnable-lift <binary> <output.ll> \
+  -dynamic-parallel \
+  -parallel-workers=<N> \
+  -parallel-fragment-dir=<fragment-dir> \
+  [other normal runnable-lift flags]
+```
+
+Current user-facing flags:
+
+- `-dynamic-parallel`
+- `-parallel-workers=<N>`
+- `-parallel-fragment-dir=<PATH>`
+
+Internal flags that agents should not pass manually:
+
+- `-parallel-worker-mode`
+- `-parallel-seed-pc`
+
+Dynamic artifacts:
+
+- coordinator output: `<output.ll>`
+- worker fragments: `<fragment-dir>/worker_<pc>.ll`
+- worker logs:
+  - `<fragment-dir>/worker_<pc>.ll.stdout.log`
+  - `<fragment-dir>/worker_<pc>.ll.stderr.log`
+- temporary merge output before rename: `<output.ll>.merged.ll`
+
+Dynamic merge behavior:
+
+- `runnable/tools/runnable-lift/CodeGenerator.cpp` spawns branch workers from the coordinator.
+- Successful worker fragments are merged back into the top-level module with `runnable/scripts/merge_dynamic_runnable_fragments.py`.
+- The final merged module replaces the coordinator output path. Dynamic mode does not produce `merged_full.ll`, `shard_results.json`, `raw/`, or `shards/`.
+
+Recommended validation:
+
+```bash
+rg -n "dynamic-parallel|parallel-workers|parallel-fragment-dir" \
+  runnable/tools/runnable-lift/Main.cpp \
+  runnable/tools/runnable-lift/CodeGenerator.cpp
+
+python3 -m unittest discover -s test -p 'test_merge_dynamic_runnable_fragments.py' -v
+```
+
+## Legacy Workflow: Offline Static Sharding
+
+This is the old address-ranged family. Historical wrappers for it were `scripts/libcrypto_parallel_lift.py` together with `run_libcrypto_parallel_lift_stable.py`.
+
+In this repository snapshot, the surviving legacy helper and CLI specification for that workflow is `runnable/scripts/_merge_dynamic_fragments_lib.py`. That path expects `runnable-lift` builds with `-addr-range-min` and `-addr-range-max` support and describes the offline per-function/static-shard artifact model instead of online branch spawning.
+
+Legacy outputs are different from the dynamic mode:
+
+- `shards/`
+- `raw/`
+- `eval/`
+- `logs/`
+- `shard_results.json`
+- `shard_results.jsonl`
+- `status.json`
+- `merged.ll`
+- `merged_full.ll`
+- `final_report.json`
+- `final_report.md`
+
+Use the legacy flow only when the task explicitly calls for static address-ranged lifting, libcrypto/OpenSSL-style offline evaluation, or comparing against historical shard reports.
+
+Recommended validation:
+
+```bash
+python3 runnable/scripts/_merge_dynamic_fragments_lib.py --help
+git show origin/wip/runnable-20260409-121909:test/lift_openssl_parallel.py | sed -n '1,120p'
+```
+
+## Guardrails
+
+- Treat dynamic branch-driven `runnable-lift` as the default explanation unless the task explicitly asks for the old static sharding flow.
+- Do not mix dynamic worker fragments (`worker_<pc>.ll`) with legacy `shards/` or `raw/` outputs in the same interpretation or report.
+- Do not describe `scripts/libcrypto_parallel_lift.py` or `run_libcrypto_parallel_lift_stable.py` as the current architecture.
+- Do not expect `merged_full.ll`, `parallel.eval.json`, or shard manifests from dynamic mode.
+- Do not feed dynamic fragments into the legacy offline evaluation pipeline. Dynamic fragments are only for `merge_dynamic_runnable_fragments.py`.
+- Do not pass `-parallel-worker-mode` or `-parallel-seed-pc` by hand. Those are worker-internal flags.
+- If a task depends on `-addr-range-min` or `-addr-range-max`, call it legacy/static sharding explicitly and verify the target branch still exposes those flags before proceeding.
+
+## References
+
+- `README.md` dynamic parallel prototype section
+- `runnable/tools/runnable-lift/Main.cpp`
+- `runnable/tools/runnable-lift/CodeGenerator.cpp`
+- `runnable/scripts/merge_dynamic_runnable_fragments.py`
+- `runnable/scripts/_merge_dynamic_fragments_lib.py`
+- `docs/superpowers/plans/2026-04-29-runnable-lift-dynamic-branch-parallel.md`
+- `test/test_merge_dynamic_runnable_fragments.py`
diff --git a/docs/superpowers/plans/2026-04-29-runnable-lift-dynamic-branch-parallel.md b/docs/superpowers/plans/2026-04-29-runnable-lift-dynamic-branch-parallel.md
new file mode 100644
index 000000000..ae7c04efd
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-29-runnable-lift-dynamic-branch-parallel.md
@@ -0,0 +1,93 @@
+# Runnable Lift Dynamic Branch Parallel Plan
+
+## Purpose
+
+This note is the repository-local reference for the current parallel lift architecture on `codex/dynamic-parallel-lift`. It exists so skills and future agents do not confuse the new online dynamic branch-driven flow with the older offline static sharding wrappers.
+
+## Current Default: Online Dynamic Branch-Driven Parallelism
+
+Primary entrypoint:
+
+```bash
+runnable-lift <binary> <output.ll> \
+  -dynamic-parallel \
+  -parallel-workers=<N> \
+  -parallel-fragment-dir=<fragment-dir>
+```
+
+Implementation anchors:
+
+- CLI flags: `runnable/tools/runnable-lift/Main.cpp`
+- worker spawning and merge hook: `runnable/tools/runnable-lift/CodeGenerator.cpp`
+- merge helper: `runnable/scripts/merge_dynamic_runnable_fragments.py`
+- merge behavior test: `test/test_merge_dynamic_runnable_fragments.py`
+
+Current behavior:
+
+- the coordinator runs in the main `runnable-lift` process
+- fresh branch frontiers can fork worker subprocesses
+- workers write `worker_<pc>.ll` fragments into `-parallel-fragment-dir`
+- successful fragments are merged back into the coordinator output module
+- the final merged top-level module is written back to the original `<output.ll>` path
+
+Dynamic artifacts:
+
+- `<output.ll>`
+- `<output.ll>.merged.ll` as a temporary pre-rename merge target
+- `<fragment-dir>/worker_<pc>.ll`
+- `<fragment-dir>/worker_<pc>.ll.stdout.log`
+- `<fragment-dir>/worker_<pc>.ll.stderr.log`
+
+Flags that are internal-only for worker subprocesses:
+
+- `-parallel-worker-mode`
+- `-parallel-seed-pc`
+
+## Legacy Static Sharding Flow
+
+Legacy static sharding refers to the older address-ranged workflow historically driven by `scripts/libcrypto_parallel_lift.py` and `run_libcrypto_parallel_lift_stable.py`.
+
+The closest legacy helper and CLI specification that still exists in this repository is `runnable/scripts/_merge_dynamic_fragments_lib.py`. Its arguments and artifact model describe the old offline address-ranged orchestration family. That flow depends on `runnable-lift` binaries exposing `-addr-range-min` and `-addr-range-max`, as seen on `origin/wip/runnable-20260409-121909`.
+
+Legacy artifacts are output-tree oriented rather than fragment-dir oriented:
+
+- `shards/`
+- `raw/`
+- `eval/`
+- `logs/`
+- `shard_results.json`
+- `shard_results.jsonl`
+- `status.json`
+- `merged.ll`
+- `merged_full.ll`
+- `final_report.json`
+- `final_report.md`
+
+Use the legacy flow only for historical per-function/address-range experiments, not for explaining the current default architecture.
+
+## Validation
+
+Dynamic validation:
+
+```bash
+rg -n "dynamic-parallel|parallel-workers|parallel-fragment-dir" \
+  runnable/tools/runnable-lift/Main.cpp \
+  runnable/tools/runnable-lift/CodeGenerator.cpp
+
+python3 -m unittest discover -s test -p 'test_merge_dynamic_runnable_fragments.py' -v
+```
+
+Legacy validation:
+
+```bash
+python3 runnable/scripts/_merge_dynamic_fragments_lib.py --help
+git grep -n "addr-range-min\\|addr-range-max" origin/wip/runnable-20260409-121909 -- runnable/tools/runnable-lift/JumpTargetManager.cpp test/lift_openssl_parallel.py
+```
+
+## Guardrails
+
+- Default to the dynamic branch-driven path when a task says "current parallel lift architecture".
+- Call out legacy/static sharding explicitly whenever a workflow depends on `-addr-range-min` or static shard manifests.
+- Do not mix dynamic `worker_<pc>.ll` fragments with legacy `shards/` and `raw/` outputs.
+- Do not claim that dynamic mode emits `merged_full.ll` or shard manifests.
+- Do not manually pass worker-internal flags when exercising the public dynamic entrypoint.
diff --git a/runnable/scripts/_merge_dynamic_fragments_lib.py b/runnable/scripts/_merge_dynamic_fragments_lib.py
index e23daee5c..ef34f6f6d 100644
--- a/runnable/scripts/_merge_dynamic_fragments_lib.py
+++ b/runnable/scripts/_merge_dynamic_fragments_lib.py
@@ -16,6 +16,19 @@
 from pathlib import Path, PurePosixPath
 from typing import Dict, Iterable, List, Optional, Tuple
 
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_CONTAINER_NAME = "runnable-parallel-lift-legacy"
+DEFAULT_RUN_DIR = REPO_ROOT
+DEFAULT_OUT_DIR = DEFAULT_RUN_DIR / "out" / "runnable-parallel-lift-legacy"
+DEFAULT_FUNCS_CSV = DEFAULT_RUN_DIR / "dataset" / "libcrypto.funcs.csv"
+DEFAULT_REFERENCE_LL = DEFAULT_OUT_DIR / "reference.ll"
+DEFAULT_GROUND_TRUTH = DEFAULT_RUN_DIR / "dataset" / "libcrypto.so"
+DEFAULT_RUN_CMP_EVAL = DEFAULT_RUN_DIR / "test" / "cmp_instruction.py"
+DEFAULT_CONTAINER_WORKDIR = "/workdir"
+DEFAULT_CONTAINER_BINARY = "/workdir/libcrypto.so"
+DEFAULT_RUNNABLE_LIFT = "runnable-lift"
+DEFAULT_CSV_IMAGE_BASE = 0x400000
+
 LL_COMMENT_RE = re.compile(r"^\s*;\s*(0x[0-9a-fA-F]+):(.*)$")
 ROOT_LABEL_RE = re.compile(r"^([A-Za-z$._0-9-]+):")
 ROOT_BLOCK_LABEL_RE = re.compile(r"^bb\.0x([0-9a-fA-F]+)")
@@ -252,7 +265,11 @@ def __init__(self, args: argparse.Namespace):
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Run the libcrypto address-ranged parallel lift workflow."
+        description=(
+            "Run the legacy libcrypto address-ranged parallel lift workflow. "
+            "This is the offline static sharding path, not runnable-lift's "
+            "dynamic branch-driven mode."
+        )
     )
     parser.add_argument("--container-name", default=DEFAULT_CONTAINER_NAME)
     parser.add_argument("--run-dir", type=Path, default=DEFAULT_RUN_DIR)
@@ -1814,3 +1831,17 @@ def resolve_raw_ll_path(config: Config, item: Dict[str, object]) -> Optional[Pat
     if fallback.exists():
         return fallback
     return None
+
+
+def main() -> int:
+    parse_args()
+    print(
+        "This module documents the legacy offline static sharding CLI shape only. "
+        "It is not the default dynamic branch-driven runnable-lift entrypoint.",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/test/test_runnable_parallel_lift_skill.py b/test/test_runnable_parallel_lift_skill.py
new file mode 100644
index 000000000..cc2574991
--- /dev/null
+++ b/test/test_runnable_parallel_lift_skill.py
@@ -0,0 +1,62 @@
+import subprocess
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILL_PATH = REPO_ROOT / ".codex" / "skills" / "runnable-parallel-lift" / "SKILL.md"
+PLAN_PATH = (
+    REPO_ROOT
+    / "docs"
+    / "superpowers"
+    / "plans"
+    / "2026-04-29-runnable-lift-dynamic-branch-parallel.md"
+)
+LEGACY_HELPER = REPO_ROOT / "runnable" / "scripts" / "_merge_dynamic_fragments_lib.py"
+
+
+class RunnableParallelLiftSkillTest(unittest.TestCase):
+    def test_skill_exists_and_points_to_dynamic_default(self) -> None:
+        self.assertTrue(SKILL_PATH.is_file(), f"missing skill: {SKILL_PATH}")
+
+        content = SKILL_PATH.read_text(encoding="utf-8")
+        self.assertIn("dynamic branch-driven", content)
+        self.assertIn("-dynamic-parallel", content)
+        self.assertIn("-parallel-workers", content)
+        self.assertIn("-parallel-fragment-dir", content)
+        self.assertIn("runnable/scripts/merge_dynamic_runnable_fragments.py", content)
+        self.assertIn("worker_<pc>.ll", content)
+
+    def test_skill_preserves_legacy_static_sharding_guardrails(self) -> None:
+        content = SKILL_PATH.read_text(encoding="utf-8")
+        self.assertIn("scripts/libcrypto_parallel_lift.py", content)
+        self.assertIn("run_libcrypto_parallel_lift_stable.py", content)
+        self.assertIn("legacy", content.lower())
+        self.assertIn("shards/", content)
+        self.assertIn("raw/", content)
+        self.assertIn("merged_full.ll", content)
+        self.assertIn("do not mix", content.lower())
+
+    def test_dynamic_parallel_reference_plan_exists(self) -> None:
+        self.assertTrue(PLAN_PATH.is_file(), f"missing plan: {PLAN_PATH}")
+        content = PLAN_PATH.read_text(encoding="utf-8")
+        self.assertIn("runnable-lift", content)
+        self.assertIn("merge_dynamic_runnable_fragments.py", content)
+        self.assertIn("worker_<pc>.ll", content)
+        self.assertIn("legacy static sharding", content.lower())
+
+    def test_legacy_helper_help_is_labeled_legacy(self) -> None:
+        result = subprocess.run(
+            ["python3", str(LEGACY_HELPER), "--help"],
+            cwd=str(REPO_ROOT),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("legacy", result.stdout.lower())
+        self.assertIn("address-ranged", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

From deb13a0148667fb98950e5619499f090b7c217df Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Sat, 2 May 2026 01:27:21 +0800
Subject: [PATCH 6/7] feat: add fn/fp root-cause analysis skill

---
 .../skills/fn-fp-root-cause-analysis/SKILL.md | 131 +++++++++++
 runnable/CMakeLists.txt                       |  15 +-
 runnable/scripts/_fn_fp_root_cause_lib.py     | 212 ++++++++++++++++++
 runnable/scripts/analyze_fn_fp_root_causes.py | 182 +++++++++++++++
 .../validate_libcrypto_ground_truth.py        |  92 ++++++++
 .../fn_fp_root_cause/function_symbols.csv     |   7 +
 .../fn_fp_root_cause/ground_truth.csv         |   9 +
 test/fixtures/fn_fp_root_cause/merged.ll      |  13 ++
 .../raw/fn_0000000000001000.raw.ll            |   2 +
 .../raw/fn_000000000000100c.raw.ll            |   2 +
 .../fn_fp_root_cause/shard_results.json       |  92 ++++++++
 .../shards/fn_0000000000001000.ll             |   2 +
 .../fn_0000000000001000.ll.coverage.csv       |   2 +
 .../shards/fn_000000000000100c.ll             |   2 +
 .../fn_000000000000100c.ll.coverage.csv       |   1 +
 test/test_fn_fp_root_cause_analysis.py        | 132 +++++++++++
 16 files changed, 893 insertions(+), 3 deletions(-)
 create mode 100644 .codex/skills/fn-fp-root-cause-analysis/SKILL.md
 create mode 100644 runnable/scripts/_fn_fp_root_cause_lib.py
 create mode 100644 runnable/scripts/analyze_fn_fp_root_causes.py
 create mode 100644 runnable/scripts/validate_libcrypto_ground_truth.py
 create mode 100644 test/fixtures/fn_fp_root_cause/function_symbols.csv
 create mode 100644 test/fixtures/fn_fp_root_cause/ground_truth.csv
 create mode 100644 test/fixtures/fn_fp_root_cause/merged.ll
 create mode 100644 test/fixtures/fn_fp_root_cause/raw/fn_0000000000001000.raw.ll
 create mode 100644 test/fixtures/fn_fp_root_cause/raw/fn_000000000000100c.raw.ll
 create mode 100644 test/fixtures/fn_fp_root_cause/shard_results.json
 create mode 100644 test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll
 create mode 100644 test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll.coverage.csv
 create mode 100644 test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll
 create mode 100644 test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll.coverage.csv
 create mode 100644 test/test_fn_fp_root_cause_analysis.py

diff --git a/.codex/skills/fn-fp-root-cause-analysis/SKILL.md b/.codex/skills/fn-fp-root-cause-analysis/SKILL.md
new file mode 100644
index 000000000..55d8fde52
--- /dev/null
+++ b/.codex/skills/fn-fp-root-cause-analysis/SKILL.md
@@ -0,0 +1,131 @@
+---
+name: fn-fp-root-cause-analysis
+description: Use when runnable lift metrics already exist and you need structured false-negative or false-positive root-cause analysis from ground-truth, merged LL, and shard artifacts such as coverage CSVs, illegalEntry logs, stderr logs, or shard result manifests
+---
+
+# FN/FP Root Cause Analysis
+
+## Overview
+
+This skill is for explaining *why* runnable lift missed or over-lifted addresses.
+Do not use it just to compute aggregate precision or recall.
+
+## When To Use
+
+- You already have ground-truth and lifted output.
+- You need evidence-backed FN or FP categories instead of only `tp/fp/fn`.
+- You have shard artifacts such as `shard_results.json`, `*.coverage.csv`, `*.illegalEntry.log`, `*.stderr.log`, `*.ll`, `*.li.csv`, or `*.need.csv`.
+
+Do not use this skill when the task is only “run evaluation and report metrics”.
+For that, run the validator script first and stop there unless asked for causes.
+
+## Inputs
+
+- Ground truth:
+  - preferred: final-layout CSV like `ground_truth.csv`
+  - plus `function_symbols.csv` for function-to-shard attribution
+- Lift output:
+  - merged LL such as `merged.ll`
+- Optional shard evidence:
+  - `shard_results.json`
+  - shard `*.coverage.csv`
+  - shard `*.illegalEntry.log`
+  - shard `*.stderr.log`
+  - shard `*.ll`
+
+## Workflow
+
+1. Compute metrics and address sets:
+
+```bash
+python3 runnable/scripts/validate_libcrypto_ground_truth.py \
+  --ground-truth-csv <ground_truth.csv> \
+  --ll <merged.ll> \
+  --function-symbols-csv <function_symbols.csv> \
+  --csv-image-base <csv image base> \
+  --rebase-base <runtime base> \
+  --summary-out <validation.json>
+```
+
+2. Analyze FN and FP causes:
+
+```bash
+python3 runnable/scripts/analyze_fn_fp_root_causes.py \
+  --validation-summary <validation.json> \
+  --ground-truth-csv <ground_truth.csv> \
+  --function-symbols-csv <function_symbols.csv> \
+  --merged-ll <merged.ll> \
+  --shard-results-json <shard_results.json> \
+  --csv-image-base <csv image base> \
+  --rebase-base <runtime base> \
+  --summary-out <analysis.json>
+```
+
+## Minimal Reproduction
+
+```bash
+python3 runnable/scripts/validate_libcrypto_ground_truth.py \
+  --ground-truth-csv test/fixtures/fn_fp_root_cause/ground_truth.csv \
+  --ll test/fixtures/fn_fp_root_cause/merged.ll \
+  --function-symbols-csv test/fixtures/fn_fp_root_cause/function_symbols.csv \
+  --csv-image-base 0x1000 \
+  --rebase-base 0x50000000 \
+  --summary-out /tmp/fnfp.validation.json
+
+python3 runnable/scripts/analyze_fn_fp_root_causes.py \
+  --validation-summary /tmp/fnfp.validation.json \
+  --ground-truth-csv test/fixtures/fn_fp_root_cause/ground_truth.csv \
+  --function-symbols-csv test/fixtures/fn_fp_root_cause/function_symbols.csv \
+  --merged-ll test/fixtures/fn_fp_root_cause/merged.ll \
+  --shard-results-json test/fixtures/fn_fp_root_cause/shard_results.json \
+  --csv-image-base 0x1000 \
+  --rebase-base 0x50000000 \
+  --summary-out /tmp/fnfp.analysis.json
+```
+
+## Output Shape
+
+Expect JSON with:
+
+- `findings[]`
+- each finding includes:
+  - `kind`: `fn` or `fp`
+  - `address`
+  - `reason`
+  - `priority`
+  - `symbol` and `range` when attributable
+  - `evidence_paths`
+
+## Supported Reason Categories
+
+- `illegal_entry_suppression`
+- `shard_timeout`
+- `shard_error`
+- `shard_empty`
+- `merge_missing`
+- `continuation_byte`
+- `ground_truth_gap`
+- `padding`
+- `outside_gt_coverage`
+- `extra_lifted_bytes`
+
+## Interpretation Rules
+
+- Prefer shard-state explanations for FN when shard evidence exists.
+- Prefer address-shape explanations for FP:
+  - continuation bytes
+  - GT gap near nearby instruction starts
+  - padding or data-section spill
+  - outside coverage
+  - extra lifted bytes inside covered space
+
+## Reporting Standard
+
+When summarizing results for reviewers, include:
+
+- representative addresses
+- category counts
+- exact evidence paths
+- first-priority investigation directions
+
+Do not collapse everything back into only aggregate metrics.
diff --git a/runnable/CMakeLists.txt b/runnable/CMakeLists.txt
index 29f842e62..b5db21034 100644
--- a/runnable/CMakeLists.txt
+++ b/runnable/CMakeLists.txt
@@ -161,12 +161,22 @@ configure_file(scripts/runnable "${CMAKE_BINARY_DIR}/runnable" COPYONLY)
 configure_file(scripts/runnable-merge-dynamic "${CMAKE_BINARY_DIR}/runnable-merge-dynamic" COPYONLY)
 configure_file(scripts/merge_dynamic_runnable_fragments.py "${CMAKE_BINARY_DIR}/merge_dynamic_runnable_fragments.py" COPYONLY)
 configure_file(scripts/_merge_dynamic_fragments_lib.py "${CMAKE_BINARY_DIR}/_merge_dynamic_fragments_lib.py" COPYONLY)
+configure_file(scripts/validate_libcrypto_ground_truth.py "${CMAKE_BINARY_DIR}/validate_libcrypto_ground_truth.py" COPYONLY)
+configure_file(scripts/analyze_fn_fp_root_causes.py "${CMAKE_BINARY_DIR}/analyze_fn_fp_root_causes.py" COPYONLY)
+configure_file(scripts/_fn_fp_root_cause_lib.py "${CMAKE_BINARY_DIR}/_fn_fp_root_cause_lib.py" COPYONLY)
 install(PROGRAMS scripts/runnable scripts/runnable-merge-dynamic DESTINATION bin)
-install(PROGRAMS scripts/merge_dynamic_runnable_fragments.py DESTINATION share/runnable)
+install(PROGRAMS
+  scripts/merge_dynamic_runnable_fragments.py
+  scripts/validate_libcrypto_ground_truth.py
+  scripts/analyze_fn_fp_root_causes.py
+  DESTINATION share/runnable)
 install(FILES runtime/support.c DESTINATION share/runnable)
 install(FILES runtime/support.h DESTINATION share/runnable)
 install(FILES include/runnable/Runtime/commonconstants.h DESTINATION share/runnable)
-install(FILES scripts/_merge_dynamic_fragments_lib.py DESTINATION share/runnable)
+install(FILES
+  scripts/_merge_dynamic_fragments_lib.py
+  scripts/_fn_fp_root_cause_lib.py
+  DESTINATION share/runnable)
 
 # Remove -rdynamic
 set(CMAKE_SHARED_LIBRARY_LINK_C_FLAGS)
@@ -174,4 +184,3 @@ set(CMAKE_SHARED_LIBRARY_LINK_C_FLAGS)
 
 
 install(EXPORT runnable NAMESPACE runnable:: DESTINATION share/runnable/cmake)
-
diff --git a/runnable/scripts/_fn_fp_root_cause_lib.py b/runnable/scripts/_fn_fp_root_cause_lib.py
new file mode 100644
index 000000000..d4583dbe6
--- /dev/null
+++ b/runnable/scripts/_fn_fp_root_cause_lib.py
@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+
+import csv
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+
+LL_COMMENT_RE = re.compile(r"^\s*;\s*(0x[0-9a-fA-F]+):(.*)$")
+HEX_RE = re.compile(r"0x[0-9a-fA-F]+|[0-9a-fA-F]{4,}")
+ILLEGAL_RANGE_RE = re.compile(r"^\s*([0-9a-fA-Fx]+)\s*,\s*([0-9a-fA-Fx]+)\s*$")
+
+
+@dataclass(frozen=True)
+class SymbolRange:
+    start_csv: int
+    end_csv: int
+    start_runtime: int
+    end_runtime: int
+    name: str
+
+
+def parse_int(value: str) -> int:
+    return int(value, 0)
+
+
+def csv_to_runtime(addr_csv: int, csv_image_base: int, rebase_base: int) -> int:
+    return rebase_base + (addr_csv - csv_image_base)
+
+
+def runtime_to_csv(addr_runtime: int, csv_image_base: int, rebase_base: int) -> int:
+    return csv_image_base + (addr_runtime - rebase_base)
+
+
+def load_ground_truth_csv(
+    path: Path,
+    *,
+    csv_image_base: int,
+    rebase_base: int,
+) -> Tuple[Set[int], List[Tuple[int, int]]]:
+    instruction_addrs: Set[int] = set()
+    data_ranges: List[Tuple[int, int]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        reader = csv.DictReader(handle)
+        for row in reader:
+            kind = row["kind"]
+            start_csv = parse_int(row["start_hex"])
+            end_csv = parse_int(row["end_hex"])
+            start_runtime = csv_to_runtime(start_csv, csv_image_base, rebase_base)
+            end_runtime = csv_to_runtime(end_csv, csv_image_base, rebase_base)
+            if kind == "instruction_start":
+                instruction_addrs.add(start_runtime)
+            elif kind == "data_section":
+                data_ranges.append((start_runtime, end_runtime))
+    return instruction_addrs, data_ranges
+
+
+def load_function_symbols_csv(
+    path: Path,
+    *,
+    csv_image_base: int,
+    rebase_base: int,
+) -> List[SymbolRange]:
+    rows: List[Tuple[int, str]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        reader = csv.DictReader(handle)
+        for row in reader:
+            start_csv = parse_int(row["address_hex"])
+            rows.append((start_csv, row["symbol"]))
+    rows.sort(key=lambda item: item[0])
+    ranges: List[SymbolRange] = []
+    for idx, (start_csv, name) in enumerate(rows):
+        next_start = rows[idx + 1][0] if idx + 1 < len(rows) else start_csv + 0x100
+        end_csv = max(start_csv, next_start - 1)
+        ranges.append(
+            SymbolRange(
+                start_csv=start_csv,
+                end_csv=end_csv,
+                start_runtime=csv_to_runtime(start_csv, csv_image_base, rebase_base),
+                end_runtime=csv_to_runtime(end_csv, csv_image_base, rebase_base),
+                name=name,
+            )
+        )
+    return ranges
+
+
+def load_lifted_addresses_from_ll(path: Path) -> List[int]:
+    addrs: Dict[int, str] = {}
+    with path.open("r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            match = LL_COMMENT_RE.match(line)
+            if match is None:
+                continue
+            addr = int(match.group(1), 16)
+            addrs[addr] = match.group(2).strip()
+    return sorted(addrs)
+
+
+def load_lifted_instruction_map(path: Path) -> Dict[int, str]:
+    lifted: Dict[int, str] = {}
+    with path.open("r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            match = LL_COMMENT_RE.match(line)
+            if match is None:
+                continue
+            addr = int(match.group(1), 16)
+            lifted[addr] = match.group(2).strip()
+    return lifted
+
+
+def write_json(path: Optional[Path], payload: Dict[str, object]) -> None:
+    if path is None:
+        return
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def hex_list(values: Iterable[int]) -> List[str]:
+    return [f"0x{value:x}" for value in sorted(values)]
+
+
+def find_symbol_for_address(symbols: Sequence[SymbolRange], runtime_addr: int) -> Optional[SymbolRange]:
+    for symbol in symbols:
+        if symbol.start_runtime <= runtime_addr <= symbol.end_runtime:
+            return symbol
+    return None
+
+
+def read_json(path: Path) -> Dict[str, object]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_shard_results(path: Path) -> Dict[str, Dict[str, object]]:
+    items = read_json(path)
+    return {item["tag"]: item for item in items}
+
+
+def tag_for_symbol(symbol: SymbolRange) -> str:
+    return f"fn_{symbol.start_csv:016x}"
+
+
+def shard_path(root: Path, relative_or_abs: Optional[str]) -> Optional[Path]:
+    if not relative_or_abs:
+        return None
+    candidate = Path(relative_or_abs)
+    if candidate.is_absolute():
+        return candidate
+    return root / candidate
+
+
+def read_text_if_exists(path: Optional[Path]) -> str:
+    if path is None or not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8", errors="ignore")
+
+
+def load_illegal_addresses(path: Optional[Path]) -> Set[int]:
+    if path is None or not path.exists():
+        return set()
+    results: Set[int] = set()
+    for line in path.read_text(encoding="utf-8", errors="ignore").splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        range_match = ILLEGAL_RANGE_RE.match(stripped)
+        if range_match is not None:
+            start_token = range_match.group(1)
+            end_token = range_match.group(2)
+            start = int(start_token, 16 if not start_token.lower().startswith("0x") else 0)
+            end = int(end_token, 16 if not end_token.lower().startswith("0x") else 0)
+            results.update(range(start, end + 1))
+            continue
+        for token in HEX_RE.findall(stripped):
+            try:
+                results.add(int(token, 16 if not token.lower().startswith("0x") else 0))
+            except ValueError:
+                continue
+    return results
+
+
+def load_coverage_addresses(path: Optional[Path]) -> Set[int]:
+    if path is None or not path.exists():
+        return set()
+    covered: Set[int] = set()
+    with path.open("r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            parts = line.strip().split(",")
+            if not parts or not parts[0]:
+                continue
+            try:
+                covered.add(int(parts[0], 16))
+            except ValueError:
+                continue
+    return covered
+
+
+def is_continuation_byte(addr: int, gt_instrs: Set[int]) -> bool:
+    if addr in gt_instrs:
+        return False
+    for base in gt_instrs:
+        if 0 < addr - base <= 3:
+            return True
+    return False
+
+
+def is_in_ranges(addr: int, ranges: Sequence[Tuple[int, int]]) -> bool:
+    return any(start <= addr <= end for start, end in ranges)
+
+
+def neighbor_ground_truth(addr: int, gt_instrs: Set[int], max_distance: int = 8) -> bool:
+    return any(abs(addr - gt) <= max_distance for gt in gt_instrs)
diff --git a/runnable/scripts/analyze_fn_fp_root_causes.py b/runnable/scripts/analyze_fn_fp_root_causes.py
new file mode 100644
index 000000000..82ef65fd9
--- /dev/null
+++ b/runnable/scripts/analyze_fn_fp_root_causes.py
@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from _fn_fp_root_cause_lib import (
+    find_symbol_for_address,
+    hex_list,
+    is_continuation_byte,
+    is_in_ranges,
+    load_coverage_addresses,
+    load_function_symbols_csv,
+    load_ground_truth_csv,
+    load_illegal_addresses,
+    load_lifted_instruction_map,
+    load_shard_results,
+    neighbor_ground_truth,
+    read_json,
+    shard_path,
+    tag_for_symbol,
+    write_json,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Analyze false negatives and false positives from runnable ground-truth validation."
+    )
+    parser.add_argument("--validation-summary", required=True, type=Path)
+    parser.add_argument("--ground-truth-csv", required=True, type=Path)
+    parser.add_argument("--function-symbols-csv", required=True, type=Path)
+    parser.add_argument("--merged-ll", required=True, type=Path)
+    parser.add_argument("--shard-results-json", required=True, type=Path)
+    parser.add_argument("--csv-image-base", required=True, type=lambda value: int(value, 0))
+    parser.add_argument("--rebase-base", required=True, type=lambda value: int(value, 0))
+    parser.add_argument("--summary-out", type=Path)
+    return parser.parse_args()
+
+
+def fn_reason_for_address(
+    addr: int,
+    symbol,
+    shard: Optional[Dict[str, object]],
+    fixture_root: Path,
+) -> Dict[str, object]:
+    evidence: List[str] = []
+    reason = "unknown_fn"
+    priority = "medium"
+
+    if shard is None:
+        return {"reason": "missing_shard_result", "priority": "high", "evidence": evidence}
+
+    status = shard.get("status")
+    coverage = load_coverage_addresses(shard_path(fixture_root, shard.get("coverage_csv")))
+    illegal_path = None
+    if shard.get("coverage_csv"):
+        coverage_path = shard_path(fixture_root, shard.get("coverage_csv"))
+        if coverage_path is not None:
+            illegal_path = coverage_path.with_name(
+                coverage_path.name.replace(".coverage.csv", ".illegalEntry.log")
+            )
+    illegal = load_illegal_addresses(illegal_path)
+    stderr_log = shard_path(fixture_root, shard.get("stderr_log"))
+
+    if addr in illegal:
+        reason = "illegal_entry_suppression"
+        priority = "high"
+        if illegal_path is not None:
+            evidence.append(str(illegal_path))
+    elif status == "timeout":
+        reason = "shard_timeout"
+        priority = "high"
+        if stderr_log:
+            evidence.append(str(stderr_log))
+    elif status == "error":
+        reason = "shard_error"
+        priority = "high"
+        if stderr_log:
+            evidence.append(str(stderr_log))
+    elif status == "empty":
+        reason = "shard_empty"
+        priority = "high"
+        if shard.get("shard_ll"):
+            evidence.append(str(shard_path(fixture_root, shard["shard_ll"])))
+    elif status == "ok" and addr in coverage:
+        reason = "merge_missing"
+        priority = "high"
+        if shard.get("shard_ll"):
+            evidence.append(str(shard_path(fixture_root, shard["shard_ll"])))
+    elif status == "ok":
+        reason = "outside_gt_coverage"
+        priority = "medium"
+    return {"reason": reason, "priority": priority, "evidence": evidence}
+
+
+def fp_reason_for_address(addr: int, gt_instrs, data_ranges) -> Dict[str, object]:
+    if is_continuation_byte(addr, gt_instrs):
+        return {"reason": "continuation_byte", "priority": "medium", "evidence": []}
+    if is_in_ranges(addr, data_ranges):
+        return {"reason": "padding", "priority": "medium", "evidence": []}
+    if neighbor_ground_truth(addr, gt_instrs) and addr % 4 == 0:
+        return {"reason": "ground_truth_gap", "priority": "low", "evidence": []}
+    upper_data_end = max((end for _, end in data_ranges), default=max(gt_instrs))
+    if addr > upper_data_end:
+        return {"reason": "outside_gt_coverage", "priority": "medium", "evidence": []}
+    return {"reason": "extra_lifted_bytes", "priority": "medium", "evidence": []}
+
+
+def main() -> int:
+    args = parse_args()
+    fixture_root = Path.cwd()
+    summary = read_json(args.validation_summary)
+    gt_instrs, data_ranges = load_ground_truth_csv(
+        args.ground_truth_csv,
+        csv_image_base=args.csv_image_base,
+        rebase_base=args.rebase_base,
+    )
+    symbols = load_function_symbols_csv(
+        args.function_symbols_csv,
+        csv_image_base=args.csv_image_base,
+        rebase_base=args.rebase_base,
+    )
+    load_lifted_instruction_map(args.merged_ll)
+    shard_results = load_shard_results(args.shard_results_json)
+
+    findings: List[Dict[str, object]] = []
+    for addr_hex in summary["fn_addresses"]:
+        addr = int(addr_hex, 16)
+        symbol = find_symbol_for_address(symbols, addr)
+        shard = shard_results.get(tag_for_symbol(symbol)) if symbol else None
+        classification = fn_reason_for_address(addr, symbol, shard, fixture_root)
+        findings.append(
+            {
+                "kind": "fn",
+                "address": addr_hex,
+                "reason": classification["reason"],
+                "priority": classification["priority"],
+                "symbol": None if symbol is None else symbol.name,
+                "range": None if symbol is None else f"0x{symbol.start_runtime:x}-0x{symbol.end_runtime:x}",
+                "evidence_paths": classification["evidence"],
+            }
+        )
+
+    for addr_hex in summary["fp_addresses"]:
+        addr = int(addr_hex, 16)
+        classification = fp_reason_for_address(addr, gt_instrs, data_ranges)
+        findings.append(
+            {
+                "kind": "fp",
+                "address": addr_hex,
+                "reason": classification["reason"],
+                "priority": classification["priority"],
+                "symbol": None,
+                "range": None,
+                "evidence_paths": classification["evidence"],
+            }
+        )
+
+    payload = {
+        "validation_summary": str(args.validation_summary.resolve()),
+        "ground_truth_csv": str(args.ground_truth_csv.resolve()),
+        "function_symbols_csv": str(args.function_symbols_csv.resolve()),
+        "merged_ll": str(args.merged_ll.resolve()),
+        "shard_results_json": str(args.shard_results_json.resolve()),
+        "categories": sorted({finding["reason"] for finding in findings}),
+        "findings": findings,
+        "summary": {
+            "fn_count": len(summary["fn_addresses"]),
+            "fp_count": len(summary["fp_addresses"]),
+            "fn_addresses": summary["fn_addresses"],
+            "fp_addresses": summary["fp_addresses"],
+        },
+    }
+    write_json(args.summary_out, payload)
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/runnable/scripts/validate_libcrypto_ground_truth.py b/runnable/scripts/validate_libcrypto_ground_truth.py
new file mode 100644
index 000000000..aedfa8e68
--- /dev/null
+++ b/runnable/scripts/validate_libcrypto_ground_truth.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+from pathlib import Path
+
+from _fn_fp_root_cause_lib import (
+    csv_to_runtime,
+    hex_list,
+    load_function_symbols_csv,
+    load_ground_truth_csv,
+    load_lifted_instruction_map,
+    write_json,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate lifted instructions against a ground-truth CSV and emit TP/FP/FN summary."
+    )
+    parser.add_argument("--ground-truth-csv", required=True, type=Path)
+    parser.add_argument("--ll", required=True, type=Path)
+    parser.add_argument("--function-symbols-csv", required=True, type=Path)
+    parser.add_argument("--csv-image-base", required=True, type=lambda value: int(value, 0))
+    parser.add_argument("--rebase-base", required=True, type=lambda value: int(value, 0))
+    parser.add_argument("--summary-out", type=Path)
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    gt_instrs, data_ranges = load_ground_truth_csv(
+        args.ground_truth_csv,
+        csv_image_base=args.csv_image_base,
+        rebase_base=args.rebase_base,
+    )
+    symbols = load_function_symbols_csv(
+        args.function_symbols_csv,
+        csv_image_base=args.csv_image_base,
+        rebase_base=args.rebase_base,
+    )
+    lifted = load_lifted_instruction_map(args.ll)
+    lifted_addrs = set(lifted)
+
+    tp = sorted(gt_instrs & lifted_addrs)
+    fn = sorted(gt_instrs - lifted_addrs)
+    fp = sorted(lifted_addrs - gt_instrs)
+
+    symbol_payload = []
+    for symbol in symbols:
+        symbol_gt = {addr for addr in gt_instrs if symbol.start_runtime <= addr <= symbol.end_runtime}
+        symbol_lifted = {addr for addr in lifted_addrs if symbol.start_runtime <= addr <= symbol.end_runtime}
+        symbol_payload.append(
+            {
+                "name": symbol.name,
+                "tag": f"fn_{symbol.start_csv:016x}",
+                "start_csv": f"0x{symbol.start_csv:x}",
+                "end_csv": f"0x{symbol.end_csv:x}",
+                "start_runtime": f"0x{symbol.start_runtime:x}",
+                "end_runtime": f"0x{symbol.end_runtime:x}",
+                "tp_addresses": hex_list(symbol_gt & symbol_lifted),
+                "fn_addresses": hex_list(symbol_gt - symbol_lifted),
+            }
+        )
+
+    payload = {
+        "ground_truth_csv": str(args.ground_truth_csv.resolve()),
+        "ll": str(args.ll.resolve()),
+        "function_symbols_csv": str(args.function_symbols_csv.resolve()),
+        "csv_image_base": f"0x{args.csv_image_base:x}",
+        "rebase_base": f"0x{args.rebase_base:x}",
+        "tp": len(tp),
+        "fp": len(fp),
+        "fn": len(fn),
+        "precision": 0.0 if not (len(tp) + len(fp)) else len(tp) / float(len(tp) + len(fp)),
+        "recall": 0.0 if not (len(tp) + len(fn)) else len(tp) / float(len(tp) + len(fn)),
+        "tp_addresses": hex_list(tp),
+        "fp_addresses": hex_list(fp),
+        "fn_addresses": hex_list(fn),
+        "data_ranges": [
+            {"start": f"0x{start:x}", "end": f"0x{end:x}"}
+            for start, end in data_ranges
+        ],
+        "symbols": symbol_payload,
+    }
+    write_json(args.summary_out, payload)
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/test/fixtures/fn_fp_root_cause/function_symbols.csv b/test/fixtures/fn_fp_root_cause/function_symbols.csv
new file mode 100644
index 000000000..45ddbfb5d
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/function_symbols.csv
@@ -0,0 +1,7 @@
+address_hex,symbol
+0x1000,fn_illegal
+0x1008,fn_timeout
+0x100c,fn_merge
+0x1010,fn_empty
+0x1014,fn_error
+0x1018,fn_ground_truth_gap
diff --git a/test/fixtures/fn_fp_root_cause/ground_truth.csv b/test/fixtures/fn_fp_root_cause/ground_truth.csv
new file mode 100644
index 000000000..9b560df05
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/ground_truth.csv
@@ -0,0 +1,9 @@
+kind,name,start_hex,end_hex,source
+code_section,.text,0x1000,0x101f,readelf
+data_section,.rodata,0x1020,0x102f,readelf
+instruction_start,,0x1000,0x1000,objdump
+instruction_start,,0x1005,0x1005,objdump
+instruction_start,,0x1008,0x1008,objdump
+instruction_start,,0x100c,0x100c,objdump
+instruction_start,,0x1010,0x1010,objdump
+instruction_start,,0x1014,0x1014,objdump
diff --git a/test/fixtures/fn_fp_root_cause/merged.ll b/test/fixtures/fn_fp_root_cause/merged.ll
new file mode 100644
index 000000000..518538e65
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/merged.ll
@@ -0,0 +1,13 @@
+define void @root(i64 %pc) {
+entrypoint:
+  br label %bb.0x50000000
+
+bb.0x50000000:
+  ; 0x50000000: mov
+  ; 0x50000002: lea
+  ; 0x50000018: call
+  ; 0x5000001b: jmp
+  ; 0x50000021: mov
+  ; 0x50000030: add
+  ret void
+}
diff --git a/test/fixtures/fn_fp_root_cause/raw/fn_0000000000001000.raw.ll b/test/fixtures/fn_fp_root_cause/raw/fn_0000000000001000.raw.ll
new file mode 100644
index 000000000..d02eccf4f
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/raw/fn_0000000000001000.raw.ll
@@ -0,0 +1,2 @@
+bb.0x50000000:
+  ; 0x50000000: mov
diff --git a/test/fixtures/fn_fp_root_cause/raw/fn_000000000000100c.raw.ll b/test/fixtures/fn_fp_root_cause/raw/fn_000000000000100c.raw.ll
new file mode 100644
index 000000000..31bc97570
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/raw/fn_000000000000100c.raw.ll
@@ -0,0 +1,2 @@
+bb.0x5000000c:
+  ; 0x5000000c: mov
diff --git a/test/fixtures/fn_fp_root_cause/shard_results.json b/test/fixtures/fn_fp_root_cause/shard_results.json
new file mode 100644
index 000000000..daae8f3d2
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/shard_results.json
@@ -0,0 +1,92 @@
+[
+  {
+    "tag": "fn_0000000000001000",
+    "index": 0,
+    "name": "fn_illegal",
+    "start": 4096,
+    "end_inclusive": 4103,
+    "entry_rebased": 1342177280,
+    "range_max_used": 1342177288,
+    "exact_end_exclusive": 1342177288,
+    "status": "ok",
+    "raw_rc": 0,
+    "raw_ll": "test/fixtures/fn_fp_root_cause/raw/fn_0000000000001000.raw.ll",
+    "compact_instruction_count": 1,
+    "shard_ll": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll",
+    "coverage_csv": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll.coverage.csv",
+    "stderr_log": null,
+    "stdout_log": null
+  },
+  {
+    "tag": "fn_0000000000001008",
+    "index": 1,
+    "name": "fn_timeout",
+    "start": 4104,
+    "end_inclusive": 4107,
+    "entry_rebased": 1342177288,
+    "range_max_used": 1342177292,
+    "exact_end_exclusive": 1342177292,
+    "status": "timeout",
+    "raw_rc": 124,
+    "raw_ll": null,
+    "compact_instruction_count": 0,
+    "shard_ll": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001008.ll",
+    "coverage_csv": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001008.ll.coverage.csv",
+    "stderr_log": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001008.stderr.log",
+    "stdout_log": null
+  },
+  {
+    "tag": "fn_000000000000100c",
+    "index": 2,
+    "name": "fn_merge",
+    "start": 4108,
+    "end_inclusive": 4111,
+    "entry_rebased": 1342177292,
+    "range_max_used": 1342177296,
+    "exact_end_exclusive": 1342177296,
+    "status": "ok",
+    "raw_rc": 0,
+    "raw_ll": "test/fixtures/fn_fp_root_cause/raw/fn_000000000000100c.raw.ll",
+    "compact_instruction_count": 1,
+    "shard_ll": "test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll",
+    "coverage_csv": "test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll.coverage.csv",
+    "stderr_log": null,
+    "stdout_log": null
+  },
+  {
+    "tag": "fn_0000000000001010",
+    "index": 3,
+    "name": "fn_empty",
+    "start": 4112,
+    "end_inclusive": 4115,
+    "entry_rebased": 1342177296,
+    "range_max_used": 1342177300,
+    "exact_end_exclusive": 1342177300,
+    "status": "empty",
+    "raw_rc": 0,
+    "raw_ll": null,
+    "compact_instruction_count": 0,
+    "shard_ll": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001010.ll",
+    "coverage_csv": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001010.ll.coverage.csv",
+    "stderr_log": null,
+    "stdout_log": null
+  },
+  {
+    "tag": "fn_0000000000001014",
+    "index": 4,
+    "name": "fn_error",
+    "start": 4116,
+    "end_inclusive": 4119,
+    "entry_rebased": 1342177300,
+    "range_max_used": 1342177304,
+    "exact_end_exclusive": 1342177304,
+    "status": "error",
+    "raw_rc": 1,
+    "raw_ll": null,
+    "compact_instruction_count": 0,
+    "shard_ll": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001014.ll",
+    "coverage_csv": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001014.ll.coverage.csv",
+    "stderr_log": "test/fixtures/fn_fp_root_cause/shards/fn_0000000000001014.stderr.log",
+    "stdout_log": null
+  }
+]
diff --git a/test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll b/test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll
new file mode 100644
index 000000000..d02eccf4f
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll
@@ -0,0 +1,2 @@
+bb.0x50000000:
+  ; 0x50000000: mov
diff --git a/test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll.coverage.csv b/test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll.coverage.csv
new file mode 100644
index 000000000..2a9574abf
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/shards/fn_0000000000001000.ll.coverage.csv
@@ -0,0 +1,2 @@
+0x50000000,1
+0x50000005,1
diff --git a/test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll b/test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll
new file mode 100644
index 000000000..31bc97570
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll
@@ -0,0 +1,2 @@
+bb.0x5000000c:
+  ; 0x5000000c: mov
diff --git a/test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll.coverage.csv b/test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll.coverage.csv
new file mode 100644
index 000000000..fbe65216d
--- /dev/null
+++ b/test/fixtures/fn_fp_root_cause/shards/fn_000000000000100c.ll.coverage.csv
@@ -0,0 +1 @@
+0x5000000c,1
diff --git a/test/test_fn_fp_root_cause_analysis.py b/test/test_fn_fp_root_cause_analysis.py
new file mode 100644
index 000000000..b07325409
--- /dev/null
+++ b/test/test_fn_fp_root_cause_analysis.py
@@ -0,0 +1,132 @@
+import json
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+FIXTURE_DIR = REPO_ROOT / "test" / "fixtures" / "fn_fp_root_cause"
+VALIDATE_SCRIPT = REPO_ROOT / "runnable" / "scripts" / "validate_libcrypto_ground_truth.py"
+ANALYZE_SCRIPT = REPO_ROOT / "runnable" / "scripts" / "analyze_fn_fp_root_causes.py"
+
+
+class FnFpRootCauseAnalysisTest(unittest.TestCase):
+    def test_validate_libcrypto_ground_truth_reports_expected_metrics(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            summary_path = Path(tmpdir) / "validation.json"
+            subprocess.run(
+                [
+                    "python3",
+                    str(VALIDATE_SCRIPT),
+                    "--ground-truth-csv",
+                    str(FIXTURE_DIR / "ground_truth.csv"),
+                    "--ll",
+                    str(FIXTURE_DIR / "merged.ll"),
+                    "--function-symbols-csv",
+                    str(FIXTURE_DIR / "function_symbols.csv"),
+                    "--csv-image-base",
+                    "0x1000",
+                    "--rebase-base",
+                    "0x50000000",
+                    "--summary-out",
+                    str(summary_path),
+                ],
+                check=True,
+                cwd=str(REPO_ROOT),
+                capture_output=True,
+                text=True,
+            )
+
+            summary = json.loads(summary_path.read_text(encoding="utf-8"))
+            self.assertEqual(summary["tp"], 1)
+            self.assertEqual(summary["fp"], 5)
+            self.assertEqual(summary["fn"], 5)
+            self.assertEqual(summary["tp_addresses"], ["0x50000000"])
+            self.assertEqual(summary["fn_addresses"], [
+                "0x50000005",
+                "0x50000008",
+                "0x5000000c",
+                "0x50000010",
+                "0x50000014",
+            ])
+            self.assertEqual(summary["fp_addresses"], [
+                "0x50000002",
+                "0x50000018",
+                "0x5000001b",
+                "0x50000021",
+                "0x50000030",
+            ])
+
+    def test_analyze_fn_fp_root_causes_classifies_expected_reasons(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            summary_path = Path(tmpdir) / "validation.json"
+            analysis_path = Path(tmpdir) / "analysis.json"
+            subprocess.run(
+                [
+                    "python3",
+                    str(VALIDATE_SCRIPT),
+                    "--ground-truth-csv",
+                    str(FIXTURE_DIR / "ground_truth.csv"),
+                    "--ll",
+                    str(FIXTURE_DIR / "merged.ll"),
+                    "--function-symbols-csv",
+                    str(FIXTURE_DIR / "function_symbols.csv"),
+                    "--csv-image-base",
+                    "0x1000",
+                    "--rebase-base",
+                    "0x50000000",
+                    "--summary-out",
+                    str(summary_path),
+                ],
+                check=True,
+                cwd=str(REPO_ROOT),
+                capture_output=True,
+                text=True,
+            )
+            subprocess.run(
+                [
+                    "python3",
+                    str(ANALYZE_SCRIPT),
+                    "--validation-summary",
+                    str(summary_path),
+                    "--ground-truth-csv",
+                    str(FIXTURE_DIR / "ground_truth.csv"),
+                    "--function-symbols-csv",
+                    str(FIXTURE_DIR / "function_symbols.csv"),
+                    "--merged-ll",
+                    str(FIXTURE_DIR / "merged.ll"),
+                    "--shard-results-json",
+                    str(FIXTURE_DIR / "shard_results.json"),
+                    "--csv-image-base",
+                    "0x1000",
+                    "--rebase-base",
+                    "0x50000000",
+                    "--summary-out",
+                    str(analysis_path),
+                ],
+                check=True,
+                cwd=str(REPO_ROOT),
+                capture_output=True,
+                text=True,
+            )
+
+            analysis = json.loads(analysis_path.read_text(encoding="utf-8"))
+            reasons = {
+                finding["address"]: finding["reason"]
+                for finding in analysis["findings"]
+            }
+            self.assertEqual(reasons["0x50000005"], "illegal_entry_suppression")
+            self.assertEqual(reasons["0x50000008"], "shard_timeout")
+            self.assertEqual(reasons["0x5000000c"], "merge_missing")
+            self.assertEqual(reasons["0x50000010"], "shard_empty")
+            self.assertEqual(reasons["0x50000014"], "shard_error")
+            self.assertEqual(reasons["0x50000002"], "continuation_byte")
+            self.assertEqual(reasons["0x50000018"], "ground_truth_gap")
+            self.assertEqual(reasons["0x5000001b"], "extra_lifted_bytes")
+            self.assertEqual(reasons["0x50000021"], "padding")
+            self.assertEqual(reasons["0x50000030"], "outside_gt_coverage")
+
+
+if __name__ == "__main__":
+    unittest.main()

From edae362f25b421d03e4f6ce62b7dd2b0ea2e943a Mon Sep 17 00:00:00 2001
From: iskindar <zhangzhijie1997@qq.com>
Date: Mon, 11 May 2026 23:20:35 +0800
Subject: [PATCH 7/7] fix: add branch-native SYM-20 canonical libcrypto eval
 workflow

---
 .../SKILL.md                                  |  80 +++
 ...05-10-libcrypto-canonical-eval-contract.md |  72 +++
 runnable/CMakeLists.txt                       |   6 +
 .../scripts/_compare_runnable_text_lib.py     | 140 +++++
 runnable/scripts/libcrypto_bench_paths.py     | 215 +++++++
 runnable/scripts/run_cmp_eval.py              | 320 ++++++++++
 .../validate_libcrypto_ground_truth.py        | 584 +++++++++++++++++-
 test/test_libcrypto_bench_paths.py            |  54 ++
 test/test_run_cmp_eval.py                     |  54 ++
 ...runnable_libcrypto_canonical_eval_skill.py |  31 +
 ...lidate_libcrypto_ground_truth_canonical.py | 107 ++++
 11 files changed, 1650 insertions(+), 13 deletions(-)
 create mode 100644 .codex/skills/runnable-libcrypto-canonical-eval/SKILL.md
 create mode 100644 docs/exp/2026-05-10-libcrypto-canonical-eval-contract.md
 create mode 100644 runnable/scripts/_compare_runnable_text_lib.py
 create mode 100644 runnable/scripts/libcrypto_bench_paths.py
 create mode 100644 runnable/scripts/run_cmp_eval.py
 create mode 100644 test/test_libcrypto_bench_paths.py
 create mode 100644 test/test_run_cmp_eval.py
 create mode 100644 test/test_runnable_libcrypto_canonical_eval_skill.py
 create mode 100644 test/test_validate_libcrypto_ground_truth_canonical.py

diff --git a/.codex/skills/runnable-libcrypto-canonical-eval/SKILL.md b/.codex/skills/runnable-libcrypto-canonical-eval/SKILL.md
new file mode 100644
index 000000000..ea5fb1c49
--- /dev/null
+++ b/.codex/skills/runnable-libcrypto-canonical-eval/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: runnable-libcrypto-canonical-eval
+description: Run or audit the canonical libcrypto evaluation contract for SYM-20 using the repo-local ground-truth bundle reachable from this workspace, fresh compare_runnable_text-based compares, and explicit address mapping. Use when a task mentions SYM-20, canonical libcrypto eval, gtBlock.pb, or when historical CSV/coverage-sidecar results must be distinguished from the authoritative compare path.
+---
+
+# Runnable Libcrypto Canonical Eval
+
+Use this skill when the task is specifically about the authoritative libcrypto benchmark contract, not just generic Runnable compare metrics.
+
+## Canonical Contract
+
+For `SYM-20`, the authoritative contract in this workspace is:
+
+1. Canonical binary:
+   - `python3 runnable/scripts/libcrypto_bench_paths.py binary --must-exist`
+2. Canonical ground truth protobuf:
+   - `python3 runnable/scripts/libcrypto_bench_paths.py groundtruth-pb --must-exist`
+3. Protobuf loader:
+   - `python3 runnable/scripts/libcrypto_bench_paths.py blocks-pb2 --must-exist`
+4. Compare tool:
+   - `python3 runnable/scripts/libcrypto_bench_paths.py cmp-tool --must-exist`
+5. Address mapping:
+   - derive `.text` start from the ELF
+   - quick check: `python3 runnable/scripts/libcrypto_bench_paths.py text-start`
+   - keep Runnable rebase at `0x50000000` unless the user explicitly provides another contract
+6. Compare path:
+   - `python3 runnable/scripts/validate_libcrypto_ground_truth.py cmp --ll /abs/path/to/file.ll --out-dir /abs/path/to/out`
+
+The wrapper records fresh `HIT`, `MISMATCH`, `OBJ_ONLY`, `LL_ONLY`, `FALSE_NEGATIVE`, `FALSE_POSITIVE`, `precision`, and `recall`.
+
+## Quick Start
+
+Gap-audit the canonical GT bundle:
+
+```bash
+python3 runnable/scripts/validate_libcrypto_ground_truth.py gap-audit \
+  --out-dir runs/groundtruth_validation/canonical_gap_audit
+```
+
+Compare a lift under the canonical contract:
+
+```bash
+python3 runnable/scripts/validate_libcrypto_ground_truth.py cmp \
+  --ll /abs/path/to/libcrypto.ll \
+  --out-dir runs/groundtruth_validation/canonical_cmp
+```
+
+## Historical / Non-Canonical Paths
+
+Do **not** report the following as the canonical `SYM-20` result without an explicit label:
+
+- `coverage_sidecar_union_threadpool16`
+- CSV-only GT flows such as `ground_truth.csv`
+- `rebase_base=0x50400000`
+- old libcrypto binaries whose SHA differs from the repo-local canonical bundle
+
+When historical artifacts are involved, report them as:
+
+- `historical sidecar-union / non-canonical`
+- `old-binary compare / non-canonical`
+- `canonical gtBlock.pb compare / authoritative`
+
+## Required Reporting
+
+Always include:
+
+- absolute binary path
+- absolute GT path
+- absolute `.ll` path
+- `.text` start
+- Runnable base
+- `HIT`, `MISMATCH`, `OBJ_ONLY`, `LL_ONLY`
+- `FALSE_NEGATIVE`, `FALSE_POSITIVE`
+- `precision`, `recall`
+- whether the result is `canonical` or `non-canonical`
+
+## Repo Notes
+
+- The canonical binary / protobuf are auto-discovered from this workspace's `GroudTruth` checkout, not from a checked-in `archives/` directory under `Runnable-Rewriting`.
+- `runnable/scripts/validate_libcrypto_ground_truth.py` still supports the legacy CSV validation mode used by existing fn/fp root-cause tests; use `csv-validate` only for that older flow.
diff --git a/docs/exp/2026-05-10-libcrypto-canonical-eval-contract.md b/docs/exp/2026-05-10-libcrypto-canonical-eval-contract.md
new file mode 100644
index 000000000..b8ee677cd
--- /dev/null
+++ b/docs/exp/2026-05-10-libcrypto-canonical-eval-contract.md
@@ -0,0 +1,72 @@
+# 2026-05-10 libcrypto canonical eval contract
+
+## Goal
+
+修复 `SYM-20` 里 `libcrypto` 的评估口径错配，把当前 workspace 可直接验证的 canonical contract、历史 non-canonical 路径、以及 repo-local compare tooling 拆开记录清楚。
+
+## Canonical Inputs In This Workspace
+
+- Canonical binary:
+  - `../GroudTruth/groundtruth-gap-analysis-skill/results/libcrypto-artifacts/libcrypto.so.3`
+- Canonical GT:
+  - `../GroudTruth/groundtruth-gap-analysis-skill/results/libcrypto-artifacts/libcrypto.gtBlock.pb`
+- Canonical protobuf loader:
+  - `../GroudTruth/protobuf_def/blocks_pb2.py`
+- Canonical compare wrapper:
+  - `runnable/scripts/run_cmp_eval.py`
+- Canonical audit / compare entrypoint:
+  - `runnable/scripts/validate_libcrypto_ground_truth.py`
+
+These paths are discovered by `runnable/scripts/libcrypto_bench_paths.py`.
+
+## Important Correction
+
+The earlier `SYM-20` branch version assumed top-level `scripts/`, `tests/`, and `archives/...` paths inside `Runnable-Rewriting`. That does not match the current `codex/dynamic-parallel-lift` branch layout.
+
+For this branch, the correct repo-local structure is:
+
+- scripts under `runnable/scripts/`
+- tests under `test/`
+- canonical binary / gtBlock bundle discovered from the sibling `GroudTruth` checkout
+
+## Commands
+
+Resolve canonical assets:
+
+```bash
+python3 runnable/scripts/libcrypto_bench_paths.py binary --must-exist
+python3 runnable/scripts/libcrypto_bench_paths.py groundtruth-pb --must-exist
+python3 runnable/scripts/libcrypto_bench_paths.py blocks-pb2 --must-exist
+python3 runnable/scripts/libcrypto_bench_paths.py cmp-tool --must-exist
+python3 runnable/scripts/libcrypto_bench_paths.py text-start
+```
+
+Gap-audit canonical GT coverage:
+
+```bash
+python3 runnable/scripts/validate_libcrypto_ground_truth.py gap-audit \
+  --out-dir runs/groundtruth_validation/canonical_gap_audit
+```
+
+Compare a lift under the canonical contract:
+
+```bash
+python3 runnable/scripts/validate_libcrypto_ground_truth.py cmp \
+  --ll /abs/path/to/libcrypto.ll \
+  --out-dir runs/groundtruth_validation/canonical_cmp
+```
+
+## Historical vs Canonical
+
+`SYM-19` results using:
+
+- `coverage_sidecar_union_threadpool16`
+- CSV GT bundles
+- `rebase_base=0x50400000`
+- the old `test/openssl_data/libcrypto.so.3`
+
+must be treated as `historical sidecar-union / non-canonical`, not directly compared against canonical `gtBlock.pb` metrics.
+
+## Current Caveat
+
+This branch now contains the canonical compare wrappers and path resolution logic, but it does **not** vendor the large libcrypto run artifacts themselves into the `Runnable-Rewriting` git repository. The workflow is repo-local in the sense that the scripts and skill are committed here; the binary / protobuf assets are discovered from the co-located `GroudTruth` checkout.
diff --git a/runnable/CMakeLists.txt b/runnable/CMakeLists.txt
index b5db21034..b43e55bcb 100644
--- a/runnable/CMakeLists.txt
+++ b/runnable/CMakeLists.txt
@@ -161,12 +161,17 @@ configure_file(scripts/runnable "${CMAKE_BINARY_DIR}/runnable" COPYONLY)
 configure_file(scripts/runnable-merge-dynamic "${CMAKE_BINARY_DIR}/runnable-merge-dynamic" COPYONLY)
 configure_file(scripts/merge_dynamic_runnable_fragments.py "${CMAKE_BINARY_DIR}/merge_dynamic_runnable_fragments.py" COPYONLY)
 configure_file(scripts/_merge_dynamic_fragments_lib.py "${CMAKE_BINARY_DIR}/_merge_dynamic_fragments_lib.py" COPYONLY)
+configure_file(scripts/_compare_runnable_text_lib.py "${CMAKE_BINARY_DIR}/_compare_runnable_text_lib.py" COPYONLY)
+configure_file(scripts/libcrypto_bench_paths.py "${CMAKE_BINARY_DIR}/libcrypto_bench_paths.py" COPYONLY)
+configure_file(scripts/run_cmp_eval.py "${CMAKE_BINARY_DIR}/run_cmp_eval.py" COPYONLY)
 configure_file(scripts/validate_libcrypto_ground_truth.py "${CMAKE_BINARY_DIR}/validate_libcrypto_ground_truth.py" COPYONLY)
 configure_file(scripts/analyze_fn_fp_root_causes.py "${CMAKE_BINARY_DIR}/analyze_fn_fp_root_causes.py" COPYONLY)
 configure_file(scripts/_fn_fp_root_cause_lib.py "${CMAKE_BINARY_DIR}/_fn_fp_root_cause_lib.py" COPYONLY)
 install(PROGRAMS scripts/runnable scripts/runnable-merge-dynamic DESTINATION bin)
 install(PROGRAMS
   scripts/merge_dynamic_runnable_fragments.py
+  scripts/libcrypto_bench_paths.py
+  scripts/run_cmp_eval.py
   scripts/validate_libcrypto_ground_truth.py
   scripts/analyze_fn_fp_root_causes.py
   DESTINATION share/runnable)
@@ -174,6 +179,7 @@ install(FILES runtime/support.c DESTINATION share/runnable)
 install(FILES runtime/support.h DESTINATION share/runnable)
 install(FILES include/runnable/Runtime/commonconstants.h DESTINATION share/runnable)
 install(FILES
+  scripts/_compare_runnable_text_lib.py
   scripts/_merge_dynamic_fragments_lib.py
   scripts/_fn_fp_root_cause_lib.py
   DESTINATION share/runnable)
diff --git a/runnable/scripts/_compare_runnable_text_lib.py b/runnable/scripts/_compare_runnable_text_lib.py
new file mode 100644
index 000000000..3e759a68f
--- /dev/null
+++ b/runnable/scripts/_compare_runnable_text_lib.py
@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+
+from __future__ import print_function
+
+import collections
+import re
+import subprocess
+
+
+OBJ_RE = re.compile(r"^\s+([0-9a-fA-F]+):\t(.*?)\t(.*)$")
+OBJ_BLANK_RE = re.compile(r"^\s+([0-9a-fA-F]+):\t(.*)$")
+LL_RE = re.compile(r"^\s*;\s*(0x[0-9a-fA-F]+):\s+(.*)$")
+IGNORE_TOKENS = ("nop", "data", "xchg")
+ADV_MAP = {
+    "cqto": "cqo",
+    "cltd": "cdq",
+    "cltq": "cdqe",
+    "cbtw": "cbw",
+    "cwtl": "cwde",
+}
+
+
+def adv_cmp(op1, op2):
+    return ADV_MAP.get(op1) == op2
+
+
+def op_match(op1, op2):
+    return (
+        op1 == op2
+        or op1 in op2
+        or op2 in op1
+        or ("mov" in op1 and "mov" in op2)
+        or adv_cmp(op1, op2)
+        or adv_cmp(op2, op1)
+    )
+
+
+def parse_objdump(binary_path, text_start):
+    out = subprocess.check_output(["objdump", "-d", str(binary_path)], universal_newlines=True)
+    instructions = collections.OrderedDict()
+
+    for line in out.splitlines():
+        match = OBJ_RE.match(line)
+        if match is not None:
+            addr = int(match.group(1), 16)
+            if addr < text_start:
+                continue
+            asm = match.group(3)
+            op_matcher = re.match(r"^(\S+)\s*(.*)$", asm)
+            ins = op_matcher.group(1) if op_matcher else asm.strip()
+            if ins and not any(token in ins for token in IGNORE_TOKENS):
+                instructions[addr] = ins
+            continue
+
+        match = OBJ_BLANK_RE.match(line)
+        if match is not None:
+            addr = int(match.group(1), 16)
+            if addr < text_start:
+                continue
+
+    return instructions
+
+
+def parse_ll_raw(ll_path):
+    instructions = collections.OrderedDict()
+    with open(ll_path, "r", errors="ignore") as handle:
+        for line in handle:
+            match = LL_RE.match(line)
+            if match is None:
+                continue
+            raw_addr = int(match.group(1), 16)
+            asm = match.group(2).strip()
+            op_matcher = re.match(r"^(\S+)\s*(\S*)", asm)
+            ins = op_matcher.group(1) if op_matcher else asm.split()[0]
+            if ins and not any(token in ins for token in IGNORE_TOKENS):
+                instructions[raw_addr] = ins
+    return instructions
+
+
+def normalize_ll_addresses(raw_instructions, text_start, base):
+    instructions = collections.OrderedDict()
+    for raw_addr, ins in raw_instructions.items():
+        addr = raw_addr - base if raw_addr >= base else raw_addr
+        if addr < text_start:
+            continue
+        instructions[addr] = ins
+    return instructions
+
+
+def compare(obj_instructions, ll_instructions, example_limit):
+    hits = 0
+    mismatch = 0
+    obj_only = 0
+    ll_only = 0
+    mismatch_examples = []
+    obj_only_examples = []
+    ll_only_examples = []
+
+    for addr, obj_ins in obj_instructions.items():
+        ll_ins = ll_instructions.get(addr)
+        if ll_ins is None:
+            obj_only += 1
+            if len(obj_only_examples) < example_limit:
+                obj_only_examples.append((addr, obj_ins))
+            continue
+        if op_match(obj_ins, ll_ins):
+            hits += 1
+        else:
+            mismatch += 1
+            if len(mismatch_examples) < example_limit:
+                mismatch_examples.append((addr, obj_ins, ll_ins))
+
+    for addr, ll_ins in ll_instructions.items():
+        if addr not in obj_instructions:
+            ll_only += 1
+            if len(ll_only_examples) < example_limit:
+                ll_only_examples.append((addr, ll_ins))
+
+    false_negative = obj_only + mismatch
+    false_positive = ll_only + mismatch
+    obj_count = len(obj_instructions)
+    ll_count = len(ll_instructions)
+    recall = float(hits) / obj_count if obj_count else 0.0
+    precision = float(hits) / ll_count if ll_count else 0.0
+
+    return {
+        "obj_count": obj_count,
+        "ll_count": ll_count,
+        "hit": hits,
+        "mismatch": mismatch,
+        "obj_only": obj_only,
+        "ll_only": ll_only,
+        "false_negative": false_negative,
+        "false_positive": false_positive,
+        "recall": recall,
+        "precision": precision,
+        "mismatch_examples": mismatch_examples,
+        "obj_only_examples": obj_only_examples,
+        "ll_only_examples": ll_only_examples,
+    }
diff --git a/runnable/scripts/libcrypto_bench_paths.py b/runnable/scripts/libcrypto_bench_paths.py
new file mode 100644
index 000000000..2b8a012cd
--- /dev/null
+++ b/runnable/scripts/libcrypto_bench_paths.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Iterable, List
+
+
+ROOT_DIR = Path(__file__).resolve().parents[2]
+WORKSPACE_ROOT = ROOT_DIR.parent
+BENCH_ROOT_ENV = "RUNNABLE_LIBCRYPTO_BENCH_ROOT"
+GROUND_TRUTH_ENV = "RUNNABLE_LIBCRYPTO_GROUND_TRUTH"
+GROUND_TRUTH_PB_ENV = "RUNNABLE_LIBCRYPTO_GROUND_TRUTH_PB"
+CANONICAL_TEXT_START_ENV = "RUNNABLE_LIBCRYPTO_TEXT_START"
+CANONICAL_GT_DIRNAME = "libcrypto_groudtruth_20260428"
+LEGACY_GT_DIRNAME = "libcrypto_master_test_20260414"
+READELF_TEXT_RE = re.compile(r"^\s*\[\s*\d+\]\s+(\S+)\s+\S+\s+([0-9a-fA-F]+)\s")
+
+
+def _unique_paths(paths: Iterable[Path]) -> List[Path]:
+    unique: List[Path] = []
+    seen: set[str] = set()
+    for path in paths:
+        key = os.path.normpath(str(path.expanduser()))
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(Path(key))
+    return unique
+
+
+def configured_bench_roots(repo_root: Path = ROOT_DIR) -> List[Path]:
+    candidates: List[Path] = []
+    workspace_root = repo_root.parent
+
+    env_root = os.environ.get(BENCH_ROOT_ENV)
+    if env_root:
+        candidates.append(Path(env_root).expanduser())
+
+    # Repo-local canonical artifacts currently live under GroudTruth results.
+    candidates.extend(
+        [
+            workspace_root / "GroudTruth" / "groundtruth-gap-analysis-skill" / "results" / "libcrypto-artifacts",
+            workspace_root / "GroudTruth" / "groundtruth-gap-analysis-skill" / "results",
+            workspace_root / "GroudTruth",
+            repo_root / "GroudTruth" / "groundtruth-gap-analysis-skill" / "results" / "libcrypto-artifacts",
+            repo_root / "GroudTruth" / "groundtruth-gap-analysis-skill" / "results",
+            repo_root / "GroudTruth",
+            repo_root,
+        ]
+    )
+
+    return _unique_paths(candidates)
+
+
+def _binary_candidates_from_root(root: Path) -> List[Path]:
+    root = root.expanduser()
+    if root.name == "libcrypto.so.3" or root.is_file():
+        return [root]
+
+    candidates = [
+        root / "libcrypto.so.3",
+        root / CANONICAL_GT_DIRNAME / "libcrypto.so.3",
+        root / LEGACY_GT_DIRNAME / "libcrypto.so.3",
+        root / "archives" / "groundtruth" / CANONICAL_GT_DIRNAME / "libcrypto.so.3",
+        root / "archives" / "experiments" / LEGACY_GT_DIRNAME / "libcrypto.so.3",
+        root / "groundtruth-gap-analysis-skill" / "results" / "libcrypto-artifacts" / "libcrypto.so.3",
+    ]
+    return _unique_paths(candidates)
+
+
+def binary_candidates(repo_root: Path = ROOT_DIR) -> List[Path]:
+    candidates: List[Path] = []
+    exact = os.environ.get(GROUND_TRUTH_ENV)
+    if exact:
+        candidates.append(Path(exact).expanduser())
+    for root in configured_bench_roots(repo_root):
+        candidates.extend(_binary_candidates_from_root(root))
+    return _unique_paths(candidates)
+
+
+def default_ground_truth_binary(repo_root: Path = ROOT_DIR) -> Path:
+    candidates = binary_candidates(repo_root)
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+    return candidates[0]
+
+
+def _groundtruth_pb_candidates(binary: Path, repo_root: Path = ROOT_DIR) -> List[Path]:
+    candidates: List[Path] = []
+
+    env_path = os.environ.get(GROUND_TRUTH_PB_ENV)
+    if env_path:
+        candidates.append(Path(env_path).expanduser())
+
+    if ".so" in binary.name:
+        base = binary.name.split(".so", 1)[0]
+        candidates.append(binary.with_name(f"{base}.gtBlock.pb"))
+    candidates.append(Path(str(binary) + ".gtBlock.pb"))
+    candidates.append(binary.with_name(f"{binary.name}.gtBlock.pb"))
+
+    candidates.extend(
+        [
+            repo_root / "GroudTruth" / "groundtruth-gap-analysis-skill" / "results" / "libcrypto-artifacts" / "libcrypto.gtBlock.pb",
+            repo_root / "archives" / "groundtruth" / CANONICAL_GT_DIRNAME / "libcrypto.gtBlock.pb",
+        ]
+    )
+    return _unique_paths(candidates)
+
+
+def default_groundtruth_pb(repo_root: Path = ROOT_DIR) -> Path:
+    binary = default_ground_truth_binary(repo_root)
+    candidates = _groundtruth_pb_candidates(binary, repo_root)
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+    return candidates[0]
+
+
+def default_blocks_pb2(repo_root: Path = ROOT_DIR) -> Path:
+    workspace_root = repo_root.parent
+    candidates = [
+        workspace_root / "GroudTruth" / "protobuf_def" / "blocks_pb2.py",
+        workspace_root / "GroudTruth" / "extract_gt" / "pemap" / "blocks_pb2.py",
+        repo_root / "GroudTruth" / "protobuf_def" / "blocks_pb2.py",
+        repo_root / "GroudTruth" / "extract_gt" / "pemap" / "blocks_pb2.py",
+        Path(__file__).resolve().parent / "_vendor" / "blocks_pb2.py",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+    return candidates[0]
+
+
+def default_compare_tool(repo_root: Path = ROOT_DIR) -> Path:
+    candidates = [
+        Path(__file__).resolve().parent / "run_cmp_eval.py",
+        repo_root / ".codex" / "skills" / "runnable-cmp-eval" / "scripts" / "run_cmp_eval.py",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+    return candidates[0]
+
+
+def parse_text_start_from_readelf_output(output: str) -> int:
+    for line in output.splitlines():
+        match = READELF_TEXT_RE.match(line)
+        if match and match.group(1) == ".text":
+            return int(match.group(2), 16)
+    raise RuntimeError("cannot detect .text start from readelf output")
+
+
+def detect_text_start(binary: Path) -> int:
+    result = subprocess.run(
+        ["readelf", "-WS", str(binary)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return parse_text_start_from_readelf_output(result.stdout)
+
+
+def canonical_text_start(repo_root: Path = ROOT_DIR) -> int:
+    env_value = os.environ.get(CANONICAL_TEXT_START_ENV)
+    if env_value:
+        return int(env_value, 0)
+    return detect_text_start(default_ground_truth_binary(repo_root))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Resolve canonical libcrypto benchmark asset paths."
+    )
+    parser.add_argument(
+        "kind",
+        choices=["bench-root", "binary", "groundtruth-pb", "blocks-pb2", "cmp-tool", "text-start"],
+    )
+    parser.add_argument("--repo-root", type=Path, default=ROOT_DIR)
+    parser.add_argument("--must-exist", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    repo_root = args.repo_root.resolve()
+
+    if args.kind == "bench-root":
+        value = configured_bench_roots(repo_root)[0]
+    elif args.kind == "binary":
+        value = default_ground_truth_binary(repo_root)
+    elif args.kind == "groundtruth-pb":
+        value = default_groundtruth_pb(repo_root)
+    elif args.kind == "blocks-pb2":
+        value = default_blocks_pb2(repo_root)
+    elif args.kind == "cmp-tool":
+        value = default_compare_tool(repo_root)
+    else:
+        value = hex(canonical_text_start(repo_root))
+
+    if args.kind != "text-start" and args.must_exist and not value.exists():
+        print(str(value), file=sys.stderr)
+        return 2
+    print(str(value))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/runnable/scripts/run_cmp_eval.py b/runnable/scripts/run_cmp_eval.py
new file mode 100644
index 000000000..aea0caab2
--- /dev/null
+++ b/runnable/scripts/run_cmp_eval.py
@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+
+import argparse
+from collections import Counter
+import json
+import re
+import sys
+from pathlib import Path
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import _compare_runnable_text_lib as compare_text
+
+
+OBJ_INST_RE = re.compile(r"^\s+([0-9a-fA-F]+):\t")
+LL_INST_RE = re.compile(r"^\s*;\s*(0x[0-9a-fA-F]+):")
+READELF_TEXT_RE = re.compile(r"^\s*\[\s*\d+\]\s+(\S+)\s+\S+\s+([0-9a-fA-F]+)\s")
+OBJDUMP_TEXT_RE = re.compile(r"^\s*\d+\s+(\S+)\s+[0-9a-fA-F]+\s+([0-9a-fA-F]+)\s")
+ELF_MAGIC = b"\x7fELF"
+
+
+def is_elf(path: Path):
+    try:
+        with path.open("rb") as f:
+            return f.read(4) == ELF_MAGIC
+    except OSError:
+        return False
+
+
+def parse_int(value: str):
+    return int(value, 0)
+
+
+def resolve_paths(args):
+    sample_base = Path(args.base).resolve() if args.base else None
+    binary = Path(args.binary).resolve() if args.binary else sample_base
+    ll = Path(args.ll).resolve() if args.ll else (Path(str(sample_base) + ".ll") if sample_base else None)
+
+    if binary is None or ll is None:
+        raise ValueError("provide --base, or provide both --binary and --ll")
+
+    missing = [str(path) for path in (binary, ll) if not path.exists()]
+    if missing:
+        raise FileNotFoundError("\n".join(missing))
+
+    if not is_elf(binary):
+        raise ValueError(
+            f"{binary} is not an ELF binary. "
+            "The compare_runnable_text workflow needs the real ground-truth binary or shared library."
+        )
+
+    return sample_base, binary, ll
+
+
+def detect_text_start_readelf(binary: Path):
+    import subprocess
+
+    out = subprocess.check_output(["readelf", "-WS", str(binary)], text=True)
+    for line in out.splitlines():
+        match = READELF_TEXT_RE.match(line)
+        if match and match.group(1) == ".text":
+            return int(match.group(2), 16)
+    return None
+
+
+def detect_text_start_objdump(binary: Path):
+    import subprocess
+
+    out = subprocess.check_output(["objdump", "-h", str(binary)], text=True)
+    for line in out.splitlines():
+        match = OBJDUMP_TEXT_RE.match(line)
+        if match and match.group(1) == ".text":
+            return int(match.group(2), 16)
+    return None
+
+
+def detect_text_start(binary: Path):
+    for detector in (detect_text_start_readelf, detect_text_start_objdump):
+        try:
+            text_start = detector(binary)
+        except Exception:
+            text_start = None
+        if text_start is not None:
+            return text_start
+    raise RuntimeError(f"cannot detect .text start for {binary}")
+
+
+def sample_obj_addresses(binary: Path, text_start: int, limit: int = 4096):
+    import subprocess
+
+    addrs = []
+    proc = subprocess.Popen(
+        ["objdump", "-d", str(binary)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    try:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            match = OBJ_INST_RE.match(line.rstrip("\n"))
+            if not match:
+                continue
+            addr = int(match.group(1), 16)
+            if addr < text_start:
+                continue
+            addrs.append(addr)
+            if len(addrs) >= limit:
+                break
+    finally:
+        if proc.stdout is not None:
+            proc.stdout.close()
+        proc.kill()
+        proc.wait()
+    return addrs
+
+
+def sample_ll_raw_addresses(ll_path: Path, limit: int = 4096):
+    addrs = []
+    with ll_path.open("r", encoding="utf-8", errors="ignore") as f:
+        for line in f:
+            match = LL_INST_RE.match(line.rstrip("\n"))
+            if not match:
+                continue
+            addrs.append(int(match.group(1), 16))
+            if len(addrs) >= limit:
+                break
+    return addrs
+
+
+def detect_runnable_base(binary: Path, ll_path: Path, text_start: int):
+    obj_addrs = sample_obj_addresses(binary, text_start)
+    ll_addrs = sample_ll_raw_addresses(ll_path)
+    if not obj_addrs or not ll_addrs:
+        return 0
+
+    obj_set = set(obj_addrs)
+    counts = Counter()
+    for ll_addr in set(ll_addrs):
+        for obj_addr in obj_set:
+            delta = ll_addr - obj_addr
+            if (delta & 0xFFF) == 0:
+                counts[delta] += 1
+
+    if counts:
+        return counts.most_common(1)[0][0]
+    return min(ll_addrs) - min(obj_addrs)
+
+
+def format_example_block(name: str, examples, formatter):
+    lines = [f"[{name}]"]
+    for item in examples:
+        lines.append(formatter(item))
+    return "\n".join(lines)
+
+
+def serialize_examples(examples, kind: str):
+    payload = []
+    for item in examples:
+        if kind == "mismatch":
+            addr, obj_ins, ll_ins = item
+            payload.append({"address": hex(addr), "obj": obj_ins, "ll": ll_ins})
+        else:
+            addr, ins = item
+            payload.append({"address": hex(addr), "instruction": ins})
+    return payload
+
+
+def write_text_summary(path: Path, payload: dict):
+    lines = [
+        f"sample_base={payload['sample_base']}",
+        f"binary={payload['binary']}",
+        f"ll={payload['ll']}",
+        f"source={payload['source']}",
+        f"text_start=0x{payload['text_start']:x}",
+        f"runnable_base=0x{payload['runnable_base']:x}",
+        f"obj_count={payload['obj_count']}",
+        f"ll_count={payload['ll_count']}",
+        f"hit={payload['hit']}",
+        f"mismatch={payload['mismatch']}",
+        f"obj_only={payload['obj_only']}",
+        f"ll_only={payload['ll_only']}",
+        f"false_negative={payload['false_negative']}",
+        f"false_positive={payload['false_positive']}",
+        f"precision={payload['precision']:.6f}",
+        f"recall={payload['recall']:.6f}",
+    ]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def build_payload(sample_base, binary, ll, text_start, runnable_base, examples, result):
+    return {
+        "sample_base": str(sample_base) if sample_base is not None else None,
+        "binary": str(binary),
+        "ll": str(ll),
+        "source": "fresh_compare_runnable_text",
+        "text_start": text_start,
+        "runnable_base": runnable_base,
+        "example_limit": examples,
+        "obj_count": result["obj_count"],
+        "ll_count": result["ll_count"],
+        "hit": result["hit"],
+        "mismatch": result["mismatch"],
+        "obj_only": result["obj_only"],
+        "ll_only": result["ll_only"],
+        "false_negative": result["false_negative"],
+        "false_positive": result["false_positive"],
+        "precision": result["precision"],
+        "recall": result["recall"],
+        "mismatch_examples": serialize_examples(result["mismatch_examples"], "mismatch"),
+        "obj_only_examples": serialize_examples(result["obj_only_examples"], "single"),
+        "ll_only_examples": serialize_examples(result["ll_only_examples"], "single"),
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Run Runnable compare_runnable_text evaluation.")
+    ap.add_argument("--base", help="Common base where <base> is the ELF and <base>.ll is the lift")
+    ap.add_argument("--binary", help="Path to the ground-truth ELF/shared library")
+    ap.add_argument("--ll", help="Path to the Runnable lift .ll file")
+    ap.add_argument(
+        "--text-start",
+        default="auto",
+        help="First binary virtual address to include. Use 'auto' or an integer like 0xcf000.",
+    )
+    ap.add_argument(
+        "--runnable-base",
+        default="auto",
+        help="Base to subtract from ll addresses. Use 'auto' or an integer like 0x50000000.",
+    )
+    ap.add_argument("--examples", type=int, default=10, help="How many sample lines to keep for each category")
+    ap.add_argument("--json-out", help="Optional JSON summary output path")
+    ap.add_argument("--text-out", help="Optional text summary output path")
+    ap.add_argument(
+        "--rerun",
+        action="store_true",
+        help="Accepted for compatibility. The compare workflow already runs fresh each time.",
+    )
+    args = ap.parse_args()
+
+    try:
+        sample_base, binary, ll = resolve_paths(args)
+    except Exception as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    if args.text_start == "auto":
+        text_start = detect_text_start(binary)
+    else:
+        text_start = parse_int(args.text_start)
+
+    if args.runnable_base == "auto":
+        runnable_base = detect_runnable_base(binary, ll, text_start)
+    else:
+        runnable_base = parse_int(args.runnable_base)
+
+    obj_instructions = compare_text.parse_objdump(binary, text_start)
+    ll_raw = compare_text.parse_ll_raw(ll)
+    ll_instructions = compare_text.normalize_ll_addresses(ll_raw, text_start, runnable_base)
+    result = compare_text.compare(obj_instructions, ll_instructions, args.examples)
+
+    payload = build_payload(sample_base, binary, ll, text_start, runnable_base, args.examples, result)
+
+    if args.json_out:
+        json_path = Path(args.json_out).resolve()
+        json_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    if args.text_out:
+        write_text_summary(Path(args.text_out).resolve(), payload)
+
+    print(f"sample_base={payload['sample_base']}")
+    print(f"binary={payload['binary']}")
+    print(f"ll={payload['ll']}")
+    print(f"source={payload['source']}")
+    print(f"text_start=0x{payload['text_start']:x}")
+    print(f"runnable_base=0x{payload['runnable_base']:x}")
+    print(f"obj_count={payload['obj_count']}")
+    print(f"ll_count={payload['ll_count']}")
+    print(f"hit={payload['hit']}")
+    print(f"mismatch={payload['mismatch']}")
+    print(f"obj_only={payload['obj_only']}")
+    print(f"ll_only={payload['ll_only']}")
+    print(f"false_negative={payload['false_negative']}")
+    print(f"false_positive={payload['false_positive']}")
+    print(f"precision={payload['precision']:.6f}")
+    print(f"recall={payload['recall']:.6f}")
+    print("formula_false_negative=obj_only + mismatch")
+    print("formula_false_positive=ll_only + mismatch")
+    print()
+    print(
+        format_example_block(
+            "MISMATCH_EXAMPLES",
+            result["mismatch_examples"],
+            lambda item: f"{hex(item[0])}\tOBJ={item[1]}\tLL={item[2]}",
+        )
+    )
+    print()
+    print(
+        format_example_block(
+            "OBJ_ONLY_EXAMPLES",
+            result["obj_only_examples"],
+            lambda item: f"{hex(item[0])}\tOBJ={item[1]}",
+        )
+    )
+    print()
+    print(
+        format_example_block(
+            "LL_ONLY_EXAMPLES",
+            result["ll_only_examples"],
+            lambda item: f"{hex(item[0])}\tLL={item[1]}",
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/runnable/scripts/validate_libcrypto_ground_truth.py b/runnable/scripts/validate_libcrypto_ground_truth.py
index aedfa8e68..f2c8cadd6 100644
--- a/runnable/scripts/validate_libcrypto_ground_truth.py
+++ b/runnable/scripts/validate_libcrypto_ground_truth.py
@@ -1,34 +1,435 @@
 #!/usr/bin/env python3
 
+from __future__ import annotations
+
 import argparse
+import bisect
+import collections
+import importlib.util
 import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
 
 from _fn_fp_root_cause_lib import (
-    csv_to_runtime,
     hex_list,
     load_function_symbols_csv,
     load_ground_truth_csv,
     load_lifted_instruction_map,
     write_json,
 )
+from libcrypto_bench_paths import (
+    canonical_text_start,
+    default_blocks_pb2,
+    default_compare_tool,
+    default_ground_truth_binary,
+    default_groundtruth_pb,
+)
 
 
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Validate lifted instructions against a ground-truth CSV and emit TP/FP/FN summary."
+ROOT_DIR = Path(__file__).resolve().parents[2]
+DEFAULT_BINARY = default_ground_truth_binary(ROOT_DIR)
+DEFAULT_GROUNDTRUTH = default_groundtruth_pb(ROOT_DIR)
+DEFAULT_RUN_CMP_EVAL = default_compare_tool(ROOT_DIR)
+DEFAULT_VENDOR_BLOCKS_PB2 = default_blocks_pb2(ROOT_DIR)
+DEFAULT_OUT_DIR = ROOT_DIR / "runs" / "groundtruth_validation"
+DEFAULT_RUNNABLE_BASE = 0x50000000
+DEFAULT_MIN_PRECISION = 0.80
+DEFAULT_MIN_RECALL = 0.80
+READELF_TEXT_RE = re.compile(r"^\s*\[\s*\d+\]\s+(\S+)\s+\S+\s+([0-9a-fA-F]+)\s")
+OBJDUMP_INST_RE = re.compile(r"^\s*([0-9a-fA-F]+):\s+((?:[0-9a-fA-F]{2}\s)+)\s*(.*)$")
+
+
+@dataclass
+class CmpVerdict:
+    ok: bool
+    reasons: List[str]
+
+
+def parse_int(value: str) -> int:
+    return int(value, 0)
+
+
+def ensure_file(path: Path, label: str) -> None:
+    if not path.is_file():
+        raise FileNotFoundError(f"{label} not found: {path}")
+
+
+def ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def run_cmd(cmd: Sequence[str], *, check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, check=check, text=True, capture_output=True)
+
+
+def read_json(path: Path) -> Dict[str, object]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_text(path: Path, lines: Iterable[str]) -> None:
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def detect_text_start(binary: Path) -> int:
+    out = run_cmd(["readelf", "-WS", str(binary)]).stdout
+    for line in out.splitlines():
+        match = READELF_TEXT_RE.match(line)
+        if match and match.group(1) == ".text":
+            return int(match.group(2), 16)
+    raise RuntimeError(f"cannot detect .text start for {binary}")
+
+
+def resolve_default_groundtruth_path(binary: Path) -> Path:
+    candidates: List[Path] = []
+    if ".so" in binary.name:
+        base = binary.name.split(".so", 1)[0]
+        candidates.append(binary.with_name(f"{base}.gtBlock.pb"))
+    candidates.append(Path(str(binary) + ".gtBlock.pb"))
+    candidates.append(binary.with_name(f"{binary.name}.gtBlock.pb"))
+
+    seen = set()
+    for candidate in candidates:
+        if candidate in seen:
+            continue
+        seen.add(candidate)
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(
+        f"could not infer groundtruth protobuf next to {binary}; tried: "
+        + ", ".join(str(path) for path in candidates)
+    )
+
+
+def load_blocks_pb2(path: Path):
+    spec = importlib.util.spec_from_file_location("groundtruth_blocks_pb2", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load protobuf module from {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def merge_ranges(ranges: Iterable[Tuple[int, int]]) -> List[Tuple[int, int]]:
+    sorted_ranges = sorted(ranges)
+    merged: List[List[int]] = []
+    for start, end in sorted_ranges:
+        if not merged or start > merged[-1][1]:
+            merged.append([start, end])
+            continue
+        merged[-1][1] = max(merged[-1][1], end)
+    return [(start, end) for start, end in merged]
+
+
+def in_ranges(addr: int, ranges: Sequence[Tuple[int, int]], starts: Sequence[int]) -> bool:
+    idx = bisect.bisect_right(starts, addr) - 1
+    if idx < 0:
+        return False
+    start, end = ranges[idx]
+    return start <= addr < end
+
+
+def parse_groundtruth(gt_path: Path, blocks_pb2_path: Path) -> Tuple[Set[int], List[Tuple[int, int]], List[Tuple[int, int]]]:
+    blocks_pb2 = load_blocks_pb2(blocks_pb2_path)
+    module = blocks_pb2.module()
+    module.ParseFromString(gt_path.read_bytes())
+
+    gt_inst_addrs: Set[int] = set()
+    covered_ranges: List[Tuple[int, int]] = []
+    padding_ranges: List[Tuple[int, int]] = []
+    for func in module.fuc:
+        for bb in func.bb:
+            for inst in bb.instructions:
+                gt_inst_addrs.add(int(inst.va))
+            va = int(bb.va)
+            size = int(bb.size)
+            padding = int(bb.padding)
+            covered_end = va + size - padding
+            if covered_end > va:
+                covered_ranges.append((va, covered_end))
+            if padding > 0:
+                pad_start = covered_end
+                pad_end = va + size
+                if pad_end > pad_start:
+                    padding_ranges.append((pad_start, pad_end))
+
+    return gt_inst_addrs, merge_ranges(covered_ranges), merge_ranges(padding_ranges)
+
+
+def parse_objdump_instructions(binary: Path) -> List[Tuple[int, int, str]]:
+    out = run_cmd(["objdump", "-d", "-j", ".text", str(binary)]).stdout
+    instructions: List[Tuple[int, int, str]] = []
+    for line in out.splitlines():
+        match = OBJDUMP_INST_RE.match(line)
+        if not match:
+            continue
+        addr = int(match.group(1), 16)
+        bytes_field = match.group(2).strip()
+        asm = match.group(3).strip()
+        if not asm:
+            continue
+        size = len(bytes_field.split())
+        instructions.append((addr, size, asm))
+    return instructions
+
+
+def merge_unseen_ranges(unseen: Sequence[Tuple[int, int, str]]) -> List[Tuple[int, int, int, List[str]]]:
+    if not unseen:
+        return []
+    ranges: List[Tuple[int, int, int, List[str]]] = []
+    start = unseen[0][0]
+    end = unseen[0][0] + unseen[0][1]
+    count = 1
+    sample = [unseen[0][2]]
+    for addr, size, asm in unseen[1:]:
+        if addr == end:
+            end = addr + size
+            count += 1
+            if len(sample) < 3:
+                sample.append(asm)
+            continue
+        ranges.append((start, end, count, sample))
+        start = addr
+        end = addr + size
+        count = 1
+        sample = [asm]
+    ranges.append((start, end, count, sample))
+    return ranges
+
+
+def analyze_groundtruth_gap(
+    binary: Path,
+    groundtruth: Path,
+    blocks_pb2_path: Path,
+) -> Dict[str, object]:
+    gt_inst_addrs, covered_ranges, padding_ranges = parse_groundtruth(
+        groundtruth, blocks_pb2_path
     )
-    parser.add_argument("--ground-truth-csv", required=True, type=Path)
-    parser.add_argument("--ll", required=True, type=Path)
-    parser.add_argument("--function-symbols-csv", required=True, type=Path)
-    parser.add_argument("--csv-image-base", required=True, type=lambda value: int(value, 0))
-    parser.add_argument("--rebase-base", required=True, type=lambda value: int(value, 0))
-    parser.add_argument("--summary-out", type=Path)
-    return parser.parse_args()
+    padding_starts = [start for start, _ in padding_ranges]
+
+    obj_insts = parse_objdump_instructions(binary)
+    unseen = [
+        (addr, size, asm) for addr, size, asm in obj_insts if addr not in gt_inst_addrs
+    ]
+    unseen_ranges = merge_unseen_ranges(unseen)
+
+    instruction_category_counts = collections.Counter()
+    range_category_counts = collections.Counter()
+    instruction_examples = {"padding": [], "outside_gt_coverage": []}
+    range_examples = {"padding": [], "outside_gt_coverage": []}
+
+    for addr, size, asm in unseen:
+        category = (
+            "padding"
+            if in_ranges(addr, padding_ranges, padding_starts)
+            else "outside_gt_coverage"
+        )
+        instruction_category_counts[category] += 1
+        if len(instruction_examples[category]) < 20:
+            instruction_examples[category].append(
+                {"addr": hex(addr), "size": size, "asm": asm}
+            )
+
+    unseen_range_items = []
+    for start, end, inst_count, sample_asm in unseen_ranges:
+        category = (
+            "padding"
+            if in_ranges(start, padding_ranges, padding_starts)
+            else "outside_gt_coverage"
+        )
+        range_category_counts[category] += 1
+        item = {
+            "start": hex(start),
+            "end": hex(end),
+            "inst_count": inst_count,
+            "category": category,
+            "sample_asm": sample_asm,
+        }
+        unseen_range_items.append(item)
+        if len(range_examples[category]) < 20:
+            range_examples[category].append(item)
+
+    unseen_ratio = len(unseen) / len(gt_inst_addrs) if gt_inst_addrs else 0.0
+    return {
+        "binary": str(binary),
+        "groundtruth": str(groundtruth),
+        "blocks_pb2": str(blocks_pb2_path),
+        "objdump_real_instruction_count": len(obj_insts),
+        "groundtruth_instruction_count": len(gt_inst_addrs),
+        "unseen_instruction_count": len(unseen),
+        "unseen_ratio_over_groundtruth": unseen_ratio,
+        "covered_range_count": len(covered_ranges),
+        "padding_range_count": len(padding_ranges),
+        "unseen_contiguous_range_count": len(unseen_ranges),
+        "instruction_category_counts": dict(instruction_category_counts),
+        "range_category_counts": dict(range_category_counts),
+        "instruction_examples": instruction_examples,
+        "range_examples": range_examples,
+        "unseen_ranges": unseen_range_items,
+    }
+
+
+def write_gap_outputs(out_dir: Path, summary: Dict[str, object]) -> Tuple[Path, Path]:
+    ensure_dir(out_dir)
+    json_path = out_dir / "gap.summary.json"
+    txt_path = out_dir / "gap.summary.txt"
+    write_json(json_path, summary)
+
+    lines = [
+        f"binary: {summary['binary']}",
+        f"groundtruth: {summary['groundtruth']}",
+        f"blocks_pb2: {summary['blocks_pb2']}",
+        f"objdump_real_instruction_count: {summary['objdump_real_instruction_count']}",
+        f"groundtruth_instruction_count: {summary['groundtruth_instruction_count']}",
+        f"unseen_instruction_count: {summary['unseen_instruction_count']}",
+        "unseen_ratio_over_groundtruth: "
+        f"{float(summary['unseen_ratio_over_groundtruth']):.12f}",
+        f"unseen_contiguous_range_count: {summary['unseen_contiguous_range_count']}",
+        "",
+        "[instruction_category_counts]",
+    ]
+    for key, value in summary["instruction_category_counts"].items():
+        lines.append(f"{key}: {value}")
+    lines.append("")
+    lines.append("[range_category_counts]")
+    for key, value in summary["range_category_counts"].items():
+        lines.append(f"{key}: {value}")
+    write_text(txt_path, lines)
+    return json_path, txt_path
 
 
-def main() -> int:
-    args = parse_args()
+def assess_cmp_payload(
+    payload: Dict[str, object],
+    *,
+    min_precision: float,
+    min_recall: float,
+) -> CmpVerdict:
+    reasons: List[str] = []
+    precision = float(payload.get("precision", 0.0))
+    recall = float(payload.get("recall", 0.0))
+
+    if precision < min_precision:
+        reasons.append(f"precision {precision:.6f} < {min_precision:.6f}")
+    if recall < min_recall:
+        reasons.append(f"recall {recall:.6f} < {min_recall:.6f}")
+    if precision < 0.20 and recall < 0.20:
+        reasons.append(
+            "metrics are catastrophically low; the .ll likely comes from a different binary build"
+        )
+    return CmpVerdict(ok=not reasons, reasons=reasons)
+
+
+def write_cmp_verdict(out_dir: Path, payload: Dict[str, object], verdict: CmpVerdict) -> Path:
+    verdict_path = out_dir / "cmp.verdict.txt"
+    lines = [
+        f"binary: {payload.get('binary', '')}",
+        f"ll: {payload.get('ll', '')}",
+        f"text_start: 0x{int(payload.get('text_start', 0)):x}",
+        f"runnable_base: 0x{int(payload.get('runnable_base', 0)):x}",
+        f"precision: {float(payload.get('precision', 0.0)):.6f}",
+        f"recall: {float(payload.get('recall', 0.0)):.6f}",
+        f"ok: {str(verdict.ok).lower()}",
+    ]
+    if verdict.reasons:
+        lines.append("")
+        lines.append("[reasons]")
+        lines.extend(verdict.reasons)
+    write_text(verdict_path, lines)
+    return verdict_path
+
+
+def run_cmp(
+    *,
+    binary: Path,
+    ll_path: Path,
+    out_dir: Path,
+    run_cmp_eval: Path,
+    text_start: int | None,
+    runnable_base: int,
+    min_precision: float,
+    min_recall: float,
+    examples: int,
+) -> Tuple[Dict[str, object], CmpVerdict, Path, Path, Path]:
+    ensure_file(binary, "binary")
+    ensure_file(ll_path, "ll")
+    ensure_file(run_cmp_eval, "run_cmp_eval.py")
+    ensure_dir(out_dir)
+
+    resolved_text_start = detect_text_start(binary) if text_start is None else text_start
+    json_out = out_dir / "cmp.json"
+    text_out = out_dir / "cmp.txt"
+    cmd = [
+        "python3",
+        str(run_cmp_eval),
+        "--binary",
+        str(binary),
+        "--ll",
+        str(ll_path),
+        "--text-start",
+        hex(resolved_text_start),
+        "--runnable-base",
+        hex(runnable_base),
+        "--examples",
+        str(examples),
+        "--json-out",
+        str(json_out),
+        "--text-out",
+        str(text_out),
+    ]
+    result = run_cmd(cmd, check=False)
+    if result.returncode != 0:
+        raise RuntimeError(
+            "run_cmp_eval.py failed:\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}"
+        )
+    payload = read_json(json_out)
+    verdict = assess_cmp_payload(
+        payload,
+        min_precision=min_precision,
+        min_recall=min_recall,
+    )
+    verdict_path = write_cmp_verdict(out_dir, payload, verdict)
+    return payload, verdict, json_out, text_out, verdict_path
+
+
+def print_gap_summary(summary: Dict[str, object], txt_path: Path) -> None:
+    print(f"gap_summary={txt_path}")
+    print(
+        "gap_counts="
+        f"unseen={summary['unseen_instruction_count']} "
+        f"outside_gt_coverage={summary['instruction_category_counts'].get('outside_gt_coverage', 0)} "
+        f"padding={summary['instruction_category_counts'].get('padding', 0)}"
+    )
+
+
+def print_cmp_summary(
+    payload: Dict[str, object],
+    verdict: CmpVerdict,
+    verdict_path: Path,
+) -> None:
+    print(f"cmp_verdict={verdict_path}")
+    print(
+        "cmp_metrics="
+        f"precision={float(payload.get('precision', 0.0)):.6f} "
+        f"recall={float(payload.get('recall', 0.0)):.6f} "
+        f"text_start=0x{int(payload.get('text_start', 0)):x} "
+        f"runnable_base=0x{int(payload.get('runnable_base', 0)):x}"
+    )
+    if verdict.reasons:
+        for reason in verdict.reasons:
+            print(f"cmp_reason={reason}", file=sys.stderr)
+
+
+def validate_csv_mode(args: argparse.Namespace) -> int:
     gt_instrs, data_ranges = load_ground_truth_csv(
         args.ground_truth_csv,
         csv_image_base=args.csv_image_base,
@@ -88,5 +489,162 @@ def main() -> int:
     return 0
 
 
+def add_shared_binary_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--binary", type=Path, default=DEFAULT_BINARY)
+    parser.add_argument("--groundtruth", type=Path, default=None)
+    parser.add_argument("--blocks-pb2", type=Path, default=DEFAULT_VENDOR_BLOCKS_PB2)
+    parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT_DIR)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Validate libcrypto ground truth using legacy CSV mode or canonical protobuf mode."
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    csv_parser = subparsers.add_parser(
+        "csv-validate",
+        help="Legacy CSV-based validation mode used by existing fn/fp root-cause tooling.",
+    )
+    csv_parser.add_argument("--ground-truth-csv", required=True, type=Path)
+    csv_parser.add_argument("--ll", required=True, type=Path)
+    csv_parser.add_argument("--function-symbols-csv", required=True, type=Path)
+    csv_parser.add_argument("--csv-image-base", required=True, type=parse_int)
+    csv_parser.add_argument("--rebase-base", required=True, type=parse_int)
+    csv_parser.add_argument("--summary-out", type=Path)
+
+    gap = subparsers.add_parser("gap-audit", help="Check binary .text addresses against gtBlock.pb")
+    add_shared_binary_args(gap)
+
+    cmp_parser = subparsers.add_parser("cmp", help="Run compare_runnable_text with safe defaults")
+    add_shared_binary_args(cmp_parser)
+    cmp_parser.add_argument("--ll", type=Path, required=True)
+    cmp_parser.add_argument("--run-cmp-eval", type=Path, default=DEFAULT_RUN_CMP_EVAL)
+    cmp_parser.add_argument("--text-start", default="elf")
+    cmp_parser.add_argument("--runnable-base", default=hex(DEFAULT_RUNNABLE_BASE))
+    cmp_parser.add_argument("--min-precision", type=float, default=DEFAULT_MIN_PRECISION)
+    cmp_parser.add_argument("--min-recall", type=float, default=DEFAULT_MIN_RECALL)
+    cmp_parser.add_argument("--examples", type=int, default=10)
+    cmp_parser.add_argument("--allow-low-metrics", action="store_true")
+
+    all_parser = subparsers.add_parser("all", help="Run gap audit and then compare a lift")
+    add_shared_binary_args(all_parser)
+    all_parser.add_argument("--ll", type=Path, required=True)
+    all_parser.add_argument("--run-cmp-eval", type=Path, default=DEFAULT_RUN_CMP_EVAL)
+    all_parser.add_argument("--text-start", default="elf")
+    all_parser.add_argument("--runnable-base", default=hex(DEFAULT_RUNNABLE_BASE))
+    all_parser.add_argument("--min-precision", type=float, default=DEFAULT_MIN_PRECISION)
+    all_parser.add_argument("--min-recall", type=float, default=DEFAULT_MIN_RECALL)
+    all_parser.add_argument("--examples", type=int, default=10)
+    all_parser.add_argument("--allow-low-metrics", action="store_true")
+
+    return parser
+
+
+def resolve_groundtruth(binary: Path, groundtruth: Optional[Path]) -> Path:
+    return groundtruth.resolve() if groundtruth else resolve_default_groundtruth_path(binary.resolve())
+
+
+def parse_text_start_arg(value: str) -> Optional[int]:
+    if value == "elf":
+        return None
+    return parse_int(value)
+
+
+def cmd_gap_audit(args: argparse.Namespace) -> int:
+    binary = args.binary.resolve()
+    groundtruth = resolve_groundtruth(binary, args.groundtruth)
+    blocks_pb2 = args.blocks_pb2.resolve()
+    ensure_file(binary, "binary")
+    ensure_file(groundtruth, "groundtruth")
+    ensure_file(blocks_pb2, "blocks_pb2")
+
+    summary = analyze_groundtruth_gap(binary, groundtruth, blocks_pb2)
+    _, txt_path = write_gap_outputs(args.out_dir.resolve(), summary)
+    print_gap_summary(summary, txt_path)
+    return 0
+
+
+def cmd_cmp(args: argparse.Namespace) -> int:
+    binary = args.binary.resolve()
+    groundtruth = resolve_groundtruth(binary, args.groundtruth)
+    ensure_file(groundtruth, "groundtruth")
+    payload, verdict, _, _, verdict_path = run_cmp(
+        binary=binary,
+        ll_path=args.ll.resolve(),
+        out_dir=args.out_dir.resolve(),
+        run_cmp_eval=args.run_cmp_eval.resolve(),
+        text_start=parse_text_start_arg(args.text_start),
+        runnable_base=parse_int(args.runnable_base),
+        min_precision=args.min_precision,
+        min_recall=args.min_recall,
+        examples=args.examples,
+    )
+    print_cmp_summary(payload, verdict, verdict_path)
+    if verdict.ok or args.allow_low_metrics:
+        return 0
+    return 3
+
+
+def cmd_all(args: argparse.Namespace) -> int:
+    gap_rc = cmd_gap_audit(args)
+    if gap_rc != 0:
+        return gap_rc
+    return cmd_cmp(args)
+
+
+def maybe_run_legacy_compat(args: Sequence[str]) -> Optional[int]:
+    legacy_flags = {
+        "--ground-truth-csv",
+        "--function-symbols-csv",
+        "--csv-image-base",
+        "--rebase-base",
+        "--summary-out",
+    }
+    if args and args[0] in {"csv-validate", "gap-audit", "cmp", "all"}:
+        return None
+    if any(flag in args for flag in legacy_flags):
+        parser = argparse.ArgumentParser(
+            description="Legacy CSV validation compatibility entrypoint."
+        )
+        parser.add_argument("--ground-truth-csv", required=True, type=Path)
+        parser.add_argument("--ll", required=True, type=Path)
+        parser.add_argument("--function-symbols-csv", required=True, type=Path)
+        parser.add_argument("--csv-image-base", required=True, type=parse_int)
+        parser.add_argument("--rebase-base", required=True, type=parse_int)
+        parser.add_argument("--summary-out", type=Path)
+        return validate_csv_mode(parser.parse_args(args))
+    return None
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args_list = list(sys.argv[1:] if argv is None else argv)
+    compat_rc = maybe_run_legacy_compat(args_list)
+    if compat_rc is not None:
+        return compat_rc
+
+    parser = build_parser()
+    args = parser.parse_args(args_list)
+    if args.command is None:
+        parser.print_help(sys.stderr)
+        return 2
+
+    try:
+        if args.command == "csv-validate":
+            return validate_csv_mode(args)
+        if args.command == "gap-audit":
+            return cmd_gap_audit(args)
+        if args.command == "cmp":
+            return cmd_cmp(args)
+        if args.command == "all":
+            return cmd_all(args)
+    except Exception as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
 if __name__ == "__main__":
     raise SystemExit(main())
diff --git a/test/test_libcrypto_bench_paths.py b/test/test_libcrypto_bench_paths.py
new file mode 100644
index 000000000..ad14c8dfc
--- /dev/null
+++ b/test/test_libcrypto_bench_paths.py
@@ -0,0 +1,54 @@
+import importlib.util
+import sys
+import unittest
+from pathlib import Path
+
+
+SCRIPT_PATH = REPO_ROOT = Path(__file__).resolve().parents[1] / "runnable" / "scripts" / "libcrypto_bench_paths.py"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("libcrypto_bench_paths", SCRIPT_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class LibcryptoBenchPathsTests(unittest.TestCase):
+    def test_parse_text_start_from_readelf_output(self):
+        module = load_module()
+        output = """
+  [11] .init             PROGBITS        00000000000ce5c0 0ce5c0 00001c 00  AX  0   0  4
+  [12] .plt              PROGBITS        00000000000ce5e0 0ce5e0 000990 10  AX  0   0 16
+  [13] .text             PROGBITS        00000000000cef80 0cef80 2e306e 00  AX  0   0 64
+"""
+
+        self.assertEqual(module.parse_text_start_from_readelf_output(output), 0xCEF80)
+
+    def test_default_paths_point_to_repo_local_groundtruth_assets(self):
+        module = load_module()
+        repo_root = SCRIPT_PATH.parents[2]
+
+        binary = module.default_ground_truth_binary(repo_root)
+        groundtruth = module.default_groundtruth_pb(repo_root)
+        blocks_pb2 = module.default_blocks_pb2(repo_root)
+
+        self.assertTrue(binary.exists(), binary)
+        self.assertTrue(groundtruth.exists(), groundtruth)
+        self.assertTrue(blocks_pb2.exists(), blocks_pb2)
+        self.assertIn("GroudTruth", str(binary))
+        self.assertIn("GroudTruth", str(groundtruth))
+
+    def test_build_parser_supports_canonical_kinds(self):
+        module = load_module()
+        parser = module.build_parser()
+
+        args = parser.parse_args(["cmp-tool"])
+
+        self.assertEqual(args.kind, "cmp-tool")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test/test_run_cmp_eval.py b/test/test_run_cmp_eval.py
new file mode 100644
index 000000000..deb2a23f3
--- /dev/null
+++ b/test/test_run_cmp_eval.py
@@ -0,0 +1,54 @@
+import importlib.util
+import sys
+import unittest
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "runnable" / "scripts" / "run_cmp_eval.py"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("run_cmp_eval", SCRIPT_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class RunCmpEvalTests(unittest.TestCase):
+    def test_build_payload_uses_compare_fields(self):
+        module = load_module()
+        payload = module.build_payload(
+            None,
+            Path("/tmp/libcrypto.so.3"),
+            Path("/tmp/libcrypto.ll"),
+            0xCEF80,
+            0x50000000,
+            10,
+            {
+                "obj_count": 10,
+                "ll_count": 11,
+                "hit": 9,
+                "mismatch": 1,
+                "obj_only": 0,
+                "ll_only": 1,
+                "false_negative": 1,
+                "false_positive": 2,
+                "precision": 9 / 11.0,
+                "recall": 0.9,
+                "mismatch_examples": [(0x50000000, "mov", "lea")],
+                "obj_only_examples": [(0x50000001, "ret")],
+                "ll_only_examples": [(0x50000002, "jmp")],
+            },
+        )
+
+        self.assertEqual(payload["text_start"], 0xCEF80)
+        self.assertEqual(payload["runnable_base"], 0x50000000)
+        self.assertEqual(payload["mismatch_examples"][0]["address"], "0x50000000")
+        self.assertEqual(payload["obj_only_examples"][0]["instruction"], "ret")
+        self.assertEqual(payload["ll_only_examples"][0]["instruction"], "jmp")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test/test_runnable_libcrypto_canonical_eval_skill.py b/test/test_runnable_libcrypto_canonical_eval_skill.py
new file mode 100644
index 000000000..a1b6ba52a
--- /dev/null
+++ b/test/test_runnable_libcrypto_canonical_eval_skill.py
@@ -0,0 +1,31 @@
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILL_PATH = (
+    REPO_ROOT / ".codex" / "skills" / "runnable-libcrypto-canonical-eval" / "SKILL.md"
+)
+DOC_PATH = REPO_ROOT / "docs" / "exp" / "2026-05-10-libcrypto-canonical-eval-contract.md"
+
+
+class RunnableLibcryptoCanonicalEvalSkillTest(unittest.TestCase):
+    def test_skill_exists_and_points_to_branch_native_paths(self) -> None:
+        self.assertTrue(SKILL_PATH.is_file(), f"missing skill: {SKILL_PATH}")
+        content = SKILL_PATH.read_text(encoding="utf-8")
+        self.assertIn("runnable/scripts/libcrypto_bench_paths.py", content)
+        self.assertIn("runnable/scripts/validate_libcrypto_ground_truth.py", content)
+        self.assertIn("blocks-pb2", content)
+        self.assertIn("cmp-tool", content)
+        self.assertIn("historical sidecar-union / non-canonical", content)
+
+    def test_experiment_doc_exists_and_explains_workspace_layout(self) -> None:
+        self.assertTrue(DOC_PATH.is_file(), f"missing doc: {DOC_PATH}")
+        content = DOC_PATH.read_text(encoding="utf-8")
+        self.assertIn("GroudTruth", content)
+        self.assertIn("runnable/scripts/validate_libcrypto_ground_truth.py", content)
+        self.assertIn("top-level `scripts/`, `tests/`, and `archives/...`", content)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test/test_validate_libcrypto_ground_truth_canonical.py b/test/test_validate_libcrypto_ground_truth_canonical.py
new file mode 100644
index 000000000..cb66b0b9a
--- /dev/null
+++ b/test/test_validate_libcrypto_ground_truth_canonical.py
@@ -0,0 +1,107 @@
+import importlib.util
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parents[1] / "runnable" / "scripts" / "validate_libcrypto_ground_truth.py"
+)
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location(
+        "validate_libcrypto_ground_truth", SCRIPT_PATH
+    )
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class ValidateLibcryptoGroundTruthCanonicalTests(unittest.TestCase):
+    def test_resolve_default_groundtruth_prefers_libcrypto_gtblock_name(self):
+        module = load_module()
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            binary = root / "libcrypto.so.3"
+            binary.write_bytes(b"\x7fELF")
+            expected = root / "libcrypto.gtBlock.pb"
+            expected.write_bytes(b"pb")
+
+            resolved = module.resolve_default_groundtruth_path(binary)
+
+            self.assertEqual(resolved, expected)
+
+    def test_assess_cmp_payload_fails_low_metrics(self):
+        module = load_module()
+        payload = {
+            "binary": "/tmp/libcrypto.so.3",
+            "ll": "/tmp/libcrypto.so.3.ll",
+            "text_start": 0xCEF80,
+            "runnable_base": 0x50000000,
+            "obj_count": 679479,
+            "ll_count": 847589,
+            "hit": 24175,
+            "mismatch": 112625,
+            "obj_only": 542679,
+            "ll_only": 710789,
+            "false_negative": 655304,
+            "false_positive": 823414,
+            "precision": 0.028522,
+            "recall": 0.035579,
+        }
+
+        verdict = module.assess_cmp_payload(
+            payload,
+            min_precision=0.80,
+            min_recall=0.80,
+        )
+
+        self.assertFalse(verdict.ok)
+        self.assertTrue(
+            any("precision" in reason for reason in verdict.reasons),
+            verdict.reasons,
+        )
+        self.assertTrue(
+            any("recall" in reason for reason in verdict.reasons),
+            verdict.reasons,
+        )
+
+    def test_assess_cmp_payload_accepts_strong_metrics(self):
+        module = load_module()
+        payload = {
+            "binary": "/tmp/libcrypto.so.3",
+            "ll": "/tmp/libcrypto.so.3.ll",
+            "text_start": 0xCF000,
+            "runnable_base": 0x50000000,
+            "obj_count": 932819,
+            "ll_count": 847589,
+            "hit": 787556,
+            "mismatch": 1420,
+            "obj_only": 143843,
+            "ll_only": 58613,
+            "false_negative": 145263,
+            "false_positive": 60033,
+            "precision": 0.929172,
+            "recall": 0.844275,
+        }
+
+        verdict = module.assess_cmp_payload(
+            payload,
+            min_precision=0.80,
+            min_recall=0.80,
+        )
+
+        self.assertTrue(verdict.ok)
+        self.assertEqual(verdict.reasons, [])
+
+    def test_legacy_mode_still_works_without_subcommand(self):
+        module = load_module()
+        self.assertIsNone(module.maybe_run_legacy_compat(["cmp"]))
+
+
+if __name__ == "__main__":
+    unittest.main()