Update status, compatibility, changelog, README, architecture overview,
ADR status, migration guide, contributor/CI/security/release notes and
the per-file inventory from 'migration pending' to the verified state:
- language SHA ffd1cc9: fmt/clippy clean, workspace 501 passed / 0 failed
/ 2 ignored, stdlib digest regenerated and pack-verified
- green evidence report added; the prior intermediate evidence is marked
superseded
- inventory regenerated: 1015 classified files, 0 pending
- explicit non-claims: Windows/macOS native lanes and the disposable-VM
strict lane were not re-run at this SHA, so the release decision remains
DO NOT RELEASE
Verified: cargo test -p marqdo-cli --test docs_consistency (4/4) and
git diff --check.
4.9 KiB
ADR-0052: Unified Markdown semantics — heading modes, unified payloads and keyword control flow
Status: Accepted and implemented
Date: 2026-11-21
Supersedes: ADR-0002 in part (executable roles), the AST→program mapping in
spec/mapping.md and the statement layer in spec/expression.ebnf
Specs: spec/mapping.md, spec/expression.ebnf
Authority: docs/architecture/RFC-LANG-0002-unified-semantics.md
Tracks: docs/migration/semantic-rewrite-inventory.tsv
Context
The previous language mapping binds program meaning to Markdown presentation:
Strongexecutes;Emphreturns;- an ordered list is a branch;
- a bullet list is a loop;
- a block quote is a call;
- an H2 is unconditionally a function and a standalone code span after it is a signature.
That makes ordinary document structure impossible to use freely inside a function, forces control flow to depend on list type and nesting, and gives inline code a signature privilege no other carrier has. It also means a parse failure can only be reported as a shape error, because there is no separate statement syntax to parse.
Decision
Adopt a single, breaking Markdown→program mapping. There is no V1/V2
coexistence, no per-file syntax selector and no --legacy path.
- Heading modes. H1–H6 may start their first plain Text child with an
exact
@execor@knowledgedeclaration followed by whitespace and a non-empty name. Unmarked headings inherit the nearest ancestor heading's mode; the document root is Knowledge. The declaration is stripped from the semantic heading name. - Function boundary unchanged. Only an Exec H2 is a callable function. H2
Knowledge is an inert knowledge unit. H3–H6 are sections and never create
callables. A payload with no owning Exec H2 is
sem.exec_without_function. - Unified payloads. In an Exec scope,
Strong,Emphand inlineCodeare interchangeable carriers of one statement. Only direct Text/Code children are extracted; nested carriers aresem.payload_nested; each AST carrier is extracted at most once. - Keyword control flow. A payload is exactly one of
if,else,while,end,return,params(...), assignment or expression.if/whileare closed by an explicitend;elseis optional. Lists, block quotes and paragraphs are containers with no instruction type. - Segments. A control block may not cross a heading boundary. Each heading's direct body is one segment; the stack must be empty at every boundary. Complete segments append to the owning H2 function in source order.
- Signatures. An optional
params(...)statement is legal only as the first direct payload of an Exec H2; otherwise free-variable inference applies. The old standalone code-span signature is removed. - IR unchanged in kind. Control words lower to the existing
Assign/Eval/Branch/Loop/Return. NoHostOp, no second interpreter, no runtime knowledge of Markdown. - Security unchanged.
@execis not a capability grant.@knowledgeproduces no IR and therefore no effects. - Errors never fall back to prose. A malformed payload in an Exec scope is a hard diagnostic; spelling errors in mode declarations are hard errors, not inherited modes.
Consequences
- Every
.mq.mdsource in the repository — stdlib, examples, fixtures, Rust embedded samples, docs — must be migrated. Old syntax must not remain a supported active language. spec/mapping.mdandspec/expression.ebnfare replaced in place; there is no second active spec. Historical material is archived with a banner.- Normal emphasis in an Exec section becomes a payload and may fail as an
unknown symbol. Authors must use
@knowledgesections for purely visual emphasis. This is accepted as the price of determinism. - The Rust frontend, expression parser, bundled stdlib, examples and fixtures
were migrated in the
semantics-v2-refactorhistory and the workspace gate is green atffd1cc9(seedocs/STATUS.mdanddocs/evidence/2026-11-21-semantics-v2-green.md). Platform/strict evidence is tracked separately and is not implied by the language gate. - Migration is AST-role based, not a global regex rewrite; ambiguous cases stop for manual rewrite.
Alternatives rejected
- Keep both mappings per file. Rejected: two active specs, unstable semantics for the same source, permanent maintenance and accidental execution.
- Infer control flow from list shape. Rejected: ordinary prose lists would execute and parse errors could silently become documents.
- Use
mq execfenced blocks only. Rejected: loses native Markdown document structure and the language's purpose. - Bind
endto indentation or list nesting. Rejected: reformatting would change control flow. - Treat emphasis type as intent. Rejected: no deterministic way to tell emphasis from execution from the AST.