fix(fs): name the path and the cause in fs.read / fs.read_binary errors

[paul-hammant]

Implements asks/fs-read-binary-loses-error-reason.md (from the aeb line; the ask is included in this PR).

The problem

fs.read_binary returned the constant "cannot read file" for every failure — no errno, no path, no kind. Six distinct causes, including sandbox denial and silent truncation, were indistinguishable. fs.read had the same flaw ("cannot open file" / "cannot read file").

Consequence: no Aether program could treat a missing optional file as benign while treating a permission error as fatal. It surfaced in aeb as a 79-target parallel build reporting cannot read file with no path, making an intermittent content-hash failure undiagnosable.

Before / after

Running the ask's own repro:

case	before	after
missing	cannot read file	/tmp/not-here: No such file or directory
directory	cannot read file	/tmp: Is a directory
no perms	cannot read file	/etc/shadow: Permission denied
sandbox denial	cannot read file	/etc/hostname: blocked by sandbox policy (no fs_read grant for this path)

That last row is ask item 3, verified end-to-end by installing a denying checker. A policy refusal is not a filesystem failure — reporting it as one sends whoever is debugging a grant list looking at the disk.

Scope — deliberately what the ask asked for

The ask was explicit that (2) + (3) satisfy it and that an arity change would be an unwanted drive-by. So:

• (bytes, length, err) is unchanged. Callers testing string.length(err) > 0 keep working.
• fs_read_binary_raw's public signature is unchanged. It now records why it is about to return NULL in thread-local state that the tuple wrapper reads back immediately after.
• Not done, per the ask's own scoping: no (bytes, length, kind, err) arity break, no raw errno exposed to Aether, no change to the success path or its @heap ownership contract.

fs.read is composed in Aether from file_open_raw + file_read_all_raw, so it cannot capture errno at the failing step itself. New fs_error_message(path, fallback) formats the current errno with the path for exactly that case.

A second bug, found while testing this

fs.read("/tmp") returned ("", "") — success, no content, no error.

The seekable fast path in file_read_all_raw never checked ferror, so a failed read returned an empty string as success. Reading a directory is the everyday trigger: fopen("/tmp","r") succeeds on Linux and ftell reports a positive size, so control lands there and fread fails with EISDIR.

Same class as #1116, which fixed only the streaming branch. Confirmed pre-existing on main. Arguably worse than the bug I was sent to fix — a bad message misleads, a false success corrupts. A short read with EOF and no error flag (the file shrank mid-read) still returns what was read, as before.

Lifetime contract — documented, because it caught me out

The error string is borrowed from thread-local storage, valid until that thread's next failed read. This matches the existing out._2 contract (the other messages in that tuple are static literals), so nothing changes for callers who print or ignore it.

It is now documented on both wrappers, because the first draft of my own test compared two live messages and was really comparing one buffer with itself — it reported them identical while visibly printing different text.

Verification

• make ci — C suite 230/230; .ae suite 976 passed / 977 total, up from 976 total, confirming the new test is discovered and [PASS] regression_test_fs_read_error_detail. The single failure is integration_http_server_h2, pre-existing on main and separately diagnosed in pesky_bug.md.
• Valgrind — success path clean. The 1-byte-per-call leak remaining on the error path is std.json: json.parse leaks 1 byte per call — empty-string error slot escapes the heap tracker (was: blamed on stringify) #1461 (the empty-string tuple slot), confirmed present on pristine main with the same test, so this change is leak-neutral.
• Success paths unaffected, including the io.read_file / fs.file_read_all_raw silently return "" for /proc, /sys, pipes (size-based read bug) #1116 /proc/self/status streaming case, which the fast-path ferror fix had to avoid breaking.

Test

tests/regression/test_fs_read_error_detail.ae asserts failures name the path, distinct causes give distinct messages, the old constants are gone, and the success paths still work. It deliberately does not assert exact libc wording — strerror text varies by platform and locale, and pinning it would make the test a portability trap.

🤖 Generated with Claude Code