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.

docs/modules/concelier/architecture.md

@@ -61,23 +61,28 @@
     "spec_version": "1.6",
     "raw": { /* unmodified upstream document */ }
   },
-  "identifiers": {
-    "cve": ["CVE-2025-12345"],
-    "ghsa": ["GHSA-xxxx-...."],
-    "aliases": ["CVE-2025-12345", "GHSA-xxxx-...."]
-  },
-  "linkset": {
-    "purls": ["pkg:npm/lodash@4.17.21"],
-    "cpes": ["cpe:2.3:a:lodash:lodash:4.17.21:*:*:*:*:*:*:*"],
-    "references": [
-      {"type":"advisory","url":"https://..."},
-      {"type":"fix","url":"https://..."}
-    ],
-    "reconciled_from": ["content.raw.affected.ranges", "content.raw.pkg"]
-  },
-  "supersedes": "advisory_raw:osv:GHSA-xxxx-....:v2",
-  "tenant": "default"
-}
+  "identifiers": {
+    "primary": "GHSA-xxxx-....",
+    "aliases": ["CVE-2025-12345", "GHSA-xxxx-...."]
+  },
+  "linkset": {
+    "purls": ["pkg:npm/lodash@4.17.21"],
+    "cpes": ["cpe:2.3:a:lodash:lodash:4.17.21:*:*:*:*:*:*:*"],
+    "references": [
+      {"type":"advisory","url":"https://..."},
+      {"type":"fix","url":"https://..."}
+    ],
+    "reconciled_from": ["content.raw.affected.ranges", "content.raw.pkg"]
+  },
+  "advisory_key": "CVE-2025-12345",
+  "links": [
+    {"scheme":"CVE","value":"CVE-2025-12345"},
+    {"scheme":"GHSA","value":"GHSA-XXXX-...."},
+    {"scheme":"PRIMARY","value":"CVE-2025-12345"}
+  ],
+  "supersedes": "advisory_raw:osv:GHSA-xxxx-....:v2",
+  "tenant": "default"
+}
 ```
 
 ### 1.2 Connector lifecycle
@@ -110,7 +115,7 @@ Running the same export job twice against the same snapshot must yield byte-iden
 * **Linkset builder** that correlates observations into `advisory_linksets` and annotates conflicts.
 * **Event publisher** emitting `advisory.observation.updated` and `advisory.linkset.updated` messages.
 * **Exporters** (JSON, Trivy DB, Offline Kit slices) fed from observation/linkset stores.
-* **Minimal REST** for health/status/trigger/export and observation/linkset reads.
+* **Minimal REST** for health/status/trigger/export, raw observation reads, and evidence retrieval (`GET /vuln/evidence/advisories/{advisory_key}`).
 
 **Scale:** HA by running N replicas; **locks** prevent overlapping jobs per source/exporter.