beatrina 0.9.43 → 1.0.0

package/host/engine-pool.mjs

@@ -23,11 +23,28 @@
 //   §6.9 An absent engine is a STATED FACT: a chunk whose engine has no
 //        runtime ends with a done frame that says so, never a hang.
 //
-// ON DEMAND, EXCEPT R. R starts at boot because the page will not leave
-// "connecting" until a `ready` arrives and because every existing suite
-// expects a session to be there. Every other engine starts the first time a
-// chunk of its language runs — an ipykernel that nobody asked for is 1.3
-// seconds and ~60 MB spent on a document that may hold no Python at all.
+// THREE BOOT MODES (plans/getting_rid_of_R.md K2, K2a). The HOST is what a
+// page waits for — `host-ready`, sent by host/server.mjs on every socket — so
+// no engine is on the start-up path any more:
+//   "eager"       started and AWAITED by start(). Nothing ships this way now;
+//                 it stays for a test that wants a worker before the port.
+//   "background"  started by start() WITHOUT waiting, and only when found. R:
+//                 optional is not late — R users should not pay R's start-up
+//                 on their first chunk — but a missing or broken R must never
+//                 hold the host, the document or a Save hostage.
+//   "on-demand"   started the first time a chunk of its language runs — an
+//                 ipykernel nobody asked for is 1.3 s and ~60 MB spent on a
+//                 document that may hold no Python at all.
+// An engine that has been started but has not said `ready` HOLDS what is sent
+// to it (whenEngineReady): a page may now be connected before R is, and a
+// chunk written to R's stdin before its ready would race "Restart, keep
+// variables" (the restore is queued on ready).
+//
+// AVAILABILITY IS READ WHEN AN ENGINE IS ABOUT TO START (K2b), not frozen at
+// boot: a spec may carry `detect()`, re-run by `refresh()` before every start,
+// so installing R or changing `rscript_path` takes effect without restarting
+// the host. The "primary" below is the ROUTING DEFAULT for a request that names
+// no engine (every existing page sends R's that way) — never readiness.
 
 import { EventEmitter } from "node:events";
 import { WorkerPlane } from "./worker-plane.mjs";
