beatrina 0.8.6 → 0.9.43

package/failsafe/session-documents.R

@@ -0,0 +1,104 @@
+# session-documents.R — which documents a session has open, held by the kernel.
+#
+# Why the kernel, and not the page's storage: every session of one build is
+# served by the SAME notebook file, and the page remembers its open documents
+# per file (lib/open-documents.js). So two sessions share one record, and the
+# later one overwrites the earlier — reopening a session from the menu helper
+# brought back its R (40 objects, 1.9 GB) in front of an empty notebook
+# (owner, 2026-09-14: "it has the objects but not the file").
+#
+# The session is the thing that has an identity here, so the session keeps the
+# list. The page reports it (`page-documents`); a page that attaches to a
+# running session with nobody else on it asks for it back (`session-documents`)
+# and reopens each file. Only paths, names and formats travel — never text:
+# unsaved edits stay in the page that made them, and a document that was never
+# saved is listed by name so the page can SAY it cannot come back.
+#
+# Pure functions; spike/serve.R holds the state. Pinned by
+# spike/test-session-documents.R.
+
+SESSION_DOCUMENTS_MAX <- 64L
+SESSION_DOCUMENT_FORMATS <- c("qmd", "Rmd", "md", "carmd")
+
+#' Validate a page's report into a clean list of documents.
+#'
+#' Anything malformed is dropped row by row, never the whole report: one odd
+#' row must not cost the session the record of the others.
+#'
+#' @param documents What jsonlite made of the frame's `documents` field
+#'   (simplifyVector = TRUE: a data.frame, a list, or NULL).
+#' @return A list of `list(path, name, format, active)`; `path` is "" for a
+#'   document that has no file yet. At most SESSION_DOCUMENTS_MAX rows.
+session_documents_clean <- function(documents) {
+  if (is.null(documents) || !length(documents)) return(list())
+  rows <- if (is.data.frame(documents)) {
+    lapply(seq_len(nrow(documents)), \(i) as.list(documents[i, , drop = FALSE]))
+  } else if (is.list(documents)) {
+    documents
+  } else {
+    return(list())
+  }
+  one <- function(row) {
+    if (!is.list(row)) return(NULL)
+    text_of <- function(value, cap) {
+      if (!is.character(value) || length(value) != 1L || is.na(value)) return(NULL)
+      value <- gsub("[[:cntrl:]]", " ", value)
+      if (nchar(value) > cap) return(NULL)
+      value
+    }
+    path <- text_of(row$path %||% "", 4096L)
+    name <- text_of(row$name %||% "", 200L)
+    format <- text_of(row$format %||% "", 16L)
+    if (is.null(path) || is.null(name) || is.null(format)) return(NULL)
+    # A path is reopened through the file ops, which resolve it themselves;
+    # here it need only be absolute, so a relative string cannot be read
+    # against whatever the worker's cwd is by then.
+    if (nzchar(path) && !grepl("^(/|[A-Za-z]:[/\\\\])", path)) return(NULL)
+    if (!nzchar(path) && !nzchar(trimws(name))) return(NULL)
+    if (!format %in% SESSION_DOCUMENT_FORMATS) format <- "qmd"
+    list(path = path, name = trimws(name), format = format,
+         active = isTRUE(row$active))
+  }
+  cleaned <- Filter(Negate(is.null), lapply(rows, one))
+  # The same file listed twice is one document.
+  paths <- vapply(cleaned, \(row) row$path, character(1))
+  keep <- !nzchar(paths) | !duplicated(paths)
+  head(cleaned[keep], SESSION_DOCUMENTS_MAX)
+}
+
+#' The name a session goes by: its document, not its generated notebook name.
+#'
+#' Flattened for the runtime record, which helper-sessions.sh reads with a
+#' bounded sed — a quote or a backslash would cut every field after it.
+#'
+#' @param documents A list from session_documents_clean().
+#' @return "" when there are none; else the on-screen document's name (the
+#'   first one when none is marked), then " + N more" for the rest.
+session_documents_label <- function(documents) {
+  if (!length(documents)) return("")
+  active <- Filter(\(row) isTRUE(row$active), documents)
+  lead <- if (length(active)) active[[1L]] else documents[[1L]]
+  name <- if (nzchar(lead$path)) basename(lead$path) else lead$name
+  if (!nzchar(lead$path)) name <- sprintf("%s (unsaved)", name)
+  rest <- length(documents) - 1L
+  label <- if (rest > 0L) sprintf("%s + %d more", name, rest) else name
+  trimws(substr(gsub("[\"\\\\]", "'", gsub("[[:cntrl:]]", " ", label)), 1L, 120L))
+}
+
+#' Serialise for a successor supervisor's environment (a session handoff).
+#' @param documents A list from session_documents_clean().
+#' @return A JSON string; "" when there are none.
+session_documents_encode <- function(documents) {
+  if (!length(documents)) return("")
+  as.character(jsonlite::toJSON(documents, auto_unbox = TRUE))
+}
+
+#' Read back what session_documents_encode() wrote; junk yields an empty list.
+#' @param text A JSON string (possibly "").
+#' @return A list from session_documents_clean().
+session_documents_decode <- function(text) {
+  if (!is.character(text) || length(text) != 1L || !nzchar(text)) return(list())
+  parsed <- tryCatch(jsonlite::fromJSON(text, simplifyVector = TRUE),
+                     error = function(e) NULL)
+  session_documents_clean(parsed)
+}

