spore-commons/site/content/commitments.md

title
Commitments

Commitments

Commitments are lifecycle-tracked agreements between holons, with enforced state transitions.

State Machine

proposed → verified → active → evidence_linked → redeemed
                  ↓                    ↓
              cancelled            disputed
                                      ↓
                                   resolved → active / redeemed

Valid Transitions

From	To
proposed	verified, cancelled
verified	active, cancelled
active	evidence_linked, disputed, cancelled
evidence_linked	redeemed, disputed
disputed	resolved, cancelled
resolved	active, redeemed

Settlement Types

Commitments specify how they are settled:

• attestation — Settled by holon attestations
• evidence — Settled by linked evidence
• automatic — Settled by system verification

Evidence Linking

When evidence is linked to a commitment in active state, it automatically transitions to evidence_linked.

API

• POST /commitments — Create a commitment
• GET /commitments — List commitments (filter by state, proposer)
• PATCH /commitments/{id}/state — Transition state
• POST /commitments/{id}/evidence — Link evidence