Files
marqdo-cli/spec/math.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

11 KiB
Raw Permalink Blame History

Marqdo Math v1

Status: frozen subset (math v1); product baseline 3.0.0-beta.1. 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).

# @knowledge 数学

## @knowledge 圆面积公式

$$
A = \pi r^2
$$

## @exec 计算圆面积

`params(r: Number)`

`面积 = math.eval(ref("#圆面积公式"), {"r": r}, target="A")`
`return 面积`

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):

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.