NutShell Cache verification with UCAgent

An executable, deterministic cache-verification baseline designed for the UCAgent contest. It has a hand-written constrained-random generator, independent golden scoreboard, functional coverage collector, and mutation/fault-injection tests.

Run

python -m unittest discover -s tests -v
python scripts/run_regression.py

The second command writes artifacts/regression.json and artifacts/coverage.json. No proprietary RTL or simulator is bundled; the regression therefore uses the supplied behavioural DUT adapter. This is intentional and is documented in docs/verification_report.md rather than being represented as NutShell RTL sign-off.

Integrating real NutShell RTL

1. Copy the Cache RTL and file list to rtl/ (ignored by Git if needed).
2. Implement signal mapping in src/picker_adapter.py for the project-specific Picker-generated DUT.
3. Set cache geometry in src/config.py to the RTL parameters.
4. Run the same tests under toffee-test; retain the generated toffee_report.json and update the report’s evidence table.

The test layers deliberately do not depend on a particular bus name: request/response transactions are defined in src/protocol.py.