Coverage for src/governed_harness/orchestration/engine_types.py: 100%
88 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"""Types and constants the engine shares with its helpers (#69): its paths and services, the
2outcome of a phase step, of a read-only agent call and of the independent review, and the
3effective testing strategy.
5They live apart from ``engine``, ``agent_results``, ``agent_review`` and ``engineering`` so that
6the helpers can build a ``PhaseOutcome`` and type what they share without importing their owner
7or a sibling: an import back into the owner closed a module cycle. The modules that defined them
8re-export them."""
10from __future__ import annotations
12from dataclasses import dataclass
13from pathlib import Path
14from typing import Any
16from governed_harness.agents.environment import secret_values
17from governed_harness.configuration.models import ResolvedConfiguration
18from governed_harness.domain.enums import ResultStatus
19from governed_harness.domain.models import Finding
20from governed_harness.events import SQLiteEventStore
21from governed_harness.evidence import LocalArtifactStore, SecretRedactor
22from governed_harness.runtime.state_location import resolve_state_location
23from governed_harness.storage import SQLiteStateStore
25TASK_REVISION_DIGEST_FLAG = "taskrevdigest:"
26"""State flag prefix (+ execution id) of the digest of the task revision pinned to a run."""
29@dataclass(frozen=True)
30class EnginePaths:
31 workspace: Path
32 harness_dir: Path
33 database: Path
34 artifact_dir: Path
35 state_root: Path | None = None
36 """The run registry outside the workspace (``runtime.stateDir`` or an isolated run's
37 origin, #55); ``None`` when the state lives in ``.harness/`` as in 1.0.0."""
39 @classmethod
40 def from_workspace(cls, workspace: Path) -> EnginePaths:
41 root = workspace.resolve(strict=True)
42 harness_dir = root / ".harness"
43 harness_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
44 return cls(root, harness_dir, harness_dir / "state.db", harness_dir / "artifacts")
46 @classmethod
47 def for_project(cls, resolved: ResolvedConfiguration) -> EnginePaths:
48 """The paths of a resolved project: ``.harness/`` for the workspace's own files and the
49 state location ``runtime.stateDir`` (or an isolation marker) names for the registry."""
50 paths = cls.from_workspace(resolved.workspace_root)
51 location = resolve_state_location(
52 paths.workspace, resolved.project.project_id, resolved.project.runtime.state_dir
53 )
54 if not location.external:
55 return paths
56 return cls(
57 paths.workspace,
58 paths.harness_dir,
59 location.database,
60 location.artifacts,
61 location.root,
62 )
65@dataclass
66class EngineServices:
67 resolved: ResolvedConfiguration
68 paths: EnginePaths
69 state: SQLiteStateStore
70 events: SQLiteEventStore
71 artifacts: LocalArtifactStore
73 @classmethod
74 def open(cls, resolved: ResolvedConfiguration) -> EngineServices:
75 paths = EnginePaths.for_project(resolved)
76 return cls(
77 resolved=resolved,
78 paths=paths,
79 state=SQLiteStateStore(paths.database),
80 events=SQLiteEventStore(paths.database),
81 artifacts=LocalArtifactStore(
82 paths.artifact_dir,
83 SecretRedactor(
84 literals=secret_values(resolved.project),
85 extended=bool(resolved.project.runtime.extended_redaction),
86 ),
87 ),
88 )
90 def pin_task_revision(self, execution_id: str, uri: str, digest: str) -> None:
91 """Pin the stored task revision ``uri`` to a run (``governance.pinTaskRevision``) with
92 the digest of the task as it was given: when the stored revision is redacted (#178),
93 the run works on the stored task only while it still has that digest."""
94 self.state.set_flag(f"taskrev:{execution_id}", uri)
95 self.state.set_flag(f"{TASK_REVISION_DIGEST_FLAG}{execution_id}", digest)
97 def close(self) -> None:
98 self.state.close()
99 self.events.close()
102@dataclass(frozen=True)
103class PhaseOutcome:
104 status: ResultStatus
105 summary: str
106 evidence_refs: tuple[str, ...] = ()
107 artifact_refs: tuple[str, ...] = ()
110READ_ONLY_RULE = "agent.read-only-violation"
111"""Rule id of the finding recorded when a read-only agent call changed the workspace."""
114@dataclass(frozen=True)
115class AgentCallOutcome:
116 """What a read-only agent call returned: its status, the structured result when it passed
117 and the evidence it left."""
119 status: ResultStatus
120 summary: str
121 result: dict[str, Any] | None
122 invocation_id: str | None
123 evidence_refs: tuple[str, ...]
124 protocol_error: str | None = None
125 """Since #80: why the answer broke the provider protocol (no JSON, no ``result``)."""
126 workspace_violation: str | None = None
127 """Since #92: the call changed the workspace (undone, ``agent.read-only-violation``) and its
128 answer was discarded; under ``runtime.contractRetry`` the call is sent once more."""
131@dataclass(frozen=True)
132class ReviewOutcome:
133 """Whether the independent review ran and the findings of it that block."""
135 ran: bool
136 blocking: tuple[Finding, ...] = ()
139@dataclass(frozen=True)
140class Strategy:
141 """The effective testing strategy and where it came from."""
143 name: str
144 """``tdd``, ``bdd``, ``conventional`` or ``unknown`` (the ``testing.strategy`` value)."""
145 source: str
146 """``configuration``, ``project-setup`` (a person's answer), ``detected`` or ``unknown``."""
147 frameworks: tuple[str, ...] = ()
149 @property
150 def strategy(self) -> str:
151 """The strategy's name, as the callers and the ``strategy`` key of ``as_dict`` read it."""
152 return self.name
154 def as_dict(self) -> dict[str, Any]:
155 return {
156 "strategy": self.name,
157 "source": self.source,
158 "frameworks": list(self.frameworks),
159 }
162__all__ = [
163 "READ_ONLY_RULE",
164 "TASK_REVISION_DIGEST_FLAG",
165 "AgentCallOutcome",
166 "EnginePaths",
167 "EngineServices",
168 "PhaseOutcome",
169 "ReviewOutcome",
170 "Strategy",
171]