kami
9734eec63c
Generated by per-group subagents covering all 52 modules across: core (18), infrastructure (10), apps (5), interfaces (3), plugins (7), testing (9) Documentation format: - AsciiDoc (.adoc) files in docs/modules/<group>/ - PlantUML (.puml) files in docs/diagrams/ - .adoc files reference diagrams via include:: directives Each doc covers: purpose, responsibilities, non-responsibilities, key types, event flow, integration points, invariants, PlantUML diagram, known issues, and open questions.
89 lines
3.6 KiB
Plaintext
89 lines
3.6 KiB
Plaintext
= core-risk
|
|
|
|
== purpose
|
|
|
|
Assesses operational risk at decision points by evaluating validation reports, orchestration state, and inference history. Produces a `RiskSummary` that drives approval tier selection and determines whether an operation may proceed, requires user prompting, or must be blocked.
|
|
|
|
== responsibilities
|
|
|
|
* Evaluate validation errors, cycle detection, repeated failures, and inference timeouts
|
|
* Map risk signals to a risk level (LOW, MEDIUM, HIGH, CRITICAL)
|
|
* Derive a recommended action (PROCEED, PROMPT_USER, BLOCK) from the risk level
|
|
* Provide a no-op implementation for deterministic replay paths
|
|
|
|
== non-responsibilities
|
|
|
|
* Does not enforce approvals — that belongs to `core:approvals`
|
|
* Does not define policy rules — that belongs to `core:policies`
|
|
* Does not emit events directly (signals are consumed by the approval layer)
|
|
* Does not mutate state
|
|
|
|
== key types
|
|
|
|
=== RiskAssessor
|
|
* **kind**: interface
|
|
* **purpose**: Contract for evaluating a `RiskContext` and producing a `RiskSummary`.
|
|
|
|
=== DefaultRiskAssessor
|
|
* **kind**: class
|
|
* **purpose**: Production implementation that inspects validation errors, cycles, retry exhaustion, and inference timeouts from the context.
|
|
|
|
=== NoOpRiskAssessor
|
|
* **kind**: class
|
|
* **purpose**: Returns `RiskSummary(LOW, emptyList(), PROCEED)` unconditionally. Used during deterministic replay to avoid running live risk assessment.
|
|
|
|
=== RiskContext
|
|
* **kind**: data class
|
|
* **purpose**: Immutable snapshot of all signals available for risk assessment at a decision point.
|
|
* **fields**: `validationReport` (validation issues for the current stage), `orchestrationState` (retry count, failure reason, retry policy), `inferenceState` (inference history for timeout detection)
|
|
|
|
=== TierMapping
|
|
* **kind**: file-level extension functions
|
|
* **purpose**: Maps `RiskLevel` to `Tier` (LOW→T1, MEDIUM→T2, HIGH→T3, CRITICAL→T4) and maps individual `RiskSignal` instances to their `RiskLevel`.
|
|
* **variants**:
|
|
* `RiskLevel.toApprovalTier()` — maps to `core:approvals` Tier
|
|
* `RiskLevel.toRiskAction()` — maps to `RiskAction` (PROCEED, PROMPT_USER, BLOCK); marked `internal`
|
|
* `RiskSignal.toRiskLevel()` — per-signal severity (ValidationErrors→MEDIUM, CycleWithoutExit→MEDIUM, InferenceTimeout→MEDIUM, RepeatedFailure→HIGH); marked `internal`
|
|
|
|
== event flow
|
|
|
|
*Inbound:* None directly. The `RiskContext` is assembled from:
|
|
* `ValidationReport` (produced by `core:validation`)
|
|
* `OrchestrationState` (from `core:kernel`)
|
|
* `InferenceState` (from `core:inference`)
|
|
|
|
*Outbound:* None. `RiskSummary` is returned synchronously to the caller (approval or orchestration layer).
|
|
|
|
== integration points
|
|
|
|
* `core:events.risk` — `RiskSummary`, `RiskLevel`, `RiskSignal`, `RiskAction` (event types)
|
|
* `core:approvals` — `Tier` enum
|
|
* `core:validation.model` — `ValidationReport`, `ValidationSeverity`
|
|
* `core:inference` — `InferenceState`, `InferenceStatus`
|
|
* `core:kernel` — `OrchestrationState`
|
|
|
|
== invariants
|
|
|
|
* `NoOpRiskAssessor` must be used on replay paths — live assessment on replay would produce non-deterministic results
|
|
* `RiskContext.orchestrationState` is populated from config before the first assessment call, not from `StageOutcome` (which lives in `core:kernel` and cannot be imported due to dependency direction)
|
|
|
|
== PlantUML diagram
|
|
|
|
[plantuml, core-risk, "png"]
|
|
----
|
|
include::../../diagrams/core-risk.puml[]
|
|
----
|
|
|
|
|
|
|
|
|
|
== known issues
|
|
|
|
* Signal-to-level mapping is hardcoded in `TierMapping.kt` and not configurable
|
|
* No support for custom or external risk signals
|
|
|
|
== open questions
|
|
|
|
* Should risk signal mapping become configurable or rule-driven?
|
|
* Should risk assessment emit events for audit trail purposes?
|