# Hash-edit agent guide
Anchored patches are parsed, prepared against snapshots, then committed through tool filesystem policy.
## Where to look
| Patch envelope and syntax | `input.rs`, `parser.rs`, `tokenizer.rs`, `model.rs` |
| Line and block operations | `apply.rs`, `block.rs`, `normalize.rs` |
| Stale tags and retained snapshots | `recovery.rs`, `snapshots.rs` |
| Preparation, locking, commit, metadata | `tool.rs` |
| Diagnostic text | `format.rs` |
## Local contracts
- Address operations against the original tagged snapshot, not line numbers shifted by earlier operations. Preserve overlap/range validation and block-selection rules.
- Resolve targets, reject duplicate targets, acquire mutation and cross-process locks, then prepare all sections before committing. Preparation failure must not write earlier sections.
- Multi-file patches are not all-or-nothing transactions: a later commit failure can leave earlier sections written. Preserve per-file status, changed paths, and partial-commit metadata.
- A failed result can still represent a mutation. Keep `committed_but_undurable` distinct from success and preserve `destination_written_source_retained` for undurable move destinations. Move removal/rollback failures also need accurate changed-path reporting.
- Stale-tag recovery uses retained snapshots and checked remapping. Preserve recovery warnings and metadata; do not add silent fuzzy matching.
- Restore BOM and line-ending shape through `tool.rs`; do not persist normalized snapshot text directly.
- Preserve path checks, final-symlink rejection, locks, and atomic-write error handling on write/move/remove routes.
- Keep recovery snapshots and diagnostics bounded. Syntax or recovery-marker changes require matching schema/prompt coverage in the parent layer.
Use module tests and `../tests/edit_write.rs` for original-line addressing, stale recovery, and write-failure regressions.