module.ae

// std.fs - File System Module
// Import with: import std.fs
//
// Note: fs is otherwise extern-only (no std.string import) to stay a thin
// syscall layer. find_ext is the exception — it produces a string result and
// accumulates it with std.strbuilder (leak-free across the C walk callback).
//
// Provides file, directory, path, glob, and copy/move/realpath/chmod
// operations.
//
// API shape:
//   - Raw externs end in `_raw` and return ptr/int in the old C-style
//     convention. They are the escape hatch for advanced callers.
//   - Aether-native wrappers (below) use Go-style `(value, err)` tuple
//     returns and are the idiomatic way to call fs operations.
//   - The newer wrappers `copy`, `move`, `realpath`, `chmod` ship the
//     structured-error pilot from issue #392 — they return
//     `(value, kind, message)` so callers can switch on the `KIND_*`
//     enum below without parsing English. The pilot sits *next to*
//     the (value, err) shape, not in place of it; every existing
//     wrapper keeps its (value, err) or string-error return.
//
// Performance: `copy` zero-copies via the OS's best primitive
// (copy_file_range / sendfile / fcopyfile / CopyFileExW); falls back
// to an 8 MiB read/write loop on filesystems that reject the kernel
// primitives. `move` is rename(2) with transparent EXDEV →
// copy + unlink fallback. See aether_fs.c for the full hierarchy.

import std.strbuilder

exports(
    file_open_raw, file_close_raw, file_read_all_raw, file_write_raw,
    file_exists, file_delete_raw, file_size_raw, file_mtime,
    dir_exists, dir_create_raw, dir_delete_raw, dir_list_raw,
    fs_mkdir_p_raw,
    fs_symlink_raw, fs_hard_link_raw, fs_readlink_raw, fs_is_symlink, fs_is_socket, fs_unlink_raw,
    fs_make_temp_dir_raw, fs_make_temp_file_raw,
    make_temp_dir, make_temp_file,
    STAT_KIND_FILE, STAT_KIND_DIR, STAT_KIND_SYMLINK, STAT_KIND_OTHER,
    STAT_KIND_SOCKET, STAT_KIND_FIFO, STAT_KIND_DEVICE,
    WALK_CONTINUE, WALK_SKIP_SUBTREE, WALK_STOP,
    fs_rename_raw,
    fs_try_stat, fs_get_stat_kind, fs_get_stat_size, fs_get_stat_mtime,
    fs_try_statvfs, fs_get_statvfs_total, fs_get_statvfs_free, fs_get_statvfs_avail,
    statvfs,
    fs_try_mounts, fs_get_mount_count,
    fs_release_mounts,
    mounts, mount_source, mount_point, mount_fstype, mount_options,
    fs_try_block_info, fs_get_block_size_bytes, fs_get_block_removable,
    fs_get_block_transport, block_info,
    fs_try_read_binary, fs_get_read_binary, fs_get_read_binary_length,
    fs_release_read_binary, fs_read_binary_tuple,
    dir_list_count, dir_list_get, dir_list_kind, dir_list_free,
    path_join, path_dirname, path_basename, path_extension, path_is_absolute,
    path_separator,
    clean, is_within_base, rel, join_clean, first_element,
    fs_pread_raw, fs_pread_into_raw, fs_get_pread, fs_get_pread_length,
    fs_release_pread, fs_ftruncate_raw, fs_fsync_raw,
    pwrite, pread, pread_into, ftruncate, fsync,
    file_fd_raw, fd,
    fs_glob_raw, fs_glob_multi_raw,
    fs_walk_raw, fs_watch_open_raw,
    open, close, read_all, read, write, delete, size, mtime, exists,
    create_dir, create_dir_with_mode, delete_dir, mkdir_p,
    symlink, hard_link, readlink, unlink,
    list_dir, glob, glob_multi,
    walk, watch_open, watch_wait, watch_close,
    write_binary, write_atomic, rename, file_stat, read_binary,
    fs_copy_raw, fs_move_raw, fs_realpath_raw, fs_chmod_raw,
    copy, move, realpath, chmod,
    copy_tree, remove_tree,
    find_ext, find_ext_excluding,
    KIND_OK, KIND_NOT_FOUND, KIND_PERMISSION_DENIED, KIND_EXISTS,
    KIND_CROSS_DEVICE, KIND_IO, KIND_INVALID, KIND_LOOP,
    KIND_NAME_TOO_LONG, KIND_NO_SPACE, KIND_IS_DIR, KIND_NOT_DIR,
    KIND_UNAVAILABLE,
    last_os_error, fs_error_message
)

// ---- Structured-error kinds (pilot — issue #392) ----
// Returned as the second element of the (value, kind, message) tuple
// from `copy`, `move`, `realpath`, and `chmod`. Switch on these to
// programmatically discriminate between common failure modes without
// parsing the human-readable message. Non-fs callers should treat
// any non-zero kind as "an error happened" — the message remains the
// authoritative human-readable diagnostic.
//
// Values are stable; new kinds may be appended (always with a fresh
// integer above the existing range) but existing values are part of
// the surface contract. Mirror these in std/fs/aether_fs.h as
// AETHER_FS_KIND_* macros so the C side and the Aether surface
// remain in lock-step.
const KIND_OK = 0
const KIND_NOT_FOUND = 1 // ENOENT — path or component missing
const KIND_PERMISSION_DENIED = 2 // EACCES, EPERM
const KIND_EXISTS = 3 // EEXIST — destination already there (when caller asked not to overwrite)
const KIND_CROSS_DEVICE = 4 // EXDEV — rename across filesystems (move falls back transparently)
const KIND_IO = 5 // EIO and other partial-I/O failures
const KIND_INVALID = 6 // EINVAL — illegal argument (e.g. src == dst)
const KIND_LOOP = 7 // ELOOP — symlink cycle on realpath
const KIND_NAME_TOO_LONG = 8 // ENAMETOOLONG
const KIND_NO_SPACE = 9 // ENOSPC — disk full
const KIND_IS_DIR = 10 // EISDIR — operation on a directory where a regular file was required (or vice-versa for copy/move src)
const KIND_NOT_DIR = 11 // ENOTDIR — component of path is not a directory
const KIND_UNAVAILABLE = 99 // platform feature compiled out (reserved for follow-up modules; fs primitives never return this)

// File operations - raw externs
extern file_open_raw(path: string, mode: string) -> ptr
extern file_close_raw(file: ptr) -> int
extern file_read_all_raw(file: ptr) -> string @heap
extern file_write_raw(file: ptr, data: string, length: int) -> int
extern file_exists(path: string) -> int
// Path-agnostic existence check: 1 if anything is at `path`
// (regular file, directory, symlink, fifo, ...), 0 otherwise.
// Distinct from `file_exists` (regular-file-only) and
// `dir_exists` (directory-only). Use this when the caller doesn't
// care what kind of thing is there — only whether the path is bound.
// Matches POSIX `test -e`.
extern fs_path_exists(path: string) -> int
extern file_delete_raw(path: string) -> int
// Size in bytes, as `long` (#1021): the old int surface wrapped files
// >= 2 GiB to a negative value. Returns -1 on stat failure.
extern file_size_raw(path: string) -> long

// Get file modification time as a Unix timestamp. Infallible — returns
// 0 for missing files, null paths, or stat failure. Kept as a raw
// extern with no Go-style wrapper because callers already use the 0
// sentinel for "no mtime". `long` since #1021 (Y2038-safe).
extern file_mtime(path: string) -> long
// `file_mtime_raw` returns the file's mtime as Unix epoch seconds, or
// -1 if stat failed. Use this rather than `file_mtime` when you need
// to distinguish "1970-01-01 epoch file" from "stat failed" — the
// older `file_mtime` collapses both into 0. The `fs.mtime` wrapper
// below builds the standard (value, err) tuple on top of it.
extern file_mtime_raw(path: string) -> long

