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/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/ConcelierAdvisoryDocumentProviderTests.cs

@@ -27,7 +27,9 @@ public sealed class ConcelierAdvisoryDocumentProviderTests
                 ImmutableDictionary<string, string>.Empty),
             content: new RawContent("csaf", "2.0", JsonDocument.Parse("{\"document\": {\"notes\": []}, \"vulnerabilities\": []}").RootElement),
             identifiers: new RawIdentifiers(ImmutableArray<string>.Empty, "UP-1"),
-            linkset: new RawLinkset());
+            linkset: new RawLinkset(),
+            advisoryKey: "UP-1",
+            links: ImmutableArray.Create(new RawLink("PRIMARY", "UP-1")));
 
         var records = new[]
         {
@@ -69,6 +71,13 @@ public sealed class ConcelierAdvisoryDocumentProviderTests
         public Task<AdvisoryRawQueryResult> QueryAsync(AdvisoryRawQueryOptions options, CancellationToken cancellationToken)
             => Task.FromResult(new AdvisoryRawQueryResult(_records, NextCursor: null, HasMore: false));
 
+        public Task<IReadOnlyList<AdvisoryRawRecord>> FindByAdvisoryKeyAsync(
+            string tenant,
+            IReadOnlyCollection<string> searchValues,
+            IReadOnlyCollection<string> sourceVendors,
+            CancellationToken cancellationToken)
+            => Task.FromResult(_records);
+
         public Task<AdvisoryRawVerificationResult> VerifyAsync(AdvisoryRawVerificationRequest request, CancellationToken cancellationToken)
             => throw new NotImplementedException();
     }