# Outcomes

Every event gets one outcome from the fold. It can change later: a
`pending` handshake becomes `applied` when it's met, and an `applied` claim
becomes `fork` when a concurrent claim with a lower hash arrives. `/state`
always has the current one. `POST /do` returns it,
`/state` lists it under `outcomes`, and `/events` carries it on each event.
Look a code up here. The codes are produced in
`crates/gromit-core/src/fold.rs` unless noted.

## Accepted outcomes

| Outcome | Meaning | What to do |
|---|---|---|
| `applied` | It happened. The effects are in the state | nothing |
| `suggestion` | You lacked the right, so it went to `to` as a suggestion. The state didn't change | nothing; `to` decides. Don't retry |
| `claim` | An attestation (`decision@0 inferred`) stored as a claim until the subject's holder confirms | nothing |
| `pending` | A handshake that's open (an `offered`, a `review_requested`) until its parties answer, or an agent's commitment waiting for its person to ratify within `ratify_within` (24h) | the parties, or the person, answer it from `gromit inbox` |
| `fork` | It conflicted with a concurrent event that won the hash tiebreak (two claims at once) | re-read the state. Someone else got there first |

## Rejections

A rejected event isn't stored or sent, and sending it again gets the same
answer. Fix the cause, or record it and move on. The Tiphys adapter keeps
rejected keys in a ledger and never retries them.

### Who you are

| Code | Meaning |
|---|---|
| `not_member` | the person isn't in the active `grouping.yaml` |
| `off_bus` | the person is listed `on_bus: false`; only a bridge may act for them |
| `actor_mismatch` | the actor isn't the person, or not `person/<agent>` |
| `on_behalf_not_bridge` | only bridges may set `on_behalf` |
| `no_mandate` | an agent with no active grant covering this verb. `:routine` covers only routine verbs. Checked before `requires_human`, so an agent trying a protected verb with no grant for it sees this |
| `mandate_revoked`, `mandate_expired` | the agent's mandate is no longer active |
| `grant_condition` | the grant's `when` didn't hold |
| `budget_exceeded` | a mandate budget or the verb's `budget_per_subject` is used up |
| `requires_human` | a protected verb, or `requires_party: human`, by an agent (or a bridge not mirroring a human approval) |

### Bridges

| Code | Meaning |
|---|---|
| `unknown_bridge` | a `system:` actor not listed under `bridges:` |
| `bridge_not_mandated` | the bridge isn't given this contract |
| `bridge_repo` | the entity's `repo` isn't one of the bridge's repos |
| `bridge_not_allowed` | the verb's `who` doesn't name `bridge` |
| `on_behalf_not_fact` | `on_behalf` on something other than a fact or a response |

### What you aimed at

| Code | Meaning |
|---|---|
| `unknown_contract`, `unknown_verb` | not in the rules the event names |
| `unknown_entity` | `entity` names nothing in this contract's state |
| `wrong_contract`, `wrong_entity` | the entity belongs to another contract or entity type |
| `cannot_create` | no `entity`, and this verb can't create one |
| `unknown_target` | `responds_to` names no handshake or claim |
| `wrong_target` | a response to a different verb's handshake than its `responds_to` names |
| `not_a_claim` | an attestation response aimed at something that isn't a claim |
| `kind_mismatch` | the envelope's `kind` isn't the verb's |

### The contract's rules

| Code | Meaning |
|---|---|
| `invalid_payload: <path>: <why>` | the payload doesn't match the field types or the verb's `payload:` (a missing required field, a string over `maxLength`, `ratify_within` over `7d`) |
| `managed_field: <field>` | a payload sets a field only the runtime manages (`creator`, `holder`) |
| `authority_bridge` | a field with `authority: bridge` (`head_sha`, `forge_url`), set by someone other than a bridge |
| `not_permitted` | you lack the right and nobody else on the bus holds it, so there's no one to suggest it to (`state_changed` on an item nobody holds, an `ext.*` edit on an item you don't hold); a response by someone who may not make it; or a ratified commitment no longer allowed |
| `party_to_holder` | you, or your agent, acting on your own thing where the verb excludes you, e.g. inferring a decision about your own change set |
| `party_rule` | your response doesn't count under the handshake's `party_rule` (approving your own MR) |
| `not_party`, `not_proposer` | `accept`/`reject` by someone not asked, or `withdraw` by someone who didn't ask |
| `precondition` | the verb's `when`, or a `requires` with no reason, didn't hold |
| `illegal_transition` | `state` can't move there from where it is (see the contract's `states:`) |
| `not_attenuating` | a delegation or narrowing that widens a mandate |
| `one_way_must_open`, `frozen`, `hash_mismatch`, … | a contract's own `requires` reason |
| `lapsed`, `withdrawn`, `handshake_met` | the handshake is no longer open |
| `not_redactable` | `redacted` on a field without `redactable: true` |
| `expr_error: no right lets anyone edit <field>` | an `edited` payload names a field with no `rights:` entry: a typo, or a field that has its own verb (`state` → `state_changed`, `holder` → `claimed`) |
| `expr_error: …` (other) | the contract's expression failed. A contract bug: tell the steward |

### Rules and feeds

| Code | Meaning |
|---|---|
| `unknown_rules` | the event names a bundle this sidecar can't rebuild from governance history |
| `stale_rules` | it names a bundle more than 24h after a newer one took over: an old queued event |
| `unknown_event` | it refers to an event nobody has |
| `bad_signature: …` | the signature doesn't verify (also refused by the relay) |
| `broken_feed: …` | the author's feed has a gap or fork, so their whole feed is rejected |
| `feed_gap` | the relay refused an event that isn't the next in its author's feed (`gromit-relay`). The sidecar re-signs what was queued behind it |
| `refused: audience …` | not an outcome but an HTTP 400 from `/do`: audiences narrower than the grouping are off until seed:861 |
