docs: Document the finding risk calculation contract

[justin-prime1]

Description

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

Depends on layer 2: #3151 and https://github.com/SpecterOps/bloodhound-enterprise/pull/1751

Merge blocker: PR2 must land first. This BHCE PR merges before its BHE sister, but neither merges until both are non-draft, approved, green, and free of unresolved review threads other than this ordering blocker.

Intent

Document the optional persisted calculation evidence used by BHE to render an auditable risk-score explanation without recomputing historical graph state in the browser.

Implementation

Adds optional risk_score_calculation schemas for stored/effective exposure, impact, aggregate score, and ordered per-zone zone/environment, hop/reason/divisor, source-principal count/reason, and contribution evidence. Arbitrary-precision values remain decimal strings. The bundled OpenAPI document is regenerated. There are no BHCE runtime, database, UI, graph, or migration changes.

Blast Radius / Risk

This is an additive optional contract. Generated consumers may expose the new object; enums and decimal strings must remain synchronized with BHE. Existing clients that ignore unknown optional properties should be unaffected. Deploying BHE without this shared contract would leave repository documentation/generated artifacts inconsistent.

BHE/BHCE Parity

matched: BHCE owns the additive schema; BHE owns hydration, JSON projection, and UI. The object is intentionally optional and scoped to list/relationship detail responses.

Reviewability

Review size: 78 reviewable schema lines. Excluded mechanical/generated material: 100 generated openapi.json lines.

Test Changes

No BHCE behavioral tests were added because this is schema-only. Schema generation, formatting/linting, and cleanliness were validated; the paired BHE PR covers projection and UI behavior. No tests were removed.

Rollback

Revert this schema/generated-document commit after or with the paired BHE consumer. No database, feature flag, configuration, persisted-data, or graph cleanup is involved.

Motivation and Context

The BHE sister renders exact persisted factors so analysts can audit the aggregate. 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 0bbdee2044804359a7290c958f1ef0ee88c97dcf and BHE 9cc730c67072a92533a8190e4acfeb6731bec7f8:

• OpenAPI generation and full clean just prepare-for-codereview passed.
• Paired BHE backend/API and 50 focused UI tests passed.
• Parity and independent enterprise review passed.

Explicitly Not Validated

• No standalone BHCE runtime test, because runtime behavior does not change.
• External generated clients were not separately regenerated/compatibility-tested.
• Production-scale BHE hydration benchmarking remains unvalidated in the paired PR.

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: 6a99ea34-9c54-4180-b58f-d0c82ec3dca2

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.}