beatrina 0.8.6 → 0.9.43

package/host/user-dirs.mjs

@@ -7,7 +7,7 @@
 //   data     the console history, the appearance carry, the document journal,
 //            the AI conversation store
 //
-// serve.R reaches them through `tools::R_user_dir("carmar", which)`, and every
+// serve.R reaches them through `tools::R_user_dir("beatrina", which)`, and every
 // suite in the battery relocates them for a test by setting `R_USER_CONFIG_DIR`
 // / `R_USER_DATA_DIR` — the variables R itself honours. So the host cannot
 // invent its own layout: a JavaScript supervisor writing to `~/.beatrix` would
@@ -20,21 +20,30 @@
 // leaving one arm out is how the next store to need it quietly grows a second
 // layout.
 
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { envReader } from "./env-names.mjs";
 
-const envOf = (name) => (process.env[name] == null ? "" : String(process.env[name]));
+const envOf = envReader(process.env);   // dual-read: BEATRINA_STATE or its older spelling (host/env-names.mjs)
 
 /**
  * Which R package's folders this host keeps its data, settings and caches in.
  *
- * "carmar" unless BEATRIX_APP_ID names another: the `beatrina` command sets
- * it to "beatrina" (tools/npm/bin/beatrina.mjs), so a Beatrina installed
- * beside CarmaR keeps its OWN settings, AI key, console history, document
- * history, plugins and caches instead of reading and writing CarmaR's. The
- * kernel runtime directory (~/.carmar/run) is deliberately NOT keyed on it:
- * it is how the Sessions pane and the MCP bridge find every running kernel.
+ * "beatrina" unless BEATRIX_APP_ID names another (the suites do). Every door
+ * of the product — the `beatrina` command, the pip package, the R package, a
+ * bare `node host/main.mjs` — therefore lands in the same folders.
+ * beatrina-names: keep-start — the OTHER product is named here on purpose. It is
+ * the whole subject of the sentence, and renaming it left this comment saying
+ * that Beatrina does not read Beatrina's own folders.
+ * The other product's folders (`R/carmar`, CarmaR's own, frozen at 0.8.6) are
+ * never read, moved or written: a Beatrina installed beside CarmaR keeps its OWN
+ * settings, AI key, console history, document history, plugins and caches.
+ * beatrina-names: keep-end
+ * The kernel runtime directory (~/.beatrina/run, host/runtime-dir.mjs) is
+ * deliberately NOT keyed on it: it is how the Sessions pane and the MCP bridge
+ * find every running kernel.
  * A value that is not an R package name is refused, loudly — a typo must not
  * quietly become a third data folder.
  *
@@ -43,7 +52,7 @@ const envOf = (name) => (process.env[name] == null ? "" : String(process.env[nam
  */
 export function appId(env = envOf) {
   const id = String(env("BEATRIX_APP_ID") || "").trim();
-  if (!id) return "carmar";
+  if (!id) return "beatrina";
   if (!/^[A-Za-z][A-Za-z0-9.]*[A-Za-z0-9]$/.test(id)) {
     throw new Error(`BEATRIX_APP_ID must be an R package name (letters, digits and dots); it is ${JSON.stringify(id)}.`);
   }
@@ -53,28 +62,31 @@ export function appId(env = envOf) {
 /**
  * `tools::R_user_dir(package, which)`.
  *
- * @param {string} pkg          the package name ("carmar")
+ * @param {string} pkg          the package name ("beatrina")
  * @param {"data"|"config"|"cache"} which
+ * @param {(name: string) => string} [env]  an env reader, for callers that
+ *   inject one (the plugin store's layer paths are computed per request, and
+ *   its suites relocate them with R_USER_DATA_DIR). Defaults to this module's.
  * @returns {string} an absolute directory path (NOT created)
  */
-export function rUserDir(pkg, which = "data") {
+export function rUserDir(pkg, which = "data", env = envOf) {
   const home = os.homedir();
   const windows = process.platform === "win32";
   const darwin = process.platform === "darwin";
   let base = "";
   if (which === "data") {
-    base = envOf("R_USER_DATA_DIR") || envOf("XDG_DATA_HOME")
-      || (windows ? path.join(envOf("APPDATA"), "R", "data")
+    base = env("R_USER_DATA_DIR") || env("XDG_DATA_HOME")
+      || (windows ? path.join(env("APPDATA"), "R", "data")
         : darwin ? path.join(home, "Library", "Application Support", "org.R-project.R")
           : path.join(home, ".local", "share"));
   } else if (which === "config") {
-    base = envOf("R_USER_CONFIG_DIR") || envOf("XDG_CONFIG_HOME")
-      || (windows ? path.join(envOf("APPDATA"), "R", "config")
+    base = env("R_USER_CONFIG_DIR") || env("XDG_CONFIG_HOME")
+      || (windows ? path.join(env("APPDATA"), "R", "config")
         : darwin ? path.join(home, "Library", "Preferences", "org.R-project.R")
           : path.join(home, ".config"));
   } else {
-    base = envOf("R_USER_CACHE_DIR") || envOf("XDG_CACHE_HOME")
-      || (windows ? path.join(envOf("LOCALAPPDATA"), "R", "cache")
+    base = env("R_USER_CACHE_DIR") || env("XDG_CACHE_HOME")
+      || (windows ? path.join(env("LOCALAPPDATA"), "R", "cache")
         : darwin ? path.join(home, "Library", "Caches", "org.R-project.R")
           : path.join(home, ".cache"));
   }
@@ -94,7 +106,7 @@ export function ensureUserDir(pkg, which) {
  * variable is unset.
  */
 export function stateDir() {
-  return envOf("CARMAR_STATE") || rUserDir(appId(), "data");
+  return envOf("BEATRINA_STATE") || rUserDir(appId(), "data");
 }
 
 /**
@@ -115,3 +127,33 @@ export function privateModeHeld(file, platform = process.platform) {
   if (platform === "win32") return true;
   return (fs.statSync(file).mode & 0o777) === 0o600;
 }
+
+/**
+ * Replace `file` with `text`, privately and atomically.
+ *
+ * A sibling is written 0600, checked (`privateModeHeld`), and renamed over the
+ * file — so an interrupted write leaves the PREVIOUS file intact rather than a
+ * half-written one, and no reader ever sees the file mid-write. The AI store's
+ * rule (host/planes/ai-store.mjs), lifted here for the small per-user records
+ * that are rewritten whole: the recent-documents list first. The directory is
+ * created on the way; a failure at any step throws with that step's sentence
+ * and takes the sibling with it. No fsync: safe against the process dying,
+ * not the machine.
+ *
+ * @param {string} file  absolute path of the record
+ * @param {string} text  its whole new content
+ */
+export function writePrivateAtomic(file, text) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const temp = path.join(dir, `.${path.basename(file)}.${process.pid}-${crypto.randomBytes(6).toString("hex")}`);
+  try {
+    fs.writeFileSync(temp, Buffer.from(String(text), "utf8"), { mode: 0o600 });
+    fs.chmodSync(temp, 0o600);
+    if (!privateModeHeld(temp)) throw new Error(`could not make ${path.basename(file)} private (0600)`);
+    fs.renameSync(temp, file);
+  } catch (e) {
+    try { fs.unlinkSync(temp); } catch { /* never written, or already renamed into place */ }
+    throw e;
+  }
+}

package/host/which.mjs

@@ -0,0 +1,39 @@
+// which.mjs — find an executable on PATH, synchronously, with no shell.
+//
+// `Sys.which()` for the host. Lifted out of planes/update.mjs the day a second
+// plane (planes/choose.mjs, the OS file panel) needed the same answer, so the
+// two cannot drift on what "on PATH" means. Nothing here spawns anything: a
+// candidate is a file the current user may execute, found by walking PATH in
+// order, exactly as the shell would resolve the bare name.
+//
+// Windows resolves a bare name through PATHEXT (`powershell` → `powershell.exe`),
+// so a name without an extension is tried with each of those too; a name that
+// already carries one is tried as given first.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} name  a bare command name ("osascript", "powershell.exe")
+ * @param {Record<string,string|undefined>} [env]  the environment whose PATH is walked
+ * @returns {string} the first executable found, or "" when there is none
+ */
+export function whichSync(name, env = process.env) {
+  if (typeof name !== "string" || !name) return "";
+  const dirs = String(env.PATH || env.Path || "").split(path.delimiter).filter(Boolean);
+  const exts = process.platform === "win32" && !path.extname(name)
+    ? ["", ...String(env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)]
+    : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const cand = path.join(dir, name + ext);
+      try {
+        fs.accessSync(cand, fs.constants.X_OK);
+        if (fs.statSync(cand).isFile()) return cand;
+      } catch { /* not here; the next candidate */ }
+    }
+  }
+  return "";
+}
+
+export default whichSync;

package/host/windows-runtime.mjs

@@ -21,7 +21,7 @@
 //     processx ships exactly that program, `interrupt.exe <pid> c`
 //     (processx/src/tools/interrupt.c: FreeConsole → AttachConsole(pid) →
 //     ignore Ctrl+C itself → GenerateConsoleCtrlEvent(CTRL_C_EVENT, 0)), and
-//     processx is already a dependency of the carmar package, so the helper is
+//     processx is already a dependency of the beatrina package, so the helper is
 //     on every machine that installed it. For the event to reach the worker
 //     and not the host, the worker needs a console of its own: it is spawned
 //     with `windowsHide` (CREATE_NO_WINDOW), the flag processx uses too.
@@ -38,6 +38,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { readEnv } from "./env-names.mjs";
 
 const defaultFs = {
   exists: (p) => { try { return fs.existsSync(p); } catch { return false; } },
@@ -104,7 +105,8 @@ export function detectRterm(rscript, io = defaultFs) {
 export const RTERM_INTERACTIVE_ARGS = Object.freeze(["--ess", "--no-echo", "--no-save", "--no-restore", "--no-site-file"]);
 
 /**
- * Where processx's `interrupt.exe` is. `CARMAR_WIN_INTERRUPT` first (the R
+ * Where processx's `interrupt.exe` is. `BEATRINA_WIN_INTERRUPT` (or the old
+ * `BEATRINA_WIN_INTERRUPT`) first (the R
  * launcher sets it from `system.file(package = "processx")`, which knows every
  * library path), then a helper shipped beside the host, then the libraries a
  * default install writes to: the R installation's own, R_LIBS_USER, and
@@ -115,7 +117,8 @@ export function findInterruptTool({ env = process.env, rscript = "", hostRoot =
   const w = path.win32;
   const tail = ["processx", "bin", "x64", "interrupt.exe"];
   const cands = [];
-  if (env.CARMAR_WIN_INTERRUPT) cands.push(env.CARMAR_WIN_INTERRUPT);
+  const told = readEnv(env, "WIN_INTERRUPT");
+  if (told) cands.push(told);
   if (hostRoot) cands.push(w.join(hostRoot, "bin", "interrupt.exe"));
   if (rscript) cands.push(w.join(w.dirname(w.dirname(rscript)), "library", ...tail));
   if (env.R_HOME) cands.push(w.join(env.R_HOME, "library", ...tail));

package/host/worker-plane.mjs

@@ -35,6 +35,7 @@
 //     an explicit `restart` is the one door out of it.
 
 import { EventEmitter } from "node:events";
+import { RESUME_REPORT_MS, keepTokenOk } from "./session-keep.mjs";
 
 export const WORKER_DEADLINE_FAST = 120;
 export const WORKER_DEADLINE_SLOW = 600;
@@ -45,7 +46,8 @@ export const WORKER_DEADLINES = Object.freeze({
   package_help: WORKER_DEADLINE_FAST, project_status: WORKER_DEADLINE_FAST, rm: WORKER_DEADLINE_FAST,
   debug_breaks: WORKER_DEADLINE_FAST, files: WORKER_DEADLINE_FAST, mkdir: WORKER_DEADLINE_FAST,
   renamepath: WORKER_DEADLINE_FAST, sniff: WORKER_DEADLINE_FAST,
-  view: WORKER_DEADLINE_SLOW, colstats: WORKER_DEADLINE_SLOW, import: WORKER_DEADLINE_SLOW,
+  view: WORKER_DEADLINE_SLOW, colstats: WORKER_DEADLINE_SLOW, column_values: WORKER_DEADLINE_SLOW,
+  import: WORKER_DEADLINE_SLOW,
   format: WORKER_DEADLINE_SLOW, doctor: WORKER_DEADLINE_SLOW, readfile: WORKER_DEADLINE_SLOW,
   writefile: WORKER_DEADLINE_SLOW, writefiles_atomic: WORKER_DEADLINE_SLOW,
   copypath: WORKER_DEADLINE_SLOW, deletepath: WORKER_DEADLINE_SLOW, revealpath: WORKER_DEADLINE_SLOW,
@@ -119,6 +121,10 @@ export class WorkerPlane extends EventEmitter {
     this.terminal = null;          // {wireId, route, frame, timer}
     this.running = new Set();      // exec wire ids in flight (the busy guard's evidence)
     this.hello = null;             // the decorated ready payload, replayed to late pages
+    // "Restart, keep variables" (host/session-keep.mjs): a token for the NEXT ready worker, consumed
+    // once; and the restore's report, replayed to a page that connects within RESUME_REPORT_MS.
+    this.resumePending = null;
+    this.resumeReport = null;
     this.notice = null;            // a kept give-up notice
     this.readyFrame = null;
     this.workerWd = process.cwd();
@@ -314,8 +320,8 @@ export class WorkerPlane extends EventEmitter {
     if (this.alive) this.engine.kill();
   }
 
-  async restart() {
-    this.audit("restart", {});
+  async restart({ resume } = {}) {
+    this.audit("restart", { keep: keepTokenOk(resume) });
     this.failRoutes(`${this.label} was restarted — this request was abandoned.`);
     this.expectedExit = true;
     if (this.engine) await this.engine.stop(1000);
@@ -325,7 +331,65 @@ export class WorkerPlane extends EventEmitter {
     this.restartAttempts = 0;
     this.gaveUp = false;
     this.notice = null;
-    await this.start();
+    this.resumePending = keepTokenOk(resume) ? resume : null;
+    try { await this.start(); } catch (e) { this.refuseStart(e); throw e; }
+  }
+
+  /**
+   * A start that could not happen, said to every page instead of left as a spinner. Restart R used
+   * to reject into server.mjs's audit line and nothing else, so the page waited for a ready that
+   * would never come. A payload that drifted under this session (host/payload.mjs) lands here too,
+   * and its sentence already names the door out ("Restart into").
+   */
+  refuseStart(e) {
+    const drift = e && e.code === "BEATRINA_PAYLOAD_DRIFT";
+    this.recovering = false;
+    this.gaveUp = true;
+    const message = drift ? e.message
+      : `${this.label} would not start: ${e && e.message ? e.message : e}. Beatrina is still running — the notebook, `
+        + "your text and Save all work. Restart to try again.";
+    this.audit(drift ? "worker-start-refused" : "worker-start-failed", { detail: e && e.message ? e.message : String(e) });
+    this.notice = enc({ type: "worker-died", engine: this.name, recovering: false, terminal: true,
+      attempts: this.restartAttempts, message, reason: drift ? "payload-drift" : "start-failed" });
+    this.emit("broadcast", this.notice);
+  }
+
+  /** A token for the next ready worker (a handoff successor's BEATRINA_RESUME_TOKEN). */
+  setResumePending(token) { this.resumePending = keepTokenOk(token) ? token : null; }
+
+  /**
+   * Ask the fresh worker to restore a kept workspace, and tell every page what came back. Queued like
+   * any command, so a chunk run pressed meanwhile waits for the restore rather than racing it.
+   */
+  startResume() {
+    const token = this.resumePending;
+    this.resumePending = null;
+    if (!keepTokenOk(token)) return;
+    this.audit("resume-start", {});
+    this.internal({ type: "resume", token }, (frame) => {
+      if (scalarChr(frame.cwd)) this.workerWd = frame.cwd;
+      const report = { type: "workspace_restored", restored: frame.restored ?? 0, failed: frame.failed ?? [],
+        skipped: frame.skipped ?? [], wd_missing: frame.wd_missing ?? null, error: frame.error ?? null };
+      const payload = enc(report);
+      this.resumeReport = { at: Date.now(), payload };
+      this.audit("resume-done", { restored: report.restored, failed: Array.isArray(report.failed) ? report.failed.length : 0, error: report.error != null });
+      this.emit("broadcast-pages", payload);
+    });
+  }
+
+  /** The report of a restore that finished in the last RESUME_REPORT_MS, or null. */
+  freshResumeReport(now = Date.now()) {
+    return this.resumeReport && now - this.resumeReport.at < RESUME_REPORT_MS ? this.resumeReport.payload : null;
+  }
+
+  /** Cancel a `suspend` — only one THIS page asked for, never someone else's run. */
+  cancelSuspend(rec) {
+    const route = this.active != null ? this.routes.get(this.active) : null;
+    if (this.activeType !== "suspend" || !route || route.rec !== rec) return false;
+    this.audit("suspend-cancel", {});
+    const wireId = this.active;
+    this.engine.interrupt(() => wireId === this.active);
+    return true;
   }
 
   resetSession() {
@@ -456,12 +520,12 @@ export class WorkerPlane extends EventEmitter {
       try { this.engine.debugCommand(action, expr); } catch { /* the exit event reports it */ }
       return undefined;
     }
-    const line = { continue: "c", over: "n", into: "s", out: "f", where: ".carmar_debug_where()",
-      abort: 'invokeRestart("carmar_abort_cell")', eval: scalarChr(cmd.expr) ? cmd.expr : null }[action] ?? null;
+    const line = { continue: "c", over: "n", into: "s", out: "f", where: ".beatrina_debug_where()",
+      abort: 'invokeRestart("beatrina_abort_cell")', eval: scalarChr(cmd.expr) ? cmd.expr : null }[action] ?? null;
     if (line == null || /[\n\r]/.test(line) || line.length > 4000) return err("bad debug command");
     this.audit("debug_cmd", { action });
     try { this.engine.console(line); } catch { /* the exit event reports it */ }
-    if (["over", "into", "out"].includes(action)) { try { this.engine.console(".carmar_debug_where()"); } catch { /* same */ } }
+    if (["over", "into", "out"].includes(action)) { try { this.engine.console(".beatrina_debug_where()"); } catch { /* same */ } }
     return undefined;
   }
 
@@ -535,6 +599,7 @@ export class WorkerPlane extends EventEmitter {
       this.hello = payload;
       this.emit("broadcast", payload);
       this.emit("ready", decorated);
+      if (this.resumePending) this.startResume();
       return;
     }
     this.emit("broadcast", relayFrame(e));
@@ -606,6 +671,14 @@ export class WorkerPlane extends EventEmitter {
     let started = null;
     try { started = this.start(); } catch (e) { this.audit("worker-respawn-failed", { attempt, detail: e.message }); }
     if (!started) return;
+    // start() is async: a factory or spawnPlan throwing rejects its promise.
+    // Keep recovery's bounded retry loop alive instead of terminating Node
+    // with an unhandled rejection when an installation moves mid-session.
+    started.catch((e) => {
+      this.audit("worker-respawn-failed", { attempt, detail: e.message });
+      // Retrying cannot un-replace the files: say so now rather than after six attempts.
+      if (e && e.code === "BEATRINA_PAYLOAD_DRIFT") this.refuseStart(e);
+    });
     this.audit("worker-respawn", { attempt });
     this.emit("broadcast", enc({ type: "worker-restarting", engine: this.name, attempt }));
   }

package/host/ws.mjs

@@ -1,7 +1,7 @@
 // ws.mjs — a WebSocket SERVER, RFC 6455, over Node's http upgrade event.
 //
 // Node ships a WebSocket client (>= 22) and no server, and the host has no
-// dependencies by decision (tools/mcp/carmar-mcp.mjs and test/fixtures/
+// dependencies by decision (tools/mcp/beatrina-mcp.mjs and test/fixtures/
 // ws-origin.mjs set the precedent: a few hundred lines of protocol beat a
 // package the security review must then read). What this implements is the
 // subset a notebook page uses: text frames, masked client → unmasked server,
@@ -29,6 +29,8 @@ const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
  * @property {(code?: number, reason?: string) => void} close
  * @property {(fn: (text: string) => void) => void} onMessage
  * @property {(fn: () => void) => void} onClose
+ * @property {() => boolean} ping        a protocol ping (opcode 9); the peer's network stack answers it
+ * @property {(fn: () => void) => void} onPong   called for each pong the peer sends back
  * @property {import("node:http").IncomingMessage} request  the upgrade request, kept —
  *   the gate's reasoning is recomputed from it (socket_class in serve.R)
  * @property {boolean} open
@@ -74,6 +76,7 @@ function wrap(raw, request, head) {
   let open = true;
   let closeSent = false;
   const messageHandlers = [];
+  const pongHandlers = [];
   const closeHandlers = [];
 
   const finish = () => {
@@ -138,7 +141,9 @@ function wrap(raw, request, head) {
         return;
       }
       if (opcode === 0x9) { sendFrame(0xa, payload); continue; }   // ping → pong
-      if (opcode === 0xa) continue;                                 // pong: a reply to nothing we sent
+      // A pong answers the reaper's ping (server.mjs): the peer's network stack sent it, so the
+      // transport is alive even when the page's own thread is busy or throttled and sends nothing.
+      if (opcode === 0xa) { for (const fn of pongHandlers) fn(); continue; }
       if (opcode === 0x1 || opcode === 0x2) {
         if (partial) return closeWith(1002, "interleaved message");
         partial = { opcode, chunks: [payload], bytes: payload.length };
@@ -169,6 +174,8 @@ function wrap(raw, request, head) {
     close: (code = 1000, reason = "") => closeWith(code, reason),
     onMessage: (fn) => { messageHandlers.push(fn); },
     onClose: (fn) => { closeHandlers.push(fn); },
+    ping: () => sendFrame(0x9, Buffer.alloc(0)),
+    onPong: (fn) => { pongHandlers.push(fn); },
   };
 }
 

package/host/zip.mjs

@@ -0,0 +1,237 @@
+// zip.mjs — write and read standard ZIP archives, with Node's zlib and nothing else.
+//
+// The container under `.btrn` (docs/results-plan.md R2). A .btrn must open in
+// every unzip there is — macOS Archive Utility, `unzip`, R's utils::unzip() —
+// so this writes the plain, universal subset of the format and nothing clever:
+// one local header + data per entry, a central directory, the end record.
+// Method 0 (stored) or 8 (deflated); UTF-8 names (flag bit 11); no ZIP64 (a
+// .btrn holds ≤ 100 MB of data by design — past that the data lives beside
+// it), no encryption, no data descriptors. zlib.crc32 is Node ≥ 22.2.
+//
+// READING IS READING SOMETHING FROM ELSEWHERE, so the reader refuses before it
+// trusts:
+//   · a name that is absolute, has a `..` segment, a drive letter, a
+//     backslash, a NUL, or is empty — the zip-slip family, refused by name;
+//   · the same name twice;
+//   · an encrypted entry, or a method other than 0/8;
+//   · more than `maxTotal` bytes uncompressed in all — the zip-bomb family,
+//     refused with its numbers BEFORE inflating (a per-entry ratio is
+//     optional: deflate tops out near 1032×, so it guards nothing by default);
+//   · an entry that inflates to more than it declared (zlib's
+//     maxOutputLength enforces the declared size), or whose CRC-32 differs.
+// Every refusal is a thrown Error with `code` set, so callers can say which.
+
+import zlib from "node:zlib";
+
+const SIG_LOCAL = 0x04034b50;
+const SIG_CENTRAL = 0x02014b50;
+const SIG_END = 0x06054b50;
+const FLAG_UTF8 = 0x0800;
+const U32 = 0xffffffff;
+
+/** Date → the two 16-bit MS-DOS fields (2-second resolution, 1980..2107). */
+function dosTime(date) {
+  const d = date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date(1980, 0, 1);
+  const year = Math.min(2107, Math.max(1980, d.getFullYear()));
+  return {
+    time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+    date: ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+  };
+}
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+/** The Info-ZIP Unicode Path extra field: version 1, CRC-32 of the header name, the UTF-8 name. */
+function unicodePathExtra(nameBytes) {
+  const field = Buffer.alloc(4 + 5 + nameBytes.length);
+  field.writeUInt16LE(0x7075, 0);
+  field.writeUInt16LE(5 + nameBytes.length, 2);
+  field.writeUInt8(1, 4);
+  field.writeUInt32LE(zlib.crc32(nameBytes) >>> 0, 5);
+  nameBytes.copy(field, 9);
+  return field;
+}
+
+/**
+ * Is this an entry name a reader may use? Relative, forward slashes, no
+ * `..`/`.` segment, no drive, no NUL, not empty. A directory entry ends in `/`.
+ */
+export function safeEntryName(name) {
+  const n = String(name ?? "");
+  if (!n || n.length > 1024 || /[\u0000\\]/.test(n)) return false;
+  if (n.startsWith("/") || /^[A-Za-z]:/.test(n)) return false;
+  const parts = n.replace(/\/$/, "").split("/");
+  return parts.every((p) => p !== "" && p !== "." && p !== "..");
+}
+
+/**
+ * Build a ZIP in memory.
+ *
+ * @param {Array<{name:string, data:Buffer|Uint8Array|string, compress?:boolean, date?:Date}>} entries
+ *   `compress` false stores the bytes (right for PNG/JPEG, already compressed);
+ *   the default deflates, and keeps the stored form when deflate does not help.
+ * @returns {Buffer}
+ */
+export function writeZip(entries, { date = new Date() } = {}) {
+  if (!Array.isArray(entries)) throw fail("zip_input", "writeZip needs a list of entries");
+  if (entries.length > 0xfffe) throw fail("zip_too_many", `${entries.length} entries is more than a plain ZIP holds`);
+  const seen = new Set();
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = String(entry.name ?? "");
+    if (!safeEntryName(name)) throw fail("zip_bad_name", `unsafe entry name: ${JSON.stringify(name)}`);
+    if (seen.has(name)) throw fail("zip_duplicate", `the entry ${name} appears twice`);
+    seen.add(name);
+    const raw = Buffer.isBuffer(entry.data) ? entry.data
+      : typeof entry.data === "string" ? Buffer.from(entry.data, "utf8") : Buffer.from(entry.data ?? []);
+    if (raw.length >= U32) throw fail("zip_too_large", `${name} is over 4 GB; a plain ZIP cannot hold it`);
+    const crc = zlib.crc32(raw) >>> 0;
+    let method = 0;
+    let body = raw;
+    if (entry.compress !== false && raw.length) {
+      const deflated = zlib.deflateRawSync(raw, { level: 6 });
+      if (deflated.length < raw.length) { method = 8; body = deflated; }
+    }
+    const nameBytes = Buffer.from(name, "utf8");
+    // A non-ASCII name also travels in the Info-ZIP Unicode Path field
+    // (0x7075): macOS's bundled unzip ignores the UTF-8 flag and mangles
+    // "ünïcode.csv" without it; readers that honour the flag ignore this.
+    const extra = /[^\x00-\x7f]/.test(name) ? unicodePathExtra(nameBytes) : Buffer.alloc(0);
+    const { time, date: dd } = dosTime(entry.date || date);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(SIG_LOCAL, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(FLAG_UTF8, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(dd, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(extra.length, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(SIG_CENTRAL, 0);
+    // Made by UNIX (3), spec 2.0: a reader then takes the name's bytes as they
+    // are. Marked MS-DOS (0), macOS's bundled unzip (6.00, no Unicode support)
+    // translated every non-ASCII name from code page 437 and wrote garbage.
+    central.writeUInt16LE((3 << 8) | 20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(FLAG_UTF8, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(dd, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(body.length, 20);
+    central.writeUInt32LE(raw.length, 24);
+    central.writeUInt16LE(nameBytes.length, 28);
+    central.writeUInt16LE(extra.length, 30);
+    central.writeUInt32LE(((name.endsWith("/") ? 0o40755 : 0o100644) << 16) >>> 0, 38);   // rw-r--r-- (a dir rwxr-xr-x)
+    central.writeUInt32LE(offset, 42);       // comment, disk, internal attrs: 0
+    locals.push(local, nameBytes, extra, body);
+    centrals.push(central, nameBytes, extra);
+    offset += local.length + nameBytes.length + extra.length + body.length;
+    if (offset >= U32) throw fail("zip_too_large", "the archive would pass 4 GB; a plain ZIP cannot hold it");
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(SIG_END, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+/**
+ * The central directory: every entry's name, sizes, method and where its
+ * bytes are — nothing inflated. What `bundle_list` shows, and what readZip
+ * checks the caps against before touching any data.
+ *
+ * @param {Buffer} buf
+ * @returns {Array<{name:string, method:number, crc:number, csize:number, usize:number, offset:number, dir:boolean}>}
+ */
+export function listZip(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 22) throw fail("zip_not_zip", "not a ZIP archive (too short)");
+  let end = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i -= 1) {
+    if (buf.readUInt32LE(i) === SIG_END) { end = i; break; }
+  }
+  if (end < 0) throw fail("zip_not_zip", "not a ZIP archive (no end record)");
+  const count = buf.readUInt16LE(end + 10);
+  const cdSize = buf.readUInt32LE(end + 12);
+  const cdOffset = buf.readUInt32LE(end + 16);
+  if (count === 0xffff || cdOffset === U32) throw fail("zip_zip64", "a ZIP64 archive — not a .btrn this version wrote");
+  if (cdOffset + cdSize > end) throw fail("zip_corrupt", "the central directory runs past the end record");
+  const out = [];
+  const names = new Set();
+  let p = cdOffset;
+  for (let k = 0; k < count; k += 1) {
+    if (p + 46 > end || buf.readUInt32LE(p) !== SIG_CENTRAL) throw fail("zip_corrupt", `central directory entry ${k + 1} is damaged`);
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const crc = buf.readUInt32LE(p + 16) >>> 0;
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nlen = buf.readUInt16LE(p + 28);
+    const xlen = buf.readUInt16LE(p + 30);
+    const clen = buf.readUInt16LE(p + 32);
+    const offset = buf.readUInt32LE(p + 42);
+    const name = buf.subarray(p + 46, p + 46 + nlen).toString((flags & FLAG_UTF8) ? "utf8" : "latin1");
+    if (!safeEntryName(name)) throw fail("zip_bad_name", `unsafe entry name in the archive: ${JSON.stringify(name)}`);
+    if (names.has(name)) throw fail("zip_duplicate", `the entry ${name} appears twice`);
+    names.add(name);
+    if (flags & 0x0001) throw fail("zip_encrypted", `${name} is encrypted`);
+    if (method !== 0 && method !== 8) throw fail("zip_method", `${name} uses compression method ${method}; only stored and deflated are read`);
+    out.push({ name, method, crc, csize, usize, offset, dir: name.endsWith("/") });
+    p += 46 + nlen + xlen + clen;
+  }
+  return out;
+}
+
+/**
+ * Read a ZIP: every file entry's bytes, verified.
+ *
+ * @param {Buffer} buf
+ * @param {{maxTotal?:number, maxRatio?:number, only?:(name:string)=>boolean}} [opts]
+ *   the cap on the whole archive's uncompressed bytes (default 2 GB); an
+ *   optional per-entry expansion cap (none by default: one layer of deflate
+ *   cannot pass ~1032×, and an honest file of zeros reaches 1026×, so a ratio
+ *   refuses real data while the total cap and the declared-size inflate are
+ *   what actually stop a bomb); `only` reads a subset
+ * @returns {Map<string, Buffer>}
+ */
+export function readZip(buf, { maxTotal = 2 * 1024 ** 3, maxRatio = Infinity, only = null } = {}) {
+  const entries = listZip(buf).filter((e) => !e.dir && (!only || only(e.name)));
+  const total = entries.reduce((a, e) => a + e.usize, 0);
+  if (total > maxTotal) throw fail("zip_bomb", `the archive expands to ${total} bytes, over the ${maxTotal}-byte cap`);
+  for (const e of entries) {
+    if (e.method === 8 && e.usize > Math.max(1024, e.csize * maxRatio)) {
+      throw fail("zip_bomb", `${e.name} claims to expand ${e.csize} → ${e.usize} bytes, over ${maxRatio}×`);
+    }
+  }
+  const files = new Map();
+  for (const e of entries) {
+    const p = e.offset;
+    if (p + 30 > buf.length || buf.readUInt32LE(p) !== SIG_LOCAL) throw fail("zip_corrupt", `${e.name}: its local header is damaged`);
+    const start = p + 30 + buf.readUInt16LE(p + 26) + buf.readUInt16LE(p + 28);
+    if (start + e.csize > buf.length) throw fail("zip_corrupt", `${e.name}: its data runs past the end`);
+    const body = buf.subarray(start, start + e.csize);
+    let data;
+    if (e.method === 0) {
+      if (e.csize !== e.usize) throw fail("zip_corrupt", `${e.name}: stored entry with two different sizes`);
+      data = Buffer.from(body);
+    } else {
+      try { data = zlib.inflateRawSync(body, { maxOutputLength: Math.max(1, e.usize) }); }
+      catch (err) { throw fail("zip_corrupt", `${e.name}: ${err.code === "ERR_BUFFER_TOO_LARGE" ? "inflates past its declared size" : "does not inflate"}`); }
+      if (data.length !== e.usize) throw fail("zip_corrupt", `${e.name}: inflated to ${data.length} bytes, declared ${e.usize}`);
+    }
+    if ((zlib.crc32(data) >>> 0) !== e.crc) throw fail("zip_crc", `${e.name}: CRC-32 does not match — the archive is damaged`);
+    files.set(e.name, data);
+  }
+  return files;
+}
+
+export default { writeZip, readZip, listZip, safeEntryName };

package/kernel/analyze.R

@@ -44,7 +44,7 @@ suppressPackageStartupMessages(stopifnot(requireNamespace("jsonlite", quietly =
 # raise it knowingly. Clamped to [0, 60] so a typo cannot remove the bound —
 # and 0 is a real setting, meaning "scan nothing and report it truncated".
 ANALYZE_BUDGET <- local({
-  v <- suppressWarnings(as.numeric(Sys.getenv("CARMAR_ANALYZE_BUDGET", "3")))
+  v <- suppressWarnings(as.numeric(Sys.getenv("BEATRINA_ANALYZE_BUDGET", "3")))
   if (!is.finite(v)) v <- 3
   max(0, min(v, 60))
 })