Files
marqdo-cli/spec/evaluation.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

6.6 KiB

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; module-local, refuses ambiguous resource units (ref.ambiguous)
math.parse/eval/substitute see spec/math.md P5; math.simplify/math.differentiate are declared but return math.unsupported in this build
foreign.run/call see spec/foreign.md P5, capability-gated
fs.read/write see spec/security.md capability-gated