docs(release): reconcile status, compatibility and release evidence

- adopt docs/STABLE_RELEASE_IMPLEMENTATION.md as the single next-phase plan
- archive the stale M0.5 status snapshot under docs/history/
- record real local gate results, the red baseline CI, the Windows autocrlf
  reproduction and the unresolved macOS/native-CI status
- add COMPATIBILITY.md (protocol versions + honest platform matrix),
  CHANGELOG.md, dual license files, docs/releasing.md and docs/security-gate.md
- keep strict fail-closed: document the container EPERM/read-only cgroup probe
  and the exact G-C requirements instead of claiming isolation
- document foreign environment binding (ADR-0020) and add a release-candidate
  CI job that is gated on all platform jobs
This commit is contained in:
cflmy committed 2026-11-20 13:58:40 +08:00
1 parent faa6c95cfe
commit 18d9f39562
14 files changed
+2358 -482

No files matched your search

+62
View File
@@ -3,6 +3,7 @@ name: CI
on: on:
push: push:
pull_request: pull_request:
workflow_dispatch:
env: env:
CARGO_TERM_COLOR: always CARGO_TERM_COLOR: always
@@ -107,6 +108,13 @@ jobs:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable - uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2 - uses: Swatinem/rust-cache@v2
- name: Host toolchain report
shell: bash
run: |
rustc -vV
(command -v cc && cc --version | head -1) || echo "cc: unavailable"
(command -v python3 && python3 --version) || echo "python3: unavailable"
(command -v node && node --version) || echo "node: unavailable"
- name: Workspace tests - name: Workspace tests
run: cargo test --workspace run: cargo test --workspace
- name: Portable CLI, analysis and trace smoke - name: Portable CLI, analysis and trace smoke
@@ -130,3 +138,57 @@ jobs:
test "$code" -eq 1 test "$code" -eq 1
echo "$output" | grep -qi "strict" echo "$output" | grep -qi "strict"
echo "$output" echo "$output"
release-candidate:
name: release candidate artifact (${{ matrix.os }})
needs: [test, schema, cross-platform]
if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
strategy:
fail-fast: false
matrix:
include:
- os: ubuntu-latest
target: x86_64-unknown-linux-gnu
- os: macos-latest
target: aarch64-apple-darwin
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- name: Build release binary
run: cargo build --release --locked -p marqdo-cli
- name: Package and checksum
shell: bash
run: |
set -euo pipefail
version="$(cargo metadata --no-deps --format-version 1 | python3 -c 'import json,sys; print(json.load(sys.stdin)["packages"][0]["version"])')"
stage="dist/marqdo-${version}-${{ matrix.target }}"
mkdir -p "$stage"
install -m 0755 target/release/marqdo "$stage/"
cp LICENSE-MIT LICENSE-APACHE CHANGELOG.md COMPATIBILITY.md README.md "$stage/"
cp -r spec examples "$stage/"
tar -C dist -czf "dist/marqdo-${version}-${{ matrix.target }}.tar.gz" "$(basename "$stage")"
cd dist
if command -v sha256sum >/dev/null 2>&1; then
sha256sum "marqdo-${version}-${{ matrix.target }}.tar.gz" > "marqdo-${version}-${{ matrix.target }}.tar.gz.sha256"
else
shasum -a 256 "marqdo-${version}-${{ matrix.target }}.tar.gz" > "marqdo-${version}-${{ matrix.target }}.tar.gz.sha256"
fi
cat "marqdo-${version}-${{ matrix.target }}.tar.gz.sha256"
- name: Clean-install smoke
shell: bash
run: |
set -euo pipefail
tmp="$(mktemp -d)"
tar -C "$tmp" -xzf dist/marqdo-*.tar.gz
cd "$tmp"/marqdo-*
./marqdo --version
./marqdo --help >/dev/null
./marqdo check examples/multi-module/index.mq.md
./marqdo run examples/hello.mq.md
- uses: actions/upload-artifact@v4
with:
name: marqdo-${{ matrix.target }}
path: dist/marqdo-*.tar.gz*
if-no-files-found: error
+3
View File
@@ -14,3 +14,6 @@ examples/plugin-multi-export/solver.so
# Generated plugin fixture manifests/artifacts # Generated plugin fixture manifests/artifacts
examples/plugin-demo/build/ examples/plugin-demo/build/
examples/plugin-multi-export/build/ examples/plugin-multi-export/build/
# Release artifacts
dist/
+14 -1
View File
@@ -2,7 +2,20 @@
**Start here:** read `docs/DEVELOPMENT_BLUEPRINT.md` before proposing code. It is the project architecture baseline. Then read `docs/STATUS.md` (what is actually implemented), the relevant `spec/` files, `docs/adr/` for frozen decisions, `docs/contributor-guide.md` for the workflow, and `tests/README.md` plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative. **Start here:** read `docs/DEVELOPMENT_BLUEPRINT.md` before proposing code. It is the project architecture baseline. Then read `docs/STATUS.md` (what is actually implemented), the relevant `spec/` files, `docs/adr/` for frozen decisions, `docs/contributor-guide.md` for the workflow, and `tests/README.md` plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative.
For next-phase work, also read `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` (current stabilization spec, baseline `0adebe4`, defining gaps B-01–B-18 and the G-A/G-B/G-C gates), `docs/NEXT_PHASE_IMPLEMENTATION.md` (M0.6 plan) and `docs/EXTENSIBILITY_AUDIT.md` (source-backed issues E01–E16). All are **Proposed** design input: the newer stabilization spec supersedes the earlier plans on the current baseline, gap list and release gates, while the M0.6 plan supersedes the blueprint on command-surface scope, extension registration, plugin addressing, package identity, repository decoupling and release gates. None describes implemented behavior, and each must be re-checked against current HEAD. `spec/tool-v1.md` is likewise a candidate protocol until an Accepted ADR and tests land. For next-phase work, the single authoritative plan is
`docs/STABLE_RELEASE_IMPLEMENTATION.md` (stable-release gates G-A/G-B/G-C,
PR order and release checklist). Also read `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`
(historical stabilization spec, baseline `0adebe4`), `docs/NEXT_PHASE_IMPLEMENTATION.md`
(M0.6 plan), `docs/EXTENSIBILITY_AUDIT.md` (E01–E16), `COMPATIBILITY.md` and
`docs/security-gate.md`. The older plans are historical input: the stable-release
spec supersedes them on current baseline, gap list, PR order and release gates.
None describes implemented behavior; re-check against HEAD and tests. `strict`
remains fail-closed until G-C passes.
The stable-release spec also governs scope: do not add a top-level CLI command,
Knowledge/Proof/View special-casing, a second interpreter or a new package
registry. Fix the current Windows/macOS CI behavior, protocol/environment
correctness and release evidence before expanding the surface.
## Non-negotiable architectural constraints ## Non-negotiable architectural constraints
+61
View File
@@ -0,0 +1,61 @@
# Changelog
All notable changes to the Marqdo CLI workspace. The workspace version is
currently `0.1.0`; no release tag has been cut. Dates use ISO 8601.
## Unreleased (stabilization candidate)
### Added
- `.gitattributes` byte-identity policy: canonical LF for text files and one
explicit CRLF byte fixture for Markdown line-ending semantics.
- Byte-level AST golden diagnostics: first differing byte, byte windows and an
explicit "only line endings differ" classification.
- Cross-platform Native ABI test fixtures generated for the host target, plus
`no_matching_artifact`, artifact-tamper and ABI-major-mismatch negative tests.
- Host-specific example plugin builds under `examples/plugin-*/build/`; the
tracked manifests are never rewritten by tests or CI.
- Foreign pinned-environment binding (ADR-0020): an external provider's
`entrypoint` must resolve inside `environment_dir`, built-in providers cannot
be bound to one, the child gets only the environment executable directory on
`PATH`, and `interpreter_version` is verified before execution.
- Release documentation (`COMPATIBILITY.md`, `docs/releasing.md`) and the
Linux security-gate evidence report (`docs/security-gate.md`).
### Changed
- `docs/STABLE_RELEASE_IMPLEMENTATION.md` is the single next-phase
implementation plan. Older plan documents are historical input, not current
status.
- AST conformance tests fail early when a golden contains CR bytes instead of
reporting an opaque mismatch.
- Worker plugin fixtures use the platform dynamic-library name and compiler
flags.
### Fixed
- Windows CI AST golden failure caused by CRLF checkout of canonical JSON
goldens (reproduced with a fresh `core.autocrlf=true` clone).
- macOS CI plugin failure caused by assuming a Linux `.so` and Linux-only
manifest target.
### Security
- `strict` remains `Unavailable` on every platform. This host cannot create
user/network namespaces (`EPERM` inside a container, cgroup2 read-only, no
non-interactive sudo), so no Linux OS-isolation adapter was implemented or
verified. There is no silent downgrade to `project` mode.
- Capability brokers and worker processes remain cooperative
authorization/crash isolation, not an OS sandbox.
## Baseline `0.1.0` (before this stabilization slice)
- Markdown profile `marqdo.md.v1` with 150 AST goldens.
- Native Rust interpreter, analysis and execution conformance corpus.
- lock v3 package-instance graph with full transitive closure, verified Git
cache and atomic `.marqdo/env` materialization (ADR-0016).
- Analysis v2 and Trace v2 with independent Python consumers and JSON Schemas.
- Tool Protocol v1 with SemVer/protocol negotiation and whole-bundle digests.
- Plugin ABI v1 native and worker transports with a brokered `fs.read`
capability path (ADR-0018).
- Pinned Foreign provider/environment digests and one-shot Python/Node kernels.
+61
View File
@@ -0,0 +1,61 @@
# Compatibility and support matrix
Snapshot: workspace version **0.1.0**, no release tag cut. This file records
what was actually verified and separates it from what is only implemented.
## Public protocol versions
| Surface | Version | Compatibility rule |
|---|---|---|
| Markdown profile | `marqdo.md.v1` | Frozen parser/options; semantic change needs an ADR, new goldens and a profile id bump. |
| Language / CLI | workspace `0.1.0` | Pre-1.0. CLI flags may change with a changelog note; `strict` refusal is contractual. |
| `marqdo.lock` | v3 | v1/v2 are rejected with a relock instruction; `run`/`call`/`check` never rewrite or fetch the lock. |
| Analysis | v2 | Consumers reject unknown majors; incompatible field changes require v3. |
| Trace | v2 | Binds to the exact Analysis bytes; unknown majors rejected. |
| CLI Tool | v1 | Manifest schema, SemVer negotiation and whole-bundle digest are stable for v1. |
| Plugin ABI | v1 | Struct layout/version negotiation frozen; `--trust-native-plugin` is required for in-process loading. |
| Foreign wire | v1 | One-shot request envelope; provider descriptors are explicit. |
## Platform / feature evidence
Legend: **PASS** = executed on this snapshot with logs; **UNVERIFIED** = code is
portable/tested locally but the native platform lane has not run here;
**UNSUPPORTED** = deliberately not claimed; **FAIL-CLOSED** = request is refused.
| Feature | Ubuntu Linux x86_64 | macOS arm64 | Windows x86_64 |
|---|---|---|---|
| Markdown profile / AST goldens | PASS | UNVERIFIED (CRLF fix) | UNVERIFIED (CRLF fix) |
| Rust interpreter / semantics | PASS | UNVERIFIED | UNVERIFIED |
| `run` / `call` / `check` / `inspect` / `fmt` | PASS | UNVERIFIED | UNVERIFIED |
| lock v3 path/Git graph + sync | PASS | UNVERIFIED | UNVERIFIED |
| Analysis v2 / Trace v2 + consumers | PASS | UNVERIFIED | UNVERIFIED |
| Tool Protocol v1 | PASS | UNVERIFIED | UNVERIFIED |
| Native ABI (`plugin inspect`, trusted call) | PASS (C fixture) | UNVERIFIED (host-native fixture) | UNSUPPORTED in CI lane (no `cc`) |
| Worker ABI + `fs.read` bridge | PASS (Unix) | UNVERIFIED | UNSUPPORTED (tests are Unix-gated) |
| Foreign Python/Node | PASS (system `python3`/`node`) | UNVERIFIED | UNVERIFIED |
| Foreign pinned environment binding | PASS | UNVERIFIED | UNVERIFIED |
| `strict` OS isolation | **FAIL-CLOSED / G-C NOT PASSED** | FAIL-CLOSED | FAIL-CLOSED |
The Ubuntu column is from this development host (Ubuntu 26.04 container). It is
**not** a GitHub Actions result: this checkout has no GitHub remote or CI
credentials. A fresh local clone with `core.autocrlf=true` was used to
reproduce the Windows checkout byte behavior.
## Minimum environment
- Rust 1.82+ (verified with 1.100.0).
- Linux/macOS: a C compiler for Native ABI fixtures; Python/Node only for
Foreign kernels.
- `strict` additionally requires a kernel/environment that permits user,
mount, PID and network namespaces, plus delegated cgroups. The current
container does not, so strict is refused. See
[`docs/security-gate.md`](security-gate.md).
## Explicitly unsupported in this candidate
- OS-level strict isolation on any platform (G-C not passed).
- Windows Native/Worker ABI runtime support.
- Automatic uv/npm/venv provisioning; only an explicitly provisioned, pinned
directory is verified (and must contain a regular-file executable).
- Registry/package publishing, JIT, Knowledge/Proof/View built-ins,
sessions, and general-purpose CAS.
+202
View File
@@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Marqdo 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.
+51 -34
View File
@@ -12,15 +12,16 @@ This repository is the new, independent Marqdo toolchain (M0.5). It is **not**
a compatibility rewrite of `cflmy/marqdo`; the old syntax, package format and a compatibility rewrite of `cflmy/marqdo`; the old syntax, package format and
plugin ABI v2 are not claimed to work here. plugin ABI v2 are not claimed to work here.
> **Status: working implementation, not an Alpha release.** P0/P1 and the > **Status: stabilization candidate, not released.** The language, lock v3,
> documented Math/Foreign subset are implemented and tested; modules/package/ > Analysis v2, Trace v2, Tool v1, Plugin ABI v1 (native + worker) and pinned
> security/plugin support is functional but partial; strict isolation, worker > Foreign providers are implemented and covered by tests on Linux. The
> plugins, git packages and performance/release work are not done. See > Windows AST and macOS plugin CI failures are fixed in source, but the native
> [`docs/STATUS.md`](docs/STATUS.md) and "Deliberate limits" below. The > Windows/macOS lanes have not been re-run from this checkout. **`strict` OS
> [stabilization and ecosystem-gate spec](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md) > isolation is not available**: it fails closed on every platform (G-C not
> and the M0.6 extensibility plan in > passed), and the broker/worker are not a sandbox. See
> [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) are > [`docs/STATUS.md`](docs/STATUS.md), [`COMPATIBILITY.md`](COMPATIBILITY.md)
> **Proposed** next-phase designs, not implemented feature lists. > and [`docs/security-gate.md`](docs/security-gate.md). The single next-phase
> plan is [`docs/STABLE_RELEASE_IMPLEMENTATION.md`](docs/STABLE_RELEASE_IMPLEMENTATION.md).
## Build ## Build
@@ -83,21 +84,27 @@ executes anything.
`UnitId`/anchors, import cycle detection, multi-module calls, `UnitId`/anchors, import cycle detection, multi-module calls,
`run/call/check/inspect/fmt`, reference validation (`check --refs`) and the `run/call/check/inspect/fmt`, reference validation (`check --refs`) and the
static link graph (`inspect --refs`). static link graph (`inspect --refs`).
* **P3 project** — `marqdo.yaml` validation, deterministic `marqdo.lock` for * **P3 project** — lock v3 full transitive package-instance graph for path and
path dependencies, `init`, `add`/`remove` (manifest editing), `lock`, pinned Git sources, verified content-addressed Git cache, deterministic
`sync --locked`. `lock`, strict `sync --locked` with atomic `.marqdo/env` materialization.
`run`/`call`/`check` never fetch or rewrite the lock.
* **P4 security core** — capability-checked host operations, project-relative * **P4 security core** — capability-checked host operations, project-relative
FS globs with traversal rejection, budgets, effect trace, `pure`/`project` FS globs with traversal rejection, budgets, effect trace, `pure`/`project`
modes, and **`strict` mode refuses to run** because no OS isolation adapter modes, and **`strict` mode fails closed** because no verified OS isolation
exists. adapter exists.
* **P5 Math/Foreign** — native `Formula` value from `$$...$$`; `math.parse/ * **P5 Math/Foreign** — native `Formula` value from `$$...$$`; `math.parse/
eval/substitute` over a documented exact-rational subset; one-shot Python/ eval/substitute` over a documented exact-rational subset; one-shot Python/
Node kernels via `foreign.run/call` with typed wire protocol, timeout and Node kernels via `foreign.run/call` with typed wire protocol, timeout and
output limits. output limits; pinned provider/environment digests and ADR-0020 environment
binding.
* **P6 plugin ABI** — frozen C ABI v1 header (`include/marqdo_plugin_abi_v1.h`), * **P6 plugin ABI** — frozen C ABI v1 header (`include/marqdo_plugin_abi_v1.h`),
host bindings, Rust SDK (`mq_plugin_entry!`), `plugin.yaml` validation, host bindings, Rust SDK (`mq_plugin_entry!`), `plugin.yaml` validation,
target-triple + sha256 artifact verification, C demo, and explicitly trusted target-triple + sha256 artifact verification, native and isolated worker
in-process plugin calls (`--plugin --trust-native-plugin --allow-plugin`). transports, brokered `fs.read`, and explicitly trusted in-process calls
(`--plugin --trust-native-plugin --allow-plugin`). A C ABI is not a sandbox.
* **Public protocols** — Analysis v2 and Trace v2 with JSON Schemas and
independent Python consumers; Tool Protocol v1 with arbitrary command names,
SemVer negotiation and whole-bundle digest verification.
Run everything: Run everything:
@@ -111,14 +118,14 @@ cargo clippy --workspace --all-targets -- -D warnings
## Deliberate limits (do not assume) ## Deliberate limits (do not assume)
* **Strict sandbox is not implemented.** `--mode strict` exits 1; there is no * **Strict sandbox is not implemented.** `--mode strict` exits 1; there is no
OS isolation or isolated plugin worker. `project` mode is cooperative and verified OS isolation. `project` mode is cooperative and in-process. Worker
in-process. plugins provide crash/address-space isolation, not an OS sandbox.
* **Native plugins run in-process** and require an explicit unsafe trust flag. * **Native plugins run in-process** and require an explicit unsafe trust flag.
A plugin can crash or read the host; a C ABI is not a sandbox. A plugin can crash or read the host; a C ABI is not a sandbox.
* **Package management is path-only in practice.** Git dependencies can be * **Package management is path + pinned-Git only.** There is no registry,
declared but cannot be resolved/locked; there is no registry, transitive floating-branch resolution, conflict solver, `--offline`, `tree`, `update`,
resolution, `--offline`, `tree`, `update` or environment materialization. `vendor`, or automatic uv/npm environment creation. Manifest
Manifest `capabilities` are requests, never grants. `capabilities` are requests, never grants.
* **Reference validation is opt-in**: `check --refs` reports broken links; * **Reference validation is opt-in**: `check --refs` reports broken links;
plain `check` ignores them because links are static knowledge references. plain `check` ignores them because links are static knowledge references.
Link-form calls cannot cross modules; cross-module calls use imported alias Link-form calls cannot cross modules; cross-module calls use imported alias
@@ -168,19 +175,29 @@ tests/ conformance/negative corpus (see tests/README.md)
baseline (Chinese; the M0.6 plan below supersedes it on command-surface scope, baseline (Chinese; the M0.6 plan below supersedes it on command-surface scope,
extension registration, plugin addressing, package identity, repository extension registration, plugin addressing, package identity, repository
decoupling and release gates). decoupling and release gates).
* [`docs/STABLE_RELEASE_IMPLEMENTATION.md`](docs/STABLE_RELEASE_IMPLEMENTATION.md)
— **the single authoritative next-phase plan**: PR order, G-A/G-B/G-C gates,
Windows/macOS fixes, protocol/environment stabilization, strict isolation
requirements and the release checklist.
* [`COMPATIBILITY.md`](COMPATIBILITY.md) — protocol versions, per-platform
feature evidence and explicit unsupported features.
* [`CHANGELOG.md`](CHANGELOG.md) — unreleased stabilization changes and the
`0.1.0` baseline.
* [`docs/security-gate.md`](docs/security-gate.md) — G-C probe evidence and the
exact conditions required before strict can become available.
* [`docs/releasing.md`](docs/releasing.md) — artifact, checksum, clean-install
smoke, tagging and rollback procedure.
* [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md) * [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md)
— proposed current-stage spec (Chinese, baseline `0adebe4`): CI/lock/source — historical stabilization spec (baseline `0adebe4`), superseded on current
identity/Tool/sandbox gaps B-01–B-18, H0–H3 workstreams, and the G-A/G-B/G-C priorities by the stable-release plan.
release gates. Newer than the M0.6 plan; still design input, not implemented.
* [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) — * [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) —
proposed M0.6 plan (Chinese): extensibility fixes, callable/package/kernel historical M0.6 plan.
registration, `marqdo tool`, Analysis/Trace v1, safety and release gates.
* [`docs/EXTENSIBILITY_AUDIT.md`](docs/EXTENSIBILITY_AUDIT.md) — source-backed * [`docs/EXTENSIBILITY_AUDIT.md`](docs/EXTENSIBILITY_AUDIT.md) — source-backed
audit issues E01–E16 with code locations and acceptance tests (Chinese). audit issues E01–E16.
* [`docs/contributor-guide.md`](docs/contributor-guide.md) — repo map, workflow, * [`docs/contributor-guide.md`](docs/contributor-guide.md) — repo map, workflow,
golden updates, quality gate. golden updates, quality gate.
* [`docs/STATUS.md`](docs/STATUS.md) — P0–P7 implementation matrix and honest * [`docs/STATUS.md`](docs/STATUS.md) — current work-package status, local
open items; blueprint §18 Alpha checklist. evidence and open blockers.
* [`docs/adr/`](docs/adr/) — accepted decisions (crate graph, inert executables, * [`docs/adr/`](docs/adr/) — accepted decisions (crate graph, inert executables,
`ref` ambiguity, strict refusal, AST normalization, CLI contract, BigInt/wire, `ref` ambiguity, strict refusal, AST normalization, CLI contract, BigInt/wire,
package identity, callable resolution, plugin export routing, capability package identity, callable resolution, plugin export routing, capability
@@ -211,13 +228,13 @@ marqdo inspect examples/references.mq.md --refs
marqdo inspect examples/hello.mq.md --platform # strict: unavailable marqdo inspect examples/hello.mq.md --platform # strict: unavailable
./examples/plugin-demo/build.sh ./examples/plugin-demo/build.sh
marqdo plugin inspect examples/plugin-demo marqdo plugin inspect examples/plugin-demo/build
marqdo run examples/plugin-demo/plugin-call.mq.md \ marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo --trust-native-plugin --allow-plugin demo.solver --plugin examples/plugin-demo/build --trust-native-plugin --allow-plugin demo.solver
./examples/plugin-multi-export/build.sh ./examples/plugin-multi-export/build.sh
marqdo run examples/plugin-multi-export/plugin-call.mq.md \ marqdo run examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export --trust-native-plugin --allow-plugin demo.solver --plugin examples/plugin-multi-export/build --trust-native-plugin --allow-plugin demo.solver
marqdo tool install examples/tool-unknown-name/tool.json marqdo tool install examples/tool-unknown-name/tool.json
marqdo benchmark run . marqdo benchmark run .
File diff suppressed because it is too large. Load diff
+112 -431
View File
@@ -1,454 +1,135 @@
# Marqdo Implementation Status (M0.5) # Marqdo Implementation Status
Snapshot: **2026-11-20**, workspace version `0.1.0`, plugin ABI `1.0`, Snapshot: **2026-11-20**, workspace version `0.1.0`, no release tag.
`wire_version` 1, Markdown profile `marqdo.md.v1`. Authoritative task plan: [`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md).
Support matrix: [`../COMPATIBILITY.md`](../COMPATIBILITY.md).
This file maps the blueprint's phases (`docs/DEVELOPMENT_BLUEPRINT.md` §13) to This file records what was actually executed on the current tree. "Implemented"
concrete evidence in the repository and lists honest open items. It is a status does not mean "verified on every platform"; the evidence column says which
report, not a promise. "Done" means implemented **for the documented subset** commands were run and where. The historical M0.5 snapshot is preserved at
and covered by tests; it does not mean the blueprint's full ambition is [`history/STATUS-M0.5-snapshot.md`](history/STATUS-M0.5-snapshot.md) and must
complete. not be read as current status.
> **M0.6 planning cross-reference (2026-11-20)**: this file is the M0.5 evidence ## 1. CI baseline and current evidence
> snapshot that the M0.6 audit was based on. Read
> [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md)
> (current-stage stabilization spec, baseline `0adebe4`),
> [`docs/EXTENSIBILITY_AUDIT.md`](EXTENSIBILITY_AUDIT.md) (issues E01–E16) and
> the proposed [`docs/NEXT_PHASE_IMPLEMENTATION.md`](NEXT_PHASE_IMPLEMENTATION.md)
> alongside it. The stabilization spec supersedes the earlier plans on the
> current baseline, gap list and G-A/G-B/G-C release gates; none of these plans
> claims any gap below is fixed. Per audit item
> E14, where this snapshot conflicts with the current tree (for example the CI
> workflow, console capability or `check --refs`), verify the source/tests at
> the current HEAD and update this table rather than trusting stale prose.
### R0 baseline record The last known public GitHub CI at baseline `e966b76` (run
[44680378977](https://github.com/cflmy/marqdo-cli/actions/runs/44680378977))
was **not green**:
At the M0.6 planning baseline (`0116160399fda6df69a72da438e04b0072566b0f`, - Linux `fmt + clippy + workspace tests + smoke`: PASS.
2026-11-20), the local gate passed before any M0.6 code change: - Schema instance validation + Python consumers: PASS.
- macOS `cargo test --workspace`: FAIL —
`plugin_inspect_and_explicit_trusted_invocation` used a Linux `.so` and a
Linux-target manifest.
- Windows `cargo test --workspace`: FAIL — AST golden bytes were CRLF after
checkout while the parser emits LF, producing "0 line(s) differ".
This checkout has a Gitee remote only and no GitHub Actions credentials. **No
new remote CI URL can be produced from this host.** The local gate below is
real evidence for this machine, not a substitute for the native Windows/macOS
lanes.
### Local gate after the stabilization commits
All commands were run from the repository root with Rust 1.100.0:
```text ```text
cargo fmt --all -- --check ok cargo fmt --all -- --check PASS
cargo clippy --workspace --all-targets -- -D warnings ok cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace ok (150 AST + 36 semantic cargo test --workspace PASS
+ 48 compile-error fixtures) cargo test -p marqdo-cli --test conformance_ast PASS (4 tests)
cargo test -p marqdo-cli --test integration_cli PASS (22 tests)
cargo test -p marqdo-cli --test plugin_worker PASS (4 tests)
cargo test -p marqdo-foreign --test provider PASS (8 tests)
``` ```
CI evidence: `.github/workflows/ci.yml` runs the same Linux x86_64 gate plus CLI Windows checkout reproduction: a fresh local clone with
example smoke tests. The R0 ADRs are `docs/adr/0008`–`0012` (package identity, `git -c core.autocrlf=true clone ...` kept goldens at LF, preserved the CRLF
callable resolution, plugin export routing, capability broker, kernel byte fixture, and passed all four `conformance_ast` tests. The previous
providers). behavior was reproduced by converting one golden to CRLF: the new diagnostic
reports the first differing byte and "the only difference is line endings".
### S0/H0 baseline record (current) macOS reproduction is **not possible on this host**; the fix removes the Linux
assumption by generating the manifest from the host triple and building
`solver.dylib` with `-dynamiclib`. It remains UNVERIFIED until the macOS lane
runs.
Starting point: `0adebe42f14d72a2a275564d03ff9558f197766e`, 2026-11-20. B-01 ## 2. Work package status
fixed by removing the `tests/properties/` empty-directory assertion from
`crates/cli/tests/properties.rs`; all fixtures are in-code strings, so the test
no longer depends on a directory Git cannot track. The prose-invariance
assertions were not reduced.
Local gate after the fix (Linux x86_64, rustc 1.100.0 / cargo 1.100.0): | # | Work package | State | Evidence |
|---|---|---|---|
| 0 | Windows AST line endings | **Fixed locally, Windows CI UNVERIFIED** | `.gitattributes`, byte diagnostics, CRLF structure test, autocrlf clone PASS |
| 1 | macOS native plugin fixtures | **Fixed locally, macOS CI UNVERIFIED** | host-target manifest + dylib flags, foreign-target/tamper/ABI tests PASS |
| 2 | Status/docs reconcile | **Done** | this file, `COMPATIBILITY.md`, `CHANGELOG.md`, `docs/releasing.md`, `docs/security-gate.md` |
| 3 | Package lock v3 reproducibility | **Implemented; targeted audit pending** | ADR-0016, `cargo test -p marqdo-cli --test package_env` PASS |
| 4 | Analysis/Trace/Tool protocol | **Implemented; consumers PASS locally** | schemas + `tests/consumers/*.py`, `analysis_trace`/`tool_protocol` PASS |
| 5 | Foreign pinned environment | **Done (ADR-0020)** | provider tests PASS; env binds interpreter; version drift rejected |
| 6 | ABI session/broker hardening | **Partial** | `fs.read` bridge + budgets + handle tests PASS; Windows ABI unsupported; broader services still `capability.unavailable` |
| 7 | Linux strict probe | **Done as fail-closed evidence** | `docs/security-gate.md`; userns/bwrap EPERM, cgroup ro, sudo blocked |
| 8 | Linux strict pure (L1) | **BLOCKED** | no namespace creation on this host; no adapter implemented or verified |
| 9 | Linux strict extensions (L2) | **BLOCKED** | depends on L1 |
| 10 | Native platform matrix | **Partial** | Linux PASS; macOS/Windows source fixes, remote lanes absent |
| 11 | Independent ecosystem consumers | **Partial** | Analysis/Trace Python consumers PASS; three Tool fixtures not added |
| 12 | RC/docs/artifacts | **Candidate build only** | release docs, checksummed artifact, clean-install smoke; NOT released |
```text ## 3. Verified capabilities
cargo fmt --all -- --check ok
cargo clippy --workspace --all-targets -- -D warnings ok
cargo test --workspace ok
cargo test -p marqdo-cli --test properties ok (2 tests)
```
CI run URL: not yet available from this environment; record the first pushed - Frozen Markdown profile `marqdo.md.v1` with 150 AST goldens and explicit
run here before treating H0 as CI-verified. The local gate is reproducible with CRLF byte semantics.
`CARGO_HOME=.cache/cargo CARGO_TARGET_DIR=.cache/target`. - Native Rust interpreter with 36 semantic goldens, 48 compile-error fixtures,
and runtime error source attribution.
- lock v3 full transitive package-instance graph, verified Git cache, strict
`sync --locked`, atomic `.marqdo/env` materialization; `run`/`check` never
fetch or rewrite the lock.
- Analysis v2 (logical identity, resources, byte digest) and Trace v2 (module
ownership, bounds, truncation, stale detection) with independent Python
consumers and JSON Schema validation.
- Tool Protocol v1 with arbitrary command names, SemVer/protocol negotiation,
whole-bundle digest verification, atomic install/remove.
- Plugin ABI v1: native + worker transports, capability broker executing
`fs.read` through `ProjectFs`, per-invocation budgets, host-owned handle
identity, crash/timeout isolation. Not an OS sandbox.
- Foreign kernels: one-shot Python/Node, typed wire, timeout/output caps,
provider and environment digests, and (ADR-0020) environment-bound provider
with interpreter-version verification.
S0 fix commit: `74e34c6` (`fix(ci): remove empty-directory dependency from prose ## 4. Open blockers and limits
property test (B-01)`).
### S1/H1-A record (current) 1. **No remote CI evidence for this commit.** The repository remote is Gitee;
no GitHub workflow was executed. Windows/macOS fixes are UNVERIFIED there.
2. **G-C is not passed.** `strict` remains `Unavailable`; the host cannot
create namespaces and root cgroup2 is read-only. See
[`security-gate.md`](security-gate.md). No release may claim Linux strict
isolation.
3. Windows Native/Worker ABI is explicitly unsupported (no `cc` toolchain in
the lane); it is not counted as a pass.
4. `fs.write`, `net.request`, `process`, `clock`, `random` are not executed
broker services; unsupported requests must return `capability.unavailable`.
5. uv/npm/venv provisioning is not implemented. Only a pre-provisioned,
digest-pinned directory with a regular-file executable is supported.
6. Three independent Tool consumers (`sample-view`/`knowledge`/`proof`) are
not yet added; only the portable `benchmark` fixture and Analysis/Trace
Python consumers exist.
7. No release tag/binary publication. A candidate archive and checksums are
produced locally; the release decision is **DO NOT RELEASE** until the
native CI matrix and G-C conditions in the plan are satisfied.
Implemented the lock v3 package-instance graph and fail-closed reproducibility ## 5. Reproduce
contract from ADR-0016:
* `marqdo lock` traverses the full dependency closure, records root and
per-instance `(alias → instance)` edges, the root manifest digest, full
content digests and structured path/Git sources, then writes atomically.
* `run`/`call`/`check`/`inspect` require a lock whenever dependencies are
declared, never fetch or rewrite it, and validate every `(parent, alias)`
edge. Missing edges/records, digest or source drift, root-manifest drift and
v1/v2 locks fail closed (exit 1).
* `sync` is strict in both modes and never rewrites the lock; it materializes
the entire locked closure into `.marqdo/env` with `env.json` schema 2 and
atomic publication.
* Git cache entries carry a marker and are reverified by URL, revision,
profile and content digest; revisions must be full lowercase commit hashes.
* `content_profile_version: 1` unifies hashing and materialization (B-05).
* `add`/`remove` no longer patch the lock; a stale graph is rejected with a
relock instruction.
Tests added: package file-set selection/encoding/budgets, transitive closure,
missing-edge fail-closed, root-manifest invalidation, strict sync without
`--locked`, full-closure env materialization, missing-lock and deleted-edge CLI
failures.
### S2-A/H1-B record (current)
Runtime errors now carry a logical source location (ADR-0017):
* `RuntimeError.module_id`, `origin` (`source`/`callsite`), and
`CallFrame.module_id`; attribution happens at function/module boundaries so
the innermost callee module wins.
* Host/plugin/foreign errors are marked as callsite errors without fabricating
a foreign stack.
* `LoadedProject::locate(module_id, span)` resolves the owning file and line;
the CLI no longer falls back to the entry file. Unknown modules or
out-of-range spans emit module/span with null line/file.
* Human and JSON output report the failing module; caller frames resolve their
own callsite modules.
* CLI test `runtime_error_in_imported_module_reports_that_module` reproduces
B-08 end to end with the real binary.
### S2-B/H2-A record (current)
Analysis v2 (`spec/analysis-v2.md`, `spec/schemas/analysis-v2.schema.json`):
* `project.root_id` is a logical manifest identity (`root:<name>@<version>`) or
a content-derived `workspace_snapshot` digest; physical paths are gone from
Analysis bytes.
* `modules[].resources` is an array covering the two real `marqdo-ir::Resource`
kinds, with stable module/unit/span references, payload digests and code
language. Payload text stays in the source.
* Diagnostics project `module`, `relative_path`, `span`, `line`, `column`
instead of absolute file paths.
* `analysis_digest` is SHA-256 of the exact emitted (pretty) bytes, so a
consumer can verify it; Trace binds to the same value.
* The independent Python consumer validates v2, resources and identity, and
rejects unknown versions.
* Tests cover byte-identical output after moving a project and resource
addressing for formulas/code fences.
### S2-C/H2-B record (current)
Trace v2 (`spec/trace-v2.md`, `spec/schemas/trace-v2.schema.json`):
* `source.root_id` uses the same logical Analysis identity; `analysis_digest`
is the digest of the exact emitted Analysis bytes and is independently
verifiable.
* Every span-bearing event carries `module_id`; `call.enter`/`call.exit` are
owned by the caller module, other semantic events by the current function,
effects by their `ExecutionContext`. The effect key is now `module_id`.
* Trace budgets: 100 000 events / 32 MiB by default, configurable with
`--trace-max-events` and `--trace-max-bytes`; `0` means unlimited. Semantic
recording is disabled when no trace is requested.
* On capacity exhaustion the trace ends with `trace.truncated` and
`truncated.reason`; the run status and execution result are unchanged. The
writer also enforces the byte cap on the final document.
* Worker frames are capped at 8 MiB, with aligned request/result/capability
wire caps; partial headers, oversized lengths, truncated payloads and invalid
JSON are protocol errors, clean EOF is distinct, and the host kills and marks
a worker dead after a transport failure.
* New independent `tests/consumers/trace_consumer.py` verifies identity,
digest, module references and sequence ordering in CI.
* Tests: event module ownership, 20-event truncation of a 500-iteration loop,
worker frame round-trip/EOF/partial/oversized/truncated cases.
### S3-A/H2-C Tool protocol record (current)
Tool Protocol hardening (`spec/tool-v1.md`):
* `semver` replaces the hand-rolled matcher. Tool versions and `marqdo`
requirements must parse; malformed ranges/versions are rejected.
* The core declares `SupportedProtocols { tool: 1, analysis: [2], trace: [2] }`.
Declared Analysis/Trace lists are negotiated at both install and dispatch;
empty or disjoint lists fail with `tool.protocol_incompatible`. Absent
declarations remain valid and are not forced.
* Installed records are `record_version: 2` with a whole-bundle file manifest
(path, size, SHA-256) and a deterministic bundle digest. Dispatch recomputes
the full bundle, rejects entrypoint/auxiliary/extra/missing-file tampering,
requires the record command to match and the entrypoint to be listed.
* Install copies exactly the verified bundle into staging, re-verifies it, and
rejects a source package that ships a root `record.json`. Removal detaches
the directory by rename before deleting it.
* Tests cover accepted/rejected protocol declarations, auxiliary-file/extra-file
tampering, entrypoint tampering and reserved `record.json`.
### S4-A/B-13 B-14 record (current)
* CI has an independent `schema` job that installs a pinned Draft 2020-12
validator (`jsonschema==4.23.0`), emits real Analysis/Trace artifacts,
validates each against its matching schema, and runs the independent Python
consumers. `tests/consumers/validate_protocols.py` also asserts negative
mutations (wrong type/version, missing required fields, unsupported
truncation reason, traversal entrypoint, invalid SemVer).
* Tool schema tightened: SemVer version pattern, package-relative entrypoint
pattern and non-empty protocol arrays.
* The Windows/macOS CI lane now runs `cargo test --workspace` plus portable CLI,
Analysis and Trace smoke tests and a strict-mode refusal assertion, instead
of `cargo check` only.
* Tool black-box tests no longer require a shell: they compile a portable
std-only fixture with `rustc`, so the Windows/macOS `cargo test --workspace`
lane now runs the full Tool protocol suite.
* Still Unix-only in CI: compiled C ABI plugins, worker transport tests, and
package/Git/process tests. They are not counted as cross-platform evidence;
`docs/STATUS.md` records this rather than treating `cargo test` skips as
passes.
### S5-A/B-12 record (current)
Foreign provider integrity and environment metadata:
* `KernelDescriptor` gains `environment_id`, `environment_digest` and
`interpreter_version`; external descriptors loaded by the CLI must declare a
full provider `digest` and an absolute executable entrypoint.
* Descriptors are verified at registration and again before every spawn; a
post-registration binary change returns `ForeignError::Integrity` without
starting a process. Malformed digests and relative external paths fail closed.
* The example provider pins its digest; tests cover success, post-registration
tampering and malformed descriptors.
* `environment_dir` is a pinned absolute directory whose profile-v1 tree digest
is verified at registration and before every spawn; the child receives
`MARQDO_FOREIGN_ENV` and a prepended `<env>/bin` on `PATH`. Tampering fails
with `EnvironmentIntegrity` before spawn.
* uv/npm environment **generation** and lock-v3 integration are still not
implemented; this build verifies an explicitly provisioned directory.
* H3-A is **implemented for `fs.read`**: both native and worker plugins can
request a granted `fs.read` through the broker; it executes via `ProjectFs`,
returns real bytes, and records an audit decision. Unsupported capabilities
return `capability.unavailable` rather than empty success. Worker
request/reply frames are request-scoped and carry no trusted identity
(ADR-0018).
* Per-invocation capability budgets are enforced in both the worker handler
and the host: 64 requests and 64 KiB per request. H3-A remains open for live
ABI session identity and broader executing services. H3-B (OS isolation) remains
open; `strict` is refused on every platform and no G-C claim is made.
### M0.6 implementation progress
| Step | State | Evidence |
|---|---|---|
| S0/H0 CI baseline | **Done locally** | B-01 fixed in `crates/cli/tests/properties.rs`; fresh-clone path no longer needs an empty directory; full local gate green (see §S0/H0) |
| S1/H1-A lock v3 graph | **Done** | ADR-0016; full-closure `marqdo.lock` v3; fail-closed edge lookup; strict non-rewriting `sync`; verified Git cache; unified file-set profile (see §S1/H1-A) |
| S2-A/H1-B source locations | **Done** | ADR-0017; `RuntimeError`/`CallFrame` carry `module_id`; callsite origin; CLI module-aware resolution with no entry fallback (see §S2-A/H1-B) |
| S2-B/H2-A Analysis v2 | **Done** | logical project identity, resources array, machine-path-free diagnostics, emitted-bytes digest, v2 schema + independent consumer (see §S2-B/H2-A) |
| S2-C/H2-B Trace v2 | **Done** | logical root/digest, module-owned events, bounded/truncated trace, independent consumer, hardened worker frames (see §S2-C/H2-B) |
| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) |
| S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) |
| S5-A/B-12 foreign integrity | **Done for pinned provider+environment** | provider and environment-directory digests verified at registration and before spawn; environment bin/PATH injection. uv/npm environment generation, lock-v3 integration and H3-B remain open (see §S5-A/B-12) |
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth remains open (ADR-0018) |
| S5-C/H3-B strict gate | **Gate implemented; isolation deferred** | ADR-0019 + test: strict stays unavailable with an actionable reason until a per-platform security lane passes; refusal is enforced before host/plugin creation. No G-C claim |
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
| R3 Tool Protocol | **Done (S3 hardened)** | `tool install/list/remove`; unknown-command fallback; SemVer + Analysis/Trace negotiation; whole-bundle digest verification; staged install and rename-based removal; black-box tests for arbitrary names, Unicode args, conflicts, traversal, PATH hijacking and bundle tampering |
| R4 Analysis/Trace v2 | **Done** | `check --emit` Analysis v2 and `run/call --trace-file` Trace v2 with logical identity, resources, module-owned events, capacity bounds, schemas and independent Python consumers; stale-artifact removal; value redaction |
| R5 environment/isolation | **Partial** | Pinned Git fetch with verified cache markers, transitive `@alias` resolution, full-closure atomic `.marqdo/env` materialization, foreign process-group cleanup, verified foreign provider digests and environment descriptor metadata. Strict OS isolation and uv/npm environment materialization remain explicitly unavailable (fail-closed) |
| R6 release/consumers | **Partial** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas with instance validation; Linux full gate + Windows/macOS workspace tests and portable analysis/trace smoke; Unix-only Tool/ABI/worker runtime evidence |
Reproduce the evidence:
```bash ```bash
export PATH=/root/.cargo/bin:$PATH export PATH="$HOME/.cargo/bin:$PATH"
export CARGO_HOME=/root/work/marqdo-cli/.cache/cargo # On hosts with a read-only $HOME, point CARGO_HOME at a writable directory.
export CARGO_TARGET_DIR=/root/work/marqdo-cli/.cache/target cargo fmt --all -- --check
cargo test --workspace
cargo test -p marqdo-cli
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --locked -p marqdo-cli
``` ```
## 1. Phase matrix Consumer evidence:
| Phase | Status | Main evidence | ```bash
|---|---|---| ./target/debug/marqdo check examples/multi-module/index.mq.md --refs --emit /tmp/a.json
| **P0** Formal specs + parser goldens | **Done** | `spec/markdown-profile.md`, `spec/mapping.md`, `spec/expression.ebnf`, `spec/evaluation.md`; frozen profile test `crates/marqdo-markdown/src/profile.rs`; 150 AST fixtures + goldens in `tests/conformance/ast/`; 48 compile-error fixtures in `tests/negative/`; `inspect --ast`; `conformance_ast.rs`/`negative.rs` harnesses. | ./target/debug/marqdo run examples/multi-module/index.mq.md --trace-file /tmp/t.json
| **P1** Interpreter, expressions, control flow | **Done** | `marqdo-expression`, `marqdo-ir`, `marqdo-frontend`, `marqdo-runtime`; factorial/countdown examples run without Python (`examples/factorial.mq.md`, `examples/hello.mq.md`); 36 execution goldens in `tests/conformance/semantics/`; runtime tests `crates/marqdo-runtime/tests/interpreter.rs`; prose invariance `crates/cli/tests/properties.rs`. | python3 tests/consumers/analysis_consumer.py /tmp/a.json
| **P2** Modules, references, CLI experience | **Partial** | Imports/ModuleId/UnitId/anchor/cycle detection + `run/call/check/inspect/fmt` (`crates/cli`), multi-module example and `multi_module_imports_and_cycles` CLI test; `check --refs` reference validation (all loaded documents, on-demand static analysis of link targets) and `inspect --refs` static graph. Missing: cross-module link calls, rename/interface-lock tooling, canonical AST-preserving `fmt` (see §3). | python3 tests/consumers/trace_consumer.py /tmp/a.json /tmp/t.json
| **P3** Package environment | **Partial** | `marqdo.yaml`/`marqdo.lock` types+validation, `init`, `add`/`remove`, deterministic `lock`, `sync --locked`; M0.6 adds pinned Git fetch/cache, transitive `@alias` resolution and atomic `.marqdo/env` materialization. Missing: registry, `tree/update/vendor`, `--offline`, full conflict solver. | ```
| **P4** Security core and isolation | **Partial** | `CapabilityHost`, capabilities at execution points (console and math included), project-rooted FS with traversal rejection, budgets, effect trace, pure/project modes, **strict refuses without OS isolation** (`marqdo-sandbox`); CLI test `strict_mode_refuses_without_isolation`; host unit tests. Missing: OS isolation adapter and network enforcement; isolated plugin workers exist but are not an OS sandbox. |
| **P5** Math and Foreign | **Partial (documented subset)** | `marqdo-math` exact-rational formula kernel for the grammar in `spec/math.md`; `math.parse/eval/substitute` host ops; `marqdo-foreign` Python/Node one-shot kernels with typed `foreign.call`; tests `crates/marqdo-math/tests/kernel.rs`, `crates/marqdo-foreign/tests/kernels.rs`; examples `math.mq.md`, `python-foreign.mq.md`. Missing: `simplify`/`differentiate`, matrices/series/symbolic algebra, foreign sessions, Python environment management. |
| **P6** Plugin ABI and developer experience | **Partial** | Frozen `include/marqdo_plugin_abi_v1.h`; C ABI mirrors/layout assertions, version negotiation, `plugin.yaml` validation, target triple + sha256 verification, wire envelopes, native loader; complete-name multi-export routing; `CapabilityBroker`; isolated worker transport with handshake/call timeouts; host handle table; Rust SDK; CLI `plugin inspect`, `check --plugin`, trusted native invocation. Missing: Wasm, vendor handlers, plugin installation, Rust plugin example crate. |
| **P7** Performance, release, CI | **Partial** | `.github/workflows/ci.yml` runs fmt/clippy/workspace tests plus CLI example smoke tests (including plugin inspect and invocation) on Linux x86_64. Missing: benchmarks, bytecode backend, full cross-platform test matrix (Windows/macOS currently `cargo check` only), signed releases and supply-chain checks. Tree-walk interpreter only. |
## 2. Feature evidence (selected commands)
| Command | Verified behavior |
|---|---|
| `marqdo init demo` | creates `marqdo.yaml` (`>=0.1,<1`), `index.mq.md`, `.gitignore` (`.marqdo/`); refuses existing manifest (exit 1). |
| `marqdo check index.mq.md` | static only; 0 when no error diagnostics (warnings allowed); 1 on errors; JSON `command/success/errors/diagnostics`. |
| `marqdo run index.mq.md` | executes `main` through the Rust interpreter/host; program stdout on stdout; exit 1 on runtime/compile/strict errors. |
| `marqdo call file fn --arg n=5` | typed constant arguments; prints the non-`Unit` return value. |
| `marqdo inspect file --ast/--units/--signature/--ir/--refs/--platform --json` | static dashboards; `--platform` reports strict unavailable. |
| `marqdo fmt [--check]` | normalizes CRLF and trailing newlines only; exit 1 if `--check` detects a change. |
| `marqdo plugin inspect dir` | validates manifest + verifies sha256; never `dlopen`s (`loaded: false`). |
| `marqdo run doc --plugin dir --trust-native-plugin --allow-plugin demo.solver` | calls `solver.add(a=20,b=22)` and prints `42`; without trust/grant it exits 1. |
| `marqdo lock` / `sync --locked` | deterministic path-dependency lock; `--locked` fails on manifest/dependency drift. |
Test corpus at this snapshot (`tests/README.md`):
* 150 AST fixtures + goldens (`tests/conformance/ast/`);
* 36 semantic execution fixtures + goldens (`tests/conformance/semantics/`);
* 48 compile-time hard-error fixtures, 6 inert-executable warning fixtures,
10 runtime-error fixtures (`tests/negative/`);
* `crates/cli/tests/` harnesses: `conformance_ast`, `conformance_semantics`,
`negative`, `properties`, `integration_cli`;
* crate tests across all 15 crates, including real `python3`/`node` foreign
tests (skipped if unavailable) and a compiled C plugin test (skipped without
`cc`).
At this snapshot `cargo test -p marqdo-cli` passes all 21 harness tests
(2 CLI unit + AST/semantics/negative/properties/integration) and
`cargo test --workspace` passes. The fixture counts above match
`tests/README.md`; empty `tests/integration`, `tests/properties`,
`tests/security` and `tests/abi` directories are reserved for future
workstreams — the active corpus lives in `tests/conformance`, `tests/negative`
and `crates/cli/tests`.
## 3. Open items by phase
### P0
* Wire floats now round-trip exactly: `serde_json`'s `float_roundtrip`
feature is enabled and a Python `math.pi * 9` fixture pins the exact value
(`spec/value-wire.md` §3).
* Profile change safety relies on the frozen-options unit test; no CI gate
regenerates goldens (intentional).
### P1
* The blueprint asks for a draft Turing-completeness argument. The language
supports mutable locals, branch-first-match, per-item `while` loops and
recursion with bounded budgets; a formal encoding write-up is still missing.
* The default cooperative stack budget is 128 frames so very deep recursion
yields a structured `resource.exhausted` instead of exhausting the debug-build
native stack; `--stack` raises it deliberately. A true guard-page/iterative
interpreter hardening is still open.
### P2
* `fmt` is intentionally minimal (line endings/trailing newlines only), not the
blueprint's "canonical AST-equivalent formatting"; no semantic formatting,
AST-equivalence check or render-preserving rewrite exists.
* Reference validation is opt-in: `check --refs` (and `inspect --refs`) resolve
links; plain `check` does not fail on broken links because links are static
knowledge references rather than execution inputs.
* Link-form calls cannot cross modules; cross-module calls use imported alias
expressions. The blueprint's `> [f](./other.mq.md#f)(...)` example is not
supported.
* `ref("#...")` is module-local and does not accept a selector for units with
multiple resources (it errors with `ref.ambiguous`, ADR-0003).
* No rename tooling, interface lock/ABI diffing, or incremental cache.
* Duplicate/nested project boundaries are not diagnosed (nearest
`marqdo.yaml` wins).
### P3
* Pinned Git dependencies resolve through a content-addressed cache; floating
branches, submodules and dependency install scripts remain unsupported.
* Transitive `@alias` imports resolve from each package's own manifest, but the
lock is still flat; there is no full conflict solver, registry, publishing,
signing, `tree`, `update`, `vendor`, `--offline`, or `lock --locked`.
* `sync` materializes `.marqdo/env` atomically; kernel/session environments are
not materialized.
* `add`/`remove` are shallow manifest editors.
* JSON errors from `add`/`remove`/`lock`/`sync` are plain stderr even with
`--json`.
### P4
* **Strict mode cannot run at all**: no OS isolation adapter (Linux
namespaces/seccomp/cgroups, Windows Job Object/appcontainer, macOS sandbox);
`run --mode strict` exits 1 (ADR-0004). Isolated plugin workers are
implemented but a child process is not an OS sandbox.
* `console` is a capability checked in `op_print`; it is granted by default in
`pure`/`project` mode and is not a bypass of the capability boundary.
* Network capability (`net_hosts`, `check_net`) exists but no host operation
performs network I/O and there is no `--allow-net` flag.
* Write-path symlink TOCTOU caveat (`spec/security.md` §2.1); symlink/race
hardening open.
* Budgets do not cover every allocation path; the interpreter's containers are
bounded only by fuel and available memory.
* Effect trace does not record argument values or paths (privacy-positive, but
less diagnostic detail); trace is opt-in and implicitly on for `--json`.
* `plugin_handle` wire values are structurally reconstructable; authority now
requires the host-owned owner/run/generation table, and untrusted output
containing handles is rejected (ADR-0014).
### P5
* Math is a deliberately limited calculator subset: no `simplify`,
`differentiate`, matrices, sums/integrals, trig/log functions, units,
assumptions or theorem proving. `math.simplify`/`math.differentiate` are
host ops that always return `math.unsupported`.
* Equation solving is affine-only, single target, target must occur exactly
once; other shapes are `math.unsupported`.
* Division by zero inside a formula maps to `runtime.type` (via
`MathErrorKind::Type`), not `runtime.division_by_zero`; documented divergence.
* Foreign kernels are one-shot only: no sessions, state bridge, Python/Node
environment management, or network policy for child processes.
* Foreign child processes form a process group on Unix, so timeout/overflow
kills grandchildren too; non-Unix targets still track only the direct child.
* Foreign per-call timeout (10 s) and output cap (1 MiB) are not CLI-configurable.
### P6
* Native in-process loading still requires explicit trust and a crash is a host
crash. The isolated worker transport (length-prefixed IPC, handshake/call
timeouts) is implemented for crash isolation, not as an OS sandbox.
* Wasm and hot unload/reload remain unsupported.
* The `CapabilityBroker` enforces core grants and vendor policy entries, but no
concrete vendor handler or worker-side capability bridge is shipped.
* Plugin calls are statically validated only with `check --plugin <manifest>`;
without a descriptor a missing export is a runtime `symbol.unknown`.
Positional plugin arguments are rejected.
* Multi-prefix exports are registered by complete name; explicit alias syntax
for two packages using the same export is still pending.
* No plugin installation/package management; `plugins:` in `marqdo.yaml` is
declarative only. No Rust plugin example crate (SDK has doc examples/tests).
* No hot unload/reload (ABI v1 design).
### P7
* Performance work is untouched: no benchmark suite, no bytecode backend or
differential tests against the tree-walker, no parse/compile caching.
* CI exists (`.github/workflows/ci.yml`) and runs fmt/clippy/workspace tests
plus CLI smoke tests on Linux x86_64; missing: Windows/macOS matrix,
sanitizers/fuzz gates, signing, release automation or supply-chain scanning.
* No published version, no compatibility matrix beyond the frozen ABI/format
documents.
## 4. Blueprint §18 "Alpha Definition of Done" mapping
| §18 item | Status | Evidence / gap |
|---|---|---|
| Run/call non-trivial recursive, branch, loop, call, parameter-inference programs without Python | **Met** | factorial/recursion (`examples/factorial.mq.md`, runtime + semantic goldens), countdown loop, multi-module alias call; interpreter is native Rust. |
| `.mq.md` readable under the chosen CommonMark/GFM/Math profile; standard AST behavior covered by goldens | **Met** | frozen `marqdo.md.v1`, 150 AST goldens, profile option test, `spec/markdown-profile.md`. |
| No heuristic downgrade of execution semantics; accurate source locations for invalid execution nodes | **Mostly met** | hard errors with spans for function-body executable shapes and negative corpus. Gaps: inert executable outside functions is a warning by design (ADR-0002); cross-module runtime error spans resolve against the entry file only; some lazy nested nodes are inert without a warning. |
| `check`/`inspect` side-effect free; imports, calls and static references verifiable across files | **Mostly met** | static load/analysis only; imports + cycle detection; cross-module calls validated; `check --refs` validates references across loaded documents and statically analyses link targets; `inspect --refs` prints the entry graph. |
| Minimal manifest, lock file, path/Git dependencies and environment sync | **Partial** | manifest/lock/path works, `sync --locked` verifies; git resolution, transitive deps, environment materialization and `--offline` missing. |
| All host side effects capability-authorized; untrusted code/native plugins cannot masquerade as strict sandbox | **Mostly met** | capability checks at execution points; strict refuses; native plugins require explicit trust and are documented as unsandboxed. Gaps: network enforcement not implemented (no network builtin is exposed); worker isolation is crash isolation, not an OS sandbox. |
| Formula computational subset explicit/testable; Foreign I/O, timeout and permissions explicit | **Met for the documented subset** | `spec/math.md`, `spec/foreign.md`; math kernel tests; foreign tests (timeout, protocol, output cap, env); permission gating tests/smoke. Simplification/differentiation explicitly unsupported. |
| Plugin C ABI v1, Rust SDK, C example, isolated worker basic path, ABI compat error tests | **Partial** | ABI/SDK/C example/loader/ABI-error tests exist; isolated worker with timeout/crash tests exists. Missing: Wasm, vendor handlers, plugin installation. |
| CI has at least one full research pipeline: Markdown function → Math → Foreign → Plugin → controlled output | **Partial** | CI now runs fmt/clippy/tests and CLI smoke tests; individual math/foreign/plugin paths are covered by examples and tests, but no single end-to-end pipeline document/test exists yet. |
| Examples, README, AGENTS and contributor docs allow a first change without legacy context | **Met** | `README.md`, `AGENTS.md`, this guide, `docs/STATUS.md`, specs, ADRs, `tests/README.md`, examples. |
**Conclusion: the Alpha definition of done is not fully met.** P0/P1 and the
documented P5 subset are solid; P2/P3/P4/P6 are functional but partial; P7 is
absent. The blocking items for an Alpha claim are the strict sandbox/worker
isolation story (P4/P6), git/environment package management (P3), and a CI
end-to-end pipeline (P7).
## 5. What is deliberately limited (do not overclaim)
* Only a single, frozen Markdown profile (`marqdo.md.v1`); changing parser
options/versions is a language change.
* Strict mode is a refusal, not an isolation implementation. `project` mode is
cooperative and in-process.
* Native plugins are trusted in-process code and a crash takes down the host.
`kind: worker` isolates crashes/timeouts but is not an OS sandbox.
* Ints are arbitrary precision; finite floats are binary64 and wire round-trip
is exact (`float_roundtrip` enabled), but decimal-vs-binary formatting still
applies when displaying values.
* Math is a limited exact-rational calculator, not a CAS or a prover.
* Foreign kernels are optional, one-shot, unsandboxed child processes.
* `fmt` is minimal; plain `check` does not validate Markdown links (only
`check --refs` does); link-form calls cannot cross modules.
* Package management is path-only in practice; `marqdo.yaml` capabilities are
requests, never grants.
+22 -16
View File
@@ -14,12 +14,16 @@ marqdo-cli/
├── README.md user-facing quickstart and limits ├── README.md user-facing quickstart and limits
├── docs/ ├── docs/
│ ├── DEVELOPMENT_BLUEPRINT.md architecture baseline │ ├── DEVELOPMENT_BLUEPRINT.md architecture baseline
│ ├── CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md current-stage stabilization spec (Proposed) │ ├── STABLE_RELEASE_IMPLEMENTATION.md authoritative next-phase/release plan
│ ├── NEXT_PHASE_IMPLEMENTATION.md proposed M0.6 plan (Proposed, not implemented) │ ├── STATUS.md current evidence, work packages, blockers
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6 │ ├── security-gate.md G-C probe evidence (strict stays closed)
│ ├── STATUS.md implementation matrix (P0–P7) │ ├── releasing.md artifact/checksum/smoke/tag procedure
│ ├── CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md historical stabilization spec
│ ├── NEXT_PHASE_IMPLEMENTATION.md historical M0.6 plan
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit
│ ├── history/ archived status snapshots
│ ├── contributor-guide.md this file │ ├── contributor-guide.md this file
│ └── adr/0001..0015-*.md accepted decisions │ └── adr/0001..0020-*.md accepted decisions
├── spec/ ├── spec/
│ ├── markdown-profile.md frozen parser profile `marqdo.md.v1` │ ├── markdown-profile.md frozen parser profile `marqdo.md.v1`
│ ├── mapping.md AST → program roles │ ├── mapping.md AST → program roles
@@ -243,11 +247,11 @@ $B run examples/python-foreign.mq.md --allow-foreign # needs python3
$B run examples/multi-module/index.mq.md $B run examples/multi-module/index.mq.md
(cd examples/multi-module && ../../$B lock && ../../$B sync --locked) (cd examples/multi-module && ../../$B lock && ../../$B sync --locked)
# Plugin demo (build the artifact + refresh its sha256 first) # Plugin demo (builds a host-specific manifest under build/)
./examples/plugin-demo/build.sh ./examples/plugin-demo/build.sh
$B plugin inspect examples/plugin-demo $B plugin inspect examples/plugin-demo/build
$B run examples/plugin-demo/plugin-call.mq.md \ $B run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo --trust-native-plugin --allow-plugin demo.solver --plugin examples/plugin-demo/build --trust-native-plugin --allow-plugin demo.solver
``` ```
Notes: `run` defaults to `index.mq.md` and executes `main`; `call` requires a Notes: `run` defaults to `index.mq.md` and executes `main`; `call` requires a
@@ -291,15 +295,17 @@ file and function; root-only examples (for example `math.mq.md`) define no
## 9. Known gotchas ## 9. Known gotchas
* `.cache/` is the offline cargo cache/target used in this environment; it is * `.cache/` and `.cargo-home/` are local caches used on hosts with a read-only
not part of the deliverable. `$HOME`; neither is part of the deliverable.
* Foreign availability (`python3`/`node`) and a C compiler (`cc`) determine * Foreign availability (`python3`/`node`) and a C compiler (`cc`) determine
which tests run; a skipped test is not a passed feature. which tests run; a skipped test is not a passed feature. Windows Native ABI
* The strict sandbox, plugin worker isolation and package registry are not is explicitly unsupported, not a pass.
implemented. Do not write docs or tests that pretend they are — see * Isolated worker plugins exist (crash/address-space isolation + brokered
`docs/STATUS.md` and `spec/security.md`. `fs.read`), but they are **not** an OS sandbox. The strict sandbox and a
* Runtime error spans in the CLI currently resolve against the entry file only; package registry remain unimplemented; strict fails closed. See
imported-module error locations are approximate (ADR-0006). `docs/security-gate.md` and `spec/security.md`.
* Runtime errors resolve against their owning module (ADR-0017); do not
reintroduce entry-file fallback.
* The semantic corpus may pin current quirks (for example the external-link * The semantic corpus may pin current quirks (for example the external-link
call code, or a float's last digit). A fixture diff for such a quirk is a call code, or a float's last digit). A fixture diff for such a quirk is a
deliberate change, not a free update. deliberate change, not a free update.
+454
View File
@@ -0,0 +1,454 @@
# Marqdo Implementation Status (M0.5)
Snapshot: **2026-11-20**, workspace version `0.1.0`, plugin ABI `1.0`,
`wire_version` 1, Markdown profile `marqdo.md.v1`.
This file maps the blueprint's phases (`docs/DEVELOPMENT_BLUEPRINT.md` §13) to
concrete evidence in the repository and lists honest open items. It is a status
report, not a promise. "Done" means implemented **for the documented subset**
and covered by tests; it does not mean the blueprint's full ambition is
complete.
> **M0.6 planning cross-reference (2026-11-20)**: this file is the M0.5 evidence
> snapshot that the M0.6 audit was based on. Read
> [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md)
> (current-stage stabilization spec, baseline `0adebe4`),
> [`docs/EXTENSIBILITY_AUDIT.md`](EXTENSIBILITY_AUDIT.md) (issues E01–E16) and
> the proposed [`docs/NEXT_PHASE_IMPLEMENTATION.md`](NEXT_PHASE_IMPLEMENTATION.md)
> alongside it. The stabilization spec supersedes the earlier plans on the
> current baseline, gap list and G-A/G-B/G-C release gates; none of these plans
> claims any gap below is fixed. Per audit item
> E14, where this snapshot conflicts with the current tree (for example the CI
> workflow, console capability or `check --refs`), verify the source/tests at
> the current HEAD and update this table rather than trusting stale prose.
### R0 baseline record
At the M0.6 planning baseline (`0116160399fda6df69a72da438e04b0072566b0f`,
2026-11-20), the local gate passed before any M0.6 code change:
```text
cargo fmt --all -- --check ok
cargo clippy --workspace --all-targets -- -D warnings ok
cargo test --workspace ok (150 AST + 36 semantic
+ 48 compile-error fixtures)
```
CI evidence: `.github/workflows/ci.yml` runs the same Linux x86_64 gate plus CLI
example smoke tests. The R0 ADRs are `docs/adr/0008`–`0012` (package identity,
callable resolution, plugin export routing, capability broker, kernel
providers).
### S0/H0 baseline record (current)
Starting point: `0adebe42f14d72a2a275564d03ff9558f197766e`, 2026-11-20. B-01
fixed by removing the `tests/properties/` empty-directory assertion from
`crates/cli/tests/properties.rs`; all fixtures are in-code strings, so the test
no longer depends on a directory Git cannot track. The prose-invariance
assertions were not reduced.
Local gate after the fix (Linux x86_64, rustc 1.100.0 / cargo 1.100.0):
```text
cargo fmt --all -- --check ok
cargo clippy --workspace --all-targets -- -D warnings ok
cargo test --workspace ok
cargo test -p marqdo-cli --test properties ok (2 tests)
```
CI run URL: not yet available from this environment; record the first pushed
run here before treating H0 as CI-verified. The local gate is reproducible with
`CARGO_HOME=.cache/cargo CARGO_TARGET_DIR=.cache/target`.
S0 fix commit: `74e34c6` (`fix(ci): remove empty-directory dependency from prose
property test (B-01)`).
### S1/H1-A record (current)
Implemented the lock v3 package-instance graph and fail-closed reproducibility
contract from ADR-0016:
* `marqdo lock` traverses the full dependency closure, records root and
per-instance `(alias → instance)` edges, the root manifest digest, full
content digests and structured path/Git sources, then writes atomically.
* `run`/`call`/`check`/`inspect` require a lock whenever dependencies are
declared, never fetch or rewrite it, and validate every `(parent, alias)`
edge. Missing edges/records, digest or source drift, root-manifest drift and
v1/v2 locks fail closed (exit 1).
* `sync` is strict in both modes and never rewrites the lock; it materializes
the entire locked closure into `.marqdo/env` with `env.json` schema 2 and
atomic publication.
* Git cache entries carry a marker and are reverified by URL, revision,
profile and content digest; revisions must be full lowercase commit hashes.
* `content_profile_version: 1` unifies hashing and materialization (B-05).
* `add`/`remove` no longer patch the lock; a stale graph is rejected with a
relock instruction.
Tests added: package file-set selection/encoding/budgets, transitive closure,
missing-edge fail-closed, root-manifest invalidation, strict sync without
`--locked`, full-closure env materialization, missing-lock and deleted-edge CLI
failures.
### S2-A/H1-B record (current)
Runtime errors now carry a logical source location (ADR-0017):
* `RuntimeError.module_id`, `origin` (`source`/`callsite`), and
`CallFrame.module_id`; attribution happens at function/module boundaries so
the innermost callee module wins.
* Host/plugin/foreign errors are marked as callsite errors without fabricating
a foreign stack.
* `LoadedProject::locate(module_id, span)` resolves the owning file and line;
the CLI no longer falls back to the entry file. Unknown modules or
out-of-range spans emit module/span with null line/file.
* Human and JSON output report the failing module; caller frames resolve their
own callsite modules.
* CLI test `runtime_error_in_imported_module_reports_that_module` reproduces
B-08 end to end with the real binary.
### S2-B/H2-A record (current)
Analysis v2 (`spec/analysis-v2.md`, `spec/schemas/analysis-v2.schema.json`):
* `project.root_id` is a logical manifest identity (`root:<name>@<version>`) or
a content-derived `workspace_snapshot` digest; physical paths are gone from
Analysis bytes.
* `modules[].resources` is an array covering the two real `marqdo-ir::Resource`
kinds, with stable module/unit/span references, payload digests and code
language. Payload text stays in the source.
* Diagnostics project `module`, `relative_path`, `span`, `line`, `column`
instead of absolute file paths.
* `analysis_digest` is SHA-256 of the exact emitted (pretty) bytes, so a
consumer can verify it; Trace binds to the same value.
* The independent Python consumer validates v2, resources and identity, and
rejects unknown versions.
* Tests cover byte-identical output after moving a project and resource
addressing for formulas/code fences.
### S2-C/H2-B record (current)
Trace v2 (`spec/trace-v2.md`, `spec/schemas/trace-v2.schema.json`):
* `source.root_id` uses the same logical Analysis identity; `analysis_digest`
is the digest of the exact emitted Analysis bytes and is independently
verifiable.
* Every span-bearing event carries `module_id`; `call.enter`/`call.exit` are
owned by the caller module, other semantic events by the current function,
effects by their `ExecutionContext`. The effect key is now `module_id`.
* Trace budgets: 100 000 events / 32 MiB by default, configurable with
`--trace-max-events` and `--trace-max-bytes`; `0` means unlimited. Semantic
recording is disabled when no trace is requested.
* On capacity exhaustion the trace ends with `trace.truncated` and
`truncated.reason`; the run status and execution result are unchanged. The
writer also enforces the byte cap on the final document.
* Worker frames are capped at 8 MiB, with aligned request/result/capability
wire caps; partial headers, oversized lengths, truncated payloads and invalid
JSON are protocol errors, clean EOF is distinct, and the host kills and marks
a worker dead after a transport failure.
* New independent `tests/consumers/trace_consumer.py` verifies identity,
digest, module references and sequence ordering in CI.
* Tests: event module ownership, 20-event truncation of a 500-iteration loop,
worker frame round-trip/EOF/partial/oversized/truncated cases.
### S3-A/H2-C Tool protocol record (current)
Tool Protocol hardening (`spec/tool-v1.md`):
* `semver` replaces the hand-rolled matcher. Tool versions and `marqdo`
requirements must parse; malformed ranges/versions are rejected.
* The core declares `SupportedProtocols { tool: 1, analysis: [2], trace: [2] }`.
Declared Analysis/Trace lists are negotiated at both install and dispatch;
empty or disjoint lists fail with `tool.protocol_incompatible`. Absent
declarations remain valid and are not forced.
* Installed records are `record_version: 2` with a whole-bundle file manifest
(path, size, SHA-256) and a deterministic bundle digest. Dispatch recomputes
the full bundle, rejects entrypoint/auxiliary/extra/missing-file tampering,
requires the record command to match and the entrypoint to be listed.
* Install copies exactly the verified bundle into staging, re-verifies it, and
rejects a source package that ships a root `record.json`. Removal detaches
the directory by rename before deleting it.
* Tests cover accepted/rejected protocol declarations, auxiliary-file/extra-file
tampering, entrypoint tampering and reserved `record.json`.
### S4-A/B-13 B-14 record (current)
* CI has an independent `schema` job that installs a pinned Draft 2020-12
validator (`jsonschema==4.23.0`), emits real Analysis/Trace artifacts,
validates each against its matching schema, and runs the independent Python
consumers. `tests/consumers/validate_protocols.py` also asserts negative
mutations (wrong type/version, missing required fields, unsupported
truncation reason, traversal entrypoint, invalid SemVer).
* Tool schema tightened: SemVer version pattern, package-relative entrypoint
pattern and non-empty protocol arrays.
* The Windows/macOS CI lane now runs `cargo test --workspace` plus portable CLI,
Analysis and Trace smoke tests and a strict-mode refusal assertion, instead
of `cargo check` only.
* Tool black-box tests no longer require a shell: they compile a portable
std-only fixture with `rustc`, so the Windows/macOS `cargo test --workspace`
lane now runs the full Tool protocol suite.
* Still Unix-only in CI: compiled C ABI plugins, worker transport tests, and
package/Git/process tests. They are not counted as cross-platform evidence;
`docs/STATUS.md` records this rather than treating `cargo test` skips as
passes.
### S5-A/B-12 record (current)
Foreign provider integrity and environment metadata:
* `KernelDescriptor` gains `environment_id`, `environment_digest` and
`interpreter_version`; external descriptors loaded by the CLI must declare a
full provider `digest` and an absolute executable entrypoint.
* Descriptors are verified at registration and again before every spawn; a
post-registration binary change returns `ForeignError::Integrity` without
starting a process. Malformed digests and relative external paths fail closed.
* The example provider pins its digest; tests cover success, post-registration
tampering and malformed descriptors.
* `environment_dir` is a pinned absolute directory whose profile-v1 tree digest
is verified at registration and before every spawn; the child receives
`MARQDO_FOREIGN_ENV` and a prepended `<env>/bin` on `PATH`. Tampering fails
with `EnvironmentIntegrity` before spawn.
* uv/npm environment **generation** and lock-v3 integration are still not
implemented; this build verifies an explicitly provisioned directory.
* H3-A is **implemented for `fs.read`**: both native and worker plugins can
request a granted `fs.read` through the broker; it executes via `ProjectFs`,
returns real bytes, and records an audit decision. Unsupported capabilities
return `capability.unavailable` rather than empty success. Worker
request/reply frames are request-scoped and carry no trusted identity
(ADR-0018).
* Per-invocation capability budgets are enforced in both the worker handler
and the host: 64 requests and 64 KiB per request. H3-A remains open for live
ABI session identity and broader executing services. H3-B (OS isolation) remains
open; `strict` is refused on every platform and no G-C claim is made.
### M0.6 implementation progress
| Step | State | Evidence |
|---|---|---|
| S0/H0 CI baseline | **Done locally** | B-01 fixed in `crates/cli/tests/properties.rs`; fresh-clone path no longer needs an empty directory; full local gate green (see §S0/H0) |
| S1/H1-A lock v3 graph | **Done** | ADR-0016; full-closure `marqdo.lock` v3; fail-closed edge lookup; strict non-rewriting `sync`; verified Git cache; unified file-set profile (see §S1/H1-A) |
| S2-A/H1-B source locations | **Done** | ADR-0017; `RuntimeError`/`CallFrame` carry `module_id`; callsite origin; CLI module-aware resolution with no entry fallback (see §S2-A/H1-B) |
| S2-B/H2-A Analysis v2 | **Done** | logical project identity, resources array, machine-path-free diagnostics, emitted-bytes digest, v2 schema + independent consumer (see §S2-B/H2-A) |
| S2-C/H2-B Trace v2 | **Done** | logical root/digest, module-owned events, bounded/truncated trace, independent consumer, hardened worker frames (see §S2-C/H2-B) |
| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) |
| S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) |
| S5-A/B-12 foreign integrity | **Done for pinned provider+environment** | provider and environment-directory digests verified at registration and before spawn; environment bin/PATH injection. uv/npm environment generation, lock-v3 integration and H3-B remain open (see §S5-A/B-12) |
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth remains open (ADR-0018) |
| S5-C/H3-B strict gate | **Gate implemented; isolation deferred** | ADR-0019 + test: strict stays unavailable with an actionable reason until a per-platform security lane passes; refusal is enforced before host/plugin creation. No G-C claim |
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
| R3 Tool Protocol | **Done (S3 hardened)** | `tool install/list/remove`; unknown-command fallback; SemVer + Analysis/Trace negotiation; whole-bundle digest verification; staged install and rename-based removal; black-box tests for arbitrary names, Unicode args, conflicts, traversal, PATH hijacking and bundle tampering |
| R4 Analysis/Trace v2 | **Done** | `check --emit` Analysis v2 and `run/call --trace-file` Trace v2 with logical identity, resources, module-owned events, capacity bounds, schemas and independent Python consumers; stale-artifact removal; value redaction |
| R5 environment/isolation | **Partial** | Pinned Git fetch with verified cache markers, transitive `@alias` resolution, full-closure atomic `.marqdo/env` materialization, foreign process-group cleanup, verified foreign provider digests and environment descriptor metadata. Strict OS isolation and uv/npm environment materialization remain explicitly unavailable (fail-closed) |
| R6 release/consumers | **Partial** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas with instance validation; Linux full gate + Windows/macOS workspace tests and portable analysis/trace smoke; Unix-only Tool/ABI/worker runtime evidence |
Reproduce the evidence:
```bash
export PATH=/root/.cargo/bin:$PATH
export CARGO_HOME=/root/work/marqdo-cli/.cache/cargo
export CARGO_TARGET_DIR=/root/work/marqdo-cli/.cache/target
cargo test --workspace
cargo test -p marqdo-cli
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
```
## 1. Phase matrix
| Phase | Status | Main evidence |
|---|---|---|
| **P0** Formal specs + parser goldens | **Done** | `spec/markdown-profile.md`, `spec/mapping.md`, `spec/expression.ebnf`, `spec/evaluation.md`; frozen profile test `crates/marqdo-markdown/src/profile.rs`; 150 AST fixtures + goldens in `tests/conformance/ast/`; 48 compile-error fixtures in `tests/negative/`; `inspect --ast`; `conformance_ast.rs`/`negative.rs` harnesses. |
| **P1** Interpreter, expressions, control flow | **Done** | `marqdo-expression`, `marqdo-ir`, `marqdo-frontend`, `marqdo-runtime`; factorial/countdown examples run without Python (`examples/factorial.mq.md`, `examples/hello.mq.md`); 36 execution goldens in `tests/conformance/semantics/`; runtime tests `crates/marqdo-runtime/tests/interpreter.rs`; prose invariance `crates/cli/tests/properties.rs`. |
| **P2** Modules, references, CLI experience | **Partial** | Imports/ModuleId/UnitId/anchor/cycle detection + `run/call/check/inspect/fmt` (`crates/cli`), multi-module example and `multi_module_imports_and_cycles` CLI test; `check --refs` reference validation (all loaded documents, on-demand static analysis of link targets) and `inspect --refs` static graph. Missing: cross-module link calls, rename/interface-lock tooling, canonical AST-preserving `fmt` (see §3). |
| **P3** Package environment | **Partial** | `marqdo.yaml`/`marqdo.lock` types+validation, `init`, `add`/`remove`, deterministic `lock`, `sync --locked`; M0.6 adds pinned Git fetch/cache, transitive `@alias` resolution and atomic `.marqdo/env` materialization. Missing: registry, `tree/update/vendor`, `--offline`, full conflict solver. |
| **P4** Security core and isolation | **Partial** | `CapabilityHost`, capabilities at execution points (console and math included), project-rooted FS with traversal rejection, budgets, effect trace, pure/project modes, **strict refuses without OS isolation** (`marqdo-sandbox`); CLI test `strict_mode_refuses_without_isolation`; host unit tests. Missing: OS isolation adapter and network enforcement; isolated plugin workers exist but are not an OS sandbox. |
| **P5** Math and Foreign | **Partial (documented subset)** | `marqdo-math` exact-rational formula kernel for the grammar in `spec/math.md`; `math.parse/eval/substitute` host ops; `marqdo-foreign` Python/Node one-shot kernels with typed `foreign.call`; tests `crates/marqdo-math/tests/kernel.rs`, `crates/marqdo-foreign/tests/kernels.rs`; examples `math.mq.md`, `python-foreign.mq.md`. Missing: `simplify`/`differentiate`, matrices/series/symbolic algebra, foreign sessions, Python environment management. |
| **P6** Plugin ABI and developer experience | **Partial** | Frozen `include/marqdo_plugin_abi_v1.h`; C ABI mirrors/layout assertions, version negotiation, `plugin.yaml` validation, target triple + sha256 verification, wire envelopes, native loader; complete-name multi-export routing; `CapabilityBroker`; isolated worker transport with handshake/call timeouts; host handle table; Rust SDK; CLI `plugin inspect`, `check --plugin`, trusted native invocation. Missing: Wasm, vendor handlers, plugin installation, Rust plugin example crate. |
| **P7** Performance, release, CI | **Partial** | `.github/workflows/ci.yml` runs fmt/clippy/workspace tests plus CLI example smoke tests (including plugin inspect and invocation) on Linux x86_64. Missing: benchmarks, bytecode backend, full cross-platform test matrix (Windows/macOS currently `cargo check` only), signed releases and supply-chain checks. Tree-walk interpreter only. |
## 2. Feature evidence (selected commands)
| Command | Verified behavior |
|---|---|
| `marqdo init demo` | creates `marqdo.yaml` (`>=0.1,<1`), `index.mq.md`, `.gitignore` (`.marqdo/`); refuses existing manifest (exit 1). |
| `marqdo check index.mq.md` | static only; 0 when no error diagnostics (warnings allowed); 1 on errors; JSON `command/success/errors/diagnostics`. |
| `marqdo run index.mq.md` | executes `main` through the Rust interpreter/host; program stdout on stdout; exit 1 on runtime/compile/strict errors. |
| `marqdo call file fn --arg n=5` | typed constant arguments; prints the non-`Unit` return value. |
| `marqdo inspect file --ast/--units/--signature/--ir/--refs/--platform --json` | static dashboards; `--platform` reports strict unavailable. |
| `marqdo fmt [--check]` | normalizes CRLF and trailing newlines only; exit 1 if `--check` detects a change. |
| `marqdo plugin inspect dir` | validates manifest + verifies sha256; never `dlopen`s (`loaded: false`). |
| `marqdo run doc --plugin dir --trust-native-plugin --allow-plugin demo.solver` | calls `solver.add(a=20,b=22)` and prints `42`; without trust/grant it exits 1. |
| `marqdo lock` / `sync --locked` | deterministic path-dependency lock; `--locked` fails on manifest/dependency drift. |
Test corpus at this snapshot (`tests/README.md`):
* 150 AST fixtures + goldens (`tests/conformance/ast/`);
* 36 semantic execution fixtures + goldens (`tests/conformance/semantics/`);
* 48 compile-time hard-error fixtures, 6 inert-executable warning fixtures,
10 runtime-error fixtures (`tests/negative/`);
* `crates/cli/tests/` harnesses: `conformance_ast`, `conformance_semantics`,
`negative`, `properties`, `integration_cli`;
* crate tests across all 15 crates, including real `python3`/`node` foreign
tests (skipped if unavailable) and a compiled C plugin test (skipped without
`cc`).
At this snapshot `cargo test -p marqdo-cli` passes all 21 harness tests
(2 CLI unit + AST/semantics/negative/properties/integration) and
`cargo test --workspace` passes. The fixture counts above match
`tests/README.md`; empty `tests/integration`, `tests/properties`,
`tests/security` and `tests/abi` directories are reserved for future
workstreams — the active corpus lives in `tests/conformance`, `tests/negative`
and `crates/cli/tests`.
## 3. Open items by phase
### P0
* Wire floats now round-trip exactly: `serde_json`'s `float_roundtrip`
feature is enabled and a Python `math.pi * 9` fixture pins the exact value
(`spec/value-wire.md` §3).
* Profile change safety relies on the frozen-options unit test; no CI gate
regenerates goldens (intentional).
### P1
* The blueprint asks for a draft Turing-completeness argument. The language
supports mutable locals, branch-first-match, per-item `while` loops and
recursion with bounded budgets; a formal encoding write-up is still missing.
* The default cooperative stack budget is 128 frames so very deep recursion
yields a structured `resource.exhausted` instead of exhausting the debug-build
native stack; `--stack` raises it deliberately. A true guard-page/iterative
interpreter hardening is still open.
### P2
* `fmt` is intentionally minimal (line endings/trailing newlines only), not the
blueprint's "canonical AST-equivalent formatting"; no semantic formatting,
AST-equivalence check or render-preserving rewrite exists.
* Reference validation is opt-in: `check --refs` (and `inspect --refs`) resolve
links; plain `check` does not fail on broken links because links are static
knowledge references rather than execution inputs.
* Link-form calls cannot cross modules; cross-module calls use imported alias
expressions. The blueprint's `> [f](./other.mq.md#f)(...)` example is not
supported.
* `ref("#...")` is module-local and does not accept a selector for units with
multiple resources (it errors with `ref.ambiguous`, ADR-0003).
* No rename tooling, interface lock/ABI diffing, or incremental cache.
* Duplicate/nested project boundaries are not diagnosed (nearest
`marqdo.yaml` wins).
### P3
* Pinned Git dependencies resolve through a content-addressed cache; floating
branches, submodules and dependency install scripts remain unsupported.
* Transitive `@alias` imports resolve from each package's own manifest, but the
lock is still flat; there is no full conflict solver, registry, publishing,
signing, `tree`, `update`, `vendor`, `--offline`, or `lock --locked`.
* `sync` materializes `.marqdo/env` atomically; kernel/session environments are
not materialized.
* `add`/`remove` are shallow manifest editors.
* JSON errors from `add`/`remove`/`lock`/`sync` are plain stderr even with
`--json`.
### P4
* **Strict mode cannot run at all**: no OS isolation adapter (Linux
namespaces/seccomp/cgroups, Windows Job Object/appcontainer, macOS sandbox);
`run --mode strict` exits 1 (ADR-0004). Isolated plugin workers are
implemented but a child process is not an OS sandbox.
* `console` is a capability checked in `op_print`; it is granted by default in
`pure`/`project` mode and is not a bypass of the capability boundary.
* Network capability (`net_hosts`, `check_net`) exists but no host operation
performs network I/O and there is no `--allow-net` flag.
* Write-path symlink TOCTOU caveat (`spec/security.md` §2.1); symlink/race
hardening open.
* Budgets do not cover every allocation path; the interpreter's containers are
bounded only by fuel and available memory.
* Effect trace does not record argument values or paths (privacy-positive, but
less diagnostic detail); trace is opt-in and implicitly on for `--json`.
* `plugin_handle` wire values are structurally reconstructable; authority now
requires the host-owned owner/run/generation table, and untrusted output
containing handles is rejected (ADR-0014).
### P5
* Math is a deliberately limited calculator subset: no `simplify`,
`differentiate`, matrices, sums/integrals, trig/log functions, units,
assumptions or theorem proving. `math.simplify`/`math.differentiate` are
host ops that always return `math.unsupported`.
* Equation solving is affine-only, single target, target must occur exactly
once; other shapes are `math.unsupported`.
* Division by zero inside a formula maps to `runtime.type` (via
`MathErrorKind::Type`), not `runtime.division_by_zero`; documented divergence.
* Foreign kernels are one-shot only: no sessions, state bridge, Python/Node
environment management, or network policy for child processes.
* Foreign child processes form a process group on Unix, so timeout/overflow
kills grandchildren too; non-Unix targets still track only the direct child.
* Foreign per-call timeout (10 s) and output cap (1 MiB) are not CLI-configurable.
### P6
* Native in-process loading still requires explicit trust and a crash is a host
crash. The isolated worker transport (length-prefixed IPC, handshake/call
timeouts) is implemented for crash isolation, not as an OS sandbox.
* Wasm and hot unload/reload remain unsupported.
* The `CapabilityBroker` enforces core grants and vendor policy entries, but no
concrete vendor handler or worker-side capability bridge is shipped.
* Plugin calls are statically validated only with `check --plugin <manifest>`;
without a descriptor a missing export is a runtime `symbol.unknown`.
Positional plugin arguments are rejected.
* Multi-prefix exports are registered by complete name; explicit alias syntax
for two packages using the same export is still pending.
* No plugin installation/package management; `plugins:` in `marqdo.yaml` is
declarative only. No Rust plugin example crate (SDK has doc examples/tests).
* No hot unload/reload (ABI v1 design).
### P7
* Performance work is untouched: no benchmark suite, no bytecode backend or
differential tests against the tree-walker, no parse/compile caching.
* CI exists (`.github/workflows/ci.yml`) and runs fmt/clippy/workspace tests
plus CLI smoke tests on Linux x86_64; missing: Windows/macOS matrix,
sanitizers/fuzz gates, signing, release automation or supply-chain scanning.
* No published version, no compatibility matrix beyond the frozen ABI/format
documents.
## 4. Blueprint §18 "Alpha Definition of Done" mapping
| §18 item | Status | Evidence / gap |
|---|---|---|
| Run/call non-trivial recursive, branch, loop, call, parameter-inference programs without Python | **Met** | factorial/recursion (`examples/factorial.mq.md`, runtime + semantic goldens), countdown loop, multi-module alias call; interpreter is native Rust. |
| `.mq.md` readable under the chosen CommonMark/GFM/Math profile; standard AST behavior covered by goldens | **Met** | frozen `marqdo.md.v1`, 150 AST goldens, profile option test, `spec/markdown-profile.md`. |
| No heuristic downgrade of execution semantics; accurate source locations for invalid execution nodes | **Mostly met** | hard errors with spans for function-body executable shapes and negative corpus. Gaps: inert executable outside functions is a warning by design (ADR-0002); cross-module runtime error spans resolve against the entry file only; some lazy nested nodes are inert without a warning. |
| `check`/`inspect` side-effect free; imports, calls and static references verifiable across files | **Mostly met** | static load/analysis only; imports + cycle detection; cross-module calls validated; `check --refs` validates references across loaded documents and statically analyses link targets; `inspect --refs` prints the entry graph. |
| Minimal manifest, lock file, path/Git dependencies and environment sync | **Partial** | manifest/lock/path works, `sync --locked` verifies; git resolution, transitive deps, environment materialization and `--offline` missing. |
| All host side effects capability-authorized; untrusted code/native plugins cannot masquerade as strict sandbox | **Mostly met** | capability checks at execution points; strict refuses; native plugins require explicit trust and are documented as unsandboxed. Gaps: network enforcement not implemented (no network builtin is exposed); worker isolation is crash isolation, not an OS sandbox. |
| Formula computational subset explicit/testable; Foreign I/O, timeout and permissions explicit | **Met for the documented subset** | `spec/math.md`, `spec/foreign.md`; math kernel tests; foreign tests (timeout, protocol, output cap, env); permission gating tests/smoke. Simplification/differentiation explicitly unsupported. |
| Plugin C ABI v1, Rust SDK, C example, isolated worker basic path, ABI compat error tests | **Partial** | ABI/SDK/C example/loader/ABI-error tests exist; isolated worker with timeout/crash tests exists. Missing: Wasm, vendor handlers, plugin installation. |
| CI has at least one full research pipeline: Markdown function → Math → Foreign → Plugin → controlled output | **Partial** | CI now runs fmt/clippy/tests and CLI smoke tests; individual math/foreign/plugin paths are covered by examples and tests, but no single end-to-end pipeline document/test exists yet. |
| Examples, README, AGENTS and contributor docs allow a first change without legacy context | **Met** | `README.md`, `AGENTS.md`, this guide, `docs/STATUS.md`, specs, ADRs, `tests/README.md`, examples. |
**Conclusion: the Alpha definition of done is not fully met.** P0/P1 and the
documented P5 subset are solid; P2/P3/P4/P6 are functional but partial; P7 is
absent. The blocking items for an Alpha claim are the strict sandbox/worker
isolation story (P4/P6), git/environment package management (P3), and a CI
end-to-end pipeline (P7).
## 5. What is deliberately limited (do not overclaim)
* Only a single, frozen Markdown profile (`marqdo.md.v1`); changing parser
options/versions is a language change.
* Strict mode is a refusal, not an isolation implementation. `project` mode is
cooperative and in-process.
* Native plugins are trusted in-process code and a crash takes down the host.
`kind: worker` isolates crashes/timeouts but is not an OS sandbox.
* Ints are arbitrary precision; finite floats are binary64 and wire round-trip
is exact (`float_roundtrip` enabled), but decimal-vs-binary formatting still
applies when displaying values.
* Math is a limited exact-rational calculator, not a CAS or a prover.
* Foreign kernels are optional, one-shot, unsandboxed child processes.
* `fmt` is minimal; plain `check` does not validate Markdown links (only
`check --refs` does); link-form calls cannot cross modules.
* Package management is path-only in practice; `marqdo.yaml` capabilities are
requests, never grants.
+99
View File
@@ -0,0 +1,99 @@
# Releasing Marqdo CLI
This document describes the release-candidate procedure. It does **not** grant
permission to tag or publish; that requires explicit owner approval and a green
required CI matrix on the exact commit.
## 1. Preconditions
- All applicable G-B gates in
[`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md) §16.1
are PASS with a CI URL for the same SHA.
- G-C is either PASS with a security-lane URL, or the release explicitly says
strict isolation is unavailable. Never claim G-C from local root/sudo runs.
- `git status --porcelain` is clean apart from intended release files.
- `Cargo.lock` is committed and the build uses `--locked`.
## 2. Build verification
```bash
export PATH="$HOME/.cargo/bin:$PATH"
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --locked -p marqdo-cli
```
## 3. Artifact creation
The artifact is a tarball containing the binary, license, README, changelog,
compatibility matrix and specs. Build it from the repository root:
```bash
version="$(cargo metadata --no-deps --format-version 1 \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["packages"][0]["version"])')"
target="$(rustc -vV | sed -n 's/^host: //p')"
stage="dist/marqdo-${version}-${target}"
rm -rf "$stage"
mkdir -p "$stage"
install -m 0755 target/release/marqdo "$stage/"
cp LICENSE* CHANGELOG.md COMPATIBILITY.md README.md "$stage/"
cp -r spec "$stage/"
tar -C dist -czf "dist/marqdo-${version}-${target}.tar.gz" "$(basename "$stage")"
sha256sum "dist/marqdo-${version}-${target}.tar.gz" \
| tee "dist/marqdo-${version}-${target}.tar.gz.sha256"
```
If the repository has no `LICENSE*` files at release time, do not silently
skip the license requirement: add them before shipping.
## 4. Clean-install smoke
Run in a fresh directory (not the source tree):
```bash
tmp="$(mktemp -d)"
tar -C "$tmp" -xzf dist/marqdo-*.tar.gz
cd "$tmp"/marqdo-*
./marqdo --version
./marqdo --help >/dev/null
./marqdo check examples/multi-module/index.mq.md
./marqdo run examples/hello.mq.md
./marqdo call examples/factorial.mq.md 阶乘 --arg n=5
./marqdo check examples/multi-module/index.mq.md --refs --emit analysis.json
./marqdo run examples/multi-module/index.mq.md --trace-file trace.json
python3 /path/to/tests/consumers/analysis_consumer.py analysis.json
python3 /path/to/tests/consumers/trace_consumer.py analysis.json trace.json
```
Also verify the SHA-256 file before extraction:
```bash
sha256sum -c dist/marqdo-*.tar.gz.sha256
```
## 5. Tagging and publication
Only after the above and the remote CI matrix are green on the release commit:
```bash
git fetch origin --tags
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/master)"
git tag -s "v${version}" -m "Marqdo CLI v${version}"
git push origin "v${version}"
# upload the tarball and .sha256 to the release
```
Do not force-push, do not tag a red commit, and do not upload macOS/Windows
binaries unless those platform lanes actually passed.
## 6. Rollback
- If an asset fails verification: delete the release asset and keep the tag
only if source/tag integrity is unaffected; otherwise publish a revised
patch release and mark the old one withdrawn.
- If a platform regresses: remove that platform from the supported matrix in
`COMPATIBILITY.md` and the release notes, fix, and re-run the gate. Never
delete the failing test.
- If the security gate regresses: set strict back to `Unavailable`, publish a
security note, and do not claim isolation until the lane is green again.
+78
View File
@@ -0,0 +1,78 @@
# Linux strict-isolation security gate (G-C) — evidence report
Status: **G-C NOT PASSED. `strict` remains `Unavailable` and fails closed.**
Snapshot: workspace `0.1.0`, 2026-11-20. No release tag.
This report records what was actually probed on the development host and why no
`StrictIsolation::Available` claim is made. It is evidence, not a plan to
weaken the gate.
## 1. Host and capability probe
Command output (abridged; host name removed):
```text
user: uid=0(root) gid=0(root)
kernel: Linux 7.0.0-43-generic x86_64
virt: container-other
apparmor_restrict_unprivileged_userns: 1
max_user_namespaces: 60339
cgroup2 mount: ro,nosuid,nodev,noexec,relatime,nsdelegate,memory_recursiveprot
cgroup controllers: cpuset cpu io memory hugetlb pids rdma misc dmem
unshare --user --map-root-user true
-> unshare: write failed /proc/self/uid_map: Operation not permitted (exit 1)
unshare --user --map-root-user --net true
-> unshare: unshare failed: Operation not permitted (exit 1)
bwrap --unshare-user --unshare-net --ro-bind / / true
-> bwrap: No permissions to create a new namespace (exit 1)
sudo -n true
-> sudo: The "no new privileges" flag is set, which prevents sudo from
running as root (exit 1)
```
The workspace root is writable, but the host root filesystem and cgroup2 mount
are read-only. The process is root inside a container with `no_new_privs` set;
`sudo` cannot gain privileges and the parent container refuses namespace
creation. `user.max_user_namespaces` being non-zero does not help because the
container policy/AppArmor boundary rejects the actual `uid_map` write.
## 2. Consequence
- A real Linux adapter (namespaces + seccomp/no_new_privs + cgroup v2 + fd and
process-tree control) cannot be built, applied and verified here.
- Implementing an adapter and flipping `Available` without executing the escape
and resource-limit tests would be a false security claim. It was not done.
- `PlatformCapabilities::detect()` continues to report `unavailable` with a
reason; `enforce` refuses before any host/plugin is constructed. There is no
fallback to `project`.
- Native plugin loading (`--trust-native-plugin`) is unrelated to strict mode
and remains an explicit in-process trust decision; the broker and worker
transport are not OS isolation.
Command evidence:
```bash
marqdo run examples/hello.mq.md --mode strict
# exit 1, stderr: refusing to run in strict mode: ...
marqdo inspect examples/hello.mq.md --platform --json
# platform.strict.state == "unavailable"
```
## 3. What G-C still requires
1. A controllable Ubuntu VM or self-hosted runner that permits user, mount,
PID and network namespaces and delegated cgroup v2 controllers, reachable
from an ordinary (non-root) test user.
2. A trusted supervisor that applies filesystem/network/process/resource
policy and reaps the child tree, plus a runtime probe that reports the
mechanisms actually applied.
3. Execution of the full negative matrix from
`docs/STABLE_RELEASE_IMPLEMENTATION.md` §10.5 with a malicious helper:
direct syscall reads/writes, `/proc` and inherited-fd access, IPv4/IPv6/DNS
and Unix sockets, fork/exec, CPU/memory/fd/process/output limits, and
`--trust-native-plugin` rejection.
4. A security-lane CI URL on the same commit, and only then an ADR that flips
`Unavailable` to `Available` for that specific platform.
Until all four hold, any release must state: **strict OS isolation is not
available; untrusted code must not be executed with Marqdo expecting isolation.**