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).
141 lines
6.9 KiB
Markdown
141 lines
6.9 KiB
Markdown
# 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:
|
|
|
|
1. **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`/`inspect` harder to reason about.
|
|
2. **Hard error.** Ordinary Markdown documents routinely use `**bold**`,
|
|
`*italic*`, `1. ordered` and `> quotes` in 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
|
|
|
|
1. 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 by `crates/marqdo-frontend/src/map.rs`.
|
|
2. Outside every function body, `strong`, `emph`, `list` and `block_quote`
|
|
nodes are **inert document content**. They are not mapped to IR, are not
|
|
executed, and prose is not inspected for keywords.
|
|
3. The frontend emits a **warning** `markdown.inert_executable` for every
|
|
would-be execution node found outside a function body. The document still
|
|
compiles and runs; only `check`'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 `## function` heading.
|
|
* `block_quote` → "a block quote invocation ... is inert document content";
|
|
* `list` → "a list control structure ...";
|
|
* `paragraph` → the first `strong`/`emph` found 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`/`emph` nested 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).
|
|
4. Warnings do not change exit codes: `check` exits 0 when there are no error
|
|
diagnostics even if warnings exist; `run`/`call` execute normally. JSON
|
|
`check` output sets `success = (errors == 0)` and includes the warning
|
|
entries in `diagnostics`.
|
|
|
|
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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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").
|
|
4. **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.
|
|
5. **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:
|
|
|
|
```text
|
|
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_executable` is 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_execute` asserts the warning
|
|
and that the function index is still built.
|
|
* `units.rs` tests for function ranges, nested sections, root-level `## main`
|
|
and duplicate/empty headings.
|
|
* `crates/marqdo-frontend/src/analyze.rs` tests 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/tests` and `tests/`
|
|
(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 `## function` headings;
|
|
* 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 `check` flag so existing documents can be migrated.
|