docs/plans/2026-10-05-babel.md

Babel Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: C-c C-c in a src block runs it (sh and the other shells, python, emacs-lisp, and ruby/js/R/awk for output) and writes #+RESULTS: as Emacs does.

Architecture: OrgCore/Compute/Babel.swift plans and finishes; the platform runs. Babel.plan resolves header arguments as org-babel-merge-params does (defaults, header-args properties from the file and headings, the block line, #+HEADER: lines; :results by exclusive groups; :var by name), refuses :eval never, :session, :noweb, :file, :prologue, :epilogue, :post, :stdin, :cmdline, :shebang, :cache yes and src-block references with a message, and builds a BabelJob: the program on standard input for the interpreter (shell variables as name='value', python wrapped in def main() with a result file as ob-python does, emacs-lisp evaluated in emacs --batch printing its value as JSON). Babel.finish applies org-babel-result-cond, the table import (org-table-convert-region with babel-auto, org-babel--string-to-number), python's table-or-string, and org-babel-insert-result: where the results go (#+RESULTS: after the block or #+RESULTS: name), replace/append/silent, tables aligned, lists, raw, drawer, code, org, html, latex, :wrap, : lines under ten lines and example blocks from ten, code escaping, indentation. The app asks before running (yes/no/always, trusted by block content in trusted.json; :eval query always asks), runs the job with BabelRunner, and writes the result if the block is still there.

Tech Stack: Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle with python3.

Spec: docs/design.md, "Babel execution (macOS)".

Global Constraints

• Oracle: 53 blocks run natively and by org-babel-execute-src-block; whole buffers compared.
• Shell blocks run sh, bash, … by name with the program on standard input; shell runs /bin/sh.
• The python wrapper is written for Orgstar and behaves as ob-python's (no pandas or numpy conversion).

Defaults chosen (user may change)

• python3 for python blocks (:python overrides); five-minute timeout.
• :var tables with rules, name[...] indexing, calls and src-block references aren't supported yet; tables and lists only for python and emacs-lisp.

• Babel.plan, Babel.finish, ExecuteSrcBlock, src key context, C-c C-c; oracle.
• BabelRunner, DocumentSession.runBabel, confirmation and trust; session test.
• Commit "Babel".