Concept: Effects

Status: shape-only for dispatch; fixture-rehearsed for surfaces. Effect intents (admission into outbox) and effect dispatch (idempotent execution) are wired as fixture flows. Real external dispatch is not operational (see 022 gap report item 12). Closure surfaces and tensions are admitted as fixture objects.

What an effect is

An effect is a structured consequence of an admitted atom that changes what the company must do next. Effects are the bridge from governance to product behavior.

Effects let contracts, insolvency, tax, payroll, banking, refunds, robots, sanctions, and company policies all speak the same operational language.

Effect modes

Standard modes:

RefuseAtCommit
CommitButWarn
RequireEvidence
RequireIntervention
RequireCounterpartyAck
RequireWaitingPeriod
RequireNotification
RequireAdvisorOpinion
RequireExternalAuthority
MarkContested
OpenReviewMatter
OpenClosureSurface

Each mode has a clear meaning in admission terms.

RefuseAtCommit

The atom is refused. No partial commit, no soft warning. Used when a condition is structurally incompatible with the act:

• “Account is sanctions-frozen; payment refused.”
• “License suspended; new contract refused.”

CommitButWarn

The atom is admitted but a warning is recorded with it. Useful for acts that are within authority but unusual:

• “VAT treatment under reservation; recorded.”
• “Standing is provisional pending registry confirmation.”

RequireEvidence

The atom would be admitted if specific evidence were cited. Returned as a refusal with required_evidence populated. The Koerper can gather the evidence and re-submit.

RequireIntervention

The atom requires a signed professional act before it can be admitted:

• “Termination atom requires Kanzlei opinion.”
• “Sensitive payment requires presence approval.”
• “Period close requires Steuerberater attestation.”

The intervention itself is an atom. See advisor-lenses.md.

RequireCounterpartyAck

The atom is admitted but creates an obligation that requires counterparty acknowledgment to fully resolve:

• “Invoice issued; awaiting customer acknowledgment via mesh exchange.”

The counterparty exchange is a future mesh operation (see 022 item 13).

RequireWaitingPeriod

The atom is admitted but cannot produce effects until a specified time elapses:

• “Refund admitted; settlement window opens in 14 days.”
• “Termination admitted; effective date 2026-07-01.”

RequireNotification

The atom requires a notification to be dispatched (often via effect.intent → effect.dispatch):

• “Data subject request received; notify processor.”

RequireAdvisorOpinion

A specific class of RequireIntervention. Used heavily for Steuerberater workflows.

RequireExternalAuthority

The atom requires acknowledgment or filing with an external authority before it is fully effective:

• “Cross-border tax establishment requires FR registration.”

MarkContested

The atom is admitted but marked as contested. Subsequent atoms can cite the contestation:

• “Customer disputes invoice; receivable marked contested.”

OpenReviewMatter

Opens a matter (a bounded engagement) typically for an advisor lens:

• “Period close failed → opens period-close review matter for Steuerberater.”

OpenClosureSurface

Opens a structural object that blocks finality until resolved:

• An invoice opens a receivable closure surface that blocks period close.
• A VAT-relevant transaction opens a VAT closure surface.

See Closure surfaces below.

How an atom emits effects

The capability cited by an atom declares its effect grammar — the set of effects that admitted atoms of this kind may emit. At admission, Gravity validates that the emitted effects are within the declared grammar. If they are not, admission refuses.

This means: you cannot smuggle a stronger effect through an atom by constructing an unusual content payload. The capability defines the ceiling.

Effect intents and the outbox

Some effects represent external acts (sending email, posting payments, notifying counterparties). These are admitted as effect intents into a durable outbox, then dispatched with idempotent attempt records.

The membrane operations:

effect.intent      POST /v1/effects/intent
effect.dispatch    POST /v1/effects/dispatch

Why a separate intent + dispatch step:

• Idempotency. A retried dispatch must not duplicate an external act. The intent carries an idempotency_key; subsequent dispatches for the same key produce attempt records, not duplicate acts.
• Human presence. Sensitive intents may require a human presence receipt before being admitted into the outbox.
• Auditability. The intent atom records who proposed the external act and what was promised. The dispatch attempts record what actually happened externally.
• Reversal. External acts that fail should not silently disappear; the failure is itself a recorded fact.

Effect intent

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",
});

// intent.outcome === "queued"
// intent.body.effectIntent  → effect intent ref
// intent.body.effectOutbox  → outbox ref
// intent.body.effectExecutionClaimed === false  (we have not yet executed)

If human_presence_receipt is missing for a sensitive intent, the membrane refuses with effect_human_presence_required.

Effect dispatch

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

// attempt.outcome === "executed"
// attempt.body.effectAttempt  → attempt ref
// attempt.body.effectReceipt  → effect receipt ref
// attempt.body.externalActDuplicated === false
// attempt.body.rawAdapterPayloadExposed === false

A dispatch can also fail:

const failure = await client.effectDispatch({
  ...,
  fail_fixture: true,
});

// failure.outcome === "failed"
// failure carries an idempotent attempt record

Closure surfaces

A closure surface is a structural object that opens when an atom creates business pressure that must be resolved. Open surfaces block finality.

Examples:

• An invoice atom opens a receivable closure surface. The surface closes when a matching payment observation atom admits, plus (depending on capability) advisor evidence.
• A VAT-relevant transaction opens a vat_period closure surface that closes only when the corresponding VAT filing is admitted.
• A delivery commitment opens a delivery_obligation surface that closes when delivery evidence is admitted.

Closure surfaces are queryable:

const surfaces = await client.tensionQuery({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: "reality:record",
});

// surfaces.body.tensions  → list of open tensions
// each carries the closure surfaces it depends on

The membrane operation closure.surface opens a surface explicitly (rare; usually surfaces open via effect emission):

closure.surface    POST /v1/closure/surface

Tensions

A tension is a first-class object representing an unresolved company-state conflict. Status: open | resolved | scarred.

Examples:

• financial_period_non_closure — period close requested but a receivable surface is unmatched.
• contested_atom — a counterparty disputes a fact.
• evidence_gap — required evidence has not been gathered.
• standing_lapsed — a previously valid standing has expired.

Tensions are queryable via tension.query. They are the primary input to many advisor lenses and to Zeitgestalt explanations.

Effects in projections

Effects emitted by atoms in a projected reality are projected effects:

• A projected invoice opens a projected receivable closure surface.
• A projected closure surface blocks projected period close.
• A projected effect intent does not dispatch externally.

This is why projections are useful: they let you see the full consequence cascade of a hypothetical without binding any of it.

Effects and the AI age

The effect grammar is what makes Gestalt usable by agents. An agent cannot improvise a new effect. An agent must propose atoms whose effects are within their cited capability’s declared grammar. This puts a hard ceiling on what an autonomous workcell can do, regardless of how clever its drafting becomes.

A support.refund.workcell may propose refund atoms whose effects include OpenClosureSurface(refund) and RequireCounterpartyAck. It cannot propose an atom that emits RequireExternalAuthority unless the refund capability declares that effect. The limit is mechanical, not behavioral.

What effects are not

• Not events. Events are notifications. Effects change the admissibility landscape for future atoms.
• Not callbacks. Effects are declared at capability definition time. They are part of the package, not part of an integration hook.
• Not webhooks. External notifications go through effect.intent → effect.dispatch, with idempotency and audit.
• Not workflow steps. Workflows live in Koerpers. Effects live in the Geist.

Where to read next

• Atoms and capabilities
• Realities
• Receipts and proofs
• API: effects
• API: economy — invoice/payment/period-close as effect-bearing operations