feat: add e2e observation contract

[ytallo]

Summary

• add the versioned e2e-observation/v1 and scenario-catalog contracts with canonical digests
• add optional run_contract for observe-only executions, including exact target, plan, runner, catalog, case, attempt, and deployment/campaign identity
• validate runner, catalog, target, and cases before the first model call
• return request and contract hashes, terminal observation envelopes, explicit unavailable-vs-zero metrics, and archive support for success, failure, infrastructure failure, and cancellation
• preserve legacy requests and archive behavior when run_contract is absent

Safety

Observe-only executions remain non-gating. The worker never promotes or blocks a deployment from an observation result.

Validation

• cargo fmt --all -- --check
• SKIP_DASHBOARD_BUILD=1 cargo check --all-targets
• SKIP_DASHBOARD_BUILD=1 cargo test --lib — 281 passed
• git diff --check

Related PRs and rollout order

1. This PR publishes the versioned observation contract and independent harness-e2e Registry worker.
2. iii-hq/workers#836 installs that worker only inside an ephemeral GitHub job.
3. iii-hq/release-control#21 owns plans, dispatch/admission/reconciliation, persistence, and UI.

Live Registry smoke is an explicit rollout step after all three PRs land. No Release Control deployment contains the E2E runner.

Summary by CodeRabbit

• New Features
  • Added optional observation contracts for test runs, including execution modes, selected scenarios, target identity, and runtime metadata.
  • Added structured observation results with outcomes, evidence, samples, metrics, provenance, and artifact references.
  • Added scenario catalog metadata, deterministic identifiers, and validation details.
• Bug Fixes
  • Improved validation of run identity, contracts, reports, and restored results.
  • Terminal, unsupported, and recovered executions now produce consistent observable results.
• Documentation
  • Added published schemas for observation envelopes and scenario catalog responses.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: e5832689-55b8-4cf5-b3fb-d67358e7aa89

📥 Commits

Reviewing files that changed from the base of the PR and between 6353be1 and 6cd8442.

📒 Files selected for processing (15)

• schemas/e2e-observation-v1.json
• schemas/e2e-scenario-catalog-v1.json
• schemas/manifest.json
• schemas/results.json
• src/control.rs
• src/dashboard.rs
• src/dashboard/controller.rs
• src/durable.rs
• src/fault.rs
• src/main.rs
• src/report.rs
• src/scenarios/domain.rs
• src/scenarios/mod.rs
• src/schema.rs
• src/suite.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds versioned observation schemas and Rust models, propagates observation contracts through suite and control-plane execution, generates terminal observations, and archives observations alongside or instead of reports.

Changes

Observation contract flow

Layer / File(s)	Summary
Observation contracts and schema models schemas/e2e-observation-v1.json, schemas/e2e-scenario-catalog-v1.json, schemas/manifest.json, schemas/results.json, src/report.rs, src/schema.rs, src/scenarios/*	Defines observation envelopes, run contracts, scenario catalogs, identities, metrics, provenance, validation, persistence, and generated schema snapshots.
Deterministic contract admission and catalog identity src/control.rs, src/suite.rs, src/dashboard/*, src/fault.rs, src/main.rs	Hashes requests and contracts, validates observation inputs and catalog identity, materializes deterministic scenario metadata, and propagates optional contracts into suite runs.
Terminal observation generation and recovery src/control.rs	Creates terminal observations for completed, unsupported, failed, cancelled, and recovered executions. It records outcomes, samples, metrics, availability, provenance, and artifacts.
Observation-based durable archiving src/durable.rs	Archives terminal observations without reports, validates observation payloads, derives archive identity, and preserves report-based archive handling.

Estimated code review effort: 5 (Critical) | ~120 minutes

Merge Risk: ⚪ Minimal · up to 6cd84

The PR adds versioned observation contracts while preserving legacy behavior when the optional contract is absent; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ControlPlane
  participant SuiteRun
  participant ObservationEnvelope
  participant DurableHistory
  Caller->>ControlPlane: submit RunRequest with observation contract
  ControlPlane->>ControlPlane: validate hashes, runner, catalog, and selected cases
  ControlPlane->>SuiteRun: execute with observation contract
  SuiteRun-->>ControlPlane: return execution result and report data
  ControlPlane->>ObservationEnvelope: build and validate terminal observation
  ObservationEnvelope-->>ControlPlane: return observation.json metadata
  ControlPlane->>DurableHistory: archive report and/or observation

Loading

Poem

I’m a rabbit with hashes, neat and bright,
I carried observations through the night.
Contracts stood firm, samples stayed clear,
Archives welcomed new evidence here.
Metrics kept zeros, outcomes stayed true—
A tidy burrow of schemas for you.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands.}