@mcmcjs/stan 0.1.0

package/dist/index.js

@@ -0,0 +1,976 @@
+// src/compile.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { dirname, isAbsolute, join as join2 } from "path";
+import { createRunner as createRunner3 } from "@mcmcjs/engine";
+
+// src/environment.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { basename, join } from "path";
+import { createRunner } from "@mcmcjs/engine";
+import { createRunner as createRunner2 } from "@mcmcjs/engine";
+import { DEFAULT_CMDSTAN_CHANNEL } from "@mcmcjs/core";
+var defaultRunner = createRunner();
+var INSTALLED_CMDSTAN_CHANNEL = DEFAULT_CMDSTAN_CHANNEL;
+var PINNED_CMDSTAN_VERSION = "2.39.0";
+function managedStanRoot() {
+  const home = process.env.HOME || homedir();
+  const dataHome = process.env.XDG_DATA_HOME || join(home, ".local", "share");
+  return join(dataHome, "mcmcjs", "stan");
+}
+function isCmdStanHome(dir) {
+  return existsSync(join(dir, "makefile")) && existsSync(join(dir, "bin", "stanc"));
+}
+function versionFromDirName(dir) {
+  return basename(dir).match(/^cmdstan-(\d+\.\d+\.\d+(?:-rc\d+)?)$/)?.[1];
+}
+function versionFromMakefile(home) {
+  try {
+    const makefile = readFileSync(join(home, "makefile"), "utf8");
+    return makefile.match(/CMDSTAN_VERSION\s*:?=\s*(\S+)/)?.[1];
+  } catch {
+    return void 0;
+  }
+}
+function installAt(home) {
+  if (!isCmdStanHome(home)) return void 0;
+  const version = versionFromDirName(home) ?? versionFromMakefile(home);
+  return version ? { version, home } : void 0;
+}
+function scanRoot(root) {
+  let entries;
+  try {
+    entries = readdirSync(root);
+  } catch {
+    return [];
+  }
+  const installs = [];
+  for (const name of entries) {
+    if (!name.startsWith("cmdstan-")) continue;
+    const install = installAt(join(root, name));
+    if (install) installs.push(install);
+  }
+  return installs;
+}
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, rc] = v.split("-rc");
+    const nums = (core ?? "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+    return { nums, rc: rc === void 0 ? Number.POSITIVE_INFINITY : Number.parseInt(rc, 10) || 0 };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < Math.max(pa.nums.length, pb.nums.length); i++) {
+    const d = (pa.nums[i] ?? 0) - (pb.nums[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  if (pa.rc === pb.rc) return 0;
+  return pa.rc < pb.rc ? -1 : 1;
+}
+function listCmdStanInstalls() {
+  const explicit = process.env.MCMCJS_CMDSTAN || process.env.CMDSTAN;
+  if (explicit) {
+    const install = installAt(explicit);
+    if (!install) {
+      throw new Error(
+        `MCMCJS_CMDSTAN/CMDSTAN points at ${explicit}, which is not a CmdStan directory (expected a makefile and bin/stanc); unset it or point it at a CmdStan home.`
+      );
+    }
+    return [install];
+  }
+  const home = process.env.HOME || homedir();
+  const installs = [...scanRoot(managedStanRoot()), ...scanRoot(join(home, ".cmdstan"))];
+  return installs.sort((a, b) => compareVersions(b.version, a.version));
+}
+function resolveCmdStan(requested = INSTALLED_CMDSTAN_CHANNEL) {
+  const installs = listCmdStanInstalls();
+  if (requested === INSTALLED_CMDSTAN_CHANNEL) {
+    const newest = installs[0];
+    if (newest) return newest;
+    throw new Error(
+      "CmdStan not found. Run `mcmc setup --engine stan`, or point MCMCJS_CMDSTAN at a CmdStan directory."
+    );
+  }
+  const match = installs.find((i) => i.version === requested);
+  if (match) return match;
+  throw new Error(
+    `CmdStan ${requested} not found. Run \`mcmc setup --engine stan --stan-version ${requested}\`, or point MCMCJS_CMDSTAN at a CmdStan directory.`
+  );
+}
+async function detect(command, args, parseVersion, runner) {
+  try {
+    const version = parseVersion(await runner(command, args));
+    if (version) return { found: true, version, path: command };
+  } catch {
+  }
+  return { found: false };
+}
+var versionNumber = (stdout) => stdout.match(/(\d+\.\d+(?:\.\d+)?)/)?.[1];
+function detectMake(runner = defaultRunner) {
+  return detect("make", ["--version"], versionNumber, runner);
+}
+async function detectCxx(runner = defaultRunner) {
+  for (const command of ["g++", "clang++"]) {
+    const info = await detect(command, ["--version"], versionNumber, runner);
+    if (info.found) return info;
+  }
+  return { found: false };
+}
+async function detectStanc(install, runner = defaultRunner) {
+  if (!install) return { found: false };
+  const stanc = join(install.home, "bin", "stanc");
+  return detect(stanc, ["--version"], versionNumber, runner);
+}
+
+// src/compile.ts
+function cacheKeySource(source, modelDir, depth = 4) {
+  if (depth === 0) return source;
+  const parts = [source];
+  for (const match of source.matchAll(/^\s*#include\s+[<"']?([^>"'\s]+)[>"']?/gm)) {
+    const file = match[1];
+    if (!file) continue;
+    try {
+      const included = readFileSync2(isAbsolute(file) ? file : join2(modelDir, file), "utf8");
+      parts.push(cacheKeySource(included, modelDir, depth - 1));
+    } catch {
+    }
+  }
+  return parts.join("\n");
+}
+function modelCacheDir(source, version, cacheRoot) {
+  const key = createHash("sha256").update(`${version}
+${source}`).digest("hex").slice(0, 16);
+  return join2(cacheRoot ?? join2(managedStanRoot(), "models"), key);
+}
+async function compileModel(install, modelPath, options = {}) {
+  const { runner = createRunner3(10 * 6e4), cacheRoot } = options;
+  const source = readFileSync2(modelPath, "utf8");
+  const modelDir = dirname(modelPath);
+  const dir = modelCacheDir(cacheKeySource(source, modelDir), install.version, cacheRoot);
+  const binaryPath = join2(dir, "model");
+  const okPath = join2(dir, ".ok");
+  if (existsSync2(okPath) && existsSync2(binaryPath)) return { binaryPath, cached: true };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join2(dir, "model.stan"), source);
+  await runner("make", ["-C", install.home, `STANCFLAGS=--include-paths=${modelDir}`, binaryPath]);
+  if (!existsSync2(binaryPath)) {
+    throw new Error("make reported success but produced no model executable");
+  }
+  writeFileSync(okPath, "");
+  return { binaryPath, cached: false };
+}
+
+// src/csv.ts
+import { closeSync, openSync, readSync } from "fs";
+import { fromStanName } from "@mcmcjs/core";
+var STAT_RENAME = {
+  lp__: "lp",
+  energy__: "energy",
+  divergent__: "diverging",
+  treedepth__: "tree_depth",
+  n_leapfrog__: "n_steps",
+  accept_stat__: "acceptance_rate",
+  stepsize__: "step_size"
+};
+function columnToLeaf(column) {
+  if (column.endsWith("__")) return STAT_RENAME[column] ?? null;
+  return fromStanName(column);
+}
+function parseStanNumber(field) {
+  const value = Number(field);
+  if (!Number.isNaN(value) || field === "nan") return value;
+  if (field === "inf" || field === "+inf") return Number.POSITIVE_INFINITY;
+  if (field === "-inf") return Number.NEGATIVE_INFINITY;
+  return value;
+}
+function createStanCsvTail(filePath, opts) {
+  let position = 0;
+  let pending = "";
+  let leaves;
+  let seq = 0;
+  const rows = [];
+  const emit = (count) => {
+    if (count === 0 || !leaves) return;
+    const draws = {};
+    for (let c = 0; c < leaves.length; c++) {
+      const leaf = leaves[c];
+      if (!leaf) continue;
+      const values = new Array(count);
+      for (let r = 0; r < count; r++) values[r] = rows[r]?.[c] ?? Number.NaN;
+      draws[leaf] = values;
+    }
+    rows.splice(0, count);
+    opts.onBatch({ chain: opts.chain, seq, iteration: null, draws });
+    seq += 1;
+  };
+  const consume = (line) => {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) return;
+    if (!leaves) {
+      leaves = trimmed.split(",").map(columnToLeaf);
+      return;
+    }
+    const fields = trimmed.split(",");
+    if (fields.length !== leaves.length) return;
+    rows.push(fields.map(parseStanNumber));
+    if (rows.length >= opts.batchSize) emit(opts.batchSize);
+  };
+  const poll = () => {
+    let fd;
+    try {
+      fd = openSync(filePath, "r");
+    } catch {
+      return;
+    }
+    try {
+      const chunk = Buffer.alloc(1 << 16);
+      for (; ; ) {
+        const read = readSync(fd, chunk, 0, chunk.length, position);
+        if (read <= 0) break;
+        position += read;
+        pending += chunk.toString("utf8", 0, read);
+        for (; ; ) {
+          const nl = pending.indexOf("\n");
+          if (nl < 0) break;
+          consume(pending.slice(0, nl));
+          pending = pending.slice(nl + 1);
+        }
+      }
+    } finally {
+      closeSync(fd);
+    }
+  };
+  return {
+    poll,
+    finish() {
+      poll();
+      emit(rows.length);
+    }
+  };
+}
+
+// src/doctor.ts
+async function runDoctor(runner) {
+  const install = listCmdStanInstalls()[0];
+  const cmdstan = install ? { found: true, version: install.version, path: install.home } : { found: false };
+  const [stanc, make, cxx] = await Promise.all([
+    detectStanc(install, runner),
+    detectMake(runner),
+    detectCxx(runner)
+  ]);
+  return {
+    cmdstan,
+    stanc,
+    make,
+    cxx,
+    install,
+    ready: cmdstan.found && make.found && cxx.found
+  };
+}
+
+// src/engine.ts
+var stanEngine = {
+  id: "stan",
+  displayName: "Stan (CmdStan)",
+  capabilities: { setup: true, versions: true, fit: true, predict: true },
+  async doctor(ctx) {
+    const report = await runDoctor(ctx.run);
+    const missingToolchain = !report.make.found || !report.cxx.found;
+    return {
+      engineId: "stan",
+      ready: report.ready,
+      tools: [
+        { name: "cmdstan", ...report.cmdstan },
+        { name: "stanc", ...report.stanc },
+        { name: "make", ...report.make },
+        { name: "c++", ...report.cxx }
+      ],
+      hint: report.ready ? void 0 : missingToolchain ? "Stan models compile with the system toolchain; install make and a C++ compiler (g++ or clang++), then run `mcmc setup --engine stan`." : "CmdStan not found. Run `mcmc setup --engine stan`."
+    };
+  }
+};
+
+// src/fit.ts
+import { createHash as createHash2 } from "crypto";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  mkdtempSync,
+  readFileSync as readFileSync3,
+  renameSync,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+import {
+  canonicalJson,
+  fromStanCSVFiles,
+  parseSamples,
+  RUN_RECORD_SCHEMA_VERSION,
+  toMCMCChainsJson
+} from "@mcmcjs/core";
+
+// src/runner.ts
+import { spawn } from "child_process";
+import { killTree } from "@mcmcjs/engine";
+var DETACHED = process.platform !== "win32";
+var STDERR_LIMIT = 1 << 22;
+function createStanSpawn(defaultTimeoutMs = 30 * 6e4) {
+  return (command, args, opts = {}) => new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: DETACHED
+    });
+    let stderr = "";
+    let stdoutPending = "";
+    let cancelled = false;
+    let settled = false;
+    const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs;
+    const timer = setTimeout(() => {
+      stderr += "process timed out and was killed\n";
+      killTree(child);
+    }, timeoutMs);
+    timer.unref?.();
+    const onAbort = () => {
+      cancelled = true;
+      killTree(child);
+    };
+    if (opts.signal) {
+      if (opts.signal.aborted) onAbort();
+      else opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    child.stdout?.on("data", (data) => {
+      stdoutPending += data.toString("utf8");
+      for (; ; ) {
+        const nl = stdoutPending.indexOf("\n");
+        if (nl < 0) break;
+        opts.onStdoutLine?.(stdoutPending.slice(0, nl));
+        stdoutPending = stdoutPending.slice(nl + 1);
+      }
+    });
+    child.stderr?.on("data", (data) => {
+      if (stderr.length < STDERR_LIMIT) stderr += data.toString("utf8");
+    });
+    const settle = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      opts.signal?.removeEventListener("abort", onAbort);
+      if (stdoutPending.length > 0) opts.onStdoutLine?.(stdoutPending);
+      resolve({ code, stderr, cancelled: cancelled || void 0 });
+    };
+    child.on("error", (error) => {
+      stderr = stderr || error.message;
+      settle(1);
+    });
+    child.on("close", (code) => settle(code ?? 1));
+  });
+}
+function parseIterationLine(line) {
+  const match = line.match(/Iteration:\s*(\d+)\s*\/\s*(\d+)\s*\[\s*\d+%\]\s*\((Warmup|Sampling)\)/);
+  if (!match) return null;
+  return {
+    iteration: Number.parseInt(match[1] ?? "0", 10),
+    total: Number.parseInt(match[2] ?? "0", 10),
+    warmup: match[3] === "Warmup"
+  };
+}
+
+// src/fit.ts
+function sha256(text) {
+  return createHash2("sha256").update(text).digest("hex");
+}
+function tmpParent() {
+  const uid = typeof process.getuid === "function" ? `-${process.getuid()}` : "";
+  return join3(tmpdir(), `mcmcjs${uid}`);
+}
+function chainArgs(spec, chain1, dataPath, csvPath) {
+  const s = spec.sampler;
+  const total = s.draws + s.warmup;
+  const refresh = Math.max(1, Math.floor(total / 100));
+  return [
+    "sample",
+    `num_samples=${s.draws}`,
+    `num_warmup=${s.warmup}`,
+    "adapt",
+    `delta=${s.adapt_delta}`,
+    "data",
+    `file=${dataPath}`,
+    "random",
+    `seed=${spec.seed}`,
+    `id=${chain1}`,
+    "output",
+    `file=${csvPath}`,
+    `refresh=${refresh}`
+  ];
+}
+function errorTail(stderr) {
+  const lines = stderr.trim().split("\n").map((l) => l.trim()).filter(Boolean);
+  return lines.at(-1);
+}
+async function runFit(spec, install, io) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const start = performance.now();
+  const runtimeRequested = spec.backend.version;
+  const fail = (stage, error) => ({
+    status: "error",
+    runtimeRequested,
+    elapsedMs: Math.round(performance.now() - start),
+    stage,
+    error
+  });
+  if (io.signal?.aborted) {
+    return { status: "cancelled", runtimeRequested, elapsedMs: 0 };
+  }
+  let binaryPath;
+  try {
+    ({ binaryPath } = await compileModel(install, spec.modelPath, io.compile));
+  } catch (error) {
+    return fail("compile", error.message);
+  }
+  if (io.signal?.aborted) {
+    return {
+      status: "cancelled",
+      runtimeRequested,
+      elapsedMs: Math.round(performance.now() - start)
+    };
+  }
+  const ownTmp = io.tmpDir === void 0;
+  let tmp;
+  if (io.tmpDir === void 0) {
+    mkdirSync2(tmpParent(), { recursive: true });
+    tmp = mkdtempSync(join3(tmpParent(), "stan-fit-"));
+  } else {
+    tmp = io.tmpDir;
+  }
+  try {
+    const dataPath = join3(tmp, "data.json");
+    writeFileSync2(dataPath, JSON.stringify(spec.data));
+    const chains = spec.sampler.chains;
+    const spawn2 = io.spawn ?? createStanSpawn();
+    const csvPaths = Array.from({ length: chains }, (_, i) => join3(tmp, `chain_${i + 1}.csv`));
+    const tails = io.onDraws ? csvPaths.map(
+      (path, i) => createStanCsvTail(path, {
+        chain: i,
+        batchSize: io.drawBatchSize ?? 25,
+        onBatch: io.onDraws
+      })
+    ) : [];
+    const pollTimer = tails.length > 0 ? setInterval(() => {
+      for (const tail of tails) tail.poll();
+    }, 150) : void 0;
+    pollTimer?.unref?.();
+    let results;
+    try {
+      results = await Promise.all(
+        csvPaths.map((csvPath, i) => {
+          const onProgress = io.onProgress;
+          return spawn2(binaryPath, chainArgs(spec, i + 1, dataPath, csvPath), {
+            signal: io.signal,
+            onStdoutLine: onProgress ? (line) => {
+              const p = parseIterationLine(line);
+              if (!p) return;
+              onProgress({
+                chain: i + 1,
+                of: chains,
+                fraction: p.total > 0 ? p.iteration / p.total : 0,
+                done: p.iteration === p.total
+              });
+            } : void 0
+          });
+        })
+      );
+    } finally {
+      if (pollTimer) clearInterval(pollTimer);
+    }
+    for (const tail of tails) tail.finish();
+    const elapsedMs = Math.round(performance.now() - start);
+    if (io.signal?.aborted || results.some((r) => r.cancelled)) {
+      return { status: "cancelled", runtimeRequested, elapsedMs };
+    }
+    const failed = results.findIndex((r) => r.code !== 0);
+    if (failed >= 0) {
+      const r = results[failed];
+      return fail(
+        "sample",
+        `chain ${failed + 1} exited with code ${r?.code}${r && errorTail(r.stderr) ? `: ${errorTail(r.stderr)}` : ""}`
+      );
+    }
+    let samplesJson;
+    try {
+      const texts = csvPaths.map((path) => readFileSync3(path, "utf8"));
+      samplesJson = JSON.stringify(toMCMCChainsJson(fromStanCSVFiles(texts)));
+      parseSamples(samplesJson);
+    } catch (error) {
+      return fail("load_samples", `could not read CmdStan output: ${error.message}`);
+    }
+    try {
+      const partial = `${io.outPath}.tmp`;
+      writeFileSync2(partial, samplesJson);
+      renameSync(partial, io.outPath);
+    } catch (error) {
+      return fail("write", error.message);
+    }
+    const record = {
+      schema_version: RUN_RECORD_SCHEMA_VERSION,
+      spec_hash: spec.specHash,
+      seed: spec.seed,
+      backend: { id: spec.backend.id, runtime: spec.backend.runtime },
+      runtime: { requested: runtimeRequested, actual: install.version, path: install.home },
+      model_sha256: existsSync3(spec.modelPath) ? sha256(readFileSync3(spec.modelPath, "utf8")) : void 0,
+      data_sha256: io.dataSha256 ?? sha256(canonicalJson(spec.data)),
+      ...io.dataFile ? { data_file: io.dataFile } : {},
+      samples_file: io.outPath,
+      started_at: startedAt,
+      elapsed_ms: Math.round(performance.now() - start)
+    };
+    try {
+      writeFileSync2(
+        io.recordPath ?? `${io.outPath}.run.json`,
+        `${JSON.stringify(record, null, 2)}
+`
+      );
+    } catch (error) {
+      return fail("write", `could not write the run record: ${error.message}`);
+    }
+    return {
+      status: "ok",
+      samplesFile: io.outPath,
+      runtimeRequested,
+      runtimeActual: install.version,
+      elapsedMs: Math.round(performance.now() - start)
+    };
+  } finally {
+    if (ownTmp) rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// src/matrix.ts
+import { join as join4 } from "path";
+async function runMatrix(spec, versions, io) {
+  const entries = [];
+  for (const version of versions) {
+    let entry;
+    try {
+      const install = resolveCmdStan(version);
+      const result = await runFit({ ...spec, backend: { ...spec.backend, version } }, install, {
+        ...io.fit,
+        outPath: join4(io.outDir, `${version}.samples.json`),
+        dataFile: io.dataFile,
+        dataSha256: io.dataSha256,
+        signal: io.signal
+      });
+      entry = {
+        version,
+        status: result.status,
+        samplesFile: result.samplesFile,
+        runtimeActual: result.runtimeActual,
+        elapsedMs: result.elapsedMs,
+        stage: result.stage,
+        error: result.error
+      };
+    } catch (error) {
+      entry = { version, status: "error", elapsedMs: 0, error: error.message };
+    }
+    entries.push(entry);
+    if (entry.status === "cancelled") break;
+    if (entry.status === "error" && !io.keepGoing) break;
+  }
+  return {
+    entries,
+    ok: entries.length === versions.length && entries.every((e) => e.status === "ok")
+  };
+}
+
+// src/predict.ts
+import { createHash as createHash3 } from "crypto";
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  mkdtempSync as mkdtempSync2,
+  readFileSync as readFileSync4,
+  renameSync as renameSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join5 } from "path";
+import {
+  canonicalJson as canonicalJson2,
+  fromStanCSVFiles as fromStanCSVFiles2,
+  parseSamples as parseSamples2,
+  RUN_RECORD_SCHEMA_VERSION as RUN_RECORD_SCHEMA_VERSION2,
+  toMCMCChainsJson as toMCMCChainsJson2,
+  toStanName
+} from "@mcmcjs/core";
+function predictData(spec) {
+  if (!spec.predict) throw new Error("spec has no [predict] block");
+  return { ...spec.data, ...spec.predict.data ?? {} };
+}
+function fittedParamsCsv(samples, chain) {
+  const names = samples.variables;
+  const header = names.map(toStanName).join(",");
+  const columns = names.map((name) => samples.draws.get(name));
+  const start = chain * samples.nDraws;
+  const rows = [header];
+  for (let i = 0; i < samples.nDraws; i++) {
+    rows.push(columns.map((col) => stanCell(col[start + i] ?? Number.NaN)).join(","));
+  }
+  return `${rows.join("\n")}
+`;
+}
+function stanCell(value) {
+  if (Number.isFinite(value)) return String(value);
+  if (Number.isNaN(value)) return "nan";
+  return value > 0 ? "inf" : "-inf";
+}
+function matchesTarget(name, targets) {
+  return targets.some((t) => name === t || name.startsWith(`${t}[`));
+}
+function filterToTargets(all, targets) {
+  const draws = /* @__PURE__ */ new Map();
+  for (const name of all.variables) {
+    if (matchesTarget(name, targets)) {
+      draws.set(name, all.draws.get(name));
+    }
+  }
+  return {
+    variables: [...draws.keys()],
+    nChains: all.nChains,
+    nDraws: all.nDraws,
+    draws,
+    sampleStats: /* @__PURE__ */ new Map()
+  };
+}
+function baseNames(variables) {
+  return [...new Set(variables.map((v) => v.replace(/\[.*$/, "")))];
+}
+function sha2562(text) {
+  return createHash3("sha256").update(text).digest("hex");
+}
+function tmpParent2() {
+  const uid = typeof process.getuid === "function" ? `-${process.getuid()}` : "";
+  return join5(tmpdir2(), `mcmcjs${uid}`);
+}
+async function runPredict(spec, install, io) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const start = performance.now();
+  const runtimeRequested = spec.backend.version;
+  const elapsed = () => Math.round(performance.now() - start);
+  const fail = (stage, error) => ({
+    status: "error",
+    runtimeRequested,
+    elapsedMs: elapsed(),
+    stage,
+    error
+  });
+  const targets = spec.predict?.targets;
+  if (!targets || targets.length === 0) {
+    return fail("predict", "spec has no [predict] block");
+  }
+  if (io.signal?.aborted) {
+    return { status: "cancelled", runtimeRequested, elapsedMs: 0 };
+  }
+  let posterior;
+  try {
+    posterior = parseSamples2(readFileSync4(io.samplesPath, "utf8"));
+  } catch (error) {
+    return fail("load_samples", `posterior samples did not parse: ${error.message}`);
+  }
+  let binaryPath;
+  try {
+    ({ binaryPath } = await compileModel(install, spec.modelPath, io.compile));
+  } catch (error) {
+    return fail("compile", error.message);
+  }
+  const ownTmp = io.tmpDir === void 0;
+  let tmp;
+  if (io.tmpDir === void 0) {
+    mkdirSync3(tmpParent2(), { recursive: true });
+    tmp = mkdtempSync2(join5(tmpParent2(), "stan-predict-"));
+  } else {
+    tmp = io.tmpDir;
+  }
+  try {
+    const data = predictData(spec);
+    const dataPath = join5(tmp, "data.json");
+    writeFileSync3(dataPath, JSON.stringify(data));
+    const spawn2 = io.spawn ?? createStanSpawn();
+    const chains = posterior.nChains;
+    const results = await Promise.all(
+      Array.from({ length: chains }, (_, i) => {
+        const fittedPath = join5(tmp, `fitted_${i + 1}.csv`);
+        writeFileSync3(fittedPath, fittedParamsCsv(posterior, i));
+        return spawn2(
+          binaryPath,
+          [
+            "generate_quantities",
+            `fitted_params=${fittedPath}`,
+            "data",
+            `file=${dataPath}`,
+            "random",
+            `seed=${spec.seed}`,
+            `id=${i + 1}`,
+            "output",
+            `file=${join5(tmp, `gq_${i + 1}.csv`)}`
+          ],
+          { signal: io.signal }
+        );
+      })
+    );
+    if (io.signal?.aborted || results.some((r) => r.cancelled)) {
+      return { status: "cancelled", runtimeRequested, elapsedMs: elapsed() };
+    }
+    const failed = results.findIndex((r) => r.code !== 0);
+    if (failed >= 0) {
+      const stderr = results[failed]?.stderr ?? "";
+      if (/doesn't generate any quantities/i.test(stderr)) {
+        return fail(
+          "predict",
+          `the Stan model has no generated quantities block; add one that computes ${targets.join(", ")}`
+        );
+      }
+      const tail = stderr.trim().split("\n").filter(Boolean).at(-1);
+      return fail(
+        "predict",
+        `generate_quantities failed for chain ${failed + 1}${tail ? `: ${tail}` : ""}`
+      );
+    }
+    let predictive;
+    try {
+      const texts = Array.from(
+        { length: chains },
+        (_, i) => readFileSync4(join5(tmp, `gq_${i + 1}.csv`), "utf8")
+      );
+      predictive = filterToTargets(fromStanCSVFiles2(texts), targets);
+    } catch (error) {
+      return fail(
+        "load_samples",
+        `could not read generate_quantities output: ${error.message}`
+      );
+    }
+    if (predictive.variables.length === 0) {
+      const available = baseNames(fromStanCSVFilesNames(tmp, chains));
+      return fail(
+        "predict",
+        `no generated quantity matches targets ${targets.join(", ")}; the model generates: ${available.length > 0 ? available.join(", ") : "(nothing)"}`
+      );
+    }
+    try {
+      const json = JSON.stringify(toMCMCChainsJson2(predictive));
+      parseSamples2(json);
+      const partial = `${io.outPath}.tmp`;
+      writeFileSync3(partial, json);
+      renameSync2(partial, io.outPath);
+    } catch (error) {
+      return fail("write", error.message);
+    }
+    const record = {
+      schema_version: RUN_RECORD_SCHEMA_VERSION2,
+      spec_hash: spec.specHash,
+      seed: spec.seed,
+      backend: { id: spec.backend.id, runtime: spec.backend.runtime },
+      runtime: { requested: runtimeRequested, actual: install.version, path: install.home },
+      model_sha256: existsSync4(spec.modelPath) ? sha2562(readFileSync4(spec.modelPath, "utf8")) : void 0,
+      data_sha256: sha2562(canonicalJson2(data)),
+      posterior_samples: io.samplesPath,
+      posterior_samples_sha256: sha2562(readFileSync4(io.samplesPath, "utf8")),
+      samples_file: io.outPath,
+      started_at: startedAt,
+      elapsed_ms: elapsed()
+    };
+    try {
+      writeFileSync3(`${io.outPath}.run.json`, `${JSON.stringify(record, null, 2)}
+`);
+    } catch (error) {
+      return fail("write", `could not write the run record: ${error.message}`);
+    }
+    return {
+      status: "ok",
+      samplesFile: io.outPath,
+      runtimeRequested,
+      runtimeActual: install.version,
+      elapsedMs: elapsed()
+    };
+  } finally {
+    if (ownTmp) rmSync2(tmp, { recursive: true, force: true });
+  }
+}
+function fromStanCSVFilesNames(tmp, chains) {
+  try {
+    const texts = Array.from(
+      { length: chains },
+      (_, i) => readFileSync4(join5(tmp, `gq_${i + 1}.csv`), "utf8")
+    );
+    return [...fromStanCSVFiles2(texts).variables];
+  } catch {
+    return [];
+  }
+}
+
+// src/setup.ts
+import { existsSync as existsSync5 } from "fs";
+import { cpus } from "os";
+import { join as join6 } from "path";
+import { createRunner as createRunner4 } from "@mcmcjs/engine";
+function releaseUrl(version) {
+  return `https://github.com/stan-dev/cmdstan/releases/download/v${version}/cmdstan-${version}.tar.gz`;
+}
+function shq(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function managedCmdStanHome(version) {
+  return join6(managedStanRoot(), `cmdstan-${version}`);
+}
+function planSetup(report, platform, version = PINNED_CMDSTAN_VERSION) {
+  const steps = [];
+  if (!report.make.found || !report.cxx.found) {
+    const missing = [
+      ...report.make.found ? [] : ["make"],
+      ...report.cxx.found ? [] : ["a C++ compiler (g++ or clang++)"]
+    ].join(" and ");
+    steps.push({
+      tool: "toolchain",
+      label: `install ${missing} with your system package manager`,
+      command: null
+    });
+  }
+  if (report.cmdstan.found && report.cmdstan.version === version) return steps;
+  const home = managedCmdStanHome(version);
+  const posix = platform !== "win32";
+  if (!existsSync5(join6(home, "makefile"))) {
+    const root = shq(managedStanRoot());
+    const staging = shq(join6(managedStanRoot(), `.download-${version}`));
+    const finalHome = shq(home);
+    const extracted = shq(join6(managedStanRoot(), `.download-${version}`, `cmdstan-${version}`));
+    steps.push({
+      tool: "cmdstan",
+      label: `download CmdStan ${version}`,
+      command: posix ? {
+        command: "sh",
+        args: [
+          "-c",
+          `rm -rf ${staging} && mkdir -p ${staging} && curl -fsSL ${shq(releaseUrl(version))} | tar -xz -C ${staging} && rm -rf ${finalHome} && mv ${extracted} ${finalHome} && rm -rf ${staging} && mkdir -p ${root}`
+        ]
+      } : null
+    });
+  }
+  if (!existsSync5(join6(home, "bin", "stansummary"))) {
+    steps.push({
+      tool: "build",
+      label: `build CmdStan ${version} (one-time, a few minutes)`,
+      command: posix ? { command: "make", args: ["-C", home, "build", `-j${cpus().length}`] } : null
+    });
+  }
+  return steps;
+}
+function validateVersion(version) {
+  if (!/^\d+\.\d+\.\d+(-rc\d+)?$/.test(version)) {
+    throw new Error(
+      `invalid CmdStan version: "${version}" (expected e.g. ${PINNED_CMDSTAN_VERSION})`
+    );
+  }
+}
+async function runSetup(options = {}) {
+  const {
+    runner,
+    installer = createRunner4(30 * 6e4),
+    platform = process.platform,
+    dryRun = false,
+    version = PINNED_CMDSTAN_VERSION
+  } = options;
+  validateVersion(version);
+  const before = await runDoctor(runner);
+  const plan = planSetup(before, platform, version);
+  const strip = ({ install: _install, ...report }) => report;
+  if (plan.length === 0) return { ...strip(before), steps: [] };
+  if (dryRun) {
+    return {
+      ...strip(before),
+      steps: plan.map((step) => ({ ...step, status: step.command ? "skipped" : "unsupported" }))
+    };
+  }
+  const steps = [];
+  let failed = false;
+  for (const step of plan) {
+    if (!step.command) {
+      steps.push({ ...step, status: "unsupported" });
+      failed = failed || step.tool === "toolchain";
+      continue;
+    }
+    if (failed) {
+      steps.push({ ...step, status: "skipped" });
+      continue;
+    }
+    try {
+      await installer(step.command.command, step.command.args);
+      steps.push({ ...step, status: "ran" });
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      steps.push({ ...step, status: "failed", detail });
+      failed = true;
+    }
+  }
+  const after = await runDoctor(runner);
+  return { ...strip(after), steps };
+}
+
+// src/versions.ts
+import { rmSync as rmSync3 } from "fs";
+import { join as join7 } from "path";
+function listVersions() {
+  return listCmdStanInstalls().map((install, index) => ({
+    id: install.version,
+    version: install.version,
+    path: install.home,
+    isDefault: index === 0
+  }));
+}
+function addVersion(version, options = {}) {
+  return runSetup({ ...options, version });
+}
+function removeVersion(version) {
+  const install = listCmdStanInstalls().find((i) => i.version === version);
+  if (!install) {
+    throw new Error(`CmdStan ${version} is not installed`);
+  }
+  const managedHome = join7(managedStanRoot(), `cmdstan-${version}`);
+  if (install.home !== managedHome) {
+    throw new Error(
+      `CmdStan ${version} at ${install.home} is not managed by mcmcjs; remove it yourself if intended`
+    );
+  }
+  rmSync3(managedHome, { recursive: true, force: true });
+}
+export {
+  INSTALLED_CMDSTAN_CHANNEL,
+  PINNED_CMDSTAN_VERSION,
+  addVersion,
+  chainArgs,
+  columnToLeaf,
+  compileModel,
+  createStanCsvTail,
+  createStanSpawn,
+  fittedParamsCsv,
+  isCmdStanHome,
+  listCmdStanInstalls,
+  listVersions,
+  managedCmdStanHome,
+  managedStanRoot,
+  matchesTarget,
+  modelCacheDir,
+  parseIterationLine,
+  planSetup,
+  predictData,
+  removeVersion,
+  resolveCmdStan,
+  runDoctor,
+  runFit,
+  runMatrix,
+  runPredict,
+  runSetup,
+  stanEngine
+};
+//# sourceMappingURL=index.js.map