voku / agent-edit
Deterministic, evidence-backed source mutation for coding agents: validate, apply transactionally and verify agent-map plans.
Requires
- php: ^8.3
- helgesverre/toon: ^3.1
- nikic/php-parser: ^5.2
- voku/agent-map: ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0
- voku/simple-php-code-parser: ^0.22.14
Requires (Dev)
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- 0.8.1
- 0.8.0
- 0.7.0
- 0.6.4
- 0.6.3
- 0.6.2
- 0.6.1
- 0.6.0
- 0.5.0
- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.0
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.1
- 0.1.0
- dev-ccr-15823ed8-z12v42
- dev-chore/compact-agent-edit-instructions-20261113
- dev-docs/readme-file-guide-20261110
- dev-test/real-refactoring-dogfood
- dev-release/0.6.2-tag
- dev-release/0.6.2-map-compat
- dev-release/0.4.4-marker
- dev-codex/release-security-20261024
- dev-ccr-3d900b81-gjumfz
- dev-claude/decision-link-experiment-qjop8t
- dev-ccr-353e6bd8-g2ugcl
- dev-agent-edit-coding-agent-instructions
- dev-feat/import-residue
- dev-release/0.4.3-marker
- dev-fix/residue-class-removal
- dev-release/0.4.2-marker
- dev-release/0.4.1-marker
- dev-ccr-6f81b111-pl491d-mark-0.4.0
- dev-ccr-6f81b111-pl491d-prepare-0.4.0
- dev-ccr-6f81b111-pl491d-class-removal-executor
- dev-ccr-6f81b111-pl491d-mark-0.3.0
- dev-ccr-6f81b111-pl491d-release-0.3.0
- dev-ccr-6f81b111-pl491d-residue-check
- dev-feat/class-removal-plan-1
- dev-fix/snapshot-crlf-command-output
- dev-release/0.2.2-marker
- dev-release/0.2.2-fixes
- dev-ccr-6f81b111-pl491d-explain-refusals
- dev-ccr-6f81b111-pl491d-refusal-leaves-no-bundle
- dev-release/0.2.1-marker
- dev-release/0.2.1
- dev-ccr-6f81b111-pl491d-lock-two-process
- dev-ccr-6f81b111-pl491d-receipt-write-failure
- dev-ccr-6f81b111-pl491d-mark-0.2.0
- dev-ccr-6f81b111-pl491d-release-0.2.0
- dev-ccr-6f81b111-pl491d-snapshot-tests
- dev-ccr-6f81b111-pl491d-manifest
- dev-ccr-6f81b111-pl491d-mark-0.1.1
- dev-ccr-6f81b111-pl491d-release-0.1.1
- dev-test/publication-rollback-dogfood
- dev-ccr-6f81b111-pl491d
This package is auto-updated.
Last update: 2026-11-20 01:22:12 UTC
README
Deterministic, evidence-backed source mutation for coding agents.
agent-edit is the write plane next to agent-map (the read/planning plane):
agent-map = observe + plan
agent-edit = validate + mutate + verify
agent-loop = authorize + orchestrate
It consumes one already-produced, versioned agent-map plan, revalidates every source hash, inclusive byte range, expected token and plan provenance against the current source and Map, stages and syntax-checks all rewritten PHP, publishes edits and file moves in one transaction (every file is restored on any failure), and then verifies the result against a fresh Map.
It is not an LLM editor, not a workflow engine and not a refactoring recommender. It never calls a model: a quick local fix is authored by the caller as a source_edit_plan (see Direct edits) and proven against the current source like any other plan.
Where to work in this repository
agent-edit applies caller-provided or Map-produced plans, not model-invented refactorings. The implementation responsibilities are separated here:
| Concern | Source of truth |
|---|---|
| Plan parsing and validation | src/Plan/ and src/Capability/ |
| Staging and transactional publication | src/Apply/ and src/EditEngine.php |
| What a dry run shows | src/Preview/ and src/Cli/ |
| Receipts and deterministic verification | src/Receipt/ and src/Verify/ |
| Executable regression coverage | tests/ and composer.json |
The apply/verify result is not a Contract approval and does not create a Git commit, push or PR.
Use
vendor/bin/agent-map build --root=. --paths=src --out=.agent-map/php-symbols.json vendor/bin/agent-map method-move-plan 'App\Foo::helper' 'App\Bar' --format=json > plan.json vendor/bin/agent-edit apply plan.json --dry-run # validate everything, write nothing vendor/bin/agent-edit apply plan.json # transactional apply + receipt bundle vendor/bin/agent-map build --root=. --paths=src --out=.agent-map/php-symbols.json # refresh the map vendor/bin/agent-edit verify --bundle=.agent-edit/receipts/<label>
apply writes execution.json (the receipt) into --output-dir (default .agent-edit/receipts/<label>; --task LABEL sets the label, default plan-<sha256 prefix>). verify re-reads that receipt, the bound plan and the refreshed Map and writes verification-result.json. Each verification attempt first removes the previous result, so a failed attempt cannot leave an earlier passed verdict in the bundle.
Direct edits (quick fixes without a Map)
A Map plan earns its keep when a change reaches other files: renaming a method, moving a class or deleting a symbol needs proven callers, which is what agent-map computes and agent-edit revalidates. A quick local fix (a wrong operator, a missing null check, a README sentence, a new test file) reaches no other file, so demanding a Map for it only adds a step. For those, the caller authors a source_edit_plan@1.0: the exact text it just read and the exact text it wants instead. The plan is still evidence, never authority: agent-edit proves every claim against the current bytes before it writes.
vendor/bin/agent-edit edit src/Calc.php --find='return $a - $b;' --replace='return $a + $b;' # one edit vendor/bin/agent-edit apply - <<'JSON' # several edits / new files {"type":"source_edit_plan","contract_version":"1.0","target_id":"fix-add", "edits":[{"path":"src/Calc.php","find":"return $a - $b;","replace":"return $a + $b;"}], "creates":[{"path":"tests/CalcTest.php","content":"<?php\n..."}]} JSON vendor/bin/agent-edit verify --bundle=.agent-edit/receipts/<label> # no Map needed vendor/bin/agent-edit undo --bundle=.agent-edit/receipts/<label> # restore the recorded pre-images vendor/bin/agent-edit recover --bundle=.agent-edit/receipts/<label> # finish an interrupted publication (see below) vendor/bin/agent-edit schema # JSON Schema of the plan
What agent-edit proves before anything is written (--dry-run stops here):
- Anchors.
findmust occur exactly once (or be picked withoccurrence, or replaced everywhere withall). A refusal says what to do next: the line numbers of an ambiguous match, the line where the same text exists with different whitespace or line endings, or the closest line when the text differs. A multi-linefindwritten with\nalso matches a file whose line breaks are all\r\n(the text is matched and written in the file's own line ending; uniqueness,occurrenceandallapply as usual), but a file that mixes both is not converted (text that occurs there exactly as written still matches). Optionalexpected_source_sha256refuses a file that changed since it was read. - Read-time digests. The transaction always protects the bytes agent-edit itself read while preparing the edit. Only
expected_source_sha256also protects the bytes the agent based its decision on: without it, an edit whose anchor still matches lands on a file that changed in between. An agent that read the code throughagent-map contextalready holds that digest: every source slice carriessource_sha256in exactly this format, so copying it costs nothing. A governed host can require it:ApplyRequest::$requireSourceHashes,--require-source-hashonapplyandedit, orAGENT_EDIT_REQUIRE_SOURCE_HASH=1in the agent's environment refuse any edit of an existing file without a digest (source_hash_required,next_action: add_source_hash), before anything is resolved or written. New files are exempt. Standalone use stays optional. - Syntax. Every rewritten
.phpfile is parsed before anything is staged, so a dry run already refuses a broken result and names its line; every rewritten or created.phpfile is then staged andphp -lchecked; publication is all-or-nothing and every file is restored on any failure. - API changes need caller evidence. A guard compares the declarations before and after. Removing or renaming a class, function, non-private method, non-private class constant, enum case or non-private property, or changing a signature (parameters, types, defaults, visibility) or the shape of a constant or property (visibility, PHP 8.4 setter visibility,
static,readonly,final, declared type; the backing value of an enum case), is refused with a pointer to the matchingagent-mapplan. After checking the callers by other means,"allow_signature_change": true(--allow-signature-change) applies it and records the acknowledged changes in the receipt. Bodies, private members, constant and property values and additions are never reported. - Scope. Unknown keys, absolute or
..paths,.git/and.agent-edit/targets, binary files, symlinks and paths that leave the project root are refused.
Symbol-addressed edits
Exact text is the most general anchor, but for PHP it is also the most fragile: the agent has to copy a whole method byte for byte, including its indentation, to change three lines of its body. An edit can therefore name a declaration instead and let agent-edit find it in the current source ("op" selects the edit kind; without it an edit is the find / replace form above):
{"type":"source_edit_plan","contract_version":"1.0","target_id":"trim names",
"edits":[
{"op":"replace_body", "path":"src/Greeter.php","symbol":"Greeter::greet()","code":"$name = trim($name);\n\nreturn 'Hello ' . $name;"},
{"op":"replace_symbol", "path":"src/Greeter.php","symbol":"Greeter::$count","code":"private int $count = 1;"},
{"op":"insert_member", "path":"src/Greeter.php","symbol":"Greeter","after":"greet()","code":"public function bye(): string\n{\n return 'bye';\n}"},
{"op":"remove_symbol", "path":"src/Greeter.php","symbol":"Greeter::unused()"},
{"op":"add_use", "path":"src/Greeter.php","name":"App\\Model\\User"}]}
- Symbols are
Class,Class::method(),Class::$property,Class::CONSTANT,Enum::CASEorfunction(), with a short or fully qualified class name. An unknown or ambiguous symbol is refused with the list of declarations the file really has. - Code is re-indented to its target and keeps the file's line ending, so it can be written at any indentation (
"reindent": falsekeeps it verbatim). Inreplace_symbolan omitted doc comment or attribute list keeps the existing one; code that brings its own replaces it. replace_bodykeeps the signature;insert_memberadds at the"position"startorend(default), orafter/beforea member, with one blank line of separation;remove_symbolremoves the declaration with its doc comment and attributes and leaves no doubled or dangling blank line;add_useinserts a namespace-level import in sorted position and is a no-op when it already exists.- Like
find, every symbol edit resolves against the file as read, not against the result of earlier edits, and is reduced to the smallest changed byte range: edits of one file must not overlap, and the API guard, syntax check, transaction, receipt andundoapply unchanged.remove_symboldoes not look for callers, so removing a non-private method still needsallow_signature_changeor, better, anagent-mapremoval plan.
The receipt (execution.json) binds the plan hash, Git-observed changed_files and, per file, the digest before and after plus a pre-image under before/. verify re-proves the plan is unchanged, every file still has the published digest, PHP still parses and the observed changed files are exactly the plan's files. undo restores the pre-images and removes created files only while every touched file still has the digest the edit published, so later work is never overwritten; an undone bundle no longer verifies. Files Git ignores (local config, generated code) cannot appear in git status: they are proven by digest only and listed in git_ignored_files_proven_by_digest_only. Without Git the verdict is incomplete / scope_unproven (exit code 3), as for Map plans.
Direct edits and Map plans are complementary, not interchangeable:
| Change | Use |
|---|---|
| Body fix, config/doc text, new file, private-method change | source_edit_plan (edit / apply -), with replace_body, insert_member, add_use ... for PHP |
| Rename, move or remove a class/method/property/constant | the matching agent-map plan, then apply |
| Signature change whose callers you checked yourself | source_edit_plan with allow_signature_change |
Using it from an agent
--format=json makes every apply, edit and verify call one parseable document on stdout (a failure included; nothing is split onto stderr) with the same exit codes as text mode. A dry run shows what would change before anything is written:
vendor/bin/agent-edit apply plan.json --dry-run --diff --format=json # planned_changes + unified diff, no source written vendor/bin/agent-edit edit src/Calc.php --find='a - b' --replace='a + b' --dry-run --diff vendor/bin/agent-edit apply plan.json --task T1 --format=json # changed_files + next_action
A failure looks like this, and error.code is stable:
{"schema_version": "1.0", "command": "apply", "ok": false,
"error": {"code": "anchor_ambiguous", "message": "edits[0]: `find` occurs 2 times in src/Calc.php ...",
"next_action": "disambiguate_anchor", "hint": "Nothing was changed. `find` matches more than once; ...",
"details": {"path": "src/Calc.php", "edit": 0, "matches": 2}}}
error.code |
meaning | next_action |
|---|---|---|
usage, input_not_found |
bad command line, missing file | fix_arguments, provide_input |
plan_malformed, plan_unsupported, plan_refused |
the plan breaks its contract, is not executable, or is blocked/unsafe | replan |
evidence_stale, evidence_changed |
the Map or the source moved since the plan was made | refresh_map_and_replan |
map_backend_unsupported |
the plan needs a PHPStan-backed Map | rebuild_map_with_phpstan |
anchor_missing, anchor_ambiguous, edits_overlap |
a direct edit's text is absent, matches twice, or two edits touch the same text | reread_and_retry, disambiguate_anchor, merge_edits |
source_hash_required |
the host requires expected_source_sha256 and a direct edit has none |
add_source_hash |
api_change_refused |
a direct edit would change a public declaration | use_map_plan_or_acknowledge |
target_exists |
a file to create already exists | edit_existing_file |
apply_failed, failed |
rolled back / not classified | inspect_working_tree, report |
recovery_required |
sources were published but the receipt is missing, or the bundle has a pending publication journal | recover_bundle |
next_action names the only recovery that is legal for that cause; it carries no authority, a caller still decides. A cause that is not classified is reported as failed/report, never guessed from the message. A dry run still writes a prepared receipt bundle (so a host can see the attempt); it never writes source, and its diff is printed, not persisted.
Capabilities
vendor/bin/agent-edit capabilities --format=json vendor/bin/agent-map plan-capabilities --format=json | vendor/bin/agent-edit capabilities --with-map=- vendor/bin/agent-edit instructions --format=json vendor/bin/agent-map plan-capabilities --format=json | vendor/bin/agent-edit instructions --with-map=- --format=text
The second command intersects what Map can plan with what agent-edit can execute: executable, planned_not_executable (a contract Map publishes that agent-edit cannot yet execute) and executable_not_planned. A host should expose only the intersection to a coding agent.
instructions emits a short operating procedure and the plan commands from the same executable capability registry. Without --with-map, it labels the registry as an upper bound; piping current Map capabilities through --with-map=- resolves the exact installed intersection. Hosts can include this output in a coding agent's context instead of maintaining a second, drifting list of executable refactors.
Put --format=text into a coding agent's context. The JSON and TOON forms add machine-readable capability data for hosts (each plan twice: the agent-facing description and the registry record), which an agent does not need. Measured with all 16 plans:
| Form | Bytes | Approx. tokens (bytes / 4) |
|---|---|---|
--format=text |
2,946 | ~740 |
--format=toon |
10,331 | ~2,580 |
--format=json |
16,121 | ~4,030 |
The six rules themselves are about 1,620 bytes in every form. CapabilitiesTest keeps the text form under 3,200 bytes and checks that it carries every rule and plan command of the JSON form. This measures cost only, not whether the rules change what an agent does.
The guidance keeps the boundary explicit: Map proposes a versioned plan, agent-edit validates and applies only that plan, and the host handles arbitrary behavioral edits and their semantic review. It does not add model calls or make agent-edit a free-form editor.
class_removal_plan deletes exactly one whole file: the plan must be safe (no blockers, blind spots or stale evidence), publish no edits or moves, and name the single owned source file with its hash. Apply re-proves the hash, the target's sole declaration and the absence of incoming Map evidence before the file is moved aside, hash-checked and discarded; verify requires the file and class to be gone from a rebuilt Map.
Executable contracts (all @1.0): method|function|class|property|class_constant|parameter_rename_plan, class_move_plan, method_move_plan, method_copy_plan, method_scaffold_plan, method_removal_plan, property_removal_plan, class_constant_removal_plan, class_scaffold_plan, class_removal_plan, and the caller-authored, Map-free source_edit_plan (see Direct edits).
class_scaffold_plan creates exactly one new file through the same all-or-nothing FileTransaction as direct edits: the plan must be safe, publish one file_creation edit and no moves, and the file must be a PHP open tag, optional declare, an optional namespace, use imports and exactly one class, interface, trait or enum named as planned (nothing executable at the top level, checked with the PHP tokenizer). Apply re-proves provenance, that the Map does not already declare the class and that the destination path is free (not even a dangling link) with no symlinked parent leaving the project root; the content is staged and php -l checked, and a failure removes the file and the directories it created. verify requires the file to hold exactly the planned bytes, the observed changed files to be exactly that path and the rebuilt Map to index it. For a new file whose content you author yourself, a source_edit_plan creates entry is the lighter route; the scaffold plan is for a Map-proven, PSR-4-placed declaration.
method_copy_plan and method_scaffold_plan are executable only when Map publishes a safe plan with empty blind-spot, stale and blocker evidence. A copy that refers to $this, self or static across class ownership is review_required, so agent-edit refuses it rather than copying behavior it cannot prove. Both contracts preserve Map's exact insertions and need a PHPStan-backed Map; they do not permit a host to invent a method body or patch the plan by hand.
Package API
voku\AgentEdit\EditEngine is the only authority; agent-edit apply|verify|capabilities are argument/print adapters over it.
$engine = new voku\AgentEdit\EditEngine(); $engine->preflight($plan, $map, $root); // validate everything, write nothing $engine->apply($plan, $map, $root); // mutation lock + transactional apply (no receipt) $receipt = $engine->applyWithReceipt(new ApplyRequest( repositoryRoot: $root, planPath: $planFile, mapIndexPath: $mapFile, mapRoot: $root, outputDirectory: $bundleDir, label: 'my-task', dryRun: false, authorizeMutation: static fn (string $label) => $host->assertMayMutate($label), // must throw to refuse )); $result = $engine->verify($root, $bundleDir, $mapFile); // after rebuilding the Map; writes verification-result.json $undo = $engine->undo($root, $bundleDir, $hostAuthorize); // optional host hook guards the restore too $recovery = $engine->recover($root, $bundleDir, $hostAuthorize); // resolve a pending publication-journal.json
Plan type and contract version are routed only through CapabilityRegistry. Anything it does not list (an unknown type, or a known type with an unknown contract_version) is rejected before any source is read.
Receipt
execution.json inside the bundle is an agent-edit receipt (schema_version 1.0). It binds the plan file hash, Map digest, runner identity and Git-observed changed_files, and is what verify consumes. It is not owned by agent-loop. The names execution.json, task_id (the caller-supplied label) and runner.name are kept for compatibility with hosts that already read them; model_input_tokens/model_tool_calls are always 0.
Without Git the receipt falls back to a Map-scoped observation: before mutating, agent-edit stores map-scope-before.json (path → sha256 for every Map-indexed file, plus the observed absence of preflight-validated move destinations) in the bundle and the receipt references it only by scope_evidence (source, path, sha256) with changed_files_source: map_manifest_diff. This records both sides of a file move. verify recomputes the manifest and diffs it, so an extra changed indexed file outside the plan is an error. It proves only map_indexed_files: the result is status: incomplete with scope.status: scope_unproven (never passed, CLI exit code 3), because a file outside the Map index can change unobserved. With Git the receipt and result are unchanged.
Residue: Markdown and template mentions
The PHP edit of a method_rename_plan, class_rename_plan, method_removal_plan or class_removal_plan is proven by the plan; text that merely mentions the old symbol is not. After the plan-type verifier passes, verify re-scans Markdown and Twig / Smarty / Blade files for the old symbol (with agent-map's NonPhpReferenceScanner) and adds a residue block to verification-result.json: status (clear, open or accepted), open and historical counts, truncated, scanned_files and the first non-historical references (path, line, byte range, confidence, matched text). Mentions in changelog-style files (CHANGELOG, UPGRADING, ...) are counted as historical and never block.
While non-historical mentions remain, an otherwise passed result is status: incomplete (CLI exit code 3), so a governed close cannot pass on top of stale docs. Two ways forward: fix the mentions with a separate cleanup (for example a coding agent working from the listed references) and re-run verify, which re-scans and reports clear; or accept them with --accept-residue=REASON ($engine->verify(..., acceptResidue: 'REASON')), which records the reason in the result as residue.disposition and leaves the verdict passed. The scan matches text, not types, so member_name_only hits (an ->oldName( in a template) can be unrelated; the confidence says how strong each hit is. Other plan types are unchanged.
Residue: orphaned use imports
A removal or move deletes one declaration; the use import that only it needed stays behind, and apply never adds edits the plan did not carry. After method_removal_plan, method_move_plan, property_removal_plan or class_constant_removal_plan, verify therefore lists imports in the edited file whose alias occurred in the deleted text and is no longer referenced (code, comments or docblocks) in an import_residue block. While open, an otherwise passed result is incomplete (exit code 3); remove the imports and re-run verify, or accept with --accept-residue=REASON. Grouped, function and const imports are not judged.
After an authorized mutation attempt fails, applyWithReceipt() first observes the post-rollback working tree and persists a runner_failed receipt before rethrowing the original failure. A host authorization refusal still happens before the mutation attempt and writes no receipt.
A refusal that writes no receipt (dry-run preflight refusal such as a blocked plan, an unsupported plan type or contract version, a host authorization refusal) leaves no bundle directory behind: directories applyWithReceipt() created for the attempt are removed again if they are still empty; a bundle directory that already existed, or that holds any file, is never touched. An authorized mutation attempt that fails keeps its runner_failed receipt.
When the receipt itself cannot be written (unwritable bundle directory, full disk, a blocking path), the apply outcome stays the primary signal and nothing is silent:
| Situation | Behavior |
|---|---|
| Source published, receipt write fails | ReceiptNotPersistedException (changedFiles, outputDirectory, previous = the write error). The transaction committed, so this run cannot undo it. No receipt file exists (never a half-written one), so verify refuses the bundle and a governed close cannot pass. The bundle keeps its publication journal: once the bundle is writable again, agent-edit recover writes the receipt (see below). |
| Evidence cannot be written before publication | The publication journal is written before the first source byte changes; if that fails, nothing is published and a runner_failed receipt records the attempt. |
| Apply failed (rolled back), failure receipt write fails | The original apply failure is rethrown unchanged; the receipt problem never replaces it. |
| Dry run, receipt write fails | The plain write error; nothing was published. |
Crash safety and recover
Before the first source byte changes, under the mutation lock, applyWithReceipt() writes publication-journal.json into the bundle: for every touched path the digest before and after publication (a move is two paths, a deletion or creation has no digest on one side), a pre-image of every existing file under before/, the receipt fields and the pre-publication observation (the git status snapshot, or the Map manifest without Git). The journal is removed only after the receipt is persisted and every journaled path is observed in the state the receipt claims. A journal that survives means publication or its evidence did not finish. Every bundle consumer (apply reusing the bundle, verify, undo) refuses such a bundle until recover has run.
agent-edit recover --bundle=PATH [--format=json] (EditEngine::recover()) compares every journaled path with its recorded digests, under the bundle and mutation locks and after the optional host authorization hook:
| Observed state | Result |
|---|---|
| Every path has its published bytes | published: a runner_succeeded receipt is written (unless one already records it). Its changed_files are observed again by Git (or the stored Map manifest), never taken from the journal, so verify still decides on independent evidence; any unrelated change made in the meantime makes the scope check fail closed. |
| Every path has its original bytes | not_published: a runner_failed receipt records it. |
| A mix of both, or a file a publisher had moved aside | rolled_back: every path is restored from the bundle's pre-images in one transaction (exact recorded bytes), and a runner_failed receipt records the rollback. |
| Any path matches neither digest, or lies outside the project through a moved or linked parent directory | conflict with conflict: unexpected_file (exit code 1): someone else changed it. Nothing is touched and the journal stays; resolve the file by hand and run recover again. |
The bundle already holds a runner_succeeded receipt, but the files are not in their published state |
conflict with conflict: receipt_claims_publication (exit code 1): the process died after the receipt was written and the files were changed afterwards. Nothing is touched. Restoring the original bytes does not resolve this; put the published bytes back (or remove the receipt deliberately) and run recover again. |
| The plan changes no bytes at all | Recorded as published when a success receipt exists, otherwise as not_published. |
Publisher temporary files (*.agent-edit-tx-*, *.agent-edit-plan-*) next to journaled paths are removed in every non-conflict case, but only when they appeared after the journal was written and their bytes are exactly the journaled original or published bytes of that path. A file with a publisher temporary name that already existed when the journal was written is recorded in the journal and never removed or read as a displaced original. A recovered receipt carries a recovery block (attempt, state, rolled_back). attempt binds it to the journal it resolved. If a recovery completed its rollback but lost its result file, running it again keeps that rollback receipt; a rollback receipt left by an earlier attempt on a reused bundle is never mistaken for the current one. When an existing success receipt is kept, the Map manifest it names is restored from the journal if it was lost; a receipt naming a manifest the journal does not hold stops recovery and keeps the journal. A journal entry for an original file without recorded permission bits is refused, so a restore never falls back to a default mode. Otherwise running recover again reports nothing_to_recover. Files outside the journal, such as uncommitted work in progress, are never touched. Restored files get their original permission bits back; pre-images in the bundle are written private (0600).
The bundle must not contain any path the plan publishes; such a plan is refused before anything is written. A bundle outside the project (any outputDirectory applyWithReceipt() accepts) can be recovered by its absolute path. verify and undo hold the bundle lock while they check for a pending journal and read the receipt.
What is and is not promised:
| Failure | Guarantee |
|---|---|
| Exception during publication (failed rename, syntax error, changed source) | Rolled back in-process; runner_failed receipt; no journal left. |
| Rollback itself incomplete | The journal stays; recover finishes the rollback. |
| Receipt cannot be written | The journal stays; recover writes the receipt. |
Process killed (SIGKILL, OOM killer) at any point after the journal is written |
recover reaches a consistent state from the bundle alone. Covered by real-process kill tests at several points of a multi-file publication, for direct edits and Map plans. |
| Process killed before the journal is written | Nothing was published. |
| Power loss or kernel crash | Not guaranteed. The journal and pre-images are flushed with fsync before they are renamed into place, but directory entries are not synced and filesystems differ in what survives. Treat the working tree as unverified and check it with version control. |
Route benchmark
php tools/route-benchmark.php runs the same tasks through each route a coding agent can take and measures the mechanical part of each route; CI runs it with --check. Every route starts from the same task statement, which names the target symbol:
- map+edit: an agent-map plan applied by agent-edit, run for real.
- direct: a
source_edit_planapplied by agent-edit, run for real. - native-ideal: a simulated exact-replace editor that makes no mistakes. It applies the smallest unique old/new pairs for real, so the result is checked, not assumed.
- native-naive: a plausible shortcut: replace
->total()in every file that contains it.
Each result is compared with a hand-written expected tree and executed. The fixture has traps: an unrelated Cart::total() called on the same line as Invoice::total(), a SQL string, an array key and a comment that all contain total.
| Task | Route | Correct | Unrelated files changed | Discovery calls | Bytes read | Bytes authored | Tool calls (per edit / batched) |
|---|---|---|---|---|---|---|---|
rename Invoice::total() (3 call sites, 3 files) |
native-ideal | yes | 0 | 1 | 1,637 | 508 | 9 / 8 |
| native-naive | no (runtime error) | 1 | 1 | 1,637 | 143 | 10 / 9 | |
| map+edit | yes | 0 | 1 | 709 | 107 | 3 / 3 | |
| change one method body | native-ideal | yes | 0 | 0 | 650 | 136 | 2 / 2 |
| direct | yes | 0 | 0 | 1,134 | 305 | 2 / 2 | |
| remove an unused private method | native-ideal | yes | 0 | 1 | 667 | 172 | 3 / 3 |
| direct | yes | 0 | 0 | 1,136 | 217 | 2 / 2 | |
| map+edit | yes | 0 | 1 | 662 | 110 | 3 / 3 |
How the columns are counted:
- Discovery calls: what a route needs beyond the task statement to find the places to change. For a native editor that is a grep; for Map + Edit it is building the map.
- Bytes read: grep output, the files inspected, and the output of every agent-edit and agent-map command run.
- Bytes authored: old and new text, the plan JSON, or the planner command line.
- Tool calls: shown twice:
- per edit, one call per exact replacement;
- batched, with one multi-edit call per file, which hosts that support batching can use.
--check compares every row with tools/route-benchmark.expected.json, and the table above with the measured rows. A change in any number fails CI until it is reviewed and recorded with --write.
What it shows:
- Cross-file rename: Map + Edit. 79 % fewer authored bytes and 57 % fewer read bytes than a perfect native editor, and 3 tool calls instead of 8, even when the native editor batches its edits per file. The plausible native shortcut rewrote the unrelated
Cart::total()calls and broke the code. The benchmark also found that the Map route used to refuse this task, because twototal()calls share a line; agent-map 0.24.0 keeps such calls apart by their byte range. - Local body change: native editing. It is cheaper: the direct plan carries JSON overhead and its result output. Use a direct plan here for its guarantees (receipt,
undo, API guard, read-time digest), not for cost. - Removal: Map + Edit, then native. The Map plan authors the fewest bytes (110) and also proves that nothing calls the method. A native editor needs the whole method as its
oldtext (172 bytes), and still beats a directremove_symbolplan (217 bytes), whose JSON envelope costs more than the method it removes. Direct removal is worth it for the API guard, receipt andundo, not for cost. - Native-ideal is checked, not assumed. Its edits are applied the way an exact-replace tool applies them. Making that real exposed a bug in the benchmark's own edit generator: an earlier version reported 507 authored bytes for this removal, because its edits only appeared correct.
What it does not show is agent effectiveness. It measures no model behaviour: not the tokens an agent spends deciding, not its mistakes and retries, not instruction overhead, and not whether an agent picks the right route unprompted. The native-ideal editor never errs. These numbers are lower bounds for the mechanical part of each route, not productivity. A real-agent comparison is in docs/route-experiment.md. Run 1 (12 in-session runs) hit a ceiling: every arm was correct on every case. Unprompted, agents never used the tools. With guidance, the only use was a direct edit where native editing is cheaper, and no agent used agent-map. Run 2 used harder cases: an interface rename with unrelated same-name methods on the same lines, and a 25-file real-code rename. All 12 runs were again correct, and none used either tool, not even with guidance. Run 3, a rename of 241 sites in 110 generated files, was also correct in every arm: the agents applied the edits in bulk, mostly with throwaway resolver scripts they wrote themselves, instead of using Map + Edit. So far that is no evidence for adding routing or more guidance. Preparing Run 2 did find that interface-method plans could not be applied before agent-edit 0.8.1.
Boundaries
agent-edit owns plan validation, exact edits/moves, transactional publication, rollback, the mutation lock, observed changed files, receipts and deterministic verification, and the executable capability list.
It does not own repository analysis or plan generation (agent-map), task approval/workflow state, LLM routing, briefing, durable task evidence or closeout (agent-loop), and it never commits or pushes.
Validation
composer ci
PHPStan-backed plans need phpstan/phpstan installed so Map can build a +phpstan index.