Eve library

V1–V9 Unreal execution and evidence contract

Evidence

Revision 1

On this page

This runbook qualifies every V1–V9 closure instruction that depends on Unreal Engine. It separates repository/project availability from the capabilities of the shell that happens to be running the audit.

Designated execution profile#

The profile name is ue55-linux:

  • runner class: GitHub Actions labels [self-hosted, Linux, Unreal];
  • engine: Unreal Engine 5.5.x;
  • engine root: /root/workspace/UnrealEngine-5.5;
  • commandlet executable: /root/workspace/UnrealEngine-5.5/Engine/Binaries/Linux/UnrealEditor-Cmd;
  • run-as user: ueagent;
  • automation target: LinuxEditor;
  • Linux cook/package target: Linux via RunUAT BuildCookRun;
  • durable output: the exact log, Automation report or cooked archive, and an oshun.unreal-evidence.v1 record produced by scripts/audit/write-unreal-evidence-record.mjs.

An executed record is invalid unless it identifies the full source commit, engine version and executable digest, project path and digest, commandlet, exact argv, run-as user, target platform, timestamps, exit code, and output artifact byte counts/digests. The machine contract is scripts/audit/unreal-evidence.schema.json.

Project binding#

Closure surface Project that must be recorded Normal commandlet Target
V2 V2/ue/V2.uproject UnrealEditor-Cmd for automation; RunUAT BuildCookRun for a cook LinuxEditor or Linux
V3 V3/ue/V3.uproject UnrealEditor-Cmd / project BuildGraph LinuxEditor or the explicitly selected cook target
V4 V4/ue/V4.uproject UnrealEditor-Cmd LinuxEditor
V5 V5/ue/V5.uproject UnrealEditor-Cmd / RunUAT BuildCookRun LinuxEditor or Linux
V6 V6/ue/V6.uproject UnrealEditor-Cmd / BuildGraph LinuxEditor or Linux
V7 V7/ue/Mawu.uproject UnrealEditor-Cmd / RunUAT BuildCookRun LinuxEditor or Linux

V8 has no standalone .uproject in this repository. A V8 task that says “place/cook/play in UE” must first name and approve the owning runtime project; until then it is blocked on a project binding, not satisfied by choosing an unrelated .uproject.

Local capable-host path#

On a host that actually satisfies ue55-linux, first retain:

sh
git rev-parse HEAD
test -x /root/workspace/UnrealEngine-5.5/Engine/Binaries/Linux/UnrealEditor-Cmd
id ueagent

Run editor automation as ueagent, for example V4:

sh
runuser -u ueagent -- V4/.ci/run-ue-automation-smoke.sh

Do not copy this command to a different project without changing the recorded project, suite, target, and expected output. A cook must record RunUAT BuildCookRun, its exact platform/configuration/map/archive arguments, and the cooked archive digest; an editor automation run is not cook evidence.

macOS or other host without Unreal#

Do not install, emulate, or silently skip UE merely to make the local step green. Send the commit to the designated remote runner. For V4, push a branch or tag that resolves to the intended commit and use the dispatchable remote job:

sh
gh workflow run v4-pr-gate.yml --ref <branch-or-tag>
gh run list --workflow v4-pr-gate.yml --commit <full-commit-sha>
gh run view <run-id> --json headSha
gh run watch <run-id> --exit-status
gh run download <run-id> --name v4-ue55-linux-evidence

The returned headSha must equal <full-commit-sha> before its evidence can be used. A branch name without that equality check is mutable and therefore not an evidence identity.

The UE5.5 Automation Smoke job is required to run on [self-hosted, Linux, Unreal] and upload the log, Automation report, and evidence JSON even when the commandlet is red. The current V2 planning job and V3 Windows worker are not substitutes for this Linux executed-evidence profile. The existing V6 Linux BuildGraph job has the right runner class but does not yet emit oshun.unreal-evidence.v1. V2, V3, V5, V6, or V7 closure therefore needs a project-owned dispatch/PR job on the same runner profile, upgraded to emit this record, before it can claim qualifying remote execution.

Missing-host semantics#

If either the commandlet path or ueagent is absent, record not-run-on-this-host with the checked path, host/OS, source commit, timestamp, and missing prerequisite. This status means only that the current host cannot execute the job. It is not evidence that Unreal is unavailable to the project, that the project cannot compile, or that a remote job passed or failed.

Never create an oshun.unreal-evidence.v1 record for a skipped run. That schema is reserved for an actually executed command with retained outputs.

Evidence acceptance#

An Unreal closure claim requires all of the following:

  1. An executed oshun.unreal-evidence.v1 record that passes the writer's validator and matches scripts/audit/unreal-evidence.schema.json.
  2. Exact commandlet output and Automation/cook output retained by digest.
  3. A green command exit for a pass claim; a red record remains useful evidence but cannot close the product gate.
  4. For playable/cooked claims, the packaged binary/archive plus runtime media and the relevant accessibility/performance results. A LinuxEditor Automation pass alone does not prove cook, placement, playback, or quality.
  5. The record and artifacts committed or linked to an immutable CI artifact with retention sufficient for the release decision.