feat(m0.6-r6): release examples, public schemas and cross-platform CI

- add runnable examples for an unknown-name Tool, multi-export plugin,
  external kernel provider and same-name multi-version packages
- add JSON Schemas for Analysis v1, Trace v1 and Tool v1 and validate them in CI
- extend CI with protocol/consumer smoke tests and a Windows/macOS cargo check
- add --kernel provider descriptors and R6 example integration tests
- document the examples and update M0.6 status
This commit is contained in:
cflmy committed 2026-11-20 11:50:27 +08:00
1 parent 54c7b43d15
commit 4ce37afb39
31 files changed
+537 -5

No files matched your search

+47 -1
View File
@@ -24,16 +24,62 @@ jobs:
run: cargo clippy --workspace --all-targets -- -D warnings
- name: Tests
run: cargo test --workspace
- name: Smoke test the CLI examples
- name: Validate public JSON schemas
run: |
python3 - <<'PY'
import json, pathlib
for path in pathlib.Path("spec/schemas").glob("*.json"):
json.loads(path.read_text())
print("schemas parse")
PY
- name: Smoke test the CLI, protocols and examples
run: |
cargo build -p marqdo-cli
./target/debug/marqdo check examples/factorial.mq.md
./target/debug/marqdo call examples/factorial.mq.md 阶乘 --arg n=5
./target/debug/marqdo call examples/math.mq.md 计算圆面积
./target/debug/marqdo inspect examples/references.mq.md --refs
./target/debug/marqdo check examples/multi-module/index.mq.md --refs \
--emit /tmp/marqdo-analysis.json
./target/debug/marqdo run examples/hello.mq.md \
--trace-file /tmp/marqdo-trace.json
python3 tests/consumers/analysis_consumer.py /tmp/marqdo-analysis.json
python3 - <<'PY'
import json
json.load(open("/tmp/marqdo-trace.json"))
print("trace parses")
PY
./target/debug/marqdo run examples/packages-multi-version/index.mq.md
./target/debug/marqdo run examples/kernel-mock/demo.mq.md \
--kernel examples/kernel-mock/kernel.json --allow-foreign
export MARQDO_TOOL_HOME="$(mktemp -d)"
./target/debug/marqdo tool install examples/tool-unknown-name/tool.json
./target/debug/marqdo benchmark run .
./target/debug/marqdo tool remove benchmark
./examples/plugin-demo/build.sh
./target/debug/marqdo plugin inspect examples/plugin-demo
./target/debug/marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo \
--trust-native-plugin \
--allow-plugin demo.solver
./examples/plugin-multi-export/build.sh
./target/debug/marqdo check examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export
./target/debug/marqdo run examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export \
--trust-native-plugin \
--allow-plugin demo.solver
cross-platform:
name: cargo check (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [windows-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- name: Check all targets
run: cargo check --workspace --all-targets
+1
View File
@@ -6,3 +6,4 @@
# Built plugin artifacts
examples/plugin-demo/solver.so
examples/plugin-multi-export/solver.so
Generated
+1
View File
@@ -363,6 +363,7 @@ dependencies = [
"libc",
"marqdo-span",
"marqdo-value",
"serde",
"serde_json",
"tempfile",
"thiserror",
+13 -1
View File
@@ -187,7 +187,8 @@ tests/ conformance/negative corpus (see tests/README.md)
[`package-format.md`](spec/package-format.md),
[`plugin-abi.md`](spec/plugin-abi.md), [`math.md`](spec/math.md),
[`foreign.md`](spec/foreign.md), [`tool-v1.md`](spec/tool-v1.md),
[`analysis-v1.md`](spec/analysis-v1.md), [`trace-v1.md`](spec/trace-v1.md).
[`analysis-v1.md`](spec/analysis-v1.md), [`trace-v1.md`](spec/trace-v1.md);
JSON Schemas in [`spec/schemas/`](spec/schemas/).
* [`tests/README.md`](tests/README.md) — conformance corpus and `UPDATE_GOLDENS`
workflow.
@@ -198,6 +199,9 @@ marqdo run examples/hello.mq.md
marqdo call examples/factorial.mq.md 数学.阶乘 --arg n=5
marqdo run examples/multi-module/index.mq.md
marqdo run examples/python-foreign.mq.md --allow-foreign # needs python3 or node
marqdo run examples/packages-multi-version/index.mq.md
marqdo run examples/kernel-mock/demo.mq.md \
--kernel examples/kernel-mock/kernel.json --allow-foreign
marqdo inspect examples/references.mq.md --refs
marqdo inspect examples/hello.mq.md --platform # strict: unavailable
@@ -205,6 +209,14 @@ marqdo inspect examples/hello.mq.md --platform # strict: unavailable
marqdo plugin inspect examples/plugin-demo
marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo --trust-native-plugin --allow-plugin demo.solver
./examples/plugin-multi-export/build.sh
marqdo run examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export --trust-native-plugin --allow-plugin demo.solver
marqdo tool install examples/tool-unknown-name/tool.json
marqdo benchmark run .
marqdo tool remove benchmark
```
## References
+42
View File
@@ -40,6 +40,8 @@ pub struct SandboxSettings {
pub trust_native_plugin: bool,
/// Optional Trace v1 output path.
pub trace_file: Option<PathBuf>,
/// External foreign-kernel descriptor paths.
pub kernels: Vec<PathBuf>,
}
impl SandboxSettings {
@@ -698,6 +700,16 @@ pub fn execute(
if let Some(timeout) = settings.timeout {
host.budget.deadline = Some(Instant::now() + Duration::from_secs(timeout));
}
for kernel_path in &settings.kernels {
if let Err(error) = load_kernel_descriptor(&mut host, kernel_path) {
if json {
output::print_json(&json!({"success": false, "error": error}));
} else {
eprintln!("error: {error}");
}
return 2;
}
}
for plugin_path in &settings.plugins {
if let Err(message) =
load_plugin_into_host(&mut host, plugin_path, settings.trust_native_plugin)
@@ -822,6 +834,36 @@ pub fn execute(
}
}
fn load_kernel_descriptor(host: &mut StdHost, path: &Path) -> Result<(), String> {
let text = std::fs::read_to_string(path).map_err(|error| {
format!(
"cannot read kernel descriptor `{}`: {error}",
path.display()
)
})?;
let mut descriptor: marqdo_foreign::KernelDescriptor = serde_json::from_str(&text)
.map_err(|error| format!("invalid kernel descriptor `{}`: {error}", path.display()))?;
if descriptor.builtin {
return Err("external kernel descriptors must not set `builtin: true`".to_string());
}
if descriptor.entrypoint.is_relative() {
let base = path.parent().unwrap_or_else(|| Path::new("."));
descriptor.entrypoint = base.join(&descriptor.entrypoint);
}
descriptor.entrypoint = descriptor
.entrypoint
.canonicalize()
.map_err(|error| format!("cannot open kernel provider: {error}"))?;
if !descriptor.entrypoint.is_file() {
return Err(format!(
"kernel provider executable `{}` does not exist",
descriptor.entrypoint.display()
));
}
host.register_kernel(descriptor)
.map_err(|error| format!("{}: {}", error.code(), error.message))
}
fn load_plugin_into_host(
host: &mut StdHost,
path: &Path,
+4
View File
@@ -101,6 +101,9 @@ struct SandboxArgs {
/// Write a versioned Trace v1 file for this run.
#[arg(long = "trace-file", value_name = "PATH")]
trace_file: Option<PathBuf>,
/// Register an external foreign-kernel provider (repeatable).
#[arg(long = "kernel", value_name = "PATH")]
kernel: Vec<PathBuf>,
/// Explicitly trust in-process native plugin loading (unsafe by nature).
#[arg(long = "trust-native-plugin")]
trust_native_plugin: bool,
@@ -121,6 +124,7 @@ impl SandboxArgs {
plugins: self.plugin.clone(),
trust_native_plugin: self.trust_native_plugin,
trace_file: self.trace_file.clone(),
kernels: self.kernel.clone(),
}
}
}
+97
View File
@@ -0,0 +1,97 @@
//! R6 integration examples that do not require an official external repo.
#![cfg(unix)]
use std::path::Path;
use std::process::{Command, Output};
fn repo() -> &'static Path {
Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.unwrap()
.parent()
.unwrap()
}
fn cli(args: &[&str]) -> Output {
Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(args)
.current_dir(repo())
.output()
.expect("run marqdo")
}
fn stderr(output: &Output) -> String {
String::from_utf8_lossy(&output.stderr).to_string()
}
#[test]
fn multi_version_packages_run_without_an_implicit_override() {
let output = cli(&["run", "examples/packages-multi-version/index.mq.md"]);
assert_eq!(output.status.code(), Some(0), "{}", stderr(&output));
assert_eq!(String::from_utf8_lossy(&output.stdout), "1\n2\n");
}
#[test]
fn external_kernel_provider_runs_without_core_changes() {
let output = cli(&[
"run",
"examples/kernel-mock/demo.mq.md",
"--kernel",
"examples/kernel-mock/kernel.json",
"--allow-foreign",
]);
assert_eq!(output.status.code(), Some(0), "{}", stderr(&output));
assert_eq!(String::from_utf8_lossy(&output.stdout), "42\n");
}
#[test]
fn unknown_tool_name_installs_and_dispatches() {
let home = std::env::temp_dir().join(format!(
"marqdo-r6-tool-home-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
let install = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["tool", "install", "examples/tool-unknown-name/tool.json"])
.env("MARQDO_TOOL_HOME", &home)
.current_dir(repo())
.output()
.unwrap();
assert_eq!(install.status.code(), Some(0), "{}", stderr(&install));
let run = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["benchmark", "run", "."])
.env("MARQDO_TOOL_HOME", &home)
.current_dir(repo())
.output()
.unwrap();
assert_eq!(run.status.code(), Some(0), "{}", stderr(&run));
assert!(String::from_utf8_lossy(&run.stdout).contains("arg=run"));
let remove = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["tool", "remove", "benchmark"])
.env("MARQDO_TOOL_HOME", &home)
.current_dir(repo())
.output()
.unwrap();
assert_eq!(remove.status.code(), Some(0), "{}", stderr(&remove));
let _ = std::fs::remove_dir_all(home);
}
#[test]
fn public_schemas_are_valid_json_and_versioned() {
for name in ["analysis-v1", "trace-v1", "tool-v1"] {
let path = repo()
.join("spec/schemas")
.join(format!("{name}.schema.json"));
let schema: serde_json::Value =
serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
assert_eq!(
schema["$schema"],
"https://json-schema.org/draft/2020-12/schema"
);
assert!(schema["title"].is_string());
assert!(schema["type"].as_str() == Some("object"));
}
}
+1
View File
@@ -14,6 +14,7 @@ tempfile = { workspace = true }
[dependencies]
marqdo-span = { workspace = true }
marqdo-value = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
+6 -2
View File
@@ -74,7 +74,7 @@ pub const SUPPORTED_LANGUAGES: [&str; 2] = ["python", "javascript"];
///
/// Descriptors are metadata; they do not grant process/filesystem access. The
/// host still requires an explicit foreign grant before invoking one.
#[derive(Debug, Clone, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct KernelDescriptor {
/// Stable provider id (`python`, `javascript`, `mocklang`, ...).
pub provider_id: String,
@@ -86,10 +86,14 @@ pub struct KernelDescriptor {
/// providers must point at an explicit executable.
pub entrypoint: PathBuf,
/// Content digest of the external provider program, when known.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub digest: Option<String>,
/// Advisory capability requests; never grants.
#[serde(default)]
pub permissions_requested: Vec<String>,
/// Whether this is one of the built-in Python/Node providers.
/// Whether this is one of the built-in Python/Node providers. External
/// descriptors must leave this false.
#[serde(default)]
pub builtin: bool,
}
+1 -1
View File
@@ -45,7 +45,7 @@ providers).
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
| R4 Analysis/Trace v1 | **Done** | `check --emit` Analysis v1; `run/call --trace-file` Trace v1; deterministic schema tests; independent Python consumer; stale-artifact removal; value redaction |
| R5 environment/isolation | **Partial** | Pinned Git fetch/cache, transitive `@alias` resolution, atomic `.marqdo/env` materialization, foreign process-group cleanup. Strict OS isolation remains explicitly unavailable (fail-closed) |
| R6 release/consumers | Not started | — |
| R6 release/consumers | **Done for Linux** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas; CI Linux gate + Windows/macOS `cargo check`; R6 example tests |
Reproduce the evidence:
+16
View File
@@ -0,0 +1,16 @@
# External kernel provider example
`mocklang` is not built into `marqdo-foreign`. The descriptor registers it at
run time without changing interpreter or host source:
```sh
marqdo run examples/kernel-mock/demo.mq.md \
--kernel examples/kernel-mock/kernel.json \
--allow-foreign
```
The `mocklang` executable receives the source file path as argv[1] and the
versioned request envelope on stdin. For `foreign.call` it must print exactly
one typed wire value on stdout. A missing provider or wire version is
`kernel.unavailable`; the `Code` value itself remains inert until the explicit
call.
+11
View File
@@ -0,0 +1,11 @@
## main
### 代码
```mocklang
ignored by the mock provider
```
**结果 = foreign.call(ref("#代码"), {})**
> 打印(结果)
+7
View File
@@ -0,0 +1,7 @@
{
"provider_id": "mocklang",
"languages": ["mocklang", "mock"],
"wire_version": 1,
"entrypoint": "./mocklang",
"permissions_requested": []
}
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
# Minimal external kernel provider: consume the request envelope, then emit one
# typed wire value. The source file path is argv[1].
cat >/dev/null
printf '%s' '{"type":"int","decimal":"42"}'
+19
View File
@@ -0,0 +1,19 @@
# Multi-version package example
Two directories declare the same package name `geometry` at versions `1.0.0`
and `2.0.0`. They receive different package-instance ids and different
`ModuleId`s; importing both aliases is not an implicit override.
```sh
marqdo run examples/packages-multi-version/index.mq.md
marqdo lock
```
`marqdo lock` must be run from the example directory because it discovers the
project from the current working directory:
```sh
(cd examples/packages-multi-version && ../../target/debug/marqdo lock)
```
The lock records both content-addressed instances; no version silently wins.
@@ -0,0 +1,15 @@
---
import:
geometry_v1: "@geometry_v1"
geometry_v2: "@geometry_v2"
---
## main
**一 = geometry_v1.area()**
**二 = geometry_v2.area()**
> 打印(一)
> 打印(二)
@@ -0,0 +1,8 @@
project:
name: multi-version
version: 0.1.0
dependencies:
geometry_v1:
path: ./packages/geometry-v1
geometry_v2:
path: ./packages/geometry-v2
@@ -0,0 +1,3 @@
## area
*1*
@@ -0,0 +1,3 @@
project:
name: geometry
version: 1.0.0
@@ -0,0 +1,3 @@
## area
*2*
@@ -0,0 +1,3 @@
project:
name: geometry
version: 2.0.0
+17
View File
@@ -0,0 +1,17 @@
# Multi-export plugin example
One native library exports two complete names: `solver.add` and `solver.neg`.
Both are registered and callable; there is no "first prefix wins" namespace.
```sh
./examples/plugin-multi-export/build.sh
marqdo check examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export
marqdo run examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export \
--trust-native-plugin --allow-plugin demo.solver
```
`check --plugin` validates both signatures without loading the library. The
runtime still requires the explicit in-process trust decision; a C ABI is not a
sandbox, and an isolated worker transport is not part of this build.
+17
View File
@@ -0,0 +1,17 @@
#!/usr/bin/env bash
set -euo pipefail
here="$(cd "$(dirname "$0")" && pwd)"
repo="$(cd "$here/../.." && pwd)"
cd "$repo"
cc -std=c11 -O2 -shared -fPIC -I include -DMQ_SOLVER_MULTI_EXPORT \
-o "$here/solver.so" examples/plugin-demo/solver.c
hash="$(sha256sum "$here/solver.so" | cut -d' ' -f1)"
python3 - "$here/plugin.yaml" "$hash" <<'PY'
import pathlib, re, sys
path, digest = sys.argv[1], sys.argv[2]
p = pathlib.Path(path)
text = p.read_text()
text = re.sub(r'(?m)^(\s*sha256:\s*")[0-9a-fA-F]{64}(")', r'\g<1>' + digest + r'\g<2>', text)
p.write_text(text)
PY
echo "built $here/solver.so"
@@ -0,0 +1,9 @@
## main
**和 = solver.add(a=20, b=22)**
**相反数 = solver.neg(a=7)**
> 打印(和)
> 打印(相反数)
+18
View File
@@ -0,0 +1,18 @@
# Two exports under different prefixes, built from the shared C demo with
# -DMQ_SOLVER_MULTI_EXPORT. Installing grants nothing; loading requires trust.
plugin:
name: demo.solver
version: 0.1.0
abi: "^1.0"
kind: native
exports:
- name: solver.add
signature: "($a: Int, $b: Int) -> Int"
- name: solver.neg
signature: "($a: Int) -> Int"
requires:
- math.compute
artifacts:
- target: x86_64-unknown-linux-gnu
file: solver.so
sha256: "0000000000000000000000000000000000000000000000000000000000000000"
+19
View File
@@ -0,0 +1,19 @@
# Unknown-name CLI tool example
This directory is a complete Tool Protocol v1 package. Nothing named
`benchmark` exists in the Marqdo CLI source; after installation the unknown
top-level command is dispatched by the registry.
```sh
marqdo tool install examples/tool-unknown-name/tool.json
marqdo tool list
marqdo benchmark run . --some-tool-option
marqdo tool remove benchmark
```
The executable receives the remaining arguments verbatim, inherits stdio/cwd,
and its exit code is propagated. `MARQDO_TOOL_PROTOCOL=1` and `MARQDO_BIN` are
provided for tools that need `check --emit`/`run --trace-file`.
A Tool is a user-run native process. It is **not** a C ABI plugin, a foreign
kernel, or a program inside the `.mq.md` sandbox.
+8
View File
@@ -0,0 +1,8 @@
#!/bin/sh
# A deliberately tool-specific program: the Marqdo CLI knows no `benchmark`
# command or its options.
printf 'benchmark tool: protocol=%s\n' "${MARQDO_TOOL_PROTOCOL:-unset}"
for argument in "$@"; do
printf 'arg=%s\n' "$argument"
done
exit 0
+11
View File
@@ -0,0 +1,11 @@
{
"schema": "marqdo.cli-tool",
"schema_version": 1,
"name": "demo.benchmark",
"version": "0.1.0",
"command": "benchmark",
"entrypoint": "bin/marqdo-benchmark",
"compatibility": {
"marqdo": ">=0.1,<1"
}
}
+52
View File
@@ -0,0 +1,52 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://marqdo.dev/schemas/analysis-v1.schema.json",
"title": "Marqdo Analysis v1",
"type": "object",
"required": ["schema", "schema_version", "producer", "project", "modules", "diagnostics"],
"properties": {
"schema": {"const": "marqdo.analysis"},
"schema_version": {"const": 1},
"producer": {
"type": "object",
"required": ["name", "version", "markdown_profile"],
"properties": {
"name": {"type": "string"},
"version": {"type": "string"},
"markdown_profile": {"const": "marqdo.md.v1"}
},
"additionalProperties": true
},
"project": {
"type": "object",
"required": ["root_id", "lock_digest"],
"properties": {
"root_id": {"type": "string"},
"lock_digest": {"type": "string"}
},
"additionalProperties": true
},
"modules": {
"type": "array",
"items": {
"type": "object",
"required": ["id", "package_instance_id", "relative_path", "source_digest", "units", "functions", "imports", "references", "calls"],
"properties": {
"id": {"type": "string", "pattern": "::"},
"package_instance_id": {"type": "string"},
"relative_path": {"type": "string"},
"source_digest": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"units": {"type": "array"},
"functions": {"type": "array"},
"imports": {"type": "array"},
"references": {"type": "array"},
"calls": {"type": "array"},
"resources": {"type": "integer", "minimum": 0}
},
"additionalProperties": true
}
},
"diagnostics": {"type": "array"}
},
"additionalProperties": true
}
+25
View File
@@ -0,0 +1,25 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://marqdo.dev/schemas/tool-v1.schema.json",
"title": "Marqdo CLI Tool Manifest v1",
"type": "object",
"required": ["schema", "schema_version", "name", "version", "command", "entrypoint"],
"properties": {
"schema": {"const": "marqdo.cli-tool"},
"schema_version": {"const": 1},
"name": {"type": "string", "minLength": 1},
"version": {"type": "string", "minLength": 1},
"command": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
"entrypoint": {"type": "string", "minLength": 1},
"compatibility": {
"type": "object",
"properties": {
"marqdo": {"type": "string"},
"analysis": {"type": "array", "items": {"type": "integer", "minimum": 1}},
"trace": {"type": "array", "items": {"type": "integer", "minimum": 1}}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
+55
View File
@@ -0,0 +1,55 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://marqdo.dev/schemas/trace-v1.schema.json",
"title": "Marqdo Trace v1",
"type": "object",
"required": ["schema", "schema_version", "run", "source", "events"],
"properties": {
"schema": {"const": "marqdo.trace"},
"schema_version": {"const": 1},
"run": {
"type": "object",
"required": ["id", "entry", "status"],
"properties": {
"id": {"type": "string"},
"entry": {"type": "string"},
"status": {"type": "string"}
},
"additionalProperties": true
},
"source": {
"type": "object",
"required": ["root_id", "analysis_digest"],
"properties": {
"root_id": {"type": "string"},
"analysis_digest": {"type": "string"}
},
"additionalProperties": true
},
"events": {
"type": "array",
"items": {
"type": "object",
"required": ["seq", "kind"],
"properties": {
"seq": {"type": "integer", "minimum": 0},
"kind": {"type": "string"},
"function_id": {"type": ["string", "null"]},
"module": {"type": ["string", "null"]},
"span": {
"type": ["object", "null"],
"properties": {
"start": {"type": "integer", "minimum": 0},
"end": {"type": "integer", "minimum": 0}
}
},
"detail": {"type": ["string", "null"]},
"operation": {"type": "string"},
"duration_micros": {"type": "integer", "minimum": 0}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}