Advisory AI API (structured chunks)

Scope: /advisories/{advisoryKey}/chunks (Concelier WebService) · aligned with Sprint 0112 canonical model.

Response contract

{
  "advisoryKey": "CVE-2025-0001",
  "fingerprint": "<sha256 canonical advisory>",
  "total": 3,
  "truncated": false,
  "entries": [
    {
      "type": "workaround",                  // ordered by (type, observationPath, documentId)
      "chunkId": "c0ffee12",                // sha256(documentId|observationPath) first 8 bytes
      "content": { /* structured field payload */ },
      "provenance": {
        "documentId": "tenant-a:chunk:newest",   // Observation _id
        "observationPath": "/references/0",      // JSON Pointer into observation
        "source": "nvd",
        "kind": "workaround",
        "value": "tenant-a:chunk:newest",
        "recordedAt": "2025-01-07T00:00:00Z",
        "fieldMask": ["/references/0"]
      }
    }
  ]
}

Determinism & provenance

• Sort entries by (type, observationPath, documentId) to keep cache keys stable across nodes.
• Cache keys include the advisory fingerprint, chunk/observation limits, filters, and observation hashes.
• Provenance anchors must always include both documentId and observationPath for Console/Attestor deep links and offline mirrors.

Query parameters

• tenant (required): tenant id; must match authorization context.
• limit, observations, minLength: bounded integers (see ConcelierOptions.AdvisoryChunks).
• section, format: comma-separated filters (case-insensitive).

Compatibility notes

• Mirrors and offline kits rely on fingerprint + chunkId to verify chunks without re-merging observations.
• Field names mirror GHSA REST and Cisco PSIRT openVuln payloads for downstream parity.