work

docs/modules/concelier/api/evidence-batch.md

@@ -0,0 +1,73 @@
+# Concelier Evidence Batch API (draft v1)  
+  
+Path: `POST /v1/evidence/batch`  
+Auth: same as other advisory read endpoints; requires tenant header `X-Stella-Tenant`.  
+Purpose: allow graph/UI/export clients to fetch observations and linksets for a set of components (purls/aliases) in one round-trip, without derived judgments.  
+  
+## Request  
+```json
+{
+  "items": [
+    {
+      "componentId": "component-a",
+      "purls": ["pkg:maven/org.example/app@1.0.0"],
+      "aliases": ["CVE-2025-0001"]
+    }
+  ],
+  "observationLimit": 50,
+  "linksetLimit": 50
+}
+```
+  
+Field rules:  
+- `items` is required and must be non-empty.  
+- Each item must supply at least one identifier (`purls` or `aliases`).  
+- `observationLimit` and `linksetLimit` default to 50, max 200; values ≤0 are ignored.  
+  
+## Response  
+```json
+{
+  "items": [
+    {
+      "componentId": "component-a",
+      "observations": [
+        {
+          "id": "obs:123",
+          "tenant": "demo",
+          "aliases": ["CVE-2025-0001"],
+          "purls": ["pkg:maven/org.example/app@1.0.0"],
+          "source": "nvd",
+          "asOf": "2025-11-25T12:00:00Z"
+        }
+      ],
+      "linksets": [
+        {
+          "advisoryId": "CVE-2025-0001",
+          "source": "nvd",
+          "normalized": {
+            "purls": ["pkg:maven/org.example/app@1.0.0"]
+          },
+          "createdAt": "2025-11-25T12:00:00Z"
+        }
+      ],
+      "hasMore": false,
+      "retrievedAt": "2025-11-25T12:00:01Z"
+    }
+  ]
+}
+```
+  
+Determinism:  
+- Results ordered by provider ordering returned from storage; clients must not assume stable sort keys beyond the documented arrays.  
+- `retrievedAt` is server UTC ISO-8601.  
+- `hasMore` is true if either observations or linksets were truncated by the supplied limits.  
+  
+Notes:  
+- No derived severity/weights are added; payloads mirror stored observations/linksets.  
+- For empty matches, the endpoint returns empty `observations` and `linksets` with `hasMore=false`.  
+  
+Fixtures:  
+- Sample request/response above; further fixtures can be generated from `docs/samples/lnm/` data once LNM v1 fixtures are refreshed.  
+  
+Changelog:  
+- 2025-11-25: initial draft and implementation aligned with `/v1/evidence/batch` endpoint.