Skip to content

Effect Classes

Every capability in Zakardo declares an effect class — a statement about what side effects the capability produces. Effect classes are the foundation of Zakardo’s governance model.

Effect ClassMeaningGovernanceExamples
READOnly reads data, produces no mutationsNo gates, no outboxList contacts, get analytics, search
WRITE_INTERNALMutates data within the application boundaryLogged, no gate by defaultCreate contact, update deal stage, add note
WRITE_EXTERNALProduces side effects outside the system boundaryOutbox-deferred, audit loggedSend email, call external API, post webhook
DESTRUCTIVEIrreversible operations that destroy dataRequires approval gate by defaultDelete contact, purge records, revoke access

Effect classes have a severity ordering used by the policy engine:

READ < WRITE_INTERNAL < WRITE_EXTERNAL < DESTRUCTIVE

A plan’s overall severity is determined by the maximum severity of its capability invocations. A plan containing a single DESTRUCTIVE capability is treated as destructive for governance purposes.

The combination of effect class and boundary determines the default governance behavior:

Effect ClassLOCALREMOTEUSER_ENV
READNo gateNo gateNo gate
WRITE_INTERNALLogLogLog + Warn
WRITE_EXTERNALOutbox + LogOutbox + GateOutbox + Gate
DESTRUCTIVEGate + LogGate + LogGate + Log

Gate means execution pauses until a human approves. Outbox means the side effect is staged and only committed after all plan steps succeed. Log means the action is recorded in the trace.

In traditional agent frameworks, a tool might call an external API, send an email, or delete a record — and the framework has no way to know. The developer must manually add guardrails for each tool.

In Zakardo, capabilities declare their effects upfront:

const deleteContact: CapabilityDefinition = {
name: 'contacts_delete',
effect_class: 'DESTRUCTIVE', // Runtime knows this destroys data
boundary: 'LOCAL',
// ...
};

This declaration enables:

  • Automatic governance — the policy engine applies appropriate gates without per-capability configuration
  • Planner awareness — the Planner knows which capabilities require approval and can find alternatives
  • Outbox deferral — external writes are automatically staged until the plan succeeds
  • Trust scoring — plans with higher-severity capabilities earn trust more slowly

For capabilities with WRITE_EXTERNAL effect class, Zakardo uses deferred commit:

  1. During execution, external side effects are staged in an outbox (not sent)
  2. If all plan steps succeed, the outbox entries are committed (actually sent)
  3. If any step fails, the outbox entries are discarded (never sent)

This prevents partial execution from producing orphaned side effects — e.g., sending a confirmation email for an order that failed to process.

Zakardo ships with two default policies based on effect classes:

  1. Destructive Approval — Any DESTRUCTIVE capability triggers an approval gate
  2. Audit Logging — Any WRITE_EXTERNAL capability is logged to the trace

Developers can override, extend, or replace these defaults with custom policies. See Policies.