clash-verge-rev/src-tauri/AGENTS.md

Backend Architecture Guardrails

These rules supplement the repository's root AGENTS.md.

1. Keep configuration ownership in config. Configuration writes must use its draft and persistence APIs. Patch orchestration must use feat/effects.rs and feat/executor.rs; refresh notifications must use core::notify::announce after successful persistence and commit. This keeps failed transactions from publishing state. Independent transactions retain their boundaries and announce via after_commit; runtime-only profile activation announces after successful application. New cross-layer exceptions require a rationale in the PR and an update to this file.
2. Register every new IVerge field. Add one row, including an explicit NoEffect where appropriate, to the exhaustive registry and preserve its platform attributes. Keep the serialized-field coverage test passing. Manual field-to-flag chains hide missing effects and are forbidden. No exceptions.
3. Use utils::retry for bounded retries. Do not introduce handwritten retry loops, including loop plus sleep; preserve attempt budgets, delays and terminal errors. Permanent watchers are the exception and must document their exit conditions. Traversal of distinct data or port candidates is not a retry policy.
4. Keep notifications typed. Send notice statuses through NoticeStatus and use Arc<str> for notice message payloads. Preserve the event names and status strings pinned by the golden tests. Status additions or changes require frontend and backend changes in the same PR and an updated golden list; this protects the wire contract. No exceptions.
5. Preserve lock order. The order is config_write before config_update_in_progress before lifecycle_lock. Patch callers must use the executor's guarded claim instead of independently combining these locks; this preserves Busy rejection and prevents inverted acquisition. Existing lifecycle and independent port transactions keep their established locking boundaries. A new lock requires registering its position in this rule before introducing acquisition sites.
6. Prefer reconciliation. Express new effects as idempotent ensure operations in EFFECT_ORDER so repeated application converges on the same state. A trigger chain is an exception only with a code comment explaining why the operation cannot be idempotent. Configuration rollback does not authorize reverse OS effects.