quality-harness 0.5.0__tar.gz

quality_harness-0.5.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.whl
+*.tar.gz
+
+# Go
+/sdks/go/bin/
+
+# TypeScript
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+sdks/python/.venv/
+
+# DevOps plugin
+.devops/
+
+# Runtime artifacts (agent tier)
+runtime/
+runs/
+
+# devloop
+.devloop/
+.worktrees/

quality_harness-0.5.0/AGENTS.md

@@ -0,0 +1,45 @@
+# Python SDKs
+
+## 项目定位与边界
+
+一个 uv workspace 管理 `quality-harness`、`harness-common` 与 `harness-toolbox` 三个独立分发包。
+领域 SDK 依赖 common/toolbox；toolbox 依赖 common，common 不反向依赖 toolbox。每个包只打包自己的命名空间。
+
+## 代码地图与核心模块
+
+```text
+python/
+├── e2e_harness/        # 服务 API 契约测试
+├── eval_harness/       # Agent 效果评测与对照实验
+├── perf_harness/       # 性能、容量与资源画像
+├── trace_harness/      # 调用链分析
+├── trajectory_harness/ # Agent 决策与行动序列评估
+├── common/            # 独立 harness-common：system/access/execution 契约与 report_kit
+├── toolbox/           # 独立 harness-toolbox：协议客户端、LLM、Transport 与平台适配
+├── pyproject.toml     # 包、依赖、CLI 与测试发现
+└── Makefile           # 测试、lint、格式化、构建与版本入口
+```
+
+## 关键约定
+
+- 五个领域 SDK 互不 import；公共能力集中在中立共享包。`harness_common` 统一执行事实与输出契约，各 SDK 自行拥有 runner、scheduler 和协议原语。
+- 环境共享层只管理 EnvironmentFixture 与外层执行，Case / Trial 准备清理由各 Harness 拥有；见 [环境生命周期](../../docs/environment.md)。
+- 测试贴近所属包，放在各包 `tests/`；默认 pytest 覆盖完整工程，发行包排除测试。
+- 领域可选依赖通过 extras 声明，避免给其它 SDK 增加安装负担。
+- Python 包版本使用本目录 `make bump`，同步 `pyproject.toml` 与 `uv.lock`；仓库整体版本按根目录约定独立更新。
+
+## 开发与测试
+
+从本目录运行：
+
+```bash
+uv sync --locked
+make fix
+make lint
+uv run pytest -q
+make build
+```
+
+局部验证使用 `make test TEST_FILES=<package>/tests`；toolbox 路径为 `toolbox/harness_toolbox/tests`。
+局部格式化使用 `make fix CHECK_PATHS=toolbox/harness_toolbox`，完整门禁仍运行 `make lint`。`make fix` 会修改源码，完成后再运行 lint 和测试。
+构建产物写入仓库根目录 `dist/`。领域 smoke 命令与 fixture 使用方式归对应 Harness。

quality_harness-0.5.0/Makefile

@@ -0,0 +1,31 @@
+CHECK_PATHS ?= $(if $(filter %.py,$(LINT_FILES)),$(filter %.py,$(LINT_FILES)),common/harness_common/ toolbox/harness_toolbox/ e2e_harness/ eval_harness/ perf_harness/ trace_harness/ trajectory_harness/)
+
+FIX_PATHS ?= $(CHECK_PATHS)
+
+.PHONY: test lint fix build clean bump
+
+test:
+	uv run pytest -v $(TEST_FILES)
+
+lint:
+	uv run ruff check $(CHECK_PATHS)
+
+fix:
+	uv run ruff check --fix $(FIX_PATHS)
+	uv run ruff format $(FIX_PATHS)
+
+build:
+	uv build --all-packages --out-dir ../../dist
+
+clean:
+	rm -rf dist build *.egg-info
+
+bump:
+	@current=$$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)"/\1/'); \
+	major=$$(echo $$current | cut -d. -f1); \
+	minor=$$(echo $$current | cut -d. -f2); \
+	patch=$$(echo $$current | cut -d. -f3); \
+	next="$$major.$$minor.$$((patch + 1))"; \
+	sed -i '' "s/^version = \"$$current\"/version = \"$$next\"/" pyproject.toml; \
+	uv lock; \
+	echo "bumped $$current → $$next"

