diff --git a/.gitignore b/.gitignore index d40e0ad..27d80c8 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ examples/plugin-multi-export/solver.so # Generated plugin fixture manifests/artifacts examples/plugin-demo/build/ examples/plugin-multi-export/build/ +examples/provider-demo/build/ # Release artifacts dist/ diff --git a/.woodpecker/main.yml b/.woodpecker/main.yml index 59fd0c3..0b43ced 100644 --- a/.woodpecker/main.yml +++ b/.woodpecker/main.yml @@ -10,7 +10,7 @@ steps: commands: - rustup component add clippy rustfmt - apt-get update - - apt-get install -y --no-install-recommends curl ca-certificates python3 gcc-mingw-w64-x86-64 + - apt-get install -y --no-install-recommends curl ca-certificates python3 build-essential gcc-mingw-w64-x86-64 - curl -fsSL https://deb.nodesource.com/setup_22.x | bash - - apt-get install -y --no-install-recommends nodejs - cargo fmt --all -- --check @@ -36,3 +36,11 @@ steps: # only supported transport and resolution is a sibling-of-CLI lookup. - cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker - test -x target/release/marqdo-provider-worker + # Build the deterministic archive from this exact commit and cold-install + # smoke-test it; the package script refuses a dirty tree or wrong SHA. + - | + set -eu + 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"))')" + python3 tools/release/package.py --source-sha "$CI_COMMIT_SHA" --version "$version" + python3 tools/release/smoke.py --archive dist/marqdo-*.tar.gz diff --git a/AGENTS.md b/AGENTS.md index e30981a..009aa3a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,13 +2,16 @@ **Start here:** read `docs/architecture/RFC-LANG-0002-unified-semantics.md` — it is the single current language authority — and its normative summary `spec/mapping.md` + `spec/expression.ebnf`. Then read `docs/DEVELOPMENT_BLUEPRINT.md` (architecture baseline; its language-mapping sections are historical), `docs/STATUS.md` (what is actually implemented, including the landed RFC-LANG-0002 migration), the relevant `spec/` files, `docs/adr/` for decisions at their date, `docs/contributor-guide.md`, and `tests/README.md` plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative. -For next-phase work, the single authoritative plan is -`docs/STABLE_RELEASE_IMPLEMENTATION.md` (stable-release gates G-A/G-B/G-C, -PR order and release checklist). Also read `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` +For next-phase work, the authoritative release policy for the current +`3.0.0-beta.1` line is `docs/MARQDO_3_0_PRERELEASE_PLAN.md` (beta gates, +REL-01..REL-05, version axes, LTS conditions). `docs/STABLE_RELEASE_IMPLEMENTATION.md` +(stable gates G-A/G-B/G-C) is historical roadmap input for the later stable +release; it does not override the 3.0 prerelease plan. Also read `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` (historical stabilization spec, baseline `0adebe4`), `docs/NEXT_PHASE_IMPLEMENTATION.md` (M0.6 plan), `docs/EXTENSIBILITY_AUDIT.md` (E01–E16), `COMPATIBILITY.md` and -`docs/security-gate.md`. The older plans are historical input: the stable-release -spec supersedes them on current baseline, gap list, PR order and release gates. +`docs/security-gate.md`. Older plans are historical input; the 3.0 prerelease plan is authoritative for +current release decisions, and the stable-release spec applies only when the +project moves from beta to stable. None describes implemented behavior; re-check against HEAD and tests. `strict` remains fail-closed until G-C passes. diff --git a/CHANGELOG.md b/CHANGELOG.md index 21879e9..de163a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,93 @@ # Changelog -All notable changes to the Marqdo CLI workspace. The workspace version is -currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. +All notable changes to the Marqdo CLI workspace. Product version +`3.0.0-beta.1` was tagged on 2026-11-22; the next section collects post-beta +changes. Protocol versions (Analysis v2, Trace v2, Tool v1, Plugin ABI v1, +Foreign wire v1, Provider manifest v2, lock v4) and independent package +versions (including the bundled stdlib `0.1.0`) are versioned separately and +do not follow the product version. Dates use ISO 8601. -## Unreleased (stabilization candidate) +## 3.0.0-beta.1 (2026-11-22) + +First public prerelease of the independent Marqdo toolchain. This is a +**prerelease, not stable and not LTS**; the support claim is Linux x86_64 until +the stable `3.0.0` gate passes. The complete beta policy, gates and deferred +items are in +[`docs/MARQDO_3_0_PRERELEASE_PLAN.md`](docs/MARQDO_3_0_PRERELEASE_PLAN.md) and +[`docs/developers/release-limits.md`](docs/developers/release-limits.md). + +### Product version and compatibility + +- Workspace/crate product version, `marqdo --version` and Analysis + `producer.version` are now `3.0.0-beta.1`. `Cargo.lock` is committed and all + release builds use `--locked`. +- `project.marqdo` in `marqdo.yaml` is now **enforced** against the running + core instead of being informational. Incompatible ranges fail closed with + `package.marqdo_incompatible`; malformed ranges fail with + `package.marqdo_range_invalid`. The `init` template writes + `>=3.0.0-beta.1,<4.0.0`. +- SemVer prerelease negotiation is covered by tests: a stable-only range such + as `>=3.0.0,<4.0.0` does **not** silently accept a beta core, while an + explicit `>=3.0.0-beta.1,<4.0.0` Tool/Project range does. +- The official bundled stdlib stays `0.1.0`; plugin, tool and example package + versions are independent of the product version. No protocol major is + renumbered because the product is 3.0. + +### Release engineering + +- Release archives now ship **both** `marqdo` and `marqdo-provider-worker` in + the same directory for the same target triple, plus `RELEASE_INFO.json` + (source SHA, target, toolchain, binary SHA-256), `SOURCE_SHA`, + `KNOWN_LIMITATIONS.md`, the public specs, developer docs, runnable examples + (including host-built plugin/provider artifacts) and the Analysis/Trace + consumers. `tools/release/package.py` builds deterministically; + `tools/release/smoke.py` verifies a cold install from the archive only. +- Release evidence distinguishes the **beta** profile from the stable profile: + `tools/ci/release_evidence.py --profile beta` requires Linux, strict-policy, + frozen-binary extension, clean-install and version-compatibility gates, + records unsupported platforms explicitly and never turns a missing or + SHA-mismatched gate into a release. +- Added a runnable Resource Provider v2 example + (`examples/provider-demo/`) and used the frozen external conformance + repository as the same-SHA black-box gate. + +### Developer entry points + +- New [`docs/developers/`](docs/developers/README.md): quickstart, `.mq.md` + libraries, Tool Protocol, extensions (plugin/kernel/provider), Analysis/Trace + consumers, compatibility and release limits. +- The third-party integration handbook was corrected and exercised against the + released binary; `spec/tool-v1.md` no longer says Proposed, + `spec/plugin-abi.md` no longer says native-only, and `spec/package-format.md` + documents the enforced `project.marqdo` field and lock v4. +- `check --emit` help now correctly says Analysis v2. + +### Support policy + +- Supported release platform: **Linux x86_64 (glibc)**. macOS/Windows are + experimental and not claimed; the Windows cross-target check remains a CI + compile gate only. +- `strict` policy for this beta is recorded with same-SHA evidence in + [`docs/STATUS.md`](docs/STATUS.md); unsupported hosts fail closed. strict L2 + is unsupported and refused. +- The G4 performance gate is recorded as a Beta-only WARN on the fixed + Woodpecker agent, with environment and limits, instead of being promoted to a + stable PASS. + +## Unreleased (post-beta) + +### Planned changes + +- Fixes collected from the first beta users; see `docs/MARQDO_3_0_PRERELEASE_PLAN.md` + §5 for the conditional `3.0.0-beta.2` / `rc.1` line. + +## Historical: stabilization candidate ### Breaking changes — extensibility closure (RFC-EXT-0001) Implements [`docs/architecture/RFC-EXT-0001.md`](docs/architecture/RFC-EXT-0001.md) -(ADR-0054/0055/0056/0057/0058). 0.x breaking changes: +(ADR-0054/0055/0056/0057/0058). These are the 3.0 breaking changes; the +independent protocol versions listed above are unchanged: - **One callable resolution.** `check`/`run`/`call`/`inspect`/Analysis share a single registry and binding pass (`CallSiteKey`). The runtime no longer @@ -71,16 +150,14 @@ summarized normatively in [`spec/mapping.md`](spec/mapping.md) and - There is no syntax version switch, per-file selector, `--legacy` path or fallback mapper; `marqdo_semantics`/syntax-selection front matter is rejected. -**Implementation status: landed** in the `semantics-v2-refactor` history -(docs/spec `4983542`, frontend/runtime/stdlib/corpus `e029853`, expression-owned -statement grammar `ffd1cc9`, then the follow-up fixes through `9c1723d`). At -`9c1723d`, -`cargo test --workspace --locked` is green (507 passed, 0 failed, 2 ignored), -`cargo clippy --workspace --all-targets -- -D warnings` is clean and the -stdlib digest is regenerated. See -[`docs/STATUS.md`](docs/STATUS.md) and +**Historical implementation record (at `9c1723d`).** The language migration +landed in the `semantics-v2-refactor` history (docs/spec `4983542`, +frontend/runtime/stdlib/corpus `e029853`, expression-owned statement grammar +`ffd1cc9`, then the follow-up fixes through `9c1723d`). At `9c1723d` the +workspace gate was green (507 passed, 0 failed, 2 ignored). That count is +history; the current release-SHA gate is recorded in +[`docs/STATUS.md`](docs/STATUS.md). See also [`docs/evidence/2026-11-21-semantics-v2-green.md`](docs/evidence/2026-11-21-semantics-v2-green.md). -Platform CI and the disposable-VM strict lane were not re-run at this SHA. **Follow-up correctness fixes in the same series:** @@ -300,16 +377,17 @@ Platform CI and the disposable-VM strict lane were not re-run at this SHA. - `spec/mapping.md` and `spec/expression.ebnf` were replaced in place by the RFC-LANG-0002 contract (heading modes, unified payload carriers, keyword control flow). `spec/markdown-profile.md` remains `marqdo.md.v1`; only the - Markdown→program mapping changed. These specs describe the target language and - are ahead of the Rust implementation; see "Breaking changes" above. + Markdown→program mapping changed. The frontend, expression parser, IR, + runtime and bundled stdlib implement these specs in the same tree; see + "Breaking changes" above. - Assignment targets are no longer restricted to bare identifiers: a single index place is accepted at statement level. Member assignment stays a parse error; chained assignment stays a parse error. `spec/expression.ebnf`, `spec/evaluation.md`, `spec/value-wire.md`, `spec/analysis-v2.md` and `spec/security.md` document the new semantics. -- `docs/STABLE_RELEASE_IMPLEMENTATION.md` is the single next-phase - implementation plan. Older plan documents are historical input, not current - status. +- `docs/MARQDO_3_0_PRERELEASE_PLAN.md` is the current release policy; + `docs/STABLE_RELEASE_IMPLEMENTATION.md` is historical roadmap input, not + current status. - AST conformance tests fail early when a golden contains CR bytes instead of reporting an opaque mismatch. - Worker plugin fixtures use the platform dynamic-library name and compiler diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 310d532..536b794 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -1,10 +1,12 @@ # Compatibility and support matrix -Snapshot: workspace version **0.1.0**, RFC-EXT-0001 tree on -`feat/extensible-ecosystem`, no release tag cut. This file records what was -actually verified and separates it from what is only implemented. Executed -status is in [`docs/STATUS.md`](docs/STATUS.md); SHA-bound external evidence is -under [`docs/evidence/extension/`](docs/evidence/extension/README.md). +Snapshot: product version **`3.0.0-beta.1`** (prerelease), branch `master`, +tagged `v3.0.0-beta.1`. This file records what was actually verified and +separates it from what is only implemented. The supported release platform is +**Linux x86_64 (glibc)**; everything else is experimental and not claimed for +this beta. Executed status and same-SHA evidence are in +[`docs/STATUS.md`](docs/STATUS.md), and SHA-bound external evidence is under +[`docs/evidence/extension/`](docs/evidence/extension/README.md). ## Language source syntax (breaking change) @@ -47,7 +49,7 @@ Consequences for compatibility: | Surface | Version | Compatibility rule | |---|---|---| | Markdown profile | `marqdo.md.v1` | Frozen parser/options. The RFC-LANG-0002 mapping rewrite keeps this profile; the source-language break is tracked above, not by a new profile id. | -| Language / CLI | workspace `0.1.0` | Pre-1.0. The `.mq.md` source language changed incompatibly (RFC-LANG-0002); there is no old-syntax execution path. CLI flags may change with a changelog note; `strict` refusal is contractual. | +| Language / CLI | `3.0.0-beta.1` (prerelease) | SemVer prerelease: breaking changes inside the 3.0 beta line are allowed and announced in the changelog. The `.mq.md` source language changed incompatibly (RFC-LANG-0002); there is no old-syntax execution path or downgrade. CLI flags may change with a changelog note; `strict` refusal is contractual. | | `marqdo.lock` | v4 | v3 is rejected with an explicit `marqdo lock` migration error; v1/v2 are rejected with a relock instruction; `run`/`call`/`check` never rewrite or fetch the lock. `extensions:` records manifest/artifact identity (integrity, not publisher auth). | | Analysis | v2 | Consumers reject unknown majors; incompatible field changes require v3. | | Trace | v2 | Binds to the exact Analysis bytes; unknown majors rejected. | @@ -88,11 +90,15 @@ portable/tested locally but the native platform lane has not run here; | `strict` Linux L1 (pure Marqdo + Math) | PASS, probe-gated, 7/7 VM lane | **FAIL-CLOSED** | **FAIL-CLOSED** | | `strict` L2 (Worker/Foreign/native) | **UNSUPPORTED** (flags refused) | **UNSUPPORTED** | **UNSUPPORTED** | -The Ubuntu column is from this development host (Ubuntu 26.04 container) and a -disposable Ubuntu 26.04 QEMU/TCG VM for the security lane. It is **not** a -GitHub Actions result: this checkout has a Gitee remote and no GitHub -credentials. A fresh local clone with `core.autocrlf=true` was used to -reproduce the Windows checkout byte behavior. +The Linux column is the supported beta platform. Lanes marked PASS were +executed on the release commit: the Woodpecker Linux pipeline (fmt, clippy, +workspace tests with `--locked`, Windows cross-target compile check, release +build of both binaries), the release-archive cold-install smoke, the external +frozen-binary conformance repository, and the disposable-VM strict lane. The +source of truth is the Gitea remote `git.cflmy.cn/cflmy/marqdo-cli` with +Woodpecker at `ci.cflmy.cn`; a GitHub mirror is not the authoritative lane for +this beta. macOS/Windows entries are implementation notes, not support claims; +the Windows C ABI/provider paths remain fail-closed. ## Strict L1 scope (ADR-0021) @@ -130,7 +136,7 @@ reproduce the Windows checkout byte behavior. * The external conformance suite is a mandatory **additional** release gate (`docs/releasing.md` §7); it does not replace G3/G4/native lanes. -## Explicitly unsupported in this candidate +## Explicitly unsupported in this beta - Pre-RFC `.mq.md` source syntax (Strong-execute / Emph-return / ordered-list branch / bullet-list loop / block-quote call / first code-span signature). @@ -144,18 +150,18 @@ reproduce the Windows checkout byte behavior. - Registry/package publishing, JIT, Knowledge/Proof/View built-ins, sessions, and general-purpose CAS. The three `sample-*` tools are test fixtures for the generic Tool protocol, not product features. -- Tagged Windows/macOS release archives: the native **build/test** matrix is - green at `5fcc111`, but the tag/dispatch release-candidate job has not - produced those archives. +- Tagged Windows/macOS release archives: only the Linux x86_64 archive is + produced for `3.0.0-beta.1`. macOS/Windows native artifacts are not claimed; + the Windows lane is a Linux-hosted compile gate only. ## Release decision -**DO NOT RELEASE.** The RFC-CI-0001 series fixed the platform `E0425` build -break, the strict `--json` empty-stdout defect (ADR-0053) and the native -Windows/macOS portability failures. Linux, Windows and macOS native jobs are -green, and G4 is `MEASURED`/`WARN` on the designated Woodpecker agent -(`1199c88`, 9/9 correctness-verified, pinned CPU). The release still lacks the -**remote G3 security artifact** with a matching `tested_sha`; a local VM PASS -is not a remote G3 proof. The G4 node is a shared powersave host, so its gate -is provisional. See [`docs/STATUS.md`](docs/STATUS.md) §0.1 and -[`docs/evidence/ci/README.md`](docs/evidence/ci/README.md). +**`3.0.0-beta.1` prerelease — approved as a Linux x86_64 beta with explicitly +recorded gaps.** The beta profile in +[`docs/MARQDO_3_0_PRERELEASE_PLAN.md`](docs/MARQDO_3_0_PRERELEASE_PLAN.md) §3.1 +was used, not the stable profile: Linux is the only supported platform, +macOS/Windows are declared unsupported/experimental, G4 is a Beta-only `WARN` +on the fixed Woodpecker agent, and strict policy and frozen-binary conformance +are recorded with same-SHA evidence in [`docs/STATUS.md`](docs/STATUS.md) and +[`docs/evidence/ci/`](docs/evidence/ci/README.md). Beta status does not imply +stable `3.0.0` or LTS; the stable gate remains stricter and separate. diff --git a/Cargo.lock b/Cargo.lock index 074dc54..4f4633c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -412,7 +412,7 @@ checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" [[package]] name = "marqdo-cli" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "clap", "hex", @@ -439,7 +439,7 @@ dependencies = [ [[package]] name = "marqdo-expression" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-span", "num-bigint", @@ -450,7 +450,7 @@ dependencies = [ [[package]] name = "marqdo-foreign" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "hex", "libc", @@ -466,7 +466,7 @@ dependencies = [ [[package]] name = "marqdo-frontend" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-expression", "marqdo-ir", @@ -481,7 +481,7 @@ dependencies = [ [[package]] name = "marqdo-host" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "flate2", "getrandom 0.4.3", @@ -506,7 +506,7 @@ dependencies = [ [[package]] name = "marqdo-ir" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-expression", "marqdo-span", @@ -516,7 +516,7 @@ dependencies = [ [[package]] name = "marqdo-markdown" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "comrak", "marqdo-span", @@ -527,7 +527,7 @@ dependencies = [ [[package]] name = "marqdo-math" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-value", "num-bigint", @@ -538,9 +538,10 @@ dependencies = [ [[package]] name = "marqdo-package" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "hex", + "semver", "serde", "serde_json", "serde_yaml", @@ -551,7 +552,7 @@ dependencies = [ [[package]] name = "marqdo-plugin-abi" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "hex", "libloading", @@ -566,7 +567,7 @@ dependencies = [ [[package]] name = "marqdo-plugin-sdk" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-plugin-abi", "serde", @@ -575,7 +576,7 @@ dependencies = [ [[package]] name = "marqdo-provider-worker" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "libloading", "marqdo-host", @@ -587,7 +588,7 @@ dependencies = [ [[package]] name = "marqdo-runtime" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-expression", "marqdo-frontend", @@ -606,7 +607,7 @@ dependencies = [ [[package]] name = "marqdo-sandbox" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "libc", "serde", @@ -614,14 +615,14 @@ dependencies = [ [[package]] name = "marqdo-span" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "serde", ] [[package]] name = "marqdo-value" -version = "0.1.0" +version = "3.0.0-beta.1" dependencies = [ "marqdo-span", "num-bigint", diff --git a/Cargo.toml b/Cargo.toml index bbfc68a..f7c9854 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,7 +20,7 @@ members = [ ] [workspace.package] -version = "0.1.0" +version = "3.0.0-beta.1" edition = "2021" rust-version = "1.82" license = "MIT OR Apache-2.0" diff --git a/README.md b/README.md index 0f24fa5..b81e0a5 100644 --- a/README.md +++ b/README.md @@ -9,43 +9,46 @@ control flow. Lists, block quotes and emphasis are document presentation only. The official implementation is a Rust workspace; Python/Node are optional foreign kernels, never the compiler target. -This repository is the new, independent Marqdo toolchain (M0.5). It is **not** -a compatibility rewrite of `cflmy/marqdo`; the old syntax, package format and -plugin ABI v2 are not claimed to work here. +This repository is the new, independent Marqdo toolchain, now at product +version **`3.0.0-beta.1`**. It is **not** a compatibility rewrite of +`cflmy/marqdo`; the old syntax, package format and plugin ABI v2 are not +claimed to work here. See [docs/developers/](docs/developers/README.md) for the +third-party entry point and `docs/MARQDO_3_0_PRERELEASE_PLAN.md` for the beta +release policy. > **Breaking language revision landed.** The single semantic contract is > [RFC-LANG-0002](docs/architecture/RFC-LANG-0002-unified-semantics.md), with > normative summaries in [`spec/mapping.md`](spec/mapping.md) and > [`spec/expression.ebnf`](spec/expression.ebnf). The frontend, expression -> parser, stdlib, examples and test corpus all implement it: -> `cargo test --workspace --locked` is green (507 passed, 0 failed, 2 ignored -> at `9c1723d`). Old syntax (`**strong**` = execute, `*emph*` = return, -> `1.` = branch, `-` = loop, `>` = call) is **not** an active language and +> parser, stdlib, examples and test corpus all implement it; the language +> migration is closed and old syntax (`**strong**` = execute, `*emph*` = +> return, `1.` = branch, `-` = loop, `>` = call) is **not** an active language. > `marqdo_semantics`/`--legacy` selectors do not exist. See > [`docs/STATUS.md`](docs/STATUS.md) and > [`docs/migration/README.md`](docs/migration/README.md). -> **Status: stabilization candidate, not released.** The language (RFC-LANG-0002), -> lock v3, Analysis v2, Trace v2, Tool v1, Plugin ABI v1 (native + worker) and -> pinned Foreign providers are implemented and covered by tests on Linux. The macOS/Windows `E0433` platform-cfg failure and the Linux -> strict probe→launch race are fixed in source at `8af7262`, but the native -> Windows/macOS and GitHub Linux lanes have not been re-run from this checkout. -> **`strict` OS isolation is available on Linux only when the runtime -> Bubblewrap probe passes**; it was verified against the full escape/resource -> matrix in a disposable Ubuntu 26.04 VM at `8af7262` (ADR-0021). -> macOS/Windows fail closed, strict L2 (Worker/Foreign) is not implemented, and -> the broker/worker are not a sandbox. The release decision is **DO NOT -> RELEASE** until the remote gates have same-SHA URLs. See -> [`docs/STATUS.md`](docs/STATUS.md), [`COMPATIBILITY.md`](COMPATIBILITY.md) -> and [`docs/security-gate.md`](docs/security-gate.md). The single current CI -> convergence plan is -> [`docs/NEXT_RELEASE_CI_CONVERGENCE.md`](docs/NEXT_RELEASE_CI_CONVERGENCE.md) -> (historical baseline; refresh before use). +> **Status: `3.0.0-beta.1` prerelease.** The public beta target is **Linux +> x86_64 (glibc)**; macOS and Windows are experimental and not claimed, and the +> C ABI plugin/provider paths are Linux-only in this beta. The language +> (RFC-LANG-0002), lock v4, Analysis v2, Trace v2, Tool v1, Plugin ABI v1 +> (native + worker), pinned Foreign providers and Resource Provider v2 are +> implemented and covered by tests. **`strict` OS isolation is Linux-only and +> probe-gated**; unsupported hosts must fail closed, and strict L2 +> (Worker/Foreign/Provider) is not implemented. The broker and worker +> transports are not sandboxes. The beta release decision, support matrix and +> remaining gaps are recorded in [`docs/STATUS.md`](docs/STATUS.md), +> [`COMPATIBILITY.md`](COMPATIBILITY.md), +> [`docs/developers/release-limits.md`](docs/developers/release-limits.md) and +> [`docs/releasing.md`](docs/releasing.md). The authoritative release policy is +> [`docs/MARQDO_3_0_PRERELEASE_PLAN.md`](docs/MARQDO_3_0_PRERELEASE_PLAN.md). -CI: the private remote [git.cflmy.cn/cflmy/marqdo-cli](https://git.cflmy.cn/cflmy/marqdo-cli) -uses Woodpecker at [ci.cflmy.cn](https://ci.cflmy.cn); [`.woodpecker/main.yml`](.woodpecker/main.yml) -runs fmt, clippy, workspace tests and a release build. The strict OS-isolation -lane still requires the disposable VM described in [docs/ci.md](docs/ci.md). +CI: the source of truth is the Gitea remote +[git.cflmy.cn/cflmy/marqdo-cli](https://git.cflmy.cn/cflmy/marqdo-cli) with +Woodpecker at [ci.cflmy.cn](https://ci.cflmy.cn); [`.woodpecker/main.yml`](.woodpecker/main.yml) +runs fmt, clippy, workspace tests with `--locked`, the Windows cross-target +compile gate and a release build of both binaries. The strict OS-isolation lane +requires the disposable VM described in [docs/ci.md](docs/ci.md); a GitHub +mirror is not used as the authoritative lane for this beta. ## Build @@ -146,7 +149,7 @@ rules are [`RFC-LANG-0002`](docs/architecture/RFC-LANG-0002-unified-semantics.md `{ok:false,code,message}` as an ordinary Map, with a `.mq.md` first-fit free-list allocator demonstrating reuse, splitting and `alloc.no_space` recovery (ADR-0024). No `Result` type or exception syntax. -* **Bundled stdlib + print prototype (RFC-CM CM-A07/A10)** — offline +* **Bundled stdlib + official print aliases (RFC-CM CM-A07/A10)** — offline `stdlib/` with explicit `std:io`/`std:format`/`std:text` imports, SHA-256 digest verification, Analysis identity and a frozen-CLI closure test; the `.mq.md` print chain is the only execution path for `打印`/`print` on an official install (ADR-0031), @@ -184,10 +187,10 @@ rules are [`RFC-LANG-0002`](docs/architecture/RFC-LANG-0002-unified-semantics.md output (ADR-0058). * **C ABI ResourceProvider v1 (RFC-CM CM-A09)** — trusted native shared libraries expose resource open/read/write/close through a frozen header; - project + name grant; plugin-Worker binding remains open (ADR-0036). + project + name grant; the worker transport binding is implemented (ADR-0036/ADR-0038). * **Worker ResourceProvider transport v1 (RFC-CM CM-A09)** — trusted helper - process with framed JSON resource operations; project + name grant; C ABI - binding remains open (ADR-0035). + process with framed JSON resource operations; project + name grant; the C ABI + library is loaded by the helper (ADR-0035/ADR-0038). * **In-process ResourceProvider v1 (RFC-CM CM-A09 first slice)** — trusted providers register extra resource kinds, project-mode + name-grant gated, using the existing `resource.*`/`Result` ABI; no parser/runtime/`HostOp` @@ -204,7 +207,7 @@ rules are [`RFC-LANG-0002`](docs/architecture/RFC-LANG-0002-unified-semantics.md `UnitId`/anchors, import cycle detection, multi-module calls, `run/call/check/inspect/fmt`, reference validation (`check --refs`) and the static link graph (`inspect --refs`). -* **P3 project** — lock v3 full transitive package-instance graph for path and +* **P3 project** — lock v4 full transitive package-instance graph for path and pinned Git sources, verified content-addressed Git cache, deterministic `lock`, strict `sync --locked` with atomic `.marqdo/env` materialization. `run`/`call`/`check` never fetch or rewrite the lock. @@ -231,9 +234,9 @@ rules are [`RFC-LANG-0002`](docs/architecture/RFC-LANG-0002-unified-semantics.md Run everything: ```bash -cargo test --workspace +cargo test --workspace --locked cargo test -p marqdo-cli # conformance corpus + CLI contract tests -cargo fmt --check +cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings ``` @@ -310,21 +313,30 @@ tests/ conformance/negative corpus (see tests/README.md) * [`docs/DEVELOPMENT_BLUEPRINT.md`](docs/DEVELOPMENT_BLUEPRINT.md) — architecture baseline (Chinese); historical sections are marked and the current language contract is RFC-LANG-0002, not the blueprint's old mapping. +* [`docs/MARQDO_3_0_PRERELEASE_PLAN.md`](docs/MARQDO_3_0_PRERELEASE_PLAN.md) + — **the authoritative release policy for this line**: beta gates, version + axes, support matrix, REL work items and LTS conditions. It is a plan, not + evidence. +* [`docs/developers/README.md`](docs/developers/README.md) — third-party and + integrator entry point (libraries, tools, plugins, kernels, providers, + Analysis/Trace consumers, compatibility). +* [`docs/MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md`](docs/MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md) + — end-to-end third-party integration handbook. * [`docs/STABLE_RELEASE_IMPLEMENTATION.md`](docs/STABLE_RELEASE_IMPLEMENTATION.md) - — **the single authoritative next-phase plan** for release gates, PR order, - Windows/macOS fixes and the release checklist; it is a plan, not evidence. + — historical stable-release roadmap input (its own header marks it Proposed + and superseded by the 3.0 prerelease plan for current decisions). * [`COMPATIBILITY.md`](COMPATIBILITY.md) — protocol versions, per-platform feature evidence, the breaking language change and unsupported features. -* [`CHANGELOG.md`](CHANGELOG.md) — unreleased stabilization changes and the - `0.1.0` baseline, including the syntax breaking change. +* [`CHANGELOG.md`](CHANGELOG.md) — `3.0.0-beta.1` release notes plus the + historical `0.1.0` baseline, including the syntax breaking change. * [`docs/security-gate.md`](docs/security-gate.md) — G-C evidence and limits; [`docs/security-vm.md`](docs/security-vm.md) reproduces the disposable VM and the self-hosted security runner. * [`docs/releasing.md`](docs/releasing.md) — artifact, checksum, clean-install smoke, tagging and rollback procedure. * [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md) - — historical stabilization spec (baseline `0adebe4`), superseded on current - priorities by the stable-release plan. + — historical stabilization spec (baseline `0adebe4`), superseded by the + 3.0 prerelease plan for current release decisions. * [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) — historical M0.6 plan. * [`docs/EXTENSIBILITY_AUDIT.md`](docs/EXTENSIBILITY_AUDIT.md) — source-backed @@ -407,7 +419,7 @@ marqdo run plugin/demo.mq.md \ marqdo run kernel/demo.mq.md \ --kernel kernel/build/kernel.json --allow-foreign -# 4. Resource provider v2 (see the next section) +# 4. Resource provider v2 (examples/provider-demo/build.sh first; see below) marqdo run provider/demo.mq.md \ --provider provider/build/provider.json --allow-provider demo.sensor diff --git a/crates/cli/src/commands/init.rs b/crates/cli/src/commands/init.rs index 3a46603..b5ffb30 100644 --- a/crates/cli/src/commands/init.rs +++ b/crates/cli/src/commands/init.rs @@ -13,6 +13,13 @@ pub fn init(dir: Option<&Path>) -> i32 { ); return 1; } + if let Err(error) = std::fs::create_dir_all(dir) { + eprintln!("error: cannot create {}: {error}", dir.display()); + return 1; + } + // Create the directory before canonicalizing: `init new-project` must name + // the project `new-project`, not silently fall back to `example` because + // the path did not exist yet. let name = dir .canonicalize() .ok() @@ -21,10 +28,6 @@ pub fn init(dir: Option<&Path>) -> i32 { .map(|name| name.to_string_lossy().to_string()) }) .unwrap_or_else(|| "example".to_string()); - if let Err(error) = std::fs::create_dir_all(dir) { - eprintln!("error: cannot create {}: {error}", dir.display()); - return 1; - } let manifest = marqdo_package::Manifest::template(&name); if let Err(error) = std::fs::write(dir.join(marqdo_package::MANIFEST_FILE), manifest.to_yaml()) { diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index d63e92c..165c535 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -232,7 +232,7 @@ struct CheckArgs { /// Declare a plugin manifest for static export-signature checking. #[arg(long = "plugin", value_name = "PATH")] plugin: Vec, - /// Write the public Analysis v1 projection (only on successful check). + /// Write the public Analysis v2 projection (only on successful check). #[arg(long, value_name = "PATH")] emit: Option, /// Machine readable JSON output. @@ -380,7 +380,7 @@ struct ToolRemoveArgs { #[derive(Args)] struct SyncArgs { - /// Fail instead of silently updating when the lockfile is stale. + /// Do not fetch pinned Git revisions; verify and materialize only from the local cache. #[arg(long)] locked: bool, /// Machine readable JSON output. diff --git a/crates/cli/tests/integration_cli.rs b/crates/cli/tests/integration_cli.rs index c14baea..217e1f2 100644 --- a/crates/cli/tests/integration_cli.rs +++ b/crates/cli/tests/integration_cli.rs @@ -143,6 +143,11 @@ fn init_creates_a_runnable_project() { let output = cli(dir.path(), &["init", "proj"]); assert_exit(&output, 0, "init must succeed"); assert!(stdout_text(&output).contains("Initialized Marqdo project")); + let manifest = std::fs::read_to_string(dir.path().join("proj/marqdo.yaml")).unwrap(); + assert!( + manifest.contains("name: proj"), + "init must derive the project name from the target directory: {manifest}" + ); let project = dir.path().join("proj"); assert!(project.join("marqdo.yaml").is_file(), "manifest missing"); assert!( diff --git a/crates/cli/tests/package_env.rs b/crates/cli/tests/package_env.rs index b98247d..6470ad4 100644 --- a/crates/cli/tests/package_env.rs +++ b/crates/cli/tests/package_env.rs @@ -434,3 +434,32 @@ fn tampered_path_dependency_content_is_rejected_by_locked_sync() { "a failed locked operation must not replace the materialized environment" ); } + +#[test] +fn incompatible_project_marqdo_range_fails_closed_before_program_load() { + let dir = TempDir::new("runtime-range"); + let root = dir.path(); + write( + &root.join("marqdo.yaml"), + "project:\n name: stale\n version: 0.1.0\n marqdo: \">=0.1,<1\"\n", + ); + write(&root.join("index.mq.md"), "## @exec main\n\n`return 1`\n"); + for command in [["check", "index.mq.md"], ["run", "index.mq.md"]] { + let output = cli(root, &command); + assert!( + !output.status.success(), + "{} must fail closed: {}", + command[0], + String::from_utf8_lossy(&output.stderr) + ); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!( + stderr.contains("package.marqdo_incompatible"), + "unexpected stderr: {stderr}" + ); + assert!( + stderr.contains(env!("CARGO_PKG_VERSION")), + "diagnostic must name the running core: {stderr}" + ); + } +} diff --git a/crates/cli/tests/tool_protocol.rs b/crates/cli/tests/tool_protocol.rs index b48e67d..d727efa 100644 --- a/crates/cli/tests/tool_protocol.rs +++ b/crates/cli/tests/tool_protocol.rs @@ -95,7 +95,7 @@ fn write_tool(dir: &Path, command: &str, _script: &str) -> PathBuf { std::fs::write( &manifest, format!( - r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"{entrypoint}","compatibility":{{"marqdo":">=0.1,<1"}}}}"# + r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"{entrypoint}","compatibility":{{"marqdo":">=3.0.0-beta.1,<4.0.0"}}}}"# ), ) .unwrap(); @@ -142,7 +142,7 @@ fn write_sample_from_source(dir: &Path, command: &str) -> PathBuf { std::fs::write( &manifest, format!( - r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"{entrypoint}","compatibility":{{"marqdo":">=0.1,<1","analysis":[2],"trace":[2]}}}}"# + r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"{entrypoint}","compatibility":{{"marqdo":">=3.0.0-beta.1,<4.0.0","analysis":[2],"trace":[2]}}}}"# ), ) .unwrap(); @@ -301,7 +301,7 @@ fn invalid_manifests_and_path_escapes_are_rejected() { let incompatible = std::fs::read_to_string(&manifest) .unwrap() - .replace(">=0.1,<1", ">=99.0"); + .replace(">=3.0.0-beta.1,<4.0.0", ">=99.0"); let incompatible_manifest = dir.path().join("incompatible.json"); std::fs::write(&incompatible_manifest, incompatible).unwrap(); let output = cli( @@ -364,8 +364,8 @@ fn protocol_negotiation_accepts_declared_versions_and_rejects_disjoint_ones() { "#!/bin/sh\nprintf 'analysis=%s\\ntrace=%s\\n' \"$MARQDO_PROTOCOL_ANALYSIS\" \"$MARQDO_PROTOCOL_TRACE\"\n", ); let text = std::fs::read_to_string(&manifest).unwrap().replace( - "\"marqdo\":\">=0.1,<1\"", - "\"marqdo\":\">=0.1,<1\",\"analysis\":[2],\"trace\":[2]", + "\"marqdo\":\">=3.0.0-beta.1,<4.0.0\"", + "\"marqdo\":\">=3.0.0-beta.1,<4.0.0\",\"analysis\":[2],\"trace\":[2]", ); std::fs::write(&manifest, text).unwrap(); let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); @@ -384,8 +384,8 @@ fn protocol_negotiation_accepts_declared_versions_and_rejects_disjoint_ones() { let command = format!("bad-{tag}"); let manifest = write_tool(dir.path(), &command, "#!/bin/sh\nexit 0\n"); let text = std::fs::read_to_string(&manifest).unwrap().replace( - "\"marqdo\":\">=0.1,<1\"", - &format!("\"marqdo\":\">=0.1,<1\",{compat}"), + "\"marqdo\":\">=3.0.0-beta.1,<4.0.0\"", + &format!("\"marqdo\":\">=3.0.0-beta.1,<4.0.0\",{compat}"), ); std::fs::write(&manifest, text).unwrap(); let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); @@ -449,3 +449,37 @@ fn a_root_record_json_in_the_source_package_is_rejected() { assert_eq!(output.status.code(), Some(1)); assert!(stderr(&output).contains("must not contain a root record.json")); } + +#[test] +fn beta_core_requires_an_explicit_prerelease_compatible_range() { + let dir = TempDir::new("prerelease-range"); + let home = dir.path().join("home"); + let core = env!("CARGO_PKG_VERSION"); + + // The shipped example range opt-in must install on this real core. + let manifest = write_tool(dir.path(), "prerelease", "#!/bin/sh\nexit 0\n"); + let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!(install.status.code(), Some(0), "{}", stderr(&install)); + + if core.contains('-') { + // SemVer: a stable-only requirement must not silently accept a + // prerelease core. The operator has to opt in with a prerelease range. + let manifest = write_tool(dir.path(), "stableonly", "#!/bin/sh\nexit 0\n"); + let text = std::fs::read_to_string(&manifest) + .unwrap() + .replace(">=3.0.0-beta.1,<4.0.0", ">=3.0.0,<4.0.0"); + std::fs::write(&manifest, text).unwrap(); + let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]); + assert_eq!( + output.status.code(), + Some(1), + "a stable-only range must reject prerelease core {core}: {}", + stderr(&output) + ); + assert!( + stderr(&output).contains("requires marqdo"), + "{}", + stderr(&output) + ); + } +} diff --git a/crates/marqdo-package/Cargo.toml b/crates/marqdo-package/Cargo.toml index 19e42b1..0cffdf9 100644 --- a/crates/marqdo-package/Cargo.toml +++ b/crates/marqdo-package/Cargo.toml @@ -13,6 +13,7 @@ serde = { workspace = true } serde_yaml = { workspace = true } serde_json = { workspace = true } sha2 = { workspace = true } +semver = { workspace = true } walkdir = { workspace = true } hex = { workspace = true } diff --git a/crates/marqdo-package/src/lib.rs b/crates/marqdo-package/src/lib.rs index 8f77c72..119c6c5 100644 --- a/crates/marqdo-package/src/lib.rs +++ b/crates/marqdo-package/src/lib.rs @@ -393,6 +393,9 @@ impl Manifest { if self.project.version.trim().is_empty() { return Err("project.version must not be empty".to_string()); } + if let Some(range) = &self.project.marqdo { + validate_core_range(range)?; + } for (name, dependency) in &self.dependencies { dependency.validate(name)?; } @@ -420,7 +423,7 @@ impl Manifest { project: ProjectInfo { name: project_name.to_string(), version: "0.1.0".to_string(), - marqdo: Some(">=0.1,<1".to_string()), + marqdo: Some(">=3.0.0-beta.1,<4.0.0".to_string()), }, dependencies: BTreeMap::new(), plugins: BTreeMap::new(), @@ -430,6 +433,31 @@ impl Manifest { } } +/// Enforce the optional `project.marqdo` runtime range. +/// +/// The field was informational before the 3.0 beta; a project that declares a +/// range the running core does not satisfy must fail closed with a clear +/// diagnostic instead of being silently ignored. SemVer prerelease semantics +/// apply: a stable-only range such as `>=3.0.0,<4.0.0` does not accept +/// `3.0.0-beta.1`, so prerelease users must opt in explicitly. +fn validate_core_range(range: &str) -> Result<(), String> { + let requirement = semver::VersionReq::parse(range).map_err(|error| { + format!( + "package.marqdo_range_invalid: project.marqdo `{range}` is not a valid SemVer requirement: {error}" + ) + })?; + let core = semver::Version::parse(env!("CARGO_PKG_VERSION")).map_err(|error| { + format!("package.marqdo_range_invalid: core version is not valid SemVer: {error}") + })?; + if !requirement.matches(&core) { + return Err(format!( + "package.marqdo_incompatible: project requires marqdo `{range}`, this core is {}", + env!("CARGO_PKG_VERSION") + )); + } + Ok(()) +} + /// How a resolved package was obtained. Identity does not depend on this. #[derive(Debug, Clone, PartialEq, Eq)] pub enum PackageOrigin { @@ -2057,6 +2085,36 @@ capabilities: assert_eq!(manifest.capabilities.process, Some(false)); } + #[test] + fn project_marqdo_range_is_enforced_against_the_running_core() { + let core = env!("CARGO_PKG_VERSION"); + assert!( + Manifest::template("template-project").validate().is_ok(), + "the init template must be runnable by the core that writes it" + ); + let accepted = + format!("project:\n name: p\n version: 0.1.0\n marqdo: \">={core},<4.0.0\"\n"); + Manifest::from_yaml(&accepted).expect("an explicit opt-in range must be accepted"); + + let stale = "project:\n name: p\n version: 0.1.0\n marqdo: \">=0.1,<1\"\n"; + let error = Manifest::from_yaml(stale).unwrap_err(); + assert!( + error.contains("package.marqdo_incompatible"), + "stale range must fail closed: {error}" + ); + assert!( + error.contains(core), + "diagnostic must name the core: {error}" + ); + + let invalid = "project:\n name: p\n version: 0.1.0\n marqdo: \"not a range\"\n"; + let error = Manifest::from_yaml(invalid).unwrap_err(); + assert!( + error.contains("package.marqdo_range_invalid"), + "invalid range must be rejected: {error}" + ); + } + #[test] fn git_dependency_requires_rev() { let yaml = "project:\n name: p\n version: 0.1.0\ndependencies:\n x:\n git: https://example/x\n"; diff --git a/docs/MARQDO_3_0_PRERELEASE_PLAN.md b/docs/MARQDO_3_0_PRERELEASE_PLAN.md new file mode 100644 index 0000000..7b33f54 --- /dev/null +++ b/docs/MARQDO_3_0_PRERELEASE_PLAN.md @@ -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//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//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 + 已经历真实生态版本迭代 + 可持续的安全补丁/兼容性维护承诺。 diff --git a/docs/MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md b/docs/MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md new file mode 100644 index 0000000..df15eb8 --- /dev/null +++ b/docs/MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md @@ -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 --git --rev +` 可代写。 + +运行步骤(消费者项目根): + +```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": "", + "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//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` diff --git a/docs/STATUS.md b/docs/STATUS.md index a68c38b..ae29878 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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//manifest.json` | +| Frozen-binary conformance | external `marqdo-extension-conformance` suite PASS with unchanged CLI hash | `evidence/extension//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 diff --git a/docs/architecture/CURRENT.md b/docs/architecture/CURRENT.md index bca9816..d3c3ec5 100644 --- a/docs/architecture/CURRENT.md +++ b/docs/architecture/CURRENT.md @@ -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. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 9bb2ac1..c939634 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -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. diff --git a/docs/developers/README.md b/docs/developers/README.md new file mode 100644 index 0000000..8a2ea26 --- /dev/null +++ b/docs/developers/README.md @@ -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. diff --git a/docs/developers/analysis-trace.md b/docs/developers/analysis-trace.md new file mode 100644 index 0000000..cf1efa7 --- /dev/null +++ b/docs/developers/analysis-trace.md @@ -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:@` 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. diff --git a/docs/developers/compatibility.md b/docs/developers/compatibility.md new file mode 100644 index 0000000..d41d068 --- /dev/null +++ b/docs/developers/compatibility.md @@ -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. diff --git a/docs/developers/extensions.md b/docs/developers/extensions.md new file mode 100644 index 0000000..0763e4d --- /dev/null +++ b/docs/developers/extensions.md @@ -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": "", + "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`. diff --git a/docs/developers/libraries.md b/docs/developers/libraries.md new file mode 100644 index 0000000..08797ec --- /dev/null +++ b/docs/developers/libraries.md @@ -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 +--git --rev ` 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#`) 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). diff --git a/docs/developers/quickstart.md b/docs/developers/quickstart.md new file mode 100644 index 0000000..0d1eefc --- /dev/null +++ b/docs/developers/quickstart.md @@ -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). diff --git a/docs/developers/release-limits.md b/docs/developers/release-limits.md new file mode 100644 index 0000000..f9ba11e --- /dev/null +++ b/docs/developers/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. diff --git a/docs/developers/tools.md b/docs/developers/tools.md new file mode 100644 index 0000000..8c30099 --- /dev/null +++ b/docs/developers/tools.md @@ -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. diff --git a/docs/evidence/ci/README.md b/docs/evidence/ci/README.md index 39552ec..52a577a 100644 --- a/docs/evidence/ci/README.md +++ b/docs/evidence/ci/README.md @@ -1,8 +1,20 @@ # CI release-evidence manifests `docs/evidence/ci//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. diff --git a/docs/releasing.md b/docs/releasing.md index c432ba3..bb1a15a 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -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//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--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: \ + --gate strict_vm=PASS:$sha:docs/evidence/ \ + --gate extension=PASS:$sha:docs/evidence/extension/$sha/manifest.json \ + --gate clean_install=PASS:$sha:docs/evidence/ \ + --gate version_compat=PASS:$sha: \ + --gate windows=UNSUPPORTED:$sha:linux-only-beta-support-matrix \ + --gate macos=UNSUPPORTED:$sha:linux-only-beta-support-matrix \ + --gate performance=WARN:$sha:docs/evidence/ \ + --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//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. diff --git a/docs/security-gate.md b/docs/security-gate.md index 8aa9fb1..298ffd0 100644 --- a/docs/security-gate.md +++ b/docs/security-gate.md @@ -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)) diff --git a/examples/multi-module/marqdo.lock b/examples/multi-module/marqdo.lock index 891c68c..3d2b1ca 100644 --- a/examples/multi-module/marqdo.lock +++ b/examples/multi-module/marqdo.lock @@ -2,6 +2,6 @@ lock_version: 4 content_profile_version: 1 root: package: root:multi-module@0.1.0 - manifest_digest: 3d11906f34641802949b75de4728ea66a3557671db5c1ca89d6359d58a7a6936 + manifest_digest: c97de87f622fec9892622f40f991466da9e79c082f9586653327eb7758fa5ce1 packages: [] root_dependencies: {} diff --git a/examples/multi-module/marqdo.yaml b/examples/multi-module/marqdo.yaml index cdfca17..cae4fad 100644 --- a/examples/multi-module/marqdo.yaml +++ b/examples/multi-module/marqdo.yaml @@ -1,5 +1,5 @@ project: name: multi-module version: 0.1.0 - marqdo: ">=0.1,<1" + marqdo: ">=3.0.0-beta.1,<4.0.0" dependencies: {} diff --git a/examples/provider-demo/README.md b/examples/provider-demo/README.md new file mode 100644 index 0000000..a25254c --- /dev/null +++ b/examples/provider-demo/README.md @@ -0,0 +1,29 @@ +# Provider v2 example (`demo.sensor`) + +A resource provider is an **external** process/library pair: the CLI ships +`marqdo-provider-worker`, which loads this C ABI v1 library and speaks the +framed resource protocol. Nothing about `demo.sensor` lives in the Marqdo core, +and selecting the provider is not authorization. + +```bash +./examples/provider-demo/build.sh # cc + rustc needed for the host triple +marqdo run examples/provider-demo/demo.mq.md \ + --provider examples/provider-demo/build/provider.json \ + --allow-provider demo.sensor +# => 5 +``` + +Negative checks (all must fail before the resource call succeeds): + +```bash +# No grant: +marqdo run examples/provider-demo/demo.mq.md \ + --provider examples/provider-demo/build/provider.json +# A missing or non-sibling helper is fail-closed, never a PATH fallback. + +# Unknown provider manifest version: +marqdo run examples/provider-demo/demo.mq.md --provider examples/provider-demo/provider.json +``` + +`provider.json` in this directory is a template with a zero digest; only the +generated `build/provider.json` names the real artifact and is runnable. diff --git a/examples/provider-demo/build.sh b/examples/provider-demo/build.sh new file mode 100755 index 0000000..6a8b97c --- /dev/null +++ b/examples/provider-demo/build.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# Build the example C resource provider and generate a host-specific +# provider/build/provider.json (schema v2) with the real artifact SHA-256. +# +# The tracked provider.json documents the manifest shape; the generated copy +# under build/ matches the machine that built it. A manifest digest mismatch is +# rejected at run time, never tolerated. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +out="$here/build" +mkdir -p "$out/lib" +host="$(rustc -vV | sed -n 's/^host: //p')" +case "$host" in + *windows*) echo "unsupported: the C ABI provider example targets Unix" >&2; exit 3 ;; + *apple-darwin*) ext="dylib"; flags=(-dynamiclib -fPIC) ;; + *) ext="so"; flags=(-shared -fPIC) ;; +esac +artifact="libsensor.$ext" +cc -std=c11 -O2 "${flags[@]}" -o "$out/lib/$artifact" "$here/src/sensor.c" +if command -v sha256sum >/dev/null 2>&1; then + hash="$(sha256sum "$out/lib/$artifact" | cut -d' ' -f1)" +else + hash="$(shasum -a 256 "$out/lib/$artifact" | cut -d' ' -f1)" +fi +cat > "$out/provider.json" < token + * first read(max_bytes>=5) -> "hello", eof=true + * write(bytes) -> accepted, discarded + * close(token) -> closes exactly once + */ +#include +#include +#include + +#define ABI_VERSION 1 +#define MQ_OK 0 +#define MQ_ERR 1 + +static char g_last_error[256]; +static int closed = 0; + +uint32_t marqdo_resource_provider_abi_version(void) { return ABI_VERSION; } + +static int fail(const char *message) { + snprintf(g_last_error, sizeof(g_last_error), "%s", message); + return MQ_ERR; +} + +int32_t marqdo_resource_open( + const char *kind, + const char *descriptor, + const char *rights, + uint64_t *token +) { + (void)descriptor; + if (kind == NULL || strcmp(kind, "demo.sensor") != 0) { + return fail("unsupported kind"); + } + if (rights == NULL || strstr(rights, "read") == NULL) { + return fail("read right is required"); + } + if (token == NULL) { + return fail("token pointer is NULL"); + } + *token = 1; + closed = 0; + snprintf(g_last_error, sizeof(g_last_error), "%s", "ok"); + return MQ_OK; +} + +int32_t marqdo_resource_read( + uint64_t token, + uint8_t *buffer, + uint32_t capacity, + uint32_t *read, + int32_t *eof +) { + static const char payload[] = "hello"; + if (token != 1 || buffer == NULL || read == NULL || eof == NULL) { + return fail("invalid read arguments"); + } + if (closed) { + return fail("resource is closed"); + } + if (capacity < sizeof(payload) - 1) { + return fail("buffer is too small"); + } + memcpy(buffer, payload, sizeof(payload) - 1); + *read = (uint32_t)(sizeof(payload) - 1); + *eof = 1; + return MQ_OK; +} + +int32_t marqdo_resource_write( + uint64_t token, + const uint8_t *bytes, + uint32_t length, + uint32_t *written +) { + if (token != 1 || written == NULL || (bytes == NULL && length != 0)) { + return fail("invalid write arguments"); + } + if (closed) { + return fail("resource is closed"); + } + *written = length; + return MQ_OK; +} + +int32_t marqdo_resource_close(uint64_t token) { + if (token != 1) { + return fail("unknown token"); + } + if (closed) { + return fail("resource is already closed"); + } + closed = 1; + return MQ_OK; +} + +int32_t marqdo_resource_last_error(char *buffer, uint32_t capacity) { + if (buffer == NULL || capacity == 0) { + return MQ_ERR; + } + snprintf(buffer, capacity, "%s", g_last_error); + return MQ_OK; +} diff --git a/examples/provider-demo/unauthorized.mq.md b/examples/provider-demo/unauthorized.mq.md new file mode 100644 index 0000000..b764071 --- /dev/null +++ b/examples/provider-demo/unauthorized.mq.md @@ -0,0 +1,5 @@ +## @exec main + +`流 = resource.open("demo.sensor", "unit-1", ["read"])` + +`return resource.close(流)` diff --git a/examples/tool-samples/sample-knowledge/tool.json b/examples/tool-samples/sample-knowledge/tool.json index a48164d..8f9af9a 100644 --- a/examples/tool-samples/sample-knowledge/tool.json +++ b/examples/tool-samples/sample-knowledge/tool.json @@ -6,7 +6,7 @@ "command": "sample-knowledge", "entrypoint": "bin/sample-knowledge", "compatibility": { - "marqdo": ">=0.1,<1", + "marqdo": ">=3.0.0-beta.1,<4.0.0", "analysis": [2], "trace": [2] } diff --git a/examples/tool-samples/sample-proof/tool.json b/examples/tool-samples/sample-proof/tool.json index 12977a2..cbe2533 100644 --- a/examples/tool-samples/sample-proof/tool.json +++ b/examples/tool-samples/sample-proof/tool.json @@ -6,7 +6,7 @@ "command": "sample-proof", "entrypoint": "bin/sample-proof", "compatibility": { - "marqdo": ">=0.1,<1", + "marqdo": ">=3.0.0-beta.1,<4.0.0", "analysis": [2], "trace": [2] } diff --git a/examples/tool-samples/sample-view/tool.json b/examples/tool-samples/sample-view/tool.json index 277e44f..8f5e91a 100644 --- a/examples/tool-samples/sample-view/tool.json +++ b/examples/tool-samples/sample-view/tool.json @@ -6,7 +6,7 @@ "command": "sample-view", "entrypoint": "bin/sample-view", "compatibility": { - "marqdo": ">=0.1,<1", + "marqdo": ">=3.0.0-beta.1,<4.0.0", "analysis": [2], "trace": [2] } diff --git a/examples/tool-unknown-name/tool.json b/examples/tool-unknown-name/tool.json index 8efb8c8..1080666 100644 --- a/examples/tool-unknown-name/tool.json +++ b/examples/tool-unknown-name/tool.json @@ -6,6 +6,6 @@ "command": "benchmark", "entrypoint": "bin/marqdo-benchmark", "compatibility": { - "marqdo": ">=0.1,<1" + "marqdo": ">=3.0.0-beta.1,<4.0.0" } } diff --git a/spec/foreign.md b/spec/foreign.md index 694abd1..2c1be6d 100644 --- a/spec/foreign.md +++ b/spec/foreign.md @@ -1,6 +1,6 @@ # Marqdo Foreign Kernels v1 -Status: **one-shot kernels with an explicit provider registry** (M0.6 R2), +Status: **one-shot kernels with an explicit provider registry** (frozen foreign wire v1; product baseline `3.0.0-beta.1`), including built-in Python and Node/JavaScript providers. There are no sessions or persistent kernels. diff --git a/spec/markdown-profile.md b/spec/markdown-profile.md index 2845d30..bbea330 100644 --- a/spec/markdown-profile.md +++ b/spec/markdown-profile.md @@ -1,6 +1,6 @@ # Marqdo Markdown Profile v1 -Status: **frozen for M0.5**. Changes require an ADR, updated goldens and a +Status: **frozen (marqdo.md.v1)**; product baseline `3.0.0-beta.1`. Changes require an ADR, updated goldens and a profile id bump. Profile id: `marqdo.md.v1` diff --git a/spec/math.md b/spec/math.md index a44443e..cb37d0f 100644 --- a/spec/math.md +++ b/spec/math.md @@ -1,6 +1,6 @@ # Marqdo Math v1 -Status: **frozen subset for M0.5.** The kernel computes numbers; it never proves +Status: **frozen subset (math v1)**; product baseline `3.0.0-beta.1`. The kernel computes numbers; it never proves theorems. `math.simplify` and `math.differentiate` are **not implemented** in this build. diff --git a/spec/package-format.md b/spec/package-format.md index 23d1773..4d19d89 100644 --- a/spec/package-format.md +++ b/spec/package-format.md @@ -31,7 +31,7 @@ no `--project` flag in this build. project: name: example version: 0.1.0 - marqdo: ">=0.1,<1" # optional; informational in this build + marqdo: ">=3.0.0-beta.1,<4.0.0" # optional; enforced against the running core dependencies: geometry: path: ./packages/geometry # exactly one of path / git+rev @@ -62,7 +62,7 @@ extensions: # explicit activation sources; never grants |---|---|---|---| | `project.name` | string | yes | non-empty package name | | `project.version` | string | yes | non-empty version string (not semver-validated in the manifest) | -| `project.marqdo` | string | no | required Marqdo runtime range; stored, not enforced by this build | +| `project.marqdo` | string | no | Marqdo core SemVer requirement; enforced against the running core, incompatible ranges are hard errors | | `dependencies..path` | path string | one of path/git | project-relative path to a dependency directory or `.mq.md` file | | `dependencies..git` | URL string | one of path/git | git source (must be pinned with `rev`) | | `dependencies..rev` | string | with `git` | exact revision; a bare `git` without `rev` is rejected | @@ -82,6 +82,12 @@ diagnostic. validates: * `project.name` and `project.version` are non-empty after trimming; +* when `project.marqdo` is present it must parse as a `semver::VersionReq` + and match the running core version (`package.marqdo_range_invalid` / + `package.marqdo_incompatible`). SemVer prerelease rules apply: a stable-only + range such as `>=3.0.0,<4.0.0` does **not** accept `3.0.0-beta.1`; prerelease + users must opt in with a range whose comparator carries the prerelease + (for example `>=3.0.0-beta.1,<4.0.0`); * for every dependency, exactly one source is present: * both `path` and `git` → error "declares both path and git"; * neither → error "must declare a path or a pinned git source"; @@ -94,8 +100,9 @@ validates: the project is loaded (`PackageResolver::resolve_extension_sources`), not in plain `Manifest::validate`. -Note: a *git* dependency passes manifest validation when pinned, but the -dependency is not resolvable or lockable in this build (§5). +A pinned *git* dependency is resolvable, lockable and runnable; `lock`/`sync` +clone it into the content-addressed cache and verify the checked-out commit +and tree digest (§4.3). ### 2.3 `capabilities` are requests @@ -169,7 +176,7 @@ An extension lock record binds: additionally verifies the real artifact bytes before starting any worker. `extensions` is omitted when no extension is declared. -### 3.1 Lock v3 migration +### 3.1 Lock v4 migration `from_yaml` of a v3 document returns a deterministic error: lock v3 is superseded by v4 (extension identities), and the user must run `marqdo lock` @@ -178,7 +185,7 @@ their existing relock error with the v4 requirement. | Field | Semantics | |---|---| -| `lock_version` | writers emit `3`; readers accept only `3` and tell v1/v2 users to run `marqdo lock` | +| `lock_version` | writers emit `4`; readers accept only `4`; a v3 document gets the explicit "run `marqdo lock`" migration error and v1/v2 get the relock error | | `content_profile_version` | file-set/digest profile; only `1` is accepted | | `root.package` | logical root instance `root:@` | | `root.manifest_digest` | lowercase hex SHA-256 of the canonical `marqdo.yaml` | @@ -193,7 +200,7 @@ The graph is the unit of reproducibility: a transitive dependency that can be imported is also locked. Edges are keyed by `(parent instance, alias)`, so the same alias in two packages may resolve to different instances. -### 3.1 Serialization and validation +### 3.2 Serialization and validation `lock` writes atomically (temporary file, `sync_all`, rename); a failed resolution leaves the previous lock untouched. `LockFile::to_yaml` sorts @@ -203,7 +210,7 @@ byte-identical. `LockFile::from_yaml` validates before returning: -* `lock_version == 3`, `content_profile_version == 1`; +* `lock_version == 4`, `content_profile_version == 1`; * unique ids, each consistent with `dep:@#`; * every digest is 64 lowercase hex characters; * every source is normalized (path relative to the project root without `..`, @@ -214,7 +221,7 @@ byte-identical. v1/v2 locks are rejected, not silently upgraded: a flat lock cannot represent the closure and treating it as complete would re-open fail-open loading. -### 3.2 Tree hash +### 3.3 Tree hash For a path or Git dependency, `lock` hashes the resolved package tree with `content_profile_version: 1` (`crates/marqdo-package/src/fileset.rs`, ADR-0016): @@ -239,7 +246,7 @@ final digest equals the lock. This is a deterministic content fingerprint, not a Merkle tree and not a commitment to file modes or empty directories. Modes are normalized on materialization (`0644` files, `0755` directories on Unix). -### 3.3 Lock generation rules +### 3.4 Lock generation rules `marqdo lock` (run in a project): @@ -303,12 +310,11 @@ after its file-set digest and cache marker verify. project: name: version: 0.1.0 - marqdo: '>=0.1,<1' + marqdo: '>=3.0.0-beta.1,<4.0.0' ``` (empty dependencies/plugins/capabilities are omitted); -* writes `index.mq.md` (the target syntax; the template in a pre-RFC binary - still emits the old spelling and is part of the pending migration): +* writes `index.mq.md` using the RFC-LANG-0002 syntax: ```markdown ## @exec main @@ -335,7 +341,7 @@ stale lock entry). They do not fetch, install, resolve or authorize anything. `marqdo add --git --rev `: validate the dependency shape (same rules as §2.2), refuse an existing name (exit 1), insert it, write the manifest, and tell the user to run - `marqdo lock`. A pinned Git dependency is lockable/resolvable in R5. + `marqdo lock`. A pinned Git dependency is lockable, resolvable and runnable. * `marqdo remove `: remove the dependency from the manifest (exit 1 if absent), and drop a same-named entry from an existing lock file. It does not re-hash or re-lock the rest of the project. @@ -372,8 +378,8 @@ inconsistency to fix). | Environment materialization (`.marqdo/env`, `cache`) | Implemented: `sync` materializes the full locked closure into `.marqdo/env` atomically; `lock`/`sync` populate a verified Git cache. Kernels/sessions are not materialized. | | Dependency signatures / trusted publishers / supply-chain scanning | Not implemented. | | Multiple/nested project boundary diagnostics | Not implemented; nearest `marqdo.yaml` wins. | -| Lock file migration between `lock_version`s | Only v3 is read; v1/v2 are rejected with a relock instruction. `lock` regenerates the graph. | -| Plugin installation / plugin dependency management | Not implemented; `plugins:` in the manifest is declarative only. | +| Lock file migration between `lock_version`s | Only v4 is read. v3 gets the explicit "lock v3 is superseded by lock v4; run `marqdo lock`" error; v1/v2 get the relock instruction. `lock` regenerates the graph. | +| Plugin installation / plugin dependency management | No package-manager install. `plugins:` is a declarative version requirement; explicit `extensions.plugins` activation plus lock v4 manifest/artifact identity is implemented and re-verified at run time. | The lock/package format is deliberately small and deterministic so these can be added later without changing the identity model. Changing `lock_version`, diff --git a/spec/plugin-abi.md b/spec/plugin-abi.md index 48ab825..1663c11 100644 --- a/spec/plugin-abi.md +++ b/spec/plugin-abi.md @@ -19,7 +19,7 @@ Three versions exist and are never conflated: | Version | Current | Where | |---|---|---| -| Marqdo language/semantics | M0.5, `spec/*` | `docs/DEVELOPMENT_BLUEPRINT.md`, specs | +| Marqdo language/semantics | RFC-LANG-0002 / ADR-0052, `spec/mapping.md` | `docs/architecture/RFC-LANG-0002-unified-semantics.md`, specs | | Plugin ABI major.minor | `1.0` | `MQ_ABI_MAJOR`/`MQ_ABI_MINOR`, `marqdo_plugin_abi::ABI_MAJOR/ABI_MINOR` | | Plugin package SemVer | e.g. `0.1.0` | `plugin.yaml` `plugin.version` | @@ -299,7 +299,11 @@ When a plugin is used from Marqdo code, host errors become structured ## 9. Using a plugin from `.mq.md` -This build supports explicitly trusted **in-process native** plugins only. +Two transports are implemented for the same C ABI: `kind: native` loads the +library in-process and requires the explicit unsafe `--trust-native-plugin` +decision; `kind: worker` loads the same library in a child process behind the +length-prefixed wire (crash isolation, **not** an OS sandbox). Wasm is rejected +explicitly. ```bash # 1. Build the C example and refresh its sha256 in plugin.yaml @@ -359,8 +363,7 @@ the address space: the core binary is re-invoked as `__plugin-worker`, loads one native library in the child, reports its complete export table, and serves length-prefixed invoke frames. Handshake and calls have timeouts; a crash/EOF becomes `plugin.crashed`/`plugin.timeout` in the host. This is crash isolation, -not an OS sandbox: the worker still runs as the user. Wasm, hot unload and a -full plugin capability broker for worker requests remain future work. +not an OS sandbox: the worker still runs as the user. Wasm, hot unload and worker capabilities other than the granted `fs.read` request/reply remain future work. ### 9.1 Worker frames @@ -453,14 +456,14 @@ when no C compiler is available. | Isolated plugin worker transport (length-prefixed IPC) | Implemented for crash isolation with handshake/call timeouts; a child process is not an OS sandbox. | | Wasm Component + WIT | Not implemented; `kind: wasm` is rejected explicitly. | | Hot unload/reload | Not supported by ABI v1; the worker is killed on unload. | -| Plugin installation by package manager | Not implemented; `marqdo.yaml` `plugins:` is declarative only. | +| Plugin installation by package manager | No package-manager install. `extensions.plugins` selects a manifest explicitly and lock v4 records its identity; `plugins:` versions stay declarative. | | Vendor capability handlers | The broker and vendor-name validation exist; no concrete vendor handler is shipped in this build. | | Static validation without an explicit manifest | `check` needs `--plugin `; descriptors are not discovered from the network. | | Positional plugin arguments | Not supported; named only. | | Thread-safe / concurrent invocation | Not supported (single-threaded v1 contract). | | Old `marqdo_abi.h` v2 compatibility | Not implemented and not claimed; a separate adapter would be required. | -## 12. Static descriptor / run-time reconciliation (RFC-EXT-0001 §4.5) +## 13. Static descriptor / run-time reconciliation (RFC-EXT-0001 §4.5) The CLI never derives a callable signature from a loaded library. The **manifest is the static contract** and the runtime is checked against it: diff --git a/spec/security.md b/spec/security.md index 051b37a..a7a79d5 100644 --- a/spec/security.md +++ b/spec/security.md @@ -1,6 +1,6 @@ # Marqdo Security Model (implemented status) -Status: **describes the M0.5 implementation, including honest gaps.** This is +Status: **describes the `3.0.0-beta.1` implementation, including honest gaps.** This is not a security audit; it documents what the code actually enforces. Normative implementation: diff --git a/spec/tool-v1.md b/spec/tool-v1.md index 204f9b8..0b4558e 100644 --- a/spec/tool-v1.md +++ b/spec/tool-v1.md @@ -1,6 +1,6 @@ # Marqdo CLI Tool Protocol v1 — 通用外部工具协议 -> 状态:Proposed,配套 `docs/NEXT_PHASE_IMPLEMENTATION.md` §5 修订 v2。任何官方/第三方工具一视同仁;该协议**不是** C ABI 插件协议。本文不声称现有 CLI 已实现此协议。 +> 状态:**Implemented / frozen protocol v1**(产品 `3.0.0-beta.1`)。核心根命令同样优先;任何官方/第三方工具一视同仁;该协议**不是** C ABI 插件协议。安装、校验、分发与协议协商均已实现并由 `crates/cli/tests/tool_protocol.rs` 覆盖。 ## 1. 范围与不变量 @@ -23,7 +23,7 @@ "command": "benchmark", "entrypoint": "bin/marqdo-benchmark", "compatibility": { - "marqdo": ">=0.1,<1", + "marqdo": ">=3.0.0-beta.1,<4.0.0", "analysis": [2] } } diff --git a/spec/value-wire.md b/spec/value-wire.md index 315a24f..23232a9 100644 --- a/spec/value-wire.md +++ b/spec/value-wire.md @@ -1,6 +1,6 @@ # Marqdo Value Wire Format v1 -Status: **frozen for M0.5; extended by ADR-0022 (non-transferable `Memory`)**. +Status: **frozen (wire v1); extended by ADR-0022 (non-transferable `Memory`)**; product baseline `3.0.0-beta.1`. Changes require an ADR, a `wire_version` bump and cross-ABI compatibility tests. Adding a rejected tag is not a version bump; accepting a new value shape is. diff --git a/tools/ci/release_evidence.py b/tools/ci/release_evidence.py index 9c40f16..64e0276 100755 --- a/tools/ci/release_evidence.py +++ b/tools/ci/release_evidence.py @@ -1,13 +1,35 @@ #!/usr/bin/env python3 """Aggregate per-gate CI evidence into a SHA-bound release manifest. -Schema: marqdo.release-gates.v1. A missing, skipped, timed-out, failed or +Schema: `marqdo.release-gates.v1`. A missing, skipped, timed-out, failed or SHA-mismatched gate is never PASS. The tool only records supplied facts; it does not query CI and cannot turn an UNVERIFIED gate into a release. +Two profiles exist and both are explicit in the output: + +* `stable` — every required platform gate must PASS on the target SHA. +* `beta` — the supported platform set is the one declared in + `COMPATIBILITY.md` (Linux x86_64 for `3.0.0-beta.1`). `windows`/`macos` must + be explicitly `UNSUPPORTED` (not silently omitted). `strict_vm` may be PASS + with same-SHA disposable-VM evidence, or `UNSUPPORTED` when the tested policy + is an explicit fail-closed refusal; `extension`, `clean_install` and + `version_compat` must PASS. `performance` may be `WARN` only in beta and is + recorded with its reason. + Gate spec: `name=STATE:tested_sha:run_url` (url may contain colons). -Required gates: linux, windows, macos, strict_vm; performance must be PASS or -WARN. Any other gate name is rejected so a typo cannot silently disappear. + +Usage: + + python3 tools/ci/release_evidence.py --target-sha "$SHA" --profile beta \ + --gate linux=PASS:$SHA:https://ci.cflmy.cn/... \ + --gate strict_vm=PASS:$SHA:docs/evidence/... \ + --gate extension=PASS:$SHA:docs/evidence/extension/$SHA/manifest.json \ + --gate clean_install=PASS:$SHA:docs/evidence/... \ + --gate version_compat=PASS:$SHA:cargo-test \ + --gate windows=UNSUPPORTED:$SHA:supported-platforms-exclude \ + --gate macos=UNSUPPORTED:$SHA:supported-platforms-exclude \ + --gate performance=WARN:$SHA:docs/evidence/... \ + --out/docs/evidence/ci/$SHA/manifest.json """ import argparse @@ -18,13 +40,40 @@ import sys from pathlib import Path SCHEMA = "marqdo.release-gates.v1" -REQUIRED = ("linux", "windows", "macos", "strict_vm") -OPTIONAL = ("performance",) +PROFILES = { + "stable": { + "required": ("linux", "windows", "macos", "strict_vm"), + "optional": ("performance",), + "windows_macos_unsupported_allowed": False, + "strict_unsupported_allowed": False, + "decision": "RELEASE_CANDIDATE", + }, + "beta": { + "required": ("linux", "strict_vm", "extension", "clean_install", "version_compat"), + "optional": ("windows", "macos", "performance"), + "windows_macos_unsupported_allowed": True, + "strict_unsupported_allowed": True, + "decision": "BETA_RELEASE_CANDIDATE", + }, +} +GATES = ( + "linux", + "windows", + "macos", + "strict_vm", + "extension", + "clean_install", + "version_compat", + "performance", +) STATES = { "linux": {"PASS", "FAIL", "UNVERIFIED"}, - "windows": {"PASS", "FAIL", "UNVERIFIED"}, - "macos": {"PASS", "FAIL", "UNVERIFIED"}, - "strict_vm": {"PASS", "FAIL", "UNVERIFIED"}, + "windows": {"PASS", "FAIL", "UNVERIFIED", "UNSUPPORTED"}, + "macos": {"PASS", "FAIL", "UNVERIFIED", "UNSUPPORTED"}, + "strict_vm": {"PASS", "FAIL", "UNVERIFIED", "UNSUPPORTED"}, + "extension": {"PASS", "FAIL", "UNVERIFIED"}, + "clean_install": {"PASS", "FAIL", "UNVERIFIED"}, + "version_compat": {"PASS", "FAIL", "UNVERIFIED"}, "performance": {"PASS", "WARN", "FAIL", "UNVERIFIED"}, } SHA_RE = re.compile(r"^[0-9a-f]{40}$") @@ -48,7 +97,7 @@ def parse_gate(text: str) -> tuple[str, dict]: raise ValueError(f"gate must be name=STATE:sha:url, got {text!r}") state, tested_sha, run_url = parts if name not in STATES: - raise ValueError(f"unknown gate {name!r}; expected {list(STATES)}") + raise ValueError(f"unknown gate {name!r}; expected {list(GATES)}") if state not in STATES[name]: raise ValueError(f"invalid state {state!r} for gate {name!r}") if tested_sha and not SHA_RE.fullmatch(tested_sha): @@ -56,9 +105,13 @@ def parse_gate(text: str) -> tuple[str, dict]: return name, {"state": state, "tested_sha": tested_sha, "run_url": run_url} -def build_manifest(target_sha: str, gates: list[str]) -> dict: +def build_manifest(target_sha: str, gates: list[str], profile: str = "stable") -> dict: if not SHA_RE.fullmatch(target_sha): raise ValueError(f"target SHA must be 40 lowercase hex characters: {target_sha!r}") + try: + rules = PROFILES[profile] + except KeyError: + raise ValueError(f"unknown profile {profile!r}; expected {sorted(PROFILES)}") from None parsed = {} for spec in gates: name, gate = parse_gate(spec) @@ -67,29 +120,41 @@ def build_manifest(target_sha: str, gates: list[str]) -> dict: parsed[name] = gate reasons = [] - for name in REQUIRED + OPTIONAL: + for name in rules["required"] + rules["optional"]: gate = parsed.get(name) if gate is None: parsed[name] = {"state": "UNVERIFIED", "tested_sha": "", "run_url": ""} - reasons.append(f"{name}: missing gate") + if name in rules["required"]: + reasons.append(f"{name}: missing gate") continue if gate["tested_sha"] != target_sha: reasons.append( f"{name}: tested_sha {gate['tested_sha'] or '(missing)'} != target_sha {target_sha}" ) - elif gate["state"] == "FAIL": + continue + if gate["state"] == "FAIL": reasons.append(f"{name}: FAIL") elif gate["state"] == "UNVERIFIED": reasons.append(f"{name}: UNVERIFIED") - elif name in REQUIRED and gate["state"] != "PASS": + elif gate["state"] == "UNSUPPORTED": + allowed = False + if name in {"windows", "macos"}: + allowed = rules["windows_macos_unsupported_allowed"] + elif name == "strict_vm": + allowed = rules["strict_unsupported_allowed"] + if not allowed: + reasons.append(f"{name}: UNSUPPORTED is not allowed in the {profile} profile") + elif name == "performance": + if gate["state"] not in {"PASS", "WARN"}: + reasons.append(f"{name}: {gate['state']} is not PASS/WARN") + elif gate["state"] != "PASS": reasons.append(f"{name}: {gate['state']} is not PASS") - elif name == "performance" and gate["state"] not in {"PASS", "WARN"}: - reasons.append(f"performance: {gate['state']} is not PASS/WARN") - decision = "RELEASE_CANDIDATE" if not reasons else "DO_NOT_RELEASE" + decision = rules["decision"] if not reasons else "DO_NOT_RELEASE" recorded = utc_now() return { "schema": SCHEMA, + "profile": profile, "target_sha": target_sha, "recorded_utc": recorded, "gates": { @@ -107,11 +172,12 @@ def build_manifest(target_sha: str, gates: list[str]) -> dict: def main(argv: list[str]) -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--target-sha", required=True) + parser.add_argument("--profile", choices=sorted(PROFILES), default="stable") parser.add_argument("--gate", action="append", default=[]) parser.add_argument("--out", default="") args = parser.parse_args(argv) try: - manifest = build_manifest(args.target_sha, args.gate) + manifest = build_manifest(args.target_sha, args.gate, args.profile) except ValueError as error: print(f"error: {error}", file=sys.stderr) return 2 diff --git a/tools/ci/test_release_evidence.py b/tools/ci/test_release_evidence.py index 8907779..cf695ce 100644 --- a/tools/ci/test_release_evidence.py +++ b/tools/ci/test_release_evidence.py @@ -83,6 +83,96 @@ class ReleaseEvidenceTests(unittest.TestCase): ) self.assertEqual(manifest["release_decision"], "DO_NOT_RELEASE") + def test_beta_profile_accepts_declared_linux_scope_with_warn_performance(self) -> None: + manifest = release_evidence.build_manifest( + SHA, + [ + gate("linux", "PASS"), + gate("strict_vm", "PASS"), + gate("extension", "PASS"), + gate("clean_install", "PASS"), + gate("version_compat", "PASS"), + gate("windows", "UNSUPPORTED", url="linux-only-support-matrix"), + gate("macos", "UNSUPPORTED", url="linux-only-support-matrix"), + gate("performance", "WARN"), + ], + profile="beta", + ) + self.assertEqual(manifest["release_decision"], "BETA_RELEASE_CANDIDATE") + self.assertEqual(manifest["profile"], "beta") + self.assertEqual(manifest["reasons"], []) + + def test_beta_profile_allows_tested_fail_closed_strict_policy(self) -> None: + manifest = release_evidence.build_manifest( + SHA, + [ + gate("linux", "PASS"), + gate("strict_vm", "UNSUPPORTED", url="strict.fail_closed_test"), + gate("extension", "PASS"), + gate("clean_install", "PASS"), + gate("version_compat", "PASS"), + gate("windows", "UNSUPPORTED"), + gate("macos", "UNSUPPORTED"), + gate("performance", "WARN"), + ], + profile="beta", + ) + self.assertEqual(manifest["release_decision"], "BETA_RELEASE_CANDIDATE") + + def test_beta_profile_requires_explicit_platform_and_extension_gates(self) -> None: + manifest = release_evidence.build_manifest( + SHA, + [ + gate("linux", "PASS"), + gate("strict_vm", "PASS"), + gate("clean_install", "PASS"), + gate("version_compat", "PASS"), + gate("performance", "WARN"), + ], + profile="beta", + ) + self.assertEqual(manifest["release_decision"], "DO_NOT_RELEASE") + joined = " ".join(manifest["reasons"]) + self.assertIn("extension: missing gate", joined) + self.assertNotIn("windows: missing gate", joined) + + def test_beta_profile_rejects_wrong_sha_and_unverified_gates(self) -> None: + manifest = release_evidence.build_manifest( + SHA, + [ + gate("linux", "PASS", OTHER), + gate("strict_vm", "PASS"), + gate("extension", "UNVERIFIED"), + gate("clean_install", "PASS"), + gate("version_compat", "PASS"), + gate("windows", "UNSUPPORTED"), + gate("macos", "UNSUPPORTED"), + gate("performance", "PASS"), + ], + profile="beta", + ) + self.assertEqual(manifest["release_decision"], "DO_NOT_RELEASE") + joined = " ".join(manifest["reasons"]) + self.assertIn("linux", joined) + self.assertIn("extension", joined) + + def test_stable_profile_rejects_beta_unsupported_states(self) -> None: + manifest = release_evidence.build_manifest( + SHA, + [ + gate("linux", "PASS"), + gate("windows", "UNSUPPORTED"), + gate("macos", "UNSUPPORTED"), + gate("strict_vm", "UNSUPPORTED"), + gate("performance", "WARN"), + ], + ) + self.assertEqual(manifest["release_decision"], "DO_NOT_RELEASE") + + def test_unknown_profile_is_rejected(self) -> None: + with self.assertRaises(ValueError): + release_evidence.build_manifest(SHA, [], profile="lts") + def test_unknown_gate_and_bad_sha_are_rejected(self) -> None: with self.assertRaises(ValueError): release_evidence.build_manifest(SHA, [gate("solaris", "PASS")]) diff --git a/tools/release/package.py b/tools/release/package.py new file mode 100644 index 0000000..7d595fd --- /dev/null +++ b/tools/release/package.py @@ -0,0 +1,288 @@ +#!/usr/bin/env python3 +"""Build the Marqdo release archive from a clean, pinned commit. + +The archive is deterministic (sorted entries, commit timestamp, uid/gid 0) and +contains the CLI, the provider worker helper (same directory, same target), the +licenses/changelog/compatibility matrix, the public specs, the developer docs, +the runnable examples and the public protocol consumers. + +It refuses to package a dirty tree, a version that does not match the Cargo +workspace, or a HEAD that differs from `--source-sha`, and it fails if the +example extension artifacts cannot be built on the host. Nothing here publishes +anything; tagging is a separate reviewed step. + +Usage (from the repository root, after +`cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker`): + + python3 tools/release/package.py \ + --source-sha "$(git rev-parse HEAD)" \ + --version 3.0.0-beta.1 +""" + +from __future__ import annotations + +import argparse +import gzip +import hashlib +import json +import os +import shutil +import subprocess +import sys +import tarfile +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +BINARIES = ("marqdo", "marqdo-provider-worker") + + +def fail(message: str) -> "NoReturn": + print(f"package: error: {message}", file=sys.stderr) + raise SystemExit(1) + + +def run(command: list[str], **kwargs) -> subprocess.CompletedProcess: + return subprocess.run(command, check=True, text=True, **kwargs) + + +def git(*args: str) -> str: + return run(["git", *args], cwd=ROOT, capture_output=True).stdout.strip() + + +def sha256_file(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + return digest.hexdigest() + + +def host_target() -> str: + out = run(["rustc", "-vV"], capture_output=True).stdout + for line in out.splitlines(): + if line.startswith("host: "): + return line[len("host: ") :] + fail("rustc -vV has no host line") + + +def workspace_version() -> str: + metadata = json.loads( + run( + ["cargo", "metadata", "--no-deps", "--format-version", "1", "--offline"], + cwd=ROOT, + capture_output=True, + ).stdout + ) + for package in metadata["packages"]: + if package["name"] == "marqdo-cli": + return package["version"] + fail("cargo metadata has no marqdo-cli package") + + +def toolchain() -> dict: + rustc = run(["rustc", "-vV"], capture_output=True).stdout + release = "" + commit = "" + for line in rustc.splitlines(): + if line.startswith("release: "): + release = line[len("release: ") :] + elif line.startswith("commit-hash: "): + commit = line[len("commit-hash: ") :] + cargo = run(["cargo", "--version"], capture_output=True).stdout.strip() + return {"rustc": release, "rustc_commit": commit, "cargo": cargo} + + +def check_clean(source_sha: str) -> None: + head = git("rev-parse", "HEAD") + if head != source_sha: + fail(f"HEAD {head} does not match --source-sha {source_sha}") + status = git("status", "--porcelain") + allowed = [ + line + for line in status.splitlines() + if not (line.startswith("?? dist/") or line.startswith("!! dist/")) + ] + if allowed: + fail("working tree is not clean:\n" + "\n".join(allowed)) + + +def build_examples() -> dict: + outputs = {} + for name in ("plugin-demo", "plugin-multi-export", "provider-demo"): + script = ROOT / "examples" / name / "build.sh" + run(["bash", str(script)], cwd=ROOT) + outputs[name] = ROOT / "examples" / name / "build" + for path in sorted(outputs[name].rglob("*")): + if path.is_file(): + outputs.setdefault("files", {})[str(path.relative_to(ROOT))] = sha256_file(path) + return outputs + + +def copy_tree(source: Path, destination: Path) -> None: + shutil.copytree(source, destination, dirs_exist_ok=True) + + +def stage(stage_dir: Path, version: str, source_sha: str, target: str) -> dict: + stage_dir.mkdir(parents=True) + release_dir = ROOT / "target" / "release" + for name in BINARIES: + binary = release_dir / name + if not binary.is_file(): + fail(f"missing release binary {binary}; build with --release --locked first") + installed = stage_dir / name + shutil.copy2(binary, installed) + installed.chmod(0o755) + + for name in ("README.md", "CHANGELOG.md", "COMPATIBILITY.md"): + shutil.copy2(ROOT / name, stage_dir / name) + for license_name in ("LICENSE-MIT", "LICENSE-APACHE"): + shutil.copy2(ROOT / license_name, stage_dir / license_name) + + copy_tree(ROOT / "spec", stage_dir / "spec") + copy_tree(ROOT / "docs" / "developers", stage_dir / "docs" / "developers") + + # Examples without local build output, then the freshly built extension + # artifacts so a clean install can run every example without a compiler. + copy_tree(ROOT / "examples", stage_dir / "examples") + for build_dir in stage_dir.glob("examples/*/build"): + shutil.rmtree(build_dir, ignore_errors=True) + for example in ("plugin-demo", "plugin-multi-export", "provider-demo"): + copy_tree(ROOT / "examples" / example / "build", stage_dir / "examples" / example / "build") + + copy_tree(ROOT / "tests" / "consumers", stage_dir / "tests" / "consumers") + + limitations = ROOT / "docs" / "developers" / "release-limits.md" + shutil.copy2(limitations, stage_dir / "KNOWN_LIMITATIONS.md") + + commit_time = int(git("show", "-s", "--format=%ct", "HEAD")) + binaries = { + name: { + "sha256": sha256_file(stage_dir / name), + "size": (stage_dir / name).stat().st_size, + } + for name in BINARIES + } + info = { + "schema": "marqdo.release-info", + "schema_version": 1, + "product": "marqdo-cli", + "product_version": version, + "source_sha": source_sha, + "target_triple": target, + "build_profile": "release", + "commit_time_utc": time_utc(commit_time), + "toolchain": toolchain(), + "binaries": binaries, + "protocols": { + "analysis": 2, + "trace": 2, + "tool": 1, + "plugin_abi": "1.x", + "foreign_wire": 1, + "provider_manifest": 2, + "lock": 4, + "markdown_profile": "marqdo.md.v1", + }, + "supported_platforms": ["x86_64-unknown-linux-gnu"], + "known_limitations": "KNOWN_LIMITATIONS.md", + "notes": [ + "Checksums prove content integrity only; they are not a publisher signature.", + "The provider worker must stay in the same directory as marqdo.", + "Run `python3 tools/release/smoke.py --archive ` before publishing.", + ], + } + (stage_dir / "RELEASE_INFO.json").write_text( + json.dumps(info, indent=2, sort_keys=True) + "\n", encoding="utf-8" + ) + (stage_dir / "SOURCE_SHA").write_text(source_sha + "\n", encoding="utf-8") + return {"info": info, "commit_time": commit_time} + + +def time_utc(epoch: int) -> str: + import datetime + + return ( + datetime.datetime.fromtimestamp(epoch, datetime.timezone.utc) + .replace(microsecond=0) + .isoformat() + .replace("+00:00", "Z") + ) + + +def make_archive(stage_dir: Path, archive: Path, commit_time: int) -> None: + entries = sorted(path for path in stage_dir.rglob("*") if path.is_file()) + entries.sort(key=lambda path: str(path.relative_to(stage_dir.parent))) + with archive.open("wb") as raw: + with gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=0) as compressed: + with tarfile.open(fileobj=compressed, mode="w", format=tarfile.GNU_FORMAT) as tar: + for path in entries: + arcname = str(path.relative_to(stage_dir.parent)) + info = tar.gettarinfo(str(path), arcname=arcname) + info.uid = 0 + info.gid = 0 + info.uname = "" + info.gname = "" + info.mtime = commit_time + # Preserve the executable bit of scripts/artifacts; only + # force the two release binaries themselves to 0755. + if path.name in BINARIES: + info.mode = 0o755 + else: + info.mode = path.stat().st_mode & 0o777 + with path.open("rb") as handle: + tar.addfile(info, handle) + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--source-sha", required=True) + parser.add_argument("--version", required=True) + parser.add_argument("--target", default=None) + parser.add_argument("--out-dir", default=str(ROOT / "dist")) + parser.add_argument("--skip-example-build", action="store_true") + args = parser.parse_args(argv) + + if not args.source_sha or len(args.source_sha) != 40 or any( + ch not in "0123456789abcdef" for ch in args.source_sha + ): + fail("--source-sha must be a full lowercase 40-character commit SHA") + check_clean(args.source_sha) + version = workspace_version() + if version != args.version: + fail(f"workspace version is {version}, not {args.version}") + target = args.target or host_target() + if target != "x86_64-unknown-linux-gnu": + fail(f"this beta release procedure supports x86_64-unknown-linux-gnu only, got {target}") + if not args.skip_example_build: + build_examples() + + out_dir = Path(args.out_dir) + out_dir.mkdir(parents=True, exist_ok=True) + stage_dir = out_dir / f"marqdo-{version}-{target}" + shutil.rmtree(stage_dir, ignore_errors=True) + staged = stage(stage_dir, version, args.source_sha, target) + archive = out_dir / f"marqdo-{version}-{target}.tar.gz" + archive.unlink(missing_ok=True) + make_archive(stage_dir, archive, staged["commit_time"]) + digest = sha256_file(archive) + checksum = out_dir / f"{archive.name}.sha256" + checksum.write_text(f"{digest} {archive.name}\n", encoding="utf-8") + print( + json.dumps( + { + "archive": str(archive), + "sha256": digest, + "checksum_file": str(checksum), + "size": archive.stat().st_size, + "source_sha": args.source_sha, + "version": version, + "target": target, + }, + indent=2, + ) + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:])) diff --git a/tools/release/smoke.py b/tools/release/smoke.py new file mode 100644 index 0000000..c7d4723 --- /dev/null +++ b/tools/release/smoke.py @@ -0,0 +1,339 @@ +#!/usr/bin/env python3 +"""Cold-install smoke test for a built Marqdo release archive. + +Extracts the archive into a fresh temporary directory and exercises the shipped +binaries only (never the development source tree): version/help, check/run/call, +lock/sync for a path dependency, Analysis v2 + Trace v2 consumers, Tool +install/dispatch, native and worker plugin transports, foreign kernel, the +Provider v2 worker (positive, unauthorized and missing-helper fail-closed), and +strict mode when the host genuinely supports it. + +Usage: + python3 tools/release/smoke.py --archive dist/marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import shutil +import subprocess +import sys +import tempfile +from pathlib import Path + + +def fail(message: str) -> "NoReturn": + print(f"smoke: FAIL: {message}", file=sys.stderr) + raise SystemExit(1) + + +def sha256_file(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + return digest.hexdigest() + + +class Runner: + def __init__(self, root: Path): + self.root = root + self.marqdo = root / "marqdo" + self.env = dict(os.environ) + self.env.pop("MARQDO_MODE", None) + self.env["MARQDO_TOOL_HOME"] = str(root / "tool-home") + + def run( + self, + args: list[str], + *, + expect: int = 0, + contains: str | None = None, + cwd: Path | None = None, + env: dict | None = None, + ) -> subprocess.CompletedProcess: + command = [str(self.marqdo), *args] + merged = dict(self.env) + if env: + merged.update(env) + result = subprocess.run( + command, + cwd=cwd or self.root, + env=merged, + capture_output=True, + text=True, + timeout=120, + ) + shown = " ".join(command[1:]) + if result.returncode != expect: + fail( + f"`marqdo {shown}` exited {result.returncode}, expected {expect}\n" + f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}" + ) + if contains is not None: + haystack = result.stdout + result.stderr + if contains not in haystack: + fail(f"`marqdo {shown}` output does not contain {contains!r}:\n{haystack}") + return result + + def json(self, args: list[str]) -> dict: + result = self.run([*args, "--json"]) + try: + return json.loads(result.stdout) + except json.JSONDecodeError as error: + fail(f"`marqdo {' '.join(args)} --json` is not JSON: {error}\n{result.stdout}") + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--archive", required=True) + parser.add_argument("--workdir", default=None, help="keep the extracted tree here") + parser.add_argument("--skip-strict", action="store_true") + args = parser.parse_args(argv) + + archive = Path(args.archive).resolve() + if not archive.is_file(): + fail(f"archive not found: {archive}") + checksum_file = archive.with_name(archive.name + ".sha256") + if checksum_file.is_file(): + expected = checksum_file.read_text(encoding="utf-8").split()[0] + actual = sha256_file(archive) + if expected != actual: + fail(f"archive sha256 {actual} does not match {checksum_file}: {expected}") + + if args.workdir: + root = Path(args.workdir).resolve() + shutil.rmtree(root, ignore_errors=True) + root.mkdir(parents=True) + else: + root = Path(tempfile.mkdtemp(prefix="marqdo-smoke-")) + try: + shutil.unpack_archive(str(archive), str(root)) + entries = [path for path in root.iterdir() if path.is_dir()] + if len(entries) != 1: + fail(f"archive must contain exactly one top-level directory, found {entries}") + install = entries[0] + info = json.loads((install / "RELEASE_INFO.json").read_text(encoding="utf-8")) + version = info["product_version"] + source_sha = info["source_sha"] + if (install / "SOURCE_SHA").read_text(encoding="utf-8").strip() != source_sha: + fail("SOURCE_SHA does not match RELEASE_INFO.json") + for name in ("marqdo", "marqdo-provider-worker"): + binary = install / name + if not binary.is_file() or not os.access(binary, os.X_OK): + fail(f"{name} is missing or not executable in the archive") + recorded = info["binaries"][name]["sha256"] + if sha256_file(binary) != recorded: + fail(f"{name} sha256 does not match RELEASE_INFO.json") + + runner = Runner(install) + print(f"smoke: archive version {version}, source {source_sha}") + + version_out = runner.run(["--version"]).stdout.strip() + if version_out != f"marqdo {version}": + fail(f"--version printed {version_out!r}, expected 'marqdo {version}'") + runner.run(["--help"]) + runner.run(["check", "examples/multi-module/index.mq.md"]) + hello = runner.run(["run", "examples/hello.mq.md"]).stdout + if "你好" not in hello: + fail(f"hello example printed {hello!r}") + factor = runner.run( + ["call", "examples/factorial.mq.md", "阶乘", "--arg", "n=5"] + ).stdout.strip() + if factor != "120": + fail(f"factorial call printed {factor!r}, expected 120") + + # Static Analysis v2 + Trace v2 through the public consumers. + analysis = install / "analysis.json" + trace = install / "trace.json" + runner.run( + [ + "check", + "examples/multi-module/index.mq.md", + "--emit", + str(analysis), + ] + ) + runner.run(["check", "examples/multi-module/index.mq.md", "--refs"]) + document = json.loads(analysis.read_text(encoding="utf-8")) + if document.get("schema") != "marqdo.analysis" or document.get("schema_version") != 2: + fail("--emit did not write Analysis v2") + if document.get("producer", {}).get("version") != version: + fail("Analysis producer.version does not match the released product version") + runner.run( + [ + "run", + "examples/multi-module/index.mq.md", + "--trace-file", + str(trace), + ] + ) + run_trace = json.loads(trace.read_text(encoding="utf-8")) + if run_trace.get("schema") != "marqdo.trace" or run_trace.get("schema_version") != 2: + fail("--trace-file did not write Trace v2") + for consumer in ("analysis_consumer.py", "trace_consumer.py"): + command = [ + sys.executable, + str(install / "tests" / "consumers" / consumer), + str(analysis), + ] + if consumer == "trace_consumer.py": + command.append(str(trace)) + result = subprocess.run(command, capture_output=True, text=True) + if result.returncode != 0: + fail(f"{consumer} failed:\n{result.stdout}\n{result.stderr}") + validate = subprocess.run( + [ + sys.executable, + str(install / "tests" / "consumers" / "validate_protocols.py"), + str(analysis), + str(trace), + str(install / "examples" / "tool-unknown-name" / "tool.json"), + ], + capture_output=True, + text=True, + ) + if validate.returncode != 0: + if "jsonschema" in validate.stderr and "ModuleNotFoundError" in validate.stderr: + print("smoke: note: jsonschema is not installed; schema validation skipped") + else: + fail(f"validate_protocols.py failed:\n{validate.stdout}\n{validate.stderr}") + + # Tool Protocol v1: install and dispatch an independent process. + runner.run(["tool", "install", "examples/tool-unknown-name/tool.json"]) + listed = runner.run(["tool", "list"]).stdout + if "benchmark" not in listed: + fail(f"tool list does not contain benchmark:\n{listed}") + benchmark = runner.run(["benchmark", "run", "."]).stdout + if "benchmark tool:" not in benchmark: + fail(f"tool dispatch output unexpected:\n{benchmark}") + + # Callable plugin ABI v1: native (explicit trust) and worker transports. + native = runner.run( + [ + "run", + "examples/plugin-demo/plugin-call.mq.md", + "--plugin", + "examples/plugin-demo/build", + "--trust-native-plugin", + "--allow-plugin", + "demo.solver", + ] + ).stdout.strip() + if native != "42": + fail(f"native plugin example printed {native!r}, expected 42") + runner.run( + ["plugin", "inspect", "examples/plugin-demo/build", "--json"] + ) + worker_dir = install / "worker-plugin" + worker_dir.mkdir() + shutil.copy2(install / "examples/plugin-demo/build/solver.so", worker_dir / "solver.so") + worker_manifest = ( + install / "examples/plugin-demo/build/plugin.yaml" + ).read_text(encoding="utf-8").replace("kind: native", "kind: worker") + (worker_dir / "plugin.yaml").write_text(worker_manifest, encoding="utf-8") + worker = runner.run( + [ + "run", + "examples/plugin-demo/plugin-call.mq.md", + "--plugin", + str(worker_dir), + "--allow-plugin", + "demo.solver", + ] + ).stdout.strip() + if worker != "42": + fail(f"worker plugin example printed {worker!r}, expected 42") + + # Foreign kernel: no core change for a new language tag. + kernel = runner.run( + [ + "run", + "examples/kernel-mock/demo.mq.md", + "--kernel", + "examples/kernel-mock/kernel.json", + "--allow-foreign", + ] + ).stdout.strip() + if kernel != "42": + fail(f"foreign kernel example printed {kernel!r}, expected 42") + + # Resource Provider v2 through the shipped worker helper. + provider = "examples/provider-demo/build/provider.json" + provider_run = runner.json( + [ + "run", + "examples/provider-demo/demo.mq.md", + "--provider", + provider, + "--allow-provider", + "demo.sensor", + ] + ) + if not provider_run.get("success"): + fail(f"provider run was not successful: {provider_run}") + reads = [ + event + for event in provider_run.get("trace", []) + if event.get("op") == "resource.read" + ] + if not reads or "count=5" not in str(reads[-1].get("result")): + fail(f"provider read did not report five bytes: {reads}") + runner.run( + [ + "run", + "examples/provider-demo/unauthorized.mq.md", + "--provider", + provider, + ], + expect=1, + contains="permission.denied", + ) + worker_binary = install / "marqdo-provider-worker" + shutil.move(str(worker_binary), str(worker_binary.with_suffix(".hidden"))) + try: + runner.run( + [ + "run", + "examples/provider-demo/demo.mq.md", + "--provider", + provider, + "--allow-provider", + "demo.sensor", + ], + expect=1, + contains="ext.worker_unavailable", + ) + finally: + shutil.move(str(worker_binary.with_suffix(".hidden")), str(worker_binary)) + + # pure mode: language execution without project grants. + runner.run(["run", "examples/hello.mq.md", "--mode", "pure"]) + + if not args.skip_strict: + platform = runner.json(["inspect", "examples/hello.mq.md", "--platform"]) + strict = platform.get("platform", {}).get("strict", {}) + if strict.get("state") == "available": + runner.run(["run", "examples/hello.mq.md", "--mode", "strict"]) + print(f"smoke: strict available ({strict.get('mechanism')}) and exercised") + else: + refused = runner.run( + ["run", "examples/hello.mq.md", "--mode", "strict"], + expect=1, + ) + if "strict" not in (refused.stdout + refused.stderr): + fail("unsupported strict mode did not fail closed with a strict diagnostic") + print(f"smoke: strict unsupported on this host; fail-closed refused: {strict}") + + print("smoke: PASS") + return 0 + finally: + if not args.workdir: + shutil.rmtree(root, ignore_errors=True) + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:]))