Implement Advisory Canonicalization and Backfill Migration

- Added AdvisoryCanonicalizer for canonicalizing advisory identifiers.
- Created EnsureAdvisoryCanonicalKeyBackfillMigration to populate advisory_key and links in advisory_raw documents.
- Introduced FileSurfaceManifestStore for managing surface manifests with file system backing.
- Developed ISurfaceManifestReader and ISurfaceManifestWriter interfaces for reading and writing manifests.
- Implemented SurfaceManifestPathBuilder for constructing paths and URIs for surface manifests.
- Added tests for FileSurfaceManifestStore to ensure correct functionality and deterministic behavior.
- Updated documentation for new features and migration steps.

src/Concelier/__Tests/StellaOps.Concelier.WebService.Tests/WebServiceEndpointsTests.cs

@@ -469,6 +469,55 @@ public sealed class WebServiceEndpointsTests : IAsyncLifetime
         Assert.Empty(firstIds.Intersect(secondIds));
     }
 
+    [Fact]
+    public async Task AdvisoryEvidenceEndpoint_ReturnsDocumentsForCanonicalKey()
+    {
+        await SeedAdvisoryRawDocumentsAsync(
+            CreateAdvisoryRawDocument("tenant-a", "vendor-x", "GHSA-2025-0001", "sha256:001", new BsonDocument("id", "GHSA-2025-0001:1")),
+            CreateAdvisoryRawDocument("tenant-a", "vendor-y", "GHSA-2025-0001", "sha256:002", new BsonDocument("id", "GHSA-2025-0001:2")),
+            CreateAdvisoryRawDocument("tenant-b", "vendor-x", "GHSA-2025-0001", "sha256:003", new BsonDocument("id", "GHSA-2025-0001:3")));
+
+        using var client = _factory.CreateClient();
+        var response = await client.GetAsync("/vuln/evidence/advisories/ghsa-2025-0001?tenant=tenant-a");
+
+        response.EnsureSuccessStatusCode();
+        var evidence = await response.Content.ReadFromJsonAsync<AdvisoryEvidenceResponse>();
+
+        Assert.NotNull(evidence);
+        Assert.Equal("GHSA-2025-0001", evidence!.AdvisoryKey);
+        Assert.Equal(2, evidence.Records.Count);
+        Assert.All(evidence.Records, record => Assert.Equal("tenant-a", record.Tenant));
+    }
+
+    [Fact]
+    public async Task AdvisoryEvidenceEndpoint_FiltersByVendor()
+    {
+        await SeedAdvisoryRawDocumentsAsync(
+            CreateAdvisoryRawDocument("tenant-a", "vendor-x", "GHSA-2025-0002", "sha256:101", new BsonDocument("id", "GHSA-2025-0002:1")),
+            CreateAdvisoryRawDocument("tenant-a", "vendor-y", "GHSA-2025-0002", "sha256:102", new BsonDocument("id", "GHSA-2025-0002:2")));
+
+        using var client = _factory.CreateClient();
+        var response = await client.GetAsync("/vuln/evidence/advisories/GHSA-2025-0002?tenant=tenant-a&vendor=vendor-y");
+
+        response.EnsureSuccessStatusCode();
+        var evidence = await response.Content.ReadFromJsonAsync<AdvisoryEvidenceResponse>();
+
+        Assert.NotNull(evidence);
+        var record = Assert.Single(evidence!.Records);
+        Assert.Equal("vendor-y", record.Document.Source.Vendor);
+    }
+
+    [Fact]
+    public async Task AdvisoryEvidenceEndpoint_ReturnsNotFoundWhenMissing()
+    {
+        await SeedAdvisoryRawDocumentsAsync();
+
+        using var client = _factory.CreateClient();
+        var response = await client.GetAsync("/vuln/evidence/advisories/CVE-2099-9999?tenant=tenant-a");
+
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+    }
+
     [Fact]
     public async Task AdvisoryIngestEndpoint_EmitsMetricsWithExpectedTags()
     {
@@ -1871,6 +1920,18 @@ public sealed class WebServiceEndpointsTests : IAsyncLifetime
                     { "notes", new BsonDocument() }
                 }
             },
+            { "advisory_key", upstreamId.ToUpperInvariant() },
+            {
+                "links",
+                new BsonArray
+                {
+                    new BsonDocument
+                    {
+                        { "scheme", "PRIMARY" },
+                        { "value", upstreamId.ToUpperInvariant() }
+                    }
+                }
+            },
             { "supersedes", supersedes is null ? BsonNull.Value : supersedes },
             { "ingested_at", now },
             { "created_at", now }