Files
marqdo-cli/spec/evaluation.md
T
cflmy 55a2b2d82d spec(P0): freeze markdown profile, AST mapping, expression grammar and evaluation semantics
Add the formal specifications required before implementation:

- spec/markdown-profile.md: parser version, exact option table, byte spans,
  BOM policy, front matter rule, AST JSON view, structural equivalence.
- spec/mapping.md: normative AST-to-program mapping (heading scopes, lazy
  regions, strong/emph/list/blockquote roles), strict payload extraction and
  the hard-error checklist. Invalid executable shapes never degrade to prose.
- spec/expression.ebnf: the small independent expression/statement grammar
  (Unicode identifiers, arbitrary precision integers, precedence, named
  arguments, no comments, no truthiness).
- spec/evaluation.md: value model, exact integer semantics, scopes, order,
  parameter inference via definite-assignment data flow, budgets and the v1
  builtin table.
2026-11-20 10:26:15 +08:00

131 lines
6.5 KiB
Markdown

# Marqdo Evaluation Semantics v1
Status: **frozen for M0.5**. Changes to observable behaviour require an ADR.
## 1. Values
| Type | Meaning |
|---|---|
| `Unit` | no result; a function that falls through returns `Unit` |
| `None` | explicit empty value; distinct from `Unit` |
| `Bool` | `true` / `false`; the only type usable in conditions |
| `Int` | arbitrary precision integer (`num-bigint`) |
| `Float` | IEEE-754 binary64 |
| `Text` | Unicode string |
| `List` | ordered values |
| `Map` | string-keyed record with deterministic (sorted) key order |
| `Table` | header names + rows of values (from GFM tables) |
| `Formula` | inert parsed LaTeX + provenance; math operations are explicit |
| `Code` | inert code fence + provenance; execution is explicit |
| `FunctionRef` | reference to a named function in a module |
| `PluginHandle` | opaque host-owned plugin export handle |
There is no truthiness: `if`-like conditions accept `Bool` only. There are no
implicit string↔number conversions; conversion builtins must be called.
## 2. Numeric semantics
* `Int` arithmetic (`+ - * // % **`) is exact. `/` always produces `Float`.
* Mixed `Int`/`Float` arithmetic yields `Float`; the conversion of an `Int`
larger than 2^53 may lose precision and this is documented, not silently
exported as a rounded `Int`.
* Comparisons between `Int` and `Float` are **exact** (the float is treated as
the exact binary rational it is); no lossy comparison is performed.
* `//` and `%` require `Int` operands. Floor division: `a // b` is the
mathematical floor; `a % b == a - b * (a // b)` (sign follows divisor).
* Division/modulo by zero is `runtime.division_by_zero`.
* `+` also concatenates two `Text` values. No other operator is overloaded.
* `**` on `Int` uses exact exponentiation; a negative exponent is a type error
(use `/` or `Float` operands for fractional results). Exponents above a
configurable budget are `resource.exhausted`.
* Floats may be `NaN`/`±Infinity` only as results of operations; they are
tagged explicitly on the wire. NaN compares unequal to everything.
## 3. Evaluation order and scopes
* Blocks execute in Markdown AST document order; executable inline nodes
execute in source order within a paragraph.
* A function call evaluates its arguments in source order, exactly once each,
then binds them to fresh parameter slots in an isolated frame. The callee
cannot see the caller's locals (no dynamic scoping); imported bindings are
read-only.
* Assignment binds/updates a local slot in the current frame. It never writes
an outer frame. There is no module-level assignment in v1: assignment
outside a function body is an error.
* `and`/`or` short-circuit and require `Bool` operands.
* `Return` (an `emph` node) unwinds through branch/loop bodies to the
enclosing function frame.
* `Branch` checks conditions in AST order and executes the first `true` branch
once. `Loop` re-evaluates its condition before each iteration.
* Imported modules only register definitions for the importing document; they
have no initialization side effects and their `main` is never started.
* Function calls recurse; recursion depth is bounded by the stack budget.
Mutual recursion is allowed.
## 4. Errors
All failures are structured. Compile-time problems produce diagnostics
(`markdown.invalid_construct`, `expr.parse`, `symbol.unknown`, …). Runtime
problems produce `RuntimeError { category, span, message, frames, cause }`
with a stable category code. Runtime errors stop the current function and
propagate with a call stack. A host/foreign/plugin failure never panics the
interpreter; it becomes a structured error.
## 5. Parameter inference (static, name based)
Parameters are discovered by definite-assignment data-flow analysis over the
function's control-flow graph, never from prose:
1. Build the CFG of the function body in AST order, with branch and loop
edges. Loop bodies may execute zero times.
2. Compute the set of variables *definitely assigned* on every path from the
function entry.
3. Every read of a variable that is not definitely assigned at that point and
that has no assignment anywhere in the function is a **candidate
parameter** (sorted by canonical name).
4. If a variable is assigned on some paths but read before that assignment on
others, its identity is ambiguous: emit `symbol.uninitialized` (S-04)
instead of inventing a parameter.
5. Exclude builtins, imported aliases and reserved names from inference.
6. A read that is not explained by a parameter, a local, a builtin or an
import is `symbol.unknown` with a hint (typo protection).
Consequences: `**结果 = n * 阶乘(n=n-1)**` infers `n`; `**n = 3**` followed by
reads makes `n` a local. Inferred parameters are named arguments only; an
explicit signature paragraph allows positional arguments.
## 6. Resource budgets
Every run has explicit limits (all configurable, all reported as
`resource.exhausted`): evaluation fuel, call stack depth, total output bytes,
wall-clock time, and host process count. Loops consume fuel per iteration and
expressions per node so that a hostile document cannot hang the CLI. Strict
mode additionally enforces limits at the OS level where available; if the
platform cannot provide that, strict mode refuses to run (see `security.md`).
## 7. Determinism
For a fixed source, mode, capabilities and budget, evaluation is
deterministic. Stdout/stderr from host operations are separated: program
output goes to stdout, diagnostics/traces go to stderr, and `--json` output
never mixes with program output.
## 8. Builtins v1
Builtins are part of the language surface and are capability-checked at the
host boundary. Names are stable; adding one requires a spec update.
| Name | Signature | Notes |
|---|---|---|
| `打印` / `print` | `(x) -> Unit` | writes `Value::display()` + newline to stdout |
| `长度` / `len` | `(x) -> Int` | Text scalar count, List/Map/Table size |
| `类型` / `type` | `(x) -> Text` | value type name |
| `文本` / `str` | `(x) -> Text` | explicit conversion |
| `整数` / `int` | `(x) -> Int` | from Int/Float(if integral)/Text(decimal) |
| `小数` / `float` | `(x) -> Float` | from Int/Float/Text |
| `表` / `table` | `(header: List, rows: List) -> Table` | validates row widths |
| `ref` | `(target: Text) -> FunctionRef/Formula/Code` | resolves a document address |
| `math.parse/eval/simplify/differentiate` | see `spec/math.md` | P5 |
| `foreign.run/call` | see `spec/foreign.md` | P5, capability-gated |
| `fs.read/write` | see `spec/security.md` | capability-gated |