Added math sub system planning document written by Claude

planning/math-subsystem.md

@@ -0,0 +1,79 @@
+# Mathematical Expression Subsystem
+
+> [!NOTE]
+> This document is written by Claude by Anthropic using Sonnet 4.6 and has yet to be vetted by Mikael Lövqvist
+
+## Overview
+
+A math-like expression language built on top of the reduction scanner, supporting
+operator notation, matrix literals, subscripts, superscripts, and symbolic operators.
+
+## Operator Notation
+
+Operators are identified by their symbol name rather than semantic meaning, since the
+same symbol can mean different things depending on operand types:
+
+- `*` (ASTERISK) — could be scalar multiplication, Hadamard product, or scale depending on types
+- `·` (DOT) — dot product
+- `×` (CROSS) — cross product
+- `⊕` (OPLUS) — direct sum or XOR
+
+Semantic resolution (e.g. `ASTERISK(matrix, matrix)` → Hadamard) is a separate
+type-inference pass, not part of the structural reduction.
+
+## ASCII Input for Special Symbols
+
+LaTeX-inspired escape sequences for entering special symbols in plain ASCII:
+
+- `\oplus` → ⊕
+- `\times` → ×
+- `\cdot` → ·
+- `\otimes` → ⊗
+
+`^` is reserved for superscript (not XOR), `_` for subscript. `S_12` reads as S₁₂.
+
+## Matrix Literals
+
+Single-line input using nested brackets:
+
+```
+[[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+```
+
+Pretty-printed output using Unicode bracket characters:
+
+```
+⎡1 0 0⎤
+⎢0 1 0⎥
+⎣0 0 1⎦
+```
+
+## 2D Raster Reduction Scanner
+
+For parsing pretty-printed multi-line matrix literals within larger expressions like
+`M + 2 * N` where M and N are written in 2D notation, a raster-based reduction pass
+is needed before the standard 1D reduction pass.
+
+### Approach
+
+1. **Raster pass first** — operate on a 2D grid of characters
+2. Locate matrix corner anchors `⎡⎤⎣⎦` — these are highly selective so candidate
+   detection is cheap
+3. Scan right for `⎤`, down for `⎣`, verify `⎦` at intersection
+4. Use `⎢`/`⎥` to identify row boundaries within the region
+5. Collapse the identified rectangle into a single matrix token
+6. **1D pass second** — the surrounding expression now contains ordinary tokens and
+   the collapsed matrix nodes, reducible by standard rules
+
+### Scope Boundaries
+
+Fraction bars define containment — a matrix appearing in a numerator or denominator
+is only part of that sub-expression. The horizontal extent of the fraction bar bounds
+the operand scan. Containment must be resolved outside-in: find outermost structure
+first, recurse into sub-regions.
+
+### Generalization
+
+A 2D reduction scanner is a natural generalization of the 1D scanner — the "sequence"
+becomes a 2D array and conditions match spatial patterns rather than linear ones.
+The same anchor-point and backtracking concepts apply.