// Directory operations - raw externs
extern dir_exists(path: string) -> int
extern dir_create_raw(path: string) -> int
extern dir_create_mode_raw(path: string, mode: int) -> int
extern dir_delete_raw(path: string) -> int
extern dir_list_raw(path: string) -> ptr

// `mkdir -p` semantics: create `path` and any missing parent directories.
// Treats already-existing directories as success. Raw extern — use the
// `mkdir_p` wrapper below in most code.
extern fs_mkdir_p_raw(path: string) -> int

// Symbolic-link operations (raw externs). POSIX symlink(2) / readlink(2) /
// lstat(2); on Windows CreateSymbolicLinkW, the link's own reparse data
// and the directory entry's reparse tag.
//   fs_symlink_raw:    create a symlink at `link_path` pointing to `target`.
//                      `target` is recorded verbatim (relative stays relative);
//                      Windows stores its separators as backslashes.
//   fs_readlink_raw:   read a symlink's target (on Windows, a junction's too).
//                      Returns null if not a link.
//                      `@heap`: a fresh counted string the tracker frees.
//   fs_is_symlink:     does NOT follow; returns 1 only for the link itself.
//                      On Windows a junction counts: it redirects resolution
//                      exactly as a symlink does (any name-surrogate reparse
//                      point). Pure boolean query, no wrapper (matches
//                      file_exists).
//   fs_unlink_raw:     remove a file or symlink (NOT a directory).
extern fs_symlink_raw(target: string, link_path: string) -> int
//   fs_hard_link_raw:  a second name (`link_path`) for the file at `target`;
//                      same filesystem, files only. 1 on success.
extern fs_hard_link_raw(target: string, link_path: string) -> int
extern fs_readlink_raw(path: string) -> string @heap
// Both return a fresh counted path (or null). `@heap` so the heap-tracker
// frees it — without it the returned path leaks (caught by the
// macOS leaks gate).
extern fs_make_temp_dir_raw(dir: string, prefix: string) -> string @heap
extern fs_make_temp_file_raw(dir: string, prefix: string) -> string @heap
extern fs_is_symlink(path: string) -> int
//   fs_is_socket:      1 if the path is a UNIX-domain socket (follows
//                      symlinks). POSIX only; returns 0 on Windows. Pure
//                      boolean query, no wrapper (matches fs_is_symlink). #1368
extern fs_is_socket(path: string) -> int
extern fs_unlink_raw(path: string) -> int

// Non-atomic binary write: fopen("wb") + fwrite(len bytes) + fclose.
// Binary-safe because length is explicit. Cheaper than fs_write_atomic_raw
// when a partial file on crash is acceptable — scratch writes, caches,
// and anywhere the destination isn't load-bearing for another process.
//
// These two and fs_pwrite_raw take `data: ptr`, not `string`, and are not
// exported (#2301): the wrappers pass a byte[] slice's raw data pointer.
// A `string` parameter routes through the AetherString unwrap, which would
// misread a payload beginning with the header's magic bytes as a header;
// and a heap string passed to a `ptr` parameter would write its header.
// Use write_binary / write_atomic / pwrite.
extern fs_write_binary_raw(path: string, data: ptr, length: int) -> int

// Durable write: write-to-tmp + fsync + rename over destination.
// Binary-safe — takes an explicit length so embedded NULs survive.
extern fs_write_atomic_raw(path: string, data: ptr, length: int) -> int

// POSIX rename(2). Callers pairing with write_atomic should keep
// `from` on the same filesystem as `to` for atomicity.
extern fs_rename_raw(from: string, to: string) -> int

// Split-accessor stat: call fs_try_stat first, then read the
// getters. kind encoding: see STAT_KIND_* below.
// Pair is thread-local so back-to-back calls on one thread are safe.
// #1378: the raw OS code behind the portable kind from the most recent fs
// call on this thread. 0 after a success. Branch on the KIND_* value; reach
// for this only when the exact number matters, such as telling EAGAIN from
// EWOULDBLOCK or putting the number in a log.
extern fs_last_os_error() -> int
extern fs_error_message(path: string, fallback: string) -> string

last_os_error() -> int {
    return fs_last_os_error()
}

extern fs_try_stat(path: string) -> int
extern fs_get_stat_kind() -> int

// Values fs_get_stat_kind / dir_list_kind return. SOCKET/FIFO/DEVICE are
// POSIX-only (#1368); on Windows those nodes report OTHER. Additive — code
// that only tested FILE/DIR/SYMLINK/OTHER is unaffected.
const STAT_KIND_FILE = 1
const STAT_KIND_DIR = 2
const STAT_KIND_SYMLINK = 3
const STAT_KIND_OTHER = 4
const STAT_KIND_SOCKET = 5
const STAT_KIND_FIFO = 6
const STAT_KIND_DEVICE = 7

// fs.walk callback RETURN values — steer the traversal. Return one of these
// from the walk closure; they read at the call site so the prune/stop
// affordance is visible without hunting the doc comment (return 0 is the
// implicit "keep going" if you return nothing meaningful):
//   WALK_CONTINUE (0)      descend/visit normally
//   WALK_SKIP_SUBTREE (1)  on a directory, do NOT descend into it (prune) —
//                          the `find -prune` of `! -path '*/node_modules/*'`
//   WALK_STOP (2)          end the whole walk immediately
const WALK_CONTINUE = 0
const WALK_SKIP_SUBTREE = 1
const WALK_STOP = 2
// size/mtime are `long` (#1021): 64-bit sizes (no >= 2 GiB wrap) and
// Y2038-safe mtimes.
extern fs_get_stat_size() -> long
extern fs_get_stat_mtime() -> long

// Split-accessor statvfs (#1117): fs_try_statvfs first, then read the
// three byte-count getters. All `long` (exact bytes, 64-bit). Thread-local
// like the stat pair. fs_try_statvfs returns 0 on failure (incl. Windows).
extern fs_try_statvfs(path: string) -> int
extern fs_get_statvfs_total() -> long
extern fs_get_statvfs_free() -> long
extern fs_get_statvfs_avail() -> long

// Mount enumeration (#1118). fs_try_mounts loads a thread-local mount
// table and returns the entry count (-1 on failure); the per-entry
// getters return strings BORROWED from that table, valid until the
// next fs_try_mounts / fs_release_mounts on the same thread. Backends:
// Linux /proc/self/mountinfo (octal escapes decoded), macOS and the
// BSDs getmntinfo(3), Windows drive letters. Prefer the mounts()
// wrapper below.
extern fs_try_mounts() -> int
extern fs_get_mount_count() -> int
extern fs_get_mount_source(i: int) -> string
extern fs_get_mount_point(i: int) -> string
extern fs_get_mount_fstype(i: int) -> string
extern fs_get_mount_options(i: int) -> string
extern fs_release_mounts()

// Block-device info (#1118), Linux sysfs backend. Accepts "/dev/sda",
// "sda", or a partition ("sda1", "nvme0n1p2"; the removable flag
// resolves through the parent disk). Other platforms report
// unsupported through the block_info() wrapper's error slot, never a
// fabricated answer.
extern fs_try_block_info(dev: string) -> int
extern fs_get_block_size_bytes() -> long
extern fs_get_block_removable() -> int
extern fs_get_block_transport() -> string

// Split-accessor binary read: fs_try_read_binary reads the file into
// a TLS-owned buffer; fs_get_read_binary / fs_get_read_binary_length
// read that buffer borrowed. fs_release_read_binary frees early
// (otherwise it's released on the next fs_try_read_binary call).
// The buffer is bytes whose length C reports separately, not a C string,
// so the getter is a `ptr`: as a `string`, binding it to a local copied
// it up to the first NUL. Copy it with string_new_with_length(p, n), or
// call read_binary, which does.
extern fs_try_read_binary(path: string) -> int
extern fs_get_read_binary() -> ptr
extern fs_get_read_binary_length() -> int
extern fs_release_read_binary()

