Refactor code structure for improved readability and maintainability; optimize performance in key functions.

bench/golden-corpus/README.md

@@ -1,12 +1,13 @@
-# Golden Test Corpus
+# Golden Test Corpus
 
-This directory contains the golden test corpus for StellaOps scoring validation.
+This directory contains the golden test corpus for StellaOps validation.
 Each test case is a complete, reproducible scenario with known-good inputs and expected outputs.
 
 ## Schema Version
 
 **Corpus Version**: `1.0.0`
-**Scoring Algorithm**: `v2.0` (See `docs/modules/scanner/scoring-algorithm.md`)
+**Run Manifest Schema**: `1.0.0`
+**Evidence Index Schema**: `1.0.0`
 **OpenVEX Schema**: `0.2.0`
 **SPDX Version**: `3.0.1`
 **CycloneDX Version**: `1.6`
@@ -14,94 +15,58 @@ Each test case is a complete, reproducible scenario with known-good inputs and e
 ## Directory Structure
 
 ```
-golden-corpus/
-├── README.md                    # This file
-├── corpus-manifest.json         # Index of all test cases with hashes
-├── corpus-version.json          # Versioning metadata
-│
-├── severity-levels/             # CVE severity coverage
-│   ├── critical/
-│   ├── high/
-│   ├── medium/
-│   └── low/
-│
-├── vex-scenarios/               # VEX override scenarios
-│   ├── not-affected/
-│   ├── affected/
-│   ├── fixed/
-│   └── under-investigation/
-│
-├── reachability/                # Reachability analysis scenarios
-│   ├── reachable/
-│   ├── unreachable/
-│   └── unknown/
-│
-└── composite/                   # Complex multi-factor scenarios
-    ├── reachable-with-vex/
-    └── unreachable-high-severity/
+bench/golden-corpus/
+├── README.md
+├── corpus-manifest.json
+├── corpus-version.json
+├── categories/
+│   ├── severity/
+│   ├── vex/
+│   ├── reachability/
+│   ├── unknowns/
+│   ├── scale/
+│   ├── distro/
+│   ├── interop/
+│   ├── negative/
+│   └── composite/
+└── shared/
+    ├── policies/
+    ├── feeds/
+    └── keys/
 ```
 
 ## Test Case Format
 
 Each test case directory contains:
 
-| File | Description |
+| Path | Description |
 |------|-------------|
-| `case.json` | Scenario metadata and description |
-| `sbom.spdx.json` | SPDX 3.0.1 SBOM |
-| `sbom.cdx.json` | CycloneDX 1.6 SBOM (optional) |
-| `manifest.json` | Scan manifest with digest bindings |
-| `vex.openvex.json` | OpenVEX document (if applicable) |
-| `callgraph.json` | Static call graph (if reachability applies) |
-| `proof-bundle.json` | Expected proof bundle structure |
-| `expected-score.json` | Expected scoring output |
+| `case-manifest.json` | Case metadata |
+| `run-manifest.json` | Run manifest for replay |
+| `input/sbom-cyclonedx.json` | CycloneDX SBOM input |
+| `input/sbom-spdx.json` | SPDX SBOM input |
+| `input/image.tar.gz` | Image tarball (fixture) |
+| `expected/verdict.json` | Expected verdict output |
+| `expected/evidence-index.json` | Expected evidence index |
+| `expected/unknowns.json` | Expected unknowns output |
+| `expected/delta-verdict.json` | Expected delta verdict |
 
-## Expected Score Format
-
-```json
-{
-  "schema_version": "stellaops.golden.expected/v1",
-  "score_hash": "sha256:...",
-  "stella_score": 7.5,
-  "base_cvss": 9.8,
-  "temporal_cvss": 8.5,
-  "environmental_cvss": 7.5,
-  "vex_impact": -1.0,
-  "reachability_impact": -1.3,
-  "kev_flag": false,
-  "exploit_maturity": "proof-of-concept",
-  "determinism_salt": "frozen-2025-01-15T00:00:00Z"
-}
-```
-
-## Running Golden Tests
+## Running Corpus Scripts
 
 ```bash
-# Run all golden tests
-dotnet test tests/integration/StellaOps.Integration.Determinism \
-  --filter "Category=GoldenCorpus"
-
-# Regenerate expected outputs (after algorithm changes)
-dotnet run --project bench/tools/corpus-regenerate -- \
-  --corpus-path bench/golden-corpus \
-  --algorithm-version v2.0
+python3 scripts/corpus/validate-corpus.py
+python3 scripts/corpus/generate-manifest.py
+python3 scripts/corpus/check-determinism.py
+python3 scripts/corpus/add-case.py --category severity --name SEV-009
 ```
 
-## Adding New Cases
-
-1. Create directory under appropriate category
-2. Add all required files (see Test Case Format)
-3. Run corpus validation: `dotnet run --project bench/tools/corpus-validate`
-4. Update `corpus-manifest.json` hash entries
-5. Commit with message: `corpus: add <case-id> for <scenario>`
-
 ## Versioning Policy
 
 - **Patch** (1.0.x): Add new cases, fix existing case data
 - **Minor** (1.x.0): Algorithm tuning that preserves relative ordering
-- **Major** (x.0.0): Algorithm changes that alter expected scores
+- **Major** (x.0.0): Algorithm changes that alter expected outputs
 
-When scoring algorithm changes:
+When algorithms change:
 1. Increment corpus version
-2. Regenerate all expected scores
-3. Document changes in CHANGELOG.md
+2. Regenerate case outputs
+3. Update `corpus-manifest.json`