git.stella-ops.org/bench/proof-chain/README.md

# Proof Chain Benchmark Suite

This benchmark suite measures performance of proof chain operations as specified in the Proof and Evidence Chain Technical Reference advisory.

## Overview

The benchmarks focus on critical performance paths:

1. **Content-Addressed ID Generation** - SHA-256 hashing and ID formatting
2. **Proof Spine Assembly** - Merkle tree construction and deterministic bundling
3. **Verification Pipeline** - End-to-end verification flow
4. **Key Rotation Operations** - Trust anchor lookups and key validation

## Running Benchmarks

### Prerequisites

- .NET 10 SDK
- PostgreSQL 16+ (for database benchmarks)
- BenchmarkDotNet 0.14+

### Quick Start

```bash
# Run all benchmarks
cd bench/proof-chain
dotnet run -c Release

# Run specific benchmark class
dotnet run -c Release -- --filter *IdGeneration*

# Export results
dotnet run -c Release -- --exporters json markdown
```

## Benchmark Categories

### 1. ID Generation Benchmarks

```csharp
[MemoryDiagnoser]
public class IdGenerationBenchmarks
{
    [Benchmark(Baseline = true)]
    public string GenerateEvidenceId_Small() => GenerateEvidenceId(SmallPayload);

    [Benchmark]
    public string GenerateEvidenceId_Medium() => GenerateEvidenceId(MediumPayload);

    [Benchmark]
    public string GenerateEvidenceId_Large() => GenerateEvidenceId(LargePayload);

    [Benchmark]
    public string GenerateProofBundleId() => GenerateProofBundleId(TestBundle);
}
```

**Target Metrics:**
- Evidence ID generation: < 50μs for 10KB payload
- Proof Bundle ID generation: < 500μs for typical bundle
- Memory allocation: < 1KB per ID generation

### 2. Proof Spine Assembly Benchmarks

```csharp
[MemoryDiagnoser]
public class ProofSpineAssemblyBenchmarks
{
    [Params(1, 5, 10, 50)]
    public int EvidenceCount { get; set; }

    [Benchmark]
    public ProofBundle AssembleSpine() => Assembler.AssembleSpine(
        Evidence.Take(EvidenceCount),
        Reasoning,
        VexVerdict);

    [Benchmark]
    public byte[] MerkleTreeConstruction() => BuildMerkleTree(Leaves);
}
```

**Target Metrics:**
- Spine assembly (5 evidence items): < 5ms
- Merkle tree (100 leaves): < 1ms
- Deterministic output: 100% reproducibility

### 3. Verification Pipeline Benchmarks

```csharp
[MemoryDiagnoser]
public class VerificationPipelineBenchmarks
{
    [Benchmark]
    public VerificationResult VerifySpineSignatures() => Pipeline.VerifyDsse(Bundle);

    [Benchmark]
    public VerificationResult VerifyIdRecomputation() => Pipeline.VerifyIds(Bundle);

    [Benchmark]
    public VerificationResult VerifyRekorInclusion() => Pipeline.VerifyRekor(Bundle);

    [Benchmark]
    public VerificationResult FullVerification() => Pipeline.VerifyAsync(Bundle).Result;
}
```

**Target Metrics:**
- DSSE signature verification: < 5ms per envelope
- ID recomputation: < 2ms per bundle
- Rekor verification (cached): < 10ms
- Full pipeline: < 50ms typical

### 4. Key Rotation Benchmarks

```csharp
[MemoryDiagnoser]
public class KeyRotationBenchmarks
{
    [Benchmark]
    public TrustAnchor FindAnchorByPurl() => Manager.FindAnchorForPurlAsync(Purl).Result;

    [Benchmark]
    public KeyValidity CheckKeyValidity() => Service.CheckKeyValidityAsync(AnchorId, KeyId, SignedAt).Result;

    [Benchmark]
    public IReadOnlyList<Warning> GetRotationWarnings() => Service.GetRotationWarningsAsync(AnchorId).Result;
}
```

**Target Metrics:**
- PURL pattern matching: < 100μs per lookup
- Key validity check: < 500μs (cached)
- Rotation warnings: < 2ms (10 active keys)

## Baseline Results

### Development Machine Baseline

| Benchmark | Mean | StdDev | Allocated |
|-----------|------|--------|-----------|
| GenerateEvidenceId_Small | 15.2 μs | 0.3 μs | 384 B |
| GenerateEvidenceId_Medium | 28.7 μs | 0.5 μs | 512 B |
| GenerateEvidenceId_Large | 156.3 μs | 2.1 μs | 1,024 B |
| AssembleSpine (5 items) | 2.3 ms | 0.1 ms | 48 KB |
| MerkleTree (100 leaves) | 0.4 ms | 0.02 ms | 8 KB |
| VerifyDsse | 3.8 ms | 0.2 ms | 12 KB |
| VerifyIdRecomputation | 1.2 ms | 0.05 ms | 4 KB |
| FullVerification | 32.5 ms | 1.5 ms | 96 KB |
| FindAnchorByPurl | 45 μs | 2 μs | 512 B |
| CheckKeyValidity | 320 μs | 15 μs | 1 KB |

*Baseline measured on: Intel i7-12700, 32GB RAM, NVMe SSD, .NET 10.0-preview.7*

## Regression Detection

Benchmarks are run as part of CI with regression detection:

```yaml
# .gitea/workflows/benchmark.yaml
name: Benchmark
on:
  pull_request:
    paths:
      - 'src/Attestor/**'
      - 'src/Signer/**'

jobs:
  benchmark:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Run benchmarks
        run: |
          cd bench/proof-chain
          dotnet run -c Release -- --exporters json
      - name: Compare with baseline
        run: |
          python3 tools/compare-benchmarks.py \
            --baseline baselines/proof-chain.json \
            --current BenchmarkDotNet.Artifacts/results/*.json \
            --threshold 10
```

Regressions > 10% will fail the PR check.

## Adding New Benchmarks

1. Create benchmark class in `bench/proof-chain/Benchmarks/`
2. Follow naming convention: `{Feature}Benchmarks.cs`
3. Add `[MemoryDiagnoser]` attribute for allocation tracking
4. Include baseline expectations in XML comments
5. Update baseline after significant changes:
   ```bash
   dotnet run -c Release -- --exporters json
   cp BenchmarkDotNet.Artifacts/results/*.json baselines/
   ```

## Performance Guidelines

From advisory §14.1:

| Operation | P50 Target | P99 Target |
|-----------|------------|------------|
| Proof Bundle creation | 50ms | 200ms |
| Proof Bundle verification | 100ms | 500ms |
| SBOM verification (complete) | 500ms | 2s |
| Key validity check | 1ms | 5ms |

## Related Documentation

- [Proof and Evidence Chain Technical Reference](../../docs/product-advisories/14-Dec-2025%20-%20Proof%20and%20Evidence%20Chain%20Technical%20Reference.md)
- [Attestor Architecture](../../docs/modules/attestor/architecture.md)
- [Performance Workbook](../../docs/12_PERFORMANCE_WORKBOOK.md)