# Result envelope 1

> The result envelope a runner writes for every job, field by field, rendered from result-envelope-1.schema.json.

HTML version: https://docs.codonic.dev/oarbank/reference/schemas/result-envelope-1

A runner writes this document atomically to the `--out` path when a job succeeds. The `payload` is the module’s own result; the rest is the envelope the core reads.

## Fields

**Schema ID** `https://codonic.dev/oarbank/schemas/result-envelope-1.schema.json`\
**Dialect** `https://json-schema.org/draft/2020-12/schema`\
**Raw file** [`result-envelope-1.schema.json`](/oarbank/schemas/result-envelope-1.schema.json)

### Top level

| Field                     | Type                                 | Description                                                                                                    | Constraints                                                                                          |
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `artifacts`               | array of [`Artifact`](#def-artifact) |                                                                                                                |                                                                                                      |
| `effective`               | `object`                             | \[stable] The subset of spec parameters/modes actually honoured; the core compares it with what was requested. |                                                                                                      |
| `envelope`                | `const 1`                            |                                                                                                                | default `1`                                                                                          |
| `module_version` required | `string`                             |                                                                                                                | pattern `"^(0\|[1-9]\\d*)\\.(0\|[1-9]\\d*)\\.(0\|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$"` |
| `payload` required        | `object`                             | \[stable] Module-owned result payload (<= max_inline_kb; larger data goes in artifacts).                       |                                                                                                      |
| `protocol`                | `integer`                            |                                                                                                                | default `1`                                                                                          |
| `provenance`              | [`Provenance`](#def-provenance)      |                                                                                                                |                                                                                                      |
| `schema` required         | `string`                             | \[stable] `<module>/result@N` of the payload.                                                                  | pattern `"^[a-z0-9][a-z0-9.-]*/(spec\|result)@[1-9][0-9]*$"`                                         |

Unknown fields are allowed and kept.

### `Artifact`

| Field            | Type                                         | Description                                                              | Constraints                                   |
| ---------------- | -------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| `files` required | array of [`ArtifactFile`](#def-artifactfile) |                                                                          | min items `1`                                 |
| `name` required  | `string`                                     | \[stable] Output name; a downstream stage receives it as inputs.\<name>. | pattern `"^[a-z][a-z0-9_]*$"` max length `64` |

Unknown fields are allowed and kept.

### `ArtifactFile`

| Field           | Type                | Description                                                                                                                                    | Constraints                               |
| --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `digest`        | `string` \| `null`  |                                                                                                                                                | pattern `"^[0-9a-f]{64}$"` default `null` |
| `local`         | `string` \| `null`  | \[stable] Runner-written only: workdir-relative source (a PortablePath, `/`-separated). The agent uploads it and replaces it with digest/size. | default `null`                            |
| `path` required | `string`            | \[stable] PortablePath inside the artifact (what the consumer sees under its mount). Artifacts carry no file modes.                            |                                           |
| `size`          | `integer` \| `null` |                                                                                                                                                | default `null`                            |

Unknown fields are allowed and kept.

### `Provenance`

| Field           | Type                              | Description                                          | Constraints    |
| --------------- | --------------------------------- | ---------------------------------------------------- | -------------- |
| `argv`          | map of string → array of `string` | \[stable] Tool invocations that produced the result. |                |
| `host`          | `string` \| `null`                |                                                      | default `null` |
| `tool_versions` | map of string → `string`          |                                                      |                |

Unknown fields are allowed and kept.