# 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. Cross-layer operations
   must preserve these ownership and transaction boundaries.
2. **Register every new `IVerge` field.** Register the field in the
   exhaustive effect registry, including an explicit `NoEffect` where
   appropriate, and preserve its platform attributes. Manual field-to-flag
   chains hide missing effects and are forbidden.
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 as a shared wire contract. Contract changes must keep
   frontend consumers and backend producers aligned.
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.