// Unified tuple-return shape (#271 + #273) — the canonical entry
// point that fs.read_binary wraps. Returns (bytes, length, err):
// (AetherString*, int, "") on success, (empty, 0, "<reason>") on
// failure.
//
// Position 0 (bytes) is `@heap`: the C side allocates a fresh
// AetherString via `string_new_with_length`. The destructured LHS
// owns the buffer; the heap-string-tracker frees it at function
// exit (or on reassignment) — same machinery `fs_realpath_raw`
// below relies on. Position 2 (err) stays default-borrow — the
// error message is a static C string literal.
//
// Earlier shape used `(ptr, int, string)` for position 0, which
// suppressed heap classification at every tuple-destructure site
// and silently leaked the bytes buffer at scope exit. Reported by
// the avn port (tuple-destructure-heap-classification.md) where it
// drove O(N²) RSS retention in avnserver.
extern fs_read_binary_tuple(path: string) -> (string @heap, int, string)

// Structured-error pilot (issue #392) — these externs return
// (value, kind, message) where kind is one of the KIND_* constants
// at the top of this module. fs_copy_raw zero-copies via the
// platform's best primitive (copy_file_range / sendfile / fcopyfile /
// CopyFileExW); falls back to an 8 MiB read/write loop on
// filesystems that reject the kernel primitives. See aether_fs.c for
// the full performance hierarchy.
extern fs_copy_raw(src: string, dst: string) -> (int, int, string)

// fs_move_raw — atomic rename(2) when same-fs, transparent
// copy + unlink fallback on EXDEV. Returns (1, KIND_OK, "") on
// success, (0, KIND_*, msg) on failure.
extern fs_move_raw(src: string, dst: string) -> (int, int, string)

// fs_realpath_raw — OS-canonicalise the path (deref every symlink,
// remove ./.. components). Returns (resolved_path, KIND_OK, "") on
// success, ("", KIND_*, msg) on failure.
//
// Position 0 (resolved_path) is `@heap`: a fresh counted string on
// every path, the empty one on failure (realpath(3) on POSIX, the
// GetFinalPathNameByHandleW result in UTF-8 on Windows). The
// destructured LHS owns it; the heap-string-tracker frees it at
// function exit (or on reassignment). Position 2 (msg) stays
// default-borrow — error message is a static string literal in
// the C source.
//
// Audited callers: only `fs.realpath` (the Aether wrapper below)
// passes the tuple through; no manual string.release on the
// resolved path anywhere in stdlib, tests/, examples/, tools/,
// or contrib/. See #420 follow-up.
extern fs_realpath_raw(path: string) -> (string @heap, int, string)

// fs_chmod_raw — POSIX chmod(2). On Windows only the user-write
// bit (0o200) is honoured (matches Python's os.chmod docs). Returns
// (1, KIND_OK, "") or (0, KIND_*, msg).
extern fs_chmod_raw(path: string, mode: int) -> (int, int, string)

extern dir_list_count(list: ptr) -> int
extern dir_list_get(list: ptr, index: int) -> string
// #966: file kind of entry `index`, straight from readdir's d_type — no
// stat(2) needed. Same encoding as file_stat's kind: 1 = regular file,
// 2 = directory, 3 = symlink (target not followed), 4 = other (fifo /
// socket / device). 0 = unknown: the filesystem didn't report a type
// (rare) — stat that entry to resolve it.
extern dir_list_kind(list: ptr, index: int) -> int
extern dir_list_free(list: @frees ptr)

// Path utilities - pure functions, never fail
extern path_join(path1: string, path2: string) -> string @heap
extern path_dirname(path: string) -> string @heap
extern path_basename(path: string) -> string @heap
extern path_extension(path: string) -> string @heap
extern path_is_absolute(path: string) -> int

// Lexical path ops (#632). Pure-string; never touch the filesystem.
extern path_clean(path: string) -> string @heap
extern path_is_within_base(base: string, target: string) -> int
extern path_rel(base: string, target: string) -> string @heap
// Platform path separator ("/" POSIX, "\\" Windows) — #1369.
extern path_separator() -> string

// Positional I/O (#640).
extern fs_pwrite_raw(file: ptr, data: ptr, length: int, offset: long) -> long
extern fs_pread_raw(file: ptr, length: int, offset: long) -> int
extern fs_pread_into_raw(file: ptr, buf: ptr, length: int, offset: long) -> int
extern fs_get_pread() -> ptr
extern fs_get_pread_length() -> int
extern fs_release_pread()
extern fs_ftruncate_raw(file: ptr, length: long) -> string
extern fs_fsync_raw(file: ptr) -> string

// Descriptor accessor (#1003). The OS-level fd inside an open handle,
// or -1 if the handle is closed/invalid.
extern file_fd_raw(file: ptr) -> int

// Glob: match files by pattern. Raw externs return ptr, NULL on failure.
extern fs_glob_raw(pattern: string) -> ptr
extern fs_glob_multi_raw(patterns: ptr) -> ptr

// #977: recursive walk + change notification. Raw externs; the Aether-native
// wrappers (walk / watch_open below) add the (value, err) surface. The walk
// callback is used only during the call (#2523): the caller keeps its
// environment and releases it once the walk returns.
extern fs_walk_raw(path: string, cb: @noescape ptr) -> int
extern fs_watch_open_raw(path: string) -> ptr
// Block up to timeout_ms (negative = forever): 1 = something changed,
// 0 = timeout, -1 = error / closed handle. Pending events are drained so
// one burst of changes reports once; changes between watch_open and
// watch_wait are queued, not lost.
extern fs_watch_wait(watch: ptr, timeout_ms: int) -> int
// Release the handle. Safe on null.
extern fs_watch_close(watch: ptr)

// string_concat used for duplicating borrowed strings. strlen-based —
// do NOT use for binary payloads (it truncates at the first embedded
// NUL). Length-aware reads use string_new_with_length.
extern string_concat(a: string, b: string) -> string @heap
extern string_length(str: string) -> int
extern string_char_at(str: string, index: int) -> int
extern string_substring(str: string, start: int, end: int) -> string @heap

// Length-preserving string constructor. Takes an explicit byte count
// so binary payloads with embedded NULs survive the copy. Returns a
// ref-counted AetherString with the exact byte content — consumers
// reading up to `length` see the full file.
extern string_new_with_length(data: ptr, length: size_t) -> string @heap

// ---- Go-style wrappers ----

// Open a file. Returns (handle, "") on success, (null, error) on failure.
// `mode` is fopen's ("r", "w", "a", "r+", ...); the handle carries bytes
// verbatim on every platform — on Windows it is opened binary whether or
// not the mode says 'b', like every other std.fs entry point, so a '\n'
// written through it is one byte on disk and pread/pwrite are byte-exact.
// A mode with an explicit 't' ("wt") asks for C's text mode and gets it.
open(path: string, mode: string) -> {
    handle = file_open_raw(path, mode)
    if handle == null {
        return null, "cannot open file"
    }
    return handle, ""
}

// Close a handle `open` gave, and free it. Returns "" on success, or the
// reason: a write the close flushes can fail (a full disk, a lost network
// mount), and the data is then not on disk. `defer fs.close(h)` after a
// successful open is the usual shape (#3179).
close(handle: ptr) -> string {
    if handle == null {
        return "null handle"
    }
    if file_close_raw(handle) < 0 {
        return "close failed: buffered data was not written"
    }
    return ""
}

