Execution Model

Every side effect in TheCorporation follows a single execution contract: intent, decision, receipt. No corporate state changes without passing through this gate.

The invariant

Every mutation requires all three:

1. Intent — a typed request describing what should happen (e.g., “issue 1M shares to Alice”).
2. Decision — a deterministic policy evaluation that approves, blocks, or creates a human obligation.
3. Receipt — an immutable record proving the operation happened, with request and response hashes.

The gate function:

execute_intent(intent_id, idempotency_key) → Receipt

No exceptions. Read operations bypass the gate. Everything else goes through it.

Intent lifecycle

Every intent moves through a deterministic state machine:

draft → ready_for_evaluation → authorized | blocked → executing → executed | failed | cancelled

State	Meaning
draft	Intent created, not yet evaluated
ready_for_evaluation	Awaiting policy check
authorized	Policy approved, ready to execute
blocked	Policy denied (missing obligation, tier violation, scope issue)
executing	Execution in progress
executed	Complete — receipt written, git commit made
failed	Execution attempted but errored
cancelled	Withdrawn before execution

API mapping

All execution routes are entity-scoped under /v1/entities/{entity_id}:

# 1. Create a typed intent
POST /v1/entities/{entity_id}/intents

# 2. Evaluate against policy
POST /v1/entities/{entity_id}/intents/{intent_id}/evaluate

# 3. Authorize (if evaluation passed)
POST /v1/entities/{entity_id}/intents/{intent_id}/authorize

# 4. Execute
POST /v1/entities/{entity_id}/intents/{intent_id}/execute

# 5. Read the receipt
GET /v1/entities/{entity_id}/receipts/{receipt_id}

Example: create and execute an intent with curl:

# Create intent
curl -s -X POST https://api.example.com/v1/entities/$ENTITY_ID/intents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_type": "equity.grant",
    "authority_tier": "tier2",
    "description": "Issue 1,000,000 shares of Common Stock to Jane Smith",
    "metadata": {}
  }'

# Evaluate
curl -s -X POST https://api.example.com/v1/entities/$ENTITY_ID/intents/$INTENT_ID/evaluate \
  -H "Authorization: Bearer $TOKEN"

# Authorize (after human approval if required)
curl -s -X POST https://api.example.com/v1/entities/$ENTITY_ID/intents/$INTENT_ID/authorize \
  -H "Authorization: Bearer $TOKEN"

# Execute
curl -s -X POST https://api.example.com/v1/entities/$ENTITY_ID/intents/$INTENT_ID/execute \
  -H "Authorization: Bearer $TOKEN"

# Read receipt
curl -s https://api.example.com/v1/entities/$ENTITY_ID/receipts/$RECEIPT_ID \
  -H "Authorization: Bearer $TOKEN"

Human obligations

Some actions legally require a natural person — signing formation documents, attesting to tax returns, acknowledging disclosures. When policy evaluation identifies one of these, it blocks the intent and creates an Obligation artifact.

The obligation includes a typed evidence requirement and a unique URL for the human to complete it. Once fulfilled, the intent unblocks and proceeds.

# List pending obligations
GET /v1/entities/{entity_id}/obligations

# Mark obligation as fulfilled
POST /v1/entities/{entity_id}/obligations/{obligation_id}/fulfill

# Waive an obligation (with justification)
POST /v1/entities/{entity_id}/obligations/{obligation_id}/waive

Authority tiers

Policy evaluation checks the intent against three authority tiers:

Tier	Who can execute	Examples
Tier 1	Agent-autonomous	Read operations, compliance checks, report generation
Tier 2	Agent proposes, human approves	Equity issuance, payroll, contract signing
Tier 3	Board resolution required	Dissolution, jurisdiction change, major equity events

An intent submitted at a tier above the agent’s authority is blocked until a human (or board) authorizes it.

Idempotency

The Idempotency-Key concept is baked into receipt creation: Receipt::new requires an idempotency_key string and a request_hash. Retrying a failed network request with the same key returns the existing receipt rather than creating a duplicate operation.