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).
6.9 KiB
ADR-0002: Executable nodes execute only inside level-2 function bodies
Status: Accepted Date: 2026-11-20
Context
The blueprint (§1.2 execution context, §3.2 control flow, unresolved issue
S-03) establishes that Strong (execute), Emph (return), ordered lists
(branch), bullet lists (loop) and block quotes (call) have program meaning
inside a function body, i.e. inside the range of a level-2 heading. It
leaves the module top level under-specified: if a document has **x = 1**
before any function, should that be a hard error, a silent no-op, or an
explicit top-level statement?
Two failure modes had to be avoided:
- Silent execution at module scope. There is no function frame, no return
target and no entry point, so top-level effects would be surprising and
would make
check/inspectharder to reason about. - Hard error. Ordinary Markdown documents routinely use
**bold**,*italic*,1. orderedand> quotesin prose. Treating every such node outside a function as a fatal compile error would make the language hostile to normal documentation and would break the "renders normally" goal.
The chosen baseline was: executable nodes only execute inside function bodies; elsewhere they are ordinary document content, but this must not happen silently.
Decision
- A function body is the child-block range of a
heading(level=2)up to the next heading of level ≤ 2 (crates/marqdo-frontend/src/units.rs,FunctionScope.body_start..body_end). Executable roles are assigned only inside those ranges bycrates/marqdo-frontend/src/map.rs. - Outside every function body,
strong,emph,listandblock_quotenodes are inert document content. They are not mapped to IR, are not executed, and prose is not inspected for keywords. - The frontend emits a warning
markdown.inert_executablefor every would-be execution node found outside a function body. The document still compiles and runs; onlycheck's diagnostic output reflects the warning. The warning is produced once per top-level node and has a hint to move the construct under a## functionheading.block_quote→ "a block quote invocation ... is inert document content";list→ "a list control structure ...";paragraph→ the firststrong/emphfound in the paragraph ("an execution statement" / "a return statement").- warnings are emitted only while scanning the document's direct top-level
blocks: headings, tables, code/math blocks and other non-paragraph blocks
produce none. A top-level paragraph is walked recursively, so a
strong/emphnested under a link or strikethrough inside that paragraph can still produce the inert warning. Nodes inside a function body produce no warning (they are mapped or rejected by the strict executable-shape rules instead).
- Warnings do not change exit codes:
checkexits 0 when there are no error diagnostics even if warnings exist;run/callexecute normally. JSONcheckoutput setssuccess = (errors == 0)and includes the warning entries indiagnostics.
Rationale for the nodes covered: these are exactly the block-level constructs
that map.rs would otherwise turn into statements if a function body existed.
Inline nodes inside a paragraph are covered by one paragraph-level warning
rather than one per node, which keeps normal prose readable.
Alternatives
- Hard error for every executable-looking node outside a function. Rejected (see context); it forbids emphasis in ordinary Markdown and makes writing a README a compile failure.
- Silent inert behaviour with no diagnostic. Rejected: an author could
believe top-level
**x = 1**had executed. The blueprint explicitly wants invalid execution intent surfaced. - Execute top-level nodes in an implicit module frame. Rejected: no defined entry semantics, no return target, would make imported modules potential side-effect roots (violating "modules register definitions only").
- Compile-time error only when the payload parses as a statement. Rejected: this is the forbidden heuristic ("parses as code → execute") from blueprint §1.3; role must come from node type and position, not from guessing.
- Warning per AST node. Rejected as noisy for nested content; one warning per top-level construct is enough to point at the problem.
Markdown AST shape
No new node kinds. Relevant structure:
document
heading(level=2) "f" <-- opens a function body
paragraph -> strong(text "x = 1") <-- executes (Stmt::Assign)
paragraph (before any heading)
strong(text "x = 1") <-- inert; emits markdown.inert_executable
list(ordered) <-- inert outside function; warning
block_quote <-- inert outside function; warning
A level-2 heading without a preceding level-1 heading is a module-root function
(## main) and its body executes normally. A ### section inside the function
range stays inside the function body; headings never execute.
Compatibility
- Warning code
markdown.inert_executableis part of the CLI diagnostic contract. Renaming it requires an ADR and a CLI version note. - Making this a hard error later would be a breaking language change: documents that currently compile (with warnings) would stop. If that is ever desired it needs a migration plan (e.g. an opt-in strict lint).
- No package/ABI/IR shape change: inert nodes are simply absent from the IR.
- Prose invariance is preserved: editing narrative text outside functions cannot change the IR.
Security
No effect: inert nodes never reach the interpreter, host or kernels. The warning reduces the chance of a false belief that a side effect happened, which is a security-relevant honesty property. A document cannot cause an execute-by-accident through top-level prose.
Testing
crates/marqdo-frontend/src/units.rs::tests:: executable_outside_function_warns_but_does_not_executeasserts the warning and that the function index is still built.units.rstests for function ranges, nested sections, root-level## mainand duplicate/empty headings.crates/marqdo-frontend/src/analyze.rstests hard errors for invalid executable shapes inside function bodies (the companion rule: when a node is executable, its shape is strictly checked).- Conformance/negative fixtures under
crates/cli/testsandtests/(work in progress by the fixtures workstream) are expected to cover the warning and the inert behavior;spec/mapping.md§4 documents the contract.
Migration & rollout
M0.5 ships with warnings. Rollout guidance:
- document authors move executable constructs under
## functionheadings; - tooling should show the warning in editors (the diagnostic already has a precise span);
- if a future release makes inert execution a hard error, add a deprecation
window and a
checkflag so existing documents can be migrated.