> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outcomes

> Governed outcome definitions and bindings — how a workflow run produces a claim it did not author.

Last updated 2026-11-11

·
applies to 2026-11-07

·
main

An **outcome** is the platform's durable claim about what a completed workflow run achieved. It is
what feeds executive surfaces, objective roll-ups, and the trust receipt.

The important property is *who writes it*. A workflow does **not** compose its own outcome. It emits
**facts**; a governed **outcome definition** decides what those facts mean, and an **outcome
binding** decides which workflow version is allowed to supply them.

## Four meanings of outcome

Forge uses the word *outcome* for four different things. Qualify it when you write about one.

| Meaning | What it is | Where you see it |
| - | - | - |
| A run's terminal status | How a run ended: `completed`, `failed` or `cancelled` | The run's `status` in the API and the run page in Forge Console |
| A run's execution outcome | How a completed run got there: **Completed normally**, **Completed with handled error**, **Completed with exception**, or **Completed — outcome needs review** when the evidence conflicts. It describes execution, never business success | **Execution outcome** on the run page in Forge Console |
| A work outcome | The governed claim this page describes: what a completed run achieved, judged by an outcome definition | **Planning → Outcomes** in Forge Console; goals roll these up |
| A decision's disposition | What a Trust Fabric decision did with an action: allowed, held or blocked | The **Outcome** filter and grouping under **Trust Fabric → Decisions** |

## The two tables

### `outcomeDefinitions` — what a claim means

An immutable row declaring the facts an outcome needs and the rules that turn them into a status.

| Field | Purpose |
| - | - |
| `definitionKey`, `version` | Identity. A new version is a **new row** — definitions are never edited in place. |
| `facts` | Each fact's `key`, declared `type` (`string` / `number` / `boolean` / `array`), and whether it is `required`. |
| `factTransforms` | Optional value remaps, e.g. normalizing an upstream `"approve"` to `"approved"`. |
| `statusRules` | Ordered `when` / `then` rows. First fully-matching row wins. |
| `headlines` | The text shown for each reachable claimed status. |
| `metricsSpec`, `summarySpec`, `exceptionsSpec`, `periodSpec`, `primaryArtifactSpec` | How the rest of the claim is projected from facts. |

Immutability is the point: a binding pins `(definitionKey, version)`, so a claim already made about a
completed run can never have its meaning rewritten underneath it.

### `outcomeBindings` — who may fulfill it

A row attaching one definition version to one **pinned** `workflowVersions` row, and mapping each
declared fact to a source.

| Mapping source | Resolves from |
| - | - |
| `{ kind: "output", fromField, nodeName? }` | A node output on the completed attempt, resolved by **field provenance**. `nodeName` pins the producer when more than one node emits the field. |
| `{ kind: "input", fromInput }` | A declared workflow input, read from the run's launch arguments. |

A mapping may also declare `evidenceKind: "approval" | "file"` so the claim links to the human
approval or the produced artifact that backs it.

## Status rules

Rules are evaluated top-down and the first row whose every condition matches wins. The last row
**must** have an empty `when` — an unconditional terminator — so every possible fact set resolves to
exactly one status. Authoring rejects a rule set without one.

| Operator | Meaning |
| - | - |
| `eq`, `neq` | Strict equality. No type coercion — `"3"` never equals `3`. |
| `lt`, `lte`, `gt`, `gte` | Numeric only. False against a non-number. |
| `empty`, `nonempty` | Strings and arrays only. A number is neither. |

Two rules worth internalizing before authoring:

> [!NOTE]
>
> A **missing optional fact** makes every condition on it false — **except** `empty`, which is true.
> "There were no exceptions" and "there is no exceptions list" are the same claim to an operator.

> [!WARNING]
>
> A **missing required fact**, or a fact whose runtime value contradicts its declared type, fails the
> whole outcome with `missing_fact` before any rule runs. Values are never coerced: silently reading
> `"3"` as `3` would let a numeric threshold compare a string and emit a confident claim from a broken
> mapping.

