Coverage for src/governed_harness/orchestration/feedback.py: 98%
68 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Feedback for a correction attempt and the transient-failure test for command providers.
3Both work on what the harness already recorded (validation results, findings and their redacted
4artifacts); neither runs a check of its own."""
6from __future__ import annotations
8import json
9import re
10from collections.abc import Iterable, Sequence
12from governed_harness.domain.enums import FindingSeverity, ResultStatus
13from governed_harness.domain.models import (
14 FEEDBACK_MAX_FINDINGS,
15 FEEDBACK_STREAM_CHARS,
16 FEEDBACK_TEXT_CHARS,
17 FEEDBACK_TOTAL_CHARS,
18 FeedbackDecision,
19 FeedbackFinding,
20 FeedbackGate,
21 FeedbackTrigger,
22 FeedbackValidator,
23 Finding,
24 ProviderFeedback,
25 ValidationResult,
26)
27from governed_harness.evidence import LocalArtifactStore
29_SEVERITY_ORDER = {
30 FindingSeverity.CRITICAL: 0,
31 FindingSeverity.HIGH: 1,
32 FindingSeverity.MEDIUM: 2,
33 FindingSeverity.LOW: 3,
34 FindingSeverity.INFO: 4,
35}
37TRANSIENT_SCAN_BYTES = 65536
38"""Bytes read from the end of each provider stream when looking for a transient cause."""
41def tail(text: str, limit: int) -> tuple[str, bool]:
42 """The last ``limit`` characters of ``text`` and whether anything was cut."""
43 if limit <= 0:
44 return "", bool(text)
45 if len(text) <= limit:
46 return text, False
47 return text[-limit:], True
50def head(text: str, limit: int = FEEDBACK_TEXT_CHARS) -> str:
51 """``text`` cut to ``limit`` characters, marking the cut with an ellipsis."""
52 return text if len(text) <= limit else text[: limit - 1] + "…"
55def failing_validations(validations: Iterable[ValidationResult]) -> list[ValidationResult]:
56 """Mandatory validation results that did not pass, in their recorded order."""
57 return [
58 item for item in validations if item.mandatory and item.status is not ResultStatus.PASSED
59 ]
62def verification_reason_codes(failing: Sequence[ValidationResult]) -> tuple[str, ...]:
63 """Reason codes in the form the gate engine uses: ``<validatorId>_<STATUS>``."""
64 return tuple(f"{item.validator_id}_{item.status}" for item in failing)
67class FeedbackBuilder:
68 def __init__(self, artifacts: LocalArtifactStore) -> None:
69 self.artifacts = artifacts
71 def build(
72 self,
73 *,
74 trigger: FeedbackTrigger,
75 attempt: int,
76 change_set_digest: str,
77 gate: FeedbackGate,
78 validations: Sequence[ValidationResult],
79 findings: Sequence[Finding],
80 decision: FeedbackDecision | None = None,
81 ) -> ProviderFeedback:
82 ordered = sorted(findings, key=lambda item: _SEVERITY_ORDER.get(item.severity, 5))
83 kept = ordered[:FEEDBACK_MAX_FINDINGS]
84 return ProviderFeedback(
85 attempt=attempt,
86 trigger=trigger,
87 change_set_digest=change_set_digest,
88 gate=gate,
89 findings=tuple(
90 FeedbackFinding(
91 rule_id=item.rule_id,
92 severity=item.severity,
93 validator_id=item.validator_id,
94 location=item.location,
95 message=head(item.message),
96 )
97 for item in kept
98 ),
99 omitted_findings=len(ordered) - len(kept),
100 validators=self._validators(failing_validations(validations)),
101 decision=decision,
102 )
104 def _validators(self, failing: Sequence[ValidationResult]) -> tuple[FeedbackValidator, ...]:
105 budget = FEEDBACK_TOTAL_CHARS
106 items: list[FeedbackValidator] = []
107 for result in failing:
108 report = self._report(result)
109 streams: dict[str, tuple[str, bool]] = {}
110 for name in ("stdout", "stderr"):
111 text = self._text(report.get(f"{name}Ref"))
112 excerpt, cut = tail(text, min(FEEDBACK_STREAM_CHARS, budget))
113 budget -= len(excerpt)
114 streams[name] = (excerpt, cut or bool(report.get(f"{name}Truncated")))
115 exit_code = report.get("exitCode")
116 items.append(
117 FeedbackValidator(
118 validator_id=result.validator_id,
119 status=result.status,
120 summary=head(result.summary),
121 exit_code=exit_code if isinstance(exit_code, int) else None,
122 stdout=streams["stdout"][0],
123 stderr=streams["stderr"][0],
124 stdout_truncated=streams["stdout"][1],
125 stderr_truncated=streams["stderr"][1],
126 )
127 )
128 return tuple(items)
130 def _report(self, result: ValidationResult) -> dict[str, object]:
131 """The validation report of a command validator (its first evidence reference)."""
132 try:
133 value = json.loads(self.artifacts.get(result.evidence_refs[0]))
134 except (OSError, ValueError, KeyError, IndexError):
135 return {}
136 return value if isinstance(value, dict) else {}
138 def _text(self, uri: object) -> str:
139 if not isinstance(uri, str):
140 return ""
141 try:
142 return self.artifacts.get(uri).decode("utf-8", "replace")
143 except (OSError, ValueError, KeyError):
144 return ""
147def _pattern_regex(pattern: str) -> re.Pattern[str]:
148 # A numeric code such as 429 must not match inside a longer number (a line 4290 of a log).
149 body = re.escape(pattern.strip())
150 prefix = r"(?<![0-9])" if pattern.strip()[:1].isdigit() else ""
151 suffix = r"(?![0-9])" if pattern.strip()[-1:].isdigit() else ""
152 return re.compile(prefix + body + suffix, re.IGNORECASE)
155def transient_cause(texts: Iterable[str], patterns: Sequence[str]) -> str | None:
156 """The first configured pattern found in the provider's streams, or ``None``."""
157 compiled = [(pattern, _pattern_regex(pattern)) for pattern in patterns]
158 for text in texts:
159 for pattern, regex in compiled:
160 if regex.search(text):
161 return pattern
162 return None