Files
marqdo-cli/spec/math.md
T
cflmy 0116160399 docs: formal specs, ADRs, STATUS matrix, contributor guide and honest README
Complete the documentation set for the M0.5 toolchain, grounded in the code:

- spec/references.md: import/reference/call edges, identities, loader rules,
  anchors, `ref` resolution/ambiguity, `check --refs` validation.
- spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal
  string rule, special floats, limits and exact float round-trip.
- spec/security.md: modes (strict refuses without OS isolation), capabilities,
  path rules, budgets, tracing, foreign process caveats, plugin trust.
- spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync,
  unsupported registry/git/environment work.
- spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact
  rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the
  implemented CLI plugin-invocation flow with its limitations.
- spec/math.md and spec/foreign.md: the implemented math subset and the
  foreign request/response/timeout/capability contract.
- docs/adr/0001..0007: accepted decisions for the span foundation, inert
  executables outside function bodies, ref ambiguity (S-07), strict refusal,
  AST normalization, CLI contract and BigInt/typed wire (S-08).
- docs/contributor-guide.md: repo map, workflow, fixture/golden updates,
  quality gate, ADR/commit policy.
- docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18
  Alpha checklist (conclusion: not yet Alpha-complete), including known
  divergences rather than overclaims.
- README.md rewritten from "design-only starter" to the working implementation
  with quickstart, implemented phases, deliberate limits and doc index.
- AGENTS.md: updated pointers/workflow only; architectural rules unchanged.
- Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside
  functions, unsupported math.simplify/differentiate).
2026-11-20 10:56:26 +08:00

