git.stella-ops.org/docs/implplan/HANDOFF_VERDICT_ATTESTATIONS.md

# Verdict Attestation Implementation Handoff

**Date**: 2025-12-23
**Status**: Phase 1 Complete, Phase 2 Requires Fixes
**Next Owner**: [To Be Assigned]

## Executive Summary

This document provides a handoff for the Signed Delta-Verdicts feature implementation (SPRINT_3000_0100_0001). Significant progress has been made with **~60% completion**, but build errors in unrelated components are blocking final integration.

**What's Working**:
- ✅ Evidence Locker storage layer with PostgreSQL + API endpoints
- ✅ Verdict predicate models and JSON schema
- ✅ DI registration and infrastructure wiring

**What's Blocked**:
- ❌ Policy Engine attestation service (references undefined types)
- ❌ Attestor signing handler (dependent project build errors)
- ❌ End-to-end integration tests

## Completed Work (60%)

### 1. Evidence Locker - Verdict Storage & API ✅ 100% Complete

**Files Created**:
```
src/EvidenceLocker/StellaOps.EvidenceLocker/
├── Migrations/001_CreateVerdictAttestations.sql
├── Storage/IVerdictRepository.cs
├── Storage/PostgresVerdictRepository.cs
├── Api/VerdictContracts.cs
├── Api/VerdictEndpoints.cs
└── StellaOps.EvidenceLocker.csproj (updated)
```

**Status**: ✅ **PRODUCTION READY**
- PostgreSQL migration creates `evidence_locker.verdict_attestations` table
- Repository implements full CRUD with Dapper + Npgsql
- 3 API endpoints:
  - `GET /api/v1/verdicts/{verdictId}` - Retrieve verdict
  - `GET /api/v1/runs/{runId}/verdicts` - List verdicts for run
  - `POST /api/v1/verdicts/{verdictId}/verify` - Verify signature (stub)
- DI registered in `EvidenceLockerInfrastructureServiceCollectionExtensions`
- Endpoints wired in `WebService/Program.cs`

**Test Status**: Manual testing pending (blocked by upstream components)

### 2. Policy Engine - Verdict Predicate Models ✅ 70% Complete

**Files Created**:
```
src/Policy/StellaOps.Policy.Engine/Attestation/
├── VerdictPredicate.cs (7 record types)
├── IVerdictAttestationService.cs
├── HttpAttestorClient.cs
└── VerdictPredicateBuilder.cs (BLOCKED - see below)
    VerdictAttestationService.cs (BLOCKED - see below)
```

**Status**: ⚠️ **NEEDS FIXES**

**What Works**:
- `VerdictPredicate.cs` - Complete predicate model matching JSON schema
- Record types: VerdictInfo, VerdictRuleExecution, VerdictEvidence, VerdictVexImpact, VerdictReachability
- Canonical JSON serialization with lexicographic ordering
- Determinism hash computation

**What's Broken**:
- `VerdictPredicateBuilder.cs` - References `PolicyExplainTrace` (undefined type)
- `VerdictAttestationService.cs` - References `PolicyExplainTrace` (undefined type)
- Missing project reference to `StellaOps.Canonical.Json`

### 3. Attestor - Verdict Signing Handler ❌ 0% Complete

**Status**: ⚠️ **NOT STARTED - BLOCKED**

**Blocking Issues**:
1. Pre-existing build errors in `StellaOps.Replay.Core` (fixed: added YamlDotNet)
2. Pre-existing build errors in `StellaOps.Attestor.ProofChain` (unfixed)
3. Pre-existing build errors in `StellaOps.EvidenceLocker.Infrastructure` (EvidencePortableBundleService static field access)

**Planned Implementation** (when unblocked):
```csharp
// src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/Handlers/VerdictAttestationHandler.cs
public class VerdictAttestationHandler
{
    public async Task<VerdictAttestationResponse> HandleAsync(
        VerdictAttestationRequest request,
        CancellationToken cancellationToken)
    {
        // 1. Validate predicate schema
        // 2. Create DSSE envelope with IAttestationSigningService
        // 3. Store in Evidence Locker via IVerdictRepository
        // 4. Optional: Submit to Rekor
        // 5. Return verdict ID + attestation URI
    }
}
```

