beatrina 0.8.6

package/check/acceptance.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// acceptance.mjs — does Beatrina do, on THIS machine, what a person needs?
+//
+// One file, no dependencies, so it can be copied to a Windows laptop and run
+// with the Node Beatrina already needs. It starts a supervisor on a scratch
+// port, opens a socket as the page does (Origin = the page the host served,
+// so page-only ops such as the terminal and a readline() answer are allowed),
+// and measures the things docs/beatrix-alternative-plan.md Stages 0, 1 and 4
+// are judged by:
+//
+//   startup · run · Stop (sleep, tight loop, a system() child) with the session
+//   kept · readline() · file ops and completion while R is busy · Force Stop ·
+//   the terminal · Python and JavaScript chunks when those engines exist.
+//
+// Usage
+//   node tools/beatrina/acceptance.mjs                         # this checkout's host
+//   node tools/beatrina/acceptance.mjs --installed             # the installed carmar package's host
+//   node tools/beatrina/acceptance.mjs --host=C:\path\to\host\main.mjs
+//   node tools/beatrina/acceptance.mjs --supervisor=serve-r    # the retired R supervisor, for comparison
+//   options: --port=28900 --repeat=5 --json=out.json --junit=out.xml --only=stop,readline --log=host.log
+//
+// Exit status: 0 when nothing FAILED (a SKIP is reported, never counted as a pass).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { WIN, pause, startSession, supervisorCommand } from "./session.mjs";
+
+const argv = Object.fromEntries(process.argv.slice(2).map((a) => {
+  const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+  return m ? [m[1], m[2] ?? "1"] : [a, "1"];
+}));
+const PORT = Number(argv.port || 28900 + Math.floor(Math.random() * 400));
+const REPEAT = Math.max(1, Number(argv.repeat || 3));
+const ONLY = argv.only ? new Set(argv.only.split(",")) : null;
+const SUPERVISOR = argv.supervisor || "beatrix";
+
+const results = [];
+const record = (area, name, status, detail = "", ms = null, extra = {}) => {
+  results.push({ area, name, status, detail: String(detail), ms, ...extra });
+  const tag = { pass: "PASS", fail: "FAIL", skip: "SKIP", note: "NOTE" }[status];
+  console.log(`  ${tag}  [${area}] ${name}${ms != null ? `  (${Math.round(ms)} ms)` : ""}${detail ? `  — ${String(detail).slice(0, 220)}` : ""}`);
+};
+const median = (xs) => { const s = [...xs].sort((a, b) => a - b); return s.length ? s[Math.floor((s.length - 1) / 2)] : null; };
+const want = (area) => !ONLY || ONLY.has(area);
+
+// ── the session under test ───────────────────────────────────────────────────
+const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-accept-"));
+const sup = supervisorCommand({ supervisor: SUPERVISOR, host: argv.host || "", installed: Boolean(argv.installed), binary: argv.binary || "", scratch });
+console.log(`\nBeatrina acceptance — ${sup.label}\n  ${os.type()} ${os.release()} ${process.arch} · node ${process.version} · port ${PORT}\n`);
+const session = await startSession({ command: sup, port: PORT, cwd: scratch, logFile: argv.log ? path.resolve(argv.log) : "" });
+
+async function shutdown(code) {
+  await session.shutdown();
+  writeReports();
+  try { fs.rmSync(scratch, { recursive: true, force: true }); } catch { /* Windows may hold a file a moment longer */ }
+  process.exit(code);
+}
+if (!session.announced) {
+  record("startup", "the supervisor announces a URL", "fail", session.log().split("\n").slice(-6).join(" | "));
+  await shutdown(1);
+}
+const { frames, until, ready, page } = session;
+if (!ready) { record("startup", "R announces ready", "fail", session.log().slice(-400)); await shutdown(1); }
+record("startup", `R ready (${ready.r || "?"}, worker mode ${ready.mode || "?"})`, "pass", "", session.startupMs, { r: ready.r, mode: ready.mode });
+
+let seq = 0;
+const text = (id) => session.text(id);
+const run = (source, opts = {}) => session.run(source, opts);
+const engines = Array.isArray(ready.engines) ? ready.engines : ["r"];
+
+// ── run ──────────────────────────────────────────────────────────────────────
+if (want("run")) {
+  const r = await run('keep <- 42; cat("keep=", keep, "\\n")');
+  record("run", "a chunk runs and prints", r.done?.status === "ok" && /keep= 42/.test(r.out()) ? "pass" : "fail", r.out().trim(), r.ms);
+  const warm = [];
+  for (let i = 0; i < REPEAT * 3; i += 1) warm.push((await run("invisible(1)")).ms);
+  record("run", `round trip of a trivial chunk, median of ${warm.length}`, "pass", `max ${Math.max(...warm)} ms`, median(warm), { series: warm });
+}
+
+// ── stop ─────────────────────────────────────────────────────────────────────
+async function stopCase(label, source, { engine, probe, expect, after = 900, keep }) {
+  // Every repetition is counted, not stopped at the first miss: a race shows
+  // up as a RATE, and one bad run in twenty is the finding.
+  const lat = [];
+  const misses = [];
+  for (let i = 0; i < REPEAT; i += 1) {
+    const id = `s${++seq}`;
+    const from = frames.length;
+    page.send({ type: "exec", id, source, ...(engine ? { engine } : {}) });
+    await pause(after);
+    const early = frames.slice(from).find((f) => f.type === "done" && f.id === id);
+    if (early) { misses.push(`finished before Stop: ${early.status}`); continue; }
+    const t = Date.now();
+    page.send({ type: "interrupt", id });
+    const done = await until((f) => f.type === "done" && f.id === id, 15000, from);
+    if (!done) { misses.push("no done frame 15 s after Stop"); break; }
+    // The harm is code AFTER the busy line running although Stop was pressed.
+    if (/after-stop/.test(text(id))) misses.push("the line after the busy call ran");
+    else lat.push(Date.now() - t);
+    const p = await run(probe, { engine, ms: 30000 });
+    if (!expect.test(p.out())) {
+      misses.push(`next chunk ${p.done?.status || "hung"}: ${JSON.stringify(p.out().trim().slice(0, 60))}`);
+      if (keep) await run(keep, { engine });
+    }
+  }
+  const summary = misses.length ? `${misses.length}/${REPEAT} missed — ${[...new Set(misses)].join("; ")}` : `max ${lat.length ? Math.max(...lat) : "—"} ms`;
+  record("stop", `${label}: interrupted with the session kept, ${REPEAT - misses.length}/${REPEAT}`, misses.length ? "fail" : "pass",
+    summary, lat.length ? median(lat) : null, { series: lat, misses: misses.length, repeat: REPEAT });
+}
+if (want("stop")) {
+  const probe = 'cat("keep=", exists("keep") && keep == 42, "\\n")';
+  await run("keep <- 42");
+  const keep = "keep <- 42";
+  await stopCase("Sys.sleep(60)", "Sys.sleep(60); cat('after-stop\\n')", { probe, expect: /keep= TRUE/, keep });
+  await stopCase("a tight loop", "i <- 0; while (i < 1e12) i <- i + 1; cat('after-stop\\n')", { probe, expect: /keep= TRUE/, keep });
+  await stopCase("a system() child", WIN ? 'system("ping -n 60 127.0.0.1", ignore.stdout = TRUE); cat("after-stop\\n")' : 'system("sleep 60"); cat("after-stop\\n")', { probe, expect: /keep= TRUE/, after: 1500, keep });
+}
+
+// ── readline ─────────────────────────────────────────────────────────────────
+if (want("readline")) {
+  const id = `r${++seq}`;
+  const from = frames.length;
+  page.send({ type: "exec", id, source: 'ans <- readline("Your name: "); cat("hello", ans, "\\n")' });
+  const asked = await until((f) => (f.type === "input_request") || (f.type === "done" && f.id === id), 10000, from);
+  if (!asked) record("readline", "readline() asks the page", "fail", "neither a question nor a done frame in 10 s");
+  else if (asked.type === "done") record("readline", "readline() asks the page", "fail", `returned without asking (worker mode ${ready.mode}): ${JSON.stringify(text(id))}`);
+  else {
+    page.send({ type: "input_reply", id: `rr${seq}`, value: "Beyza" });
+    const done = await until((f) => f.type === "done" && f.id === id, 10000, from);
+    record("readline", "readline() asks the page and receives the answer", done?.status === "ok" && /hello Beyza/.test(text(id)) ? "pass" : "fail", text(id).trim());
+  }
+}
+
+// ── while busy ───────────────────────────────────────────────────────────────
+const ask = (type, payload, ms) => session.ask(type, payload, ms);
+if (want("busy")) {
+  fs.writeFileSync(path.join(scratch, "note.txt"), "hello");
+  const id = `b${++seq}`;
+  const from = frames.length;
+  page.send({ type: "exec", id, source: "Sys.sleep(30)" });
+  await pause(800);
+  const w = await ask("writefile", { path: path.join(scratch, "saved.txt"), text: "saved while R was busy" });
+  record("busy", "Save (writefile) while a chunk runs", w.reply && !w.reply.error && fs.existsSync(path.join(scratch, "saved.txt")) ? "pass" : "fail", w.reply ? (w.reply.error || "") : "no reply", w.ms);
+  const rd = await ask("readfile", { path: path.join(scratch, "note.txt") });
+  record("busy", "Open (readfile) while a chunk runs", rd.reply && rd.reply.text === "hello" ? "pass" : "fail", rd.reply ? (rd.reply.error || "") : "no reply", rd.ms);
+  // Diagnostics come from the analysis process, which never waits for R.
+  const a = await ask("analyze", { uri: "chunk:accept", version: 1, source: "x <- 1\ny z" }, 15000);
+  const diag = JSON.stringify(a.reply || {});
+  record("busy", "diagnostics (analyze) while a chunk runs", a.reply && a.reply.type === "analyze" && /unexpected|error|syntax/i.test(diag) ? "pass" : "fail",
+    a.reply ? diag.slice(0, 120) : "no reply in 15 s", a.ms);
+  // Live completion reads R's workspace, so it is a WORKER op and waits by
+  // design; the page stops waiting after 1.5 s and keeps the analyzer's names.
+  const c = await ask("complete", { line: "rowSum", cursor: 6 }, 2500);
+  record("busy", "live completion while a chunk runs (a worker op: waits for R by design)", "note",
+    c.reply ? "answered" : "no answer within the page's 1.5 s budget, as designed", c.ms);
+  page.send({ type: "interrupt", id });
+  await until((f) => f.type === "done" && f.id === id, 15000, from);
+}
+
+// ── force stop ───────────────────────────────────────────────────────────────
+if (want("force")) {
+  await run("keep <- 42");
+  const id = `f${++seq}`;
+  const from = frames.length;
+  page.send({ type: "exec", id, source: "repeat tryCatch(Sys.sleep(1), interrupt = function(e) NULL)" });
+  await pause(900);
+  const t = Date.now();
+  page.send({ type: "force_stop", id });
+  const done = await until((f) => f.type === "done" && f.id === id, 20000, from);
+  const again = await until((f) => f.type === "ready", 60000, from);
+  const p = again ? await run('cat("fresh=", !exists("keep"), "\\n")') : null;
+  record("force", "Force Stop ends an uninterruptible chunk and a fresh R answers", done && again && p && /fresh= TRUE/.test(p.out()) ? "pass" : "fail",
+    `done=${done ? done.status : "none"} ready=${Boolean(again)} probe=${p ? p.out().trim() : "—"}`, again ? Date.now() - t : null);
+}
+
+// ── crash recovery ───────────────────────────────────────────────────────────
+// R dies under a running chunk (kill -9, as a segfault or the OOM killer would):
+// the chunk must END with a sentence, the page must be told, and a fresh R must
+// answer — never a spinner that waits for a process that is gone.
+if (want("crash")) {
+  const probe = await run('cat("pid=", Sys.getpid(), "\\n")');
+  const pid = Number((probe.out().match(/pid= (\d+)/) || [])[1]);
+  const id = `c${++seq}`;
+  const from = frames.length;
+  page.send({ type: "exec", id, source: "Sys.sleep(60)" });
+  await pause(800);
+  const t = Date.now();
+  let killed = false;
+  try { process.kill(pid, WIN ? undefined : "SIGKILL"); killed = true; } catch { killed = false; }
+  const done = await until((f) => f.type === "done" && f.id === id, 20000, from);
+  const told = await until((f) => f.type === "worker-died", 20000, from);
+  const again = await until((f) => f.type === "ready" && Number(f.pid) !== pid, 60000, from);
+  const after = again ? await run('cat("alive after crash\\n")') : null;
+  record("crash", "R killed under a running chunk: the chunk ends, the page is told, a fresh R answers",
+    killed && done && told && again && /alive after crash/.test(after ? after.out() : "") ? "pass" : "fail",
+    `killed=${killed} done=${done ? done.status : "none"} worker-died=${Boolean(told)} ready=${Boolean(again)}`, again ? Date.now() - t : null);
+}
+
+// ── memory over a working session ────────────────────────────────────────────
+// The SUPERVISOR's resident memory while a session runs many chunks, some with
+// tables. Growth that does not level off is the leak an 8-hour day would find.
+function rssKb(pid) {
+  if (WIN) {
+    const r = spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { encoding: "utf8" });
+    const m = String(r.stdout).match(/"([\d,.\s]+) K"/);
+    return m ? Number(m[1].replace(/[^\d]/g, "")) : null;
+  }
+  const r = spawnSync("ps", ["-o", "rss=", "-p", String(pid)], { encoding: "utf8" });
+  const v = Number(String(r.stdout).trim());
+  return Number.isFinite(v) && v > 0 ? v : null;
+}
+if (want("memory")) {
+  const rounds = Math.max(4, Number(argv.memoryRounds || 8));
+  const samples = [];
+  await run("df <- data.frame(id = seq_len(5000), x = rnorm(5000), g = sample(letters, 5000, TRUE))");
+  for (let round = 0; round < rounds; round += 1) {
+    for (let i = 0; i < 50; i += 1) await run(i % 10 === 0 ? "df" : `invisible(sum(df$x) + ${i})`);
+    samples.push(rssKb(session.child.pid));
+  }
+  const ok = samples.every((v) => v != null);
+  const firstHalf = samples.slice(0, Math.floor(samples.length / 2));
+  const secondHalf = samples.slice(Math.floor(samples.length / 2));
+  const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+  const growthMb = ok ? (mean(secondHalf) - mean(firstHalf)) / 1024 : null;
+  record("memory", `supervisor memory over ${rounds * 50} chunks (every tenth prints a 5,000-row table)`,
+    ok ? "note" : "skip", ok ? `RSS ${Math.round(samples[0] / 1024)} → ${Math.round(samples[samples.length - 1] / 1024)} MB; second half vs first half ${growthMb >= 0 ? "+" : ""}${growthMb.toFixed(1)} MB` : "memory could not be read on this platform",
+    null, { rssKb: samples, growthMb });
+}
+
+// ── terminal ─────────────────────────────────────────────────────────────────
+if (want("terminal")) {
+  const from = frames.length;
+  page.send({ type: "term_open", cols: 80, rows: 24, cwd: scratch });
+  const opened = await until((f) => f.type === "term" && (f.event === "open" || f.event === "error" || f.error), 10000, from);
+  if (!opened || opened.event !== "open") {
+    record("terminal", "a terminal opens", "fail", opened ? (opened.message || opened.error || JSON.stringify(opened)) : "no answer in 10 s");
+  } else {
+    await pause(800);
+    page.send({ type: "term_input", id: opened.id, text: WIN ? "echo beatrina-%NUMBER_OF_PROCESSORS%-ok\r\n" : "echo beatrina-$((6*7))\n" });
+    const hit = await until((f) => f.type === "term" && f.id === opened.id && f.event === "data" && (WIN ? /beatrina-\d+-ok/ : /beatrina-42/).test(f.text || ""), 10000, from);
+    record("terminal", "a terminal opens and runs a command", hit ? "pass" : "fail", hit ? "" : "no output in 10 s");
+    page.send({ type: "term_close", id: opened.id });
+  }
+}
+
+// ── other engines ────────────────────────────────────────────────────────────
+for (const [engine, setup, probe, sleeper] of [
+  ["python", "keep_py = 42\nprint('py keep', keep_py)", "print('py keep', keep_py)", "import time\ntime.sleep(60)\nprint('after-stop')"],
+  ["js", "globalThis.keepJs = 42; console.log('js keep', keepJs)", "console.log('js keep', keepJs)", "for (let i = 0; i < 1e13; i++) {}\nconsole.log('after-stop')"],
+]) {
+  if (!want(engine)) continue;
+  const row = Array.isArray(ready.engine_status) ? ready.engine_status.find((e) => e.engine === engine) : null;
+  if (!engines.includes(engine)) { record(engine, `${engine} chunks`, "skip", row ? row.detail || "engine not available" : "this host has no such engine"); continue; }
+  const first = await run(setup, { engine, ms: 120000 });
+  record(engine, `a ${engine} chunk runs (first run starts the engine)`, first.done?.status === "ok" && /keep 42/.test(first.out()) ? "pass" : "fail", first.out().trim() || first.done?.message || "", first.ms);
+  await stopCase(`${engine}: a busy chunk`, sleeper, { engine, probe, expect: /keep 42/, after: 1500, keep: setup });
+}
+
+// ── report ───────────────────────────────────────────────────────────────────
+function writeReports() {
+  const summary = {
+    supervisor: sup.label, platform: `${os.type()} ${os.release()}`, arch: process.arch, node: process.version,
+    r: results.find((r) => r.r)?.r || "", when: new Date().toISOString(), repeat: REPEAT,
+    passed: results.filter((r) => r.status === "pass").length, failed: results.filter((r) => r.status === "fail").length,
+    skipped: results.filter((r) => r.status === "skip").length, results,
+  };
+  if (argv.json) fs.writeFileSync(argv.json, JSON.stringify(summary, null, 2));
+  if (argv.junit) {
+    const esc = (s) => String(s).replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "\"": "&quot;" })[c]);
+    const cases = results.map((r) => `  <testcase classname="beatrina.acceptance.${esc(r.area)}" name="${esc(r.name)}" time="${((r.ms || 0) / 1000).toFixed(3)}">${
+      r.status === "fail" ? `<failure message="${esc(r.detail)}"/>` : r.status === "skip" ? `<skipped message="${esc(r.detail)}"/>` : ""}</testcase>`);
+    fs.writeFileSync(argv.junit, `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="beatrina-acceptance" tests="${results.length}" failures="${summary.failed}" skipped="${summary.skipped}">\n${cases.join("\n")}\n</testsuite>\n`);
+  }
+  console.log(`\n${summary.passed} passed · ${summary.failed} failed · ${summary.skipped} skipped — ${sup.label}`);
+}
+await shutdown(results.some((r) => r.status === "fail") ? 1 : 0);

