beatrina 0.8.6

package/failsafe/journal.R

@@ -0,0 +1,684 @@
+# journal.R — the durable document journal, answered by the SUPERVISOR.
+#
+# The page's history engine (lib/history/transaction-engine.js) accepts edits
+# in memory; lib/history/journal.js turns each accepted transaction into a
+# RECORD and hands ordered batches here. This file is the store: an append-only
+# NDJSON journal plus a full checkpoint per document, under the user's own
+# app-data directory, 0700/0600. It never evaluates anything and never reads a
+# document's text for any purpose but writing it back.
+#
+# WHY THE SUPERVISOR AND NOT A FIFTH CHILD. The plan (robust.md B1) asked for a
+# persistence service independent of the R worker. The supervisor already IS
+# that for file ops (fileio.R, docs/document-model-plan.md D3): it evaluates
+# no user code, it is never behind a running cell, and a 20 MB PUT measured
+# 97 ms end to end in its loop. A journal append is a few hundred bytes; a
+# checkpoint is the document plus its Undo stacks, single-digit megabytes at
+# the outside. Spawning a fourth R process to write a kilobyte would buy
+# nothing but a queue. Every function here is PURE in fileio.R's sense —
+# takes a request, touches disk, RETURNS the frame — so if a measurement ever
+# says otherwise, moving them into a child is a routing change.
+#
+# ── the on-disk shape ──────────────────────────────────────────────────────
+#
+#   <root>/<key>/                 key = the document's durable key, ':' → '__'
+#     journal.ndjson              one record per line: "<bytes>\t<json>\n"
+#     checkpoint.json             the newest checkpoint envelope (a JSON string
+#                                 the page's checkpoint codec wrote; its SHA-256
+#                                 is inside, verified by the page on load)
+#     checkpoint.rev              the revision of that envelope
+#     pins/<rev>.json             a named version, with its content
+#     meta.json                   display name, file binding, gaps, updated
+#     journal.corrupt-<time>      bytes cut from a journal that did not end
+#                                 at a line boundary — kept as evidence
+#
+# The record line carries its own byte length so a torn write (power loss
+# between the write and the fsync the OS never promised) is detected at the
+# next open: the tail is cut at the last complete, contiguous line and the
+# cut bytes are moved aside rather than deleted. Contiguity (each record's
+# baseRevision equals the previous record's revision) is checked on every
+# append; a mismatch is refused as `discontiguous` and the page re-bases with
+# a full checkpoint. Nothing here rewrites an accepted record.
+#
+# What is NOT promised, in words: R has no fsync. `close()` hands the bytes to
+# the operating system; a power cut before the OS writes them loses the tail,
+# and the next open says so. The store is safe against the CarmaR process
+# dying, not against the machine dying.
+
+journal_root <- function() {
+  root <- Sys.getenv("CARMAR_HISTORY_DIR", "")
+  if (!nzchar(root)) {
+    state <- Sys.getenv("CARMAR_STATE", "")
+    if (!nzchar(state)) state <- tools::R_user_dir("carmar", "data")
+    root <- file.path(state, "history")
+  }
+  root
+}
+JOURNAL_ENABLED <- !identical(Sys.getenv("CARMAR_NO_JOURNAL", ""), "1")
+# Per-document byte budget for the journal file. Above it, records at or
+# below the newest checkpoint are compacted away (the checkpoint holds the
+# state and both Undo stacks; pins hold their own content), never the tail.
+journal_budget <- function() {
+  v <- suppressWarnings(as.numeric(Sys.getenv("CARMAR_HISTORY_BUDGET", "")))
+  if (!length(v) || is.na(v) || v < 65536) 64 * 1024 * 1024 else v
+}
+JOURNAL_KEY_RE <- "^[a-z]+:[A-Za-z0-9._~-]{1,200}$"
+JOURNAL_MAX_REPLY_BYTES <- 6e6           # under the 8 MB frame cap, with room
+
+journal_valid_key <- function(key) is.character(key) && length(key) == 1L && !is.na(key) && grepl(JOURNAL_KEY_RE, key)
+
+journal_dir <- function(key) file.path(journal_root(), sub(":", "__", key, fixed = TRUE))
+
+#' A directory only this user may enter; created on first use.
+journal_ensure_dir <- function(path) {
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE, showWarnings = FALSE)
+    if (!dir.exists(path)) stop("could not create the history directory")
+  }
+  Sys.chmod(path, "0700")
+  invisible(path)
+}
+
+journal_error <- function(type, id, code, message, ...) {
+  list(type = type, id = id, error = message, code = code, ...)
+}
+
+# ── the journal file ───────────────────────────────────────────────────────
+
+#' Every complete, contiguous record line, with the byte offset where the
+#' verified prefix ends. Reads the whole file: the tail after a checkpoint is
+#' small by design (checkpoints every 40 edits), and a large one means the
+#' page could not checkpoint for a long time, which `open` reports.
+journal_scan <- function(path) {
+  empty <- list(records = character(), revisions = integer(), offsets = integer(), end = 0L, last = NA_integer_, torn = FALSE)
+  if (!file.exists(path)) return(empty)
+  size <- file.info(path)$size
+  if (is.na(size) || size == 0) return(empty)
+  raw <- readBin(path, "raw", n = size)
+  tab <- as.raw(9L); nl <- as.raw(10L)
+  records <- character(); revs <- integer(); offsets <- integer()
+  pos <- 1L; total <- length(raw); torn <- FALSE; last <- NA_integer_
+  # Byte scanning on purpose: the length prefix counts BYTES (that is what a
+  # torn write leaves), so character-indexed substring() would drift on the
+  # first multi-byte record. A while loop is the honest shape of "walk the
+  # buffer until it stops being well-formed".
+  while (pos <= total) {
+    t <- pos
+    while (t <= total && t < pos + 12L && raw[t] != tab) t <- t + 1L
+    if (t > total || raw[t] != tab) { torn <- TRUE; break }
+    len <- suppressWarnings(as.integer(rawToChar(raw[pos:(t - 1L)])))
+    if (is.na(len) || len < 2L) { torn <- TRUE; break }
+    start <- t + 1L; end <- start + len - 1L
+    if (end + 1L > total || raw[end + 1L] != nl) { torn <- TRUE; break }
+    # rawToChar refuses an embedded NUL (a zeroed sector reads as one): that is
+    # corruption, and corruption ends the verified prefix rather than the scan.
+    json <- tryCatch(rawToChar(raw[start:end]), error = function(e) NULL)
+    if (is.null(json)) { torn <- TRUE; break }
+    Encoding(json) <- "UTF-8"
+    parsed <- tryCatch(jsonlite::fromJSON(json, simplifyVector = FALSE), error = function(e) NULL)
+    if (is.null(parsed) || !is.numeric(parsed$revision) || !is.numeric(parsed$baseRevision)
+        || (!is.na(last) && parsed$baseRevision != last)) { torn <- TRUE; break }
+    records[[length(records) + 1L]] <- json
+    revs[[length(revs) + 1L]] <- as.integer(parsed$revision)
+    offsets[[length(offsets) + 1L]] <- pos
+    last <- as.integer(parsed$revision)
+    pos <- end + 2L
+  }
+  list(records = records, revisions = revs, offsets = offsets, end = pos - 1L, last = last, torn = torn)
+}
+
+#' Cut a torn tail at the last complete record, keeping the cut bytes.
+journal_repair <- function(path, scan) {
+  if (!scan$torn) return(FALSE)
+  size <- file.info(path)$size
+  if (is.na(size) || scan$end >= size) return(FALSE)
+  raw <- readBin(path, "raw", n = size)
+  evidence <- paste0(path, ".corrupt-", format(Sys.time(), "%Y%m%d-%H%M%S"))
+  writeBin(raw[(scan$end + 1L):size], evidence)
+  Sys.chmod(evidence, "0600")
+  writeBin(raw[seq_len(scan$end)], path)
+  Sys.chmod(path, "0600")
+  TRUE
+}
+
+journal_write_private <- function(path, text) {
+  con <- file(path, open = "wb")
+  on.exit(close(con), add = TRUE)
+  writeBin(charToRaw(enc2utf8(text)), con)
+  close(con); on.exit()
+  if (!isTRUE(Sys.chmod(path, "0600"))) stop("could not make the history file private")
+  invisible(TRUE)
+}
+
+#' Atomic replace within the same directory: write a sibling, rename over.
+journal_replace <- function(path, text) {
+  temp <- tempfile(pattern = ".carmar-journal-", tmpdir = dirname(path))
+  journal_write_private(temp, text)
+  if (!isTRUE(suppressWarnings(file.rename(temp, path)))) {
+    unlink(temp)
+    stop("could not replace the history file atomically; the previous one was left unchanged")
+  }
+  invisible(TRUE)
+}
+
+journal_read_meta <- function(dir) {
+  path <- file.path(dir, "meta.json")
+  if (!file.exists(path)) return(list(schema = 1L, gaps = list(), pins = list()))
+  meta <- tryCatch(jsonlite::fromJSON(path, simplifyVector = FALSE), error = function(e) NULL)
+  if (!is.list(meta)) list(schema = 1L, gaps = list(), pins = list()) else meta
+}
+journal_write_meta <- function(dir, meta) {
+  meta$updated <- as.numeric(Sys.time()) * 1000
+  journal_replace(file.path(dir, "meta.json"),
+                  as.character(jsonlite::toJSON(meta, auto_unbox = TRUE, null = "null", digits = NA)))
+}
+journal_checkpoint_revision <- function(dir) {
+  path <- file.path(dir, "checkpoint.rev")
+  if (!file.exists(path)) return(NA_integer_)
+  v <- suppressWarnings(as.integer(readLines(path, warn = FALSE)[1L]))
+  if (length(v) != 1L || is.na(v)) NA_integer_ else v
+}
+
+#' The store's view of one document: scanned, repaired if torn, cached.
+#' `sockets` is the supervisor's; tests pass their own environment.
+journal_state <- function(key, cache = journal_cache) {
+  st <- cache[[key]]
+  dir <- journal_dir(key)
+  if (!is.null(st) && identical(st$dir, dir)) return(st)
+  journal_ensure_dir(dir)
+  path <- file.path(dir, "journal.ndjson")
+  scan <- journal_scan(path)
+  repaired <- journal_repair(path, scan)
+  cp <- journal_checkpoint_revision(dir)
+  st <- new.env(parent = emptyenv())
+  st$dir <- dir; st$path <- path
+  st$last <- if (!is.na(scan$last)) scan$last else if (!is.na(cp)) cp else NA_integer_
+  st$checkpoint <- cp
+  st$repaired <- repaired
+  st$bytes <- if (file.exists(path)) file.info(path)$size else 0
+  cache[[key]] <- st
+  st
+}
+journal_cache <- new.env(parent = emptyenv())
+
+# ── the ops ────────────────────────────────────────────────────────────────
+# Each returns a FRAME. Records travel as VERBATIM JSON STRINGS in both
+# directions: the page serialised each one and signed it (sha), and re-encoding
+# through jsonlite would collapse `abandoned: ["x"]` to `"x"` and
+# `operations: [op]` to `op` (auto_unbox) — the exact fidelity bug relay_frame
+# exists to prevent. `journal_frame()` splices them into the reply by hand.
+
+journal_open <- function(id, key = NULL, meta = NULL, takeover = FALSE) {
+  if (!JOURNAL_ENABLED) return(journal_error("journal_open", id, "unavailable", "The document journal is disabled (CARMAR_NO_JOURNAL=1)."))
+  if (!journal_valid_key(key)) return(journal_error("journal_open", id, "invalid_key", "A journal needs a durable document key."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_open", id, "io", conditionMessage(st)))
+  stored <- journal_read_meta(st$dir)
+  if (is.list(meta) && length(meta)) {
+    stored$display <- meta
+    tryCatch(journal_write_meta(st$dir, stored), error = function(e) NULL)
+  }
+  # ADVISORY lease: which live process last opened this key. Two windows on
+  # one file would otherwise interleave records into one journal. The holder
+  # is reported so the page can decline to write; a dead pid is not a holder.
+  # This is disclosure, not a fence — writer authority is stage C's.
+  lease <- journal_lease(st$dir, key, takeover)
+  if (!is.null(lease$error)) return(journal_error("journal_open", id, "io", lease$error))
+  list(type = "journal_open", id = id, key = key, heldBy = lease$held, epoch = lease$epoch, takenOver = isTRUE(lease$takenOver),
+       exists = !is.na(st$last) || !is.na(st$checkpoint),
+       checkpointRevision = if (is.na(st$checkpoint)) NULL else st$checkpoint,
+       durableRevision = if (is.na(st$last)) NULL else st$last,
+       repaired = isTRUE(st$repaired), bytes = st$bytes, budget = journal_budget(),
+       pins = journal_pins(st$dir), meta = stored$display %||% NULL, gaps = stored$gaps %||% list())
+}
+
+#' READ-ONLY: does the store keep a history for `key`, from what PATH was it
+#' last saved, and does THAT path still exist on disk? The page asks this to
+#' tell a copied file from a moved one (stage C1): a file carrying an embedded
+#' id whose stored path differs from where it just opened is a COPY when the
+#' old path still exists, a MOVE when it is gone. Unlike `journal_open` this
+#' takes no lease and CREATES NOTHING — a probe of an unknown key must not
+#' leave an empty history directory behind, so it never calls `journal_state`.
+journal_probe <- function(id, key = NULL) {
+  if (!JOURNAL_ENABLED) return(journal_error("journal_probe", id, "unavailable", "The document journal is disabled (CARMAR_NO_JOURNAL=1)."))
+  if (!journal_valid_key(key)) return(journal_error("journal_probe", id, "invalid_key", "A journal needs a durable document key."))
+  dir <- journal_dir(key)
+  if (!dir.exists(dir)) return(list(type = "journal_probe", id = id, key = key, exists = FALSE, path = NULL, pathExists = FALSE))
+  stored <- journal_read_meta(dir)
+  cp <- journal_checkpoint_revision(dir)
+  exists <- file.exists(file.path(dir, "journal.ndjson")) || !is.na(cp)
+  path <- stored$display$path
+  ok_path <- is.character(path) && length(path) == 1L && nzchar(path)
+  list(type = "journal_probe", id = id, key = key, exists = isTRUE(exists),
+       path = if (ok_path) path else NULL,
+       pathExists = isTRUE(ok_path && file.exists(path)))
+}
+
+#' The writer lease: WHO may append, decided on disk, fenced by an epoch.
+#'
+#' `open` issues a lease `{pid, port, epoch, at}` and returns the epoch; every
+#' append and checkpoint must carry it, and a write whose epoch is not the
+#' current one is refused as `fenced` — the old writer learns it lost the
+#' document rather than interleaving into it. A LIVE other holder (its pid
+#' answers signal 0) is reported, and the caller gets no epoch unless it asks
+#' for a `takeover`, which bumps the epoch: the previous holder's next write is
+#' then fenced, atomically, by the rename that replaced the lease file. A
+#' dead holder is simply replaced. The epoch is monotone per key and comes
+#' from the lease file itself, so a restarted supervisor cannot reissue one.
+#'
+#' Two supervisors on one machine see the same file: this is the cross-process
+#' authority robust.md stage C asks for, at the journal. The FILE save has its
+#' own guard (`expected` bytes, fileio.R); the two are deliberately separate.
+journal_lease <- function(dir, key, takeover = FALSE) {
+  path <- file.path(dir, "lease.json")
+  prior <- if (file.exists(path)) tryCatch(jsonlite::fromJSON(path, simplifyVector = FALSE), error = function(e) NULL) else NULL
+  me_pid <- Sys.getpid()
+  alive <- is.list(prior) && is.numeric(prior$pid) && prior$pid != me_pid &&
+    isTRUE(tryCatch(tools::pskill(as.integer(prior$pid), 0L), error = function(e) FALSE))
+  if (alive && !isTRUE(takeover)) return(list(held = list(pid = as.integer(prior$pid), port = prior$port, epoch = prior$epoch), epoch = NULL))
+  epoch <- if (is.list(prior) && is.numeric(prior$epoch)) as.integer(prior$epoch) + 1L else 1L
+  me <- list(pid = me_pid, port = as.integer(Sys.getenv("CARMAR_PORT", "0")), epoch = epoch, at = as.numeric(Sys.time()) * 1000)
+  ok <- tryCatch({ journal_replace(path, as.character(jsonlite::toJSON(me, auto_unbox = TRUE, digits = NA))); TRUE }, error = function(e) FALSE)
+  if (!ok) return(list(held = NULL, epoch = NULL, error = "The writer lease could not be written."))
+  list(held = NULL, epoch = epoch, takenOver = alive)
+}
+
+#' Is `epoch` the current lease for this key? Read from disk on every write:
+#' the lease file is the authority, not this process's memory of it.
+journal_lease_current <- function(dir, epoch) {
+  if (!is.numeric(epoch) || length(epoch) != 1L || is.na(epoch)) return(FALSE)
+  prior <- journal_lease_read(dir)
+  is.list(prior) && is.numeric(prior$epoch) && as.integer(prior$epoch) == as.integer(epoch)
+}
+
+#' The lease on disk, or NULL when the key has none (never opened, or its
+#' folder was archived — the lease went with it).
+journal_lease_read <- function(dir) {
+  path <- file.path(dir, "lease.json")
+  if (!file.exists(path)) return(NULL)
+  tryCatch(jsonlite::fromJSON(path, simplifyVector = FALSE), error = function(e) NULL)
+}
+
+#' Why a write is refused, or NULL when the lease is current. Two answers,
+#' because they ask for different things: `unleased` (no epoch at all — this
+#' window never opened the key, or opened it before the kernel was up) is
+#' cured by `journal_open`; `fenced` (an epoch that is no longer current) is
+#' another window's takeover and nothing here cures it.
+journal_lease_refusal <- function(type, id, dir, epoch) {
+  if (!is.numeric(epoch) || length(epoch) != 1L || is.na(epoch) || is.null(journal_lease_read(dir)))
+    return(journal_error(type, id, "unleased", "This window holds no writer lease for this document; open it first."))
+  if (!journal_lease_current(dir, epoch))
+    return(journal_error(type, id, "fenced", "Another window took over this document's history. This window no longer writes it."))
+  NULL
+}
+
+#' Save As: the history follows the document to its new key. The old key's
+#' directory is renamed; the old key is kept in `meta.aliases` so a checkpoint
+#' the engine stamped with it still verifies. A history already under the new
+#' key (an earlier document at that path) is set aside as abandoned first —
+#' the file the user just wrote there supersedes it.
+journal_rename <- function(id, from = NULL, to = NULL) {
+  if (!journal_valid_key(from) || !journal_valid_key(to)) return(journal_error("journal_rename", id, "invalid_key", "A rename needs two durable document keys."))
+  if (identical(from, to)) return(list(type = "journal_rename", id = id, from = from, to = to, renamed = FALSE))
+  src <- journal_dir(from); dst <- journal_dir(to)
+  if (!dir.exists(src)) return(journal_error("journal_rename", id, "missing", "There is no history under the old key."))
+  for (key in c(from, to)) if (exists(key, envir = journal_cache, inherits = FALSE)) rm(list = key, envir = journal_cache)
+  if (dir.exists(dst)) {
+    aside <- paste0(dst, ".abandoned-", format(Sys.time(), "%Y%m%d-%H%M%S"))
+    if (!isTRUE(suppressWarnings(file.rename(dst, aside)))) return(journal_error("journal_rename", id, "io", "The history already at the new key could not be set aside."))
+  }
+  if (!isTRUE(suppressWarnings(file.rename(src, dst)))) return(journal_error("journal_rename", id, "io", "The history could not be moved to its new key."))
+  meta <- journal_read_meta(dst)
+  meta$aliases <- unique(c(meta$aliases %||% list(), list(from)))
+  tryCatch(journal_write_meta(dst, meta), error = function(e) NULL)
+  list(type = "journal_rename", id = id, from = from, to = to, renamed = TRUE, aliases = meta$aliases)
+}
+
+#' Set aside a document's whole history (the user declined to recover it):
+#' the directory is renamed, listed as abandoned, deletable from Settings.
+journal_archive <- function(id, key = NULL) {
+  if (!journal_valid_key(key)) return(journal_error("journal_archive", id, "invalid_key", "A journal needs a durable document key."))
+  dir <- journal_dir(key)
+  if (exists(key, envir = journal_cache, inherits = FALSE)) rm(list = key, envir = journal_cache)
+  if (!dir.exists(dir)) return(list(type = "journal_archive", id = id, key = key, archived = FALSE))
+  to <- paste0(dir, ".abandoned-", format(Sys.time(), "%Y%m%d-%H%M%S"))
+  ok <- isTRUE(suppressWarnings(file.rename(dir, to)))
+  if (!ok) return(journal_error("journal_archive", id, "io", "The history could not be set aside."))
+  list(type = "journal_archive", id = id, key = key, archived = TRUE)
+}
+
+journal_append <- function(id, key = NULL, records = NULL, epoch = NULL) {
+  if (!JOURNAL_ENABLED) return(journal_error("journal_append", id, "unavailable", "The document journal is disabled."))
+  if (!journal_valid_key(key)) return(journal_error("journal_append", id, "invalid_key", "A journal needs a durable document key."))
+  refused <- journal_lease_refusal("journal_append", id, journal_dir(key), epoch)
+  if (!is.null(refused)) return(refused)
+  records <- as.list(records)
+  if (!length(records) || !all(vapply(records, function(r) is.character(r) && length(r) == 1L && nzchar(r), logical(1))))
+    return(journal_error("journal_append", id, "invalid_record", "Append needs one or more serialised records."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_append", id, "io", conditionMessage(st)))
+  # Validate the WHOLE batch before writing a byte of it.
+  last <- st$last
+  lines <- character(length(records))
+  for (i in seq_along(records)) {
+    json <- records[[i]]
+    parsed <- tryCatch(jsonlite::fromJSON(json, simplifyVector = FALSE), error = function(e) NULL)
+    if (is.null(parsed) || !identical(parsed$key, key) || !is.numeric(parsed$revision)
+        || !is.numeric(parsed$baseRevision) || parsed$revision != parsed$baseRevision + 1
+        || !is.character(parsed$sha) || !grepl("^[a-f0-9]{64}$", parsed$sha))
+      return(journal_error("journal_append", id, "invalid_record", "A record is malformed or belongs to another document."))
+    if (!is.na(last) && parsed$baseRevision != last) {
+      # An exact retry of the record already at the tail is acknowledged, not
+      # refused: the ack for it may have been lost, and the page must be able
+      # to ask again with the same bytes.
+      if (!is.na(last) && parsed$revision == last && i == 1L && length(records) == 1L
+          && identical(journal_tail_json(st), json)) {
+        return(list(type = "journal_append", id = id, key = key, durableRevision = last, retried = TRUE))
+      }
+      return(journal_error("journal_append", id, "discontiguous",
+                           sprintf("The journal ends at revision %d, not %d.", last, as.integer(parsed$baseRevision)),
+                           lastRevision = last))
+    }
+    if (is.na(last) && parsed$baseRevision != 0 && is.na(st$checkpoint))
+      return(journal_error("journal_append", id, "discontiguous", "An empty journal starts at revision 0.", lastRevision = 0L))
+    lines[[i]] <- paste0(nchar(json, type = "bytes"), "\t", json, "\n")
+    last <- as.integer(parsed$revision)
+  }
+  added <- sum(nchar(lines, type = "bytes"))
+  if (st$bytes + added > journal_budget() * 2) {
+    return(journal_error("journal_append", id, "quota",
+                         sprintf("This document's history has reached its %d MB budget; checkpoint to compact it.", as.integer(journal_budget() / 1048576))))
+  }
+  ok <- tryCatch({
+    con <- file(st$path, open = "ab")
+    on.exit(close(con), add = TRUE)
+    writeBin(charToRaw(enc2utf8(paste0(lines, collapse = ""))), con)
+    close(con); on.exit()
+    Sys.chmod(st$path, "0600")
+    TRUE
+  }, error = function(e) conditionMessage(e))
+  if (!isTRUE(ok)) return(journal_error("journal_append", id, "io", ok))
+  st$last <- last
+  st$bytes <- st$bytes + added
+  list(type = "journal_append", id = id, key = key, durableRevision = last)
+}
+
+#' The JSON of the last record, for the exact-retry rule.
+journal_tail_json <- function(st) {
+  scan <- journal_scan(st$path)
+  if (!length(scan$records)) return(NULL)
+  scan$records[[length(scan$records)]]
+}
+
+journal_checkpoint <- function(id, key = NULL, revision = NULL, generation = NULL, envelope = NULL, meta = NULL, rebase = FALSE, epoch = NULL) {
+  if (!JOURNAL_ENABLED) return(journal_error("journal_checkpoint", id, "unavailable", "The document journal is disabled."))
+  if (!journal_valid_key(key)) return(journal_error("journal_checkpoint", id, "invalid_key", "A journal needs a durable document key."))
+  refused <- journal_lease_refusal("journal_checkpoint", id, journal_dir(key), epoch)
+  if (!is.null(refused)) return(refused)
+  if (!is.numeric(revision) || length(revision) != 1L || is.na(revision) || revision < 0
+      || !is.character(envelope) || length(envelope) != 1L || !nzchar(envelope))
+    return(journal_error("journal_checkpoint", id, "invalid_checkpoint", "A checkpoint needs a revision and its envelope."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_checkpoint", id, "io", conditionMessage(st)))
+  revision <- as.integer(revision)
+  tail_end <- if (!is.na(st$last)) st$last else if (!is.na(st$checkpoint)) st$checkpoint else 0L
+  if (revision < tail_end && !isTRUE(rebase))
+    return(journal_error("journal_checkpoint", id, "stale_checkpoint",
+                         sprintf("The journal is already at revision %d.", tail_end), lastRevision = tail_end))
+  if (revision < tail_end) {
+    # A RE-BASE: the page's history no longer follows this tail (a recovery it
+    # could not replay, an opening it declined). The records above `revision`
+    # are not deleted — they are moved aside as evidence, exactly like a torn
+    # tail — and the journal continues from the checkpoint.
+    cut <- tryCatch(journal_supersede(st, revision), error = function(e) conditionMessage(e))
+    if (is.character(cut)) return(journal_error("journal_checkpoint", id, "io", cut))
+  }
+  stored <- journal_read_meta(st$dir)
+  ok <- tryCatch({
+    journal_replace(file.path(st$dir, "checkpoint.json"), envelope)
+    journal_replace(file.path(st$dir, "checkpoint.rev"), paste0(revision, "\n"))
+    TRUE
+  }, error = function(e) conditionMessage(e))
+  if (!isTRUE(ok)) return(journal_error("journal_checkpoint", id, "io", ok))
+  gap <- NULL
+  if (revision > tail_end) {
+    # Records between the tail and this checkpoint never reached the store
+    # (an outage, an overflow, another opening). Say so, durably.
+    gap <- list(from = tail_end, to = revision, at = as.numeric(Sys.time()) * 1000)
+    stored$gaps <- c(stored$gaps %||% list(), list(gap))
+  }
+  if (is.list(meta) && length(meta)) stored$display <- meta
+  tryCatch(journal_write_meta(st$dir, stored), error = function(e) NULL)
+  st$checkpoint <- revision
+  st$last <- revision
+  pruned <- journal_compact(st, revision)
+  list(type = "journal_checkpoint", id = id, key = key, checkpointRevision = revision,
+       prunedBytes = pruned, gap = gap)
+}
+
+#' Move every record above `revision` into a superseded-evidence file.
+journal_supersede <- function(st, revision) {
+  scan <- journal_scan(st$path)
+  keep <- scan$revisions <= revision
+  if (all(keep)) return(FALSE)
+  gone <- scan$records[!keep]
+  evidence <- paste0(st$path, ".superseded-", format(Sys.time(), "%Y%m%d-%H%M%S"))
+  journal_write_private(evidence, paste0(nchar(gone, type = "bytes"), "\t", gone, "\n", collapse = ""))
+  kept <- scan$records[keep]
+  journal_replace(st$path, if (length(kept)) paste0(nchar(kept, type = "bytes"), "\t", kept, "\n", collapse = "") else "")
+  st$bytes <- file.info(st$path)$size
+  st$last <- if (length(kept)) max(scan$revisions[keep]) else NA_integer_
+  TRUE
+}
+
+#' Drop records at or below the checkpoint once the file is over budget.
+#' Never a byte of the tail; pins carry their own content.
+journal_compact <- function(st, checkpoint) {
+  if (st$bytes <= journal_budget()) return(0)
+  scan <- journal_scan(st$path)
+  keep <- scan$revisions > checkpoint
+  before <- st$bytes
+  kept <- scan$records[keep]
+  text <- if (length(kept)) paste0(nchar(kept, type = "bytes"), "\t", kept, "\n", collapse = "") else ""
+  ok <- tryCatch({ journal_replace(st$path, text); TRUE }, error = function(e) FALSE)
+  if (!ok) return(0)
+  st$bytes <- nchar(text, type = "bytes")
+  before - st$bytes
+}
+
+#' Everything recovery needs: the checkpoint envelope and the tail after it,
+#' page by page when the tail is long.
+journal_load <- function(id, key = NULL, afterRevision = NULL) {
+  if (!JOURNAL_ENABLED) return(journal_error("journal_load", id, "unavailable", "The document journal is disabled."))
+  if (!journal_valid_key(key)) return(journal_error("journal_load", id, "invalid_key", "A journal needs a durable document key."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_load", id, "io", conditionMessage(st)))
+  cp_path <- file.path(st$dir, "checkpoint.json")
+  envelope <- if (is.null(afterRevision) && file.exists(cp_path)) {
+    raw <- readBin(cp_path, "raw", n = file.info(cp_path)$size); s <- rawToChar(raw); Encoding(s) <- "UTF-8"; s
+  } else NULL
+  from <- if (is.numeric(afterRevision)) as.integer(afterRevision) else if (is.na(st$checkpoint)) -1L else st$checkpoint
+  scan <- journal_scan(st$path)
+  wanted <- which(scan$revisions > from)
+  records <- scan$records[wanted]
+  # Page the tail under the frame cap; the page asks again from the last one.
+  budget <- JOURNAL_MAX_REPLY_BYTES - nchar(envelope %||% "", type = "bytes") - 4096
+  sizes <- cumsum(nchar(records, type = "bytes") + 2L)
+  fits <- if (length(records)) sizes <= max(budget, 0) else logical(0)
+  more <- length(records) > sum(fits)
+  records <- records[fits]
+  frame <- list(type = "journal_load", id = id, key = key, aliases = journal_read_meta(st$dir)$aliases %||% list(),
+                checkpointRevision = if (is.na(st$checkpoint)) NULL else st$checkpoint,
+                durableRevision = if (is.na(st$last)) NULL else st$last,
+                more = more, repaired = isTRUE(st$repaired),
+                gaps = journal_read_meta(st$dir)$gaps %||% list(), pins = journal_pins(st$dir))
+  structure(frame, raw = list(records = records, checkpoint = envelope))
+}
+
+#' Records in a revision range, verbatim, for the time machine's walk-back.
+journal_read <- function(id, key = NULL, fromRevision = NULL, toRevision = NULL) {
+  if (!journal_valid_key(key)) return(journal_error("journal_read", id, "invalid_key", "A journal needs a durable document key."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_read", id, "io", conditionMessage(st)))
+  scan <- journal_scan(st$path)
+  lo <- if (is.numeric(fromRevision)) as.integer(fromRevision) else 0L
+  hi <- if (is.numeric(toRevision)) as.integer(toRevision) else .Machine$integer.max
+  wanted <- which(scan$revisions >= lo & scan$revisions <= hi)
+  records <- scan$records[wanted]
+  sizes <- cumsum(nchar(records, type = "bytes") + 2L)
+  fits <- if (length(records)) sizes <= JOURNAL_MAX_REPLY_BYTES else logical(0)
+  frame <- list(type = "journal_read", id = id, key = key, more = length(records) > sum(fits))
+  structure(frame, raw = list(records = records[fits]))
+}
+
+#' The time-machine list: one row per record, newest first, bounded.
+journal_versions <- function(id, key = NULL, beforeRevision = NULL, limit = 200L) {
+  if (!journal_valid_key(key)) return(journal_error("journal_versions", id, "invalid_key", "A journal needs a durable document key."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_versions", id, "io", conditionMessage(st)))
+  scan <- journal_scan(st$path)
+  limit <- max(1L, min(as.integer(limit %||% 200L), 1000L))
+  before <- if (is.numeric(beforeRevision)) as.integer(beforeRevision) else .Machine$integer.max
+  idx <- rev(which(scan$revisions < before))
+  idx <- idx[seq_len(min(length(idx), limit))]
+  rows <- lapply(idx, function(i) {
+    r <- jsonlite::fromJSON(scan$records[[i]], simplifyVector = FALSE)
+    list(revision = r$revision, kind = r$kind, id = r$id, at = r$at,
+         label = if (identical(r$kind, "edit")) r$entry$label else r$label,
+         origin = if (identical(r$kind, "edit")) r$entry$origin else "user",
+         generation = r$generation,
+         abandoned = if (identical(r$kind, "edit")) length(r$abandoned) else 0L)
+  })
+  list(type = "journal_versions", id = id, key = key, rows = rows,
+       more = length(idx) == limit && length(idx) < length(scan$revisions),
+       pins = journal_pins(st$dir), gaps = journal_read_meta(st$dir)$gaps %||% list())
+}
+
+journal_pins <- function(dir) {
+  path <- file.path(dir, "pins")
+  if (!dir.exists(path)) return(list())
+  files <- list.files(path, pattern = "^[0-9]+\\.json$", full.names = TRUE)
+  pins <- lapply(files, function(f) {
+    p <- tryCatch(jsonlite::fromJSON(f, simplifyVector = FALSE), error = function(e) NULL)
+    if (is.list(p)) list(revision = p$revision, name = p$name, at = p$at) else NULL
+  })
+  Filter(Negate(is.null), pins)
+}
+
+#' A named version: the page sends the content it reconstructed for that
+#' revision, so a pin outlives compaction of the records that led to it.
+journal_pin <- function(id, key = NULL, revision = NULL, name = NULL, state = NULL) {
+  if (!journal_valid_key(key)) return(journal_error("journal_pin", id, "invalid_key", "A journal needs a durable document key."))
+  if (!is.numeric(revision) || length(revision) != 1L || is.na(revision) || revision < 0
+      || !is.character(name) || length(name) != 1L || !nzchar(trimws(name))
+      || !is.character(state) || length(state) != 1L || !nzchar(state))
+    return(journal_error("journal_pin", id, "invalid_pin", "A pin needs a revision, a name and the content at that revision."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_pin", id, "io", conditionMessage(st)))
+  dir <- file.path(st$dir, "pins")
+  ok <- tryCatch({
+    journal_ensure_dir(dir)
+    body <- list(schema = 1L, revision = as.integer(revision), name = substr(trimws(name), 1L, 120L),
+                 at = as.numeric(Sys.time()) * 1000)
+    head <- as.character(jsonlite::toJSON(body, auto_unbox = TRUE, digits = NA))
+    # `state` is the page's JSON, spliced verbatim for the same fidelity reason as records.
+    journal_replace(file.path(dir, paste0(as.integer(revision), ".json")),
+                    paste0(substr(head, 1L, nchar(head) - 1L), ",\"state\":", state, "}"))
+    TRUE
+  }, error = function(e) conditionMessage(e))
+  if (!isTRUE(ok)) return(journal_error("journal_pin", id, "io", ok))
+  list(type = "journal_pin", id = id, key = key, revision = as.integer(revision), pins = journal_pins(st$dir))
+}
+
+journal_unpin <- function(id, key = NULL, revision = NULL) {
+  if (!journal_valid_key(key) || !is.numeric(revision) || length(revision) != 1L)
+    return(journal_error("journal_unpin", id, "invalid_pin", "Unpin needs a document key and a revision."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_unpin", id, "io", conditionMessage(st)))
+  unlink(file.path(st$dir, "pins", paste0(as.integer(revision), ".json")))
+  list(type = "journal_unpin", id = id, key = key, pins = journal_pins(st$dir))
+}
+
+#' The content of one pin, verbatim.
+journal_pin_read <- function(id, key = NULL, revision = NULL) {
+  if (!journal_valid_key(key) || !is.numeric(revision) || length(revision) != 1L)
+    return(journal_error("journal_pin_read", id, "invalid_pin", "Reading a pin needs a document key and a revision."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_pin_read", id, "io", conditionMessage(st)))
+  path <- file.path(st$dir, "pins", paste0(as.integer(revision), ".json"))
+  if (!file.exists(path)) return(journal_error("journal_pin_read", id, "missing_pin", "No such named version."))
+  raw <- readBin(path, "raw", n = file.info(path)$size); text <- rawToChar(raw); Encoding(text) <- "UTF-8"
+  structure(list(type = "journal_pin_read", id = id, key = key, revision = as.integer(revision)), raw = list(pin = text))
+}
+
+#' Every document the store knows, for the recovery list and Settings.
+journal_list <- function(id) {
+  if (!JOURNAL_ENABLED) return(list(type = "journal_list", id = id, documents = list(), enabled = FALSE))
+  root <- journal_root()
+  dirs <- if (dir.exists(root)) list.dirs(root, recursive = FALSE, full.names = TRUE) else character()
+  docs <- lapply(dirs, function(dir) {
+    name <- basename(dir)
+    abandoned <- grepl("\\.abandoned-[0-9-]+$", name)
+    key <- sub("__", ":", sub("\\.abandoned-[0-9-]+$", "", name), fixed = FALSE)
+    key <- sub("__", ":", key, fixed = TRUE)
+    if (!journal_valid_key(key)) return(NULL)
+    meta <- journal_read_meta(dir)
+    path <- file.path(dir, "journal.ndjson")
+    list(key = key, dir = name, abandoned = abandoned, meta = meta$display %||% NULL, updated = meta$updated %||% NULL,
+         checkpointRevision = { v <- journal_checkpoint_revision(dir); if (is.na(v)) NULL else v },
+         bytes = (if (file.exists(path)) file.info(path)$size else 0)
+           + (if (file.exists(file.path(dir, "checkpoint.json"))) file.info(file.path(dir, "checkpoint.json"))$size else 0),
+         pins = length(journal_pins(dir)))
+  })
+  list(type = "journal_list", id = id, enabled = TRUE, root = root, documents = Filter(Negate(is.null), docs))
+}
+
+#' Deliberate deletion of one document's history. The page confirms first.
+journal_delete <- function(id, key = NULL) {
+  if (!journal_valid_key(key)) return(journal_error("journal_delete", id, "invalid_key", "A journal needs a durable document key."))
+  dir <- journal_dir(key)
+  if (exists(key, envir = journal_cache, inherits = FALSE)) rm(list = key, envir = journal_cache)
+  if (dir.exists(dir)) unlink(dir, recursive = TRUE)
+  list(type = "journal_delete", id = id, key = key, deleted = !dir.exists(dir))
+}
+
+#' The whole history of one document as one JSON text, for the user to keep.
+journal_export <- function(id, key = NULL) {
+  if (!journal_valid_key(key)) return(journal_error("journal_export", id, "invalid_key", "A journal needs a durable document key."))
+  st <- tryCatch(journal_state(key), error = function(e) e)
+  if (inherits(st, "error")) return(journal_error("journal_export", id, "io", conditionMessage(st)))
+  scan <- journal_scan(st$path)
+  cp_path <- file.path(st$dir, "checkpoint.json")
+  envelope <- if (file.exists(cp_path)) { raw <- readBin(cp_path, "raw", n = file.info(cp_path)$size); s <- rawToChar(raw); Encoding(s) <- "UTF-8"; s } else NULL
+  head <- list(format = "carmar-history-export", schema = 1L, key = key, exported = as.numeric(Sys.time()) * 1000,
+               checkpointRevision = if (is.na(st$checkpoint)) NULL else st$checkpoint, meta = journal_read_meta(st$dir))
+  text <- as.character(jsonlite::toJSON(head, auto_unbox = TRUE, null = "null", digits = NA))
+  text <- paste0(substr(text, 1L, nchar(text) - 1L),
+                 ",\"checkpoint\":", if (is.null(envelope)) "null" else jsonlite::toJSON(jsonlite::unbox(envelope)),
+                 ",\"records\":[", paste0(scan$records, collapse = ","), "]}")
+  if (nchar(text, type = "bytes") > JOURNAL_MAX_REPLY_BYTES)
+    return(journal_error("journal_export", id, "too_large", "This history is too large to export over the kernel connection."))
+  structure(list(type = "journal_export", id = id, key = key), raw = list(bundle = text))
+}
+
+# ── the frame writer ───────────────────────────────────────────────────────
+
+#' Serialise a journal frame, splicing verbatim JSON fields in by hand.
+#' `attr(frame, "raw")` holds them: `records` (a character vector of JSON
+#' objects) and any scalar JSON text (`checkpoint`, `pin`, `bundle`), which
+#' are emitted as JSON STRINGS (quoted) because the page decodes them itself.
+journal_frame <- function(frame) {
+  raw <- attr(frame, "raw")
+  attr(frame, "raw") <- NULL
+  head <- as.character(jsonlite::toJSON(frame, auto_unbox = TRUE, null = "null", na = "null", digits = NA))
+  if (is.null(raw)) return(head)
+  extra <- character()
+  if (!is.null(raw$records)) extra <- c(extra, paste0("\"records\":[", paste0(raw$records, collapse = ","), "]"))
+  for (name in setdiff(names(raw), "records")) {
+    value <- raw[[name]]
+    extra <- c(extra, paste0("\"", name, "\":", if (is.null(value)) "null" else as.character(jsonlite::toJSON(jsonlite::unbox(value)))))
+  }
+  if (!length(extra)) return(head)
+  paste0(substr(head, 1L, nchar(head) - 1L), if (identical(head, "{}")) "" else ",", paste0(extra, collapse = ","), "}")
+}
+
+`%||%` <- function(a, b) if (is.null(a)) b else a