diff --git a/AGENTS.md b/AGENTS.md index 765bf9c..fe6757d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Marqdo CLI — Agent / Contributor Operating Rules -**Start here:** read `docs/DEVELOPMENT_BLUEPRINT.md` before proposing code. It is the project architecture baseline. Then read `docs/STATUS.md` (what is actually implemented), the relevant `spec/` files, `docs/adr/` for frozen decisions, `docs/contributor-guide.md` for the workflow, and `tests/README.md` plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative. +**Start here:** read `docs/architecture/RFC-LANG-0002-unified-semantics.md` — it is the single current language authority — and its normative summary `spec/mapping.md` + `spec/expression.ebnf`. Then read `docs/DEVELOPMENT_BLUEPRINT.md` (architecture baseline; its language-mapping sections are historical), `docs/STATUS.md` (what is actually implemented, including the in-progress syntax migration), the relevant `spec/` files, `docs/adr/` for decisions at their date, `docs/contributor-guide.md`, and `tests/README.md` plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative. For next-phase work, the single authoritative plan is `docs/STABLE_RELEASE_IMPLEMENTATION.md` (stable-release gates G-A/G-B/G-C, @@ -21,29 +21,31 @@ correctness and release evidence before expanding the surface. 1. New independent language/toolchain. **Do not silently modify `cflmy/marqdo`** or claim compatibility with its syntax, package format or plugin ABI. 2. CommonMark/GFM/Math AST is the sole Markdown syntax structure. Do **not** implement a second Markdown parser or use regex heuristics to decide whether text is executable. -3. Executable roles are based on AST type and valid structural context: `Strong` execution, `Emph` return, ordered list branch, bullet list loop, blockquote invocation, heading scoping. Invalid executable shapes are compile errors, not ordinary prose fallbacks. -4. Prose and executable nodes may mix freely in one function/branch/loop body. Prose itself never causes an action. +3. The language has **one** Markdown→program mapping (RFC-LANG-0002): `@exec`/`@knowledge` heading modes with ancestor inheritance; only an Exec H2 is callable; `Strong`, `Emph` and inline `Code` are interchangeable one-statement payload carriers; `if`/`else`/`while`/`end`/`return`/`params` decide control flow; lists, block quotes and paragraphs are presentation containers with no instruction type. Invalid payloads are hard errors, never prose fallbacks. Do not reintroduce Strong=execute, Emph=return, ordered-list=branch, bullet-list=loop or block-quote=call, and do not add a per-file syntax switch, `map_v1`, `--legacy` or a second active spec. +4. Prose and executable payloads may mix freely in one function/branch/loop body. Prose itself never causes an action; executable payloads with no owning H2 Exec function are errors (`sem.exec_without_function`). 5. Marqdo is executed by **its own Rust interpreter**. Python/Node are optional foreign kernels, never the official compiler target. -6. Code fences and math expressions create inert native `Code` and `Formula` values. Evaluation requires explicit calls and relevant capability grants. -7. YAML project/dependency and frontmatter imports must be explicit. Markdown Links are static references, not implicit calls or imports. +6. Code fences and math expressions create inert native `Code` and `Formula` values. Evaluation requires explicit calls and relevant capability grants. Inline `Code` spans are payload carriers only in an Exec scope; fenced code is never executed. +7. YAML project/dependency and frontmatter imports must be explicit. Markdown Links are static references, never calls or imports. Calls are expressions inside executable payloads. 8. Third-party plugins require a versioned **C ABI and SDK**. A C ABI is not a sandbox. Default third-party execution must be isolated; in-process native loading requires explicit trust. 9. Side effects go through `CapabilityHost`; do not invent host bypasses for tests, plugins, math or foreign kernels. `check` and `inspect` cannot execute untrusted project code. 10. Language semantics, package format, ABI, authorization defaults or public CLI behavior changes require an ADR + tests + spec updates. +11. The current tree is **spec-first**: RFC-LANG-0002 and `spec/` describe the target language, while the Rust frontend, expression parser and bundled stdlib still implement the pre-RFC mapping. Do not claim the new syntax is implemented or make a release claim until the migration is complete and its gates are green; keep `docs/STATUS.md` honest. ## Development workflow -1. Identify the affected rule and cite the section of `docs/DEVELOPMENT_BLUEPRINT.md`. -2. Add a small `.mq.md` positive/negative conformance fixture and define the expected Markdown AST and execution IR. -3. Implement only the smallest module that satisfies this fixture. Keep Markdown parser, semantic mapper, runtime and host separated. -4. Run formatting, clippy, unit tests, gold tests and relevant security/ABI compatibility tests (`cargo fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace`, `cargo test -p marqdo-cli`). -5. Write the tradeoff and state of completion in the PR. Never say a feature is finished because a design example looks executable. Update `spec/` and `docs/STATUS.md` when behavior or status changes; the docs describe what the code does and flag blueprint divergences explicitly. +1. Identify the affected rule and cite RFC-LANG-0002 / `spec/mapping.md` (or, for architecture-only changes, the relevant `docs/DEVELOPMENT_BLUEPRINT.md` section). +2. Update the normative spec **in place** first; there is never a second active syntax spec. +3. Add a small `.mq.md` positive/negative conformance fixture and define the expected Markdown AST, execution IR and diagnostics. +4. Implement only the smallest module that satisfies this fixture. Keep Markdown parser, semantic mapper, expression parser, runtime and host separated. +5. Run formatting, clippy, unit tests, golden tests and relevant security/ABI compatibility tests (`cargo fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace`, `cargo test -p marqdo-cli`). +6. Write the tradeoff and state of completion in the PR. Never say a feature is finished because a design example looks executable. Update `spec/` and `docs/STATUS.md` when behavior or status changes; the docs describe what the code does and flag divergences explicitly. ## Unresolved design topics -The blueprint's section **17** lists issues that need separate Accepted ADRs (e.g. emphasis conflicts, parameter inference ambiguity, plugin memory ownership, strict platform isolation). Use its proposed baseline for prototypes, but do not freeze these topics through undocumented code. +RFC-LANG-0002 resolves the old emphasis/control-role conflict: `Strong`, `Emph` and inline `Code` are equivalent carriers and controls are keywords with explicit `end`. Remaining topics still need separate Accepted ADRs (parameter inference policy, plugin memory ownership, strict platform isolation, future `elif`/`for`/`break`, knowledge anchors). Do not freeze them through undocumented code. ## Priorities -P0 AST/grammar contracts → P1 independent interpreter → P2 references/CLI → P3 package/env → P4 sandbox → P5 math/foreign → P6 plugin ABI/SDK → P7 performance/release. Design the Host security boundary and ABI early, even if full implementation arrives later. +P0 language migration to RFC-LANG-0002 (frontend, expression parser, stdlib, fixtures) → P1 independent interpreter → P2 references/CLI → P3 package/env → P4 sandbox → P5 math/foreign → P6 plugin ABI/SDK → P7 performance/release. Design the Host security boundary and ABI early, even if full implementation arrives later. -**Never** translate Marqdo into Python as the official execution method; **never** silently downgrade an invalid execution node to prose or a requested strict sandbox to an unrestricted process. +**Never** translate Marqdo into Python as the official execution method; **never** silently downgrade an invalid payload to prose, a requested strict sandbox to an unrestricted process, or the current syntax to a legacy mapper. diff --git a/CHANGELOG.md b/CHANGELOG.md index 551db6b..37371b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,66 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. ## Unreleased (stabilization candidate) +### Breaking changes — language source syntax (RFC-LANG-0002) + +**The `.mq.md` source language changed incompatibly. Old source files are not +executable.** The current contract is +[`docs/architecture/RFC-LANG-0002-unified-semantics.md`](docs/architecture/RFC-LANG-0002-unified-semantics.md) +(accepted by [`docs/adr/0052-unified-markdown-semantics.md`](docs/adr/0052-unified-markdown-semantics.md)), +summarized normatively in [`spec/mapping.md`](spec/mapping.md) and +[`spec/expression.ebnf`](spec/expression.ebnf). + +- Removed the old mapping in which `Strong` executes, `Emph` returns, an + ordered list is a branch, a bullet list is a loop, a block quote is a call and + the first standalone code span is a signature. +- Headings now declare `@exec` / `@knowledge`; unmarked headings inherit the + nearest ancestor's mode, and the document root is Knowledge. +- Only an Exec H2 is a callable function; H2 Knowledge is inert and H3–H6 are + non-callable sections. A payload with no owning Exec H2 is + `sem.exec_without_function`. +- `Strong`, `Emph` and inline `Code` are interchangeable carriers of exactly one + statement; the AST kind no longer selects the operation. +- Control flow comes from keywords in the payload: `if`/`else`/`while`/`end` + (explicitly closed) plus `return ` and `params(...)`. Ordered lists, + bullet lists, block quotes and paragraphs are presentation containers with no + instruction type; a plain list or quote produces zero statements. +- `params(...)` is the only function-signature declaration, legal only as the + first direct payload of an Exec H2. An Emph/Strong payload in a signature + position is no longer special. +- There is no syntax version switch, per-file selector, `--legacy` path or + fallback mapper; `marqdo_semantics`/syntax-selection front matter is rejected. + +**This entry records the accepted target contract, not a finished +implementation.** The Rust frontend, expression parser and bundled stdlib in +this checkout still implement the pre-RFC mapping, so executable-source tests +are expected to be red until the migration lands; see +[`docs/STATUS.md`](docs/STATUS.md) and +[`docs/migration/README.md`](docs/migration/README.md). Do not describe this +candidate as accepting the new syntax. + +**Required migration actions for consumers and the repository:** + +1. Rewrite every active `.mq.md` source by AST role (not by a global regex): + stdlib modules, examples, fixtures, project templates, Rust-embedded samples + and documentation snippets. +2. Give callable functions an explicit `## @exec 名称` heading, or place them + under an `# @exec` namespace. Knowledge documents and visual emphasis belong + in `@knowledge` sections; a `Strong`/`Emph` payload in an Exec section is a + statement and may fail as an unknown symbol. +3. Replace italic returns with `return ` in any carrier. +4. Convert an ordered-list branch to a first-true nested `if`/`else`/`end` + chain; convert each bullet-list item to its own `while`/`end` loop, preserving + item order and early-return behavior. +5. Convert block-quote calls to payload calls (`**print(x)**`, + `` `print(x)` `` or `> **print(x)**`) and standalone code-span signatures to + `params(...)` as the first direct Exec H2 payload. +6. Replace old shape expectations with the `sem.*` diagnostics in + `spec/mapping.md` §8; ordinary lists/quotes are now valid inert Markdown. +7. Regenerate `stdlib/stdlib.json` only in the same change that migrates the + stdlib sources, and never use `UPDATE_*_GOLDENS=1` to mask a semantic change. +8. A dependency or lock built from old source syntax is not compatible; relock + and re-verify the package instance identity after migration. + ### Added - `.gitattributes` byte-identity policy: canonical LF for text files and one @@ -35,7 +95,9 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. compile-negative fixtures and 2 runtime-negative fixtures covering right-associative `**`, unary-minus precedence, parentheses, float negative exponents, Strong+CodeSpan payloads, branch/loop conditions, inert prose and - code fences, and source spans inside one/two-backtick code spans. + code fences, and source spans inside one/two-backtick code spans. (Recorded + under the pre-RFC mapping, now superseded by RFC-LANG-0002; the fixtures are + being migrated to the unified payload/keyword syntax.) - Independent Tool Protocol v1 consumers `sample-view`, `sample-knowledge` and `sample-proof` (analysis/trace readers) with install, dispatch and remove tests; none is a hard-coded CLI command. @@ -181,6 +243,11 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. ### Changed +- `spec/mapping.md` and `spec/expression.ebnf` were replaced in place by the + RFC-LANG-0002 contract (heading modes, unified payload carriers, keyword + control flow). `spec/markdown-profile.md` remains `marqdo.md.v1`; only the + Markdown→program mapping changed. These specs describe the target language and + are ahead of the Rust implementation; see "Breaking changes" above. - Assignment targets are no longer restricted to bare identifiers: a single index place is accepted at statement level. Member assignment stays a parse error; chained assignment stays a parse error. `spec/expression.ebnf`, @@ -196,7 +263,9 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. - List-item condition paragraphs now accept only inert description; an executable `Strong`/`Emph` there is a hard `markdown.invalid_construct` error instead of being silently swallowed. Condition expression spans are - mapped from the literal bytes inside the code-span backticks. + mapped from the literal bytes inside the code-span backticks. (Pre-RFC + mapping; superseded by RFC-LANG-0002, where lists have no condition head at + all.) - Linux strict `inspect --platform` remains a snapshot, not a promise. A run that loses namespace/resources between probe and launch must fail closed. diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 5c65381..fe91812 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -2,14 +2,52 @@ Snapshot: workspace version **0.1.0**, code/security SHA **`8af7262`**, no release tag cut. This file records what was actually verified and separates it -from what is only implemented. +from what is only implemented. Executed status is in +[`docs/STATUS.md`](docs/STATUS.md). + +## Language source syntax (breaking change) + +**The `.mq.md` source language is a breaking change.** The current contract is +[RFC-LANG-0002](docs/architecture/RFC-LANG-0002-unified-semantics.md) +(accepted by [ADR-0052](docs/adr/0052-unified-markdown-semantics.md)), with the +normative summaries in [`spec/mapping.md`](spec/mapping.md) and +[`spec/expression.ebnf`](spec/expression.ebnf): + +- H1–H6 headings declare `@exec`/`@knowledge` modes; unmarked headings inherit + the nearest ancestor's mode and the document root is Knowledge. +- Only an Exec H2 is a callable function. H2 Knowledge is inert and H3–H6 are + non-callable sections. +- In an Exec scope, `Strong`, `Emph` and inline `Code` are interchangeable + carriers of one statement; the original emphasis role is gone. +- Control flow comes from keywords in the payload (`if`/`else`/`while`/`end`/ + `return`/`params(...)`). Ordered lists, bullet lists and block quotes are + inert presentation containers. +- There is no version selector, `--legacy` path or fallback mapper. + +Consequences for compatibility: + +- **Old pre-RFC `.mq.md` source is not executable.** A file that relied on + `Strong` = execute, `Emph` = return, ordered list = branch, bullet list = + loop, block quote = call or a first code-span signature must be rewritten by + AST role (see `docs/migration/README.md`). A parse failure is a hard + diagnostic, never a fallback to prose. +- The Markdown parser profile stays `marqdo.md.v1`; only the Markdown→program + mapping changed. Rendering of otherwise-ordinary Markdown is unaffected. +- **Implementation state:** `spec/` is ahead of the Rust implementation. The + frontend migration is only partially present in this worktree: heading-mode + and Knowledge-unit plumbing has started, but the executable mapping, statement + parser and bundled stdlib still follow pre-RFC behaviour. Tests that exercise + executable Marqdo source are therefore expected to be red, and this candidate + must not be described as supporting the new syntax until the full migration + lands. See [`docs/STATUS.md`](docs/STATUS.md) and + [`docs/migration/README.md`](docs/migration/README.md). ## Public protocol versions | Surface | Version | Compatibility rule | |---|---|---| -| Markdown profile | `marqdo.md.v1` | Frozen parser/options; semantic change needs an ADR, new goldens and a profile id bump. | -| Language / CLI | workspace `0.1.0` | Pre-1.0. CLI flags may change with a changelog note; `strict` refusal is contractual. | +| Markdown profile | `marqdo.md.v1` | Frozen parser/options. The RFC-LANG-0002 mapping rewrite keeps this profile; the source-language break is tracked above, not by a new profile id. | +| Language / CLI | workspace `0.1.0` | Pre-1.0. The `.mq.md` source language changed incompatibly (RFC-LANG-0002); there is no old-syntax execution path. CLI flags may change with a changelog note; `strict` refusal is contractual. | | `marqdo.lock` | v3 | v1/v2 are rejected with a relock instruction; `run`/`call`/`check` never rewrite or fetch the lock. | | Analysis | v2 | Consumers reject unknown majors; incompatible field changes require v3. | | Trace | v2 | Binds to the exact Analysis bytes; unknown majors rejected. | @@ -72,6 +110,10 @@ reproduce the Windows checkout byte behavior. ## Explicitly unsupported in this candidate +- Pre-RFC `.mq.md` source syntax (Strong-execute / Emph-return / ordered-list + branch / bullet-list loop / block-quote call / first code-span signature). + Old sources are a rewrite task, not a compatibility mode: there is no + `--legacy`, `marqdo_semantics` selector or second mapper. - OS-level strict isolation on macOS/Windows (Linux only, probe-gated). - Strict L2: Worker/Foreign execution inside strict (refused in L1). - Windows Native/Worker ABI runtime support. diff --git a/README.md b/README.md index 57ae1c5..9766ccf 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,48 @@ # Marqdo CLI -Marqdo is a **Markdown-native, independently interpreted programming language**: -standard CommonMark/GFM structures carry program control (headings scope, -`**strong**` executes, `*emph*` returns, ordered lists branch, bullet lists -loop, block quotes call), prose and executable nodes mix in one document, and -all side effects go through a capability-checked host boundary. The official -implementation is a Rust workspace; Python/Node are optional foreign kernels, -never the compiler target. +Marqdo is a **Markdown-native, independently interpreted programming language**. +A `.mq.md` file is ordinary CommonMark/GFM prose plus explicit executable +regions: a heading declares `@exec` or `@knowledge`, `**strong**`, `*emph*` and +inline `` `code` `` are interchangeable carriers of one statement, and keywords +inside that payload — `if`, `else`, `while`, `end`, `return`, `params` — decide +control flow. Lists, block quotes and emphasis are document presentation only. +The official implementation is a Rust workspace; Python/Node are optional +foreign kernels, never the compiler target. This repository is the new, independent Marqdo toolchain (M0.5). It is **not** a compatibility rewrite of `cflmy/marqdo`; the old syntax, package format and plugin ABI v2 are not claimed to work here. +> **Breaking language revision in progress.** The current semantic contract is +> [RFC-LANG-0002](docs/architecture/RFC-LANG-0002-unified-semantics.md) +> (see also [`spec/mapping.md`](spec/mapping.md) and +> [`spec/expression.ebnf`](spec/expression.ebnf)). The repository documentation, +> examples and test sources have been migrated to this single syntax, but the +> Rust frontend, expression parser and bundled `stdlib/` have **not** landed it +> yet. Until they do, executable tests that contain migrated source are expected +> to be red; this checkout must not be described as supporting the new syntax. +> Old syntax (`**strong**` = execute, `*emph*` = return, `1.` = branch, +> `-` = loop, `>` = call) is **not** an active language. Migration status: +> [`docs/migration/README.md`](docs/migration/README.md) and +> [`docs/STATUS.md`](docs/STATUS.md). + > **Status: stabilization candidate, not released.** The language, lock v3, > Analysis v2, Trace v2, Tool v1, Plugin ABI v1 (native + worker) and pinned -> Foreign providers are implemented and covered by tests on Linux. The -> macOS/Windows `E0433` platform-cfg failure and the Linux strict -> probe→launch race are fixed in source at `8af7262`, but the native -> Windows/macOS and GitHub Linux lanes have not been re-run from this -> checkout. **`strict` OS isolation is available on Linux only when the -> runtime Bubblewrap probe passes**; it was verified against the full -> escape/resource matrix in a disposable Ubuntu 26.04 VM at `8af7262` -> (ADR-0021). macOS/Windows fail closed, strict L2 (Worker/Foreign) is not -> implemented, and the broker/worker are not a sandbox. The release decision -> is **DO NOT RELEASE** until the remote gates have same-SHA URLs. See +> Foreign providers are implemented and covered by tests on Linux for the +> pre-RFC syntax. The macOS/Windows `E0433` platform-cfg failure and the Linux +> strict probe→launch race are fixed in source at `8af7262`, but the native +> Windows/macOS and GitHub Linux lanes have not been re-run from this checkout. +> **`strict` OS isolation is available on Linux only when the runtime +> Bubblewrap probe passes**; it was verified against the full escape/resource +> matrix in a disposable Ubuntu 26.04 VM at `8af7262` (ADR-0021). +> macOS/Windows fail closed, strict L2 (Worker/Foreign) is not implemented, and +> the broker/worker are not a sandbox. The release decision is **DO NOT +> RELEASE** until the remote gates have same-SHA URLs. See > [`docs/STATUS.md`](docs/STATUS.md), [`COMPATIBILITY.md`](COMPATIBILITY.md) > and [`docs/security-gate.md`](docs/security-gate.md). The single current CI > convergence plan is -> [`docs/NEXT_RELEASE_CI_CONVERGENCE.md`](docs/NEXT_RELEASE_CI_CONVERGENCE.md). +> [`docs/NEXT_RELEASE_CI_CONVERGENCE.md`](docs/NEXT_RELEASE_CI_CONVERGENCE.md) +> (historical baseline; refresh before use). CI: the private remote [git.cflmy.cn/cflmy/marqdo-cli](https://git.cflmy.cn/cflmy/marqdo-cli) uses Woodpecker at [ci.cflmy.cn](https://ci.cflmy.cn); [`.woodpecker.yml`](.woodpecker.yml) @@ -45,11 +60,16 @@ cargo build -p marqdo-cli ## Quickstart +> **Not yet executable in this checkout.** The source below is the only current +> syntax. The published binary still contains the pre-RFC frontend and will +> report these sources as Knowledge (no callable `main`) or a payload error +> until the migration lands. See [`docs/STATUS.md`](docs/STATUS.md). + ```bash marqdo init demo cd demo marqdo check index.mq.md -marqdo run index.mq.md # executes ## main +marqdo run index.mq.md # executes ## @exec main once implemented marqdo inspect index.mq.md --ast marqdo inspect index.mq.md --signature marqdo call index.mq.md main @@ -58,37 +78,68 @@ marqdo call index.mq.md main Example project from scratch (`index.mq.md`): ````markdown -# 数学 +# @knowledge 数学 -## 阶乘 +## @exec 阶乘 -1. `n <= 1` +`params(n: Int)` - *1* +`if n <= 1` -2. `n > 1` +`return 1` - **结果 = n * 阶乘(n=n-1)** +`else` - *结果* +`结果 = n * 阶乘(n=n-1)` +`return 结果` + +`end` ```` ```bash marqdo check examples/factorial.mq.md -marqdo call examples/factorial.mq.md 数学.阶乘 --arg n=5 # 120 +marqdo call examples/factorial.mq.md 数学.阶乘 --arg n=5 # target: 120 ``` The parser is frozen: `marqdo.md.v1` = CommonMark 0.31.2 + GFM tables, strikethrough, task lists + `$...$`/`$$...$$` math (comrak `=1.0.0`). A `.mq.md` file still renders normally in any compatible Markdown reader; rendering never -executes anything. +executes anything. The Markdown profile is unchanged by the semantic rewrite. + +## Language in 60 seconds + +* **Headings declare the mode.** `# @knowledge 笔记` is a document namespace; + `## @exec main` overrides to an executable function. Any H1–H6 may carry + `@exec`/`@knowledge`; unmarked headings inherit the nearest ancestor. The + document root is Knowledge. An Exec H2 is the only callable function; H3–H6 + are sections inside it. +* **Closed carriers are interchangeable.** In an Exec section, `**x = 1**`, + `*x = 1*` and `` `x = 1` `` are the same assignment. Prefer inline code spans + for expressions containing `*` or `**`. +* **Statements are explicit.** `if `, `else`, `while `, `end`, + `return `, `params(n: Int)`, assignment, or an expression call. Each + carrier holds exactly one statement; every `if`/`while` is closed by `end` + inside the same heading body. +* **Containers do not compute.** `1.`, `-`, `>` and emphasis only organize the + document. `> print(1)` is prose; `> **print(1)**` contains a call. +* **Knowledge is inert.** Nothing in a `@knowledge` section executes, so it is + the place for normal emphasis, explanatory lists, tables and formula + resources. +* **No syntax switch.** There is no `marqdo_semantics` field or `--legacy` + flag; all `.mq.md` files use this syntax. + +The full contract is [`spec/mapping.md`](spec/mapping.md) and +[`spec/expression.ebnf`](spec/expression.ebnf); the rationale and migration +rules are [`RFC-LANG-0002`](docs/architecture/RFC-LANG-0002-unified-semantics.md). ## What works (implemented and tested) -* **P0 contracts** — frozen Markdown profile, AST → program mapping, strict - expression grammar, evaluation semantics; 160 AST goldens, 73 semantic - goldens, 52 compile-error fixtures and 21 runtime-error fixtures - (`tests/`). +* **P0 contracts** — frozen Markdown profile, evaluation semantics and the + pre-RFC AST → program mapping; 160 AST goldens, 73 semantic goldens, 52 + compile-error fixtures and 21 runtime-error fixtures (`tests/`). The test + corpus has been rewritten to the current syntax but the frontend has not, so + these suites are **expected red** until the migration in + [`docs/migration/`](docs/migration/README.md) lands. * **P1 interpreter** — native Rust tree-walk interpreter: values, scopes, functions, static parameter inference, assignments, branches, loops, returns, recursion, structured errors, fuel/stack/output budgets. @@ -192,8 +243,9 @@ cargo clippy --workspace --all-targets -- -D warnings `capabilities` are requests, never grants. * **Reference validation is opt-in**: `check --refs` reports broken links; plain `check` ignores them because links are static knowledge references. - Link-form calls cannot cross modules; cross-module calls use imported alias - expressions such as `geometry.圆面积(r=2)`. + Markdown links never call; calls are expressions inside executable payloads, + and cross-module calls use imported alias expressions such as + `geometry.圆面积(r=2)`. * **`ref("#anchor")` is module-local** and errors with `ref.ambiguous` when a heading range contains more than one formula/code block instead of picking the first. @@ -235,18 +287,26 @@ tests/ conformance/negative corpus (see tests/README.md) ## Documentation index * [`AGENTS.md`](AGENTS.md) — operating rules for contributors and coding agents. +* [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](docs/architecture/RFC-LANG-0002-unified-semantics.md) + — **the single language authority**: full new syntax, breaking changes, + architecture, migration and acceptance gates. Adopted by + [ADR-0052](docs/adr/0052-unified-markdown-semantics.md). +* [`spec/mapping.md`](spec/mapping.md) — normative AST→program mapping + (heading modes, unified carriers, control stack, diagnostics). +* [`spec/expression.ebnf`](spec/expression.ebnf) — normative statement and + expression grammar. +* [`docs/migration/README.md`](docs/migration/README.md) — migration rules and + the inventory of remaining work. * [`docs/DEVELOPMENT_BLUEPRINT.md`](docs/DEVELOPMENT_BLUEPRINT.md) — architecture - baseline (Chinese; the M0.6 plan below supersedes it on command-surface scope, - extension registration, plugin addressing, package identity, repository - decoupling and release gates). + baseline (Chinese); historical sections are marked and the current language + contract is RFC-LANG-0002, not the blueprint's old mapping. * [`docs/STABLE_RELEASE_IMPLEMENTATION.md`](docs/STABLE_RELEASE_IMPLEMENTATION.md) - — **the single authoritative next-phase plan**: PR order, G-A/G-B/G-C gates, - Windows/macOS fixes, protocol/environment stabilization, strict isolation - requirements and the release checklist. + — **the single authoritative next-phase plan** for release gates, PR order, + Windows/macOS fixes and the release checklist; it is a plan, not evidence. * [`COMPATIBILITY.md`](COMPATIBILITY.md) — protocol versions, per-platform - feature evidence and explicit unsupported features. + feature evidence, the breaking language change and unsupported features. * [`CHANGELOG.md`](CHANGELOG.md) — unreleased stabilization changes and the - `0.1.0` baseline. + `0.1.0` baseline, including the syntax breaking change. * [`docs/security-gate.md`](docs/security-gate.md) — G-C evidence and limits; [`docs/security-vm.md`](docs/security-vm.md) reproduces the disposable VM and the self-hosted security runner. @@ -281,6 +341,9 @@ tests/ conformance/negative corpus (see tests/README.md) ## Examples +> Examples are migrated to the current syntax but cannot execute until the +> frontend migration lands; the commands below are the intended contract. + ```bash marqdo run examples/hello.mq.md marqdo call examples/factorial.mq.md 数学.阶乘 --arg n=5 diff --git a/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md b/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md index 345b1c8..17dabda 100644 --- a/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md +++ b/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md @@ -1,9 +1,16 @@ # Marqdo CLI 核心稳定化、协议冻结与独立生态准入实施规范 -> **Historical review baseline (`0adebe4`, 2026-11-20).** The source review -> and CI facts here are a snapshot, not current state. The current overview is -> [`architecture/CURRENT.md`](architecture/CURRENT.md); executed status is in -> [`STATUS.md`](STATUS.md). +> **Historical / Superseded review baseline (`0adebe4`, 2026-11-20).** The +> source review and CI facts here are a snapshot, not current state. The current +> overview is [`architecture/CURRENT.md`](architecture/CURRENT.md); executed +> status is in [`STATUS.md`](STATUS.md). +> +> **语言语义已被取代:** 本文件的语言描述早于 +> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md) +> ([ADR-0052](adr/0052-unified-markdown-semantics.md))。现行唯一语言规范是 +> 该 RFC 与 `spec/mapping.md` / `spec/expression.ebnf`;本文的旧分阶段路线、 +> 问题清单和门槛均为历史输入,不表示已实现,也不得覆盖 RFC。下一阶段计划以 +> [`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md) 为准。 > **文档状态:Proposed / 可直接用作下一阶段工程实施基线** @@ -43,7 +50,7 @@ Marqdo 是以 Markdown 语法树为正式结构、具有确定执行语义的编程语言。其基础原则为“代码即文档,文档即知识库,知识即可执行”。它不是将 Markdown 翻译成 Python 后执行的工具。普通文档内容保持 Markdown 可读性,具有执行语义的结构由固定 Markdown profile 和 language mapping 解释,再由独立 Rust 解释器运行。 -语言规范权威入口:`spec/markdown-profile.md`、`spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`。修改这些文件规定的语义属于**语言版本变更**,必须单独提出 ADR 和金样测试;本文件不会擅自改变它们。 +语言规范权威入口(现行):`docs/architecture/RFC-LANG-0002-unified-semantics.md` 及其摘要 `spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`;`spec/markdown-profile.md` 仍固定 Markdown profile。(本句在写作时指向旧映射,已按 RFC 更新;下文其余叙述为历史。)修改这些文件规定的语义属于**语言版本变更**,必须单独提出 ADR 和金样测试;本文件不会擅自改变它们。 语言核心应独立完成 Markdown AST 解析、函数和参数推断、表达式与控制流、模块/显式导入、静态检查、确定的值及错误语义、Rust 原生执行、能力检查、依赖环境。编译/运行 **不需要** Knowledge、Proof 或 View。 diff --git a/docs/DEVELOPMENT_BLUEPRINT.md b/docs/DEVELOPMENT_BLUEPRINT.md index a84ab7f..b551a27 100644 --- a/docs/DEVELOPMENT_BLUEPRINT.md +++ b/docs/DEVELOPMENT_BLUEPRINT.md @@ -7,11 +7,15 @@ > **优先阅读**:本文件 → `spec/` 形式规范 → `tests/conformance/` 金样 → 相关模块源码 > **约定**:**[D]** 已确定的设计方向;**[P]** 本文提出的可实现细节,须经形式化测试和 ADR 批准后冻结;**[F]** 后期能力,不应阻塞首个独立运行版本。 +> **语言映射状态(2026-11-21,必读)**:本文档原本是 M0.5/M0.6 期的架构蓝图,其中关于 Markdown 程序角色的描述(旧映射:`Strong`=执行、`Emph`=返回、有序列表=分支、无序列表=循环、引用块=调用、首个独立 CodeSpan=签名)**已被废止,仅作为历史设计记录**。现行唯一语言语义权威是 +> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md)(由 [ADR-0052](adr/0052-unified-markdown-semantics.md) 采纳),其规范摘要为 [`spec/mapping.md`](../spec/mapping.md) 与 [`spec/expression.ebnf`](../spec/expression.ebnf)。 +> 本文 §0.1、§1.2–1.4、§2.2、§2.4、§3.1–3.2、§4.1、§5.2、§6.2、§8.1、§13、§14、§16.3、§17 已按现行映射改写或标注历史;其余章节(IR、ABI、安全、包管理、发布)仍是架构参考。 +> **实现状态**:RFC 与 `spec/` 领先于 Rust 实现。当前前端、表达式解析器与标准库仍实现旧映射,执行源码的测试预期为红;见 [`docs/STATUS.md`](STATUS.md) 与 [`docs/migration/README.md`](migration/README.md)。不要把本蓝图或 RFC 示例当作现有 CLI 已经支持的证据。 +> **示例标注**:本文未明确标注为“历史”的 Markdown/`.mq.md` 示例均按 RFC-LANG-0002 目标语法书写,属于示意片段,前端迁移前不能原样运行;标注为历史的片段保留旧映射,仅供决策考古。 + **这不是对 `cflmy/marqdo` 的兼容性重构。本项目必须从语言目标出发,独立建立 Marqdo 工具链。** 旧仓库只作为经验、算法、测试和可能的代码复用来源;旧语法、旧 ABI、旧插件体系不因名称相同而自动成为新版本的兼容契约。 -> **M0.6 规划说明**:`docs/NEXT_PHASE_IMPLEMENTATION.md`(Proposed)与 `docs/EXTENSIBILITY_AUDIT.md` 已在命令规模、能力注册、插件寻址、包身份、仓库解耦和发布门槛上提出新的目标方案;发生冲突时以该 M0.6 计划为准。`spec/`、已接受 ADR 与测试仍是已实现语言行为的规范来源,Proposed 内容不表示已实现。 -> -> **当前阶段基线**:`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`(Proposed,审查基线 `0adebe4`)基于 M0.6 计划之后的提交重新审查 CI、锁图、源码身份、Analysis/Trace、Tool 与安全隔离,并定义 G-A/G-B/G-C 发布门槛。该文在**当前基线、问题清单和发布门槛**上取代上述两份文档;冲突时以其为准,但同样不表示已实现。 +> **规划文档关系(2026-11-21 更新)**:语言语义只以 RFC-LANG-0002 与 `spec/` 为准。下一阶段工作与发布门槛以 [`docs/STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md) 为准;`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`(审查基线 `0adebe4`)、`docs/NEXT_PHASE_IMPLEMENTATION.md`(M0.6)与 `docs/NEXT_RELEASE_CI_CONVERGENCE.md` 是历史规划输入,不表示已实现,也不能覆盖 RFC 的语言映射。当前执行状态见 [`docs/STATUS.md`](STATUS.md)。 --- @@ -19,7 +23,7 @@ 1. **[D] Markdown 是语言的语法,而不只是程序的注释格式。** Marqdo 的合法源码是选定 Markdown 方言的严格子集;不要求任意 `.md` 自动变成可运行程序。 2. **[D] 标准 Markdown AST 是唯一的文档结构事实来源。** 使用成熟解析器;不用正则表达式重新识别 Markdown 块/强调/列表。可以构造程序 IR,但不能平行维护另一套“私有 Markdown AST”。 -3. **[D] Markdown 节点的程序角色是确定的。** `Strong`、`Emph`、`OrderedList`、`BulletList`、`BlockQuote` 等在适用的程序区域有明确语义。解析失败即诊断;禁止“像代码就执行,否则当文本”的启发式。 +3. **[D] Markdown 节点的程序角色是确定的。** 标题上的 `@exec`/`@knowledge` 声明(或从最近祖先标题继承)决定该区域是执行还是知识;执行区域内 `Strong`、`Emph`、行内 `Code` 是等价的单语句载荷,`if`/`else`/`while`/`end`/`return`/`params` 决定控制与签名,列表、引用块和段落只是容器。解析失败即诊断;禁止“像代码就执行,否则当文本”的启发式。现行权威为 RFC-LANG-0002;旧“`Strong`=执行、`Emph`=返回、列表=分支/循环、引用块=调用”映射已废止。 4. **[D] 自然语言可与执行节点同处一个段落或分支。** 叙述永远不触发执行,任何中文/英文词语都不能被猜成控制关键字。 5. **[D] Marqdo 自主执行,不翻译成 Python 作为正式后端。** 用 Rust 实现表达式求值、词法作用域、函数调用、返回、分支、循环和运行时错误;初期 tree-walk,后期可加字节码。 6. **[D] 表格、数学公式、代码围栏是原生文档值。** 公式计算和外部语言执行是 CLI 内置能力,但读取或渲染文档不会自动求值/执行它们。 @@ -30,7 +34,7 @@ ### 0.1 设计理念与取舍 -Marqdo 想要实现的不是 Python 的 Markdown 版本,也不是 Jupyter Notebook 的另一种封装,而是**让标准 Markdown 结构直接承担程序控制语义**:标题承载作用域、粗体承载执行、斜体承载返回、有序列表承载分支、无序列表承载循环、引用块承载调用。编程者通过有限约定撰写源文件,编译器对这些约定进行严格解释,普通 Markdown 阅读器仍能渲染。 +Marqdo 想要实现的不是 Python 的 Markdown 版本,也不是 Jupyter Notebook 的另一种封装,而是**让标准 Markdown 结构直接承担程序作用域与载荷承载**:标题用 `@exec`/`@knowledge` 声明语义模式并沿祖先继承,只有 Exec H2 是可调用函数;执行区域内粗体、斜体与行内代码是等价的单语句载荷,程序操作由载荷中的 `if`/`else`/`while`/`end`/`return`/`params` 关键字决定;有序/无序列表与引用块只组织阅读顺序,不产生指令。普通 Markdown 阅读器仍能渲染源文件。(上述为现行 RFC-LANG-0002 映射;本蓝图早期“粗体承载执行、斜体承载返回、有序列表承载分支、无序列表承载循环、引用块承载调用”的表述属于历史设计,已废止。) **不追求**“任意人类叙述皆可编译”;**不追求**“每种 Markdown 强调方式都仍有普通文档原义”;**不追求**“每一个 Markdown 节点都必须执行”;**不追求**“复杂程序完全不需要学习计算表达式”。 @@ -57,50 +61,53 @@ Marqdo 想要实现的不是 Python 的 Markdown 版本,也不是 Jupyter Note - 单个解析器可能在 AST 中合并相邻引用行、把 Setext/ATX 标题统一为 `Heading`、把不同项目符号统一为 `BulletList`。语言语义针对**AST 节点**,规范书写使用固定符号,但不能依赖丢失的源码标记。 - 不从渲染后的 HTML 反推程序。输入 Markdown AST 是唯一解析来源,源位置信息应被保留用于 IDE 和诊断。 -### 1.2 文档区域与执行区域 +### 1.2 文档区域与执行区域(RFC-LANG-0002) -**[P] 作用域**:`# 名称` 建立顶层作用域,`## 名称` 建立函数;更深层标题在当前函数内部创建命名分节而**不**引入新运行时函数。Markdown AST 中标题通常是同级块,必须按 heading level 另建**范围索引**:一个 `##` 的范围延续到下一个同级或更高级标题之前。若没有上层 `#`,函数位于模块根。嵌套标题和代码围栏内的标题不产生顶层函数。 +**[D] 标题模式**:H1–H6 的首个纯 Text 子节点可以以 `@exec` 或 `@knowledge` 加空白与非空名称开头,声明该标题范围的模式;未声明的标题继承最近祖先标题的模式,文档根为 Knowledge。模式声明不属于语义名称,`@exec`/`@knowledge` 不进入可调用名称。`# @exec 名称` 建立执行命名空间,`## @exec 名称` 建立**唯一可调用函数**;H2 Knowledge 只是知识单元,H3–H6 只是分节,永不创建可调用函数。 -**[P] 执行上下文限定**:程序区域内,强/斜体节点参与执行;标题文字、链接标签、表格数据单元、代码围栏内容、数学内部、HTML 原文等**惰性叶节点**中的内联格式绝不执行。此约束基于祖先 AST 类型、不是表达式文本。出现在正文或列表体中的普通 `Paragraph` 可以混合 `Text` 与执行节点。 +**[P] 执行上下文限定**:只有 Exec 范围(继承或显式)中的 `Strong`、`Emph`、行内 `Code` 才是载荷候选;每个闭合载体承载**恰好一条语句**,载体种类不决定操作。标题文字、链接标签与 URL、图片 alt、表格数据单元、代码围栏、数学、HTML、front matter 等惰性叶节点中的内容绝不执行。列表、引用块和段落只决定载荷的文档顺序,不赋予 Branch/Loop/Call 角色。 -**[P] 函数范围与入口**:`main`(模块根下唯一入口函数)为 `marqdo run` 默认入口,导入模块的 `main` 不执行;`marqdo call file.mq.md 函数名` 选择明确目标。纯叙述函数调用后返回 `Unit`,不自动返回其段落内容。 +**[D] 函数范围与入口**:只有 Exec H2 产生函数;其直接正文与后代 Exec H3–H6 分节按源序拼接为同一函数体,并在每个标题边界重置并要求控制栈为空。`main` 必须是 Exec H2 才能作为 `marqdo run` 默认入口;`marqdo call file.mq.md 函数名` 选择明确目标。无任何显式 `return` 的函数自然结束返回 `Unit`,不等于 `None`。 -### 1.3 核心 Markdown AST 映射(强制无歧义) +### 1.3 核心 Markdown AST 映射(RFC-LANG-0002;强制无歧义) -| Markdown AST 节点 | 程序意义 | 必须满足的条件 | 非法时 | +| Markdown AST 节点 | 当前程序意义 | 必须满足的条件 | 非法时 | |---|---|---|---| -| `Document` | 模块 | 文档根 | 编译错误 | -| `Heading(level=1)` | 命名空间/对象域 | 非空规范名称 | 编译错误 | -| `Heading(level=2)` | 函数 | 非空可寻址名称;作用域唯一 | 编译错误 | -| `Heading(level>=3)` | 分节/源码定位 | 必须位于所属模块或函数范围 | 不执行 | +| `Document` | 模块,根模式为 Knowledge | 文档根 | 编译错误 | +| `Heading(level=1)` | 命名空间/顶层单元(声明或继承模式) | 非空规范名称 | 编译错误 | +| `Heading(level=2, mode=Exec)` | **唯一可调用函数** | 非空可寻址名称;作用域唯一 | 编译错误 | +| `Heading(level=2, mode=Knowledge)` | 惰性知识单元 | 非空名称 | 不执行 | +| `Heading(level>=3)` | 所属函数/知识单元的分节(可本地覆盖模式) | 必须位于合法祖先范围 | 不创建函数 | | `Text` | 叙述 | 不参与求值 | 不报错 | -| `Strong` | 执行语句 | 其完整纯文本/代码跨度载荷满足 `Statement` 文法 | **硬错误,不降级为强调** | -| `Emph` | 返回语句 | 载荷满足 `Expression` 文法;可嵌入段落 | **硬错误** | -| `Code` 行内 | 符号、形式条件、名称载荷 | 仅当位于声明/分支/循环头等规定位置才被解释 | 指定位置非法时报错 | -| `OrderedList` | 顺序优先的条件分支 | 每个 Item 有合法布尔条件头 | **硬错误,不降级为普通列表** | -| `BulletList` | 循环组 | 每个 Item 有合法条件或遍历头 | **硬错误** | -| `BlockQuote` | 调用 | 完整的调用节点结构;不得混普通引文 | **硬错误** | -| `Table` | 结构化值 | GFM 合法数据表 | 类型/约束错误 | +| `Strong` @ Exec | 单语句载荷载体 | 直接 Text/Code 子节点内容恰好一条语句;嵌套载体/复杂子节点报错 | **硬错误,不降级为强调** | +| `Emph` @ Exec | 单语句载荷载体 | 与 `Strong` 完全等价 | **硬错误** | +| `Code` 行内 @ Exec | 单语句载荷载体 | 与 `Strong`/`Emph` 完全等价;不享有签名特权 | 载荷非法时报错 | +| `Code` 行内 @ Knowledge/惰性区 | 文档代码文本 | 不执行 | 不报错 | +| `OrderedList` / `BulletList` | 纯文档容器 | 按源序递归提取其中的合法载荷;列表属性不影响指令 | **不产生隐含分支/循环** | +| `Paragraph` | 纯文档容器/载荷载体宿主 | 按源序提取合法载荷;纯叙述零指令 | 不报错 | +| `BlockQuote` | 纯文档容器 | 按源序递归提取合法载荷;引用本身不是调用 | **不产生隐含调用** | +| `Table` | 结构化值 | GFM 合法数据表;单元格内容不执行 | 类型/约束错误 | | `CodeBlock` | `Code` 值 | 识别语言标记;未知语言允许存档 | 请求运行未知语言时报错 | | `Math` | `Formula` 值 | 可渲染,不承诺均可符号解析 | 请求计算不受支持时诊断 | | `Link` | 静态知识引用 | 可解析内外资源;普通外链不自动加载 | 按引用策略诊断 | | `Image` / `Footnote` | 文档资源/来源 | 惰性 | 不执行 | | `ThematicBreak` | 视觉分隔 | 惰性 | 不执行 | -**关于保留标记的代价**:在函数体中 `**自然语言强调**` 会尝试编译成语句并失败,`*普通斜体*` 会尝试返回并失败,`1. 步骤` 会被视为分支,`- 条目` 会被视为循环,`> 引言` 会被视为调用。作者需要使用普通段落、标题、公式或其他未保留结构表达这些内容。这是语言设计选择,不是解析器缺陷。 +**关于保留标记的代价(RFC-LANG-0002)**:在 Exec 范围内 `**自然语言强调**`、`*普通斜体*` 和 `` `任意代码` `` 都会被当作一条语句载荷;若无法解析为合法语句,就是硬诊断,不会被猜成排版。需要纯视觉强调时,放进 `@knowledge` 分节或其他惰性区域。列表和引用块不再被强制解释为分支/循环/调用,普通文档结构可以在函数内自由使用。 -**关键消歧约束**:不要采用“在 `Strong` 中能解析成语句才是执行,否则不执行”的规则。AST 节点类型及位置确定角色,角色确定后才解析内部表达式。错误必须立即报告。 +**关键消歧约束**:不要采用“在 `Strong` 中能解析成语句才是执行,否则不执行”的规则。AST 节点类型及其模式/位置决定它是否是载荷,载荷必须按唯一文法完整解析;控制操作只由载荷内的关键字决定,不能由载体种类或容器种类决定。错误必须立即报告。旧的 Strong=执行/Emph=返回/List=分支/Quote=调用规则**不得**再作为现行设计。 -### 1.4 Markdown 结构对齐的困难问题(必须写进测试) +### 1.4 Markdown 结构对齐的困难问题(必须写进测试;RFC-LANG-0002) -1. `Strong`/`Emph` 在一个 Paragraph 内可多次出现;按 DFS 文档顺序遍历并执行,但遇到 `Return` 立即短路剩余节点。`Strong`/`Emph` 相互嵌套或包含 `Link` 等非纯载荷时首版拒绝,避免 AST 内容被递归执行两次。 -2. `OrderedList` 不能使用 `1.` 后的任何自然语言充当条件。每个列表项的**首个块**必须是 Paragraph,且它的第一个有效 inline 节点必须为 `CodeSpan(布尔表达式)`;其余同段文本只作说明。每个 Item 后续块按顺序构成分支体。分支从上到下选首个为 `true` 的条件,只执行该分支。无命中返回 `Unit` 并继续执行列表之后的节点。 -3. `BulletList` 的结构头与分支类似;每个 Item 是一个独立的 `while` 型循环,循环头条件每轮重新求值,每轮执行其余 Item 块;多个 Item 按顺序执行多个循环。集合遍历优先采用标准库 `map/filter/fold` 或预定义迭代器;是否增加独立 foreach 头必须另写 ADR。 -4. `BlockQuote` 默认表示**一次明确调用**。只接受**一个 Paragraph**,内容必须是完整 `CallExpr` 或 `Link + 后续实参`;不接受普通引文、多个段落或嵌套引用块。两次独立调用必须分成两个独立 `BlockQuote` AST 节点(需实测 CommonMark 的合并行为)。若作者需要在引用块内写叙述,首版不允许;避免调用/引证混淆。 -5. 标题内部的 `Strong`、表格中的 `Strong` 不会因递归访问而执行。实现必须基于**上下文访问器**而非无条件遍历全树。 -6. Markdown `*` 既是乘法运算符又是强调界定符。执行语句中推荐 `**a * b**`(包含空格)或稳定的 `**\`a*b\`**`(渲染突出一个行内代码表达式)。两者**都属于 Strong**,表达式载荷相同;如源码被 Markdown 解析为非法嵌套,则报出“请将表达式放入行内代码跨度”。检查器必须直接验证最终 AST,而不靠原始正则。 +1. `Strong`/`Emph`/行内 `Code` 在 Exec 范围内都是单语句载体,彼此等价;必须提取完整外壳节点且只提取一次。嵌套 `Strong`/`Emph`/`Link`/数学等复杂子节点报 `sem.payload_nested`,不得部分执行或静默拼接。 +2. `OrderedList`/`BulletList` 只是容器,`ordered`/`start`/`tight`/任务框选等属性不影响指令;编译器按源序递归提取其中载荷,没有条件头、没有隐含分支或循环。空投影(零语句)不等于产生 `List([])` 值。 +3. `BlockQuote` 只是容器,没有调用语义;其中合法的独立载荷照常执行,纯引用正文零指令。旧 `>` 自动调用规则已废止。 +4. 标题模式声明只在标题首个纯 Text 子节点以精确 `@exec`/`@knowledge` 开头时生效;大小写变体、拼错、冲突声明、空名称都是硬错误,不可退回祖先模式。Setext 标题只继承模式,不携带声明。 +5. 标题内部的 `Strong`、表格单元格中的 `Strong`、链接标签中的载荷绝不执行;实现必须基于上下文访问器而不是无条件遍历全树。 +6. Markdown `*`/`**` 仍是强调界定符。表达式中的乘方 `**` 只在载荷已提取后具有运算符意义;为避免 Markdown 吃掉运算符或把载荷切碎,推荐把表达式放进行内 CodeSpan(例如 `` `n = n ** 2` ``)。检查器必须直接验证最终 AST,不能靠原始正则。 7. CommonMark 的“紧凑/松散列表”、换行、嵌套列表及标点有复杂规则;定义的是**AST 的结构匹配**,而不是缩进空格个数。提供 `marqdo inspect --ast` 展示实际节点。 -8. 数学公式与代码围栏**不因为位于函数内部而执行**。可通过所属函数的标题范围生成地址,但不能执行其内部文本。 +8. 数学公式与代码围栏**不因为位于 Exec 标题内部而执行**。行内 `Code` 是载荷载体,围栏代码块是惰性 `Code` 值,两者不可混同。 +9. 控制块(`if`/`while`)只能在同一标题的直接正文内闭合;跨 H3/H4 或跨越 Knowledge 分节的 `end` 必须分别报 `sem.unclosed_control` 与 `sem.unmatched_end`,不得跨边界“修复”。 --- @@ -117,21 +124,21 @@ Marqdo 想要实现的不是 Python 的 Markdown 版本,也不是 Jupyter Note ### 2.2 可选形式参数声明 -**[D]** 默认允许从执行表达式静态推断参数,**不能**从自然语言、行内代码提及、标题措辞推断。**[P]** 若需要稳定的公开 API,在函数标题后第一个段落用单独的行内代码跨度声明可选签名: +**[D]** 默认允许从执行表达式静态推断参数,**不能**从自然语言、行内代码提及、标题措辞推断。**[P]** 若需要稳定的公开 API,在函数体第一条直接执行载荷写 `params(...)` 声明(RFC-LANG-0002): ```markdown -## 圆面积 +## @exec 圆面积 -`(r: Number, precision: Int = 2)` +`params(r: Number, precision: Int = 2)` 按照圆面积公式计算。 -**结果 = pi * r * r** +`结果 = pi * r * r` -*结果* +`return 结果` ``` -**固定规则**:仅标题后的第一个合法 `Paragraph(CodeSpan)` 可是签名;其他位置的代码跨度仍是普通符号。没有签名不代表需要从当前调用者环境中找变量。允许 `()`, 必选形参、类型注解、编译期常量默认值;首版不支持可变参数、解构形参、运行时默认表达式。 +**固定规则(RFC-LANG-0002)**:`params(...)` 只能作为 Exec H2 的**第一条直接执行载荷**、最多一次、且不得位于列表或引用块内部;它是编译期元数据,不是运行时调用。其他位置的 `params` 报 `sem.signature_position`。允许必选形参、类型注解、编译期常量默认值;首版不支持可变参数、解构形参、运行时默认表达式。旧“函数标题后的独立 CodeSpan 即签名”规则已废止。 ### 2.3 静态参数推断(必须区分于动态作用域) @@ -148,10 +155,10 @@ Marqdo 想要实现的不是 Python 的 Markdown 版本,也不是 Jupyter Note 统一调用形式:`函数(...)`;零参数仍写 `函数()`;位置参数只对显式签名开放,具名实参允许覆盖声明顺序,禁止重复实参、未知实参、多余位置参数。参数表达式**按源码出现顺序、恰好求值一次**,再绑定到被调用函数的形参槽;调用者帧和被调用者帧隔离。默认实参值仅在缺失时使用,显式 `None` 不等于未提供。参数绑定失败必须按规范传播错误。 -- `> 打印("你好")`:`BlockQuote` 表示调用语句;执行后结果丢弃,必要时由执行记录保留。 -- `**面积 = 计算圆面积(r=3)**`:在粗体执行节点中的表达式调用,保存返回结果。 -- `> [计算面积](./math.mq.md#计算面积)(r=3)`:调用被 Markdown 链接引用的目标;需对 Link 与后缀参数进行 AST 级匹配,不按行字符串拼接。 -- `*面积*`:`Emph` 返回整个函数,嵌套在分支或循环中也必须向外传播到函数帧;不得只退出局部列表项。 +- `> **打印("你好")`:调用来自载荷内的表达式,引用块本身不是调用;执行后结果丢弃,必要时由执行记录保留。 +- `**面积 = 计算圆面积(r=3)**`:在粗体载荷中的表达式调用,保存返回结果;也可用 `` `面积 = 计算圆面积(r=3)` ``。 +- `[计算面积](./math.mq.md#计算面积)`:只是静态引用;跨模块调用必须在显式导入/锁定闭包内以表达式调用完成,需对 Link 目标与后缀参数进行 AST 级匹配,不按行字符串拼接。 +- `**return 面积**`、`*return 面积*` 或 `` `return 面积` ``:显式 `return` 退出整个 H2 函数,嵌套在分支或循环中也向外传播到函数帧;斜体/粗体本身不再表示返回。 - 函数自然结束返回 `Unit`;`None` 是显式空值,`Unit` 是无结果,二者必须区分。 - 初期**不支持同名重载**;默认值、命名空间和语言类型均不参与模糊候选选取。支持函数递归与互递归。 @@ -165,49 +172,41 @@ Marqdo 想要实现的不是 Python 的 Markdown 版本,也不是 Jupyter Note ### 3.1 表达式是小型独立文法,不是第二套 Markdown -**[D]** Markdown AST 确定“哪里可以执行”;执行节点的文本载荷使用一个**独立、严格、很小的表达式解析器**。不得把整个 `.mq.md` 转译成 Python。表达式候选文法(简化 EBNF): +**[D]** Markdown AST 确定“哪里可以执行”;每条执行载荷的文本使用一个**独立、严格、很小的语句/表达式解析器**(现行文法见 `spec/expression.ebnf`,权威为 RFC-LANG-0002)。不得把整个 `.mq.md` 转译成 Python。载荷必须恰好是一条语句并被完整消费: ```ebnf -Statement = Assignment | Expression ; -Assignment = Identifier, "=", Expression ; -Expression = OrExpression ; -OrExpression= AndExpression, { "or", AndExpression } ; -AndExpression = CompareExpression, { "and", CompareExpression } ; -CompareExpression = AddExpression, [ CompareOp, AddExpression ] ; -CompareOp = "==" | "!=" | "<" | "<=" | ">" | ">=" ; -AddExpression = MulExpression, { ("+" | "-"), MulExpression } ; -MulExpression = UnaryExpression, { ("*" | "/" | "//" | "%"), UnaryExpression } ; -UnaryExpression = ("not" | "-" | "+"), UnaryExpression | PowerExpression ; -PowerExpression = PostfixExpression, [ "**", UnaryExpression ] ; -PostfixExpression = Primary, { CallArgs | ".", Identifier | "[", Expression, "]" } ; -CallArgs = "(", [ Argument, { ",", Argument } ], ")" ; -Argument = [ Identifier, "=" ], Expression ; -Primary = Literal | Identifier | "(", Expression, ")" | ListLiteral | RecordLiteral ; +payload = statement , EOF ; +statement = if_stmt | else_stmt | while_stmt | end_stmt + | return_stmt | params_stmt | assignment | expression ; +if_stmt = "if" , expression ; +else_stmt = "else" ; +while_stmt = "while" , expression ; +end_stmt = "end" ; +return_stmt = "return" , expression ; +params_stmt = "params" , "(" , [ parameter_list ] , ")" ; +assignment = assign_target , "=" , expression ; ``` -- 以上是**建议子集**,需要单独 `spec/expression.ebnf`、优先级表、歧义测试后冻结。`**` 既是 Markdown 强调界定符也是表达式乘方符号,但后者只出现在已提取的表达式载荷内部;若 Markdown 已把输入分割成意外 AST,使用行内代码跨度保证载荷保真。 +- `if`/`while` 由显式 `end` 闭合,`else` 可选且最多一次;控制配对由前端独立控制栈完成,不属于表达式文法。没有 `elif`/`for`/`break`/`continue`/`try`/`end if`/分号多语句/行尾冒号。`if`/`while`/`return` 需要非空表达式并消费整个载荷。 +- 表达式部分沿用既有优先级、字面量、调用、索引、赋值与 `Memory` 位置写入;`**` 只在已提取的载荷内是乘方符号,Markdown 强调边界仍由 Comrak AST 决定,必要时用行内 CodeSpan 保证载荷保真。 - 数值初期选择 `Int`(任意精度或严格有界的语义必须明确,**推荐任意精度 BigInt**)、`Float64`、`Bool`、`Text`、`None`、`Unit`、`List`、`Map`、`Table`、`Formula`、`Code`、`FunctionRef`、`Result`、`PluginHandle` 等。跨 ABI/JSON 边界保留类型标签和大整数的字符串形式,禁止 silently 精度损失。 - 只有 `Bool` 可用于条件。`and`/`or` 短路;数值除零、类型错误、未定义变量、越界均是结构化错误;禁止隐式字符串数字转换。字典访问和数组索引的越界语义必须标准化。 - 赋值为当前局部绑定更新,不隐式写入外层作用域;模块导入绑定只读。 -### 3.2 控制流与程序区域 +### 3.2 控制流与程序区域(RFC-LANG-0002) -**OrderedList = `Branch`**:项目按照 AST 顺序检查条件;首个为 `true` 的项执行一次。必须只有一个条件头 CodeSpan;描述文本可紧随条件,后续 Markdown 块皆可含叙述与执行。无匹配时继续下一节点。禁止先检查所有条件再选择(条件求值可能涉及错误;原则上条件必须是纯计算表达式,禁止在条件里产生 I/O 副作用)。 +**载荷关键字,不是 Markdown 类型**:每条 Exec 载荷是一条语句;`if ` 打开 `Branch`,`else` 切换最近尚未关闭的 `if` 的 else 分支,`while ` 打开 `Loop`,`end` 关闭最近的 `if`/`while`,`return ` 产生 `Return` 并退出整个 H2 函数。`else`/`end` 不产生运行时指令。控制栈在标题边界必须为空,`if`/`while` 不得跨标题闭合。 -**BulletList = `Loop`**:每项代表一个 while-loop,条件每次迭代求值;条件必须是 `Bool`;循环体可含 Text、Paragraph、Strong、Emph、BlockQuote、嵌套 OrderedList/BulletList;每次执行都消耗 fuel。 +**容器无语义**:`Paragraph`、有序/无序 `List`、`BlockQuote` 只是按源序递归提取合法载荷;`1.` 与 `-` 的替换、`>` 的包裹、列表紧/松属性都不改变指令。空容器投影为零语句,不是 `List([])` 值。 -**BlockQuote = `Call`**:整体是一个 Call 结构;无效调用硬错误。调用表达式可以包括具名参数或标准 Markdown Link 目标。是否允许 `> [引用](#函数)` 无显式括号首版建议**不允许**。 +**求值顺序**:同级块按 Markdown AST 文档顺序;段内载荷按源序;分支只执行命中臂;循环条件每轮重新求值;参数按源码出现顺序求值一次;函数帧隔离;导入模块无副作用初始化。错误传播停止当前控制流并保留调用栈/源码位置。 -**Strong = `ExecStmt`**、**Emph = `Return`**:所有出现于程序上下文中的对应节点都按固定角色处理;AST 中 `Strong` 与 `Emph` 的拼写变体具有相同执行行为。返回沿所有嵌套控制流传播到所属函数边界。 - -**求值顺序**:同级块按 Markdown AST 文档顺序;段内执行节点按源序;分支只执行命中项;循环按项顺序执行;参数按源码出现顺序求值一次;函数帧隔离;导入模块无副作用初始化。错误传播停止当前控制流并保留调用栈/源码位置。 - -**基本示例**(M0.5 候选;新解释器尚未验证): +**基本示例**(RFC-LANG-0002 目标语法;前端尚未迁移,不能原样运行): ````markdown -# 数学 +# @exec 数学 -## 阶乘 +## @exec 阶乘 数学定义为: @@ -215,30 +214,32 @@ $$ n! = \begin{cases}1,& n\le1\\n(n-1)!,& n>1\end{cases} $$ -1. `n <= 1`,递归终点。 +`if n <= 1` - *1* +`return 1` -2. `n > 1`,计算更小的问题。 +`else` - **结果 = n * 阶乘(n=n-1)** +`return n * 阶乘(n=n-1)` - *结果* +`end` -## 倒计时 +## @exec 倒计时 -**n = 3** +`n = 3` -- `n > 0`,继续执行。 +`while n > 0` - > 打印(n) +`打印(n)` - **n = n - 1** +`n = n - 1` -*n* +`end` + +`return n` ```` -上述阶乘函数通过自由变量推断形参 `n`,故自调用采用 `阶乘(n=n-1)`;倒计时的 `n` 在入口赋值后才读取,属于局部变量,不应被推断成参数。嵌套段落的强调节点在 Markdown AST 中须以金样确认。 +上述阶乘函数通过自由变量推断形参 `n`(公开 API 推荐用 `params(n: Int)` 显式声明);倒计时的 `n` 在入口赋值后才读取,属于局部变量,不应被推断成参数。旧版“列表条件头 + 斜体返回”的示例属于历史设计,见 RFC-LANG-0002 §1.4 的迁移对照。 ### 3.3 终止与图灵完备性 @@ -260,9 +261,9 @@ $$ |---|---|---|---| | `Import` | YAML `import` | 模块加载/静态编译 | 否,模块只注册定义 | | `Reference` | 普通 Markdown `[说明](目标)` | 文档索引阶段 | 否 | -| `Call` | `BlockQuote` 或执行表达式的 `CallExpr` | 静态解析并在执行时调用 | 是(函数有运行时行为) | +| `Call` | Exec 载荷中的表达式调用 | 静态解析并在执行时调用 | 是(函数有运行时行为) | -`[牛顿第二定律](#牛顿第二定律)` 只是引用;`> [计算作用力](#计算作用力)(m=2,a=3)` 才是明确调用。跨模块调用须在固定的模块/文件权限下解析,外网 HTTP 链接绝不通过导入自动下载和执行。外部文档链接可以纳入可选的网络知识索引,但**不得**改变本地程序求值。 +`[牛顿第二定律](#牛顿第二定律)` 只是引用;明确调用必须在 Exec 载荷中写出表达式,例如 `` `print(计算作用力(m=2, a=3))` ``。引用块本身不再是调用,`> [计算作用力](#计算作用力)(m=2,a=3)` 若不处于 Exec 载荷内则只是文档引用。跨模块调用须在固定的模块/文件权限下解析,外网 HTTP 链接绝不通过导入自动下载和执行。外部文档链接可以纳入可选的网络知识索引,但**不得**改变本地程序求值。 ### 4.2 规范身份与兼容 @@ -292,19 +293,21 @@ M0.5 的“知识单元”只等价于**可寻址标题范围 + 其正文 AST + ### 5.2 示例(候选 API) ````markdown -## 圆面积公式 +## @knowledge 圆面积公式 $$ A = \pi r^2 $$ -## 计算圆面积 +## @exec 计算圆面积 依据[圆面积公式](#圆面积公式)代入半径。 -**面积 = math.eval(ref("#圆面积公式"), {"r": r}, target="A")** +`params(r: Number)` -*面积* +`面积 = math.eval(ref("#圆面积公式"), {"r": r}, target="A")` + +`return 面积` ```` `Formula` 可以按函数标题范围寻址。一个范围存在多段公式时,默认对象选择必须是明确规则(例如禁止无选择器,要求 `math.formulas(ref(...))` 列出候选;不选“第一条”)。数学可符号计算子集应该单独版本化。高级张量/量子数学可通过插件提供,不进入不可控的内核表面。 @@ -331,7 +334,7 @@ $$ ### 6.2 例子(候选 API) ````markdown -## Python 校验 +## @knowledge Python 校验 ```python import json, math, sys @@ -339,11 +342,13 @@ args = json.load(sys.stdin) print(json.dumps({"area": math.pi * args["r"] ** 2})) ``` -## main +## @exec main -**结果 = foreign.call(ref("#Python 校验"), {"r": 2})** +`params(r: Number)` -> 打印(结果.area) +`结果 = foreign.call(ref("#python-校验"), {"r": r})` + +`打印(结果.area)` ```` 不能因为这个文件里存在 Python 代码围栏就自动创建 Python 进程;当 `foreign.call` 被执行且权限通过后才创建或复用受控内核。 @@ -441,9 +446,11 @@ import: quantum: "@quantum" --- -# main +# @exec 示例模块 -**面积 = geometry.圆面积(r=3)** +## @exec main + +`面积 = geometry.圆面积(r=3)` ```` `capabilities` 是**项目提出的权限请求**,不等于宿主已批准的权限;导入和安装不能自动赋权。 @@ -766,7 +773,7 @@ marqdo sync --locked - 固定 Markdown 解析器、扩展配置及版本;枚举节点级映射、惰性区域、表达式载荷抽取算法。 - 写 `spec/markdown-profile.md`, `spec/mapping.md`, `spec/expression.ebnf`, `spec/evaluation.md`。 -- 先写 ≥100 个 AST 金样和负例:`Strong`/`Emph` 等价源码、嵌套列表、含叙述分支、标题边界、块引用合并、Markdown 中乘号/下划线/反引号、无效执行表达式必须硬错误。 +- 先写 ≥100 个 AST 金样和负例:`Strong`/`Emph`/行内 `Code` 载荷等价源码、标题模式声明与继承、嵌套列表/引用容器(应为零指令或合法载荷)、控制块跨标题边界、Markdown 中乘号/下划线/反引号、无效载荷必须硬错误。 - 交付最小 `inspect --ast`,能输出节点、span 和解析来源。 - **验收**:AST 结构语义无歧义;任何执行位错误不静默退化为文本;渲染前后 Markdown 正常。 @@ -816,11 +823,11 @@ marqdo sync --locked | 类别 | 目标 | 核心样例 | |---|---|---| -| AST 金样 | Markdown AST 不被私有解析取代 | 等价粗斜体、混合段落、嵌套列表、引用合并 | -| 语义正例 | 正确程序可执行 | 参数、递归、嵌套分支/循环、调用值 | -| 语义反例 | 不进行启发式兜底 | 非法粗体、非法斜体、非布尔条件、错误调用 | +| AST 金样 | Markdown AST 不被私有解析取代 | 等价粗斜体、混合段落、嵌套列表、引用合并、`@exec`/`@knowledge` 前缀 | +| 语义正例 | 正确程序可执行 | 参数/`params`、递归、`if`/`else`/`while`/`end`、`return` 值 | +| 语义反例 | 不进行启发式兜底 | 非法载荷、悬空 `else`、缺失 `end`、非布尔条件、`params` 位置错误 | | 不变性 | 叙述修改不影响程序 | 只改 Text/非执行资源,IR 与输出保持 | -| AST 等价性 | 等价 Markdown 结构语义相同 | `**a**` vs `__a__`、列表标记替代 | +| AST 等价性 | 等价 Markdown 结构语义相同 | `**a**`/`*a*`/`` `a` `` 载荷等价、列表/引用容器替换不改变指令 | | 参数数据流 | 推断正确和诊断准确 | 自增输入、分支部分赋值、同名全局、错别字 | | 引用/导入 | 可寻址、可复现 | 重名、断链、循环导入、模块版本冲突 | | 数学 | 求值子集准确、超界报错 | 数值精度、导数、非法 LaTeX、不可解方程 | @@ -907,7 +914,7 @@ Migration & rollout: ### 16.3 不允许的实现捷径 -- 解析失败便把 `Strong`/`List` 当成普通 Markdown; +- 解析失败便把 Exec 载荷或容器当成普通 Markdown 并静默跳过; - 用自然语言词(“若/执行/返回/对”等)决定是否启动控制节点; - 为解决语法问题写大量文本级 regex 来覆盖 Markdown AST; - 把 Marqdo 编译为 Python 作为唯一官方运行语义; @@ -923,16 +930,18 @@ Migration & rollout: ## 17. 首批仍需通过 ADR 冻结的设计问题(不是阻止开发的借口) +> **状态更新(2026-11-21)**:本节 S-01/S-02/S-03/S-06 描述的旧映射冲突已由 [RFC-LANG-0002](architecture/RFC-LANG-0002-unified-semantics.md) 与 [ADR-0052](adr/0052-unified-markdown-semantics.md) 解决并废止;下表保留原始表述作为历史记录,其中“本文默认立场”不再是现行设计。仍未冻结的语义问题(参数推断策略、未来 `elif`/`for`/`break`、知识锚点等)需要单独的 Accepted ADR。 + 下列问题涉及语义精确性。团队可以按本文暂定规则编写参考实现和测试,但**不得在对外声称语言已稳定时留下空白**。 -| ID | 问题 | 本文默认立场 | 冻结前需要的证据 | +| ID | 问题 | 本文默认立场(历史) | 冻结前需要的证据 / 现行状态 | |---|---|---|---| -| S-01 | 直接运行 `Strong` 中的数学 `*` 与 CommonMark 强调冲突 | 强调强制执行,允许行内代码无损载荷 | Markdown AST 金样/错误诊断 | -| S-02 | 普通斜体与返回冲突 | 程序体中的 Emph 永远是返回,文档约束使用者 | 真实文档可读性与反例测试 | -| S-03 | `OrderedList`/`BulletList` 在无前缀 `#` 的顶层语义 | 只在函数体内执行;其他区域按文档处理 | 作用域与链接索引测试 | -| S-04 | 参数推断在部分赋值路径中的歧义 | 静态数据流;不确定时报错 | CFG 案例与 ABI 变更测试 | -| S-05 | 中文函数名与英文点号/括号表达式 | Unicode 标识符、固定优先级;含空格走链接引用 | 词法与调用金样 | -| S-06 | 用 Markdown Link + 参数列表作为调用 | BlockQuote 内接受 `Link + suffix`,固定 AST 形式 | 标准解析器真实解析结果 | +| S-01 | 直接运行 `Strong` 中的数学 `*` 与 CommonMark 强调冲突 | 强调强制执行,允许行内代码无损载荷 | 已由 RFC-LANG-0002 解决:载荷统一、建议用行内 CodeSpan;需 AST 金样 | +| S-02 | 普通斜体与返回冲突 | 程序体中的 Emph 永远是返回,文档约束使用者 | 已由 RFC-LANG-0002 解决:`return` 是关键字,斜体只是等价载体 | +| S-03 | `OrderedList`/`BulletList` 在无前缀 `#` 的顶层语义 | 只在函数体内执行;其他区域按文档处理 | 已由 RFC-LANG-0002 解决:列表只是容器,无隐含指令 | +| S-04 | 参数推断在部分赋值路径中的歧义 | 静态数据流;不确定时报错 | 仍需 ADR;CFG 案例与 ABI 变更测试 | +| S-05 | 中文函数名与英文点号/括号表达式 | Unicode 标识符、固定优先级;含空格走链接引用 | 仍需词法与调用金样 | +| S-06 | 用 Markdown Link + 参数列表作为调用 | BlockQuote 内接受 `Link + suffix`,固定 AST 形式 | 已废止:BlockQuote 不再调用;跨文件调用须显式导入/表达式调用,另有 ADR | | S-07 | 多公式/代码围栏在同一章节下如何寻址 | 不自动选第一条;显式 selector/API | 引用稳定性与用户体验测试 | | S-08 | 任意精度数值与跨语言/插件 JSON 边界 | BigInt 为精确整数、wire 有类型标签 | 数值和跨 ABI 测试 | | S-09 | strict sandbox 不同平台的保障 | 不能落实就拒绝 strict | Linux/Win/macOS 安全功能矩阵 | diff --git a/docs/EXTENSIBILITY_AUDIT.md b/docs/EXTENSIBILITY_AUDIT.md index cb96e3a..74f94bd 100644 --- a/docs/EXTENSIBILITY_AUDIT.md +++ b/docs/EXTENSIBILITY_AUDIT.md @@ -1,6 +1,16 @@ # M0.6 扩展性审计:源码问题、改造路径与测试契约 -> 源文档 `docs/NEXT_PHASE_IMPLEMENTATION.md` §1A 的审计摘录,供开发者按问题创建 PR;具体开发次序和发布门槛请看主文档。该审计之后的稳定化基线与 G-A/G-B/G-C 门槛见 `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`。 +> **Historical / Superseded planning input.** 本审计是 M0.6 时期(审查基线 +> `0116160`)的源码扩展性证据,不是当前语言语义或发布路线。语言的唯一现行 +> 权威是 +> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md) +> ([ADR-0052](adr/0052-unified-markdown-semantics.md));下一阶段计划以 +> [`docs/STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md) +> 为准;执行状态见 [`docs/STATUS.md`](STATUS.md)。下文关于 +> `Strong/Emph/List/Quote` 的“用户可见语义”表述描述的是已被 RFC-LANG-0002 +> 废止的旧映射,仅作为当时审计记录保留。 + +> 源文档 `docs/NEXT_PHASE_IMPLEMENTATION.md` §1A 的审计摘录,供开发者按问题创建 PR;具体开发次序和发布门槛请看主文档。该审计之后的稳定化基线(历史)见 `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`;当前路线与发布门槛以 `docs/STABLE_RELEASE_IMPLEMENTATION.md` 为准。 ## 1A. **扩展性审计(v3 增补,优先级高于后续阶段)** @@ -98,7 +108,7 @@ Python/Node 可以继续作为内置 provider;新增 Julia/R/自定义内核 当前项目版本 `0.1.0`,**不对错误设计承担无限兼容义务**。开发者应优先保证未来长期正确性,而不是维护早期内部 enum 的表面稳定。推荐机制: - **内部接口(可以直接破坏)**:`HostOp` 分发、`Builtin` 内部查找、`PluginSlot` 单 namespace、模块 loader、非公开 IR、CLI 命令内部结构;每次变更要有迁移 PR、替换后的测试和明确的 PR 说明。 -- **用户可见语义(默认保护)**:`Strong/Emph/List/Quote` 语义、显式 YAML import、无括号调用的拒绝规则、链接不执行、函数参数推断等。若发现客观错误,也必须有 ADR、版本升级和一致性金样,而不能把“扩展性”当作随意改语法的理由。 +- **用户可见语义(默认保护,现行映射见 RFC-LANG-0002)**:`@exec`/`@knowledge` 标题模式与继承、Exec H2 可调用性、`Strong`/`Emph`/行内 `Code` 单语句载荷等价、`if/else/while/end/return/params` 关键字、显式 YAML import、链接不执行、函数参数推断等。若发现客观错误,也必须有 ADR、版本升级和一致性金样,而不能把“扩展性”当作随意改语法的理由。(本审计原文写作时仍是旧 `Strong/Emph/List/Quote` 映射,已被 RFC-LANG-0002 废止。) - **版本化公共协议(只能显式破坏)**:Tool Protocol、Analysis/Trace、插件 ABI、Value Wire、Lock 格式。新旧同时可用或明确不兼容均可,但不能把 schema 名不变、字段意义变了当作修复。 - **冗余命令(可以有序削减)**:`init`、`inspect`、`fmt`、`plugin inspect`、`remove`、`lock` 等仅作为现有 0.x 行为,保留要以维护收益证明;公开主线禁止因此增加更多命令。删除时提供对应的文档内替代方式,避免把重要能力一起删除。 diff --git a/docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md b/docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md index 175a38a..ee9bc43 100644 --- a/docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md +++ b/docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md @@ -4,6 +4,19 @@ > implemented behavior. The implemented first slice is described in > [`architecture/CURRENT.md`](architecture/CURRENT.md). +> **Syntax note — RFC-LANG-0002 is the current language contract.** The +> compute-kernel / stdlib-ownership / resource model in this RFC is still the +> current design input. Its `.mq.md` examples and Markdown-role wording were +> migrated to the single current syntax +> ([RFC-LANG-0002](architecture/RFC-LANG-0002-unified-semantics.md), +> [ADR-0052](adr/0052-unified-markdown-semantics.md)): `## @exec` heading +> modes, `params`, `return`, `if/else/end`, `while/end`, and one-statement +> payloads carried by `Strong`, `Emph` or inline `Code`. Any remaining old +> spelling (for example "`##/**/*` roles") is historical and is **not** an +> active language. The Rust frontend still implements the pre-RFC mapping, so +> these examples are target syntax, not currently runnable programs; see +> [`STATUS.md`](STATUS.md). + > **状态**:Draft / 架构与迁移提案,未批准、未实施。所有代码均为目标语义草案,不能当作已运行示例。 > **日期**:2026-11-20 @@ -57,7 +70,7 @@ Marqdo 语义核心 资源调 - **G2 系统构造性**:只要基础 OS 资源端点已存在并获授权,Marqdo 应自行实现 `print/read_line/copy_file/HTTP parser/CLI commands` 等高层 API。 - **G3 内核稳定**:未来 100 个独立标准库函数,不意味着增加 100 个内置函数或触及 Rust 编译器/解释器。 - **G4 语义统一**:高级函数运行在与普通程序**同一个**值、内存、调用、错误、来源映射和权限体系下,没有“标准库专用魔法规则”。 -- **G5 兼容现有 Markdown 语义**:`##/**/*`、链接/表格惰性、函数与模块寻址、执行顺序不被重写。 +- **G5 兼容当前 Markdown 到程序的映射**:按 RFC-LANG-0002,执行由 `@exec` 模式与载荷关键字决定;链接/表格保持惰性;函数与模块寻址、执行顺序不被重写。 - **G6 工程品质**:至少能构造可扩展容器、网络字节协议、异构表格、持续交互工具,同时明确性能瓶颈和安全保证。 - **G7 明确安全边界**:内部虚拟内存权限与资源访问权限分别验证;不能把“运行在 Rust 内”误写为“自动内存安全”,也不能把普通 Worker 等同于 OS 隔离。 @@ -377,18 +390,18 @@ std.io.print(value) - 标准输出内容与编译器日志、trace、`--json` 通道保持隔离。 - 首版可支持保持 `print` 完全一致,同时引入 `write_text` / `write_bytes` 作为标准库独立能力;用户未授权写标准输出时,仍必须拒绝。 -示例(**目标 `.mq.md`,非已实现语法,`std` 对应正常模块导入**): +示例(**目标 `.mq.md`,按 RFC-LANG-0002 书写、非已实现语法,`std` 对应正常模块导入**): ````markdown -## 打印 +## @exec 打印 先将任何可打印值格式化为文本,再编码为 UTF-8 字节。 -**显示文字 = format.display(值)** +`显示文字 = format.display(值)` -**数据 = text.utf8_encode(显示文字 + "\n")** +`数据 = text.utf8_encode(显示文字 + "\n")` -> io.write_all(io.stdout(), 数据) +`io.write_all(io.stdout(), 数据)` ```` 这些 `format.display`、`text.utf8_encode` 和 `io.write_all` 必须有真实的 `.mq.md` 定义;其最终字节写入依赖已有授权 `Stream.write` 而不是新的 `HostOp::PrintJson` 等。 @@ -534,40 +547,46 @@ F ∈ L(K,E) **工程性能评估**:记录 `wall_time / peak_RSS / CPU / fuel / bytes_moved / allocations / copy_count`,与 Rust 原生和其他参考语言比较。初期不设无依据的“必须达到 80% 原生速度”的硬指标;若性能瓶颈来自逐字节 Rust↔Marqdo 调用/隐藏复制,先优化执行路径、批量传输、字节码/JIT,再讨论原生加速。任何 O(1) 原语若退化为 O(n) 隐式全表复制,必须单独报告。 -### 7.6 三种验收样例(目标伪代码,非现有可运行程序) +### 7.6 三种验收样例(按 RFC-LANG-0002 书写的目标伪代码,非现有可运行程序) **A. 用 Marqdo 实现堆分配器而不调用 Rust `malloc` 算法**: ````markdown -## 分配 +## @exec 分配 内存管理器保存 region、next、free-list 等元数据。 -1. `存在足够的空闲块` - > 复用空闲块并更新元数据 -2. `没有足够的空闲块` - > 需要时增长(region) - > 更新区域中的尾指针 +`if 存在足够的空闲块` -*分配得到的偏移量* +`复用空闲块并更新元数据` + +`else` + +`需要时增长(region)` + +`更新区域中的尾指针` + +`end` + +`return 分配得到的偏移量` ```` **B. 打印与读取由标准库完成**: ````markdown -## main +## @exec main -**输入 = io.read_line()** +`输入 = io.read_line()` -**输出 = "收到:" + 输入** +`输出 = "收到:" + 输入` -> io.print(输出) +`io.print(输出)` ```` **C. 同一个 GFM 表格运行不同的 `.mq.md` 算法**: ````markdown -## 分析数据 +## @exec 分析数据 | 名称 | 分数 | | --- | ---: | @@ -576,12 +595,12 @@ F ∈ L(K,E) 表格是数据,不在渲染时执行;函数通过显式数据引用取得逻辑 Table。 -**结果 = table.filter(输入表, 过滤函数)** +`结果 = table.filter(输入表, 过滤函数)` -*结果* +`return 结果` ```` -B/C 中的函数名、输入参数和文档表格访问均仅为目标接口示意,须在真正实现时遵守冻结的 `##` 函数声明、参数推断/导入和文档资源寻址规则。**不能为了示例好看就把尚不存在的语法当成现实。** +B/C 中的函数名、输入参数和文档表格访问均仅为目标接口示意,须在真正实现时遵守冻结的 `## @exec` 函数声明、参数推断/导入和文档资源寻址规则。**不能为了示例好看就把尚不存在的语法当成现实。** --- ## 8. 重构目标架构、仓库组织与实际代码改动 diff --git a/docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md b/docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md index 994c43f..66dcf57 100644 --- a/docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md +++ b/docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md @@ -4,18 +4,30 @@ > implemented behavior. The implemented first slice is described in > [`architecture/CURRENT.md`](architecture/CURRENT.md). +> **Syntax note — RFC-LANG-0002 is the current language contract.** The +> compute / memory / resource / ABI model in this RFC is still the current +> design input. Its `.mq.md` examples and Markdown-role wording were migrated +> to the single current syntax +> ([RFC-LANG-0002](architecture/RFC-LANG-0002-unified-semantics.md), +> [ADR-0052](adr/0052-unified-markdown-semantics.md)): `## @exec` heading +> modes, `params`, `return`, `if/else/end`, `while/end`, and one-statement +> payloads carried by `Strong`, `Emph` or inline `Code`. Any remaining old +> spelling (for example "`##` function, `**` execute, `*` return") is +> historical and is **not** an active language. The Rust frontend still +> implements the pre-RFC mapping, so these examples are target syntax, not +> currently runnable programs; see [`STATUS.md`](STATUS.md). -> **状态**:设计提案(Draft,未实施,未批准) -> **日期**:2026-11-20 -> **建议归档路径**:`docs/architecture/RFC-CM-0001-compute-machine.md` -> **验证基线**:`cflmy/marqdo-cli`,Git 提交 `a113d894962d8c00eb02efb42e0e73f8b084a1fa`(检索于 2026-11-20) +> **状态**:设计提案(Draft,未实施,未批准) +> **日期**:2026-11-20 +> **建议归档路径**:`docs/architecture/RFC-CM-0001-compute-machine.md` +> **验证基线**:`cflmy/marqdo-cli`,Git 提交 `a113d894962d8c00eb02efb42e0e73f8b084a1fa`(检索于 2026-11-20) > **兼容性**:涉及 `Value`、表达式赋值、运行时、主机能力和线协议的变更,必须通过 ADR、规范版本与相应测试;本 RFC 不声明任何新接口目前可用。 --- ## 摘要 -Marqdo 的优势不应只是用 Markdown 排版代码,而应是:在不更换 Markdown 语法角色的前提下,以**自身定义的计算语义**构造算法、数据结构、运行时工具和知识制品。现有解释器已提供整数、浮点、文本、列表、映射、控制流和函数调用,但尚未提供**由 Marqdo 程序控制的可寻址字节存储**;其赋值左侧仅支持标识符,系统交互集中在一组固定 `HostOp` 与外部插件能力中。这妨碍了用 `.mq.md` 自己编写内存分配器、二进制协议、共享节点结构、虚拟机器等低层算法。 +Marqdo 的优势不应只是用 Markdown 排版代码,而应是:在不更换自身计算模型的前提下,以**自身定义的计算语义**构造算法、数据结构、运行时工具和知识制品。现有解释器已提供整数、浮点、文本、列表、映射、控制流和函数调用,但尚未提供**由 Marqdo 程序控制的可寻址字节存储**;其赋值左侧仅支持标识符,系统交互集中在一组固定 `HostOp` 与外部插件能力中。这妨碍了用 `.mq.md` 自己编写内存分配器、二进制协议、共享节点结构、虚拟机器等低层算法。 **提议:以“托管值 + 多个可增长的线性内存区域 + 不透明系统资源”为计算机器的三个基础领域。** @@ -45,12 +57,12 @@ Marqdo 必须能在不借助 Python、JavaScript 或宿主语言提供专门算 ### 1.3 设计原则 -**P1 语义最小而充分**:首先增加无法由现有表达式自然实现的基础机制,不先增加高级 API 或新关键词。 -**P2 高级能力在语言中生长**:新增算法/数据结构不修改解释器、不修改 `HostOp`、不需要重新编译 CLI。 -**P3 读写位置统一**:索引读取和索引赋值遵循同一类“位置”语义;`Memory` 的读取/写入是基础例子,普通列表的值语义不得无声改变。 -**P4 内外边界诚实**:内存操作是语言计算;操作系统 I/O 依赖权限、平台接口和底层实现。 -**P5 可读性**:普通 Markdown 文档仍然可读;`##`/`**`/`*`/列表/blockquote 的现有角色不因本 RFC 改变。 -**P6 安全与可验证性**:将可验证的保证限定在区域边界和权限边界;不对自定义分配器的块级错误作虚假保证。 +**P1 语义最小而充分**:首先增加无法由现有表达式自然实现的基础机制,不先增加高级 API 或新关键词。 +**P2 高级能力在语言中生长**:新增算法/数据结构不修改解释器、不修改 `HostOp`、不需要重新编译 CLI。 +**P3 读写位置统一**:索引读取和索引赋值遵循同一类“位置”语义;`Memory` 的读取/写入是基础例子,普通列表的值语义不得无声改变。 +**P4 内外边界诚实**:内存操作是语言计算;操作系统 I/O 依赖权限、平台接口和底层实现。 +**P5 可读性**:普通 Markdown 文档仍然可读;按 RFC-LANG-0002,执行语义只由 `@exec` 模式与载荷中的 `if`/`else`/`while`/`end`/`return` 关键字决定,普通 `##`/`**`/`*`/列表/blockquote 不内建指令角色。 +**P6 安全与可验证性**:将可验证的保证限定在区域边界和权限边界;不对自定义分配器的块级错误作虚假保证。 **P7 零隐式权限**:能够导入模块、持有字符串或解析文档,不代表拥有文件、网络或设备访问权。 ## 2. 现有仓库事实及需要保留的设计 @@ -344,28 +356,28 @@ Memory 支持字节缓冲区与数据布局,但 GPU 计算仍需要执行后 这一方案故意**只修改最少的表达式语义**。 -- `##` 函数、`**` 执行、`*` 返回、Markdown 列表与引用规则继续维持规范。 +- 函数由 `## @exec 名称` 声明;执行/返回/条件/循环由载荷中的 `if`、`else`、`while`、`end`、`return` 关键字决定(RFC-LANG-0002);Markdown 列表与引用只是文档容器。 - `[]()` 是**文档/知识的静态寻址**;动态 Memory 的字节偏移属于执行期位置,两者不强行共享 URI 语法。 - 普通 GFM 表格是文档值;可用于初始化/展示内存快照,但不会自动变成内存分配器。 - `memory.new(...)` 与 `resource.open(...)` 都可按普通函数调用表达;不新增 `memory`、`pointer`、`asm`、`register` 这样的语法关键字。 - 内存状态变化可选输出可读 GFM Table 供 View/Proof 使用;证明必须以抽象执行语义为依据,而不是假设表格文本本身就是执行存储。 -示例(**候选语法,当前尚不可运行**): +示例(**目标语法,按 RFC-LANG-0002 书写;当前尚不可运行**): ````markdown -## 研究一个字节缓冲区 +## @exec 研究一个字节缓冲区 此函数演示“可引用的存储区域”与普通 Markdown 叙述并存。 -**区域 = memory.new(1, 4)** +`区域 = memory.new(1, 4)` -**`区域[8] = 42`** +`区域[8] = 42` -**另一个名字 = 区域** +`另一个名字 = 区域` -**`另一个名字[9] = 99`** +`另一个名字[9] = 99` -*区域[8] + 区域[9]* +`return 区域[8] + 区域[9]` ```` 预期结果 141。注意这里 `另一个名字 = 区域` 分享 Memory 身份;一般列表/表格并不因此被改造成共享字节缓冲区。 @@ -388,7 +400,7 @@ Memory 支持字节缓冲区与数据布局,但 GPU 计算仍需要执行后 - `marqdo-value`:新增不可伪造的 Memory 值表示;必要时添加 ResourceHandle,注意现有 PluginHandle 不能随意直接复用为 OS 资源句柄。 - `marqdo-expression`:`AssignTarget` 的 Local / Index 变体;保留原有表达式读取。 -- `marqdo-frontend`:更新表达式 AST 对应 IR 和定位信息;不改变 Markdown 语义映射。 +- `marqdo-frontend`:更新表达式 AST 对应 IR 和定位信息;不改变 RFC-LANG-0002 定义的模式/载荷映射(语法迁移是独立的全仓库工作)。 - `marqdo-runtime`:Memory 实例生命周期/增长/边界检查/预算;执行位置写入;参考解释器。 - `marqdo-host`:逐步提供可注册资源操作的能力边界;必须保持旧 `HostOp` 兼容窗口,不能一次砍断所有旧调用。 - `marqdo-package` / CLI:发布标准库兼容信息,继续利用已存在的 path/Git pinned lock;资源授权仍由真实操作者提供。 @@ -425,7 +437,7 @@ marqdo-stdlib/ ### R1:最小可寻址存储(核心里程碑) - `Memory` 区域:创建、大小、增长、读取一字节、写入一字节;实现总/单区域预算、错误恢复与 trace。 -- 支持 `**\`m[8] = 42\`**` 这类现有 Markdown 负载中的索引赋值。 +- 支持 `` `m[8] = 42` `` 这类现有 Markdown 载荷中的索引赋值。 - 不开放裸指针、不引入新寄存器、不改旧 List/Map/Table 的赋值与复制行为。 - 运行跨区域隔离与别名测试;报错不能导致原有区域被污染。 diff --git a/docs/NEXT_PHASE_IMPLEMENTATION.md b/docs/NEXT_PHASE_IMPLEMENTATION.md index 8baef13..c453a96 100644 --- a/docs/NEXT_PHASE_IMPLEMENTATION.md +++ b/docs/NEXT_PHASE_IMPLEMENTATION.md @@ -5,6 +5,13 @@ > for next-phase work and is not current status. See > [`architecture/CURRENT.md`](architecture/CURRENT.md) for the tree as it is today. > Keep this file as design history; do not use it as an implementation claim. +> +> **语言语义已被取代:** 本文件出现的 `Strong`/`Emph`/有序列表/无序列表/引用块 +> 程序角色是旧映射,已被 +> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md) +> ([ADR-0052](adr/0052-unified-markdown-semantics.md))废止。现行唯一语言规范 +> 是该 RFC 与 `spec/mapping.md` / `spec/expression.ebnf`;下列 M0.6 路线、 +> 审计与验收均为历史输入。§3 的旧语法示例已替换为目标语法并标注历史。 > **文档性质**:面向没有参与任何历史讨论的开发者的独立架构决策、实施计划及验收契约。 @@ -20,7 +27,7 @@ 本文件用于告诉陌生开发者“下一步为什么做、具体做什么、哪些不要做、怎样验收”,**不是**另起一套取代现有实现的语言规范。建议依次阅读: -1. `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`:后续稳定化、协议冻结与独立生态准入的当前阶段规范(Proposed);先用它刷新基线与发布门槛。 +1. `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`:历史稳定化/协议冻结规范(Proposed,审查基线 `0adebe4`);语言与路线已被 RFC-LANG-0002 和 `STABLE_RELEASE_IMPLEMENTATION.md` 取代,仅作历史输入。 2. 本文件:产品边界、M0.6 实施次序与发布条件。 3. `docs/STATUS.md`:M0.5 当前实现的阶段性记录;该文件可能因后续修复提交而局部滞后,存在冲突时以当前源码和回归测试为准,并同步修正状态表。 4. `spec/markdown-profile.md`、`spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`:**现有语言行为的规范来源**。 @@ -42,7 +49,7 @@ - 对外输出**稳定、最小、版本化**的数据契约,不公开整个私有 IR 并让三个外部仓库依赖 Rust 内部结构。 - **用户入口统一,工程仓库独立**:通过同一 `Tool Protocol` 安装任意合规清单后自动得到 `marqdo `。`view`、`knowledge`、`prove` 只是示例,不在 CLI 中注册硬编码的特殊名字、发布地址或适配器。 - 拒绝为了“以后可能有用”增加顶层命令;先用真实消费者需求、测试和 ADR 证明必要性。 -- **开放扩展点,但不开放语言语法的任意重定义**:允许注册外部函数、工具、内核、依赖来源;禁止插件重新解释 `Strong`、`Emph`、列表或引用的核心语义。 +- **开放扩展点,但不开放语言语法的任意重定义**:允许注册外部函数、工具、内核、依赖来源;禁止插件重新解释标题模式、载荷载体、关键字控制流或容器语义(RFC-LANG-0002;旧 `Strong`/`Emph`/列表/引用映射已废止)。 - **允许破坏性修正错误架构**:现处 `0.1.0` 早期阶段,凡未对外冻结或存在显著扩展阻塞的内部 API 可重构;涉及公开 ABI、wire、清单或语言行为时必须显式升级版本、加负例和迁移说明。 ## 1. 本次真实仓库审查(不是假定的空仓) @@ -184,7 +191,7 @@ Python/Node 可以继续作为内置 provider;新增 Julia/R/自定义内核 当前项目版本 `0.1.0`,**不对错误设计承担无限兼容义务**。开发者应优先保证未来长期正确性,而不是维护早期内部 enum 的表面稳定。推荐机制: - **内部接口(可以直接破坏)**:`HostOp` 分发、`Builtin` 内部查找、`PluginSlot` 单 namespace、模块 loader、非公开 IR、CLI 命令内部结构;每次变更要有迁移 PR、替换后的测试和明确的 PR 说明。 -- **用户可见语义(默认保护)**:`Strong/Emph/List/Quote` 语义、显式 YAML import、无括号调用的拒绝规则、链接不执行、函数参数推断等。若发现客观错误,也必须有 ADR、版本升级和一致性金样,而不能把“扩展性”当作随意改语法的理由。 +- **用户可见语义(默认保护,现行见 RFC-LANG-0002)**:`@exec`/`@knowledge` 模式与继承、Exec H2 可调用性、`Strong`/`Emph`/行内 `Code` 载荷等价、`if/else/while/end/return/params`、显式 YAML import、链接不执行、函数参数推断等。若发现客观错误,也必须有 ADR、版本升级和一致性金样,而不能把“扩展性”当作随意改语法的理由。(原文的 `Strong/Emph/List/Quote` 是旧映射,已废止。) - **版本化公共协议(只能显式破坏)**:Tool Protocol、Analysis/Trace、插件 ABI、Value Wire、Lock 格式。新旧同时可用或明确不兼容均可,但不能把 schema 名不变、字段意义变了当作修复。 - **冗余命令(可以有序削减)**:`init`、`inspect`、`fmt`、`plugin inspect`、`remove`、`lock` 等仅作为现有 0.x 行为,保留要以维护收益证明;公开主线禁止因此增加更多命令。删除时提供对应的文档内替代方式,避免把重要能力一起删除。 @@ -275,38 +282,55 @@ docs/ - Analysis/Trace 导出器读取核心已产生的数据,禁止维护另一套符号解析器。 - 外部工具不能反向要求核心增加 `knowledge`, `proof`, `view` 专用类型或运行逻辑。 -## 3. 语言行为在本次迭代中保持冻结 +## 3. 语言行为在本次迭代中保持冻结(历史章节) -### 3.1 Markdown 结构的唯一语义 +> **历史说明:** 本节写于 RFC-LANG-0002 之前,原文描述的 `Strong`/`Emph`/列表/ +> 引用块映射已被废止。原文的“本次迭代冻结旧映射、函数体外惰性告警”不再是 +> 现行设计;现行规则是标题模式 + 统一载荷 + 关键字控制流,非法载荷为硬错误 +> 且旧 `.mq.md` 源不可执行。下面保留改写后的示例仅用于说明目标语法;它不是 +> 本 M0.6 计划的实现承诺。 -在 **level-2 函数体内部**(当前 ADR-0002):`Strong` = 计算/赋值;`Emph` = 退出函数并返回;`OrderedList` = 有序首匹配分支;`BulletList` = 条件循环;`BlockQuote` = 显式调用;`Text` = 惰性叙述;`CodeSpan` 在分支/循环头的特定结构位置表示条件;`Link` = 静态引用;数学节点与代码围栏 = 原生惰性资源。一级标题给命名空间,二级标题给函数,三级及以上标题给文档分节。 +### 3.1 Markdown 结构的唯一语义(RFC-LANG-0002) -函数体外不执行程序;现有 ADR-0002 规定可疑“执行节点”惰性并告警,而不是直接在模块根运行。除非另提 ADR,不要偷偷改为硬错误。源码同义 Markdown 结构(例如 `**x**` / `__x__`)按同一 AST 语义执行;也不因为正文中文有“如果/返回/执行”就推断控制流。 +在 Exec 范围(显式 `@exec` 或从祖先继承)内:标题声明/继承 `@exec` 与 +`@knowledge` 模式;只有 Exec H2 是可调用函数;`Strong`、`Emph`、行内 `Code` +是等价的单语句载荷载体;`if`/`else`/`while`/`end`/`return`/`params(...)` +决定控制与签名;`Text` = 惰性叙述;`Link` = 静态引用;数学节点与代码围栏 = +原生惰性资源;有序列表、无序列表与引用块只是容器,不产生指令。一级标题给 +命名空间/默认模式,二级标题给函数(Exec)或知识单元(Knowledge),三级及 +以上标题只给文档分节并继承所属函数。 + +函数体外不产生执行投影;Exec 载荷若没有所属 H2 函数是 +`sem.exec_without_function` 硬错误,绝不提升为模块级执行。源码同义 Markdown +结构(例如 `**x**` / `__x__`)在载荷提取上等价;不因为正文中文有“如果/返回/ +执行”就推断控制流。 ```markdown -# 数学 +# @exec 数学 -## 阶乘 +## @exec 阶乘 输入 `n`,计算非负整数的阶乘。 -1. `n <= 1`,递归基。 +`params(n: Int)` - *1* +`if n <= 1` -2. `n > 1`,继续递归。 +`return 1` - **结果 = n * 阶乘(n=n-1)** +`else` - *结果* +`return n * 阶乘(n=n-1)` + +`end` ``` -期望:`marqdo call factorial.mq.md 数学.阶乘 --arg n=5` 返回 `120`。实际放置测试时以现有 `examples/factorial.mq.md` 为准并追加金样,**不要为了执行把示例转换成 Python**。 +期望(目标语法,前端尚未迁移):`marqdo call factorial.mq.md 数学.阶乘 --arg n=5` 返回 `120`。实际放置测试时以迁移后的示例与金样为准,**不要为了执行把示例转换成 Python**。 ### 3.2 函数与参数推断必须严格而可检查 - 标题保持自然名称,如 `## 计算圆面积`,**不要把参数名强制放进标题**;标题变更可能影响 Markdown 锚点,参数变更不应顺便破坏链接。 -- 显式签名放在约定的标题后独立 `CodeSpan` 段落,例如 `` `(r, precision=2)` ``;无签名允许静态形参推断。 +- 显式签名写成 Exec H2 的第一条直接载荷 `params(r, precision=2)`(或带类型 `params(r: Number, precision: Int = 2)`);无签名允许静态形参推断。旧“标题后独立 CodeSpan `(r, precision=2)`”签名已被 RFC-LANG-0002 废止。 - 参数推断源于执行表达式及控制流的自由变量/确定赋值分析,不从叙述文本或 LLM 中猜测;可见未初始化局部变量应报错。 - 推断签名默认只接受具名调用,显式签名可接受位置调用;无参数调用仍用括号 `()`;调用的解析器只有一套。 - 重复形参、错误实参、未解析别名、变量读写歧义产生稳定诊断码。 @@ -317,9 +341,9 @@ docs/ - 表达式解析来自 `marqdo-expression`,不是“普通 Markdown 括号里藏 Python”。 - 既有 ADR-0007 采用任意精度整数及类型化 wire v1;浮点、布尔和 `Unit` 语义以 `spec/evaluation.md` 为准。变更必须同步 ABI/Foreign/wire 的兼容性测试。 -- `OrderedList` 的首个条件头为符合结构规定的 `CodeSpan`;同一段落里条件后的叙述和后续缩进段落不参与条件求值。无 `CodeSpan` 的清单在函数内是非法分支,不回退成普通清单。 -- `BulletList` 的每个 item 是一个 `while` 条件与循环体;不默认把 `- [ ]` 任务清单当普通 UI 清单。 -- 引用块一次只表达一个显式调用;链接形式调用是否跨文件支持由 `spec/references.md` 目前的限制决定,不能为了满足文档示例绕过模块 loader。 +- 条件不再由列表首段 CodeSpan 表达:写 `if ` … `end`,列表只是容器。旧“`OrderedList` 首段 CodeSpan 条件头”规则已被 RFC-LANG-0002 废止;普通列表在 Exec 范围内按源序提取合法载荷,零语句投影是合法惰性结构。 +- 循环写 `while ` … `end`;不再把每个 bullet item 当作独立 while。`- [ ]` 任务清单与普通列表一样没有隐含指令。 +- 引用块不是调用;调用必须来自 Exec 载荷中的表达式。跨文件调用是否支持由 `spec/references.md` 的显式导入限制决定,不能为了满足文档示例绕过模块 loader。 - 公式和代码块必须先构建惰性值,只有 `math.*`、`foreign.*` 或明确 Host API 才能执行;不自动运行任意外部语言。 ### 3.4 引用的最小承诺 @@ -632,7 +656,7 @@ Core 不包含 Lean、Proof IR、证明驱动器或证书存储。新的证明 ### 12.3 `marqdo-view` -默认按原 Markdown 阅读,不执行;使用 Analysis v1 对源码 Strong/Emph/分支/循环和函数做精确标注。存在真实 Trace v1 时,可选择播放调用帧与历史结果;若用户选择运行,View 须明确发起 `marqdo run/call` 并尊重沙箱与权限。它不实现第二个解释器、第二个静态语义分析器,不将未运行的语义节点当成已执行结果。 +默认按原 Markdown 阅读,不执行;使用 Analysis v1 对源码标题模式、载荷、`if`/`while`/`return` 控制流和函数做精确标注。存在真实 Trace v1 时,可选择播放调用帧与历史结果;若用户选择运行,View 须明确发起 `marqdo run/call` 并尊重沙箱与权限。它不实现第二个解释器、第二个静态语义分析器,不将未运行的语义节点当成已执行结果。 ### 12.4 对外工具的独立性条件 @@ -708,13 +732,13 @@ Core 不包含 Lean、Proof IR、证明驱动器或证书存储。新的证明 | EXT-PACKAGE | 相同包多版本、项目跨目录、全局缓存移动、Git pin、离线同步、锁漂移 | `ModuleId` 依赖物理路径,知识/证明制品不可复用 | | EXT-KERNEL | 注册从未内置的语言标签、缺 provider、超时、非授权进程、wire 版本冲突 | Foreign 不可真正扩展或会绕开 Host | | EXT-ABI | 多 namespace、重复 export、跨语言 C/Rust 示例、ABI 主版本拒绝、Worker crash、capability broker、伪造句柄与重放拒绝 | C ABI 宣称可扩展但只支持固定单一路径 | -| EXT-SEMANTIC | 修改普通叙述后的执行 IR 稳定;外部组件不能改变 `Strong/List` 等 AST 意义 | 将“扩展”错误扩大到语言执行规则 | +| EXT-SEMANTIC | 修改普通叙述后的执行 IR 稳定;外部组件不能改变标题模式/载荷/容器等 AST 意义 | 将“扩展”错误扩大到语言执行规则 | | EXT-CONSUMER | Core 公开 JSON 在 Rust 私有 IR 改动之后仍与独立客户端兼容;Reference 非执行 | 外部仓库将被迫跟随 Core 频繁升级 | | 测试域 | 正例 | 必须负例/反例 | 测试位置 | |---|---|---|---| -| Markdown AST | Strong/Emph/list/quote/heading、CJK、多行、GFM table、Math | 强调嵌套、缺失条件、task-list 错位、parser 版本漂移 | `tests/conformance/ast` + profile tests | +| Markdown AST | heading modes、payload carriers(Strong/Emph/Code)、lists/quotes、CJK、多行、GFM table、Math | 嵌套载荷、模式拼写、缺失 `end`、task-list 错位、parser 版本漂移 | `tests/conformance/ast` + profile tests | | 语言求值 | 阶乘、递归、嵌套分支、函数调用、命名实参、返回 | 未初始化、重复参数、非法返回、fuel/stack 超限 | `tests/conformance/semantics` + negative | | 叙述不变性 | 只修改普通正文,IR/值不变 | 文本中插 `if/return` 不改变结果 | `crates/cli/tests/properties.rs` | | 函数接口 | 推断形参、显式签名、跨模块别名 | 名称冲突/模糊/缺少参数/错误签名 | frontend + CLI tests | @@ -785,7 +809,7 @@ cargo build -p marqdo-cli 维护者可以用以下清单判断是否允许另一名未参与设计讨论的开发者独立推进项目: -- [ ] 能解释为什么 Marqdo 的 Strong/Emph/List/Quote 具有固定控制流,而 Text 不执行。 +- [ ] 能解释为什么 Marqdo 的模式/载荷/关键字控制流是确定的,而 Text 与容器不执行。 - [ ] 知道唯一 Markdown parser 在哪里;不会编写第二套行正则解析器。 - [ ] 能在 `spec/mapping.md` 定位函数、分支、循环和返回的约束。 - [ ] 能在 `crates/marqdo-runtime` 找到原生求值,在 `marqdo-host` 找到所有副作用检查。 diff --git a/docs/NEXT_RELEASE_CI_CONVERGENCE.md b/docs/NEXT_RELEASE_CI_CONVERGENCE.md index 9c81820..2273faa 100644 --- a/docs/NEXT_RELEASE_CI_CONVERGENCE.md +++ b/docs/NEXT_RELEASE_CI_CONVERGENCE.md @@ -1,9 +1,18 @@ # Marqdo CLI:CI 收敛、语言边界回归与稳定发行实施规范 -> **Historical baseline (`c9f01aa8`, 2026-11-20).** The CI SHA and run -> below are a snapshot. Refresh the remote SHA and CI evidence before use. -> The current overview is [`architecture/CURRENT.md`](architecture/CURRENT.md); -> executed status is in [`STATUS.md`](STATUS.md). +> **Historical / Superseded baseline (`c9f01aa8`, 2026-11-20).** The CI SHA +> and run below are a snapshot. Refresh the remote SHA and CI evidence before +> use. The current overview is +> [`architecture/CURRENT.md`](architecture/CURRENT.md); executed status is in +> [`STATUS.md`](STATUS.md). Next-phase work is governed by +> [`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md). +> +> **语言语义已被取代:** 本文件的 Markdown/`**` 语义讨论写于 RFC-LANG-0002 之前; +> `Strong`=语句、`Emph`=返回、有序列表=分支、无序列表=循环、CodeSpan 条件头、 +> BlockQuote=调用的旧映射已被 +> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md) +> ([ADR-0052](adr/0052-unified-markdown-semantics.md))废止。§3 的旧语法示例已替换 +> 为目标语法并标注历史;现行规范见 `spec/mapping.md` / `spec/expression.ebnf`。 > **文档性质:** 可直接入库的执行规范 / Release Convergence Plan。供未阅读任何历史聊天的维护者、贡献者与 DeepSeek Harness 使用。 @@ -55,7 +64,7 @@ marqdo-markdown:固定 Comrak/CommonMark/GFM/Math profile(唯一 Markdown │ Canonical MdNode + byte Span ▼ marqdo-frontend:Heading 作用域/导入/参数推断/Markdown AST→IR - │ 条件头、分支、循环、调用、引用、源码位置 + │ 标题模式、载荷、控制关键字、引用、源码位置 ▼ marqdo-ir + marqdo-expression:可执行 AST/强类型表达式语法 │ @@ -184,23 +193,28 @@ bwrap: Creating new namespace failed: Resource temporarily unavailable ## 3. Markdown 与乘方:从疑虑收缩为正式回归测试 -### 3.1 已确定的语义,不得擅自改变 +### 3.1 已确定的语义,不得擅自改变(已按 RFC-LANG-0002 更新) -Markdown 源码经过冻结 Comrak profile。`##` 定义函数;普通函数段落中的 `Strong` 是可执行语句;`Emph` 是返回表达式;有序列表是分支,无序列表是循环;列表项第一段的**首个 CodeSpan** 是条件表达式;后续普通文字可解释目的;BlockQuote 是显式调用。完整计算表达式由独立 Marqdo 表达式解析器解释。 +> **历史说明:** 本节原文写于旧映射时期(`##` 无条件函数、`Strong`=语句、 +> `Emph`=返回、有序列表=分支、无序列表=循环、首段 CodeSpan=条件、 +> BlockQuote=调用)。该映射已被 RFC-LANG-0002 废止,原文中的“不要以修复乘方 +> 为由改语法”等表述是当时语境;现行规则如下。 -**用户本地实测**已经说明:适当空格使 Markdown 按预期生成 AST,乘方可以正确运行。故这一轮**不应以“修复乘方”为由重新设计强/斜体语法**。Markdown 标记本身具有分隔符词法规则:紧凑写法造成不同 AST 属于需要准确文档化的语言边界,而不是一律归咎解释器。 +Markdown 源码经过冻结 Comrak profile(Markdown profile 不变)。现行映射:标题以 `@exec`/`@knowledge` 声明模式并从祖先继承;只有 Exec H2 是可调用函数;`Strong`、`Emph`、行内 `Code` 是等价的单语句载荷载体;`if`/`else`/`while`/`end`/`return`/`params(...)` 决定控制与签名;列表、引用块、段落只是容器。完整计算表达式由独立 Marqdo 表达式解析器解释。 + +Markdown 标记仍具有分隔符词法规则:紧凑写法造成不同 AST 属于需要准确文档化的语言边界,而不是一律归咎解释器。因此目标语法推荐把表达式放进独立的行内 CodeSpan 载荷;`**` 只有在载荷提取后才作为乘方运算符。 ```markdown -## main +## @exec main -**n = 2** +`n = 2` -**`n = n ** 2`** +`n = n ** 2` -> print(n) +`print(n)` ``` -以上是建议的、对 `**` 乘方运算最稳妥的可读写法:外围 Strong 定义执行语句,内部 CodeSpan 避免 Markdown 把计算运算符看作强调分隔符。对于本机已经验证能形成正确 AST 的空格写法,也应以 AST 金样记录,不应禁止。 +以上为目标语法示例(前端尚未迁移,不能原样运行):独立行内 CodeSpan 作为载荷,避免 Markdown 把计算运算符看作强调分隔符。对于能形成正确 AST 的写法,也应以 AST 金样记录。 **正式判断标准:** `marqdo inspect --ast` 的 Comrak AST 是否对应规范结构;其后 `check`/`run` 是否按该结构执行。不得为“猜测用户想写什么”而增加原始 Markdown 正则修复器,也不得因源码像表达式就跳过 Markdown AST。 @@ -218,38 +232,40 @@ Markdown 源码经过冻结 Comrak profile。`##` 定义函数;普通函数段 | 编号建议 | 源码表达 | 预期 | 证明什么 | |---|---|---|---| -| 37 | `*` + CodeSpan(`2 ** 3 ** 2`) + `*` | `Int 512` | Markdown→右结合解析→求值 | -| 38 | `*` + CodeSpan(`-2 ** 2`) + `*` | `Int -4` | 一元负号优先级 | -| 39 | `*` + CodeSpan(`(-2) ** 2`) + `*` | `Int 4` | 括号与优先级 | -| 40 | `*` + CodeSpan(`2.0 ** -1`) + `*` | `Float 0.5` | 浮点负指数 | -| 41 | `**` + CodeSpan(`n = 2 ** 3`) + `**`,然后返回 `n` | `Int 8` | Strong + CodeSpan 嵌套路径 | -| 42 | 有序列表条件 `` `n ** 2 == 4` `` + 叙述 + 引用调用 | 只调用真分支 | 条件 Markdown / 段落 / 控制流 | -| 43 | 无序列表条件 `` `n ** 2 < limit` `` + 叙述 + 递增 | 预期迭代和返回 | 循环、条件重新求值、乘方 | +| 37 | 独立 CodeSpan 载荷 `` `2 ** 3 ** 2` `` | `Int 512` | Markdown→右结合解析→求值 | +| 38 | 独立 CodeSpan 载荷 `` `-2 ** 2` `` | `Int -4` | 一元负号优先级 | +| 39 | 独立 CodeSpan 载荷 `` `(-2) ** 2` `` | `Int 4` | 括号与优先级 | +| 40 | 独立 CodeSpan 载荷 `` `2.0 ** -1` `` | `Float 0.5` | 浮点负指数 | +| 41 | 载荷 `` `n = 2 ** 3` `` 后 `` `return n` `` | `Int 8` | 赋值 + return 关键字 | +| 42 | `` `if n ** 2 == 4` `` + 打印 + `` `else` `` + 打印 + `` `end` `` | 只执行真分支 | 关键字分支 / 载荷 / 控制流 | +| 43 | `` `while n ** 2 < limit` `` + 递增 + `` `end` `` + `` `return n` `` | 预期迭代和返回 | 循环、条件重新求值、乘方 | -例如,给 42 建立下述源文件;相应 expected 的 `stdout` 应为 `乘方正确\n`,返回值应为 `Unit`,实际 JSON 具体类型按已存在 wire-v1 金样约定构造: +例如,给 42 建立下述(目标语法)源文件;相应 expected 的 `stdout` 应为 `乘方正确\n`,返回值应为 `Unit`,实际 JSON 具体类型按已存在 wire-v1 金样约定构造: ```markdown -## main +## @exec main -**n = 2** +`n = 2` -1. `n ** 2 == 4`,正确分支的自然语言说明。 +`if n ** 2 == 4` - > print("乘方正确") +`print("乘方正确")` -2. `n ** 2 != 4`,另一分支的说明。 +`else` - > print("乘方错误") +`print("乘方错误")` + +`end` ``` 对 41: ```markdown -## main +## @exec main -**`n = 2 ** 3`** +`n = 2 ** 3` -*n* +`return n` ``` ### 3.4 必须新增的负向/边界测试 @@ -259,18 +275,23 @@ Markdown 源码经过冻结 Comrak profile。`##` 定义函数;普通函数段 | `2 ** -1`,纯 Int | 类型错误;不是神奇地得到 `0.5` | Runtime error fixture | | `2 ** 100001` | `resource.exhausted`(当前指数限额) | Runtime error fixture | | `2 **` | 解析器诊断非法表达式,正确源码 span | 负向 fixture | -| 列表头 `` `n ** 2 ==` `` | 条件表达式语法错误,定位到原 Markdown 源码中缺失操作数的位置 | Frontend / CLI error | +| `if` 条件 `` `n ** 2 ==` `` | 载荷语法错误,定位到原 Markdown 源码中缺失操作数的位置 | Frontend / CLI error | | 多反引号 CodeSpan 包含 `**` | 仍能正确映射完整表达式与字节 Span | AST + frontend | | `**n=n**2**` 等缺少空格的 Markdown 边界 | 固定 Comrak 真实 AST,不推断用户意图,不自动更正 | AST golden + 文档例子 | | `**n = n ** 2**`(有空格) | 在实际 profile 中确认 AST,再据此固定接受/拒绝结果 | AST + CLI | -| 普通叙述段落出现 `` `n ** 2` `` | 不执行计算、不被作为分支条件 | 结构/副作用性质测试 | +| `@knowledge` 段落出现 `` `n ** 2` `` | 不执行计算、不产生 IR | 结构/副作用性质测试 | | 代码围栏中出现 `**` | 保持惰性,不会触发运算 | AST + inert fixture | | 纯说明段落的修改 | 可执行 IR/实际结果不变 | property test | | 强行嵌套 Markdown 强调导致非法 payload | 给出诊断,不静默换另一计算规则 | negative test | -**条件头被吞掉的可执行节点:** 当前 `map.rs::condition_of()` 使用 `&item.children[1..]` 形成分支体,首段里第一个 CodeSpan 后若出现 `Strong` / `Emph`,这些可执行标记可能被整体忽略。建议在原有“首个 CodeSpan + 说明文本”语法上增加一个严格检查:首段剩余结构仅允许惰性叙述(按已冻结 profile 判定),保留其原始 AST 与 SourceSpan;若出现其他可执行角色,报 `markdown.invalid_construct`,不能无声丢弃。先补复现 fixture,再制定必要的精确规则;**无需更换 CodeSpan 条件头的正式语法**。 +> **历史说明:** 以下两段描述的是 RFC-LANG-0002 之前的条件头/CodeSpan +> 实现细节(`map.rs::condition_of()`、`markdown.invalid_construct`)。在现行 +> 映射中列表不再有条件头,载荷统一用 `sem.*` 诊断;这两段只作为旧实现考古, +> 不得据此恢复旧语法。 -**CodeSpan 源码位置:** `condition_of()` 当前使用 `PayloadSegments::single(&literal, condition_node.span)`,须回归验证反引号是否计入字节跨度;若诊断偏移,修正 span 映射而不是改 Markdown AST。要求单/双反引号、中文前缀、换行和多字节 UTF-8 的准确来源测试。 +**条件头被吞掉的可执行节点(旧实现,历史):** 旧 `map.rs::condition_of()` 使用 `&item.children[1..]` 形成分支体,首段里第一个 CodeSpan 后若出现 `Strong` / `Emph`,这些可执行标记可能被整体忽略。旧建议是在“首个 CodeSpan + 说明文本”语法上增加严格检查;该语法已被废止,目标语法改由关键字控制流表达分支。 + +**CodeSpan 源码位置(历史):** 旧 `condition_of()` 使用 `PayloadSegments::single(&literal, condition_node.span)`,须回归验证反引号是否计入字节跨度。该回归要求作为 span 映射经验保留;新 frontend 需为所有载荷载体(Strong/Emph/Code)提供准确字节跨度。 ### 3.5 正确的测试组织与执行命令 @@ -389,7 +410,7 @@ ADR-0021 已实现 Bubblewrap supervisor,Linux strict L1 在专用 Ubuntu 26.0 ### 7.1 关闭条件:最短可衡量路径 - **第一个工作包完成:** G1~G3 全绿(解决旧 CI 三处失败);不再存在 E0433 / 环境依赖的错误断言。 -- **第二个工作包完成:** G5/G6 全绿(乘方、Strong/CodeSpan、列表叙述、负向边界、源 Span);语言语义不需重新设计。 +- **第二个工作包完成(历史验收,旧映射):** G5/G6 全绿(乘方、Strong/CodeSpan、列表叙述、负向边界、源 Span);该结论对应旧映射,语言语义已由 RFC-LANG-0002 重写。 - **第三个工作包完成:** G7/G8 全绿或清楚地标为非承诺子能力;独立 Tool 消费无硬编码。 - **第四个工作包完成:** G9 由专用 VM 自托管 CI 在同 SHA PASS,或经负责人明确决定仅发行 G-B 并真正关闭 G-C 声明。 - **第五个工作包完成:** G10/G11 PASS、Release Candidate 清洁安装,再经批准完成 G12。 @@ -492,7 +513,7 @@ Approved by / time: (2) Ubuntu 普通 CI 下 strict probe 与实际启动竞态/资源不足的 fail-closed 契约,并在独立安全 VM 保证严格隔离正向执行与 7/7 攻击矩阵; (3) 增加完整 Markdown AST、乘方、分支/循环条件、源 Span、惰性与 - 错误边界的黄金测试和端到端语义测试,不擅自改 CodeSpan 条件语法; + 错误边界的黄金测试和端到端语义测试;条件头/CodeSpan 旧语法已废止,目标语法见 RFC-LANG-0002; (4) 验证 lock v3、Analysis/Trace、完全通用的 Tool、ABI/Worker/Foreign 的支持矩阵和独立消费者; (5) 完成全平台 CI、同 SHA 的 G-C 证据、Release Candidate 干净安装、 diff --git a/docs/STABLE_RELEASE_IMPLEMENTATION.md b/docs/STABLE_RELEASE_IMPLEMENTATION.md index fb39668..330ba93 100644 --- a/docs/STABLE_RELEASE_IMPLEMENTATION.md +++ b/docs/STABLE_RELEASE_IMPLEMENTATION.md @@ -1,5 +1,15 @@ # Marqdo CLI 稳定版本开发与发布实施总规范 +> **Historical roadmap note / superseded language syntax.** 本文件是稳定版本 +> 规划快照(编写基线 `e966b766`,2026-11-20),不是执行状态记录。其语言前提 +> 早于 +> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md) +> ([ADR-0052](adr/0052-unified-markdown-semantics.md)):旧 `Strong`=执行、 +> `Emph`=返回、列表=分支/循环、引用块=调用的映射已被废止;语言语义只以该 RFC +> 与 `spec/mapping.md` / `spec/expression.ebnf` 为准。发布计划/门槛内容仍可作为 +> 下一阶段规划的参考输入,但必须按当前 HEAD、`docs/STATUS.md` 与迁移台账刷新后 +> 才能当作现行门禁;不得据此声称新语法或任一平台已完成。 + > **定位:** 可直接提交到 `cflmy/marqdo-cli` 的 `docs/STABLE_RELEASE_IMPLEMENTATION.md`,并完整交由 DeepSeek Harness 执行。 > **状态:** Proposed / 下一阶段唯一总体实施计划(必须以实际代码、规范和测试验证结果修正状态)。 > **编写基线:** `cflmy/marqdo-cli`,默认分支 `master`,远程 HEAD `e966b7661f03ee7462df959917f5630353e66b10`(2026-11-20)。 diff --git a/docs/STATUS.md b/docs/STATUS.md index 9cd3ba0..7b3cca6 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -38,9 +38,10 @@ What changed in this migration: What did **not** change in this migration: -* the Rust frontend (`units.rs`, `payload.rs`, `map.rs`, `signature.rs`), the - expression parser and the bundled `stdlib/**/*.mq.md` still implement the - pre-RFC mapping; +* the Rust frontend migration is only partially present in this worktree: + heading-mode/Knowledge-unit plumbing has begun, but the executable mapping + (`map.rs`), statement parser and the bundled `stdlib/**/*.mq.md` still follow + pre-RFC behaviour; * as a result, `cargo test --workspace --locked` is **expected to be red**: the semantic/negative/CLI fixtures now feed the old frontend. The last green workspace run (491 passed, 0 failed, 2 ignored at `8af7262`) is historical @@ -48,6 +49,13 @@ What did **not** change in this migration: * no platform, security or protocol result should be inferred from this documentation migration. +Observed in this worktree +([evidence](evidence/2026-11-21-semantic-docs-migration.md)): +`cargo fmt --all -- --check` PASS; `cargo check --workspace --tests --locked` +PASS; `conformance_ast` 4/4 PASS; `docs_consistency` 4/4 PASS; +`conformance_semantics` and `negative` FAIL as expected against the pre-RFC +frontend. The migrated example lock digest was regenerated with the real CLI. + Remaining work, owners and status: [`migration/README.md`](migration/README.md) and [`migration/semantic-rewrite-inventory.tsv`](migration/semantic-rewrite-inventory.tsv). A release is blocked until the frontend, expression parser, stdlib, fixtures and @@ -123,6 +131,12 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL ## 2. Work package status +> **Pre-RFC baseline warning.** Rows and numbers in this section describe work +> executed before the RFC-LANG-0002 syntax migration. The Markdown/AST and +> platform/security rows remain valid; language-source rows (fixtures, control +> mapping, semantic goldens) are historical and are expected red until the +> frontend migration lands. See §0. + | # | Work package | State | Evidence | |---|---|---|---| | 0 | Windows AST line endings | Fixed locally; **Windows CI UNVERIFIED** | `.gitattributes`, CRLF fixture | @@ -130,8 +144,8 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL | 2 | Cross-platform strict `cfg` | **Fixed locally; native CI UNVERIFIED** | `#[cfg]` dispatch + non-Linux regression test | | 3 | Strict probe→launch race | **Fixed locally; GitHub Linux CI UNVERIFIED** | fail-closed CLI contract + probe-OK/launch-EAGAIN seam test | | 4 | Parallel security matrix isolation | **Fixed** | unique paths + helper `OnceLock`; 7/7 in parallel workspace run | -| 5 | Markdown/power/control-flow corpus | **Done locally** | 160 AST, 73 semantic, 52 compile-negative, 21 runtime-negative fixtures | -| 6 | Condition header + source spans | **Fixed** | executable tails rejected; literal-inside-backtick mapping tests | +| 5 | Markdown/power/control-flow corpus | **Pre-RFC evidence; test text migrated, execution pending** | 160 AST + 73 semantic + 45 compile-negative + 2 warning + 21 runtime-negative fixtures after migration; suites expected red | +| 6 | Condition header + source spans | **Historical (old syntax)** | condition headers were removed by RFC-LANG-0002; payload/source-span rules live in `spec/mapping.md` §3 | | 7 | Independent Tool consumers | **Done locally** | `sample-view`/`sample-knowledge`/`sample-proof` E2E test | | 8 | lock v3 reproducibility | **Implemented; tamper test added** | `package_env` PASS | | 9 | Analysis/Trace/Tool/ABI/Foreign | **Implemented; supported-matrix bounded** | protocol tests, plugin/worker/foreign tests | @@ -144,9 +158,11 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL ## 3. Verified capabilities - Frozen Markdown profile `marqdo.md.v1` with 160 AST goldens and explicit - CRLF byte semantics. -- Native Rust interpreter with 73 semantic goldens, 52 compile-error fixtures, - and runtime error source attribution. + CRLF byte semantics (unchanged by the semantic rewrite). +- Native Rust interpreter (pre-RFC mapping) with 73 migrated semantic fixtures, + 45 migrated compile-error fixtures, 2 warning fixtures and 21 runtime-error + fixtures; the executable suites are **expected red** until the frontend + migration lands, so these are not current PASS evidence. - Native `**` power is pinned end-to-end: right associativity, unary-minus precedence, parentheses, float negative exponents, branch/loop conditions, Strong+CodeSpan payloads, and inert prose/code fences. diff --git a/docs/adr/0002-executables-only-in-function-bodies.md b/docs/adr/0002-executables-only-in-function-bodies.md index ac0cc1f..1a7a9b2 100644 --- a/docs/adr/0002-executables-only-in-function-bodies.md +++ b/docs/adr/0002-executables-only-in-function-bodies.md @@ -1,6 +1,14 @@ # ADR-0002: Executable nodes execute only inside level-2 function bodies -Status: **Accepted** +> **Historical / superseded in part.** The execution-scope decision (payloads +> only inside an owning H2 function, never at module top level) remains, but +> the carrier/role rules in this ADR (`Strong` executes, `Emph` returns, lists +> and quotes are instructions) were replaced by +> [ADR-0052](0052-unified-markdown-semantics.md) and +> [`spec/mapping.md`](../../spec/mapping.md). The syntax examples below are the +> syntax at the time of the decision, not current syntax. + +Status: **Accepted (historical mapping superseded by ADR-0052)** Date: 2026-11-20 ## Context diff --git a/docs/adr/0003-ref-resolution-and-ambiguity.md b/docs/adr/0003-ref-resolution-and-ambiguity.md index f59ae07..188fa0f 100644 --- a/docs/adr/0003-ref-resolution-and-ambiguity.md +++ b/docs/adr/0003-ref-resolution-and-ambiguity.md @@ -1,5 +1,14 @@ # ADR-0003: `ref` resolution order and `ref.ambiguous` (S-07) +> **Historical syntax note.** The AST shape below uses the pre-RFC-LANG-0002 +> spelling, where a `strong` node carried an executable statement. Under the +> current contract +> ([RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md), +> [ADR-0052](0052-unified-markdown-semantics.md), +> [`spec/mapping.md`](../../spec/mapping.md)), `Strong`, `Emph` and inline +> `Code` are interchangeable one-statement payload carriers inside an `@exec` +> scope. The `ref` resolution decision itself remains current. + Status: **Accepted** Date: 2026-11-20 diff --git a/docs/adr/0005-ast-normalization.md b/docs/adr/0005-ast-normalization.md index 3b025c6..29a90af 100644 --- a/docs/adr/0005-ast-normalization.md +++ b/docs/adr/0005-ast-normalization.md @@ -1,5 +1,16 @@ # ADR-0005: AST normalization (Setext headings, task items, code-span ticks, strikethrough) +> **Historical mapping note.** The profile/AST normalization rules in this ADR +> remain current. Its role claims — that ordered/bullet list structure +> "determines branch/loop roles" and that `strong`/`emph` carry execute/return +> roles — were superseded by +> [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) / +> [ADR-0052](0052-unified-markdown-semantics.md) and +> [`spec/mapping.md`](../../spec/mapping.md): lists and block quotes are +> presentation containers, and `Strong`, `Emph` and inline `Code` are +> interchangeable one-statement payload carriers. Strikethrough and the other +> inert regions stay inert. + Status: **Accepted** Date: 2026-11-20 diff --git a/docs/adr/0006-cli-contract.md b/docs/adr/0006-cli-contract.md index f1d8356..2674906 100644 --- a/docs/adr/0006-cli-contract.md +++ b/docs/adr/0006-cli-contract.md @@ -55,6 +55,14 @@ Codes are stable contract. Diagnostic **codes** (for example `markdown.invalid_construct`, `expr.parse`, `symbol.unknown`, `permission.denied`, `ref.ambiguous`) are stable; message wording is not. +> **Historical diagnostic note.** `markdown.invalid_construct` (and the +> executable-shape `Strong`/`Emph`/list/quote errors it described) belongs to +> the pre-RFC-LANG-0002 mapping. Under the current contract +> ([RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) / +> [ADR-0052](0052-unified-markdown-semantics.md), +> [`spec/mapping.md`](../../spec/mapping.md) §8) syntax-role failures use the +> `sem.*` codes. The rest of this CLI contract is unaffected. + ### 3. Stream separation * **Program output** (`打印`/`print`) goes to stdout in text mode. In JSON mode diff --git a/docs/adr/0007-arbitrary-precision-int-and-wire.md b/docs/adr/0007-arbitrary-precision-int-and-wire.md index 2e110dc..3b7220c 100644 --- a/docs/adr/0007-arbitrary-precision-int-and-wire.md +++ b/docs/adr/0007-arbitrary-precision-int-and-wire.md @@ -1,5 +1,13 @@ # ADR-0007: Arbitrary-precision `Int` and the typed wire encoding (S-08) +> **Historical syntax note.** The numeric model and typed wire-encoding +> decisions remain current. The phrase "code spans/plain text of +> `strong`/`emph`/conditions" below describes the pre-RFC-LANG-0002 +> payload/condition mapping; under +> [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) / +> [ADR-0052](0052-unified-markdown-semantics.md), payloads are carried by +> `Strong`, `Emph` or inline `Code` and control flow is keyword based. + Status: **Accepted** Date: 2026-11-20 diff --git a/docs/adr/0022-addressable-memory-and-place-assignment.md b/docs/adr/0022-addressable-memory-and-place-assignment.md index 6df6915..0b31923 100644 --- a/docs/adr/0022-addressable-memory-and-place-assignment.md +++ b/docs/adr/0022-addressable-memory-and-place-assignment.md @@ -1,5 +1,14 @@ # ADR-0022: Addressable `Memory` and Memory-index place assignment (RFC-CM P1) +> **Historical syntax note.** The `Memory` index place-assignment decision +> remains current. The sentence below that "the surface syntax remains a +> `strong` node … no Markdown role, heading or list meaning changes" is the +> historical pre-RFC-LANG-0002 spelling: under +> [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) / +> [ADR-0052](0052-unified-markdown-semantics.md), `m[i] = b` is carried by any +> `Strong`/`Emph`/inline `Code` payload inside an `@exec` scope, and lists, +> quotes and headings carry no instruction role. + Status: **Accepted** Date: 2026-11-20 Relates to: `docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md` (CM-A01/CM-A02/CM-A03), diff --git a/docs/adr/0052-unified-markdown-semantics.md b/docs/adr/0052-unified-markdown-semantics.md new file mode 100644 index 0000000..1ddf658 --- /dev/null +++ b/docs/adr/0052-unified-markdown-semantics.md @@ -0,0 +1,98 @@ +# ADR-0052: Unified Markdown semantics — heading modes, unified payloads and keyword control flow + +Status: **Accepted (target contract; frontend implementation pending)** +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. +* Until the Rust frontend, expression parser, bundled stdlib and fixtures are + migrated, the implemented CLI does **not** accept this syntax. The tree must + not be released or described as complete during that window. See + `docs/STATUS.md`. +* Test fixtures are migrated as text; execution goldens are expected to be red + until the implementation lands. No test may silently keep asserting the old + mapping as current. +* 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. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..8f82dec --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,33 @@ +# Architecture Decision Records (ADRs) + +These files record decisions **at the date they were made**. They are not a +description of current language behavior, implementation state or current +architecture; read them as decision history. + +- **Status is not a current-language claim.** A status such as "Accepted" means + the decision was accepted then, not that its syntax or behavior is still + active. Superseded ADRs keep their original decision text and date; they are + not rewritten. +- **Syntax-role decisions are superseded by + [ADR-0052](0052-unified-markdown-semantics.md).** The earlier mapping — + `Strong` executes, `Emph` returns, ordered list is a branch, bullet list is a + loop, block quote is a call, plus the associated `markdown.inert_executable` / + `markdown.invalid_construct` role diagnostics — is retired. The current + language contract is + [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md), with its + normative summaries [`spec/mapping.md`](../../spec/mapping.md) and + [`spec/expression.ebnf`](../../spec/expression.ebnf): `@exec`/`@knowledge` + heading modes, `Strong`/`Emph`/inline `Code` as interchangeable + one-statement payload carriers, and `if`/`else`/`while`/`end`/`return`/ + `params` keywords. The Rust frontend in this checkout still implements the + pre-RFC mapping; see [`docs/STATUS.md`](../STATUS.md). +- **Infrastructure ADRs** (crates, ABI, capabilities, CLI/JSON contract, + packaging, security isolation) remain current unless a later ADR supersedes + them. ADRs with a historical banner keep the banner scoped to the superseded + part. +- This index is not a spec. For current architecture see + [`docs/architecture/CURRENT.md`](../architecture/CURRENT.md); for executed + status see [`docs/STATUS.md`](../STATUS.md). + +Files: `0001`–`0050`, plus `0051-byte-exact-http-framing.md` (HTTP framing) and +`0052-unified-markdown-semantics.md` (current language mapping). diff --git a/docs/architecture/Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md b/docs/architecture/Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md index f53a535..45c489b 100644 --- a/docs/architecture/Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md +++ b/docs/architecture/Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md @@ -1,5 +1,17 @@ # Marqdo CLI 最新提交架构审查与重构 RFC +> **Historical review input.** This document is a review snapshot frozen at +> commit `7fbe069…` (2026-11-21). It is **not** current architecture, status or +> language guidance. Its responsibility-split analysis (core / runtime / +> platform boundary / stdlib / CLI) remains useful review input, but its +> Markdown-syntax references describe the historical pre-RFC mapping. The +> current language contract is +> [RFC-LANG-0002](RFC-LANG-0002-unified-semantics.md) with +> [`spec/mapping.md`](../../spec/mapping.md) and +> [ADR-0052](../adr/0052-unified-markdown-semantics.md); any old-syntax snippet +> below (e.g. `> resource.write(...)` as a call) is archived spelling, not a +> current tutorial. Status lives in [`../STATUS.md`](../STATUS.md). + > 状态:**审查报告 / 待讨论设计,不是已实施代码** > 仓库:[`cflmy/marqdo-cli`](https://github.com/cflmy/marqdo-cli) > 冻结审查提交:[`7fbe069196e61d06a00d64fe8d65049c327373eb`](https://github.com/cflmy/marqdo-cli/commit/7fbe069196e61d06a00d64fe8d65049c327373eb) @@ -218,7 +230,7 @@ stdin 与 stdout 使用同一个 `ResourceTable`、同一个权限检查和同 1. 将任意长度文本按**字节**分片编码,或按需增长 Memory;禁止超过区域上限时静默截断。 2. `resource.write` 若 `{ok:false}`,返回带原因的 `Result`;若 `0 < count < requested`,继续写剩余字节;若 `count=0` 且有剩余,返回 `io.write_zero` 防止死循环。 -3. 不因 `> resource.write(...)` 语句返回值被忽略而掩盖错误;`打印` 的失败须有明确可观测结果。若要求完全兼容旧 `print` 的致命失败行为,需要规定 `Result` 到致命错误的桥接方式,不能在 `.mq.md` 中擅自吞错。 +3. 不因 `resource.write(...)` 载荷返回值被忽略而掩盖错误(旧语法写作 `> resource.write(...)`;RFC-LANG-0002 中引用块只是容器);`打印` 的失败须有明确可观测结果。若要求完全兼容旧 `print` 的致命失败行为,需要规定 `Result` 到致命错误的桥接方式,不能在 `.mq.md` 中擅自吞错。 4. 使用统一缓冲生命周期与容量预算;stdout、文件和 TCP 共享 `write_all`,只在入口处选择资源。 5. 确保多字节 Unicode、嵌入 NUL、超过一页、短写、失效资源、无权限、EOF 等均有测试。 diff --git a/docs/architecture/RFC-LANG-0002-unified-semantics.md b/docs/architecture/RFC-LANG-0002-unified-semantics.md new file mode 100644 index 0000000..4068741 --- /dev/null +++ b/docs/architecture/RFC-LANG-0002-unified-semantics.md @@ -0,0 +1,1863 @@ +# Marqdo CLI 下一代统一语义:破坏性重构、完整语法规范与全仓库迁移实施手册 + +> **仓库采纳记录(2026-11-21)**:本文件是当前**唯一**的语言语义权威规范,由 +> [ADR-0052](../adr/0052-unified-markdown-semantics.md) 采纳并取代此前所有 +> Strong/Emph/List/Quote 映射描述。`spec/mapping.md` 与 `spec/expression.ebnf` +> 已原位改写为本规范的可执行摘要。**Rust 前端与标准库尚未落地本规范**;当前 +> 状态、测试红区和迁移台账见 [`../STATUS.md`](../STATUS.md) 与 +> [`../migration/semantic-rewrite-inventory.tsv`](../migration/semantic-rewrite-inventory.tsv)。 +> 下文保留原始 RFC 的状态行(“待批准”)作为历史表述,不改变其技术内容。 + +> **文档定位**:本文件是**无需任何聊天背景即可独立实施的、单一现行语法开发规范**:先讲完整语言使用方法,再说明相较旧语法的破坏性变化,然后规定实现架构、全仓库迁移和阻断性验收。不能只阅读 RFC 标题就开始编码。 +> **状态**:待批准的目标规范与实施计划;不代表当前 CLI 已支持。**开发目标是一次性替换原有语义**,不提供 V1/V2 双编译、不按文件选择语法、不保留旧 Mapper 和运行时兼容分支。 +> **仓库**:[`cflmy/marqdo-cli`](https://github.com/cflmy/marqdo-cli),源码审查 SHA `7fbe069196e61d06a00d64fe8d65049c327373eb`。 +> **语法名称**:下文称“新语法”或“新语义”,此名称用于规范和发布说明,**不是可切换的运行模式或 Front matter 选项**。 +> **Markdown 层**:继续使用当前 Comrak/CommonMark/GFM AST;若扩展设置不变,Markdown 解析器 Profile 可保持原身份。变更的是唯一的 Markdown→Program 语义映射。 +> **规范所有权**:实施后 `spec/mapping.md`、`spec/expression.ebnf` 等现行文件**原位替换**为新规则;旧文本仅保存在 Git 历史或带显著废止说明的历史目录,不再作为第二份规范。 +> **唯一合法标题模式**:`@exec` 和 `@knowledge`。`@knowledg`、`@kongwledge`、`@Exec` 均非合法别名;在模式声明位置出现时应诊断。 +> **最终条件**:整个仓库(含 `stdlib/`、`examples/`、README、spec、测试数据、CLI 帮助文本)迁移完成,**仓库内不存在任何活跃的 V1 语义入口**后才允许合并为可发布分支。 + +--- + +# 第 0 章:这门语言是什么?先把语法讲明白 + +**Marqdo 是一门以 Markdown 为源文件的、具有独立表达式语法和运行时的编程语言。** 源文件仍是 `.mq.md`。Markdown 负责标题、段落、列表、引用、表格、公式和普通说明的文档组织;Marqdo 负责在**明确声明为执行的标题区域中**解释程序载荷。用户不需要为算法调用 Python 或 Rust,已有内存、值、函数、I/O 资源等能力仍由现有 CLI Runtime 支撑;本 RFC 只改变**怎样书写和确定性地识别程序**。 + +**旧语法与新语法的一句话对比**: + +- **旧语法**:`**...**` 是执行、`*...*` 是返回、`1.` 是条件分支、`-` 是循环、`>` 是调用;Markdown 的排版类型直接决定指令。 +- **唯一新语法**:标题中写 `@exec` 或 `@knowledge` 明确执行/知识模式;`**...**`、`*...*`、`` `...` `` 都只是**等价的程序语句载体**;**载荷里面**的 `if`、`else`、`while`、`end`、`return` 决定控制流;`1.`、`-`、`>` 仅组织显示,不再自动产生程序指令。 + +## 0.1 30 秒掌握的第一份新语法程序 + +以下是 **唯一目标语法**,在重构完成之前不能用当前 CLI 原样运行;重构完成后它就是唯一合法语法。 + +````markdown +# @knowledge 数学演示 + +这是普通文档。这一行**加粗**只会显示为加粗,不执行。 + +## @exec main + +**x = 5** +`y = x * x` +**return y** +```` + +**执行结果:** `marqdo run index.mq.md` 返回整数 `25`(按现有 CLI 的返回值展示方式输出)。 + +**你必须看懂的六件事:** + +1. **没有语义版本开关**:所有 `.mq.md` 均按同一套新规则编译,文件无须 `marqdo_semantics` 字段。旧程序必须改写,不允许默认回退旧语法。 +2. `# @knowledge 数学演示`:H1 命名空间 / 文档单元,模式 Knowledge;普通 Markdown 完全合法。 +3. `## @exec main`:H2 函数 `main`,覆盖父级模式;`@exec` 不属于可调用名称。 +4. `**x = 5**`:闭合载荷,内部是赋值语句;外部加粗只影响 Markdown 显示。 +5. `` `y = x * x` ``:也是相同的执行载荷;独立 CodeSpan 可避免 `*` 运算被 Markdown 识别为强调。 +6. `**return y**`:函数退出来自显式关键字 `return`,不再由斜体自动触发。 + +## 0.2 函数、说明、条件分支在一份文件里 + +````markdown +# @exec 计算 + +## main + +`x = 10` + +1. **if x == 10** + + > `print("正确")` + +2. *else* + + > **print("错误")** + +**end** +`return x` + +### @knowledge 关于判断条件 + +这部分可以正常写**加粗**、*斜体*、`if` 示例、列表与 GFM 表格。 + +| 条件 | 说明 | +| --- | --- | +| x == 10 | 正确 | +| 其他 | 错误 | +```` + +**执行结果:** 在允许控制台输出的环境中输出 `正确` 并返回整数 `10`(`print` 的具体换行等仍遵守现有标准库)。 + +注意:`# @exec 计算` 将执行模式传给未标记的 `## main`;`### @knowledge` 则只在自己的小节内覆盖为知识模式。**列表序号 `1.`/`2.` 和引用符 `>` 都没有指令含义**。如果把列表全部改成 `-`,或者把 `print` 移出 `>`,控制语义仍应相同(仅来源 Span 和 Markdown 结构不同)。 + +## 0.3 一个普通文档,完全无需执行 + +````markdown +# @knowledge 我的笔记 + +## 本章目标 + +1. 阅读文献 +2. 设计实验 +3. 撰写论文 + +这是**重点**;这是*提醒*;这是`x = 10`的代码例子。 + +> 这只是引用,不是函数调用。 +```` + +**结果:** 编译时保留这些 Markdown 结构,不生成可执行语句,也不会报“列表缺条件”。运行 `main` 会报告没有入口函数,因为这里并未定义函数。这不是 `[]` 空列表值,也不是一次返回 `Unit` 的函数执行,而是**没有可执行入口**。 + +## 0.4 最小语法速查表(初学者和审查者先看这里) + +| 想实现的意图 | 新写法(例) | 确定性解释 | +|---|---|---| +| 语法选择 | **没有语法选择开关** | 全部 `.mq.md` 仅按当前新语法编译 | +| 声明知识区域 | `# @knowledge 说明` | 该标题的本节及继承子节只产生文档节点 | +| 声明执行区域 | `## @exec main` | H2 定义函数,允许其中的载荷执行 | +| 继承模式 | `### 子节` | 使用最近祖先标题的模式 | +| 局部切换模式 | `### @knowledge 原理` / `### @exec 计算` | 在该标题范围覆盖祖先模式 | +| 显式参数 | `` `params(n: Int)` `` | H2 Exec 函数第一个直接载荷,只作为编译期声明 | +| 赋值 | `**x = 1**` / `` `x = 1` `` | 两者完全相同 | +| 一般计算 | `*print(x)*` / `` `print(x)` `` | 调用/求值语句;斜体不再是返回 | +| 返回 | `**return x**` / `` `return x` `` | 返回整个当前函数 | +| 条件开始 | `` `if x > 0` `` | 进入 if then 分支 | +| 否则 | `*else*` | 分割最近一个尚未结束的 if | +| 分支结束 | `**end**` | 关闭最近未结束的控制结构 | +| 循环开始 | `` `while i < n` `` | 循环条件,每轮重新求值 | +| 普通列表 | `1. 说明` / `- 说明` | **没有**自动条件/循环语义 | +| 普通引用 | `> 说明` | **没有**自动调用语义 | +| 函数调用 | `> **print(x)**` 或 `**print(x)**` | 调用来源于载荷表达式,与引用符无关 | +| 惰性代码示例 | 围栏 ` ```python ... ``` ` | 不执行;不同于行内 CodeSpan | +| 章节内强调但不执行 | 在 `@knowledge` 子节使用 `**重点**` | 正常 Markdown 强调 | + +**最危险的常见错误**:在 `@exec` 段落中写 `**重要**`,如果被提取为独立闭合载荷,解释器会把 `重要` 当成一个程序表达式。V2 **不**通过自然语言判断它是不是想强调。需要普通强调时,放在 `@knowledge` 章节或规范定义的惰性数据区域中。这里有意保持“已进入执行模式就严格解析”的确定性,而非猜测。 + +--- + +# 第 1 章:V1 实际语法、为什么要改、V2 改了什么 + +## 1.1 重构前真实规则(审查基线已实现,重构后废止) + +审查基线上的旧仓库 `spec/mapping.md` 和 `crates/marqdo-frontend/src/map.rs` 采用下面的映射(重构完成后这些规则必须废止): + +| 旧结构 | 旧含义 | 典型例子 | +|---|---|---| +| H1 `# 标题` | 命名空间 | `# 数学` | +| H2 `## 标题` | 函数 | `## 平方` | +| H3–H6 | 函数内章节 | `### 算法步骤` | +| Strong `**...**` | 语句(赋值/表达式) | `**x = 1**` | +| Emphasis `*...*` | 返回语句 | `*x*` | +| OrderedList `1.` | 互斥条件分支 | 第一段必须以 CodeSpan 条件开头 | +| BulletList `-` | 独立 while 循环 | 第一段必须以 CodeSpan 条件开头 | +| BlockQuote `>` | 函数调用 | 整个引用块必须满足调用格式 | +| 普通段落 | 普通文字;但其中 Strong/Emph 会按上述规则执行 | `这是说明。**x = 1**` | +| GFM 表格 / 数学 / 围栏代码 | 通常为惰性文档资源 | `|a|b|`、`$x$`、代码围栏 | + +**旧语法例子(当前可编译的语法形式)**: + +````markdown +## 分类 + +1. `n < 0` + + *-1* + +2. `n == 0` + + *0* + +3. `n > 0` + + *1* +```` + +这个程序靠列表决定“分支”,靠斜体决定“返回”;普通列表无法在函数内自由出现。虽然是严格确定性规则,却将普通 Markdown 的排版类型与程序指令过度绑定。 + +## 1.2 新语法的四项正式设计原则 + +**原则 A:所有级别的标题可以声明语义模式。** 从 `#` 到 `######` 都能精确使用 `@exec` 或 `@knowledge`,默认从结构祖先继承,不读取正文猜测。 + +**原则 B:闭合标记的计算意义统一。** `Strong`、`Emph`、行内 `Code` 在同一 Exec 范围内,只是同一种“单语句载荷”的不同 Markdown 显示形式,不再对应固定执行/返回角色。原始 AST 类型仍保留用于渲染和 source span。 + +**原则 C:载荷文本由明确的程序关键字决定控制操作。** `if`、`else`、`while`、`end`、`return`,以及 `params` 声明、赋值、调用与已有表达式语法;列表和引用块仅作容器。程序错误必须报错,不能回退为文档。 + +**原则 D:知识编译不在本轮开发。** 本轮保留结构、身份、跨度、文档资源,为将来可寻址知识、证明和依赖分析留接口;不开发全节点持久锚点、图谱和证明系统。 + +## 1.3 旧语法 → 新语法逐项迁移对照(开发者必须能据此改代码) + +| 语义需求 | V1 源码 | V2 源码 | 新语法实际变化 | +|---|---|---|---| +| 函数 | `## main` | `## @exec main`(或继承 H1 Exec) | 默认知识模式;Exec H2 才可调用 | +| 命名空间 | `# 算法` | `# @knowledge 算法` / `# @exec 算法` | 允许设置后代默认模式 | +| 普通加粗 | 函数体内经常触发执行 | 在 Knowledge 内正常显示 | 视觉排版不再全局等于执行 | +| 赋值 | `**x = 1**` | `**x = 1**` 或 `*x = 1*` 或 `` `x = 1` `` | 闭合载荷统一 | +| 返回 | `*x*` | `*return x*` 或 `**return x**` | 返回由关键字表意 | +| 条件分支 | `1. \`cond\`` + 子项代码 | `**if cond**` ... `**end**` | 不受列表类型限制 | +| else 分支 | V1 用互斥列表多个条件表达 | `*else*` | 显式 else,不能当作一条独立的 if | +| 循环 | `- \`cond\`` + 子项代码 | `` `while cond` `` ... `` `end` `` | 不受 bullet 绑定 | +| 调用 | `> print(x)` 或 `**print(x)**` | `> **print(x)**` 或 `**print(x)**` | 引用块本身不再执行 | +| 位置写入 | `**m[0] = 1**` | `` `m[0] = 1` `` 或 `**m[0] = 1**` | Memory 单字节写入语义不变 | +| 函数参数 | H2 后首个独立 CodeSpan `(x: Int)` | `**params(x: Int)**` 或 `` `params(x: Int)` `` | 无 CodeSpan 特权 | +| 普通列表 | 在函数内常报条件错误 | 普通知识/说明列表不会自动报错 | 空执行投影,不是 `List([])` | +| 普通引用 | 在函数内常报调用格式错误 | 普通引用不产生 IR | 只有其中合规载荷可执行 | +| Markdown 章节 | 标题不带模式 | 标题可显式声明或继承模式 | 模式不是函数名的一部分 | +| 标准库 / 内存 / 资源 | 原有语义 | 原有语义 | 不因 V2 重构改变 Runtime | + +## 1.4 V1 同一程序迁移为 新语法的完整前后示例 + +**旧语法程序(迁移前,不得用新 CLI 运行)**: + +````markdown +## 求和 + +`(n: Int)` + +**i = 0** +**sum = 0** + +- `i < n` + + **sum = sum + i** + **i = i + 1** + +*sum* +```` + +**新语法程序(完全相同的核心算法)**: + +````markdown +## @exec 求和 + +**params(n: Int)** + +`i = 0` +`sum = 0` +`while i < n` +`sum = sum + i` +`i = i + 1` +`end` +`return sum` +```` + +调用 `求和(n=5)` 应当返回 `10`。这体现了重构真正改变的地方:**循环和返回由语句本身描述,Markdown 只决定程序在文档中的承载与排列。** + +--- +# 第 2 章:新语法标题声明的完整语法 + +## 2.1 `@exec` / `@knowledge` 在哪里、怎么写 + +**只有 Markdown 解析器识别出的标题节点**(Heading,级别 H1–H6)才有资格携带模式声明。推荐写成: + +````markdown +# @knowledge 一级知识单元 +## @exec 函数名 +### @knowledge 概念解释 +### @exec 后续计算 +#### @knowledge 小节资料 +##### @exec 更细的计算段 +###### @knowledge 注释 +```` + +语法草案(标题自身由 CommonMark 解析;以下是其**首个纯 Text 子节点**的严格前缀语法,而不是第二个 Markdown 正则解析器): + +```ebnf +heading_mode_prefix = "@exec" | "@knowledge" ; +heading_decl = heading_mode_prefix, whitespace, nonempty_title ; +nonempty_title = any_nonempty_heading_content_after_mode ; +``` + +- `@exec` 与 `@knowledge` **大小写敏感、拼写完整、后面必须有空白和非空标题名**。 +- 仅当前缀位于**标题开头、直接 Text 子节点**,且作为完整词时识别。不能搜寻标题中任意子串。 +- `## @exec main` 合法;`## main @exec` **不会**启用 Exec,标题名就是 `main @exec`。 +- `## @exec` 因没有标题名而失败;`## @exec @knowledge main` 因冲突声明而失败。 +- `## @knowledg main`、`## @kongwledge main`、`## @Exec main` 按未知声明报错,提供 `@knowledge` / `@exec` 的拼写建议。不能自动恢复。 +- `## **@exec** main` 中 `@exec` 不在第一个普通文本节点上:不算模式声明,也不扫描嵌套 Strong 猜意图。 +- 原标题用于 Markdown 渲染(用户仍能看到 `@exec`),但**语义名字**必须剥离声明标记:`## @exec main` 的函数名是 `main`。 +- 前缀类似 `@other` 的首词在 V2 中为未知模式声明,给出精确诊断;需要字面以 `@` 开头的标题,可选择不把它放在标题的第一个纯 Text 词,或在未来另订转义规范。**不私自引入未经约定的转义语法。** +- 正文中的 `@exec`、`@knowledge` 只是普通文本,不会改变模式。 + +**为什么需要这些限制?** 因为单元类型是编译期决定执行边界的显式信息。拼写错误若退化成继承模式,可能使应运行的代码静默失效,或使普通知识意外执行。 + +## 2.2 标题模式的继承、覆盖和结束 + +Markdown 标题本来就具有由层级决定的范围:H3 隶属于最近的 H2;遇到下一个同级或更高级标题,当前 H3 结束。V2 不改变这一范围。 + +定义: + +```text +Mode(document root) = Knowledge +Mode(heading) = heading.explicit_mode 当含有效声明 +Mode(heading) = Mode(nearest_ancestor_heading) 没有声明且存在祖先 +Mode(heading) = Knowledge 没有声明且无祖先 +``` + +**“最近祖先”是标题层级栈计算结果,不是自然语言上下文推理。** 解析器以源文件 Markdown AST 的顶层 Heading 顺序、Heading level 确定这个栈。跳级(H1 直接到 H3)时仍按最近有效祖先继承,不凭“缺少 H2”猜测 H2。 + +完整演示: + +````markdown +# @exec 项目 + +## main + +`a = 1` + +### @knowledge 思路 + +**这一行只会被当作文档。** + +#### 实验说明 + +*不返回* + +### @exec 继续 + +`a = a + 1` +`return a` + +## @knowledge 参考资料 + +1. 正常列表 +2. 正常说明 + +## 第二个知识章节 + +`return 0` +```` + +**说明**:行内 HTML 注释只是本规范示意,为避免不同解析器对注释/标题的 AST 差异,在正式 golden fixture 中应删除这些注释。示例中最后一个 `## 第二个知识章节` **仍然继承 H1 的 Exec**,即使紧邻其前的 H2 是 Knowledge;兄弟节点不能互相传染模式。这是必须测试的边界。 + +## 2.3 标题级别与函数边界是两件不同的事 + +本 RFC **保留已有函数声明的层级约定**,不允许新标记把每个标题都变成函数: + +| 标题 | 声明/继承模式 | 语言对象 | 能否被 `marqdo call` 直接调用 | 对执行的作用 | +|---|---|---|---|---| +| H1 | Knowledge 或 Exec | Namespace/顶层单元 | 否 | 设定后代默认模式 | +| H2 | Exec | Function + Unit | **能** | 开启函数主体 | +| H2 | Knowledge | Knowledge Unit | 否 | 普通知识章节,不创建函数 | +| H3–H6 | Exec | Function 中的 Section | 否 | 若归属于 H2 Exec,可追加语句片段 | +| H3–H6 | Knowledge | Function 或知识章节下的 Section | 否 | 保留文档,不追加语句 | + +**为什么 H3 不能自动变成函数?** 目前 CLI 的 H2 绑定、模块导入、名字查找、参数推断、`run main` 约定均基于 H2。模式允许各级标题切换执行权限,并不等于打破函数层级。将两者分离有利于渐进改造。 + +**非法情况:没有 H2 Exec 函数却试图执行代码。** + +````markdown +# @knowledge 论文 +## @knowledge 第一节 +### @exec 试算 +`x = 10` +```` + +此例不能把 `x = 10` 当全局初始化,也不能偷偷创建 `试算()`。检查时报 `sem.exec_without_function`(含所属 H3 和最近 H2 的位置)。如要创建可调用的试算函数,应将父 H2 声明成 `@exec` 或新建一个 H2 Exec 函数。 + +同理:在 H1 Exec 的直接正文出现闭合载荷但没有 H2 函数时,属于**无所属函数的可执行载荷**,报错,而不是当作模块级表达式执行。 + +## 2.4 唯一语法与 Front matter 规则 + +**重构完成后不需要、也不允许按文件选择语法版本**。每一个 `.mq.md`、依赖模块、测试 fixture、官方标准库文件都使用同一套新语法。以下文件合法: + +````markdown +--- +import: + io: "std:io" +--- + +# @knowledge 项目 + +## @exec main + +`return 1` +```` + +- `import` 等既有 Front matter 项仍按原用途处理;**不得引入** `marqdo_semantics: 2`、`syntax: v1`、`--syntax v1`、`--legacy` 等入口。 +- 对旧草案中出现的 `marqdo_semantics` 字段,目标编译器应报 `sem.unsupported_version_directive`,提示移除;不能把它当语义分支、也不能忽略未知键后造成错误自信。该字段不能用于“看似成功”的兼容运行。 +- 目标语言的默认根模式是 **Knowledge**;H1–H6 的 `@exec`、`@knowledge` 采用严格 AST 前缀声明与祖先继承,**不使用正文内容做判别**。 +- 无声明的旧式 `## main` 在默认 Knowledge 下不是函数;这类项目应在重构阶段批量改写为 `## @exec main` 或通过 `# @exec` 继承。 +- `marqdo.md.v1` 代表当前固定的底层 Markdown 解析 Profile 时,可原样保留解析器名称;**不能继续把旧 `spec/mapping.md` 当作活跃语义规范**。新的语义不以运行时可切换的版本号呈现。 +- 已安装第三方依赖如果只提供旧语法,应在加载/检查阶段明确失败,要求升级包;不能悄悄编译成旧指令。锁文件和 digest 仍应可重复、可审计。 + +**强制要求**:最终代码中不得存在 `map_v1`、按语义版本分派的 `match`、专用 V1 语法迁就逻辑或混合版本模块测试。历史行为仅可保留为“不再合法”的负面测试与 Git 历史。 + +--- + +# 第 3 章:统一闭合载荷——什么会执行、怎样写、怎样报错 + +## 3.1 “闭合标记统一”在 新语法的精确定义 + +以下在 **相同函数、相同 Exec 模式、相同 payload 文本**条件下编译为相同 IR: + +````markdown +**x = 10** +*x = 10* +`x = 10` +```` + +以下亦等价: + +````markdown +**return x** +*return x* +`return x` +```` + +三行是**三种互相替换的写法**,不是要求同一函数连续执行三次! + +统一的是**计算语义**,不是 Markdown 的渲染方式:加粗仍显示为加粗,斜体仍显示为斜体,行内代码仍显示为行内代码。源码、source span、AST kind、阅读风格都被保存。 + +| Comrak AST kind | 是否为 V2 MVP 载荷 | 提取规则 | 附注 | +|---|---|---|---| +| `Strong` | 是 | 合并其**直接** Text/Code 载荷子节点 | 不保留“专用执行”角色 | +| `Emph` | 是 | 同 Strong | 不保留“专用返回”角色 | +| `Code`(**行内**) | 是 | 直接使用其 literal | 必须在合法提取上下文 | +| `CodeBlock`(围栏或缩进) | 否 | 作为惰性 Code 资源 | **不要**因此把所有代码围栏直接执行 | +| `Strikethrough` | 否(本期) | 惰性文档 | 将来扩展需独立 ADR | +| `Link/Image` | 否 | 链接/图片值 | 链接关系、`[]()` 保持原语义 | +| `Table/Math/HTML` | 否 | 惰性文档数据 | GFM 表格单元格不直接执行 | + +**关于 `****...****` 等标记**:不能直接数 Markdown 字符决定语义。CommonMark 可能把多个星号解析为嵌套 Strong/Emph,甚至不存在一个完整的闭合 AST 节点。V2 只承认**真实生成的合法载荷 AST 节点**;如果存在受许可的嵌套载体,可按下述单次提取处理;无法满足提取规则的形态报错。严禁用正则重新扫描原始星号串并把它当新语法。 + +## 3.2 精确的载荷提取规则 + +在 `@exec` 中,Frontend 使用以下规则;不应由 Runtime 再判断: + +1. 只从可执行范围下、允许遍历的 Markdown 容器提取**外层**合法载荷节点。 +2. 对独立行内 CodeSpan:取 `literal`,产生**一条**程序语句的候选载荷。 +3. 对 Strong/Emph:仅允许直接 Text 与 Code 子节点,按原始顺序连接为一个字符串;其内部 Code **被外层消费,不得二次执行**。 +4. 如果 Strong/Emph 内包含另一个 Strong/Emph、Link、Image、Math 或其它未获许可的复杂嵌套:在 Exec 位置硬错误 `sem.payload_nested`;不能跳过错误节点,也不能递归到子节点执行半条语句。 +5. 同一个载荷只允许**一条语句**。例如 `` `x = 1; return x` `` 报错误;正确做法是拆成两个独立闭合节点。 +6. 载荷可以包含空格与合法表达式文本,仍必须被完整消耗至 EOF。不能忽略尾部错误字符。 +7. 每个载荷必须拥有 source span;嵌套 Strong(Code) 时记录源文本片段到 payload 的片段映射,以支持精确错误定位。 +8. 单独出现的 CodeSpan 与被 Strong/Emph 包裹的 CodeSpan,在规范上的计算效果一致;嵌套情况只执行一次。 + +**推荐写法(避免 `*` 被 CommonMark 当作强调标记):** + +````markdown +**`y = x * x`** +```` + +或更短地写: + +````markdown +`y = x * x` +```` + +这两者均产生一条赋值语句。**不要**把复杂的 `**return x * x**` 当作无需 golden 验证的示例:Markdown 强调与乘法符号会相互干扰。 + +## 3.3 哪些 Markdown 区域绝对不递归执行? + +| 区域 | 行为 | 为什么 | +|---|---|---| +| `@knowledge` 下全部正文 | 零执行语句 | 明确的知识/文档模式 | +| 标题文本、标题中的模式声明 | 不执行 | 标题只声明边界、身份与模式 | +| `[]()` 的链接标签和 URL | 不执行 | 避免“知识链接 = 函数调用”混淆 | +| 图片说明 | 不执行 | 文档数据 | +| GFM Table 单元格 | 不执行 | 表格仍是数据 | +| 公式 / MathBlock | 不执行 | 公式是知识资源;显式调用才能求值 | +| HTML | 不执行 | 避免绕过 AST 规则 | +| 围栏代码 / 缩进代码块 | 不执行 | 代码资源仍惰性;保留 Markdown 自然展示 | +| Front matter | 不执行 | 模块配置与元数据 | +| 删除线 / 不允许的扩展 Markdown 节点 | 不执行 | 未定义为执行载荷 | + +**这里没有“语法解析成功才执行”一说。** 执行边界由单元模式和语法载荷类型决定;只要在合法执行位置中提取出载荷,就必须完整编译,错误不能回退为普通文字。 + +## 3.4 普通段落、列表、引用块中的载荷怎么处理? + +以下五种形式都仅提取 `print(x)` 作为调用表达式(不改变 `print` 的功能): + +````markdown +## @exec main + +**print(1)** + +*print(1)* + +`print(1)` + +> **print(1)** + +- `print(1)` +```` + +这段是**同一函数顺序调用五次**的示例,用于展示不同承载形式可以共存。替换任一承载形式时,该次操作的语义保持一致。`>` 不再“执行调用”,`-` 不再“执行循环”,由括号内的 `print(1)` 形成调用表达式。 + +**普通引用合法**: + +````markdown +## @exec main + +> 这是对算法的解释,不是调用。 + +`return 1` +```` + +**普通列表合法**: + +````markdown +## @exec main + +1. 第一步:准备数据。 +2. 第二步:校验结果。 + +`return 1` +```` + +这些文档节点没有可执行载荷,因此产生零条相应指令,不因为缺少条件而报错。**空的执行投影**不同于创建一个 `[]` 值。 + +**普通 Markdown 排版的真实限制**: + +````markdown +## @exec main + +这里的 **关键思想** 是保持不变量。 +```` + +由于 `Strong` 是统一载荷载体,`关键思想` 会被当作程序表达式。若没有该变量,产生明确的符号错误;即使恰有同名变量,也会求值(不得靠“看起来是中文”跳过)。**这是本次确定性设计主动接受的代价,而不是遗漏的优化项。** 要无歧义地表达普通强调,应使用 `@knowledge` 子章节或不会被递归执行的惰性 Markdown 区域。 + +--- + +# 第 4 章:新语法程序语句、关键字和完整控制流教程 + +## 4.1 关键字一览:最少词汇,足够明确的控制意图 + +| 关键字 | 语法 | 含义 | 是否新增计算原语 | +|---|---|---|---| +| `if` | `if ` | 开始条件分支 | 否,映射已有 `Branch` | +| `else` | `else` | 切换至当前 if 的否则分支 | 否 | +| `while` | `while ` | 开始循环 | 否,映射已有 `Loop` | +| `end` | `end` | 结束最近未关闭的 if/while | 否,仅用于编译期配对 | +| `return` | `return ` | 返回当前 H2 函数,终止后续执行 | 否,映射已有 `Return` | +| `params` | `params(name: Type, ...)` | H2 Exec 函数的可选参数声明 | 否,编译期元数据 | + +现有 `true`、`false`、`None`、`and`、`or`、`not` 等仍具有原表达式含义。`print`、`input`、`open`、`memory`、`table` **不是**控制关键字,属于已有内置函数或标准库 API;本 RFC 不负责发明新的 I/O 函数。 + +**语法统一意味着**:关键字必须位于载荷文本中,而不是写在 Markdown 标记外面再让编译器猜测。 + +- ✅ `` `if x > 0` `` +- ✅ `**if x > 0**` +- ✅ `*return x*` +- ❌ `1. if x > 0`(只是普通文本,不是执行载荷) +- ❌ `> print(x)`(只是普通引用正文,不是调用语句) +- ❌ `if x > 0`(在普通段落中,不在闭合载荷内,只是普通文字) + +## 4.2 赋值与表达式:沿用当前语言既有计算语法 + +````markdown +## @exec main + +`a = 10` +**b = 20** +*sum = a + b* +`return sum` +```` + +返回 `30`。斜体 `*sum = a + b*` **不是返回**,只是第三条赋值操作。 + +表达式仍保持现有整数、浮点、字符串、布尔、列表、Map 记录、运算、索引与函数调用规则。当前 V1 已有 `m[0] = 1` 的 Memory 索引写入能力,V2 仅允许统一载体承载它,不因此允许对任意 List/Map 成员执行原地修改。`a.field = 1` 等当前不支持的赋值形式仍不合法。 + +函数调用是表达式,既可以丢弃结果: + +````markdown +`print("你好")` +```` + +也可以接收结果: + +````markdown +`x = 求和(n=5)` +```` + +不需要引用块 `>` 才能调用。 + +## 4.3 `return`:告别斜体专用返回 + +````markdown +## @exec double + +`params(x: Int)` + +**`return x * 2`** +```` + +- `return` 从**当前 H2 函数**返回,不只是结束某个列表项或局部 H3 章节。 +- `return x` 必须带表达式;`return` 空语句在首版报错,不自动代表 `None`/`Unit`。 +- 自然执行到函数末尾仍返回现有 `Unit`,与显式 `None` 不同。 +- `*x*` 在 V2 Exec 区域代表求值表达式 `x` 并丢弃结果,**不再 return**。 +- 若 `` `return x` `` 出现在 Knowledge 模式,保留为文档,不执行也不报变量未知。 + +## 4.4 `if` / `else` / `end`:可读、互斥、能嵌套 + +**最简单的分支:** + +````markdown +## @exec main + +`x = 3` +`if x > 0` +`print("positive")` +`else` +`print("non-positive")` +`end` +`return x` +```` + +规范语义:条件计算一次,必须是 Bool;为真执行 `if` 和 `else` 之间的载荷,否则执行 `else` 和 `end` 之间的载荷。**不能两个分支都执行。** `else` 可以省略;但 `end` 不能省略。 + +**将它排成有序列表也完全合法**: + +````markdown +## @exec main + +`x = 3` + +1. **if x > 0** + + > `print("positive")` + +2. *else* + + - **print("non-positive")** + +**end** +`return x` +```` + +两段程序的控制流应相同;区别仅在文档的排版。`1.`、`2.` 与嵌套 `>`、`-` 不是运行时条件或循环指令。 + +**嵌套分支:** + +````markdown +## @exec main + +`x = 12` +`if x > 0` + `if x > 10` + `print("large")` + `else` + `print("small")` + `end` +`else` + `print("non-positive")` +`end` +`return x` +```` + +这里代码行的前导空格只是为了帮助阅读,**不能保证在 CommonMark 中形成相同的 AST**(连续 4 个空格可能变成缩进代码块而惰性)。正式可运行测试应使用规范的 Markdown 列表结构或顶格独立段落,如下: + +````markdown +## @exec main + +`x = 12` + +`if x > 0` + +`if x > 10` + +`print("large")` + +`else` + +`print("small")` + +`end` + +`else` + +`print("non-positive")` + +`end` + +`return x` +```` + +匹配规则:每个 `else` 只作用于**栈顶尚未结束的 `if`**;每个 `end` 关闭最近的 `if` 或 `while`。这是一套确定的编译期配对规则,不靠缩进/列表种类/解释器猜测。 + +**不支持 `else if` 专用写法(本期)**:若需要多路判断,可在 `else` 内另写一个嵌套 `if ... end`,按上述栈规则执行。若未来证明有显著可读性需求,再独立讨论 `elif`,不能开发者自行在 Parser 中宽容接受。 + +## 4.5 `while` / `end`:不依赖 bullet List 的循环 + +````markdown +## @exec count + +`params(n: Int)` +`i = 0` +`while i < n` +`i = i + 1` +`end` +`return i` +```` + +运行 `count(n=5)` 返回 `5`。 + +**循环语义:** 每一轮先求 Bool 条件;为 true 时执行循环体;为 false 时退出循环。与 V1 的 `Stmt::Loop` 语义一致。`end` 只在语法层关闭控制块,不额外执行任何操作。 + +**在引用块/有序列表/无序列表中书写也等价**,例如: + +````markdown +## @exec count + +`params(n: Int)` +`i = 0` + +- `while i < n` + + > **i = i + 1** + +`end` +`return i` +```` + +`-` 仅用于使循环体视觉上呈现为子项内容;它并不决定循环语义。即使将 `-` 改成 `1.`,程序应仍然按 `while` 执行。 + +## 4.6 `end`:为什么增加它,怎样严格约束 + +`end` 是当前候选规范最重要的新增**控制界定关键字**。它并不是一种新的计算能力;它只给 `if` / `while` 的作用域设置一个明确终点。 + +理由:如果让列表层级或 Markdown 引用块决定控制流终点,程序改成另一种排版时就可能改变执行意义。**要真正实现 `1.`、`-`、`>` 的“只是约定、不强制控制类型”,必须将控制范围从容器类型中解耦。** 显式 `end` 是一种小而可证明的解决方案。 + +严格规则: + +- 每一个 `if` 恰有一个匹配的 `end`;`else` 可选且最多一个。 +- 每一个 `while` 恰有一个匹配的 `end`。 +- `else` 不能独立出现;不能对应 `while`;一个 `if` 不能有两个 `else`。 +- `end` 不能独立出现;语义片段末尾若仍有未闭合控制块则报错。 +- 不允许控制块跨越**标题边界**(见第 6 章),也不能跨 H2 函数、不同 `@exec` 章节或知识区域。 +- `if x > 0:` 带尾冒号首版不合法;规范语句不使用冒号,因为 Markdown 控制不由缩进决定。 + +## 4.7 `params(...)`:统一的函数参数声明 + +V1 曾将 H2 后“首个独立 CodeSpan `(n: Int)`”解释为函数签名,这是一个与载荷统一原则冲突的特殊规则。 + +V2 推荐显式声明: + +````markdown +## @exec 加法 + +**params(a: Int, b: Int)** + +`return a + b` +```` + +`params` 只在 H2 Exec 函数**第一条直接执行载荷**处合法,且每个函数最多一次;前面可以有普通说明文字,但不能已有赋值/调用/return,也不能把 `params` 藏在 List/BlockQuote 中。`params` 是编译期签名声明,不是运行时函数。对其外层用 `**`、`*`、CodeSpan,签名语义一致。 + +无 `params` 时,第一版可沿用已有的自由变量参数推断,但对公共 API 给出可配置的 lint,鼓励显式参数。类型表达与默认参数规则复用既有签名规范;不能从此处擅自承诺泛型、高阶函数或新类型系统。 + +## 4.8 当前不支持的写法:不要让实现者自行发明 + +| 写法 | 首版处理 | 正确替代 | +|---|---|---| +| `if x > 0:` | 语法错误 | `if x > 0` | +| `else x > 0` | 语法错误 | 嵌套 `if` | +| `elif x > 0` | 未定义关键字,语法错误或未知符号 | 嵌套 `if` | +| `return`(无表达式) | 语法错误 | `return None`(如果确实要返回 None) | +| `end if` | 语法错误 | `end` | +| `for x in xs` | 未纳入首版语法 | 标准库算法或 `while` | +| `break`、`continue`、`try` | 未纳入首版语法 | 首版不承诺 | +| `a.b = 1` | 保留现有赋值能力限制 | 使用相应数据操作 API | +| `x = 1; return x` 单个载荷 | 语法错误 | 两个独立闭合载荷 | +| 直接写 `> print(x)` | 文档引用,不执行 | `> **print(x)**` | +| 直接写 `1. if x > 0` | 文档列表,不执行 | `1. **if x > 0**` | +| 让 `*x*` 返回 | V2 不返回 | `*return x*` | + +--- +# 第 5 章:精确的语法文法与确定性解释规则(实现者必须阅读) + +## 5.1 两层语法、单一解析流水线(绝非双语义编译器) + +编译输入依次经过: + +1. **官方 Comrak/CommonMark/GFM Parser**:只做一次 Markdown 解析,得到 AST 与 UTF-8 source spans。 +2. **标题模式解析器**:只使用 AST 的 Heading level 和标题首个普通 Text 子节点的精确词法位置,得到 H1–H6 模式信息。 +3. **统一载荷映射器**:只在 `@exec` 且有所属 H2 Exec 函数的范围内,按 AST 顺序采集 Strong/Emph/CodeSpan。 +4. **载荷语句解析器**:仅对已经明确选中的载荷文本,按正式 Marqdo 语句文法解释 `if/else/while/end/return` 等。 +5. **控制结构组块器**:通过显式控制栈,将语句 token 降低到已有 IR。 + +严禁“先尝试当程序解析,失败就当普通文档”;严禁用普通中文说明、关键字出现频率、列表的首行是否看起来像条件,决定是否执行。 + +## 5.2 建议冻结的 V2 载荷文法 + +以下 EBNF 是**替换旧 Statement 规则的唯一新语句层**,其中 `expr`、`assignment` 和 `parameter_list` 应复用现有表达式/签名 Parser,不复制一套 Python 解析器。 + +```ebnf +(* 每一个独立 Markdown 载荷对应且只对应一条 statement。 *) +carrier_statement = "if", required_space, expr, EOF + | "else", EOF + | "while", required_space, expr, EOF + | "end", EOF + | "return", required_space, expr, EOF + | "params", "(", parameter_list, ")", EOF + | assignment, EOF + | expr, EOF ; + +(* assignment: 复用既有 assign_target '=' expr; + 函数调用仍属于 expr(作为单独载荷执行时结果丢弃)。 *) +``` + +**词法必须考虑完整单词边界**:`ifdef()`、`returning()` 不是 `if`、`return` 控制语句;反之,单独的 `if`、`else` 等当作标识符使用应明确报保留字错误。为了避免自相矛盾,Tokeniser 和 Parser 均应对关键字使用同一套保留字定义。 + +- `if`、`while` 后必须为可完整消费的表达式;表达式运行结果必须 Bool。现有条件纯度限制仍适用。 +- `else`、`end` 后不允许额外词元,`end if`、`else x` 均硬错误。 +- `return` 后必须是表达式;其作用范围是当前 H2 函数,不是当前段落/列表项。 +- `params` 仅允许声明位置;作为普通表达式调用不得偷偷生效。 +- 首版**没有**冒号、缩进结束、自动括号、换行分号语法糖。 +- 空载荷 `****`、空 CodeSpan 等不得被忽略;对识别出的 Exec 载荷应报 `sem.empty_payload`。 + +## 5.3 从载荷序列组建结构化 IR 的严格规则 + +对每个 H2 Exec 函数,按各个**执行片段**的源码顺序处理。一个执行片段是标题自己的直接正文,不含下一标题的内容(H3–H6 是独立片段)。在单个片段里,先得到: + +```text +TokenStream = [StatementToken(payload, span, carrier_kind, owner_unit), ...] +``` + +随后使用控制栈: + +```text +open_if(condition): + push IfFrame(cond, then=[], else=None) + +on_statement(stmt): + append stmt to the current innermost active body + +on_else: + require stack.top == IfFrame and frame.else is None + switch frame active branch from then to else + +open_while(condition): + push WhileFrame(cond, body=[]) + +on_end: + require stack not empty + pop one frame + lower it to Branch or Loop + append lowered statement to enclosing frame/body + +at_segment_end: + require stack empty + append the segment's complete IR statements to current H2 Function.body +``` + +该算法可以保证: + +- `else` 配对最近尚未结束、且位于栈顶的 `if`;不得跳过未关闭的 `while` 寻找更外层 `if`。 +- `end` 只关闭栈顶最近的一层 if/while,没有匹配结构时报错。 +- `return` 属于正在打开的 body,但运行时终止整个 H2 函数;降为现有 `Stmt::Return` IR。 +- `else` 不会成为单独一条 Runtime 指令;它只是 IR `Branch` 的分支边界。 +- 相同载荷序列应产生相同的**归一化可执行 IR**,不因列表编号、引用层数、加粗/斜体/行内代码形态改变运算类别。 + +**一个实现注意点**:现有 `Branch` IR 的每个 arm 带 `condition`,没有专用可选 else;首版可以将兜底 else 降为最后一个 `true` arm,并明确保持既有“从左到右找第一匹配”的短路求值。如果未来 IR 引入更明确的 `else_body`,必须同步更改 IR schema、Trace 规范和**全部下游消费者及测试**;不能在本轮暗改行为。 + +## 5.4 容器的遍历:保留文档结构、但不赋予控制语义 + +推荐定义一个纯粹、可复用的 AST 遍历算子(伪代码): + +```text +Extract(node, mode): + if mode == Knowledge: return [] + if node is inert subtree: return [] + if node is an allowed outer carrier: return [extract_one_payload(node)] + if node is Paragraph, List, Item, BlockQuote: + return concat(Extract(child, Exec) for child in source order) + return [] +``` + +遍历顺序必须是 **AST 文档序、子节点顺序**。禁止通过文件扫描另建“代码行”列表来重排执行顺序。 + +| Markdown 容器 | V2 编译器对它做什么 | 它**不**做什么 | +|---|---|---| +| 普通 Paragraph | 递归提取其中的允许载荷 | 不因为普通文字执行 | +| OrderedList | 按 ListItem 顺序提取载荷 | 不自动创建 Branch | +| BulletList | 按 ListItem 顺序提取载荷 | 不自动创建 Loop | +| BlockQuote | 按嵌套 Block 顺序提取载荷 | 不自动创建 Call | +| Heading | 切换/继承模式与片段 | 不作为语句、也不吞掉其后的 H2/H3 | +| Link | 保留引用关系 | 不从链接文字提取内部执行 | +| Table | 保留 GFM 结构 | 不把单元格代码片段当语句 | + +**两个不可违反的原则**: + +1. **单次拥有**:`Strong(Code("x=1"))` 仅提取外层 Strong 这一条;不能既执行 Strong 又执行 Code。 +2. **不变量不丢**:同一载荷的 source span、原始 Markdown 节点类型与所属标题必须随 IR 生成后保留在可观察的分析数据中。 + +## 5.5 章节边界与控制流:禁止跨标题配对 + +如果一个 if 在某个 `### @exec` 小节打开,它的 `end` 必须写在**同一标题直接正文片段**中;不能跨到下一个 H3、H4,也不能跨到 Knowledge 子标题去关闭。 + +````markdown +## @exec main + +`if x > 0` + +### @knowledge 说明 + +这里是普通知识文本。 + +### @exec 续写 + +`end` +```` + +**预期:** 在 H2 直接正文片段末尾报 `sem.unclosed_control`;`### @exec 续写` 的 `end` 又是 `sem.unmatched_end`。即使字符串与两个节点都存在,编译器也必须拒绝“跨标题互相修复”。 + +为什么这样规定?标题是 Marqdo 已有的可寻址单元边界。如果 if 的有效代码跨过一个知识单元,那么在 Markdown 文档中插入或移动小节就可能无意改变控制流,严重损害局部分析和日后知识编译。**显式 `end` 不应跨单元隐式续接。** + +同一 H2 函数的多个完整 Exec 片段,仍会按源码顺序进入它的函数体。例如: + +````markdown +## @exec main + +`a = 1` + +### @knowledge 解释 + +这段不执行。 + +### @exec 第二阶段 + +`a = a + 1` +`return a` +```` + +此函数返回 `2`。知识片段没有执行效果,但也不会因为知识内容出现 `return` 一词而中断执行。 + +**解析片段分割的建议实现**:用顶层 Heading 序列记录每个 Heading 的 `direct_body` 范围(从该 Heading 到下一 Heading,不包括后代 Heading 本身),再根据 Heading 栈合成 H2 函数的执行片段列表;不应误把整个 H2 的 body 当成单一片段以致忽略 H3 的模式覆盖。 + +## 5.6 程序的显式声明与静态作用域 + +- H2 Exec 定义函数名、参数、返回路径;H1 可保留 Namespace。 +- H3–H6 只是 Section,不改变函数名,不创建新的调用帧,不自动清空局部变量。`### @exec` 前后同一 H2 函数的本地变量可连续使用。 +- 参数声明仅在 H2 的第一条直接执行载荷中合法;后续章节不得重新声明 `params`。 +- `@knowledge` 中的标识符/CodeSpan 不参与 V2 参数推断,不增加符号使用,不触发运行时副作用。 +- 已有导入 `import:`、包作用域、函数查找、显式/推断参数规则原则上保持;出现 V2 特例必须在规范中明确记载。 +- 普通程序不应仅因源码从 Strong 换成 CodeSpan 就发生新的名称绑定、类型系统或函数调用语义。 + +## 5.7 可证明的确定性与其精确边界 + +令 `P` 为固定的 Markdown 解析器,`M` 为重构后**唯一的语义映射器**,`R` 为静态分析和 IR 构建,则: + +```text +P(source, fixed_profile) = AST +M(AST, explicit_mode_rules) = IR or Diagnostics +R(IR, imports) = ExecutableProgram or Diagnostics +``` + +在 `source`、解析 Profile、导入图与唯一现行语法契约不变时,结果必须确定。 + +**不能承诺的事情**:仅凭 AST 可以知道作者有没有“想用加粗强调”。相同 Markdown AST 中的 Strong 在相同 Exec 位置只有一个既定含义——程序载荷。因此本规范保证确定性而不假装可以猜测人类意图。这个取舍必须在 README 的新语言语法介绍中直接告知开发者。 + +--- + +# 第 6 章:错误语义、真实边界和新手最容易踩的坑 + +## 6.1 三种完全不同的“空” + +| 情况 | 意义 | 是否生成可执行语句 | +|---|---|---| +| `@knowledge` 中普通 Markdown 列表 | 文档节点 | 0 条 | +| `@exec` 中普通 Markdown 列表(没有可执行载荷) | 文档节点 | 0 条 | +| 运行函数结束但没有显式 `return` | 现有 `Unit` 结果 | 已执行已出现的语句,随后返回 Unit | + +不要将上面任何一种误写成运行时的空 `List([])`;也不要因为该文件没有 `main` 就生成一个虚构的空函数。没有入口时 `run` 应报告无入口诊断。 + +## 6.2 常见错误与规范性诊断 + +| 错误文件片段(放在 Exec 中) | 必须如何处理 | 推荐诊断代码 | +|---|---|---| +| `## @knowledg main` | 未知模式声明,不能继承隐藏错误 | `sem.invalid_mode_marker` | +| `## @exec` | 缺少标题名称 | `sem.empty_unit_name` | +| `**if x >**` | 语法错误,不降级文档 | `sem.syntax` | +| `**else**`(无 if) | 无匹配分支 | `sem.unmatched_else` | +| `**else**`(重复 else) | 重复,否则分支只允许一个 | `sem.duplicate_else` | +| `**end**`(无 if/while) | 不能独立结束 | `sem.unmatched_end` | +| `**if true**` 到片段结束无 end | 未闭合控制 | `sem.unclosed_control` | +| `**while 123**` | 类型非 Bool(按类型能力在静态或运行时报错) | `runtime.type` 等现有类型错误 | +| `**return**` | 需要表达式 | `sem.syntax` | +| `**return x; print(x)**` | 一载荷多语句 | `sem.syntax` | +| `**params(n: Int)**` 出现在函数中部 | 非法参数声明位置 | `sem.signature_position` | +| `### @exec 子节` 处于 Knowledge H2 之下且有 Exec 载荷 | 无合法函数归属 | `sem.exec_without_function` | +| `**重点**`(位于 Exec,未定义) | 这确实是载荷;应报未知变量 | `symbol.unknown` | +| `> print(1)`(没有闭合载荷) | 只是引用,不应报调用格式错误,也不执行 | 无错误 | +| `1. 普通事项` | 普通列表,不应报条件格式错误,也不执行 | 无错误 | +| `**`非法嵌套 Markdown`**` | 不允许在可执行载荷里非法嵌套 | `sem.payload_nested` | + +代码命名是 **V2 诊断 API 的提案**;实施时可以以已有规范的 `markdown.*`、`expr.*` 命名策略形成正式名称,但必须保证 `code` 稳定、可用作自动化判断,`message` 只供人阅读。 + +## 6.3 错误不退化为知识,知识不自动提升为执行 + +以下两种程序必须始终保持不同语义: + +````markdown +## @knowledge 说明 + +**return x +** +```` + +这只是文档,允许存在,因为它没有声称是程序语句。 + +````markdown +## @exec main + +**return x +** +```` + +这是**显式执行区域中的非法载荷**,必须报告语法错误。绝不能试图“作者大概在写文档”而跳过。 + +另一个危险错误是:把标题里的 `@knowledg` 当作未知普通文字,从 H1 `@exec` 继续继承执行。这会使原本希望安全展示的代码被执行。该拼写应硬错误,避免安全意图降级。 + +## 6.4 新人写程序的推荐约定(风格,不是强制语义) + +建议在官方例子中采用下列可读性约定: + +- 使用 `# @knowledge` 为文档项目开头;在需要计算的 H2 明确写 `## @exec 函数名`,无需猜测继承。 +- 对涉及 `*`、`**`、`<`、`>`、字符串的复杂表达式,优先选用独立 CodeSpan 或 Strong 包裹 CodeSpan(防止 Markdown 格式与运算符冲突)。 +- 推荐独立一行一个程序载荷;`if/else/end` 各占一条载荷;虽然允许在普通段落中嵌套多个载荷,但会影响可读性与诊断。 +- `1.` / `-` / `>` 用于呈现文档结构;不对它们赋予“必然分支/循环/调用”的心理预期。 +- 把普通强调、算法解释、大段说明放在 `@knowledge` 章节,减少 Exec 区强调查错。 +- 公共函数建议写 `params(...)`,复杂程序优先使用完整显式签名;若继续允许参数推断,必须按**新语法自己的规范**保留它,而不是因为 V1 兼容而保留旧签名特例。 +- 不要写无条件的“语法糖容错”:看到 `if ...:`、错拼模式、未匹配 `end` 必须诊断,而非悄悄修复。 + +--- +# 第 7 章:编译架构设计——具体修改到哪些 crate、哪些文件 + +## 7.1 技术边界:一次性替换语义映射,保留计算内核 + +本项目不是重新实现运行时:已有的数值计算、Memory、Resource、Capability、Plugin ABI 与托管值语义尽量原样保留。但**整个仓库所有 `.mq.md` 源码与其测试都必须同步换语法**,这一点不是可选的“后续迁移”。 + +```text + .mq.md(唯一新语法) + │ + Comrak/GFM(单解析器) + │ + 原生 Markdown AST + │ + Heading/Unit + @exec/@knowledge + 确定性模式继承与覆盖 + │ + 执行片段的统一闭合载荷提取 + │ + 一套 Statement Parser(关键字) + │ + 显式 if/else/while/end 组块 + │ + 现有 marqdo-ir + │ + 现有静态检查器 / Runtime / Host + │ + 同仓库已迁移 stdlib/ +``` + +**五条不可突破的边界**: + +1. 只有**一套** Markdown AST、一套语义 mapper、一套语句 parser、一套 Runtime;不得创建 `map_v1.rs`、`map_v2.rs` 共存或 per-file 版本判别器。 +2. **原位替换** `spec/mapping.md` 与 `spec/expression.ebnf` 的规范性内容;旧规范的历史价值由 Git 提供,而不是在 `spec/` 中继续作为“活跃可选版本”。 +3. 控制关键字是语言表面语法,不是新 HostOp;映射至现有 Branch、Loop、Return/Assign/Eval IR,必要的 IR 字段变更须最小化。 +4. `@exec` 不扩大资源访问权限;Resource/Host 授权和安全隔离不因这次语法重构改变。 +5. 同仓库 `stdlib/` **随语法变更一起迁移并重新打包与校验摘要**,不得留下“新语法主程序 + 旧语法标准库”的过渡状态。 + +**集成纪律**:允许在开发分支上出现中途不通过的 commits,但不可将语义残缺的状态合并到主分支、打包、发版。最终合并门槛是一条从源文件到正式 CLI 的全仓库通过链路。 + +## 7.2 现有代码事实与破坏性重构修改清单 + +以审查 SHA `7fbe069...` 为基准。**不增加新的 crate;按职责小范围增改已有文件即可。** + +| 文件/目录 | 当前职责 | 新语法落地动作 | 禁止留下的旧架构 | +|---|---|---|---| +| `crates/marqdo-markdown/src/ast.rs` | AST kinds 与字节 spans | 保持 CommonMark/GFM 结构和真实 span;增加 AST 探针测试 | 不加入第二个 Markdown lexer | +| `crates/marqdo-frontend/src/units.rs` | H1→namespace、H2→function、H3+→section | 精确剥离标题模式前缀、H1–H6 祖先继承;**只有 Exec H2 创建 callable** | 按旧 H2 无条件造函数 | +| `crates/marqdo-frontend/src/map.rs` | 按 Strong/Emph/Ordered/Bullet/Quote 解释指令 | **直接重写为唯一 mapper**:段落、列表、引用作为容器;载荷文本决定语句 | `map_v1.rs`、`map_v2.rs` 并存 | +| `crates/marqdo-frontend/src/payload.rs` | 文本/Code 源映射 | 统一 Strong/Emph/CodeSpan、单次提取、精确文件 span | 把 Emph 专门视为 Return | +| `crates/marqdo-frontend/src/signature.rs` | H2 首个纯 CodeSpan `(...)` 的特殊签名 | 移除旧特例,实现首个直接执行载荷 `params(...)` | 两套签名声明共存 | +| `crates/marqdo-frontend/src/analyze.rs` | 函数/导入/IR 装配 | 单路径连接模式索引、载荷与控制栈 | per-module 版本分派 | +| `crates/marqdo-expression/src/{lexer,parser,ast}.rs` | 独立计算表达式与基础赋值 | 同一词法语法加 `if/else/while/end/return/params`;不重写表达式计算 | `parse_statement_v1` 后备分支 | +| `crates/marqdo-ir/src/lib.rs` | Function/Stmt/Branch/Loop 等 IR | 尽量复用;必要时提升语义元数据和 source map | 并行的 `LegacyStmt` IR | +| `crates/cli/src/{loader,commands,main}.rs` | 装配、run/call/check/fmt/inspect | 移除语义版本选择;入口、诊断、帮助与样例仅按新规则 | `--legacy`、旧模块按 v1 加载 | +| `stdlib/**/*.mq.md` | 正式标准库源码 | **全数迁移**,API 名/值语义可保持;更新 digest、bundled 路径和 fixture | 包中存在旧的斜体返回等语法 | +| `spec/` | 权威规范 | 将 `mapping.md` / `expression.ebnf` 等**原位变更**为当前唯一规范,校对其他相关 spec | 活跃的 mapping-v1 与 mapping-v2 两份规范 | +| `examples/` | 公开可运行样例 | 全部源文件逐个重写和自动跑通 | README 仍展示旧式列表控制 | +| `tests/`、`crates/*/tests/` | conformance、negative、integration、security | 旧语义测试替换为新行为;Markdown AST profile 测试可留原始 Markdown 输入 | 旧语法“仍应通过”的断言 | +| `README.md`、`docs/`、`COMPATIBILITY.md`、`CHANGELOG.md` | 面向用户的介绍/说明/历史 | 现行文本全部更新;历史 ADR 归档/标记废止 | 活跃入口链接到旧语法教程 | +| `tools/`、CI 配置 | 打包/性能/检查 | 迁移扫描、示例执行检查、stdlib digest 校验与多平台门禁 | CI 仍将旧语法成功视为正确 | + +**建议目标结构:保留现有 crate 组织,不因本轮工作新增版本目录。** + +```text +marqdo-cli/ +├── crates/ +│ ├── marqdo-markdown/src/ # 仅 Markdown AST/Profile +│ ├── marqdo-expression/src/ # 唯一词法/语句/表达式解析 +│ ├── marqdo-frontend/src/ +│ │ ├── units.rs # 标题角色和模式继承 +│ │ ├── payload.rs # 统一载荷与 source span +│ │ ├── map.rs # 唯一 Markdown→Stmt 映射与控制栈 +│ │ ├── signature.rs # params 声明(无旧写法) +│ │ └── analyze.rs # 单入口 +│ ├── marqdo-ir/ # 共享 IR +│ ├── marqdo-runtime/ # 既有值/内存/资源执行语义 +│ ├── marqdo-host/ # 既有权限和系统边界 +│ └── cli/ # 单语法 CLI +├── stdlib/ # 全部已更新的单版本官方标准库 +├── spec/ +│ ├── mapping.md # 当前唯一 AST→IR 规范 +│ ├── expression.ebnf # 当前唯一语句/表达式 EBNF +│ └── markdown-profile.md # Comrak/GFM 解析 profile +├── examples/ # 只有新语法可运行样例 +├── tests/ # 以“新语法”划分功能,而非版本 +└── docs/ # 现行指南+显式历史目录 +``` + +开发期间可以把不同职责的测试放在 `tests/semantics/heading_modes/`、`tests/semantics/control/` 等,但**不得创建 `tests/v1/` 与 `tests/v2/` 的永久双轨布局**。 + +## 7.3 数据结构设计:把新的概念压到最少 + +推荐在 Frontend 内部(不是对外语言 Value)使用: + +```rust +// 设计草图,不代表现有 API +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum SemanticMode { Knowledge, Exec } + +struct HeadingMode { + unit: UnitId, + mode: SemanticMode, + origin: ModeOrigin, // Explicit | Inherited { ancestor } + marker_span: Option, +} + +struct ExecutableSegment<'a> { + owner_function: FunctionId, + owner_unit: UnitId, + direct_blocks: &'a [MdNode], + mode: SemanticMode, // 只接受 Exec +} + +struct StatementPayload { + text: String, + file_segments: Vec, + outer_span: Span, + carrier: CarrierKind, // Strong | Emph | InlineCode + owner_unit: UnitId, +} + +enum V2StmtToken { + If(Expr), Else, While(Expr), End, Return(Expr), + Assignment(AssignTarget, Expr), Eval(Expr), Params(Signature), +} +``` + +结构必须能够保持:同一个 AST 不被重复遍历造成重复执行;每个 Payload 可追溯到精确 UTF-8 span;每个参数/控制词可追溯到原始语句;语义模式与 H2 Callable 身份是**不同字段**。 + +## 7.4 唯一 AST→IR 生成流水线 + +不能继续以旧 `Mapper::block()` 为默认路径;必须将其**替换**为新规则: + +```text +1. parse_markdown_once +2. build_heading_index_and_resolve_modes +3. index H2 Exec callable functions +4. collect document resources (inert) +5. traverse direct Exec function segments in source order +6. extract eligible closed payloads exactly once +7. parse every payload under one statement grammar +8. pair if/else/while/end within permitted segment scope +9. build Function.body / source maps +10. infer/validate signatures; resolve calls; emit IR +11. existing runtime and capability boundary +``` + +- 普通 Markdown 容器不触发语句;Knowledge 节点的可执行投影为空。 +- Exec 有效载荷的语法错必须报错;不能回退成文档。 +- 控制块不能跨越被规范设为终止边界的 Heading 片段,`end` 必须显式闭合。 +- 若当前源码缺少 `@exec`,不得“猜它是旧语言”;将其按 Knowledge 规则处理。对旧 `main`,`run` 应明确报告无可调用入口,而不是执行旧式 Strong/Emph。 +- 不允许在 CLI loader 内部临时维持旧 mapper 来“让一部分 fixture 继续通过”。 + +## 7.5 Source Span、UnitId 与 Analysis/Trace 的破坏性版本管理 + +- Heading 显示文本保留,语义名字剥离 `@exec`/`@knowledge` 后沿用 NFC/空白归一化,唯一性按新 Unit 索引检查。 +- `ModeOrigin`(Explicit/Inherited)进入 inspect/Analysis,以便编辑器解释某节点为何参与执行。 +- byte Span 不准丢;BOM/CRLF/CJK/Unicode source map 必须有 golden。 +- Analysis、Trace、CLI JSON、外部 Tool Protocol 若因模式索引、FunctionId 或 IR 产生**公共 schema 变更**,需按各自协议规范评估版本提升并更新**全部消费者和 fixture**;不必为了运行旧源文件而做兼容转换层。 +- 现有 `spec/analysis-v1.md`、`spec/trace-v1.md` 是结构化接口的历史版本名,并不表示它们可控制 `.mq.md` 旧语法。**源语言破坏性升级**不意味着所有无关 ABI/协议都必须强制破坏;但如确有破坏,就必须版本化协议并迁移消费者。 +- 必须显式记录 `semantic_revision` 作为新工具输出的**描述性字段**或 schema 契约;它不是一个源文件可选择的解析器分支。 +- 语法升级时清理因旧规则产生的缓存/锁文件构建派生物,避免将旧 IR 当成新 IR 执行。 + +## 7.6 与运行时、权限及标准库的边界 + +- 本轮**不重新设计** Memory/Resource/Value;新关键字只是 Frontend 语法并降级为原有 IR,不新建 `HostOp::If/Return`。 +- `@exec` 绝非权限授权;现有 Strict/Project/Pure、安全隔离、文件/网络授权仍是系统层决定。 +- `stdlib/` 既保持在同一仓库,又必须在**本轮全部迁移**。其中 `format.mq.md`、`io.mq.md`、`text.mq.md`、`data/table.mq.md`、`net/http.mq.md` 和 `stdlib/tests/*.mq.md` 都不得留旧式 `*return*`、有序分支或 bullet 循环。 +- 应**重算** `stdlib/stdlib.json` 中的 digest,并验证 frozen CLI 离线加载和相同摘要的构建重现;源码变更会改变包身份和 Analysis snapshot,这是预期的破坏性变更,不能硬改 expected digest 以掩盖问题。 +- 先保证已有函数的 API/行为在新语法下成立,**不顺手增加 stdin 等新标准库功能**,否则无法区分语法重构缺陷与扩展功能缺陷;缺口另设 issue。 +- 已锁定依赖的包如果只提供旧语法,需更新包和 lock,不能继续自动调用旧 mapper。 + +--- + +# 第 8 章:破坏性重构策略——不存在 V1 兼容路径 + +## 8.1 决策与发布契约 + +**本轮是原位、单语言、破坏性的语法升级。** 无论源文件是否有 Front matter、来自用户工作区还是 `std:`、来自锁定依赖还是 CLI 示例,全部使用唯一新的 AST→IR 映射。**不允许** `map_v1`、`parse_statement_v1`、`--legacy`、按文件语义版本切换、跨语法模块调用和双份 active spec。 + +升级前的代码不是“保留旧格式后仍能运行”,而是**需要升级的源文件**。CLI 的发行说明应显著列为 breaking change,必要时提升 Marqdo 的语言契约版本和 CLI 发行版本。一次性的迁移脚本**可以**作为开发期离线工具辅助改写仓库,但不得引入生产 CLI 的运行时语法兼容路径,不得自动吞掉不可翻译的旧语法。 + +## 8.2 原有语义到新语义的迁移规则(强制应用至全部代码资产) + +| 旧写法/行为 | 必须转换的新写法/行为 | 语义保真检查 | +|---|---|---| +| H2 无模式却默认为函数 | `## @exec 名称`,或从有效 Exec H1 继承 | `run/call` 入口不变、函数名剥离标记 | +| `**x=1**` 执行 | 在 Exec 范围仍可用,或统一 CodeSpan | 显式 Exec 下仅执行一次 | +| `*x*` 意味返回 | `*return x*`、`**return x**` 或独立 `` `return x` `` | return 路径和出口一致 | +| 有序列表互斥分支 | 显式 `if` / `else` / `end`;多臂条件需**保序、短路、只执行第一真分支** | 不能将互斥语义误写成并列多个 if | +| 无序列表各项独立循环 | 各自 `while cond` / `end` | 不得意外合并多个 while | +| `> print(x)` 自动调用 | Exec 下明确 `> **print(x)**` 或 `` `print(x)` `` | 原来调用次数/顺序一致 | +| H2 首段纯 CodeSpan `(n: Int)` 签名 | H2 Exec 第一条直接载荷 `params(n: Int)` | 参数顺序、默认值、名称相同 | +| 强制列表条件 / quote 调用导致报错 | 普通 Markdown 列表/引用成为容器或知识内容 | 对纯文档不再生成旧式错误 | +| CodeSpan 原先惰性(段落内) | Exec 下完整合法 CodeSpan 可成为载荷 | 原有文档必须明确标到 Knowledge,防止新增副作用 | +| 原文件缺语义标记 | 加标题级显式声明或按祖先继承 | 不允许依据正文内容猜执行意图 | + +迁移采用 AST 角色比对,而不是只做正则替换。遇到嵌套强调、特殊链接调用、段落内多载荷、旧多臂短路等情况,无法静态保真就**停止并人工改写该文件**。完成后废弃迁移专用临时脚本或放入明显的 `tools/dev-only/`,不得长期维护旧语言编译器。 + +## 8.3 仓库文档及测试的全量迁移边界 + +此次迁移**必须覆盖所有活跃资产**,而不只是 `spec/mapping.md`: + +1. **用户入口**:`README.md`、`COMPATIBILITY.md`、`CHANGELOG.md`、`docs/STATUS.md`、`docs/contributor-guide.md`、`tests/README.md`、`stdlib/README.md`、`examples/**/README.md`、CLI `--help` 与错误提示。 +2. **权威语言规范**:`spec/mapping.md`、`spec/expression.ebnf`、`spec/markdown-profile.md`(若 parser settings 未改只需说明语义变化)、`spec/evaluation.md`、`spec/references.md`,以及引用执行规则的数学/安全/包/ABI spec。 +3. **官方源码**:`stdlib/**/*.mq.md`、`examples/**/*.mq.md`、仓库全部 `.mq.md`(包括测试 fixture、项目模板 `INIT_TEMPLATE`、Rust/Python 测试中内嵌字符串)。 +4. **测试与黄金文件**:`tests/conformance/ast/**`、`tests/conformance/semantics/**`、`tests/negative/**`、`tests/security/**`、`crates/cli/tests/**`、各 crate 内联 `#[test]`/`#[cfg(test)]` 测试、协议消费者用的示例数据和 snapshot。 +5. **构建与发布**:`stdlib/stdlib.json` 摘要、`tools/pack-stdlib.py` 的打包验收、CI 工作流、跨平台 build/test、Tool/Analysis/Trace 的消费者脚本与 schema(只有公共协议确实变化才改 schema)。 +6. **历史资料**:`docs/adr/*` 与历史 RFC/审核报告中描述旧语法的内容不必伪造成新决策,应保留为**显式归档**,在顶部标明 `Historical / Superseded` 并给出当前唯一规范链接;从 README/架构索引删除到旧语法的“现行指引”链接。历史文件中的旧例子不得被当作活跃可运行教程或自动校验的代码示例。 + +**每一文件必须有迁移账目**:`path | type | old semantics? | required action | owner | test gate | status`,不能用“grep 没找到 return”代表已经审阅全部仓库。 + +## 8.4 仓库真实资产基线与差异化处置 + +基于 `7fbe069...` 递归 Git tree,审查时约 **942 个文件**。以下数量是**审查 SHA 的目录统计,不是当前工作分支的不变真理**;实施时必须重新导出完整文件清单。 + +| 范围 | 基线规模 | 迁移要求 | +|---|---:|---| +| `docs/` | 约 92 文件,包含 39 个 ADR | 活跃规范与教程重写;历史决策标记废止/历史 | +| `spec/` | 21 文件 | 对执行/语义映射的规范原位升级,引用关系审查 | +| `examples/` | 44 文件 | 所有可运行 `.mq.md`、项目配置和 README 一起更新 | +| `stdlib/` | 11 文件;含 9 个 `.mq.md` | **全部**标准库和 self-test 重写,更新摘要 | +| `tests/` | 约 632 文件;AST conformance 320 文件、语义 conformance 146 文件 | 按测试性质分别保留 Markdown profile 或重写语义黄金 | +| `crates/cli/tests/` | 17 个集成测试文件 | 审计 Rust 内嵌 `.mq.md` 字符串、快照、预期诊断 | +| `crates/` 其他目录 | 多个单元测试/夹具 | 搜索并重写所有携带旧语义的源码样例 | + +**最容易做错的地方**是 `tests/conformance/ast/`:它验证原生 Markdown AST 的解析,某些只测试强调/有序列表结构的源文件**可以保留**,因为 Markdown AST 没有变化;但任何从该输入进一步断言 `Return/Branch/Loop` 的测试都必须更新。测试是否修改,应由其**验证目标**决定,而非机械批量把每份 Markdown 都加 `@exec`。 + +`tests/conformance/semantics/` 的约 73 组语义样例,以及 `tests/negative/` 中的旧“列表必须有条件”“引用块只能调用”等断言,需要彻底审查:许多原负例在新语法下应成为**合法惰性 Markdown**,不能继续期待报错;另一些旧负例需要替换为 `if` 缺少条件、悬空 `else`、缺少 `end`、非法 `params` 位置等负面样例。 + +## 8.5 必须重新审查的现行文档(逐一可执行的改写要求) + +| 文件 | 修改动作 | 完成标准 | +|---|---|---| +| `README.md` | 以 `# @knowledge` / `## @exec main` 开篇;重写 Hello、Factorial、Loop、Return;明示旧语法不支持 | 第一个 Quickstart 可直接运行,源码不需额外版本字段 | +| `docs/DEVELOPMENT_BLUEPRINT.md` | 将“Strong→执行/Emph→Return/List→Branch/Quote→Call”的设计替换;若已过时标示历史并链接新规范 | 无旧语法被当作现行设计 | +| `docs/STATUS.md` | 更新真实完成度、最新 SHA、语义重构状态和测试结果 | 不声称未跑的平台通过 | +| `docs/architecture/README.md` | 指向一个生效的语言规范入口;历史 RFC 明确不是活跃编译契约 | 从入口找不到相互冲突的现行映射 | +| `docs/contributor-guide.md` | 写出语法变更流程、fixtures、fmt/golden 更新和审核清单 | 新贡献者无需聊天背景可提交语法 PR | +| `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`、`docs/NEXT_PHASE_IMPLEMENTATION.md` | 清理旧分期、旧兼容目标,与本计划合并或归档 | 无两份相冲突的开发路线图 | +| `docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md`、`docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md` | 保留计算模型有效内容,更新示例语法与前端假设;历史提案标注覆盖范围 | 不把旧例子当新 CLI 可运行程序 | +| `COMPATIBILITY.md` | 将旧源语法列为不兼容;同时独立呈现 OS/ABI/Plugin 兼容矩阵 | “兼容”不暗示旧语法可以执行 | +| `CHANGELOG.md`、`docs/releasing.md` | 明确 breaking change、所需代码改写、依赖更新与正式门禁 | 发布者知道这是破坏性升级 | +| `tests/README.md` / `stdlib/README.md` | 描述新的测试分类与新样例 | 文档中的命令与实际路径匹配 | +| `spec/mapping.md` | **原位完整替换**为新 AST→IR 映射 | 不再存在 V1 语义作为可选路径 | +| `spec/expression.ebnf` | 以关键字语句和现有 expression 组成唯一文法 | `if/else/while/end/return/params` 均有规范与反例 | +| `spec/evaluation.md` | 更新 Return/Branch/Loop 来源及跨标题边界,保留数值/Memory/Resource 运行语义 | 只变语法、不悄悄更改结果/权限 | +| `spec/references.md` | 复核 `@exec/@knowledge` 剥离后的标题名与 FunctionId/ref 解析 | 文档链接、模块锚点不会错位 | + +**历史 ADR 操作规范**:历史文本中旧语法示例保留且注明“当时语法,仅供决策考古”。若旧 ADR 的决策已被本轮推翻,必须新增一份替代 ADR 并在旧 ADR 顶部加 `Superseded by ADR-...`;不要悄悄修改 ADR 日期或把历史叙述改写成仿佛当年已接受新语法。 + +## 8.6 测试集的全面改造规范(不是简单 regenerate golden) + +| 测试类别/路径 | 操作 | 新验收逻辑 | +|---|---|---| +| `tests/conformance/ast/` | 保留无关的 Markdown AST golden;增加模式前缀 H1–H6、closed carrier、BOM/CRLF/CodeSpan AST fixtures | 原生 Markdown AST 不因语义升级被篡改 | +| `tests/conformance/semantics/` | **逐组改写**旧 Strong/Emph/List/Quote 语义;按照真实程序插入 Exec 标题、return/if/while/end/params | 值、可观测副作用与错误类型符合新规则 | +| `tests/negative/*.mq.md + *.expected.json` | 分类:旧负例变正例、负例保留但原因改变、旧负例删除并由新负例替代 | 不保留错误的“普通列表必须报错”预期 | +| `tests/negative/runtime/` | 语法移植,保留真实运行时负例(越界、类型、权限等) | 错误仍来自 Runtime 而不是旧格式解析失败 | +| `tests/negative/warnings/` | 重新定义“Knowledge 惰性、无可调用 main、Exec 无所属函数”等 warning/error | 不保留 V1 `markdown.inert_executable` 的错误预期 | +| `crates/cli/tests/conformance_*.rs` | 更新 golden harness 的源语义假设 | 检查当前唯一扫描器,不按文件分流 | +| `crates/cli/tests/negative.rs` | 更新反例分类和新错误码 | 负面测试不靠老规则凑数量 | +| `crates/cli/tests/examples_r6.rs` / `integration_cli.rs` | 迁移 CLI 用例中硬编码源码、命令与 expected JSON | run/call/check 都能操作新语法 | +| `crates/cli/tests/print_routing.rs` | 迁移旧语法的载荷,保留 stdout 路由与可观测结果 | 不会因改写误测 `HostOp::Print` 回退 | +| `crates/cli/tests/stdlib_*`、`p2_closure.rs` | 使用新标准库源码和新 digest 跑离线冻结二进制闭包 | 冻结 CLI 可以完全使用新语法的 stdlib | +| `crates/cli/tests/resource_streams.rs` / `http_over_tcp.rs` | 对 fixture 的 Markdown 语句做迁移,保留真实文件/TCP 行为断言 | 资源权限、短写、EOF 的回归通过 | +| `crates/cli/tests/analysis_trace.rs` / `tool_protocol.rs` | 检查 UnitId/FunctionId/Span/Trace 与 schema 是否变化;更新消费者 | CLI 工具输出不包含旧 mapper 身份 | +| `crates/cli/tests/package_env.rs` / `plugin_worker.rs` | 迁移依赖包和插件演示中的 `.mq.md`,更新 lock/摘要 | 不通过旧语法旁路来让插件测试通过 | +| `crates/cli/tests/properties.rs` | 增加 Strong↔Emph↔Code、List↔Bullet↔Quote 不变性和知识惰性性质 | 比较归一化 IR + 运行结果/trace | +| 各 crate 的源码内 `#[test]` | 精确审计嵌入的 Markdown 文本、错误码和解析假设 | Rust 单元测试也使用唯一语法 | +| `tests/security/` | 更新 helper 及正向执行 fixture,不降低安全拒绝要求 | 相同 sandbox 策略仍然 fail-closed | +| `tools/pack-stdlib.py` 与发布 CI | 校验打包摘要和语义语料闭包 | 未迁移样例/测试不得通过打包门禁 | + +**强制 golden 更新规范**:每次变更先人工或受控生成“新规范正确的期望”,再运行测试;只有当新输出有明确语义解释时才能更新 golden。禁止 `UPDATE_GOLDENS=1` 一键覆盖所有预期并把语义变化视作已经审查。 + +## 8.7 全库扫描与可追溯迁移台账 + +在同一基线生成仓库文件台账(建议提交 `docs/migration/semantic-rewrite-inventory.tsv`,完成后也可保留审计证据),至少包含: + +```text +pathcategoryactiveold_semanticsactionownerverificationstatus +``` + +扫描顺序: + +1. 使用 `git ls-files` 遍历所有跟踪文件(不只 `.mq.md`);另用 `rg` 发现 README、Rust 测试常量、文档围栏和模板中的旧语法模式。 +2. 通过解析 Markdown AST 区分普通 Markdown 强调与执行节点,不允许纯 regex 自动批量改写代码。 +3. 标记 `active/spec`、`active/tutorial`、`active/example`、`active/stdlib`、`active/test`、`historical/adr`、`generated/golden` 和 `non-semantic`。 +4. 对每个语义受影响文件,记录新语法写法、关联测试编号和审查者。跨文件引用以最新 UnitId/FunctionId 重新验证。 +5. **迁移覆盖率 = 100% 已分类文件**;活跃的 `.mq.md` 必须全部可按唯一新语法分析、运行或按预期负例拒绝。历史文档可保留旧示例,但必须有明显历史声明并从活跃规范入口隔离。 + +可作为 CI **初步扫描**(仅找候选,不作为正确性证明): + +```bash +git ls-files '*.mq.md' '*.md' '*.rs' '*.py' '*.json' '*.yml' '*.yaml' > /tmp/marqdo-semantic-files.txt +rg -n 'Strong.*执行|Emph.*返回|OrderedList.*分支|BulletList.*循环|BlockQuote.*调用|inert_executable|map_v1|map_v2|marqdo_semantics|--legacy' README.md COMPATIBILITY.md CHANGELOG.md docs spec examples stdlib tests crates tools || true +``` + +**CI 最终证明不能依赖 grep 零匹配**:必须结合 manifest 台账、真实 AST/IR 编译、全量示例执行、负例诊断、stdlib digest、文档代码样例检查和冻结二进制 E2E。 + +## 8.8 不应为了破坏性重构添加的“多余东西” + +- 不新增兼容 crate、第二解析器、第二语法版本 dispatch、`--legacy` 或源文件语义版本标记。 +- 不为旧语法永久保留多一套教程、golden、stdlib 子目录或测试执行器。 +- 不以删除大量负例/测试来“提高通过率”;旧测试若不再适用,必须以新的等价责任测试替换并记录。 +- 不改变 Memory、Resource 的抽象语义;不借语法重构添加 Host API 或无关功能。 +- 不让历史 ADR 在正文中未经标注地继续宣称旧语法现行有效。 + +--- + +# 第 9 章:阶段实施计划(全仓库同步交付) + +**开发分支可以分多个提交实现,但不能把只有 Frontend 换了、标准库和文档未迁移的状态作为可发布中间产物。** 每阶段应明确“代码变化 + 文档变化 + 测试/黄金变化 + 全库状态”,最终合并必须完整闭环。 + +| 阶段 | 具体交付 | 阻断性验收 | +|---|---|---| +| **S0:规范冻结与资产台账** | 决定唯一语法、真实 Comrak AST probes、所有文件的分类和 owner;批准破坏性 ADR | 100% 跟踪文件分类,禁止源语义版本分流 | +| **S1:模式/标题索引替换** | 在 `units.rs` 原位实现 H1–H6 标记继承、知识与可执行 H2 分离 | 标题 mode 与 Unit/FunctionId golden 全部通过 | +| **S2:统一载荷替换** | 直接重构 `payload.rs`、`map.rs`;删旧 Strong/Emph/Quote/List 专用分支 | 每种闭合标记都只执行一次;普通列表/quote 无固定执行义 | +| **S3:关键词控制与签名** | 单套 Statement Parser;`if/else/while/end/return/params`、控制栈和 source span | 完整文法正反例、嵌套和跨标题负例通过 | +| **S4:官方标准库迁移** | `stdlib/**/*.mq.md` 全数改写,更新 `stdlib.json` 和 `std:` loader self-test | frozen CLI 离线加载、print、HTTP、Table、UTF-8 测试通过 | +| **S5:官方示例和文档迁移** | README、现行 docs、spec、`examples/`、CLI Help、init 模板全部迁移 | Quickstart 全部可复制运行;无旧语法现行指引 | +| **S6:全量测试语料替换** | semantics 146 文件逐项、negative/runtime/warnings、Rust 内嵌 fixture、协议 schema/golden 差异审计 | 所有新负例/正例充分覆盖,不允许保留旧期待行为 | +| **S7:跨模块与安全回归** | lock v3、Plugin/Worker/Foreign、Tool/Analysis/Trace、strict sandbox、Memory/Resource | 语法升级不绕过资源权限,错误/Trace 有可解释变更 | +| **S8:完整仓库 RC 审计** | 全量 CI、真实平台状态、Breaking release notes、迁移覆盖报表 | 100% 迁移清单闭合;单语法全仓通过;无双 mapper | + +**推荐提交切分**:可以是 `docs(spec)` → `frontend/expr` → `stdlib` → `examples` → `tests` → `ci/release`,但不可让 Cargo/stdlib 的暂时失败成为长期的主分支状态。若使用 PR,最稳妥的是一个特性分支持续集成,最后一次合并而非多次把未迁移状态合入 main。 + +## 9.1 开发规范与职责划分 + +- 语言团队只改 Markdown AST→语义投影、Expression Parser、Function/Unit 索引;运行时团队确认无新增语义边界需要改动。 +- 标准库团队负责迁移 `.mq.md`,**不得**借旧语法继续在 `std:` 模块中工作。 +- 测试团队按业务行为和语法形态双维度建设 fixtures,逐条记录旧测试被新测试接替的位置。 +- 文档团队负责所有现行入口和 README 实例可运行性,维护 `docs/migration/` 台账。 +- 审查者对每个提交检查:是否引入第二语法入口?是否有未迁移 `.mq.md`?是否更新对应 spec/test? + +## 9.2 每阶段最小交付格式 + +```text +阶段编号:Sx +变更文件:... +已改现行文档:... +替代/新增测试:... +运行命令与结果:... +受影响的 stdlib digest / protocol fixture:... +剩余未迁移文件及 owner:... +未完成的真实平台验证(不得冒充 PASS):... +``` + +## 9.3 阶段与门禁的依赖关系 + +- `S1/S2/S3` 可在同一分支重构,但在准备 S4 前必须能编译并运行本规范第 13 章的纯计算示例。 +- `S4` 完成之后,必须验证一份使用 `std:io` 的 Hello 程序可完全在新的单语法 CLI 上运行。 +- `S5/S6` 不得互相等待导致文档与测试长期背离,应针对每份现行示例同时提交相应 fixture。 +- `S7/S8` 需验证没有旧 mapper、旧模块调用路径或旧规范入口,尤其是跟踪目录中没有独立的 legacy test runner。 + +--- + +# 第 10 章:完整语法与行为测试矩阵(用于直接创建 fixture) + +本章使用**固定输入 → 精确行为**表达测试要求。每个正例必须同时检查 Parser AST、模式、载荷序列、规范化 IR、执行结果;每个反例至少检查稳定错误码、源跨度和“不得静默执行”。 + +## 10.1 A 组:标题模式、函数归属和单语法(A01–A18) + +| ID | 最小测试场景 | 必须验证 | +|---|---|---| +| A01 | 文件没有任何语义版本 Front matter | 直接按唯一新语法处理 | +| A02 | Front matter 提供 `import` 但无语义版本 | 导入可解析,只有新语法 | +| A03 | `# @knowledge 项目` | H1 Knowledge,语义名为 `项目` | +| A04 | `# @exec 项目` + `## main` | H2 继承 Exec,成为函数 | +| A05 | `## @exec main`(无 H1) | 根 H2 可为 Exec 函数 | +| A06 | `## @knowledge 注释` | 知识单元,不是 Callable | +| A07 | `### @exec 过程`(Exec H2 下) | 属于 H2,执行语句追加 | +| A08 | H4 Knowledge 与同级 H4 Exec | 同级分别继承父级,无 sibling 泄漏 | +| A09 | H1 Exec → H2 Knowledge → H2 无标记 | 后者继承 H1 Exec | +| A10 | H1 Knowledge → H2 Exec → H3 Knowledge → H3 Exec | 仅 Exec 片段产出 IR | +| A11 | H2 Knowledge 下 H3 Exec 带载荷 | `sem.exec_without_function` | +| A12 | H1 Exec 下无所属函数的载荷 | `sem.exec_without_function` | +| A13 | `## @exec`(无真实名称) | `sem.empty_unit_name` | +| A14 | `## @knowledg main` | 明确错误并提示 `@knowledge` | +| A15 | `## @Exec main` | 非法模式标记,不能猜测大小写 | +| A16 | `## @exec @knowledge main` | 冲突声明 | +| A17 | `## 关于 @exec 的说明` | 标题普通正文,不改变模式 | +| A18 | 含 `marqdo_semantics` Front matter | `sem.unsupported_version_directive`,不得分派旧编译器 | + +## 10.2 B 组:载荷等价与惰性边界(B01–B18) + +| ID | 输入变体 | 必须验证 | +|---|---|---| +| B01 | `**x = 1**` | 一个 Assign | +| B02 | `*x = 1*` | 同 B01 的 Assign | +| B03 | `` `x = 1` `` | 同 B01 的 Assign | +| B04 | `**`x = 1`**`(实际按真实 AST 验证) | 恰好一次 Assign | +| B05 | `*`x = 1`*`(实际按真实 AST 验证) | 恰好一次 Assign | +| B06 | `**return x**` | Return(x) | +| B07 | `*return x*` | 同 B06 | +| B08 | `` `return x` `` | 同 B06 | +| B09 | `*x*`(在 Exec 中) | Eval(x),不是 Return | +| B10 | `**重点**`(在 Knowledge 中) | 零指令,无未知变量错误 | +| B11 | `**重点**`(在 Exec 中) | 参与表达式解析,无对应变量则 symbol.unknown | +| B12 | `> 普通引用正文` | 零指令,无调用错误 | +| B13 | `> **print(1)**` | 一次调用 | +| B14 | `1. 普通事项` | 零指令,无条件错误 | +| B15 | `- 普通事项` | 零指令,无循环错误 | +| B16 | Table Cell 中含 `**print(1)**` | 零指令 | +| B17 | 链接 Label 或图片 Alt 含闭合标记 | 零指令 | +| B18 | 复杂非法嵌套 Strong/Emph/Link | `sem.payload_nested`;不能部分执行 | + +## 10.3 C 组:控制关键字、作用域与副作用(C01–C22) + +| ID | 场景 | 预期 | +|---|---|---| +| C01 | `if true ... end` | then 运行一次 | +| C02 | `if false ... end` | then 不运行 | +| C03 | `if false ... else ... end` | else 运行一次 | +| C04 | `if true ... else ... end` | else 不运行 | +| C05 | if 嵌套 if | 最近未结束 if 优先配对 | +| C06 | if 嵌套 while | while 完成后再配对外层 if | +| C07 | while 3 次 | 条件逐轮求值,确切循环次数 | +| C08 | while 假条件 | 循环体零次 | +| C09 | `return` 在 if 内 | 退出整个 H2 函数 | +| C10 | `return` 在 while 内 | 退出整个 H2 函数 | +| C11 | `end` 无 open | `sem.unmatched_end` | +| C12 | `else` 无 if | `sem.unmatched_else` | +| C13 | `else` 对应栈顶 while | 必须拒绝 | +| C14 | if 两次 else | `sem.duplicate_else` | +| C15 | if 缺 end | `sem.unclosed_control` | +| C16 | while 缺 end | `sem.unclosed_control` | +| C17 | 控制块跨 H3 标题 | 不允许跨越,明确关联 Span | +| C18 | `if x > 0:` | `sem.syntax` | +| C19 | `end if` | `sem.syntax` | +| C20 | `return` 无表达式 | `sem.syntax` | +| C21 | `ifdef()`、`returning()` | 视为普通标识符调用,而非关键字前缀 | +| C22 | if 条件非 Bool | 既有 static/runtime type 错误 | + +## 10.4 D 组:参数、名称、标准库与跨模块(D01–D16) + +| ID | 场景 | 必须验证 | +|---|---|---| +| D01 | `params(x: Int)` 是 Exec H2 第一条直接载荷 | 显式签名正确 | +| D02 | 同参数声明换 Strong/Emph/Code | 相同签名 | +| D03 | `params` 出现在 List/Quote 内 | `sem.signature_position` | +| D04 | `params` 出现在其他语句之后 | `sem.signature_position` | +| D05 | 同函数第二次 `params` | 拒绝重复声明 | +| D06 | 没有 `params` | 对实际 Exec 载荷进行自由变量推断,不读取 Knowledge 文本 | +| D07 | Knowledge 中的未定义名 | 不进入程序符号分析 | +| D08 | H3 Exec 读取父 H2 的已赋值变量 | 同一调用帧 | +| D09 | H2 Knowledge 被 `call` | 拒绝,给出明确错误 | +| D10 | **新语法**模块导入**新语法**同仓库 stdlib | 成功解析执行,stdout 等效 | +| D11 | 依赖包仅有旧式源语法 | 编译拒绝,不能启用兼容 mapper | +| D12 | 资源权限拒绝 | `@exec` 不绕过 Capability | +| D13 | Memory 写入载荷在多种 Markdown 载体中等价 | Byte 写入与读回结果相同 | +| D14 | 函数无 Return | 返回 Unit,不等于 None | +| D15 | 语义名剥离模式前缀 | UnitId/FunctionId 一致且可查找 | +| D16 | 已升级的项目依赖锁文件 | digest/instance identity 可重现,无旧源码暗编译 | + +## 10.5 E 组:全仓迁移、格式化和工具行为(E01–E20) + +| ID | 场景 | 验收 | +|---|---|---| +| E01 | `marqdo run` 不带语义版本参数 | 唯一新语法 | +| E02 | 旧 H2/Emph 返回用例 | 不按旧语义运行,迁移后的新例成功 | +| E03 | 老式列表强制条件负例 | 转为新语法下的合法普通列表测试 | +| E04 | 仓库所有 `.mq.md` 分类审计 | 活跃正例可编译/负例按新规则拒绝 | +| E05 | 全仓没有语义 mapper 分派 | 代码检查 + 单元测试确保只有单入口 | +| E06 | `inspect --ast` | 原生 Markdown AST 未被改造 | +| E07 | `inspect --semantics`/相应输出 | 显示 Explicit/Inherited、FunctionOwner | +| E08 | 载荷 SourceSpan | 精确到字节 | +| E09 | UTF-8 中文 | 位置准确 | +| E10 | CRLF/BOM | 结果可重现 | +| E11 | Setext H1/H2 | 真正 Markdown AST 规则一致 | +| E12 | `fmt` 往返 | 语义 IR 和文档结构稳定 | +| E13 | Strong↔Emph↔Code 元变换 | 规范化 IR 等价 | +| E14 | Ordered↔Bullet↔Quote 容器等价 | 保持相同 payload 顺序时 IR 等价 | +| E15 | README Quickstart | 原样拷贝可执行 | +| E16 | `examples/**/*.mq.md` | 全数有 `check` / `run` / `call` 或明确负例 | +| E17 | `stdlib/**/*.mq.md` | 完全使用新语法、离线 frozen CLI 通过 | +| E18 | `stdlib/stdlib.json` | digest 与实际新源码树一致 | +| E19 | `docs/` 中全部 active 代码围栏 | 标为可运行的例子能按唯一语法执行;历史例子显式注明 | +| E20 | CI 工作流/发布门禁 | 无旧语言通过条件,无跳过迁移语义集的永久例外 | + +## 10.6 目标 fixture 分类(按语义功能,不按语言版本) + +```text +tests/ +├── conformance/ +│ ├── ast/ # Markdown Profile 结构基线;无需强改纯 AST 样例 +│ └── semantics/ # 完全迁移新 AST→IR 语义与 golden +├── negative/ # 新语法错误+原有 Runtime 错误 +├── semantics/ +│ ├── heading_modes/ # H1–H6 继承、错误前缀 +│ ├── payload_carriers/ # Strong/Emph/Code 等价 +│ ├── control_flow/ # if/else/while/end/return +│ ├── functions_and_imports/ # params/H2 callable/模块引用 +│ └── transformations/ # 元变换和结构等价 +└── security/ # 既有权限拒绝+更新的正例 +``` + +不要创建 `tests/v1/` 与 `tests/v2/` 两套永久语义族。测试元数据可记录 `language_revision: "current"` 供诊断和追溯,但不得充当编译器模式选择器。 + +每条 golden 必须保留:原始 `.mq.md`、预期 IR/结果或诊断码、精确 SourceSpan(如该测试关心)、依赖/权限/执行环境,以及“是否在新语法重构中由旧 fixture 改写”的台账引用。 + +--- + +# 第 11 章:开发规范、代码审查规则和禁止事项 + +## 11.1 语言规范先行,而不是直接“修改到能跑” + +每次改变语法,提交必须包含以下内容并按顺序进行: + +1. **原位更新**适用的规范章节(优先 `spec/mapping.md` 和 `spec/expression.ebnf`),说明哪些源码合法、哪些非法以及原因;不创建并行活跃规范。 +2. 增加**真实 Markdown AST golden**,确认 CommonMark/GFM 实际解析出了什么,尤其是星号嵌套和 CodeSpan。 +3. 增加正常使用的**源码 → 归一化 IR → 结果** golden,以及相同语义的至少一个 Markdown 载体替换测试。 +4. 增加至少两个**负面样例**:确保非法控制流和错拼指令不会被吞掉。 +5. 再实现 Frontend / Expression 变化;如必须更改 Runtime,应提交单独 ADR 证明现有 IR 无法表达该语义。 +6. 更新 README 的语法速查与迁移表;用户文档不能落后于可执行程序。 + +**合并时检查的关键问题**:新特性是真的语言语法,还是只是一个标准库函数?若只是功能,放进同仓库 `stdlib/`,不要增加关键字或 HostOp。 + +## 11.2 确定性原则(不得违反) + +**明确禁止的写法或实现策略**: + +- `try parse executable; if fails => ordinary prose`。 +- 因为一个列表的第一项出现 `if`,就推断整个列表是可执行分支。 +- 通过自然语言内容(如“若”“否则”“执行”“返回”)猜测控制语义。 +- 因 `Strong` 是加粗,就赋值;因 `Emph` 是斜体,就返回(这是被废止的旧行为)。 +- 因 `BlockQuote` 是引用块就自动调用;因 `OrderedList` 是列表就自动分支。 +- 源码原始字符串中寻找 `@exec`、`return`、`if` 任意子串决定 AST 结构。 +- 遇到未知 `@knowledg` 就退回上一祖先模式。 +- 在 Knowledge 中反复扫描载荷、为“看起来是代码”的部分制造假执行事件。 +- 根据 `--allow-read`、`--allow-net` 权限开关改变 AST→IR 编译结果。 +- 在 Parser 中引入与 V2 正式文法没有对应测试的自动修复、冒号容错或语法猜测。 + +**严格隔离测试**:同一份 Knowledge 文档在不同权限开关下,应产生相同的零执行投影;同一份 Exec 文档在静态编译阶段也不应因 Host 权限不同而改变 AST 或 IR,权限只在运行时检查。 + +## 11.3 Markdown 是语言界面的一部分,需要像 ABI 一样审查 + +- **保留 Markdown 可渲染性**:不能因为方便而用私有的 Markdown 解析分支吞掉普通段落、链接或表格。 +- **保留源码位置**:不能只输出拼接后的 `"return x"` 而丢失它原来位于 `*...*` 还是 `` `...` ``、哪个标题或哪个列表项。 +- **保留结构关系**:即使所有执行载荷线性化,原始 AST/Unit 仍可供 inspect、未来知识索引和分析工具读取。 +- **保留语法正交性**:Strong 与 CodeSpan 的执行行为应尽可能等价;列表类型、引用容器类型不能意外影响指令种类。 +- **保留函数可读性**:示例应避免过度嵌套 Markdown 标记;在一个函数里不得为了满足测试而把复杂程序压成一行巨大的载荷。 +- **不牺牲文档自然性**:默认 Knowledge,说明段落/表格/引用与正规 Markdown 一样工作;Exec 模式下的强调冲突必须在文档中诚实提醒。 + +## 11.4 Rust 工程边界和模块耦合约束 + +| 责任 | 唯一所属模块 | 禁止的替代方案 | +|---|---|---| +| Comrak/GFM AST | `marqdo-markdown` | 第二 Markdown parser 或 regex 语法解释 | +| 标题声明、模式继承 | `marqdo-frontend/units.rs`(或同 crate 小模块) | Host/CLI 猜标题语义 | +| Strong/Emph/CodeSpan 提取 | `marqdo-frontend/payload.rs` | 运行时自行识别 Markdown 强调 | +| 唯一 AST→IR 编排与控制栈 | `marqdo-frontend/map.rs` | `map_v1` + `map_v2` 同时存在 | +| 语句词法与关键字 | `marqdo-expression` | CLI 用正则解析 if/return | +| 函数参数 `params` | `marqdo-frontend/signature.rs` | 旧式孤立 CodeSpan `(x: Int)` 特例 | +| 数值运算、内存和资源执行 | 现有 Runtime/Host | `HostOp::If` 或 `HostOp::Return` | +| 高级文本和 I/O 组合 | 同仓库 `stdlib/` | 在 Rust 中反复增加同类算法 Builtin | +| 仓库迁移审计 | `docs/migration/` 台账 + 现有 CI | 主程序新语法、标准库旧语法 | + +依赖方向保持 `markdown → frontend → ir → runtime`。不要因为破坏性语法升级创建另一个 Runtime、解释器或兼容 crate。 + +**必审项目**:每个影响 `.mq.md` 表面的 PR 必须列出受影响 README/Spec/Example/Stdlib/Test;没有同步迁移证据的 PR 不得视为完成。 + +## 11.5 性能、可维护性与错误恢复 + +- 解析源码只执行一次 Comrak;模式与语义索引尽量单次顺序扫描;载荷 AST 用引用视图而非复制全树。 +- `N` 个 Markdown 节点的模式计算和提取应接近 `O(N)`,不应因每层标题重复扫描父标题或递归遍历整个文档形成 `O(N^2)`。 +- 对恶意嵌套 Markdown 必须限制 AST 深度、表达式深度和控制栈深度,限制来自现有资源预算与解析器安全策略,不应无限递归崩溃。 +- 解析器可在 IDE 检查时恢复多个错误以展示给用户,但生成执行器之前**只要存在硬错误就不得运行**;错误恢复只是诊断能力,不是容错执行。 +- 诊断必须含机器可用的 `code` 和原始 `Span`;必要时提供 `related_span` 指向未关闭的 if 或对应的重复模式声明。 +- 原有缓存、分析摘要和构建产物必须在此次破坏性升级时失效/重建;不得让旧语义生成的缓存 IR 在新运行时直接复用。 + +## 11.6 Review Checklist(每个语法 PR 都必须回答) + +- [ ] 该 PR 是否改变了已定义语义?如改变,是否有批准的 ADR 和规范修订? +- [ ] 所有用户示例是否能被当前提案文法精确解释,而不是依赖人类脑补? +- [ ] 是否新增了不必要的关键字、Rust HostOp 或重复 Runtime 分支? +- [ ] 是否存在某种 Markdown 排版转换会改变程序行为?若有,是否是本来就该改变的载荷文本? +- [ ] 有没有将 Exec 语法错误静默改成普通文档? +- [ ] 普通 `1.` / `-` / `>` 是否不再强制成为分支、循环或调用? +- [ ] 是否对照真实 Comrak AST 验证星号、CodeSpan、换行与混合文本? +- [ ] Heading 继承是否正确处理兄弟、子标题、跳级和源文件结尾? +- [ ] 函数的名称、参数、作用域与 Call 语义是否保真? +- [ ] 是否已经删除所有 V1 编译分支,旧语法不能再作为合法活跃程序执行? +- [ ] 权限、Sandbox、Resource、Trace 是否保持原有安全要求? +- [ ] 迁移台账是否覆盖 README、全部 active docs、stdlib、examples、所有 fixture、Rust 内嵌样例和 CI? + +--- + +# 第 12 章:验收标准、CI 门禁与发布条件 + +## 12.1 必须完成的架构与全仓验收 + +| 门禁 | 必须证明 | 阻断场景 | +|---|---|---| +| G01 | **只有新语法**:无 per-file 版本、无旧 mapper、无 legacy flag | 新程序仍可通过 V1 fallback | +| G02 | 所有活跃 `.mq.md` 经单一新 mapper 编译/校验 | 某 stdlib 模块仍用斜体返回 | +| G03 | H1–H6 模式继承确定 | 同层兄弟模式泄漏 | +| G04 | Knowledge 绝无执行副作用 | Knowledge Table 的 `print` 被调用 | +| G05 | Strong/Emph/CodeSpan 单句等价 | 换强调方式后 Assign 变 Return | +| G06 | 闭合节点仅提取一次 | 嵌套 CodeSpan 触发两次执行 | +| G07 | if/else/while/end 严格配对 | `else` 越过栈顶 while 绑定外层 if | +| G08 | 列表/引用块无指令特权 | 把 `1.` 换成 `-` 导致 Branch→Loop | +| G09 | 错误有确定码和精确 SourceSpan | `if x >` 被当普通说明吞掉 | +| G10 | H2 Exec 才可调用,H3 归属正确 | H3 被导出独立函数 | +| G11 | 不允许跨语义片段非法配对 | `end` 越过标题边界关闭旧 if | +| G12 | `params` 无特殊 Markdown 容器特权 | 只有独立 CodeSpan 可声明参数 | +| G13 | 复用现有 IR/Runtime/Memory/Resource | 新增一套 V2 VM | +| G14 | 安全权限保持原约束 | `@exec` 绕过文件网络 capability | +| G15 | `stdlib/` **完整迁移 + digest 更新** | 旧式标准库在新 CLI 下无法载入 | +| G16 | `examples/` 与 README 样例原样可运行 | 文档需要读者自行补模式声明 | +| G17 | `spec/` 只有一套现行语义规范 | `mapping-v1.md` 与 `mapping-v2.md` 双活跃 | +| G18 | 全仓测试 golden 与 Rust 嵌入 fixture 重构 | 旧负例仍要求普通列表报错 | +| G19 | 历史 ADR 明确历史,不误导开发者 | README 将旧 RFC 视为现行语法 | +| G20 | 文件级迁移台账 100% 闭合 | “未审阅”文件不计入失败 | +| G21 | README 初学者无需聊天背景能使用 | 找不到可复制的 main/if/while 示例 | +| G22 | 平台与安全 CI 如实标记实际验证状态 | 把本地 PASS 说成 Windows/macOS CI 全绿 | + +**阻断性合并结论**:任一 G01–G22 未通过,不得合并为声称已经完成的破坏性语法重构,也不得发布“新语法稳定版”。 + +## 12.2 推荐 CI 检查与全仓语法门禁 + +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace --locked + +# 下一步由开发者实现并固定的门禁(本 RFC 不声称现有脚本已存在) +# python3 tools/check-language-migration.py --inventory docs/migration/semantic-rewrite-inventory.tsv +# python3 tools/check-document-examples.py --readme README.md --active-docs docs/ +# python3 tools/check-stdlib-syntax.py --stdlib stdlib/ +# python3 tools/check-single-mapper.py --crates crates/ +``` + +新增检查脚本必须逐个列出失败文件和对应语义理由。脚本不应只用搜索文本来判断语法:需要调用真实 Frontend 对活跃 `.mq.md` 语料分类/解析;对于 Markdown 教程中标注的“可运行示例”,应提取到临时目录执行 `marqdo check/run/call` 并验证预期结果。 + +现有安全矩阵、Package Lock、Tool/Analysis/Trace、ABI/Foreign/Worker 回归必须并行验证;任何未能运行的目标平台明确标 `UNVERIFIED`,不能伪造 PASS。 + +## 12.3 性质测试优先于“碰巧跑通几个例子” + +建议 10 类变形测试: + +1. 同一载荷的 Strong ↔ Emph ↔ CodeSpan 替换(若 Markdown 解析出的 AST 结构满足合法要求)应使归一化 IR 等价。 +2. OrderedList ↔ BulletList 替换,在**提取载荷流相同**时不改变 Branch/Loop 类别。 +3. 在普通引用块外加一层 BlockQuote 包装,不应改变合法载荷操作类别;来源 Span 会变化。 +4. 载荷节点前后插入普通 Knowledge 段落,不改变已有语句的控制结果。 +5. 在 Exec H2 下插入 Knowledge 子节后,原执行片段已完整结束时,执行结果不改变。 +6. `@exec` → `@knowledge` 模式切换必须将所覆盖的所有载荷从执行投影中移除,不能保留副作用。 +7. 交换同级两个 Knowledge H3 不改变同一 H2 Exec 的**可执行** IR(在它们均无 exec 语句且不触及名称冲突时)。 +8. 代码跨不同容器的视觉调整保持相同 payload 顺序时,执行结果不变。 +9. 对不带任何语义版本字段的合法新语法文件,必须直接按唯一 mapper 编译;额外加入旧式版本 Front matter 字段必须产生稳定诊断。 +10. 将合法 `if...end` 刻意拆成不同标题片段,必须产生明确的 unclosed/unmatched 诊断,不可默默修复。 + +**归一化 IR 规则**:剔除源代码 span、carrier 样式、Markdown 容器元数据,而保留运算语义、控制依赖、调用顺序、布尔分支结果与返回路径。对于副作用程序还要比较 Trace 序列或 mock Host 行为;仅比较返回值不够。 + +## 12.4 进入 Release Candidate 的完整定义 + +- README Quickstart 与 `examples/` 全部原样运行;用户不必设置版本字段或 --legacy。 +- `spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md` 和相关规范只有一套当前有效的语法与行为定义。 +- `stdlib/**/*.mq.md` 全部迁移,`stdlib/stdlib.json` digest 及冻结二进制离线闭包通过;第三方依赖旧语法明确拒绝。 +- `tests/conformance/ast` 保持 Markdown 原生正确性;语义/负例/CLI 集成/安全/跨模块 fixture 全部按新语法更新,golden 更新经过语义审查。 +- 已删除旧 Strong/Emph/List/Quote 自动指令映射和按语义版本路由;相关遗留代码不再编译、不得隐藏在 `cfg(feature="legacy")` 中。 +- `docs/migration/semantic-rewrite-inventory.tsv` 全部跟踪文件分类完成,所有 active 文件的迁移工作结束,并有可复现测试证据。 +- `docs/adr/` 历史决策标明 superseded,现行文档入口不会指向旧语法作为教程。 +- Package/Capability/Memory/Resource/Tool/Analysis/Trace 正常回归;不同平台按真实测试结果汇报。 +- Changelog/Release Notes 公开说明旧源代码**不兼容**、标准库包身份变化及如何改写。 + +此处的“没有兼容性回归”只指**已承诺保持不变的计算结果、标准库公开函数功能、资源权限和安全边界**,不包括旧 `.mq.md` 源码仍可直接执行——旧语法不兼容是本次明确接受的破坏性变化。 + +--- + +# 第 13 章:可复制的完整新语法例子与预期结果 + +本章所有示例均用于**重构完成后的唯一语法 CLI**;基线仓库尚无法原样执行 `@exec`、`return`、`end` 等形式。除了特别标记外,示例只使用已存在的算术、函数及 `print` 基础能力。 + +## 13.1 示例 A:纯文档与执行函数共存 + +文件:`examples/language/01-hello.mq.md` + +````markdown +# @knowledge 学习笔记 + +普通 Markdown 可以使用**加粗**、*斜体*和 `return` 这样的文本。 + +1. 第一条说明 +2. 第二条说明 + +## @exec main + +`print("Hello from Marqdo v2")` +`return 1` + +### @knowledge 使用方法 + +这一小节并不执行。 + +| 语言标记 | 作用 | +| --- | --- | +| @exec | 标记可执行区域 | +| @knowledge | 标记普通文档区域 | +```` + +预期:`main` 输出一行 `Hello from Marqdo v2`,返回 `1`;加粗、斜体、知识表格不参与计算。 + +## 13.2 示例 B:一份完整的条件分类程序 + +文件:`examples/language/02-classify.mq.md` + +````markdown +# @exec 数值分类 + +## 分类 + +`params(n: Int)` + +`if n < 0` +`return -1` +`else` + `if n == 0` + `return 0` + `else` + `return 1` + `end` +`end` +```` + +**可实际执行的 AST 安全写法**:上例为了突出逻辑层级,在 fenced `markdown` 示例中使用了两空格缩进;实现时应将所有 Exec 载荷顶格独立成段,以避免 CommonMark 将某些连续缩进视作不同容器。官方仓库 golden **必须使用下面的完整形式**,且取代上面的人类阅读示意: + +````markdown +# @exec 数值分类 + +## 分类 + +`params(n: Int)` + +`if n < 0` + +`return -1` + +`else` + +`if n == 0` + +`return 0` + +`else` + +`return 1` + +`end` + +`end` +```` + +预期:`分类(n=-2) => -1`,`分类(n=0) => 0`,`分类(n=7) => 1`。所有 `return` 直接退出当前函数,不需要最后再写一个额外的返回表达式。 + +## 13.3 示例 C:多级标题覆盖、局部变量共享 + +文件:`examples/language/03-mode-inheritance.mq.md` + +````markdown +# @knowledge 计算说明 + +## @exec main + +`x = 5` + +### @knowledge 推导 + +这是**重点说明**,不会被执行。 + +| 表达式 | 值 | +| --- | --- | +| x + 1 | 6 | + +### @exec 实现 + +`x = x + 1` +`return x` +```` + +预期:返回 `6`,两个 Exec 片段共享当前 H2 函数的 `x`,Knowledge 片段零指令;不能把 H3 `实现` 导出为独立函数。 + +## 13.4 示例 D:写内存与语法载体等价 + +文件:`examples/language/04-memory.mq.md` + +````markdown +## @exec main + +**m = memory.new(1, 1)** + +*`m[0] = 42`* + +`return m[0]` +```` + +预期:返回 `42`。`*` 在这里承载写入语句,不是 Return。这个例子必须与等价的 `**`m[0] = 42`**` 和独立 CodeSpan `m[0] = 42` 归一化 IR 一致。 + +## 13.5 示例 E:普通引用、列表和受控计算并存 + +文件:`examples/language/05-prose-and-control.mq.md` + +````markdown +## @exec main + +下面两项是算法步骤说明,不是分支,也不是循环: + +1. 初始化计数 +2. 运行迭代 + +`n = 3` +`counter = 0` + +> 注意:这是普通 Markdown 引用,不是调用。 + +- `while counter < n` + + **counter = counter + 1** + +**end** +`return counter` +```` + +预期:返回 `3`;两个普通有序列表项和引用说明不生成语句;无序列表只提供展示结构,真正的循环由 `while/end` 决定。 + +## 13.6 示例 F:尚不存在的系统输入接口,明确不能当成运行验收 + +````markdown +--- +import: + io: "std:io" +--- + +## @exec main + +`name = io.读取一行("你的名字:")` +`io.写值(name)` +`return name` +```` + +这只是 **将来标准库补齐 stdin 之后的接口构想**。它不能作为 V2 语义重构成功的必要测试,也不能被标记为现有功能已经实现。与新语法有关的验收在本章节其他示例中完成;stdin/file API 属于单独的计算内核和标准库迭代计划。 + +--- diff --git a/docs/ci.md b/docs/ci.md index 12b89ba..de55335 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -26,6 +26,16 @@ build (depends on test): Node.js 22 is required because the optional foreign-kernel tests use ES-module syntax; Debian bookworm's Node 18 fails those tests. +> **Language-syntax migration note.** `cargo test --workspace` includes +> conformance fixtures that execute `.mq.md` source. The target language is +> [RFC-LANG-0002](architecture/RFC-LANG-0002-unified-semantics.md) while the +> Rust frontend is still being migrated, so those executable-source tests are +> **expected to be red** on a correct migration branch. Do not interpret that as +> a CI-configuration regression or "fix" it by restoring the old mapper or +> regenerating goldens; see [`STATUS.md`](STATUS.md) and +> [`migration/README.md`](migration/README.md). The pipeline definition itself +> (fmt/clippy/test/build, security lane, platform gaps) is unchanged. + ## What this pipeline does not cover - **Strict security lane**: needs a disposable VM/self-hosted runner with diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md index 310b0a9..754d04f 100644 --- a/docs/contributor-guide.md +++ b/docs/contributor-guide.md @@ -1,9 +1,19 @@ # Marqdo Contributor Guide This guide is for people changing the Marqdo CLI workspace. It assumes you have -read `AGENTS.md` (the non-negotiable architectural rules) and -`docs/DEVELOPMENT_BLUEPRINT.md` §0/§1/§11/§13/§14. Formal contracts live in -`spec/`; decisions live in `docs/adr/`. +read `AGENTS.md` (the non-negotiable architectural rules), the current language +authority [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md) +with its normative summaries `spec/mapping.md` + `spec/expression.ebnf`, and +`docs/DEVELOPMENT_BLUEPRINT.md` §0/§1/§11/§13/§14 (the language-mapping sections +there are historical and defer to the RFC). Decisions live in `docs/adr/` at +their date. + +> **Implementation state:** RFC-LANG-0002 and `spec/` are ahead of the Rust +> implementation. The frontend, expression parser and bundled stdlib still +> implement the pre-RFC mapping, so tests that execute Marqdo source are expected +> to be red until the migration lands. Status and evidence are in +> [`STATUS.md`](STATUS.md); the migration rules and inventory are in +> [`migration/README.md`](migration/README.md). ## 1. Repository map @@ -13,9 +23,11 @@ marqdo-cli/ ├── AGENTS.md operator rules for contributors/agents ├── README.md user-facing quickstart and limits ├── docs/ -│ ├── DEVELOPMENT_BLUEPRINT.md architecture baseline +│ ├── DEVELOPMENT_BLUEPRINT.md architecture baseline (language-mapping sections historical) +│ ├── architecture/RFC-LANG-0002-unified-semantics.md current language authority │ ├── STABLE_RELEASE_IMPLEMENTATION.md authoritative next-phase/release plan │ ├── STATUS.md current evidence, work packages, blockers +│ ├── migration/ syntax-migration rules + file inventory │ ├── security-gate.md G-C probe evidence (strict stays closed) │ ├── releasing.md artifact/checksum/smoke/tag procedure │ ├── CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md historical stabilization spec @@ -23,11 +35,11 @@ marqdo-cli/ │ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit │ ├── history/ archived status snapshots │ ├── contributor-guide.md this file -│ └── adr/0001..0020-*.md accepted decisions +│ └── adr/0001..0052-*.md decisions at their date (ADR-0052 = current language mapping) ├── spec/ │ ├── markdown-profile.md frozen parser profile `marqdo.md.v1` -│ ├── mapping.md AST → program roles -│ ├── expression.ebnf executable payload grammar +│ ├── mapping.md current heading-mode/payload/control-flow mapping +│ ├── expression.ebnf statement/payload grammar (keywords) │ ├── evaluation.md values, numbers, control flow, builtins │ ├── references.md imports/references/calls/ref() │ ├── value-wire.md typed wire_version 1 values @@ -46,7 +58,7 @@ marqdo-cli/ │ ├── marqdo-expression/ lexer/parser/AST for executable payloads │ ├── marqdo-markdown/ comrak profile, canonical AST, front matter │ ├── marqdo-ir/ Module/Unit/Function/Stmt IR, builtin table -│ ├── marqdo-frontend/ units, map, signature, infer, calls, resources +│ ├── marqdo-frontend/ units/modes, map, payloads, signature, infer, calls │ ├── marqdo-math/ Formula parser/evaluator (exact rationals) │ ├── marqdo-foreign/ Python/Node one-shot kernel supervisor │ ├── marqdo-sandbox/ modes + platform capability detection @@ -104,13 +116,16 @@ Rules (from blueprint §11.1, adjusted by ADR-0001): ## 3. Adding a feature or fixture (workflow) -The project uses a fixture-first workflow (blueprint §13/§14, AGENTS § -"Development workflow"). The expected sequence is: +The project uses a fixture-first workflow (RFC-LANG-0002, blueprint §13/§14, +AGENTS § "Development workflow"). The expected sequence is: -1. **Find the rule.** Identify the affected spec section and blueprint section. +1. **Find the rule.** Identify the affected section of RFC-LANG-0002 / + `spec/` (or, for architecture-only changes, the relevant blueprint section). If the change alters observable language semantics, package/lock format, ABI, authorization defaults or public CLI behavior, write/supersede an ADR - first (`docs/adr/`, template in blueprint §16.2). + first (`docs/adr/`, template in blueprint §16.2). There is one active + language mapping: do not add a second mapper, a per-file syntax selector, + `--legacy` or a parallel syntax spec. 2. **Write a failing fixture.** Add a small `.mq.md` positive and/or negative case under the right directory: * AST shape: `tests/conformance/ast/NNN-name.mq.md` + golden @@ -135,6 +150,30 @@ The project uses a fixture-first workflow (blueprint §13/§14, AGENTS § 6. **Write the tradeoff/limitations** in `docs/STATUS.md` when a P-level claim changes, and in the PR description (paths, commands run, skipped tests). +### 3.1 Syntax rules for fixtures and examples (RFC-LANG-0002) + +Every `.mq.md` fixture, example, stdlib module and documentation fence must use +the single current syntax: + +* heading modes `@exec` / `@knowledge` with ancestor inheritance; only an Exec + H2 is callable; +* `Strong`, `Emph` and inline `Code` as interchangeable one-statement payload + carriers; +* `if`/`else`/`while`/`end`/`return`/`params(...)` keywords inside the payload; +* lists, block quotes and paragraphs as inert containers (no implicit + branch/loop/call); +* no version directive, `marqdo_semantics` field or old-signature code span. + +Do not reintroduce the superseded mapping (`Strong`=execute, `Emph`=return, +ordered list=branch, bullet list=loop, block quote=call) in new fixtures. Old +shape negatives that are now valid inert Markdown must be replaced with +negatives for the `sem.*` codes in `spec/mapping.md` §8; genuine runtime +negatives keep their behavior and only change source spelling. Because the +frontend is not migrated yet, executable-source tests are expected to be red: +do not weaken assertions, delete failing tests or refresh goldens to make them +green. Record each migrated active file in +[`migration/README.md`](migration/README.md) / the migration inventory. + If a fixture reveals an implementation bug, fix the code, not the expected behavior. Negative fixtures must assert hard errors — never weaken them to warnings or prose fallbacks. @@ -157,7 +196,10 @@ fixture are both errors. Semantic goldens (`*.expected.json`): `UPDATE_SEMANTICS_GOLDENS=1` exists for authoring convenience, but never use it blindly — verify every value against the fixture source first. Invalid, inconsistent or unverified expected values defeat -the corpus. +the corpus. During the RFC-LANG-0002 migration do not regenerate goldens to make +red executable-source tests pass: the target spec is ahead of the frontend, and +a golden may only change with a stated semantic reason. See +[`STATUS.md`](STATUS.md). Negative goldens are hand-written expected code lists (exact sorted multiset for compile-time errors; warning suites; runtime suites). Do not auto-generate them. @@ -256,24 +298,26 @@ $B run examples/plugin-demo/plugin-call.mq.md \ Notes: `run` defaults to `index.mq.md` and executes `main`; `call` requires a file and function; root-only examples (for example `math.mq.md`) define no -`main`. `--mode strict` is expected to refuse to run (ADR-0004). +`main`. `--mode strict` is expected to refuse to run (ADR-0004). The examples +are being migrated to RFC-LANG-0002 syntax; until the frontend migration lands +the current CLI may not accept them, so a failing example run is not evidence +that the target syntax is already implemented. See [`STATUS.md`](STATUS.md). ## 8. Docs, ADRs and commit policy * `spec/` = normative contracts; `docs/` = architecture/decisions/status; `README.md` = user quickstart; `AGENTS.md` = contributor rules. -* `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` is the current-stage - stabilization spec (baseline `0adebe4`). It supersedes the M0.6 planning pair - on the current baseline, gap list (B-01–B-18) and the G-A/G-B/G-C release - gates. `docs/NEXT_PHASE_IMPLEMENTATION.md` and - `docs/EXTENSIBILITY_AUDIT.md` remain the M0.6 planning/evidence pair. All are - **Proposed**: the M0.6 plan supersedes the blueprint only on command-surface - scope, extension registration, plugin addressing, package identity, repository - decoupling and release gates. - Language semantics remain normative in `spec/` + Accepted ADRs + tests, and - `spec/tool-v1.md` is a candidate protocol until an ADR and implementation - tests land. Never cite these proposed documents as evidence that a feature - exists. +* Language semantics are normative only in RFC-LANG-0002 (`docs/architecture/`) + and its in-place summaries in `spec/`; the language-mapping sections of the + blueprint are historical. Do not add a second active syntax spec. + `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`, + `docs/NEXT_PHASE_IMPLEMENTATION.md` and + `docs/NEXT_RELEASE_CI_CONVERGENCE.md` are **Historical/Superseded** planning + input (their banners link the RFC); `docs/STABLE_RELEASE_IMPLEMENTATION.md` is + the authoritative next-phase/release plan. None describes implemented + behavior. `spec/tool-v1.md` is a candidate protocol until an ADR and + implementation tests land. Never cite a proposed or historical document as + evidence that a feature exists. * Changes to language semantics, AST mapping, wire format, plugin ABI, package/lock format, authorization defaults or public CLI behavior require an **Accepted ADR** (or superseding one) plus spec updates and tests. Use the @@ -282,9 +326,11 @@ file and function; root-only examples (for example `math.mq.md`) define no * ADRs are immutable once Accepted: add a new ADR with `Status: Superseded by ADR-NNNN` rather than rewriting history (typo fixes aside). -* Docs must describe what the code does. When implementation and blueprint +* Docs must describe what the code does. When implementation and spec disagree, document the implementation and flag the divergence explicitly as - a limitation/open item; never invent behavior. + a limitation/open item; never invent behavior. Right now `spec/` is ahead of + the frontend, so say that explicitly rather than claiming the new syntax + works. * Do not edit generated/vendored state, and never modify tests to hide a regression. * Commit in reviewable units with a message stating the affected spec/ADR and @@ -304,6 +350,10 @@ file and function; root-only examples (for example `math.mq.md`) define no `fs.read`), but they are **not** an OS sandbox. The strict sandbox and a package registry remain unimplemented; strict fails closed. See `docs/security-gate.md` and `spec/security.md`. +* The syntax migration is in progress in this tree: `spec/` and the docs + describe RFC-LANG-0002, while the Rust frontend and stdlib still implement + the pre-RFC mapping. Executable-source tests are expected to be red; do not + "fix" them by restoring the old mapping or by regenerating goldens. * Runtime errors resolve against their owning module (ADR-0017); do not reintroduce entry-file fallback. * The semantic corpus may pin current quirks (for example the external-link diff --git a/docs/evidence/2026-11-21-semantic-docs-migration.md b/docs/evidence/2026-11-21-semantic-docs-migration.md new file mode 100644 index 0000000..9a3aa48 --- /dev/null +++ b/docs/evidence/2026-11-21-semantic-docs-migration.md @@ -0,0 +1,86 @@ +# 2026-11-21 — RFC-LANG-0002 documentation and test-text migration + +Status: **partial evidence**. This records the repository-wide *text* migration +to the single syntax, not an implementation of the frontend. Semantic and +negative suites are expected red; see the tail of this file. + +- Repository: `cflmy/marqdo-cli` +- Worktree base: `0d8ed44` (`feat(http): parse and build HTTP/1.1 framing by bytes`), + plus uncommitted migration edits in the worktree (this evidence file is part + of those edits; no commit SHA can pin the uncommitted tree). +- The worktree also contains an **in-progress, partially applied frontend + migration** (e.g. heading-mode/Knowledge-unit plumbing) that is outside this + documentation migration. Only the commands below were observed; a later + worktree state may legitimately differ. +- Machined: Linux x86_64, Rust 1.100.0. +- Authority: [`../architecture/RFC-LANG-0002-unified-semantics.md`](../architecture/RFC-LANG-0002-unified-semantics.md), + [`../adr/0052-unified-markdown-semantics.md`](../adr/0052-unified-markdown-semantics.md). + +## What was migrated + +| Scope | Result | +|---|---| +| `spec/mapping.md`, `spec/expression.ebnf` | Replaced in place with the unified mapping/statement grammar. | +| `spec/evaluation.md`, `references.md`, `markdown-profile.md`, `security.md`, `math.md`, `foreign.md`, `package-format.md`, `plugin-abi.md`, analysis/trace notes | Updated for heading modes, payload origin, `sem.*` diagnostics, and in-place examples. | +| `README.md`, `AGENTS.md`, `COMPATIBILITY.md`, `CHANGELOG.md`, `docs/STATUS.md` | Rewritten to the current syntax with an explicit "spec ahead of implementation" state. | +| `docs/architecture/*`, `docs/migration/*`, `docs/adr/*` | New RFC/ADR/index, migration guide + inventory, historical banners on superseded decisions. | +| Active guides and planning docs | Rewritten or explicitly marked Historical/Superseded; old examples retained only as archives. | +| `examples/**` (15 `.mq.md`) | Migrated; example lock digests regenerated with the real CLI. | +| `tests/conformance/semantics/**` (73 `.mq.md`) | Migrated; expected value goldens unchanged. | +| `tests/negative/**` | 45 hard-error, 2 warning-model, 21 runtime fixtures for the new syntax/diagnostics; genuine runtime negatives retained. | +| `tests/security/run-lane.sh` | Embedded fixtures migrated. | +| Rust-embedded `.mq.md` literals in `crates/**/*.rs` | ~121 embedded programs migrated; no frontend semantics implemented. | +| `stdlib/**/*.mq.md` | **Not migrated** — tracked as pending with the frontend; `stdlib/README.md` says so. | + +Coverage and remaining items: +[`../migration/semantic-rewrite-inventory.tsv`](../migration/semantic-rewrite-inventory.tsv). + +## Commands and results + +```text +cargo fmt --all -- --check + PASS (exit 0) + +cargo check --workspace --tests --locked + PASS — Finished dev profile in 41.10s (string/fixture edits compile; + no semantic implementation was added) + +cargo test -p marqdo-cli --test conformance_ast + 4 passed, 0 failed + (the Markdown profile and 160 AST goldens are unchanged) + +cargo test -p marqdo-cli --test docs_consistency + 4 passed, 0 failed + (one overview, resolvable links in the checked set, SHA-pinned evidence) + +cargo test -p marqdo-cli --test conformance_semantics + FAILED at tests/conformance/semantics/01-constant-return.mq.md: + error[expr.parse]: invalid return expression: unexpected integer literal `1` + after expression + (the pre-RFC expression parser does not know the `return` keyword) + +cargo test -p marqdo-cli --test negative + FAILED: warning goldens expect sem.inferred_signature (not emitted by the + pre-RFC frontend); compile negatives panic/emit old diagnostics; runtime + fixtures parse as Knowledge under the pre-RFC mapper, so they "succeed" with + Unit instead of reaching their runtime errors. + +cd examples/packages-multi-version && ../../target/debug/marqdo lock + locked 2 package(s); lock file equal to the migrated expectations + (content digests verified with the real Rust file-set hash) +``` + +These failures are the expected "spec ahead of implementation" state recorded +in [`../STATUS.md`](../STATUS.md) §0, not evidence that the migrated fixtures +are invalid under the target semantics. The real closure requires implementing +RFC-LANG-0002 in `marqdo-frontend` / `marqdo-expression`, migrating +`stdlib/**/*.mq.md`, regenerating `stdlib.json`, and then re-running the full +gate. + +## Explicit non-claims + +- No new syntax is claimed executable by the current binary. +- No platform, security, ABI or protocol result is refreshed by this migration. +- No golden was regenerated to make a red suite pass. +- The `markdown.inert_executable` warning model is retired; the current + warning/error contract is `sem.*` in `spec/mapping.md` §8. diff --git a/docs/evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md b/docs/evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md index 9af5b18..5c9341c 100644 --- a/docs/evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md +++ b/docs/evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md @@ -1,5 +1,17 @@ # Marqdo CLI release candidate — 0.1.0 / `8af7262` +> **Historical evidence note (syntax).** This SHA-pinned report records the +> language mapping in effect at `8af7262`. References below to executable +> `Strong`/`Emph` payloads and to condition-header errors such as +> `markdown.invalid_construct` describe that historical mapping. Under the +> current contract +> [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) / +> [ADR-0052](../adr/0052-unified-markdown-semantics.md), +> `Strong`, `Emph` and inline `Code` are interchangeable one-statement payload +> carriers and control flow comes from `if`/`else`/`while`/`end`/`return` +> keywords, with `sem.*` diagnostics. Logs, counts, SHAs and results below are +> unchanged and remain pinned to this SHA. + ```text Source SHA: 8af72620f12e2494a59830a23abb393768b610e9 Workspace version: 0.1.0 diff --git a/docs/history/README.md b/docs/history/README.md index dc3a7e5..21829b1 100644 --- a/docs/history/README.md +++ b/docs/history/README.md @@ -1,5 +1,14 @@ # Historical snapshots +> **Historical (archived).** Everything in this directory is frozen at a past +> commit and is **not** current state. In particular, the language contract moved +> to the breaking rewrite +> [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) (see +> [ADR-0052](../adr/0052-unified-markdown-semantics.md) and +> [`spec/mapping.md`](../../spec/mapping.md)). Old-syntax examples in these +> snapshots are kept **as archives** and are not current syntax; do not copy +> them as tutorials. + This directory holds plans, reviews and status snapshots that were true at a past commit but are **not current state**. They remain for provenance and design history; do not cite them as what the tree does now. diff --git a/docs/history/STATUS-M0.5-snapshot.md b/docs/history/STATUS-M0.5-snapshot.md index e1e47a9..3ad1832 100644 --- a/docs/history/STATUS-M0.5-snapshot.md +++ b/docs/history/STATUS-M0.5-snapshot.md @@ -1,5 +1,14 @@ # Marqdo Implementation Status (M0.5) +> **Historical snapshot (2026-11-20).** This file is archived evidence of the +> M0.5 state and is **not** current status or language guidance. The language +> contract was later rewritten by +> [RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) / +> [ADR-0052](../adr/0052-unified-markdown-semantics.md) and +> [`spec/mapping.md`](../../spec/mapping.md). Any old-syntax examples or role +> wording below are preserved **as archives**, not as current syntax; see +> [`../STATUS.md`](../STATUS.md) for the current state. + Snapshot: **2026-11-20**, workspace version `0.1.0`, plugin ABI `1.0`, `wire_version` 1, Markdown profile `marqdo.md.v1`. diff --git a/docs/migration/README.md b/docs/migration/README.md new file mode 100644 index 0000000..d2871f6 --- /dev/null +++ b/docs/migration/README.md @@ -0,0 +1,177 @@ +# Semantic rewrite: migration guide and inventory + +Status: **migration in progress**. The target language contract is +[RFC-LANG-0002](../architecture/RFC-LANG-0002-unified-semantics.md) and +[`spec/mapping.md`](../../spec/mapping.md). The Rust frontend and bundled +stdlib are **not yet migrated**, so executable tests are expected to be red +until the implementation lands. See [`../STATUS.md`](../STATUS.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) + +- **Text migration: complete.** Specs, active docs, examples, all non-stdlib + test/fixture `.mq.md` files, the security-lane embedded fixtures and + Rust-embedded `.mq.md` literals were rewritten. 1009 present tracked+new files are + classified in the inventory; there are no `pending` text items. +- **Implementation: pending.** 51 inventory rows remain + `pending-implementation`: the 9 frontend/expression/IR files that implement + the mapping and the 42 stdlib fileset entries (sources + manifest). +- **Verification:** `cargo fmt --check`, `cargo check --workspace --tests`, + `conformance_ast` (4/4) and `docs_consistency` (4/4) pass. The semantic, + negative, property and CLI suites that execute Marqdo source are expected red + against the pre-RFC frontend. Evidence: + [`../evidence/2026-11-21-semantic-docs-migration.md`](../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. + +## Migration rules for this repository + +1. **One syntax.** Do not add `marqdo_semantics`, `--legacy`, `syntax: v1` or a + second example. Old syntax is either migrated or marked historical. +2. **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 阶乘`). +3. **Mode on H1.** Prefer an explicit `# @knowledge 名称` for document + namespaces and `# @exec 名称` only when the whole namespace is executable. +4. **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. +5. **Control flow.** `if ` … `[else]` … `end`; `while ` … `end`. + A control block never crosses a heading. `return ` replaces the old + italic return. +6. **Branch migration.** An ordered list with N arms is *first true arm wins*. + Convert N arms to a nested if/else chain (an inner `if` inside `else`), not + to N independent `if`s. A single arm becomes `if`. A bullet list is a + sequence of independent `while` loops, one per item, in item order. +7. **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. +8. **Signatures.** The first standalone code span `(n: Int)` becomes + `params(n: Int)` as the first direct payload of the Exec H2. Keep parameter + names, order and defaults. +9. **Knowledge.** Purely visual emphasis and explanatory lists belong in + `@knowledge` sections. A `Strong` inside an Exec section is a payload and + must be a valid statement. +10. **Preserve meaning.** Do not change function names, argument names/defaults, + evaluation order, early-return behavior, values, stdout or expected error + intent. For `.expected.json` value goldens (return value/args/stdout), keep + the file unless the semantic name really changed. +11. **Expected diagnostics.** Old shape errors about lists/quotes/emphasis + become valid inert Markdown, not errors. Replace them with new negatives for + `sem.*` codes (see `spec/mapping.md` §8). Keep genuine runtime negatives + (bounds, type, permission) and only migrate their source spelling. +12. **No silent golden regeneration.** Do not run `UPDATE_*_GOLDENS=1` to mask + a semantic change. A golden update needs a stated new-semantic reason. +13. **Tests are text-only here.** Rust test strings and the `init` template + text are migrated; the frontend, expression parser and stdlib `.mq.md` + sources are not. Those implementation items are tracked as pending in the + inventory. Do not change protocol schemas or security logic in this + migration. +14. **Use the review aids, not them as proof.** `tools/dev-only/check-mq-syntax.py` + catches unbalanced control blocks and unknown `sem.*` codes; + `tools/dev-only/gen-migration-inventory.py` regenerates the inventory. Both + are audit aids; the real gate is the migrated frontend plus the RFC §12 + acceptance matrix. + +## Conversion examples + +Old: + +```markdown +## 分类 + +1. `n < 0` + + *-1* + +2. `n == 0` + + *0* + +3. `n > 0` + + *1* +``` + +New (first-true chain, explicit `end`): + +```markdown +## @exec 分类 + +`if n < 0` + +`return -1` + +`else` + +`if n == 0` + +`return 0` + +`else` + +`return 1` + +`end` + +`end` +``` + +Old loop: + +```markdown +## 求和 + +`(n: Int)` + +**i = 0** +**sum = 0** + +- `i < n` + + **sum = sum + i** + **i = i + 1** + +*sum* +``` + +New: + +```markdown +## @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: + +```text +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. diff --git a/docs/migration/semantic-rewrite-inventory.tsv b/docs/migration/semantic-rewrite-inventory.tsv new file mode 100644 index 0000000..612c2cc --- /dev/null +++ b/docs/migration/semantic-rewrite-inventory.tsv @@ -0,0 +1,1010 @@ +path category active old_semantics action owner verification status +.gitattributes non-semantic no none none - n/a reviewed +.github/workflows/ci.yml non-semantic no none none - n/a reviewed +.github/workflows/security-linux.yml non-semantic no none none - n/a reviewed +.gitignore non-semantic no none none - n/a reviewed +.woodpecker.yml non-semantic no none none - n/a reviewed +AGENTS.md tutorial yes old mapping rewrite docs review migrated +CHANGELOG.md tutorial yes old mapping rewrite docs review migrated +COMPATIBILITY.md tutorial yes old mapping rewrite docs review migrated +Cargo.lock non-semantic no none none - n/a reviewed +Cargo.toml non-semantic no none none - n/a reviewed +LICENSE-APACHE non-semantic no none none - n/a reviewed +LICENSE-MIT non-semantic no none none - n/a reviewed +README.md tutorial yes old mapping rewrite docs review migrated +crates/cli/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/analysis.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/cli/src/args.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands/check.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands/init.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/cli/src/commands/inspect.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands/package.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands/run.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands/sandbox.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/commands/tool.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/loader.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/main.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/cli/src/output.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/stdlib.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/cli/src/tool.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/src/trace.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/cli/tests/analysis_trace.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/architecture_boundaries.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/conformance_ast.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/conformance_semantics.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/docs_consistency.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/examples_r6.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/http_over_tcp.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/integration_cli.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/negative.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/p2_closure.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/package_env.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/plugin_worker.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/print_routing.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/properties.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/resource_streams.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/stdlib_bundle.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/cli/tests/stdlib_http.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/stdlib_product.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/stdlib_table.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/cli/tests/tool_protocol.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-expression/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-expression/src/ast.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-expression/src/lexer.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-expression/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-expression/src/parser.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-foreign/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-foreign/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-foreign/tests/kernels.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-foreign/tests/provider.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-frontend/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-frontend/src/analyze.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-frontend/src/calls.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-frontend/src/infer.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-frontend/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-frontend/src/map.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-frontend/src/payload.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-frontend/src/resources.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/marqdo-frontend/src/signature.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-frontend/src/units.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-host/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/include/marqdo_resource_provider.h rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/budget.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/capability.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/context.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/fs.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/handles.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/host.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/host/dispatch.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/host/effects.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/host/providers.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/host/resource_ops.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/kernels.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/plugin_worker.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/process.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/provider_c.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/provider_worker.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/resource.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/src/trace.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-host/tests/c_provider.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-host/tests/capability_broker.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-host/tests/plugin_exports.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-host/tests/resource_streams.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-host/tests/worker_provider.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-ir/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-ir/src/builtins.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-ir/src/callable.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-ir/src/lib.rs rust-source yes old mapping implement RFC-LANG-0002 language cargo test pending-implementation +crates/marqdo-markdown/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-markdown/src/ast.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-markdown/src/frontmatter.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-markdown/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-markdown/src/profile.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-markdown/src/text.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/src/ast.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/src/error.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/src/eval.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/src/parse.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-math/tests/kernel.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-package/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-package/src/fileset.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/marqdo-package/src/lib.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/marqdo-plugin-abi/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/abi.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/artifact.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/error.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/loader.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/manifest.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/wire.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/src/worker.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-abi/tests/loader_unix.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-plugin-sdk/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-sdk/src/bytes.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-sdk/src/call.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-sdk/src/entry.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-sdk/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-plugin-sdk/src/tests.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-plugin-sdk/src/wire.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-provider-worker/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-provider-worker/src/main.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-provider-worker/tests/worker_binding.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-runtime/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-runtime/src/builtins_impl.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-runtime/src/interpreter.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-runtime/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-runtime/src/memory.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-runtime/src/value_ops.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-runtime/tests/interpreter.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test migrated +crates/marqdo-sandbox/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-sandbox/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-sandbox/src/linux.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-sandbox/tests/security_linux.rs rust-test yes embedded old syntax migrate embedded .mq.md strings language cargo test reviewed +crates/marqdo-span/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-span/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-value/Cargo.toml rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-value/src/diagnostic.rs rust-source yes embedded text/help migrate embedded .mq.md text only language cargo test migrated +crates/marqdo-value/src/error.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-value/src/lib.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-value/src/value.rs rust-source yes not syntax-bearing review language cargo test reviewed +crates/marqdo-value/src/wire.rs rust-source yes not syntax-bearing review language cargo test reviewed +docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/DEVELOPMENT_BLUEPRINT.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/EXTENSIBILITY_AUDIT.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md architecture yes compute RFC migrate examples / mark historical spelling docs review migrated +docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md architecture yes compute RFC migrate examples / mark historical spelling docs review migrated +docs/NEXT_PHASE_IMPLEMENTATION.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/NEXT_RELEASE_CI_CONVERGENCE.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/STABLE_RELEASE_IMPLEMENTATION.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/STATUS.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/adr/0001-crate-graph-and-span-foundation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0002-executables-only-in-function-bodies.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0003-ref-resolution-and-ambiguity.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0004-strict-mode-refuses-without-isolation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0005-ast-normalization.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0006-cli-contract.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0007-arbitrary-precision-int-and-wire.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0008-package-instance-identity-and-source-resolution.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0009-unified-callable-resolution.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0010-plugin-export-registration.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0011-capability-broker.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0012-external-kernel-provider.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0013-generic-cli-tool-protocol.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0014-host-plugin-handle-authority.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0015-public-analysis-trace-v1.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0016-lock-v3-graph-and-package-file-set.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0017-runtime-error-source-locations.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0018-worker-capability-bridge.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0019-strict-mode-availability-gate.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0020-foreign-environment-binding.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0021-linux-strict-isolation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0022-addressable-memory-and-place-assignment.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0023-minimal-structure-observation-and-construction.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0024-recoverable-result-convention.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0025-minimal-resource-stream-abi.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0026-buffered-project-file-write-streams.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0027-print-migration-compat-a.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0028-bundled-stdlib-and-std-imports.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0029-full-value-formatting-and-handle-observation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0030-print-compat-b-routing.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0031-print-compat-c-remove-host-formatting.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0032-table-logical-value-and-stdlib-algorithms.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0033-in-process-resource-provider-v1.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0034-tcp-resource-endpoint.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0035-worker-resource-provider-transport.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0036-c-abi-resource-provider.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0037-provider-package-manifest.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0038-c-abi-provider-worker-binding.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0039-stdlib-extraction-intent.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0040-stdio-stdin-stderr-and-stdlib-streams.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0041-resource-operation-fs.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0042-clock-resource-operation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0043-env-resource-operation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0044-process-resource-operation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0045-fs-append-read-at-walk.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0046-random-resource-operation.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0047-net-dns-udp-listener.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0048-tls-resource-endpoint.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0049-compression-resource-operations.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0050-host-regex-extension.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0051-byte-exact-http-framing.md historical no decision at its date banner if syntax-role docs review historical +docs/adr/0052-unified-markdown-semantics.md decision yes old mapping adopt current language decision docs review migrated +docs/adr/README.md decision yes n/a index current decisions/history docs review migrated +docs/architecture/CURRENT.md architecture yes status/index update to RFC-LANG-0002 docs docs_consistency migrated +docs/architecture/Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md architecture no review input historical banner docs review historical +docs/architecture/README.md architecture yes status/index update to RFC-LANG-0002 docs docs_consistency migrated +docs/architecture/RFC-LANG-0002-unified-semantics.md architecture yes old mapping adopt as sole authority docs review migrated +docs/ci.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/contributor-guide.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/development-credentials.md tutorial yes none reviewed docs review reviewed +docs/evidence/2026-11-20-bundled-stdlib-cm-a10.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-c-provider.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-c-worker-binding.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-full-value-formatting.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-http-over-tcp.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-http-parser.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-local-gate.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-memory-p1.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-memory-p2-closure.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-p2-closure-gate.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-p6-profile.json historical no archived banner only docs review historical +docs/evidence/2026-11-20-p6-profile.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-print-compat-b.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-print-compat-c.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-provider-abi-cm-a09.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-provider-package.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-resource-file-write-p3.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-resource-stream-p3.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-result-and-free-list-p2.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-rfc-cm-completion-audit.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-stdlib-package.json historical no archived banner only docs review historical +docs/evidence/2026-11-20-stdlib-package.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-stdlib-print-compat-a.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-strict-gc-8af7262.log historical no archived banner only docs review historical +docs/evidence/2026-11-20-strict-gc-8af7262.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-strict-gc.log historical no archived banner only docs review historical +docs/evidence/2026-11-20-strict-gc.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-strict-resource-cm-a11.log historical no archived banner only docs review historical +docs/evidence/2026-11-20-strict-resource-cm-a11.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-structure-api-p2.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-table-cm-a08.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-table-cross-storage.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-tcp-endpoint.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-worker-provider.md historical no archived banner only docs review historical +docs/evidence/2026-11-20-workspace-tests-8af7262.log historical no archived banner only docs review historical +docs/evidence/2026-11-21-compress-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-datetime-clock-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-docs-and-test-migration.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-env-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-fs-extended.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-fs-file-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-http-bytes.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-json-csv-multi.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-json-csv-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-module-split.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-net-endpoints.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-path-regex-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-process-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-random-product.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-regex-extension.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-resource-operation.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-semantic-docs-migration.md evidence yes old syntax record migration evidence docs docs_consistency migrated +docs/evidence/2026-11-21-stdio-streams.md historical no archived banner only docs review historical +docs/evidence/2026-11-21-tls-endpoint.md historical no archived banner only docs review historical +docs/evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md historical no archived banner only docs review historical +docs/history/README.md historical no archived banner only docs review historical +docs/history/STATUS-M0.5-snapshot.md historical no archived banner only docs review historical +docs/migration/README.md migration yes n/a maintain inventory/guide docs review migrated +docs/migration/semantic-rewrite-inventory.tsv migration yes n/a maintain inventory/guide docs review migrated +docs/releasing.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/security-gate.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +docs/security-vm.md tutorial yes old mapping rewrite + historical banner where needed docs docs_consistency migrated +examples/factorial.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/hello.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/kernel-mock/README.md example yes old syntax review examples run reviewed +examples/kernel-mock/demo.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/kernel-mock/kernel.json example yes old syntax review examples run reviewed +examples/kernel-mock/mocklang example yes old syntax review examples run reviewed +examples/math.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/memory-buffer.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/multi-module/geometry.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/multi-module/index.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/multi-module/marqdo.lock example yes old syntax review examples run reviewed +examples/multi-module/marqdo.yaml example yes old syntax review examples run reviewed +examples/packages-multi-version/README.md example yes old syntax review examples run reviewed +examples/packages-multi-version/index.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/packages-multi-version/marqdo.lock example yes old syntax review examples run reviewed +examples/packages-multi-version/marqdo.yaml example yes old syntax review examples run reviewed +examples/packages-multi-version/packages/geometry-v1/index.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/packages-multi-version/packages/geometry-v1/marqdo.yaml example yes old syntax review examples run reviewed +examples/packages-multi-version/packages/geometry-v2/index.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/packages-multi-version/packages/geometry-v2/marqdo.yaml example yes old syntax review examples run reviewed +examples/plugin-demo/README.md example yes old syntax review examples run reviewed +examples/plugin-demo/build.sh example yes old syntax review examples run reviewed +examples/plugin-demo/plugin-call.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/plugin-demo/plugin.yaml example yes old syntax review examples run reviewed +examples/plugin-demo/solver.c example yes old syntax review examples run reviewed +examples/plugin-multi-export/README.md example yes old syntax review examples run reviewed +examples/plugin-multi-export/build.sh example yes old syntax review examples run reviewed +examples/plugin-multi-export/plugin-call.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/plugin-multi-export/plugin.yaml example yes old syntax review examples run reviewed +examples/python-foreign.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/references.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/stdlib-bundle.mq.md example yes old syntax migrate source examples examples_r6 / run migrated +examples/tool-samples/sample-knowledge/README.md example yes old syntax review examples run reviewed +examples/tool-samples/sample-knowledge/src/main.rs example yes old syntax review examples run reviewed +examples/tool-samples/sample-knowledge/tool.json example yes old syntax review examples run reviewed +examples/tool-samples/sample-proof/README.md example yes old syntax review examples run reviewed +examples/tool-samples/sample-proof/src/main.rs example yes old syntax review examples run reviewed +examples/tool-samples/sample-proof/tool.json example yes old syntax review examples run reviewed +examples/tool-samples/sample-view/README.md example yes old syntax review examples run reviewed +examples/tool-samples/sample-view/src/main.rs example yes old syntax review examples run reviewed +examples/tool-samples/sample-view/tool.json example yes old syntax review examples run reviewed +examples/tool-unknown-name/README.md example yes old syntax review examples run reviewed +examples/tool-unknown-name/bin/marqdo-benchmark example yes old syntax review examples run reviewed +examples/tool-unknown-name/tool.json example yes old syntax review examples run reviewed +include/marqdo_plugin_abi_v1.h non-semantic no none none - n/a reviewed +rustfmt.toml non-semantic no none none - n/a reviewed +spec/analysis-v1.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/analysis-v2.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/evaluation.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/expression.ebnf spec yes old mapping in-place rewrite language cargo test / review migrated +spec/foreign.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/mapping.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/markdown-profile.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/math.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/package-format.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/plugin-abi.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/references.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/schemas/analysis-v1.schema.json spec yes old mapping in-place rewrite language cargo test / review migrated +spec/schemas/analysis-v2.schema.json spec yes old mapping in-place rewrite language cargo test / review migrated +spec/schemas/tool-v1.schema.json spec yes old mapping in-place rewrite language cargo test / review migrated +spec/schemas/trace-v1.schema.json spec yes old mapping in-place rewrite language cargo test / review migrated +spec/schemas/trace-v2.schema.json spec yes old mapping in-place rewrite language cargo test / review migrated +spec/security.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/tool-v1.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/trace-v1.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/trace-v2.md spec yes old mapping in-place rewrite language cargo test / review migrated +spec/value-wire.md spec yes old mapping in-place rewrite language cargo test / review migrated +stdlib/README.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/clock.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/compress.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/data/csv.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/data/json.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/data/table.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/datetime.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/demo.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/env.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/format.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/fs/file.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/io.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/io/console.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/io/stream.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/net/http.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/path.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/process.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/random.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/regex.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/stdlib.json stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/clock.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/compress.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/console.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/csv.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/datetime.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/demo.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/env.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/format.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/fs.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/http.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/io.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/json.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/path.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/process.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/random.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/regex.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/stream.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/table.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/text.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/tests/utf8.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/text.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +stdlib/text/utf8.mq.md stdlib yes old syntax migrate with frontend + digest stdlib stdlib_product pending-implementation +tests/README.md test yes old syntax migrate source/expectations tests negative/properties migrated +tests/abi/capability_plugin.c test yes harness review tests review reviewed +tests/architecture/README.md test yes harness review tests review reviewed +tests/conformance/ast/001-atx-h1.ast.json test yes harness review tests review reviewed +tests/conformance/ast/001-atx-h1.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/002-atx-h2.ast.json test yes harness review tests review reviewed +tests/conformance/ast/002-atx-h2.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/003-atx-h3.ast.json test yes harness review tests review reviewed +tests/conformance/ast/003-atx-h3.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/004-atx-h4.ast.json test yes harness review tests review reviewed +tests/conformance/ast/004-atx-h4.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/005-atx-h5.ast.json test yes harness review tests review reviewed +tests/conformance/ast/005-atx-h5.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/006-atx-h6.ast.json test yes harness review tests review reviewed +tests/conformance/ast/006-atx-h6.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/007-atx-closing-hashes.ast.json test yes harness review tests review reviewed +tests/conformance/ast/007-atx-closing-hashes.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/008-setext-level1.ast.json test yes harness review tests review reviewed +tests/conformance/ast/008-setext-level1.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/009-setext-level2.ast.json test yes harness review tests review reviewed +tests/conformance/ast/009-setext-level2.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/010-unicode-chinese-heading.ast.json test yes harness review tests review reviewed +tests/conformance/ast/010-unicode-chinese-heading.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/011-heading-cjk-emoji.ast.json test yes harness review tests review reviewed +tests/conformance/ast/011-heading-cjk-emoji.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/012-heading-empty.ast.json test yes harness review tests review reviewed +tests/conformance/ast/012-heading-empty.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/013-heading-inline-markup.ast.json test yes harness review tests review reviewed +tests/conformance/ast/013-heading-inline-markup.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/014-heading-in-blockquote.ast.json test yes harness review tests review reviewed +tests/conformance/ast/014-heading-in-blockquote.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/015-heading-in-list-item.ast.json test yes harness review tests review reviewed +tests/conformance/ast/015-heading-in-list-item.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/016-heading-in-fenced-code.ast.json test yes harness review tests review reviewed +tests/conformance/ast/016-heading-in-fenced-code.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/017-heading-whitespace-normalised.ast.json test yes harness review tests review reviewed +tests/conformance/ast/017-heading-whitespace-normalised.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/018-heading-level-jump.ast.json test yes harness review tests review reviewed +tests/conformance/ast/018-heading-level-jump.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/019-paragraph-single.ast.json test yes harness review tests review reviewed +tests/conformance/ast/019-paragraph-single.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/020-paragraph-multiline-softbreak.ast.json test yes harness review tests review reviewed +tests/conformance/ast/020-paragraph-multiline-softbreak.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/021-hard-break-two-spaces.ast.json test yes harness review tests review reviewed +tests/conformance/ast/021-hard-break-two-spaces.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/022-hard-break-backslash.ast.json test yes harness review tests review reviewed +tests/conformance/ast/022-hard-break-backslash.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/023-empty-document.ast.json test yes harness review tests review reviewed +tests/conformance/ast/023-empty-document.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/024-whitespace-only-document.ast.json test yes harness review tests review reviewed +tests/conformance/ast/024-whitespace-only-document.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/025-bom-document.ast.json test yes harness review tests review reviewed +tests/conformance/ast/025-bom-document.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/026-mixed-paragraph-blocks.ast.json test yes harness review tests review reviewed +tests/conformance/ast/026-mixed-paragraph-blocks.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/027-strong-asterisk.ast.json test yes harness review tests review reviewed +tests/conformance/ast/027-strong-asterisk.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/028-strong-underscore.ast.json test yes harness review tests review reviewed +tests/conformance/ast/028-strong-underscore.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/029-emph-asterisk.ast.json test yes harness review tests review reviewed +tests/conformance/ast/029-emph-asterisk.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/030-emph-underscore.ast.json test yes harness review tests review reviewed +tests/conformance/ast/030-emph-underscore.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/031-strong-emph-nested.ast.json test yes harness review tests review reviewed +tests/conformance/ast/031-strong-emph-nested.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/032-emph-in-strong.ast.json test yes harness review tests review reviewed +tests/conformance/ast/032-emph-in-strong.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/033-strong-in-emph.ast.json test yes harness review tests review reviewed +tests/conformance/ast/033-strong-in-emph.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/034-intraword-underscore.ast.json test yes harness review tests review reviewed +tests/conformance/ast/034-intraword-underscore.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/035-multiline-emphasis.ast.json test yes harness review tests review reviewed +tests/conformance/ast/035-multiline-emphasis.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/036-emphasis-with-punctuation.ast.json test yes harness review tests review reviewed +tests/conformance/ast/036-emphasis-with-punctuation.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/037-strong-with-code-span.ast.json test yes harness review tests review reviewed +tests/conformance/ast/037-strong-with-code-span.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/038-emph-with-code-span.ast.json test yes harness review tests review reviewed +tests/conformance/ast/038-emph-with-code-span.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/039-code-single-tick.ast.json test yes harness review tests review reviewed +tests/conformance/ast/039-code-single-tick.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/040-code-double-tick.ast.json test yes harness review tests review reviewed +tests/conformance/ast/040-code-double-tick.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/041-code-triple-tick.ast.json test yes harness review tests review reviewed +tests/conformance/ast/041-code-triple-tick.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/042-code-with-spaces.ast.json test yes harness review tests review reviewed +tests/conformance/ast/042-code-with-spaces.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/043-code-empty.ast.json test yes harness review tests review reviewed +tests/conformance/ast/043-code-empty.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/044-code-with-special-chars.ast.json test yes harness review tests review reviewed +tests/conformance/ast/044-code-with-special-chars.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/045-code-multiline-payload.ast.json test yes harness review tests review reviewed +tests/conformance/ast/045-code-multiline-payload.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/046-fenced-no-language.ast.json test yes harness review tests review reviewed +tests/conformance/ast/046-fenced-no-language.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/047-fenced-with-language.ast.json test yes harness review tests review reviewed +tests/conformance/ast/047-fenced-with-language.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/048-fenced-info-multiword.ast.json test yes harness review tests review reviewed +tests/conformance/ast/048-fenced-info-multiword.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/049-fenced-tilde.ast.json test yes harness review tests review reviewed +tests/conformance/ast/049-fenced-tilde.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/050-indented-code.ast.json test yes harness review tests review reviewed +tests/conformance/ast/050-indented-code.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/051-fenced-unclosed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/051-fenced-unclosed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/052-fenced-with-tabs.ast.json test yes harness review tests review reviewed +tests/conformance/ast/052-fenced-with-tabs.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/053-indented-code-after-paragraph.ast.json test yes harness review tests review reviewed +tests/conformance/ast/053-indented-code-after-paragraph.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/054-fenced-in-list.ast.json test yes harness review tests review reviewed +tests/conformance/ast/054-fenced-in-list.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/055-inline-math.ast.json test yes harness review tests review reviewed +tests/conformance/ast/055-inline-math.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/056-inline-display-math.ast.json test yes harness review tests review reviewed +tests/conformance/ast/056-inline-display-math.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/057-block-math.ast.json test yes harness review tests review reviewed +tests/conformance/ast/057-block-math.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/058-block-math-fraction.ast.json test yes harness review tests review reviewed +tests/conformance/ast/058-block-math-fraction.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/059-math-unclosed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/059-math-unclosed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/060-math-escaped-dollar.ast.json test yes harness review tests review reviewed +tests/conformance/ast/060-math-escaped-dollar.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/061-math-in-paragraph-mixed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/061-math-in-paragraph-mixed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/062-table-basic.ast.json test yes harness review tests review reviewed +tests/conformance/ast/062-table-basic.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/063-table-alignments.ast.json test yes harness review tests review reviewed +tests/conformance/ast/063-table-alignments.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/064-table-escaped-pipe.ast.json test yes harness review tests review reviewed +tests/conformance/ast/064-table-escaped-pipe.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/065-table-missing-cells.ast.json test yes harness review tests review reviewed +tests/conformance/ast/065-table-missing-cells.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/066-table-inline-markup.ast.json test yes harness review tests review reviewed +tests/conformance/ast/066-table-inline-markup.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/067-table-no-leading-pipes.ast.json test yes harness review tests review reviewed +tests/conformance/ast/067-table-no-leading-pipes.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/068-table-empty-cells.ast.json test yes harness review tests review reviewed +tests/conformance/ast/068-table-empty-cells.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/069-bullet-dash.ast.json test yes harness review tests review reviewed +tests/conformance/ast/069-bullet-dash.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/070-bullet-markers-mixed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/070-bullet-markers-mixed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/071-bullet-nested.ast.json test yes harness review tests review reviewed +tests/conformance/ast/071-bullet-nested.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/072-ordered-start-3.ast.json test yes harness review tests review reviewed +tests/conformance/ast/072-ordered-start-3.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/073-ordered-paren-delimiter.ast.json test yes harness review tests review reviewed +tests/conformance/ast/073-ordered-paren-delimiter.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/074-ordered-nested.ast.json test yes harness review tests review reviewed +tests/conformance/ast/074-ordered-nested.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/075-list-tight.ast.json test yes harness review tests review reviewed +tests/conformance/ast/075-list-tight.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/076-list-loose.ast.json test yes harness review tests review reviewed +tests/conformance/ast/076-list-loose.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/077-task-list.ast.json test yes harness review tests review reviewed +tests/conformance/ast/077-task-list.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/078-list-item-multiple-paragraphs.ast.json test yes harness review tests review reviewed +tests/conformance/ast/078-list-item-multiple-paragraphs.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/079-list-item-with-blockquote.ast.json test yes harness review tests review reviewed +tests/conformance/ast/079-list-item-with-blockquote.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/080-list-item-with-fence.ast.json test yes harness review tests review reviewed +tests/conformance/ast/080-list-item-with-fence.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/081-list-item-multiline.ast.json test yes harness review tests review reviewed +tests/conformance/ast/081-list-item-multiline.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/082-ordered-item-branch-shape.ast.json test yes harness review tests review reviewed +tests/conformance/ast/082-ordered-item-branch-shape.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/083-bullet-item-loop-shape.ast.json test yes harness review tests review reviewed +tests/conformance/ast/083-bullet-item-loop-shape.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/084-quote-single-paragraph.ast.json test yes harness review tests review reviewed +tests/conformance/ast/084-quote-single-paragraph.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/085-quote-nested.ast.json test yes harness review tests review reviewed +tests/conformance/ast/085-quote-nested.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/086-quote-multiple-paragraphs.ast.json test yes harness review tests review reviewed +tests/conformance/ast/086-quote-multiple-paragraphs.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/087-quote-with-code.ast.json test yes harness review tests review reviewed +tests/conformance/ast/087-quote-with-code.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/088-quote-with-list.ast.json test yes harness review tests review reviewed +tests/conformance/ast/088-quote-with-list.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/089-quote-call-shape.ast.json test yes harness review tests review reviewed +tests/conformance/ast/089-quote-call-shape.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/090-quote-lazy-continuation.ast.json test yes harness review tests review reviewed +tests/conformance/ast/090-quote-lazy-continuation.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/091-link-inline.ast.json test yes harness review tests review reviewed +tests/conformance/ast/091-link-inline.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/092-link-with-title.ast.json test yes harness review tests review reviewed +tests/conformance/ast/092-link-with-title.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/093-reference-link.ast.json test yes harness review tests review reviewed +tests/conformance/ast/093-reference-link.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/094-reference-link-collapsed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/094-reference-link-collapsed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/095-reference-link-shortcut.ast.json test yes harness review tests review reviewed +tests/conformance/ast/095-reference-link-shortcut.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/096-image-basic.ast.json test yes harness review tests review reviewed +tests/conformance/ast/096-image-basic.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/097-image-with-title.ast.json test yes harness review tests review reviewed +tests/conformance/ast/097-image-with-title.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/098-link-with-emphasis.ast.json test yes harness review tests review reviewed +tests/conformance/ast/098-link-with-emphasis.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/099-link-in-strong.ast.json test yes harness review tests review reviewed +tests/conformance/ast/099-link-in-strong.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/100-autolinks-disabled-behaviour.ast.json test yes harness review tests review reviewed +tests/conformance/ast/100-autolinks-disabled-behaviour.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/101-link-with-fragment.ast.json test yes harness review tests review reviewed +tests/conformance/ast/101-link-with-fragment.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/102-inline-html.ast.json test yes harness review tests review reviewed +tests/conformance/ast/102-inline-html.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/103-block-html.ast.json test yes harness review tests review reviewed +tests/conformance/ast/103-block-html.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/104-html-comment.ast.json test yes harness review tests review reviewed +tests/conformance/ast/104-html-comment.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/105-html-script-block.ast.json test yes harness review tests review reviewed +tests/conformance/ast/105-html-script-block.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/106-html-inline-break.ast.json test yes harness review tests review reviewed +tests/conformance/ast/106-html-inline-break.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/107-thematic-break-dashes.ast.json test yes harness review tests review reviewed +tests/conformance/ast/107-thematic-break-dashes.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/108-thematic-break-stars.ast.json test yes harness review tests review reviewed +tests/conformance/ast/108-thematic-break-stars.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/109-thematic-break-underscores.ast.json test yes harness review tests review reviewed +tests/conformance/ast/109-thematic-break-underscores.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/110-thematic-break-between-paragraphs.ast.json test yes harness review tests review reviewed +tests/conformance/ast/110-thematic-break-between-paragraphs.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/111-frontmatter-valid.ast.json test yes harness review tests review reviewed +tests/conformance/ast/111-frontmatter-valid.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/112-frontmatter-empty.ast.json test yes harness review tests review reviewed +tests/conformance/ast/112-frontmatter-empty.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/113-frontmatter-imports.ast.json test yes harness review tests review reviewed +tests/conformance/ast/113-frontmatter-imports.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/114-frontmatter-later-is-thematic-break.ast.json test yes harness review tests review reviewed +tests/conformance/ast/114-frontmatter-later-is-thematic-break.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/115-frontmatter-invalid-yaml.ast.json test yes harness review tests review reviewed +tests/conformance/ast/115-frontmatter-invalid-yaml.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/116-frontmatter-with-bom.ast.json test yes harness review tests review reviewed +tests/conformance/ast/116-frontmatter-with-bom.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/117-entities-named.ast.json test yes harness review tests review reviewed +tests/conformance/ast/117-entities-named.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/118-entities-numeric.ast.json test yes harness review tests review reviewed +tests/conformance/ast/118-entities-numeric.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/119-backslash-escapes.ast.json test yes harness review tests review reviewed +tests/conformance/ast/119-backslash-escapes.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/120-escaped-pipe-in-table.ast.json test yes harness review tests review reviewed +tests/conformance/ast/120-escaped-pipe-in-table.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/121-cjk-paragraph.ast.json test yes harness review tests review reviewed +tests/conformance/ast/121-cjk-paragraph.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/122-emoji-text.ast.json test yes harness review tests review reviewed +tests/conformance/ast/122-emoji-text.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/123-cjk-emphasis.ast.json test yes harness review tests review reviewed +tests/conformance/ast/123-cjk-emphasis.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/124-mixed-scripts.ast.json test yes harness review tests review reviewed +tests/conformance/ast/124-mixed-scripts.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/125-prose-with-executable.ast.json test yes harness review tests review reviewed +tests/conformance/ast/125-prose-with-executable.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/126-prose-and-control-flow.ast.json test yes harness review tests review reviewed +tests/conformance/ast/126-prose-and-control-flow.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/127-invalid-strong-nested-markup.ast.json test yes harness review tests review reviewed +tests/conformance/ast/127-invalid-strong-nested-markup.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/128-invalid-emph-nested-markup.ast.json test yes harness review tests review reviewed +tests/conformance/ast/128-invalid-emph-nested-markup.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/129-invalid-list-no-condition.ast.json test yes harness review tests review reviewed +tests/conformance/ast/129-invalid-list-no-condition.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/130-invalid-quote-not-call.ast.json test yes harness review tests review reviewed +tests/conformance/ast/130-invalid-quote-not-call.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/131-invalid-empty-payloads.ast.json test yes harness review tests review reviewed +tests/conformance/ast/131-invalid-empty-payloads.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/132-inert-executable-outside-function.ast.json test yes harness review tests review reviewed +tests/conformance/ast/132-inert-executable-outside-function.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/133-strikethrough.ast.json test yes harness review tests review reviewed +tests/conformance/ast/133-strikethrough.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/134-strikethrough-with-strong.ast.json test yes harness review tests review reviewed +tests/conformance/ast/134-strikethrough-with-strong.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/135-tight-vs-loose-equivalence.ast.json test yes harness review tests review reviewed +tests/conformance/ast/135-tight-vs-loose-equivalence.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/136-nested-container-blocks.ast.json test yes harness review tests review reviewed +tests/conformance/ast/136-nested-container-blocks.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/137-multiple-levels-document.ast.json test yes harness review tests review reviewed +tests/conformance/ast/137-multiple-levels-document.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/138-footnotes-disabled.ast.json test yes harness review tests review reviewed +tests/conformance/ast/138-footnotes-disabled.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/139-code-fence-info-attributes.ast.json test yes harness review tests review reviewed +tests/conformance/ast/139-code-fence-info-attributes.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/140-table-and-list-mixed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/140-table-and-list-mixed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/141-html-block-in-list.ast.json test yes harness review tests review reviewed +tests/conformance/ast/141-html-block-in-list.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/142-math-and-code-mixed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/142-math-and-code-mixed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/143-heading-setext-with-emphasis.ast.json test yes harness review tests review reviewed +tests/conformance/ast/143-heading-setext-with-emphasis.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/144-multi-byte-span-check.ast.json test yes harness review tests review reviewed +tests/conformance/ast/144-multi-byte-span-check.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/145-frontmatter-then-heading.ast.json test yes harness review tests review reviewed +tests/conformance/ast/145-frontmatter-then-heading.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/146-crlf-line-endings.ast.json test yes harness review tests review reviewed +tests/conformance/ast/146-crlf-line-endings.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/147-tab-indented-list.ast.json test yes harness review tests review reviewed +tests/conformance/ast/147-tab-indented-list.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/148-blockquote-heading-mixed.ast.json test yes harness review tests review reviewed +tests/conformance/ast/148-blockquote-heading-mixed.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/149-table-with-header-only.ast.json test yes harness review tests review reviewed +tests/conformance/ast/149-table-with-header-only.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/150-document-only-frontmatter.ast.json test yes harness review tests review reviewed +tests/conformance/ast/150-document-only-frontmatter.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/151-power-strong-codespan.ast.json test yes harness review tests review reviewed +tests/conformance/ast/151-power-strong-codespan.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/152-power-strong-tight.ast.json test yes harness review tests review reviewed +tests/conformance/ast/152-power-strong-tight.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/153-power-strong-spaced.ast.json test yes harness review tests review reviewed +tests/conformance/ast/153-power-strong-spaced.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/154-power-multitick-codespan.ast.json test yes harness review tests review reviewed +tests/conformance/ast/154-power-multitick-codespan.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/155-power-code-fence-inert.ast.json test yes harness review tests review reviewed +tests/conformance/ast/155-power-code-fence-inert.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/156-power-prose-codespan-inert.ast.json test yes harness review tests review reviewed +tests/conformance/ast/156-power-prose-codespan-inert.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/157-branch-condition-description.ast.json test yes harness review tests review reviewed +tests/conformance/ast/157-branch-condition-description.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/158-loop-condition-power.ast.json test yes harness review tests review reviewed +tests/conformance/ast/158-loop-condition-power.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/159-condition-tail-structure.ast.json test yes harness review tests review reviewed +tests/conformance/ast/159-condition-tail-structure.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/ast/160-power-math-block.ast.json test yes harness review tests review reviewed +tests/conformance/ast/160-power-math-block.mq.md test yes Markdown AST only keep AST baseline tests conformance_ast reviewed +tests/conformance/semantics/01-constant-return.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/01-constant-return.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/02-text-return.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/02-text-return.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/03-float-arithmetic.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/03-float-arithmetic.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/04-big-int-arithmetic.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/04-big-int-arithmetic.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/05-factorio-recursion.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/05-factorio-recursion.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/06-fibonacci-recursion.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/06-fibonacci-recursion.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/07-euclid-iterative.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/07-euclid-iterative.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/08-loop-sum.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/08-loop-sum.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/09-nested-control-flow.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/09-nested-control-flow.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/10-explicit-positional-signature.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/10-explicit-positional-signature.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/11-default-parameters.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/11-default-parameters.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/12-named-arguments.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/12-named-arguments.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/13-function-ref-call.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/13-function-ref-call.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/14-function-ref-value.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/14-function-ref-value.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/15-string-builtins.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/15-string-builtins.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/16-int-builtins.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/16-int-builtins.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/17-float-builtins.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/17-float-builtins.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/18-table-builtin.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/18-table-builtin.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/19-type-builtin.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/19-type-builtin.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/20-math-eval-ref.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/20-math-eval-ref.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/21-math-eval-positional.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/21-math-eval-positional.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/22-print-stdout.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/22-print-stdout.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/23-unit-fallthrough.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/23-unit-fallthrough.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/24-none-value.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/24-none-value.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/25-bool-operators.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/25-bool-operators.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/26-mixed-comparison.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/26-mixed-comparison.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/27-floor-division-modulo.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/27-floor-division-modulo.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/28-index-and-member.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/28-index-and-member.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/29-map-record-literal.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/29-map-record-literal.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/30-print-list-and-map.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/30-print-list-and-map.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/31-string-concat.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/31-string-concat.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/32-recursive-sum.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/32-recursive-sum.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/33-conditional-return-in-loop.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/33-conditional-return-in-loop.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/34-elif-chain.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/34-elif-chain.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/35-default-and-named-mixed.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/35-default-and-named-mixed.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/36-foreign-call-python.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/36-foreign-call-python.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/37-power-right-associative.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/37-power-right-associative.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/38-power-unary-minus.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/38-power-unary-minus.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/39-power-parenthesized.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/39-power-parenthesized.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/40-power-float-negative-exponent.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/40-power-float-negative-exponent.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/41-power-strong-codespan.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/41-power-strong-codespan.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/42-power-branch.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/42-power-branch.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/43-power-loop.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/43-power-loop.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/44-inert-power-prose.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/44-inert-power-prose.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/45-memory-buffer.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/45-memory-buffer.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/46-memory-grow-zero-fill.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/46-memory-grow-zero-fill.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/47-memory-isolation-and-alias.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/47-memory-isolation-and-alias.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/48-memory-bump-allocator.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/48-memory-bump-allocator.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/49-memory-linked-list.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/49-memory-linked-list.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/50-memory-allocation-failure-atomic.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/50-memory-allocation-failure-atomic.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/51-list-map-value-semantics.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/51-list-map-value-semantics.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/52-text-codepoints.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/52-text-codepoints.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/53-table-projection.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/53-table-projection.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/54-table-filter-stdlib.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/54-table-filter-stdlib.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/55-first-fit-free-list-allocator.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/55-first-fit-free-list-allocator.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/56-memory-binary-tree.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/56-memory-binary-tree.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/57-csv-row-splitter.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/57-csv-row-splitter.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/58-memory-hash-table.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/58-memory-hash-table.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/59-utf8-encoder.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/59-utf8-encoder.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/60-utf8-decoder.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/60-utf8-decoder.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/61-memory-graph-adjacency.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/61-memory-graph-adjacency.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/62-json-array-parser.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/62-json-array-parser.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/63-memory-bytecode-vm.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/63-memory-bytecode-vm.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/64-memory-integer-codecs.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/64-memory-integer-codecs.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/65-table-sort-stdlib.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/65-table-sort-stdlib.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/66-resource-stdout-write.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/66-resource-stdout-write.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/67-table-join-stdlib.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/67-table-join-stdlib.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/68-csv-quoted-row.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/68-csv-quoted-row.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/69-table-group-stdlib.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/69-table-group-stdlib.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/70-matrix-multiply.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/70-matrix-multiply.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/71-http-parser.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/71-http-parser.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/72-table-columnar.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/72-table-columnar.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/conformance/semantics/73-sparse-matrix.expected.json test yes harness review tests review reviewed +tests/conformance/semantics/73-sparse-matrix.mq.md test yes old syntax migrate source tests conformance/negative migrated +tests/consumers/analysis_consumer.py test yes harness review tests review reviewed +tests/consumers/trace_consumer.py test yes harness review tests review reviewed +tests/consumers/validate_protocols.py test yes harness review tests review reviewed +tests/e2e/README.md test yes harness review tests review reviewed +tests/fixtures/tool_echo.rs test yes harness review tests review reviewed +tests/negative/01-invalid-mode-marker-case.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/01-invalid-mode-marker-case.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/02-invalid-mode-marker-misspelled.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/02-invalid-mode-marker-misspelled.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/03-invalid-mode-marker-conflict.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/03-invalid-mode-marker-conflict.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/04-empty-unit-name-exec.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/04-empty-unit-name-exec.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/05-empty-unit-name-knowledge.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/05-empty-unit-name-knowledge.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/06-exec-without-function-under-knowledge.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/06-exec-without-function-under-knowledge.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/07-exec-without-function-under-h1.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/07-exec-without-function-under-h1.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/08-payload-nested-strong-emph.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/08-payload-nested-strong-emph.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/09-payload-nested-strong-strong.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/09-payload-nested-strong-strong.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/10-payload-nested-strong-link.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/10-payload-nested-strong-link.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/11-payload-nested-strong-math.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/11-payload-nested-strong-math.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/12-payload-nested-strong-strikethrough.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/12-payload-nested-strong-strikethrough.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/13-payload-nested-emph-strong.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/13-payload-nested-emph-strong.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/14-payload-nested-emph-emph.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/14-payload-nested-emph-emph.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/15-payload-nested-linebreak.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/15-payload-nested-linebreak.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/16-empty-payload-strong.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/16-empty-payload-strong.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/17-empty-payload-emph.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/17-empty-payload-emph.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/18-syntax-if-missing-operand.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/18-syntax-if-missing-operand.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/19-syntax-if-trailing-colon.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/19-syntax-if-trailing-colon.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/20-syntax-end-if.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/20-syntax-end-if.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/21-syntax-return-missing-value.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/21-syntax-return-missing-value.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/22-syntax-multi-statement-payload.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/22-syntax-multi-statement-payload.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/23-syntax-malformed-params.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/23-syntax-malformed-params.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/24-unmatched-else.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/24-unmatched-else.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/25-duplicate-else.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/25-duplicate-else.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/26-unmatched-end.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/26-unmatched-end.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/27-unclosed-control-if.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/27-unclosed-control-if.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/28-unclosed-control-while.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/28-unclosed-control-while.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/29-control-across-heading.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/29-control-across-heading.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/30-signature-position-after-statement.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/30-signature-position-after-statement.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/31-signature-position-in-list.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/31-signature-position-in-list.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/32-signature-position-duplicate.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/32-signature-position-duplicate.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/33-unsupported-version-directive.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/33-unsupported-version-directive.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/34-unsupported-syntax-selection.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/34-unsupported-syntax-selection.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/35-unknown-function.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/35-unknown-function.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/36-unknown-variable.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/36-unknown-variable.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/37-call-arity-missing-argument.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/37-call-arity-missing-argument.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/38-call-arity-unknown-named.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/38-call-arity-unknown-named.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/39-uninitialized-partial-branch.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/39-uninitialized-partial-branch.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/40-frontmatter-invalid-yaml.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/40-frontmatter-invalid-yaml.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/41-frontmatter-invalid-import-shape.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/41-frontmatter-invalid-import-shape.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/42-frontmatter-duplicate-import-alias.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/42-frontmatter-duplicate-import-alias.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/43-unknown-variable-with-signature.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/43-unknown-variable-with-signature.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/44-duplicate-function-name.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/44-duplicate-function-name.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/45-duplicate-namespace-name.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/45-duplicate-namespace-name.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/01-division-by-zero.expected.json test yes harness review tests review reviewed +tests/negative/runtime/01-division-by-zero.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/02-type-error.expected.json test yes harness review tests review reviewed +tests/negative/runtime/02-type-error.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/03-index-out-of-bounds.expected.json test yes harness review tests review reviewed +tests/negative/runtime/03-index-out-of-bounds.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/04-unknown-field.expected.json test yes harness review tests review reviewed +tests/negative/runtime/04-unknown-field.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/05-not-callable.expected.json test yes harness review tests review reviewed +tests/negative/runtime/05-not-callable.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/06-permission-denied-foreign.expected.json test yes harness review tests review reviewed +tests/negative/runtime/06-permission-denied-foreign.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/07-math-unsupported.expected.json test yes harness review tests review reviewed +tests/negative/runtime/07-math-unsupported.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/08-stack-overflow.expected.json test yes harness review tests review reviewed +tests/negative/runtime/08-stack-overflow.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/09-branch-condition-not-bool.expected.json test yes harness review tests review reviewed +tests/negative/runtime/09-branch-condition-not-bool.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/10-function-ref-bad-argument.expected.json test yes harness review tests review reviewed +tests/negative/runtime/10-function-ref-bad-argument.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/11-int-negative-exponent.expected.json test yes harness review tests review reviewed +tests/negative/runtime/11-int-negative-exponent.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/12-integer-exponent-limit.expected.json test yes harness review tests review reviewed +tests/negative/runtime/12-integer-exponent-limit.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/13-memory-out-of-bounds.expected.json test yes harness review tests review reviewed +tests/negative/runtime/13-memory-out-of-bounds.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/14-memory-byte-range.expected.json test yes harness review tests review reviewed +tests/negative/runtime/14-memory-byte-range.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/15-index-assign-non-memory.expected.json test yes harness review tests review reviewed +tests/negative/runtime/15-index-assign-non-memory.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/16-memory-huge-offset.expected.json test yes harness review tests review reviewed +tests/negative/runtime/16-memory-huge-offset.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/17-memory-grow-beyond-max.expected.json test yes harness review tests review reviewed +tests/negative/runtime/17-memory-grow-beyond-max.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/18-memory-negative-pages.expected.json test yes harness review tests review reviewed +tests/negative/runtime/18-memory-negative-pages.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/19-list-append-wrong-type.expected.json test yes harness review tests review reviewed +tests/negative/runtime/19-list-append-wrong-type.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/20-table-cell-out-of-bounds.expected.json test yes harness review tests review reviewed +tests/negative/runtime/20-table-cell-out-of-bounds.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/runtime/21-map-key-not-text.expected.json test yes harness review tests review reviewed +tests/negative/runtime/21-map-key-not-text.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/warnings/01-inferred-signature.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/warnings/01-inferred-signature.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/negative/warnings/02-knowledge-and-containers-are-inert.expected.json test yes old syntax migrate source/expectations tests negative/properties migrated +tests/negative/warnings/02-knowledge-and-containers-are-inert.mq.md test yes old negative shape rebuild for sem.* diagnostics tests negative migrated +tests/security/escape_helper.c test yes harness review tests review reviewed +tests/security/run-lane.sh test yes old syntax migrate source/expectations tests negative/properties migrated +tools/dev-only/check-mq-syntax.py tooling yes migration aid review docs review reviewed +tools/dev-only/gen-migration-inventory.py tooling yes migration aid review docs review reviewed +tools/pack-stdlib.py tooling yes migration aid review docs review reviewed +tools/perf/bench.py tooling yes migration aid review docs review reviewed diff --git a/docs/releasing.md b/docs/releasing.md index 388685e..528fd2a 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -9,6 +9,14 @@ required CI matrix on the exact commit. - All applicable gates in [`NEXT_RELEASE_CI_CONVERGENCE.md`](NEXT_RELEASE_CI_CONVERGENCE.md) §7 are PASS with a CI URL for the same SHA. +- **Language migration is closed for the release SHA.** The source language is + [RFC-LANG-0002](architecture/RFC-LANG-0002-unified-semantics.md); the + release notes must state that this is a **breaking** change and that + pre-RFC `.mq.md` sources are not executable (no `--legacy` path). The + migration inventory must be 100% classified, `stdlib/**/*.mq.md` and examples + migrated, and executable-source tests green on the migrated tree. Until then + this document describes a candidate only, never a releasable state; see + [`STATUS.md`](STATUS.md) and [`migration/README.md`](migration/README.md). - G-C is either PASS with a security-lane URL, or the release explicitly says strict isolation is unavailable. Never claim G-C from local root/sudo runs. - `git status --porcelain` is clean apart from intended release files. @@ -52,7 +60,10 @@ skip the license requirement: add them before shipping. ## 4. Clean-install smoke -Run in a fresh directory (not the source tree): +Run in a fresh directory (not the source tree). The example commands below +assume the examples have been migrated to RFC-LANG-0002 and are accepted by the +frozen binary; a failing example run on an un-migrated tree is not a release +signal: ```bash tmp="$(mktemp -d)" diff --git a/docs/security-gate.md b/docs/security-gate.md index ffa33d6..d7b2fe6 100644 --- a/docs/security-gate.md +++ b/docs/security-gate.md @@ -8,6 +8,17 @@ the earlier `b6fc182` run is retained below as history. **No remote self-hosted security-lane CI URL exists yet.** Snapshot: workspace `0.1.0`, 2026-11-20. See ADR-0021. +> **Language-syntax migration note.** This evidence predates RFC-LANG-0002 +> ([`architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md)): +> the `.mq.md` fixtures and the example paths used by the lane are being +> migrated to the unified syntax, and the lane must be re-run on the migrated +> tree before it is cited as evidencing the new syntax. The **security facts +> here do not change** — `@exec` is a compile-time projection, not a capability +> grant; `@knowledge` produces no IR and therefore no host effect; resource, +> file, network, stdin/stdout, memory and budget checks remain at the +> `CapabilityHost` boundary, and the strict sandbox is unaffected. See +> [`STATUS.md`](STATUS.md) for the current red/green state. + This report separates three things that are often conflated: 1. the **mechanism** (Bubblewrap namespaces + rlimits + supervisor), diff --git a/docs/security-vm.md b/docs/security-vm.md index a0ee6a6..e35b9bb 100644 --- a/docs/security-vm.md +++ b/docs/security-vm.md @@ -5,6 +5,13 @@ development host is a container that cannot create namespaces. This document records how that VM was built so the result can be reproduced and so the VM can be registered as a dedicated self-hosted security runner. +> **Language-syntax migration note.** The lane fixtures are `.mq.md` sources and +> are being migrated to RFC-LANG-0002 +> ([`architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md)). +> Re-run `tests/security/run-lane.sh` on the migrated tree before using this VM +> as evidence for the new syntax; the VM/OS-isolation procedure itself is +> unchanged. See [`STATUS.md`](STATUS.md). + **Do not run this on a daily host with valuable data.** The VM is disposable; the commands below do not disable AppArmor or any global host protection. diff --git a/spec/analysis-v2.md b/spec/analysis-v2.md index 81bbf00..0ca7bda 100644 --- a/spec/analysis-v2.md +++ b/spec/analysis-v2.md @@ -160,7 +160,7 @@ Diagnostics no longer embed absolute physical paths: "line": 2, "column": 3, "severity": "warning", - "code": "markdown.inert_executable", + "code": "sem.inferred_signature", "message": "...", "hints": [] } @@ -170,6 +170,11 @@ Diagnostics no longer embed absolute physical paths: the owning module. `span`, `line` or `column` may be `null` when no precise location exists. +The `code` value is an open, stable string: the current language revision adds +the `sem.*` family (`spec/mapping.md` §8) and removes the old +`markdown.inert_executable` warning. This is a diagnostic-value change, not an +Analysis schema change; `schema_version` stays 2. + ## 6. Compatibility * Writers emit `schema_version: 2`. There is no v1 writer and no diff --git a/spec/expression.ebnf b/spec/expression.ebnf index cc6cf68..4365d75 100644 --- a/spec/expression.ebnf +++ b/spec/expression.ebnf @@ -1,23 +1,71 @@ -(* Marqdo Expression Grammar v1 - Status: frozen for M0.5, extended by ADR-0022 with Memory-index assignment - targets. This is the only grammar for executable payloads. - It is a small independent language: it is NOT Markdown and NOT translated - to Python. Markdown AST decides where a payload exists; this grammar - decides what it means. +(* Marqdo Statement and Expression Grammar + Status: current language contract, breaking rewrite (RFC-LANG-0002). + This replaces the earlier v1 expression-only grammar in place. - Terminals are described in prose where Unicode categories matter. + There is one grammar for every executable payload. Markdown AST decides + which closed carrier (Strong / Emph / inline Code) is a payload and where + it lives; this grammar decides what that payload means. No second parser + and no per-file syntax selector exists. + + Implementation state: the Rust expression parser still implements the + previous, control-free grammar; this file is the target contract. See + docs/STATUS.md. *) -program = [ statement ] , EOF ; +(* One payload is exactly one statement and must consume the whole payload. *) +payload = statement , EOF ; -statement = assignment | expression ; +statement = if_stmt + | else_stmt + | while_stmt + | end_stmt + | return_stmt + | params_stmt + | assignment + | expression ; + +if_stmt = "if" , space_required , expression ; +else_stmt = "else" ; +while_stmt = "while" , space_required , expression ; +end_stmt = "end" ; +return_stmt = "return" , space_required , expression ; +params_stmt = "params" , "(" , [ parameter_list ] , ")" ; + +(* `if`, `else`, `while`, `end`, `return` and `params` are reserved statement + words only when they are the complete first token of a payload. + `ifdef(x)` and `returning(x)` are ordinary identifiers; a bare `if` used as + an identifier is a reserved-word error. `else`/`end` take no additional + tokens: `else x` and `end if` are syntax errors. No trailing colon: + `if x > 0:` is a syntax error. No `elif`, `for`, `break`, `continue`, + `try`, empty `return`, `end if`, or semicolon-separated multi-statement + payload exists in this revision. + + Control pairing is not part of this grammar; it is a separate compile-time + stack in the frontend: + - every `if` has exactly one closing `end`; + - `else` is optional and at most one per `if`; + - every `while` has exactly one closing `end`; + - `else` must bind the top-of-stack `if`; `end` closes the top frame; + - a frame must close inside the same heading's direct body. +*) + +(* Function parameter declaration. It is legal only as the first direct + execution payload of an Exec H2 function, at most once, and never inside a + list or block quote. The declaration is compile-time metadata, not a + runtime call. *) +parameter_list = parameter , { "," , parameter } , [ "," ] ; +parameter = identifier , ":" , type_name , [ "=" , expression ] ; +type_name = identifier ; +(* Parameter names are unique; positional parameters precede defaulted ones. + Types and default expressions reuse the existing signature rules. *) + +(* Assignment and place writes are unchanged from the previous revision. *) assignment = assign_target , "=" , expression ; assign_target = identifier | postfix_expr , "[" , expression , "]" ; -(* v1 left-hand sides are a local identifier or one index place. The index - target writes one byte into an addressable Memory region; other base values - are rejected at run time. Member assignment (`a.b = 1`) is a parse error. - Chained assignment is a parse error. See ADR-0022. *) +(* The index target writes one byte into an addressable Memory region; other + base values are rejected at run time. Member assignment (`a.b = 1`) and + chained assignment are parse errors. See ADR-0022. *) expression = or_expr ; or_expr = and_expr , { "or" , and_expr } ; @@ -60,8 +108,9 @@ record_entry = ( identifier | text_literal ) , ":" , expression ; identifier = xid_start , { xid_continue } ; (* Unicode XID per UAX #31: Chinese, Latin, etc. are valid. - Keywords are reserved and cannot be identifiers: - true, false, None, and, or, not. *) + Reserved words cannot be identifiers: + true, false, None, and, or, not, + if, else, while, end, return, params. *) int_literal = digit , { digit } ; (* arbitrary precision decimal integer; no sign here (unary @@ -77,7 +126,8 @@ escape = "\\" , ( '"' | "\\" | "n" | "t" | "r" | "u{" , hexdigit , { hex text_char = ? any Unicode scalar value except '"' and "\\" ? ; (* Whitespace: any Unicode whitespace separates tokens. Newlines inside a - code-span payload are whitespace. There are no comments in v1. *) + code-span payload are whitespace. There are no comments. `space_required` + means at least one whitespace character after the keyword. *) (* Notes on the Markdown boundary *) (* - A "**" inside a payload is the power operator only when it survived @@ -88,3 +138,5 @@ text_char = ? any Unicode scalar value except '"' and "\\" ? ; payload; the frontend maps them back through the text/code segments to file spans. *) (* - Maximum nesting depth is 128; exceeding it is an expr.parse error. *) +(* - Every payload must be fully consumed. A trailing token is a syntax error, + never an ignored suffix. *) diff --git a/spec/foreign.md b/spec/foreign.md index f621b94..694abd1 100644 --- a/spec/foreign.md +++ b/spec/foreign.md @@ -21,7 +21,9 @@ Access is by `ref("#heading")` (exactly one code/formula resource in that heading range; `ref.ambiguous` otherwise — see `spec/references.md` §5): ````markdown -## Python 校验 +# @knowledge 示例 + +## @knowledge Python 校验 ```python import json, math, sys @@ -30,11 +32,11 @@ r = int(envelope["input"]["entries"]["r"]["decimal"]) print(json.dumps({"type": "float", "value": math.pi * r ** 2})) ``` -## main +## @exec main -**结果 = foreign.call(ref("#python-校验"), {"r": 3})** - -> 打印(结果) +`结果 = foreign.call(ref("#python-校验"), {"r": 3})` +`print(结果)` +`return 结果` ```` The anchor is the GitHub-style slug of the heading (`#python-校验`), not the diff --git a/spec/mapping.md b/spec/mapping.md index 00b553d..e4c8662 100644 --- a/spec/mapping.md +++ b/spec/mapping.md @@ -1,255 +1,402 @@ -# Marqdo AST → Program Mapping v1 +# Marqdo AST → Program Mapping -Status: **frozen for M0.5**. This file is the normative mapping from Markdown -AST structure to program meaning. It is derived directly from -`docs/DEVELOPMENT_BLUEPRINT.md` sections 1.2–1.4 and 3.2. +Status: **current language contract, breaking rewrite (RFC-LANG-0002)**. This +file replaces the earlier Strong/Emph/List/Quote mapping in place; there is no +second active mapping and no per-file syntax selector. -## 1. The two rules that override everything +> **Implementation state:** this document is normative for the target language, +> but the Rust frontend in this checkout still implements the pre-RFC mapping. +> Tests that exercise executable Marqdo source are therefore expected to be red +> until the frontend migration lands. See `docs/STATUS.md` and +> `docs/migration/semantic-rewrite-inventory.tsv`. Do not read this document as +> evidence that the CLI already supports the syntax. -1. **Node type and structural position decide the role.** A `strong` node in an - executable position is an execution statement and its payload must parse as - a `Statement`. It is never "prose that happens to look like code". -2. **Invalid executable shapes are hard errors.** If a node occupies an - executable role but its shape is invalid, compilation fails with a - `markdown.invalid_construct` diagnostic. There is no fallback to prose. +Authority: `docs/architecture/RFC-LANG-0002-unified-semantics.md`. +Markdown parsing remains `marqdo.md.v1` (`spec/markdown-profile.md`); only the +Markdown→program mapping changes. -Prose never causes an action. Natural-language words (“if”, “return”, “若”, -“执行”) are never interpreted as keywords. +## 0. The mapping in one page -## 2. Document regions and heading scopes +1. **Headings declare the semantic mode.** `@exec` and `@knowledge` may prefix + any H1–H6 heading. Unmarked headings inherit the nearest ancestor heading's + mode. The document root is Knowledge. +2. **Only an Exec H2 is a callable function.** H1 is a namespace/top-level + unit, H2 Exec is a function, H2 Knowledge is an inert knowledge unit, and + H3–H6 are sections that never create callable functions. +3. **Closed carriers carry one statement each.** In an Exec scope, `Strong`, + `Emph` and inline `Code` are interchangeable carriers of one payload. They + no longer mean execute/return/lazy respectively. +4. **Keywords inside the payload decide the operation.** `if`, `else`, `while`, + `end`, `return`, `params(...)`, assignment and expression statements. Lists, + block quotes and paragraphs are document containers only. +5. **Errors never fall back to prose.** Once a payload is extracted from an + Exec scope it must parse fully; a failure is a diagnostic. +6. **Control blocks never cross a heading segment.** Every `if`/`while` must be + closed by `end` inside the same heading's direct body. A `return` unwinds + the whole H2 function. -A document root is a module. Heading nodes create addressable scopes: +Two rules override everything else: -| AST | Role | Requirements | +* **Node type and structural position decide whether a node is a payload + candidate**, never the success or failure of parsing and never natural + language. +* **Invalid payloads are hard errors**, never "ordinary Markdown". + +## 1. Document regions and heading modes + +### 1.1 Declaring a mode + +A heading mode declaration is recognized only when it is the exact prefix of +the heading's **first plain Text child**, followed by whitespace and a non-empty +heading name: + +```ebnf +heading_mode_prefix = "@exec" | "@knowledge" ; +heading_decl = heading_mode_prefix , whitespace , nonempty_title ; +``` + +The two legal words are case-sensitive and complete. The rules: + +| Source | Result | +|---|---| +| `## @exec main` | Exec heading, semantic name `main` | +| `## @knowledge 原理` | Knowledge heading, semantic name `原理` | +| `## main` | no declaration; inherit | +| `## 关于 @exec 的讨论` | no declaration; the `@exec` is ordinary title text | +| `## @Exec main` / `## @knowledg main` | `sem.invalid_mode_marker` (no case/spelling repair) | +| `## @exec` | `sem.empty_unit_name` | +| `## @exec @knowledge main` | conflicting declarations; hard error | +| `## **@exec** main` | not a declaration; `@exec` is not the first plain Text child | +| prose containing `@exec` | ordinary text; never changes mode | + +The heading's **display text** is unchanged for Markdown rendering. Its +**semantic name** has the declaration (and the whitespace after it) removed, +then applies the existing NFC/trim/whitespace-collapse normalization. All +identity, duplicate checks, function registration and `ref` lookup use the +semantic name; `@exec`/`@knowledge` are never part of a callable name. + +ATX headings are the only accepted declaration form. A Setext heading has no +prefix declaration in the first version and simply inherits its mode; do not +invent an implicit declaration for it. + +### 1.2 Inheritance + +Using the Markdown heading stack (nearest lower-level ancestor heading, by +source order): + +```text +Mode(document root) = Knowledge +Mode(H) = Explicit(H) if H has a valid declaration +Mode(H) = Mode(nearest ancestor) if H has no declaration and has an ancestor +Mode(H) = Knowledge if H has no declaration and no ancestor +``` + +Inheritance is a structural calculation over heading levels, not inference from +prose. A heading's scope ends at the next heading of the same or higher level +(same or smaller number); deeper headings are inside it. Siblings never share a +mode: an unmarked heading after a sibling that explicitly switched to Knowledge +still inherits from the nearest **ancestor**, not from the sibling. + +Skipped levels (H1 directly followed by H3) still use the nearest valid +ancestor heading. + +### 1.3 Heading roles + +| Heading | Mode | Language object | Callable? | Effect | +|---|---|---|---|---| +| H1 | Knowledge/Exec | Namespace or top-level unit | No | Sets the default mode for descendants | +| H2 | Exec | Function + Unit | **Yes** | Opens the function body | +| H2 | Knowledge | Knowledge unit | No | Document section; no function | +| H3–H6 | Exec | Section of the owning H2 Exec function | No | Appends an execution segment to that function | +| H3–H6 | Knowledge | Section (knowledge or under a function) | No | Retained as document; no statements | + +H3–H6 never create functions, never export callables and never create a new +call frame. An Exec payload under an H1 without an H2 Exec function, or under a +Knowledge H2, is `sem.exec_without_function`; it is never promoted to a function +and never executed as module-level code. + +### 1.4 Version selection + +There is no syntax-version switch. Every `.mq.md` file, imported module, +dependency, fixture and stdlib module uses this mapping. Introducing +`marqdo_semantics`, `syntax: v1`, `--legacy`, `--syntax` or any per-file mode +selection is an error (`sem.unsupported_version_directive` where the old +directive is seen); no implicit downgrade to an earlier mapper is permitted. + +## 2. Inert regions + +The following are never searched for payloads, even inside an Exec scope: + +| Region | Treatment | +|---|---| +| every `@knowledge` subtree | zero executable statements | +| heading text (including a mode declaration) | unit identity only | +| link labels and URLs, image alt text | document/link data | +| GFM table cells | table data | +| math / math blocks | inert `Formula` resources | +| HTML blocks/inline HTML | document data | +| fenced and indented code blocks | inert `Code` resources | +| front matter | module configuration | +| strikethrough and other non-MVP extensions | inert document data | + +Inline `Code` (a code span) is a payload carrier in Exec scope. A fenced code +block is a different AST node and stays inert; the two must not be conflated. + +## 3. Executable payload carriers + +### 3.1 Accepted carriers + +Only these Comrak AST nodes are payload carriers in the first version: + +| AST kind | Payload | +|---|---| +| `Strong` | concatenation of its **direct** Text and inline Code children, in source order | +| `Emph` | same as `Strong` | +| inline `Code` | the code span literal | + +They are **interchangeable carriers of one statement**. For the same Exec +scope, owner function and payload text: + +```text +Parse(Strong("return n")) == Parse(Emph("return n")) == Parse(Code("return n")) +``` + +The original AST kind is still recorded for rendering and source spans. Format +does not select the operation. + +### 3.2 Extraction rules + +1. Traverse an Exec heading's direct body in Markdown AST document order, and + recurse only through the allowed containers `Paragraph`, `List`, `ListItem` + and `BlockQuote`. +2. Extract only complete outer carrier nodes. A nested `Code` inside a + `Strong`/`Emph` is consumed by the outer carrier and must not execute again. +3. For `Strong`/`Emph`, only direct Text and inline Code children are allowed. + Any nested `Strong`, `Emph`, `Link`, `Image`, math, line break or other + complex child is `sem.payload_nested`. Never extract a partial statement or + silently concatenate multiple fragments. +4. A payload must be fully consumed by exactly one statement. `x = 1; return x` + in one carrier is `sem.syntax`; write two carriers instead. +5. Empty carriers in Exec scope are `sem.empty_payload`; they are never ignored. +6. Every payload keeps its original UTF-8 file span. For `Strong(Code(...))` + record the segment mapping so diagnostics point into the inner text, not at + the emphasis delimiters. +7. Two adjacent carriers produce two statements in source order. One carrier is + never split into multiple statements by newlines or semicolons. + +### 3.3 Containers + +Containers provide order and layout, not operation type: + +| Container | Compiler behavior | Not allowed | |---|---|---| -| `document` | module | exactly one root | -| `heading(level=1)` | namespace / object domain | non-empty canonical name | -| `heading(level=2)` | function | non-empty canonical name, unique in its scope | -| `heading(level>=3)` | section (source location) | does not create a function | +| `Paragraph` | extract permitted carriers in source order | prose does not execute | +| ordered `List` | recurse through items in source order | no implicit `Branch` | +| bullet `List` | recurse through items in source order | no implicit `Loop` | +| `BlockQuote` | recurse through nested blocks in source order | no implicit `Call` | +| `Heading` | switches/extends mode and segments | not a statement | -Scope rules: +A list's `ordered`/`start`/`tight` attributes, an item's checkbox, and quote +nesting depth never affect control flow. A plain ordered or bullet list with no +carriers has an empty execution projection (zero statements), which is not the +same as producing a `List([])` value. -* The range of a heading extends until the next heading of the same or a - lower level (i.e. same or smaller number), or the end of the document. -* A level-2 heading without a preceding level-1 heading belongs to the module - root. Nested headings inside a section remain part of the enclosing function. -* Headings inside container blocks (block quotes, list items) or inside fenced - code blocks never create functions. -* A function's canonical name is the normalised text of its heading children: - NFC, trimmed, internal whitespace collapsed to one space. Empty names are - errors. Duplicate canonical names in the same scope are errors. GitHub-style - anchor slugs are derived for navigation but are **not** the identity. -* `main` at module root is the default entry point for `marqdo run`; an - imported module's `main` is not run automatically. +### 3.4 The deliberate emphasis cost -## 3. Lazy (inert) regions +In an Exec scope, `**重要**` is a payload and is parsed as the expression +`重要`. If no such symbol exists, that is `symbol.unknown`. The language does +not guess that the author wanted emphasis. Put purely visual emphasis in a +`@knowledge` section (or another inert region). This is a deliberate +determinism trade-off, not an implementation gap. -The following nodes are inert regardless of where they appear. Their inline -content is never executed: +## 4. Statements -* heading text (headings scope, they do not run) -* `link` labels and `image` alt text -* `table` cells (tables are document values) -* `strikethrough` wrappers: their content is inert prose and is not traversed - for execution; do not rely on formatting to hide executable nodes -* `code_block` and inline `code` outside designated payload positions -* `math` / `math_block` -* `html_block` / `html_inline` -* front matter -* text and other inline nodes inside prose paragraphs +Each extracted payload is exactly one statement, defined by +`spec/expression.ebnf`: -Inline formatting inside those regions (e.g. `strong` inside a heading) does -not execute. The implementation must use a context-aware visitor, not a blind -whole-tree walk. +```text +if else while end +return params(...) assignment expression +``` -## 4. Executable roles in function bodies +Lexical details: -Inside a function (`heading(level=2)` range) the following roles apply, -including inside branch and loop bodies: +* Keywords are recognized only as complete first tokens: `ifdef(...)` and + `returning` are ordinary identifiers; a bare `if`/`else` used as an + identifier is a reserved-keyword error. +* `if`, `while` and `return` require a non-empty expression that consumes the + whole payload (to EOF). Trailing characters are errors. +* `else` and `end` accept no additional tokens; `else x` and `end if` are + `sem.syntax`. +* No trailing colon: `if x > 0:` is `sem.syntax`. No `elif`, `for`, `break`, + `continue`, `try`, `end if` or semicolon-separated statements in this + version. +* `return` always requires an expression; falling off the end of a function + still returns `Unit`. Explicit `return None` is available when `None` is the + intended value. +* `params(...)` is a compile-time signature declaration, not a runtime + callable; see §6. +* Existing expression precedence, literals, calls, indexing, assignment and + `Memory` place writes are unchanged. Conditions must evaluate to `Bool` and + keep the existing purity rule. -| AST node | Role | Shape requirement | On invalid shape | -|---|---|---|---| -| `strong` | execution statement | strict payload parses as `Statement` | hard error | -| `emph` | return statement | strict payload parses as `Expression` | hard error | -| `list(ordered=true)` | branch | each item starts with a condition header | hard error | -| `list(ordered=false)` | loop | each item starts with a loop condition header | hard error | -| `block_quote` | call | one paragraph forming a complete call | hard error | -| `paragraph` | prose + inline execution | inline executable nodes run in order | n/a | -| everything else | inert document value | — | type/constraint errors only if used | +## 5. Control-stack lowering -Outside functions (module top-level prose) the same executable nodes are inert -document content (S-03 in the blueprint: executable lists/strong/emph only run -inside a function body). The single exception is `main` itself, which is a -function. To make this explicit rather than silent, the frontend emits a -`markdown.inert_executable` **warning** for every would-be execution node found -outside a function body; the document still compiles and the node does nothing. +Within one execution segment, payloads form a token stream. Lower it with one +explicit stack: -Headings inside container blocks (block quotes, list items) or fenced code never -create functions and never execute inline markup. +```text +open_if(cond) -> push IfFrame(cond, then=[], else=None) +statement -> append to the innermost active body +else -> require top is IfFrame with else=None; switch to else body +open_while(cond)-> push WhileFrame(cond, body=[]) +end -> require a non-empty stack; pop the top frame and lower it +at_segment_end -> require the stack to be empty +``` -### 4.1 Strict payload extraction +Rules: -For `strong`/`emph`, the payload is the concatenation of the direct `text` and -`code` child literals, exactly as written. Nested `strong`, `emph`, `link`, -`strikethrough`, line breaks, math, HTML or any other inline node is an error: -one AST node must never be executed twice or hide control content. +* `else` pairs with the top-of-stack `IfFrame` only. It may not skip an open + `while` or an inner `if`. +* At most one `else` per `if`; `else` with no open `if` is + `sem.unmatched_else`; a second `else` is `sem.duplicate_else`. +* `end` closes exactly the most recent open `if`/`while`; no match is + `sem.unmatched_end`. +* Reaching a segment boundary with an open frame is `sem.unclosed_control`, + with a related span on the opener. The compiler must not synthesize an `end`. +* `if` lower to the existing `Branch` IR; the optional `else` may lower to a + final unconditional arm while preserving left-to-right short-circuit + evaluation and executing at most one arm. `while` lowers to `Loop`; `return` + lowers to `Return` and unwinds the whole H2 function. `else`/`end` generate no + runtime instruction of their own. -`**x = 1**` and `**`x = 1`**` have the same payload `x = 1`. `**a * b**` -parses as text in most cases; when Markdown emphasis and the multiplication -operator conflict, the author should use a code span for the payload: -`` **`a * b`** ``. There is no text-based second parse. +## 6. Functions, signatures and calls -### 4.2 Paragraph and document order +* Only an Exec H2 creates a callable function. Its body is the concatenation, + in source order, of its direct Exec body segment and the Exec segments of its + H3–H6 descendants that are part of the same function. Knowledge segments + contribute nothing. +* H3–H6 Exec sections share the H2 function's frame; locals assigned in one + segment are visible in later segments. They do not create new functions. +* `params(name: Type, ...)` is legal only as the **first direct execution + payload of an Exec H2 function**, at most once, and not inside a list or + block quote. It is compile-time metadata and may be preceded by prose or a + Knowledge subsection but not by an executing statement. Violations are + `sem.signature_position`; a duplicate declaration is also rejected. +* A function without `params` keeps the existing free-variable inference for + the first version. Public functions should declare `params`; the optional + `sem.inferred_signature` lint may be enabled. +* Calls are ordinary expressions. `print(1)`, `f(n=5)` and `> **print(1)**` + all call because the payload contains a call; the block quote itself does + not create a call. A plain `> print(1)` is inert prose. +* `@knowledge` content is never scanned for identifiers, free variables or + calls. +* `main` must be an Exec H2 to be the default `run` entry; if none exists, `run` + reports `sem.no_entry_function`. -Executable inline nodes in a paragraph run in source order. Blocks run in AST -document order. A `return` short-circuits the remaining nodes of the enclosing -function, including nodes inside branches and loops. +## 7. Segments and the heading boundary -### 4.3 Branch (`ordered list`) +An **execution segment** is one heading's direct body, excluding descendant +headings. Segments are ordered by source position. For each Exec H2 function, +process its own segment followed by the Exec segments of its descendant +headings, in document order. -Each item must: +The control stack is reset and required to be empty at every heading boundary. +A control block opened in one heading's direct body must be closed in that same +body; `end` in a later H3/H4 or on the other side of a Knowledge heading is +`sem.unmatched_end` there, while the opener's segment reports +`sem.unclosed_control`. The two errors are reported independently and are never +"repaired" across the boundary. -1. contain at least one block; -2. have a `paragraph` as its **first** block; -3. have an inline `code` node as the **first inline node** of that paragraph; - its literal is the condition expression; -4. any remaining inline content in that first paragraph is **inert prose** - (`text`, inline `code`, links, images, math, HTML, strikethrough and line - breaks). An executable `Strong`/`Emph` there is a hard - `markdown.invalid_construct` error, not silently ignored description. +Complete segments are appended to the enclosing function body in source order; +earlier segments' assignments remain visible to later ones. -The condition literal is mapped from the bytes **inside** the code-span -backticks. Delimiters are part of the Code node's source span, but condition -expression spans and parse diagnostics point at the literal. +## 8. Diagnostics -The item's remaining blocks form the branch body. Items are tested in AST -order; the first condition evaluating to `true` is executed once. No match -means `Unit` and execution continues after the list. Conditions must be -`Bool`; they must be pure (side effects in conditions are a static error when -detectable and a runtime capability concern otherwise). +Stable machine-readable codes (the human `message`/`hint` text may change): -### 4.4 Loop (`bullet list`) +| Code | Trigger | +|---|---| +| `sem.invalid_mode_marker` | unknown/case-variant/conflicting `@...` declaration at heading start | +| `sem.empty_unit_name` | a declaration with no non-empty heading name | +| `sem.duplicate_unit_name` | duplicate canonical heading/unit name in one scope | +| `sem.exec_without_function` | an executable payload with no owning H2 Exec function | +| `sem.payload_nested` | a `Strong`/`Emph` with a disallowed nested node | +| `sem.empty_payload` | an empty carrier in an Exec scope | +| `sem.syntax` | malformed statement, missing condition/value, trailing tokens, colon, unsupported keyword | +| `sem.unmatched_else` | `else` with no open `if` at the top of the stack | +| `sem.duplicate_else` | a second `else` for the same `if` | +| `sem.unmatched_end` | `end` with no open control frame | +| `sem.unclosed_control` | an open `if`/`while` at a heading/function/file boundary | +| `sem.signature_position` | `params` not at the first direct payload, duplicated, or in a container | +| `sem.unsupported_version_directive` | legacy `marqdo_semantics`/syntax-selection front matter | +| `sem.no_entry_function` | `run` with no Exec H2 `main` | +| `sem.inferred_signature` | lint: public function without explicit `params` | -Each item is an independent `while` loop. Item structure matches the branch -header rule: the first paragraph's first inline node must be a `code` span -(condition), and the remaining blocks are the loop body. The condition is -re-evaluated before every iteration and must be `Bool`. Items execute in -order, so a bullet list is a sequence of loops, one per item. +Existing `expr.*`, `symbol.unknown`, `runtime.*`, `resource.*` and capability +diagnostics keep their meaning. Diagnostics are ordered by +`(source_file, start_byte, code)`, and each carries an exact UTF-8 span plus a +related span when an opener or conflicting declaration is involved. A file with +any hard error is never executed. -Iteration over collections is expressed with stdlib `map`/`filter`/`fold`; -a dedicated `forEach` header is intentionally not part of v1. +## 9. Security and the runtime boundary -### 4.5 Call (`block quote`) +`@exec` is a compile-time projection, not a capability grant. Resource, file, +network, stdin/stdout, memory and budget checks are unchanged. A payload in +`@knowledge` produces zero IR, so it can never cause a host effect, even if its +text looks like `resource.open(...)`. Permission flags never change the +AST→IR result; they are checked at runtime by the existing host boundary. -A block quote is exactly one `paragraph` and nothing else. The paragraph is -parsed with the call grammar: +The mapping introduces no `HostOp` for `if`/`else`/`while`/`end`/`return`, no +second interpreter and no runtime knowledge of Markdown emphasis. It lowers to +the existing `Assign`/`Eval`/`Branch`/`Loop`/`Return` IR. -* plain payload: `打印("你好")`, `math.eval(ref("#公式"), {"r": r}, target="A")` - — the strict payload must parse as a complete `CallExpr`; -* link form: `[计算面积](./math.mq.md#计算面积)(r=3)` — the first inline node - must be a `link`, its destination identifies the target function, and the - remaining `text`/`code` payload must be a parenthesised argument list. +## 10. Migration table (old mapping → current mapping) -Anything else (a second paragraph, plain prose, a nested quote, an expression -that is not a call) is a hard error. Two calls require two block quote nodes. -`> [说明](#目标)` without an argument list is not accepted in v1. +| Requirement | Old source | Current source | +|---|---|---| +| Namespace | `# 算法` | `# @knowledge 算法`, or `# @exec 算法` for an Exec default | +| Function | `## main` | `## @exec main` (or an unmarked H2 under an Exec H1) | +| Assignment | `**x = 1**` | `**x = 1**`, `*x = 1*` or `` `x = 1` `` | +| Return | `*x*` | `**return x**`, `*return x*` or `` `return x` `` | +| Branch | ordered list with a first code-span condition | `if cond ... else ... end`; containers are presentation only | +| Loop | bullet list with a first code-span condition | `while cond ... end` | +| Call | block quote containing a call, or a Strong expression | any carrier whose expression is a call | +| Signature | first standalone code span `(n: Int)` after the H2 | `params(n: Int)` as the first direct payload | +| Ordinary list | error inside a function | ordinary document structure, zero statements | +| Ordinary quote | error inside a function | ordinary document structure, zero statements | +| Knowledge | implied by position/inertness only | explicit `@knowledge` scope | -The call result is discarded by the statement form; use `strong` to bind it -(`**面积 = 计算面积(r=3)**`). +Old files are not compatible. Migration must be done by AST role, not by a +global regular expression, and a migrated program must preserve function names, +argument meaning, evaluation order, early-return behavior and side effects. -## 5. Calls, returns and values - -* A call is `函数(...)`; zero-argument calls still write `()`. -* Positional arguments are only allowed for functions with an explicit - signature. Named arguments can be given in any order for any function. -* Arguments are evaluated in source order exactly once before binding. -* `emph` returns the value of its expression from the enclosing function - (propagating through branch/loop bodies), never from a block. -* `*表达式*` used in a branch is a return from the whole function. -* A function that ends without a return evaluates to `Unit`. `None` is an - explicit empty value and is distinct from `Unit`. -* An `emph` node outside any function body is inert document content and emits - a `markdown.inert_executable` warning (ADR-0002); it is not executed and is - not a hard error. Inside a function body, every `emph` is a return. - -## 6. Function signatures and parameter inference - -* Optional explicit signature: the first `paragraph` immediately after the - function heading, if and only if it consists solely of one inline `code` - span, and that span parses as `(name: Type = default, ...)`. - The declaration is inert Markdown otherwise. -* Without a signature, parameters are inferred from **free reads of executable - expressions** using data-flow analysis over the function's control-flow - graph (see `evaluation.md` §5). Natural language, heading words, code spans - outside executable positions and prose never introduce parameters. -* Inferred parameters are identified by name. Functions with inferred - signatures accept **named arguments only**. Explicit signatures allow - positional arguments in declaration order. -* A read that is neither a parameter, a local assignment, a module constant, - an imported binding nor a builtin is a `symbol.unknown` error with a hint; - the CLI can list inferred signatures with `inspect --signature`. - -## 7. Example: ordered list branch - -Source: +## 11. Canonical example ```markdown -## 分类 +# @knowledge 数学演示 -1. `n < 0` - **结果 = -1** -2. `n == 0` - **结果 = 0** -3. `n > 0` - **结果 = 1** +这是普通文档;**加粗**只显示为加粗。 -*结果* +## @exec main + +`x = 5` +`y = x * x` +`return y` ``` -AST (abridged): +Normalized IR: `Assign(x, 5)`, `Assign(y, Mul(x, x))`, `Return(y)`. The H1 is +Knowledge; the H2 overrides to Exec and is the callable `main`. -```text -heading(2) 分类 - list(ordered) start=1 - item - paragraph -> code("n < 0"), text("") - strong -> text("结果 = -1") - item - paragraph -> code("n == 0") - strong -> text("结果 = 0") - ... - paragraph - emph -> text("结果") -``` +## 12. Non-negotiable implementation constraints -IR: +Do not: -```text -Function 分类(params=[n]) - Branch [ - (Eval(n < 0), [Assign(结果, -1)]), - (Eval(n == 0), [Assign(结果, 0)]), - (Eval(n > 0), [Assign(结果, 1)]), - ] - Return(Ident(结果)) -``` - -## 8. Hard-error checklist - -The following are compile errors with source spans, never prose fallbacks: - -* `strong`/`emph` in a function body whose payload does not parse; -* nested `strong`/`emph`/link inside an executable payload; -* ordered list item whose first inline node is not a code span condition; -* bullet list item without a condition header; -* executable `Strong`/`Emph` in the description remainder of a condition - paragraph (it would otherwise be swallowed); -* non-`Bool` condition (detected statically when the type is known, else at - runtime as `runtime.type`); -* block quote that is not exactly one complete call; -* duplicate function names in a scope; -* empty heading names; -* `emph`/`strong`/control structures outside any function body are inert and - produce a `markdown.inert_executable` warning (see §4); they never return - from or execute anything at module level; -* executable node inside a lazy region being interpreted (must not happen). +* try to parse a carrier and fall back to prose on failure; +* infer a list is a branch because an item looks like a condition; +* use emphasis type to choose execute vs return; +* use block-quote/list type to choose call/branch/loop; +* scan raw Markdown text for `@exec`/`if`/`return` instead of using the AST; +* recover a misspelled `@knowledge` by inheriting the ancestor mode; +* expose a per-file syntax switch, legacy mapper, `--legacy` flag or dual + active specification. diff --git a/spec/markdown-profile.md b/spec/markdown-profile.md index 671fc91..2845d30 100644 --- a/spec/markdown-profile.md +++ b/spec/markdown-profile.md @@ -7,6 +7,13 @@ Profile id: `marqdo.md.v1` Parser: [comrak](https://comrak.ee/) `=1.0.0`, `default-features = false` CommonMark baseline: 0.31.2 +> **Semantic mapping notice (RFC-LANG-0002).** The Markdown profile is +> unchanged by the breaking syntax revision: the same CommonMark/GFM AST and +> byte spans are produced. What changed is the separate Markdown→program +> mapping in `spec/mapping.md` (heading `@exec`/`@knowledge` modes, unified +> `Strong`/`Emph`/inline `Code` payloads, keyword control flow). Do not bump +> this profile id for a semantic-mapping-only change. + ## 1. Why a profile Markdown is the syntax of the language. Any parser behaviour that can change @@ -22,7 +29,7 @@ Enabled extensions: | Option | Value | Consequence | |---|---|---| | `extension.table` | `true` | GFM tables produce `table`/`table_row`/`table_cell` nodes. | -| `extension.strikethrough` | `true` | `~~x~~` produces `strikethrough`. Inert unless it appears in an executable payload (where it is an error). | +| `extension.strikethrough` | `true` | `~~x~~` produces `strikethrough`. Strikethrough is never an executable carrier and its content is inert in both modes. | | `extension.tasklist` | `true` | `- [x]`/`- [ ]` items carry a checkbox flag on the item node. | | `extension.math_dollars` | `true` | `$...$` and inline `$$...$$` produce `math`; standalone `$$` fences with `math_dollars_block` produce `math_block`. | | `extension.math_dollars_block` | `true` | Multi-line `$$` display math is a block node. | diff --git a/spec/math.md b/spec/math.md index 32d4950..a44443e 100644 --- a/spec/math.md +++ b/spec/math.md @@ -19,17 +19,20 @@ with two or more formulas the runtime raises `ref.ambiguous` and refuses to pick one (`spec/references.md` §5, ADR-0003). ```markdown -## 圆面积公式 +# @knowledge 数学 + +## @knowledge 圆面积公式 $$ A = \pi r^2 $$ -## 计算圆面积 +## @exec 计算圆面积 -**面积 = math.eval(ref("#圆面积公式"), {"r": 4}, target="A")** +`params(r: Number)` -*面积* +`面积 = math.eval(ref("#圆面积公式"), {"r": r}, target="A")` +`return 面积` ``` Nothing is evaluated by reading or rendering the document. `math.*` must be diff --git a/spec/package-format.md b/spec/package-format.md index 53f18b4..6e6464f 100644 --- a/spec/package-format.md +++ b/spec/package-format.md @@ -257,16 +257,17 @@ after its file-set digest and cache marker verify. ``` (empty dependencies/plugins/capabilities are omitted); -* writes `index.mq.md`: +* writes `index.mq.md` (the target syntax; the template in a pre-RFC binary + still emits the old spelling and is part of the pending migration): ```markdown - ## main + ## @exec main - **问候 = "你好,Marqdo"** + `问候 = "你好,Marqdo"` - > 打印(问候) + `打印(问候)` - *问候* + `return 问候` ``` * writes `.gitignore` containing `.marqdo/`; diff --git a/spec/plugin-abi.md b/spec/plugin-abi.md index 158503d..ab8ba68 100644 --- a/spec/plugin-abi.md +++ b/spec/plugin-abi.md @@ -323,11 +323,11 @@ namespace (`solver`). Document syntax (`examples/plugin-demo/plugin-call.mq.md`): ```markdown -## main +## @exec main -**结果 = solver.add(a=20, b=22)** - -> 打印(结果) +`结果 = solver.add(a=20, b=22)` +`print(结果)` +`return 结果` ``` Semantics: diff --git a/spec/references.md b/spec/references.md index e7220d6..2a5b259 100644 --- a/spec/references.md +++ b/spec/references.md @@ -1,7 +1,9 @@ -# Marqdo References, Imports and Calls v1 +# Marqdo References, Imports and Calls -Status: **frozen for M0.5 except where marked "current limitation".** Language -changes require an ADR plus updated tests. +Status: **current contract; breaking syntax revision (RFC-LANG-0002)**. +Import/reference/call identity, lock and resolution rules are unchanged; the +source spelling of a function heading and a call statement changed. See +`spec/mapping.md` for the current AST→program mapping. Normative implementation: @@ -10,9 +12,9 @@ Normative implementation: | Front matter parsing | `crates/marqdo-markdown/src/frontmatter.rs` | | Module loading, project root, cycles | `crates/cli/src/loader.rs` | | Module/Unit/Function identities | `crates/marqdo-ir/src/lib.rs` | -| Heading scopes, anchors | `crates/marqdo-frontend/src/units.rs` | +| Heading scopes, modes, anchors | `crates/marqdo-frontend/src/units.rs` | | Resource collection and attribution | `crates/marqdo-frontend/src/resources.rs` | -| Link-call mapping | `crates/marqdo-frontend/src/map.rs` | +| Executable payload → statement mapping | `crates/marqdo-frontend/src/map.rs` | | `ref(...)` runtime resolution | `crates/marqdo-runtime/src/builtins_impl.rs` | | Static link graph (`inspect --refs`) | `crates/cli/src/commands.rs` | | Cross-module call validation | `crates/marqdo-frontend/src/calls.rs` | @@ -29,12 +31,14 @@ separate and **only the call edge can execute code**. |---|---|---|---| | **Import** | YAML front matter `import:` mapping | module load / static analysis | No. Imported modules only register definitions; their `main` never runs. | | **Reference** | Markdown `[label](url)` | `inspect --refs` (static graph) | No. Rendered/read as documentation only. | -| **Call** | `> f(...)` block quote, link-form block quote `> [f](#f)(...)`, or a `CallExpr` in an executable payload | static validation, then execution | Yes, at runtime, through the interpreter. | +| **Call** | a `CallExpr` in an executable payload, e.g. `` `f(...)` ``, `**f(...)**`, `*f(...)*` or `> **f(...)**` | static validation, then execution | Yes, at runtime, through the interpreter. | Consequences: * A Markdown link never calls, imports or loads anything. `[计算作用力](#计算作用力)` - is a reference; `> [计算作用力](#计算作用力)()` is a call. + is a reference; `` `计算作用力()` `` in an Exec section is a call. +* The block quote itself never creates a call. `> print(1)` is inert prose; + `> **print(1)**` contains a call payload. * `ref("#anchor")` is a **runtime builtin**, not an import; it only resolves an inert resource or function reference in the running module. * The reference graph is static metadata and creates no proof obligation. @@ -81,10 +85,14 @@ pub struct UnitId { pub module: ModuleId, pub path: Vec } outermost heading to this unit (root unit has an empty path). * Canonical heading names are NFC-normalized, trimmed, with internal whitespace collapsed to one space (`marqdo_markdown::normalize_name`). +* A heading mode declaration (`@exec`/`@knowledge`) is stripped before + normalization. `## @exec main` has the semantic name `main`; the declaration + is never part of a `UnitId`, `FunctionId` or anchor. * `Display` renders `#`; the root unit renders as `#`. -* `UnitKind` is `root`, `namespace` (`#`), `function` (`##`) or `section` - (`###`+). Sections are addressable but not callable. +* `UnitKind` is `root`, `namespace` (`#`), `function` (`##` Exec) or `section` + (`###`+). A Knowledge H2 is an addressable knowledge unit, not a `function`. + Sections are addressable but not callable. ### 2.3 `FunctionId` @@ -101,8 +109,8 @@ pub struct FunctionId { pub module: ModuleId, pub name: String } `local_name`; if several namespaces define the same local name the lookup returns `None` rather than guessing. * No overloads: duplicate canonical names in one scope are hard errors - (`markdown.invalid_construct`, "duplicate heading name ... in the same - scope") and are never auto-suffixed. + (`sem.duplicate_unit_name`, "duplicate heading name ... in the same scope") and + are never auto-suffixed. ### 2.4 Anchors are a separate namespace, not identity @@ -129,7 +137,7 @@ import: util: "./lib/util.mq.md" --- -# main +# @exec main ``` Parsing rules (`crates/marqdo-markdown/src/frontmatter.rs::imports`): @@ -139,6 +147,9 @@ Parsing rules (`crates/marqdo-markdown/src/frontmatter.rs::imports`): * any other front matter key is metadata for tools and is ignored by the interpreter; invalid YAML is a `frontmatter.invalid` diagnostic, never silently dropped; +* the removed `marqdo_semantics`/`syntax` keys are **not** metadata that may be + ignored: seeing them is `sem.unsupported_version_directive` because they + would otherwise look like a syntax selector; * imports are never inferred: a link, a file name or a directory scan does not create an import; * the diagnostic span recorded for all imports of a file is the whole front @@ -271,17 +282,20 @@ Algorithm: Example (from `examples/math.mq.md`): ```markdown -## 圆面积公式 +# @knowledge 数学 + +## @knowledge 圆面积公式 $$ A = \pi r^2 $$ -## 计算圆面积 +## @exec 计算圆面积 -**面积 = math.eval(ref("#圆面积公式"), {"r": 4}, target="A")** +`params(r: Number)` -*面积* +`面积 = math.eval(ref("#圆面积公式"), {"r": r}, target="A")` +`return 面积` ``` `ref("#圆面积公式")` resolves the single formula under that heading; the @@ -298,7 +312,9 @@ formula is still inert until `math.eval` consumes it. | module not present in the program | `symbol.unknown` | `ref.unresolved` (`crates/marqdo-value/src/diagnostic.rs`) is a **compile-time** -code used by link-form call mapping, not by the `ref` builtin. +code used by `check --refs` link validation (and by stale pre-RFC link-call +fixtures), not by the `ref` builtin. There is no link-form call in the current +language. ## 6. Call edges @@ -316,25 +332,26 @@ Static validation (`crates/marqdo-frontend/src/calls.rs`) checks arity, argument names and the named-only rule for inferred signatures. Type errors are runtime concerns in v1. -### 6.2 Block-quote calls +### 6.2 Calls written in payloads -`> f(...)` is a call statement; the payload must parse as a complete -`CallExpr` (see `mapping.md` §4.5). Its result is discarded. +A call is a statement or expression inside an executable payload, for example +`` `f(...)` ``, `**f(...)**`, `*f(...)*` or `> **f(...)**`. Its result is +discarded unless it is used by an assignment or another expression. -Link form `> [label](#anchor)(args)` resolves the link target **within the -current module** using the anchor map, then the canonical unit-name fallback, -and requires the target to be a function unit. Notes: +The old link-form block-quote call (`> [label](#anchor)(args)`) is **removed** +with the previous syntax; a block quote is now an ordinary container and its +plain content is inert. Migrate such a call to an ordinary payload call. If the +target can only be expressed as a link in the old form and no stable function +reference exists, stop and require a manual rewrite; do not generate a call the +new grammar cannot express. -* a zero-argument link call must still write `()`; proxy `> [f](#f)` is a hard - error; -* `http(s)` link targets used as calls are a hard `ref.unresolved` error; - external links are never downloaded or called; -* a relative-path link target such as `> [f](./other.mq.md#f)(x=1)` is - **not supported** in this build: mapping reports `module.unresolved` with - the hint to import the module in front matter and call through its alias. - Cross-module calls therefore go through an alias expression - (`geometry.f(...)`), not through a Markdown link. Blueprint §2.4's - `> [计算面积](./math.mq.md#计算面积)(r=3)` example is a **known divergence**. +Notes: + +* a call expression with no arguments still writes `()`; a bare function value + is not a call; +* `http(s)` link targets are never downloaded or called; +* cross-module calls go through an import alias expression + (`geometry.f(...)`), never through a Markdown link. ### 6.3 Imported alias calls @@ -347,13 +364,22 @@ program is loaded, and emits `symbol.unknown` for an unknown function. | Code | Severity | Where produced | |---|---|---| -| `module.unresolved` | error | loader (bad import target), call mapping (relative-path link call) | +| `module.unresolved` | error | loader (bad import target) | | `module.cycle` | error | loader | -| `ref.unresolved` | error | link-form call target mapping, external links used as calls, `check --refs` link validation | +| `ref.unresolved` | error | `check --refs` link validation, stale link-form call fixtures | | `ref.ambiguous` | runtime error | `ref` builtin (≥ 2 resources) | | `symbol.unknown` | error / runtime error | static call validation; `ref` anchor miss at runtime | | `frontmatter.invalid` | error | analyser (bad YAML/import shape) | -| `markdown.invalid_construct` | error | empty/duplicate heading names, invalid link-call shape | +| `sem.invalid_mode_marker` | error | heading mode declaration (see `mapping.md` §8) | +| `sem.empty_unit_name` | error | heading mode declaration with no name | +| `sem.duplicate_unit_name` | error | duplicate canonical heading/unit name in one scope | +| `sem.exec_without_function` | error | Exec payload with no owning Exec H2 | +| `sem.unsupported_version_directive` | error | legacy `marqdo_semantics`/syntax-selection front matter | + +The previous `markdown.invalid_construct` role errors (Strong/Emph/List/Quote +shape, empty or duplicate heading names) are replaced by the `sem.*` codes and +the heading-name validation in `mapping.md`; runtime shape errors keep their +existing `runtime.*` codes. ## 8. Current limitations (open ADR candidates) @@ -361,10 +387,13 @@ program is loaded, and emits `symbol.unknown` for an unknown function. documented syntax for referencing a resource in an imported module. 2. Ordinary Markdown link resolution is inspection-only; `check` does not validate links and there is no `--refs` flag on `check`. -3. Link-form calls cannot cross modules (see §6.2). +3. Markdown links never call; the removed link-form block-quote call has no + replacement link syntax (use a payload call). 4. Headings inside container blocks or fenced code never create units, and a - heading whose name is empty is a hard error rather than an ignored heading. + heading whose semantic name is empty is a hard error rather than an ignored + heading. 5. Anchor lookup in `ref` does not fall back to canonical unit names, while - link-form calls and `inspect --refs` do. This asymmetry is intentional for - the frozen build but should be unified by a future ADR (it is easy to get - surprising results with headings containing punctuation). + `inspect --refs` does. This asymmetry is intentional for the frozen build + but should be unified by a future ADR. +6. A legacy front matter key such as `marqdo_semantics` is rejected + (`sem.unsupported_version_directive`); it is not a syntax selector. diff --git a/spec/security.md b/spec/security.md index 1510759..d48fb7b 100644 --- a/spec/security.md +++ b/spec/security.md @@ -48,6 +48,15 @@ On a host that cannot create the namespaces the same block is for the Linux construction, L1 scope and non-goals; ADR-0019 still governs every other platform. +### 1.1 `@exec` is not a grant + +The `@exec` heading mode introduced by RFC-LANG-0002 is a **compile-time +projection**, not an authorization. A payload in `@exec` still passes the same +`CapabilityHost` checks, budgets and sandbox rules; a payload in `@knowledge` +produces no IR and therefore cannot cause a host effect at all. No heading +annotation, keyword or Markdown container can grant a file/network/process +capability, and permission flags never change the AST→IR result. + ## 2. Capability grants `Capabilities` (`crates/marqdo-host/src/capability.rs`) is the effective grant diff --git a/spec/trace-v1.md b/spec/trace-v1.md index 5475c48..a84c1df 100644 --- a/spec/trace-v1.md +++ b/spec/trace-v1.md @@ -43,9 +43,9 @@ use UTF-8 byte offsets into the source identified by `source.root_id` and |---|---|---| | `call.enter` | null | function entry; `function_id` is canonical | | `call.exit` | `ok` / `return` / error code | function exit | -| `return` | value type name | explicit `Emph` return; no value content | -| `branch.eval` | `true` / `false` | ordered-list branch condition | -| `loop.iteration` | `continue` / `exit` | bullet-list loop condition | +| `return` | value type name | explicit `return` statement; no value content | +| `branch.eval` | `true` / `false` | `if` condition for an `if/else/end` group | +| `loop.iteration` | `continue` / `exit` | `while` condition for a `while/end` group | | `effect` | result summary | a `HostOp` effect; `operation` names it | Future event kinds are additive. Consumers must ignore unknown kinds rather diff --git a/tools/dev-only/check-mq-syntax.py b/tools/dev-only/check-mq-syntax.py new file mode 100644 index 0000000..d1e82ef --- /dev/null +++ b/tools/dev-only/check-mq-syntax.py @@ -0,0 +1,157 @@ +#!/usr/bin/env python3 +"""Review aid for the RFC-LANG-0002 migration (NOT a parser). + +Checks migrated `.mq.md` files for common mistakes: + * unclosed/unmatched if/else/while/end inside an executable segment; + * `if`/`while`/`return` without an expression; `else`/`end` with trailing text; + * semicolon-separated statements in one payload; + * unknown `sem.*` codes in negative expected JSON. + +It intentionally ignores Knowledge sections and does not try to be a +normative validator; the Rust frontend migration must provide the real +validation. Usage: python3 tools/dev-only/check-mq-syntax.py ... +""" +from __future__ import annotations +import json +import re +import sys +from pathlib import Path + +KNOWN_SEM = { + "sem.invalid_mode_marker", "sem.empty_unit_name", "sem.duplicate_unit_name", "sem.exec_without_function", + "sem.payload_nested", "sem.empty_payload", "sem.syntax", "sem.unmatched_else", + "sem.duplicate_else", "sem.unmatched_end", "sem.unclosed_control", + "sem.signature_position", "sem.unsupported_version_directive", + "sem.no_entry_function", "sem.inferred_signature", +} +HEADING = re.compile(r"^(#{1,6})\s+(.*)$") +MODE = re.compile(r"^@(exec|knowledge)\b\s*(.*)$") + + +def payload_of(line: str): + s = line.strip() + while True: + n = re.sub(r"^(?:>|[-+*]\s+|\d+[.)]\s+)", "", s).strip() + if n == s: + break + s = n + if len(s) >= 4 and s.startswith("**") and s.endswith("**") and "**" not in s[2:-2]: + return s[2:-2] + if len(s) >= 2 and s.startswith("*") and s.endswith("*") and not s.startswith("**") and "*" not in s[1:-1]: + return s[1:-1] + m = re.match(r"^(`+)(.*)\1$", s, re.S) + if m: + return m.group(2) + return None + + +def check(path: Path) -> list[str]: + errors: list[str] = [] + stack: list[tuple[str, int]] = [] + headings: list[tuple[int, str | None, int]] = [] # level, explicit mode + segment = "root" + + def effective(level: int) -> str: + for hl, mode, _ln in reversed(headings): + if hl < level: + if mode: + return mode + # continue to a higher explicit ancestor + return "knowledge" + + def close_segment(line: int) -> None: + nonlocal stack + if stack: + kind, op = stack[-1] + errors.append(f"{path}:{line}: unclosed {kind} from line {op} in {segment}") + stack = [] + + for i, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1): + m = HEADING.match(raw) + if m: + close_segment(i) + level, body = len(m.group(1)), m.group(2) + mm = MODE.match(body) + mode = mm.group(1) if mm else None + name = mm.group(2).strip() if mm else body.strip() + if mm and not name: + errors.append(f"{path}:{i}: mode without heading name") + if not mm and re.match(r"^@[A-Za-z]", name): + errors.append(f"{path}:{i}: unknown mode marker {name.split()[0]}") + while headings and headings[-1][0] >= level: + headings.pop() + headings.append((level, mode, i)) + segment = f"H{level} {name}" + continue + text = payload_of(raw) + if text is None: + continue + text = text.strip() + if not text: + errors.append(f"{path}:{i}: empty executable payload") + continue + owning = False + for hl, _mode, _ln in reversed(headings): + if hl == 2: + owning = effective(2) == "exec" + break + if not owning: + continue + if ";" in text: + errors.append(f"{path}:{i}: semicolon in one payload: {text!r}") + first = text.split(None, 1)[0] + if first in ("if", "while"): + if len(text.split()) == 1: + errors.append(f"{path}:{i}: {first} without expression") + stack.append((first, i)) + elif first == "else": + if text != "else": + errors.append(f"{path}:{i}: else with trailing tokens") + if not stack or not stack[-1][0].startswith("if"): + errors.append(f"{path}:{i}: unmatched else") + elif stack[-1][0] == "if_else": + errors.append(f"{path}:{i}: duplicate else") + else: + stack[-1] = ("if_else", stack[-1][1]) + elif first == "end": + if text != "end": + errors.append(f"{path}:{i}: end with trailing tokens") + if not stack: + errors.append(f"{path}:{i}: unmatched end") + else: + stack.pop() + elif first == "return" and len(text.split()) == 1: + errors.append(f"{path}:{i}: return without expression") + elif first == "params" and not re.match(r"^params\s*\(.*\)$", text, re.S): + errors.append(f"{path}:{i}: malformed params") + close_segment(len(headings) + 1) + return errors + + +def main(argv: list[str]) -> int: + roots = [Path(a) for a in argv] or [Path("tests"), Path("examples")] + failures: list[str] = [] + count = 0 + for root in roots: + paths = [root] if root.is_file() else sorted(root.rglob("*")) + for path in paths: + if path.name.endswith(".mq.md"): + count += 1 + failures.extend(check(path)) + elif path.suffix == ".json" and "negative" in path.as_posix(): + try: + data = json.loads(path.read_text(encoding="utf-8")) + except Exception as error: # noqa: BLE001 - review aid + failures.append(f"{path}: invalid JSON: {error}") + continue + for code in data.get("codes", []): + if code.startswith("sem.") and code not in KNOWN_SEM: + failures.append(f"{path}: unknown sem code {code}") + for failure in failures: + print(failure) + print(f"checked {count} .mq.md files, {len(failures)} issue(s)") + return 1 if failures else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/tools/dev-only/gen-migration-inventory.py b/tools/dev-only/gen-migration-inventory.py new file mode 100644 index 0000000..eb0e0ca --- /dev/null +++ b/tools/dev-only/gen-migration-inventory.py @@ -0,0 +1,171 @@ +#!/usr/bin/env python3 +"""Generate docs/migration/semantic-rewrite-inventory.tsv. + +The inventory classifies every git-tracked file for the RFC-LANG-0002 +single-syntax migration. It is a repository audit aid, not a compiler and not +a substitute for `cargo test` or the real frontend. +""" +from __future__ import annotations +import re +import subprocess +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +OLD_MARKERS = re.compile( + r"^##\s+[^@\s].*$|^\*[^*\n].*\*$|^\*\*[^*\n].*\*\*$|" + r"markdown\.inert_executable|markdown\.invalid_construct|" + r"marqdo_semantics|--legacy|map_v1", + re.M, +) +NEW_MARKERS = re.compile(r"@exec|@knowledge") +FRONTEND = { + "crates/marqdo-frontend/src/units.rs", + "crates/marqdo-frontend/src/map.rs", + "crates/marqdo-frontend/src/payload.rs", + "crates/marqdo-frontend/src/signature.rs", + "crates/marqdo-frontend/src/analyze.rs", + "crates/marqdo-expression/src/lexer.rs", + "crates/marqdo-expression/src/parser.rs", + "crates/marqdo-expression/src/ast.rs", + "crates/marqdo-ir/src/lib.rs", +} + + +def tracked() -> list[str]: + """Tracked files plus untracked-but-not-ignored files. + + The migration adds new fixtures/docs before they are committed; an inventory + that only reads `git ls-files` would silently omit them. + """ + listed = subprocess.run( + ["git", "ls-files"], cwd=ROOT, check=True, text=True, capture_output=True + ).stdout.splitlines() + untracked = subprocess.run( + ["git", "ls-files", "--others", "--exclude-standard"], + cwd=ROOT, + check=True, + text=True, + capture_output=True, + ).stdout.splitlines() + return sorted({line for line in listed + untracked if line}) + + +def deleted() -> set[str]: + out = subprocess.run( + ["git", "ls-files", "--deleted"], cwd=ROOT, check=True, text=True, capture_output=True + ).stdout + return {line for line in out.splitlines() if line} + + +def changed() -> set[str]: + out = subprocess.run( + ["git", "status", "--porcelain"], cwd=ROOT, check=True, text=True, capture_output=True + ).stdout + result = set() + for line in out.splitlines(): + if len(line) > 3: + result.add(line[3:].strip()) + return result + + +def classify(path: str, changed_set: set[str]) -> tuple[str, str, str, str, str, str, str]: + """Return category, active, old_semantics, action, owner, verification, status.""" + p = Path(path) + text = "" + full = ROOT / path + if full.is_file() and full.stat().st_size < 2_000_000: + try: + text = full.read_text(encoding="utf-8") + except UnicodeDecodeError: + text = "" + is_changed = path in changed_set + + if path == "docs/adr/0052-unified-markdown-semantics.md": + return ("decision", "yes", "old mapping", "adopt current language decision", "docs", "review", "migrated") + if path == "docs/adr/README.md": + return ("decision", "yes", "n/a", "index current decisions/history", "docs", "review", "migrated") + if path == "docs/evidence/2026-11-21-semantic-docs-migration.md": + return ("evidence", "yes", "old syntax", "record migration evidence", "docs", "docs_consistency", "migrated") + if path.startswith("docs/adr/"): + return ("historical", "no", "decision at its date", "banner if syntax-role", "docs", "review", "historical") + if path.startswith("docs/history/") or path.startswith("docs/evidence/"): + return ("historical", "no", "archived", "banner only", "docs", "review", "historical") + if path.startswith("docs/migration/"): + return ("migration", "yes", "n/a", "maintain inventory/guide", "docs", "review", "migrated") + if path.startswith("docs/architecture/RFC-LANG-0002"): + return ("architecture", "yes", "old mapping", "adopt as sole authority", "docs", "review", "migrated") + if path.startswith("docs/architecture/Marqdo_CLI_Latest"): + return ("architecture", "no", "review input", "historical banner", "docs", "review", "historical") + if path.startswith("docs/architecture/"): + return ("architecture", "yes", "status/index", "update to RFC-LANG-0002", "docs", "docs_consistency", "migrated") + if path.startswith("docs/MARQDO_COMPUTE"): + return ("architecture", "yes", "compute RFC", "migrate examples / mark historical spelling", "docs", "review", "migrated") + if path.startswith("docs/"): + if is_changed: + return ("tutorial", "yes", "old mapping", "rewrite + historical banner where needed", "docs", "docs_consistency", "migrated") + return ("tutorial", "yes", "none", "reviewed", "docs", "review", "reviewed") + if path.startswith("spec/"): + return ("spec", "yes", "old mapping", "in-place rewrite", "language", "cargo test / review", "migrated") + if path.endswith(".mq.md"): + if path.startswith("stdlib/"): + return ("stdlib", "yes", "old syntax", "migrate with frontend + digest", "stdlib", "stdlib_product", "pending-implementation") + if path.startswith("tests/conformance/ast/"): + return ("test", "yes", "Markdown AST only", "keep AST baseline", "tests", "conformance_ast", "reviewed") + if path.startswith("tests/negative/"): + return ("test", "yes", "old negative shape", "rebuild for sem.* diagnostics", "tests", "negative", "migrated") + if path.startswith("examples/"): + return ("example", "yes", "old syntax", "migrate source", "examples", "examples_r6 / run", "migrated") + if NEW_MARKERS.search(text): + return ("test", "yes", "old syntax", "migrate source", "tests", "conformance/negative", "migrated") + return ("test", "yes", "old syntax", "needs migration", "tests", "review", "pending") + if path.startswith("tests/"): + if is_changed: + return ("test", "yes", "old syntax", "migrate source/expectations", "tests", "negative/properties", "migrated") + return ("test", "yes", "harness", "review", "tests", "review", "reviewed") + if path.startswith("crates/"): + if path in FRONTEND: + return ("rust-source", "yes", "old mapping", "implement RFC-LANG-0002", "language", "cargo test", "pending-implementation") + if "/tests/" in path or path.endswith("/tests.rs"): + return ("rust-test", "yes", "embedded old syntax", "migrate embedded .mq.md strings", "language", "cargo test", "migrated" if is_changed else "reviewed") + if is_changed: + return ("rust-source", "yes", "embedded text/help", "migrate embedded .mq.md text only", "language", "cargo test", "migrated") + return ("rust-source", "yes", "not syntax-bearing", "review", "language", "cargo test", "reviewed") + if path.startswith("stdlib/"): + return ("stdlib", "yes", "old syntax", "migrate with frontend + digest", "stdlib", "stdlib_product", "pending-implementation") + if path.startswith("tools/"): + return ("tooling", "yes", "migration aid", "review", "docs", "review", "reviewed") + if path.startswith("examples/"): + return ("example", "yes", "old syntax", "review", "examples", "run", "reviewed") + if path in {"README.md", "COMPATIBILITY.md", "CHANGELOG.md", "AGENTS.md"}: + return ("tutorial", "yes", "old mapping", "rewrite", "docs", "review", "migrated") + return ("non-semantic", "no", "none", "none", "-", "n/a", "reviewed") + + +def main() -> int: + changed_set = changed() + deleted_set = deleted() + rows = [] + for path in tracked(): + if path in deleted_set: + continue + rows.append((path, *classify(path, changed_set))) + rows.sort(key=lambda row: row[0]) + out = ROOT / "docs/migration/semantic-rewrite-inventory.tsv" + with out.open("w", encoding="utf-8", newline="\n") as handle: + handle.write( + "path\tcategory\tactive\told_semantics\taction\towner\tverification\tstatus\n" + ) + for row in rows: + handle.write("\t".join(row) + "\n") + counts: dict[str, int] = {} + for row in rows: + counts[row[-1]] = counts.get(row[-1], 0) + 1 + print(f"wrote {out} ({len(rows)} rows)") + for status, count in sorted(counts.items()): + print(f" {status}: {count}") + return 0 + + +if __name__ == "__main__": + sys.exit(main())