Files
marqdo-cli/spec/evaluation.md
T
cflmy e26971f489 feat(cli): route print through the bundled stdlib (Compat-B)
- Add Program.print_override and lazy stdlib injection: only programs that
  call 打印/print load std:io and route to io.写值 (ADR-0030).
- Record resource.open/read/write/close as trace effect events so the stdlib
  print path is auditable; HostOp::Print no longer runs on that path.
- Permit only stdio/stdout (existing console) in strict; file/network
  resource opens remain permission.denied.
- Exclude std: modules from the human-readable checked-module count; update
  the Python analysis consumer to accept std: instance ids.
- Add print-routing and strict-console tests, ADR-0030 and evidence.

Gate: fmt, clippy -D warnings, 418 tests passed.
2026-11-20 22:10:59 +08:00

307 lines
18 KiB
Markdown

# 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` |
Read-only observation members:
| Value | Members |
|---|---|
| Formula | `latex`, `display`, `unit` |
| Code | `language`, `source`, `content_hash`, `unit` |
| FunctionRef | `module`, `name` (ADR-0029) |
| PluginHandle | `plugin`, `export` (ADR-0029); the numeric host id stays private |
| Memory, Resource | no fields (opaque) |
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 `Int`s;
`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:
```text
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
`RuntimeError`s. 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.
```text
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, and strict's
existing console channel, 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 |
`打印/print` is **Compat-B** (ADR-0030): when the verified bundled stdlib is
available and a loaded module calls the builtin, the loader injects
`stdlib/io.mq.md` and sets a program-level `print_override`; the runtime calls
`io.写值` instead of `HostOp::Print`. The stdlib chain formats every one of the
15 value types, encodes UTF-8 into `Memory`, and writes via
`resource.write(stdout)`. The legacy builtin remains the fallback when no bundle
is available. Compat-C (removing the legacy formatting path) is not done.
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.