// Read the whole of an open handle, from its start. Returns (text, "") on
// success, ("", error) on failure; the handle stays open (#3179).
read_all(handle: ptr) -> {
    if handle == null {
        return "", "null handle"
    }
    text = file_read_all_raw(handle)
    if text == null {
        return "", "read failed"
    }
    return text, ""
}

// Read the entire contents of a file at `path`. Opens, reads, closes.
// Returns (content, "") on success, ("", error) on failure.
//
// The error names the path and the cause — "<path>: No such file or
// directory", "<path>: Is a directory", "<path>: Permission denied" — rather
// than the single "cannot open file" this used to return for every cause.
//
// LIFETIME: the error string is BORROWED from thread-local storage and is only
// valid until this thread's next failed read. Print it, or copy it with
// `string.concat(err, "")`, before issuing another read — do NOT hold it across
// one. Do not free it. The text read is the caller's string, released like any
// other when its place lets it go (#3168).
read(path: string) -> {
    // "rb", not "r": Windows text mode collapses "\r\n" back to "\n" and stops
    // at the first Ctrl-Z (0x1A) byte, neither of which fs.read should do — it
    // returns verbatim bytes on POSIX and must match. (read_binary already uses
    // "rb".) The 'b' is a no-op on POSIX.
    handle = file_open_raw(path, "rb")
    if handle == 0 {
        // Was the bare "cannot open file" — no path, no reason, so a missing
        // file, a permission error and a sandbox denial were indistinguishable.
        // fs_error_message reads errno while it is still this call's.
        return "", fs_error_message(path, "cannot open file")
    }
    content = file_read_all_raw(handle)
    if content == 0 {
        file_close_raw(handle)
        return "", fs_error_message(path, "cannot read file")
    }
    content_copy = string_concat(content, "")
    file_close_raw(handle)
    return content_copy, ""
}

// Write `content` to a file at `path`. Opens in write mode, writes, closes.
// Returns "" on success, error string on failure.
write(path: string, content: string) -> {
    // "wb", not "w": on Windows text mode translates every '\n' into "\r\n",
    // so fs.write would silently corrupt exact/binary content (e.g. writing
    // "hello world\n" produced 13 bytes and a different sha256 than on POSIX).
    // The 'b' is a no-op on POSIX, so this is verbatim-bytes on every platform.
    handle = file_open_raw(path, "wb")
    if handle == 0 {
        return fs_error_message(path, "cannot open file for writing")
    }
    length = string_length(content)
    ok = file_write_raw(handle, content, length)
    if ok == 0 {
        err = fs_error_message(path, "write failed")
        file_close_raw(handle)
        return err
    }
    closed = file_close_raw(handle)
    if closed < 0 {
        return fs_error_message(path, "close failed: buffered data was not written")
    }
    return ""
}

// Delete the file at `path`. Returns "" on success, error on failure.
delete(path: string) -> {
    ok = file_delete_raw(path)
    if ok == 0 {
        return "cannot delete file"
    }
    return ""
}

// Return the size of the file at `path` in bytes, as `long` (#1021 —
// files >= 2 GiB used to wrap negative through the old int surface).
// Returns (size, "") on success, (0, error) on failure.
//
// The success arm returns FIRST: the first `return` statement pins the
// inferred tuple slot types, so the `long`-typed arm must come before
// the int-literal error arm or the size slot narrows back to int.
size(path: string) -> {
    s = file_size_raw(path)
    if s >= 0 {
        return s, ""
    }
    return 0, "cannot stat file"
}

// Return the file's mtime as Unix epoch seconds.
// Returns (mtime, "") on success, (0, error) on failure. Distinguishes
// "stat failed" from "file's mtime is 0" (which the older `file_mtime`
// extern collapses into a single sentinel). Prefer this wrapper for
// new code; `file_mtime` stays for back-compat.
// Success arm first — same tuple-slot-inference constraint as `size`.
mtime(path: string) -> {
    m = file_mtime_raw(path)
    if m >= 0 {
        return m, ""
    }
    return 0, "cannot stat file"
}

// Does anything exist at `path`? Returns 1 for any kind of
// filesystem entry (regular file, directory, symlink, fifo, ...),
// 0 if nothing is there or `path` is empty. Use this when you don't
// care whether the target is a file or a directory — for type-
// specific checks reach for `file.exists` (regular-file-only) or
// `dir.exists` (directory-only). Matches POSIX `test -e`.
exists(path: string) -> int {
    return fs_path_exists(path)
}

// Create a directory. Returns "" on success, error on failure.
create_dir(path: string) -> {
    ok = dir_create_raw(path)
    if ok == 0 {
        return "cannot create directory"
    }
    return ""
}

// Like `create_dir` but with an explicit POSIX-style mode (0777-masked).
// Use this when the directory needs to be private — e.g.
// `fs.create_dir_with_mode("/run/myapp/keys", 448)` for 0o700 — without
// the mkdir-then-chmod race the "always 0755 + shell out to chmod"
// workaround would open. Windows ignores the mode at the directory
// layer; the parameter is accepted for API portability.
create_dir_with_mode(path: string, mode: int) -> {
    ok = dir_create_mode_raw(path, mode)
    if ok == 0 {
        return "cannot create directory"
    }
    return ""
}

// Delete a directory. Returns "" on success, error on failure.
delete_dir(path: string) -> {
    ok = dir_delete_raw(path)
    if ok == 0 {
        return "cannot delete directory"
    }
    return ""
}

// `mkdir -p`: create `path` and any missing parent directories. Treats
// already-existing directories as success. Returns "" on success, error
// on failure.
mkdir_p(path: string) -> {
    ok = fs_mkdir_p_raw(path)
    if ok == 0 {
        return "cannot mkdir -p"
    }
    return ""
}

// Create a symbolic link at `link_path` pointing to `target`. The target
// is recorded verbatim — relative targets stay relative. Returns "" on
// success, error on failure (e.g. `link_path` already exists). On Windows
// a relative target is resolved against the link's directory to decide
// whether the link is to a directory (Windows records that), the
// target's separators are stored as backslashes, and creating a link
// needs the privilege administrators hold and Developer Mode grants
// everyone; without it this fails.
symlink(target: string, link_path: string) -> {
    ok = fs_symlink_raw(target, link_path)
    if ok == 0 {
        return "cannot create symlink"
    }
    return ""
}

// Hard link: `link_path` becomes another name for the file at `target`
// (same filesystem; not directories). Returns "" on success, error on
// failure (e.g. `link_path` already exists, or they are on different
// filesystems). Windows uses CreateHardLinkW (NTFS).
hard_link(target: string, link_path: string) -> {
    ok = fs_hard_link_raw(target, link_path)
    if ok == 0 {
        return "cannot create hard link"
    }
    return ""
}

// Read a symbolic link. Returns (target, "") on success,
// ("", error) if `path` is not a symlink or can't be read.
readlink(path: string) -> {
    target = fs_readlink_raw(path)
    if target == null {
        return "", "not a symlink"
    }
    // target is @heap-owned; hand it straight back (the copy this used to
    // make left the C allocation to leak on every call).
    return target, ""
}

// The documented defaults for make_temp_dir / make_temp_file. The C side only
// defaulted a NULL dir, so the empty string these document became the
// template "/<prefix>XXXXXX" at the filesystem root and failed.
extern os_temp_dir_raw() -> string @heap

fn temp_parent(dir: string) -> string {
    if dir == "" {
        return os_temp_dir_raw()
    }
    return dir
}

fn temp_prefix(prefix: string) -> string {
    if prefix == "" {
        return "ae"
    }
    return prefix
}