package/check/session.mjs

@@ -0,0 +1,215 @@
+// session.mjs — start a Beatrix (or the retired R supervisor) and talk to it as the page does.
+//
+// Shared by tools/beatrina/acceptance.mjs and tools/beatrina/run-document.mjs.
+// No dependencies beyond Node, so the folder can be copied to a Windows laptop.
+
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const repo = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const WIN = process.platform === "win32";
+export const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** The installed carmar package's host/main.mjs, asked of R itself. */
+export function installedHost() {
+  const r = spawnSync(WIN ? "Rscript.exe" : "Rscript",
+    ["-e", "cat(system.file('app', 'host', 'main.mjs', package = 'carmar'))"], { encoding: "utf8" });
+  return String(r.stdout || "").trim();
+}
+
+/**
+ * What to start. `supervisor: "serve-r"` stages the retired R supervisor
+ * (comparison only); otherwise a Beatrix host: `host` path, the installed
+ * package's, or this checkout's.
+ */
+export function supervisorCommand({ supervisor = "beatrix", host = "", installed = false, binary = "", scratch }) {
+  if (binary) {
+    // A packaged single executable (the executable build is retired): it takes no script.
+    const abs = path.resolve(binary);                  // the session runs in a scratch cwd
+    if (!fs.existsSync(abs)) throw new Error(`no Beatrina executable at ${abs}`);
+    return { label: `Beatrina executable (${path.basename(abs)})`, cmd: abs, args: [] };
+  }
+  if (supervisor === "serve-r") {
+    const stage = path.join(scratch, "serve-r");
+    fs.mkdirSync(stage, { recursive: true });
+    for (const dir of [path.join(repo, "spike"), path.join(repo, "retired", "r-supervisor", "spike")]) {
+      for (const f of fs.readdirSync(dir)) {
+        const p = path.join(dir, f);
+        if (fs.statSync(p).isFile()) fs.copyFileSync(p, path.join(stage, f));
+        else if (f === "plugins" || f === "examples") fs.cpSync(p, path.join(stage, f), { recursive: true });
+      }
+    }
+    fs.copyFileSync(path.join(repo, "kernel.protocol"), path.join(stage, "kernel-protocol"));
+    const version = String(spawnSync(process.execPath, ["-p", "require(process.argv[1]).version", path.join(repo, "notebook.version.cjs")], { encoding: "utf8" }).stdout).trim();
+    fs.writeFileSync(path.join(stage, "kernel-version"), `${version}\n`);
+    for (const f of fs.readdirSync(path.join(repo, "dist")).filter((x) => /^carmar_V.*\.html$/.test(x))) {
+      fs.copyFileSync(path.join(repo, "dist", f), path.join(stage, f));
+    }
+    return { label: "R supervisor (serve.R, retired)", cmd: WIN ? "Rscript.exe" : "Rscript", args: [path.join(stage, "serve.R")] };
+  }
+  // Absolute: the session runs in a scratch cwd, and check.R passes a path relative to the kit.
+  const main = path.resolve(host || (installed ? installedHost() : path.join(repo, "host", "main.mjs")));
+  if (!main || !fs.existsSync(main)) throw new Error(`no Beatrina host at ${main || "(installed package not found)"}`);
+  return { label: `Beatrina (${path.relative(process.cwd(), main) || main})`, cmd: process.execPath, args: [main] };
+}
+
+// ── a WebSocket that can carry an Origin (Node's own cannot) ─────────────────
+export function openSocket(port, origin) {
+  const key = crypto.randomBytes(16).toString("base64");
+  return new Promise((resolve, reject) => {
+    const sock = net.connect(port, "127.0.0.1");
+    let buf = Buffer.alloc(0);
+    let open = false;
+    let partial = null;
+    const handlers = [];
+    const frame = (text) => {
+      const body = Buffer.from(text, "utf8");
+      const mask = crypto.randomBytes(4);
+      const head = body.length < 126 ? Buffer.from([0x81, 0x80 | body.length])
+        : body.length < 65536 ? Buffer.from([0x81, 0xfe, body.length >> 8, body.length & 0xff])
+          : Buffer.concat([Buffer.from([0x81, 0xff]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(body.length)); return b; })()]);
+      for (let i = 0; i < body.length; i += 1) body[i] ^= mask[i & 3];
+      return Buffer.concat([head, mask, body]);
+    };
+    sock.on("error", reject);
+    sock.on("connect", () => sock.write([`GET / HTTP/1.1`, `Host: 127.0.0.1:${port}`, "Upgrade: websocket", "Connection: Upgrade",
+      `Sec-WebSocket-Key: ${key}`, "Sec-WebSocket-Version: 13", `Origin: ${origin}`, "", ""].join("\r\n")));
+    sock.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      if (!open) {
+        const end = buf.indexOf("\r\n\r\n");
+        if (end < 0) return;
+        const status = buf.subarray(0, end).toString("latin1").split(" ")[1];
+        buf = buf.subarray(end + 4);
+        if (status !== "101") { sock.destroy(); reject(new Error(`socket refused: HTTP ${status}`)); return; }
+        open = true;
+        resolve(api);
+      }
+      for (;;) {
+        if (buf.length < 2) return;
+        const fin = (buf[0] & 0x80) !== 0;
+        const op = buf[0] & 0x0f;
+        let len = buf[1] & 0x7f;
+        let off = 2;
+        if (len === 126) { if (buf.length < 4) return; len = buf.readUInt16BE(2); off = 4; } else if (len === 127) { if (buf.length < 10) return; len = Number(buf.readBigUInt64BE(2)); off = 10; }
+        if (buf.length < off + len) return;
+        const payload = buf.subarray(off, off + len);
+        buf = buf.subarray(off + len);
+        if (op === 0x9) { const pong = Buffer.from(frame("")); pong[0] = 0x8a; sock.write(pong); continue; }
+        if (op === 0x8) { sock.end(); return; }
+        if (op === 0x1 || op === 0x0) {
+          partial = op === 0x1 ? payload : Buffer.concat([partial || Buffer.alloc(0), payload]);
+          if (!fin) continue;
+          const text = partial.toString("utf8");
+          partial = null;
+          handlers.forEach((fn) => fn(text));
+        }
+      }
+    });
+    const api = {
+      send: (obj) => sock.write(frame(JSON.stringify(obj))),
+      onMessage: (fn) => handlers.push(fn),
+      close: () => { try { sock.destroy(); } catch { /* gone */ } },
+    };
+  });
+}
+
+
+/**
+ * Start a supervisor on `port`, open a page socket, and wait for R's ready.
+ * @returns {Promise<object>} the session: frames, until, text, run, ask, ready, startupMs, log, shutdown
+ */
+export async function startSession({ command, port, cwd, env = {}, readyMs = 90000, logFile = "" }) {
+  const t0 = Date.now();
+  const child = spawn(command.cmd, command.args, {
+    cwd,
+    env: {
+      ...process.env, CARMAR_PORT: String(port), CARMAR_NO_NATIVE_DIALOG: "1", CARMAR_NO_RUNTIME_FILE: "1",
+      CARMAR_HISTORY_DIR: path.join(cwd, ".beatrina-history"), CARMAR_NO_UPDATE_CHECK: "1", CARMAR_LINGER: "0",
+      BEATRIX_NO_OPEN: "1",                   // the `beatrix` command opens a browser unless told not to
+      ...env,
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  let hostLog = "";
+  // A binary that cannot be started is a result to report, not a crash.
+  child.on("error", (e) => { hostLog += `\n${e.message}`; });
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (d) => { hostLog = (hostLog + d).slice(-6000); });
+  // The whole host log, both streams, when asked (tools/beatrina/repeat-acceptance.mjs keeps one per run).
+  if (logFile) {
+    const log = fs.createWriteStream(logFile, { flags: "a" });
+    child.stdout.on("data", (d) => log.write(d));
+    child.stderr.on("data", (d) => log.write(d));
+    child.on("exit", (code, signal) => log.end(`\n[host exited: ${signal || code}]\n`));
+  }
+  const announced = await new Promise((resolve) => {
+    let out = "";
+    const timer = setTimeout(() => resolve(null), 120000);
+    child.stdout.on("data", (d) => {
+      out += d;
+      const line = out.split("\n").find((l) => /"url"/.test(l));
+      if (line) { clearTimeout(timer); try { resolve(JSON.parse(line)); } catch { resolve(null); } }
+    });
+    child.on("exit", () => { clearTimeout(timer); resolve(null); });
+  });
+
+  let stopped = false;
+  const shutdown = async () => {
+    if (stopped) return;
+    stopped = true;
+    if (session.page) session.page.close();
+    try { await fetch(`http://127.0.0.1:${port}/shutdown`, { method: "POST", signal: AbortSignal.timeout(3000) }); } catch { /* fall through */ }
+    const exited = child.exitCode !== null || await Promise.race([new Promise((r) => child.once("exit", () => r(true))), pause(8000).then(() => false)]);
+    if (!exited && child.exitCode === null) {
+      if (WIN) spawnSync("taskkill", ["/T", "/F", "/PID", String(child.pid)]);
+      else { try { process.kill(child.pid, "SIGKILL"); } catch { /* gone */ } }
+    }
+  };
+  const session = { child, port, announced, page: null, frames: [], ready: null, startupMs: null, log: () => hostLog, shutdown };
+  if (!announced) return session;
+
+  const page = await openSocket(port, `http://127.0.0.1:${port}`);
+  session.page = page;
+  const frames = session.frames;
+  page.onMessage((t) => { try { frames.push(JSON.parse(t)); } catch { /* not JSON */ } });
+  session.until = async (pred, ms, from = 0) => {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+      for (let i = from; i < frames.length; i += 1) if (pred(frames[i])) return frames[i];
+      await pause(15);
+    }
+    return null;
+  };
+  session.text = (id) => frames.filter((f) => (f.type === "stdout" || f.type === "stream" || f.type === "stderr") && f.id === id).map((f) => f.text || "").join("\n");
+  let seq = 0;
+  session.nextId = (prefix = "a") => `${prefix}${++seq}`;
+  session.send = (obj) => page.send(obj);
+  /** Run a chunk and wait for its done frame. */
+  session.run = async (source, { engine, document, srcname, ms = 30000, id = session.nextId("a") } = {}) => {
+    const from = frames.length;
+    const started = Date.now();
+    page.send({ type: "exec", id, source, ...(engine ? { engine } : {}), ...(document ? { document } : {}), ...(srcname ? { srcname } : {}) });
+    const done = await session.until((f) => f.type === "done" && f.id === id, ms, from);
+    return { id, done, ms: Date.now() - started, out: () => session.text(id), frames: () => frames.slice(from).filter((f) => f.id === id) };
+  };
+  /** Send a request op and wait for its reply. */
+  session.ask = async (type, payload, ms = 10000) => {
+    const id = session.nextId("q");
+    const from = frames.length;
+    const t = Date.now();
+    page.send({ type, id, ...payload });
+    const reply = await session.until((f) => f.id === id && f.type !== "stdout" && f.type !== "stderr", ms, from);
+    return { reply, ms: Date.now() - t };
+  };
+  session.ready = await session.until((f) => f.type === "ready", readyMs);
+  session.startupMs = Date.now() - t0;
+  return session;
+}

package/engines/js/document-exec.mjs

@@ -0,0 +1,82 @@
+// document-exec.mjs — the notebook exec envelope (`document_exec_v1`) for JavaScript.
+//
+// The page refuses to run any chunk against a kernel whose ready frame does not
+// claim `document_exec_v1`, and sends every run with a `document` descriptor
+// (lib/document-execution.js). This is engines/python/document_exec.py in
+// JavaScript — which is itself spike/knitr-run.R's run_document_cell() minus
+// knitr: a document's `setup` chunk runs once per (document, setup source) and
+// is then a Ready snapshot; a failed setup blocks dependent chunks until it is
+// fixed, run explicitly, or retried. Chunk options are not applied (they are
+// knitr's, render-time, and have no JavaScript meaning), so the done frame says
+// `cacheHit: false` and `effectiveOptions: null` — nothing claimed that was not
+// done. The error sentences are R's, verbatim: the page shows them and its tests
+// assert them.
+
+export const FEATURE = "document_exec_v1";
+const LABEL_RE = /^[A-Za-z0-9_.-]+$/;
+
+export class DocumentExecError extends Error {}
+
+/** Per-document setup state for ONE evaluating session. */
+export class DocumentSetups {
+  constructor() { this.docs = new Map(); }
+
+  reset() { this.docs.clear(); }
+
+  /**
+   * Decide what an envelope asks for, before anything runs. Throws
+   * DocumentExecError with the user-facing sentence.
+   * @returns {{docId: string, label: string|null, setupSource: string|null, setupSrcname: string|null,
+   *            runSetup: boolean, runChunk: boolean, execution: object}}
+   */
+  plan(source, document) {
+    if (!document || typeof document !== "object" || typeof document.id !== "string" || !document.id) {
+      throw new DocumentExecError("A notebook run needs its document identity.");
+    }
+    const docId = document.id;
+    const setup = document.setup ?? null;
+    if (setup !== null && (typeof setup !== "object" || typeof setup.source !== "string")) {
+      throw new DocumentExecError("Invalid setup chunk descriptor.");
+    }
+    const isSetup = document.isSetup === true;
+    const retry = document.retrySetup === true;
+    const selection = document.selection === true;
+    const setupKey = setup ? setup.source : "";
+    const previous = this.docs.get(docId);
+    if (previous && previous.source === setupKey && previous.status === "failed" && !isSetup && !retry) {
+      throw new DocumentExecError("Setup previously failed. Fix it or explicitly run the setup chunk before running dependent chunks.");
+    }
+    const setupChanged = !previous || previous.source !== setupKey;
+    const runSetup = setup !== null && (setupChanged || isSetup || previous.status === "failed");
+    let label = null;
+    if (!isSetup) {
+      label = document.label;
+      if (typeof label !== "string" || !LABEL_RE.test(label)) {
+        throw new DocumentExecError("Use a unique chunk label containing letters, numbers, dots, hyphens or underscores.");
+      }
+      const isDict = (x) => x && typeof x === "object" && !Array.isArray(x);
+      if (!isDict(document.options ?? {}) || !isDict(document.expressions ?? {})) {
+        throw new DocumentExecError("Invalid chunk options.");
+      }
+    }
+    return {
+      docId, label,
+      setupSource: setup ? setupKey : null,
+      setupSrcname: setup ? (setup.srcname ?? null) : null,
+      runSetup, runChunk: !isSetup,
+      execution: {
+        source: isSetup && setup ? setup.source : source,
+        setupSource: setup ? setup.source : "",
+        optionsKey: document.optionsKey ?? null,
+        full: !selection,
+      },
+    };
+  }
+
+  /** Invalidate BEFORE running: a failed partial setup must not leave a snapshot. */
+  setupStarted(docId) { this.docs.delete(docId); }
+  setupOk(docId, source) { this.docs.set(docId, { source, status: "ok" }); }
+  setupFailed(docId, source) { this.docs.set(docId, { source, status: "failed" }); }
+  /** No setup chunk: the snapshot is the empty source, so one added later is a CHANGE. */
+  noSetup(docId) { this.docs.set(docId, { source: "", status: "ok" }); }
+}