docs(spec): adopt RFC-LANG-0002 unified language semantics
Replace the Strong/Emph/List/Quote mapping in place with the single @exec/@knowledge heading-mode model, unified payload carriers and keyword control flow. - add the authoritative RFC, ADR-0052 and a historical ADR index - rewrite spec/mapping.md and spec/expression.ebnf as the normative mapping/statement grammar; update evaluation, references, math, foreign, package-format, plugin-abi, security and schema notes - rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking language change; update the architecture index/overview and active docs - mark superseded planning docs, compute RFCs, evidence and syntax-role ADRs as historical/superseded without rewriting their decisions - add migration guide, per-file inventory and dev-only audit scripts The frontend/stdlib migration is completed in the following commits; this commit contains documentation only.
This commit is contained in:
1 parent
0d8ed44010
commit
49835424ee
47 files changed
+4941
-603
No files matched your search
@@ -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.
|
||||
+71
-2
@@ -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 <expr>` 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 <expr>` 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.
|
||||
|
||||
|
||||
+45
-3
@@ -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.
|
||||
|
||||
@@ -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 <Bool>`, `else`, `while <Bool>`, `end`,
|
||||
`return <expr>`, `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
|
||||
|
||||
@@ -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。
|
||||
|
||||
|
||||
+116
-107
@@ -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 <expr>` 打开 `Branch`,`else` 切换最近尚未关闭的 `if` 的 else 分支,`while <expr>` 打开 `Loop`,`end` 关闭最近的 `if`/`while`,`return <expr>` 产生 `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 安全功能矩阵 |
|
||||
|
||||
@@ -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 行为,保留要以维护收益证明;公开主线禁止因此增加更多命令。删除时提供对应的文档内替代方式,避免把重要能力一起删除。
|
||||
|
||||
|
||||
@@ -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. 重构目标架构、仓库组织与实际代码改动
|
||||
|
||||
@@ -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 的赋值与复制行为。
|
||||
- 运行跨区域隔离与别名测试;报错不能导致原有区域被污染。
|
||||
|
||||
|
||||
@@ -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 <command>`。`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 <expr>` … `end`,列表只是容器。旧“`OrderedList` 首段 CodeSpan 条件头”规则已被 RFC-LANG-0002 废止;普通列表在 Exec 范围内按源序提取合法载荷,零语句投影是合法惰性结构。
|
||||
- 循环写 `while <expr>` … `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` 找到所有副作用检查。
|
||||
|
||||
@@ -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 干净安装、
|
||||
|
||||
@@ -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)。
|
||||
|
||||
+24
-8
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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 等均有测试。
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
+10
@@ -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
|
||||
|
||||
+78
-28
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -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 <expr>` … `[else]` … `end`; `while <expr>` … `end`.
|
||||
A control block never crosses a heading. `return <expr>` 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.
|
||||
File diff suppressed because it is too large.
Load diff
+12
-1
@@ -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)"
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+6
-1
@@ -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
|
||||
|
||||
+68
-16
@@ -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. *)
|
||||
+7
-5
@@ -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
|
||||
|
||||
+355
-208
@@ -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 <expr> else while <expr> end
|
||||
return <expr> 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.
|
||||
@@ -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. |
|
||||
|
||||
+7
-4
@@ -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
|
||||
|
||||
@@ -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/`;
|
||||
|
||||
+4
-4
@@ -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:
|
||||
|
||||
+70
-41
@@ -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<String> }
|
||||
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 `<module>#<path joined by '/'>`; the root unit renders as
|
||||
`<module>#`.
|
||||
* `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.
|
||||
@@ -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
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
@@ -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 <dir>...
|
||||
"""
|
||||
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:]))
|
||||
@@ -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())
|
||||
Reference in new issue
Block a user