Coverage for src/governed_harness/orchestration/friction.py: 88%
468 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"""Low friction for small changes (#58) and the plan-approval checkpoint (#8), wired into the
2engine's phases.
4``RunEngine`` delegates every step of the ``friction`` settings to this class, as it does for
5the agent-results and ladder settings: a project without the section runs exactly the earlier
6code path (``active`` is false and the engine never calls in). What each phase does:
8* INTENT: the lane. ``fastLane.mode: auto`` classifies the task with the router's size (#44) and
9 its risk flags: size ``S`` without a risk flag is the fast lane, anything else the full flow.
10 The lane, the size, the rule that decided and what the fast lane leaves out are recorded
11 (``lane.classified`` and a ``lane-decision`` evidence). A fast-lane run skips the agent's
12 ambiguity review. Under ``governance.riskProfile`` the fast lane is the light profile: ``auto``
13 as above, ``light`` for any task without a risk flag, ``full`` never; the light profile also
14 skips the ``locate`` call and the ``planApproval: risk`` checkpoint, and is on even without
15 ``friction.fastLane``.
16* PLANNING: no decomposition and no preflight on the baseline in the fast lane; the
17 plan-approval checkpoint (``planApproval``) for ``L`` tasks and tasks with a risk flag.
18* VERIFICATION: the ChangeSet is profiled (risk factors, files, change type). A risk factor or
19 a ChangeSet larger than ``S`` takes the run out of the fast lane (``lane.escalated``). The
20 fast lane runs the affected tests first, the validators side by side and reuses a validator
21 result for the same validator, ChangeSet, baseline and configuration; no light mutation. A
22 documentation-only or configuration-only ChangeSet needs no new tests and no requirement
23 traceability (``changeTypes``).
24* INDEPENDENT_REVIEW: in the fast lane the agent review runs only on a signal (a risk factor, a
25 finding of severity MEDIUM or above, a ChangeSet larger than ``S``).
26* DECISION: a pre-authorised approval is applied on the person's behalf only when its condition
27 holds (gate passed, no risk factor, size ``S``), its contract digest is unchanged and it has
28 not expired; otherwise the person is asked as usual.
30Nothing here skips a mandatory validator before the decision or decides for a person: the
31human decision is either a person's, or a person's recorded in advance under a condition the
32harness checked."""
34from __future__ import annotations
36import json
37from collections.abc import Callable, Collection, Sequence
38from concurrent.futures import ThreadPoolExecutor
39from datetime import timedelta
40from typing import TYPE_CHECKING, Any
42from governed_harness.agents.routing import classify_size
43from governed_harness.checks import parse_unified_diff
44from governed_harness.checks.risk import detect_risk_factors
45from governed_harness.configuration.agent_results import DEFAULT_SIZE_THRESHOLDS
46from governed_harness.configuration.models import ValidatorDefinition
47from governed_harness.domain.actors import require_human_actor
48from governed_harness.domain.enums import (
49 ActorType,
50 DecisionKind,
51 EvidenceKind,
52 FindingSeverity,
53 PhaseId,
54 ResultStatus,
55)
56from governed_harness.domain.errors import NotFoundError, PolicyViolationError
57from governed_harness.domain.ids import new_id
58from governed_harness.domain.models import (
59 HARNESS_ACTOR,
60 Actor,
61 ChangeSet,
62 Execution,
63 Finding,
64 GateEvaluation,
65 HumanDecision,
66 PhaseExecution,
67 Plan,
68 PreAuthorization,
69 Task,
70 ValidationResult,
71 utc_now,
72)
73from governed_harness.evidence.hashing import sha256_json
74from governed_harness.friction import (
75 affected_python_tests,
76 change_type,
77 exempt_from_tests,
78 plan_digest,
79)
80from governed_harness.intake import task_digest
81from governed_harness.ladder.contract import derive_contract
82from governed_harness.orchestration.engine_types import PhaseOutcome
83from governed_harness.validators import ValidatorOutput
85if TYPE_CHECKING:
86 from governed_harness.configuration.friction import (
87 FastLaneConfig,
88 FastVerificationConfig,
89 FrictionConfig,
90 PreAuthorizationConfig,
91 )
92 from governed_harness.configuration.models import ProjectConfiguration
93 from governed_harness.orchestration.engine_types import EngineServices
94 from governed_harness.orchestration.hosts import EngineHost
96LANE_FLAG = "lane"
97LIGHT_PROFILE_STEPS: tuple[str, ...] = ("locate", "planApproval")
98"""What the light profile of ``governance.riskProfile`` leaves out beyond the fast lane's
99``skip``: the ``locate`` call of INTENT and the ``planApproval: risk`` checkpoint of PLANNING."""
100PROFILE_FLAG = "changeprofile"
101PREAUTH_FLAG = "preauth"
102PREAUTH_USED_FLAG = "preauthused"
103PLAN_APPROVAL_FLAG = "planapproval"
104CACHE_FLAG = "validatorcache"
105AFFECTED_TESTS_ID = "harness.affected-tests"
106_REVIEW_SEVERITIES = frozenset(
107 {FindingSeverity.MEDIUM, FindingSeverity.HIGH, FindingSeverity.CRITICAL}
108)
109_BLOCKING_SEVERITIES = frozenset({FindingSeverity.HIGH, FindingSeverity.CRITICAL})
110_CACHEABLE = frozenset({ResultStatus.PASSED})
113class Friction:
114 def __init__(self, engine: EngineHost) -> None:
115 self.engine = engine
117 # ----- configuration ------------------------------------------------------------------------
118 @property
119 def s(self) -> EngineServices:
120 return self.engine.s
122 @property
123 def project(self) -> ProjectConfiguration:
124 return self.s.resolved.project
126 @property
127 def config(self) -> FrictionConfig | None:
128 return self.project.friction
130 @property
131 def risk_profile(self) -> str | None:
132 """``governance.riskProfile``: ``auto``, ``light``, ``full`` or ``None`` (1.x)."""
133 return self.project.governance_settings.risk_profile
135 @property
136 def fast_lane(self) -> FastLaneConfig | None:
137 """The fast lane in effect. Under ``governance.riskProfile`` it is the light profile:
138 ``full`` has none, ``auto`` and ``light`` have one even when ``friction.fastLane`` is
139 absent or ``off`` (its ``skip`` and ``verification`` are kept when present)."""
140 from governed_harness.configuration.friction import FastLaneConfig
142 config = self.config
143 lane = config.fast_lane if config else None
144 profile = self.risk_profile
145 if profile == "full":
146 return None
147 if profile in {"auto", "light"} and (lane is None or not lane.enabled):
148 return (lane or FastLaneConfig()).model_copy(update={"mode": "auto"})
149 return lane if lane is not None and lane.enabled else None
151 @property
152 def pre_authorization(self) -> PreAuthorizationConfig | None:
153 config = self.config
154 settings = config.pre_authorization if config else None
155 return settings if settings is not None and settings.enabled else None
157 @property
158 def fast_verification(self) -> FastVerificationConfig | None:
159 lane = self.fast_lane
160 return lane.verification if lane else None
162 @property
163 def change_types(self) -> bool:
164 config = self.config
165 return bool(config and config.change_types)
167 @property
168 def plan_approval(self) -> str:
169 config = self.config
170 return (config.plan_approval if config else None) or "off"
172 @property
173 def active(self) -> bool:
174 """Whether a ``friction`` setting that acts on a run is configured; without one the
175 engine runs the earlier path and never calls into this class."""
176 return any(
177 (
178 self.fast_lane is not None,
179 self.pre_authorization is not None,
180 self.change_types,
181 self.plan_approval != "off",
182 )
183 )
185 def _flag(self, key: str) -> Any:
186 raw = self.s.state.get_flag(key)
187 return json.loads(raw) if raw else None
189 def _set_flag(self, key: str, value: Any) -> None:
190 self.s.state.set_flag(key, json.dumps(value, sort_keys=True))
192 def _files_bound(self) -> int:
193 routing = self.project.agent_routing
194 thresholds = routing.thresholds if routing else None
195 configured = thresholds.files if thresholds else None
196 return (configured or DEFAULT_SIZE_THRESHOLDS["files"])[0]
198 # ----- size and risk of a task ----------------------------------------------------------------
199 def task_size(self, execution: Execution, task: Task) -> dict[str, Any]:
200 """The router's size of the task (#44) and its risk flags, before any change."""
201 signals = self.engine.results.task_signals(execution, task)
202 routing = self.project.agent_routing
203 size, rule = classify_size(signals, routing.thresholds if routing else None)
204 return {
205 "size": size,
206 "rule": rule,
207 "riskFlags": list(signals.risk_flags),
208 "requirements": signals.requirements,
209 "files": signals.files,
210 "loc": signals.loc,
211 }
213 # ----- INTENT: the lane ---------------------------------------------------------------------
214 def classify(self, execution: Execution, phase: PhaseExecution, task: Task) -> dict[str, Any]:
215 """The lane of the run for the current task revision, recorded once per revision."""
216 config = self.fast_lane
217 if config is None: # not reached: the engine classifies only in the fast lane 217 ↛ 218line 217 didn't jump to line 218 because the condition on line 217 was never true
218 raise RuntimeError("friction.fastLane is not enabled")
219 digest = task_digest(task)
220 known = self.lane(execution)
221 if known is not None and known.get("taskDigest") == digest:
222 return known
223 sized = self.task_size(execution, task)
224 profile = self.risk_profile
225 reasons: list[str] = []
226 if profile == "light":
227 # The light profile whatever the size; a risk flag still asks for the full one.
228 if sized["riskFlags"]: 228 ↛ 229line 228 didn't jump to line 229 because the condition on line 228 was never true
229 reasons.append(f"risk flag(s) {', '.join(sized['riskFlags'])}")
230 elif sized["size"] != "S":
231 reasons.append(f"size {sized['size']} ({sized['rule']})")
232 declared = [
233 item.criterion_id
234 for item in task.acceptance_criteria
235 if item.verification is not None
236 and (
237 item.verification.probe
238 or item.verification.deferred
239 or item.verification.manual
240 or item.verification.level.value > "L1"
241 )
242 ]
243 if task.probes or task.checklist or declared:
244 # A person who asked for stronger evidence asked for the full flow.
245 reasons.append("the task declares verification beyond L1 (probes, deferred or manual)")
246 lane = "full" if reasons else "fast"
247 skip: list[str] = list(config.skipped) if lane == "fast" else []
248 if profile is not None and lane == "fast":
249 skip += [step for step in LIGHT_PROFILE_STEPS if step not in skip]
250 fallback = "no risk flag" if profile == "light" else "size S and no risk flag"
251 record: dict[str, Any] = {
252 "lane": lane,
253 "size": sized["size"],
254 "rule": sized["rule"],
255 "riskFlags": sized["riskFlags"],
256 "signals": {key: sized[key] for key in ("requirements", "files", "loc")},
257 "reasons": reasons or [fallback],
258 "skip": skip,
259 "taskDigest": digest,
260 "escalated": False,
261 }
262 if profile is not None:
263 # governance.riskProfile: the governance profile the lane stands for.
264 record["profile"] = profile
265 record["governance"] = "light" if lane == "fast" else "full"
266 ref = self.engine.results.record_json(
267 execution,
268 PhaseId.INTENT,
269 record,
270 kind="lane-decision",
271 summary=f"Lane {lane}: {'; '.join(record['reasons'])}",
272 supports=(task.task_id,),
273 )
274 record["ref"] = ref
275 self._set_flag(f"{LANE_FLAG}:{execution.execution_id}", record)
276 self.s.events.append(
277 execution.execution_id,
278 "lane.classified",
279 {
280 key: record[key]
281 for key in (
282 "lane",
283 "size",
284 "rule",
285 "reasons",
286 "skip",
287 "taskDigest",
288 "profile",
289 "governance",
290 )
291 if key in record
292 }
293 | {"evidenceRef": ref},
294 phase_execution_id=phase.phase_execution_id,
295 )
296 return record
298 def lane(self, execution: Execution) -> dict[str, Any] | None:
299 value = self._flag(f"{LANE_FLAG}:{execution.execution_id}")
300 return value if isinstance(value, dict) else None
302 def fast(self, execution: Execution) -> bool:
303 lane = self.lane(execution)
304 return bool(lane and lane.get("lane") == "fast" and not lane.get("escalated"))
306 def skips(self, execution: Execution, step: str, phase_id: PhaseId | None = None) -> bool:
307 """Whether the fast lane leaves ``step`` out of this run; recorded when it does."""
308 if self.fast_lane is None or not self.fast(execution):
309 return False
310 lane = self.lane(execution) or {}
311 if step not in (lane.get("skip") or []):
312 return False
313 self.s.events.append(
314 execution.execution_id,
315 "lane.step.skipped",
316 {"step": step, "phaseId": phase_id.value if phase_id else None, "lane": "fast"},
317 )
318 return True
320 def escalate(self, execution: Execution, reasons: Sequence[str]) -> None:
321 lane = self.lane(execution)
322 if lane is None or lane.get("lane") != "fast" or lane.get("escalated"): 322 ↛ 323line 322 didn't jump to line 323 because the condition on line 322 was never true
323 return
324 lane = {**lane, "escalated": True, "escalationReasons": list(reasons)}
325 self._set_flag(f"{LANE_FLAG}:{execution.execution_id}", lane)
326 self.s.events.append(
327 execution.execution_id,
328 "lane.escalated",
329 {"from": "fast", "to": "full", "reasons": list(reasons)},
330 )
332 # ----- the ChangeSet: risk factors, size and change type --------------------------------------
333 def profile(self, execution: Execution, change_set: ChangeSet) -> dict[str, Any]:
334 """Risk factors, files, lines and change type of the ChangeSet, once per digest. A fast
335 run whose ChangeSet shows a risk factor or outgrows ``S`` leaves the fast lane."""
336 key = f"{PROFILE_FLAG}:{execution.execution_id}:{change_set.digest}"
337 known = self._flag(key)
338 if isinstance(known, dict):
339 return known
340 from governed_harness.orchestration.verification_checks import declared_interfaces
342 task = self.engine.run_task(execution)
343 text = self.engine._compute_owned_diff(execution).unified_diff.decode("utf-8", "replace")
344 interfaces = [path for pair in declared_interfaces(task) for path in pair]
345 signals = detect_risk_factors(parse_unified_diff(text), interface_paths=interfaces)
346 factors = sorted({signal.factor for signal in signals}, key=str)
347 paths = [item.path for item in change_set.files]
348 profile: dict[str, Any] = {
349 "digest": change_set.digest,
350 "riskFactors": factors,
351 "files": len(paths),
352 "lines": sum(item.additions + item.deletions for item in change_set.files),
353 "changeType": change_type(paths),
354 "filesBound": self._files_bound(),
355 }
356 self._set_flag(key, profile)
357 reasons = [f"risk factor {factor}" for factor in factors]
358 if len(paths) > profile["filesBound"]: 358 ↛ 359line 358 didn't jump to line 359 because the condition on line 358 was never true
359 reasons.append(f"files={len(paths)}>{profile['filesBound']} (ChangeSet larger than S)")
360 if reasons and self.fast(execution):
361 self.escalate(execution, reasons)
362 return profile
364 def tests_exempt(self, execution: Execution, change_set: ChangeSet, check: str) -> str | None:
365 """The reason ``check`` (a test or traceability requirement) does not apply to this
366 ChangeSet, when ``changeTypes`` is on and the ChangeSet is not code."""
367 if not self.change_types or not change_set.files:
368 return None
369 kind = self.profile(execution, change_set)["changeType"]
370 if not exempt_from_tests(kind):
371 return None
372 self.s.events.append(
373 execution.execution_id,
374 "change-type.exempted",
375 {"check": check, "changeType": kind, "digest": change_set.digest},
376 )
377 return f"{kind} change: {check} does not apply (friction.changeTypes)"
379 def not_applicable(
380 self, execution: Execution, change_set: ChangeSet, validator_id: str, reason: str
381 ) -> ValidatorOutput:
382 """A NOT_APPLICABLE result that records why a check did not run."""
383 results = self.engine.results
384 ref = results.record_json(
385 execution,
386 PhaseId.VERIFICATION,
387 {"validatorId": validator_id, "status": "NOT_APPLICABLE", "reason": reason},
388 kind="validator-not-applicable",
389 summary=f"{validator_id}: {reason}",
390 evidence_kind=EvidenceKind.TEST_REPORT,
391 )
392 from governed_harness.domain.enums import ValidationKind
394 now = utc_now()
395 actor = Actor(actor_type=ActorType.TOOL, actor_id=f"validator.{validator_id}", version="1")
396 result = ValidationResult(
397 validation_result_id=new_id("validation"),
398 execution_id=execution.execution_id,
399 validator_id=validator_id,
400 change_set_digest=change_set.digest,
401 status=ResultStatus.NOT_APPLICABLE,
402 kind=ValidationKind.SUCCESS,
403 mandatory=False,
404 summary=reason,
405 evidence_refs=(ref,),
406 started_at=now,
407 finished_at=now,
408 provenance=self.engine._provenance(execution).model_copy(update={"actor": actor}),
409 )
410 return ValidatorOutput(result)
412 # ----- INDEPENDENT_REVIEW: the agent review on signals -----------------------------------------
413 def review_signals(self, execution: Execution, change_set: ChangeSet) -> list[str]:
414 profile = self.profile(execution, change_set)
415 signals = [f"risk factor {factor}" for factor in profile["riskFactors"]]
416 if profile["files"] > profile["filesBound"]: 416 ↛ 417line 416 didn't jump to line 417 because the condition on line 416 was never true
417 signals.append(f"{profile['files']} files (larger than S)")
418 validations = self.engine._latest_validations(execution.execution_id, change_set.digest)
419 mandatory = {
420 finding for item in validations if item.mandatory for finding in item.finding_ids
421 }
422 ids = {finding for item in validations for finding in item.finding_ids}
423 findings = [
424 item
425 for item in self.s.state.list("finding", Finding, execution_id=execution.execution_id)
426 if item.finding_id in ids
427 and (
428 item.severity in _BLOCKING_SEVERITIES
429 or (
430 item.severity in _REVIEW_SEVERITIES
431 and (item.finding_id in mandatory or item.introduced is True)
432 )
433 )
434 ]
435 if findings:
436 # A finding an optional validator also reports on the baseline (introduced is not
437 # true) is no signal: it was there before the change.
438 signals.append(f"{len(findings)} finding(s) of this change of severity MEDIUM or above")
439 lane = self.lane(execution) or {}
440 if lane.get("escalated"):
441 signals.append("the run left the fast lane")
442 return signals
444 def agent_review_wanted(self, execution: Execution, change_set: ChangeSet) -> bool:
445 """In the fast lane the agent review runs only on a signal; elsewhere always."""
446 lane = self.lane(execution) or {}
447 if ( 447 ↛ 452line 447 didn't jump to line 452 because the condition on line 447 was never true
448 self.fast_lane is None
449 or lane.get("lane") != "fast"
450 or "agentReview" not in (lane.get("skip") or [])
451 ):
452 return True
453 signals = self.review_signals(execution, change_set)
454 if signals:
455 self.s.events.append(
456 execution.execution_id,
457 "review.agent.signals",
458 {"signals": signals, "digest": change_set.digest},
459 )
460 return True
461 self.s.events.append(
462 execution.execution_id,
463 "review.agent.skipped",
464 {"reason": "fast lane: no review signal", "digest": change_set.digest},
465 )
466 return False
468 # ----- VERIFICATION: affected tests first, parallel validators, cache by digest -------------
469 def _cache_key(self, execution: Execution, change_set: ChangeSet, definition: Any) -> str:
470 return sha256_json(
471 {
472 "validator": definition.model_dump(mode="json", by_alias=True),
473 "changeSet": change_set.digest,
474 "baseline": self.s.state.get_flag(f"baseline:{execution.execution_id}"),
475 "configuration": execution.configuration_digest,
476 }
477 )
479 def _reused(
480 self, execution: Execution, change_set: ChangeSet, definition: Any
481 ) -> ValidatorOutput | None:
482 key = self._cache_key(execution, change_set, definition)
483 cached = self._flag(f"{CACHE_FLAG}:{execution.project_id}:{key}")
484 if not isinstance(cached, dict):
485 return None
486 try:
487 earlier = self.s.state.get("validation", str(cached["validationId"]), ValidationResult)
488 except (NotFoundError, KeyError):
489 return None
490 now = utc_now()
491 result = earlier.model_copy(
492 update={
493 "validation_result_id": new_id("validation"),
494 "execution_id": execution.execution_id,
495 "change_set_digest": change_set.digest,
496 "summary": f"{earlier.summary} (reused from {earlier.validation_result_id}: "
497 "same validator, ChangeSet, baseline and configuration)",
498 "finding_ids": (),
499 "tool_invocation_ids": (),
500 "started_at": now,
501 "finished_at": now,
502 }
503 )
504 self.s.events.append(
505 execution.execution_id,
506 "validator.reused",
507 {
508 "validatorId": definition.validator_id,
509 "fromValidationId": earlier.validation_result_id,
510 "fromExecutionId": earlier.execution_id,
511 "digest": change_set.digest,
512 },
513 )
514 return ValidatorOutput(result)
516 def _remember(
517 self, execution: Execution, change_set: ChangeSet, definition: Any, output: Any
518 ) -> None:
519 if output.result.status not in _CACHEABLE or output.findings:
520 return
521 key = self._cache_key(execution, change_set, definition)
522 self._set_flag(
523 f"{CACHE_FLAG}:{execution.project_id}:{key}",
524 {"validationId": output.result.validation_result_id},
525 )
527 def affected_tests(
528 self,
529 change_set: ChangeSet,
530 definitions: Sequence[Any],
531 exclude: Collection[str] = (),
532 ) -> tuple[Any, list[str]] | None:
533 """The pytest validator and the affected test files, when there are any, without the
534 ``exclude`` files (the frozen acceptance tests a dispute can cover, #161)."""
535 pytest_definition = next(
536 (
537 item
538 for item in definitions
539 if item.command and "pytest" in " ".join(item.command) and item.mandatory
540 ),
541 None,
542 )
543 if pytest_definition is None:
544 return None
545 tests = affected_python_tests(
546 self.s.paths.workspace, [item.path for item in change_set.files if item.after_digest]
547 )
548 tests = [item for item in tests if item not in exclude]
549 if not tests:
550 return None
551 return pytest_definition, tests
553 def run_validators(
554 self,
555 execution: Execution,
556 change_set: ChangeSet,
557 definitions: Sequence[ValidatorDefinition],
558 prepare: Callable[[ValidatorDefinition], Callable[[], ValidatorOutput]],
559 save: Callable[[ValidatorOutput], None],
560 exclude: Collection[str] = (),
561 ) -> list[ValidatorOutput]:
562 """The profile validators of VERIFICATION. Outside the fast lane (or without
563 ``fastLane.verification``) one after the other, as before. In the fast lane: the
564 affected tests first (a failure stops the attempt; the full suite runs before the
565 gate), then the validators side by side, reusing a PASSED result of the same validator
566 for the same ChangeSet, baseline and configuration. The ``exclude`` files are left out
567 of the affected tests: the frozen acceptance tests under ``disputes: person`` run in
568 ``harness.acceptance-tests`` and the full suite, where a failure confined to them can
569 open a dispute instead of stopping the attempt first (#161)."""
570 config = self.fast_verification
571 if config is None or not self.fast(execution): 571 ↛ 572line 571 didn't jump to line 572 because the condition on line 571 was never true
572 return self._run_in_order(definitions, prepare, save)
573 outputs = (
574 self._affected_first(execution, change_set, definitions, prepare, save, exclude)
575 if config.affected_tests_first
576 else []
577 )
578 if any(item.result.status is not ResultStatus.PASSED for item in outputs):
579 # The affected tests already fail: the full suite would not change the outcome of
580 # this attempt, and it still runs before the gate.
581 return outputs
582 cache = bool(config.cache)
583 slots: list[ValidatorOutput | None] = [
584 self._reused(execution, change_set, definition) if cache else None
585 for definition in definitions
586 ]
587 pending = [(index, item) for index, item in enumerate(definitions) if slots[index] is None]
588 workers = max(1, min(len(pending), self.project.runtime.max_parallel))
589 parallel = bool(config.parallel) and workers > 1
590 self._fill(slots, pending, prepare, workers if parallel else 1)
591 ran = {index for index, _ in pending}
592 for index, definition in enumerate(definitions):
593 slot = self._saved(definition, slots[index], save)
594 if cache and index in ran:
595 self._remember(execution, change_set, definition, slot)
596 outputs.append(slot)
597 if parallel:
598 self.s.events.append(
599 execution.execution_id,
600 "verification.parallel",
601 {"validators": [item.validator_id for _, item in pending], "workers": workers},
602 )
603 return outputs
605 @staticmethod
606 def _saved(
607 definition: ValidatorDefinition,
608 slot: ValidatorOutput | None,
609 save: Callable[[ValidatorOutput], None],
610 ) -> ValidatorOutput:
611 if slot is None: # not reached: every slot was reused or run 611 ↛ 612line 611 didn't jump to line 612 because the condition on line 611 was never true
612 raise RuntimeError(f"validator {definition.validator_id} has no result")
613 save(slot)
614 return slot
616 @staticmethod
617 def _run_in_order(
618 definitions: Sequence[ValidatorDefinition],
619 prepare: Callable[[ValidatorDefinition], Callable[[], ValidatorOutput]],
620 save: Callable[[ValidatorOutput], None],
621 ) -> list[ValidatorOutput]:
622 """Every validator one after the other, as outside the fast lane."""
623 outputs = []
624 for definition in definitions:
625 output = prepare(definition)()
626 save(output)
627 outputs.append(output)
628 return outputs
630 def _affected_first(
631 self,
632 execution: Execution,
633 change_set: ChangeSet,
634 definitions: Sequence[ValidatorDefinition],
635 prepare: Callable[[ValidatorDefinition], Callable[[], ValidatorOutput]],
636 save: Callable[[ValidatorOutput], None],
637 exclude: Collection[str] = (),
638 ) -> list[ValidatorOutput]:
639 """Run the pytest validator on the affected test files only, when there are any."""
640 selection = self.affected_tests(change_set, definitions, exclude)
641 if selection is None:
642 return []
643 pytest_definition, tests = selection
644 command = (*(pytest_definition.command or ()), *tests)
645 affected = pytest_definition.model_copy(
646 update={"validator_id": AFFECTED_TESTS_ID, "command": command}
647 )
648 output = prepare(affected)()
649 save(output)
650 self.s.events.append(
651 execution.execution_id,
652 "verification.affected-tests",
653 {
654 "tests": tests,
655 "status": output.result.status.value,
656 "digest": change_set.digest,
657 },
658 )
659 return [output]
661 @staticmethod
662 def _fill(
663 slots: list[ValidatorOutput | None],
664 pending: list[tuple[int, ValidatorDefinition]],
665 prepare: Callable[[ValidatorDefinition], Callable[[], ValidatorOutput]],
666 workers: int,
667 ) -> None:
668 """Run the pending validators into their slots, side by side when ``workers`` > 1."""
669 if workers <= 1:
670 for index, definition in pending:
671 slots[index] = prepare(definition)()
672 return
673 # Contexts are prepared on this thread; only the validator commands run side by side.
674 calls = [(index, prepare(definition)) for index, definition in pending]
675 with ThreadPoolExecutor(max_workers=workers) as pool:
676 futures = [(index, pool.submit(call)) for index, call in calls]
677 for index, future in futures:
678 slots[index] = future.result()
680 def fast_verification_applies(self, execution: Execution) -> bool:
681 """Whether VERIFICATION of this run uses the fast-lane verification."""
682 return self.fast_verification is not None and self.fast(execution)
684 # ----- PLANNING: the plan-approval checkpoint (#8) -----------------------------------------
685 def plan_checkpoint(
686 self, execution: Execution, phase: PhaseExecution, task: Task, plan: Plan, plan_ref: str
687 ) -> PhaseOutcome | None:
688 mode = self.plan_approval
689 if mode == "off":
690 return None
691 digest = plan_digest(plan, task_digest(task))
692 key = f"{PLAN_APPROVAL_FLAG}:{execution.execution_id}"
693 state = self._flag(key)
694 if isinstance(state, dict) and state.get("digest") == digest:
695 status = state.get("status")
696 if status in {"APPROVED", "NOT_REQUIRED"}: 696 ↛ 698line 696 didn't jump to line 698 because the condition on line 696 was always true
697 return None
698 if status == "REJECTED":
699 return PhaseOutcome(ResultStatus.FAILED, "The plan was rejected by a person")
700 sized = self.task_size(execution, task)
701 reasons: list[str] = []
702 if mode == "always": 702 ↛ 703line 702 didn't jump to line 703 because the condition on line 702 was never true
703 reasons.append("planApproval: always")
704 if sized["size"] == "L": 704 ↛ 705line 704 didn't jump to line 705 because the condition on line 704 was never true
705 reasons.append(f"size L ({sized['rule']})")
706 if sized["riskFlags"]:
707 reasons.append(f"risk flag(s) {', '.join(sized['riskFlags'])}")
708 if reasons and mode == "risk" and self.skips(execution, "planApproval", PhaseId.PLANNING): 708 ↛ 711line 708 didn't jump to line 711 because the condition on line 708 was never true
709 # governance.riskProfile: the light profile has no plan-approval checkpoint under
710 # ``risk`` (``always`` is a person's request and still applies).
711 reasons = []
712 light = True
713 else:
714 light = False
715 if not reasons:
716 reason = (
717 "light governance profile" if light else f"size {sized['size']} and no risk flag"
718 )
719 self._set_flag(key, {"digest": digest, "status": "NOT_REQUIRED", "reason": reason})
720 self.s.events.append(
721 execution.execution_id,
722 "plan.approval.skipped",
723 {"digest": digest, "reason": reason, "size": sized["size"]},
724 phase_execution_id=phase.phase_execution_id,
725 )
726 return None
727 covering = self._covering_pre_authorization(execution, task)
728 if covering is not None:
729 self._set_flag(
730 key,
731 {
732 "digest": digest,
733 "status": "APPROVED",
734 "reasons": reasons,
735 "preAuthorizationId": covering.pre_authorization_id,
736 "actorId": covering.actor.actor_id,
737 },
738 )
739 self.s.events.append(
740 execution.execution_id,
741 "plan.approval.covered",
742 {
743 "digest": digest,
744 "reasons": reasons,
745 "preAuthorizationId": covering.pre_authorization_id,
746 "actorId": covering.actor.actor_id,
747 },
748 phase_execution_id=phase.phase_execution_id,
749 )
750 return None
751 pending = {"digest": digest, "status": "PENDING", "reasons": reasons, "planRef": plan_ref}
752 if state != pending: 752 ↛ 760line 752 didn't jump to line 760 because the condition on line 752 was always true
753 self._set_flag(key, pending)
754 self.s.events.append(
755 execution.execution_id,
756 "plan.approval.requested",
757 {"digest": digest, "reasons": reasons, "planRef": plan_ref},
758 phase_execution_id=phase.phase_execution_id,
759 )
760 return PhaseOutcome(
761 ResultStatus.BLOCKED,
762 f"The plan needs a person's approval ({'; '.join(reasons)}): harness plan decide "
763 f"--run {execution.execution_id} --decision APPROVE --digest {digest}",
764 (plan_ref,),
765 )
767 def plan_approval_state(self, execution: Execution) -> dict[str, Any] | None:
768 value = self._flag(f"{PLAN_APPROVAL_FLAG}:{execution.execution_id}")
769 return value if isinstance(value, dict) else None
771 def decide_plan(
772 self,
773 execution: Execution,
774 *,
775 decision: DecisionKind,
776 digest: str,
777 actor: Actor,
778 rationale: str,
779 ) -> dict[str, Any]:
780 """A person approves or rejects the plan waiting at the checkpoint, bound to its
781 digest."""
782 if actor.actor_type is not ActorType.HUMAN: 782 ↛ 783line 782 didn't jump to line 783 because the condition on line 782 was never true
783 raise PolicyViolationError("only a person can approve a plan")
784 require_human_actor(actor.actor_id, "approve a plan")
785 if decision not in {DecisionKind.APPROVE, DecisionKind.REJECT}: 785 ↛ 786line 785 didn't jump to line 786 because the condition on line 785 was never true
786 raise PolicyViolationError("a plan is approved or rejected")
787 state = self.plan_approval_state(execution)
788 if not state or state.get("status") != "PENDING": 788 ↛ 789line 788 didn't jump to line 789 because the condition on line 788 was never true
789 raise NotFoundError(f"run {execution.execution_id} has no plan waiting for approval")
790 if state.get("digest") != digest:
791 raise PolicyViolationError(
792 f"the digest does not match the plan waiting for approval ({state.get('digest')})"
793 )
794 status = "APPROVED" if decision is DecisionKind.APPROVE else "REJECTED"
795 record = {
796 **state,
797 "status": status,
798 "actorId": actor.actor_id,
799 "rationale": rationale.strip() or decision.value,
800 "decidedAt": utc_now().isoformat(),
801 }
802 self._set_flag(f"{PLAN_APPROVAL_FLAG}:{execution.execution_id}", record)
803 self.s.events.append(
804 execution.execution_id,
805 "plan.approval.decided",
806 {"digest": digest, "decision": decision.value, "rationale": record["rationale"]},
807 actor=actor,
808 )
809 if decision is DecisionKind.REJECT:
810 latest = self.engine.get_execution(execution.execution_id)
811 self.engine._save_execution(
812 latest.model_copy(
813 update={
814 "status": ResultStatus.FAILED,
815 "terminal_reason": "The plan was rejected by a person",
816 "updated_at": utc_now(),
817 }
818 )
819 )
820 return record
822 # ----- pre-authorised approval ---------------------------------------------------------------
823 def contract_digest(self, execution: Execution, task: Task) -> str:
824 """The operational-contract digest of the run's task revision (#55), the same summary
825 INTENT records."""
826 defaults = self.engine.ladder.intake.defaults(execution, task)
827 return derive_contract(task, task_digest(task), defaults).digest
829 def preauthorize(
830 self,
831 execution: Execution,
832 actor: Actor,
833 *,
834 hours: int | None = None,
835 rationale: str = "",
836 identity_source: str | None = None,
837 with_contract: bool = False,
838 ) -> PreAuthorization:
839 """Record a person's approval in advance for this run, bound to the contract digest
840 and the condition (gate passed, no risk factor, size S)."""
841 settings = self.pre_authorization
842 if settings is None:
843 raise PolicyViolationError(
844 "pre-authorised approval needs friction.preAuthorization.mode: allow"
845 )
846 if actor.actor_type is not ActorType.HUMAN: 846 ↛ 847line 846 didn't jump to line 847 because the condition on line 846 was never true
847 raise PolicyViolationError("only a person can pre-authorise an approval")
848 require_human_actor(actor.actor_id, "pre-authorise an approval")
849 if execution.current_phase is not PhaseId.INTENT: 849 ↛ 850line 849 didn't jump to line 850 because the condition on line 849 was never true
850 raise PolicyViolationError(
851 "an approval is pre-authorised with the operational contract, in INTENT; "
852 f"run {execution.execution_id} is in {execution.current_phase.value}"
853 )
854 chosen = hours or settings.hours
855 if chosen < 1 or chosen > settings.limit_hours: 855 ↛ 856line 855 didn't jump to line 856 because the condition on line 855 was never true
856 raise PolicyViolationError(
857 f"a pre-authorisation lasts 1 to {settings.limit_hours} hours "
858 "(friction.preAuthorization.maxHours)"
859 )
860 task = self.engine.run_task(execution)
861 digest = self.contract_digest(execution, task)
862 now = utc_now()
863 record = PreAuthorization(
864 pre_authorization_id=new_id("preauth"),
865 execution_id=execution.execution_id,
866 task_id=task.task_id,
867 actor=actor,
868 contract_digest=digest,
869 task_digest=task_digest(task),
870 rationale=rationale.strip()
871 or "Approve in advance if the gate passes, with no risk factor, at size S",
872 authorized_at=now,
873 expires_at=now + timedelta(hours=chosen),
874 identity_source=identity_source, # type: ignore[arg-type]
875 )
876 self.s.state.put(
877 "pre_authorization",
878 record.pre_authorization_id,
879 record,
880 execution_id=execution.execution_id,
881 project_id=execution.project_id,
882 )
883 ref = self.s.artifacts.put_json(
884 record.model_dump(mode="json", by_alias=True),
885 metadata={"kind": "pre-authorization", "executionId": execution.execution_id},
886 )
887 self.engine._record_evidence(
888 execution,
889 PhaseId.INTENT,
890 EvidenceKind.HUMAN_DECISION,
891 ref,
892 f"Pre-authorised approval until {record.expires_at.isoformat()} under gatePassed, "
893 "noRiskFactors and sizeS",
894 supports=(task.task_id,),
895 )
896 self.s.events.append(
897 execution.execution_id,
898 "decision.preauthorized",
899 record.model_dump(mode="json", by_alias=True),
900 actor=actor,
901 )
902 self.s.state.set_flag(
903 f"{PREAUTH_FLAG}:{execution.execution_id}", record.pre_authorization_id
904 )
905 if with_contract: 905 ↛ 918line 905 didn't jump to line 918 because the condition on line 905 was always true
906 # The person confirms the contract the pre-authorisation is bound to in the same
907 # act: one interaction (withPreAuthorization), not two.
908 self.engine.results.set_flag_json(
909 f"contractconfirmed:{execution.execution_id}",
910 {"digest": digest, "actorId": actor.actor_id, "confirmedAt": now.isoformat()},
911 )
912 self.s.events.append(
913 execution.execution_id,
914 "contract.confirmed",
915 {"digest": digest, "taskDigest": record.task_digest, "withPreAuthorization": True},
916 actor=actor,
917 )
918 return record
920 def pre_authorization_record(self, execution: Execution) -> PreAuthorization | None:
921 identifier = self.s.state.get_flag(f"{PREAUTH_FLAG}:{execution.execution_id}")
922 if not identifier:
923 return None
924 try:
925 return self.s.state.get("pre_authorization", identifier, PreAuthorization)
926 except NotFoundError:
927 return None
929 def _covering_pre_authorization(
930 self, execution: Execution, task: Task
931 ) -> PreAuthorization | None:
932 """A pre-authorisation of the run that is in force for the current contract: it may
933 cover the plan approval (the person approved the run's work in advance)."""
934 record = self.pre_authorization_record(execution)
935 if record is None or record.expires_at <= utc_now():
936 return None
937 if record.contract_digest != self.contract_digest(execution, task): 937 ↛ 938line 937 didn't jump to line 938 because the condition on line 937 was never true
938 return None
939 return record
941 def pre_authorization_failures(
942 self,
943 execution: Execution,
944 record: PreAuthorization,
945 gate: GateEvaluation,
946 change_set: ChangeSet,
947 ) -> list[str]:
948 """Why the condition of ``record`` does not hold for this ChangeSet (empty: it holds)."""
949 reasons: list[str] = []
950 if self.s.state.list("decision", HumanDecision, execution_id=execution.execution_id): 950 ↛ 951line 950 didn't jump to line 951 because the condition on line 950 was never true
951 reasons.append("a person already decided in this run")
952 if record.expires_at <= utc_now():
953 reasons.append(f"it expired at {record.expires_at.isoformat()}")
954 task = self.engine.run_task(execution)
955 if self.contract_digest(execution, task) != record.contract_digest: 955 ↛ 956line 955 didn't jump to line 956 because the condition on line 955 was never true
956 reasons.append("the operational contract changed after it was given")
957 if gate.status is not ResultStatus.PASSED: 957 ↛ 958line 957 didn't jump to line 958 because the condition on line 957 was never true
958 reasons.append(f"the automatic gate is {gate.status.value}, not PASSED")
959 if gate.change_set_digest != change_set.digest: 959 ↛ 960line 959 didn't jump to line 960 because the condition on line 959 was never true
960 reasons.append("the gate was evaluated for another ChangeSet")
961 profile = self.profile(execution, change_set)
962 if profile["riskFactors"]:
963 reasons.append(f"risk factor(s) {', '.join(profile['riskFactors'])}")
964 sized = self.task_size(execution, task)
965 if sized["size"] != "S":
966 reasons.append(f"the task is size {sized['size']} ({sized['rule']})")
967 if profile["files"] > profile["filesBound"]: 967 ↛ 968line 967 didn't jump to line 968 because the condition on line 967 was never true
968 reasons.append(f"the ChangeSet has {profile['files']} files (larger than S)")
969 if self.engine.ladder.active and self.engine.ladder.manual_items(task): 969 ↛ 970line 969 didn't jump to line 970 because the condition on line 969 was never true
970 reasons.append("manual checklist items only a person can tick")
971 if self.engine.results.active and self.engine.results.required_acknowledgements( 971 ↛ 974line 971 didn't jump to line 974 because the condition on line 971 was never true
972 execution, change_set.digest
973 ):
974 reasons.append("risk factors a person must acknowledge")
975 return reasons
977 def apply_pre_authorization(
978 self, execution: Execution, gate: GateEvaluation, change_set: ChangeSet
979 ) -> HumanDecision | None:
980 """At DECISION: the approval the person gave in advance, recorded on their behalf when
981 its condition holds; ``None`` (the person is asked as usual) otherwise."""
982 record = self.pre_authorization_record(execution)
983 if record is None or self.s.state.get_flag(f"{PREAUTH_USED_FLAG}:{execution.execution_id}"):
984 return None
985 reasons = self.pre_authorization_failures(execution, record, gate, change_set)
986 if reasons:
987 key = f"preauthrefused:{execution.execution_id}:{change_set.digest}"
988 if not self.s.state.get_flag(key): 988 ↛ 999line 988 didn't jump to line 999 because the condition on line 988 was always true
989 self.s.state.set_flag(key, "1")
990 self.s.events.append(
991 execution.execution_id,
992 "decision.preauthorization.not-applied",
993 {
994 "preAuthorizationId": record.pre_authorization_id,
995 "digest": change_set.digest,
996 "reasons": reasons,
997 },
998 )
999 return None
1000 try:
1001 contract = self.engine._current_contract_digest(execution)
1002 except PolicyViolationError:
1003 return None
1004 decided_at = utc_now()
1005 expiry = self.project.governance_settings.decision_expiry_hours
1006 decision = HumanDecision(
1007 decision_id=new_id("decision"),
1008 execution_id=execution.execution_id,
1009 gate_evaluation_id=gate.gate_evaluation_id,
1010 actor=record.actor,
1011 decision=DecisionKind.APPROVE,
1012 rationale=(
1013 f"Pre-authorised approval {record.pre_authorization_id} given at "
1014 f"{record.authorized_at.isoformat()}: the gate passed, no risk factor, size S. "
1015 f"{record.rationale}"
1016 ),
1017 change_set_digest=change_set.digest,
1018 configuration_digest=execution.configuration_digest,
1019 policy_digest=execution.policy_digest,
1020 acceptance_contract_digest=contract,
1021 identity_source=record.identity_source,
1022 decided_at=decided_at,
1023 expires_at=decided_at + timedelta(hours=expiry) if expiry else None,
1024 pre_authorization_id=record.pre_authorization_id,
1025 )
1026 self.s.state.put(
1027 "decision",
1028 decision.decision_id,
1029 decision,
1030 execution_id=execution.execution_id,
1031 project_id=execution.project_id,
1032 )
1033 # The harness writes the record; the decision is the person's, given in advance (the
1034 # event of that act, decision.preauthorized, carries their actor).
1035 self.s.events.append(
1036 execution.execution_id,
1037 "human.decision.recorded",
1038 decision.model_dump(mode="json"),
1039 actor=HARNESS_ACTOR,
1040 )
1041 self.s.events.append(
1042 execution.execution_id,
1043 "decision.preauthorization.applied",
1044 {
1045 "preAuthorizationId": record.pre_authorization_id,
1046 "decisionId": decision.decision_id,
1047 "digest": change_set.digest,
1048 "actorId": record.actor.actor_id,
1049 },
1050 )
1051 self.s.state.set_flag(f"{PREAUTH_USED_FLAG}:{execution.execution_id}", decision.decision_id)
1052 if self.engine.ladder.active: 1052 ↛ 1053line 1052 didn't jump to line 1053 because the condition on line 1052 was never true
1053 self.engine.ladder.after_decision(execution, decision)
1054 latest = self.engine.get_execution(execution.execution_id)
1055 self.engine._save_execution(
1056 latest.model_copy(
1057 update={"human_decision_id": decision.decision_id, "updated_at": utc_now()}
1058 )
1059 )
1060 return decision
1062 # ----- reports ------------------------------------------------------------------------------
1063 def brief(self, execution: Execution) -> dict[str, Any] | None:
1064 """What the decision brief shows: the lane, the change type and the pre-authorisation."""
1065 if not self.active:
1066 return None
1067 lane = self.lane(execution)
1068 record = self.pre_authorization_record(execution)
1069 profile: dict[str, Any] | None = None
1070 if execution.change_set_digest: 1070 ↛ 1075line 1070 didn't jump to line 1075 because the condition on line 1070 was always true
1071 known = self._flag(
1072 f"{PROFILE_FLAG}:{execution.execution_id}:{execution.change_set_digest}"
1073 )
1074 profile = known if isinstance(known, dict) else None
1075 return {
1076 "lane": {
1077 key: lane.get(key)
1078 for key in ("lane", "size", "rule", "reasons", "skip", "escalated")
1079 }
1080 | {"escalationReasons": lane.get("escalationReasons") or []}
1081 if lane
1082 else None,
1083 "changeType": profile.get("changeType") if profile else None,
1084 "riskFactors": profile.get("riskFactors") if profile else None,
1085 "preAuthorization": {
1086 "preAuthorizationId": record.pre_authorization_id,
1087 "actorId": record.actor.actor_id,
1088 "expiresAt": record.expires_at.isoformat(),
1089 "contractDigest": record.contract_digest,
1090 "applied": bool(
1091 self.s.state.get_flag(f"{PREAUTH_USED_FLAG}:{execution.execution_id}")
1092 ),
1093 }
1094 if record
1095 else None,
1096 "planApproval": self.plan_approval_state(execution),
1097 }
1100__all__ = ["AFFECTED_TESTS_ID", "Friction"]