# V1–V9 Unreal execution and evidence contract

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.
