# Remediation Heuristics for Advisory AI (DOCS-AIAI-31-008)

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

This note defines the deterministic remediation heuristics Advisory AI applies when SBOM context is present. It aligns with `SBOM-AIAI-31-001` (path/timeline endpoints) and the CLI fixtures shipped in `CLI-VULN-29-001`.

## Inputs
- SBOM context document (schema `stellaops.sbom.context/1.0`), e.g. `out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json` (SHA256 `421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18`).
- Version timelines from `/sbom/versions?artifactId=...` (clamped to 500 entries by default).
- Dependency paths from `/sbom/paths?artifactId=...` (clamped to 200 paths by default).
- Advisory/VEX evidence from Link-Not-Merge (`advisory_observations`, `advisory_linksets`).

## Heuristics (deterministic)
1) **Blast radius score** per package
   - `score = (directPaths * 2) + transitivePaths + exposedRuntimeHint`
   - `exposedRuntimeHint = 3` when the runtime signal `exposure=external` is present, else `0`.
   - Scores are capped at `20` to keep ordering stable.

2) **Fix candidate ranking**
   - Prefer vendor fixed versions present in timeline; fall back to highest patch version above current.
   - Reject candidates that would **increase** blast radius by adding new transitive edges (>10% increase).
   - If no fix exists, emit `advisory.remediation.noFixAvailable` and cite the timeline.

3) **Configuration-only mitigations**
   - When VEX status is `not_affected` **and** blast radius score < 5, recommend configuration hardening (feature flags, admission policy) instead of upgrades.

4) **Refusal conditions**
   - Missing SBOM context → return deterministic remediation with `sbomSummary` counts set to 0 and note `contextUnavailable` in metadata.
   - Timeline gaps (non-monotonic dates or hashes) → `409 advisory.contextHashMismatch` with the offending hash list.

## Example (offline fixture)
Using `sample-sbom-context.json`:

| Package | Paths | Blast radius | Suggested action |
| --- | --- | --- | --- |
| openssl@1.1.1w | 2 direct, 4 transitive | `(2*2)+4 = 8` | Upgrade to vendor fixed `1.1.1x` (from timeline); verify after replacement. |
| zlib@1.2.11 | 1 direct, 2 transitive | `(1*2)+2 = 4` | Apply VEX `not_affected` justification if available; otherwise patch to `1.2.12`. |

## Operator checklist
- Export SBOM context and hashes into Offline Kit (`offline-kit/advisory-ai/fixtures/sbom-context/`).
- Verify clamps: `timelineClamp=500`, `dependencyPathClamp=200` unless explicitly overridden in `AdvisoryAI:Tasks:Remediation`.
- Record blast-radius scores in audit logs when remediation is generated (helps replay).
- Keep fixtures in sync with CLI guardrail artefact hashes and note any override in sprint Execution Log.