feat(verification): discriminated-union spec + deadline runner + typed result (Phase 2A/2B)

[pradeepvrd]

Summary

Phase 2A + 2B of the verification redesign (PR #6 rework). Lands the
type-safe spec, typed result, and single-deadline runner; ships the JSON
Schema / validate_spec authoring contract and a regression test that pins
the real optimize-scale literal.

Phase 2A — engine

• verification/spec.py: hand-maintained Annotated[Union, Field(discriminator=\"type\")] of PodHealthyVerifier | ScalingCompleteVerifier | SequenceSpec | ParallelSpec. name is metadata, recursion is checks: list[VerificationNode]. Bare list/dict roots are rejected; a bare leaf is a valid whole spec. Structured so a Wave 2 registry-driven parse_node can swap only the parsing without reshaping the runner's isinstance dispatch.
• verification/base.py: pydantic VerificationResult with success, elapsed_time, reason, optional name, children (compound), raw (leaf). The legacy loose details is gone.
• verification/runner.py: VerifierAgent.wait_for_condition(spec, timeout_sec=120) (public signature preserved) computes one time.monotonic() deadline at entry. Parallel children each see the full remaining deadline; sequences are fail-fast (later steps recorded as skipped). The runner is the only clock source — verifiers also use time.monotonic.
• verification/verifiers/{pod_healthy,scaling_complete}.py: consume k8s.kubectl.get_json / k8s.conditions.poll_until; both null-guard .status on the raw kubectl JSON return. details= → raw=; name is echoed onto the result.

Phase 2B — authoring contract

• verification/schema.py: json_schema() (pydantic-derived JSON Schema for editor autocomplete) and validate_spec(data) (returns the concrete parsed node, propagates ValidationError).
• tests/unit/verification/test_optimize_scale_regression.py: pins a literal of the migrated optimize-scale verification (type: parallel with pod_healthy + scaling_complete children); both leaf verify methods are stubbed so the test runs without a cluster. This was the gap that hid the original parse bug.

Out of scope (Wave 4 harness PR): the task-file migration of complextasks/optimize-scale/task.yaml to native YAML, and the harness/scenario.py / harness/default.py registry-lookup change. The engine + authoring contract live independently here; the task-file change can be made against a single component PR.

Key decisions / notes for reviewers

• The runner accepts a VerificationSpec, an already-parsed SequenceSpec / ParallelSpec node, an existing leaf with a verify method, or a raw mapping. This keeps scenario.py callers free to pre-parse (mapping-registry path in §7c) without forcing them to.
• _run_parallel hands each child the full remaining deadline (no rebudgeting). Workers are bounded by _MAX_PARALLEL_WORKERS = 8 and by the deadline-bounded verify calls, so a slow kubectl wait does not linger past the deadline.
• _run_sequence skips remaining children when the deadline elapses between iterations, and also when the previous child failed (fail-fast); skipped children land in children with success=False.
• Leaf verifiers swapped to time.monotonic for start_time so the runner and leaves share one clock (was time.time in the legacy code).
• verification/__init__.py keeps the import light — no provider SDKs, no deepeval, no mcp are pulled at package import. test_package_import.py enforces this in a subprocess.

Test plan

• uv run ruff check devops_bench/ tests/unit/verification/ — clean
• uv run pytest tests/ -q — 345 passed (303 baseline + 42 new), 12 unrelated DeprecationWarnings
• uv run python -c \"from devops_bench.verification import VerificationSpec, VerifierAgent\" — no SDK / deepeval / mcp pulled
• Regression: literal of migrated optimize-scale spec parses + dispatches (test_optimize_scale_regression.py)
• .status: null is null-guarded on both pods and deployment leaves
• Bare list / bare dict-without-type rejected at parse time

What reviewers should scrutinize

• Whether the runner's wait_for_condition accepting four input shapes (VerificationSpec, parsed compound node, leaf with verify, raw mapping) is the right boundary, or whether we should narrow it.
• The parallel-deadline semantics: each child gets the full remaining deadline (intentionally not rebudgeted). Documented as the invariant; per-node timeout overrides may only ever tighten this — the documented Phase-A extension point.
• The _skipped / _timed_out helpers carry elapsed_time=0.0; the legacy code used time.time() - start for skipped members. The new value matches the "not run" semantics; flag if you want a different convention.
• VerificationNode is a Phase-A hand-maintained union. The Wave 2 metrics PR will introduce a VERIFIERS registry and swap only the parsing — the runner's isinstance dispatch stays intact.

Blockers

None.