Files
marqdo-cli/spec/evaluation.md
T
cflmy 1377af1601 feat(stdlib): ship a verified bundled stdlib with std: imports
- Move the Compat-A print prototype into stdlib/ as the official offline
  bundle with stdlib.json (version 0.1.0 + sha256 content digest).
- Add std:<relative> import resolution in the loader with bundle path
  confinement, extension inference and fail-closed digest verification.
- Record the verified version/digest/instance_id in Analysis v2
  project.stdlib; stdlib modules get a std:name@version#digest instance id.
- Add CLI tests: std:io execution, digest-tamper rejection, missing manifest,
  Analysis identity, no foreign/plugin calls, and frozen binary hash equality.
- Update ADR-0028, specs, status, changelog and evidence.

Gate: fmt, clippy -D warnings, 415 tests passed.
2026-11-20 21:43:14 +08:00

17 KiB

Marqdo Evaluation Semantics v1

Status: frozen for M0.5; extended by ADR-0022 (Memory) and ADR-0024 (recoverable results). 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
Memory opaque runtime-owned addressable byte region (ADR-0022); copies share identity, offsets are region-relative
Resource opaque host-issued resource/stream handle (ADR-0025); not indexable, not wire-transferable, rendered as Resource

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.
  • The only other writable place is an index into a Memory region (m[offset] = byte, ADR-0022). List, Map and Table values keep their v1 value semantics; list[i] = value, map[key] = value and obj.field = value are not defined and are rejected at run time or parse time rather than silently changing those values into shared mutable objects.
  • For m[offset] = byte the operands are evaluated exactly once in the order base, offset, right-hand side. The target must evaluate to Memory, the offset to a non-negative Int inside the region and the value to an Int in 0..=255; otherwise the statement fails without writing anything.
  • 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.

3.1 Addressable Memory (ADR-0022)

Memory is a separate storage domain from managed List/Map/Table values. It exists so .mq.md programs can construct allocators, encodings and data structures without a new Markdown node, keyword or host operation.

  • Creation. memory.new(initial_pages, max_pages) creates a zero-filled region and returns its handle. Both arguments are non-negative Ints; initial_pages <= max_pages, and max_pages must fit the per-region budget. Rejection is atomic: no region or committed byte is created.
  • Page size. One logical page is 64 KiB (PAGE_SIZE). Print, trace and storage use bytes; page counts never mix with byte offsets.
  • Size and growth. memory.size(memory) returns committed pages. memory.grow(memory, pages) is grow-only and returns the old page count; old offsets keep their bytes, every new byte is zero. A failed grow (declared maximum, region budget or total budget) leaves the region and the budget unchanged. Growing by zero pages is a no-op returning the current count. Regions never shrink and there is no user-visible free(region).
  • Read/write. m[offset] returns an Int in 0..=255; m[offset] = byte writes one byte. Offsets are non-negative and region-relative; negative, out-of-range and unrepresentable BigInt offsets are runtime.index. Out-of-range byte values are runtime.type. No implicit truncation or wrapping occurs.
  • Identity and equality. Copying a Memory value, passing it to a function or storing it in a collection shares the same region. Two handles are == only when they designate the same region instance; Memory has no ordering comparison and no byte-content equality operator.
  • Lifetime. A region lives for one run and is dropped with the runtime. Block-level ownership (malloc/free) is a standard-library concern; the runtime only guarantees that a single access stays inside its region.
  • Diagnostics. Unknown, stale or cross-run handles are runtime.memory; budget failures are resource.exhausted; a non-Memory index-assignment base is runtime.type.
  • Boundary. A live handle never crosses the wire: to_wire emits only {"type":"memory"}, decoding that tag is a WireError::Invalid, and every host/plugin/foreign call rejects arguments containing Memory.
  • Display. Value::display() renders Memory without the internal region identity; 类型(m) returns "Memory".

3.2 Recoverable results (ADR-0024)

A recoverable failure is an ordinary Map, not a new value type or syntax:

success: {ok: true,  value: <any Value>}
failure: {ok: false, code: <Text>, message: <Text> [, details: <Map>]}

ok is always a Bool. Success carries value; failure carries a stable dot-separated code and a human-readable message. Constructors such as 成功/失败 are ordinary .mq.md functions, not builtins.

  • Expected conditions (no free block, malformed parser input, invalid byte sequence, and later EOF/short I/O results) should use this shape so a caller can branch on ok.
  • Language-invariant violations (wrong type, out-of-bounds, unknown/stale Memory handle, budget exhaustion, capability denial) remain fatal RuntimeErrors. There is no catch mechanism and a library must not try to convert them into Err.
  • map.get returning None is a lookup result, not this convention; use map.has to distinguish a stored None (ADR-0023).
  • code is stable within its library; callers must not branch on message. Recommended prefixes include alloc.*, parse.*, codec.*, table.* and, later, io.*.
  • Stream EOF/partial semantics belong to the resource ABI (CM-A06); this section only reserves the shape {ok: true, value: {count, eof, ...}} for later, without defining it.

3.3 Resource streams (ADR-0025)

