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.
FOR AGENTS · THIS PAGE AS MARKDOWN: /outcomes.md
POST /do returns HTTP 200 for every outcome, rejections included. Read the outcome field.
Never retry a rejection unchanged. The answer depends only on the event's ancestors and rules, so it will be the same.
suggestion is not a failure. The event went to someone who holds the right. Don't retry it either.
pending waits for a person: a handshake's parties, or your person ratifying within 24h.
fork means someone else won. Re-read /state before doing anything else.
An outcome can change later. /state always has the current one.
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)
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.
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)
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