package/host/ai-authority.mjs

@@ -0,0 +1,55 @@
+// ai-authority.mjs — the supervisor's half of the chat authority contract.
+//
+// The page's half is `lib/ai-authority.js`, and the two lists are ONE list in
+// two files for the reason every other pair in this project is (THEME_TOKENS /
+// EDITOR_TOKENS, LATEX_TEMPLATE_KEYS / TEMPLATE_KEYS): the kernel ships `host/`
+// and `spike/` without `lib/`, and no host module imports across that line.
+// `test/ai-chat-authority.test.mjs` reads both files and fails if they drift.
+//
+// WHY THE HOST IS WHERE THIS IS DECIDED. A CLI turn is a process THIS process
+// spawns. The tool list handed to that process is the only gate with no
+// page-side bypass: there is nothing in the browser to work around, because
+// the spawn was never made with those tools in it. The page's copy exists to
+// ASK for a level and to describe the lane honestly; the host's copy is what
+// happens.
+//
+// The level arriving on the wire is a REQUEST, and `normalizeAuthority` fails
+// closed — absent or unrecognised is `read`. An older page that never heard of
+// the field asks for the reading tools and gets them; silence never grants the
+// most (fix.md P1.5: "switching providers never silently increases authority"
+// covers switching anything else, too).
+
+export const READ_TOOLS = Object.freeze([
+  "beatrina_status", "notebook_read", "chunk_read", "file_list", "file_read",
+]);
+
+export const WRITE_TOOLS = Object.freeze([
+  "chunk_insert", "chunk_update", "chunk_run",
+]);
+
+export const AUTHOR_TOOLS = Object.freeze([...READ_TOOLS, ...WRITE_TOOLS]);
+
+export const AUTHORITY_LEVELS = Object.freeze(["text", "read", "author"]);
+
+/** Read a level off the wire, failing closed. */
+export function normalizeAuthority(value) {
+  const asked = String(value || "").toLowerCase();
+  return AUTHORITY_LEVELS.includes(asked) ? asked : "read";
+}
+
+/** The tools a level may use. `text` gets none. */
+export function toolsFor(authority) {
+  if (authority === "author") return AUTHOR_TOOLS.slice();
+  if (authority === "read") return READ_TOOLS.slice();
+  return [];
+}
+
+/** The `--allowedTools` value for a spawned Claude Code turn at this level. */
+export function allowedToolsArg(authority) {
+  return toolsFor(authority).map((name) => `mcp__beatrina__${name}`).join(",");
+}
+
+export default {
+  READ_TOOLS, WRITE_TOOLS, AUTHOR_TOOLS, AUTHORITY_LEVELS,
+  normalizeAuthority, toolsFor, allowedToolsArg,
+};

package/host/ai-policy.mjs

@@ -26,15 +26,16 @@
 //
 // ── where a policy comes from ──────────────────────────────────────────────
 //
