2eaf0f699b
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
- Added AirgapTimelineImpact, AirgapTimelineImpactInput, and AirgapTimelineImpactResult records for managing air-gap bundle import impacts. - Introduced EvidenceSnapshotRecord, EvidenceSnapshotLinkInput, and EvidenceSnapshotLinkResult records for linking findings to evidence snapshots. - Created IEvidenceSnapshotRepository interface for managing evidence snapshot records. - Developed StalenessValidationService to validate staleness and enforce freshness thresholds. - Implemented AirgapTimelineService for emitting timeline events related to bundle imports. - Added EvidenceSnapshotService for linking findings to evidence snapshots and verifying their validity. - Introduced AirGapOptions for configuring air-gap staleness enforcement and thresholds. - Added minimal jsPDF stub for offline/testing builds in the web application. - Created TypeScript definitions for jsPDF to enhance type safety in the web application.
36 lines
2.1 KiB
Markdown
36 lines
2.1 KiB
Markdown
# Risk Explainability
|
|
|
|
> Source: `CONTRACT-RISK-SCORING-002` (2025-12-05). Fixtures live under `docs/risk/samples/explain/`; all hashes in `SHA256SUMS`. Keep outputs deterministic (frozen payloads, stable ordering).
|
|
|
|
## Purpose
|
|
- Show how the scoring engine produces per-factor contributions and traces that UI/CLI/export surfaces render for auditors and operators.
|
|
|
|
## Scope & Audience
|
|
- Audience: Console/CLI users, auditors, SREs.
|
|
- In scope: explainability payload shape, field meanings, provenance, UI/CLI mapping, offline/export behavior.
|
|
- Out of scope: formula math (see `formulas.md`), API specifics (see `api.md`).
|
|
|
|
## Payload Shape
|
|
- Envelope: `job_id`, `tenant_id`, `context_id`, `profile_id`, `profile_version`, `profile_hash`, `finding_id`, `raw_score`, `normalized_score`, `severity`, `signal_values{}`, `signal_contributions{}`, optional `override_applied`, `override_reason`, `gates_triggered[]`, `scored_at`, `provenance` (job hash + fixture hashes).
|
|
- Factor entries (from `signal_values`/`signal_contributions`): `name`, `source`, `type`, `path`, `raw_value`, `normalized_value`, `weight`, `contribution`, `provenance`.
|
|
- UI/CLI expectations: deterministic ordering (factor type → source → timestamp), highlight top contributors, show attestation status for each factor.
|
|
|
|
## UI/CLI Views
|
|
- Console: frame sample in `docs/risk/samples/explain/console-frame.json` shows top contributors, gate badges, and provenance hashes.
|
|
- CLI `stella risk explain job-001`: deterministic text fixture in `docs/risk/samples/explain/cli-explain.txt`; `--json` mirrors `explain-trace.json`.
|
|
- Export Center: embed explain payload + SHA256 manifest; CSV export keeps deterministic ordering.
|
|
|
|
## Determinism & Offline Posture
|
|
- Example payload: `docs/risk/samples/explain/explain-trace.json` (hash in `SHA256SUMS`).
|
|
- No live calls; all captures from frozen fixtures. Use exact ordering and timestamps when regenerating.
|
|
|
|
## Open Items
|
|
- Add schema file once JSON schema is frozen; update references accordingly.
|
|
|
|
## References
|
|
- `docs/risk/overview.md`
|
|
- `docs/risk/profiles.md`
|
|
- `docs/risk/factors.md`
|
|
- `docs/risk/formulas.md`
|
|
- `docs/risk/api.md`
|