release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run

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 2c7c4f31e7
55 files changed
+3136 -453

No files matched your search

+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.