release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run

REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

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

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

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

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

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
This commit is contained in:
cflmy committed 2026-11-22 02:31:32 +08:00
1 parent 56189b176c
commit 2c7c4f31e7
55 files changed
+3136 -453

No files matched your search

+1 -1
View File
@@ -2,6 +2,6 @@ lock_version: 4
content_profile_version: 1
root:
package: root:multi-module@0.1.0
manifest_digest: 3d11906f34641802949b75de4728ea66a3557671db5c1ca89d6359d58a7a6936
manifest_digest: c97de87f622fec9892622f40f991466da9e79c082f9586653327eb7758fa5ce1
packages: []
root_dependencies: {}
+1 -1
View File
@@ -1,5 +1,5 @@
project:
name: multi-module
version: 0.1.0
marqdo: ">=0.1,<1"
marqdo: ">=3.0.0-beta.1,<4.0.0"
dependencies: {}
+29
View File
@@ -0,0 +1,29 @@
# Provider v2 example (`demo.sensor`)
A resource provider is an **external** process/library pair: the CLI ships
`marqdo-provider-worker`, which loads this C ABI v1 library and speaks the
framed resource protocol. Nothing about `demo.sensor` lives in the Marqdo core,
and selecting the provider is not authorization.
```bash
./examples/provider-demo/build.sh # cc + rustc needed for the host triple
marqdo run examples/provider-demo/demo.mq.md \
--provider examples/provider-demo/build/provider.json \
--allow-provider demo.sensor
# => 5
```
Negative checks (all must fail before the resource call succeeds):
```bash
# No grant:
marqdo run examples/provider-demo/demo.mq.md \
--provider examples/provider-demo/build/provider.json
# A missing or non-sibling helper is fail-closed, never a PATH fallback.
# Unknown provider manifest version:
marqdo run examples/provider-demo/demo.mq.md --provider examples/provider-demo/provider.json
```
`provider.json` in this directory is a template with a zero digest; only the
generated `build/provider.json` names the real artifact and is runnable.
+45
View File
@@ -0,0 +1,45 @@
#!/usr/bin/env bash
# Build the example C resource provider and generate a host-specific
# provider/build/provider.json (schema v2) with the real artifact SHA-256.
#
# The tracked provider.json documents the manifest shape; the generated copy
# under build/ matches the machine that built it. A manifest digest mismatch is
# rejected at run time, never tolerated.
set -euo pipefail
here="$(cd "$(dirname "$0")" && pwd)"
out="$here/build"
mkdir -p "$out/lib"
host="$(rustc -vV | sed -n 's/^host: //p')"
case "$host" in
*windows*) echo "unsupported: the C ABI provider example targets Unix" >&2; exit 3 ;;
*apple-darwin*) ext="dylib"; flags=(-dynamiclib -fPIC) ;;
*) ext="so"; flags=(-shared -fPIC) ;;
esac
artifact="libsensor.$ext"
cc -std=c11 -O2 "${flags[@]}" -o "$out/lib/$artifact" "$here/src/sensor.c"
if command -v sha256sum >/dev/null 2>&1; then
hash="$(sha256sum "$out/lib/$artifact" | cut -d' ' -f1)"
else
hash="$(shasum -a 256 "$out/lib/$artifact" | cut -d' ' -f1)"
fi
cat > "$out/provider.json" <<JSON
{
"schema": "marqdo.provider",
"schema_version": 2,
"name": "demo.sensor",
"version": "0.1.0",
"abi": "c-abi-1",
"transport": "worker",
"kinds": ["demo.sensor"],
"artifacts": [
{
"target": "$host",
"path": "lib/$artifact",
"sha256": "$hash"
}
],
"permissions_requested": []
}
JSON
echo "built $out/lib/$artifact for $host (sha256 $hash)"
echo "now run: marqdo run $here/demo.mq.md --provider $out/provider.json --allow-provider demo.sensor"
+35
View File
@@ -0,0 +1,35 @@
# @knowledge 设备测试
## @exec main
打开独立仓库提供的资源;此标题仅决定文档语义,不涉及 Provider 注册。
`流 = resource.open("demo.sensor", "unit-1", ["read"])`
`内存 = memory.new(1, 1)`
`读取 = resource.read(流, 内存, 0, 5)`
`关闭 = resource.close(流)`
`if not 读取.ok`
`return 读取`
`else`
`if not 关闭.ok`
`return 关闭`
`else`
`if true`
`return 读取.value.count`
`end`
`end`
`end`
+17
View File
@@ -0,0 +1,17 @@
{
"schema": "marqdo.provider",
"schema_version": 2,
"name": "demo.sensor",
"version": "0.1.0",
"abi": "c-abi-1",
"transport": "worker",
"kinds": ["demo.sensor"],
"artifacts": [
{
"target": "x86_64-unknown-linux-gnu",
"path": "lib/libsensor.so",
"sha256": "0000000000000000000000000000000000000000000000000000000000000000"
}
],
"permissions_requested": []
}
+111
View File
@@ -0,0 +1,111 @@
/*
* Conformance resource provider (C ABI v1) for the unknown kind `demo.sensor`.
*
* The host's released `marqdo-provider-worker` helper loads this library and
* serves the framed-JSON resource protocol; the CLI never links this code.
* The provider ABI is re-declared here from the public C ABI specification
* (no standalone header is published yet).
*
* Behaviour used by the fixture:
* open("demo.sensor", "unit-1", ["read"]) -> token
* first read(max_bytes>=5) -> "hello", eof=true
* write(bytes) -> accepted, discarded
* close(token) -> closes exactly once
*/
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#define ABI_VERSION 1
#define MQ_OK 0
#define MQ_ERR 1
static char g_last_error[256];
static int closed = 0;
uint32_t marqdo_resource_provider_abi_version(void) { return ABI_VERSION; }
static int fail(const char *message) {
snprintf(g_last_error, sizeof(g_last_error), "%s", message);
return MQ_ERR;
}
int32_t marqdo_resource_open(
const char *kind,
const char *descriptor,
const char *rights,
uint64_t *token
) {
(void)descriptor;
if (kind == NULL || strcmp(kind, "demo.sensor") != 0) {
return fail("unsupported kind");
}
if (rights == NULL || strstr(rights, "read") == NULL) {
return fail("read right is required");
}
if (token == NULL) {
return fail("token pointer is NULL");
}
*token = 1;
closed = 0;
snprintf(g_last_error, sizeof(g_last_error), "%s", "ok");
return MQ_OK;
}
int32_t marqdo_resource_read(
uint64_t token,
uint8_t *buffer,
uint32_t capacity,
uint32_t *read,
int32_t *eof
) {
static const char payload[] = "hello";
if (token != 1 || buffer == NULL || read == NULL || eof == NULL) {
return fail("invalid read arguments");
}
if (closed) {
return fail("resource is closed");
}
if (capacity < sizeof(payload) - 1) {
return fail("buffer is too small");
}
memcpy(buffer, payload, sizeof(payload) - 1);
*read = (uint32_t)(sizeof(payload) - 1);
*eof = 1;
return MQ_OK;
}
int32_t marqdo_resource_write(
uint64_t token,
const uint8_t *bytes,
uint32_t length,
uint32_t *written
) {
if (token != 1 || written == NULL || (bytes == NULL && length != 0)) {
return fail("invalid write arguments");
}
if (closed) {
return fail("resource is closed");
}
*written = length;
return MQ_OK;
}
int32_t marqdo_resource_close(uint64_t token) {
if (token != 1) {
return fail("unknown token");
}
if (closed) {
return fail("resource is already closed");
}
closed = 1;
return MQ_OK;
}
int32_t marqdo_resource_last_error(char *buffer, uint32_t capacity) {
if (buffer == NULL || capacity == 0) {
return MQ_ERR;
}
snprintf(buffer, capacity, "%s", g_last_error);
return MQ_OK;
}
@@ -0,0 +1,5 @@
## @exec main
`流 = resource.open("demo.sensor", "unit-1", ["read"])`
`return resource.close(流)`
@@ -6,7 +6,7 @@
"command": "sample-knowledge",
"entrypoint": "bin/sample-knowledge",
"compatibility": {
"marqdo": ">=0.1,<1",
"marqdo": ">=3.0.0-beta.1,<4.0.0",
"analysis": [2],
"trace": [2]
}
+1 -1
View File
@@ -6,7 +6,7 @@
"command": "sample-proof",
"entrypoint": "bin/sample-proof",
"compatibility": {
"marqdo": ">=0.1,<1",
"marqdo": ">=3.0.0-beta.1,<4.0.0",
"analysis": [2],
"trace": [2]
}
+1 -1
View File
@@ -6,7 +6,7 @@
"command": "sample-view",
"entrypoint": "bin/sample-view",
"compatibility": {
"marqdo": ">=0.1,<1",
"marqdo": ">=3.0.0-beta.1,<4.0.0",
"analysis": [2],
"trace": [2]
}
+1 -1
View File
@@ -6,6 +6,6 @@
"command": "benchmark",
"entrypoint": "bin/marqdo-benchmark",
"compatibility": {
"marqdo": ">=0.1,<1"
"marqdo": ">=3.0.0-beta.1,<4.0.0"
}
}