228 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Marqdo Math v1
Status: **frozen subset for M0.5.** The kernel computes numbers; it never proves
theorems. `math.simplify` and `math.differentiate` are **not implemented** in
this build.
Implementation: `crates/marqdo-math` (`parse`, `evaluate`, `substitute`,
`MathError`), host adapter `crates/marqdo-host/src/kernels.rs::math`, builtin
metadata `crates/marqdo-ir/src/builtins.rs`, tests
`crates/marqdo-math/tests/kernel.rs`.
## 1. From Markdown to a value
A `math` / `math_block` node is an **inert document resource**, never an
operation. The frontend attributes every formula to its innermost enclosing
heading unit (`crates/marqdo-frontend/src/resources.rs`). `ref("#heading")`
returns a `Formula` value only when that unit contains exactly one resource;
with two or more formulas the runtime raises `ref.ambiguous` and refuses to
pick one (`spec/references.md` §5, ADR-0003).
```markdown
## 圆面积公式
$$
A = \pi r^2
$$
## 计算圆面积
**面积 = math.eval(ref("#圆面积公式"), {"r": 4}, target="A")**
*面积*
```
Nothing is evaluated by reading or rendering the document. `math.*` must be
called explicitly and the host checks the `math` capability at execution time
(default: granted in `pure`/`project`; there is no CLI flag to revoke it today).
## 2. Grammar
The parser accepts exactly this LaTeX subset (whitespace insignificant; byte
offsets are reported for parse errors):
```text
formula = expr [ "=" expr ] ; single '=' only, never assignment
expr = term { ("+" | "-") term } ;
term = unary { ("*" | "/" | "·" | "×" | implicit) unary } ;
unary = ("+" | "-") unary | power ;
power = primary [ "^" unary ] ; right associative
primary = number
| identifier Unicode letter (plus digits/underscore)
| "\pi" | "pi" | "\e" | "e" constants
| "(" expr ")" | "\left(" expr "\right)"
| "{" expr "}" grouping
| "\frac{" expr "}{" expr "}" exact division
| "\sqrt{" expr "}" real square root
;
number = digits [ "." digits ] | "." digits ; decimal, no exponent form
```
Rules and edge cases:
* `\cdot` and `\times` are accepted as synonyms for `*`.
* Implicit multiplication between adjacent factors: `2x`, `\pi r^2`, `(a)(b)`,
`m a`. Concatenated letters form one identifier (`ma` is the variable `ma`;
write `m a` or `m * a` for a product). Two adjacent number literals are a
parse error ("ambiguous").
* Unicode identifiers are supported (`面积`, `r`, `速度`). Plain multi-letter
identifiers are variables, but names of common elementary functions (`sin`,
`cos`, `log`, `exp`, ...) are reserved and rejected as unsupported so
`sin(x)` is not silently read as a product.
* Underscores are ordinary identifier characters: `x_1` is the variable `x_1`,
not a subscript.
* A single top-level `=` creates an `Equation { left, right }`; it is **not**
assignment and never writes a Marqdo binding. A second `=` is a parse error.
* `\frac{a}{b}` is exact division (`Div`); `1.5 + 2.5` is an exact rational
computation, not binary floating point.
* `\sqrt{x}` is real-valued: a negative radicand is a `Type` error.
* Decimal literals have no exponent form (`1e3` is rejected); `2e` is
`2 * e` (number times the constant), while `2e3` is rejected rather than
reinterpreted.
### 2.1 Unsupported constructs
Everything outside the grammar is a structured `Unsupported` or `Parse` error:
matrices, sums/integrals, function applications (`\sin`, `\cos`, ...),
multi-letter commands, `\left[`/`\right]`, mismatched/missing braces,
scientific notation, commas, arrays, subscripts, superscript commands other
than the `^` operator, `\frac`/`\sqrt` without braced arguments, labels,
alignment characters, line breaks. There is no `simplify`, `differentiate`,
`integrate`, `matrix` or theorem/proof operation in this build.
## 3. Numeric semantics
* Exact rational arithmetic uses `num-rational::Ratio` over the
`num-bigint::BigInt` type that also backs `Value::Int`; integers are
arbitrary precision.
* Decimal literals are exact rationals (`0.25` = `1/4`). `Int` bindings become
exact integers. `Float` bindings are interpreted as the **exact binary
rational value** of the `f64`; non-finite `Float` bindings are a `Type`
error.
* `+ - * / ^` are exact when both operands are exact. Division keeps a
rational, so `\frac{1}{3} * 3` is exactly `1`.
* The final value is a Marqdo `Int` exactly when the exact result is an
integer, and a `Float` otherwise (`crates/marqdo-math/src/eval.rs`, the
`Numeric` enum). Examples: `1.5 + 2.5` → `Int(4)`; `1 / 2` → `Float(0.5)`;
`100 / 4` → `Int(25)`.
* `\pi`, `\e` and a `\sqrt` of a non-perfect square introduce an `f64`
approximation. Anything derived from them is a `Float`. Precision follows
IEEE-754 binary64 (about 15–17 significant decimal digits); approximate
results are never presented as exact.
* `\sqrt` of a perfect square of an exact rational stays exact (`\sqrt{4}` →
`Int(2)`); `\sqrt{1/4}` is `Float(0.5)` in this build (it becomes
approximate via the root path, matching the documented test).
* The exponent of `^` must evaluate to an integer. Magnitude is bounded by
`MAX_EXPONENT`. Negative integer exponents are exact reciprocals (the result
is therefore a `Float` unless it is integral). `0 ^ 0` is a `Type` error.
* Exact intermediate/result numerators and denominators are bounded by
`MAX_RESULT_BITS`; exceeding the bound returns a structured `Unsupported`
error rather than hanging or exhausting memory.
* Division by zero is a `Type` error inside the kernel. The host maps all
`MathErrorKind::Type` to `runtime.type`; it does **not** produce
the interpreter's `runtime.division_by_zero` code for a formula. This is a
known divergence from the module doc comment in
`crates/marqdo-math/src/lib.rs` and should be fixed or documented in an ADR.
* Constants are reserved: a binding named `pi` or `e` never overrides the
constant, and they cannot be solve targets (use `E`, `x`, `r`, ...).
### 3.1 Bounds
| Constant | Value | Location |
|---|---|---|
| `MAX_SOURCE_BYTES` | 1,000,000 | `crates/marqdo-math/src/parse.rs` |
| `MAX_PARSE_DEPTH` | 256 | parse.rs |
| `MAX_AST_NODES` | 512 | parse.rs |
| `MAX_EXPONENT` | 10,000 | `crates/marqdo-math/src/eval.rs` |
| `MAX_RESULT_BITS` | 1,000,000 | eval.rs |
The AST-node bound also bounds later recursion for long operator chains, so
hostile input cannot overflow the stack during evaluation, rendering or
substitution. No code path panics on untrusted LaTeX; all failures are
`MathError`.
## 4. Equations and solving a target
`FormulaKind` is `Expression(expr)` or `Equation { left, right }`.
`evaluate(formula, bindings, target)`:
* for a plain expression, `target` must be `None`; supplying one is
`Unsupported` ("a target variable is only meaningful for an equation");
* for an equation, `target` is required (`Unsupported` otherwise); an empty
target is `Unsupported`;
* the target must occur **exactly once** and the equation must be **affine in
the target**. Other variables are substituted from `bindings` first; a
missing binding is `UndefinedVariable`.
Affine solving supported by `crates/marqdo-math/src/eval.rs`:
* `+`, `-`, multiplication by a target-free side, division where the target is
in the numerator, and inversion of those operations in either direction:
`2x = 4`, `4 = 2x`, `x / 2 = 3`, `3 = x / 2`, `x + 2 = 5`, `2x + 1 = 7`,
`(x + 1) * 2 = 8`, `x = 2y + 1` (with `y` bound);
* `F = m a` solved for `F`, `m` or `a`.
Rejected as `Unsupported`: target occurs zero times or more than once, target
in a denominator, under a root, in an exponent, or in a non-affine product
(e.g. `x * x`). Equations never mutate bindings and never create Marqdo
variables.
## 5. Substitution
`substitute(formula, bindings)` replaces bound variables with exact numeric
literals and keeps unbound variables symbolic. The returned `Formula.source` is
a deterministic canonical rendering that `parse` accepts again; it is not
byte-identical to the input formatting. Host-facing `math.substitute` wraps the
result in a `Formula` value with `unit: None`, `display: false`, span of the
call site.
## 6. Host-facing surface (`math.*`)
All operations are builtins in `crates/marqdo-ir/src/builtins.rs`, dispatched
in `crates/marqdo-runtime/src/builtins_impl.rs`, and executed in the host
adapter `crates/marqdo-host/src/kernels.rs`. `math` capability is checked
before touching the kernel.
| Builtin | Parameters | Result |
|---|---|---|
| `math.parse` | `formula: Formula or Text` | `Formula` (source = input; `unit=None`, `display=false`); parse errors are `math.unsupported` |
| `math.eval` | `formula: Formula or Text`, `bindings: Map`, optional `target: Text` | `Int` or `Float`; equation requires target |
| `math.substitute` | `formula: Formula or Text`, `bindings: Map` | `Formula` with canonical source |
| `math.simplify` | `formula` | **not implemented**: runtime error `math.unsupported` ("not part of the supported math subset in this build") |
| `math.differentiate` | `formula`, `变量` | **not implemented**: `math.unsupported` |
Input typing:
* formula arguments accept a `Formula` value or `Text`; anything else is
`runtime.type`;
* `bindings` must be a `Map` whose values are `Int` or `Float`; any other
value type is `runtime.type` with a message naming the binding;
* `target` must be `Text` or `None`; other types are `runtime.type`;
* builtin arity/parameter-name mistakes are catchable statically
(`call.arity`, see `spec/mapping.md` §6);
* the math kernel is a pure computation: no file, network, process or plugin
effects, and nothing it returns is a capability.
### 6.1 Error mapping
Host mapping (`crates/marqdo-host/src/kernels.rs::math_error`):
| `MathErrorKind` | Runtime code |
|---|---|
| `Parse` | `math.unsupported` (message includes the byte offset when known) |
| `Unsupported` | `math.unsupported` |
| `UndefinedVariable` | `symbol.unknown` |
| `Type` | `runtime.type` |
## 7. What this is not
* Not a computer-algebra system: no simplification, differentiation,
integration, matrices, series, assumptions, units or symbolic rewriting.
* Not a theorem prover: `F = m a` is an equation value, not a proof, and a
numeric solve is not a certificate.
* Not a LaTeX renderer: rendering is the Markdown reader's job; the kernel only
receives the raw `latex` text of a `math` node.
* Not error-free in the floating-point sense: approximation precision is
documented, not guaranteed beyond binary64.