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.
97 lines
4.9 KiB
Markdown
97 lines
4.9 KiB
Markdown
# 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.
|