Explanation API and Replay Semantics

The Explanation API produces explanation content with citation and provenance metadata. The current response, provider requirements and replay limits are specified below. A response or output hash does not establish a signed attestation, verified evidence or identical regenerated output.

Audience: platform operators, security analysts, and integrators wiring Stella Ops AI explanations into review workflows or release gates.

This guide covers the explanation endpoints, the attestation format, and the replay semantics that distinguish current contracts from deterministic-replay design.

Overview

The Explanation API provides evidence-anchored explanations answering:

• What is this vulnerability?
• Why does it matter in this context?
• Evidence: What supports exploitability?
• Counterfactual: What would change the verdict?

The configured generator retrieves evidence nodes and classifies its extracted citations. The classification does not guarantee that every claim is verified.

Explanation Types

Current API Endpoints

Source reviewed at ad9edbcef5 (PCD-456, 2026-10-08): the composed host maps the operations below beneath /api/advisoryai/v1/advisory-ai. The alias builder preserves the original handler, method and authorization metadata; a prefix change cannot supply an absent operation or a different response body.

Generate Explanation

POST /api/advisoryai/v1/advisory-ai/explain takes ExplainRequest: findingId, artifactDigest, scope, scopeId and vulnerabilityId are required; explanationType, componentPurl, plainLanguage, maxLength and correlationId are the supported options. It requires the operate policy (advisory-ai:operate or advisory-ai:admin) and the handler’s explain-scope check. Invalid operation input returns 400; authorization failure returns 403.

The result is ExplainResponse: explanation ID, content, three-line summary, citations, confidence/citation rate, authority, evidence references, model/prompt metadata, generated time and output hash. It has no attestation, signature or replay-manifest field. Generation requires the configured evidence and inference providers; publication alone does not prove their availability or output quality.

Replay Explanation

GET /api/advisoryai/v1/advisory-ai/explain/{explanationId}/replay returns the same ExplainResponse type. The service loads the stored request, validates referenced evidence and calls generation again. It does not return an original/replayed/identical/similarity comparison and does not prove bit-for-bit determinism. Missing stored data or failed validation maps to 404. Although its route has the view policy, the additional explain check excludes a view-only caller; operate/admin satisfies both current checks.

Unavailable explanation operations

GET-by-explanation-ID and POST validation are not mapped by this host. A library ValidateAsync method is not an HTTP publication. No alias or replacement request is supplied for those former guide examples.

Reverify StellaOps.AdvisoryAI.WebService/Program.cs, Contracts/ExplainRequest.cs, Contracts/ExplainResponse.cs, Endpoints/AdvisoryAiConsolidatedRouteAliases.cs and StellaOps.AdvisoryAI/Explanation/EvidenceAnchoredExplanationGenerator.cs under src/AdvisoryAI/. This is source-contract review, not deployed acceptance.

Evidence Types

Authority Classification

Explanations are classified by their evidence backing:

public enum ExplanationAuthority
{
    EvidenceBacked,  // Verified-citation ratio meets the generator threshold
    Suggestion       // AI suggestion requiring human review
}

Attestation Format

The schema and attachment sketches below are design material, not fields returned by ExplainResponse. Run attestation is a separate contract with configured signing custody; explanation generation does not guarantee a DSSE envelope.

Predicate Type

https://stellaops.org/attestation/ai-explanation/v1

Predicate Schema

{
  "_type": "https://stellaops.org/attestation/ai-explanation/v1",
  "explanationId": "expl-20251226-001",
  "explanationType": "Full",
  "authority": "EvidenceBacked",
  "finding": {
    "findingId": "finding-abc123",
    "vulnerabilityId": "CVE-2024-1234",
    "componentPurl": "pkg:npm/lodash@4.17.20"
  },
  "model": {
    "modelId": "claude-sonnet-4-20250514",
    "promptTemplateVersion": "v2.1.0"
  },
  "inputs": {
    "inputHashes": ["sha256:abc123...", "sha256:def456..."],
    "evidenceRefs": ["nvd:CVE-2024-1234", "sbom:..."]
  },
  "output": {
    "contentHash": "sha256:789xyz...",
    "confidenceScore": 0.92,
    "citationRate": 0.85,
    "citationCount": 6
  },
  "generatedAt": "2025-12-26T10:30:00Z"
}