quality_harness-0.5.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: quality-harness
+Version: 0.5.0
+Summary: Quality testing and evidence analysis SDKs for software and agents
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: atif<1.8,>=1.7
+Requires-Dist: harness-common<0.7,>=0.6.0
+Requires-Dist: harness-toolbox[http,llm,prometheus]<0.7,>=0.6.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pytest>=8.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: spec-case[model]>=0.2.1
+Provides-Extra: dev
+Requires-Dist: kubernetes-asyncio<37,>=36.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Provides-Extra: kube
+Requires-Dist: harness-toolbox[kube]<0.7,>=0.6.0; extra == 'kube'
+Provides-Extra: trace-corpus
+Requires-Dist: pyarrow<22,>=14; extra == 'trace-corpus'

quality_harness-0.5.0/build.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+exec uv build --out-dir ../../dist

quality_harness-0.5.0/common/AGENTS.md

@@ -0,0 +1,20 @@
+# Python 共享内核
+
+`harness-common` 提供系统描述、访问契约和执行证据，不依赖 toolbox、领域 SDK 或第三方运行库。
+具体 HTTP、LLM、数据库与平台访问属于 toolbox；领域 Harness 拥有调度和判据。
+
+```text
+harness_common/
+├── system/       # Repository/Component/Product、Service/Environment、资源、部署契约
+├── access/       # Client/DataSource、EnvironmentContext 与环境 Fixture 生命周期
+├── execution/    # Experiment/Execution/Operation、Outcome/Artifact、Reducer/Verdict 与 run 布局
+├── report_kit/   # 中立报告结构和 HTML 渲染，独立于执行生命周期
+├── identity.py  # 身份协议
+├── __init__.py  # 稳定包根导出
+└── tests/       # 跨模块契约与 conformance 测试
+```
+
+`system` 描述目标，`access` 获取事实，`execution` 组织与解释证据。它们是包内职责分组，
+不是独立分发包；跨组引用必须指向具体模块，避免依赖包根聚合导出造成循环。
+包根保持既有符号和类型身份；深层导入迁移见 [0.6 升级说明](README.md)。
+从 `sdks/python` 运行 `make fix`、`make lint`、`make test` 和 `make build`。

quality_harness-0.5.0/common/README.md

@@ -0,0 +1,34 @@
+# Harness Common for Python
+
+Standard-library contracts shared by the quality SDKs. Import public models and lifecycle
+contracts from `harness_common`; concrete protocol clients live in `harness_toolbox`.
+
+## Upgrade to 0.6
+
+Package-root exports such as `from harness_common import Service, ClientManager, Execution`
+retain their identity and behavior. Internal modules are now grouped by responsibility:
+
+| Previous module under `harness_common` | New module |
+| --- | --- |
+| `repository`, `component`, `product`, `forge`, `service`, `environment`, `host`, `workload`, `resource`, `deployment` | `system.<module>` |
+| `client`, `datasource`, `context`, `fixture` | `access.<module>` |
+| `artifact`, `experiment`, `operation`, `outcome`, `overlay`, `reducer`, `run`, `verdict` | `execution.<module>` |
+| `execution` | `execution.execution` (`from harness_common.execution import Execution` also remains valid) |
+| `llm` | `harness_toolbox.llm` |
+
+`identity` and `report_kit` keep their existing paths. Replace old deep imports; no flat
+compatibility modules are shipped. For example:
+
+```python
+from harness_common.execution.verdict import RunVerdict
+from harness_common.execution.run import run_dir_for
+```
+
+Install `harness-toolbox[llm]>=0.6,<0.7` for `LLMClient`, `LLMConfig` and `ChatResult`.
+The old `harness-common[llm]` extra is removed. The LLM re-exports from `eval_harness`
+and the `eval_harness.llm` compatibility package are removed; import directly from
+`harness_toolbox.llm`. Client request, timeout and retry behavior is unchanged.
+
+Upgrade `harness-common` and `harness-toolbox` together to 0.6; `quality-harness>=0.5.0`
+selects this compatible pair and the LLM extra. Publish common before toolbox, then
+quality-harness, so every dependency is available when a downstream package is installed.

quality_harness-0.5.0/common/harness_common/__init__.py

