@danielsimonjr/mathts-workbook 0.1.8 → 0.2.0

package/dist/chunk-TS2WDJ7W.js

@@ -0,0 +1,1239 @@
+// src/fs-atomic.ts
+import { writeFileSync, renameSync, unlinkSync } from "fs";
+var counter = 0;
+function writeFileAtomic(file, content) {
+  const tmp = `${file}.${process.pid}.${counter++}.tmp`;
+  writeFileSync(tmp, content, { encoding: "utf-8", flag: "wx" });
+  try {
+    renameSync(tmp, file);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/yaml-safe.ts
+import { parse as parseYaml } from "yaml";
+var POLLUTION_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function parseYamlHardened(content) {
+  return parseYaml(content, { schema: "core", merge: false, logLevel: "silent" });
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function findPollutionKeys(value, seen = /* @__PURE__ */ new WeakSet(), found = []) {
+  if (!isPlainObject(value) && !Array.isArray(value)) return found;
+  if (seen.has(value)) return found;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) findPollutionKeys(item, seen, found);
+    return found;
+  }
+  for (const key of Object.getOwnPropertyNames(value)) {
+    if (POLLUTION_KEYS.has(key)) {
+      found.push(key);
+      continue;
+    }
+    findPollutionKeys(value[key], seen, found);
+  }
+  return found;
+}
+function assertNoPollution(value) {
+  const keys = findPollutionKeys(value);
+  if (keys.length > 0) {
+    throw new Error(`Disallowed key "${keys[0]}" (prototype pollution)`);
+  }
+}
+
+// src/graph.ts
+function buildDependencyGraph(cells) {
+  const nodes = /* @__PURE__ */ new Map();
+  for (const cell of cells) {
+    nodes.set(cell.id, {
+      id: cell.id,
+      dependencies: cell.dependsOn ?? [],
+      dependents: []
+    });
+  }
+  for (const cell of cells) {
+    for (const depId of cell.dependsOn ?? []) {
+      const depNode = nodes.get(depId);
+      if (depNode) {
+        depNode.dependents.push(cell.id);
+      }
+    }
+  }
+  const executionOrder = topologicalSort(nodes);
+  return { nodes, executionOrder };
+}
+function topologicalSort(nodes) {
+  const visited = /* @__PURE__ */ new Set();
+  const result = [];
+  function visit(id) {
+    if (visited.has(id)) return;
+    visited.add(id);
+    const node = nodes.get(id);
+    if (node) {
+      for (const depId of node.dependencies) {
+        visit(depId);
+      }
+    }
+    result.push(id);
+  }
+  for (const id of nodes.keys()) {
+    visit(id);
+  }
+  return result;
+}
+function getDependents(graph, cellId) {
+  const result = [];
+  const visited = /* @__PURE__ */ new Set();
+  function collect(id) {
+    const node = graph.nodes.get(id);
+    if (!node) return;
+    for (const depId of node.dependents) {
+      if (!visited.has(depId)) {
+        visited.add(depId);
+        result.push(depId);
+        collect(depId);
+      }
+    }
+  }
+  collect(cellId);
+  return result;
+}
+function getAncestors(graph, id) {
+  const result = /* @__PURE__ */ new Set();
+  function visit(nodeId) {
+    if (result.has(nodeId)) return;
+    const node = graph.nodes.get(nodeId);
+    if (!node) return;
+    result.add(nodeId);
+    for (const dep of node.dependencies) visit(dep);
+  }
+  visit(id);
+  return graph.executionOrder.filter((nodeId) => result.has(nodeId));
+}
+function toMermaid(graph) {
+  const lines = ["graph TD"];
+  for (const id of graph.nodes.keys()) {
+    lines.push(`  ${id}["${id}"]`);
+  }
+  for (const [id, node] of graph.nodes) {
+    for (const dep of node.dependencies) {
+      lines.push(`  ${dep} --> ${id}`);
+    }
+  }
+  return lines.join("\n");
+}
+function toDOT(graph) {
+  const lines = ["digraph deps {"];
+  for (const id of graph.nodes.keys()) {
+    lines.push(`  ${id} [label="${id}"];`);
+  }
+  for (const [id, node] of graph.nodes) {
+    for (const dep of node.dependencies) {
+      lines.push(`  ${dep} -> ${id};`);
+    }
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+function detectCycles(graph) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(id, path) {
+    if (stack.has(id)) {
+      const cycleStart = path.indexOf(id);
+      cycles.push(path.slice(cycleStart));
+      return true;
+    }
+    if (visited.has(id)) return false;
+    visited.add(id);
+    stack.add(id);
+    const node = graph.nodes.get(id);
+    if (node) {
+      for (const depId of node.dependencies) {
+        dfs(depId, [...path, id]);
+      }
+    }
+    stack.delete(id);
+    return false;
+  }
+  for (const id of graph.nodes.keys()) {
+    if (!visited.has(id)) {
+      dfs(id, []);
+    }
+  }
+  return cycles;
+}
+
+// src/parser.ts
+import { stringify as stringifyYaml } from "yaml";
+var CELL_TYPE_KEYS = [
+  "markdown",
+  "code",
+  "tensor",
+  "equation",
+  "visualization",
+  "data",
+  "test",
+  "export"
+];
+var RESERVED_CELL_KEYS = ["id", "depends_on", "language", "format", "output", "error"];
+var IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isValidIdentifier(id) {
+  return typeof id === "string" && IDENTIFIER_RE.test(id);
+}
+var SUPPORTED_CELL_TYPES = ["code", "markdown", "data", "test", "equation", "visualization"];
+var EXECUTION_MODES = ["reactive", "sequential", "manual"];
+function detectCellType(cell) {
+  for (const key of CELL_TYPE_KEYS) {
+    if (key in cell) {
+      return key;
+    }
+  }
+  return "code";
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toContent(raw) {
+  if (raw === null || raw === void 0) return "";
+  if (typeof raw === "string") return raw;
+  return stringifyYaml(raw).trim();
+}
+function normalizeRuntime(raw) {
+  const rt = isPlainObject2(raw) ? raw : {};
+  const runtime = {
+    engine: rt.engine === "custom" ? "custom" : "mathts",
+    execution: typeof rt.execution === "string" && EXECUTION_MODES.includes(rt.execution) ? rt.execution : "reactive"
+  };
+  if (typeof rt.timeout === "number") runtime.timeout = rt.timeout;
+  return runtime;
+}
+function mapCell(raw, index, errors) {
+  if (!isPlainObject2(raw)) {
+    errors.push(`Cell at index ${index}: must be a mapping`);
+    return { id: `#${index}`, type: "code", content: "" };
+  }
+  const rawId = raw.id;
+  let id;
+  if (rawId === void 0 || rawId === null) {
+    errors.push(`Cell at index ${index}: missing "id"`);
+    id = `#${index}`;
+  } else if (typeof rawId !== "string" || !IDENTIFIER_RE.test(rawId)) {
+    errors.push(
+      `Cell "${String(rawId)}": id must be a valid identifier ([A-Za-z_][A-Za-z0-9_]*)`
+    );
+    id = String(rawId);
+  } else {
+    id = rawId;
+  }
+  const presentTypeKeys = CELL_TYPE_KEYS.filter(
+    (k) => Object.prototype.hasOwnProperty.call(raw, k)
+  );
+  if (presentTypeKeys.length === 0) {
+    errors.push(
+      `Cell "${id}": no recognized type key (expected one of ${CELL_TYPE_KEYS.join(", ")})`
+    );
+  } else if (presentTypeKeys.length > 1) {
+    errors.push(`Cell "${id}": multiple type keys (${presentTypeKeys.join(", ")})`);
+  }
+  const type = presentTypeKeys[0] ?? "code";
+  const content = presentTypeKeys[0] ? toContent(raw[presentTypeKeys[0]]) : "";
+  if (presentTypeKeys[0] && !SUPPORTED_CELL_TYPES.includes(type)) {
+    errors.push(
+      `Cell "${id}": type '${type}' is reserved but not yet supported (supported: ${SUPPORTED_CELL_TYPES.join(", ")})`
+    );
+  }
+  let dependsOn;
+  if (raw.depends_on !== void 0) {
+    if (!Array.isArray(raw.depends_on)) {
+      errors.push(`Cell "${id}": depends_on must be a list`);
+    } else {
+      dependsOn = raw.depends_on.map((d) => String(d));
+    }
+  }
+  const metadata = {};
+  for (const key of Object.keys(raw)) {
+    if (RESERVED_CELL_KEYS.includes(key) || CELL_TYPE_KEYS.includes(key)) continue;
+    metadata[key] = raw[key];
+  }
+  const cell = { id, type, content };
+  if (dependsOn) cell.dependsOn = dependsOn;
+  if (Object.keys(metadata).length > 0) cell.metadata = metadata;
+  if (raw.output !== void 0) cell.output = raw.output;
+  if (raw.error !== void 0) cell.error = String(raw.error);
+  return cell;
+}
+function parseWorkbook(content) {
+  try {
+    if (!content.trim()) {
+      return { success: false, errors: ["Empty workbook content"] };
+    }
+    const errors = [];
+    const warnings = [];
+    const doc = parseYamlHardened(content);
+    if (!isPlainObject2(doc)) {
+      return { success: false, errors: ["Workbook must be a YAML mapping"] };
+    }
+    for (const key of findPollutionKeys(doc)) {
+      errors.push(`Disallowed key "${key}" (prototype pollution)`);
+    }
+    const metadata = isPlainObject2(doc.metadata) ? doc.metadata : {};
+    const workbook = {
+      version: doc.version != null ? String(doc.version) : "1.0",
+      metadata,
+      runtime: normalizeRuntime(doc.runtime),
+      cells: []
+    };
+    if (doc.cells === void 0) {
+      warnings.push("Workbook has no cells");
+    } else if (!Array.isArray(doc.cells)) {
+      errors.push('Workbook "cells" must be a list');
+    } else {
+      const idSet = /* @__PURE__ */ new Set();
+      const cells = doc.cells.map((raw, i) => {
+        const cell = mapCell(raw, i, errors);
+        if (IDENTIFIER_RE.test(cell.id)) {
+          if (idSet.has(cell.id)) {
+            errors.push(`Duplicate cell id: "${cell.id}"`);
+          } else {
+            idSet.add(cell.id);
+          }
+        }
+        return cell;
+      });
+      for (const cell of cells) {
+        for (const dep of cell.dependsOn ?? []) {
+          if (!idSet.has(dep)) {
+            errors.push(`Cell "${cell.id}": depends_on references unknown cell "${dep}"`);
+          }
+        }
+      }
+      workbook.cells = cells;
+    }
+    const success = errors.length === 0;
+    return {
+      success,
+      workbook: success ? workbook : void 0,
+      errors: errors.length > 0 ? errors : void 0,
+      warnings: warnings.length > 0 ? warnings : void 0
+    };
+  } catch (error) {
+    return {
+      success: false,
+      errors: [`Parse error: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+}
+function serializeCell(cell) {
+  const out = { [cell.type]: cell.content, id: cell.id };
+  if (cell.dependsOn && cell.dependsOn.length > 0) out.depends_on = cell.dependsOn;
+  if (cell.metadata) {
+    for (const [key, value] of Object.entries(cell.metadata)) {
+      if (CELL_TYPE_KEYS.includes(key) || RESERVED_CELL_KEYS.includes(key)) continue;
+      out[key] = value;
+    }
+  }
+  if (cell.output !== void 0) out.output = cell.output;
+  if (cell.error !== void 0) out.error = String(cell.error);
+  return out;
+}
+function serializeWorkbook(workbook) {
+  if (!workbook || !Array.isArray(workbook.cells)) {
+    throw new Error('serializeWorkbook: invalid workbook (missing "cells" array)');
+  }
+  const runtime = {
+    engine: workbook.runtime?.engine ?? "mathts",
+    execution: workbook.runtime?.execution ?? "reactive"
+  };
+  if (workbook.runtime?.timeout !== void 0) runtime.timeout = workbook.runtime.timeout;
+  const doc = {
+    version: String(workbook.version ?? "1.0"),
+    metadata: workbook.metadata ?? {},
+    runtime,
+    cells: workbook.cells.map(serializeCell)
+  };
+  return stringifyYaml(doc, { lineWidth: 0 });
+}
+function stripOutputs(workbook) {
+  return {
+    ...workbook,
+    cells: workbook.cells.map((cell) => ({
+      ...cell,
+      output: void 0,
+      error: void 0
+    }))
+  };
+}
+function importWorkbook(input) {
+  let obj;
+  try {
+    obj = parseYamlHardened(input);
+  } catch (error) {
+    return { success: false, errors: [`Invalid JSON/YAML: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return { success: false, errors: ['Input must be an object with a "cells" array'] };
+  }
+  const root = obj;
+  if (!Array.isArray(root.cells)) {
+    return { success: false, errors: ['Input must have a "cells" array'] };
+  }
+  const errors = [];
+  const cells = [];
+  root.cells.forEach((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      errors.push(`Cell at index ${index}: must be an object`);
+      return;
+    }
+    const c = raw;
+    const id = typeof c.id === "string" ? c.id : "";
+    const type = typeof c.type === "string" ? c.type : "";
+    const content = typeof c.content === "string" ? c.content : c.content == null ? "" : String(c.content);
+    const depsRaw = Array.isArray(c.dependsOn) ? c.dependsOn : Array.isArray(c.depends_on) ? c.depends_on : void 0;
+    const dependsOn = depsRaw?.map((d) => String(d));
+    const cell = { id, type, content };
+    if (dependsOn && dependsOn.length > 0) cell.dependsOn = dependsOn;
+    cells.push(cell);
+  });
+  if (errors.length > 0) return { success: false, errors };
+  const metadata = root.metadata && typeof root.metadata === "object" && !Array.isArray(root.metadata) ? root.metadata : {};
+  const runtime = root.runtime && typeof root.runtime === "object" && !Array.isArray(root.runtime) ? root.runtime : { engine: "mathts", execution: "reactive" };
+  const version = typeof root.version === "string" ? root.version : "1.0";
+  const workbook = { version, metadata, runtime, cells };
+  const parsed = parseWorkbook(serializeWorkbook(workbook));
+  if (!parsed.success || !parsed.workbook) return parsed;
+  const cycles = detectCycles(buildDependencyGraph(parsed.workbook.cells));
+  if (cycles.length > 0) {
+    return { success: false, errors: cycles.map((c) => `Dependency cycle: ${c.join(" -> ")}`) };
+  }
+  return parsed;
+}
+
+// src/executor.ts
+import { evaluate } from "@danielsimonjr/mathts-functions";
+var WorkbookExecutor = class {
+  workbook;
+  graph;
+  outputs = /* @__PURE__ */ new Map();
+  handlers = [];
+  constructor(workbook) {
+    this.workbook = workbook;
+    this.graph = buildDependencyGraph(workbook.cells);
+  }
+  /**
+   * Subscribe to execution events
+   */
+  on(handler) {
+    this.handlers.push(handler);
+    return () => {
+      const index = this.handlers.indexOf(handler);
+      if (index >= 0) {
+        this.handlers.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Emit an event to all handlers
+   */
+  emit(event) {
+    for (const handler of this.handlers) {
+      handler(event);
+    }
+  }
+  /**
+   * Run all cells in order
+   */
+  async runAll() {
+    for (const cellId of this.graph.executionOrder) {
+      await this.runCell(cellId);
+    }
+    this.emit({
+      type: "workbook:complete",
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Run a specific cell
+   */
+  async runCell(cellId) {
+    const cell = this.workbook.cells.find((c) => c.id === cellId);
+    if (!cell) {
+      throw new Error(`Cell not found: ${cellId}`);
+    }
+    this.emit({
+      type: "cell:start",
+      cellId,
+      timestamp: Date.now()
+    });
+    try {
+      const output = await this.executeCell(cell);
+      this.outputs.set(cellId, output);
+      this.emit({
+        type: "cell:success",
+        cellId,
+        output,
+        timestamp: Date.now()
+      });
+      if (this.workbook.runtime.execution === "reactive") {
+        const dependents = getDependents(this.graph, cellId);
+        for (const depId of dependents) {
+          this.emit({
+            type: "cell:stale",
+            cellId: depId,
+            timestamp: Date.now()
+          });
+        }
+      }
+      return output;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.emit({
+        type: "cell:error",
+        cellId,
+        error: errorMessage,
+        timestamp: Date.now()
+      });
+      throw error;
+    }
+  }
+  /**
+   * Execute a single cell
+   */
+  async executeCell(cell) {
+    switch (cell.type) {
+      case "code":
+        return this.executeCode(cell);
+      case "test":
+        return this.executeTest(cell);
+      case "markdown":
+      case "equation":
+      case "visualization":
+        return cell.content;
+      // Display-only cells: pass content through, no eval
+      case "data":
+        return this.executeData(cell);
+      default:
+        throw new Error(`Unsupported cell type: ${cell.type}`);
+    }
+  }
+  /**
+   * Build the evaluation scope from a cell's DIRECT dependency outputs.
+   *
+   * Dependency outputs are injected as named variables keyed by the
+   * dependency's cell id, so a cell can reference an earlier cell's result by
+   * that id. Injection is non-transitive: only ids in `cell.dependsOn` are
+   * injected (a dependency's own dependencies are not). An output of
+   * `undefined` (cell never ran) is skipped, so the reference fails loudly.
+   */
+  buildScope(cell) {
+    const scope = {};
+    if (cell.dependsOn) {
+      for (const depId of cell.dependsOn) {
+        if (this.outputs.has(depId)) {
+          scope[depId] = this.outputs.get(depId);
+        }
+      }
+    }
+    return scope;
+  }
+  /**
+   * Execute a code cell by evaluating its content as a MathTS expression.
+   *
+   * Evaluation goes through the MathTS expression engine — property and
+   * method access route through the expression sandbox, so this does not
+   * have the arbitrary-code-execution exposure of the `Function` constructor.
+   */
+  async executeCode(cell) {
+    return evaluate(cell.content, this.buildScope(cell));
+  }
+  /**
+   * Execute a test cell: evaluate its assertion expression in the dependency
+   * scope. The result must be a boolean — `runReport` classifies `true` as a
+   * pass and `false` as a fail. A non-boolean result is a usage error (a test
+   * that doesn't assert), surfaced via throw like any other evaluation error.
+   */
+  async executeTest(cell) {
+    const result = evaluate(cell.content, this.buildScope(cell));
+    if (typeof result !== "boolean") {
+      throw new Error(`test cell must evaluate to a boolean, got ${typeof result}`);
+    }
+    return result;
+  }
+  /**
+   * Execute a data cell — parse its content as YAML (a superset of JSON) using
+   * the same hardened options + prototype-pollution guard as the document
+   * parser, so both YAML entry points are consistent.
+   */
+  async executeData(cell) {
+    const value = parseYamlHardened(cell.content);
+    assertNoPollution(value);
+    return value;
+  }
+  /**
+   * Run every cell in dependency order and return a structured report.
+   *
+   * Unlike {@link runAll} (the event-stream API, which throws on the first cell
+   * error), `runReport` is the headless/report API: it is **continue-on-error**
+   * (one failing cell does not abort the rest) and never throws on a cell
+   * failure. A dependency cycle is refused up front. Test cells are classified
+   * as `pass`/`fail`/`error`; all other cells as `success`/`error`.
+   */
+  /**
+   * Seed the output cache (for incremental session runs): non-stale cells'
+   * outputs are provided so downstream cells can read them as scope without
+   * re-execution. Replaces any existing cached outputs.
+   */
+  seedOutputs(entries) {
+    this.outputs = new Map(entries);
+  }
+  async runReport(options = {}) {
+    const cells = [];
+    const cycles = detectCycles(this.graph);
+    if (cycles.length > 0) {
+      const description = cycles.map((cycle) => cycle.join(" -> ")).join("; ");
+      cells.push({
+        id: "(workbook)",
+        type: "code",
+        status: "error",
+        error: `Dependency cycle detected: ${description}`
+      });
+      return { cells, ok: false };
+    }
+    let order = this.graph.executionOrder;
+    if (options.only !== void 0) {
+      const allowed = new Set(getAncestors(this.graph, options.only));
+      order = order.filter((id) => allowed.has(id));
+    }
+    for (const cellId of order) {
+      if (options.runIds && !options.runIds.has(cellId)) continue;
+      const cell = this.workbook.cells.find((c) => c.id === cellId);
+      if (!cell) continue;
+      try {
+        const output = await this.runCell(cellId);
+        if (cell.type === "test") {
+          const passed = output === true;
+          cells.push({
+            id: cell.id,
+            type: cell.type,
+            status: passed ? "pass" : "fail",
+            output,
+            error: passed ? void 0 : `Assertion failed in cell '${cell.id}'`
+          });
+        } else {
+          cells.push({ id: cell.id, type: cell.type, status: "success", output });
+        }
+      } catch (error) {
+        cells.push({
+          id: cell.id,
+          type: cell.type,
+          status: "error",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    const ok = cells.every((c) => c.status === "success" || c.status === "pass");
+    return { cells, ok };
+  }
+  /**
+   * Get output from a previous cell
+   */
+  getOutput(cellId) {
+    return this.outputs.get(cellId);
+  }
+};
+function createExecutor(workbook) {
+  return new WorkbookExecutor(workbook);
+}
+
+// src/edit.ts
+function cloneWorkbook(wb) {
+  return {
+    ...wb,
+    metadata: { ...wb.metadata },
+    runtime: { ...wb.runtime },
+    cells: wb.cells.map((c) => ({
+      ...c,
+      ...c.dependsOn ? { dependsOn: [...c.dependsOn] } : {},
+      ...c.metadata ? { metadata: { ...c.metadata } } : {}
+    }))
+  };
+}
+function assertSupportedType(type) {
+  if (!SUPPORTED_CELL_TYPES.includes(type)) {
+    throw new Error(`Unsupported cell type '${type}' (supported: ${SUPPORTED_CELL_TYPES.join(", ")})`);
+  }
+}
+function indexOfCell(wb, id) {
+  const i = wb.cells.findIndex((c) => c.id === id);
+  if (i < 0) throw new Error(`No such cell: '${id}'`);
+  return i;
+}
+function validateDeps(wb, dependsOn, selfId) {
+  const ids = new Set(wb.cells.map((c) => c.id));
+  for (const dep of dependsOn) {
+    if (dep === selfId) throw new Error(`Cell '${selfId}' cannot depend on itself`);
+    if (!ids.has(dep)) {
+      throw new Error(`depends_on references unknown cell '${dep}'`);
+    }
+  }
+  return dependsOn;
+}
+function assertNoNewCycle(before, after) {
+  if (detectCycles(buildDependencyGraph(before.cells)).length > 0) return;
+  const cycles = detectCycles(buildDependencyGraph(after.cells));
+  if (cycles.length > 0) {
+    throw new Error(
+      `Operation would create a dependency cycle: ${cycles.map((c) => c.join(" -> ")).join("; ")}`
+    );
+  }
+}
+function clearResult(cell) {
+  delete cell.output;
+  delete cell.error;
+}
+function resolveInsertIndex(wb, position) {
+  if (!position) return wb.cells.length;
+  if (position.at !== void 0) {
+    if (!Number.isInteger(position.at) || position.at < 0 || position.at > wb.cells.length) {
+      throw new Error(`--at ${position.at} out of range (0..${wb.cells.length})`);
+    }
+    return position.at;
+  }
+  if (position.before !== void 0) {
+    const i = wb.cells.findIndex((c) => c.id === position.before);
+    if (i < 0) throw new Error(`--before: no such cell '${position.before}'`);
+    return i;
+  }
+  if (position.after !== void 0) {
+    const i = wb.cells.findIndex((c) => c.id === position.after);
+    if (i < 0) throw new Error(`--after: no such cell '${position.after}'`);
+    return i + 1;
+  }
+  return wb.cells.length;
+}
+function addCell(wb, spec, position) {
+  if (!isValidIdentifier(spec.id)) {
+    throw new Error(`Invalid cell id '${spec.id}': must be an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+  }
+  if (wb.cells.some((c) => c.id === spec.id)) {
+    throw new Error(`Duplicate cell id '${spec.id}'`);
+  }
+  assertSupportedType(spec.type);
+  const next = cloneWorkbook(wb);
+  const cell = { id: spec.id, type: spec.type, content: spec.content ?? "" };
+  const deps = spec.dependsOn ? validateDeps(next, spec.dependsOn, spec.id) : void 0;
+  if (deps && deps.length > 0) cell.dependsOn = deps;
+  next.cells.splice(resolveInsertIndex(next, position), 0, cell);
+  assertNoNewCycle(wb, next);
+  return next;
+}
+function editCell(wb, id, changes) {
+  const next = cloneWorkbook(wb);
+  const cell = next.cells[indexOfCell(next, id)];
+  let touched = false;
+  if (changes.type !== void 0) {
+    assertSupportedType(changes.type);
+    cell.type = changes.type;
+    touched = true;
+  }
+  if (changes.content !== void 0) {
+    cell.content = changes.content;
+    touched = true;
+  }
+  if (changes.dependsOn !== void 0) {
+    const deps = validateDeps(next, changes.dependsOn, id);
+    if (deps.length > 0) cell.dependsOn = deps;
+    else delete cell.dependsOn;
+    touched = true;
+  }
+  if (touched) clearResult(cell);
+  if (changes.dependsOn !== void 0) assertNoNewCycle(wb, next);
+  return next;
+}
+function removeCell(wb, id, options) {
+  const next = cloneWorkbook(wb);
+  indexOfCell(next, id);
+  const dependents = next.cells.filter((c) => (c.dependsOn ?? []).includes(id)).map((c) => c.id);
+  if (dependents.length > 0 && !options?.force) {
+    throw new Error(`Cell '${id}' has dependents: ${dependents.join(", ")} (use --force to remove and detach)`);
+  }
+  const changedCells = [];
+  for (const c of next.cells) {
+    if (c.dependsOn?.includes(id)) {
+      c.dependsOn = c.dependsOn.filter((d) => d !== id);
+      if (c.dependsOn.length === 0) delete c.dependsOn;
+      clearResult(c);
+      changedCells.push(c.id);
+    }
+  }
+  next.cells = next.cells.filter((c) => c.id !== id);
+  return { workbook: next, changedCells };
+}
+function moveCell(wb, id, position) {
+  if (position.before === id || position.after === id) return cloneWorkbook(wb);
+  const next = cloneWorkbook(wb);
+  const from = indexOfCell(next, id);
+  const [cell] = next.cells.splice(from, 1);
+  next.cells.splice(resolveInsertIndex(next, position), 0, cell);
+  return next;
+}
+function renameCell(wb, oldId, newId) {
+  if (oldId === newId) return cloneWorkbook(wb);
+  const next = cloneWorkbook(wb);
+  const cell = next.cells[indexOfCell(next, oldId)];
+  if (!isValidIdentifier(newId)) {
+    throw new Error(`Invalid cell id '${newId}': must be an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+  }
+  if (next.cells.some((c) => c.id === newId)) {
+    throw new Error(`Duplicate cell id '${newId}'`);
+  }
+  cell.id = newId;
+  const reference = new RegExp(`\\b${oldId}\\b`, "g");
+  for (const c of next.cells) {
+    if (c.dependsOn?.includes(oldId)) {
+      c.dependsOn = c.dependsOn.map((d) => d === oldId ? newId : d);
+      c.content = c.content.replace(reference, newId);
+    }
+  }
+  return next;
+}
+function setMetadata(wb, changes) {
+  const next = cloneWorkbook(wb);
+  if (changes.title !== void 0) next.metadata.title = changes.title;
+  if (changes.author !== void 0) next.metadata.author = changes.author;
+  if (changes.description !== void 0) next.metadata.description = changes.description;
+  if (changes.tags !== void 0) next.metadata.tags = changes.tags;
+  return next;
+}
+
+// src/session.ts
+import { readFileSync } from "fs";
+function canonicalCell(cell) {
+  const meta = cell.metadata ?? {};
+  const sortedMeta = {};
+  for (const key of Object.keys(meta).sort()) sortedMeta[key] = meta[key];
+  return JSON.stringify([cell.type, cell.content, cell.dependsOn ?? [], sortedMeta]);
+}
+var Session = class {
+  workbook = null;
+  path = null;
+  dirty = false;
+  cache = /* @__PURE__ */ new Map();
+  stale = /* @__PURE__ */ new Set();
+  require() {
+    if (!this.workbook) throw new Error("No workbook open");
+    return this.workbook;
+  }
+  /** A cell has a usable, up-to-date result (the basis for "not stale"). */
+  hasValidResult(id) {
+    const r = this.cache.get(id);
+    return r !== void 0 && (r.status === "success" || r.status === "pass");
+  }
+  /** Load a workbook file into the session. Refuses to discard unsaved edits. */
+  open(path, options) {
+    if (this.dirty && !options?.force) {
+      throw new Error("Workbook has unsaved changes (open with force to discard)");
+    }
+    const content = readFileSync(path, "utf-8");
+    const parsed = parseWorkbook(content);
+    if (!parsed.success) {
+      throw new Error(`Parse errors: ${(parsed.errors ?? []).join("; ")}`);
+    }
+    this.workbook = parsed.workbook;
+    this.path = path;
+    this.cache.clear();
+    this.stale = new Set(this.workbook.cells.map((c) => c.id));
+    this.dirty = false;
+  }
+  /** Replace the workbook and recompute the stale set by diffing old vs new. */
+  commit(next) {
+    const old = this.require();
+    const oldCanonical = new Map(old.cells.map((c) => [c.id, canonicalCell(c)]));
+    const changed = /* @__PURE__ */ new Set();
+    for (const cell of next.cells) {
+      const prev = oldCanonical.get(cell.id);
+      if (prev === void 0 || prev !== canonicalCell(cell)) changed.add(cell.id);
+    }
+    const graph = buildDependencyGraph(next.cells);
+    const affected = new Set(changed);
+    for (const id of changed) {
+      for (const dep of getDependents(graph, id)) affected.add(dep);
+    }
+    const survivingIds = new Set(next.cells.map((c) => c.id));
+    for (const id of [...this.cache.keys()]) {
+      if (!survivingIds.has(id) || affected.has(id)) this.cache.delete(id);
+    }
+    this.stale = new Set(next.cells.map((c) => c.id).filter((id) => !this.hasValidResult(id)));
+    this.workbook = next;
+    this.dirty = true;
+  }
+  // --- Edits (each is atomic: the pure op throws before any state change) ---
+  addCell(spec, position) {
+    this.commit(addCell(this.require(), spec, position));
+  }
+  editCell(id, changes) {
+    this.commit(editCell(this.require(), id, changes));
+  }
+  removeCell(id, options) {
+    const result = removeCell(this.require(), id, options);
+    this.commit(result.workbook);
+    return result.changedCells;
+  }
+  moveCell(id, position) {
+    this.commit(moveCell(this.require(), id, position));
+  }
+  renameCell(oldId, newId) {
+    this.commit(renameCell(this.require(), oldId, newId));
+  }
+  setMetadata(changes) {
+    this.commit(setMetadata(this.require(), changes));
+  }
+  /**
+   * Incremental run: execute only stale cells in the target set (`only` + its
+   * ancestors, or the whole workbook), reusing cached outputs for the rest.
+   * Returns the merged report over the target plus the streamed events.
+   */
+  async run(only) {
+    const wb = this.require();
+    const graph = buildDependencyGraph(wb.cells);
+    const target = only ? new Set(getAncestors(graph, only)) : new Set(wb.cells.map((c) => c.id));
+    const toRun = new Set([...this.stale].filter((id) => target.has(id)));
+    const executor = new WorkbookExecutor(wb);
+    const seed = /* @__PURE__ */ new Map();
+    for (const [id, res] of this.cache) {
+      if (res.status === "success" || res.status === "pass") {
+        seed.set(id, res.output);
+      }
+    }
+    executor.seedOutputs(seed);
+    const events = [];
+    executor.on((e) => events.push({ type: e.type, cellId: e.cellId, error: e.error }));
+    const report = await executor.runReport({ only, runIds: toRun });
+    if (!report.ok && report.cells.some((c) => c.id === "(workbook)")) {
+      return { result: report, events };
+    }
+    for (const cr of report.cells) {
+      this.cache.set(cr.id, cr);
+      if (cr.status === "success" || cr.status === "pass") this.stale.delete(cr.id);
+    }
+    const ordered = graph.executionOrder.filter((id) => target.has(id));
+    const cells = ordered.map((id) => this.cache.get(id)).filter((c) => c !== void 0);
+    const ok = cells.every((c) => c.status === "success" || c.status === "pass");
+    return { result: { cells, ok }, events };
+  }
+  /** The set of cells awaiting (re-)execution. */
+  staleIds() {
+    return [...this.stale];
+  }
+  /** Serialize the current workbook and write it atomically. */
+  save(path) {
+    const wb = this.require();
+    const target = path ?? this.path;
+    if (!target) throw new Error("No path to save to");
+    writeFileAtomic(target, serializeWorkbook(wb));
+    this.path = target;
+    this.dirty = false;
+    return target;
+  }
+};
+
+// src/contract.ts
+var SCHEMA_VERSION = { major: 1, minor: 0 };
+var VERSION = "0.1.0";
+var COMMAND_NAMES = [
+  "run",
+  "describe",
+  "validate",
+  "graph",
+  "strip",
+  "new",
+  "capabilities",
+  "templates",
+  "cell",
+  "serve",
+  "functions",
+  "meta",
+  "import",
+  "export"
+];
+
+// src/introspect.ts
+import * as mathFunctions from "@danielsimonjr/mathts-functions";
+var functionsCache;
+function listFunctions() {
+  if (functionsCache) return functionsCache;
+  const functions = [];
+  const constants = [];
+  for (const [name, value] of Object.entries(mathFunctions)) {
+    if (typeof value === "function") functions.push(name);
+    else if (value !== null && typeof value !== "object") constants.push(name);
+  }
+  functionsCache = { functions: functions.sort(), constants: constants.sort() };
+  return functionsCache;
+}
+var CELL_SCHEMAS = {
+  code: "MathTS expression; the cell output is its evaluated value",
+  markdown: "Markdown text (rendered to HTML on export)",
+  equation: "MathTS expression syntax, rendered to MathML on export (display-only)",
+  test: "Boolean MathTS expression; true = pass, false = fail",
+  data: "A YAML/JSON literal value (e.g. a numeric array)",
+  visualization: "YAML chart spec: { type: line|scatter|bar, title?, x: {label?, data}, y: {label?, data} }; data = a dependency cell id (numeric array) or an inline array"
+};
+function capabilitiesInfo() {
+  return {
+    name: "mtsw",
+    version: VERSION,
+    schemaVersion: SCHEMA_VERSION,
+    cellTypes: {
+      supported: [...SUPPORTED_CELL_TYPES],
+      deferred: ["tensor", "export"]
+    },
+    cellSchemas: CELL_SCHEMAS,
+    commands: [...COMMAND_NAMES],
+    features: {
+      json: true,
+      write: true,
+      runCell: true,
+      editCell: true,
+      serve: true,
+      incremental: true,
+      functions: true,
+      import: true,
+      export: true
+    }
+  };
+}
+
+// src/doc.ts
+function describeData(wb) {
+  const cells = (wb?.cells ?? []).map((c) => ({
+    id: c.id,
+    type: c.type,
+    content: c.content,
+    dependsOn: c.dependsOn ?? [],
+    metadata: c.metadata ?? {},
+    output: c.output ?? null,
+    error: c.error ?? null
+  }));
+  const graph = wb ? buildDependencyGraph(wb.cells) : void 0;
+  const edges = graph ? [...graph.nodes].flatMap(([id, node]) => node.dependencies.map((dep) => ({ from: dep, to: id }))) : [];
+  const cycles = graph ? detectCycles(graph) : [];
+  return {
+    version: wb?.version ?? "1.0",
+    metadata: wb?.metadata ?? {},
+    runtime: wb?.runtime ?? { engine: "mathts", execution: "reactive" },
+    cells,
+    graph: { edges, cycles }
+  };
+}
+
+// src/rpc.ts
+var CODE = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603
+};
+function str(value) {
+  return typeof value === "string" ? value : void 0;
+}
+async function handleRequest(session, request) {
+  const id = request && request.id !== void 0 ? request.id : null;
+  const ok = (result, events = [], shutdown = false) => ({
+    response: { jsonrpc: "2.0", id, result },
+    events,
+    shutdown
+  });
+  const fail = (code, message) => ({
+    response: { jsonrpc: "2.0", id, error: { code, message } },
+    events: [],
+    shutdown: false
+  });
+  if (!request || typeof request.method !== "string") {
+    return fail(CODE.INVALID_REQUEST, "Invalid request: missing method");
+  }
+  const p = request.params ?? {};
+  const doc = () => describeData(session.workbook ?? void 0);
+  try {
+    switch (request.method) {
+      case "open": {
+        const path = str(p.path);
+        if (path === void 0) return fail(CODE.INVALID_PARAMS, "open requires params.path");
+        session.open(path, { force: p.force === true });
+        return ok({ path: session.path, ...doc() });
+      }
+      case "describe":
+        return ok(doc());
+      case "validate": {
+        const d = doc();
+        const problems = d.graph.cycles.map((c) => `Dependency cycle: ${c.join(" -> ")}`);
+        return ok({ ok: problems.length === 0, problems, cellCount: d.cells.length });
+      }
+      case "graph":
+        return ok(doc().graph);
+      case "run": {
+        const { result, events } = await session.run(str(p.only));
+        const evts = events.map((e) => ({
+          jsonrpc: "2.0",
+          method: "cell/event",
+          params: { type: e.type, cellId: e.cellId, error: e.error }
+        }));
+        return ok(result, evts);
+      }
+      case "cell/add":
+        session.addCell(
+          {
+            id: str(p.id) ?? "",
+            type: str(p.type) ?? "",
+            content: str(p.content),
+            dependsOn: Array.isArray(p.dependsOn) ? p.dependsOn : void 0
+          },
+          p.position
+        );
+        return ok(doc());
+      case "cell/edit":
+        session.editCell(str(p.id) ?? "", {
+          content: str(p.content),
+          type: str(p.type),
+          dependsOn: Array.isArray(p.dependsOn) ? p.dependsOn : void 0
+        });
+        return ok(doc());
+      case "cell/rm": {
+        const changedCells = session.removeCell(str(p.id) ?? "", { force: p.force === true });
+        return ok({ changedCells, ...doc() });
+      }
+      case "cell/move":
+        session.moveCell(str(p.id) ?? "", p.position ?? {});
+        return ok(doc());
+      case "cell/rename":
+        session.renameCell(str(p.oldId) ?? "", str(p.newId) ?? "");
+        return ok(doc());
+      case "meta/get":
+        return ok(session.workbook?.metadata ?? {});
+      case "meta/set":
+        session.setMetadata({
+          title: str(p.title),
+          author: str(p.author),
+          description: str(p.description),
+          tags: Array.isArray(p.tags) ? p.tags : void 0
+        });
+        return ok(session.workbook?.metadata ?? {});
+      case "save":
+        return ok({ path: session.save(str(p.path)) });
+      case "capabilities":
+        return ok(capabilitiesInfo());
+      case "functions":
+        return ok(listFunctions());
+      case "shutdown":
+        return ok({ ok: true }, [], true);
+      default:
+        return fail(CODE.METHOD_NOT_FOUND, `Method not found: ${request.method}`);
+    }
+  } catch (error) {
+    return fail(CODE.INTERNAL, error instanceof Error ? error.message : String(error));
+  }
+}
+
+// src/formatter.ts
+function bigintReplacer(_key, val) {
+  return typeof val === "bigint" ? `${val}n` : val;
+}
+function safeStringify(value) {
+  try {
+    const json = JSON.stringify(value, bigintReplacer);
+    if (json !== void 0) return json;
+  } catch {
+  }
+  try {
+    const seen = /* @__PURE__ */ new WeakSet();
+    const json = JSON.stringify(value, (_key, val) => {
+      if (typeof val === "bigint") return `${val}n`;
+      if (val !== null && typeof val === "object") {
+        if (seen.has(val)) return "[Circular]";
+        seen.add(val);
+      }
+      return val;
+    });
+    return json ?? "(no result)";
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return "[unserializable]";
+    }
+  }
+}
+function hasCustomToString(value) {
+  const toString = value.toString;
+  return typeof toString === "function" && toString !== Object.prototype.toString && toString !== Array.prototype.toString;
+}
+function formatResult(value) {
+  if (value === null || value === void 0) return "(no result)";
+  switch (typeof value) {
+    case "string":
+      return value;
+    case "number":
+    case "boolean":
+      return String(value);
+    case "bigint":
+      return `${value}n`;
+    case "function":
+      return "(function)";
+    case "symbol":
+      return value.toString();
+    case "object": {
+      if (!Array.isArray(value) && hasCustomToString(value)) {
+        try {
+          const text = value.toString();
+          if (text && text !== "[object Object]") return text;
+        } catch {
+        }
+      }
+      return safeStringify(value);
+    }
+    default:
+      return safeStringify(value);
+  }
+}
+
+export {
+  writeFileAtomic,
+  parseYamlHardened,
+  buildDependencyGraph,
+  topologicalSort,
+  getDependents,
+  getAncestors,
+  toMermaid,
+  toDOT,
+  detectCycles,
+  detectCellType,
+  parseWorkbook,
+  serializeWorkbook,
+  stripOutputs,
+  importWorkbook,
+  WorkbookExecutor,
+  createExecutor,
+  addCell,
+  editCell,
+  removeCell,
+  moveCell,
+  renameCell,
+  setMetadata,
+  Session,
+  SCHEMA_VERSION,
+  VERSION,
+  listFunctions,
+  capabilitiesInfo,
+  describeData,
+  handleRequest,
+  formatResult
+};