// make_temp_dir(dir, prefix) — atomically create and return a uniquely-named
// temp DIRECTORY under `dir`, name starting `prefix` (mkdtemp — no race). The
// caller owns it: clean up with remove_tree(). Returns (path, "") or ("", err).
// Empty `dir` → the OS temp dir (os.temp_dir); empty `prefix` → "ae".
make_temp_dir(dir: string, prefix: string) -> {
    p = fs_make_temp_dir_raw(temp_parent(dir), temp_prefix(prefix))
    if p == null { return "", "cannot create temp dir" }
    return p, ""
}

// make_temp_file(dir, prefix) — atomically create and return a uniquely-named
// temp FILE under `dir` (mkstemp — created O_EXCL, no race). The caller owns
// it: delete() when done. Returns (path, "") or ("", err).
make_temp_file(dir: string, prefix: string) -> {
    p = fs_make_temp_file_raw(temp_parent(dir), temp_prefix(prefix))
    if p == null { return "", "cannot create temp file" }
    // p is @heap-owned; hand it straight back (string_concat here would leak
    // the original and double-allocate).
    return p, ""
}

// Remove a file or symlink. Refuses to remove a directory — use
// `delete_dir` for that. Returns "" on success, error on failure.
unlink(path: string) -> {
    ok = fs_unlink_raw(path)
    if ok == 0 {
        return "cannot unlink"
    }
    return ""
}

// List directory contents.
// Returns (DirList ptr, "") on success, (null, error) on failure.
// Caller must free the returned ptr with dir_list_free.
list_dir(path: string) -> {
    list = dir_list_raw(path)
    if list == null {
        return null, "cannot list directory"
    }
    return list, ""
}

// Glob for files matching a pattern.
// Returns (DirList ptr, "") on success, (null, error) on failure.
glob(pattern: string) -> {
    list = fs_glob_raw(pattern)
    if list == null {
        return null, "glob failed"
    }
    return list, ""
}

// Multi-pattern glob.
glob_multi(patterns: ptr) -> {
    list = fs_glob_multi_raw(patterns)
    if list == null {
        return null, "glob failed"
    }
    return list, ""
}

// #977: recursive directory walk. Visits `path` itself first (depth 0), then
// every entry beneath it, calling `cb` per entry:
//
//     n, err = fs.walk(root, |path: string, kind: int, depth: int| {
//         // kind: 1 file / 2 dir / 3 symlink / 4 other (same as file_stat)
//         return fs.WALK_CONTINUE   // or WALK_SKIP_SUBTREE (prune this dir) /
//                                   // WALK_STOP (end the walk). Raw: 0 / 1 / 2.
//     })
//
// The callback's return PRUNES: WALK_SKIP_SUBTREE (1) on a directory means "do
// not descend into it" — the `find -prune` of `! -path '*/node_modules/*'`,
// without walking the excluded subtree first. WALK_STOP (2) ends the walk.
//
// One readdir sweep per directory — entry kinds come from d_type (#966), so
// nothing is stat'ed unless the filesystem doesn't report a type. Symlinks
// are reported but never followed (no cycles).
//
// `path` is BORROWED. It points into the one buffer the walk rewrites for the
// next entry, so it is only valid until the callback returns. Storing it
// directly keeps the pointer, not the bytes: `list.add(paths, path)` leaves a
// dangling pointer that reads as garbage long after the walk finished, and
// the corruption surfaces wherever the string is finally used rather than
// here. Copy at the boundary to keep a path:
//
//     list.add(paths, string.copy(path))
//
// Traversal order within a directory is the platform's readdir order
// (unspecified).
// Returns (entries visited, "") or (0, error) when `path` can't be read.
walk(path: string, cb: fn) -> {
    n = fs_walk_raw(path, cb)
    if n < 0 {
        return 0, "cannot walk path"
    }
    return n, ""
}

// #977: watch a directory (or file) for changes — create / delete / modify /
// rename inside it — over the platform primitive (kqueue on macOS/BSD,
// inotify on Linux, FindFirstChangeNotification on Windows). The event is a
// coarse "something changed here" ping: re-list the directory to see what.
// Non-recursive; one handle watches one path; a handle is single-threaded.
//
//     w, err = fs.watch_open(dir)
//     changed = fs.watch_wait(w, 1000)   // 1 changed / 0 timeout / -1 error
//     fs.watch_close(w)
//
// Changes that happen between watch_open and watch_wait are queued, not
// lost — so "open watch, do work, then wait" never misses an edit.
watch_open(path: string) -> {
    w = fs_watch_open_raw(path)
    if w == null {
        return null, "cannot watch path"
    }
    return w, ""
}

// Block up to timeout_ms (negative = forever). 1 = changed, 0 = timeout,
// -1 = error / closed handle. Drains pending events so one burst of changes
// reports once.
watch_wait(watch: ptr, timeout_ms: int) -> int {
    return fs_watch_wait(watch, timeout_ms)
}

// Release the watch handle. Safe on null.
watch_close(watch: ptr) {
    fs_watch_close(watch)
}

// A slice with no bound (`p as byte[]`, `.len` -1) has no length to write.
fn unbounded_write(fname: string) {
    panic("fs.${fname}: the slice has no bound (.len -1); give it one, as `(p as byte[])[0..n]`")
}

// Non-atomic binary write: open, write every byte of `data`, close.
// Binary-safe — the length travels with the slice (#2301), so embedded
// NULs survive. An empty slice writes an empty file.
//
// For a string, write its byte view: `fs.write_binary(path,
// string.bytes(s))`; for a `std.bytes` buffer, `bytes.view(buf)`; for a
// prefix, sub-slice it (`string.bytes(s)[0..n]`). Text that is never
// binary can use `fs.write` instead.
//
// When you want the write to be crash-safe, use `fs.write_atomic`
// instead (stage + fsync + rename). `write_binary` skips that
// machinery for cheaper writes to scratch paths, caches, or any
// destination where a partial file on crash is acceptable.
//
// Returns "" on success, error on failure (open / write / close).
// On failure, whatever bytes were written stay on disk — caller
// removes the partial file if needed.
write_binary(path: string, data: byte[]) -> string {
    if data.len < 0 {
        unbounded_write("write_binary")
    }
    ok = fs_write_binary_raw(path, data, data.len)
    if ok == 0 {
        return fs_error_message(path, "binary write failed")
    }
    return ""
}

// Durable write: stage `data` into a sibling tmp file, fsync, then
// rename(2) over `path`. On crash between write and rename, the
// destination is either the old contents or the new — never a
// partial write. Binary-safe: the length travels with the slice
// (#2301), so embedded NULs survive. For a string pass
// `string.bytes(s)`; for a `std.bytes` buffer, `bytes.view(buf)`.
//
// Returns "" on success, error on failure (tmp create, write, fsync,
// rename — the tmp is removed if any step fails so the filesystem
// isn't littered with aborted writes).
write_atomic(path: string, data: byte[]) -> {
    if data.len < 0 {
        unbounded_write("write_atomic")
    }
    ok = fs_write_atomic_raw(path, data, data.len)
    if ok == 0 {
        return fs_error_message(path, "atomic write failed")
    }
    return ""
}

// Rename `from` to `to` — thin POSIX rename(2) wrapper. Atomic when
// both sides are on the same filesystem. Returns "" on success,
// error on failure (e.g. cross-filesystem rename, destination dir
// not writable, source missing).
rename(from: string, to: string) -> {
    ok = fs_rename_raw(from, to)
    if ok == 0 {
        // Both paths: the reason can be the destination's (a missing
        // directory, no write permission there) as well as the source's.
        return fs_error_message("${from} -> ${to}", "rename failed")
    }
    return ""
}