@@ -0,0 +1,75 @@
+"""common — harness-neutral shared code and runtime identities.
+
+The harnesses (e2e / eval / perf / trace / trajectory) depend on this package but never on each
+other; only genuinely neutral code lives here (no harness domain concept leaks in).
+
+The canonical case model — `Case` / `CaseSet` / `FacetSchema` and the `Face` / `FACES`
+judgment-face enum — lives upstream in `spec_case.model` / `spec_case.facets`
+(the spec-case package, `[model]` extra): the case format is the asset layer's contract,
+and this repo is one of its runners. Import those names from `spec_case` directly.
+
+`Forge` and `Repository` identify where source lives; `Product` names a business product;
+`Component` identifies a buildable unit within a Repository. `Environment` identifies where
+execution happens. `Service` identifies a Component's runtime presence in one Environment.
+`Workload` locates a declared runtime carrier; a Service can reference multiple workloads.
+`Operation` identifies a capability exposed by a Service; `HttpOperation` adds its HTTP
+transport contract. An `Execution` groups domain-defined work such as an e2e CaseRun or
+a perf Trial; each `OperationRun` owns one raw `Outcome`. Domain engines own scheduling
+details. A domain `Reducer` projects the recorded Outcomes into one or more
+`Artifact` objects without calling the tested Service again. `Deployment` records an
+attempt applied through a `Deployer`.
+`Experiment` names reproducible verification intent; `ExperimentRun` records one execution
+and references its `Artifact` outputs.
+"""
+
+from __future__ import annotations
+
+from harness_common.execution.artifact import Artifact as Artifact
+from harness_common.system.component import Component as Component
+from harness_common.system.deployment import Deployer as Deployer
+from harness_common.system.deployment import Deployment as Deployment
+from harness_common.system.environment import Environment as Environment
+from harness_common.system.environment import HostEnvironment as HostEnvironment
+from harness_common.system.host import Host as Host
+from harness_common.system.environment import EnvironmentFacts as EnvironmentFacts
+from harness_common.system.environment import EnvironmentSnapshot as EnvironmentSnapshot
+from harness_common.execution.execution import Execution as Execution
+from harness_common.execution.experiment import Experiment as Experiment
+from harness_common.execution.experiment import ExperimentRun as ExperimentRun
+from harness_common.system.forge import Forge as Forge
+from harness_common.identity import Identity as Identity
+from harness_common.execution.operation import HttpOperation as HttpOperation
+from harness_common.execution.operation import Operation as Operation
+from harness_common.execution.operation import OperationRun as OperationRun
+from harness_common.execution.outcome import Outcome as Outcome
+from harness_common.system.product import Product as Product
+from harness_common.system.repository import Repository as Repository
+from harness_common.execution.reducer import Reducer as Reducer
+from harness_common.system.service import Service as Service
+from harness_common.system.workload import KubernetesWorkload as KubernetesWorkload
+from harness_common.system.workload import Workload as Workload
+from harness_common.system.workload import WorkloadInstance as WorkloadInstance
+from harness_common.system.workload import (
+    KubernetesWorkloadInstance as KubernetesWorkloadInstance,
+)
+
+from harness_common.access.client import Client as Client
+from harness_common.access.client import ClientManager as ClientManager
+from harness_common.access.client import ClientProvider as ClientProvider
+from harness_common.access.datasource import DataSource as DataSource
+from harness_common.access.datasource import ServiceDataSource as ServiceDataSource
+from harness_common.access.client import client_key as client_key
+from harness_common.access.fixture import EnvironmentFixture as EnvironmentFixture
+from harness_common.access.context import EnvironmentContext as EnvironmentContext
+from harness_common.access.fixture import FixtureContext as FixtureContext
+from harness_common.access.fixture import EnvironmentBudgets as EnvironmentBudgets
+from harness_common.access.fixture import EnvironmentRun as EnvironmentRun
+from harness_common.access.fixture import run_environment as run_environment
+
+from harness_common.system.resource import Resource as Resource
+from harness_common.system.resource import ServiceResource as ServiceResource
+from harness_common.system.resource import ResourceInstanceRef as ResourceInstanceRef
+from harness_common.system.resource import ResourceInstance as ResourceInstance
+from harness_common.system.resource import ResourceMeasurement as ResourceMeasurement
+from harness_common.system.resource import ResourceCoverage as ResourceCoverage
+from harness_common.system.resource import ResourceSnapshot as ResourceSnapshot