@@ -66,20 +83,58 @@ export class EnginePool extends EventEmitter {
     this.planes = new Map();
     this.starting = new Map();           // engine → Promise, so two chunks start one engine
     this.sockets = () => [];
+    this.deadlineScale = deadlineScale;
+    this.respawnMax = respawnMax;
     this.primaryName = specs[0] ? specs[0].name : "r";
-    for (const spec of specs) {
-      if (!spec.available) continue;
-      const plane = new WorkerPlane({
-        engineFactory: spec.factory, name: spec.name, label: spec.label,
-        audit: (event, fields = {}) => audit(event, { engine: spec.name, ...fields }),
-        deadlineScale, respawnMax,
-        decorateReady: (frame) => this.onReady(spec, frame),
-      });
-      plane.sockets = () => this.sockets();
-      plane.on("broadcast", (payload) => this.emit("broadcast", payload));
-      plane.on("broadcast-pages", (payload) => this.emit("broadcast-pages", payload));
-      this.planes.set(spec.name, plane);
+    for (const spec of specs) if (spec.available) this.makePlane(spec);
+  }
+
+  /** The WorkerPlane for one spec, created once — at construction, or when a
+   *  refresh() finds a runtime that was absent at boot. */
+  makePlane(spec) {
+    if (this.planes.has(spec.name)) return this.planes.get(spec.name);
+    const plane = new WorkerPlane({
+      engineFactory: spec.factory, name: spec.name, label: spec.label,
+      audit: (event, fields = {}) => this.audit(event, { engine: spec.name, ...fields }),
+      deadlineScale: this.deadlineScale, respawnMax: this.respawnMax,
+      decorateReady: (frame) => this.onReady(spec, frame),
+    });
+    plane.sockets = () => this.sockets();
+    plane.on("broadcast", (payload) => {
+      this.emit("broadcast", payload);
+      // A death, a restart or a refusal changes this engine's row; the host
+      // re-announces the table so a page's greyed chunks follow the fact.
+      if (typeof payload === "string" && /"type":"worker-(died|restarting)"/.test(payload)) this.emit("engines-changed");
+    });
+    plane.on("broadcast-pages", (payload) => this.emit("broadcast-pages", payload));
+    plane.on("ready", () => { spec.startError = ""; this.emit("engines-changed"); });
+    this.planes.set(spec.name, plane);
+    return plane;
+  }
+
+  /**
+   * Re-read one engine's availability (K2b). Only a spec that carries
+   * `detect()` changes; the others are what boot discovered. A runtime that
+   * disappears under a RUNNING engine is not acted on here — the process is
+   * already running and keeps its session until it is restarted.
+   * @returns {object|null} the spec
+   */
+  refresh(name) {
+    const spec = this.specs.find((s) => s.name === engineKey(name, this.primaryName));
+    if (!spec || typeof spec.detect !== "function") return spec || null;
+    let found;
+    try { found = spec.detect() || {}; } catch (e) { found = { available: false, detail: e.message }; }
+    const was = Boolean(spec.available);
+    spec.available = Boolean(found.available);
+    spec.detail = found.detail || "";
+    if (found.version != null) spec.version = found.version;
+    if (found.runtime != null) spec.runtime = found.runtime;
+    if (spec.available) this.makePlane(spec);
+    if (was !== spec.available) {
+      this.audit("engine-discovery", { engine: spec.name, available: spec.available, detail: spec.detail });
+      this.emit("engines-changed");
     }
+    return spec;
   }
 
   /** The plane for an engine, or null when this host has no such engine. */
@@ -104,6 +159,11 @@ export class EnginePool extends EventEmitter {
         engine: spec.name, label: spec.label, available: Boolean(spec.available),
         detail: spec.detail || "", runtime: spec.runtime || null,
         started: Boolean(plane && plane.engine), alive: Boolean(plane && plane.alive),
+        // Has it said `ready`? `alive` is only "the process exists".
+        ready: Boolean(plane && plane.engine && plane.hello),
+        boot: spec.boot || "eager",
+        // Why a background start failed, until the engine next says ready.
+        error: spec.startError || (plane && plane.gaveUp ? "stopped" : ""),
         pid: plane && plane.engine ? plane.pid : null,
         version: spec.version || "",
       };
@@ -143,9 +203,60 @@ export class EnginePool extends EventEmitter {
     for (const p of this.planes.values()) { if (p.engine && p.alive) { try { p.engine.kill(); } catch { /* gone */ } } }
   }
 
+  /**
+   * Start what boots with the host. "eager" is awaited (and its failure is the
+   * caller's); "background" is kicked and NOT awaited — the returned promise
+   * of each is kept on `this.background` for a test to wait on. A background
+   * engine that will not start is recorded on its row and announced as a
+   * terminal worker-died, never thrown: the host serves without it.
+   */
   async start() {
-    const eager = this.specs.filter((s) => s.available && s.boot !== "on-demand");
+    const eager = this.specs.filter((s) => s.available && (s.boot || "eager") === "eager");
     for (const spec of eager) await this.planes.get(spec.name).start();
+    this.background = this.specs.filter((s) => s.boot === "background").map((spec) => this.startBackground(spec));
+  }
+
+  async startBackground(spec) {
+    this.refresh(spec.name);
+    if (!spec.available) return { ok: false, message: spec.detail || "" };
+    const r = await this.ensure(spec.name);
+    if (!r.ok) {
+      // The bare cause: the page words the sentence (lib/host-words.js).
+      const cause = r.message.replace(/^The \S+ engine would not start: /, "");
+      spec.startError = cause;
+      const plane = this.planes.get(spec.name);
+      // The page is told the way a failed Restart tells it (WorkerPlane.refuseStart).
+      if (plane && !plane.notice) plane.refuseStart(new Error(cause));
+      this.emit("engines-changed");
+    }
+    return r;
+  }
+
+  /**
+   * Resolve once an engine that has been STARTED has said `ready`, or has
+   * given up (a terminal worker-died), whichever is first. An engine that
+   * already said ready resolves at once. Commands for it wait on this, so no
+   * write can overtake its ready — and the restore that ready queues.
+   */
+  whenEngineReady(key) {
+    const plane = this.planes.get(key);
+    if (!plane || !plane.engine || plane.hello || plane.gaveUp) return Promise.resolve();
+    if (!this.readyWaits) this.readyWaits = new Map();
+    if (!this.readyWaits.has(key)) {
+      this.readyWaits.set(key, new Promise((resolve) => {
+        const done = () => {
+          clearInterval(poll);
+          plane.off("ready", done);
+          this.readyWaits.delete(key);
+          resolve();
+        };
+        plane.on("ready", done);
+        // A give-up is a flag, not an event; the plane's own sweep is 100 ms.
+        const poll = setInterval(() => { if (plane.gaveUp || !plane.engine) done(); }, 100);
+        poll.unref?.();
+      }));
+    }
+    return this.readyWaits.get(key);
   }
 
   /**
@@ -154,6 +265,8 @@ export class EnginePool extends EventEmitter {
    */
   async ensure(name) {
     const key = engineKey(name, this.primaryName);
+    // Availability is read NOW (K2b), before anything is started.
+    if (!this.planes.get(key)?.engine) this.refresh(key);
     const spec = this.specs.find((s) => s.name === key);
     if (!spec) {
       return { ok: false, message: `Beatrina has no ${key} engine; this chunk was not run.` };
@@ -163,7 +276,7 @@ export class EnginePool extends EventEmitter {
       return { ok: false, message: `${spec.label} is not installed or was not found; this chunk was not run. `
         + `${spec.detail || ""} Doctor lists what was searched.`.replace(/\s+/g, " ").trim() };
     }
-    const plane = this.planes.get(key);
+    const plane = this.makePlane(spec);
     if (plane.engine) return { ok: true, plane };
     if (!this.starting.has(key)) {
       this.audit("engine-start", { engine: key });
@@ -250,14 +363,15 @@ export class EnginePool extends EventEmitter {
     if (!scalarChr(cmd.id) || typeof cmd.source !== "string") return undefined;
     const key = engineKey(cmd.engine, this.primaryName);
     const plane = this.planes.get(key);
-    if (plane && plane.engine) return plane.exec(cmd, rec);
+    if (plane && plane.engine && plane.hello) return plane.exec(cmd, rec);
     // An engine that is not up yet: start it, THEN dispatch. The page sees a
     // slower first chunk and nothing else — no queue of its own, no state here.
-    this.ensure(key).then((r) => {
+    this.ensure(key).then(async (r) => {
       if (!r.ok) {
         this.audit("engine-absent", { engine: key });
         return rec.ws.send(enc({ type: "done", id: cmd.id, status: "error", message: r.message }));
       }
+      await this.whenEngineReady(key);
       return r.plane.exec(cmd, rec);
     }).catch((e) => {
       rec.ws.send(enc({ type: "done", id: cmd.id, status: "error", message: e.message }));
@@ -279,7 +393,16 @@ export class EnginePool extends EventEmitter {
     if (cmd.type === "debug_breaks") this.noteBreaks(cmd);
     const key = engineKey(cmd.engine, this.primaryName);
     const plane = this.planes.get(key);
-    if (plane && plane.engine) return plane.request(cmd, rec);
+    if (plane && plane.engine && plane.hello) return plane.request(cmd, rec);
+    // Started, not yet ready (a background R still booting): held, not refused.
+    if (plane && plane.engine && !plane.gaveUp) {
+      this.whenEngineReady(key).then(() => {
+        if (plane.engine && plane.hello) return plane.request(cmd, rec);
+        if (scalarChr(cmd.id)) rec.ws.send(enc({ type: cmd.type, id: cmd.id, error: `${plane.label} did not start.`, code: "no-engine" }));
+        return undefined;
+      });
+      return undefined;
+    }
     if (!scalarChr(cmd.id)) return undefined;
     const spec = this.specs.find((s) => s.name === key);
     const why = !spec ? `Beatrina has no ${key} engine.`
@@ -333,11 +456,15 @@ export class EnginePool extends EventEmitter {
   async restart(engine, opts = {}) {
     const key = engineKey(engine, this.primaryName);
     const plane = this.planes.get(key);
-    if (!plane) return undefined;
-    if (!plane.engine) {
-      // Restarting an engine that never started is "start it", not an error.
+    if (!plane || !plane.engine) {
+      // Restarting an engine that never started is "start it", not an error —
+      // and ensure() re-reads availability, so "Restart R" after installing R
+      // is how a running host picks it up (K2b).
       const r = await this.ensure(key);
-      return r.ok ? undefined : undefined;
+      // A refusal is re-announced as the engines table, which is what a page
+      // reads to say why (host-ready's engine_status row for this engine).
+      if (!r.ok) this.emit("engines-changed");
+      return undefined;
     }
     return plane.restart(key === this.primaryName ? opts : {});
   }

package/host/engine-r.mjs

@@ -60,7 +60,14 @@ export function detectRscript(explicit = readEnv(process.env, "RSCRIPT"), platfo
   for (const cand of KNOWN_RSCRIPT) if (fs.existsSync(cand)) return cand;
   const versions = "/Library/Frameworks/R.framework/Versions";
   if (fs.existsSync(versions)) {
-    const hits = fs.readdirSync(versions)
+    // A framework folder that EXISTS but cannot be listed (permissions, a
+    // half-removed install, a sandbox) is an R this process cannot run — "not
+    // found", said by the caller. It threw here, and at start that is a host
+    // that will not come up over an R it did not need (found 2026-09-23 by
+    // running the no-R suites with R's files unreadable).
+    let names = [];
+    try { names = fs.readdirSync(versions); } catch { names = []; }
+    const hits = names
       .map((v) => path.join(versions, v, "Resources/bin/Rscript"))
       .filter((p) => fs.existsSync(p)).sort().reverse();
     if (hits.length) return hits[0];

package/host/jobs/document-child.mjs

@@ -0,0 +1,271 @@
+// document-child.mjs — the `render`, `typst` and `latex` jobs with no R
+// (plans/getting_rid_of_R.md Stage 3, K7).
+//
+// The R child (spike/job-run.R) renders through rmarkdown or Quarto and needs R
+// to start at all, so a prose-only document could not be rendered on a machine
+// without R. This child speaks the SAME framed wire — a sentinel, then one
+// JSON object with the job's own id stamped (the frame-fidelity rule: the plane
+// forwards these bytes, never re-encodes them) — and the same events:
+// `started`, `output`, `done`. Everything Quarto prints goes to stdout as
+// ordinary output, which the plane streams into the job's log.
+//
+// It renders with QUARTO only: rmarkdown is an R package. Before rendering it
+// asks Quarto which engine the document binds to, and a document whose R
+// chunks need knitr is refused in words rather than failed half-way.
+//
+// `typst` is spike/typst.R's typst_compile(), ported rule for rule: typst from
+// BEATRINA_TYPST, PATH, or Quarto's bundled copy (`quarto typst`); `--root`
+// one level up for a file inside `.beatrina-preview`; a PDF beside the source,
+// or one SVG per page (`<stem>-N.svg`, the old ones deleted first) for the
+// live preview; the first `error:` and its `file.typ:L:C` said as one sentence.
+//
+// `latex` is spike/latex.R's latex_compile(), ported to host/latex-compile.mjs
+// and driven from here exactly as job-run.R drives the R one: the options are
+// re-validated by the plane's own jobSpec() before anything starts (this file
+// is runnable by hand, and a task that trusted its environment would be a very
+// quiet way to run the wrong thing), and the compile's source identity
+// (BEATRINA_LATEX_IDENTITY: uri, version, generation) is stamped on EVERY
+// frame from `started` to `done`, after the job id — job-run.R's
+// `compile_identity`, which is how the page drops a reply for an older edit.
+//
+// Inputs arrive in the ENVIRONMENT, never argv (jobs.mjs: the wire never
+// carries code): BEATRINA_JOB_ID / _TASK / _TARGET / _FORMAT, BEATRINA_SENTINEL,
+// BEATRINA_JOB_R_AVAILABLE ("1" when this session has R), and for `latex`
+// BEATRINA_LATEX_ENGINE / _TIMEOUT / _FETCH / _IDENTITY (jobs.mjs latexOptions).
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { readEnv } from "../env-names.mjs";
+import { documentWorkdir, findQuarto, missingForRender, quartoEngines } from "../quarto.mjs";
+import { latexCompile, LATEX_TIMEOUT } from "../latex-compile.mjs";
+import { jobSpec } from "../planes/jobs.mjs";
+import { descendantsOf } from "../planes/proc-tree.mjs";
+
+const SENTINEL = readEnv(process.env, "SENTINEL");
+const id = readEnv(process.env, "JOB_ID") || "job";
+const task = readEnv(process.env, "JOB_TASK");
+const target = readEnv(process.env, "JOB_TARGET");
+const format = readEnv(process.env, "JOB_FORMAT");
+const haveR = readEnv(process.env, "JOB_R_AVAILABLE") === "1";
+const started = Date.now();
+/** A LaTeX compile's source identity, stamped on every frame once validated. */
+let compileIdentity = null;
+
+/** One control frame: the sentinel, then compact JSON with this job's id first. */
+const emit = (obj) => {
+  const { type, ...rest } = obj;
+  process.stdout.write(`${SENTINEL}${JSON.stringify({ type, id, ...(compileIdentity || {}), ...rest })}\n`);
+};
+const done = (ok, error = "") => {
+  emit({ type: "job", event: "done", ok, error, elapsed: Math.round((Date.now() - started) / 10) / 100 });
+  process.exitCode = ok ? 0 : 1;
+};
+
+async function main() {
+  // As job-run.R: a LaTeX job's options are checked BEFORE `started`, and a
+  // refusal is a lone `done` (exit 2), so no frame carries an unvalidated identity.
+  const latex = task === "latex" ? prepareLatex() : null;
+  if (task === "latex" && !latex) return;
+  emit({ type: "job", event: "started", task, root: path.dirname(target), pid: process.pid });
+  if (!target || !fs.existsSync(target)) return done(false, `'${target}' is not a file`);
+  if (task === "typst") return typst();
+  if (task === "latex") return compileLatex(latex);
+  if (task !== "render") return done(false, `this child renders and typesets documents; it was asked for '${task}'`);
+
+  const bin = findQuarto();
+  if (!bin) {
+    return done(false, "Quarto is not installed, or Beatrina could not find it. Install Quarto from https://quarto.org, "
+      + "or set BEATRINA_QUARTO to the binary. Your document is unchanged.");
+  }
+  const { engines, detail } = quartoEngines(bin, target);
+  const missing = missingForRender(engines, { r: haveR });
+  if (missing) return done(false, missing);
+  if (!engines && detail) process.stdout.write(`(quarto inspect could not say which engine this document uses: ${detail})\n`);
+
+  let text = "";
+  try { text = fs.readFileSync(target, "utf8"); } catch { text = ""; }
+  const workdir = documentWorkdir(target, text);
+  if (workdir.declared && !fs.existsSync(workdir.path)) {
+    return done(false, `the document declares beatrina-workdir: ${workdir.declared}, but '${workdir.path}' is not a folder`);
+  }
+  const args = ["render", target];
+  if (format) args.push("--to", format);
+  // As job-run.R: PNG figures (no cairo needed) and the .typ kept for Typst.
+  if (format === "typst") args.push("-M", "fig-format:png", "-M", "keep-typ:true");
+  if (workdir.declared) args.push("--execute-dir", workdir.path);
+
+  const status = await runStreaming(bin, args, { cwd: path.dirname(target) });
+  const { lines } = status;
+  if (status.error) return done(false, `quarto could not be started: ${status.error}`);
+  if (status.code !== 0) return done(false, `quarto render exited ${status.signal || status.code}`);
+
+  // The output path is REPORTED by Quarto ("Output created: <path>", relative
+  // to the document's folder) and checked to exist — never guessed.
+  const hits = lines.map((l) => l.trim()).filter((l) => l.startsWith("Output created:"));
+  let produced = null;
+  if (hits.length) {
+    const reported = hits[hits.length - 1].replace(/^Output created:/, "").trim();
+    const candidate = path.isAbsolute(reported) ? reported : path.join(path.dirname(target), reported);
+    if (fs.existsSync(candidate)) produced = path.resolve(candidate);
+  }
+  emit({ type: "job", event: "output", renderer: "quarto", path: produced, format: format || null });
+  return done(true);
+}
+
+/** At most this many characters of a run's output are KEPT (all are streamed). */
+const KEPT_CHARS = 1000000;
+
+/**
+ * Run a program, streaming its output into the job log and keeping the lines.
+ *
+ * What is kept is bounded twice — 20,000 lines and, as job-run.R's
+ * run_streaming, 1,000,000 characters — and `truncated` says when either bound
+ * dropped something, because a list that silently stops looks exactly like a
+ * transcript that ended. (R cuts mid-line at the character bound; this drops
+ * whole lines from the head, so the first kept line is never a fragment.)
+ * A timeout kills the child's DESCENDANTS first, then the child — latexmk runs
+ * pdflatex and bibtex beneath it, and SIGTERM to latexmk alone left them
+ * running (job-run.R does the same through kernel_kill_tree).
+ *
+ * `merge` puts stderr on stdout's pipe, IN ORDER, as processx's `2>&1` does
+ * for job-run.R. Two pipes read separately interleave however the reads land,
+ * and for a compile the order is data: a `!` line and the `l.N` after it are
+ * one diagnostic only when they arrive adjacent. On a POSIX system the program
+ * is exec'd by `/bin/sh -c 'exec "$0" "$@" 2>&1'` with the binary and every
+ * argument as POSITIONAL parameters — the script is a constant, nothing from
+ * the job is ever parsed by the shell, and `exec` keeps the child's pid the
+ * engine's own. Windows has no such sh; there the two pipes are read as before.
+ */
+function runStreaming(bin, args, { cwd, timeoutMs = 0, merge = false } = {}) {
+  return new Promise((resolve) => {
+    const lines = [];
+    let tail = "";
+    let timedOut = false;
+    let truncated = false;
+    let keptChars = 0;
+    const keep = (chunk) => {
+      const text = String(chunk);
+      process.stdout.write(text);
+      const parts = (tail + text).split("\n");
+      tail = parts.pop();
+      lines.push(...parts);
+      keptChars += parts.reduce((n, p) => n + p.length + 1, 0);
+      if (lines.length > 20000) {
+        lines.splice(0, lines.length - 20000).forEach((p) => { keptChars -= p.length + 1; });
+        truncated = true;
+      }
+      while (keptChars > KEPT_CHARS && lines.length) { keptChars -= lines.shift().length + 1; truncated = true; }
+    };
+    const [cmd, argv] = merge && process.platform !== "win32"
+      ? ["/bin/sh", ["-c", 'exec "$0" "$@" 2>&1', bin, ...args]]
+      : [bin, args];
+    const child = spawn(cmd, argv, { cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      timedOut = true;
+      for (const pid of descendantsOf(child.pid)) { try { process.kill(pid, "SIGKILL"); } catch { /* gone */ } }
+      try { child.kill("SIGTERM"); } catch { /* gone */ }
+    }, timeoutMs) : null;
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    for (const sig of ["SIGTERM", "SIGINT"]) process.on(sig, () => { try { child.kill(sig); } catch { /* gone */ } });
+    child.on("error", (e) => { if (timer) clearTimeout(timer); resolve({ code: null, error: e.message, lines, timedOut, truncated }); });
+    child.on("close", (code, signal) => { if (timer) clearTimeout(timer); if (tail) lines.push(tail); resolve({ code, signal, lines, timedOut, truncated }); });
+  });
+}
+
+/** The typst to run: [binary, prefix-args], or null. */
+function typstCommand() {
+  const explicit = readEnv(process.env, "TYPST");
+  if (explicit && fs.existsSync(explicit)) return [explicit, []];
+  const exe = process.platform === "win32" ? "typst.exe" : "typst";
+  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
+    if (dir && fs.existsSync(path.join(dir, exe))) return [path.join(dir, exe), []];
+  }
+  const quarto = findQuarto();
+  return quarto ? [quarto, ["typst"]] : null;
+}
+
+async function typst() {
+  const found = typstCommand();
+  if (!found) return done(false, "Typst was not found. It comes with Quarto — install Quarto, or set BEATRINA_TYPST to a typst binary.");
+  const [bin, prefix] = found;
+  const timeoutS = Number(readEnv(process.env, "TYPST_TIMEOUT")) > 0 ? Number(readEnv(process.env, "TYPST_TIMEOUT")) : 120;
+  const pages = readEnv(process.env, "TYPST_PAGES") === "svg";
+  const stem = path.basename(target).replace(/\.[^.]+$/, "");
+  const here = path.dirname(target);
+  const root = path.basename(here) === ".beatrina-preview" ? path.dirname(here) : here;
+  const pdf = path.join(here, `${stem}.pdf`);
+  const pageFiles = () => fs.readdirSync(here).filter((n) => n.startsWith(`${stem}-`) && /^[0-9]+\.svg$/.test(n.slice(stem.length + 1)))
+    .sort().map((n) => path.join(here, n));
+  if (pages) pageFiles().forEach((f) => { try { fs.unlinkSync(f); } catch { /* gone */ } });
+  const args = pages
+    ? [...prefix, "compile", "--root", root, "--format", "svg", target, path.join(here, `${stem}-{p}.svg`)]
+    : [...prefix, "compile", "--root", root, target, pdf];
+  const r = await runStreaming(bin, args, { cwd: here, timeoutMs: timeoutS * 1000 });
+  if (r.timedOut) return done(false, `The Typst compile did not finish within ${timeoutS} seconds.`);
+  if (r.error) return done(false, `typst could not be started: ${r.error}`);
+  if (r.code !== 0) {
+    const at = r.lines.findIndex((l) => /^error:/.test(l));
+    let detail = "";
+    if (at >= 0) {
+      const span = r.lines.slice(at, at + 6);
+      // eslint-disable-next-line no-control-regex
+      const where = span.find((l) => /\.typ:[0-9]+:[0-9]+/.test(l));
+      detail = [span[0].replace(/^error:\s*/, ""), where ? where.replace(/[\u2500-\u257F]|[\x00-\x1f]/g, "").trim() : ""].filter(Boolean).join(" — ");
+    }
+    return done(false, detail ? `Typst: ${detail.slice(0, 400)}` : "Typst reported an error; see the log in Jobs.");
+  }
+  if (pages) {
+    const made = pageFiles();
+    if (!made.length) return done(false, "Typst compiled the document but wrote no pages.");
+    emit({ type: "job", event: "output", renderer: "typst", path: null, format: "svg", pages: made.length });
+    return done(true);
+  }
+  emit({ type: "job", event: "output", renderer: "typst", path: fs.existsSync(pdf) ? path.resolve(pdf) : null });
+  return done(true);
+}
+
+/**
+ * Validate a LaTeX job the way job-run.R does — the plane's own jobSpec(), so
+ * the two cannot disagree about what is runnable — and adopt its identity.
+ * @returns {{engine: string, timeout: number, fetch: boolean}|null} null after a refusal
+ */
+function prepareLatex() {
+  try {
+    const identityText = readEnv(process.env, "LATEX_IDENTITY");
+    const identity = identityText ? JSON.parse(identityText) : null;
+    const timeoutText = readEnv(process.env, "LATEX_TIMEOUT", String(LATEX_TIMEOUT));
+    const spec = jobSpec("latex", target, {
+      engine: readEnv(process.env, "LATEX_ENGINE", "auto"),
+      // as.numeric(): "" and junk are NA, which the validator refuses.
+      timeout: timeoutText.trim() === "" ? NaN : Number(timeoutText),
+      fetch: readEnv(process.env, "LATEX_FETCH") === "1",
+      identity,
+    });
+    if (!spec.ok) throw new Error(spec.error);
+    compileIdentity = identity ? { uri: identity.uri, version: identity.version, generation: identity.generation } : null;
+    return {
+      engine: spec.env.BEATRINA_LATEX_ENGINE,
+      timeout: Number(spec.env.BEATRINA_LATEX_TIMEOUT),
+      fetch: spec.env.BEATRINA_LATEX_FETCH === "1",
+    };
+  } catch (e) {
+    done(false, e && e.message ? e.message : String(e));
+    process.exitCode = 2;
+    return null;
+  }
+}
+
+async function compileLatex({ engine, timeout, fetch }) {
+  try {
+    await latexCompile({ target, engine, timeout, fetch, emit,
+      runStreaming: (bin, args, opts) => runStreaming(bin, args, { ...opts, merge: true }) });
+  } catch (e) {
+    // Reported, never swallowed: the message is the job's result.
+    return done(false, e && e.message ? e.message : String(e));
+  }
+  return done(true);
+}
+
+main().catch((e) => done(false, e && e.message ? e.message : String(e)));

package/host/journal-store.mjs

@@ -22,7 +22,8 @@
 //                                 the page's checkpoint codec wrote)
 //     checkpoint.rev              the revision of that envelope
 //     pins/<rev>.json             a named version, with its content
-//     meta.json                   display name, file binding, gaps, updated
+//     meta.json                   display name, file binding, gaps, updated,
+//                                 and `saved` — what the last Save wrote (N3)
 //     journal.corrupt-<time>      bytes cut from a journal that did not end at
 //                                 a line boundary — kept as evidence
 //
@@ -295,6 +296,10 @@ export function createJournalStore() {
 
   // ── the ops ───────────────────────────────────────────────────────────────
 
+  const HEX64 = /^[0-9a-f]{64}$/;
+  const validSaved = (v) => v != null && typeof v === "object" && !Array.isArray(v)
+    && typeof v.model === "string" && HEX64.test(v.model) && typeof v.file === "string" && HEX64.test(v.file);
+
   const open = (id, key, meta, takeover) => {
     if (!enabled) return err("journal_open", id, "unavailable", "The document journal is disabled (BEATRINA_NO_JOURNAL=1).");
     if (!validKey(key)) return err("journal_open", id, "invalid_key", "A journal needs a durable document key.");
@@ -428,7 +433,7 @@ export function createJournalStore() {
     return before - st.bytes;
   };
 
-  const checkpoint = (id, key, revision, generation, envelope, meta, rebase, epoch) => {
+  const checkpoint = (id, key, revision, generation, envelope, meta, rebase, epoch, saved) => {
     if (!enabled) return err("journal_checkpoint", id, "unavailable", "The document journal is disabled.");
     if (!validKey(key)) return err("journal_checkpoint", id, "invalid_key", "A journal needs a durable document key.");
     const refused = leaseRefusal("journal_checkpoint", id, dirOf(key), epoch);
@@ -437,6 +442,9 @@ export function createJournalStore() {
         || typeof envelope !== "string" || !envelope.length) {
       return err("journal_checkpoint", id, "invalid_checkpoint", "A checkpoint needs a revision and its envelope.");
     }
+    // Refused before anything is written, so a bad marker never leaves a
+    // checkpoint on disk that the store's state does not know about.
+    if (saved != null && !validSaved(saved)) return err("journal_checkpoint", id, "invalid_saved", "A save marker needs two SHA-256 digests.");
     let st;
     try { st = stateOf(key); } catch (e) { return err("journal_checkpoint", id, "io", e.message); }
     const rev = Math.trunc(revision);
@@ -464,6 +472,13 @@ export function createJournalStore() {
       stored.gaps = [...(stored.gaps ?? []), gap];
     }
     if (meta && typeof meta === "object" && Object.keys(meta).length) stored.display = meta;
+    // N3: a Save rides on a checkpoint and says what it wrote — two digests,
+    // the document's content and the file's bytes. It is kept apart from
+    // `display` because the next opening's journal_open replaces `display`
+    // before it loads, and this is exactly what that opening needs to read.
+    // Content-addressed, so it is never cleared: a later edit simply stops it
+    // matching. Anything malformed is refused rather than stored half-read.
+    if (saved != null) stored.saved = { model: saved.model, file: saved.file, at: Date.now() };
     try { writeMeta(st.dir, stored); } catch { /* the checkpoint still stands */ }
     st.checkpoint = rev;
     st.last = rev;
@@ -501,6 +516,7 @@ export function createJournalStore() {
     return { type: "journal_load", id, key, aliases: meta.aliases ?? [],
       checkpointRevision: st.checkpoint, durableRevision: st.last,
       more, repaired: st.repaired === true, gaps: meta.gaps ?? [], pins: pinsOf(st.dir),
+      saved: validSaved(meta.saved) ? meta.saved : null,
       __raw: { records, checkpoint: envelope } };
   };
 
@@ -691,7 +707,7 @@ export function createJournalStore() {
       case "journal_probe": return probe(cmd.id, cmd.key);
       case "journal_append": return append(cmd.id, cmd.key, cmd.records, cmd.epoch);
       case "journal_checkpoint": return checkpoint(cmd.id, cmd.key, cmd.revision, cmd.generation, cmd.envelope,
-        cmd.meta && typeof cmd.meta === "object" ? cmd.meta : null, cmd.rebase === true, cmd.epoch);
+        cmd.meta && typeof cmd.meta === "object" ? cmd.meta : null, cmd.rebase === true, cmd.epoch, cmd.saved ?? null);
       case "journal_archive": return archive(cmd.id, cmd.key);
       case "journal_rename": return rename(cmd.id, cmd.from, cmd.to);
       case "journal_load": return load(cmd.id, cmd.key, cmd.afterRevision);