// Single-stat accessor. Returns (kind, size, mtime, "") on success,
// (0, 0, 0, error) on failure. `kind` is one of:
//   1 = file, 2 = directory, 3 = symlink, 4 = other (FIFO, socket,
//       device, ...).
// `mtime` is a Unix timestamp, `size` is in bytes. Uses lstat(2) —
// symlinks report kind 3, the target is NOT followed.
//
// Cheaper than the existing file_exists + fs_is_symlink + size +
// file_mtime quartet when callers need more than one field.
// Two inference constraints keep size/mtime `long` here (#1021):
// the getters are bound to locals (a call expression directly inside
// a tuple return types as int; a variable carries the extern's
// declared long), and the success arm returns first (the first
// `return` pins the tuple slot types). The getters all return 0 after
// a failed fs_try_stat, so binding them before the ok-check is safe.
file_stat(path: string) -> {
    ok = fs_try_stat(path)
    kind = fs_get_stat_kind()
    size = fs_get_stat_size()
    mtime = fs_get_stat_mtime()
    if ok != 0 {
        return kind, size, mtime, ""
    }
    return 0, 0, 0, "cannot stat path"
}

// Exact filesystem byte counts for the filesystem containing `path` (#1117).
// Returns (total, free, avail, "") on success, (0, 0, 0, error) on failure.
// `avail` (POSIX f_bavail) is the space usable by an unprivileged process —
// the one you want for "how much can I actually write here" (e.g. auto-filling
// a write range: `end = avail / file_size`). POSIX statvfs(2); portable across
// Linux/macOS/BSD. Not available on Windows (returns the error branch there).
//
// Same `long`-inference discipline as file_stat (#1021): bind the getters to
// locals so they keep their `long` type, and return the success arm first so
// the first `return` pins the tuple slots to long. The getters all read 0
// after a failed fs_try_statvfs, so binding them before the ok-check is safe.
statvfs(path: string) -> {
    ok = fs_try_statvfs(path)
    total = fs_get_statvfs_total()
    free = fs_get_statvfs_free()
    avail = fs_get_statvfs_avail()
    if ok != 0 {
        return total, free, avail, ""
    }
    return 0, 0, 0, "cannot statvfs path"
}

// Load the mount table. Returns (count, "") on success or
// (0, "cannot enumerate mounts"). Read entries with mount_source /
// mount_point / mount_fstype / mount_options; free early with
// fs_release_mounts (otherwise the next mounts() call reuses the slot).
mounts() -> {
    n = fs_try_mounts()
    if n >= 0 {
        return n, ""
    }
    return 0, "cannot enumerate mounts"
}

mount_source(i: int) -> string {
    return fs_get_mount_source(i)
}

mount_point(i: int) -> string {
    return fs_get_mount_point(i)
}

mount_fstype(i: int) -> string {
    return fs_get_mount_fstype(i)
}

mount_options(i: int) -> string {
    return fs_get_mount_options(i)
}

// Block-device facts. Returns (size_bytes, removable, transport, "")
// on success; removable is 1/0 or -1 when the kernel does not say.
// On platforms without a backend (everything but Linux today) returns
// (0, -1, "", "block info unavailable on this platform").
block_info(dev: string) -> {
    ok = fs_try_block_info(dev)
    size = fs_get_block_size_bytes()
    removable = fs_get_block_removable()
    transport = fs_get_block_transport()
    if ok != 0 {
        return size, removable, transport, ""
    }
    return 0, 0 - 1, "", "block info unavailable on this platform"
}

// Binary-safe file read. Preserves embedded NULs and reports the
// exact byte length. Returns (content, length, "") on success,
// ("", 0, error) on failure.
//
// The returned string is a length-aware copy: `string.length(content)`
// equals the returned `length` even when the payload contains NULs.
// Under the hood the copy goes through `string_new_with_length`
// rather than `string_concat`, which is strlen-based and would
// silently truncate at the first embedded NUL. The TLS buffer inside
// the runtime is released after the copy completes, so the caller
// doesn't have to manage lifetime.
//
// On failure the error names the path and the cause — "<path>: No such file
// or directory", "<path>: Permission denied", or, for a sandbox refusal,
// "<path>: blocked by sandbox policy (no fs_read grant for this path)". That
// last one is deliberately distinct: a policy refusal is not a filesystem
// failure, and reporting it as one sends people looking at the disk instead of
// at their grants.
//
// LIFETIME: the error string is BORROWED from thread-local storage, valid only
// until this thread's next failed read. Print it, or copy it with
// `string.concat(err, "")`, before issuing another read. Do not free it. The
// bytes are the caller's, released like any other string (#3168).
read_binary(path: string) -> {
    // Single tuple-returning extern (#271 + #273). The four-extern
    // split-accessor pattern (fs_try_read_binary + fs_get_read_binary
    // + fs_get_read_binary_length + fs_release_read_binary) that this
    // wrapper used to orchestrate is still in place for callers built
    // directly against it; new bindings reach for the unified shape.
    return fs_read_binary_tuple(path)
}

// Copy file contents from `src` to `dst`, preserving source mode bits
// (file owner is NOT changed). Returns (bytes_copied, kind, message):
//   on success: (n, KIND_OK, "")
//   on failure: (bytes_so_far, KIND_*, "<reason>")
//
// Symlinks in `src` are followed (matches POSIX `cp` without -P).
// `dst` is overwritten if it exists; if `dst` is an existing directory
// the call returns KIND_IS_DIR — we do not nest into it. `src` and
// `dst` must differ lexically; the call returns KIND_INVALID otherwise.
//
// Performance: zero-copy primitives are tried in order
// (copy_file_range → sendfile on Linux; fcopyfile on macOS;
// CopyFileExW on Windows). An 8 MiB read/write loop is the portable
// fallback for filesystems that reject the kernel primitives. The
// reported byte count saturates at INT_MAX for files larger than
// 2^31 bytes — the data is still copied correctly; only the count is
// truncated.
copy(src: string, dst: string) -> {
    return fs_copy_raw(src, dst)
}

// Move file from `src` to `dst`. Atomic on the same filesystem;
// transparently falls back to copy + unlink across filesystems
// (EXDEV). Returns (1, KIND_OK, "") on success, (0, KIND_*, msg) on
// failure. Cross-device directory moves surface as KIND_IS_DIR (the
// underlying copy refuses to recurse into directories — that needs
// a higher-level walker).
move(src: string, dst: string) -> {
    return fs_move_raw(src, dst)
}

// OS-canonicalise the path: deref every symlink, fold . and ..
// components. Returns (resolved_path, KIND_OK, "") on success,
// ("", KIND_*, msg) on failure (KIND_NOT_FOUND if a component is
// missing, KIND_LOOP for symlink cycles, KIND_NAME_TOO_LONG if the
// resolved form exceeds the OS limit). The resolved path is spelled
// the way the OS spells it: `/`-separated on POSIX; on Windows
// backslashes with the drive letter upper-cased (`D:\dir\file`) or,
// for a network path, its `\\server\share\...` root. The returned
// path is owned by the runtime; the caller does not need to free it.
realpath(path: string) -> {
    return fs_realpath_raw(path)
}

// Change the permission bits at `path`. POSIX chmod(2) — follows
// symlinks. On Windows only the user-write bit (0o200) is honoured;
// every other bit is silently ignored (matches Python's os.chmod
// docs). `mode` is masked with 07777 internally. Returns
// (1, KIND_OK, "") or (0, KIND_*, msg).
chmod(path: string, mode: int) -> {
    return fs_chmod_raw(path, mode)
}

// Lexically clean `path` per POSIX filepath.Clean semantics — collapse
// `//` and `./`, resolve `..` against a segment stack (drop the
// parent), preserve a leading `/`, preserve unresolved leading `..`
// on relative paths. Empty input → ".". Pure-string, no filesystem
// access.
//
// Examples:
//   fs.clean("/a//b/./c/../d") → "/a/b/d"
//   fs.clean("../../x")        → "../../x"   (relative, unresolved)
//   fs.clean("/..")            → "/"         (rooted)
//   fs.clean("")               → "."
clean(path: string) -> string {
    return path_clean(path)
}

