# Remediation Module Architecture

> **Status: Planned.** The Remediation marketplace is a planned feature for developer-facing fix templates, PR generation, and contributor trust scoring. Source code at `src/Remediation/` contains initial scaffolding. This architecture document is a design specification pending full implementation.

## Overview

The Remediation module provides a developer-facing signed-PR remediation marketplace for the Stella Ops platform. It enables developers to discover, apply, and verify community-contributed or vendor-supplied fix templates for known vulnerabilities (CVEs).

## Key Concepts

### Fix Templates
Structured remediation patches tied to specific CVE + PURL combinations. Templates include unified diff content, version range applicability, and trust scores from contributor history.

### PR Submissions
Tracks the lifecycle of a remediation pull request from submission through scanning, merging, and post-merge verification. Each submission produces attestation evidence including reachability deltas and fix-chain DSSE envelopes.

### Contributors
Community members or vendors who submit fix templates. Each contributor has a trust score computed from their verification history (verified fixes, rejections).

### Marketplace Sources
Curated collections of fix templates from community, partner, or vendor origins. Sources are rated independently and can be enabled/disabled per tenant.

## Domain Model

```
FixTemplate (remediation.fix_templates)
├── CveId (text, indexed)
├── Purl (text, indexed — pkg:type/name)
├── VersionRange (semver range)
├── PatchContent (unified diff)
├── Status (pending/verified/rejected)
├── TrustScore (0.0–1.0)
├── DsseDigest (nullable — signed envelope hash)
└── ContributorId / SourceId (foreign keys)

PrSubmission (remediation.pr_submissions)
├── FixTemplateId (nullable FK)
├── PrUrl, RepositoryUrl, SourceBranch, TargetBranch
├── CveId (text, indexed)
├── Status (opened/scanning/merged/verified/failed/inconclusive)
├── PreScanDigest, PostScanDigest
├── ReachabilityDeltaDigest, FixChainDsseDigest
├── Verdict (fixed/partial/not_fixed/inconclusive)
└── ContributorId

Contributor (remediation.contributors)
├── Username (unique)
├── VerifiedFixes, TotalSubmissions, RejectedSubmissions
└── TrustScore (computed)

MarketplaceSource (remediation.marketplace_sources)
├── Key (unique)
├── SourceType (community/partner/vendor)
├── Enabled, TrustScore
└── LastSyncAt
```

## Trust Scoring

Contributor trust score formula:
```
score = clamp((verified * 1.0 - rejected * 0.5) / max(total, 1), 0, 1)
```

Trust tiers:
- **trusted** (> 0.8): Verified track record
- **established** (> 0.5): Growing history
- **new** (> 0.2): Recently joined
- **untrusted** (<= 0.2): Insufficient or negative history

## API Surface

All endpoints under `/api/v1/remediation/`.

### Templates
- `GET /templates` — List fix templates (filter by CVE, PURL)
- `GET /templates/{id}` — Get template detail
- `POST /templates` — Create template (requires `remediation.submit`)

### Submissions
- `GET /submissions` — List PR submissions
- `GET /submissions/{id}` — Get submission with attestation chain
- `POST /submissions` — Submit PR for verification
- `GET /submissions/{id}/status` — Pipeline status

### Matching
- `GET /match?cve=...&purl=...&version=...` — Find applicable fix templates

### Contributors
- `GET /contributors` — List contributors
- `GET /contributors/{username}` — Profile with trust score

### Sources
- `GET /sources` — List marketplace sources
- `GET /sources/{key}` — Source detail
- `POST /sources` — Create/update source (requires `remediation.manage`)

## Authorization Policies

| Policy | Description |
|--------|-------------|
| `remediation.read` | Read templates, submissions, contributors, sources |
| `remediation.submit` | Create templates and submit PRs |
| `remediation.manage` | Manage marketplace sources, verify/reject templates |

## Verification Pipeline

1. PR submitted (status: `opened`)
2. Pre-merge scan captures baseline SBOM digest
3. PR merged (status: `merged`)
4. Post-merge scan captures updated SBOM digest
5. Reachability delta computed between pre/post digests
6. Fix-chain DSSE envelope signed
7. Verdict determined: `fixed`, `partial`, `not_fixed`, or `inconclusive`

## Webhook Integration

The `RemediationPrWebhookHandler` in the Signals module detects remediation PRs by:
- Title convention: `fix(CVE-XXXX-NNNNN): description`
- Label: `stella-ops/remediation`

## Module Location

```
src/Remediation/
├── StellaOps.Remediation.Core/         — Domain models, interfaces, services
├── StellaOps.Remediation.WebService/   — API endpoints, Program.cs
├── StellaOps.Remediation.Persistence/  — SQL migrations, repositories
└── __Tests/StellaOps.Remediation.Tests/ — Unit tests
```

## Related Sprints

- SPRINT_20260220_010: Registry and persistence
- SPRINT_20260220_011: Signals webhook handler
- SPRINT_20260220_012: Verification pipeline
- SPRINT_20260220_013: Matching, sources, policy
- SPRINT_20260220_014: UI components
- SPRINT_20260220_015: Documentation

## Related Contracts

- `docs/contracts/remediation-pr-v1.md`