# Advisory AI API (structured chunks)

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

## Response contract

```jsonc
{
  "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 GraphQL and Cisco PSIRT openVuln payloads for downstream parity.