tallydocs
gromit 0.2.0
Docs menu
Docs / Build / Outcomes

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.

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.

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