-//   CARMAR_AI_POLICY=/etc/carmar/ai-policy.json   a file the user cannot write
-//   CARMAR_AI_PROVIDERS=anthropic,lmstudio        the quick form
-//   CARMAR_AI_LOCAL_ONLY=1                        only on-machine providers
+//   BEATRINA_AI_POLICY=/etc/beatrina/ai-policy.json   a file the user cannot write
+//   BEATRINA_AI_PROVIDERS=anthropic,lmstudio        the quick form
+//   BEATRINA_AI_LOCAL_ONLY=1                        only on-machine providers
 //
 // The file wins where both are set, because a file is the form an administrator
 // can own while an environment variable is inherited from whoever started the
 // process — on a shared host, that may be the user.
 
 import fs from "node:fs";
+import { envReader } from "./env-names.mjs";
 
 /**
  * The providers whose text never leaves the machine.
@@ -54,7 +55,7 @@ export const KEY_PROVIDERS = Object.freeze(["openai", "anthropic", "google", "gr
 export const CLI_PROVIDERS = Object.freeze(["claudecode", "codex"]);
 export const ALL_PROVIDERS = Object.freeze([...ON_MACHINE_PROVIDERS, ...KEY_PROVIDERS, ...CLI_PROVIDERS]);
 
-const sysEnv = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const sysEnv = envReader(process.env);   // dual-read: BEATRINA_AI_POLICY or its older spelling (host/env-names.mjs)
 const asList = (v) => (v == null ? [] : (Array.isArray(v) ? v : [v]));
 
 /**
@@ -101,6 +102,12 @@ export function normaliseBaseUrls(raw) {
   return { values, errors };
 }
 
+// Every key this file reads. A policy carrying anything else is a policy
+// whose author meant something the supervisor will not do — `provider` for
+// `providers` was accepted in silence and read as "permit all fifteen"
+// (fix.md P1.4). An unknown key is a refusal, with the key named.
+export const POLICY_KEYS = Object.freeze(["providers", "local_only", "note", "models", "base_urls"]);
+
 const policySplit = (value) => String(value || "").split(/[,\s]+/).map((s) => s.trim()).filter((s) => s.length);
 // Control characters are 0x00-0x1f and 0x7f — R's [[:cntrl:]], spelled out.
 // eslint-disable-next-line no-control-regex
@@ -115,12 +122,13 @@ const stripControl = (s) => String(s).replace(/[\u0000-\u001f\u007f]/g, " ");
  * named nothing / named something valid / named only junk — and conflating the
  * last two is the fail-open bug.
  */
-export function carmarAiPolicy(env = sysEnv) {
-  const file = String(env("CARMAR_AI_POLICY", "")).trim();
+export function beatrinaAiPolicy(env = sysEnv) {
+  const file = String(env("BEATRINA_AI_POLICY", "")).trim();
   let named = [];
   let models = {};
   let baseUrls = {};
-  let localOnly = env("CARMAR_AI_LOCAL_ONLY", "") === "1";
+  let localOnly = env("BEATRINA_AI_LOCAL_ONLY", "") === "1";
+  let namedKeyPresent = false;
   let note = "";
   let source = "";
   let errors = [];
@@ -128,13 +136,25 @@ export function carmarAiPolicy(env = sysEnv) {
   if (file.length) {
     source = file;
     if (!fs.existsSync(file)) {
-      errors.push(`CARMAR_AI_POLICY names a file that does not exist: ${file}`);
+      errors.push(`BEATRINA_AI_POLICY names a file that does not exist: ${file}`);
     } else {
       let doc = null;
       let parseError = "";
       try { doc = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { parseError = e.message; }
-      if (parseError) errors.push(`CARMAR_AI_POLICY is not valid JSON: ${parseError}`);
-      else {
+      if (parseError) errors.push(`BEATRINA_AI_POLICY is not valid JSON: ${parseError}`);
+      else if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+        errors.push("BEATRINA_AI_POLICY must be a JSON object of policy keys.");
+      } else {
+        const unknownKeys = Object.keys(doc).filter((k) => !POLICY_KEYS.includes(k));
+        if (unknownKeys.length) {
+          errors.push(`AI policy: ${unknownKeys.map((k) => `'${k}'`).join(", ")} `
+            + `${unknownKeys.length === 1 ? "is not a policy key" : "are not policy keys"}. `
+            + `A policy may name: ${POLICY_KEYS.join(", ")}. A key nobody reads permits everything, which is never what the file meant.`);
+        }
+        // "the key is present" and "the key names something" are different
+        // facts: `providers: []` used to read as "said nothing", which the
+        // default answers with every provider.
+        namedKeyPresent = Object.prototype.hasOwnProperty.call(doc, "providers");
         named = asList(doc && doc.providers).flat().map((v) => String(v));
         if (doc && doc.local_only === true) localOnly = true;
         note = String(asList(doc && doc.note).flat()[0] ?? "").trim();
@@ -148,20 +168,34 @@ export function carmarAiPolicy(env = sysEnv) {
         errors = errors.concat(endpoints.errors);
       }
     }
-  } else if (String(env("CARMAR_AI_PROVIDERS", "")).length) {
+  } else if (String(env("BEATRINA_AI_PROVIDERS", "")).length) {
     source = "env";
-    named = policySplit(env("CARMAR_AI_PROVIDERS", ""));
+    named = policySplit(env("BEATRINA_AI_PROVIDERS", ""));
   } else if (localOnly) {
     source = "env";
   }
 
   const unknown = named.filter((n) => !ALL_PROVIDERS.includes(n));
-  const asked = named.length > 0;                 // did the policy NAME anything at all?
+  // ASKED means the policy spoke about providers at all — including an empty
+  // list, which speaks and names nothing. Only silence inherits the default.
+  const asked = named.length > 0 || namedKeyPresent;
   named = named.filter((n) => ALL_PROVIDERS.includes(n));
 
   let providers = named.length ? named : (asked ? [] : [...ALL_PROVIDERS]);
   if (localOnly) providers = providers.filter((p) => ON_MACHINE_PROVIDERS.includes(p));
 
+  // local_only is a promise about where the words GO, so an endpoint that
+  // leaves the machine contradicts it — and an on-machine provider pointed at
+  // a hosted gateway is exactly how that happens without looking wrong.
+  if (localOnly) {
+    Object.entries(baseUrls).forEach(([provider, url]) => {
+      if (!LOOPBACK_RE.test(url)) {
+        errors.push(`AI policy: local_only is set, but base_urls.${provider} is ${url}, which leaves this machine. `
+          + "Point it at loopback, or drop local_only.");
+      }
+    });
+  }
+
   let set = source.length > 0 && errors.length === 0;
   if (set && !providers.length) {
     errors.push(`The AI policy permits no provider at all${
@@ -193,18 +227,6 @@ export function carmarAiPolicy(env = sysEnv) {
 export const aiProviderAllowed = (provider, policy) =>
   policy.set !== true || (typeof provider === "string" && provider.length > 0 && policy.providers.includes(provider));
 
-/**
- * May this model be used with this provider? TRUE when no models are pinned for
- * that provider — pinning is opt-in per provider. DISCLOSURE ONLY: a model id
- * is a field in a request body the page builds and sends itself, so there is no
- * door here to close.
- */
-export const aiModelAllowed = (provider, model, policy) => {
-  if (policy.set !== true) return true;
-  const allowed = policy.models[provider || ""];
-  if (!allowed || !allowed.length) return true;
-  return typeof model === "string" && model.length > 0 && allowed.includes(model);
-};
 
 /**
  * The sentence the notebook shows when something is refused. Names the
@@ -213,6 +235,6 @@ export const aiModelAllowed = (provider, model, policy) => {
  * message.
  */
 export const aiPolicyReason = (policy) => {
-  const base = `This CarmaR is configured to allow only: ${policy.providers.join(", ")}.`;
+  const base = `This Beatrina is configured to allow only: ${policy.providers.join(", ")}.`;
   return policy.note.length ? `${base} ${policy.note}` : base;
 };

package/host/bundle.mjs

@@ -0,0 +1,194 @@
+// bundle.mjs — `.btrn`, the Beatrina document that travels (docs/results-plan.md R2).
+//
+// A standard ZIP (host/zip.mjs) holding the document, its results and the files
+// it needs — "transfer the whole document like carmnote" (owner, 2026-09-19):   // beatrina-names: keep
+//
+//   manifest.json          format, version, app, created, title, what is inside
+//                          (every entry: size + SHA-256), and the data: its mode
+//                          and every file's path, size and SHA-256
+//   <name>.qmd             the document, plain text (its own .Rmd/.md if it was one)
+//   results/results.json   the beatrina-results/1 record (lib/document-results.js)
+//   results/figures/*      the record's figures, stored (PNG is compressed already)
+//   data/<relative path>   every file the document needs, deflated, at the path it
+//                          uses: data, bibliography, citation style, images, included
+//                          files, project settings (lib/bundle.js documentFiles)
+//
+// NO HISTORY, by the owner's decision (2026-09-19): Undo history holds every
+// keystroke, deleted text included — a document sent to someone must not carry
+// what its author removed. A CarmNote carries none either; the author's own
+// history stays in their session's journal.
+//
+// DATA ≤ 100 MB (compressed, in total) travels inside. Past that it goes BESIDE
+// the bundle, in `<name>.btrn-data/` at the same relative paths, and the manifest
+// keeps each file's size and SHA-256 so the receiver can tell a missing or a
+// changed file by name. A folder, not a second zip: big data stays usable as it
+// is, and ZIP's 4 GB ceiling never comes up.
+//
+// Pure where it can be: buildBundle / readBundle take bytes and return bytes or
+// parts; the plane (host/planes/bundle.mjs) does the file system and the doors.
+
+import crypto from "node:crypto";
+import path from "node:path";
+import { writeZip, readZip, listZip, safeEntryName } from "./zip.mjs";
+
+export const BUNDLE_FORMAT = "beatrina-bundle";
+export const BUNDLE_VERSION = 1;
+export const BUNDLE_EXT = ".btrn";
+/** Data travels inside up to this many compressed bytes; past it, beside. */
+export const DATA_INSIDE_MAX = 100 * 1024 * 1024;
+/** Reading: the whole archive may not expand past this. */
+export const BUNDLE_READ_MAX = 2 * 1024 ** 3;
+
+export const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+/** `/w/paper.btrn` → `/w/paper.btrn-data` — where beside-mode data lives. */
+export const dataFolderFor = (bundlePath) => `${bundlePath}-data`;
+
+/** A data path the bundle may carry: relative, safe, a file (not a folder). */
+export function safeDataPath(rel) {
+  const r = String(rel ?? "").replace(/\\/g, "/");
+  return safeEntryName(r) && !r.endsWith("/") && r.length <= 512;
+}
+
+/**
+ * Build a .btrn.
+ *
+ * @param {object} parts
+ * @param {string} parts.source        the document's text
+ * @param {string} parts.sourceName    its name inside, e.g. "paper.qmd"
+ * @param {string} [parts.title]
+ * @param {string|null} [parts.results]   the results record, JSON text (figures external)
+ * @param {Array<{name:string, data:Buffer, mime?:string}>} [parts.figures]  results/figures/<name>
+ * @param {Array<{path:string, bytes:Buffer}>} [parts.data]  files the code reads, by relative path
+ * @param {string} [parts.app]         the app version that wrote it
+ * @param {Date} [parts.created]
+ * @param {number} [parts.insideMax]   DATA_INSIDE_MAX unless a test says otherwise
+ * @param {string} [parts.bundleName]  the .btrn's own file name, for the beside folder's name
+ * @returns {{zip:Buffer, manifest:object, beside:Array<{path:string, bytes:Buffer}>}}
+ *   `beside` is the data to write in <bundle>-data/ when it did not fit inside
+ */
+export function buildBundle(parts) {
+  const {
+    source, sourceName, title = "", results = null, figures = [],
+    data = [], app = "", created = new Date(), insideMax = DATA_INSIDE_MAX, bundleName = "",
+  } = parts || {};
+  if (typeof source !== "string") throw fail("bundle_input", "a bundle needs the document's source");
+  if (!/^[^/\\]+\.(qmd|Rmd|rmd|md)$/.test(String(sourceName || ""))) {
+    throw fail("bundle_input", `the document inside must be a .qmd, .Rmd or .md file name, not ${JSON.stringify(sourceName)}`);
+  }
+  const files = [];
+  const seen = new Set();
+  const add = (name, bytes, compress = true) => {
+    if (seen.has(name)) throw fail("bundle_input", `${name} twice`);
+    seen.add(name);
+    files.push({ name, data: bytes, compress });
+  };
+  add(sourceName, Buffer.from(source, "utf8"));
+  if (results != null) {
+    add("results/results.json", Buffer.from(String(results), "utf8"));
+    for (const f of figures || []) {
+      if (!safeEntryName(`results/figures/${f.name}`) || f.name.includes("/")) throw fail("bundle_input", `bad figure name ${JSON.stringify(f.name)}`);
+      add(`results/figures/${f.name}`, f.data, false);
+    }
+  }
+  const dataFiles = (data || []).map((d) => {   // each: {path, bytes, kind?}
+    const rel = String(d.path).replace(/\\/g, "/");
+    if (!safeDataPath(rel)) throw fail("bundle_bad_path", `a data path must be relative and stay inside the document's folder: ${JSON.stringify(d.path)}`);
+    return { path: rel, bytes: d.bytes, size: d.bytes.length, sha256: sha256(d.bytes), kind: d.kind || "data" };
+  });
+
+  const manifestFor = (mode, dataEntries) => ({
+    format: BUNDLE_FORMAT, version: BUNDLE_VERSION, app, created: created.toISOString(), title,
+    source: sourceName,
+    entries: dataEntries.concat(files).map((f) => ({ name: f.name, size: f.data.length, sha256: sha256(f.data) })),
+    data: {
+      mode, ...(mode === "beside" ? { folder: `${path.basename(bundleName || sourceName.replace(/\.[^.]+$/, ".btrn"))}-data` } : {}),
+      files: dataFiles.map(({ path: p, size, sha256: h, kind }) => ({ path: p, size, sha256: h, kind })),
+    },
+  });
+  const zipWith = (manifest, dataEntries) => writeZip([
+    { name: "manifest.json", data: Buffer.from(JSON.stringify(manifest, null, 1), "utf8") },
+    ...files, ...dataEntries,
+  ], { date: created });
+
+  // Inside first; measure what the data costs compressed, and move it beside
+  // only when it passes the cap.
+  const inside = dataFiles.map((d) => ({ name: `data/${d.path}`, data: d.bytes, compress: true }));
+  let zip = zipWith(manifestFor(dataFiles.length ? "inside" : "none", inside), inside);
+  const dataBytes = listZip(zip).filter((e) => e.name.startsWith("data/")).reduce((a, e) => a + e.csize, 0);
+  if (dataBytes <= insideMax) {
+    return { zip, manifest: manifestFor(dataFiles.length ? "inside" : "none", inside), beside: [] };
+  }
+  const manifest = manifestFor("beside", []);
+  zip = zipWith(manifest, []);
+  return { zip, manifest, beside: dataFiles.map((d) => ({ path: d.path, bytes: d.bytes })), dataCompressed: dataBytes };
+}
+
+/**
+ * Read a .btrn: every part, VERIFIED. The manifest's SHA-256 for each entry is
+ * checked, and an entry the manifest does not list is refused — nothing is
+ * half-loaded.
+ *
+ * @param {Buffer} buf
+ * @returns {{manifest:object, source:string, sourceName:string, results:string|null,
+ *   figures:Map<string,Buffer>, data:Map<string,Buffer>}}
+ */
+export function readBundle(buf, { maxTotal = BUNDLE_READ_MAX } = {}) {
+  const all = readZip(buf, { maxTotal });
+  const rawManifest = all.get("manifest.json");
+  if (!rawManifest) throw fail("bundle_no_manifest", "not a Beatrina document (no manifest.json)");
+  let manifest;
+  try { manifest = JSON.parse(rawManifest.toString("utf8")); } catch { throw fail("bundle_bad_manifest", "manifest.json is not JSON"); }
+  if (manifest.format !== BUNDLE_FORMAT) throw fail("bundle_bad_manifest", `not a Beatrina document (format ${JSON.stringify(manifest.format)})`);
+  if (!(Number(manifest.version) >= 1)) throw fail("bundle_bad_manifest", "the manifest names no version");
+  if (Number(manifest.version) > BUNDLE_VERSION) {
+    throw fail("bundle_newer", `this document was written by a newer Beatrina (bundle version ${manifest.version}); update Beatrina to open it`);
+  }
+  const listed = new Map((manifest.entries || []).map((e) => [e.name, e]));
+  for (const [name, bytes] of all) {
+    if (name === "manifest.json") continue;
+    const want = listed.get(name);
+    if (!want) throw fail("bundle_unlisted", `${name} is in the archive but not in its manifest`);
+    if (want.size !== bytes.length || want.sha256 !== sha256(bytes)) throw fail("bundle_digest", `${name} does not match its manifest — the document is damaged`);
+  }
+  for (const name of listed.keys()) if (!all.has(name)) throw fail("bundle_missing", `the manifest lists ${name}, which is not in the archive`);
+  const sourceName = String(manifest.source || "");
+  if (!all.has(sourceName)) throw fail("bundle_missing", "the document itself is missing");
+  const figures = new Map();
+  const data = new Map();
+  for (const [name, bytes] of all) {
+    if (name.startsWith("results/figures/")) figures.set(name.slice("results/figures/".length), bytes);
+    else if (name.startsWith("data/")) data.set(name.slice("data/".length), bytes);
+  }
+  return {
+    manifest, sourceName, source: all.get(sourceName).toString("utf8"),
+    results: all.has("results/results.json") ? all.get("results/results.json").toString("utf8") : null,
+    figures, data,
+  };
+}
+
+/**
+ * What opening a bundle would do to each data file, pure: compare the
+ * manifest's digest with the file at the document's folder.
+ *
+ * @param {object} manifest
+ * @param {(rel:string) => (Buffer|null)} readLocal  the file beside the document, or null
+ * @returns {Array<{path:string, size:number, kind:string, state:'absent'|'same'|'differs'}>}
+ */
+export function dataPlan(manifest, readLocal) {
+  return ((manifest && manifest.data && manifest.data.files) || []).map((f) => {
+    const local = readLocal(f.path);
+    const state = !local ? "absent" : sha256(local) === f.sha256 ? "same" : "differs";
+    return { path: f.path, size: f.size, kind: f.kind || "data", state };
+  });
+}
+
+/** `paper.btrn` → `paper.qmd` — the name the document takes inside. */
+export function innerNameFor(bundlePath, format = "qmd") {
+  const stem = path.basename(String(bundlePath || "document")).replace(/\.btrn$/i, "") || "document";
+  const ext = { qmd: "qmd", rmd: "Rmd", md: "md" }[String(format).toLowerCase()] || "qmd";
+  return `${stem}.${ext}`;
+}
+
+export default { buildBundle, readBundle, dataPlan, innerNameFor, dataFolderFor, safeDataPath, sha256 };

package/host/deployment.mjs

@@ -13,6 +13,8 @@
 // client is not a browser and therefore is this same OS user; anywhere the port
 // is reachable by someone else the same header proves nothing, so it is refused.
 
+import { envReader } from "./env-names.mjs";
+
 export const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "[::1]", "localhost"];
 
 /** Split a comma/space-separated environment value into trimmed, non-empty parts. */
@@ -45,8 +47,8 @@ export function isLoopbackBind(bind) {
  *   `errors` is EMPTY when the posture is safe to serve. A non-empty `errors`
  *   must abort startup; it is never a warning.
  */
-export function carmarDeployment(port, env = envFromProcess()) {
-  let bind = env("CARMAR_BIND", "127.0.0.1").trim();
+export function beatrinaDeployment(port, env = envFromProcess()) {
+  let bind = env("BEATRINA_BIND", "127.0.0.1").trim();
   if (!bind) bind = "127.0.0.1";
   const loopback = isLoopbackBind(bind);
 
@@ -54,9 +56,9 @@ export function carmarDeployment(port, env = envFromProcess()) {
   // the same-origin case. Off loopback the server is behind a proxy, so its own
   // page arrives with the PROXY's origin — which the operator must name.
   const selfOrigins = [`http://${bind}:${port}`, `http://127.0.0.1:${port}`, `http://localhost:${port}`];
-  const origins = unique([...selfOrigins, ...splitList(env("CARMAR_ORIGINS", ""))]);
+  const origins = unique([...selfOrigins, ...splitList(env("BEATRINA_ORIGINS", ""))]);
 
-  let hostsEnv = splitList(env("CARMAR_HOSTS", ""));
+  let hostsEnv = splitList(env("BEATRINA_HOSTS", ""));
   const defaultHosts = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
   // A configured host may or may not carry a port. Accept both spellings so an
   // operator writing `stats.example.edu` is not silently refused behind a proxy
@@ -68,31 +70,31 @@ export function carmarDeployment(port, env = envFromProcess()) {
   // allowing an Origin-less client. Binding off loopback breaks it, but so does
   // a shared multi-user host or a container whose 127.0.0.1 is forwarded out,
   // so the posture is declarable in its own right.
-  const requireOrigin = env("CARMAR_REQUIRE_ORIGIN", "") === "1" || !loopback;
+  const requireOrigin = env("BEATRINA_REQUIRE_ORIGIN", "") === "1" || !loopback;
 
-  const trustProxy = env("CARMAR_TRUST_PROXY", "") === "1";
-  const userHeader = env("CARMAR_USER_HEADER", "X-Forwarded-User").trim();
-  const proxyAddrs = splitList(env("CARMAR_TRUSTED_PROXY", "127.0.0.1 ::1"));
-  const allowOpen = env("CARMAR_ALLOW_UNAUTHENTICATED", "") === "1";
+  const trustProxy = env("BEATRINA_TRUST_PROXY", "") === "1";
+  const userHeader = env("BEATRINA_USER_HEADER", "X-Forwarded-User").trim();
+  const proxyAddrs = splitList(env("BEATRINA_TRUSTED_PROXY", "127.0.0.1 ::1"));
+  const allowOpen = env("BEATRINA_ALLOW_UNAUTHENTICATED", "") === "1";
 
   const errors = [];
   if (!loopback) {
     if (!hostsEnv.length) {
-      errors.push(`CARMAR_BIND is ${bind} but CARMAR_HOSTS is unset. Off loopback the `
+      errors.push(`BEATRINA_BIND is ${bind} but BEATRINA_HOSTS is unset. Off loopback the `
         + "Host allow-list is the only defence against DNS rebinding, so it must "
-        + "name the hostname readers will use (e.g. CARMAR_HOSTS=stats.example.edu).");
+        + "name the hostname readers will use (e.g. BEATRINA_HOSTS=stats.example.edu).");
     }
     if (!trustProxy && !allowOpen) {
-      errors.push(`CARMAR_BIND is ${bind} with no authentication in front of it. Put `
+      errors.push(`BEATRINA_BIND is ${bind} with no authentication in front of it. Put `
         + "Beatrina behind a reverse proxy that authenticates and set "
-        + "CARMAR_TRUST_PROXY=1, or set CARMAR_ALLOW_UNAUTHENTICATED=1 to serve code "
+        + "BEATRINA_TRUST_PROXY=1, or set BEATRINA_ALLOW_UNAUTHENTICATED=1 to serve code "
         + "execution to everyone who can reach this port. See docs/server.md.");
     }
     if (trustProxy && !userHeader) {
-      errors.push("CARMAR_TRUST_PROXY=1 requires a non-empty CARMAR_USER_HEADER.");
+      errors.push("BEATRINA_TRUST_PROXY=1 requires a non-empty BEATRINA_USER_HEADER.");
     }
     if (trustProxy && !proxyAddrs.length) {
-      errors.push("CARMAR_TRUST_PROXY=1 requires CARMAR_TRUSTED_PROXY to name the proxy's address.");
+      errors.push("BEATRINA_TRUST_PROXY=1 requires BEATRINA_TRUSTED_PROXY to name the proxy's address.");
     }
   }
 
@@ -127,7 +129,7 @@ export function carmarDeployment(port, env = envFromProcess()) {
  *
  * @param {{REMOTE_ADDR?: string} & Record<string, string>} req a Rook-shaped
  *   request: `REMOTE_ADDR` plus `HTTP_*` header keys
- * @param {ReturnType<typeof carmarDeployment>} deployment
+ * @param {ReturnType<typeof beatrinaDeployment>} deployment
  * @returns {string}
  */
 export function proxyUser(req, deployment) {
@@ -150,9 +152,14 @@ export function rookOf(req) {
   return out;
 }
 
-/** A getter with `Sys.getenv`'s signature over `process.env`. */
+/**
+ * A getter with `Sys.getenv`'s signature over `process.env` — dual-read: a
+ * `CARMAR_*` name asked for here is also answered by its `BEATRINA_*` spelling
+ * (host/env-names.mjs), so the call sites above keep the vocabulary the
+ * deployment vectors in test/host-deployment.test.mjs use.
+ */
 export function envFromProcess(source = process.env) {
-  return (name, unset = "") => (source[name] == null ? unset : String(source[name]));
+  return envReader(source);
 }
 
 function unique(list) {