Module run 

AI Run Definition

A Run is a single execution attempt of a Task. It captures the execution context (baseline commit, environment, Plan version) and accumulates artifacts (PatchSets, Evidence, ToolInvocations) during execution. The Run is step ⑤ in the end-to-end flow described in mod.rs.

Position in Lifecycle

 ④  Task ──runs──▶ [Run₀, Run₁, ...]
                       │
                       ▼
 ⑤  Run (Created → Patching → Validating → Completed/Failed)
      │
      ├──task──▶ Task          (mandatory, 1:1)
      ├──plan──▶ Plan          (snapshot reference)
      ├──snapshot──▶ ContextSnapshot  (optional)
      │
      │  ┌─── agent execution loop ───┐
      │  │                            │
      │  │  ⑥ ToolInvocation (1:N)    │
      │  │       │                    │
      │  │       ▼                    │
      │  │  ⑦ PatchSet (Proposed)     │
      │  │       │                    │
      │  │       ▼                    │
      │  │  ⑧ Evidence (1:N)          │
      │  │       │                    │
      │  │       ├─ pass ─────────────┘
      │  │       └─ fail → new PatchSet
      │  └────────────────────────────┘
      │
      ▼
 ⑨  Decision (terminal verdict)

Status Transitions

Created ──▶ Patching ──▶ Validating ──▶ Completed
               │              │
               └──────────────┴──▶ Failed

Relationships

Field	Target	Cardinality	Notes
task	Task	1	Mandatory owning Task
plan	Plan	0..1	Snapshot reference (frozen at Run start)
snapshot	ContextSnapshot	0..1	Static context at Run start
patchsets	PatchSet	0..N	Candidate diffs, chronological

Reverse references (by run_id):

• Provenance.run_id → this Run (1:1, LLM config)
• ToolInvocation.run_id → this Run (1:N, action log)
• Evidence.run_id → this Run (1:N, validation results)
• Decision.run_id → this Run (1:1, terminal verdict)

Purpose

• Execution Context: Records the baseline commit, host environment, and Plan version so that results can be reproduced.
• Artifact Collection: Accumulates PatchSets (candidate diffs) during the agent execution loop.
• Isolation: Each Run is independent — a retry creates a new Run with potentially different parameters, without mutating the previous Run’s state.

Structs

Environment

Host environment snapshot captured at Run creation time.

Run

A single execution attempt of a Task.

Enums

RunStatus

Lifecycle status of a Run.