Master now contains the fast-forwarded RFC-LANG-0002 series; the former semantics-v2-refactor branch was deleted, so only master remains. - STATUS lists the full linear series (docs, implementation, expression grammar, status, seven follow-up fixes) and the verification at9c1723d: fmt/clippy clean, 507 passed / 0 failed / 2 ignored, stdlib digest verified - counts updated to 49 compile-negative fixtures and 507 workspace tests across README, COMPATIBILITY, CHANGELOG, CURRENT and the migration guide - green evidence pins code commit9c1723dand lists the follow-up fixes; CHANGELOG gains the follow-up correctness section - migration inventory regenerated: 1019 classified files, 0 pending - CURRENT.md baseline is the 40-hex9c1723dcommit required by the docs gate Verified: docs_consistency 4/4, fmt, clippy -D warnings and the full workspace suite green; python3 tools/pack-stdlib.py PASS.
6.2 KiB
Semantic rewrite: migration guide and inventory
Status: complete. The language contract is
RFC-LANG-0002 and
spec/mapping.md; the frontend, statement parser,
runtime and bundled stdlib implement it. See ../STATUS.md
and the green gate in
../evidence/2026-11-21-semantics-v2-green.md.
This directory records the repository-wide migration required by the RFC:
every active .mq.md source, example, fixture and documentation snippet must
use the single new syntax. Old syntax is not an active language.
Current state (2026-11-21)
- Complete. Specs, active docs, examples, all test/fixture
.mq.mdfiles, the security-lane embedded fixtures, Rust-embedded literals and the bundledstdlib/**/*.mq.mdsources use the single syntax. 1019 present tracked+new files are classified in the inventory: 0pending, 0pending-implementation. - Implementation: frontend heading modes and segments, the unified payload
mapper, the
marqdo-expressionstatement grammar, control-stack lowering,params(...)/inference and thesem.*diagnostics are implemented. - Verification at
9c1723d:cargo fmt --check,cargo clippy -D warningsandcargo test --workspace --locked(507 passed, 0 failed, 2 ignored) all pass;python3 tools/pack-stdlib.pyverifies the regenerated digest. Evidence:../evidence/2026-11-21-semantics-v2-green.md. The earlier intermediate record is kept at../evidence/2026-11-21-semantic-docs-migration.md. - Old v1 compile-negative fixtures were deleted and replaced by new-semantic negatives; they are intentionally absent from the inventory rather than counted as reviewed.
- Platform CI and the disposable-VM strict lane were not re-run by the language migration; they remain separate release gates.
Migration rules for this repository
- One syntax. Do not add
marqdo_semantics,--legacy,syntax: v1or a second example. Old syntax is either migrated or marked historical. - Exec H2 is explicit. Write
## @exec 名称for every callable function, even under an Exec H1. Heading names keep the original semantic name (## @exec 阶乘, not## @exec @exec 阶乘). - Mode on H1. Prefer an explicit
# @knowledge 名称for document namespaces and# @exec 名称only when the whole namespace is executable. - One payload, one statement. Use a standalone inline code span by default
(
`x = 1`) because it is Markdown-unambiguous. Use**...**or*...*when the fixture is specifically testing carrier equivalence. - Control flow.
if <expr>…[else]…end;while <expr>…end. A control block never crosses a heading.return <expr>replaces the old italic return. - Branch migration. An ordered list with N arms is first true arm wins.
Convert N arms to a nested if/else chain (an inner
ifinsideelse), not to N independentifs. A single arm becomesif. A bullet list is a sequence of independentwhileloops, one per item, in item order. - Calls.
> print(x)was an old call; in the new language it is inert prose. Write> **print(x)**,`print(x)`or a plain paragraph payload. A block quote itself never calls. - Signatures. The first standalone code span
(n: Int)becomesparams(n: Int)as the first direct payload of the Exec H2. Keep parameter names, order and defaults. - Knowledge. Purely visual emphasis and explanatory lists belong in
@knowledgesections. AStronginside an Exec section is a payload and must be a valid statement. - Preserve meaning. Do not change function names, argument names/defaults,
evaluation order, early-return behavior, values, stdout or expected error
intent. For
.expected.jsonvalue goldens (return value/args/stdout), keep the file unless the semantic name really changed. - Expected diagnostics. Old shape errors about lists/quotes/emphasis
become valid inert Markdown, not errors. Replace them with new negatives for
sem.*codes (seespec/mapping.md§8). Keep genuine runtime negatives (bounds, type, permission) and only migrate their source spelling. - No silent golden regeneration. Do not run
UPDATE_*_GOLDENS=1to mask a semantic change. A golden update needs a stated new-semantic reason. - Tests are text-only here. Rust test strings and the
inittemplate text are migrated; the frontend, expression parser and stdlib.mq.mdsources are not. Those implementation items are tracked as pending in the inventory. Do not change protocol schemas or security logic in this migration. - Use the review aids, not them as proof.
tools/dev-only/check-mq-syntax.pycatches unbalanced control blocks and unknownsem.*codes;tools/dev-only/gen-migration-inventory.pyregenerates the inventory. Both are audit aids; the real gate is the migrated frontend plus the RFC §12 acceptance matrix.
Conversion examples
Old:
## 分类
1. `n < 0`
*-1*
2. `n == 0`
*0*
3. `n > 0`
*1*
New (first-true chain, explicit end):
## @exec 分类
`if n < 0`
`return -1`
`else`
`if n == 0`
`return 0`
`else`
`return 1`
`end`
`end`
Old loop:
## 求和
`(n: Int)`
**i = 0**
**sum = 0**
- `i < n`
**sum = sum + i**
**i = i + 1**
*sum*
New:
## @exec 求和
`params(n: Int)`
`i = 0`
`sum = 0`
`while i < n`
`sum = sum + i`
`i = i + 1`
`end`
`return sum`
Inventory
semantic-rewrite-inventory.tsv is generated from the tracked tree with
python3 tools/dev-only/gen-migration-inventory.py and records each file's
category, action and status. Columns:
path category active action verification status
Categories: spec, architecture, tutorial, example, stdlib, test,
rust-test, historical, non-semantic. Status: migrated, reviewed,
historical, pending-implementation, pending.
The final gate is 100% of tracked files classified and all active
.mq.md files migrated, not a grep with no matches.