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:
1 parent
faa6c95cfe
commit
18d9f39562
14 files changed
+2358
-482
No files matched your search
@@ -3,6 +3,7 @@ name: CI
|
||||
on:
|
||||
push:
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
@@ -107,6 +108,13 @@ jobs:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- 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
|
||||
run: cargo test --workspace
|
||||
- name: Portable CLI, analysis and trace smoke
|
||||
@@ -130,3 +138,57 @@ jobs:
|
||||
test "$code" -eq 1
|
||||
echo "$output" | grep -qi "strict"
|
||||
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
|
||||
@@ -14,3 +14,6 @@ examples/plugin-multi-export/solver.so
|
||||
# Generated plugin fixture manifests/artifacts
|
||||
examples/plugin-demo/build/
|
||||
examples/plugin-multi-export/build/
|
||||
|
||||
# Release artifacts
|
||||
dist/
|
||||
@@ -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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
@@ -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
@@ -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.
|
||||
@@ -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
|
||||
plugin ABI v2 are not claimed to work here.
|
||||
|
||||
> **Status: working implementation, not an Alpha release.** P0/P1 and the
|
||||
> documented Math/Foreign subset are implemented and tested; modules/package/
|
||||
> security/plugin support is functional but partial; strict isolation, worker
|
||||
> plugins, git packages and performance/release work are not done. See
|
||||
> [`docs/STATUS.md`](docs/STATUS.md) and "Deliberate limits" below. The
|
||||
> [stabilization and ecosystem-gate spec](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md)
|
||||
> and the M0.6 extensibility plan in
|
||||
> [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) are
|
||||
> **Proposed** next-phase designs, not implemented feature lists.
|
||||
> **Status: stabilization candidate, not released.** The language, lock v3,
|
||||
> Analysis v2, Trace v2, Tool v1, Plugin ABI v1 (native + worker) and pinned
|
||||
> Foreign providers are implemented and covered by tests on Linux. The
|
||||
> Windows AST and macOS plugin CI failures are fixed in source, but the native
|
||||
> Windows/macOS lanes have not been re-run from this checkout. **`strict` OS
|
||||
> isolation is not available**: it fails closed on every platform (G-C not
|
||||
> passed), and the broker/worker are not a sandbox. See
|
||||
> [`docs/STATUS.md`](docs/STATUS.md), [`COMPATIBILITY.md`](COMPATIBILITY.md)
|
||||
> 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
|
||||
|
||||
@@ -83,21 +84,27 @@ executes anything.
|
||||
`UnitId`/anchors, import cycle detection, multi-module calls,
|
||||
`run/call/check/inspect/fmt`, reference validation (`check --refs`) and the
|
||||
static link graph (`inspect --refs`).
|
||||
* **P3 project** — `marqdo.yaml` validation, deterministic `marqdo.lock` for
|
||||
path dependencies, `init`, `add`/`remove` (manifest editing), `lock`,
|
||||
`sync --locked`.
|
||||
* **P3 project** — lock v3 full transitive package-instance graph for path and
|
||||
pinned Git sources, verified content-addressed Git cache, deterministic
|
||||
`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
|
||||
FS globs with traversal rejection, budgets, effect trace, `pure`/`project`
|
||||
modes, and **`strict` mode refuses to run** because no OS isolation adapter
|
||||
exists.
|
||||
modes, and **`strict` mode fails closed** because no verified OS isolation
|
||||
adapter exists.
|
||||
* **P5 Math/Foreign** — native `Formula` value from `$$...$$`; `math.parse/
|
||||
eval/substitute` over a documented exact-rational subset; one-shot Python/
|
||||
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`),
|
||||
host bindings, Rust SDK (`mq_plugin_entry!`), `plugin.yaml` validation,
|
||||
target-triple + sha256 artifact verification, C demo, and explicitly trusted
|
||||
in-process plugin calls (`--plugin --trust-native-plugin --allow-plugin`).
|
||||
target-triple + sha256 artifact verification, native and isolated worker
|
||||
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:
|
||||
|
||||
@@ -111,14 +118,14 @@ cargo clippy --workspace --all-targets -- -D warnings
|
||||
## Deliberate limits (do not assume)
|
||||
|
||||
* **Strict sandbox is not implemented.** `--mode strict` exits 1; there is no
|
||||
OS isolation or isolated plugin worker. `project` mode is cooperative and
|
||||
in-process.
|
||||
verified OS isolation. `project` mode is cooperative and in-process. Worker
|
||||
plugins provide crash/address-space isolation, not an OS sandbox.
|
||||
* **Native plugins run in-process** and require an explicit unsafe trust flag.
|
||||
A plugin can crash or read the host; a C ABI is not a sandbox.
|
||||
* **Package management is path-only in practice.** Git dependencies can be
|
||||
declared but cannot be resolved/locked; there is no registry, transitive
|
||||
resolution, `--offline`, `tree`, `update` or environment materialization.
|
||||
Manifest `capabilities` are requests, never grants.
|
||||
* **Package management is path + pinned-Git only.** There is no registry,
|
||||
floating-branch resolution, conflict solver, `--offline`, `tree`, `update`,
|
||||
`vendor`, or automatic uv/npm environment creation. Manifest
|
||||
`capabilities` are requests, never grants.
|
||||
* **Reference validation is opt-in**: `check --refs` reports broken links;
|
||||
plain `check` ignores them because links are static knowledge references.
|
||||
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,
|
||||
extension registration, plugin addressing, package identity, repository
|
||||
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)
|
||||
— proposed current-stage spec (Chinese, baseline `0adebe4`): CI/lock/source
|
||||
identity/Tool/sandbox gaps B-01–B-18, H0–H3 workstreams, and the G-A/G-B/G-C
|
||||
release gates. Newer than the M0.6 plan; still design input, not implemented.
|
||||
— historical stabilization spec (baseline `0adebe4`), superseded on current
|
||||
priorities by the stable-release plan.
|
||||
* [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) —
|
||||
proposed M0.6 plan (Chinese): extensibility fixes, callable/package/kernel
|
||||
registration, `marqdo tool`, Analysis/Trace v1, safety and release gates.
|
||||
historical M0.6 plan.
|
||||
* [`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,
|
||||
golden updates, quality gate.
|
||||
* [`docs/STATUS.md`](docs/STATUS.md) — P0–P7 implementation matrix and honest
|
||||
open items; blueprint §18 Alpha checklist.
|
||||
* [`docs/STATUS.md`](docs/STATUS.md) — current work-package status, local
|
||||
evidence and open blockers.
|
||||
* [`docs/adr/`](docs/adr/) — accepted decisions (crate graph, inert executables,
|
||||
`ref` ambiguity, strict refusal, AST normalization, CLI contract, BigInt/wire,
|
||||
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
|
||||
|
||||
./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 \
|
||||
--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
|
||||
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 benchmark run .
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
+112
-431
@@ -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`,
|
||||
`wire_version` 1, Markdown profile `marqdo.md.v1`.
|
||||
Snapshot: **2026-11-20**, workspace version `0.1.0`, no release tag.
|
||||
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
|
||||
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.
|
||||
This file records what was actually executed on the current tree. "Implemented"
|
||||
does not mean "verified on every platform"; the evidence column says which
|
||||
commands were run and where. The historical M0.5 snapshot is preserved at
|
||||
[`history/STATUS-M0.5-snapshot.md`](history/STATUS-M0.5-snapshot.md) and must
|
||||
not be read as current status.
|
||||
|
||||
> **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.
|
||||
## 1. CI baseline and current evidence
|
||||
|
||||
### 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`,
|
||||
2026-11-20), the local gate passed before any M0.6 code change:
|
||||
- Linux `fmt + clippy + workspace tests + smoke`: PASS.
|
||||
- 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
|
||||
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)
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace PASS
|
||||
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
|
||||
example smoke tests. The R0 ADRs are `docs/adr/0008`–`0012` (package identity,
|
||||
callable resolution, plugin export routing, capability broker, kernel
|
||||
providers).
|
||||
Windows checkout reproduction: a fresh local clone with
|
||||
`git -c core.autocrlf=true clone ...` kept goldens at LF, preserved the CRLF
|
||||
byte fixture, and passed all four `conformance_ast` tests. The previous
|
||||
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
|
||||
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.
|
||||
## 2. Work package status
|
||||
|
||||
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
|
||||
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)
|
||||
```
|
||||
## 3. Verified capabilities
|
||||
|
||||
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`.
|
||||
- Frozen Markdown profile `marqdo.md.v1` with 150 AST goldens and explicit
|
||||
CRLF byte semantics.
|
||||
- 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
|
||||
property test (B-01)`).
|
||||
## 4. Open blockers and limits
|
||||
|
||||
### 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
|
||||
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:
|
||||
## 5. Reproduce
|
||||
|
||||
```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
|
||||
export PATH="$HOME/.cargo/bin:$PATH"
|
||||
# On hosts with a read-only $HOME, point CARGO_HOME at a writable directory.
|
||||
cargo fmt --all -- --check
|
||||
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 |
|
||||
|---|---|---|
|
||||
| **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.
|
||||
```bash
|
||||
./target/debug/marqdo check examples/multi-module/index.mq.md --refs --emit /tmp/a.json
|
||||
./target/debug/marqdo run examples/multi-module/index.mq.md --trace-file /tmp/t.json
|
||||
python3 tests/consumers/analysis_consumer.py /tmp/a.json
|
||||
python3 tests/consumers/trace_consumer.py /tmp/a.json /tmp/t.json
|
||||
```
|
||||
+22
-16
@@ -14,12 +14,16 @@ marqdo-cli/
|
||||
├── README.md user-facing quickstart and limits
|
||||
├── docs/
|
||||
│ ├── DEVELOPMENT_BLUEPRINT.md architecture baseline
|
||||
│ ├── CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md current-stage stabilization spec (Proposed)
|
||||
│ ├── NEXT_PHASE_IMPLEMENTATION.md proposed M0.6 plan (Proposed, not implemented)
|
||||
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6
|
||||
│ ├── STATUS.md implementation matrix (P0–P7)
|
||||
│ ├── STABLE_RELEASE_IMPLEMENTATION.md authoritative next-phase/release plan
|
||||
│ ├── STATUS.md current evidence, work packages, blockers
|
||||
│ ├── security-gate.md G-C probe evidence (strict stays closed)
|
||||
│ ├── 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
|
||||
│ └── adr/0001..0015-*.md accepted decisions
|
||||
│ └── adr/0001..0020-*.md accepted decisions
|
||||
├── spec/
|
||||
│ ├── markdown-profile.md frozen parser profile `marqdo.md.v1`
|
||||
│ ├── 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
|
||||
(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
|
||||
$B plugin inspect examples/plugin-demo
|
||||
$B plugin inspect examples/plugin-demo/build
|
||||
$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
|
||||
@@ -291,15 +295,17 @@ file and function; root-only examples (for example `math.mq.md`) define no
|
||||
|
||||
## 9. Known gotchas
|
||||
|
||||
* `.cache/` is the offline cargo cache/target used in this environment; it is
|
||||
not part of the deliverable.
|
||||
* `.cache/` and `.cargo-home/` are local caches used on hosts with a read-only
|
||||
`$HOME`; neither is part of the deliverable.
|
||||
* Foreign availability (`python3`/`node`) and a C compiler (`cc`) determine
|
||||
which tests run; a skipped test is not a passed feature.
|
||||
* The strict sandbox, plugin worker isolation and package registry are not
|
||||
implemented. Do not write docs or tests that pretend they are — see
|
||||
`docs/STATUS.md` and `spec/security.md`.
|
||||
* Runtime error spans in the CLI currently resolve against the entry file only;
|
||||
imported-module error locations are approximate (ADR-0006).
|
||||
which tests run; a skipped test is not a passed feature. Windows Native ABI
|
||||
is explicitly unsupported, not a pass.
|
||||
* Isolated worker plugins exist (crash/address-space isolation + brokered
|
||||
`fs.read`), but they are **not** an OS sandbox. The strict sandbox and a
|
||||
package registry remain unimplemented; strict fails closed. See
|
||||
`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
|
||||
call code, or a float's last digit). A fixture diff for such a quirk is a
|
||||
deliberate change, not a free update.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.**
|
||||
Reference in new issue
Block a user