release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs

REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
This commit is contained in:
cflmy committed 2026-11-22 02:31:32 +08:00
1 parent 56189b176c
commit 1b4fceea6b
55 files changed
+3136 -453

No files matched your search

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