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:
cflmy committed 2026-11-21 12:24:19 +08:00
1 parent 0d8ed44010
commit 49835424ee
47 files changed
+4941 -603

No files matched your search

+12 -5
View File
@@ -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
View File
@@ -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 安全功能矩阵 |
+12 -2
View File
@@ -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. 重构目标架构、仓库组织与实际代码改动
+33 -21
View File
@@ -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 的赋值与复制行为。
- 运行跨区域隔离与别名测试;报错不能导致原有区域被污染。
+47 -23
View File
@@ -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` 找到所有副作用检查。
+57 -36
View File
@@ -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 干净安装、
+10
View File
@@ -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
View File
@@ -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
+11
View File
@@ -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
+8
View File
@@ -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.
+33
View File
@@ -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
View File
@@ -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
View File
@@ -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
+9
View File
@@ -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.
+9
View File
@@ -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`.
+177
View File
@@ -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
View File
@@ -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)"
+11
View File
@@ -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),
+7
View File
@@ -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.