Skip to content

Make the pages state what the std file tools do - #24

Merged
vinniefalco merged 1 commit into
cppalliance:masterfrom
vinniefalco:master
Nov 18, 2026
Merged

vinniefalco merged 1 commit into
cppalliance:masterfrom
vinniefalco:master

Conversation

@vinniefalco

@vinniefalco vinniefalco commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

The decision pages describe the std Pack, and the review of cppalliance/runvil-plugin-std#2 changed a few things that the pages did not follow. This brings two pages back in line with the merged code. It changes two Markdown files under decisions/ and no code.

What the pages say now

decisions/tools-and-packs.md, in the entry on the std file tools:

decisions/files-and-the-vfs.md:

  • The paragraph on the known gap links issue 4. The sentence that says whether to add a contract function is the owner's to decide is unchanged.

Two new items under Planned work

Both are in the "Undecided" form that the list already uses, and each ends with "The owner has yet to decide on it."

  • A removal in the contract that takes a file only, so that Delete needs no stat before it (issue 3).
  • A way in the contract for a tool to edit a file without losing another task's change (issue 4).

These two items were not asked for by name. Remove them if the list should hold decided work only.

Checks

  • Only decisions/tools-and-packs.md and decisions/files-and-the-vfs.md change. Nothing under plan/ changes.
  • No quote of the owner changed: the quoted strings of each page are the same before and after, 25 in tools-and-packs.md and 43 in files-and-the-vfs.md.
  • node --test tools/docs-claims.mjs passes, 3 of 3. That tool does not read decisions/, so the new text was compared with the std code at a806bf6 by hand.
  • Every other statement about std and bash in the eight pages was compared with the merged code, and none was found false.

Summary by CodeRabbit

  • Documentation
    • Clarified how text replacement counts matches, handles overlapping occurrences, and reports failures, including when an edit would exceed the size limit.
    • Documented that file-tool operations are performed in order but may not prevent lost edits when another task changes a file between reading and writing.
    • Clarified that directory deletion may remove an empty directory created between inspection and removal.
    • Updated planned-work notes to reflect these file-editing and deletion behaviors.

The pages describe the `std` Pack, and the merged code of that Pack does more than two pages said about `StrReplace` and `Delete`. `tools-and-packs.md` said that a failure of `StrReplace` states how many times the text occurs, and it said nothing about the time between the two requests of `Delete`. The two pages now state each failure of `StrReplace`, the directory that `Delete` can remove, and the two issues that track the open gaps, and the diff changes no code.

- `tools-and-packs.md` says that a failure of `StrReplace` states the count when the text occurs zero times, or more than once without `replace_all`. The count is of the occurrences that do not overlap, from the start of the file, and a call with `replace_all` replaces those.
- The page says that a text that starts at more than one place does not occur once, even where the places overlap. When the count for such a text is one, a call without `replace_all` is refused, and that failure states no count.
- The page says that `StrReplace` refuses an edit that would leave the file over 16 MiB, before it builds the edited text.
- The page said that `Delete` asks what the path names before it asks for the removal. It now also says that the two are requests of their own, so a directory with no entries that another task puts at the path between them is removed, and that a directory with entries is never removed. cppalliance/runvil-plugin-std#3 tracks a removal in the contract that takes a file only.
- The lost edit of `StrReplace` gets the link cppalliance/runvil-plugin-std#4 in `tools-and-packs.md` and in `files-and-the-vfs.md`. The words of `files-and-the-vfs.md` on the decision of the owner stay as they are.
- The list of planned work in `tools-and-packs.md` gets two items that start with the word "Undecided": a removal that takes a file only, and an edit that keeps the change of another task. Each item ends with the sentence that the owner has yet to decide on it.
- Each quote in the two pages is the same: 25 quoted strings in `tools-and-packs.md` and 43 in `files-and-the-vfs.md`, before and after.
- The diff changes two Markdown files and adds no test.
Copilot AI balanced review requested due to automatic review settings November 18, 2026 20:40

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

Walkthrough

The decision documents now describe file-tool ordering and concurrent-edit behavior, StrReplace matching and size limits, and a Delete race involving separate inspection and removal requests. They also record planned contract changes for the Delete and StrReplace cases.

Changes: File Tool Contracts

Layer / File(s) Summary
Document file-tool behavior
decisions/files-and-the-vfs.md, decisions/tools-and-packs.md
The documents describe how read-then-write edits can lose intervening changes, StrReplace matching and its 16 MiB size check, and how Delete’s separate requests can remove a newly created empty directory. Planned-work entries describe possible contract changes for these cases.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

  • cppalliance/runvil-harness#19: Adds explicit Engine VFS effects and ToolFiles to the Pack API, which relate to the file-tool behavior documented here.
Merge Risk: Minimal · up to ee199

This documentation-only change clarifies how the std file tools behave, including StrReplace matching and size limits and Delete's separate requests. It does not change runtime behavior and carries no identified merge risk.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@vinniefalco
vinniefalco merged commit ee199e3 into cppalliance:master Nov 18, 2026
10 of 11 checks passed

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The StrReplace overlap/count and preallocation-limit guarantees need confirmation against runvil-plugin-std at a806bf6, which is outside this checkout and unavailable through the provided tools.

No open issues 🎉

What changed in this PR

Updates two decision pages to reflect the merged std Pack’s file-tool behavior. This is documentation-only; no code changes.

Changes:

  • Clarifies StrReplace’s occurrence counting, overlapping matches, and 16 MiB output limit.
  • Documents Delete’s directory-removal race and links both known file-operation gaps to tracking issues.
  • Adds explicitly undecided contract improvements for file-only removal and edits that preserve concurrent changes.
File Description
decisions/​tools-and-packs.md Clarifies file-tool behavior and records two undecided contract improvements.
decisions/​files-and-the-vfs.md Links the existing lost-edit gap to its tracking issue.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants