Build the DoE region reader + automated R/LaTeX report pipeline

Closes the "still open" reader-tool note from §XXXV.10: scripts/
extract_doe_region.py spools DOE-PERSIST-TRIAL's on-disk binary ring off
disk/artemis.img into a CSV -- direct file read by default, or via a real
loop device (--loop, losetup) per the literal request. Independent
Python reimplementation of doe_region.c's own ring-walk, verified
against a live 3-record write/read round trip.

analyse_multiuser_doe.R (house style, ggplot2/svglite) and
multiuser_doe_report.tex (same preamble convention as
bare_metal_doe_report.tex) auto-discover whatever data exists and
degrade gracefully to a placeholder when a campaign has 0 trials so far
-- the whole point being this can be rebuilt at any point during a
multi-day campaign, including mid-run. build_multiuser_doe_report.sh
chains extraction -> R -> svg_to_pdf.py -> pdflatex into one command.

Found and fixed a real bug while verifying: the R script's SCRIPT_DIR
detection silently wrote charts/tables/report output to the repo root
instead of the analysis directory when invoked from a different cwd --
switched to the robust commandArgs() "--file=" idiom. Verified live both
branches (0 trials and a real 3-record write), reverted synthetic test
data and incidental svg_to_pdf.py churn on ~85 unrelated committed
figures before committing. FABRIC-3.md §XXXV.11 has the full account.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BWpNjdwPtFLuVLaAq44L9K

experiments/bare_metal/analysis/report/multiuser_doe_report.tex

@@ -0,0 +1,148 @@
+\documentclass[10pt,a4paper]{article}
+
+%% ── Packages ──────────────────────────────────────────────────────────────────
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage[margin=2.5cm]{geometry}
+\usepackage{graphicx}
+\usepackage{subcaption}
+\usepackage{booktabs}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{xcolor}
+\usepackage{microtype}
+\usepackage{parskip}
+\usepackage{enumitem}
+\usepackage[hidelinks,colorlinks=true,linkcolor=black,citecolor=black,urlcolor=blue]{hyperref}
+\usepackage{lmodern}
+
+%% ── Colour palette (matches bare_metal_doe_report.tex) ─────────────────────────
+\definecolor{sfblue}{RGB}{31,119,180}
+\definecolor{sforange}{RGB}{255,127,14}
+\definecolor{sfgreen}{RGB}{44,160,44}
+\definecolor{sfgray}{RGB}{80,80,80}
+
+%% ── Figure path ───────────────────────────────────────────────────────────────
+\graphicspath{{figures/}}
+
+%% ── Title metadata ────────────────────────────────────────────────────────────
+\title{%
+  \textbf{LithosAnanke Multiuser/Multitasking Design of Experiments}\\[0.4em]
+  \large Concurrent Worker VM Load Across Three Instruction-Set Architectures
+}
+\author{%
+  R.\,A. James (Captain Bob)\\[0.2em]
+  \small StarForth Project \quad\texttt{robert.allan.james@gmail.com}
+}
+\date{%
+  Generated automatically by \texttt{scripts/build\_multiuser\_doe\_report.sh}\\[0.2em]
+  \textnormal{(Patent Pending --- Provisional Filed December 2025)}
+}
+
+%% ═════════════════════════════════════════════════════════════════════════════
+\begin{document}
+
+\maketitle
+\thispagestyle{empty}
+
+%% ── Abstract ──────────────────────────────────────────────────────────────────
+\begin{abstract}
+\noindent
+This report analyses the multiuser/multitasking Design of Experiments
+(FABRIC-3.md \S{}XXXIII/\S{}XXXV): a 6-cell factorial over concurrency level
+(2, 4, or 8 simultaneously live worker VMs, each birthed and touched twice
+by the Mama VM Hera) crossed with workload mode (uniform -- every worker
+runs the same workload; heterogeneous -- worker $n$ runs workload
+$n \bmod 10$), run per instruction-set architecture with a fixed seed.
+Trial outcomes -- concurrency, mode, fail count, and trial-end fleet
+physics (cumulative preemptive switch count, fleet heat conservation) --
+persist to a dedicated block-backed region on \texttt{disk/artemis.img}
+(\texttt{DOE-PERSIST-TRIAL}, \S{}XXXV.10) rather than depending on a live
+serial-log tail, so this report can be rebuilt at any point during a
+multi-day campaign, including while it is still running, from whatever
+trials have completed so far.
+\end{abstract}
+
+\section{Current campaign status}
+
+\input{sections/multiuser_summary_autogen.tex}
+
+\IfFileExists{figures/multiuser_placeholder.pdf}{%
+  \begin{figure}[h]
+    \centering
+    \includegraphics[width=0.6\textwidth]{multiuser_placeholder.pdf}
+  \end{figure}
+}{}
+
+\IfFileExists{figures/multiuser_fail_rate.pdf}{%
+\section{Fail rate by concurrency and workload mode}
+
+\begin{figure}[h]
+  \centering
+  \includegraphics[width=0.75\textwidth]{multiuser_fail_rate.pdf}
+  \caption{Fraction of trials with \texttt{fail\_count > 0}, by concurrency
+  level (2/4/8 workers) and workload mode. Labels give (failed/total) trials
+  per cell.}
+\end{figure}
+}{}
+
+\IfFileExists{figures/multiuser_switch_count.pdf}{%
+\clearpage
+\section{Preemptive switch load}
+
+\begin{figure}[h]
+  \centering
+  \includegraphics[width=0.75\textwidth]{multiuser_switch_count.pdf}
+  \caption{Distribution of cumulative Stage-3 preemptive switch count at
+  trial end, by concurrency level. Higher concurrency is expected to drive
+  more switch events per trial.}
+\end{figure}
+}{}
+
+\IfFileExists{figures/multiuser_fleet_k_sequence.pdf}{%
+\section{Fleet heat conservation across the trial sequence}
+
+\begin{figure}[h]
+  \centering
+  \includegraphics[width=\textwidth]{multiuser_fleet_k_sequence.pdf}
+  \caption{Trial-end fleet heat (\texttt{fleet\_k\_q48}, decoded from
+  Q48.16) across the shuffled trial run order. The dashed line marks the
+  conserved value (1.0); persistent drift away from it across the
+  sequence would indicate a real conservation violation rather than
+  per-trial noise.}
+\end{figure}
+}{}
+
+\IfFileExists{figures/multiuser_isa_panel.pdf}{%
+  \clearpage
+  \section{Per-ISA comparison}
+  \begin{figure}[h]
+    \centering
+    \includegraphics[width=\textwidth]{multiuser_isa_panel.pdf}
+    \caption{Fail rate by concurrency and mode, faceted by ISA -- populated
+    once more than one architecture's trials have been persisted.}
+  \end{figure}
+}{}
+
+\section{Methodology notes}
+
+\begin{itemize}
+  \item \textbf{Persistence, not a serial-log dependency.} Earlier attempts
+    at this campaign relied entirely on a live QEMU serial-log tail and
+    were lost when the process was interrupted (FABRIC-3.md \S{}XXXV.10).
+    Every number in this report comes from \texttt{disk/artemis.img}'s
+    own on-disk DoE region, read directly by
+    \texttt{scripts/extract\_doe\_region.py} with no live QEMU process
+    required.
+  \item \textbf{Rebuildable mid-campaign.} This report's build script
+    (\texttt{scripts/build\_multiuser\_doe\_report.sh}) can be re-run at
+    any point -- including while a multi-day campaign is still executing
+    -- and will reflect however many trials have completed at that moment.
+  \item \textbf{Trial-summary, not per-tick.} Unlike the per-tick
+    \texttt{HB-ON} serial stream (which remains the authoritative live
+    instrumentation during a run), the persisted region stores one summary
+    record per completed trial (\S{}XXXV.4) -- sized to comfortably fit
+    the device budget for the full campaign, not a raw tick mirror.
+\end{itemize}
+
+\end{document}

experiments/bare_metal/analysis/report/sections/multiuser_summary_autogen.tex

@@ -0,0 +1,4 @@
+% Auto-generated by analyse_multiuser_doe.R -- do not edit by hand.
+No trial data has been persisted to the DoE region yet. This section
+will populate automatically the next time this report is built after
+the campaign has produced at least one completed trial.