sprints work.

2026-01-20 00:45:38 +02:00
parent b34bde89fa
commit 4903395618
275 changed files with 52785 additions and 79 deletions
--- a/docs/modules/binary-index/deltasig-v2-schema.md
+++ b/docs/modules/binary-index/deltasig-v2-schema.md
@@ -0,0 +1,164 @@
+# 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)