​
Lifecycle

draft → voting → (approved | rejected) → executed
          ↓
      escalated (if human-gate required)
          ↓
        voting

​
States

StateMeaningTransitions
draftCreated, not yet opened for voting→ voting, escalated, cancelled
escalatedWaiting on human approval from escalation engine→ voting, rejected
votingActive voting period→ approved, rejected
approvedThreshold + quorum met→ executed
rejectedThreshold not met OR quorum not met OR voting expired(terminal)
executedAction performed and chain-confirmed(terminal)
cancelledWithdrawn by proposer before voting(terminal)

​
Kinds

enum ProposalKind {
    Spend {
        amount_usd: f64,
        recipient: String,
        description: String,
    },
    Membership {
        action: MembershipAction, // Add | Remove | UpdateRole
        target: Did,
    },
    Amend {
        before: ConstitutionYaml,
        after: ConstitutionYaml,
        rationale: String,
    },
    Custom {
        payload: serde_json::Value,
        description: String,
    },
}

​
Creating a proposal

const proposal = await orgs.proposals.create({
  entity: "helios-research",
  kind: {
    type: "spend",
    amountUsd: 12500,
    recipient: "aws-bedrock",
    description: "Q2 compute reservation",
  },
  idempotencyKey: "helios-2026-q2-compute",
});

// State: draft → escalated (if >= require_human_above_usd) or voting

​
Voting

await orgs.proposals.vote(proposal.id, {
  choice: "approve", // approve | reject | abstain
  signature: signer.sign(proposal.id),
});

​
Execution

Once a proposal reaches approved state, it can be executed by any member with execute permission: 
const receipt = await orgs.proposals.execute(proposal.id);
// Returns chain transaction signature, confirmation timestamp, audit chain entry
Execution is idempotent — calling execute on an already-executed proposal returns the existing receipt, not a duplicate.

​
Cancellation

Only the proposer can cancel a proposal, and only while in draft state. Once voting opens, the only ways out are approved, rejected, or executed.

​
Visibility

All proposals are visible to members of the entity. You can expose a public-facing view of proposals to anyone with a proposal ID, for transparency — configured per-entity.