## Critical Fixes Required

### Fix 1: Define PolicyExplainTrace Model (Policy Engine)

**Problem**: `VerdictPredicateBuilder.Build()` references undefined type `PolicyExplainTrace`

**Solution Option A** - Create New Model:
```csharp
// src/Policy/StellaOps.Policy.Engine/Materialization/PolicyExplainTrace.cs
namespace StellaOps.Policy.Engine.Materialization;

public sealed record PolicyExplainTrace
{
    public required string TenantId { get; init; }
    public required string PolicyId { get; init; }
    public required int PolicyVersion { get; init; }
    public required string RunId { get; init; }
    public required string FindingId { get; init; }
    public required DateTimeOffset EvaluatedAt { get; init; }

    // Verdict data
    public required string VerdictStatus { get; init; } // passed, warned, blocked, quieted, ignored
    public required string VerdictSeverity { get; init; }
    public required double VerdictScore { get; init; }
    public string? VerdictRationale { get; init; }

    // Rule chain execution
    public required ImmutableArray<RuleExecution> RuleChain { get; init; }

    // Evidence
    public required ImmutableArray<EvidenceReference> Evidence { get; init; }

    // VEX impacts
    public ImmutableArray<VexImpact> VexImpacts { get; init; } = ImmutableArray<VexImpact>.Empty;

    // Reachability
    public ReachabilityAnalysis? Reachability { get; init; }

    // Metadata
    public ImmutableDictionary<string, string> Metadata { get; init; } = ImmutableDictionary<string, string>.Empty;
}

public sealed record RuleExecution
{
    public required string RuleName { get; init; }
    public required string Outcome { get; init; }
    public required int ExecutionOrder { get; init; }
    public string? Condition { get; init; }
}

public sealed record EvidenceReference
{
    public required string Type { get; init; } // advisory, vex, sbom, reachability
    public required string Identifier { get; init; }
    public required string Digest { get; init; } // sha256 of content
}

public sealed record VexImpact
{
    public required string ProductId { get; init; }
    public required string VulnerabilityId { get; init; }
    public required string Status { get; init; }
    public required string Justification { get; init; }
}

public sealed record ReachabilityAnalysis
{
    public required bool IsReachable { get; init; }
    public ImmutableArray<string> CallChain { get; init; } = ImmutableArray<string>.Empty;
}
```

**Solution Option B** - Use Existing Model:
- Find existing policy evaluation result model (e.g., `EffectiveFinding`)
- Extend it with trace information
- Update `VerdictPredicateBuilder.Build()` parameter type

**Recommendation**: Option A (new model) - cleaner separation, avoids coupling to materialization layer

### Fix 2: Add Missing Project References (Policy Engine)

**File**: `src/Policy/StellaOps.Policy.Engine/StellaOps.Policy.Engine.csproj`

**Add**:
```xml
<ItemGroup>
  <ProjectReference Include="../../__Libraries/StellaOps.Canonical.Json/StellaOps.Canonical.Json.csproj" />
</ItemGroup>
```

### Fix 3: Fix Attestor.ProofChain Build Errors (Attestor)

**Problem**: `StellaOps.Attestor.ProofChain` references missing types from `StellaOps.Attestor.Envelope`

**Investigation Required**:
1. Verify project reference path in `StellaOps.Attestor.ProofChain.csproj`
2. Check if `EnvelopeKey`, `EnvelopeSignatureService` exist in Envelope project
3. May be pre-existing broken code - check git blame

**Workaround** (if not fixable):
- Implement `VerdictAttestationHandler` directly in `StellaOps.Attestor.WebService`
- Use `IAttestationSigningService` directly without ProofChain dependency

### Fix 4: Fix EvidencePortableBundleService Static Access (Evidence Locker)

**Problem**: `EvidencePortableBundleService.cs` tries to access instance field `_options` from static context

