release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated Cargo.lock; project.marqdo is enforced against the running core with package.marqdo_range_invalid/package.marqdo_incompatible fail-closed diagnostics; Tool SemVer prerelease negotiation tests; init template and examples use the beta range. Verify init derives the project name from the target directory instead of falling back to 'example'. REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for the release evidence. REL-03: deterministic release packaging (tools/release/package.py) ships the CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json, known-limitations, specs, developer docs, examples incl. built plugin/provider artifacts and consumers; tools/release/smoke.py cold-install tests the archive. REL-04: docs/developers entry pages; corrected and self-contained third-party integration handbook; stale Proposed/native-only/informational spec claims fixed; release/status/compatibility/changelog/releasing docs updated. REL-05: release_evidence.py gains an explicit beta profile (BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build step now packages and smoke-tests the archive on every pipeline. Adds a runnable Resource Provider v2 example and corrects check --emit to Analysis v2.
This commit is contained in:
1 parent
56189b176c
commit
2c7c4f31e7
55 files changed
+3136
-453
No files matched your search
@@ -0,0 +1,120 @@
|
||||
# RFC-REL-0001 — Marqdo 3.0 预发布路线、发布门禁与 LTS 策略(建议草案)
|
||||
|
||||
> 状态:**Adopted as the release policy for `3.0.0-beta.1`**(2026-11-22)。REL-01~REL-05 已按本文实施;实际门禁结果记录在 `docs/STATUS.md`、`docs/evidence/` 和 `docs/evidence/ci/<release-sha>/manifest.json`。
|
||||
> 代码核对基线(提议时):`cflmy/marqdo-cli@56189b176c612bf399ff965c3b642077f6b04617`,2026-11-22;§2 的“剩余门禁”表是迁移前快照,当前事实以 `docs/STATUS.md` 为准。
|
||||
> 现有发布依据:`docs/releasing.md`、`docs/STATUS.md`、`COMPATIBILITY.md`、`spec/extension-selection.md`、`spec/callable-resolution.md`。
|
||||
> 本文是策略与门禁定义;**tag 只能在该 SHA 的全部门禁通过后创建**,本文本身不构成任意 SHA 的发布批准。
|
||||
|
||||
## 1. 产品定位和版本结论
|
||||
|
||||
- 旧 `cflmy/marqdo` 已发布至 `v2.9.1`,新的 `marqdo-cli` 是同一品牌下的**语言重实现与破坏性架构更新**,不是旧 CLI 的逐项兼容升级。
|
||||
- 公开产品版本可从 `3.0.0-beta.1` 起步;`3.0.0` 不带后缀应留给稳定版。Rust 工作区、CLI `--version`、Analysis `producer.version`、Tool 版本协商均应反映该版本。
|
||||
- 使用一个仓库作为 3.x 官方主实现;旧仓库保留历史与迁移链接,**不声称源文件、插件 ABI、lockfile 兼容**。
|
||||
- 正式提供持续维护承诺之前,不应把任何 Beta 或 RC 称为 LTS。建议待稳定的 `3.0.0`、`3.1.x` 实际使用数据验证后,再考虑把 `3.2.x` 设为第一条 LTS;是否能以此命名取决于质量门禁,而不是预定日历。
|
||||
|
||||
## 2. 已核实事实与剩余门禁
|
||||
|
||||
| 事项 | 基线证据 | 结论 |
|
||||
|---|---|---|
|
||||
| 语言执行语义 | RFC-LANG-0002、ADR-0052、现有测试 | 已实现、破坏性,不允许旧语法自动降级 |
|
||||
| 外部插件与 Provider | ADR-0054~0058、`spec/resource-provider-v2.md`、`spec/extension-selection.md` | 核心路径已实现;Provider Worker 仅宣称 Linux x86_64 |
|
||||
| 独立扩展验收 | `docs/evidence/extension/6a7bb983.../manifest.json`:7 项 PASS | 证据只绑定旧 SHA `6a7bb98`,需在发布提交重跑 |
|
||||
| CI | `actions/runs/44928442709`,SHA `56189b1` | Linux、Windows、macOS 各运行契约 PASS;tag 发行包任务因未打 tag 而 SKIPPED |
|
||||
| strict/G3 | `actions/runs/44928442715` 查询时 queued;本地隔离 VM 历史 PASS | 发布 SHA 缺远程 G3 证据;不可声称整个 strict 已认证 |
|
||||
| G4 | `docs/evidence/2026-11-21-perf-woodpecker-agent-1.md` | 9/9 结果正确,固定 agent 两次 5 warmup / 20 样本;共享 powersave 环境,WARN、旧 SHA |
|
||||
| 公开版本 | `Cargo.toml` 仍为 `0.1.0`,若干工具兼容样例 `<1` | 3.0.0-beta 发布前必须迁移验证 |
|
||||
| 第三方入门 | README 有扩展示例、`spec/` 有协议;Tool v1 标头仍称 Proposed,plugin spec 某段称 Native only | 需要整合并去除失效状态文本 |
|
||||
|
||||
## 3. 两套必须明确分开的发布策略
|
||||
|
||||
### 3.1 Beta(允许明确声明的非安全性缺口)
|
||||
|
||||
目标平台为 **Linux x86_64**;其他平台的核心 CLI 测试结果可以公开说明,但不默认提供支持声明。所有清单要公开写明平台、功能和限制。
|
||||
|
||||
**不可豁免的 Beta 门禁:**
|
||||
|
||||
1. 在清洁、固定的同一提交(发布 SHA)上:`cargo fmt --all -- --check`、`cargo clippy --workspace --all-targets -- -D warnings`、`cargo test --workspace --locked`、`cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker` 全部通过。
|
||||
2. GitHub 最新同 SHA 的 Linux 主 CI PASS;发布产物中 `marqdo` 与同平台 `marqdo-provider-worker` 同目录,不允许只打包 CLI。
|
||||
3. 冻结 CLI 的外部仓库黑盒验收在**发布 SHA**重新执行,至少 pure pinned-Git 包、Callable Worker、陌生 Foreign Kernel、Provider v2、Tool/Analysis/Trace、权限负例及工件改动负例全部 PASS;生成并校验 `docs/evidence/extension/<SHA>/manifest.json`。
|
||||
4. 冷安装、离线 `--version`/`--help`、`check/run/call`、lock/sync、Tool 安装与分发、Provider Worker 启动、错 SHA/错目标/未授权拒绝全部由发布归档中的**实际二进制**完成;不得依赖开发源码目录。
|
||||
5. **不得虚假宣传安全隔离。** 发布包若保留并开放 Linux `strict`,必须有该 SHA 的真实 G3 隔离负例证据;若暂无证据,需采用明确经过测试的 fail-closed 禁用方式并在公告中写 `strict: unsupported`。不允许仅改 README 却继续将未验证的 `strict` 描述为安全保障。Beta 的这一策略必须经维护者明确签字并由 CI 可复查。
|
||||
6. G4 基准不得造假;若当期固定节点仍是 WARN,可由维护者批准 **Beta-only WARN** 并公开环境和限制;必须通过 9 个正确性基准,不允许数值漂移或已确认的灾难性回退。
|
||||
7. 明确产品版本 `3.0.0-beta.1` 与协议独立版本;工具 SemVer 协商在真实测试版上可安装、拒绝不兼容范围、不会误把 `<1` 当成支持 3.x。
|
||||
8. `README`、`CHANGELOG`、`COMPATIBILITY`、`docs/STATUS`、`docs/releasing`、协议入口页、迁移说明,均更新至同一事实基线;无“未实现却声称已发布”或“已实现仍称 Proposed”的矛盾。
|
||||
9. 不发布未经实际构建/烟测的平台二进制;产物附 SHA256、SOURCE_SHA、构建工具链信息和已知限制。
|
||||
|
||||
**可延期至后续 Beta 或稳定版:** Windows Native/Worker ABI、macOS Provider Worker、strict L2、uv/npm 自动建环境、分布式 registry、JIT、内置 Knowledge/Proof/View、成熟异步/并发模型、未经承诺的平台安装包。明确注明项目默认 `project` 模式不是 OS 沙箱,Worker 也不是完整沙箱。
|
||||
|
||||
### 3.2 Stable / LTS(不可用 Beta 例外替代)
|
||||
|
||||
- Stable `3.0.0`:在公开支持的 Linux 平台上所有承诺功能有安全/兼容/性能证据;公开协议与变更策略清楚;有迁移说明和至少一次真实使用者反馈周期。平台可继续限定 Linux,不要求通过虚假的“全平台 LTS”门禁。
|
||||
- LTS(建议后续 `3.2.x`):冻结 `.mq.md` 语言语义、Analysis/Trace/Tool/Plugin/Provider 各自协议主版本和 lockfile 契约;提供安全修复流程、回归 CI、外部仓库兼容矩阵、从 3.0 及 2.9 迁移材料、发布渠道与公告模板。
|
||||
- LTS 应提前承诺支持窗口(建议至少 12 个月,实际长短由维护资源决定),定义安全补丁与非破坏性修复回移规则,明确 API/ABI 哪些会不兼容;不因开发完成某一里程碑自动称 LTS。
|
||||
- 默认不为旧 `cflmy/marqdo` 的历史语法或旧插件 ABI 建隐性兼容层。需要迁移的由独立迁移工具、教程和示例承担。
|
||||
|
||||
## 4. 3.0.0-beta.1 之前建议拆分的 5 个短 PR
|
||||
|
||||
**REL-01:全仓版本线迁移(强制)**
|
||||
- 将 Cargo workspace 包的产品版本改为 `3.0.0-beta.1`,更新 Cargo.lock 与 crate 编译产物;不必将 *独立协议版本*、依赖包版本、官方 stdlib 版本一并改为 3。
|
||||
- 扫描 `0.1.0`、`>=0.1,<1`、`M0.5`、`pre-1.0` 等在发行说明、JSON schema consumer、Tool fixture、示例、CI 中是 **产品版本**还是 **独立包/协议版本**。逐项更新,严禁盲目全局替换。
|
||||
- `project.marqdo` 目前文档注明仅 informational;为未来稳定兼容,建议在 Beta 之前增加**显式版本范围的检查**,最少在不兼容时发出清晰诊断并在 Beta 正式版前确保 fail-closed;编写对应正负测试。如果无法实现,必须写明 Beta 不保证该字段生效。
|
||||
- 为使用 `semver::VersionReq` 的 Tool manifest 添加 `>=3.0.0-beta.1,<4.0.0` 等真实候选测试,并确保带预发布后缀的版本匹配符合 SemVer 语义。
|
||||
|
||||
**REL-02:测试版支持矩阵与安全策略(强制)**
|
||||
- 发布声明只选自己真实能够测试和修复的平台。建议首发 Linux x86_64,其他平台根据可运行烟测增列为 Experimental。
|
||||
- 为 `strict` 选择:A. 当 SHA 的 G3 真实通过则在 Linux 标为实验性 probe-gated;B. 若无,则构建/配置和端到端测试保证 **fail closed**,公开标为不支持。禁止“默默降级到 project”。
|
||||
|
||||
**REL-03:全量发行归档与冻结二进制(强制)**
|
||||
- `cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker`。
|
||||
- 打包 `marqdo` + `marqdo-provider-worker`、文档/许可证/协议/必要示例,清洁目录安装后测试;两者同目标 triple、版本、来源 SHA;检查归档 SHA256。
|
||||
- 在干净外部仓库重复黑盒套件,证据绑定发行 SHA 和精确二进制 hash;至少做未授权和工件篡改的消极测试。
|
||||
|
||||
**REL-04:开发者入口文档(强制)**
|
||||
- `docs/developers/README.md`、`quickstart.md`、`tools.md`、`libraries.md`、`extensions.md`、`analysis-trace.md`、`compatibility.md`;与 `spec/` 的规范性协议以链接方式衔接,避免复制分叉契约。
|
||||
- 设置 `marqdo view/knowledge/prove` 作为 Tool 使用的示例,并将其作为外部仓库模板,而不是 CLI 内置命令。
|
||||
- 修复 `spec/tool-v1.md` 的 Proposed 状态和 `spec/plugin-abi.md` 的 Native-only 旧说法;修复旧版发布指令、样例 version、已过时的 G3/G4 状态。
|
||||
|
||||
**REL-05:Beta Release Candidate 审批(强制)**
|
||||
- 切 release candidate SHA,再跑所有必需门禁,不在验证期间继续修改同一版本的内容;必要变更形成下一 SHA 并重跑。
|
||||
- 将稳定版发布策略与 Beta 策略分别标记和自动验证,不用一个 `DO_NOT_RELEASE` 字段悄悄代表两种不同门槛。
|
||||
- 维护者明确批准 `v3.0.0-beta.1` 标签和 GitHub prerelease(`prerelease: true`),不要把测试版误当正式发布或 LTS。保留回滚/撤回方案与已知限制。
|
||||
|
||||
## 5. 建议的版本线(条件性,不是承诺日程)
|
||||
|
||||
| 版本 | 目的 | 进入条件 |
|
||||
|---|---|---|
|
||||
| `3.0.0-beta.1` | 发布真正可运行、可接第三方库的新语言基线 | 上述 Beta gate 全绿或明确允许的非安全性 WARN |
|
||||
| `3.0.0-beta.2` | 修复外部消费者、协议示例及安装包问题 | 跨仓回归全部 PASS,收集第一轮外部反馈 |
|
||||
| `3.0.0-rc.1` | 冻结最小公共契约和平台支持范围 | 不再新增破坏语义;发布契约全部文档化 |
|
||||
| `3.0.0` | 3.x 稳定版 | 公开承诺范围内的 release gate 完整 PASS |
|
||||
| `3.1.x` | Tools/Knowledge/View/Proof 实际生态检验 | 外部仓库无核心改动迭代,公共协议更成熟 |
|
||||
| `3.2.x LTS`(候选) | 长期支持分支 | 真实跨版本兼容证明、安全更新流程、明确维护窗口 |
|
||||
|
||||
**建议首先冻结而不强求全部功能成熟的内容**:RFC-LANG-0002 的语义;Analysis v2、Trace v2、Tool v1、Plugin ABI v1、Provider v2、lock v4 的**当前定义**。未来不兼容修改应提升**对应协议版本**,不能因为产品叫 3.0 就把所有协议号写成 3。
|
||||
|
||||
## 6. 发版前必须人工审阅的风险
|
||||
|
||||
- 原始 `docs/releasing.md` 按稳定版执行,对 Beta 需要新增经批准的 `prerelease` profile,不能在脚本中硬关门禁。
|
||||
- GitHub Push CI 成功但 Release Artifact job 因没有 tag/workflow_dispatch 而跳过,属于正常条件流程,不是产物已验证。
|
||||
- 当前冻结二进制外部证据绑定 `6a7bb98`,与最新 `56189b1` **不一致**,需重跑。
|
||||
- 原始 `spec/tool-v1.md` 文件标头仍写 Proposed(源码已实现);`spec/plugin-abi.md` 第 9 节开头仍声称“Native only”;README 开头仍保留旧里程碑状态与测试数字。公共入口不能带这些明显冲突。
|
||||
- 版本从 0.x 改 3.0 prerelease 后,插件 manifest `plugin.version` 与产品 version、官方 stdlib version、协议 schema version 并不是同一个版本轴;必须在发布和升级说明中画清楚。
|
||||
- 第三方 GitHub/GitLab/Gitea 源、工具二进制和 Provider SHA256 只能验证内容完整性,不提供出版者身份保证;不能把它当签名来源认证。
|
||||
|
||||
## 6.1 实施状态(3.0.0-beta.1)
|
||||
|
||||
| 条目 | 状态 | 落点 |
|
||||
|---|---|---|
|
||||
| REL-01 版本线迁移 | 已实施 | workspace/CLI/Analysis `3.0.0-beta.1`;`project.marqdo` 强制校验;工具预发布 SemVer 正负测试 |
|
||||
| REL-02 支持矩阵与 strict 策略 | 已实施 | Linux x86_64 支持;macOS/Windows 实验性不声称;strict 同 SHA VM 证据或 fail-closed 策略记录在 STATUS |
|
||||
| REL-03 发行归档与冻结二进制 | 已实施 | `tools/release/package.py`、`tools/release/smoke.py`;归档含 CLI+worker、SOURCE_SHA、RELEASE_INFO、KNOWN_LIMITATIONS |
|
||||
| REL-04 开发者入口文档 | 已实施 | `docs/developers/`、修正后的第三方接入手册、spec 状态清理 |
|
||||
| REL-05 Beta RC 审批 | 已实施 | `tools/ci/release_evidence.py --profile beta`、`v3.0.0-beta.1` tag/prerelease、rollback 与已知限制 |
|
||||
|
||||
## 7. 最终判定公式
|
||||
|
||||
Beta = `同 SHA 主 CI PASS` + `同 SHA 冻结二进制外部扩展 PASS` + `Linux 安装包 PASS` + `版本兼容 PASS` + `清晰支持矩阵` + `严格安全门禁(G3 实证或 strict fail-closed 禁用)` + `维护者批准`。
|
||||
|
||||
Stable = 上述条件 + 所承诺功能的完整安全/性能门禁 + 公共接口与迁移政策冻结。
|
||||
|
||||
LTS = Stable + 已经历真实生态版本迭代 + 可持续的安全补丁/兼容性维护承诺。
|
||||
@@ -0,0 +1,506 @@
|
||||
# Marqdo 3.x 第三方开发者接入手册
|
||||
|
||||
> 状态:**随 `3.0.0-beta.1` 发布**(Linux x86_64 beta)。产品版本为 `3.0.0-beta.1`;协议版本独立:Analysis v2、Trace v2、Tool v1、Plugin ABI v1、Foreign wire v1、Provider manifest v2、Lock v4、Markdown profile `marqdo.md.v1`。官方 stdlib 包版本 `0.1.0`、插件/工具/示例包版本也都是独立版本轴,不随产品版本变化。
|
||||
>
|
||||
> 本文是入门与工程接洽流程;与已发布二进制冲突时,以该版本 `--help`、`--version`、`spec/` 和 release notes 为准。本文所有命令片段都已在 `3.0.0-beta.1` 二进制上验证;未验证的可能平台行为会明确标注为 UNVERIFIED/UNSUPPORTED,绝不默认为支持。
|
||||
|
||||
配套入口:[`developers/README.md`](developers/README.md)(按任务分拆的
|
||||
quickstart/libraries/tools/extensions/analysis-trace/compatibility)和
|
||||
[`developers/release-limits.md`](developers/release-limits.md)(beta 限制)。
|
||||
|
||||
## 0. 快速定位:你要开发的是什么?
|
||||
|
||||
| 目标 | 必须使用的扩展入口 | 可否完全独立于核心仓库 | 第三方主要交付物 |
|
||||
|---|---|---|---|
|
||||
| 普通 AI、数学、量子算法、SKILL、数据处理 | Marqdo `.mq.md` 包 | 是 | `index.mq.md`、`marqdo.yaml`、README、fixtures |
|
||||
| 知识分析、Proof、View、IDE、Lint 等外部工具 | CLI Tool Protocol v1 | 是 | 独立可执行程序、`tool.json`、Analysis/Trace 消费者 |
|
||||
| 高性能原生算法/量子门适配函数 | Callable Plugin ABI v1 | 是(遵循 ABI) | `plugin.yaml`、目标平台动态库、C header/SDK |
|
||||
| 新的 Python/R/Julia 等外语执行后端 | Foreign Kernel | 是(遵循 wire) | `kernel.json`、可执行 provider、固定环境 |
|
||||
| 硬件资源、数据库会话、外部流设备 | Resource Provider v2 | 是(遵循别名协议) | `provider.json`、C ABI library(`marqdo-provider-worker` 由 CLI 发行包提供,不随扩展分发) |
|
||||
| 改变 `@exec` 语义、增添 `if` 关键字/原生数值类型 | 正式语言 RFC | **不是**第三方扩展 | core 变更 + 迁移 + 完整语言一致性测试 |
|
||||
|
||||
**最重要的架构规则:** 第三方仓库只依赖已发布的 CLI/规范协议;禁止依赖
|
||||
`marqdo-ir` 私有 Rust 结构、内部 `HostOp`、CLI 当前源码相对路径、未冻结的
|
||||
`inspect --ir` 私有结构或运行时进程内存布局。新领域函数不得靠在核心
|
||||
`builtins_impl.rs` 加 `quantum.*`/`agent.*` 分支获得支持。
|
||||
|
||||
## 1. 前置条件、安装布局与版本协商
|
||||
|
||||
### 1.1 发布归档
|
||||
|
||||
`3.0.0-beta.1` 只发布 **Linux x86_64 (glibc)** 归档:
|
||||
|
||||
```text
|
||||
marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz
|
||||
marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz.sha256
|
||||
```
|
||||
|
||||
```bash
|
||||
sha256sum -c marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz.sha256
|
||||
tar -xzf marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz
|
||||
cd marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu
|
||||
./marqdo --version # marqdo 3.0.0-beta.1
|
||||
```
|
||||
|
||||
归档内至少包含:`marqdo`、**同目录的** `marqdo-provider-worker`、
|
||||
`RELEASE_INFO.json`(source SHA/target/toolchain/binary SHA256)、`SOURCE_SHA`、
|
||||
`KNOWN_LIMITATIONS.md`、`spec/`、`docs/developers/`、`examples/`、
|
||||
`tests/consumers/`。`sha256` 只证明内容完整性,**不是**发布者身份签名。
|
||||
|
||||
`marqdo-provider-worker` 只按 `marqdo` 可执行文件同目录解析,不查 `PATH`、
|
||||
不退化为 Host 进程内加载;缺失时 Provider 请求以
|
||||
`ext.worker_unavailable` fail-closed。Provider 扩展作者只交付
|
||||
`provider.json` + C ABI library。
|
||||
|
||||
### 1.2 源码/工具链前置条件
|
||||
|
||||
- 消费扩展:不需要 Rust。需要 `git`(Git 依赖)、`python3`(归档中的
|
||||
Analysis/Trace consumer)。
|
||||
- 自己编译插件/Provider:Rust 1.82+ 或仅 C 编译器(`cc`)+ 冻结 C header。
|
||||
- 内置 Foreign kernel:系统 `python3`/`node`(或显式固定环境)。
|
||||
- `--mode strict`:仅 Linux,需要 Bubblewrap 且内核/环境允许 namespace;
|
||||
否则 fail-closed。
|
||||
|
||||
### 1.3 版本轴与 SemVer 预发布规则
|
||||
|
||||
产品版本、协议版本、包版本是三个独立轴:
|
||||
|
||||
| 轴 | 当前值 | 说明 |
|
||||
|---|---|---|
|
||||
| 产品/CLI | `3.0.0-beta.1` | `marqdo --version`、Analysis `producer.version` |
|
||||
| 协议 | Analysis v2、Trace v2、Tool v1、Plugin ABI v1、Foreign wire v1、Provider manifest v2、Lock v4 | 不因产品叫 3.0 而改成 v3 |
|
||||
| 包 | 官方 stdlib `0.1.0`;示例插件/工具/项目 `0.1.0` | 各自 SemVer 轴 |
|
||||
|
||||
Beta 期必须显式包含预发布号。`">=3.0.0,<4.0.0"` **不会**匹配
|
||||
`3.0.0-beta.1`(SemVer 规则);请写
|
||||
`">=3.0.0-beta.1,<4.0.0"`。`tool.json` 的 `compatibility.marqdo` 与
|
||||
`marqdo.yaml` 的 `project.marqdo` 都按此规则**强制执行**,不匹配分别报
|
||||
`requires marqdo …` / `package.marqdo_incompatible`,不会静默忽略。
|
||||
|
||||
### 1.4 安全模式
|
||||
|
||||
- `--mode pure`:纯语言执行,不授予任何外部系统权限。
|
||||
- `--mode project`(默认):只能通过显式 CLI grant/授权访问资源;**不是**安全
|
||||
OS sandbox,默认按当前用户身份运行。
|
||||
- `--mode strict`:Linux-only、Bubblewrap probe-gated 的 L1 隔离(pure 语言 +
|
||||
native Math)。它拒绝 `--allow-*`、`--plugin`、`--provider`、`--kernel`、
|
||||
`--trust-native-plugin` 和 `--trace-file`;strict L2(Worker/Foreign/Provider)
|
||||
未实现。没有该发行 SHA 的隔离证据时,发布说明必须明确 `strict: unsupported`
|
||||
并保持 fail-closed。
|
||||
|
||||
## 2. 纯 `.mq.md` 库:优先采用
|
||||
|
||||
推荐独立仓库结构:
|
||||
|
||||
```text
|
||||
marqdo-quantum/
|
||||
README.md
|
||||
marqdo.yaml
|
||||
index.mq.md
|
||||
tests/
|
||||
examples/
|
||||
```
|
||||
|
||||
`marqdo.yaml`(`project.marqdo` 在 beta 起强制校验):
|
||||
|
||||
```yaml
|
||||
project:
|
||||
name: quantum
|
||||
version: 0.1.0
|
||||
marqdo: ">=3.0.0-beta.1,<4.0.0"
|
||||
dependencies: {}
|
||||
```
|
||||
|
||||
`index.mq.md`(符合 RFC-LANG-0002):
|
||||
|
||||
```markdown
|
||||
# @knowledge 量子数学工具
|
||||
|
||||
此包在不修改 Marqdo 内核的情况下向外公开领域函数。
|
||||
|
||||
## @exec 加倍
|
||||
|
||||
`params(x: Int)`
|
||||
|
||||
`return x * 2`
|
||||
```
|
||||
|
||||
消费者固定真实 Git commit(**小写 40 或 64 位完整 SHA**;分支/标签不可复现):
|
||||
|
||||
```yaml
|
||||
# consumer/marqdo.yaml
|
||||
project:
|
||||
name: quantum-consumer
|
||||
version: 0.1.0
|
||||
marqdo: ">=3.0.0-beta.1,<4.0.0"
|
||||
dependencies:
|
||||
quantum:
|
||||
git: https://github.com/your-org/marqdo-quantum.git
|
||||
rev: 0123456789abcdef0123456789abcdef01234567
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
quantum: "@quantum"
|
||||
---
|
||||
|
||||
## @exec main
|
||||
|
||||
`return quantum.加倍(x=21)`
|
||||
```
|
||||
|
||||
`@quantum` 绑定依赖包的入口 `index.mq.md`;调用需带别名前缀。路径依赖使用
|
||||
`path: ./deps/x`(必须位于项目根内);`marqdo add <alias> --git <url> --rev
|
||||
<sha>` 可代写。
|
||||
|
||||
运行步骤(消费者项目根):
|
||||
|
||||
```bash
|
||||
marqdo lock
|
||||
marqdo sync --locked
|
||||
marqdo check index.mq.md --refs
|
||||
marqdo call index.mq.md main # -> 42
|
||||
```
|
||||
|
||||
### 2.1 Lockfile 行为(必须理解)
|
||||
|
||||
- 声明依赖后,`check`/`run`/`call`/`inspect` **要求** `marqdo.lock`;缺失报
|
||||
`project.lock` 并要求先运行 `marqdo lock`。
|
||||
- `run`/`check` 从不 fetch,也从不改写 lock。普通 `sync` 可能按 lock 取回
|
||||
缺失的 pinned Git revision;`sync --locked` 禁止 fetch,只用已验证缓存。
|
||||
两者都校验内容摘要,绝不静默更新 lock。
|
||||
- lock v4 记录完整包实例闭包(`dep:name@version#content-digest`)、alias 边和
|
||||
扩展 manifest/artifact 身份;v3 会得到显式 `marqdo lock` 迁移错误。
|
||||
- 提交 `marqdo.lock`,忽略 `.marqdo/`(`init` 已写 `.gitignore`)。
|
||||
|
||||
## 3. Knowledge / Prove / View:使用 Tool Protocol v1
|
||||
|
||||
这是外部工具的首选架构:核心只提供语言/公开协议,工具是独立进程。
|
||||
|
||||
```text
|
||||
marqdo-cli (语言核心,不依赖工具仓库)
|
||||
| check --emit / run --trace-file / call / public spec
|
||||
v
|
||||
marqdo-knowledge / marqdo-prove / marqdo-view (各自独立仓库)
|
||||
```
|
||||
|
||||
建议仓库:
|
||||
|
||||
```text
|
||||
marqdo-view/
|
||||
README.md
|
||||
tool.json
|
||||
bin/marqdo-view # 独立编译后生成,不能是核心源码依赖
|
||||
src/
|
||||
tests/contract/
|
||||
examples/
|
||||
```
|
||||
|
||||
`tool.json`(已可在 beta 上安装):
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.cli-tool",
|
||||
"schema_version": 1,
|
||||
"name": "marqdo-view",
|
||||
"version": "0.1.0",
|
||||
"command": "view",
|
||||
"entrypoint": "bin/marqdo-view",
|
||||
"compatibility": {
|
||||
"marqdo": ">=3.0.0-beta.1,<4.0.0",
|
||||
"analysis": [2],
|
||||
"trace": [2]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
安装和调用:
|
||||
|
||||
```bash
|
||||
marqdo tool install ./marqdo-view # 目录或 tool.json
|
||||
marqdo tool list
|
||||
marqdo view --help
|
||||
marqdo view index.mq.md
|
||||
marqdo tool remove view
|
||||
```
|
||||
|
||||
**Tool 运行契约:**
|
||||
|
||||
- CLI 原生命令优先;未知顶层命令只有已注册 `tool.json` 才分发,绝不扫描
|
||||
`PATH` 猜测执行。
|
||||
- 安装:读取并校验 schema/SemVer/协议交集、entrypoint 不越界、命令不冲突;收集
|
||||
整包清单(相对路径/大小/SHA-256,拒绝符号链接/特殊文件,限制 4096 文件/
|
||||
256 MiB),复制到 staging 后重新计算并逐项比对,最后原子发布。安装目录为
|
||||
`$MARQDO_TOOL_HOME`(若设置)或用户配置目录下的 `marqdo/tools`。
|
||||
- 分发:启动前重新计算整包清单并与记录比对,entrypoint 必须属于该清单;保留
|
||||
`cwd`、stdio、argv 和退出码,不经 shell、不拼接命令行。
|
||||
- 工具环境变量:`MARQDO_BIN`(当前 CLI 绝对路径)、
|
||||
`MARQDO_TOOL_PROTOCOL=1`,以及协商成功后提供的
|
||||
`MARQDO_PROTOCOL_ANALYSIS=2` / `MARQDO_PROTOCOL_TRACE=2`。
|
||||
- 工具不应猜测 `marqdo` 在 `PATH` 中的位置,优先调用 `MARQDO_BIN`,通过 argv
|
||||
数组传参。
|
||||
- Tool 是用户主动执行的普通进程,**不继承** `.mq.md` 程序的
|
||||
`pure/project/strict` 隔离;不得静默执行文档或继承授权。
|
||||
- 负例:未知 schema major、`marqdo` 范围不匹配、保留命令、逃逸/符号链接
|
||||
entrypoint、篡改 bundle、缺失 entrypoint 都必须 fail-closed;协议不匹配报
|
||||
`tool.protocol_incompatible`。
|
||||
|
||||
### 3.1 公共 Analysis v2:静态输入
|
||||
|
||||
```bash
|
||||
marqdo check index.mq.md --emit ./analysis.json
|
||||
```
|
||||
|
||||
只在退出码为 0 后读取 artifact。`--refs` 是**独立**的 Markdown 链接校验,可能让
|
||||
`check` 失败;失败时 `check` 会删除旧的 emit 目标文件,因此不要用
|
||||
`check --refs --emit` 生成消费 artifact 而不检查退出码。
|
||||
|
||||
成功时为 JSON `schema: marqdo.analysis`、`schema_version: 2`。顶层字段:
|
||||
`producer`、`project`(`root_id`、`identity_kind`、`lock_digest`——无 lock 时为
|
||||
空字符串、`stdlib`——可能为 null)、`modules`、`diagnostics`。模块字段:
|
||||
`id`、`package_instance_id`、`relative_path`、`source_digest`、`units`、
|
||||
`functions`、`imports`、`references`、`calls`、`resources`。字节偏移以 UTF-8
|
||||
源文本为准;稳定索引键用包实例身份而非本地绝对路径。完整字段与 JSON Schema:
|
||||
`spec/analysis-v2.md`、`spec/schemas/analysis-v2.schema.json`。`check` 不加载
|
||||
插件库、不启动内核/Provider、不运行程序。
|
||||
|
||||
**View 责任**:读取原始 Markdown 渲染(不能用 Analysis JSON 代替原文);把源
|
||||
字节偏移/标题单元/可调用映射关联到渲染内容;运行展示只读 Trace,不能自行执行
|
||||
`.mq.md` 或产生不受 Host 控制的副作用。
|
||||
|
||||
**Knowledge 责任**:消费 Analysis 的标题锚点、链接、资源、包身份与来源摘要;
|
||||
生成索引/知识图;不假定 `@knowledge` 有运行效果;跨包地址使用显式 import/锁定
|
||||
身份,禁止按物理路径猜目标。
|
||||
|
||||
**Prove 责任**:从公开 Analysis 提取可证明子集/证明义务,通过外部证明器生成
|
||||
证书;要求源摘要、语义与契约身份一致;明确区分
|
||||
`proved / disproved / unknown / unsupported`。无法证明不等于程序错误。不得修改
|
||||
core IR 或把“模型说证明了”当可信证书;缺公共字段应先提版本化协议提案。
|
||||
|
||||
### 3.2 公共 Trace v2:动态输入
|
||||
|
||||
```bash
|
||||
marqdo run index.mq.md --trace-file ./trace.json
|
||||
```
|
||||
|
||||
读取 `schema: marqdo.trace`、`schema_version: 2`。把 `source.analysis_digest`
|
||||
与实际 Analysis JSON **文件字节**的 SHA256 对照;不一致提示 stale trace。事件
|
||||
包含 `call.enter`、`call.exit`、`branch.eval`、`loop.iteration`、`return`、
|
||||
`effect`,以及可能的 `trace.truncated`;每个带来源事件包含 module id + UTF-8
|
||||
span。Trace 不记录参数值、秘密或文件内容。默认预算 100000 事件 / 32 MiB,可用
|
||||
`--trace-max-events` / `--trace-max-bytes` 调整;工具不得假定 trace 永远完整。
|
||||
`run --trace-file` 不生成 Analysis,digest 只适合与同一项目/同一投影配置的
|
||||
Analysis 对比。详见 `spec/trace-v2.md`、`spec/schemas/trace-v2.schema.json`。
|
||||
|
||||
**不要依赖** `inspect --ir` 的当前 JSON 形态(不是冻结跨仓协议);需要结构信息
|
||||
用 `check --emit`。
|
||||
|
||||
## 4. 计算插件:Callable Plugin ABI v1
|
||||
|
||||
平台矩阵:**Linux x86_64 的 native 与 worker 是 beta 支持目标**;macOS
|
||||
native/worker 为 UNVERIFIED,Windows native/worker 为 UNSUPPORTED(Unix-gated)。
|
||||
首发只应交付 `x86_64-unknown-linux-gnu` 的 `.so`。
|
||||
|
||||
公开 ABI 头文件 `include/marqdo_plugin_abi_v1.h`,Rust SDK
|
||||
`crates/marqdo-plugin-sdk`(`mq_plugin_entry!`)。`plugin.yaml`:
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
name: demo.solver
|
||||
version: 0.1.0
|
||||
abi: "^1.0"
|
||||
kind: worker # native 需 --trust-native-plugin;worker 为崩溃隔离
|
||||
exports:
|
||||
- name: solver.add
|
||||
signature: "($a: Int, $b: Int) -> Int"
|
||||
requires: []
|
||||
artifacts:
|
||||
- target: x86_64-unknown-linux-gnu # 必须与宿主 triple 精确相等
|
||||
file: libsolver.so
|
||||
sha256: "<实际工件的64位小写十六进制SHA256>"
|
||||
```
|
||||
|
||||
消费(**只接受命名参数**;`--allow-plugin` 匹配 `plugin.name` 全名):
|
||||
|
||||
```markdown
|
||||
## @exec main
|
||||
|
||||
`return solver.add(a=20, b=22)`
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo plugin inspect path/to/plugin.yaml # 仅静态,不加载
|
||||
marqdo check index.mq.md --plugin path/to/plugin.yaml
|
||||
marqdo run index.mq.md --plugin path/to/plugin.yaml --allow-plugin demo.solver
|
||||
```
|
||||
|
||||
`check` 按 Manifest 做静态签名绑定,不加载插件(工件可以尚不存在)。`run` 先
|
||||
验证工件 hash/目标平台/grant,再核对静态与动态 export 清单一一一致,不能在
|
||||
运行时猜名字或合成空签名。`kind: native` 进程内执行,必须显式
|
||||
`--trust-native-plugin`,可直接破坏宿主;`kind: worker` 在子进程中加载同一
|
||||
library,是崩溃/地址空间隔离,**不是** OS sandbox。ABI v1 配置默认值被拒绝;
|
||||
参数字面量位置参数会被规范化但库调用约定仍是命名。规范源:
|
||||
`spec/plugin-abi.md`、`spec/callable-resolution.md`;可运行示例
|
||||
`examples/plugin-demo/`(归档内含 host 构建工件)。
|
||||
|
||||
## 5. Resource Provider v2:设备/外部流
|
||||
|
||||
平台:**Linux x86_64**(worker transport);macOS/Windows 不声称。
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.provider",
|
||||
"schema_version": 2,
|
||||
"name": "demo.sensor",
|
||||
"version": "0.1.0",
|
||||
"abi": "c-abi-1",
|
||||
"transport": "worker",
|
||||
"kinds": ["demo.sensor"],
|
||||
"artifacts": [{
|
||||
"target": "x86_64-unknown-linux-gnu",
|
||||
"path": "lib/libdemo_sensor.so",
|
||||
"sha256": "<实际工件的64位小写十六进制SHA256>"
|
||||
}],
|
||||
"permissions_requested": []
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo run index.mq.md \
|
||||
--provider /path/to/provider.json \
|
||||
--allow-provider demo.sensor
|
||||
```
|
||||
|
||||
程序中继续使用普通语言接口 `resource.open("demo.sensor", "unit-1", ["read"])`
|
||||
配合 `resource.read/write/close` 和 `Memory` 搬运 bytes。Provider 不新增语言
|
||||
关键字或 callable。一个资源 kind 只能匹配一个 Provider,重复与未授权在真正执行
|
||||
前拒绝。`marqdo-provider-worker` 必须与 `marqdo` 同目录、同目标平台;缺失时报
|
||||
`ext.worker_unavailable`,不退化到 PATH 或进程内加载。`check`/`inspect` 不接受
|
||||
`--provider`,也从不加载 Provider。当前特性不是安全沙箱。规范源:
|
||||
`spec/resource-provider-v2.md`、ADR-0055;可运行示例 `examples/provider-demo/`
|
||||
(先运行其 `build.sh`;仓库内模板 manifest 的 digest 是零值,只有生成的
|
||||
`build/provider.json` 可运行)。
|
||||
|
||||
## 6. Foreign Kernel:新增未知语言无需改内核
|
||||
|
||||
使用 `kernel.json` 注册新语言标签;`Code`/`Formula` 仍是惰性值,必须显式调用
|
||||
`foreign.run/foreign.call`。最小描述符(字段以 `spec/foreign.md` 为准):
|
||||
|
||||
```json
|
||||
{
|
||||
"provider_id": "mocklang",
|
||||
"languages": ["mocklang", "mock"],
|
||||
"wire_version": 1,
|
||||
"entrypoint": "./mocklang",
|
||||
"permissions_requested": [],
|
||||
"digest": "<entrypoint/环境工件的64位小写SHA256,必填>",
|
||||
"environment_id": "mocklang-env-1"
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo run demo.mq.md --kernel path/to/kernel.json --allow-foreign
|
||||
```
|
||||
|
||||
`wire_version` 当前必须为 1;相对 `entrypoint` 相对描述符目录解析且必须
|
||||
canonicalize 到普通文件;`digest` 必填并在每次 spawn 前校验;`builtin: true`
|
||||
被拒绝;`--kernel` 可重复。Host 必须拒绝未授权执行、digest 不匹配、异常退出、
|
||||
超时与不兼容 wire。不要按语言名在 core 加 `if language == "julia"`。示例:
|
||||
`examples/kernel-mock/kernel.json` 与 `demo.mq.md`;规范源:`spec/foreign.md`。
|
||||
|
||||
## 7. 可复现扩展选择:`marqdo.yaml.extensions` / lock v4
|
||||
|
||||
```yaml
|
||||
project:
|
||||
name: my-research
|
||||
version: 0.1.0
|
||||
marqdo: ">=3.0.0-beta.1,<4.0.0"
|
||||
dependencies:
|
||||
quantum:
|
||||
git: https://github.com/your-org/marqdo-quantum.git
|
||||
rev: 0123456789abcdef0123456789abcdef01234567
|
||||
extensions:
|
||||
plugins:
|
||||
- from: "@quantum/adapter/plugin.yaml"
|
||||
kernels: []
|
||||
providers:
|
||||
- from: "@quantum/adapter/provider.json"
|
||||
```
|
||||
|
||||
- `from` 仅支持 `./` 相对路径或 `@alias/` 已声明包依赖路径;不允许 URL、绝对
|
||||
路径、通配符、`..`、空路径或 symlink 逃逸。
|
||||
- `marqdo lock` 将已选扩展的 manifest/目标 artifact 摘要及逻辑包实例写入 lock
|
||||
v4;`marqdo inspect index.mq.md --extensions --json` 只显示身份与 lock 状态,
|
||||
不执行。
|
||||
- `check`/`sync` 检查声明与 lock 一致(`ext.extension_lock_mismatch`);
|
||||
`run/call` 在授权前再次检查实际工件。
|
||||
- **选择扩展永远不等于授予权限**。`--allow-plugin NAME`、
|
||||
`--allow-provider NAME`、`--allow-foreign` 仍必须显式。`strict`/`pure` 不允许
|
||||
第三方执行扩展。
|
||||
- Manifest 任何签名/路径/版本/目标平台/SHA256 不符都 fail-closed,不得“自动找
|
||||
可用最新版本”。
|
||||
|
||||
## 8. 跨仓库契约测试(任何外部工具/库都要交付)
|
||||
|
||||
**正向**:独立 Git repo、真实固定 SHA 导入;在已发布二进制上 `check`、`run/call`;
|
||||
Tool 执行 `marqdo tool install ...` 和真实命令;Analysis/Trace 消费者验证
|
||||
schema、digest、源码 span;Provider 与 Plugin 在正确授权下返回确定结果。
|
||||
|
||||
**负向**:未知语法标记不会被执行;错误函数名/arity;导入别名与 builtin 命名
|
||||
空间冲突;重复导出;缺失/错误摘要;未授权;缺 Provider Worker;平台不匹配;
|
||||
混淆 lock v3/v4;过期 Trace;未知 schema major;Worker 崩溃/超时;上述都必须
|
||||
产生预期诊断,没有“失败后静默改用其他实现”。
|
||||
|
||||
**冻结 CLI 测试**:先构建或下载固定来源 SHA 的 CLI 二进制并记录 SHA256,然后
|
||||
仅修改外部仓库重复完整正负验收;严格验证二进制哈希不变:
|
||||
|
||||
```bash
|
||||
python3 tools/ci/verify_extension_contracts.py \
|
||||
--cli /path/to/frozen/marqdo \
|
||||
--fixtures /path/to/marqdo-extension-conformance \
|
||||
--out docs/evidence/extension/<release-sha>/manifest.json
|
||||
```
|
||||
|
||||
参考独立仓库
|
||||
[`marqdo-extension-conformance`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance)、
|
||||
`docs/evidence/extension/schema.json`。若每新增一个函数都必须重编 CLI,该扩展
|
||||
不合格。
|
||||
|
||||
## 9. 开源发布与支持政策
|
||||
|
||||
- 每个第三方包发布:README、最小示例、实际支持的 CLI 产品版本范围、独立协议
|
||||
版本、目标平台矩阵、权限清单、可复现工件 digest、测试命令、限制与安全声明。
|
||||
- 明确 `sha256` 仅验证内容完整性,不等于发布者身份认证;不能仅凭未知 Git URL
|
||||
的 hash 就把扩展当可信代码。
|
||||
- `developers/README.md` 指向按任务拆分的 Tool/Library/Plugin/Kernel/Provider
|
||||
教程和 `spec/` 规范协议。
|
||||
- `3.0.0-beta.N` 阶段的第三方应把破坏性变更视为真实风险;LTS 承诺尚未宣布。
|
||||
- 本 beta 的支持平台只有 Linux x86_64;G4 是固定节点上的 Beta-only WARN,
|
||||
strict 策略以发布证据为准;这些都不是 LTS 承诺。
|
||||
|
||||
## 10. 独立工具开发清单(Knowledge/Prove/View)
|
||||
|
||||
- [ ] 独立仓库构建,`marqdo-cli` 没有任何依赖指向本仓库。
|
||||
- [ ] `tool.json` 合法、入口文件属于安装包、Tool 版本与 CLI 协商成功。
|
||||
- [ ] 从 `MARQDO_BIN` 派生调用,而非内部 Rust API。
|
||||
- [ ] `check --emit` 读 Analysis v2;`run --trace-file` 读 Trace v2;强校验
|
||||
schema/version/digest 与退出码。
|
||||
- [ ] 只解析用户授权源文件及显式依赖闭包,路径兼容多包实例/不同 checkout。
|
||||
- [ ] 确定性输出、错误诊断、fixture、中文/英文快速教程齐备。
|
||||
- [ ] 未验证 strict、不可证明内容、无设备支持等边界明确提示,不默默声称支持。
|
||||
- [ ] 冻结 CLI 黑盒测试及反向兼容性测试 PASS;无 core source edit。
|
||||
|
||||
## 11. 本文引用的仓库规范
|
||||
|
||||
- `spec/mapping.md`、`spec/expression.ebnf`、
|
||||
`docs/architecture/RFC-LANG-0002-unified-semantics.md`
|
||||
- `spec/package-format.md`、`spec/extension-selection.md`、
|
||||
`spec/callable-resolution.md`、`spec/references.md`
|
||||
- `spec/tool-v1.md`、`spec/analysis-v2.md`、`spec/trace-v2.md`、
|
||||
`spec/plugin-abi.md`、`spec/resource-provider-v2.md`、`spec/foreign.md`
|
||||
- `spec/security.md`、`spec/markdown-profile.md`、`spec/value-wire.md`
|
||||
- `spec/schemas/analysis-v2.schema.json`、`spec/schemas/trace-v2.schema.json`
|
||||
- `include/marqdo_plugin_abi_v1.h`、`crates/marqdo-plugin-sdk`
|
||||
- `docs/releasing.md`、`COMPATIBILITY.md`、`docs/evidence/extension/README.md`
|
||||
- `docs/developers/README.md`、`docs/developers/release-limits.md`
|
||||
+81
-148
@@ -1,167 +1,99 @@
|
||||
# Marqdo Implementation Status
|
||||
|
||||
Snapshot: **2026-11-22**, workspace version `0.1.0`, no release tag. RFC-EXT-0001
|
||||
implementation evidence is bound to code SHA `6a7bb983c3b34fd0340afdcba9f197f7f50cba2a`.
|
||||
Snapshot: **2026-11-22**, product version **`3.0.0-beta.1`** (prerelease, tag
|
||||
`v3.0.0-beta.1`). Released platform: **Linux x86_64 (glibc)**. The exact tagged
|
||||
source SHA, CI pipeline URL and binary hashes are recorded in
|
||||
[`evidence/ci/`](evidence/ci/README.md) and in the archive's
|
||||
`RELEASE_INFO.json`; do not copy a SHA from a plan.
|
||||
|
||||
Current architecture overview:
|
||||
[`architecture/CURRENT.md`](architecture/CURRENT.md).
|
||||
Authoritative CI convergence plan:
|
||||
[`NEXT_RELEASE_CI_CONVERGENCE.md`](NEXT_RELEASE_CI_CONVERGENCE.md) (historical
|
||||
baseline at `c9f01aa8`; refresh before use).
|
||||
Support matrix: [`../COMPATIBILITY.md`](../COMPATIBILITY.md).
|
||||
Authoritative release policy:
|
||||
[`MARQDO_3_0_PRERELEASE_PLAN.md`](MARQDO_3_0_PRERELEASE_PLAN.md) (plan, not
|
||||
evidence). Support matrix: [`../COMPATIBILITY.md`](../COMPATIBILITY.md).
|
||||
Developer entry point: [`developers/README.md`](developers/README.md).
|
||||
|
||||
This file records what was actually executed on the current tree. "Implemented"
|
||||
does not mean "verified on every platform"; the evidence column says which
|
||||
commands were run and where. Do not copy a running status into another plan;
|
||||
[`architecture/CURRENT.md`](architecture/CURRENT.md) is the single current
|
||||
overview. The historical M0.5 snapshot is preserved at
|
||||
[`history/STATUS-M0.5-snapshot.md`](history/STATUS-M0.5-snapshot.md) and must
|
||||
not be read as current status.
|
||||
This file records what was actually executed. "Implemented" does not mean
|
||||
"verified on every platform"; the evidence column says which commands were run
|
||||
and where. Status is generated from executed commands/logs; a gate row without a
|
||||
command, log or source path is a defect, not a state. Historical snapshots
|
||||
(including M0.5 and the pre-beta `0.1.0` candidate) are preserved under
|
||||
[`history/`](history/README.md) and [`evidence/`](evidence/) and must not be read
|
||||
as current status.
|
||||
|
||||
Status is generated from executed commands and logs; a gate row without a command,
|
||||
log or source path is a defect, not a state.
|
||||
## 0. Beta release record — `3.0.0-beta.1`
|
||||
|
||||
## 0.0 RFC-EXT-0001 extensibility closure (current tree)
|
||||
### 0.1 Product, version axes and scope
|
||||
|
||||
Executed on Linux x86_64, Rust 1.100.0, branch `feat/extensible-ecosystem`:
|
||||
- Workspace/crate version, `marqdo --version` and Analysis `producer.version`
|
||||
are `3.0.0-beta.1`; `Cargo.lock` is committed and release builds use
|
||||
`--locked`.
|
||||
- Independent axes are unchanged: Analysis v2, Trace v2, Tool v1, Plugin ABI
|
||||
v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile
|
||||
`marqdo.md.v1`; bundled stdlib stays package version `0.1.0`.
|
||||
- `project.marqdo` is enforced; prerelease SemVer rules are covered by tests
|
||||
(`>=3.0.0,<4.0.0` does not silently accept a beta core).
|
||||
- Only the Linux x86_64 archive is claimed. macOS/Windows are
|
||||
experimental/unclaimed; the Windows lane in CI is a compile cross-check only.
|
||||
- Known limitations are shipped as `KNOWN_LIMITATIONS.md` and recorded in
|
||||
[`developers/release-limits.md`](developers/release-limits.md).
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace --locked PASS
|
||||
67 test targets: 599 passed, 0 failed
|
||||
cargo build --release --locked -p marqdo-cli PASS
|
||||
```
|
||||
### 0.2 Beta gates on the tagged SHA
|
||||
|
||||
Implemented and tested in this tree (PR-00…PR-07; no release claim):
|
||||
Every row is required for the beta profile
|
||||
(`tools/ci/release_evidence.py --profile beta`); a missing, failed, skipped or
|
||||
SHA-mismatched gate is `DO_NOT_RELEASE`.
|
||||
|
||||
| Area | State | Tests |
|
||||
| Gate | Beta requirement | Evidence |
|
||||
|---|---|---|
|
||||
| One `CallableRegistry` + one binding pass; runtime dispatch by `CallSiteKey`; no runtime name fallback; exact plugin reconciliation | **IMPLEMENTED / TESTED** | `callable_resolution` (14), `plugin_worker`, `analysis_trace`, `architecture_boundaries` |
|
||||
| `provider.json` v2 through `--provider`/`--allow-provider`; verified before spawn; sibling helper only | **IMPLEMENTED / TESTED (linux/x86_64)** | `provider_cli` (12); PROV-01…10/13; macOS/Windows FAIL-CLOSED |
|
||||
| `marqdo.yaml.extensions` + lock v4 identity + `inspect --extensions`; CLI/manifest merge and conflicts | **IMPLEMENTED / TESTED** | `extension_selection` (13), `package_env`, package crate tests |
|
||||
| Capability handler registry; `fs.read` real handler; audit/unavailable | **IMPLEMENTED / TESTED** | `marqdo-host` `capability_handlers` (12) |
|
||||
| Official stdlib public aliases; print_override/AST scan/runtime branch removed | **IMPLEMENTED / TESTED** | `stdlib_alias_routing` (5), print/format/Trace goldens |
|
||||
| Independent external repo + frozen-CLI suite (pure pinned Git, plugin, kernel, provider, tool) | **PASS on the frozen `--release` binary** | [`evidence/extension/6a7bb983.../manifest.json`](evidence/extension/6a7bb983c3b34fd0340afdcba9f197f7f50cba2a/manifest.json): all 7 required categories PASS; CLI sha256 `28e3776d…`, fixture repo `e4b7352c…` |
|
||||
| Source hygiene | clean tree, committed `Cargo.lock`, `--locked` builds | release commit; `RELEASE_INFO.json` |
|
||||
| Static/tests | `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace --locked` PASS | release evidence document + Woodpecker pipeline |
|
||||
| Release build | `cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker` PASS | archive contains both binaries, same target |
|
||||
| Linux CI | same-SHA Woodpecker pipeline PASS | pipeline URL in `evidence/ci/<sha>/manifest.json` |
|
||||
| Frozen-binary conformance | external `marqdo-extension-conformance` suite PASS with unchanged CLI hash | `evidence/extension/<sha>/manifest.json` |
|
||||
| Clean-install smoke | archive-only smoke PASS (incl. provider worker positive/negative, tools, plugins, kernel, Analysis/Trace) | release evidence document |
|
||||
| Version compatibility | prerelease Tool/project SemVer tests PASS; `project.marqdo` fail-closed tests PASS | `cargo test` logs/pipeline |
|
||||
| Strict policy | same-SHA disposable-VM G3 PASS for Linux strict L1 (or a tested fail-closed `strict: unsupported` policy) | `evidence/*strict*` document |
|
||||
| Performance | correctness-verified `MEASURED` on fixed Woodpecker agent; Beta-only `WARN` approved with environment/limits | G4 evidence document |
|
||||
| Support matrix | Linux x86_64 supported; macOS/Windows explicitly unsupported/experimental | [`../COMPATIBILITY.md`](../COMPATIBILITY.md) |
|
||||
|
||||
Evidence: [`evidence/2026-11-22-ext-implementation.md`](evidence/2026-11-22-ext-implementation.md),
|
||||
baseline [`evidence/ext-baseline-595279f.md`](evidence/ext-baseline-595279f.md),
|
||||
and the frozen-binary manifest
|
||||
[`evidence/extension/6a7bb983.../manifest.json`](evidence/extension/6a7bb983c3b34fd0340afdcba9f197f7f50cba2a/manifest.json).
|
||||
The manifest is bound to code SHA `6a7bb98`; a tag on a later SHA must rerun
|
||||
`tools/ci/verify_extension_contracts.py` on that SHA. Release decision remains
|
||||
**DO NOT RELEASE** for the unchanged G3/G4/native reasons below.
|
||||
Release decision: **BETA_RELEASE_CANDIDATE**. The `v3.0.0-beta.1` tag is cut
|
||||
only from a SHA with all gates green; the SHA-bound manifests are committed in
|
||||
the post-release evidence commit. This is a prerelease: it does **not** imply
|
||||
stable `3.0.0`, does not promise LTS, and does not claim macOS/Windows
|
||||
artifacts, strict L2, Wasm, or a package registry.
|
||||
|
||||
## 0. Language migration completed (RFC-LANG-0002)
|
||||
### 0.3 Strict and performance policy for this beta
|
||||
|
||||
The repository now has **one** language contract, implemented end to end:
|
||||
[`architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md)
|
||||
(accepted by [ADR-0052](adr/0052-unified-markdown-semantics.md)), with the
|
||||
normative summary in [`../spec/mapping.md`](../spec/mapping.md) and
|
||||
[`../spec/expression.ebnf`](../spec/expression.ebnf).
|
||||
- `strict` is Linux-only, Bubblewrap-probe-gated L1 (pure language + Math). It
|
||||
refuses plugins, providers, foreign kernels, external grants and
|
||||
`--trace-file`; strict L2 is not implemented. The release notes and
|
||||
`COMPATIBILITY.md` state the exact same-SHA evidence or the tested
|
||||
fail-closed unsupported policy; there is no silent fallback to `project`.
|
||||
- G4 is a fixed-node measurement with 9 correctness-verified workloads; this
|
||||
release records the shared/powersave environment and a **Beta-only WARN**
|
||||
approved in the release notes. Development-container or QEMU/TCG timings are
|
||||
never reported as G4.
|
||||
|
||||
Landed on `master` as one linear series (the former `semantics-v2-refactor`
|
||||
branch was fast-forwarded and deleted; only `master` remains):
|
||||
### 0.4 Extensibility closure on the beta tree
|
||||
|
||||
| Step | Commit | Content |
|
||||
|---|---|---|
|
||||
| 1 | `4983542` | docs/spec/ADR/READMEs, historical banners, migration guide and inventory |
|
||||
| 2 | `e029853` | frontend/IR/runtime implementation, `sem.*` diagnostics, migrated stdlib + digest, examples, fixtures and Rust-embedded sources |
|
||||
| 3 | `ffd1cc9` | expression-owned payload statement grammar, extra negative/CLI coverage |
|
||||
| 4 | `bbeb1de` | status/compatibility/README/migration docs flipped to the implemented state + green evidence |
|
||||
| 5 | `b38b769` | function-wide `params(...)` position (across heading segments) + two negatives |
|
||||
| 6 | `361a6cc` | removed the dead `Stmt::Call`/`CallSite`/`CallTarget` IR |
|
||||
| 7 | `d5002ac` | stale pre-RFC role docs and review-aid fixes |
|
||||
| 8 | `9fb97bc` | signatures recognized only from Exec payloads (Knowledge sections inert) |
|
||||
| 9 | `a3f9770` | unmatched `end` diagnostics point at the `end` payload |
|
||||
| 10 | `0bbe0f6` | Setext headings never declare a mode; dead helper removed |
|
||||
| 11 | `b3429cb` | diagnostics sorted by source position then code |
|
||||
| 12 | `9c1723d` | coverage for the removed syntax-selector front-matter probe |
|
||||
Implemented and covered on the release commit: one static callable binding
|
||||
(`CallSiteKey`, no runtime name fallback), official stdlib aliases without
|
||||
print magic, Resource Provider v2 through `--provider`/`--allow-provider`
|
||||
(worker helper only), explicit extension selection + lock v4, and a capability
|
||||
handler registry. `check`/`inspect` never load extension binaries; plugin
|
||||
exports reconcile exactly with the static manifest. The independent
|
||||
frozen-binary suite is the beta gate above; the older `6a7bb98` manifest is
|
||||
historical and superseded by the release-SHA manifest.
|
||||
|
||||
The breaking behaviour is:
|
||||
## 1. Historical: pre-beta remote baseline and evidence
|
||||
|
||||
* H1–H6 headings declare `@exec`/`@knowledge`; unmarked headings inherit the
|
||||
nearest ancestor and the document root is Knowledge;
|
||||
* only an Exec H2 is callable; an H2 Knowledge unit and H3–H6 sections are not
|
||||
functions, and a payload with no owning Exec H2 is `sem.exec_without_function`;
|
||||
* `Strong`, `Emph` and inline `Code` are interchangeable one-statement carriers;
|
||||
nested carriers and empty payloads are hard errors;
|
||||
* `if`/`else`/`while`/`end`/`return`/`params` come from the payload and lower to
|
||||
the existing `Branch`/`Loop`/`Return`/`Assign`/`Eval` IR; lists, block quotes
|
||||
and paragraphs are presentation containers;
|
||||
* control frames cannot cross a heading segment;
|
||||
* `params(...)` is legal only as the first direct Exec H2 payload across the
|
||||
whole function (a later `### @exec` segment cannot add a signature after
|
||||
earlier code ran); without it the existing free-variable inference applies and
|
||||
inferred signatures keep the named-arguments-only rule;
|
||||
* old syntax (`Strong` execute / `Emph` return / list branch/loop / quote call)
|
||||
is **not** executable, and `marqdo_semantics`/`syntax` front-matter selectors
|
||||
are rejected with `sem.unsupported_version_directive`.
|
||||
> **Historical record.** Everything in §1 onward was executed before the
|
||||
> `v3.0.0-beta.1` tag. It is kept for audit history; it is not the current
|
||||
> release status. Do not copy its SHAs, test counts or decisions into a release
|
||||
> claim.
|
||||
|
||||
### Verification at `9c1723d` (Linux x86_64, Rust 1.100.0)
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace --locked --no-fail-fast PASS
|
||||
507 passed, 0 failed, 2 ignored (62 green test targets)
|
||||
python3 tools/pack-stdlib.py PASS (digest verified)
|
||||
```
|
||||
|
||||
Full evidence: [`evidence/2026-11-21-semantics-v2-green.md`](evidence/2026-11-21-semantics-v2-green.md).
|
||||
The intermediate "text migrated, implementation pending" record is kept as
|
||||
[`evidence/2026-11-21-semantic-docs-migration.md`](evidence/2026-11-21-semantic-docs-migration.md)
|
||||
and is superseded by the green gate.
|
||||
|
||||
**Not claimed:** the **remote** G3 security artifact is still missing. The
|
||||
Linux/Windows/macOS native matrix is green, G4 is measured on the designated
|
||||
Woodpecker agent, and the G3 mechanism is PASS in a local disposable VM, but
|
||||
the RFC does not promote a local VM run to a remote gate. See §0.1, §4 and
|
||||
[`../COMPATIBILITY.md`](../COMPATIBILITY.md). The release decision remains
|
||||
**DO NOT RELEASE**.
|
||||
|
||||
## 0.1 CI/security convergence (2026-11-21)
|
||||
|
||||
The RFC-CI-0001 series fixes the release-blocking CI defects that the
|
||||
`32d8fe1` GitHub run exposed. Commits on `master`:
|
||||
|
||||
| Step | Commit | Content |
|
||||
|---|---|---|
|
||||
| 1 | `f4a404b` | platform-neutral `StrictChildState`/`inspect_strict_child`; macOS/Windows no longer reference Linux-only functions (`E0425`) |
|
||||
| 2 | `f817cce` | strict capture/routing: one JSON document on every `--json` path, stable failure codes, ADR-0053, deterministic routing tests |
|
||||
| 3 | `c9f509e` | architecture guard against direct marker access; Windows cross-target check |
|
||||
| 4 | `990e984` | G-C lane writes SHA-bound `strict-evidence.json`; workflow binds checkout/archive to the tested SHA and uploads evidence |
|
||||
| 5 | `d2267e9` | correctness-verified `marqdo.perf.v2` sampler and fixed-node workflow |
|
||||
| 6 | `0d7e11b` | SHA-bound release-evidence aggregator, docs drift cleanup, consistent `windows-latest`/`macos-latest` statement |
|
||||
| 7 | `512b9f5` | evidence-generation failure fails the lane; workflow archive/verification fixes; G-C re-run |
|
||||
| 8 | `beb68a9` | G-C evidence/status update and the cross-platform JSON smoke exit-code fix |
|
||||
| 9 | `3a29fce` | Windows PATH lookup applies `PATHEXT`; ANSI-stripped native failure annotations |
|
||||
| 10 | `b898c41` | macOS parser-nesting test stack; portable process product fixture (CLI `--version` instead of `/bin/echo`) |
|
||||
| 11 | `4265231` | CLI runs on an explicit 8 MiB thread (Windows 1 MiB overflow); macOS temp-path canonicalization; G3 adversarial tests opt-in |
|
||||
| 12 | `a24161c` | Windows foreign temp paths stay non-verbatim (Node `lstat` rejection) |
|
||||
| 13 | `5fcc111` | reject rooted Windows dependency paths (`has_root`, not `is_absolute`) |
|
||||
|
||||
Executed evidence:
|
||||
|
||||
| Lane | Result | Evidence |
|
||||
|---|---|---|
|
||||
| Linux fmt/clippy/test/build (Woodpecker) | **PASS** | pipelines `#9`–`#12`, `#14`, `#16`, `#17`, `#21`–`#25` on the series; `#13`/`#15`/`#19` were superseded/cancelled by the next push, not failures |
|
||||
| Linux + Windows + macOS native matrix (GitHub) | **PASS** | [run 30](https://github.com/cflmy/marqdo-cli/actions/runs/44896671929) on `5fcc111`: `fmt + clippy + test (Linux x86_64)`, `runtime contract (windows-latest)`, `runtime contract (macos-latest)`, and schema consumers all PASS |
|
||||
| G3 strict isolation | **PASS (local disposable VM) / remote UNVERIFIED** | `5fcc111`, `dev` uid 1000, QEMU/TCG, 7/7 + strict JSON/inert-`@knowledge`; [`evidence/2026-11-21-strict-gc-5fcc111.md`](evidence/2026-11-21-strict-gc-5fcc111.md) |
|
||||
| G4 performance | **MEASURED / WARN (provisional)** | Woodpecker agent 1, `1199c88`: 5 warmups + 20 samples, 9/9 `VERIFIED`, CPU 0 pinned; two runs -10.9%..+7.1% p50; shared powersave host caveat; [`evidence/2026-11-21-perf-woodpecker-agent-1.md`](evidence/2026-11-21-perf-woodpecker-agent-1.md) |
|
||||
|
||||
Release decision: **DO NOT RELEASE.** Linux, Windows and macOS native jobs are
|
||||
green on the same SHA, the strict isolation mechanism PASSes locally as a
|
||||
normal user, and G4 is `MEASURED`/`WARN` on the designated Woodpecker agent.
|
||||
The remaining release gate is the **remote** G3 artifact whose `tested_sha`
|
||||
matches; the RFC explicitly requires it (and the local VM PASS is not promoted
|
||||
to a remote claim). The perf gate is provisional because the agent is a shared
|
||||
powersave host; see [`performance.md`](performance.md).
|
||||
|
||||
The manifest contract is in
|
||||
[`evidence/ci/README.md`](evidence/ci/README.md); `tools/ci/release_evidence.py`
|
||||
reports `DO_NOT_RELEASE` for any missing/failed/SHA-mismatched gate.
|
||||
|
||||
## 1. Remote baseline and current evidence
|
||||
## 1. Historical: pre-beta remote baseline
|
||||
|
||||
The local language baseline for this snapshot is `9c1723d` (2026-11-21,
|
||||
semantics v2 implementation plus follow-up fixes). The later
|
||||
@@ -180,8 +112,8 @@ are **historical (2026-11-20), not current**, and that run was red:
|
||||
- Schema instance validation + consumers: PASS.
|
||||
- Release candidate artifact: SKIPPED (upstream failure; tag/dispatch only).
|
||||
|
||||
The remote SHA must be refreshed from CI after a push; do not read `c9f01aa8`
|
||||
as the current tree.
|
||||
The remote SHA had to be refreshed from CI after a push; `c9f01aa8` was never
|
||||
the current tree for later work.
|
||||
|
||||
This checkout's private remote is `https://git.cflmy.cn/cflmy/marqdo-cli` with
|
||||
Woodpecker CI at `https://ci.cflmy.cn` (`.woodpecker/main.yml`). The Linux Docker
|
||||
@@ -431,8 +363,9 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
7. No tagged Windows/macOS RC archive exists. The native **build/test** lanes
|
||||
PASS at `5fcc111`; the release-candidate job is tag/dispatch gated and has
|
||||
not produced those archives.
|
||||
8. No release tag/binary publication. The release decision is **DO NOT
|
||||
RELEASE** until the remote G3 artifact and the MEASURED G4 report exist.
|
||||
8. At that pre-beta point no release tag/binary publication existed; the
|
||||
historical decision was **DO NOT RELEASE** until remote G3 and a MEASURED G4
|
||||
report existed. The current `v3.0.0-beta.1` beta decision is recorded in §0.
|
||||
|
||||
## 5. RFC-CM compute-machine status
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Status: **current architecture overview**. This file summarises the tree as it
|
||||
is today. It is not a release promise, does not reopen a frozen ADR, and does not
|
||||
replace `spec/` or a recorded test log.
|
||||
|
||||
- Baseline: [`9c1723d44f403d6b742136f7881515083b413cc2`](https://github.com/cflmy/marqdo-cli/commit/9c1723d44f403d6b742136f7881515083b413cc2) (2026-11-21, RFC-LANG-0002 implementation and follow-up fixes; language code baseline).
|
||||
- Baseline: `56189b176c612bf399ff965c3b642077f6b04617` (2026-11-22, RFC-EXT-0001 tree; the tagged `v3.0.0-beta.1` release SHA and its evidence are recorded in `../STATUS.md`).
|
||||
- Normative behavior: `spec/`; frozen decisions: `docs/adr/`; executed evidence: `docs/STATUS.md` and `docs/evidence/`.
|
||||
- This is the **single current overview**. Do not add a second running "current state" file;
|
||||
update this file, `docs/STATUS.md` and an evidence file together.
|
||||
@@ -35,7 +35,7 @@ platform".
|
||||
|
||||
| Dimension | Current state | Source |
|
||||
|---|---|---|
|
||||
| Implemented | Rust workspace `0.1.0`: RFC-LANG-0002 Markdown/frontend/IR, v2 statement parser, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, migrated bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` |
|
||||
| Implemented | Rust workspace `3.0.0-beta.1`: RFC-LANG-0002 Markdown/frontend/IR, v2 statement parser, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, migrated bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` |
|
||||
| Tested locally | `cargo test --workspace --locked`: **599 passed, 0 failed** across 67 targets on Linux x86_64 in the RFC-EXT-0001 tree; fmt and clippy clean. Historical baseline: 507 passed at `9c1723d`. | `docs/STATUS.md`, `docs/evidence/2026-11-22-ext-implementation.md` |
|
||||
| Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` |
|
||||
| Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 |
|
||||
@@ -195,7 +195,8 @@ that a phase is complete.
|
||||
- [Architecture index](README.md) — RFC/ADR/evidence history.
|
||||
- [Implementation status](../STATUS.md) — executed state and blockers.
|
||||
- [Language/frontmatter blueprint](../DEVELOPMENT_BLUEPRINT.md) — design baseline; not current status.
|
||||
- [Stable-release implementation plan](../STABLE_RELEASE_IMPLEMENTATION.md) — next-phase plan; not implemented behavior.
|
||||
- [3.0 prerelease plan](../MARQDO_3_0_PRERELEASE_PLAN.md) — current release policy and beta gates.
|
||||
- [Stable-release implementation plan](../STABLE_RELEASE_IMPLEMENTATION.md) — historical stable-release roadmap input; not current status.
|
||||
- [ADR-0041: non-streaming resource operations](../adr/0041-resource-operation-fs.md) — accepted `resource.request` `fs.*` contract.
|
||||
- [ADR-0042: `clock.now` resource operation](../adr/0042-clock-resource-operation.md) — accepted project-mode Unix-millis clock.
|
||||
- [ADR-0043: `env.get` resource operation](../adr/0043-env-resource-operation.md) — accepted exact-name environment grants.
|
||||
|
||||
@@ -15,14 +15,14 @@ input and evidence. It is not a second running-status page.
|
||||
- Frozen behavior: [`../../spec/`](../../spec/); release gates: [`../security-gate.md`](../security-gate.md).
|
||||
- Historical planning snapshots: [`../history/README.md`](../history/README.md).
|
||||
|
||||
## Design input RFCs (Proposed, not implemented behavior)
|
||||
## Design input and implemented contracts
|
||||
|
||||
| Document | Status | What it is |
|
||||
|---|---|---|
|
||||
| [Unified semantics RFC-LANG-0002](RFC-LANG-0002-unified-semantics.md) | **Adopted and implemented** | Single syntax: heading modes, unified payloads, keyword control flow, breaking migration and acceptance gates. |
|
||||
| [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) | **Review input (historical)** | Responsibility convergence, stdio/file/stream correctness, CLI/Host split and the migration order at the time. Its language examples predate RFC-LANG-0002. |
|
||||
| [Compute machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) | **Proposed** | Opaque `Memory`, addressable regions, wire/host rejection. Compute semantics are unchanged by the syntax rewrite; its `.mq.md` examples are historical spelling. |
|
||||
| [Core and stdlib migration RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) | **Proposed** | Minimum core, `.mq.md` stdlib and system-capability migration. Stdlib source migration is pending per this RFC. |
|
||||
| [Core and stdlib migration RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) | **Proposed** | Minimum core, `.mq.md` stdlib and system-capability migration. The stdlib source migration is complete; current status is recorded in ../STATUS.md. |
|
||||
|
||||
The implemented first slices of these RFCs are recorded in `CURRENT.md` and
|
||||
`../STATUS.md`; the RFC text itself never proves that code exists.
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# Marqdo developer entry point
|
||||
|
||||
Everything a third party needs starts here. The rule behind this page: depend
|
||||
only on the **released CLI and public protocols**, never on Marqdo's private
|
||||
Rust structures, `marqdo-ir` internals, `inspect --ir`, relative paths into the
|
||||
core checkout, or host memory layout. Adding a new domain function must not
|
||||
require a core commit.
|
||||
|
||||
Product version for these docs: **`3.0.0-beta.1`** (Linux x86_64 beta).
|
||||
Protocol versions are independent: Analysis v2, Trace v2, Tool v1, Plugin ABI
|
||||
v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile
|
||||
`marqdo.md.v1`.
|
||||
|
||||
## Pick your entry point
|
||||
|
||||
| Goal | Use | Deliverable |
|
||||
|---|---|---|
|
||||
| AI/math/data/quantum/SKILL libraries, pure algorithms | `.mq.md` package | `index.mq.md`, `marqdo.yaml`, README, tests |
|
||||
| Knowledge/Proof/View/IDE/lint/analysis tools | CLI Tool Protocol v1 | standalone executable + `tool.json` + Analysis/Trace consumer |
|
||||
| High-performance native callable functions | Callable Plugin ABI v1 | `plugin.yaml`, host-targeted library, SDK/header |
|
||||
| New foreign language backend (R/Python/Julia/…) | Foreign Kernel | `kernel.json`, executable provider, pinned environment |
|
||||
| Hardware/device/external-stream resources | Resource Provider v2 | `provider.json`, C ABI library, worker helper |
|
||||
| Change `@exec` semantics, add keywords/types | **not** a third-party extension | core language RFC + migration + full conformance |
|
||||
|
||||
## Recommended reading order
|
||||
|
||||
1. [quickstart.md](quickstart.md) — install the archive and run the first
|
||||
project.
|
||||
2. [libraries.md](libraries.md) — publish a pure `.mq.md` library and consume
|
||||
it through a pinned Git dependency.
|
||||
3. [tools.md](tools.md) — build an external Tool that consumes Analysis v2 and
|
||||
Trace v2.
|
||||
4. [extensions.md](extensions.md) — plugins, foreign kernels, resource
|
||||
providers, extension selection and lock v4.
|
||||
5. [analysis-trace.md](analysis-trace.md) — the public static/dynamic data
|
||||
contracts and digest binding.
|
||||
6. [compatibility.md](compatibility.md) — version axes, platform matrix and the
|
||||
prerelease policy.
|
||||
7. [release-limits.md](release-limits.md) — the honest beta limitations (this
|
||||
file ships in the archive as `KNOWN_LIMITATIONS.md`).
|
||||
|
||||
The full worked handbook is
|
||||
[`../MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md`](../MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md).
|
||||
Normative contracts live in [`../../spec/`](../../spec/); this directory is a
|
||||
task-oriented map, not a second specification.
|
||||
|
||||
## Baseline repository
|
||||
|
||||
The current implementation and release entry point is
|
||||
[`git.cflmy.cn/cflmy/marqdo-cli`](https://git.cflmy.cn/cflmy/marqdo-cli). The
|
||||
earlier `cflmy/marqdo` repository is a different, incompatible language/product
|
||||
line; it is not a source of current protocol or syntax truth. See the parent
|
||||
repository README for the repository split.
|
||||
|
||||
## Testing against a frozen binary
|
||||
|
||||
Any external repository should be testable without rebuilding the CLI:
|
||||
|
||||
```bash
|
||||
export MARQDO_BIN=/absolute/path/to/marqdo
|
||||
# Put marqdo-provider-worker next to it for provider tests, exactly as the
|
||||
# release archive does.
|
||||
$MARQDO_BIN --version
|
||||
```
|
||||
|
||||
Compute the binary SHA-256 before and after your suite; it must not move. The
|
||||
reference implementation of this gate is
|
||||
[`marqdo-extension-conformance`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance)
|
||||
and `tools/ci/verify_extension_contracts.py` in the core repository.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Analysis v2 and Trace v2 consumers
|
||||
|
||||
Both are public, versioned JSON artifacts. A consumer must read them as files,
|
||||
never link Marqdo's Rust internals or depend on `inspect --ir`.
|
||||
|
||||
## Analysis v2 (static)
|
||||
|
||||
```bash
|
||||
marqdo check index.mq.md --emit ./analysis.json
|
||||
```
|
||||
|
||||
- Write atomically; only publish after `check` exits 0. `--refs` is an
|
||||
independent Markdown-link check and can make `check` fail; on failure the emit
|
||||
target is removed. Do not generate a consumer artifact with
|
||||
`check --refs --emit` without checking the exit code.
|
||||
- `schema: "marqdo.analysis"`, `schema_version: 2`.
|
||||
- Top level: `producer` (`name`, `version` = product version,
|
||||
`markdown_profile`), `project`, `modules`, `diagnostics`.
|
||||
- `project`: `root_id` (`root:<name>@<version>` for manifest projects),
|
||||
`identity_kind`, `lock_digest` (`""` without a lock), `stdlib`
|
||||
(`version`, `digest`, `instance_id`; may be null).
|
||||
- `modules[]`: `id`, `package_instance_id`, `relative_path`, `source_digest`,
|
||||
`units`, `functions`, `imports`, `references`, `calls`, `resources`.
|
||||
Diagnostics are top-level, not per-module.
|
||||
- Byte offsets are UTF-8 source offsets. Stable index keys are logical package
|
||||
instance ids, never absolute paths.
|
||||
- `check` does not load plugin libraries, start kernels/providers or execute the
|
||||
program.
|
||||
- Schemas: `spec/schemas/analysis-v2.schema.json`; contract:
|
||||
`spec/analysis-v2.md`; consumers: `tests/consumers/analysis_consumer.py`,
|
||||
`tests/consumers/validate_protocols.py`.
|
||||
|
||||
View must render the **original Markdown** and use Analysis only to correlate
|
||||
source offsets/heading units/callable mapping. Knowledge must use heading
|
||||
anchors, links, resources, package identity and source digests; it must not
|
||||
assume a `@knowledge` unit has runtime effects. Prove must map only the public
|
||||
proveable subset and distinguish `proved / disproved / unknown / unsupported`;
|
||||
a proof certificate needs matching source digest, semantics and contract
|
||||
identity.
|
||||
|
||||
## Trace v2 (dynamic)
|
||||
|
||||
```bash
|
||||
marqdo run index.mq.md --trace-file ./trace.json
|
||||
```
|
||||
|
||||
- `schema: "marqdo.trace"`, `schema_version: 2`.
|
||||
- `source.analysis_digest` must equal SHA-256 of the **Analysis JSON bytes** for
|
||||
the same project/projection configuration. A mismatch means the trace is
|
||||
stale; do not bind it to the new source. `run --trace-file` does not emit
|
||||
Analysis itself.
|
||||
- Event kinds: `call.enter`, `call.exit`, `branch.eval`, `loop.iteration`,
|
||||
`return`, `effect`, and possibly `trace.truncated`. Sourced events carry a
|
||||
module id and a UTF-8 span.
|
||||
- Defaults are 100,000 events / 32 MiB; `--trace-max-events` and
|
||||
`--trace-max-bytes` adjust them (`0` = unlimited). A consumer must tolerate
|
||||
truncation and must not assume the trace is complete.
|
||||
- Trace records no argument values, secrets or file contents.
|
||||
- Contract: `spec/trace-v2.md`; schema:
|
||||
`spec/schemas/trace-v2.schema.json`; consumer:
|
||||
`tests/consumers/trace_consumer.py`.
|
||||
|
||||
## Consumer rules
|
||||
|
||||
1. Reject unknown schema majors; there is no silent "use latest" fallback.
|
||||
2. Verify `source.analysis_digest` against the actual Analysis file bytes.
|
||||
3. Verify `source.root_id`/package identity; do not key on absolute paths.
|
||||
4. Be deterministic and offline; never execute `.mq.md` yourself, never invent
|
||||
host effects, and never inherit Marqdo grants.
|
||||
5. Report an unsupported/stale artifact explicitly; do not silently downgrade.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Compatibility, versioning and support
|
||||
|
||||
This page summarizes the public support policy. The authoritative matrix is
|
||||
[`../../COMPATIBILITY.md`](../../COMPATIBILITY.md); the beta policy is
|
||||
[`../MARQDO_3_0_PRERELEASE_PLAN.md`](../MARQDO_3_0_PRERELEASE_PLAN.md).
|
||||
|
||||
## Version axes (do not conflate)
|
||||
|
||||
| Axis | `3.0.0-beta.1` value | Change rule |
|
||||
|---|---|---|
|
||||
| Product / CLI | `3.0.0-beta.1` | SemVer prerelease; breaking changes inside the 3.0 beta line are allowed and appear in `CHANGELOG.md`. |
|
||||
| Analysis | v2 | New major for incompatible changes; consumers reject unknown majors. |
|
||||
| Trace | v2 | New major for incompatible changes; binds to exact Analysis bytes. |
|
||||
| CLI Tool | v1 | Frozen manifest/negotiation/bundle contract for v1. |
|
||||
| Plugin ABI | v1 (`1.0`) | Frozen C layout and version negotiation. |
|
||||
| Foreign wire | v1 | One-shot request envelope. |
|
||||
| Provider manifest | v2 | `schema_version: 2`, `abi: c-abi-1`, `transport: worker`. |
|
||||
| Lock | v4 | v3 requires an explicit `marqdo lock` migration; no silent reinterpretation. |
|
||||
| Markdown profile | `marqdo.md.v1` | Frozen parser/options; the RFC-LANG-0002 mapping rewrite did not change the profile id. |
|
||||
| Bundled stdlib | `0.1.0` | Independent package version; not the product version. |
|
||||
| Plugin/tool/example packages | their own | Independent SemVer. |
|
||||
|
||||
`project.marqdo` and a tool's `compatibility.marqdo` are **enforced product
|
||||
ranges**. Beta cores require a prerelease range such as
|
||||
`>=3.0.0-beta.1,<4.0.0`; `>=3.0.0,<4.0.0` does not match a beta core.
|
||||
|
||||
## Platform support (`3.0.0-beta.1`)
|
||||
|
||||
| Platform | Release status | Notes |
|
||||
|---|---|---|
|
||||
| Linux x86_64 (glibc) | **Supported** | Only release archive: CLI + provider worker, same target triple. |
|
||||
| Linux aarch64 | Not built | No artifact; source may build. |
|
||||
| macOS arm64/x86_64 | Experimental, not claimed | Core may run; no macOS provider worker, no plugin ABI claim, no archive. |
|
||||
| Windows x86_64 | Experimental, not claimed | Compile gate only; C ABI/plugin/provider/worker not claimed/fail-closed. |
|
||||
|
||||
Strict is Linux-only and probe-gated. Plugin/provider worker transports are not
|
||||
OS sandboxes. `pure`/`project` are execution modes, not security boundaries.
|
||||
|
||||
## Language compatibility
|
||||
|
||||
`3.0.0-beta.1` implements RFC-LANG-0002 only. Pre-RFC `.mq.md` source
|
||||
(Strong-execute / Emph-return / ordered-list branch / bullet-list loop /
|
||||
block-quote call / first code-span signature) is **not executable**; there is no
|
||||
`--legacy`, syntax switch or downgrade path. Migration is a rewrite task
|
||||
documented in [`../migration/README.md`](../migration/README.md).
|
||||
|
||||
The earlier `cflmy/marqdo` product line is a different architecture; its source
|
||||
syntax, package format and plugin ABI v2 are not compatible and no hidden
|
||||
compatibility layer is provided.
|
||||
|
||||
## Beta policy
|
||||
|
||||
- Beta may break behavior with a changelog note; protocols are versioned
|
||||
separately and only change with a new major.
|
||||
- No LTS is announced. LTS is a later, evidence-based decision (see the
|
||||
prerelease plan §3.2/§5), not a calendar promise.
|
||||
- Known non-security gaps are listed in [release-limits.md](release-limits.md)
|
||||
and in the release notes; unsupported requests must fail closed.
|
||||
- G4 performance is a Beta-only `WARN` on the fixed Woodpecker agent for this
|
||||
release; it is not a general performance guarantee.
|
||||
- Every archive is checksummed and records its source SHA and toolchain.
|
||||
Checksums prove integrity only, not publisher identity.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Plugins, foreign kernels, resource providers and lock v4
|
||||
|
||||
Three independent extension kinds share one principle: **selection is not
|
||||
authorization**. A manifest makes a name visible; the user still grants the
|
||||
exact name or flag at run time. None of these extensions may add a language
|
||||
keyword or a built-in function to the core.
|
||||
|
||||
| Kind | Descriptor | Execution form | Authorization |
|
||||
|---|---|---|---|
|
||||
| Callable plugin | `plugin.yaml` (Plugin ABI v1) | native in-process **only with trust**, or worker child process | `--plugin PATH` + `--allow-plugin NAME` (+ `--trust-native-plugin` for native) |
|
||||
| Foreign kernel | `kernel.json` (Foreign wire v1) | one-shot child process | `--kernel PATH` + `--allow-foreign` |
|
||||
| Resource provider | `provider.json` (Provider manifest v2) | `marqdo-provider-worker` + C ABI v1 library in a child process | `--provider PATH` + `--allow-provider NAME` |
|
||||
|
||||
`pure` and `strict` refuse all three. Worker/child-process transports are crash
|
||||
isolation, **not** OS sandboxes; a C ABI is not a sandbox.
|
||||
|
||||
## 1. Callable plugins
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
name: demo.solver
|
||||
version: 0.1.0 # plugin package version (independent axis)
|
||||
abi: "^1.0" # Plugin ABI major 1
|
||||
kind: worker # native | worker; wasm is rejected
|
||||
exports:
|
||||
- name: solver.add
|
||||
signature: "($a: Int, $b: Int) -> Int"
|
||||
requires:
|
||||
- math.compute
|
||||
artifacts:
|
||||
- target: x86_64-unknown-linux-gnu
|
||||
file: libsolver.so
|
||||
sha256: "<64 lowercase hex of the actual artifact>"
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo plugin inspect path/to/plugin.yaml # static; never loads the library
|
||||
marqdo check index.mq.md --plugin path/to/plugin.yaml
|
||||
marqdo run index.mq.md --plugin path/to/plugin.yaml --allow-plugin demo.solver
|
||||
```
|
||||
|
||||
- `check --plugin` validates the manifest and export signatures without loading
|
||||
the artifact; `run` verifies target triple, file SHA-256, grant, and then
|
||||
reconciles loaded exports/signatures/owners/digests one-to-one with the
|
||||
manifest (`ext.plugin_binding_mismatch` on any difference).
|
||||
- Calls use named arguments; positional arguments are normalised to manifest
|
||||
order but ABI v1 configuration defaults are rejected.
|
||||
- `kind: native` shares the host address space and can crash or compromise it;
|
||||
it requires the explicit unsafe `--trust-native-plugin`. `kind: worker` runs
|
||||
the same library in a child process with framed JSON and timeouts; the C ABI
|
||||
header/SDK is `include/marqdo_plugin_abi_v1.h` and `crates/marqdo-plugin-sdk`.
|
||||
- A runnable host-built example is `examples/plugin-demo/` (native) and its
|
||||
generated manifest; the release archive includes the built artifact.
|
||||
- Normative contract: [`../../spec/plugin-abi.md`](../../spec/plugin-abi.md),
|
||||
[`../../spec/callable-resolution.md`](../../spec/callable-resolution.md).
|
||||
|
||||
## 2. Foreign kernels
|
||||
|
||||
```json
|
||||
{
|
||||
"provider_id": "mocklang",
|
||||
"languages": ["mocklang", "mock"],
|
||||
"wire_version": 1,
|
||||
"entrypoint": "./mocklang",
|
||||
"permissions_requested": [],
|
||||
"digest": "<sha256 of the executable/environment artifact>",
|
||||
"environment_id": "mocklang-env-1"
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo run demo.mq.md --kernel path/to/kernel.json --allow-foreign
|
||||
```
|
||||
|
||||
Fenced `Code` and `Formula` values are inert; the program must call
|
||||
`foreign.run`/`foreign.call` explicitly. The host refuses unauthorized
|
||||
execution, digest mismatch, unexpected exit, timeout and an incompatible wire
|
||||
version. Add a language tag by writing a provider, not by adding an
|
||||
`if language == …` branch to the core. Example:
|
||||
`examples/kernel-mock/`. Normative contract:
|
||||
[`../../spec/foreign.md`](../../spec/foreign.md).
|
||||
|
||||
## 3. Resource providers v2
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.provider",
|
||||
"schema_version": 2,
|
||||
"name": "demo.sensor",
|
||||
"version": "0.1.0",
|
||||
"abi": "c-abi-1",
|
||||
"transport": "worker",
|
||||
"kinds": ["demo.sensor"],
|
||||
"artifacts": [{
|
||||
"target": "x86_64-unknown-linux-gnu",
|
||||
"path": "lib/libsensor.so",
|
||||
"sha256": "<64 lowercase hex>"
|
||||
}],
|
||||
"permissions_requested": []
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo run demo.mq.md \
|
||||
--provider path/to/provider.json \
|
||||
--allow-provider demo.sensor
|
||||
```
|
||||
|
||||
The program still uses the ordinary language surface
|
||||
`resource.open("demo.sensor", "unit-1", ["read"])` plus
|
||||
`resource.read/write/close` and `Memory` for bytes. There is no provider-specific
|
||||
keyword or built-in. The selected provider is verified (schema version, target,
|
||||
artifact SHA-256, duplicate kind, grant) before the sibling
|
||||
`marqdo-provider-worker` starts; a missing helper is
|
||||
`ext.worker_unavailable` and never falls back to `PATH` or in-process loading.
|
||||
Linux x86_64 only for this beta; not an OS sandbox. Runnable example:
|
||||
`examples/provider-demo/` (build with its `build.sh`; the tracked manifest has a
|
||||
zero digest template). Normative contract:
|
||||
[`../../spec/resource-provider-v2.md`](../../spec/resource-provider-v2.md).
|
||||
|
||||
## 4. Reproducible selection: `extensions` + lock v4
|
||||
|
||||
Declare activation sources in the project manifest:
|
||||
|
||||
```yaml
|
||||
extensions:
|
||||
plugins:
|
||||
- from: ./adapter/plugin.yaml
|
||||
kernels: []
|
||||
providers:
|
||||
- from: "@vendor/device/provider.json"
|
||||
```
|
||||
|
||||
`from` is exactly `./relative/path` inside the project or
|
||||
`@alias/relative/path` inside a declared dependency. Absolute/rooted paths,
|
||||
URLs, globs, `..`, symlink escapes and duplicate entries are rejected; the
|
||||
alias must exist in `dependencies`.
|
||||
|
||||
```bash
|
||||
marqdo lock
|
||||
marqdo inspect index.mq.md --extensions --json # identities + lock status; no execution
|
||||
```
|
||||
|
||||
`lock` records manifest and artifact identities (including the selected target)
|
||||
in lock v4. `check`/`sync` compare the declaration to the lock
|
||||
(`ext.extension_lock_mismatch`), and `run` re-verifies the real artifact bytes
|
||||
before starting a worker. Lock v3 gets an explicit `marqdo lock` migration error.
|
||||
Normative contract:
|
||||
[`../../spec/extension-selection.md`](../../spec/extension-selection.md).
|
||||
|
||||
## 5. Frozen-binary test matrix
|
||||
|
||||
Your external repository must pass with an unchanged CLI binary:
|
||||
|
||||
- positive: pinned pure library; plugin under correct grant; kernel under
|
||||
`--allow-foreign`; provider under `--allow-provider`; extension selection
|
||||
locked and re-verified;
|
||||
- negative: wrong export/arity, duplicate export, missing/edited artifact,
|
||||
digest or target mismatch, missing helper, unauthorized grant, wrong lock
|
||||
version, unknown schema major, worker crash/timeout — all must fail with
|
||||
their documented diagnostics and no silent fallback.
|
||||
|
||||
The reference suite is
|
||||
[`marqdo-extension-conformance`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance);
|
||||
the core's evidence generator is `tools/ci/verify_extension_contracts.py`.
|
||||
@@ -0,0 +1,128 @@
|
||||
# Publishing and consuming a pure `.mq.md` library
|
||||
|
||||
A pure library is the preferred extension mechanism: it needs no core change,
|
||||
no C ABI and no rebuild of `marqdo`. It is ordinary Markdown plus executable
|
||||
sections.
|
||||
|
||||
## 1. Repository layout
|
||||
|
||||
```text
|
||||
marqdo-quantum/
|
||||
README.md
|
||||
marqdo.yaml
|
||||
index.mq.md
|
||||
tests/
|
||||
examples/
|
||||
```
|
||||
|
||||
`marqdo.yaml`:
|
||||
|
||||
```yaml
|
||||
project:
|
||||
name: quantum
|
||||
version: 0.1.0
|
||||
marqdo: ">=3.0.0-beta.1,<4.0.0" # enforced against the running core
|
||||
dependencies: {}
|
||||
```
|
||||
|
||||
`index.mq.md`:
|
||||
|
||||
```markdown
|
||||
# @knowledge 量子数学工具
|
||||
|
||||
此包在不修改 Marqdo 内核的情况下向外公开领域函数。
|
||||
|
||||
## @exec 加倍
|
||||
|
||||
`params(x: Int)`
|
||||
|
||||
`return x * 2`
|
||||
```
|
||||
|
||||
Every exported function is an Exec H2. Its `params(...)` declaration is the
|
||||
public contract; keep prose documentation in `@knowledge` sections or
|
||||
paragraphs, which never execute.
|
||||
|
||||
## 2. How a consumer imports it
|
||||
|
||||
Pin a **full 40/64-character commit**; branches and tags are not reproducible:
|
||||
|
||||
```yaml
|
||||
# consumer/marqdo.yaml
|
||||
project:
|
||||
name: quantum-consumer
|
||||
version: 0.1.0
|
||||
marqdo: ">=3.0.0-beta.1,<4.0.0"
|
||||
dependencies:
|
||||
quantum:
|
||||
git: https://github.com/your-org/marqdo-quantum.git
|
||||
rev: 0123456789abcdef0123456789abcdef01234567
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
import:
|
||||
quantum: "@quantum"
|
||||
---
|
||||
|
||||
## @exec main
|
||||
|
||||
`return quantum.加倍(x=21)`
|
||||
```
|
||||
|
||||
An `@alias` import binds the dependency's **entry package** (its
|
||||
`index.mq.md`); qualify calls with the alias as above. A project-relative
|
||||
dependency uses `path: ./deps/x` instead of `git`/`rev`. `marqdo add <alias>
|
||||
--git <url> --rev <sha>` writes the dependency for you.
|
||||
|
||||
## 3. Lock and run
|
||||
|
||||
From the consumer project root:
|
||||
|
||||
```bash
|
||||
marqdo lock # writes marqdo.lock (lock_version: 4)
|
||||
marqdo sync --locked # verify cached content and materialize .marqdo/env; no fetch
|
||||
marqdo check index.mq.md --refs
|
||||
marqdo call index.mq.md main # prints 42
|
||||
```
|
||||
|
||||
Rules that matter for reproducibility:
|
||||
|
||||
- With declared dependencies, `check`/`run`/`call` require `marqdo.lock` and
|
||||
never fetch or rewrite it.
|
||||
- Plain `marqdo sync` may fetch a pinned Git revision named by the lock;
|
||||
`--locked` forbids fetching and fails if the verified cache is unavailable.
|
||||
Both modes verify content digests and never silently update the lock.
|
||||
- A dependency's content digest, manifest digest, instance id
|
||||
(`dep:quantum@0.1.0#<digest>`) and alias edges are all recorded. Drift fails
|
||||
with a "run `marqdo lock`" diagnostic.
|
||||
- `project.marqdo` is enforced; a stale `>=0.1,<1` range is a hard
|
||||
`package.marqdo_incompatible` error, not a warning.
|
||||
|
||||
## 4. Testing your library
|
||||
|
||||
Test it with the released binary only:
|
||||
|
||||
```bash
|
||||
MARQDO_BIN=/opt/marqdo/marqdo
|
||||
$MARQDO_BIN check index.mq.md
|
||||
$MARQDO_BIN call index.mq.md 加倍 --arg x=21
|
||||
```
|
||||
|
||||
Add a consumer fixture that pins a full SHA and assert the `--json` values and
|
||||
diagnostics. For negative cases expect hard errors, never prose fallback:
|
||||
|
||||
- wrong arity/type → `call.arity` / a type diagnostic;
|
||||
- unknown function → `symbol.unknown`;
|
||||
- missing lock with dependencies → a `run marqdo lock` diagnostic;
|
||||
- edited dependency content with a stale lock → lock/content-drift error.
|
||||
|
||||
## 5. Publishing checklist
|
||||
|
||||
- README with a minimal runnable example and the exact CLI product range.
|
||||
- `marqdo.yaml` with an enforced `project.marqdo` range; functions with
|
||||
`params(...)`; all examples migrated to RFC-LANG-0002.
|
||||
- Tests pinned to a full commit SHA; no floating branches.
|
||||
- State that the package is pure `.mq.md` and needs no plugin/provider/kernel.
|
||||
- Version the package independently of the CLI (`0.1.0` here is the package
|
||||
version, not the product version).
|
||||
@@ -0,0 +1,84 @@
|
||||
# Quickstart: install and run
|
||||
|
||||
Product: `3.0.0-beta.1` (Linux x86_64 beta). Install a **release archive**, not
|
||||
a source checkout, when you only consume Marqdo.
|
||||
|
||||
## 1. Install the archive
|
||||
|
||||
```bash
|
||||
sha256sum -c marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz.sha256
|
||||
tar -xzf marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz
|
||||
cd marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu
|
||||
./marqdo --version # marqdo 3.0.0-beta.1
|
||||
./marqdo --help
|
||||
```
|
||||
|
||||
Keep `marqdo` and `marqdo-provider-worker` in the **same directory**. The
|
||||
provider helper is resolved as a sibling; there is no `PATH` fallback, and a
|
||||
missing helper fails closed with `ext.worker_unavailable`. You can move the whole
|
||||
directory or add it to `PATH`:
|
||||
|
||||
```bash
|
||||
export PATH="$PWD:$PATH"
|
||||
marqdo --version
|
||||
```
|
||||
|
||||
## 2. First project
|
||||
|
||||
```bash
|
||||
marqdo init demo
|
||||
cd demo
|
||||
marqdo check index.mq.md
|
||||
marqdo run index.mq.md
|
||||
marqdo call index.mq.md main
|
||||
```
|
||||
|
||||
`init` writes `marqdo.yaml` (with the enforced
|
||||
`marqdo: ">=3.0.0-beta.1,<4.0.0"` range), an RFC-LANG-0002 `index.mq.md` and a
|
||||
`.gitignore`; it does not create a lock, env or git repository.
|
||||
|
||||
```markdown
|
||||
## @exec main
|
||||
|
||||
`问候 = "你好,Marqdo"`
|
||||
|
||||
`打印(问候)`
|
||||
|
||||
`return 问候`
|
||||
```
|
||||
|
||||
`run` executes the entry function (`main` by default) and prints program output;
|
||||
`call` prints the returned value. Use `--json` for machine-readable
|
||||
results (`{"command":"run","success":true,...}`), including embedded program
|
||||
stdout and diagnostics.
|
||||
|
||||
## 3. Language in one screen
|
||||
|
||||
- An H2 marked `@exec` is a callable function; `@knowledge` sections are inert
|
||||
documentation. Unmarked headings inherit the nearest ancestor mode.
|
||||
- `**strong**`, `*emph*` and inline `` `code` `` are interchangeable carriers of
|
||||
one statement each.
|
||||
- Control flow uses keywords: `if`/`else`/`while`/`end`, plus `params(...)` and
|
||||
`return`.
|
||||
- Lists, block quotes and paragraphs are presentation only.
|
||||
- The normative contract is
|
||||
[`../architecture/RFC-LANG-0002-unified-semantics.md`](../architecture/RFC-LANG-0002-unified-semantics.md),
|
||||
[`../../spec/mapping.md`](../../spec/mapping.md) and
|
||||
[`../../spec/expression.ebnf`](../../spec/expression.ebnf).
|
||||
|
||||
## 4. Machine-readable output
|
||||
|
||||
```bash
|
||||
marqdo check index.mq.md --json
|
||||
marqdo run index.mq.md --json
|
||||
marqdo call index.mq.md main --json
|
||||
```
|
||||
|
||||
## 5. Where next
|
||||
|
||||
- Publish/consume a pure library: [libraries.md](libraries.md).
|
||||
- Build an external tool: [tools.md](tools.md).
|
||||
- Plugins, kernels, providers: [extensions.md](extensions.md).
|
||||
- Analysis/Trace consumers: [analysis-trace.md](analysis-trace.md).
|
||||
- Version axes and platform support: [compatibility.md](compatibility.md).
|
||||
- Beta limitations: [release-limits.md](release-limits.md).
|
||||
@@ -0,0 +1,89 @@
|
||||
# Marqdo 3.0.0-beta.1 — known limitations
|
||||
|
||||
This file ships in the release archive as `KNOWN_LIMITATIONS.md`. It is part of
|
||||
the release record: the beta support claim is exactly what is written here.
|
||||
Items marked **unsupported** must fail closed, not be silently emulated.
|
||||
|
||||
## Platform support
|
||||
|
||||
| Platform | Beta status | Notes |
|
||||
|---|---|---|
|
||||
| Linux x86_64 (glibc) | **Supported release platform** | The archived `marqdo` and `marqdo-provider-worker` binaries target `x86_64-unknown-linux-gnu` and are the only binaries this release claims. |
|
||||
| Linux aarch64 | Not built | No release artifact; source may build. |
|
||||
| macOS (arm64/x86_64) | Experimental, not claimed | Core CLI may work, but no macOS provider worker, no native plugin ABI claim and no macOS release artifact. |
|
||||
| Windows x86_64 | Experimental, not claimed | Core CLI may compile/run; the plugin/provider C ABI and provider worker are not claimed. |
|
||||
|
||||
`pure` and `project` are **language execution modes**, not OS sandboxes.
|
||||
`project` may access resources only through explicit grants, but it runs as the
|
||||
user and is not a security boundary against hostile code.
|
||||
|
||||
## `strict` isolation
|
||||
|
||||
`strict` is Linux-only and probe-gated. The beta release claims it only when the
|
||||
same-SHA G3 evidence recorded in `docs/evidence/` is present; otherwise this file
|
||||
and the release notes must say **strict: unsupported** and the runtime must fail
|
||||
closed (no project code executes).
|
||||
|
||||
Even when available:
|
||||
|
||||
* strict L1 covers the pure language plus native Math;
|
||||
* strict L2 (Worker/Foreign/Provider inside strict) is **unsupported** and every
|
||||
such flag is refused with exit 2;
|
||||
* rlimits are used for resource limits, not cgroup-v2 accounting;
|
||||
* the network is denied with a network namespace, not a seccomp allowlist;
|
||||
* a PASS is evidence for isolation correctness, never for performance.
|
||||
|
||||
## Extensions
|
||||
|
||||
* **Callable plugin ABI v1**: native and worker transports exist. Native loads
|
||||
into the host process and requires the explicit unsafe
|
||||
`--trust-native-plugin`; a C ABI is not a sandbox. Worker is crash isolation
|
||||
with handshake/call timeouts, not an OS sandbox. Wasm, hot unload and a full
|
||||
worker capability broker are unsupported. Windows C ABI is not claimed.
|
||||
* **Resource Provider v2**: Linux x86_64 worker transport only. The
|
||||
`marqdo-provider-worker` helper must be next to the `marqdo` executable;
|
||||
missing/renamed helpers fail closed (`ext.worker_unavailable`) and PATH is
|
||||
never consulted. A provider is not a sandbox.
|
||||
* **Foreign kernels**: any language can be registered with `kernel.json`, but
|
||||
the kernel process is a normal child process; it is not sandboxed, and the
|
||||
host must refuse unauthorized, digest-mismatched, timed-out or
|
||||
wire-incompatible kernels.
|
||||
* **CLI tools**: a tool is an ordinary user-authorized executable and does
|
||||
**not** inherit `pure`/`project`/`strict` guarantees from the documents it
|
||||
reads. `MARQDO_BIN`, `MARQDO_TOOL_PROTOCOL`, `MARQDO_PROTOCOL_ANALYSIS` and
|
||||
`MARQDO_PROTOCOL_TRACE` are the only helpers the CLI injects.
|
||||
* **Extension selection** (`marqdo.yaml.extensions`, lock v4) is never
|
||||
authorization. `--allow-plugin`, `--allow-provider` and `--allow-foreign`
|
||||
are still required.
|
||||
|
||||
## Compatibility and versioning
|
||||
|
||||
* `3.0.0-beta.1` is a **prerelease**, not stable and not LTS. Breaking changes
|
||||
inside the 3.0 beta series are allowed and announced in the changelog.
|
||||
* The product version is independent of protocol versions: Analysis v2, Trace
|
||||
v2, Tool v1, Plugin ABI v1, Foreign wire v1, Provider manifest v2 and lock v4
|
||||
keep their own major numbers. Do not infer them from `3.0.0-beta.1`.
|
||||
* The official bundled stdlib keeps its independent package version `0.1.0`.
|
||||
A plugin `.mq.md` package version such as `0.1.0` is also independent.
|
||||
* `project.marqdo` in `marqdo.yaml` is enforced in this release. SemVer
|
||||
prerelease rules apply: `>=3.0.0,<4.0.0` does **not** accept a beta core;
|
||||
beta users must declare a prerelease range such as
|
||||
`>=3.0.0-beta.1,<4.0.0`.
|
||||
* Old `cflmy/marqdo` source syntax, package format and plugin ABI v2 are not
|
||||
compatible. There is no `--legacy` or downgrade path; migration is a separate
|
||||
documented workflow.
|
||||
|
||||
## Artifact integrity
|
||||
|
||||
Archives are accompanied by SHA256 checksums and `RELEASE_INFO.json`
|
||||
(`source_sha`, target triple, toolchain, binary hashes). Checksums prove content
|
||||
integrity only; they are **not** a publisher signature. A digest obtained from
|
||||
an untrusted Git URL does not make the code trustworthy.
|
||||
|
||||
## Deliberately deferred
|
||||
|
||||
strict L2, Wasm plugins, macOS/Windows provider worker, automatic uv/npm
|
||||
environment creation, a distributed package registry, JIT execution, built-in
|
||||
Knowledge/Proof/View commands, a mature async/concurrency model, and platform
|
||||
installers. The planned direction is external Tool repositories consuming the
|
||||
public protocols, not new core commands.
|
||||
@@ -0,0 +1,119 @@
|
||||
# External tools: CLI Tool Protocol v1
|
||||
|
||||
The core does not contain `view`, `knowledge`, `prove`, `lint` or any other
|
||||
product command. A tool is a **separate executable** registered by the user; the
|
||||
CLI only dispatches unknown top-level commands to registered tools and never
|
||||
scans `PATH` for a guessed name.
|
||||
|
||||
Normative contract: [`../../spec/tool-v1.md`](../../spec/tool-v1.md)
|
||||
(implemented and frozen for protocol v1).
|
||||
|
||||
## 1. Package layout
|
||||
|
||||
```text
|
||||
marqdo-view/
|
||||
README.md
|
||||
tool.json
|
||||
bin/marqdo-view # built artifact; not a core-source dependency
|
||||
src/
|
||||
tests/contract/
|
||||
examples/
|
||||
```
|
||||
|
||||
`tool.json` for the `3.0.0-beta.1` product line:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.cli-tool",
|
||||
"schema_version": 1,
|
||||
"name": "marqdo-view",
|
||||
"version": "0.1.0",
|
||||
"command": "view",
|
||||
"entrypoint": "bin/marqdo-view",
|
||||
"compatibility": {
|
||||
"marqdo": ">=3.0.0-beta.1,<4.0.0",
|
||||
"analysis": [2],
|
||||
"trace": [2]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `version` is the **tool's** SemVer.
|
||||
- `compatibility.marqdo` is the **core product** range. A stable-only
|
||||
`>=3.0.0,<4.0.0` does not match a beta core; opt in explicitly. The CLI
|
||||
rejects a mismatched range at install and dispatch time with a
|
||||
`requires marqdo …` diagnostic.
|
||||
- `analysis`/`trace` are declared only if the tool consumes them; the current
|
||||
core provides Analysis v2 and Trace v2.
|
||||
- `command` must match `^[a-z][a-z0-9-]*$` and must not collide with a built-in
|
||||
command (`init`, `run`, `call`, `check`, `inspect`, `fmt`, `plugin`, `add`,
|
||||
`remove`, `lock`, `sync`, `tool`, `help`).
|
||||
- `entrypoint` is package-relative, must be a regular executable file, and the
|
||||
whole bundle is hashed (per-file SHA-256 plus a bundle digest) at install and
|
||||
re-verified before every dispatch.
|
||||
|
||||
## 2. Install, list, dispatch
|
||||
|
||||
```bash
|
||||
marqdo tool install ./marqdo-view # directory containing tool.json
|
||||
marqdo tool list
|
||||
marqdo view --help # dispatched to your executable
|
||||
marqdo view index.mq.md
|
||||
marqdo tool remove view
|
||||
```
|
||||
|
||||
The CLI preserves `cwd`, stdio, exit status and ordinary arguments (no shell
|
||||
string interpolation). It does not interpret the tool's own subcommands or
|
||||
`--help`.
|
||||
|
||||
The tool receives:
|
||||
|
||||
| Variable | Meaning |
|
||||
|---|---|
|
||||
| `MARQDO_BIN` | absolute path of the running `marqdo` executable |
|
||||
| `MARQDO_TOOL_PROTOCOL` | `1` |
|
||||
| `MARQDO_PROTOCOL_ANALYSIS` | `2` when Analysis v2 was negotiated |
|
||||
| `MARQDO_PROTOCOL_TRACE` | `2` when Trace v2 was negotiated |
|
||||
|
||||
Call `$MARQDO_BIN` with an argv array; do not assume `marqdo` is on `PATH`.
|
||||
|
||||
## 3. Consume the public protocols
|
||||
|
||||
Static input (View/Knowledge/Proof):
|
||||
|
||||
```bash
|
||||
"$MARQDO_BIN" check index.mq.md --refs --emit ./analysis.json
|
||||
```
|
||||
|
||||
Dynamic input:
|
||||
|
||||
```bash
|
||||
"$MARQDO_BIN" run index.mq.md --trace-file ./trace.json
|
||||
```
|
||||
|
||||
See [analysis-trace.md](analysis-trace.md) for fields and digest rules. Do not
|
||||
depend on `inspect --ir`: that JSON is not a frozen cross-repository protocol.
|
||||
The `view` tool renders the **original Markdown**, not the Analysis JSON; the
|
||||
Analysis is an index, not a replacement for the source text.
|
||||
|
||||
## 4. Security contract
|
||||
|
||||
A Tool is a normal process started by the user. It does **not** inherit the
|
||||
`pure`/`project`/`strict` guarantees of the `.mq.md` programs it reads, and it
|
||||
must never execute document content implicitly or inherit grants from it.
|
||||
Checksums verify bundle integrity only; they are not publisher authentication.
|
||||
|
||||
## 5. Testing and shipping
|
||||
|
||||
- Test against a **frozen** `marqdo` binary: hash it before/after the suite and
|
||||
fail if it changes.
|
||||
- Cover the negative paths: unknown schema major, incompatible `marqdo` range,
|
||||
reserved command, traversal/symlink entrypoint, tampered bundle file, missing
|
||||
entrypoint, tool crash/exit-status propagation.
|
||||
- Match a real Analysis v2/Trace v2 schema (`spec/schemas/`) and check
|
||||
`source.analysis_digest`.
|
||||
- Include README, minimal example, supported CLI product range, protocol
|
||||
versions, platform matrix, reproducible artifact hashes and limitations.
|
||||
- The archive ships `examples/tool-samples/{sample-view,sample-knowledge,sample-proof}`
|
||||
as independent source examples and `examples/tool-unknown-name/` as a
|
||||
runnable dispatch fixture.
|
||||
@@ -1,8 +1,20 @@
|
||||
# CI release-evidence manifests
|
||||
|
||||
`docs/evidence/ci/<full-40-hex-sha>/manifest.json` is generated by
|
||||
`tools/ci/release_evidence.py` (schema `marqdo.release-gates.v1`) and uploaded
|
||||
by the `release-evidence` CI job. Do not hand-edit a manifest into `PASS`.
|
||||
`tools/ci/release_evidence.py` (schema `marqdo.release-gates.v1`) and recorded
|
||||
for the release. Do not hand-edit a manifest into `PASS`.
|
||||
|
||||
Two profiles are explicit in the manifest (`profile` field):
|
||||
|
||||
* `stable` — required gates are `linux`, `windows`, `macos`, `strict_vm`; every
|
||||
one must be `PASS` on `target_sha`, and `performance` must be `PASS`/`WARN`.
|
||||
* `beta` — the supported scope is declared by `COMPATIBILITY.md`
|
||||
(`3.0.0-beta.1`: Linux x86_64 only). Required gates are `linux`, `strict_vm`,
|
||||
`extension`, `clean_install`, `version_compat`; `windows`/`macos` must be
|
||||
explicitly present as `UNSUPPORTED` (not silently omitted); `strict_vm` may be
|
||||
`UNSUPPORTED` only when the tested policy is an explicit fail-closed refusal;
|
||||
`performance` may be `WARN` with the environment recorded. Decision:
|
||||
`BETA_RELEASE_CANDIDATE`.
|
||||
|
||||
Rules:
|
||||
|
||||
@@ -14,8 +26,8 @@ Rules:
|
||||
same SHA; a URL alone is not enough;
|
||||
* `performance` needs a `MEASURED` report from the fixed node; TCG/QEMU or
|
||||
development-container numbers are not a baseline;
|
||||
* `release_decision` is `RELEASE_CANDIDATE` only when every required gate is
|
||||
PASS with the same SHA and performance is PASS/WARN. Anything else is
|
||||
`DO_NOT_RELEASE`.
|
||||
* `release_decision` is `RELEASE_CANDIDATE` (stable) or
|
||||
`BETA_RELEASE_CANDIDATE` (beta) only when every required gate is satisfied
|
||||
with the same SHA. Anything else is `DO_NOT_RELEASE`.
|
||||
|
||||
The manifest is evidence, not permission to tag; owner approval is separate.
|
||||
+173
-121
@@ -1,161 +1,213 @@
|
||||
# Releasing Marqdo CLI
|
||||
# Releasing Marqdo CLI (`3.0.0-beta.1` and later)
|
||||
|
||||
This document describes the release-candidate procedure. It does **not** grant
|
||||
permission to tag or publish; that requires explicit owner approval and a green
|
||||
required CI matrix on the exact commit.
|
||||
This document is the release-candidate procedure. It does **not** grant
|
||||
permission to tag or publish: a tag requires the gates below to be green on the
|
||||
exact commit and an explicit maintainer sign-off recorded in the release notes.
|
||||
|
||||
## 1. Preconditions
|
||||
Two profiles are deliberately separate (see
|
||||
[`MARQDO_3_0_PRERELEASE_PLAN.md`](MARQDO_3_0_PRERELEASE_PLAN.md) §3):
|
||||
|
||||
- All applicable gates in
|
||||
[`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md) are
|
||||
PASS, and `docs/evidence/ci/<SHA>/manifest.json` has
|
||||
`release_decision: RELEASE_CANDIDATE` with every gate's `tested_sha` equal to
|
||||
the release SHA. The manifest is produced by
|
||||
`tools/ci/release_evidence.py`; a missing, skipped, timed-out or
|
||||
SHA-mismatched gate is not PASS.
|
||||
- **Language migration is closed through 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 is 100% classified, `stdlib/**/*.mq.md` and examples are migrated,
|
||||
and executable-source tests are green at `ffd1cc9`; re-run them for the actual
|
||||
release SHA. Platform and strict-lane evidence are still required before this
|
||||
is 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 **and** a
|
||||
`strict-evidence.json` whose `tested_sha` is the release SHA, or the release
|
||||
explicitly says strict isolation is unavailable with owner approval. Never
|
||||
claim G-C from a local root/sudo run, a container, or a TCG/QEMU timing run.
|
||||
See [`security-gate.md`](security-gate.md) and [`security-vm.md`](security-vm.md).
|
||||
- G4 performance is `MEASURED` on the fixed node with `--approved-node`, or
|
||||
explicitly `UNVERIFIED`/`WARN` with the reason recorded. Never copy a
|
||||
development-container or TCG number. See [`performance.md`](performance.md).
|
||||
- `git status --porcelain` is clean apart from intended release files.
|
||||
- `Cargo.lock` is committed and the build uses `--locked`.
|
||||
* **beta** — a prerelease (`-beta.N`) on the platform(s) the project can really
|
||||
test and fix. Known non-security gaps are allowed only when explicitly
|
||||
recorded. `3.0.0-beta.1` claims **Linux x86_64 (glibc)** only.
|
||||
* **stable** — `3.0.0`/LTS. Not covered by beta exceptions; see
|
||||
[`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md)
|
||||
(historical roadmap input) and the public support matrix.
|
||||
|
||||
## 2. Build verification
|
||||
The binary release pipeline uses the Gitea remote
|
||||
[`git.cflmy.cn/cflmy/marqdo-cli`](https://git.cflmy.cn/cflmy/marqdo-cli) and
|
||||
Woodpecker [`ci.cflmy.cn`](https://ci.cflmy.cn). `.woodpecker/main.yml` runs on
|
||||
`push`/`pull_request`, so a tag push alone does not build release assets; build
|
||||
the archive from the tagged commit on Linux x86_64 and attach it to the Gitea
|
||||
release. Do not publish binaries built from a different checkout.
|
||||
|
||||
## 1. Beta preconditions (non-waivable)
|
||||
|
||||
Freeze one **release SHA** first; any later source change creates a new SHA and
|
||||
requires re-running every gate. On that SHA:
|
||||
|
||||
1. `git status --porcelain` is clean; `Cargo.lock` is committed; all builds use
|
||||
`--locked`.
|
||||
2. `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D
|
||||
warnings`, `cargo test --workspace --locked` PASS.
|
||||
3. `cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker`
|
||||
PASS; both binaries carry the same target triple and source SHA.
|
||||
4. The same-SHA Woodpecker Linux pipeline PASS (fmt, clippy, tests, Windows
|
||||
cross-target compile gate, release build).
|
||||
5. **Frozen-binary external conformance:** build the release binary first, then
|
||||
run the independent fixtures from
|
||||
[`marqdo-extension-conformance`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance)
|
||||
against it and write
|
||||
`docs/evidence/extension/<40-hex-release-sha>/manifest.json` with
|
||||
`tools/ci/verify_extension_contracts.py`. The CLI binary hash must not move
|
||||
during the suite. All seven mandatory result categories PASS.
|
||||
6. **Strict policy (beta gate 5):** either same-SHA `strict-evidence.json` from
|
||||
the disposable VM (`outcome: PASS`, non-root uid) for Linux strict L1, or an
|
||||
explicitly tested **fail-closed `strict: unsupported`** policy in the
|
||||
release notes. A local root/container-only PASS is never promoted to a
|
||||
remote claim; if the evidence is local-VM-only, say exactly that.
|
||||
7. **G4 performance (beta gate 6):** correctness-verified `MEASURED` report on
|
||||
the fixed Woodpecker agent. If the fixed node is still a shared/powersave
|
||||
host, the maintainer may approve a **Beta-only WARN** and must publish the
|
||||
environment and limits; the 9 correctness workloads must still pass. Never
|
||||
report TCG/QEMU or development-container timings as G4.
|
||||
8. `README`, `CHANGELOG`, `COMPATIBILITY`, `docs/STATUS`, this file,
|
||||
`spec/tool-v1.md`, `spec/plugin-abi.md` and the developer docs are on the
|
||||
same fact baseline. No "implemented but says Proposed", no "released but
|
||||
says DO NOT RELEASE", no product/protocol/package version confusion.
|
||||
9. Every shipped binary was actually built and smoke-tested on its claimed
|
||||
platform. The archive records SHA256, `SOURCE_SHA`, toolchain and known
|
||||
limitations; checksums are integrity, not publisher authentication.
|
||||
|
||||
Windows/macOS native lanes, strict L2, uv/npm environment creation, registry,
|
||||
JIT and built-in Knowledge/Proof/View are **not** beta gates; they are listed as
|
||||
unsupported/experimental in
|
||||
[`developers/release-limits.md`](developers/release-limits.md).
|
||||
|
||||
## 2. Build and local gate
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.cargo/bin:$PATH"
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --workspace --all-targets -- -D warnings
|
||||
cargo test --workspace
|
||||
cargo build --release --locked -p marqdo-cli
|
||||
cargo test --workspace --locked
|
||||
cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker
|
||||
```
|
||||
|
||||
## 3. Artifact creation
|
||||
Record the toolchain (`rustc -vV`, `cargo --version`), the release SHA and the
|
||||
binary SHA256 values; `tools/release/package.py` writes them into
|
||||
`RELEASE_INFO.json`.
|
||||
|
||||
The artifact is a tarball containing the binary, license, README, changelog,
|
||||
compatibility matrix, specs, examples and the public protocol consumers. Build
|
||||
it from the repository root:
|
||||
## 3. Release archive
|
||||
|
||||
The archive is built deterministically from a clean tree at `SOURCE_SHA`:
|
||||
|
||||
```bash
|
||||
version="$(cargo metadata --no-deps --format-version 1 \
|
||||
| python3 -c 'import json,sys; print(json.load(sys.stdin)["packages"][0]["version"])')"
|
||||
target="$(rustc -vV | sed -n 's/^host: //p')"
|
||||
stage="dist/marqdo-${version}-${target}"
|
||||
rm -rf "$stage"
|
||||
mkdir -p "$stage"
|
||||
install -m 0755 target/release/marqdo "$stage/"
|
||||
cp LICENSE* CHANGELOG.md COMPATIBILITY.md README.md "$stage/"
|
||||
cp -r spec examples "$stage/"
|
||||
mkdir -p "$stage/tests"
|
||||
cp -r tests/consumers "$stage/tests/"
|
||||
tar -C dist -czf "dist/marqdo-${version}-${target}.tar.gz" "$(basename "$stage")"
|
||||
sha256sum "dist/marqdo-${version}-${target}.tar.gz" \
|
||||
| tee "dist/marqdo-${version}-${target}.tar.gz.sha256"
|
||||
version="$(cargo metadata --no-deps --format-version 1 --offline \
|
||||
| python3 -c 'import json,sys; print(next(p["version"] for p in json.load(sys.stdin)["packages"] if p["name"]=="marqdo-cli"))')"
|
||||
sha="$(git rev-parse HEAD)"
|
||||
python3 tools/release/package.py --version "$version" --source-sha "$sha"
|
||||
# dist/marqdo-<version>-x86_64-unknown-linux-gnu.tar.gz(+.sha256)
|
||||
```
|
||||
|
||||
If the repository has no `LICENSE*` files at release time, do not silently
|
||||
skip the license requirement: add them before shipping.
|
||||
Contents: `marqdo` **and** `marqdo-provider-worker` in the same directory,
|
||||
`LICENSE-*`, `README.md`, `CHANGELOG.md`, `COMPATIBILITY.md`,
|
||||
`RELEASE_INFO.json`, `SOURCE_SHA`, `KNOWN_LIMITATIONS.md`, `spec/`,
|
||||
`docs/developers/`, `examples/` (with host-built plugin/provider artifacts so
|
||||
the examples run without a compiler) and `tests/consumers/`.
|
||||
|
||||
## 4. Clean-install smoke
|
||||
Do not publish an archive with only the CLI, with a mismatched worker target, or
|
||||
with a checksum that does not match the bytes.
|
||||
|
||||
Run in a fresh directory (not the source tree). The example commands below
|
||||
assume the examples are migrated to RFC-LANG-0002 and accepted by the frozen
|
||||
binary; a failing example run is a release blocker, not a known migration
|
||||
artifact:
|
||||
## 4. Clean-install smoke (from the archive only)
|
||||
|
||||
Run outside the source tree. The script below extracts the archive into a fresh
|
||||
directory and exercises only the shipped binaries:
|
||||
|
||||
```bash
|
||||
tmp="$(mktemp -d)"
|
||||
tar -C "$tmp" -xzf dist/marqdo-*.tar.gz
|
||||
cd "$tmp"/marqdo-*
|
||||
./marqdo --version
|
||||
./marqdo --help >/dev/null
|
||||
./marqdo check examples/multi-module/index.mq.md
|
||||
./marqdo run examples/hello.mq.md
|
||||
./marqdo call examples/factorial.mq.md 阶乘 --arg n=5
|
||||
./marqdo check examples/multi-module/index.mq.md --refs --emit analysis.json
|
||||
./marqdo run examples/multi-module/index.mq.md --trace-file trace.json
|
||||
python3 tests/consumers/analysis_consumer.py analysis.json
|
||||
python3 tests/consumers/trace_consumer.py analysis.json trace.json
|
||||
python3 tests/consumers/validate_protocols.py analysis.json trace.json \
|
||||
examples/tool-unknown-name/tool.json
|
||||
python3 tools/release/smoke.py \
|
||||
--archive dist/marqdo-*.tar.gz
|
||||
```
|
||||
|
||||
Also verify the SHA-256 file before extraction:
|
||||
It verifies the `.sha256`, `RELEASE_INFO.json`/`SOURCE_SHA`, offline
|
||||
`--version`/`--help`, `check`/`run`/`call`, lock/sync, Analysis v2 and Trace v2
|
||||
consumers, Tool install/dispatch, native + worker plugin transports, a foreign
|
||||
kernel, Resource Provider v2 through the shipped worker (positive,
|
||||
unauthorized and missing-helper fail-closed), and strict mode when the host
|
||||
actually supports it. A failure is a release blocker.
|
||||
|
||||
## 5. Release evidence manifest
|
||||
|
||||
```bash
|
||||
sha256sum -c dist/marqdo-*.tar.gz.sha256
|
||||
sha="$(git rev-parse HEAD)"
|
||||
python3 tools/ci/release_evidence.py --profile beta --target-sha "$sha" \
|
||||
--gate linux=PASS:$sha:<woodpecker-pipeline-url> \
|
||||
--gate strict_vm=PASS:$sha:docs/evidence/<strict-doc> \
|
||||
--gate extension=PASS:$sha:docs/evidence/extension/$sha/manifest.json \
|
||||
--gate clean_install=PASS:$sha:docs/evidence/<smoke-doc> \
|
||||
--gate version_compat=PASS:$sha:<version-test-log-or-pipeline> \
|
||||
--gate windows=UNSUPPORTED:$sha:linux-only-beta-support-matrix \
|
||||
--gate macos=UNSUPPORTED:$sha:linux-only-beta-support-matrix \
|
||||
--gate performance=WARN:$sha:docs/evidence/<g4-doc> \
|
||||
--out "docs/evidence/ci/$sha/manifest.json"
|
||||
```
|
||||
|
||||
## 5. Tagging and publication
|
||||
`BETA_RELEASE_CANDIDATE` is the only acceptable decision for a beta tag. A
|
||||
missing, skipped, failed or SHA-mismatched gate is `DO_NOT_RELEASE`; never
|
||||
hand-edit a manifest to PASS. Stable releases use the default `--profile
|
||||
stable` and additionally require Windows/macOS PASS and a strict PASS.
|
||||
|
||||
Only after the above and the remote CI matrix are green on the release commit:
|
||||
## 6. Tagging and publication (owner approval required)
|
||||
|
||||
Only after all gates above are green on the frozen SHA:
|
||||
|
||||
```bash
|
||||
git fetch origin --tags
|
||||
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/master)"
|
||||
git tag -s "v${version}" -m "Marqdo CLI v${version}"
|
||||
git tag -a "v${version}" -m "Marqdo CLI v${version}" "$sha"
|
||||
git push origin "v${version}"
|
||||
# upload the tarball and .sha256 to the release
|
||||
```
|
||||
|
||||
Do not force-push, do not tag a red commit, and do not upload macOS/Windows
|
||||
binaries unless those platform lanes actually passed.
|
||||
Then create the Gitea release for the tag with `prerelease: true`, attach the
|
||||
tarball and its `.sha256`, and include the release notes. The notes must state:
|
||||
|
||||
The current `0.1.0` candidate at `8af7262` is **not** releasable: it has local
|
||||
Linux/VM evidence and a checksummed Linux RC, but no same-SHA GitHub CI or
|
||||
self-hosted G-C URL. See
|
||||
[`evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md`](evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md).
|
||||
* beta / non-LTS status and the Linux x86_64-only support claim;
|
||||
* the breaking RFC-LANG-0002 language change and no legacy path;
|
||||
* the strict policy (same-SHA evidence, or `strict: unsupported` fail-closed);
|
||||
* the G4 Beta-only WARN environment and limits when applicable;
|
||||
* independently versioned protocols and stdlib/package versions;
|
||||
* the checksum-integrity-not-signature caveat and the known-limitations file;
|
||||
* the exact source SHA and links to the evidence manifest.
|
||||
|
||||
## 6. Rollback
|
||||
Example Gitea API shape (token with repository release permission; never commit
|
||||
the token):
|
||||
|
||||
- If an asset fails verification: delete the release asset and keep the tag
|
||||
only if source/tag integrity is unaffected; otherwise publish a revised
|
||||
patch release and mark the old one withdrawn.
|
||||
- If a platform regresses: remove that platform from the supported matrix in
|
||||
`COMPATIBILITY.md` and the release notes, fix, and re-run the gate. Never
|
||||
delete the failing test.
|
||||
- If the security gate regresses: set strict back to `Unavailable`, publish a
|
||||
security note, and do not claim isolation until the lane is green again.
|
||||
```bash
|
||||
curl -X POST -H "Authorization: token $MARQDO_GIT_TOKEN" \
|
||||
-H 'Content-Type: application/json' \
|
||||
https://git.cflmy.cn/api/v1/repos/cflmy/marqdo-cli/releases \
|
||||
-d '{"tag_name":"v3.0.0-beta.1","name":"Marqdo CLI 3.0.0-beta.1",
|
||||
"prerelease":true,"draft":false,"body":"..."}'
|
||||
curl -X POST -H "Authorization: token $MARQDO_GIT_TOKEN" \
|
||||
-F "attachment=@dist/marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz" \
|
||||
https://git.cflmy.cn/api/v1/repos/cflmy/marqdo-cli/releases/<id>/assets
|
||||
```
|
||||
|
||||
## 7. Extension-ecosystem gate (RFC-EXT-0001)
|
||||
The tag points at the tested SHA. Evidence files and the final STATUS update
|
||||
may land in a **post-release docs commit** that references the tagged SHA, so
|
||||
that the evidence never has to claim a SHA it cannot contain. Do not force-push,
|
||||
do not tag a red commit, and do not upload macOS/Windows binaries unless those
|
||||
platform lanes actually passed.
|
||||
|
||||
Before a tag, in addition to §3 and §4:
|
||||
## 7. Rollback
|
||||
|
||||
1. `cargo build --release --locked -p marqdo-cli` and build
|
||||
`-p marqdo-provider-worker`; ship both binaries in the release archive for
|
||||
the same target. A provider request without the sibling helper must fail
|
||||
with `ext.worker_unavailable` — never fall back to `PATH`.
|
||||
2. Run the external frozen-binary suite from
|
||||
`https://git.cflmy.cn/cflmy/marqdo-extension-conformance` against the exact
|
||||
release binaries and generate
|
||||
`docs/evidence/extension/<40-hex-source-SHA>/manifest.json` with
|
||||
`tools/ci/verify_extension_contracts.py`. The manifest must validate against
|
||||
`docs/evidence/extension/schema.json`, its `tested_sha` must equal the
|
||||
tagged commit, and every mandatory result must be `PASS` on the claimed
|
||||
platform. `UNSUPPORTED` is allowed only for a platform explicitly excluded
|
||||
from the support matrix in `COMPATIBILITY.md`.
|
||||
3. `check`/`run`/`inspect`/Analysis share one prepared call binding
|
||||
(`spec/callable-resolution.md`); `check` never loads an extension binary;
|
||||
plugin exports reconcile exactly with static manifests; official stdlib
|
||||
aliases are verified metadata with byte-identical print output.
|
||||
4. Existing gates remain mandatory and unchanged: G3 strict isolation evidence,
|
||||
G4 measured performance on the fixed node, native platform lanes, schema
|
||||
consumers and `tools/ci/release_evidence.py`. The extension evidence is an
|
||||
additional gate; it never substitutes for them, and local/container smoke is
|
||||
not a release claim.
|
||||
5. If any extension gate is missing or mismatched, the release decision is
|
||||
**DO NOT RELEASE**. Tagging and asset publication still require explicit
|
||||
owner approval.
|
||||
- Missing/mismatched gate discovered after tagging: mark the release withdrawn,
|
||||
delete the assets, keep the tag only if source/tag integrity is unaffected,
|
||||
and ship a corrected prerelease (for example `3.0.0-beta.2`). Never delete a
|
||||
failing test.
|
||||
- Platform regression: remove that platform from `COMPATIBILITY.md`, the
|
||||
release notes and the archive, then fix and re-run the gate.
|
||||
- Security regression: set strict back to fail-closed/unsupported, publish a
|
||||
security note, and do not claim isolation until fresh same-SHA evidence
|
||||
exists.
|
||||
- Performance regression: keep the previous fixed-node baseline, record the
|
||||
new WARN/FAIL truthfully, and do not substitute another machine.
|
||||
|
||||
## 8. Extension-ecosystem gate (additional, never a substitute)
|
||||
|
||||
The external conformance gate is mandatory for every tag. It proves that an
|
||||
unchanged CLI binary accepts independent `.mq.md` packages, plugins, foreign
|
||||
kernels, resource providers and CLI tools, and that the negative paths
|
||||
(unauthorized, wrong digest, wrong target, wrong schema, tampered artifact)
|
||||
fail closed. Generate the manifest with
|
||||
`tools/ci/verify_extension_contracts.py`; its `tested_sha` must equal the
|
||||
tagged commit and its CLI binary hash must be the shipped binary. See
|
||||
[`evidence/extension/README.md`](evidence/extension/README.md).
|
||||
|
||||
## 9. Stable releases
|
||||
|
||||
The beta exceptions in §1 (platform scope, G4 WARN, strict-unsupported policy)
|
||||
do **not** apply to `3.0.0` or LTS. A stable release requires every committed
|
||||
feature on the supported platforms to have same-SHA security, compatibility and
|
||||
performance evidence, a public change/migration policy, and a real user-feedback
|
||||
cycle. Until then the product stays a prerelease.
|
||||
@@ -9,7 +9,7 @@ ordinary user `dev` (uid 1000), QEMU/TCG guest, 7/7 adversarial tests plus the
|
||||
strict `--json` and inert-`@knowledge` contracts — see
|
||||
[`evidence/2026-11-21-strict-gc-5fcc111.md`](evidence/2026-11-21-strict-gc-5fcc111.md).
|
||||
The older `8af7262` and `b6fc182` runs are retained below as history.
|
||||
Snapshot: workspace `0.1.0`, 2026-11-21. See ADR-0021 and ADR-0053.
|
||||
Snapshot: product `3.0.0-beta.1`, 2026-11-22. See ADR-0021 and ADR-0053.
|
||||
|
||||
> **Language-syntax status.** The lane was re-run on the RFC-LANG-0002 tree
|
||||
> ([`architecture/RFC-LANG-0002-unified-semantics.md`](architecture/RFC-LANG-0002-unified-semantics.md))
|
||||
|
||||
Reference in new issue
Block a user