docs/plans/2026-10-05-table-formulas.md

 1# Table Formulas Implementation Plan
 2
 3> **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.
 4
 5**Goal:** `#+TBLFM` recalculation (`C-c *`, `C-u C-c *`, `C-c C-c` on a `#+TBLFM` line) computed natively where Calc's results can be reproduced exactly, and in Emacs otherwise.
 6
 7**Architecture:** `OrgCore/Compute/Calc.swift` implements the Calc subset table formulas use with Calc's number model: exact integers, decimal floats rounded half-up to 12 digits after each operation (`math-make-float`, `math-div-float`, `math-ipow`), `*` binding tighter than `/`, exact results for special trig and log values, and `math-format-number` for `float`, `fix`, `sci` and `eng` formats. `TableFormulas.swift` ports `org-table-recalculate`, `org-table-eval-formula`, `org-table-get-range`, row descriptors (`@I`, `@-1`, `@<`, `@>`), lhs ranges and `org-table-justify-field-maybe`, then aligns with the existing `org-table-align` port. Anything outside the domain (text in a referenced field, division by zero, names, constants, `remote()`, Lisp, durations, unsupported functions or flags) returns `.external(.emacsTable)`: the app runs `emacs --batch` on a snapshot of the buffer in the file's folder and splices back the table text if the table is unchanged. Lisp formulas ask first, with "always" stored by content hash in `trusted.json`.
 8
 9**Tech Stack:** Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 / Calc oracle.
10
11**Spec:** `docs/design.md`, "Table formula evaluator".
12
13## Global Constraints
14
15- Calc oracle: 475 expressions (fixed and random) against `calc-eval` with `org-calc-default-modes`, every display format.
16- Table oracle: 20 tables × every row and `#+TBLFM` line × `org-table-recalculate t`/`nil` and `org-ctrl-c-ctrl-c`, text and point; corpus `#+TBLFM` lines.
17- On an error partway through, Emacs keeps the fields already written; here nothing changes.
18- New command step `.external(ExternalRequest)` for work done outside the text.
19
20## Defaults chosen (user may change)
21
22- Keys: `C-c *` recalculates the row, `C-c C-c` on `#+TBLFM` the table; "Recalculate Table" in the palette for `C-u C-c *`.
23- Emacs is found at `ORGSTAR_EMACS`, Homebrew, `/usr/local/bin` or Emacs.app.
24
25---
26
27### Task 1: Calc
28
29- [x] Numbers, operators, functions, formats; oracle.
30
31### Task 2: Recalculation
32
33- [x] `tableRecalculate`, `TableRecalculate`, `tblfm` key context, bindings; oracle; corpus.
34
35### Task 3: Emacs fallback
36
37- [x] `.external`, `EmacsRunner.recalculateTable`, `DocumentSession.recalculateInEmacs`, `TrustStore`, editor wiring; test with a text field.
38- [x] Commit "Table formulas".