**File**: `src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.Infrastructure/Services/EvidencePortableBundleService.cs`

**Lines**: 143, 148, 153, 154, 248, 249, 250

**Investigation Required**: Check if methods are incorrectly marked as static

## Remaining Work (40%)

### Task 1: Complete Policy Engine Integration (4-6 hours)

**Files to Create/Modify**:
1. Define `PolicyExplainTrace` model (1 hour)
2. Fix `VerdictPredicateBuilder.cs` compilation (30 min)
3. Fix `VerdictAttestationService.cs` compilation (30 min)
4. Add Canonical.Json project reference (5 min)
5. Wire up service in DI container (15 min)
6. Call attestation service from policy evaluator (1 hour)
7. Unit tests for VerdictPredicateBuilder (2 hours)

**Acceptance Criteria**:
- [ ] VerdictPredicateBuilder builds and passes tests
- [ ] VerdictAttestationService builds and passes tests
- [ ] Policy evaluation calls attestation service
- [ ] Determinism hash is stable across runs

### Task 2: Implement Attestor Handler (2-4 hours)

**Files to Create**:
1. `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/Handlers/VerdictAttestationHandler.cs`
2. API endpoint in `Program.cs`: `POST /internal/api/v1/attestations/verdict`
3. DI registration

**Acceptance Criteria**:
- [ ] Handler accepts predicate JSON + subject descriptor
- [ ] Creates DSSE envelope via `IAttestationSigningService`
- [ ] Stores in Evidence Locker via `IVerdictRepository`
- [ ] Optional: submits to Rekor
- [ ] Returns verdict ID + attestation URI

### Task 3: Integration Tests (2-3 hours)

**Files to Create**:
1. `src/Policy/__Tests/StellaOps.Policy.Engine.Tests/Attestation/VerdictPredicateBuilderTests.cs`
2. `src/Policy/__Tests/StellaOps.Policy.Engine.Tests/Attestation/VerdictAttestationServiceTests.cs`
3. `src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.Tests/VerdictRepositoryTests.cs`

**Test Coverage**:
- [ ] Schema validation (predicate matches JSON schema)
- [ ] Determinism hash stability
- [ ] Rule chain mapping accuracy
- [ ] Evidence digest computation
- [ ] End-to-end: Policy run → Attestation → Storage → Retrieval
- [ ] Replay test: Same inputs → Same determinism hash

### Task 4: CLI Commands (3-4 hours)

**Files to Create**:
```
src/Cli/StellaOps.Cli/Commands/Verdict/
├── VerdictGetCommand.cs
├── VerdictVerifyCommand.cs
├── VerdictListCommand.cs
└── VerdictDownloadCommand.cs
```

**Commands**:
- `stella verdict get <verdict-id>` - Retrieve verdict attestation
- `stella verdict verify <verdict-id>` - Verify DSSE signature
- `stella verdict list --run <run-id>` - List verdicts for run
- `stella verdict download <verdict-id> --output <path>` - Download DSSE bundle

## Estimated Effort to Complete

| Task | Effort | Priority | Risk |
|------|--------|----------|------|
| Fix PolicyExplainTrace + refs | 2 hours | P0 | Low |
| Fix Attestor.ProofChain errors | 1-4 hours | P0 | High (may be unfixable) |
| Complete Policy Engine | 4-6 hours | P0 | Low |
| Implement Attestor Handler | 2-4 hours | P0 | Medium |
| Integration Tests | 2-3 hours | P1 | Low |
| CLI Commands | 3-4 hours | P2 | Low |
| **Total** | **14-23 hours** | | |

## Build Verification Steps

### Step 1: Fix and Build Policy Engine
```bash
cd "C:\dev\New folder\git.stella-ops.org"

# Add PolicyExplainTrace model (see Fix 1)
# Add Canonical.Json reference (see Fix 2)

dotnet build src/Policy/StellaOps.Policy.Engine/StellaOps.Policy.Engine.csproj
# Expected: SUCCESS
```