// Lexically-cleaned join. `path_join(a, b)` followed by `clean` in one
// call — the path that actually hits the filesystem after a user-
// supplied segment is appended. Use this (not bare `path_join`) wherever
// `b` may contain `..` or `.` — object keys, archive entry names, any
// caller-controlled tail — so `join_clean("bucket", "a/../b")` collapses
// to "bucket/b" rather than leaving the traversal in place. Pair with
// `is_within_base` for the containment check.
//
// Empty-segment handling mirrors path_join's identity behaviour: an
// empty `a` or `b` cleans the other side alone (so the result is never
// a spurious "./x" or "x/.").
//
// Examples:
//   fs.join_clean("bucket", "a/../b") → "bucket/b"
//   fs.join_clean("/data", "x/./y")   → "/data/x/y"
//   fs.join_clean("", "a/../b")       → "b"
//   fs.join_clean("bucket", "")       → "bucket"
join_clean(a: string, b: string) -> string {
    if string_length(a) == 0 {
        return path_clean(b)
    }
    if string_length(b) == 0 {
        return path_clean(a)
    }
    return path_clean(path_join(a, b))
}

// First cleaned path segment. Cleans `path` then returns the leading
// component up to (but not including) the first "/". For a rooted path
// the leading "/" is dropped first, so `first_element("/a/b")` is "a".
// A path that cleans to "." or "/" yields "". Useful for splitting an
// object key into its top-level bucket/prefix after traversal has been
// neutralised.
//
// Examples:
//   fs.first_element("a/b/c")     → "a"
//   fs.first_element("/a/b")      → "a"
//   fs.first_element("x/../y/z")  → "y"
//   fs.first_element("only")      → "only"
//   fs.first_element("/")         → ""
first_element(path: string) -> string {
    cleaned = path_clean(path)
    start = 0
    if string_length(cleaned) > 0 {
        if string_char_at(cleaned, 0) == 47 { // leading '/'
            start = 1
        }
    }
    i = start
    n = string_length(cleaned)
    while i < n {
        if string_char_at(cleaned, i) == 47 {
            return string_substring(cleaned, start, i)
        }
        i = i + 1
    }
    return string_substring(cleaned, start, n)
}

// Lexical containment: does cleaned `target` lie under cleaned `base`?
// Returns 1 yes, 0 no. SECURITY-CRITICAL primitive for any code that
// resolves a user-supplied path against a data dir / static-asset
// root / archive extraction prefix — call this BEFORE open(2) to
// reject `../../etc/passwd` at the door.
//
// Pure-string: does NOT follow symlinks. A symlink under `base`
// pointing outside is an open-time concern this function does not
// address. For symlink-aware containment, use realpath on both sides
// first (one extra syscall per request) then call this.
//
// Examples:
//   fs.is_within_base("/data", "/data/x/y")    → 1
//   fs.is_within_base("/data", "/data")        → 1   (identical)
//   fs.is_within_base("/data", "/data/../x")   → 0   (cleans to /x)
//   fs.is_within_base("/data", "/datax/y")     → 0   (prefix but not subdir)
is_within_base(base: string, target: string) -> int {
    return path_is_within_base(base, target)
}

// Relative path from cleaned `base` to cleaned `target` (Go
// filepath.Rel). Returns the relative path on success, "" when
// one is absolute and the other relative (no relative path exists).
// `base == target` returns ".".
//
// Useful for showing paths relative to a project root in logs / UI.
// Less security-critical than is_within_base — same lexical
// computation in a different shape.
rel(base: string, target: string) -> string {
    return path_rel(base, target)
}

// Positional binary-safe write. Writes every byte of `data` at
// `offset` bytes from the start of the file — the length travels with
// the slice (#2301). Returns (written, "") on success, (-1, error) on
// failure. Loops on short writes (POSIX permits returning fewer bytes
// than asked). An empty slice writes nothing and returns (0, "").
// The file must be opened in a mode admitting writes — "r+", "w+",
// "w", "a+", "wb+", etc. — via `fs.open(path, mode)`.
//
// This is the "scatter-write" primitive — reconstructing a file from
// blocks fetched out of order (rsync, zsync, parallel downloads,
// sparse-file build). For sequential append, `fs.write` is simpler.
// Success arm first — same tuple-slot-inference constraint as `size`
// (the count slot is `long`).
pwrite(file: ptr, data: byte[], offset: long) -> {
    if data.len < 0 {
        unbounded_write("pwrite")
    }
    // An empty slice may carry a null data pointer (string.bytes("") does),
    // which the C side rejects; nothing to write is a success, not an error.
    if data.len == 0 {
        long none_written = 0
        return none_written, ""
    }
    n = fs_pwrite_raw(file, data, data.len, offset)
    if n >= 0 {
        return n, ""
    }
    return -1, "pwrite failed"
}

// Positional binary-safe read. Reads up to `length` bytes from
// `offset` into an owned AetherString. Returns (bytes, n, "") on
// success — `n` may be less than `length` if EOF was reached (short
// reads are NOT an error per the POSIX convention for sparse-file
// I/O). Returns ("", 0, error) on failure.
//
// Same tuple shape as fs.read_binary so destructuring stays
// consistent.
pread(file: ptr, length: int, offset: long) -> {
    ok = fs_pread_raw(file, length, offset)
    if ok == 0 {
        return "", 0, "pread failed"
    }
    raw = fs_get_pread()
    n = fs_get_pread_length()
    owned = string_new_with_length(raw, n)
    fs_release_pread()
    return owned, n, ""
}

// Read up to `length` bytes at `offset` directly into the existing
// std.bytes buffer `buf` (a `bytes` handle), clamped to the buffer's
// capacity, with no per-call allocation or copy. After the call `buf`
// holds the bytes read and its length is the returned count, so
// bytes.get_le64 / a bytes.cursor can read them in place. This is the
// copy-free sibling of `pread` for a reused fixed-size block buffer
// (#1102): reuse one buffer across a loop instead of allocating a fresh
// string per block.
//
// Returns (n, err): `n` is the byte count (n == 0 = EOF, 0 < n < length =
// short read), `err` is "" on success or a message on I/O error. Same
// EOF / short-read / error distinction as `pread`.
pread_into(file: ptr, buf: ptr, length: int, offset: long) -> int! {
    n = fs_pread_into_raw(file, buf, length, offset)
    if n < 0 {
        return 0, "pread_into failed"
    }
    return n, ""
}

// Set the file length to `length` bytes. Extends with zero bytes if
// the new length is greater than the current size. Returns "" on
// success, an error message on failure. Required at the end of an
// out-of-order reconstruction to clip trailing padding.
ftruncate(file: ptr, length: long) -> string {
    return fs_ftruncate_raw(file, length)
}

// Flush kernel buffers for `file` to durable storage (POSIX fsync /
// Windows _commit). Required AFTER pwrite for the data-survives-crash
// guarantee — pwrite alone makes the bytes visible to other handles
// on the same machine but doesn't promise they reach the disk.
// Returns "" on success.
fsync(file: ptr) -> string {
    return fs_fsync_raw(file)
}

// The OS-level file descriptor inside an open handle, or -1 on a
// null handle (#1003). Exists for capability plumbing: open through
// the stdlib, then narrow the descriptor with
// capsicum.rights_limit(fs.fd(handle), ...) before capsicum.enter().
// The fd is owned by the handle — do not close it directly; it is
// released by close, which also frees the handle itself, so
// never call fd() on a handle that has been closed.
fd(file: ptr) -> int {
    return file_fd_raw(file)
}

