UCAgent NutShell Cache Verification

这是 GitLink UCAgent 赛题的 NutShell Cache 验证提交包。作品包含两条证据链：

1. Python reference-vs-DUT 验证闭环，用于展示 stimulus、scoreboard、coverage、invariant 和 bug injection 能力。
2. 真实 NutShell Cache RTL harness，通过 Picker/Toffee/Verilator wrapper 运行 semantic scoreboard clean run。

重要边界：runner.py 是 Python harness；真实 RTL 入口是 rtl_scoreboard_runner.py 或 scripts/run_packaged_rtl_scoreboard.py。真实 RTL run 已完成 2500 generated / 2492 executed / 0 failures。该 D-cache RTL 配置对 io_flush[1] 触发设计断言，所以本提交不声明 RTL flush 覆盖；flush 语义由 Python harness 覆盖，并在 RTL 统计中作为 waiver。

Quick Start

Linux 解压后应可直接运行：

unzip ucagent-nutshell-cache-verification.zip
cd ucagent-nutshell-cache-verification
python -m pytest -q

Python harness:

python -m ucagent_cache_verifier.runner --seed 20260706 --transactions 2500
python -m ucagent_cache_verifier.runner --seed 20260706 --transactions 2500 --inject-bugs --artifact-dir artifacts_buggy

真实 RTL scoreboard：

python scripts/run_packaged_rtl_scoreboard.py

该脚本会自动设置 PYTHONPATH，使用 zip 中随包保存的 external/Example-NutShellCache/Cache/UT_Cache 运行时包装目录。若评委环境 ABI 与随包 wrapper 不兼容，请按 docs/rtl_evidence/reproduce_rtl.md 重新生成 UT_Cache 后再运行同一脚本。

Results

• Python clean run: PASS, 2500 transactions, threshold coverage 100.0%, failures 0
• Python bug-injected run: FAILURES_DETECTED, failures 809
• Unit tests: 7 passed, 1 skipped
• Real RTL transaction smoke: PASS, RTL_TRANSACTION_SMOKE_RC:0
• Real RTL scoreboard clean run: PASS, generated 2500, executed 2492, skipped flush/post-flush 8, failures 0
• RTL raw global functional coverage: 85.71%
• RTL supported-domain functional coverage after documented waiver: 100.0%
• Official RTL pytest smoke flow: PASS with tools/toffee_compat/sitecustomize.py, 1 passed
• Official UCAgent FastMCP loop: PASS, ReadTextFile / SetCurrentStageJournal / Complete / Exit

RTL Evidence

Evidence is under docs/rtl_evidence/:

• nutshell_commit.txt: Example-NutShellCache and Picker commits
• picker_command.txt: Picker generation command
• toffee_port_map.md: wrapper port map
• reproduce_rtl.md: bundled wrapper and regeneration notes
• rtl_compile.log: Verilator/CMake/Ninja compile log
• rtl_transaction_smoke.log: port-level transaction smoke log
• rtl_scoreboard.console.log: RTL scoreboard summary
• rtl_scoreboard.fst: RTL scoreboard FST waveform
• rtl_scoreboard_coverage.dat: RTL scoreboard Verilator coverage database
• rtl_pytest_official_fixed.log: fixed official pytest smoke flow log
• rtl_coverage_waiver.md: unsupported RTL flush/post-flush waiver

UCAgent Evidence

UCAgent evidence is under docs/ucagent_raw_sessions/:

• session_01_prompt.md
• session_01_output.md
• session_01_manual_fix.diff
• coverage_before_after.md
• official_ucagent_cli_run.md
• official_ucagent_codex_backend_run.md
• platform_export/manual_mcp_server.sanitized.log
• platform_export/ucagent_mcp_direct_codex.sanitized.log

The sanitized logs are the reviewer-facing UTF-8 evidence. Raw console logs are preserved in the same directory.

Key Files

• src/ucagent_cache_verifier/cache_model.py: Python reference model and bug-injected DUT
• src/ucagent_cache_verifier/generator.py: directed plus constrained-random stimulus
• src/ucagent_cache_verifier/scoreboard.py: sync/async scoreboard
• src/ucagent_cache_verifier/coverage.py: threshold-based functional coverage
• src/ucagent_cache_verifier/rtl_scoreboard_runner.py: real RTL semantic scoreboard runner
• scripts/run_packaged_rtl_scoreboard.py: packaged RTL scoreboard entry point
• docs/verification_report.md: verification report
• docs/rtl_integration.md: RTL integration notes