# runifold-effect Agent guide
Read ../../AGENTS.md first. This guide adds local boundaries.
## Purpose
Owns: Write-ahead effects, stable replay identity and explicit recovery.
Does not own: Vendor-specific business handlers and guaranteed remote exactly-once delivery.
## Key files and execution path
Start at `src/executor.rs` and follow its module declarations and calls.
- `src/executor.rs`
- `src/handler.rs`
- `src/store.rs`
- `src/record.rs`
## Extension points
Add handler-specific reconciliation through EffectReconciler. Keep durable Started/Completed transitions and observability failure behavior intact.
- RF-EFFECT-003: ambiguous non-idempotent effects cannot be retried without evidence.
- Stable keys bind capability, effect class and canonical input. Completed outcomes replay without handler execution.
Public exports are in the crate entry point. Consult
[the architecture map](../../docs/ai/architecture.md) before crossing a crate boundary.
Tests next to implementation exercise local invariants; `tests/` (where present)
exercises public or protocol boundaries. Keep extensions within this ownership.
## Dependencies
- `runifold-core`: normal
## Invariants and common mistakes
Preserve the root architectural laws. Do not introduce a second execution path,
ambient authority, hidden retry, or vendor wire types into neutral contracts.
Do not infer a public API from historical RFC examples; verify current exports.
Changes to a public contract need a regression test and release documentation.
## Tests to run
```sh
cargo test -p runifold-effect --locked
cargo clippy -p runifold-effect --all-targets --all-features --locked -- -D warnings
```
Database tests may require Docker; see [testing](../../docs/ai/testing.md).
After changing features, dependencies, entry points or recipes, run
`python3 scripts/ai-knowledge.py --write` and `--check` at the workspace root.