# DeltaSig v2 Predicate Schema

> **Sprint**: SPRINT_20260119_004_BinaryIndex_deltasig_extensions  
> **Status**: Implemented

## Overview

DeltaSig v2 extends the function-level binary diff predicate with:

- **Symbol Provenance**: Links function matches to ground-truth corpus sources (debuginfod, ddeb, buildinfo, secdb)
- **IR Diff References**: CAS-stored intermediate representation diffs for detailed analysis
- **Explicit Verdicts**: Clear vulnerability status with confidence scores
- **Function Match States**: Per-function vulnerable/patched/modified/unchanged classification

## Schema

**Predicate Type URI**: `https://stella-ops.org/predicates/deltasig/v2`

### Key Fields

| Field | Type | Description |
|-------|------|-------------|
| `schemaVersion` | string | Always `"2.0.0"` |
| `subject` | object | Single subject (PURL, digest, arch) |
| `functionMatches` | array | Function-level matches with evidence |
| `verdict` | string | `vulnerable`, `patched`, `partial`, `unknown`, `partially_patched`, `inconclusive` |
| `confidence` | number | 0.0-1.0 confidence score |
| `summary` | object | Aggregate statistics |

### Function Match

```json
{
  "functionId": "sha256:abc123...",
  "name": "ssl_handshake",
  "address": 4194304,
  "size": 256,
  "matchScore": 0.95,
  "matchMethod": "semantic_ksg",
  "matchState": "patched",
  "symbolProvenance": {
    "sourceId": "fedora-debuginfod",
    "observationId": "obs:gt:12345",
    "confidence": 0.98,
    "resolvedAt": "2026-01-19T12:00:00Z"
  },
  "irDiff": {
    "casDigest": "sha256:def456...",
    "statementsAdded": 5,
    "statementsRemoved": 3,
    "changedInstructions": 8
  }
}
```

### Summary

```json
{
  "totalFunctions": 150,
  "vulnerableFunctions": 0,
  "patchedFunctions": 12,
  "unknownFunctions": 138,
  "functionsWithProvenance": 45,
  "functionsWithIrDiff": 12,
  "avgMatchScore": 0.85,
  "minMatchScore": 0.42,
  "maxMatchScore": 0.99,
  "totalIrDiffSize": 1234
}
```

## Version Negotiation

Clients can request specific predicate versions:

```json
{
  "preferredVersion": "2",
  "requiredFeatures": ["provenance", "ir-diff"]
}
```

Response:

```json
{
  "version": "2.0.0",
  "predicateType": "https://stella-ops.org/predicates/deltasig/v2",
  "features": ["provenance", "ir-diff"]
}
```

## VEX Integration

DeltaSig v2 predicates can be converted to VEX observations via `IDeltaSigVexBridge`:

| DeltaSig Verdict | VEX Status |
|------------------|------------|
| `patched` | `fixed` |
| `vulnerable` | `affected` |
| `partially_patched` | `under_investigation` |
| `inconclusive` | `under_investigation` |
| `unknown` | `not_affected` (conservative) |

### Evidence Blocks

VEX observations include evidence blocks:

1. **deltasig-summary**: Aggregate statistics
2. **deltasig-function-matches**: High-confidence matches with provenance
3. **deltasig-predicate-ref**: Reference to full predicate

## Implementation

### Core Services

| Interface | Implementation | Description |
|-----------|----------------|-------------|
| `IDeltaSigServiceV2` | `DeltaSigServiceV2` | V2 predicate generation |
| `ISymbolProvenanceResolver` | `GroundTruthProvenanceResolver` | Ground-truth lookup |
| `IIrDiffGenerator` | `IrDiffGenerator` | IR diff generation with CAS |
| `IDeltaSigVexBridge` | `DeltaSigVexBridge` | VEX observation generation |

### DI Registration

```csharp
services.AddDeltaSigV2();
```

Or with options:

```csharp
services.AddDeltaSigV2(
    configureProvenance: opts => opts.IncludeStale = false,
    configureIrDiff: opts => opts.MaxParallelism = 4
);
```

## Migration from v1

Use `DeltaSigPredicateConverter`:

```csharp
// v1 → v2
var v2 = DeltaSigPredicateConverter.ToV2(v1Predicate);

// v2 → v1
var v1 = DeltaSigPredicateConverter.ToV1(v2Predicate);
```

Notes:
- v1 → v2: Provenance and IR diff will be empty (add via resolver/generator)
- v2 → v1: Provenance and IR diff are discarded; verdict/confidence are lost

## JSON Schema

Full schema: [`docs/schemas/predicates/deltasig-v2.schema.json`](../../../schemas/predicates/deltasig-v2.schema.json)

## Related Documentation

- [Ground-Truth Corpus](./ground-truth-corpus.md)
- [Semantic Diffing](./semantic-diffing.md)
- [Architecture](./architecture.md)