up

docs/provenance/inline-dsse.md

@@ -173,9 +173,23 @@ db.events.createIndex(
   { "provenance.dsse.rekor.logIndex": 1 },
   { name: "events_by_rekor_logindex" }
 );
+
+db.events.createIndex(
+  { "provenance.dsse.envelopeDigest": 1 },
+  { name: "events_by_envelope_digest", sparse: true }
+);
+
+db.events.createIndex(
+  { "ts": -1, "kind": 1, "trust.verified": 1 },
+  { name: "events_by_ts_kind_verified" }
+);
 ```
 
-Corresponding C# helper: `MongoIndexes.EnsureEventIndexesAsync`.
+Deployment options:
+- **Ops script:** `mongosh stellaops_db < ops/mongo/indices/events_provenance_indices.js`
+- **C# helper:** `MongoIndexes.EnsureEventIndexesAsync(database, ct)`
+
+This section was updated as part of `PROV-INDEX-401-030` (completed 2025-11-27).
 
 ---
 
@@ -270,3 +284,82 @@ Body: { "dsse": { ... }, "trust": { ... } }
 ```
 
 The body matches the JSON emitted by `publish_attestation_with_provenance.sh`. Feedser validates the payload, ensures `trust.verified = true`, and then calls `AttachStatementProvenanceAsync` so the DSSE metadata lands inline on the target statement. Clients receive HTTP 202 on success, 400 on malformed input, and 404 if the statement id is unknown.
+
+---
+
+## 10. Backfill service
+
+`EventProvenanceBackfillService` (`src/StellaOps.Events.Mongo/EventProvenanceBackfillService.cs`) orchestrates backfilling historical events with DSSE provenance metadata.
+
+### 10.1 Components
+
+| Class | Purpose |
+|-------|---------|
+| `IAttestationResolver` | Interface for resolving attestation metadata by subject digest. |
+| `EventProvenanceBackfillService` | Queries unproven events, resolves attestations, updates events. |
+| `StubAttestationResolver` | Test/development stub implementation. |
+
+### 10.2 Usage
+
+```csharp
+var resolver = new MyAttestationResolver(rekorClient, attestationRepo);
+var backfillService = new EventProvenanceBackfillService(mongoDatabase, resolver);
+
+// Count unproven events
+var count = await backfillService.CountUnprovenEventsAsync(
+    new[] { "SBOM", "VEX", "SCAN" });
+
+// Backfill with progress reporting
+var progress = new Progress<BackfillResult>(r =>
+    Console.WriteLine($"{r.EventId}: {r.Status}"));
+
+var summary = await backfillService.BackfillAllAsync(
+    kinds: new[] { "SBOM", "VEX", "SCAN" },
+    limit: 1000,
+    progress: progress);
+
+Console.WriteLine($"Processed: {summary.TotalProcessed}");
+Console.WriteLine($"Success: {summary.SuccessCount}");
+Console.WriteLine($"Not found: {summary.NotFoundCount}");
+Console.WriteLine($"Errors: {summary.ErrorCount}");
+```
+
+### 10.3 Implementing IAttestationResolver
+
+Implementations should query the attestation store (Rekor, CAS, or local Mongo) by subject digest:
+
+```csharp
+public class RekorAttestationResolver : IAttestationResolver
+{
+    private readonly IRekorClient _rekor;
+    private readonly IAttestationRepository _attestations;
+
+    public async Task<AttestationResolution?> ResolveAsync(
+        string subjectDigestSha256,
+        string eventKind,
+        CancellationToken cancellationToken)
+    {
+        // Look up attestation by subject digest
+        var record = await _attestations.GetAsync(subjectDigestSha256, eventKind, cancellationToken);
+        if (record is null) return null;
+
+        // Fetch Rekor proof if available
+        var proof = await _rekor.GetProofAsync(record.RekorUuid, RekorBackend.Sigstore, cancellationToken);
+
+        return new AttestationResolution
+        {
+            Dsse = new DsseProvenance { /* ... */ },
+            Trust = new TrustInfo { Verified = true, Verifier = "Authority@stella" },
+            AttestationId = record.Id
+        };
+    }
+}
+```
+
+### 10.4 Reference files
+
+- `src/StellaOps.Events.Mongo/IAttestationResolver.cs`
+- `src/StellaOps.Events.Mongo/EventProvenanceBackfillService.cs`
+- `src/StellaOps.Events.Mongo/StubAttestationResolver.cs`
+
+This section was added as part of `PROV-BACKFILL-401-029` (completed 2025-11-27).