commit e92448f8634b76dcf0fcfb84784229c92ea548c5 Author: marqdo-extension-conformance Date: Sat Nov 21 23:08:00 2026 +0800 Initial external conformance skeleton: contract, pure-lib/consumer, foreign kernel diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml new file mode 100644 index 0000000..f216565 --- /dev/null +++ b/.github/workflows/conformance.yml @@ -0,0 +1,37 @@ +name: extension-conformance + +on: + push: + pull_request: + workflow_dispatch: + +jobs: + conformance: + # This repository does not build the Marqdo CLI. It consumes one frozen + # release binary supplied to the job as the absolute path in the + # `MARQDO_BIN` repository variable. + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Require a frozen CLI (never built here) + run: | + set -eu + test -n "${MARQDO_BIN:-}" || { echo "MARQDO_BIN is not configured"; exit 2; } + test -x "$MARQDO_BIN" || { echo "MARQDO_BIN is not executable: $MARQDO_BIN"; exit 2; } + env: + MARQDO_BIN: ${{ vars.MARQDO_BIN }} + - name: Build native fixtures with cc + run: | + ./plugin/build.sh + ./provider/build.sh + - name: Run frozen-binary conformance suite + run: python3 tests/run_all.py + env: + MARQDO_BIN: ${{ vars.MARQDO_BIN }} + MARQDO_EXPECTED_SHA256: ${{ vars.MARQDO_EXPECTED_SHA256 }} + - name: Upload evidence + if: always() + uses: actions/upload-artifact@v4 + with: + name: extension-evidence + path: evidence/results.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..87b6cf0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +# Generated native artifacts (built by each fixture's build.sh) +plugin/build/ +provider/build/ +*.so +*.dylib +*.dll +*.o +*.marker + +# Marqdo project state: dependency cache / materialized environment +.marqdo/ +consumer/.marqdo/ + +# Evidence scratch output from a local run +evidence/raw/ + +# Python caches +__pycache__/ +*.pyc + +# Editor / OS noise +.DS_Store +*.swp diff --git a/CONTRACT.md b/CONTRACT.md new file mode 100644 index 0000000..e26cb12 --- /dev/null +++ b/CONTRACT.md @@ -0,0 +1,126 @@ +# Conformance contract + +This repository is a **third-party** conformance fixture. It does not define +Marqdo semantics; it consumes the published Marqdo contracts below. Where this +document and the upstream specification disagree, the upstream specification +wins and this fixture is wrong. + +## 1. Versions consumed + +| Item | Version used here | Notes | +|---|---|---| +| Marqdo CLI / core | `marqdo 0.1.0` (`--version`) | Frozen binary supplied externally as `$MARQDO_BIN`; SHA-256 recorded in evidence and checked before/after the run | +| Language semantics | RFC-LANG-0002 / ADR-0052 | Single Markdown→program mapping: `@exec`/`@knowledge` heading modes, `if`/`else`/`while`/`end`/`return`/`params` keywords, `Strong`/`Emph`/inline `Code` as interchangeable one-statement payload carriers | +| Markdown profile | `marqdo.md.v1` | constant in Analysis `producer.markdown_profile` | +| Plugin ABI | C ABI v1.0 (`MQ_ABI_MAJOR=1`, `MQ_ABI_MINOR=0`) | `include/marqdo_plugin_abi_v1.h` (verbatim public header copy) | +| Plugin manifest | `plugin.yaml`, ABI requirement `^1.0`, `kind: worker` | worker transport is the fixture default | +| Value Wire | `wire_version = 1` (type-tagged values) | used by plugin envelopes and the foreign-kernel stdin envelope | +| Analysis | `marqdo.analysis` `schema_version: 2` | produced by `marqdo check FILE --emit FILE` | +| Trace | `marqdo.trace` `schema_version: 2` | produced by `marqdo run FILE --trace-file FILE` | +| Tool Protocol | CLI Tool Protocol v1 (`schema_version: 1`, `analysis: [2]`, `trace: [2]`) | installed via `marqdo tool install tool/tool.json` | +| Resource Provider | `provider.json` **schema_version: 2**, `abi: c-abi-1`, `transport: worker`, kind `demo.sensor` | the frozen CLI does not yet expose `--provider/--allow-provider`; see §7 | +| Provider worker wire | ADR-0035 framed JSON v1: 4-byte big-endian length + JSON, max 1 MiB/frame, ops `ping/open/read/write/close/shutdown` | implemented independently in `provider/sensor.c` (`-DDEMO_SENSOR_WORKER`) | +| Foreign kernel wire | `spec/foreign.md` v1: stdin `{"wire_version":1,"kind":"request","input":...}`, stdout exactly one typed value for `foreign.call` | implemented in `kernel/mocklang` (unknown language tag `mocklang`) | +| Git dependency / lock | `lock_version: 3`, `content_profile_version: 1`, source `git` pinned to a full lowercase 40-hex commit | `marqdo lock`/`sync`/`check`/`run` | + +## 2. Platform / target assumptions + +* Evidence is produced on **Linux x86_64** (`x86_64-unknown-linux-gnu`). +* Toolchain assumptions: `python3` (standard library only), `cc`/`gcc`, + `git`, POSIX shell. No Node, no Rust toolchain, no Marqdo workspace, no + network access is required for the normal suite. +* The plugin/provider `build.sh` scripts map the host to a Rust-style target + triple. macOS maps to `*-apple-darwin` (`.dylib`); Windows is treated as + `UNSUPPORTED` by this fixture and the build script fails explicitly instead of + guessing another platform's artifact. A `UNSUPPORTED` result is never a + `PASS`. + +## 3. Hashes and identity + +* **Artifact integrity**: lowercase hex SHA-256 of the exact artifact bytes + (`plugin.yaml` / `provider.json` `sha256` fields). This is an integrity + check, not publisher authentication. +* **Analysis digest**: SHA-256 of the exact UTF-8 bytes written by + `check --emit` (Trace v2 binds it as `source.analysis_digest`, + `sha256:`). The independent tool verifies this binding. +* **Tool digest**: SHA-256 of `tool/inspect_ext.py` as recorded in evidence. +* **Fixture identity**: full Git commit SHA of this repository at test time; + recorded in evidence as `fixture_repo_sha`. +* **Frozen CLI**: SHA-256 of `$MARQDO_BIN`, recorded before/after and asserted + unchanged. The evidence run used the provisional release binary with + SHA-256 `0179cd04a79a6bd26e5576ba9751ce51eaf3fba4ff14d44e8e5e0fea18d54ce2` + (supplied by the task); the final release binary is supplied later and must + be re-run through this suite. Scripts never hardcode this value: it is read + from `$MARQDO_BIN` (optionally asserted against `$MARQDO_EXPECTED_SHA256`). + +## 4. Grants and default run mode + +| Extension | Default transport | Required CLI grant | Default mode | +|---|---|---|---| +| `.mq.md` package | in-process Marqdo runtime | none (file reads are project-relative) | `project` | +| Callable plugin | `kind: worker` child process | `--plugin ` + `--allow-plugin demo.solver` | `project` | +| Foreign kernel | child process | `--kernel ` + `--allow-foreign` | `project` | +| Resource provider | worker (framed JSON) | `--provider ` + `--allow-provider demo.sensor` (not yet available) | `project` | +| CLI tool | separate CLI process | `tool install`; the tool stays outside the `.mq.md` sandbox | n/a | + +`pure` and `strict` modes must refuse every external extension grant. The +fixture asserts those refusals as negative tests (exit 2 at CLI preflight). +Manifest `requires`/`permissions_requested` declarations are **requests**, never +grants. + +## 5. Determinism / offline behavior + +* `check --emit` output must be location-independent (no absolute paths, + timestamps, PIDs). The tool's heading-anchor digest must be identical for the + same logical project regardless of checkout directory. +* `run --trace-file` must produce a valid Trace v2 document whose + `source.analysis_digest` matches the emitted Analysis bytes. +* After `marqdo lock` has populated `.marqdo/cache`, deleting the Git source + repository must not break `check`/`run` (no fetch at check/run time). +* Moving the project directory must not change module identity or Analysis + output. +* The tool consumer only uses the Python standard library and the public + Analysis v2 / Trace v2 files; it never links Rust or reads private IR. + +## 6. Unsupported / fail-closed behavior declared by this fixture + +* Missing plugin export: must fail closed (runtime `symbol.unknown` in the + current binary; static rejection is required by RFC-EXT-0001 §4.3 and is a + recorded gap). +* Wrong argument names / missing required arguments: static `call.arity`. +* Positional plugin arguments: not supported by ABI v1; must be rejected + (static rejection is a recorded gap; runtime rejects with `runtime.type`). +* Duplicate full export across two plugins: deterministic prepare failure. +* Tampered / missing / wrong-target plugin artifact: fail closed before the + main function is executed. +* Plugin ABI major mismatch: `plugin.abi_mismatch`. +* Kernel digest mismatch: fail closed before spawn. +* `pure`/`strict` with extension grants: CLI preflight refusal (exit 2). +* Resource provider CLI: `UNSUPPORTED` in the current binary; the provider + implementation and framed worker are still built and self-tested here. +* Unknown platforms: `build.sh` fails explicitly; the runner records + `UNSUPPORTED`, never `PASS`. + +## 7. Known gaps observed through this suite + +Recorded in `evidence/results.json` (`known_gaps`) with exit codes and repro +commands. Summary: + +1. **Static unknown plugin export is not rejected.** + `$MARQDO_BIN check plugin/demo-missing-export.mq.md --plugin plugin/build` + exits `0`, but RFC-EXT-0001 §4.3/§4.5 and the plugin spec require a static + `symbol.unknown`; only `run` fails (exit 1). Repro recorded as case + `neg_plugin_unknown_export_check_static`. +2. **Static positional plugin arguments are not rejected.** + `check` exits `0`; `run` fails with `runtime.type: plugin calls require named + arguments`. RFC-EXT-0001 §4.5(3) forbids "static pass, runtime reject". + Repro recorded as case `neg_plugin_positional_check_static`. +3. **No `--provider` / `--allow-provider` in the frozen CLI.** + `$MARQDO_BIN run provider/demo.mq.md --provider provider/build/provider.json + --allow-provider demo.sensor` exits `2` with `unexpected argument + '--provider'`. RFC-EXT-0001 §5.2 requires these flags, so all provider CLI + cases are `UNSUPPORTED` (the provider manifest v2 + worker implementation + themselves are self-tested and pass). +4. `check --help` still says "Write the public Analysis v1 projection" although + `--emit` writes `schema_version: 2` (documentation drift only; the Analysis + v2 contract is what the tool validates). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..569ca20 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 marqdo-extension-conformance contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3fc6862 --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +# marqdo-extension-conformance + +An independent, black-box conformance repository for the **Marqdo CLI extension +surface**. It is physically separate from `marqdo-cli`: this repository contains +its own sources, its own copy of the public C ABI header, and never links a Rust +crate, a Marqdo workspace path, or a private interpreter structure. + +The suite is executed against **one frozen Marqdo CLI binary** supplied as an +absolute path through `MARQDO_BIN`. It never runs `cargo run`, `cargo build`, or +copies sources into the CLI workspace. The binary's SHA-256 is recorded before +and after the run and must be unchanged. + +The contract and exact protocol versions are in [CONTRACT.md](CONTRACT.md). +The implementation of the language itself is **not** redefined here: every +`.mq.md` file uses the single current Markdown→program mapping (RFC-LANG-0002, +`@exec`/`@knowledge` heading modes). + +## What is exercised + +| Area | Directory | Mechanism | +|---|---|---| +| External `.mq.md` package with cross-module functions, pinned Git dependency, lock/sync, offline cache | [`pure-lib/`](pure-lib), [`consumer/`](consumer) | `marqdo lock` / `sync` / `check` / `run`; git dependency pinned to a full commit SHA | +| Callable plugin, multiple exports across different prefixes, worker transport | [`plugin/`](plugin) | `plugin.yaml` + C ABI v1 artifact; `run --plugin --allow-plugin` | +| Foreign kernel with a completely unknown language tag | [`kernel/`](kernel) | `kernel.json` + standalone executable speaking the foreign JSON wire; `run --kernel --allow-foreign` | +| Resource provider v2 for an unknown kind (`demo.sensor`), framed-JSON worker protocol | [`provider/`](provider) | `provider.json` (schema v2) + C ABI provider + standalone worker; CLI `--provider/--allow-provider` support is not present in the current frozen binary (see known gaps) | +| Independent CLI tool consumer of Analysis v2 / Trace v2 | [`tool/`](tool) | `tool.json` + stdlib-only Python consumer; `tool install` then the tool's own top-level command | +| Frozen-binary and evidence integrity | [`tests/`](tests), [`evidence/`](evidence), [`scripts/`](scripts) | `verify_frozen_cli.py`, `run_all.py`, `record_evidence.py`, JSON Schema validation | + +## Quick start + +```bash +export MARQDO_BIN=/absolute/path/to/frozen/marqdo # required; never hardcoded +sha256sum "$MARQDO_BIN" # record the frozen binary + +# optional: pin the expected frozen binary digest for an evidence run +export MARQDO_EXPECTED_SHA256=<64 lowercase hex> + +python3 tests/verify_frozen_cli.py # records path + sha256 +./plugin/build.sh # cc builds the C ABI plugin fixtures +./provider/build.sh # cc builds the C ABI provider + worker +python3 tests/run_all.py # full matrix + evidence/results.json +``` + +`tests/run_all.py` rebuilds native fixtures when needed, runs the positive and +negative suites, verifies the CLI digest did not change, regenerates +`evidence/results.json`, and validates it against +`evidence/extension-evidence.schema.json`. + +Each suite can also be run alone: + +```bash +python3 tests/test_positive.py +python3 tests/test_negative.py +``` + +Exit codes: `0` when every mandatory case passes (or is honestly +`UNSUPPORTED`); `1` when a mandatory case fails. Cases marked +`known_gap: true` are real divergences from the published contract in the +current frozen binary; they are reported as `FAIL` in the matrix and evidence, +and only `--strict` makes them affect the exit code. They are documented in +[CONTRACT.md §7](CONTRACT.md#7-known-gaps-observed-through-this-suite). + +## Isolation and safety + +* A C ABI plugin is **not** a sandbox. The fixture uses the worker transport so + the native library runs in a child process, but that child still runs as the + current user. `--mode strict` is expected to refuse external execution and is + tested as a negative case. +* A foreign kernel is a child process with the host user's privileges. It is + not a sandbox either. +* The capability/authorization model is never bypassed: every effectful + extension call needs its explicit CLI grant (`--allow-plugin`, + `--allow-foreign`, `--allow-provider` once available). +* `check` is expected to be side-effect free: the plugin fixture contains a C + constructor that writes a marker file whenever the shared library is loaded, + and a test asserts the marker is absent after `check` and present after `run`. + +## Reproducibility notes + +* Native artifacts are rebuilt per machine; their SHA-256 is written into the + generated `build/` manifests and recorded in the evidence file. +* The Git dependency is **not** a floating branch: tests create a temporary + local Git repository (`git init` + commit), take the full 40-hex commit SHA, + and put `file://` URL + full `rev` into the generated consumer manifest. + Setting `MARQDO_FIXTURE_GIT_URL` / `MARQDO_FIXTURE_GIT_REV` overrides this to + demonstrate a remote URL with the same full-SHA pinning. +* `evidence/results.json` is machine-generated; never hand-edit or hand-claim a + `PASS`. + +## Known CLI gaps in the current frozen binary + +These are recorded as `FAIL` (with `known_gap: true`) or `UNSUPPORTED` in +`evidence/results.json`, with exact command, exit code, stderr and the expected +contract. See [CONTRACT.md §7](CONTRACT.md#7-known-gaps-observed-through-this-suite). + +1. `check --plugin` does not statically reject an unknown plugin export; the + document passes `check` and only fails at runtime with `symbol.unknown`. +2. `check --plugin` accepts positional plugin arguments; the runtime rejects + them with `runtime.type`. The contract requires support or a *static* + rejection. +3. The frozen CLI has no `--provider` / `--allow-provider` flags, so the + external Resource Provider cannot be activated through the normal CLI. Its + implementation (C ABI v1 + ADR-0035 framed-JSON worker) is complete and + self-tested here; the CLI cases are `UNSUPPORTED` with a precise repro. + +## License + +The test fixtures and scripts in this repository are provided under the MIT +license (see `LICENSE`). The copied public header +`include/marqdo_plugin_abi_v1.h` is the canonical frozen Marqdo Plugin ABI v1 +header and is reproduced verbatim for third-party interoperability. diff --git a/consumer/README.md b/consumer/README.md new file mode 100644 index 0000000..b6d7b03 --- /dev/null +++ b/consumer/README.md @@ -0,0 +1,23 @@ +# demo-consumer — pinned Git dependency consumer + +`index.mq.md` imports the external package `demo-pure-lib` through the explicit +front-matter alias `m: "@math"`, where `math` is the `dependencies.math` alias +from the generated `marqdo.yaml`. + +The tracked `marqdo.yaml.template` is **not** directly runnable: the test suite +substitutes: + +* `__PURE_LIB_GIT_URL__` — `file://...` URL of a temporary Git repository + created from `../pure-lib` (or `$MARQDO_FIXTURE_GIT_URL` when set); +* `__PURE_LIB_REV__` — the **full 40-hex commit SHA** of that repository. + +because a floating or short revision must be rejected. Expected output: + +```text +42 +正数 +``` + +The generated project is exercised with `marqdo lock`, `marqdo sync`, +`marqdo check`, `marqdo run`, after deleting the source Git repository (offline +cache reuse), and after relocating the whole project directory. diff --git a/consumer/index.mq.md b/consumer/index.mq.md new file mode 100644 index 0000000..aa8db6e --- /dev/null +++ b/consumer/index.mq.md @@ -0,0 +1,16 @@ +--- +import: + m: "@math" +--- + +## @exec main + +`数 = m.加倍(21)` + +`名 = m.标签(数=数)` + +> **打印(数)** + +> **打印(名)** + +`return 数` diff --git a/consumer/marqdo.yaml.template b/consumer/marqdo.yaml.template new file mode 100644 index 0000000..6d54733 --- /dev/null +++ b/consumer/marqdo.yaml.template @@ -0,0 +1,12 @@ +project: + name: demo-consumer + version: 0.1.0 + marqdo: ">=0.1,<1" +dependencies: + math: + # Full commit SHA only: a branch, tag, short SHA or floating rev must be + # rejected by marqdo. The URL is a file:// URL to a temporary Git checkout + # created by the test suite, or the remote URL set through + # MARQDO_FIXTURE_GIT_URL (whose repository root must itself be this package). + git: "__PURE_LIB_GIT_URL__" + rev: "__PURE_LIB_REV__" diff --git a/include/marqdo_plugin_abi_v1.h b/include/marqdo_plugin_abi_v1.h new file mode 100644 index 0000000..24f73fe --- /dev/null +++ b/include/marqdo_plugin_abi_v1.h @@ -0,0 +1,472 @@ +/* + * Marqdo plugin C ABI, generation v1. + * ===================================================================== + * + * This header is the canonical, frozen description of the Marqdo native + * plugin ABI v1. It is an independent ABI generation: it is *not* the old + * `marqdo_abi.h` v2 interface and is neither source- nor binary-compatible + * with it. Only an explicit, separately tested adapter may ever bridge the + * two. + * + * This file defines stable-layout C types only: + * + * - fixed-width integers (`int32_t`, `uint32_t`) and `size_t`, + * - byte buffers represented as length + pointer (`MqBytes` / + * `MqOwnedBytes`), + * - opaque, host-owned handles (`MqCallContext`), + * - `extern "C"` function pointers. + * + * The following must NEVER cross this boundary: + * + * - Rust `String` / `Vec` / `Result` / trait objects / panics, + * - C++ exceptions, Go runtime objects or garbage-collected pointers, + * - raw pointers to host-internal structures (other than the opaque + * `MqCallContext *` minted for one invocation), + * - real filesystem handles, sockets, keys or OS resources; capabilities + * are requested symbolically through `MqHostApi::request_capability`. + * + * A C ABI IS NOT A SANDBOX + * ------------------------ + * Native plugins are loaded into the host process. They are not isolated: + * a plugin can read host memory, call arbitrary syscalls, crash the process + * or corrupt the host. In-process native loading therefore requires an + * explicit user trust decision. Untrusted third-party plugins must run in an + * isolated worker process (same logical plugin API, length-prefixed IPC + * transport) or a Wasm component. Do not present this ABI as a security + * boundary. + * + * VERSIONS + * -------- + * Three independent versions exist and must never be conflated: + * + * 1. Marqdo language / syntax / semantics version, + * 2. plugin ABI major.minor (this header, `MQ_ABI_MAJOR`/`MQ_ABI_MINOR`), + * 3. plugin package SemVer (declared in `plugin.yaml`). + * + * This header is ABI major 1, minor 0. + * + * TARGET AND WORD SIZE + * -------------------- + * The layout below uses `size_t`, so it depends on the target triple and the + * pointer width. A plugin artifact is only loadable by a host built for the + * same target triple and the same pointer width (32-bit and 64-bit objects + * are never interchangeable). All struct fields use native endianness; + * host and plugin must share the target byte order. The JSON wire payloads + * are UTF-8 and endian-neutral. + * + * LAYOUT EXPECTATIONS (little/big-endian, size_t == 8 bytes) + * --------------------------------------------------------- + * sizeof(MqBytes) == 16, alignof == 8 + * sizeof(MqOwnedBytes) == 16, alignof == 8 + * sizeof(MqPluginApi) == 32, alignof == 8 + * sizeof(MqHostApi) == 56, alignof == 8 + * sizeof(MqPluginInvoke) == 8 + * The same expectations are asserted in `crates/marqdo-plugin-abi`. + * + * BUFFER OWNERSHIP AND LIFETIMES + * ------------------------------ + * There are three distinct kinds of byte buffer: + * + * (a) Host-owned input buffers (`args_wire`, capability `request_wire`, + * `export_name`, `signature_wire`, `plugin_metadata_wire` as watched by + * the host). The producer of the pointer keeps it valid only for the + * duration of the call in which it is passed. The consumer MUST NOT + * retain the pointer, MUST NOT free it and MUST copy any data it needs + * to keep. In particular the host copies plugin metadata, export names + * and signatures during the entry/registration call. + * + * (b) Host-allocated output buffers. The host owns `alloc`/`free`. A plugin + * that produces `MqOwnedBytes` output (`result_wire`, `error_wire`, + * capability `reply_wire`) MUST allocate the memory with + * `host->alloc(host->host_data, size)` and write the payload there. The + * consuming side (host for invoke results/errors, plugin for capability + * replies) copies what it needs and then releases the buffer with + * `host->free(host->host_data, data)`. The producer MUST NOT free the + * buffer itself and MUST NOT use `malloc`/`new`/GC memory for it. + * + * (c) Plugin-owned static metadata. During `mq_plugin_entry_v1` the plugin + * passes `plugin_metadata_wire` pointing at storage it owns (typically a + * static string). It only has to remain valid for the duration of the + * entry call; the host copies it. + * + * Zero-length semantics: a buffer with `len == 0` must have `data == NULL` + * (hosts and plugins must treat `{NULL, 0}` as the empty buffer). A buffer + * with `len > 0` must have a non-NULL `data`. Violations are protocol errors + * (`MQ_ERR_INVALID_ARGUMENT` / `MQ_ERR_BAD_WIRE`), never silent. + * + * SIZE LIMITS (enforced by the host; plugins should fail fast) + * ----------------------------------------------------------- + * MQ_MAX_EXPORT_NAME_BYTES 256 + * MQ_MAX_SIGNATURE_WIRE_BYTES 4096 + * MQ_MAX_METADATA_WIRE_BYTES 65536 + * MQ_MAX_REQUEST_WIRE_BYTES 8384512 (8 MiB - 4096) + * MQ_MAX_RESULT_WIRE_BYTES 8384512 (8 MiB - 4096) + * MQ_MAX_ERROR_WIRE_BYTES 1048576 (1 MiB) + * MQ_MAX_CAPABILITY_REPLY_BYTES 8384512 (8 MiB - 4096) + * JSON depth is additionally limited to 64 levels. Requests/results that + * exceed these limits are rejected with a structured error; they must not + * be truncated and reparsed. + * + * ERROR FIELD BEHAVIOUR + * --------------------- + * `mq_plugin_entry_v1` returns `MQ_OK` (0) on success, a non-zero + * `MQ_ERR_*` code on failure. On a non-zero return the host MUST NOT read + * `plugin_metadata_wire`, `plugin_api.abi_*` or any registered callback. + * + * `MqPluginInvoke` returns `MQ_OK` (0) on success and a non-zero code on + * failure: + * - on success, `*result_wire` holds exactly one UTF-8 JSON response + * envelope (see `spec/value-wire.md` / wire_version 1) and + * `*error_wire` MUST be `{NULL, 0}`; + * - on failure, `*error_wire` holds a UTF-8 JSON error envelope + * (`{ "wire_version": 1, "kind": "response", "error": {...} }`) and + * `*result_wire` MUST be `{NULL, 0}`. The host treats a missing error + * envelope as an unstructured plugin failure and still fails the call. + * Both output pointers MUST be non-NULL as provided by the host; writing + * through a NULL output pointer is a caller/plugin contract violation. + * + * OOM / NULL ALLOCATION: `host->alloc` returns NULL on failure (and for + * `size == 0`). A plugin that cannot allocate must return + * `MQ_ERR_OUT_OF_MEMORY` and must not write partial output buffers. + * + * THREAD MODEL + * ------------ + * v1 is deliberately single-threaded and synchronous: + * - `mq_plugin_entry_v1` is called exactly once, by the loading thread; + * - every `MqPluginInvoke` and every host callback for a given loaded + * plugin instance runs on that same thread; + * - at most one invocation is in flight per instance; the host serializes + * calls. A plugin must not start its own threads that call back into + * `MqHostApi`, and must not invoke the host from a signal handler; + * - there is no async/parallel callback contract in v1. `MqCallContext` + * is valid only for the duration of the invocation it was minted for, + * must not be cached, and must not be used after the call returns. + * + * UNLOADING / SHUTDOWN + * -------------------- + * v1 does not support hot-unload or reload of a loaded native library. + * A plugin lives for the lifetime of the process (or of the trusted loading + * scope); there is no `shutdown` callback in v1. Hosts must not unload a + * library while a call is in flight, and must keep all registered function + * pointers reachable until shutdown. Plugins must tolerate never being + * unloaded. + * + * VERSION NEGOTIATION + * ------------------- + * The host fills `MqPluginApi::struct_size` with sizeof(MqPluginApi) before + * the entry call and zeroes the remaining fields; the plugin fills in + * `abi_major`, `abi_minor` and `plugin_metadata_wire`. The host then: + * - rejects the load if `plugin->abi_major != MQ_ABI_MAJOR` (major is + * never negotiated); + * - accepts a plugin minor greater than its own, but clamps to the host's + * supported minor and only uses features defined at that minor. + * The plugin mirrors the check against the host table: + * - reject if `host == NULL`, `plugin == NULL`, + * `host->struct_size < sizeof(MqHostApi)` (the exact size of the v1.0 + * table it was built against) or `host->abi_major != MQ_ABI_MAJOR`. + * `struct_size` is the extension mechanism: a consumer must only read a + * field when `struct_size >= offsetof(field) + sizeof(field)`; a producer + * sets `struct_size = sizeof(its struct)` and may append new fields only in + * a later ABI minor while never reordering or resizing earlier fields. + * Fields appended in a later minor are ABSENT (not usable) when the + * negotiated minor is lower. + * + * EXCEPTIONS, PANICS, UNDEFINED BEHAVIOUR + * --------------------------------------- + * No panic, exception, longjmp or unwinding of any kind may cross the ABI + * boundary. Rust plugins should call `extern "C"` entry points from + * panic-aborting builds or catch panics inside the SDK; C++ plugins must + * catch all exceptions inside their invocation function. The host treats a + * process crash as a host process crash: this ABI cannot contain it. + * + * WIRE FORMAT + * ----------- + * All payloads are UTF-8 JSON, `wire_version == 1`. See the canonical + * `spec/value-wire.md` (type-tagged values: every value is an object with a + * `type` tag; 64-bit-and-beyond integers use decimal strings; NaN/Infinity + * use explicit tags). Names: + * - request : {"wire_version":1,"kind":"request","function":..., + * "args":{...},"context":{...}} + * - response : {"wire_version":1,"kind":"response","value":{...}} + * - error : {"wire_version":1,"kind":"response","error": + * {"kind":"...","code":"...","message":"...",...}} + * `export_name` and capability `name` are UTF-8 byte strings (not JSON). + * `signature_wire` is the JSON object {"signature":""}. + * `plugin_metadata_wire` is the JSON object + * {"name":"","version":""} (extra fields ignored). + */ + +#ifndef MARQDO_PLUGIN_ABI_V1_H +#define MARQDO_PLUGIN_ABI_V1_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* ------------------------------------------------------------------ */ +/* Version and result codes */ +/* ------------------------------------------------------------------ */ + +/** Plugin ABI major version. Major mismatches always fail the load. */ +#define MQ_ABI_MAJOR 1u +/** Plugin ABI minor version implemented by this header. */ +#define MQ_ABI_MINOR 0u +/** Human-readable ABI version of this header. */ +#define MQ_ABI_VERSION_STRING "1.0" +/** Required exported symbol name. */ +#define MQ_PLUGIN_ENTRY_SYMBOL "mq_plugin_entry_v1" + +/** Success. */ +#define MQ_OK 0 +/** Malformed argument (NULL pointer, bad pointer/length pair, ...). */ +#define MQ_ERR_INVALID_ARGUMENT 1 +/** ABI major mismatch or incompatible struct_size. */ +#define MQ_ERR_ABI_MISMATCH 2 +/** A required export could not be registered. */ +#define MQ_ERR_REGISTRATION 3 +/** Operation/type/capability not supported by this version. */ +#define MQ_ERR_UNSUPPORTED 4 +/** Host allocation failed. */ +#define MQ_ERR_OUT_OF_MEMORY 5 +/** Payload is not valid wire_version 1 JSON. */ +#define MQ_ERR_BAD_WIRE 6 +/** Unexpected internal plugin failure (including caught panics). */ +#define MQ_ERR_INTERNAL 7 +/** Capability request failed or was denied by the host. */ +#define MQ_ERR_CAPABILITY 8 + +/* ------------------------------------------------------------------ */ +/* Size limits */ +/* ------------------------------------------------------------------ */ + +#define MQ_MAX_EXPORT_NAME_BYTES 256u +#define MQ_MAX_SIGNATURE_WIRE_BYTES 4096u +#define MQ_MAX_METADATA_WIRE_BYTES 65536u +#define MQ_MAX_REQUEST_WIRE_BYTES ((8u * 1024u * 1024u) - 4096u) +#define MQ_MAX_RESULT_WIRE_BYTES ((8u * 1024u * 1024u) - 4096u) +#define MQ_MAX_ERROR_WIRE_BYTES (1024u * 1024u) +#define MQ_MAX_CAPABILITY_REPLY_BYTES ((8u * 1024u * 1024u) - 4096u) + +/* ------------------------------------------------------------------ */ +/* Stable-layout buffer types */ +/* ------------------------------------------------------------------ */ + +/** + * Borrowed, immutable byte view. + * + * Ownership stays with the producer; the pointer is valid only for the + * duration of the call that received it. `{NULL, 0}` is the empty buffer. + * A non-NULL `data` with `len == 0` is tolerated by neither side. + */ +typedef struct { + const uint8_t *data; + size_t len; +} MqBytes; + +/** + * Mutable byte buffer ownership transfer. + * + * The producer allocates with `MqHostApi::alloc` and passes ownership to the + * consumer, which copies the bytes and then calls `MqHostApi::free` on + * `data`. `{NULL, 0}` is the empty buffer. A buffer left non-empty when the + * call returns is owned by the documented consumer; it is never freed by + * the producer. + */ +typedef struct { + uint8_t *data; + size_t len; +} MqOwnedBytes; + +/** + * Opaque, host-owned invocation context. + * + * The plugin only ever receives a pointer to this type and must pass the + * same pointer back to `request_capability`. Its layout is private to the + * host and may change between ABI minors without notice. It is valid only + * during the invocation it was minted for and must not be cached, copied or + * inspected. Never dereference this pointer from a plugin. + */ +typedef struct MqCallContext MqCallContext; + +/* ------------------------------------------------------------------ */ +/* Function pointer types */ +/* ------------------------------------------------------------------ */ + +/** + * Plugin invocation callback, registered once per export. + * + * Contract: see the ERROR FIELD BEHAVIOUR section above. The callback runs + * on the host invocation thread, with at most one call in flight per plugin + * instance. It must be reentrant-safe with respect to its own state because + * repeated invocations may occur sequentially. It must not panic/throw. + * + * @param ctx Opaque host context for this call (may be NULL only + * if the host could not mint one; then the plugin should + * fail with MQ_ERR_INVALID_ARGUMENT). + * @param args_wire Borrowed UTF-8 JSON request envelope. + * @param result_wire Host-provided out-parameter; on success must be + * filled with a host-allocated UTF-8 JSON response + * envelope. Must not be NULL. + * @param error_wire Host-provided out-parameter; on failure must be filled + * with a host-allocated UTF-8 JSON error envelope. Must + * not be NULL. + * @return MQ_OK on success, a non-zero MQ_ERR_* code otherwise. + */ +typedef int32_t (*MqPluginInvoke)( + MqCallContext *ctx, + MqBytes args_wire, + MqOwnedBytes *result_wire, + MqOwnedBytes *error_wire +); + +/* ------------------------------------------------------------------ */ +/* Host API table */ +/* ------------------------------------------------------------------ */ + +/** + * Host-provided function table, valid for the whole life of the plugin + * instance. All function pointers are non-NULL in ABI v1.0. + * + * `host_data` is an opaque host-owned pointer that must be passed back to + * every function that takes it. Plugins must not interpret it. + */ +typedef struct { + /** + * sizeof(MqHostApi) as seen by the host. Consumers must check this + * against their own required size before reading any field (see VERSION + * NEGOTIATION). Producers never shrink the table; fields are only + * appended and never reordered. + */ + uint32_t struct_size; + /** Host-supported ABI major (must be MQ_ABI_MAJOR). */ + uint32_t abi_major; + /** Host-supported ABI minor (features above this are unavailable). */ + uint32_t abi_minor; + /** Opaque host state; pass back to every callback that accepts it. */ + void *host_data; + + /** + * Host allocator. Returns NULL on failure and for `size == 0`. + * The returned memory is at least `size` bytes and suitably aligned for + * byte buffers. The matching `free` must be used; never free with + * malloc/new/free() from the plugin runtime. + */ + void *(*alloc)(void *host_data, size_t size); + + /** + * Host deallocator; must be called exactly once for a pointer returned by + * `alloc` (including capability replies allocated by the host). Passing + * NULL is a no-op. + */ + void (*free)(void *host_data, void *ptr); + + /** + * Register one plugin export during `mq_plugin_entry_v1`. + * + * `export_name` is a UTF-8 dotted name, already namespaced by the + * manifest validation (e.g. "solver.add"). `signature_wire` is UTF-8 + * JSON: {"signature":"(...)"}. Name and signature are copied by the + * host during this call. Returns MQ_OK or a non-zero MQ_ERR_* code; on + * failure the export must be considered not registered. + * + * Export names must not shadow Marqdo built-ins and must match the + * manifest exports exactly. + */ + int32_t (*register_function)( + void *host_data, + MqBytes export_name, + MqBytes signature_wire, + MqPluginInvoke invoke + ); + + /** + * Request a whitelisted capability from the host for the current call. + * + * `name` is a UTF-8 capability name (e.g. "math.compute", "fs.read", + * "clock"). `request_wire` is a UTF-8 JSON capability request whose shape + * is defined per capability. On success the host allocates + * `reply_wire` (with `alloc`) and the plugin must copy and then free it + * with `free`. On failure `reply_wire` is `{NULL, 0}` and the call + * returns a non-zero code. + * + * Capabilities are granted structurally by the host's authorization + * layer before the plugin is loaded; this function only consumes a grant + * and can never escalate privileges. `ctx` must be the context of the + * current invocation only. + */ + int32_t (*request_capability)( + MqCallContext *ctx, + MqBytes name, + MqBytes request_wire, + MqOwnedBytes *reply_wire + ); +} MqHostApi; + +/* ------------------------------------------------------------------ */ +/* Plugin API table (host-filled, plugin-filled) */ +/* ------------------------------------------------------------------ */ + +/** + * Plugin-side version/metadata table. + * + * The host initializes `struct_size` to sizeof(MqPluginApi) and zeroes the + * rest before calling the entry point. The plugin must set `abi_major`, + * `abi_minor` and `plugin_metadata_wire` and must not change + * `struct_size` (it may only be larger in a future ABI minor; consumers + * check it). + */ +typedef struct { + /** sizeof(MqPluginApi) as initialized by the host. */ + uint32_t struct_size; + /** Plugin ABI major; must equal MQ_ABI_MAJOR for the load to proceed. */ + uint32_t abi_major; + /** Plugin ABI minor; the host clamps and negotiates down as needed. */ + uint32_t abi_minor; + /** + * Plugin metadata JSON, plugin-owned static storage, valid only for the + * duration of the entry call. Format: + * {"name":"","version":""} + * The host copies it during the call. Must be a non-empty, valid UTF-8 + * JSON object. + */ + MqBytes plugin_metadata_wire; +} MqPluginApi; + +/** + * Required exported entry point. Exactly one per plugin artifact. + * + * @param host Host API table, host-owned, valid for the plugin lifetime. + * Must be non-NULL. + * @param plugin Plugin API table, host-provided. The plugin must fill it in + * and may not retain it. Must be non-NULL. + * @return MQ_OK on success, a non-zero MQ_ERR_* code on failure. + * + * The host calls this exactly once on the loading thread. The plugin + * registers every export through `host->register_function` during this call + * and must return MQ_OK only after all exports are registered successfully. + */ +typedef int32_t (*MqPluginEntryV1)(const MqHostApi *host, MqPluginApi *plugin); + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +/* + * Compile-time layout checks for the canonical 64-bit target. On other word + * sizes the expected sizes are smaller (every pointer/size_t shrinks by 4 + * bytes); the Rust side asserts the corresponding architecture-specific + * values. + */ +#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L +#if defined(__LP64__) || defined(_LP64) +_Static_assert(sizeof(MqBytes) == 16, "MqBytes layout must stay 16 bytes on 64-bit"); +_Static_assert(sizeof(MqOwnedBytes) == 16, "MqOwnedBytes layout must stay 16 bytes on 64-bit"); +_Static_assert(sizeof(MqPluginApi) == 32, "MqPluginApi layout must stay 32 bytes on 64-bit"); +_Static_assert(sizeof(MqHostApi) == 56, "MqHostApi layout must stay 56 bytes on 64-bit"); +#endif +#endif + +#endif /* MARQDO_PLUGIN_ABI_V1_H */ diff --git a/kernel/README.md b/kernel/README.md new file mode 100644 index 0000000..004851d --- /dev/null +++ b/kernel/README.md @@ -0,0 +1,27 @@ +# kernel/ — unknown-language Foreign Kernel + +`mocklang` is **not** a built-in Marqdo language. `kernel.json` registers it at +run time through the existing external-kernel registry: + +```bash +MARQDO_BIN=/abs/path/to/frozen/marqdo +"$MARQDO_BIN" run kernel/demo.mq.md \ + --kernel kernel/kernel.json \ + --allow-foreign +``` + +It implements `spec/foreign.md` v1: + +* argv[1] is a path to the inert `Code` resource taken from `ref("#内核程序")`; +* stdin receives one `{"wire_version":1,"kind":"request","input":...}` envelope; +* stdout receives exactly one type-tagged Value Wire v1 value for + `foreign.call`. + +The descriptor pins the provider executable by SHA-256. `kernel.json.digest` +is the SHA-256 of `mocklang`; `tests/test_positive.py` asserts the pin and +`python3 scripts/refresh_kernel_digest.py` refreshes it after an edit. The +suite also proves the digest is enforced by tampering with a copy. + +The `demo.mq.md` file also shows that the code fence is **inert**: `check` +succeeds without any kernel registered, and only the explicit `foreign.call` +starts the process. diff --git a/kernel/demo.mq.md b/kernel/demo.mq.md new file mode 100644 index 0000000..0adda12 --- /dev/null +++ b/kernel/demo.mq.md @@ -0,0 +1,17 @@ +# @knowledge mocklang 外部内核演示 + +## @knowledge 内核程序 + +```mocklang +// Inert code resource. It is read as a Code value and only executed through an +// explicit foreign.call; a code fence never starts a process by itself. +answer = 42 +``` + +## @exec main + +`结果 = foreign.call(ref("#内核程序"), {})` + +> **打印(结果)** + +`return 结果` diff --git a/kernel/kernel.json b/kernel/kernel.json new file mode 100644 index 0000000..f70a6a3 --- /dev/null +++ b/kernel/kernel.json @@ -0,0 +1,12 @@ +{ + "provider_id": "mocklang", + "languages": [ + "mocklang", + "mock" + ], + "wire_version": 1, + "entrypoint": "./mocklang", + "permissions_requested": [], + "digest": "fc190c3d61de682597003bdd8bbef3429a89da8c1d7c2b6474bbbd3b93c3aa09", + "environment_id": "mocklang-python3-v1" +} diff --git a/kernel/mocklang b/kernel/mocklang new file mode 100755 index 0000000..91f7dc1 --- /dev/null +++ b/kernel/mocklang @@ -0,0 +1,50 @@ +#!/usr/bin/env python3 +"""Unknown-language foreign kernel for the Marqdo foreign JSON wire (v1). + +The Marqdo host writes the inert code resource to a temporary file and passes +its path as argv[1]; stdin receives exactly one JSON envelope: + + {"wire_version": 1, "kind": "request", "input": } + +For foreign.call, stdout must contain exactly one type-tagged wire value +(spec/value-wire.md). This provider is intentionally not a built-in language: +`mocklang` is unknown to the Marqdo CLI and is registered only through +kernel.json at run time. +""" +import hashlib +import json +import sys + + +def main() -> int: + source_path = sys.argv[1] if len(sys.argv) > 1 else "" + try: + envelope = json.load(sys.stdin) + except json.JSONDecodeError as error: # pragma: no cover - protocol failure + print(f"mocklang: invalid request envelope: {error}", file=sys.stderr) + return 1 + if envelope.get("wire_version") != 1 or envelope.get("kind") != "request": + print("mocklang: expected wire_version 1 request envelope", file=sys.stderr) + return 1 + try: + with open(source_path, "rb") as source_file: + source = source_file.read() + except OSError as error: # pragma: no cover - protocol failure + print(f"mocklang: cannot read code resource: {error}", file=sys.stderr) + return 1 + input_value = envelope.get("input") + result = { + "type": "map", + "entries": { + "engine": {"type": "text", "value": "mocklang"}, + "answer": {"type": "int", "decimal": "42"}, + "source_digest": {"type": "text", "value": hashlib.sha256(source).hexdigest()}, + "input_kind": {"type": "text", "value": "null" if input_value is None else "typed"}, + }, + } + sys.stdout.write(json.dumps(result, ensure_ascii=False)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/pure-lib/README.md b/pure-lib/README.md new file mode 100644 index 0000000..da57143 --- /dev/null +++ b/pure-lib/README.md @@ -0,0 +1,20 @@ +# demo-pure-lib — external `.mq.md` package + +A standalone Marqdo package with three modules and cross-module calls: + +``` +index.mq.md ──import──> arithmetic.mq.md ──import──> base.mq.md + └───────import──> labels.mq.md +``` + +Exports (H2 `@exec` functions in the package root module, callable by the +consumer through its dependency alias): + +* `加倍(x: Int) -> Int` — calls `arith.加倍`, which calls `base.add`. +* `标签(数: Int) -> Text` — calls `labels.标签`, which branches on `数 > 0`. + +No resource access, no plugin, no foreign kernel: this is the "pure library" +leg of the conformance suite. `tests/test_positive.py` commits **this directory** +into a temporary Git repository, pins the full commit SHA in a generated +consumer manifest, and then exercises `marqdo lock`, `sync`, `check`, `run`, +offline cache reuse and project relocation. diff --git a/pure-lib/arithmetic.mq.md b/pure-lib/arithmetic.mq.md new file mode 100644 index 0000000..955a85b --- /dev/null +++ b/pure-lib/arithmetic.mq.md @@ -0,0 +1,10 @@ +--- +import: + base: "./base.mq.md" +--- + +## @exec 加倍 + +`params(x: Int)` + +`return base.add(a=x, b=x)` diff --git a/pure-lib/base.mq.md b/pure-lib/base.mq.md new file mode 100644 index 0000000..18f1ec7 --- /dev/null +++ b/pure-lib/base.mq.md @@ -0,0 +1,5 @@ +## @exec add + +`params(a: Int, b: Int)` + +`return a + b` diff --git a/pure-lib/index.mq.md b/pure-lib/index.mq.md new file mode 100644 index 0000000..88c1b74 --- /dev/null +++ b/pure-lib/index.mq.md @@ -0,0 +1,17 @@ +--- +import: + arith: "./arithmetic.mq.md" + labels: "./labels.mq.md" +--- + +## @exec 加倍 + +`params(x: Int)` + +`return arith.加倍(x)` + +## @exec 标签 + +`params(数: Int)` + +`return labels.标签(数=数)` diff --git a/pure-lib/labels.mq.md b/pure-lib/labels.mq.md new file mode 100644 index 0000000..b432121 --- /dev/null +++ b/pure-lib/labels.mq.md @@ -0,0 +1,13 @@ +## @exec 标签 + +`params(数: Int)` + +`if 数 > 0` + +`return "正数"` + +`else` + +`return "非正数"` + +`end` diff --git a/pure-lib/marqdo.yaml b/pure-lib/marqdo.yaml new file mode 100644 index 0000000..082d789 --- /dev/null +++ b/pure-lib/marqdo.yaml @@ -0,0 +1,4 @@ +project: + name: demo-pure-lib + version: 0.1.0 + marqdo: ">=0.1,<1" diff --git a/scripts/refresh_kernel_digest.py b/scripts/refresh_kernel_digest.py new file mode 100755 index 0000000..e0a6d8f --- /dev/null +++ b/scripts/refresh_kernel_digest.py @@ -0,0 +1,28 @@ +#!/usr/bin/env python3 +"""Refresh the SHA-256 pin in kernel/kernel.json from kernel/mocklang. + +This script is for fixture maintainers only. Tests never rewrite the fixture; +they read the committed digest and fail if it no longer matches. +""" +import hashlib +import json +import pathlib +import sys + +ROOT = pathlib.Path(__file__).resolve().parent.parent +KERNEL = ROOT / "kernel" + + +def main() -> int: + mocklang = KERNEL / "mocklang" + descriptor = KERNEL / "kernel.json" + digest = hashlib.sha256(mocklang.read_bytes()).hexdigest() + data = json.loads(descriptor.read_text(encoding="utf-8")) + data["digest"] = digest + descriptor.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") + print(f"kernel.json digest = {digest} ({mocklang.name})") + return 0 + + +if __name__ == "__main__": + sys.exit(main())