doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

docs/modules/binary-index/semantic-diffing.md

@@ -1,7 +1,7 @@
 # Semantic Diffing Architecture
 
-> **Status:** PLANNED
-> **Version:** 1.0.0
+> **Status:** PHASE 1 IMPLEMENTED (B2R2 IR Lifting)
+> **Version:** 1.1.0
 > **Related Sprints:**
 > - `SPRINT_20260105_001_001_BINDEX_semdiff_ir_semantics.md`
 > - `SPRINT_20260105_001_002_BINDEX_semdiff_corpus.md`
@@ -722,5 +722,146 @@ Delta-sig predicates are stored in the Evidence Locker and can be included in po
 
 ---
 
+---
+
+## 17. B2R2 Troubleshooting Guide
+
+This section covers common issues and resolutions when using B2R2 for IR lifting.
+
+### 17.1 Lifting Failures
+
+**Symptom:** `B2R2LiftingException: Failed to lift function at address 0x...`
+
+**Common Causes:**
+1. **Unsupported instruction** - B2R2 may not recognize certain instructions
+2. **Invalid entry point** - Function address is not a valid entry point
+3. **Obfuscated code** - Heavy obfuscation defeats parsing
+
+**Resolution:**
+```csharp
+// Check if architecture is supported before lifting
+if (!liftingService.SupportsArchitecture(binary.Architecture))
+{
+    // Fall back to disassembly-only mode
+    return await _disassemblyService.DisassembleAsync(binary, ct);
+}
+
+// Use try-lift with fallback
+var result = await _liftingService.TryLiftWithFallbackAsync(
+    binary,
+    new LiftingOptions { FallbackToDisassembly = true },
+    ct);
+```
+
+### 17.2 Memory Issues
+
+**Symptom:** `OutOfMemoryException` during lifting of large binaries
+
+**Common Causes:**
+1. **Pool exhaustion** - Too many concurrent lifter instances
+2. **Large function** - Single function exceeds memory budget
+3. **Memory leak** - Lifter instances not properly disposed
+
+**Resolution:**
+```yaml
+# Adjust pool configuration in appsettings.yaml
+BinaryIndex:
+  B2R2Pool:
+    MaxInstancesPerIsa: 4          # Reduce if OOM
+    RecycleAfterOperations: 1000   # Force recycle more often
+    MaxFunctionSizeBytes: 1048576  # Skip very large functions
+```
+
+### 17.3 Performance Issues
+
+**Symptom:** Lifting takes longer than expected (>30s for small binaries)
+
+**Common Causes:**
+1. **Cold pool** - No warm lifter instances available
+2. **Complex CFG** - Function has extremely complex control flow
+3. **Cache misses** - IR cache not configured or full
+
+**Resolution:**
+```csharp
+// Ensure pool is warmed at startup
+await _lifterPool.WarmAsync(new[] { ISA.AMD64, ISA.ARM64 }, ct);
+
+// Check cache health
+var stats = await _cacheService.GetStatisticsAsync(ct);
+if (stats.HitRate < 0.5)
+{
+    _logger.LogWarning("Low cache hit rate: {HitRate:P}", stats.HitRate);
+}
+```
+
+### 17.4 Determinism Issues
+
+**Symptom:** Same binary produces different IR hashes on repeated lifts
+
+**Common Causes:**
+1. **Non-deterministic block ordering** - Blocks not sorted by address
+2. **Timestamp inclusion** - IR includes lift timestamp
+3. **B2R2 version mismatch** - Different versions produce different IR
+
+**Resolution:**
+- Ensure `InvariantCulture` is used for all string formatting
+- Sort basic blocks by entry address before hashing
+- Include B2R2 version in cache keys
+- Use `DeterministicHash` utility for consistent hashing
+
+### 17.5 Architecture Detection Issues
+
+**Symptom:** Wrong architecture selected for multi-arch binary (fat binary)
+
+**Common Causes:**
+1. **Universal binary** - macOS fat binaries contain multiple architectures
+2. **ELF with multiple ABIs** - Rare but possible
+
+**Resolution:**
+```csharp
+// Explicitly specify target architecture
+var liftOptions = new LiftingOptions
+{
+    TargetArchitecture = ISA.AMD64,  // Force x86-64
+    IgnoreOtherArchitectures = true
+};
+```
+
+### 17.6 LowUIR Mapping Issues
+
+**Symptom:** Specific B2R2 LowUIR statements not mapped correctly
+
+**Reference: LowUIR Statement Type Mapping**
+
+| B2R2 LowUIR | Stella IR Model | Notes |
+|-------------|-----------------|-------|
+| `LMark` | `IrLabel` | Block label markers |
+| `Put` | `IrAssignment` | Register write |
+| `Store` | `IrStore` | Memory write |
+| `InterJmp` | `IrJump` | Cross-function jump |
+| `IntraJmp` | `IrJump` | Intra-function jump |
+| `InterCJmp` | `IrConditionalJump` | Cross-function conditional |
+| `IntraCJmp` | `IrConditionalJump` | Intra-function conditional |
+| `SideEffect` | `IrCall`/`IrReturn` | Function calls, returns |
+| `Def`/`Use`/`Phi` | `IrPhi` | SSA form constructs |
+
+### 17.7 Diagnostic Commands
+
+```bash
+# Check B2R2 health
+stella ops binaryindex health --verbose
+
+# Run benchmark suite
+stella ops binaryindex bench --iterations 100 --binary sample.so
+
+# View cache statistics
+stella ops binaryindex cache --stats
+
+# Dump effective configuration
+stella ops binaryindex config
+```
+
+---
+
 *Document Version: 1.1.0*
-*Last Updated: 2026-01-16*
+*Last Updated: 2026-01-19*