Files
marqdo-cli/docs/adr/0052-unified-markdown-semantics.md
cflmy bbeb1de768 docs(status): record the landed RFC-LANG-0002 implementation
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.
2026-11-21 12:31:38 +08:00

4.9 KiB
Raw Permalink Blame History

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:

  • Strong executes;
  • Emph returns;
  • 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.

  1. Heading modes. H1–H6 may start their first plain Text child with an exact @exec or @knowledge declaration 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.
  2. 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.
  3. Unified payloads. In an Exec scope, Strong, Emph and inline Code are interchangeable carriers of one statement. Only direct Text/Code children are extracted; nested carriers are sem.payload_nested; each AST carrier is extracted at most once.
  4. Keyword control flow. A payload is exactly one of if, else, while, end, return, params(...), assignment or expression. if/while are closed by an explicit end; else is optional. Lists, block quotes and paragraphs are containers with no instruction type.
  5. 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.
  6. 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.
  7. IR unchanged in kind. Control words lower to the existing Assign/Eval/Branch/Loop/Return. No HostOp, no second interpreter, no runtime knowledge of Markdown.
  8. Security unchanged. @exec is not a capability grant. @knowledge produces no IR and therefore no effects.
  9. 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.md source in the repository — stdlib, examples, fixtures, Rust embedded samples, docs — must be migrated. Old syntax must not remain a supported active language.
  • spec/mapping.md and spec/expression.ebnf are 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 @knowledge sections 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-refactor history and the workspace gate is green at ffd1cc9 (see docs/STATUS.md and docs/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 exec fenced blocks only. Rejected: loses native Markdown document structure and the language's purpose.
  • Bind end to 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.