Core Concepts

Transaction Lifecycles

Four worked flows that show how a sentence travels the wire end to end — from an auto-committing read to a parked critical action, an ambiguous resolution, and a human override.

Low-tier, auto-commit

A read or a trivially-safe write floors at LOW and commits without a human in the loop. The two-phase shape still holds — the runtime proposes, receives a preview, and commits idempotently — but no approval gate interrupts it.

low-tier lifecycle

# 1. PROPOSE — no side effects
{ "performative": "PROPOSE",
  "body": { "verb": "commerce.get_product", "args": { "sku": "SKU-1042" } } }

# 2. PROPOSAL — tier LOW, preview returned
{ "performative": "PROPOSAL",
  "body": { "outcome": "preview", "tier": "LOW", "proposal_id": "prop_1a" } }

# 3. COMMIT — executes immediately, idempotent
{ "performative": "COMMIT",
  "body": { "proposal_id": "prop_1a", "idempotency_key": "read@run_9" } }

High-tier, out-of-band approval

When the resolved facts cross a threshold — here an order over 1,000 SAR — the profile floors the tier at HIGH and the runtime parks the proposal. The owner approves on a separate credential; only then does the commit run.

high-tier lifecycle

# PROPOSAL parks at HIGH — awaiting a DECIDE
{ "performative": "PROPOSAL",
  "body": { "outcome": "preview", "tier": "HIGH", "proposal_id": "prop_2b",
            "preview": { "en": "Create purchase order for SAR 1,250.00" } } }

# Owner approves out of band, on a separate credential
{ "performative": "DECIDE",
  "body": { "proposal_id": "prop_2b", "decision": "approve" } }

# Only now does the runtime COMMIT
{ "performative": "COMMIT",
  "body": { "proposal_id": "prop_2b", "idempotency_key": "po@run_9" } }

Credential separation

The DECIDE that approves a parked proposal runs on a credential the speaker does not hold. Approval is never self-service.

Ambiguous resolution

The agent said “refund Mohammed’s last order,” but three customers match. The system does not guess — it returns an AMBIGUOUS refusal (200 OK) with up to eight candidates. The agent (or a human) re-proposes with the resolved id.

AMBIGUOUS refusal

{ "performative": "PROPOSAL",
  "body": {
    "outcome": "refusal", "code": "AMBIGUOUS",
    "message": "3 customers match 'Mohammed'. Choose one.",
    "candidates": [
      { "id": "cust_11", "label": "Mohammed Al-Otaibi", "hint": "Riyadh" },
      { "id": "cust_22", "label": "Mohammed Said",       "hint": "Jeddah" },
      { "id": "cust_33", "label": "Mohammed Trading",    "hint": "Dammam" }
    ]
  } }

Suspension & human override

If a grant or workspace is suspended mid-flight, an in-progress commit refuses with SUSPENDED rather than proceeding optimistically. A parked action can also be overridden by a human: an owner may DECIDE to reject, or approve with a modification limited to the facts the profile marks modifiable. The runtime routes on the outcome — on_approved, on_rejected, or on_timeout — and the whole sequence lands in the append-only audit log.

Governed reversal

To undo a committed action, the speaker sends a ROLLBACK with the compensation_token from the original EVENT. The system answers with a PROPOSAL — a compensation preview — which is committed like any other action for a COMPENSABLE verb, or refused with IRREVERSIBLE when no reversal exists. A reversal is always shown before it happens.