beatrina 0.8.6

package/kernel/fileio.R

@@ -0,0 +1,656 @@
+# fileio.R — the file system, in one place, for BOTH processes.
+#
+# Sourced by serve.R (the supervisor) and by worker.R. Every function here is
+# PURE in the sense that matters for the split: it takes a request id and
+# arguments, touches the file system, and RETURNS the frame to send — it never
+# emits. The worker wraps each one in `emit(fs_x(...))`; the supervisor sends
+# the returned frame to the socket that asked. One body, two callers, so the
+# two processes cannot drift on what a path may be.
+#
+# Why the supervisor answers these at all (2026-09-09, docs/document-model-plan.md
+# D3): in the worker they queued behind a running cell — a Save waited for a
+# 40-second fit — and the document model that follows (the kernel holding the
+# open documents) cannot sit behind evaluation. The supervisor evaluates no
+# user code; listing a folder and writing bytes is not evaluation.
+#
+# `wd`: the WORKER owns the working directory (setwd() in a chunk moves it),
+# so a relative path is resolved against the wd the caller passes — the worker
+# passes getwd(), the supervisor passes the cwd the worker last reported. Every
+# path is made absolute FIRST (fs_abs), then confined (within_root), then used.
+
+#' Make a path absolute against `wd`, expanding `~`. An absolute path is
+#' returned expanded and unchanged.
+fs_abs <- function(p, wd = getwd()) {
+  p <- path.expand(p)
+  if (grepl("^(/|[A-Za-z]:[/\\]|\\\\)", p)) return(p)
+  file.path(wd, p)
+}
+
+# ── the confinement root ────────────────────────────────────────────────────
+# CARMAR_ROOT restricts every FILE command — browse, read, write, import, and
+# changing the working directory — to one subtree. It exists for managed
+# deployments where a notebook should see the project share and nothing else.
+#
+# It is a GUARDRAIL, not a sandbox, and the difference must be stated plainly
+# rather than implied: this session evaluates arbitrary R, so a determined user
+# can call file.remove() on anything their account can reach and no in-process
+# check can stop them. What the root does buy is real all the same — it stops
+# the UI (and a mis-click, a stray path, a shared notebook someone else wrote)
+# from wandering out of the project, and it makes "the notebook only touches
+# /srv/projects/x" an enforceable default rather than a hope. Containment is
+# the operating system's job: run the kernel as a user who cannot read the
+# rest, or in a container.
+confine_root <- local({
+  raw <- Sys.getenv("CARMAR_ROOT", "")
+  if (!nzchar(raw)) NULL
+  else normalizePath(path.expand(raw), mustWork = FALSE)
+})
+
+#' Canonicalise a path that may not exist yet.
+#'
+#' `normalizePath()` resolves symlinks by ASKING THE FILE SYSTEM, so it can
+#' only do it for a path that is already there; handed a path that does not
+#' exist it returns the string unchanged. That is fatal for a confinement
+#' check on a CREATE: on macOS `/var` is a symlink to `/private/var`, so a
+#' root under `tempdir()` canonicalises to `/private/var/...` while the
+#' not-yet-created file inside it stays `/var/...`, and the prefix comparison
+#' says "outside" about a path that is plainly inside.
+#'
+#' So: normalise the deepest ancestor that DOES exist, then re-append the
+#' components below it. The existing part gets real symlink resolution; the
+#' part that does not exist yet cannot contain a symlink, because there is
+#' nothing there to be one.
+#'
+#' @param p A path, absolute or relative.
+#' @return The canonical absolute path.
+canonical_path <- function(p) {
+  full <- path.expand(p)
+  if (file.exists(full)) return(normalizePath(full, mustWork = FALSE))
+  parts <- character(0)
+  at <- full
+  repeat {
+    up <- dirname(at)
+    parts <- c(basename(at), parts)
+    if (identical(up, at)) break            # reached the filesystem root
+    if (file.exists(up)) {
+      return(do.call(file.path, as.list(c(normalizePath(up, mustWork = FALSE), parts))))
+    }
+    at <- up
+  }
+  normalizePath(full, mustWork = FALSE)
+}
+
+#' Is `p` inside the confinement root (when there is one)?
+#'
+#' Compared after canonicalisation, so `..` and symlinks are resolved before
+#' the comparison rather than after — string-prefix checks on un-normalised
+#' paths are how confinement bugs happen. The trailing separator matters too:
+#' without it, /srv/project would also admit /srv/project-secrets.
+within_root <- function(p) {
+  if (is.null(confine_root)) return(TRUE)
+  if (!is.character(p) || length(p) != 1L || is.na(p)) return(FALSE)
+  full <- canonical_path(p)
+  identical(full, confine_root) ||
+    startsWith(full, paste0(confine_root, .Platform$file.sep))
+}
+
+#' The standard refusal, so every file command says the same thing.
+outside_root_msg <- function() {
+  sprintf("outside the permitted folder (%s)", confine_root)
+}
+
+#' List a directory for the Files pane.
+#'
+#' Directories first because that is how every file browser reads. A bad path
+#' answers with an `error` FIELD: the pane holding a stale bookmark must see
+#' "not a directory", not take the worker down.
+#'
+#' @param id Request id.
+#' @param path Directory to list; NULL or "" means the working directory. `~`
+#'   is expanded.
+#' @param all TRUE also lists dotfiles (never `.` / `..`). Off by default —
+#'   the same default `list.files()` has — and a client-side toggle.
+#' @return Invisibly NULL. Emits one `files` frame.
+fs_files <- function(id, path = NULL, all = FALSE, wd = getwd()) {
+  p <- if (is.null(path) || !is.character(path) || !nzchar(path[1L])) wd
+       else fs_abs(path[1L], wd)
+  p <- normalizePath(p, mustWork = FALSE)
+  if (!within_root(p)) {
+    return(list(type = "files", id = id, path = p, error = outside_root_msg()))
+    return(invisible(NULL))
+  }
+  if (!dir.exists(p)) {
+    return(list(type = "files", id = id, path = p, error = "not a directory"))
+    return(invisible(NULL))
+  }
+  if (file.access(p, mode = 4L) != 0L) {
+    return(list(type = "files", id = id, path = p, error = "not readable"))
+    return(invisible(NULL))
+  }
+  nms <- list.files(p, all.files = isTRUE(all), no.. = TRUE)
+  info <- file.info(file.path(p, nms))
+  isdir <- info$isdir %in% TRUE          # a broken symlink reports NA
+  ord <- order(!isdir, tolower(nms))
+  entries <- lapply(ord, function(i) list(
+    name = nms[i], size = as.numeric(info$size[i]),
+    mtime = as.numeric(info$mtime[i]), isdir = isdir[i]))
+  return(list(type = "files", id = id, path = p, parent = dirname(p),
+            entries = entries))
+}
+
+#' Create a folder — the file tree's New Folder.
+#'
+#' `recursive = FALSE` on purpose: the tree only ever creates a child of a
+#' folder it is already showing, so a missing intermediate means the tree is
+#' stale, and silently manufacturing the whole chain would hide that. Refuses
+#' an existing name rather than succeeding quietly, because "New Folder" that
+#' returns ok on a name already taken reads as "created" and is not.
+#'
+#' @param id Request id.
+#' @param path Absolute path of the folder to create.
+#' @return Invisibly NULL. Emits one `mkdir` frame with `path` or `error`.
+fs_mkdir <- function(id, path = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "mkdir", id = id, path = path, error = msg))
+    invisible(NULL)
+  }
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  p <- fs_abs(path, wd)
+  if (!within_root(p)) return(fail(outside_root_msg()))
+  if (file.exists(p)) return(fail("something with that name is already here"))
+  if (!dir.exists(dirname(p))) return(fail(paste0("no such folder: ", dirname(p))))
+  ok <- tryCatch(dir.create(p, recursive = FALSE), warning = function(w) FALSE,
+                 error = function(e) FALSE)
+  if (!isTRUE(ok)) return(fail("the folder could not be created"))
+  return(list(type = "mkdir", id = id, path = normalizePath(p, mustWork = FALSE)))
+  invisible(NULL)
+}
+
+#' Rename or move one entry — the tree's inline rename.
+#'
+#' BOTH ends are checked against the root. Checking only the source would let
+#' a rename carry a file OUT of the permitted folder, which is the same
+#' capability the root exists to deny; a guard that reads one end of a
+#' two-ended operation is not a guard.
+#'
+#' Refuses to clobber. An overwrite here is indistinguishable from a typo, and
+#' the tree has no undo.
+#'
+#' @param id Request id.
+#' @param path Existing absolute path.
+#' @param to Absolute destination path.
+#' @return Invisibly NULL. Emits one `renamepath` frame with `from`/`to`, or `error`.
+fs_renamepath <- function(id, path = NULL, to = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "renamepath", id = id, path = path, error = msg))
+    invisible(NULL)
+  }
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  if (!is.character(to) || length(to) != 1L || !nzchar(to)) return(fail("no new name"))
+  from <- fs_abs(path, wd)
+  dest <- fs_abs(to, wd)
+  if (!within_root(from) || !within_root(dest)) return(fail(outside_root_msg()))
+  if (!file.exists(from)) return(fail("that file is no longer here"))
+  if (file.exists(dest)) return(fail("something with that name is already here"))
+  if (!dir.exists(dirname(dest))) return(fail(paste0("no such folder: ", dirname(dest))))
+  ok <- tryCatch(file.rename(from, dest), warning = function(w) FALSE,
+                 error = function(e) FALSE)
+  if (!isTRUE(ok)) return(fail("the rename failed"))
+  return(list(type = "renamepath", id = id,
+            from = normalizePath(from, mustWork = FALSE),
+            to = normalizePath(dest, mustWork = FALSE)))
+  invisible(NULL)
+}
+
+#' Delete files and folders — the tree's Delete.
+#'
+#' Takes a VECTOR, because the tree deletes a selection and N separate round
+#' trips would leave a half-deleted selection on any failure. Each path is
+#' root-checked individually; one refusal does not cancel the others, and the
+#' frame reports exactly what went and what did not, so the tree never has to
+#' guess which rows to drop.
+#'
+#' A non-empty folder needs `recursive = TRUE` — asked for explicitly by the
+#' caller, which is the client that showed the confirmation naming the folder.
+#'
+#' @param id Request id.
+#' @param paths Character vector of absolute paths.
+#' @param recursive TRUE to remove non-empty folders.
+#' @return Invisibly NULL. Emits one `deletepath` frame: `deleted`, `failed`.
+fs_deletepath <- function(id, paths = NULL, recursive = FALSE, wd = getwd()) {
+  if (!is.character(paths) || !length(paths)) {
+    return(list(type = "deletepath", id = id, error = "no paths"))
+    return(invisible(NULL))
+  }
+  deleted <- character(0)
+  failed <- list()
+  note <- function(p, why) failed[[length(failed) + 1L]] <<- list(path = p, error = why)
+  for (raw in paths) {
+    if (!is.character(raw) || is.na(raw) || !nzchar(raw)) { note(raw, "no path"); next }
+    p <- fs_abs(raw, wd)
+    if (!within_root(p)) { note(p, outside_root_msg()); next }
+    if (!file.exists(p)) { note(p, "already gone"); next }
+    is_dir <- dir.exists(p)
+    if (is_dir && !isTRUE(recursive) && length(list.files(p, all.files = TRUE, no.. = TRUE))) {
+      note(p, "the folder is not empty")
+      next
+    }
+    ok <- tryCatch(unlink(p, recursive = is_dir, force = FALSE) == 0L,
+                   warning = function(w) FALSE, error = function(e) FALSE)
+    # unlink() reports 0 for "nothing to do" as well as success, so the file
+    # system is asked again rather than trusting the status code.
+    if (isTRUE(ok) && !file.exists(p)) deleted <- c(deleted, p) else note(p, "could not be deleted")
+  }
+  return(list(type = "deletepath", id = id, deleted = I(as.list(deleted)),
+            failed = I(failed)))
+  invisible(NULL)
+}
+
+#' Copy a file or folder — the tree's Duplicate.
+#'
+#' Both ends root-checked, for the same reason rename checks both: a copy is a
+#' two-ended operation, and a guard that reads one end lets data OUT.
+#'
+#' Refuses to clobber. `file.copy(overwrite = FALSE)` returns FALSE rather than
+#' erroring on a collision, so the check is explicit and the message says which
+#' of the two things went wrong.
+#'
+#' @param id Request id.
+#' @param path Existing absolute path.
+#' @param to Absolute destination path.
+#' @return Invisibly NULL. Emits one `copypath` frame with `from`/`to`, or `error`.
+fs_copypath <- function(id, path = NULL, to = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "copypath", id = id, path = path, error = msg))
+    invisible(NULL)
+  }
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  if (!is.character(to) || length(to) != 1L || !nzchar(to)) return(fail("no destination"))
+  from <- fs_abs(path, wd)
+  dest <- fs_abs(to, wd)
+  if (!within_root(from) || !within_root(dest)) return(fail(outside_root_msg()))
+  if (!file.exists(from)) return(fail("that file is no longer here"))
+  if (file.exists(dest)) return(fail("something with that name is already here"))
+  if (!dir.exists(dirname(dest))) return(fail(paste0("no such folder: ", dirname(dest))))
+  ok <- tryCatch({
+    if (dir.exists(from)) {
+      # file.copy(recursive=) copies the DIRECTORY INTO the target, so the
+      # destination must exist first and is named by its parent, not itself.
+      dir.create(dest, recursive = FALSE)
+      kids <- list.files(from, all.files = TRUE, no.. = TRUE, full.names = TRUE)
+      all(file.copy(kids, dest, recursive = TRUE, copy.date = TRUE))
+    } else {
+      file.copy(from, dest, overwrite = FALSE, copy.date = TRUE)
+    }
+  }, warning = function(w) FALSE, error = function(e) FALSE)
+  if (!isTRUE(ok) || !file.exists(dest)) return(fail("the copy failed"))
+  return(list(type = "copypath", id = id,
+            from = normalizePath(from, mustWork = FALSE),
+            to = normalizePath(dest, mustWork = FALSE)))
+  invisible(NULL)
+}
+
+#' Show one entry in the desktop file manager.
+#'
+#' The path is root-checked and handed to the platform opener as an ARGUMENT
+#' VECTOR, never interpolated into a shell string: a file called
+#' `; rm -rf ~` is a legal filename, and `system()` on a composed string would
+#' run it. `system2()` with a character vector does not go through a shell.
+#'
+#' @param id Request id.
+#' @param path Absolute path to reveal.
+#' @return Invisibly NULL. Emits one `revealpath` frame.
+fs_revealpath <- function(id, path = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "revealpath", id = id, path = path, error = msg))
+    invisible(NULL)
+  }
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  p <- fs_abs(path, wd)
+  if (!within_root(p)) return(fail(outside_root_msg()))
+  if (!file.exists(p)) return(fail("that file is no longer here"))
+  p <- normalizePath(p, mustWork = TRUE)
+  sysname <- unname(Sys.info()[["sysname"]])
+  status <- tryCatch(switch(sysname,
+    Darwin  = system2("/usr/bin/open", c("-R", p), stdout = FALSE, stderr = FALSE),
+    Windows = system2("explorer", sprintf("/select,%s", p), stdout = FALSE, stderr = FALSE),
+    system2("xdg-open", dirname(p), stdout = FALSE, stderr = FALSE)),
+    warning = function(w) 0L, error = function(e) 1L)
+  # Windows explorer returns 1 on success; only a hard failure is reported.
+  if (!identical(sysname, "Windows") && !identical(as.integer(status), 0L)) {
+    return(fail("the file manager could not be opened"))
+  }
+  return(list(type = "revealpath", id = id, path = p))
+  invisible(NULL)
+}
+
+#' Read a text file — the script editor's Open.
+#'
+#' Text only, and capped: the editor is for .R scripts, and handing a 400 MB
+#' CSV to a textarea is not an editing session, it is a hung tab. A binary
+#' file is refused by the NUL byte rather than rendered as mojibake.
+#'
+#' @param id Request id.
+#' @param path File to read; `~` is expanded.
+#' @return Invisibly NULL. Emits one `readfile` frame with `text`, or `error`.
+MAX_TEXT_BYTES <- 4e6
+
+#' Decode file bytes into the ONE text the page edits, and say how.
+#'
+#' Until 7.18 every byte that was not valid UTF-8 was silently dropped between
+#' `rawToChar` and the JSON frame: a Latin-1 `.tex` (`\usepackage[latin1]
+#' {inputenc}`, still common) opened as "Caf" for "Café" with no error, and a
+#' save was then refused with the wrong message. The page edits UTF-8; the
+#' file keeps its own encoding; this pair is the boundary. Only two encodings
+#' are named because only two are decidable from bytes alone — valid UTF-8 is
+#' UTF-8, and anything else is read as Latin-1, which every byte sequence is.
+#'
+#' @param raw_bytes Raw vector.
+#' @return list(text = UTF-8 string, encoding = "utf-8" | "latin1"), or NULL
+#'   when the bytes cannot be made into a string at all.
+text_from_bytes <- function(raw_bytes) {
+  text <- tryCatch(rawToChar(raw_bytes), error = function(e) NULL)
+  if (is.null(text)) return(NULL)
+  if (validUTF8(text)) {
+    Encoding(text) <- "UTF-8"
+    return(list(text = text, encoding = "utf-8"))
+  }
+  latin <- iconv(text, from = "latin1", to = "UTF-8")
+  if (is.na(latin)) return(NULL)
+  list(text = latin, encoding = "latin1")
+}
+
+#' Encode the page's UTF-8 text back into the file's bytes.
+#' @param text UTF-8 string.
+#' @param encoding "utf-8" (default) or "latin1", as `text_from_bytes` reported.
+#' @return Raw vector, or a character error message when `text` holds a
+#'   character the encoding cannot carry (a `€` in a Latin-1 file): the save
+#'   fails closed and says which, rather than writing a `?`.
+bytes_from_text <- function(text, encoding = "utf-8") {
+  text <- enc2utf8(text)
+  if (identical(encoding, "latin1")) {
+    out <- iconv(text, from = "UTF-8", to = "latin1")
+    if (is.na(out)) {
+      return("the file is Latin-1 and the text now holds a character Latin-1 cannot store; use Save As to write it as UTF-8")
+    }
+    return(charToRaw(out))
+  }
+  if (!identical(encoding, "utf-8")) return(sprintf("unknown file encoding '%s'", encoding))
+  charToRaw(text)
+}
+
+file_encoding_arg <- function(encoding) {
+  if (is.character(encoding) && length(encoding) == 1L && nzchar(encoding)) encoding else "utf-8"
+}
+
+fs_readfile <- function(id, path = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "readfile", id = id, path = path, error = msg))
+    invisible(NULL)
+  }
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  p <- fs_abs(path, wd)
+  if (!within_root(p)) return(fail(outside_root_msg()))
+  if (!file.exists(p) || dir.exists(p)) return(fail("not a readable file"))
+  size <- file.info(p)$size
+  if (isTRUE(size > MAX_TEXT_BYTES)) {
+    return(fail(sprintf("too large to edit (%.1f MB)", size / 1e6)))
+  }
+  raw_bytes <- tryCatch(readBin(p, "raw", n = size),
+                        error = function(e) conditionMessage(e))
+  if (is.character(raw_bytes)) return(fail(raw_bytes))
+  if (any(raw_bytes == as.raw(0L))) return(fail("not a text file"))
+  decoded <- text_from_bytes(raw_bytes)
+  if (is.null(decoded)) return(fail("could not decode as text"))
+  return(list(type = "readfile", id = id, path = normalizePath(p), text = decoded$text,
+            encoding = decoded$encoding))
+}
+
+#' Replace (or create) `p`: write a temp file beside it, then rename OVER the
+#' target in one filesystem operation. Never move the original away first:
+#' readers must see either the old file or the new one, not a missing path.
+#' R uses rename(2) on POSIX and replacement-enabled MoveFileExW on Windows.
+#' This is namespace atomicity on supported local filesystems, not an fsync /
+#' power-loss durability guarantee. The mode of an existing file is kept.
+#' Returns NULL on success or the sentence to report.
+fs_replace_atomic <- function(p, body_bytes) {
+  temp <- tempfile(pattern = ".carmar-save-", tmpdir = dirname(p))
+  existed <- file.exists(p)
+  old_mode <- if (existed) file.info(p)$mode else NULL
+  cleanup_save <- function() {
+    if (file.exists(temp)) unlink(temp)
+  }
+  # Error replies are observable by the browser immediately. Clean first so a
+  # completed failure reply also means recovery has finished on disk.
+  fail_after_cleanup <- function(msg) {
+    cleanup_save()
+    msg
+  }
+  on.exit(cleanup_save(), add = TRUE)
+  ok <- tryCatch({
+    con <- file(temp, open = "wb")
+    writeBin(body_bytes, con)
+    close(con)
+    con <- NULL
+    if (!is.null(old_mode)) Sys.chmod(temp, mode = old_mode)
+    TRUE
+  }, error = function(e) conditionMessage(e),
+  finally = if (exists("con", inherits = FALSE) && !is.null(con)) try(close(con), silent = TRUE))
+  if (is.character(ok)) return(fail_after_cleanup(ok))
+  # Keep the existing test knob as an alias for the pre-replacement boundary.
+  # The original is still at its path; a failure needs no restoration rename.
+  if (identical(Sys.getenv("CARMAR_TEST_SAVE_FAILURE", ""), "after-backup")) {
+    return(fail_after_cleanup("simulated failure before replacement"))
+  }
+  replaced <- tryCatch(suppressWarnings(file.rename(temp, p)), error = function(e) FALSE)
+  if (!isTRUE(replaced)) {
+    return(fail_after_cleanup("could not atomically replace the file; the original was left unchanged"))
+  }
+  NULL
+}
+
+#' Write a text file — the script editor's Save.
+#'
+#' Writes exactly the bytes given. The directory must already exist: a Save
+#' that silently creates a tree is a Save that puts the file somewhere else than
+#' the user believes. The replacement is a same-directory rename, and an
+#' optional exact previous value makes an editor Save fail closed if another
+#' program changed the file since it was opened.
+#'
+#' Binary travels as `base64`: the page's blob exports (xlsx, png, a plot)
+#' had no way onto the disk from a webview with no download delegate, and R
+#' is the one process here that can write a file where the person asked. The
+#' decoded size is capped at the same MAX_TEXT_BYTES — 4 MB decoded is a
+#' 5.4 MB frame, under the supervisor's 8 MB cap — and the exact-content
+#' check is refused because it is defined over TEXT (re-encoded the way the
+#' file was decoded); a binary file has no such previous value to compare.
+#'
+#' @param id Request id.
+#' @param path Destination; `~` is expanded.
+#' @param text Contents.
+#' @param base64 Binary contents, base64-encoded; when given, `text` is ignored.
+#' @return Invisibly NULL. Emits one `writefile` frame with `path`, or `error`.
+fs_writefile <- function(id, path = NULL, text = "", expected = NULL, encoding = NULL,
+                         base64 = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "writefile", id = id, path = path, error = msg))
+    invisible(NULL)
+  }
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  p <- fs_abs(path, wd)
+  if (!within_root(p)) return(fail(outside_root_msg()))
+  if (dir.exists(p)) return(fail("that is a directory"))
+  if (!dir.exists(dirname(p))) return(fail(paste0("no such folder: ", dirname(p))))
+  binary <- is.character(base64) && length(base64) == 1L && nzchar(base64)
+  if (binary) {
+    if (!is.null(expected)) return(fail("the exact-content check applies to text saves"))
+    body_bytes <- tryCatch(jsonlite::base64_dec(base64), error = function(e) NULL)
+    if (!is.raw(body_bytes)) return(fail("not valid base64"))
+    if (length(body_bytes) > MAX_TEXT_BYTES) return(fail("too large to write through R"))
+  } else {
+    if (!is.null(text) && !is.character(text)) return(fail("text must be a string"))
+    if (is.character(text) && sum(nchar(text, type = "bytes")) > MAX_TEXT_BYTES) {
+      return(fail("too large to save from the editor"))
+    }
+    body <- if (is.character(text) && length(text)) paste(text, collapse = "\n") else ""
+    encoding <- file_encoding_arg(encoding)
+    body_bytes <- bytes_from_text(body, encoding)
+    if (is.character(body_bytes)) return(fail(body_bytes))
+  }
+  if (!is.null(expected)) {
+    if (!is.character(expected)) return(fail("expected text must be a string"))
+    before <- paste(expected, collapse = "\n")
+    if (!file.exists(p)) return(fail("the file was removed after it was opened; nothing was written"))
+    size <- file.info(p)$size
+    raw <- tryCatch(readBin(p, "raw", n = size), error = function(e) NULL)
+    # Compare BYTES to bytes: the page's expectation is re-encoded the way
+    # the file was decoded, so a Latin-1 file matches its own bytes.
+    before_bytes <- bytes_from_text(before, encoding)
+    if (is.null(raw) || is.character(before_bytes) || !identical(raw, before_bytes)) {
+      return(fail("the file changed on disk after it was opened; nothing was written"))
+    }
+  }
+  err <- fs_replace_atomic(p, body_bytes)
+  if (!is.null(err)) return(fail(err))
+  # Built field by field: a `encoding = NULL` inside list() is an element the
+  # supervisor's JSON would render as `{}`, and a binary file has no encoding.
+  reply <- list(type = "writefile", id = id, path = normalizePath(p), bytes = length(body_bytes))
+  if (binary) reply$binary <- TRUE else reply$encoding <- encoding
+  return(reply)
+}
+
+#' Atomically replace several existing text files after exact-content checks.
+#'
+#' Every temporary and backup lives beside its target, so rename stays on one
+#' filesystem. All preconditions are checked before the first rename; a later
+#' failure restores every target already swapped.
+fs_writefiles_atomic <- function(id, files = NULL, wd = getwd()) {
+  fail <- function(msg) {
+    return(list(type = "writefiles_atomic", id = id, error = msg))
+    invisible(NULL)
+  }
+  records <- if (is.data.frame(files)) {
+    lapply(seq_len(nrow(files)), function(i) as.list(files[i, , drop = FALSE]))
+  } else if (is.list(files)) files else list()
+  if (!length(records)) return(fail("no files"))
+  if (length(records) > 50L) return(fail("too many files in one change"))
+
+  plans <- list()
+  for (item in records) {
+    p <- if (is.list(item) && is.character(item$path) && length(item$path)) fs_abs(item$path[[1L]], wd) else ""
+    before <- if (is.list(item) && is.character(item$before)) paste(item$before, collapse = "\n") else NULL
+    after <- if (is.list(item) && is.character(item$after)) paste(item$after, collapse = "\n") else NULL
+    if (!nzchar(p) || is.null(before) || is.null(after)) return(fail("each file needs path, before and after"))
+    if (!within_root(p)) return(fail(outside_root_msg()))
+    if (!file.exists(p) || dir.exists(p)) return(fail(paste0("not an existing text file: ", p)))
+    size <- file.info(p)$size
+    raw <- tryCatch(readBin(p, "raw", n = size), error = function(e) NULL)
+    # The file's own encoding decides the comparison and the write, exactly
+    # as emit_writefile does; a rename across a Latin-1 project stays exact.
+    encoding <- file_encoding_arg(if (is.list(item)) item$encoding else NULL)
+    before_bytes <- bytes_from_text(before, encoding)
+    after_bytes <- bytes_from_text(after, encoding)
+    if (is.character(after_bytes)) return(fail(paste0(basename(p), ": ", after_bytes)))
+    if (is.null(raw) || is.character(before_bytes) || !identical(raw, before_bytes)) {
+      return(fail(paste0(basename(p), " changed after the preview; nothing was written")))
+    }
+    if (length(after_bytes) > MAX_TEXT_BYTES) return(fail(paste0(basename(p), " is too large")))
+    plans[[length(plans) + 1L]] <- list(path = p, before = before, after = after, bytes = after_bytes,
+      mode = file.info(p)$mode,
+      temp = tempfile(pattern = ".carmar-new-", tmpdir = dirname(p)),
+      backup = tempfile(pattern = ".carmar-old-", tmpdir = dirname(p)))
+  }
+
+  cleanup <- function() {
+    for (plan in plans) {
+      if (file.exists(plan$temp)) unlink(plan$temp)
+      if (file.exists(plan$backup) && file.exists(plan$path)) unlink(plan$backup)
+    }
+  }
+  on.exit(cleanup(), add = TRUE)
+  for (plan in plans) {
+    con <- NULL
+    ok <- tryCatch({
+      con <- file(plan$temp, open = "wb")
+      writeBin(plan$bytes, con)
+      close(con)
+      con <- NULL
+      Sys.chmod(plan$temp, mode = plan$mode)
+      TRUE
+    }, error = function(e) conditionMessage(e),
+    finally = if (!is.null(con)) try(close(con), silent = TRUE))
+    if (!identical(ok, TRUE)) return(fail(as.character(ok)))
+  }
+
+  swapped <- integer(0)
+  for (i in seq_along(plans)) {
+    plan <- plans[[i]]
+    ok <- file.rename(plan$path, plan$backup) && file.rename(plan$temp, plan$path)
+    if (!ok) {
+      if (!file.exists(plan$path) && file.exists(plan$backup)) file.rename(plan$backup, plan$path)
+      for (j in rev(swapped)) {
+        prior <- plans[[j]]
+        if (file.exists(prior$path)) unlink(prior$path)
+        if (file.exists(prior$backup)) file.rename(prior$backup, prior$path)
+      }
+      return(fail("could not replace every file; all completed replacements were restored"))
+    }
+    swapped <- c(swapped, i)
+  }
+  for (plan in plans) if (file.exists(plan$backup)) unlink(plan$backup)
+  return(list(type = "writefiles_atomic", id = id,
+            paths = I(vapply(plans, function(plan) normalizePath(plan$path), character(1)))))
+}
+
+
+#' Write raw bytes to `path` (absolute or relative to `wd`), atomically and
+#' confined — the body of `PUT /files`. Returns the frame to report.
+fs_write_raw <- function(id, path = NULL, bytes = raw(0), wd = getwd(), expected = NULL) {
+  fail <- function(msg) list(type = "writefile", id = id, path = path, error = msg)
+  if (!is.character(path) || length(path) != 1L || !nzchar(path)) return(fail("no path"))
+  if (!is.raw(bytes)) return(fail("no bytes"))
+  if (!is.null(expected) && !is.raw(expected)) return(fail("expected content must be bytes"))
+  p <- fs_abs(path, wd)
+  if (!within_root(p)) return(fail(outside_root_msg()))
+  if (dir.exists(p)) return(fail("that is a directory"))
+  if (!dir.exists(dirname(p))) return(fail(paste0("no such folder: ", dirname(p))))
+  if (!is.null(expected)) {
+    if (!file.exists(p)) return(fail("the file was removed after it was opened; nothing was written"))
+    size <- file.info(p)$size
+    before <- if (is.finite(size) && size == length(expected))
+      tryCatch(readBin(p, "raw", n = size), error = function(e) NULL) else NULL
+    if (is.null(before) || !identical(before, expected)) {
+      return(fail("the file changed on disk after it was opened; nothing was written"))
+    }
+  }
+  err <- fs_replace_atomic(p, bytes)
+  if (!is.null(err)) return(fail(err))
+  list(type = "writefile", id = id, path = normalizePath(p), bytes = length(bytes), binary = TRUE)
+}
+
+#' A Content-Type for `GET /files`, by extension; anything else is opaque.
+fs_content_type <- function(path) {
+  base <- basename(path)
+  ext <- if (grepl("\\.", base)) tolower(sub("^.*\\.", "", base)) else ""
+  types <- c(png = "image/png", jpg = "image/jpeg", jpeg = "image/jpeg", gif = "image/gif",
+             svg = "image/svg+xml", pdf = "application/pdf", html = "text/html; charset=utf-8",
+             htm = "text/html; charset=utf-8", csv = "text/csv; charset=utf-8",
+             tsv = "text/tab-separated-values; charset=utf-8", txt = "text/plain; charset=utf-8",
+             md = "text/markdown; charset=utf-8", qmd = "text/markdown; charset=utf-8",
+             rmd = "text/markdown; charset=utf-8", carmd = "text/markdown; charset=utf-8",
+             r = "text/plain; charset=utf-8", tex = "application/x-tex", bib = "text/plain; charset=utf-8",
+             json = "application/json", xlsx = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+             docx = "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+             zip = "application/zip", rdata = "application/octet-stream", rds = "application/octet-stream")
+  hit <- if (nzchar(ext) && ext %in% names(types)) types[[ext]] else "application/octet-stream"
+  hit
+}
+
+#' A file name safe inside a Content-Disposition header: ASCII, no quotes,
+#' no control characters, never empty.
+fs_disposition_name <- function(name) {
+  n <- iconv(as.character(name), to = "ASCII", sub = "_")
+  n <- gsub('[^A-Za-z0-9._ -]', "_", n)
+  n <- trimws(n)
+  if (!nzchar(n)) "download" else n
+}