Resource is a host-issued opaque handle to an external stream, in a separate domain from Memory. It is not indexable, not a byte address and cannot be constructed from a number, document or wire value.

resource.open(kind: Text, descriptor: Text, rights: List) -> Resource
resource.read(handle, memory: Memory, offset: Int, max_bytes: Int)
    -> {ok:true, value:{count:Int, eof:Bool}} | {ok:false, code, message}
resource.write(handle, memory: Memory, offset: Int, length: Int)
    -> {ok:true, value:{count:Int}} | {ok:false, code, message}
resource.close(handle)
    -> {ok:true, value:None} | {ok:false, code, message}
  • Providers: stdio/stdout with ["write"] (pure/project, console grant); file with ["read"] (project, fs_read grant, bounded by the 8 MiB file limit); file with ["write"] (project, fs_write grant, 8 MiB buffered write flushed on close, ADR-0026). Mixed rights and other kinds are resource.unsupported.
  • resource.read checks the destination Memory range before calling the provider, caps the request to the remaining buffer, writes the returned bytes and reports the actual count plus eof. EOF is success, not an error.
  • resource.write copies bytes out of Memory for the call only; a short write is a count. stdout output is charged to the output budget and delivered to the program stdout channel. A project-file write stream appends to a bounded host buffer and does not touch the filesystem until close; a failed close leaves the handle open with its buffer, and an unclosed writer never creates the file.
  • Reading/writing/closing an already closed handle returns {ok:false, code:"resource.closed"}. Forged/cross-run/stale handles are fatal runtime.resource; unsupported kind/rights/direction are resource.unsupported; capability/path denial is permission.denied; a writer buffer above 8 MiB is resource.exhausted and appends atomically.
  • Memory arguments never cross the host boundary as handles: the interpreter copies bytes for the call. Resource handles never cross the value wire.

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. Addressable-memory failures use the stable codes runtime.memory (unknown/stale handle, invalid page counts), runtime.index (offset outside the region, including negative or huge offsets), runtime.type (wrong operand type or byte value outside 0..=255) and resource.exhausted (region or run budget).

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, host process count, and addressable memory. Addressable memory has two independent budgets (ADR-0022): total committed bytes across all regions (DEFAULT_MAX_TOTAL_BYTES = 64 MiB) and committed bytes per region (DEFAULT_MAX_REGION_BYTES = 16 MiB, hence at most 256 pages of 64 KiB), overridable with --max-memory and --max-region-memory. Memory is a pure computation: it needs no capability grant and is available in pure, project and strict modes, subject to these budgets. 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)
memory.new (initial_pages: Int, max_pages: Int) -> Memory creates a zero-filled region; budgets are checked before allocation (ADR-0022)
memory.size (memory: Memory) -> Int committed page count
memory.grow (memory: Memory, pages: Int) -> Int grow-only; returns the previous page count, new bytes are zero
list.append (list: List, value) -> List new list with one appended value; input unchanged (ADR-0023)
list.concat (left: List, right: List) -> List new concatenated list; inputs unchanged
map.keys (map: Map) -> List Text keys in canonical sorted order
map.has (map: Map, key: Text) -> Bool key membership
map.get (map: Map, key: Text) -> Value stored value or None; use map.has when None is a legal value
map.set (map: Map, key: Text, value) -> Map new map with the key; input unchanged
map.remove (map: Map, key: Text) -> Map new map without the key; missing key is a no-op
text.codepoints (text: Text) -> List Unicode scalar values as Int, in order
text.from_codepoint (codepoint: Int) -> Text or None None for a surrogate or a value outside 0..=0x10FFFF
table.columns (table: Table) -> List header names in column order
table.row (table: Table, row: Int) -> List new list of row cells; non-negative coordinate
table.cell (table: Table, row: Int, column: Int) -> Value cell value; non-negative coordinates
resource.open (kind: Text, descriptor: Text, rights: List) -> Resource capability-checked stream open (ADR-0025)
resource.read (handle, memory: Memory, offset: Int, max_bytes: Int) -> Result bounded chunk read into Memory; {count,eof}
resource.write (handle, memory: Memory, offset: Int, length: Int) -> Result bounded byte write; {count}
resource.close (handle) -> Result releases the host slot
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

The legacy 打印/print builtin remains the default and still uses the host output path. stdlib/ (the bundled standard library, std: imports) contains an explicitly imported .mq.md format/utf8/io prototype (ADR-0027 Compat-A) whose output is comparison-tested against 打印 for Unit/None/Bool/Int/Float/Text/List/Map/Table; it does not replace the builtin, and Formula/Code/FunctionRef/PluginHandle formatting is not yet expressible in the standard library.

The list.*, map.*, text.* and table.* entries are observation and construction primitives, not algorithms (ADR-0023). They return new values and never mutate their arguments. Sorting, filtering, joining, grouping, JSON/CSV and table transformations remain standard-library work: adding one must not add a builtin. map.get returns None for a missing key; map.has is the unambiguous membership check when a stored None is possible. table.row and table.cell use non-negative coordinates, while List indexing keeps its v1 negative-index rule.