// --- Recursive directory operations (#command-alikes) ------------------------
//
// copy_tree / remove_tree are the recursive counterparts to copy() (single
// file) and delete_dir() (empty dir only). Pure Aether over dir_list_raw +
// copy/mkdir_p/delete — no `cp -R` / `rm -rf` shell-out. They walk with the
// module's own dir listing (kind from readdir's d_type, no per-entry stat) so
// fs stays dependency-free. Symlinks are copied/removed as entries, never
// followed into (no cycles). Both return "" on success, an error string
// otherwise.

// --- Scoped source discovery (the `find … -name '*.ext'` replacement) --------
//
// find_ext(root, ext) collects every file under `root` whose name ends with
// `ext` (e.g. ".java"), recursively — the declarative form of
// `find <root> -name '*.<ext>'`. find_ext_excluding additionally drops files
// whose name ends with any of the newline-separated `exclude` suffixes (the
// `! -name '*Test.scala'` filters). Both return the matches as a
// newline-separated string (one path per line, no trailing newline) — the
// argfile shape a compiler `@file` wants — or "" when none match. Built on
// fs.walk (one readdir sweep per dir, no shell-out). For an arbitrary
// predicate, use fs.walk with a closure directly; these are the common case.

// _ends_any(name, suffixes) — 1 if name ends with any '\n'-separated suffix.
_ends_any(name: string, suffixes: string) -> int {
    if string_length(suffixes) == 0 { return 0 }
    n = string_length(suffixes)
    start = 0
    i = 0
    while i <= n {
        at_end = 0
        if i == n { at_end = 1 }
        is_nl = 0
        if i < n {
            if string_char_at(suffixes, i) == 10 { is_nl = 1 }
        }
        if at_end == 1 { is_nl = 1 }
        if is_nl == 1 {
            if i > start {
                suf = string_substring(suffixes, start, i)
                if _str_ends_with(name, suf) == 1 { return 1 }
            }
            start = i + 1
        }
        i = i + 1
    }
    return 0
}

// _str_ends_with(s, suffix) — 1 if s ends with suffix. Char-based (no
// std.string import in fs).
_str_ends_with(s: string, suffix: string) -> int {
    ls = string_length(s)
    lf = string_length(suffix)
    if lf > ls { return 0 }
    if lf == 0 { return 1 }
    off = ls - lf
    j = 0
    while j < lf {
        if string_char_at(s, off + j) != string_char_at(suffix, j) { return 0 }
        j = j + 1
    }
    return 1
}

find_ext(root: string, ext: string) -> string {
    return find_ext_excluding(root, ext, "")
}

// Do the walk + accumulation and return the filled strbuilder handle (a `ptr`).
// The `finish` (which produces the heap string) is kept OUT of this function on
// purpose: a function that both creates a capturing closure (the walk callback)
// AND returns a heap string mis-tracks that return — the caller's binding leaks
// (a compiler heap-tracker gap; see the ask). Returning a plain `ptr` here
// side-steps it, and find_ext_excluding below finishes it with no closure in
// scope, where the heap-string return is tracked correctly.
//
// `cnt` is a capture the callback assigns to, so it lives in a heap cell the
// walk closure and this scope share. That cell used to leak once per call
// (#2019): fs_walk_raw owned and freed the closure before returning, and the
// scope-exit free was withheld because the compiler could not see that.
// The cell is reference-counted now, and the closure is released here once
// the walk returns (fs_walk_raw's callback is `@noescape`, #2523).
_find_ext_collect(root: string, ext: string, exclude: string) -> ptr {
    sb = strbuilder.new(256)
    cnt = 0
    _n, _e = walk(root, | path: string, kind: int, depth: int | {
            if kind == STAT_KIND_FILE {
                if _str_ends_with(path, ext) == 1 {
                    if _ends_any(path, exclude) == 0 {
                        // strbuilder is a `ptr` capture appended in place (never
                        // reassigned), so the per-entry concat does not leak the
                        // way `acc = concat(acc, …)` on a captured string did.
                        if cnt > 0 { strbuilder.append(sb, "\n") }
                        strbuilder.append(sb, path)
                        cnt = cnt + 1
                    }
                }
            }
            return 0
        })
    return sb
}

find_ext_excluding(root: string, ext: string, exclude: string) -> string {
    sb = _find_ext_collect(root, ext, exclude)
    return strbuilder.finish(sb)
}

// _is_dot_entry(name) — 1 if name is "." or "..". Char-based (fs is extern-only,
// no std.string import); "." is 46.
_is_dot_entry(name: string) -> int {
    n = string_length(name)
    if n == 1 {
        if string_char_at(name, 0) == 46 { return 1 }
    }
    if n == 2 {
        if string_char_at(name, 0) == 46 {
            if string_char_at(name, 1) == 46 { return 1 }
        }
    }
    return 0
}

// remove_tree(path) — delete `path` and everything beneath it (rm -rf). A file
// is unlinked; a directory has its contents removed bottom-up, then itself. A
// missing path is success (idempotent, like `rm -rf`). Returns "" or an error.
remove_tree(path: string) -> string {
    // A link (a symlink, or on Windows a junction) is removed itself, never
    // descended into: what it points at is not part of this tree. On Windows
    // file_stat follows links, so a junction looked like a directory and
    // remove_tree deleted the files of the directory it pointed at. Checked
    // before existence, which follows the link and misses a dangling one.
    // `return unlink(path)`, as the file branch returns delete(path): an
    // interpolated error built here would make every return of this
    // function a fresh heap string, which its recursive caller does not
    // free (each link in a tree leaked one).
    if fs_is_symlink(path) == 1 {
        return unlink(path)
    }
    // Not present → nothing to do.
    if fs_path_exists(path) == 0 { return "" }
    // A plain file (or symlink): unlink it.
    k, _s, _m, serr = file_stat(path)
    if string_length(serr) == 0 {
        if k != STAT_KIND_DIR {
            return delete(path)
        }
    }
    // Directory: remove each child first, then the (now-empty) dir.
    lst = dir_list_raw(path)
    if lst != null {
        cnt = dir_list_count(lst)
        i = 0
        while i < cnt {
            name = dir_list_get(lst, i)
            i = i + 1
            if string_length(name) == 0 { continue }
            if _is_dot_entry(name) == 1 { continue }
            child = path_join(path, name)
            cerr = remove_tree(child)
            if string_length(cerr) > 0 {
                dir_list_free(lst)
                return cerr
            }
        }
        dir_list_free(lst)
    }
    return delete_dir(path)
}

// copy_tree(src, dst) — recursively copy the tree at `src` into `dst`,
// creating `dst` and every subdirectory. A regular file is copied with copy()
// (mode bits preserved); a directory is created then recursed. `dst` is
// created if absent. Returns "" or an error. (Does not delete extra files
// already under `dst` — it overlays; remove_tree(dst) first for a clean copy.)
copy_tree(src: string, dst: string) -> string {
    k, _s, _m, serr = file_stat(src)
    if string_length(serr) > 0 { return serr }
    if k != STAT_KIND_DIR {
        // Single file (or symlink target): copy it directly.
        _n, _ck, cmsg = copy(src, dst)
        return cmsg
    }
    // Directory: ensure dst exists, then copy each child.
    merr = mkdir_p(dst)
    if string_length(merr) > 0 { return merr }
    lst = dir_list_raw(src)
    if lst == null { return "cannot list directory" }
    cnt = dir_list_count(lst)
    i = 0
    out_err = ""
    while i < cnt {
        name = dir_list_get(lst, i)
        i = i + 1
        if string_length(name) == 0 { continue }
        if _is_dot_entry(name) == 1 { continue }
        s_child = path_join(src, name)
        d_child = path_join(dst, name)
        cerr = copy_tree(s_child, d_child)
        if string_length(cerr) > 0 {
            out_err = cerr
            i = cnt
        }
    }
    dir_list_free(lst)
    return out_err
}