[RGB-loop]

Fixes #372. It was closed as completed on 2026-10-21, but it still reproduces on main 8e2fce26; #415 changes another branch of failure() (Capacity) and does not cover this path.

Problem

A write call whose path goes below a regular file or a symlink (/a.txt/x, /dlink/x, where dlink -> dir) is refused as an engine failure:

fs.write / fs.rm / fs.edit / fs.cp / fs.mv  ->  Unknown | Content(WrongLogicalRole)

Mutation::resolve looks a name up under whatever the previous entry was. The content layer answers WrongLogicalRole, and failure() maps that to Unknown. files.rs keeps the Store call Workspace of an Unknown (by design, since its outcome is uncertain). As a result, each such call holds one slot. After as many of them as the Store has call Workspaces (OwnerConfig::default().namespaces, 16), every fs.write/rm/mkdir is refused Failed | Capacity: Store call Workspace capacity. Reads are unaffected and nothing is committed. (From reading files.rs, the slots are only returned when the Store is reopened; I did not run that part.)

The same inputs already get a precise answer elsewhere. fs.mkdir on the write route returns NotDirectory at the blocking entry, and reads return NoSuchPath.

Fix

Mutation::resolve refuses a name below an entry that is not a directory as NotDirectory, with the path of that entry as the message. This is exactly how fs.mkdir answers on the same route. A symlink is not followed, as before. The call becomes a known refusal, so files.rs closes its Workspace. Production change: +6 lines in write/mutation.rs.

Why NotDirectory, not NoSuchPath:

• Mutation::optional reads NoSuchPath as "absent, create it". With NoSuchPath, write /a.txt/x would go on to the create path and fail differently depending on depth.
• NotDirectory matches the existing fs.mkdir answer for the same input on the write route, and POSIX ENOTDIR.

Not changed: a genuinely uncertain Unknown still keeps its Workspace. That custody rule is untouched. This PR only stops a certain refusal from being reported as Unknown.

Tests

layerfs-api/tests/write_refusals.rs::a_write_through_a_non_directory_is_not_directory:

• fs.write, rm, mkdir, edit, cp and mv through a file or a symlink return ("NotDirectory", "<blocking entry>").
• After one pass over all cases, the test makes namespaces + 1 more such calls that are not fs.mkdir (mkdir never keeps a Workspace), then requires a valid fs.write to succeed. Without the fix, these calls use up all 16 Workspaces and that write is refused Capacity.

On main 8e2fce26 without the fix (only the new test added), it fails:

left:  ("Unknown", "Content(WrongLogicalRole)")
right: ("NotDirectory", "/a.txt")

With the fix, it passes.

Run locally on this branch, rebased on main 8e2fce26 (Linux, Rust 1.95.0, --locked --offline, Disposable fixture, no mount):

• cargo test -p layerfs-store-service --all-targets passes.
• cargo test -p layerfs-api --all-targets passes (104 passed, 15 ignored).
• cargo clippy -p layerfs-api -p layerfs-store-service --all-targets --no-deps -- -D warnings -A clippy::result_large_err -A clippy::unnecessary_sort_by passes. The two allowed lints are pre-existing (store_service.rs, examples/issue367_rm_probe.rs); neither is in the changed files.
• rustfmt --check passes on the changed files.

The SDK guide (fs-write.md) now lists NotDirectory among the shared write refusals.

Not checked: the pinned Rust 1.85.1 (not installed here), the whole workspace, cargo fmt --all and the boundary guard. Upstream CI has not run on this branch yet; all results above are local.

Production LOC: 109,056 -> 109,062 (delta +6), tools/production_loc.py --root.

🤖 Generated with Claude Code

[yifanxuaaa]

Merged into main as fbecc17, thanks! #465 moved the crates to engine/, so I rebased your commit onto main (9e3ae56, your authorship kept) and recounted the LOC line (102165 -> 102171, +6 in layerfs-store-service under engine). Checked with the pinned Rust 1.85.1: write_refusals and the related layerfs-api and store-service tests pass, fmt and Clippy -D warnings are clean. This PR's branch still holds the pre-rebase commit, so GitHub shows it as closed rather than merged.