Write boundary

A requested edit is not enough to authorize a write. ast-mcp requires a route that matches the target's capabilities and proves the caller is operating on current state.

Route selection

Parseable source commonly supports both patch strategies. The agent selects one explicitly; configuration can narrow the effective methods but never silently changes the selection.

Commit sequence

1. Resolve and canonicalize every batch path.
2. Preflight read, write, delete, symlink, and approval policy for the complete batch.
3. Confirm the requested route matches each file's capabilities.
4. Compare every supplied SHA-256 with current state.
5. Build candidates from reviewed ordered operations and parse structural rewrites.
6. Acquire cooperating locks in deterministic path order.
7. Recheck policy, approval, configuration generation, and source hashes inside the lock.
8. Format the candidate according to the resident configuration snapshot without touching live targets.
9. Atomically replace files and release locks on success or failure.

A preview may return a short-lived, one-use receipt bound to the session, source hash, configuration generation, normalized operations, and unformatted strategy candidate. Preview does not run formatters or create formatter staging files. Receipt commit formats that candidate, then writes the formatted result after authorization and freshness checks. A stale hash or receipt, ambiguous Aider block, unexpected AST match count, capped preview, formatter rejection, or lost MCP connection is a safe stop.

Concurrency

In-process queues coordinate calls inside one server. Filesystem lock files coordinate cooperating processes. Sorting multi-file lock acquisition prevents lock-order inversions, and the hash recheck inside the lock closes the race between preview and commit.