Files
marqdo-cli/docs/developers/compatibility.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

3.4 KiB

Compatibility, versioning and support

This page summarizes the public support policy. The authoritative matrix is ../../COMPATIBILITY.md; the beta policy is ../MARQDO_3_0_PRERELEASE_PLAN.md.

Version axes (do not conflate)

Axis 3.0.0-beta.1 value Change rule
Product / CLI 3.0.0-beta.1 SemVer prerelease; breaking changes inside the 3.0 beta line are allowed and appear in CHANGELOG.md.
Analysis v2 New major for incompatible changes; consumers reject unknown majors.
Trace v2 New major for incompatible changes; binds to exact Analysis bytes.
CLI Tool v1 Frozen manifest/negotiation/bundle contract for v1.
Plugin ABI v1 (1.0) Frozen C layout and version negotiation.
Foreign wire v1 One-shot request envelope.
Provider manifest v2 schema_version: 2, abi: c-abi-1, transport: worker.
Lock v4 v3 requires an explicit marqdo lock migration; no silent reinterpretation.
Markdown profile marqdo.md.v1 Frozen parser/options; the RFC-LANG-0002 mapping rewrite did not change the profile id.
Bundled stdlib 0.1.0 Independent package version; not the product version.
Plugin/tool/example packages their own Independent SemVer.

project.marqdo and a tool's compatibility.marqdo are enforced product ranges. Beta cores require a prerelease range such as >=3.0.0-beta.1,<4.0.0; >=3.0.0,<4.0.0 does not match a beta core.

Platform support (3.0.0-beta.1)

Platform Release status Notes
Linux x86_64 (glibc) Supported Only release archive: CLI + provider worker, same target triple.
Linux aarch64 Not built No artifact; source may build.
macOS arm64/x86_64 Experimental, not claimed Core may run; no macOS provider worker, no plugin ABI claim, no archive.
Windows x86_64 Experimental, not claimed Compile gate only; C ABI/plugin/provider/worker not claimed/fail-closed.

Strict is Linux-only and probe-gated. Plugin/provider worker transports are not OS sandboxes. pure/project are execution modes, not security boundaries.

Language compatibility

3.0.0-beta.1 implements RFC-LANG-0002 only. Pre-RFC .mq.md source (Strong-execute / Emph-return / ordered-list branch / bullet-list loop / block-quote call / first code-span signature) is not executable; there is no --legacy, syntax switch or downgrade path. Migration is a rewrite task documented in ../migration/README.md.

The earlier cflmy/marqdo product line is a different architecture; its source syntax, package format and plugin ABI v2 are not compatible and no hidden compatibility layer is provided.

Beta policy

  • Beta may break behavior with a changelog note; protocols are versioned separately and only change with a new major.
  • No LTS is announced. LTS is a later, evidence-based decision (see the prerelease plan §3.2/§5), not a calendar promise.
  • Known non-security gaps are listed in release-limits.md and in the release notes; unsupported requests must fail closed.
  • G4 performance is a Beta-only WARN on the fixed Woodpecker agent for this release; it is not a general performance guarantee.
  • Every archive is checksummed and records its source SHA and toolchain. Checksums prove integrity only, not publisher identity.