Marqdo CLI
Marqdo is a Markdown-native, independently interpreted programming language.
A .mq.md file is ordinary CommonMark/GFM prose plus explicit executable
regions: a heading declares @exec or @knowledge, **strong**, *emph* and
inline `code` are interchangeable carriers of one statement, and keywords
inside that payload — if, else, while, end, return, params — decide
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.
Breaking language revision landed. The single semantic contract is RFC-LANG-0002, with normative summaries in
spec/mapping.mdandspec/expression.ebnf. The frontend, expression parser, stdlib, examples and test corpus all implement it:cargo test --workspace --lockedis green (507 passed, 0 failed, 2 ignored at9c1723d). Old syntax (**strong**= execute,*emph*= return,1.= branch,-= loop,>= call) is not an active language andmarqdo_semantics/--legacyselectors do not exist. Seedocs/STATUS.mdanddocs/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
E0433platform-cfg failure and the Linux strict probe→launch race are fixed in source at8af7262, but the native Windows/macOS and GitHub Linux lanes have not been re-run from this checkout.strictOS 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 at8af7262(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. Seedocs/STATUS.md,COMPATIBILITY.mdanddocs/security-gate.md. The single current CI convergence plan isdocs/NEXT_RELEASE_CI_CONVERGENCE.md(historical baseline; refresh before use).
CI: the private remote git.cflmy.cn/cflmy/marqdo-cli
uses Woodpecker at ci.cflmy.cn; .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.
Build
Requires Rust 1.82+.
cargo build -p marqdo-cli
# binary: target/debug/marqdo (or $CARGO_TARGET_DIR/debug/marqdo)
Quickstart
marqdo init demo
cd demo
marqdo check index.mq.md
marqdo run index.mq.md # executes ## @exec main
marqdo inspect index.mq.md --ast
marqdo inspect index.mq.md --signature
marqdo call index.mq.md main
Example project from scratch (index.mq.md):
# @knowledge 数学
## @exec 阶乘
`params(n: Int)`
`if n <= 1`
`return 1`
`else`
`结果 = n * 阶乘(n=n-1)`
`return 结果`
`end`
marqdo check examples/factorial.mq.md
marqdo call examples/factorial.mq.md 数学.阶乘 --arg n=5 # 120
The parser is frozen: marqdo.md.v1 = CommonMark 0.31.2 + GFM tables,
strikethrough, task lists + $...$/$$...$$ math (comrak =1.0.0). A .mq.md
file still renders normally in any compatible Markdown reader; rendering never
executes anything. The Markdown profile is unchanged by the semantic rewrite.
Language in 60 seconds
- Headings declare the mode.
# @knowledge 笔记is a document namespace;## @exec mainoverrides to an executable function. Any H1–H6 may carry@exec/@knowledge; unmarked headings inherit the nearest ancestor. The document root is Knowledge. An Exec H2 is the only callable function; H3–H6 are sections inside it. - Closed carriers are interchangeable. In an Exec section,
**x = 1**,*x = 1*and`x = 1`are the same assignment. Prefer inline code spans for expressions containing*or**. - Statements are explicit.
if <Bool>,else,while <Bool>,end,return <expr>,params(n: Int), assignment, or an expression call. Each carrier holds exactly one statement; everyif/whileis closed byendinside the same heading body. - Containers do not compute.
1.,-,>and emphasis only organize the document.> print(1)is prose;> **print(1)**contains a call. - Knowledge is inert. Nothing in a
@knowledgesection executes, so it is the place for normal emphasis, explanatory lists, tables and formula resources. - No syntax switch. There is no
marqdo_semanticsfield or--legacyflag; all.mq.mdfiles use this syntax.
The full contract is spec/mapping.md and
spec/expression.ebnf; the rationale and migration
rules are RFC-LANG-0002.
What works (implemented and tested)
- P0 contracts — frozen
marqdo.md.v1profile, RFC-LANG-0002 AST → program mapping, the v2 statement grammar and evaluation semantics; 160 AST goldens, 73 semantic fixtures, 49 compile-error fixtures, 2 warning fixtures and 21 runtime-error fixtures, all green (tests/). - P1 interpreter — native Rust tree-walk interpreter: values, scopes, functions, static parameter inference, assignments, branches, loops, returns, recursion, structured errors, fuel/stack/output budgets.
- Addressable memory (RFC-CM P1) — opaque run-scoped
Memoryregions with 64 KiB zero-filled pages, grow-onlymemory.new/size/grow, bounded byte read/write,m[i] = byte, run/per-region budgets, host-boundary and wire rejection (ADR-0022). - Minimal structure primitives (RFC-CM CM-A04) — value-semantics
list.append/concat,map.keys/has/get/set/remove, Unicode scalartext.codepoints/from_codepoint, and non-negativetable.columns/row/cell; pure builtins with no mutation or new syntax (ADR-0023). - Recoverable results (RFC-CM CM-A05) —
{ok:true,value}/{ok:false,code,message}as an ordinary Map, with a.mq.mdfirst-fit free-list allocator demonstrating reuse, splitting andalloc.no_spacerecovery (ADR-0024). NoResulttype or exception syntax. - Bundled stdlib + print prototype (RFC-CM CM-A07/A10) — offline
stdlib/with explicitstd:io/std:format/std:textimports, SHA-256 digest verification, Analysis identity and a frozen-CLI closure test; the.mq.mdprint chain is the only execution path for打印/printon an official install (ADR-0031), covering all 15 value types;HostOp::Printand the legacy formatter are removed (ADR-0027/0028/0029/0030/0031). - HTTP/1.1 framing in
.mq.md—stdlib/net/http.mq.mdstatus/header/ chunked parsing and request construction; a loopback TCP test runs a real exchange (ADR-0034; no TLS/host HTTP claim). - Blocking TCP endpoint (RFC-CM P5 first slice) —
resource.open("tcp", "<ip>:<port>", ["read","write"])with exact IP grants, project mode and 5-second timeouts; DNS/TLS/UDP/server sockets excluded (ADR-0034). - C ABI provider worker (RFC-CM CM-A09) —
marqdo-provider-workerloads a trusted C ABI library in a separate framed-JSON helper process (ADR-0038). - Provider package manifest v1 (RFC-CM CM-A09) — local
marqdo.providermanifest installs a trusted C ABI provider; no registry/signature/CLI install (ADR-0037). - Third-party Resource Provider v2 through the normal CLI (RFC-EXT-0001
PR-03) — a
provider.jsonv2 bundle with a targeted, sha256-verifiedc-abi-1artifact is selected with repeatable--providerand authorized by the exact--allow-providername onrun/call; the existingmarqdo-provider-workertransport is spawned only after every manifest, artifact, grant and duplicate-kind check passes.check/inspectnever load providers,pure/strictrefuse them, and the worker transport is linux/x86_64-only in this release (ADR-0055,spec/resource-provider-v2.md). - Single callable binding through the frozen composition root
(RFC-EXT-0001 PR-01/02) — one
CallableRegistryand one binding pass feedcheck/run/call/inspect/Analysis; the runtime dispatches byCallSiteKeyand never re-resolves a name or guesses a plugin. Static plugin descriptors must reconcile one-to-one with the loaded exports (ADR-0054,spec/callable-resolution.md). - Official stdlib public aliases (RFC-EXT-0001 PR-06) —
打印/printare verifiedstdlib.jsonmetadata bound toio.mq.md::写值; theprint_override/AST-scan/runtime special case is removed with byte-identical 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).
- 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).
- 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.*/ResultABI; no parser/runtime/HostOpchange (ADR-0033). - Table stdlib algorithms (RFC-CM CM-A08) —
stdlib/data/table.mq.mdselect/filter/sort/append/set/join/group over the logicalTablevalue; value-returning, input-immutable, with GFM AST laziness unchanged (ADR-0032). - Resource streams (RFC-CM CM-A06) — opaque host-issued
Resourcehandles;resource.open/read/write/closetransfer bytes throughMemory; stdout write in pure/project, granted project-file read, and buffered project-file write flushed onclosein project; strict refuses all resource opens until verified (ADR-0025/0026). - P2 references + CLI — explicit YAML front-matter imports,
ModuleId/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
pinned Git sources, verified content-addressed Git cache, deterministic
lock, strictsync --lockedwith atomic.marqdo/envmaterialization.run/call/checknever fetch or rewrite the lock. - P4 security core — capability-checked host operations, project-relative
FS globs with traversal rejection, budgets, effect trace,
pure/projectmodes, and Linuxstrictmode using Bubblewrap namespaces, no-new-privs, capability dropping, rlimits, a wall-clock supervisor and child self-verification (ADR-0021). It is probe-gated and verified in a disposable Ubuntu VM; unsupported hosts fail closed. - P5 Math/Foreign — native
Formulavalue from$$...$$;math.parse/ eval/substituteover a documented exact-rational subset; one-shot Python/ Node kernels viaforeign.run/callwith typed wire protocol, timeout and output limits; pinned provider/environment digests and ADR-0020 environment binding. - P6 plugin ABI — frozen C ABI v1 header (
include/marqdo_plugin_abi_v1.h), host bindings, Rust SDK (mq_plugin_entry!),plugin.yamlvalidation, target-triple + sha256 artifact verification, native and isolated worker transports, brokeredfs.read, and explicitly trusted in-process calls (--plugin --trust-native-plugin --allow-plugin). A C ABI is not a sandbox. - Public protocols — Analysis v2 and Trace v2 with JSON Schemas and independent Python consumers; Tool Protocol v1 with arbitrary command names, SemVer negotiation and whole-bundle digest verification.
Run everything:
cargo test --workspace
cargo test -p marqdo-cli # conformance corpus + CLI contract tests
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
Deliberate limits (do not assume)
- Strict is Linux-only and L1-only.
--mode strictenables the Bubblewrap supervisor only when its runtime probe passes; otherwise it exits- It supports pure Marqdo + Math and rejects Foreign, plugins, kernels, external grants and trace files (exit 2). Worker plugins provide crash/address-space isolation, not an OS sandbox, and are not allowed in strict.
- Native plugins run in-process and require an explicit unsafe trust flag. A plugin can crash or read the host; a C ABI is not a sandbox.
- Package management is path + pinned-Git only. There is no registry,
floating-branch resolution, conflict solver,
--offline,tree,update,vendor, or automatic uv/npm environment creation. Manifestcapabilitiesare requests, never grants. - Reference validation is opt-in:
check --refsreports broken links; plaincheckignores them because links are static knowledge references. Markdown links never call; calls are expressions inside executable payloads, and cross-module calls use imported alias expressions such asgeometry.圆面积(r=2). ref("#anchor")is module-local and errors withref.ambiguouswhen a heading range contains more than one formula/code block instead of picking the first.fmtis minimal (line endings/trailing newlines), not AST-preserving reformatting.- Math is a limited calculator, not a CAS/prover: no
simplify/differentiate/matrices/series; equation solving is affine-only. - Foreign kernels are unsandboxed one-shot child processes (no sessions, no state bridge); they run with the host user's filesystem/network access.
- Finite floats are IEEE-754 binary64; the typed wire round-trip is exact
(
serde_json/float_roundtrip), tagged integers never lose digits, and display formatting is decimal rather than bit-identical.
Repository layout
crates/marqdo-span shared byte spans/source maps (leaf)
crates/marqdo-value Value model, diagnostics, typed wire encoding
crates/marqdo-expression strict expression/statement parser
crates/marqdo-markdown frozen comrak profile, canonical AST, front matter
crates/marqdo-ir module/unit/function/statement IR, builtin table
crates/marqdo-frontend heading scopes, mapping, inference, static calls
crates/marqdo-math exact-rational Formula subset
crates/marqdo-foreign Python/Node one-shot kernel supervisor
crates/marqdo-sandbox mode parsing + platform isolation detection
crates/marqdo-plugin-abi C ABI v1 mirrors, manifest, artifacts, loader
crates/marqdo-plugin-sdk Rust plugin SDK and entry macro
crates/marqdo-host CapabilityHost, budgets, FS, math/foreign/plugin adapters
crates/marqdo-runtime tree-walk interpreter
crates/marqdo-package marqdo.yaml / marqdo.lock / root discovery
crates/cli CLI composition root (binary `marqdo`)
include/ frozen plugin C ABI header
spec/ normative language/format/ABI specs
docs/ blueprint, ADRs, status, contributor guide
examples/ runnable documents + multi-module + plugin demo
tests/ conformance/negative corpus (see tests/README.md)
Documentation index
AGENTS.md— operating rules for contributors and coding agents.docs/architecture/RFC-LANG-0002-unified-semantics.md— the single language authority: full new syntax, breaking changes, architecture, migration and acceptance gates. Adopted by ADR-0052.spec/mapping.md— normative AST→program mapping (heading modes, unified carriers, control stack, diagnostics).spec/expression.ebnf— normative statement and expression grammar.docs/migration/README.md— migration rules and the inventory of remaining work.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/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.COMPATIBILITY.md— protocol versions, per-platform feature evidence, the breaking language change and unsupported features.CHANGELOG.md— unreleased stabilization changes and the0.1.0baseline, including the syntax breaking change.docs/security-gate.md— G-C evidence and limits;docs/security-vm.mdreproduces the disposable VM and the self-hosted security runner.docs/releasing.md— artifact, checksum, clean-install smoke, tagging and rollback procedure.docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md— historical stabilization spec (baseline0adebe4), superseded on current priorities by the stable-release plan.docs/NEXT_PHASE_IMPLEMENTATION.md— historical M0.6 plan.docs/EXTENSIBILITY_AUDIT.md— source-backed audit issues E01–E16.docs/contributor-guide.md— repo map, workflow, golden updates, quality gate.docs/STATUS.md— current work-package status, local evidence and open blockers.docs/adr/— accepted decisions (crate graph, inert executables,refambiguity, strict refusal, AST normalization, CLI contract, BigInt/wire, package identity, callable resolution, plugin export routing, capability broker, kernel providers, generic CLI tools, plugin-handle authority, public Analysis/Trace v1).- Specs:
markdown-profile.md,mapping.md,expression.ebnf,evaluation.md,references.md,value-wire.md,security.md,package-format.md,plugin-abi.md,math.md,foreign.md,tool-v1.md,analysis-v2.md,trace-v2.md; JSON Schemas inspec/schemas/. tests/README.md— conformance corpus andUPDATE_GOLDENSworkflow.
Examples
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
./examples/plugin-demo/build.sh
marqdo plugin inspect examples/plugin-demo/build
marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo/build --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/build --trust-native-plugin --allow-plugin demo.solver
marqdo tool install examples/tool-unknown-name/tool.json
marqdo benchmark run .
marqdo tool remove benchmark
Extending Marqdo without modifying or rebuilding the CLI
RFC-EXT-0001 defines five extension kinds. Each one is discovered only through
an explicit manifest/flag, is versioned, and is authorized separately from
being visible. A physically separate repository exercising all five against a
frozen binary is marqdo-extension-conformance
(https://git.cflmy.cn/cflmy/marqdo-extension-conformance).
| Kind | Static discovery | Execution | Grant |
|---|---|---|---|
.mq.md package |
marqdo.yaml dependency + marqdo.lock |
Marqdo interpreter | project mode |
| Callable plugin | plugin.yaml ABI v1 exports |
worker (default) or trusted native | --plugin + --allow-plugin NAME |
| Foreign kernel | kernel.json + pinned executable digest |
one-shot child process | --kernel + --allow-foreign |
| Resource provider | provider.json schema v2 |
marqdo-provider-worker + C ABI |
--provider + --allow-provider NAME |
| CLI Tool | tool.json install record |
independent CLI process | tool installation, no project grants |
# 1. Pure Markdown library from a pinned Git dependency
marqdo lock && marqdo sync
marqdo check consumer/index.mq.md
marqdo run consumer/index.mq.md
# 2. Callable ABI plugin (worker transport by default)
marqdo run plugin/demo.mq.md \
--plugin plugin/build --allow-plugin demo.ext
# 3. Foreign kernel with a language label the CLI has never heard of
marqdo run kernel/demo.mq.md \
--kernel kernel/build/kernel.json --allow-foreign
# 4. Resource provider v2 (see the next section)
marqdo run provider/demo.mq.md \
--provider provider/build/provider.json --allow-provider demo.sensor
# 5. Independent CLI Tool consuming only public Analysis v2
marqdo tool install tool/tool.json
marqdo inspect-ext tool/demo.mq.md
One callable resolution, visible in check and run
Calls are bound statically once per prepared program (ADR-0054, normative
details in spec/callable-resolution.md):
f(...): local callable value → official alias/reserved builtin → current namespace → canonical name → unique local name;alias.f(...): explicit import alias → builtin dotted name → exact plugin export;some_value.f(...): dynamic language value only.
check and run consume the same binding; an unknown export, wrong arguments
or a duplicate export fails before execution. An import alias that collides
with a builtin/plugin dotted namespace (for example importing a module as
math) is rejected with ext.import_namespace_conflict; rename it. A plugin
manifest is the static contract: run verifies the loaded artifact and its
exports/signatures match the manifest exactly
(ext.plugin_binding_mismatch otherwise) and never synthesises a signature.
Declaring extensions in the project (lock v4)
A project can declare explicit activation sources and lock their identity; a declaration is visibility/activation, never a grant:
extensions:
plugins:
- from: ./adapter/plugin.yaml
kernels: []
providers:
- from: "@vendor/device/provider.json"
marqdo lock # writes lock_version: 4 with manifest/artifact identities
marqdo inspect index.mq.md --extensions --json # identity + lock status, no execution
Only ./relative/path (project) and @alias/relative/path (declared
dependency) are accepted; absolute paths, URLs, globs and .. are rejected.
check/sync compare the declaration with the lock
(ext.extension_lock_mismatch), run additionally re-verifies the real
artifact bytes, and pure/strict refuse project-declared third-party
extensions. Lock v3 requires an explicit marqdo lock migration. See
spec/extension-selection.md and
docs/adr/0056-extension-selection-locking.md.
Official stdlib aliases, no print magic
打印/print are declared in the verified stdlib/stdlib.json
(public_aliases, covered by aliases_digest) and bound as ordinary
Marqdo calls to io.mq.md::写值 (ADR-0058). There is no
Program.print_override, no AST-wide print scan and no runtime print branch;
output bytes, permissions and Trace behavior are unchanged, and a program that
never uses the alias does not load the stdlib module graph. Third-party
packages cannot claim 打印/print or std.* names.
Third-party resource providers (provider.json v2)
An external repository adds a new resource kind (for example demo.sensor)
with a provider.json schema-version-2 bundle and a targeted c-abi-1 shared
library. No CLI rebuild and no core change are needed: select the manifest with
repeatable --provider and authorize it by its exact manifest name with
--allow-provider (also repeatable). A --provider without a matching
--allow-provider is permission.denied and the helper is never started;
wildcards (*) are not accepted.
marqdo run index.mq.md \
--provider vendor/demo-sensor/provider.json \
--allow-provider demo.sensor
marqdo call index.mq.md main \
--provider vendor/demo-sensor/provider.json \
--allow-provider demo.sensor
The document still uses the ordinary resource surface, e.g.
resource.open("demo.sensor", "unit-1", ["read"]); provider kinds do not become
new callables.
check/inspectdo not accept these options and never load a provider.--mode pureand--mode strictreject--provider/--allow-providerin preflight; strict L1 stays fail-closed and does not silently switch toproject.- Everything is verified before any worker starts:
schema_version: 2,abi: c-abi-1,transport: worker, strict SemVer, non-reserved kinds, the current target artifact's bundle containment and sha256, exact grants and duplicate provider names/kinds. - The helper
marqdo-provider-workermust ship next to themarqdoexecutable for the same target (noPATHfallback); a missing helper isext.worker_unavailable. The worker transport is linux/x86_64-only in this release; other platforms fail withext.platform_unsupported. - The helper is a trusted process, not an OS sandbox: it runs with the user's
privileges.
sha256is an integrity check, not publisher authentication. Seespec/resource-provider-v2.mdand ADR-0055.
References
- CommonMark 0.31.2 · GFM · Comrak
- Cargo · uv
- Wasmtime Component Model
- Legacy Marqdo source (reference only): https://github.com/cflmy/marqdo