Skip to content
Gestalt

API: Intents and commits

Capability state: fixture-rehearsed. intent.precheck is wired through Gravity in crates/gestalt-cloud. intent.commit walks an end-to-end fixture flow with durable atom commit journal (recent commit 9d3570e).

The intent operations are the most basic membrane crossing: a vessel proposes an act, the cloud Geist either admits, refuses, or pends.

intent.precheck

Section titled “intent.precheck”

Predict whether a proposed intent would pass admission, without attempting to commit.

POST /v1/intents/precheck
runtime_owner: cloud_geist
sdk_role: construct request and verify receipt
request_record: CloudIntentPrecheckRequest

Request

Section titled “Request”
interface IntentPrecheckRequest {
  tenant: GestaltRef;       // e.g. "tenant_node:rheinwerk_calibration"
  capability: GestaltRef;   // e.g. "capability:issue_invoice_fixture_v1"
  action: string;           // e.g. "issue"
  evidence: GestaltRef[];   // evidence_bundle:* refs
  fixture?: boolean;        // marker; cloud is fixture-only today
}

Response

Section titled “Response”

MembraneResponse<unknown> with one of these body shapes:

Refused (most common when evidence is missing):

{
  "operation": "intent.precheck",
  "outcome": "refused",
  "body": {
    "failedGate": "required_evidence_missing",
    "missingEvidence": ["invoice_payload"]
  },
  "receipt": {
    "ref": "receipt:fixture_precheck_refusal",
    "outcome": "refused",
    "reasons": ["fixture precheck requires invoice_payload"],
    "fixture": true
  }
}

Pending action:

{
  "operation": "intent.precheck",
  "outcome": "pending",
  "body": { "pendingAction": "pending_action:..." },
  "receipt": {...}
}

Admitted preview (would admit if committed):

{
  "operation": "intent.precheck",
  "outcome": "verified",
  "body": { "admissible": true, "previewedEffects": [...] },
  "receipt": {...}
}

SDK example

Section titled “SDK example”
const response = await client.precheckIntent({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:issue_invoice_fixture_v1",
  action: "issue",
  evidence: ["evidence_bundle:invoice_payload"],
});

intent.commit

Section titled “intent.commit”

Submit a standing-bound intent for actual admission.

POST /v1/intents/commit
runtime_owner: cloud_geist
sdk_role: submit standing-bound intent
request_record: CloudIntentCommitRequest
responses: atom | refusal | pending_action | receipt

Request

Section titled “Request”

CloudIntentCommitRequest (server-side type) — broadly the same shape as the precheck request plus signing posture and additional context. The TS SDK wraps this through the contract; for explicit construction see crates/gestalt-cloud/src/lib.rs.

Response

Section titled “Response”

MembraneResponse<unknown> with one of:

Admitted — atom committed:

{
  "operation": "intent.commit",
  "outcome": "admitted",
  "body": { "atom": "atom:01H...", ... },
  "receipt": {...}
}

Refused — structured refusal.

Pending — pending action created.

Outcomes

Section titled “Outcomes”
admitted    atom committed; receipt carries the atom ref
refused     structured refusal
pending     pending action awaits a higher signing posture

Refusal codes you may see

Section titled “Refusal codes you may see”
required_evidence_missing
authority_package_missing
authority_package_stale
standing_missing
standing_stale
capability_unrecognized
capability_superseded
session_expired
session_tampered
scope_mismatch
cross_tenant_access

Full list in ../reference/refusal-codes.md.

Section titled “Where to read next”