DSSE Envelope

{
  "payloadType": "application/vnd.stellaops.ai-explanation+json",
  "payload": "<base64-encoded-predicate>",
  "signatures": [
    {
      "keyId": "stellaops-ai-signer-2025",
      "sig": "<base64-signature>"
    }
  ]
}

OCI Attachment

Attestations are pushed as OCI referrers:

Artifact: sha256:imagedigest
  └── Referrer: application/vnd.stellaops.ai-explanation+json
      └── expl-20251226-001.dsse.json

Replay Semantics

Replay Manifest

Every explanation includes a replay manifest enabling deterministic reproduction:

{
  "manifestVersion": "1.0",
  "explanationId": "expl-20251226-001",
  "model": {
    "modelId": "claude-sonnet-4-20250514",
    "weightsDigest": "sha256:modelweights...",
    "promptTemplateVersion": "v2.1.0"
  },
  "inputs": {
    "findingId": "finding-abc123",
    "artifactDigest": "sha256:abcdef...",
    "evidenceHashes": {
      "advisory": "sha256:111...",
      "sbom": "sha256:222...",
      "reachability": "sha256:333..."
    }
  },
  "parameters": {
    "temperature": 0.0,
    "seed": 42,
    "maxTokens": 4096
  },
  "output": {
    "contentHash": "sha256:789xyz...",
    "generatedAt": "2025-12-26T10:30:00Z"
  }
}

Determinism Requirements

For replay to produce identical output:

Divergence Detection

When replay produces different output:

{
  "diverged": true,
  "similarity": 0.94,
  "originalHash": "sha256:789xyz...",
  "replayedHash": "sha256:different...",
  "divergencePoints": [
    {
      "position": 1234,
      "original": "...uses lodash@4.17.20...",
      "replayed": "...uses lodash version 4.17.20..."
    }
  ],
  "likelyCause": "model_update"
}

Divergence Causes

CLI Commands

# Generate explanation
stella advisory explain finding-abc123 \
  --type full \
  --plain-language \
  --attest --sign

# Replay explanation
stella advisory replay expl-20251226-001

# Verify explanation attestation
stella attest verify expl-20251226-001.dsse.json

# Check for divergence
stella advisory replay expl-20251226-001 --detect-divergence

Configuration

advisoryAi:
  explanation:
    # Default explanation type
    defaultType: Full

    # Plain language by default
    plainLanguage: true

    # Maximum explanation length
    maxLength: 4000

    # Minimum citation rate for EvidenceBacked authority
    minCitationRate: 0.80

    # Generate attestation for each explanation
    generateAttestation: true

    # Sign attestations
    signAttestation: true

  # Determinism settings for replay
  inference:
    temperature: 0.0
    seed: 42
    maxTokens: 4096

3-Line Summary Format

Every explanation includes a 3-line summary following the AI UX pattern:

Error Handling

Generation Errors

{
  "error": "evidence_retrieval_failed",
  "message": "Unable to retrieve SBOM for artifact sha256:abc...",
  "recoverable": true,
  "suggestion": "Ensure the artifact has been scanned before requesting explanation"
}

Validation Errors

{
  "error": "citation_verification_failed",
  "message": "Citation [2] references evidence that no longer exists",
  "invalidCitations": ["sbom:payment-service:lodash@4.17.20"],
  "suggestion": "Re-generate explanation with current evidence"
}

Related Documentation

• Advisory AI API Reference — base conventions, scopes, and the summary/conflict/remediation endpoints
• Guardrails & Evidence Intake — how evidence is sanitized, cited, and sealed
• AI Attestations
• LLM Provider Plugins
• Offline Model Bundles
• Advisory AI Architecture