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

97 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.