# SBOM Context Hand-off for Advisory AI (SBOM-AIAI-31-003)

_Updated: 2025-11-24 · Owners: Advisory AI Guild · SBOM Service Guild · Sprint 0111_

Defines the contract and smoke test for passing SBOM context from SBOM Service to Advisory AI `/v1/sbom/context` consumers. Aligns with `SBOM-AIAI-31-001` (paths/timelines) and the CLI fixtures published on 2025-11-19.

## Contract
- **Endpoint** (SBOM Service): `/sbom/context`
- **Request** (minimal):
```json
{
  "artifactId": "registry.stella-ops.internal/runtime/api",
  "purl": "pkg:oci/runtime-api@sha256:d2c3...",
  "timelineClamp": 500,
  "dependencyPathClamp": 200
}
```
- **Response** (summarised):
```json
{
  "schema": "stellaops.sbom.context/1.0",
  "generated": "2025-11-19T00:00:00Z",
  "packages": [
    {"name":"openssl","version":"1.1.1w","purl":"pkg:deb/openssl@1.1.1w"},
    {"name":"zlib","version":"1.2.11","purl":"pkg:deb/zlib@1.2.11"}
  ],
  "timeline": 8,
  "dependencyPaths": 5,
  "hash": "sha256:421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18"
}
```
- **Determinism**: clamp values fixed unless overridden; `generated` timestamp frozen per fixture when offline.
- **Headers**: `X-StellaOps-Tenant` required; `X-StellaOps-ApiKey` optional for bootstrap.

## Smoke test (tenants/offline)
1. Start SBOM Service with fixture data loaded (or use `sample-sbom-context.json`).
2. Run: `curl -s -H "X-StellaOps-Tenant: demo" -H "Content-Type: application/json" \
   -d @out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json \
   http://localhost:8080/sbom/context | jq .hash` (expect `sha256:421a...9d18`).
3. Configure Advisory AI:
   - `AdvisoryAI:SBOM:BaseAddress=http://localhost:8080`
   - `AdvisoryAI:SBOM:ApiKey=<key-if-required>`
4. Call Advisory AI cache-only: `stella advise run remediation --advisory-key csaf:redhat:RHSA-2025:1001 --artifact-id registry.stella-ops.internal/runtime/api --timeout 0 --json`.
   - Expect exit 0 and `sbomSummary.dependencyPaths=5` in response.
5. Record the hash and endpoint in ops log; mirror fixture + hashes into Offline Kit under `offline-kit/advisory-ai/fixtures/sbom-context/`.

## Failure modes
- `409 advisory.contextHashMismatch` — occurs when the returned `hash` differs from the LNM linkset `provenanceHash`; refresh context or re-export.
- `403` — tenant/api key mismatch; check `X-StellaOps-Tenant` and API key.
- `429` — clamp exceeded; reduce `timelineClamp`/`dependencyPathClamp` or narrow `artifactId`.

## References
- `docs/sbom/remediation-heuristics.md` (blast-radius scoring).
- `docs/advisory-ai/guardrails-and-evidence.md` (evidence contract).
- `docs/modules/cli/artefacts/guardrails-artefacts-2025-11-19.md` (hashes for fixtures).