Define Level 2 contracts

[burtenshaw]

This PR defines RFC 008 Level 2 contracts, versioned schemas and shared validation cases. First of three stacked PRs tracked in #1177.

[cursor]

Alignment Review Report

PR #1178 — Define Level 2 contracts (ben/rfc008-l2-01-contracts). Implements the RFC 008 "Level 2 execution amendment": manifest schema 2 (NormalizedManifestV2 + ExecutionDeclaration), report schema 2 (ValidationReportV2), the bounded data-only RuntimePlan, LaunchSpec, immutable wire evidence (WireExchange/RuntimeEvidence), and severity policy v2.

Automated Checks

• Lint: PASS (scoped to this PR). ruff format --check, usort check, and ruff check are all clean on the 11 changed Python files. The repo-wide lint.sh reports 57 files needing formatting, but every one is pre-existing (e.g. src/openenv/core/README.md) — none are touched by this PR.
• Debug code: CLEAN (this PR). check-debug.sh flags many print(...)/TODOs, but all are pre-existing (CLI console.print, docstrings, test_local_docker_provider.py); none appear in this diff.
• Tests: PASS — tests/test_validation/ → 169 passed.
• Schema sync: PASS — scripts/sync_validation_schemas.py --check → "validation schemas in sync"; the 3 new committed JSON schemas match their Pydantic models.

Open RFCs Context

• RFC 008 — Environment Auto-Validation (In Review, @zkwentz) — directly implemented and amended by this PR.
• RFC 004 — Rubrics — leveraged, not required, via llm_judged / judge pinning / rubric_tree; unchanged here.
• RFC 002 — Env Spec (In Review) — this PR extends the validation: block of openenv.yaml with an execution key (validation-owned namespace); the core env spec is unchanged.

Tier 1: Fixes Required

None. Verified in detail:

• Path-traversal / symlink-escape defenses in ExecutionDeclaration._package_relative + load_runtime_plan (resolve(strict=True) + is_relative_to), covered by tests.
• Sidecar bounds (65 536 bytes, depth 32, 10k nodes, 1–100 actions), duplicate-key rejection, non-finite rejection, and strict typing (seed as unsigned 32-bit int) all implemented and tested.
• LaunchSpec refuses mutable image refs, host-credential inheritance, unsafe env-var names/values, and infinite budgets.
• V2 union field ordering (NormalizedManifestV2 | NormalizedManifest | None) avoids subclass field-dropping on serialization; round-trip + type-preservation are tested.
• New tests/test_validation/support/runtime.py imports (providers.ExecResult, types.ProviderCapability) resolve against existing modules.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. Invariants I checked specifically:

• Dual API boundary / "agents cannot reset" (INVARIANTS.md). RuntimePlan.reset/seed and the single-session reset→step→state collector run on the infrastructure/orchestration side (validation drives the subject like a training orchestrator). agent_boundary is api-only, and the amendment keeps session telemetry off agent MCP tools. No agent gains reset/step/state — consistent with the invariant.
• Rewards in environment / client-server separation. Untouched; reward well-formedness is read from the env's own channel, and the validation package introduces no client→server import.

RFC Conflicts

ALIGNMENT FLAG: PR amends and implements the same In-Review RFC in one change

• Principle/RFC at stake: RFC 008 (In Review). The "Level 2 execution amendment" is added to rfcs/008-environment-auto-validation.md (+157 lines) in the same PR that implements its contracts (manifest v2, report v2, runtime plan, LaunchSpec, policy v2).
• The concern: These contracts (schema versions, sidecar bounds, launch security posture, policy v2) become hard to change once downstream slices (#1177) depend on them, yet the amendment specifying them is not yet Accepted. This is not a code-vs-RFC divergence — I verified the implementation matches the amendment field-by-field — it is a request to ratify the amendment text before the contracts calcify.
• Suggested reviewer: @zkwentz (RFC 008 author) to confirm the amendment; @Darktex (author of INVARIANTS.md / PRINCIPLES.md, incl. the dual-API-boundary invariant) to sign off that the reset/step/state collector surface stays on the orchestration side.

Observation (non-blocking)

• When a package opts into schema 2 but the runtime graders are not wired yet, run_validation emits a v2 report with only static results and levels_run=[static]. That is honest (it does not imply runtime coverage), but it also surfaces no runtime.* SKIP entries for the requested-but-unimplemented checks. RFC 008 states a partial implementation "must expose the missing requested checks as named SKIPs" — worth confirming whether that SKIP surfacing is expected to land with the runtime execution slice (PR3) rather than here. Not a blocker for a contracts-only PR.

Summary

• 0 mechanical issues to fix (Tier 1 clean: lint, debug, tests, schema-sync all green for this PR).
• 1 alignment point for human review (ratify the RFC 008 L2 amendment that lands with its implementation).
• 0 RFC conflicts / divergences (the flag above is a process/ratification note; 1 non-blocking observation on future SKIP surfacing).

Overall: a high-quality, thoroughly tested contracts PR that faithfully implements the RFC 008 Level 2 amendment. No blocking issues.

  

_{Sent by Cursor Automation: Pre-review}

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[cursor]

REQUEST_CHANGES at c2ab165b

Exact-head CI is red on both Python versions with a single failure:

tests/test_cli/test_validate.py::test_write_report_validation_report_only

Root cause: write_report now accepts ValidationReport | ValidationReportV2, but the existing CLI test still asserts the annotation is exactly ValidationReport. Reproduced locally.

Please update that test for the intentional V2 union (keep the dict-rejection check). Stacked #1179/#1181 inherit the same red until #1178 is fixed and they rebased.

Not reviewing the full Level-2 contract surface until CI is green. Not 0.6.0 wheel-blocking for Thursday unless you want L2 in the cut (currently separate from draft #1211).

  

_{Sent by Cursor Automation: Release}

[cursor]

APPROVE at d7eaf3c8

Prior CI blocker fixed: write_report again annotates report: ValidationReport (V2 subclasses remain compatible). Local + exact-head tests 3.11/3.12 green; Bugbot clean.

Not Thursday 0.6.0 cargo unless you intentionally fold L2 into the cut.

View PR

  

_{Sent by Cursor Automation: Release}