quality_harness-0.5.0/common/harness_common/access/__init__.py

@@ -0,0 +1 @@
+"""Access contracts shared across harnesses."""

quality_harness-0.5.0/common/harness_common/access/client.py

@@ -0,0 +1,127 @@
+"""Execution-scoped, asynchronous client ownership.
+
+ClientProvider keys describe configuration, not object identity. Consumers receive a
+_ClientBorrower; only the root execution owns and disposes the ClientManager.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from typing import Protocol, TypeVar, cast
+
+
+class Client(Protocol):
+    async def initialize(self) -> None: ...
+    async def dispose(self) -> None: ...
+
+
+C = TypeVar("C", bound=Client, covariant=True)
+
+
+class ClientProvider(Protocol[C]):
+    """Keyed client construction, independent of data or environment semantics.
+
+    @spec Both environment and data clients share lifecycle ownership.
+    @rule client_key covers implementation, target, credentials and capacity policy.
+    Construction is pure; initialize owns I/O, and the root owns disposal.
+    """
+
+    @property
+    def client_key(self) -> str: ...
+    def create_client(self, clients: _ClientBorrower) -> C: ...
+
+
+class _ClientBorrower(Protocol):
+    async def get(self, provider: ClientProvider[C]) -> C: ...
+
+
+def client_key(protocol: str, configuration: object) -> str:
+    """Hash JSON-compatible configuration, including credentials, without exposing it."""
+    canonical = json.dumps(
+        configuration, sort_keys=True, separators=(",", ":"), allow_nan=False
+    )
+    return protocol + ":" + hashlib.sha256(canonical.encode()).hexdigest()
+
+
+class ClientManager:
+    """Share initialized clients within one event loop and close them at root exit.
+
+    Initialize dependencies through the supplied borrower before publishing a
+    client as ready. Reverse readiness order then closes consumers first.
+    Join all command work before leaving the root context: borrowed clients are
+    invalid after disposal. Managers cannot be reopened or shared across loops.
+    """
+
+    def __init__(self) -> None:
+        self._pending: dict[str, asyncio.Task[Client]] = {}
+        self._ready: list[Client] = []
+        self._disposal: asyncio.Task[None] | None = None
+        self._cleanup_errors: list[BaseException] = []
+        self._unclean: set[str] = set()
+
+    async def get(self, provider: ClientProvider[C]) -> C:
+        if self._disposal is not None:
+            raise RuntimeError("client manager is disposed")
+        key = provider.client_key
+        task = self._pending.get(key)
+        if task is None:
+            # Store before the task can run; factories can themselves request dependencies.
+            task = asyncio.create_task(self._initialize(provider))
+            self._pending[key] = task
+            task.add_done_callback(lambda done: self._settled(key, done))
+        # A cancelled consumer must not cancel initialization needed by other consumers.
+        return cast(C, await asyncio.shield(task))
+
+    def _settled(self, key: str, task: asyncio.Task[Client]) -> None:
+        failed = task.cancelled() or task.exception() is not None
+        if failed and key not in self._unclean and self._pending.get(key) is task:
+            del self._pending[key]
+
+    async def _initialize(self, provider: ClientProvider[Client]) -> Client:
+        client = provider.create_client(self)
+        try:
+            await client.initialize()
+            self._ready.append(client)
+            return client
+        except BaseException as error:
+            try:
+                await client.dispose()
+            except BaseException as cleanup:
+                self._cleanup_errors.append(cleanup)
+                self._unclean.add(provider.client_key)
+                raise BaseExceptionGroup(
+                    "client initialization and cleanup failed", [error, cleanup]
+                ) from None
+            raise
+
+    async def dispose(self) -> None:
+        """Idempotent, concurrent-safe cleanup; cancellation of a waiter cannot stop it."""
+        if self._disposal is None:
+            self._disposal = asyncio.create_task(self._dispose())
+        await asyncio.shield(self._disposal)
+
+    async def _dispose(self) -> None:
+        pending = list(self._pending.values())
+        for task in pending:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*pending, return_exceptions=True)
+        self._pending.clear()
+        for client in reversed(self._ready):
+            try:
+                await client.dispose()
+            except BaseException as error:
+                self._cleanup_errors.append(error)
+        self._ready.clear()
+        if self._cleanup_errors:
+            raise BaseExceptionGroup("client cleanup failed", self._cleanup_errors)
+
+    async def __aenter__(self) -> ClientManager:
+        if self._disposal is not None:
+            raise RuntimeError("client manager is disposed")
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.dispose()

quality_harness-0.5.0/common/harness_common/access/context.py

@@ -0,0 +1,29 @@
+"""Execution-scoped environment access, independent of fixture orchestration."""
+
+import time
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from harness_common.access.client import _ClientBorrower
+from harness_common.system.environment import Environment
+
+
+E = TypeVar("E", bound=Environment)
+
+
+@dataclass(frozen=True)
+class EnvironmentContext(Generic[E]):
+    """Bind an environment, borrowed clients and a monotonic deadline in seconds.
+
+    @spec Deployment, tests and diagnosis can use this context without a fixture.
+    @rule It neither opens connections nor owns disposal or automatic cancellation.
+    Callers propagate remaining_s into operations and join work before root exit.
+    """
+
+    environment: E
+    clients: _ClientBorrower
+    deadline: float
+
+    @property
+    def remaining_s(self) -> float:
+        return max(0.0, self.deadline - time.monotonic())

quality_harness-0.5.0/common/harness_common/access/datasource.py

@@ -0,0 +1,25 @@
+"""Data access associations built on the neutral client provider contract."""
+
+from dataclasses import dataclass
+from typing import Generic, Protocol
+
+from harness_common.access.client import C, ClientProvider
+from harness_common.system.service import Service
+
+
+class DataSource(ClientProvider[C], Protocol[C]):
+    """A source of data; lifecycle and reuse follow ClientProvider.
+
+    Accessible environment providers need not be described as data sources.
+    """
+
+    # Safe discovery metadata, not credentials or part of client_key.
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class ServiceDataSource(Generic[C]):
+    """Associate business ownership without changing client identity or lifetime."""
+
+    service: Service
+    source: DataSource[C]

quality_harness-0.5.0/common/harness_common/access/fixture.py

@@ -0,0 +1,198 @@
+"""Environment lifetime around a domain-owned execution (no Case abstraction)."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Generic, Protocol, TypeVar
+
+from harness_common.access.client import ClientManager
+from harness_common.access.context import EnvironmentContext
+from harness_common.system.environment import Environment, EnvironmentSnapshot
+
+S = TypeVar("S")
+S_contra = TypeVar("S_contra", contravariant=True)
+R = TypeVar("R")
+
+
+@dataclass(frozen=True)
+class FixtureContext(EnvironmentContext):
+    """Fixture phase information extends the neutral environment context."""
+
+    phase: str
+
+
+class EnvironmentFixture(Protocol[S_contra]):
+    """Project-owned shared resources; retain partial handles in preallocated state.
+
+    Cleanup must tolerate incomplete preparation. Borrowed clients remain valid
+    until cleanup returns; only their manager owns final disposal.
+    """
+
+    async def prepare(self, ctx: FixtureContext, state: S_contra) -> None: ...
+    async def cleanup(self, ctx: FixtureContext, state: S_contra) -> None: ...
+
+
+@dataclass(frozen=True)
+class EnvironmentBudgets:
+    prepare_s: float
+    run_s: float
+    cleanup_s: float
+    dispose_s: float
+
+
+@dataclass(frozen=True)
+class EnvironmentPhase:
+    name: str
+    duration_ms: int
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class EnvironmentObservation:
+    phase: str
+    snapshot: EnvironmentSnapshot
+
+
+@dataclass
+class EnvironmentRun(Generic[R]):
+    """Outer health and evidence; the domain result retains its own verdicts."""
+
+    result: R | None = None
+    phases: list[EnvironmentPhase] = field(default_factory=list)
+    observations: list[EnvironmentObservation] = field(default_factory=list)
+
+    @property
+    def healthy(self) -> bool:
+        return all(phase.error is None for phase in self.phases)
+
+
+async def run_environment(
+    environment: Environment,
+    state: S,
+    fixture: EnvironmentFixture[S],
+    run: Callable[[EnvironmentContext, S], Awaitable[R]],
+    *,
+    budgets: EnvironmentBudgets,
+    observe: Callable[[S], EnvironmentSnapshot] | None = None,
+    required: dict[str, str] | None = None,
+) -> EnvironmentRun[R]:
+    """Prepare → domain (including case cleanup) → environment cleanup → dispose.
+
+    Exceptions become outer phase errors without inventing a domain result.
+    Cancellation propagates after bounded teardown. Async callbacks must cooperate
+    with cancellation and finish their own child work before returning.
+    Disposal has a cooperative deadline: native cleanup is joined even on overrun.
+    ``observe`` is a synchronous view of facts already collected by the project.
+    """
+    if any(
+        value <= 0
+        for value in (
+            budgets.prepare_s,
+            budgets.run_s,
+            budgets.cleanup_s,
+            budgets.dispose_s,
+        )
+    ):
+        raise ValueError("environment phases require positive budgets")
+    if required and observe is None:
+        raise ValueError("required facts need an observe callback")
+    clients = ClientManager()
+    execution: EnvironmentRun[R] = EnvironmentRun()
+
+    def capture(phase: str) -> EnvironmentSnapshot | None:
+        if observe is None:
+            return None
+        snapshot = deepcopy(observe(state))
+        execution.observations.append(EnvironmentObservation(phase, snapshot))
+        return snapshot
+
+    async def phase(
+        name: str,
+        budget: float,
+        callback: Callable[[FixtureContext], Awaitable[None]],
+        *,
+        cooperative: bool = False,
+    ) -> bool:
+        started = time.monotonic()
+        error = None
+        try:
+            ctx = FixtureContext(
+                environment, clients, deadline=started + budget, phase=name
+            )
+            if cooperative:
+                await callback(ctx)
+                if ctx.remaining_s <= 0:
+                    raise TimeoutError(f"{name} exceeded its time budget")
+            else:
+                async with asyncio.timeout(budget):
+                    await callback(ctx)
+        except Exception as exc:
+            error = f"{type(exc).__name__}: {exc}"
+        finally:
+            execution.phases.append(
+                EnvironmentPhase(name, int((time.monotonic() - started) * 1000), error)
+            )
+        return error is None
+
+    async def prepare(ctx: FixtureContext) -> None:
+        try:
+            await fixture.prepare(ctx, state)
+        finally:
+            # Capture partial preparation too, before any teardown can rewrite it.
+            snapshot = capture("prepare")
+        if snapshot is not None:
+            if (snapshot.name, snapshot.kind) != (environment.name, environment.kind):
+                raise ValueError("snapshot conflicts with selected environment")
+            if required and (
+                not snapshot.target.source or not snapshot.target.observed_at
+            ):
+                raise ValueError("required target facts need source and observed_at")
+            for key, expected in (required or {}).items():
+                if snapshot.target.values.get(key) != expected:
+                    raise ValueError(
+                        f"environment condition {key}: observed {snapshot.target.values.get(key)!r}, required {expected!r}"
+                    )
+
+    async def execute(ctx: EnvironmentContext) -> None:
+        execution.result = await run(ctx, state)
+
+    async def cleanup(ctx: FixtureContext) -> None:
+        try:
+            await fixture.cleanup(ctx, state)
+        finally:
+            capture("cleanup")
+
+    async def teardown() -> None:
+        try:
+            await phase("cleanup", budgets.cleanup_s, cleanup)
+        finally:
+            # ClientManager shields native disposal. Join it before returning;
+            # report overruns instead of leaking disposal into the next execution.
+            await phase(
+                "dispose",
+                budgets.dispose_s,
+                lambda ctx: clients.dispose(),
+                cooperative=True,
+            )
+
+    try:
+        if await phase("prepare", budgets.prepare_s, prepare):
+            await phase("run", budgets.run_s, execute)
+    finally:
+        # Teardown owns a separate task so cancellation of the run cannot skip
+        # cleanup or invalidate borrowed clients while cleanup still uses them.
+        task = asyncio.create_task(teardown())
+        interrupted = False
+        while not task.done():
+            try:
+                await asyncio.shield(task)
+            except asyncio.CancelledError:
+                interrupted = True
+        task.result()
+        if interrupted:
+            raise asyncio.CancelledError
+    return execution

quality_harness-0.5.0/common/harness_common/execution/__init__.py

@@ -0,0 +1,3 @@
+"""Execution facts and evidence interpretation; scheduling remains domain-owned."""
+
+from harness_common.execution.execution import Execution as Execution