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.
The Four Effect Classes
Section titled “The Four Effect Classes”| Effect Class | Meaning | Governance | Examples |
|---|---|---|---|
READ | Only reads data, produces no mutations | No gates, no outbox | List contacts, get analytics, search |
WRITE_INTERNAL | Mutates data within the application boundary | Logged, no gate by default | Create contact, update deal stage, add note |
WRITE_EXTERNAL | Produces side effects outside the system boundary | Outbox-deferred, audit logged | Send email, call external API, post webhook |
DESTRUCTIVE | Irreversible operations that destroy data | Requires approval gate by default | Delete contact, purge records, revoke access |
Severity Ordering
Section titled “Severity Ordering”Effect classes have a severity ordering used by the policy engine:
READ < WRITE_INTERNAL < WRITE_EXTERNAL < DESTRUCTIVEA 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 Governance Matrix
Section titled “The Governance Matrix”The combination of effect class and boundary determines the default governance behavior:
| Effect Class | LOCAL | REMOTE | USER_ENV |
|---|---|---|---|
READ | No gate | No gate | No gate |
WRITE_INTERNAL | Log | Log | Log + Warn |
WRITE_EXTERNAL | Outbox + Log | Outbox + Gate | Outbox + Gate |
DESTRUCTIVE | Gate + Log | Gate + Log | Gate + 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.
Why Explicit Declaration Matters
Section titled “Why Explicit Declaration Matters”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
The Deferred Outbox Pattern
Section titled “The Deferred Outbox Pattern”For capabilities with WRITE_EXTERNAL effect class, Zakardo uses deferred commit:
- During execution, external side effects are staged in an outbox (not sent)
- If all plan steps succeed, the outbox entries are committed (actually sent)
- 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.
Default Policies
Section titled “Default Policies”Zakardo ships with two default policies based on effect classes:
- Destructive Approval — Any
DESTRUCTIVEcapability triggers an approval gate - Audit Logging — Any
WRITE_EXTERNALcapability is logged to the trace
Developers can override, extend, or replace these defaults with custom policies. See Policies.
Further Reading
Section titled “Further Reading”- Capabilities — the full anatomy of a capability definition
- Policies — writing custom governance rules
- Execution Engine API — how gates and outbox work at runtime