## What a run produces

Materialization is scheduled for **every** completed production run. The workflow engine knows
nothing about outcomes — it does not check whether one is expected.

* **No active binding** → no row is written, and the run reports `not_declared`. This is the ordinary
  case for most workflows, not an error.
* **N active bindings** → N outcome rows for that attempt, keyed by definition. Run surfaces show the
  **worst** status across them.

Each row settles into one of three states:

| State | Meaning |
| - | - |
| `ready` | The claim was built and every evidence reference verified. |
| `invalid` | A **definite** negative — a required fact was missing or mistyped, a mapping was ambiguous, or evidence was fully read and did not verify. The run is raised to `critical`. |
| `pending` | Evidence reading hit a bounded cap, so neither fulfilment nor breach was observed. Retried once, then the run is raised to `attention`. Deliberately **not** `invalid` — an unread page is not a broken promise. |

## Authoring and permissions

Creating and retiring outcome definitions, and attaching and retiring bindings, all require
`objectives:manage`. It is deliberately separate from `workflows:manage`: authoring a workflow and
deciding what that workflow is allowed to **claim** are different powers. Grant it to people, not to
agents: an agent that could author a definition could author the standard its own run is measured
against.

When a workflow publishes a new version, every active binding is re-validated against it. A binding
that still resolves is carried forward automatically; one that no longer resolves is **not** carried,
and an audit event records why. A workflow that keeps claiming outcomes off renamed-away fields
would be worse than one that stops claiming.

## Trust receipts

Every outcome carries a trust receipt: a canonicalized (RFC 8785 JCS) record of the identity,
authority, credentials, capabilities, models, decisions, cost, and artifact lineage behind the run,
plus a SHA-256 digest of itself.

Where a signing key is configured, the receipt is additionally signed with Ed25519 over that same
digest and reports `signed: true`. Signing is deterministic, so re-reading an outcome returns a
byte-identical receipt. A deployment with no key still serves receipts with `signed: false` — the
digest still binds the contents, but nothing attests to origin.

To verify an exported receipt: remove `integrity.digest`, canonicalize with JCS, SHA-256 the result,
and compare. Then, if signed, verify the signature over the raw bytes of that digest with the
published key. Exports include these instructions inline.

### Workflow run certificates

Forge also has a separate `run-trust-receipt/v1` certificate contract for an individual workflow
run attempt. It binds the attempt's terminal result and observed evidence without requiring an
outcome definition or binding. The certificate records observation time, provenance, and coverage
for each evidence section; missing attribution remains explicit.

The exact stored envelope contains `payload` and `integrity`. Forge signs the raw SHA-256 digest
of the RFC 8785 canonicalized `payload` with Ed25519. Verification checks the closed payload and
envelope shapes, digest, signature, and trusted deployment/key identity. This protocol differs
from the outcome receipt described above. A failed run may have a valid certificate, and a valid
signature does not imply complete evidence.

Error summaries use the shared run-content masking policy before they are frozen and signed.
Reads return that exact signed account. Decision evidence remains partial when Forge cannot prove
that every approval producer was captured, even when all recorded canonical decisions were read.

Terminal integration preserves newly ended attempts for asynchronous issuance, including failed,
cancelled, test, delegated, and personal-assistant runs. Historical discovery requests certificates
for known retained terminal attempts in bounded passes. Those certificates report retrospective
provenance and their actual issuance time; missing history is not reconstructed.

Certificate reads follow the source run's permissions and retention. Actual source deletion also
removes its stored certificates and requests; public verification keys remain retained. Exports
can still be verified with a separately trusted archived public key. The existing outcome receipt
and machine dossier contracts above remain unchanged.

The [Console Runs surface](https://docs.gloo.com/forge/console/production/runs.md) provides receipt access from run lists and the
run canvas. Deployment signing readiness and completed issuance determine availability; code
deployment alone does not prove that a live certificate exists.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.