docs: Document the finding risk score API contract

[justin-prime1]

Description

Sister BHE PR: https://github.com/SpecterOps/bloodhound-enterprise/pull/1751

Depends on layer 1: #3150 and https://github.com/SpecterOps/bloodhound-enterprise/pull/1750

Followed by layer 3: #3152 and https://github.com/SpecterOps/bloodhound-enterprise/pull/1752

Merge blocker: Layer 1 must land first. This BHCE PR merges before its BHE sister, but neither merges until both are approved and green.

Intent

Document the shared, lossless public contract for Enterprise finding-risk scores without adding BHCE runtime behavior.

Implementation

Adds optional decimal-string risk_score fields, numeric-sort support, a unified-findings CSV RiskScore column, updated examples, and regenerated OpenAPI output. Decimal strings preserve arbitrary-precision integers for JavaScript consumers.

Blast Radius / Risk

This changes shared OpenAPI source/generated documentation only. Generated clients may expose a new optional field and CSV consumers observe an appended column; existing fields remain unchanged. BHCE adds no database, analysis, API implementation, or UI behavior.

BHE/BHCE Parity

matched: BHCE owns the shared contract; BHE owns calculation, persistence, projections, numeric sorting, CSV generation, and UI. Runtime calculation remains intentionally Enterprise-only.

Reviewability

Review size: 50 reviewable OpenAPI lines. Excluded mechanical/generated material: 27 generated openapi.json lines.

Test Changes

No BHCE runtime tests were added because this is contract-only. OpenAPI generation and full repository preparation validate source/generated consistency; runtime behavior is tested in the sister BHE PR. No tests were removed.

Rollback

Revert this PR and regenerate OpenAPI. Existing servers and persisted data are unaffected; regenerate any external clients produced from this prototype contract.

Motivation and Context

The BHE sister persists arbitrary-precision scores; the shared JSON, sort, and CSV contract must describe them without precision loss. No Jira or GitHub issue is associated with this prototype, by author request.

Resolves N/A — prototype authorized without a ticket.

How Has This Been Tested?

Validation / Evidence

At BHCE 5ef3b1750c0bbc08ed8e71e03ca22be217113ca3 and BHE ef9c5103a740a8d515229ec3c7b421c993bdc934:

• OpenAPI generation completed cleanly.
• Full clean just prepare-for-codereview passed.
• Paired BHE focused Go/UI/race, parity, and enterprise review gates passed.

Explicitly Not Validated

• No BHCE runtime/database behavior, because none changes here.
• External generated clients were not separately regenerated/tested.

Screenshots (optional):

Runtime evidence from the paired BHE PR:

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist:

• I have met the contributing prerequisites
  • Assigned myself to this PR
  • Added the appropriate labels
  • Associated an issue: N/A by author request
  • Read the Contributing guide
• I have ensured that related documentation is up-to-date
• I have followed proper test practices

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: c1c7b36c-9a6a-4cf2-9de7-129041e6a8e2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}