Files
cflmy 92bfbf2568 feat(rfc-cm): baseline P0-P3 compute machine, stdlib and resource slices
Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:

- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
  read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
  recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
  write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
  print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
  encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.

Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
2026-11-20 21:16:54 +08:00

395 lines
12 KiB
Rust

//! Public Analysis/Trace v1 black-box contract (spec/analysis-v1.md,
//! spec/trace-v1.md).
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU32, Ordering};
static COUNTER: AtomicU32 = AtomicU32::new(0);
struct TempDir(PathBuf);
impl TempDir {
fn new(tag: &str) -> Self {
let id = COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!(
"marqdo-protocol-test-{}-{id}-{tag}",
std::process::id()
));
std::fs::create_dir_all(&path).unwrap();
Self(path)
}
fn path(&self) -> &Path {
&self.0
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn binary() -> &'static str {
env!("CARGO_BIN_EXE_marqdo")
}
fn cli(dir: &Path, args: &[&str]) -> Output {
Command::new(binary())
.args(args)
.current_dir(dir)
.output()
.expect("run marqdo")
}
fn write(dir: &Path, name: &str, source: &str) -> PathBuf {
let path = dir.join(name);
std::fs::write(&path, source).unwrap();
path
}
const PROGRAM: &str = r#"# 数学
## 加一
`(n)`
*n + 1*
## main
**结果 = 加一(41)**
> 打印("secret-value")
*结果*
"#;
#[test]
fn analysis_is_deterministic_and_has_stable_semantic_nodes() {
let dir = TempDir::new("analysis");
write(dir.path(), "index.mq.md", PROGRAM);
let first = dir.path().join("first.json");
let second = dir.path().join("second.json");
for path in [&first, &second] {
let output = cli(
dir.path(),
&[
"check",
"index.mq.md",
"--refs",
"--emit",
path.to_str().unwrap(),
],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
}
let first_bytes = std::fs::read(&first).unwrap();
let second_bytes = std::fs::read(&second).unwrap();
assert_eq!(first_bytes, second_bytes, "analysis must be deterministic");
let analysis: serde_json::Value = serde_json::from_slice(&first_bytes).unwrap();
assert_eq!(analysis["schema"], "marqdo.analysis");
assert_eq!(analysis["schema_version"], 2);
let module = &analysis["modules"][0];
assert_eq!(module["id"], "root:default::index.mq.md");
assert_eq!(module["package_instance_id"], "root:default");
assert!(
analysis["project"]["root_id"]
.as_str()
.unwrap_or_default()
.starts_with("sha256:"),
"standalone documents use a workspace snapshot identity"
);
assert_eq!(analysis["project"]["identity_kind"], "workspace_snapshot");
assert_eq!(module["functions"].as_array().unwrap().len(), 2);
let main = module["functions"]
.as_array()
.unwrap()
.iter()
.find(|function| function["local_name"] == "main")
.unwrap();
let body = main["body"].as_array().unwrap();
assert_eq!(body.last().unwrap()["kind"], "return");
let calls = module["calls"].as_array().unwrap();
assert!(calls.iter().any(|call| call["state"] == "function"
&& call["target"] == "root:default::index.mq.md::数学.加一"));
// Independent Python consumer, if available.
let consumer = Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.unwrap()
.parent()
.unwrap()
.join("tests/consumers/analysis_consumer.py");
if let Ok(output) = Command::new("python3").arg(&consumer).arg(&first).output() {
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
assert!(String::from_utf8_lossy(&output.stdout).starts_with("functions="));
}
}
#[test]
fn analysis_v2_identity_is_location_independent() {
let first = TempDir::new("analysis-identity-a");
let second = TempDir::new("analysis-identity-b");
let source = "## main\n\n**x = 1**\n\n*x*\n";
for dir in [&first, &second] {
write(
dir.path(),
"marqdo.yaml",
"project:\n name: doc\n version: 0.1.0\n",
);
write(dir.path(), "index.mq.md", source);
}
let mut bytes = Vec::new();
for dir in [&first, &second] {
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
bytes.push(std::fs::read(&target).unwrap());
}
assert_eq!(
bytes[0], bytes[1],
"moving a project must not change Analysis bytes"
);
let text = String::from_utf8(bytes[0].clone()).unwrap();
assert!(
!text.contains(first.path().to_str().unwrap()),
"machine path leaked into Analysis"
);
let analysis: serde_json::Value = serde_json::from_slice(&bytes[0]).unwrap();
assert_eq!(analysis["project"]["root_id"], "root:doc@0.1.0");
assert_eq!(analysis["project"]["identity_kind"], "manifest");
}
#[test]
fn analysis_v2_projects_memory_place_targets_additively() {
let dir = TempDir::new("analysis-place");
let source = "## main\n\n**内存 = memory.new(1, 2)**\n\n**`内存[0] = 7`**\n\n*内存[0]*\n";
write(dir.path(), "index.mq.md", source);
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let analysis: serde_json::Value =
serde_json::from_slice(&std::fs::read(&target).unwrap()).unwrap();
let body = analysis["modules"][0]["functions"][0]["body"]
.as_array()
.expect("body is an array");
assert_eq!(body[0]["target"], "内存");
assert_eq!(body[1]["target"]["kind"], "index");
assert_eq!(body[1]["target"]["base"]["kind"], "variable");
assert_eq!(body[1]["target"]["index"]["kind"], "literal");
assert_eq!(body[1]["target"]["index"]["type"], "int");
}
#[test]
fn analysis_v2_projects_addressable_formula_and_code_resources() {
let dir = TempDir::new("analysis-resources");
let source = r#"## calc
`(x)`
$$A = x + 1$$
```python
print(1)
```
*x*
"#;
write(
dir.path(),
"marqdo.yaml",
"project:\n name: res\n version: 0.1.0\n",
);
write(dir.path(), "index.mq.md", source);
let target = dir.path().join("analysis.json");
let output = cli(
dir.path(),
&["check", "index.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let analysis: serde_json::Value =
serde_json::from_slice(&std::fs::read(&target).unwrap()).unwrap();
let resources = analysis["modules"][0]["resources"].as_array().unwrap();
assert_eq!(resources.len(), 2, "{resources:?}");
let formula = resources
.iter()
.find(|resource| resource["kind"] == "formula")
.unwrap();
let code = resources
.iter()
.find(|resource| resource["kind"] == "code")
.unwrap();
assert_eq!(
formula["id"],
"root:res@0.1.0::index.mq.md#resource:formula-1"
);
assert_eq!(code["id"], "root:res@0.1.0::index.mq.md#resource:code-1");
assert_eq!(formula["module_id"], "root:res@0.1.0::index.mq.md");
assert_eq!(formula["language"], serde_json::Value::Null);
assert_eq!(code["language"], "python");
assert_eq!(formula["content_digest"].as_str().unwrap().len(), 64);
assert_eq!(code["content_digest"].as_str().unwrap().len(), 64);
assert!(
!analysis.to_string().contains("A = x + 1"),
"resource payloads stay in source, not Analysis"
);
}
#[test]
fn trace_v2_budget_truncates_long_loops_without_failing_the_run() {
let dir = TempDir::new("trace-budget");
write(
dir.path(),
"index.mq.md",
"## main\n\n**i = 0**\n\n- `i < 500`\n\n **i = i + 1**\n\n*i*\n",
);
let trace_path = dir.path().join("trace.json");
let output = cli(
dir.path(),
&[
"run",
"index.mq.md",
"--trace-file",
trace_path.to_str().unwrap(),
"--trace-max-events",
"20",
],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let trace: serde_json::Value =
serde_json::from_slice(&std::fs::read(&trace_path).unwrap()).unwrap();
assert_eq!(trace["schema_version"], 2);
assert_eq!(trace["run"]["status"], "ok");
assert_eq!(trace["limits"]["max_events"], 20);
assert_eq!(trace["truncated"]["reason"], "event_budget");
assert_eq!(trace["truncated"]["limit"], 20);
let events = trace["events"].as_array().unwrap();
assert!(events.len() <= 21, "events: {}", events.len());
assert_eq!(events.last().unwrap()["kind"], "trace.truncated");
let mut previous = None;
for event in events {
let seq = event["seq"].as_u64().unwrap();
if let Some(previous) = previous {
assert!(seq > previous);
}
previous = Some(seq);
}
}
#[test]
fn failed_check_removes_stale_analysis() {
let dir = TempDir::new("analysis-error");
write(dir.path(), "bad.mq.md", "## main\n\n1. 没有条件\n");
let target = dir.path().join("analysis.json");
std::fs::write(&target, "stale").unwrap();
let output = cli(
dir.path(),
&["check", "bad.mq.md", "--emit", target.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
assert!(!target.exists(), "stale success artifact must be removed");
}
#[test]
fn trace_records_calls_effects_and_status_without_secrets() {
let dir = TempDir::new("trace");
write(dir.path(), "index.mq.md", PROGRAM);
let trace_path = dir.path().join("trace.json");
let output = cli(
dir.path(),
&[
"run",
"index.mq.md",
"--trace-file",
trace_path.to_str().unwrap(),
],
);
assert_eq!(
output.status.code(),
Some(0),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let text = std::fs::read_to_string(&trace_path).unwrap();
assert!(
!text.contains("secret-value"),
"values must not be recorded"
);
let trace: serde_json::Value = serde_json::from_str(&text).unwrap();
assert_eq!(trace["schema"], "marqdo.trace");
assert_eq!(trace["schema_version"], 2);
assert_eq!(trace["run"]["status"], "ok");
assert_eq!(trace["run"]["entry"], "root:default::index.mq.md::main");
let events = trace["events"].as_array().unwrap();
assert!(events
.iter()
.any(|event| event["kind"] == "call.enter"
&& event["module_id"] == "root:default::index.mq.md"));
assert!(events.iter().any(|event| event["kind"] == "effect"));
assert!(events.iter().any(|event| event["kind"] == "call.exit"));
let mut previous = None;
for event in events {
let seq = event["seq"].as_u64().unwrap();
if let Some(previous) = previous {
assert!(seq > previous);
}
previous = Some(seq);
}
// Error runs still write a terminal trace.
write(dir.path(), "bad.mq.md", "## main\n\n**x = 1 // 0**\n");
let error_trace = dir.path().join("error-trace.json");
let output = cli(
dir.path(),
&[
"run",
"bad.mq.md",
"--trace-file",
error_trace.to_str().unwrap(),
],
);
assert_eq!(output.status.code(), Some(1));
let trace: serde_json::Value =
serde_json::from_slice(&std::fs::read(&error_trace).unwrap()).unwrap();
assert_eq!(trace["run"]["status"], "runtime.division_by_zero");
}