Skip to content
Gestalt

API: Effects

Capability state: effect.intent is staging-durable; effect.dispatch is fixture-rehearsed. Real external dispatch is not operational (see 022 gap report item 12).

The effect operations admit external acts (sending email, posting payments, notifying counterparties) into a durable outbox and dispatch them with idempotent attempt records. See concepts: effects.

effect.intent

Section titled “effect.intent”

Admit a sensitive effect into a durable outbox without claiming external execution.

POST /v1/effects/intent
state: staging-durable
sdk_role: admit a sensitive effect into a durable outbox without claiming external execution
request_record: CloudEffectIntentRequest
responses: effect_intent | effect_outbox | refusal | receipt

Request

Section titled “Request”
interface EffectIntentRequest {
  tenant?: GestaltRef;
  subject?: GestaltRef;
  effect_kind?: string;          // e.g. "send_invoice_email"
  adapter?: string;              // e.g. "fixture_email_adapter"
  mode?: string;                 // e.g. "fire_and_record"
  idempotency_key: string;
  evidence?: GestaltRef[];
  human_presence_receipt?: GestaltRef;
  dry_run?: boolean;
}

Response

Section titled “Response”
{
  "operation": "effect.intent",
  "outcome": "queued",
  "body": {
    "effectIntent": "effect_intent:fixture",
    "effectOutbox": "effect_outbox:fixture",
    "effectExecutionClaimed": false,
    "rawAdapterPayloadExposed": false
  },
  "receipt": {...}
}

effectExecutionClaimed: false — the intent is queued, not executed. rawAdapterPayloadExposed: false — no adapter-internal data is returned through the membrane.

SDK example

Section titled “SDK example”
const intent = await client.effectIntent({
  tenant: "tenant_node:rheinwerk_calibration",
  subject: "company_geist:rheinwerk_calibration",
  effect_kind: "send_invoice_email",
  adapter: "fixture_email_adapter",
  mode: "fire_and_record",
  idempotency_key: "invoice-2026-04-001-email",
  evidence: ["evidence_bundle:invoice_payload"],
  human_presence_receipt: "human_presence_receipt:fixture_private_presence",
});

Refusal codes

Section titled “Refusal codes”
effect_human_presence_required
effect_idempotency_key_collision
effect_capability_grammar_violation
effect_adapter_unknown
required_evidence_missing

If the intent is for a sensitive effect and no human presence receipt is cited, the membrane refuses with effect_human_presence_required. This enforces that sensitive external acts have a human-attested trigger.

effect.dispatch

Section titled “effect.dispatch”

Dispatch a queued fixture effect with idempotent durable attempt and receipt records.

POST /v1/effects/dispatch
state: fixture-rehearsed
sdk_role: dispatch a queued fixture effect with idempotent durable attempt and receipt records
request_record: CloudEffectDispatchRequest
responses: effect_attempt | effect_receipt | refusal | receipt

Request

Section titled “Request”
interface EffectDispatchRequest {
  tenant?: GestaltRef;
  effect_intent?: GestaltRef;
  idempotency_key?: string;
  fail_fixture?: boolean;       // for testing the failure path
}

Response

Section titled “Response”

Executed:

{
  "operation": "effect.dispatch",
  "outcome": "executed",
  "body": {
    "effectAttempt": "effect_attempt:fixture",
    "effectReceipt": "effect_receipt:fixture",
    "externalActDuplicated": false,
    "rawAdapterPayloadExposed": false
  },
  "receipt": {...}
}

Failed (idempotent record):

{
  "operation": "effect.dispatch",
  "outcome": "failed",
  "body": {
    "effectAttempt": "effect_attempt:fixture",
    "effectReceipt": "effect_receipt:fixture",
    "externalActDuplicated": false
  },
  "receipt": {...}
}

A failed outcome carries an idempotent attempt record; subsequent dispatches with the same idempotency key produce additional attempt records, not duplicate external acts.

SDK example

Section titled “SDK example”
const attempt = await client.effectDispatch({
  tenant: "tenant_node:rheinwerk_calibration",
  effect_intent: intent.body.effectIntent,
  idempotency_key: "invoice-2026-04-001-email",
});


if (attempt.outcome === "executed") {
  // external act recorded as performed
} else if (attempt.outcome === "failed") {
  // external act attempted but failed; the failure is recorded
}

Capability grammar enforcement

Section titled “Capability grammar enforcement”

Effects must be within the cited capability’s declared effect grammar. You cannot smuggle a stronger effect by constructing an unusual content payload — Gravity refuses with effect_capability_grammar_violation at admission time.

Idempotency

Section titled “Idempotency”

effect.intent requires idempotency_key. Repeating the same key for the same subject is rejected (effect_idempotency_key_collision). This is what lets a Koerper safely retry an intent without producing multiple outbox entries.

effect.dispatch retries record additional attempts under the same effect_intent. The external system is contacted at most once per attempt; the attempt records are durable.

Section titled “Where to read next”