### Step 2: Fix and Build Attestor
```bash
# Fix ProofChain errors (see Fix 3)

dotnet build src/Attestor/StellaOps.Attestor/StellaOps.Attestor.sln
# Expected: SUCCESS
```

### Step 3: Build Evidence Locker
```bash
# Fix EvidencePortableBundleService (see Fix 4)

dotnet build src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.sln
# Expected: SUCCESS
```

### Step 4: Run Database Migration
```bash
# Ensure PostgreSQL is running
psql -U stellaops -d stellaops_dev

\i src/EvidenceLocker/StellaOps.EvidenceLocker/Migrations/001_CreateVerdictAttestations.sql
# Expected: Table created with indexes
```

### Step 5: Manual API Test
```bash
# Start Evidence Locker WebService
dotnet run --project src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.WebService

# Test endpoint
curl http://localhost:5000/api/v1/verdicts/test-verdict-id
# Expected: 404 Not Found (table is empty)
```

## Known Issues & Workarounds

### Issue 1: PolicyExplainTrace Undefined
**Workaround**: Create stub model (see Fix 1) or use EffectiveFinding

### Issue 2: Attestor.ProofChain Build Failures
**Workaround**: Implement handler without ProofChain dependency

### Issue 3: No Existing Policy Trace Model
**Root Cause**: Policy Engine doesn't currently expose execution trace
**Long-term Fix**: Enhance policy evaluator to return detailed trace data

### Issue 4: Missing End-to-End Integration Point
**Root Cause**: Policy Engine evaluator needs hook to call attestation service
**Location**: Likely in `src/Policy/StellaOps.Policy.Engine/Evaluation/` or similar
**Investigation Required**: Find where policy verdicts are finalized

## Success Criteria (Definition of Done)

- [ ] All projects build successfully without errors
- [ ] Database migration runs cleanly
- [ ] Policy evaluation generates verdict attestations
- [ ] Verdicts stored in Evidence Locker with DSSE envelopes
- [ ] API endpoints return correct responses
- [ ] Determinism hash enables bit-for-bit replay
- [ ] Unit test coverage ≥80% for new code
- [ ] Integration tests validate end-to-end flow
- [ ] CLI commands work for basic operations
- [ ] Documentation updated (API docs, user guides)

## Rollout Strategy

### Phase 1: Infrastructure (Current)
- ✅ Database schema
- ✅ Storage layer
- ✅ API endpoints

### Phase 2: Integration (Blocked)
- ❌ Policy Engine attestation service
- ❌ Attestor signing handler
- ❌ End-to-end wiring

### Phase 3: Testing & Polish
- ⏸️ Unit tests
- ⏸️ Integration tests
- ⏸️ Performance testing

### Phase 4: User-Facing Features
- ⏸️ CLI commands
- ⏸️ UI integration (future sprint)
- ⏸️ Documentation

## References

- **Implementation Status**: `docs/implplan/IMPLEMENTATION_STATUS_VERDICT_ATTESTATIONS.md`
- **JSON Schema**: `docs/schemas/stellaops-policy-verdict.v1.schema.json`
- **Sprint Plan**: `docs/implplan/SPRINT_3000_0100_0001_signed_verdicts.md`
- **API Documentation**: `docs/policy/verdict-attestations.md`
- **Product Advisory**: `docs/product-advisories/23-Dec-2026 - Competitor Scanner UI Breakdown.md`

## Contact & Escalation

**Current Owner**: Claude Code Session (2025-12-23)
**Next Owner**: [To Be Assigned]

**For Questions**:
1. Check `IMPLEMENTATION_STATUS_VERDICT_ATTESTATIONS.md` for detailed file inventory
2. Check `verdict-attestations.md` for API/schema documentation
3. Check git commits for implementation context: `git log --all --grep="verdict" --since="2025-12-20"`

**Escalation Path**:
- Build Issues → Infrastructure Team
- Schema/Design Questions → Product Architecture Team
- Integration Blockers → Policy Engine Team

---

**Next Action**: Assign owner, prioritize Fix 1-4, schedule 2-3 day sprint to complete remaining 40%