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
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:
1 parent
56189b176c
commit
2c7c4f31e7
55 files changed
+3136
-453
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user