Document native apply_patch duplicate-path and original-hunk ordering constraints
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 88/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- rust
- Domain
- documentation
Research direction
Start with the model-facing tool description in codex-rs/core/src/tools/handlers/apply_patch_spec.rs, then review the duplicate-path guard in codex-rs/apply-patch/src/invocation.rs and hunk-order notes in parser.rs. Add the three constraints and recovery guidance without changing validation or approval-preview behavior; verify the documented examples remain consistent with the existing native apply_patch behavior.
Written by the indexing model from the issue text.
Description
What is the type of issue?
Documentation is missing from the model-facing native apply_patch contract.
What is the issue?
The native freeform tool accepts a grammar that permits repeated file paths and update hunks in any order, but runtime verification imposes additional semantic constraints that the tool description does not explain:
- A path can be the target of only one file operation in a patch. Put multiple edits to a file in one
*** Update Fileblock. - Update hunks match the original file, in forward file order. A later hunk cannot match a line inserted by an earlier hunk.
These are reasonable constraints; this report requests model-facing guidance and actionable recovery text, not relaxed matching or duplicate-operation execution.
An aggregate 30-day local audit classified 83 failed patch calls as duplicate file operations. A broader 1,607 failures said expected source lines were missing, but I have not attributed those to hunk ordering; stale source and other causes remain possible. No private patch contents or chat identifiers are included.
Minimal reproductions
Start each trial with fixture.txt containing:
alpha
middle
omega
A. Repeated path (native verifier rejects multiple operations target ...):
*** Begin Patch
*** Update File: fixture.txt
@@
-alpha
+ALPHA
*** Update File: fixture.txt
@@
-omega
+OMEGA
*** End Patch
B. Reverse original-file order (fails to find alpha, although it exists):
*** Begin Patch
*** Update File: fixture.txt
@@
-omega
+OMEGA
@@
-alpha
+ALPHA
*** End Patch
C. Matching a line introduced by the preceding hunk (fails to find ALPHA):
*** Begin Patch
*** Update File: fixture.txt
@@
-alpha
+ALPHA
@@
-ALPHA
+ALPHA AGAIN
*** End Patch
Working control: one update block, original content, forward order:
*** Begin Patch
*** Update File: fixture.txt
@@
-alpha
+ALPHA
@@
-omega
+OMEGA
*** End Patch
The working control produced the expected three lines, with the first and last capitalized. Rejected trials left the fixture unchanged. These trials used the native apply_patch tool in Codex Desktop, bundled backend 0.159.0-alpha.12.1, macOS arm64.
Where did you find it?
Current public source inspected at 6326163b9abd7802c0e57be4e326e5f898bbba75:
- Model-facing freeform tool description explains only freeform input and avoiding JSON wrapping.
- Lark grammar constrains syntax but cannot express these file-content/path relationships.
- Duplicate-path runtime guard.
- Parser's internal hunk-order documentation.
- Original-file matching implementation.
Suggested acceptance criteria
Add the three short rules to the model-facing tool description or an always-loaded native patch instruction. For a duplicate target, suggest combining edits into one file block. For a failed hunk, suggest refreshing the original source and preserving forward hunk order. Keep existing validation and approval-preview behavior.
This concerns Codex's native freeform format, not the separate Responses API structured apply-patch operation format. I searched for matching duplicate-path and hunk-order documentation reports; #14424 concerns physically squashed patch lines instead.
- Dominant language
- Rust
- Stars
- 127k
- Forks
- 19.9k
- Avg merge
- 1m
- Merged PRs (30d)
- 994
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from openai/codex
-
app bug windows-os
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
Maintainers usually reply within 1 day
-
app-server bug CLI
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
openai/codex#51152 · 1 comment ·
Maintainers usually reply within 1 day
-
app bug
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
openai/codex#51001 · 1 comment ·
Maintainers usually reply within 1 day
-
bug tool-calls
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
app bug dots mcp windows-os
Difficulty 2/5 Under an hour Newbie friendliness 75/100
openai/codex#50982 · 1 comment ·
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 80/100
Devolutions/picky-rs#546 · 1 comment ·
Maintainers usually reply within 3 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Maintainers usually reply within 1 day
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
zcashlabs/thus-spoke-zakura#153 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 79/100
topgrade-rs/topgrade#2395 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
matrix-org/matrix-rust-sdk#7217 ·
Maintainers usually reply within 1 day