feat(m0.6-r4): public Analysis v1 and Trace v1
- add check --emit with a deterministic, read-only semantic projection: package-aware modules, signatures, normalized bodies, refs, calls, diagnostics and source digests - remove stale analysis artifacts on compile errors; atomic writes - add run/call --trace-file with interpreter call/branch/loop/return events and host effect events under one sequence; redact values and record error status - add Analysis/Trace v1 specs, ADR-0015 and an independent Python consumer - add contract tests for determinism, stale artifacts, trace ordering/status and secret redaction
This commit is contained in:
1 parent
25a1faa6ef
commit
b5a28a9825
16 files changed
+1365
-13
No files matched your search
@@ -179,14 +179,15 @@ tests/ conformance/negative corpus (see tests/README.md)
|
||||
* [`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
|
||||
broker, kernel providers, generic CLI tools, plugin-handle authority).
|
||||
broker, kernel providers, generic CLI tools, plugin-handle authority, public Analysis/Trace v1).
|
||||
* Specs: [`markdown-profile.md`](spec/markdown-profile.md),
|
||||
[`mapping.md`](spec/mapping.md), [`expression.ebnf`](spec/expression.ebnf),
|
||||
[`evaluation.md`](spec/evaluation.md), [`references.md`](spec/references.md),
|
||||
[`value-wire.md`](spec/value-wire.md), [`security.md`](spec/security.md),
|
||||
[`package-format.md`](spec/package-format.md),
|
||||
[`plugin-abi.md`](spec/plugin-abi.md), [`math.md`](spec/math.md),
|
||||
[`foreign.md`](spec/foreign.md), [`tool-v1.md`](spec/tool-v1.md).
|
||||
[`foreign.md`](spec/foreign.md), [`tool-v1.md`](spec/tool-v1.md),
|
||||
[`analysis-v1.md`](spec/analysis-v1.md), [`trace-v1.md`](spec/trace-v1.md).
|
||||
* [`tests/README.md`](tests/README.md) — conformance corpus and `UPDATE_GOLDENS`
|
||||
workflow.
|
||||
|
||||
|
||||
@@ -0,0 +1,579 @@
|
||||
//! Public Analysis v1 projection (spec/analysis-v1.md).
|
||||
//!
|
||||
//! This is deliberately not a serde dump of `marqdo-ir`: the schema and node
|
||||
//! kinds are the public contract, while internal Rust types may change. The
|
||||
//! exporter is read-only and never executes a document, loads a plugin or
|
||||
//! starts a foreign kernel.
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use marqdo_expression::{BinaryOp, Expr, UnaryOp};
|
||||
use marqdo_ir::{CallTarget, Function, Module, SignatureKind, Stmt, UnitKind};
|
||||
use marqdo_span::Span;
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
use crate::loader::LoadedProject;
|
||||
|
||||
/// Schema name and version.
|
||||
pub const SCHEMA: &str = "marqdo.analysis";
|
||||
pub const SCHEMA_VERSION: u32 = 1;
|
||||
|
||||
/// Build the deterministic public projection.
|
||||
pub fn build(project: &LoadedProject) -> Value {
|
||||
let mut modules = Vec::new();
|
||||
for (module_id, file) in &project.files {
|
||||
let module = &file.analysis.module;
|
||||
modules.push(json!({
|
||||
"id": module_id.to_string(),
|
||||
"package_instance_id": module_id.instance,
|
||||
"relative_path": module_id.relative_path,
|
||||
"source_digest": sha256_hex(file.source.as_bytes()),
|
||||
"units": units_json(module),
|
||||
"functions": module.functions.iter().map(function_json).collect::<Vec<_>>(),
|
||||
"imports": module.imports.iter().map(|import| json!({
|
||||
"alias": import.alias,
|
||||
"target": import.target,
|
||||
"span": import.span,
|
||||
"resolved": project.program.resolve_import(module_id, &import.alias).map(ToString::to_string),
|
||||
})).collect::<Vec<_>>(),
|
||||
"references": reference_edges(project, module_id),
|
||||
"calls": module.functions.iter().flat_map(|function| calls_json(project, module, function)).collect::<Vec<_>>(),
|
||||
"resources": module.resources.len(),
|
||||
}));
|
||||
}
|
||||
modules.sort_by(|a, b| {
|
||||
a.get("id")
|
||||
.and_then(Value::as_str)
|
||||
.cmp(&b.get("id").and_then(Value::as_str))
|
||||
});
|
||||
json!({
|
||||
"schema": SCHEMA,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"producer": {
|
||||
"name": "marqdo",
|
||||
"version": env!("CARGO_PKG_VERSION"),
|
||||
"markdown_profile": "marqdo.md.v1",
|
||||
},
|
||||
"project": {
|
||||
"root_id": format!("sha256:{}", sha256_hex(project.root.to_string_lossy().as_bytes())),
|
||||
"lock_digest": lock_digest(project),
|
||||
},
|
||||
"modules": modules,
|
||||
"diagnostics": crate::output::diagnostics_json(&project.diagnostics),
|
||||
})
|
||||
}
|
||||
|
||||
/// Digest of the serialized projection (used by Trace v1 to detect staleness).
|
||||
pub fn digest(project: &LoadedProject) -> String {
|
||||
let bytes = serde_json::to_vec(&build(project)).unwrap_or_default();
|
||||
sha256_hex(&bytes)
|
||||
}
|
||||
|
||||
/// Atomically write the projection. An error must not leave a stale success
|
||||
/// artifact behind.
|
||||
pub fn write(project: &LoadedProject, path: &Path) -> Result<(), String> {
|
||||
let value = build(project);
|
||||
let bytes = serde_json::to_vec_pretty(&value)
|
||||
.map_err(|error| format!("cannot encode analysis: {error}"))?;
|
||||
let parent = path
|
||||
.parent()
|
||||
.filter(|parent| !parent.as_os_str().is_empty())
|
||||
.unwrap_or_else(|| Path::new("."));
|
||||
std::fs::create_dir_all(parent)
|
||||
.map_err(|error| format!("cannot create `{}`: {error}", parent.display()))?;
|
||||
let temporary = parent.join(format!(
|
||||
".{}.tmp-{}",
|
||||
path.file_name()
|
||||
.map(|name| name.to_string_lossy().to_string())
|
||||
.unwrap_or_else(|| "analysis.json".to_string()),
|
||||
std::process::id()
|
||||
));
|
||||
std::fs::write(&temporary, bytes)
|
||||
.map_err(|error| format!("cannot write `{}`: {error}", temporary.display()))?;
|
||||
if let Err(error) = std::fs::rename(&temporary, path) {
|
||||
let _ = std::fs::remove_file(&temporary);
|
||||
return Err(format!("cannot publish `{}`: {error}", path.display()));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn lock_digest(project: &LoadedProject) -> Value {
|
||||
let path = project.root.join(marqdo_package::LOCK_FILE);
|
||||
match std::fs::read(path) {
|
||||
Ok(bytes) => Value::String(format!("sha256:{}", sha256_hex(&bytes))),
|
||||
Err(_) => Value::String(String::new()),
|
||||
}
|
||||
}
|
||||
|
||||
fn units_json(module: &Module) -> Vec<Value> {
|
||||
module
|
||||
.units
|
||||
.iter()
|
||||
.map(|unit| {
|
||||
let kind = match unit.kind {
|
||||
UnitKind::Root => "root",
|
||||
UnitKind::Namespace => "namespace",
|
||||
UnitKind::Function => "function",
|
||||
UnitKind::Section => "section",
|
||||
};
|
||||
json!({
|
||||
"id": unit.id.to_string(),
|
||||
"kind": kind,
|
||||
"name": unit.name,
|
||||
"level": unit.level,
|
||||
"span": span_json(unit.span),
|
||||
"function": unit.function.as_ref().map(ToString::to_string),
|
||||
})
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
fn function_json(function: &Function) -> Value {
|
||||
json!({
|
||||
"id": function.id.to_string(),
|
||||
"unit_id": function.unit.to_string(),
|
||||
"local_name": function.local_name,
|
||||
"namespace": function.namespace,
|
||||
"span": span_json(function.span),
|
||||
"heading_span": span_json(function.heading_span),
|
||||
"signature": {
|
||||
"kind": match function.signature {
|
||||
SignatureKind::Explicit => "explicit",
|
||||
SignatureKind::Inferred => "inferred",
|
||||
},
|
||||
"params": function.params.iter().map(|param| json!({
|
||||
"name": param.name,
|
||||
"required": param.default.is_none(),
|
||||
"type": param.type_annotation,
|
||||
"default": param.default.as_ref().map(expr_json),
|
||||
"span": span_json(param.span),
|
||||
})).collect::<Vec<_>>(),
|
||||
},
|
||||
"effects": ["unknown"],
|
||||
"body": function.body.iter().map(stmt_json).collect::<Vec<_>>(),
|
||||
})
|
||||
}
|
||||
|
||||
fn stmt_json(stmt: &Stmt) -> Value {
|
||||
match stmt {
|
||||
Stmt::Assign {
|
||||
name, value, span, ..
|
||||
} => json!({
|
||||
"kind": "assign",
|
||||
"target": name,
|
||||
"value": expr_json(value),
|
||||
"span": span_json(*span),
|
||||
}),
|
||||
Stmt::Eval { expr, span } => json!({
|
||||
"kind": "expression",
|
||||
"value": expr_json(expr),
|
||||
"span": span_json(*span),
|
||||
}),
|
||||
Stmt::Call { call, span } => json!({
|
||||
"kind": "call_site",
|
||||
"target": call_target_json(&call.target),
|
||||
"args": call.args.iter().map(arg_json).collect::<Vec<_>>(),
|
||||
"span": span_json(*span),
|
||||
}),
|
||||
Stmt::Branch { arms, span } => json!({
|
||||
"kind": "branch",
|
||||
"arms": arms.iter().map(|arm| json!({
|
||||
"condition": expr_json(&arm.condition),
|
||||
"condition_span": span_json(arm.condition_span),
|
||||
"body": arm.body.iter().map(stmt_json).collect::<Vec<_>>(),
|
||||
"span": span_json(arm.span),
|
||||
})).collect::<Vec<_>>(),
|
||||
"span": span_json(*span),
|
||||
}),
|
||||
Stmt::Loop {
|
||||
condition,
|
||||
condition_span,
|
||||
body,
|
||||
span,
|
||||
} => json!({
|
||||
"kind": "loop",
|
||||
"condition": expr_json(condition),
|
||||
"condition_span": span_json(*condition_span),
|
||||
"body": body.iter().map(stmt_json).collect::<Vec<_>>(),
|
||||
"span": span_json(*span),
|
||||
}),
|
||||
Stmt::Return { value, span } => json!({
|
||||
"kind": "return",
|
||||
"value": expr_json(value),
|
||||
"span": span_json(*span),
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
fn expr_json(expr: &Expr) -> Value {
|
||||
let span = span_json(expr.span());
|
||||
match expr {
|
||||
Expr::Int(value) => {
|
||||
json!({"kind":"literal","type":"int","value":value.to_string(),"span":span})
|
||||
}
|
||||
Expr::Float(value) => json!({"kind":"literal","type":"float","value":value,"span":span}),
|
||||
Expr::Text(value) => json!({"kind":"literal","type":"text","value":value,"span":span}),
|
||||
Expr::Bool(value) => json!({"kind":"literal","type":"bool","value":value,"span":span}),
|
||||
Expr::None => json!({"kind":"literal","type":"none","span":span}),
|
||||
Expr::Ident(ident) => {
|
||||
json!({"kind":"variable","name":ident.name,"span":span_json(ident.span)})
|
||||
}
|
||||
Expr::List(items) => {
|
||||
json!({"kind":"list","items":items.iter().map(expr_json).collect::<Vec<_>>(),"span":span})
|
||||
}
|
||||
Expr::Record(entries) => json!({
|
||||
"kind":"record",
|
||||
"entries": entries.iter().map(|entry| json!({
|
||||
"key": entry.key,
|
||||
"key_span": span_json(entry.key_span),
|
||||
"value": expr_json(&entry.value),
|
||||
})).collect::<Vec<_>>(),
|
||||
"span":span
|
||||
}),
|
||||
Expr::Unary { op, operand, .. } => json!({
|
||||
"kind":"unary",
|
||||
"op": unary_name(*op),
|
||||
"operand": expr_json(operand),
|
||||
"span":span
|
||||
}),
|
||||
Expr::Binary {
|
||||
op, left, right, ..
|
||||
} => json!({
|
||||
"kind":"binary",
|
||||
"op": binary_name(*op),
|
||||
"left": expr_json(left),
|
||||
"right": expr_json(right),
|
||||
"span":span
|
||||
}),
|
||||
Expr::Member { base, name, .. } => json!({
|
||||
"kind":"member",
|
||||
"base": expr_json(base),
|
||||
"field": name,
|
||||
"span":span
|
||||
}),
|
||||
Expr::Index { base, index, .. } => json!({
|
||||
"kind":"index",
|
||||
"base": expr_json(base),
|
||||
"index": expr_json(index),
|
||||
"span":span
|
||||
}),
|
||||
Expr::Call { callee, args, .. } => json!({
|
||||
"kind":"call",
|
||||
"callee": expr_json(callee),
|
||||
"args": args.iter().map(arg_json).collect::<Vec<_>>(),
|
||||
"span":span
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
fn arg_json(arg: &marqdo_expression::Arg) -> Value {
|
||||
json!({
|
||||
"name": arg.name,
|
||||
"value": expr_json(&arg.value),
|
||||
"span": span_json(arg.span),
|
||||
})
|
||||
}
|
||||
|
||||
fn call_target_json(target: &CallTarget) -> Value {
|
||||
match target {
|
||||
CallTarget::Function { name } => json!({"kind":"function","name":name}),
|
||||
CallTarget::Qualified {
|
||||
module_alias,
|
||||
function,
|
||||
} => json!({"kind":"qualified","module_alias":module_alias,"function":function}),
|
||||
CallTarget::Resolved { module, function } => {
|
||||
json!({"kind":"resolved","module":module.to_string(),"function":function})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn reference_edges(project: &LoadedProject, module_id: &marqdo_ir::ModuleId) -> Vec<Value> {
|
||||
let Some(file) = project.files.get(module_id) else {
|
||||
return Vec::new();
|
||||
};
|
||||
let parent = file.path.parent().unwrap_or_else(|| Path::new("."));
|
||||
let mut edges = Vec::new();
|
||||
file.analysis.document.root.walk(&mut |node| {
|
||||
let marqdo_markdown::MdKind::Link { url, .. } = &node.kind else {
|
||||
return;
|
||||
};
|
||||
edges.push(resolve_reference(
|
||||
project,
|
||||
module_id,
|
||||
&file.analysis.units,
|
||||
parent,
|
||||
url,
|
||||
node.span,
|
||||
));
|
||||
});
|
||||
edges.sort_by_key(|edge| {
|
||||
edge.get("span")
|
||||
.and_then(|span| span.get("start"))
|
||||
.and_then(Value::as_u64)
|
||||
.unwrap_or(0)
|
||||
});
|
||||
edges
|
||||
}
|
||||
|
||||
fn resolve_reference(
|
||||
project: &LoadedProject,
|
||||
source_module: &marqdo_ir::ModuleId,
|
||||
units: &marqdo_frontend::UnitIndex,
|
||||
parent: &Path,
|
||||
url: &str,
|
||||
span: Span,
|
||||
) -> Value {
|
||||
if let Some(fragment) = url.strip_prefix('#') {
|
||||
let unit = units.anchors.get(fragment).or_else(|| {
|
||||
units
|
||||
.units
|
||||
.iter()
|
||||
.find(|unit| unit.name == fragment)
|
||||
.map(|unit| &unit.id)
|
||||
});
|
||||
return json!({
|
||||
"source": source_module.to_string(),
|
||||
"url": url,
|
||||
"span": span_json(span),
|
||||
"state": if unit.is_some() { "resolved" } else { "unresolved" },
|
||||
"target_module": source_module.to_string(),
|
||||
"target_unit": unit.map(ToString::to_string),
|
||||
});
|
||||
}
|
||||
if url.starts_with("http://") || url.starts_with("https://") {
|
||||
return json!({
|
||||
"source": source_module.to_string(),
|
||||
"url": url,
|
||||
"span": span_json(span),
|
||||
"state": "external",
|
||||
"target_module": null,
|
||||
"target_unit": null,
|
||||
});
|
||||
}
|
||||
let (path_part, fragment) = match url.split_once('#') {
|
||||
Some((path, fragment)) => (path, Some(fragment)),
|
||||
None => (url, None),
|
||||
};
|
||||
let candidate = parent.join(path_part);
|
||||
let Some(target_module) = project.module_id_for_path(&candidate) else {
|
||||
return json!({
|
||||
"source": source_module.to_string(),
|
||||
"url": url,
|
||||
"span": span_json(span),
|
||||
"state": "unresolved",
|
||||
"target_module": null,
|
||||
"target_unit": null,
|
||||
});
|
||||
};
|
||||
let target_units = project
|
||||
.files
|
||||
.get(&target_module)
|
||||
.map(|file| &file.analysis.units);
|
||||
let resolved = match (fragment, target_units) {
|
||||
(None, _) => Some(None),
|
||||
(Some(fragment), Some(units)) => units
|
||||
.anchors
|
||||
.get(fragment)
|
||||
.or_else(|| {
|
||||
units
|
||||
.units
|
||||
.iter()
|
||||
.find(|unit| unit.name == fragment)
|
||||
.map(|unit| &unit.id)
|
||||
})
|
||||
.map(|unit| Some(unit.to_string())),
|
||||
(Some(_), None) => None,
|
||||
};
|
||||
let (state, target_unit) = match resolved {
|
||||
Some(unit) => ("resolved", unit),
|
||||
None => ("unresolved", None),
|
||||
};
|
||||
json!({
|
||||
"source": source_module.to_string(),
|
||||
"url": url,
|
||||
"span": span_json(span),
|
||||
"state": state,
|
||||
"target_module": target_module.to_string(),
|
||||
"target_unit": target_unit,
|
||||
})
|
||||
}
|
||||
|
||||
fn calls_json(project: &LoadedProject, module: &Module, function: &Function) -> Vec<Value> {
|
||||
let mut calls = Vec::new();
|
||||
collect_calls(project, module, function, &function.body, &mut calls);
|
||||
calls.sort_by_key(|call| {
|
||||
call.get("span")
|
||||
.and_then(|span| span.get("start"))
|
||||
.and_then(Value::as_u64)
|
||||
.unwrap_or(0)
|
||||
});
|
||||
calls
|
||||
}
|
||||
|
||||
fn collect_calls(
|
||||
project: &LoadedProject,
|
||||
module: &Module,
|
||||
function: &Function,
|
||||
body: &[Stmt],
|
||||
calls: &mut Vec<Value>,
|
||||
) {
|
||||
for stmt in body {
|
||||
match stmt {
|
||||
Stmt::Assign { value, .. } | Stmt::Eval { expr: value, .. } => {
|
||||
expr_calls(project, module, function, value, calls)
|
||||
}
|
||||
Stmt::Return { value, .. } => expr_calls(project, module, function, value, calls),
|
||||
Stmt::Call { call, span } => calls.push(json!({
|
||||
"function": function.id.to_string(),
|
||||
"span": span_json(*span),
|
||||
"callee": call_target_json(&call.target),
|
||||
"state": "resolved",
|
||||
})),
|
||||
Stmt::Branch { arms, .. } => {
|
||||
for arm in arms {
|
||||
expr_calls(project, module, function, &arm.condition, calls);
|
||||
collect_calls(project, module, function, &arm.body, calls);
|
||||
}
|
||||
}
|
||||
Stmt::Loop {
|
||||
condition, body, ..
|
||||
} => {
|
||||
expr_calls(project, module, function, condition, calls);
|
||||
collect_calls(project, module, function, body, calls);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn expr_calls(
|
||||
project: &LoadedProject,
|
||||
module: &Module,
|
||||
function: &Function,
|
||||
expr: &Expr,
|
||||
calls: &mut Vec<Value>,
|
||||
) {
|
||||
match expr {
|
||||
Expr::Call { callee, args, span } => {
|
||||
let (state, target) = resolve_callee(project, module, callee);
|
||||
calls.push(json!({
|
||||
"function": function.id.to_string(),
|
||||
"span": span_json(*span),
|
||||
"callee": callee_json(callee),
|
||||
"state": state,
|
||||
"target": target,
|
||||
}));
|
||||
for arg in args {
|
||||
expr_calls(project, module, function, &arg.value, calls);
|
||||
}
|
||||
}
|
||||
Expr::Unary { operand, .. } => expr_calls(project, module, function, operand, calls),
|
||||
Expr::Binary { left, right, .. } => {
|
||||
expr_calls(project, module, function, left, calls);
|
||||
expr_calls(project, module, function, right, calls);
|
||||
}
|
||||
Expr::List(items) => {
|
||||
for item in items {
|
||||
expr_calls(project, module, function, item, calls);
|
||||
}
|
||||
}
|
||||
Expr::Record(entries) => {
|
||||
for entry in entries {
|
||||
expr_calls(project, module, function, &entry.value, calls);
|
||||
}
|
||||
}
|
||||
Expr::Member { base, .. } => expr_calls(project, module, function, base, calls),
|
||||
Expr::Index { base, index, .. } => {
|
||||
expr_calls(project, module, function, base, calls);
|
||||
expr_calls(project, module, function, index, calls);
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
fn resolve_callee(
|
||||
project: &LoadedProject,
|
||||
module: &Module,
|
||||
callee: &Expr,
|
||||
) -> (&'static str, Value) {
|
||||
match callee {
|
||||
Expr::Ident(ident) => {
|
||||
if marqdo_ir::builtins::find(&ident.name).is_some() {
|
||||
("builtin", json!(ident.name))
|
||||
} else if let Some(function) = module.function(&ident.name) {
|
||||
("function", json!(function.id.to_string()))
|
||||
} else {
|
||||
("unresolved", Value::Null)
|
||||
}
|
||||
}
|
||||
Expr::Member { base, name, .. } => {
|
||||
if let Expr::Ident(alias) = base.as_ref() {
|
||||
let qualified = format!("{}.{}", alias.name, name);
|
||||
if marqdo_ir::builtins::find(&qualified).is_some() {
|
||||
return ("builtin", json!(qualified));
|
||||
}
|
||||
if let Some(target_module) = project.program.resolve_import(&module.id, &alias.name)
|
||||
{
|
||||
if let Some(target) = project.program.module(target_module) {
|
||||
if let Some(function) = target.function(name) {
|
||||
return ("function", json!(function.id.to_string()));
|
||||
}
|
||||
}
|
||||
}
|
||||
if project.program.external_callable(&qualified).is_some() {
|
||||
return ("plugin", json!(qualified));
|
||||
}
|
||||
}
|
||||
("unresolved", Value::Null)
|
||||
}
|
||||
_ => ("unresolved", Value::Null),
|
||||
}
|
||||
}
|
||||
|
||||
fn callee_json(callee: &Expr) -> Value {
|
||||
match callee {
|
||||
Expr::Ident(ident) => json!({"kind":"ident","name":ident.name}),
|
||||
Expr::Member { base, name, .. } => {
|
||||
json!({"kind":"member","base":callee_json(base),"field":name})
|
||||
}
|
||||
other => json!({"kind":"expression","span":span_json(other.span())}),
|
||||
}
|
||||
}
|
||||
|
||||
fn span_json(span: Span) -> Value {
|
||||
json!({"start": span.start, "end": span.end})
|
||||
}
|
||||
|
||||
fn unary_name(op: UnaryOp) -> &'static str {
|
||||
match op {
|
||||
UnaryOp::Not => "not",
|
||||
UnaryOp::Neg => "neg",
|
||||
UnaryOp::Pos => "pos",
|
||||
}
|
||||
}
|
||||
|
||||
fn binary_name(op: BinaryOp) -> &'static str {
|
||||
match op {
|
||||
BinaryOp::Or => "or",
|
||||
BinaryOp::And => "and",
|
||||
BinaryOp::Eq => "eq",
|
||||
BinaryOp::Ne => "ne",
|
||||
BinaryOp::Lt => "lt",
|
||||
BinaryOp::Le => "le",
|
||||
BinaryOp::Gt => "gt",
|
||||
BinaryOp::Ge => "ge",
|
||||
BinaryOp::Add => "add",
|
||||
BinaryOp::Sub => "sub",
|
||||
BinaryOp::Mul => "mul",
|
||||
BinaryOp::Div => "div",
|
||||
BinaryOp::FloorDiv => "floor_div",
|
||||
BinaryOp::Mod => "mod",
|
||||
BinaryOp::Pow => "pow",
|
||||
}
|
||||
}
|
||||
|
||||
fn sha256_hex(bytes: &[u8]) -> String {
|
||||
let mut hasher = Sha256::new();
|
||||
hasher.update(bytes);
|
||||
hex::encode(hasher.finalize())
|
||||
}
|
||||
@@ -38,6 +38,8 @@ pub struct SandboxSettings {
|
||||
pub plugins: Vec<PathBuf>,
|
||||
/// Explicit trust decision for in-process native plugin loading.
|
||||
pub trust_native_plugin: bool,
|
||||
/// Optional Trace v1 output path.
|
||||
pub trace_file: Option<PathBuf>,
|
||||
}
|
||||
|
||||
impl SandboxSettings {
|
||||
@@ -266,7 +268,13 @@ fn plugin_signature(raw: &str) -> Result<marqdo_ir::callable::CallableSignature,
|
||||
}
|
||||
|
||||
/// `marqdo check`.
|
||||
pub fn check(file: Option<&Path>, json: bool, refs: bool, plugins: &[PathBuf]) -> i32 {
|
||||
pub fn check(
|
||||
file: Option<&Path>,
|
||||
json: bool,
|
||||
refs: bool,
|
||||
plugins: &[PathBuf],
|
||||
emit: Option<&Path>,
|
||||
) -> i32 {
|
||||
let mut project = match load_project(file, json) {
|
||||
Ok(project) => project,
|
||||
Err(code) => return code,
|
||||
@@ -284,6 +292,14 @@ pub fn check(file: Option<&Path>, json: bool, refs: bool, plugins: &[PathBuf]) -
|
||||
project.diagnostics.extend(ref_diagnostics);
|
||||
}
|
||||
let errors = output::error_count(&project.diagnostics);
|
||||
if let Some(path) = emit {
|
||||
if errors > 0 {
|
||||
let _ = std::fs::remove_file(path);
|
||||
} else if let Err(error) = crate::analysis::write(&project, path) {
|
||||
eprintln!("error: {error}");
|
||||
return 2;
|
||||
}
|
||||
}
|
||||
if json {
|
||||
output::print_json(&json!({
|
||||
"command": "check",
|
||||
@@ -667,7 +683,7 @@ pub fn execute(
|
||||
}
|
||||
};
|
||||
let mut host = StdHost::new(mode, capabilities, project.root.clone());
|
||||
if trace || json {
|
||||
if trace || json || settings.trace_file.is_some() {
|
||||
host = host.with_trace();
|
||||
}
|
||||
if let Some(fuel) = settings.fuel {
|
||||
@@ -745,6 +761,17 @@ pub fn execute(
|
||||
&function_name,
|
||||
runtime_args,
|
||||
);
|
||||
if let Some(path) = &settings.trace_file {
|
||||
let status = match &result {
|
||||
Ok(_) => "ok",
|
||||
Err(error) => error.code(),
|
||||
};
|
||||
let entry = format!("{}::{}", project.entry, function_name);
|
||||
if let Err(error) = crate::trace::write(&project, &host, &entry, status, path) {
|
||||
eprintln!("error: {error}");
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
let stdout = host.take_output();
|
||||
let stdout_text = String::from_utf8_lossy(&stdout).to_string();
|
||||
let trace_entries = host.trace().to_vec();
|
||||
|
||||
+16
-3
@@ -4,11 +4,13 @@
|
||||
//! diagnostics (`check`/`inspect`) or executes through the runtime and
|
||||
//! capability host (`run`/`call`). It never holds a second interpreter.
|
||||
|
||||
mod analysis;
|
||||
mod args;
|
||||
mod commands;
|
||||
mod loader;
|
||||
mod output;
|
||||
mod tool;
|
||||
mod trace;
|
||||
|
||||
use std::ffi::OsString;
|
||||
use std::path::PathBuf;
|
||||
@@ -96,6 +98,9 @@ struct SandboxArgs {
|
||||
/// Explicitly trusted plugin manifest/directory to load (repeatable).
|
||||
#[arg(long = "plugin", value_name = "PATH")]
|
||||
plugin: Vec<PathBuf>,
|
||||
/// Write a versioned Trace v1 file for this run.
|
||||
#[arg(long = "trace-file", value_name = "PATH")]
|
||||
trace_file: Option<PathBuf>,
|
||||
/// Explicitly trust in-process native plugin loading (unsafe by nature).
|
||||
#[arg(long = "trust-native-plugin")]
|
||||
trust_native_plugin: bool,
|
||||
@@ -115,6 +120,7 @@ impl SandboxArgs {
|
||||
timeout: self.timeout,
|
||||
plugins: self.plugin.clone(),
|
||||
trust_native_plugin: self.trust_native_plugin,
|
||||
trace_file: self.trace_file.clone(),
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -162,6 +168,9 @@ struct CheckArgs {
|
||||
/// Declare a plugin manifest for static export-signature checking.
|
||||
#[arg(long = "plugin", value_name = "PATH")]
|
||||
plugin: Vec<PathBuf>,
|
||||
/// Write the public Analysis v1 projection (only on successful check).
|
||||
#[arg(long, value_name = "PATH")]
|
||||
emit: Option<PathBuf>,
|
||||
/// Machine readable JSON output.
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
@@ -313,9 +322,13 @@ fn main() {
|
||||
let cli = Cli::parse();
|
||||
let code = match cli.command {
|
||||
Command::Init(args) => commands::init(args.dir.as_deref()),
|
||||
Command::Check(args) => {
|
||||
commands::check(args.file.as_deref(), args.json, args.refs, &args.plugin)
|
||||
}
|
||||
Command::Check(args) => commands::check(
|
||||
args.file.as_deref(),
|
||||
args.json,
|
||||
args.refs,
|
||||
&args.plugin,
|
||||
args.emit.as_deref(),
|
||||
),
|
||||
Command::Inspect(args) => {
|
||||
let flags = commands::InspectFlags {
|
||||
ast: args.ast,
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
//! Public Trace v1 writer (spec/trace-v1.md).
|
||||
//!
|
||||
//! Events come from the interpreter (semantic) and the capability host
|
||||
//! (effects). No argument values, secrets or handles are recorded.
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use marqdo_host::{Host, SemanticEvent, StdHost, TraceEntry};
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
use crate::loader::LoadedProject;
|
||||
|
||||
/// Schema name and version.
|
||||
pub const SCHEMA: &str = "marqdo.trace";
|
||||
pub const SCHEMA_VERSION: u32 = 1;
|
||||
|
||||
/// Write a trace atomically for one run.
|
||||
pub fn write(
|
||||
project: &LoadedProject,
|
||||
host: &StdHost,
|
||||
entry: &str,
|
||||
status: &str,
|
||||
path: &Path,
|
||||
) -> Result<(), String> {
|
||||
let run_id = format!(
|
||||
"{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|duration| duration.as_nanos())
|
||||
.unwrap_or(0)
|
||||
);
|
||||
let analysis_digest = crate::analysis::digest(project);
|
||||
let root_id = format!(
|
||||
"sha256:{}",
|
||||
sha256_hex(project.root.to_string_lossy().as_bytes())
|
||||
);
|
||||
let mut events: Vec<Value> = host
|
||||
.semantic_events()
|
||||
.iter()
|
||||
.map(semantic_json)
|
||||
.chain(host.trace().iter().map(effect_json))
|
||||
.collect();
|
||||
events.sort_by_key(|event| event.get("seq").and_then(Value::as_u64).unwrap_or(u64::MAX));
|
||||
let trace = json!({
|
||||
"schema": SCHEMA,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"run": {"id": run_id, "entry": entry, "status": status},
|
||||
"source": {"root_id": root_id, "analysis_digest": format!("sha256:{analysis_digest}")},
|
||||
"events": events,
|
||||
});
|
||||
let bytes = serde_json::to_vec_pretty(&trace)
|
||||
.map_err(|error| format!("cannot encode trace: {error}"))?;
|
||||
atomic_write(path, &bytes)
|
||||
}
|
||||
|
||||
fn semantic_json(event: &SemanticEvent) -> Value {
|
||||
json!({
|
||||
"seq": event.seq,
|
||||
"kind": event.kind,
|
||||
"function_id": event.function_id,
|
||||
"span": event.span.map(|span| json!({"start": span.start, "end": span.end})),
|
||||
"detail": event.detail,
|
||||
})
|
||||
}
|
||||
|
||||
fn effect_json(entry: &TraceEntry) -> Value {
|
||||
json!({
|
||||
"seq": entry.seq,
|
||||
"kind": "effect",
|
||||
"module": entry.module,
|
||||
"span": entry.span.map(|span| json!({"start": span.start, "end": span.end})),
|
||||
"detail": entry.result,
|
||||
"operation": entry.op,
|
||||
"duration_micros": entry.duration_micros,
|
||||
})
|
||||
}
|
||||
|
||||
fn atomic_write(path: &Path, bytes: &[u8]) -> Result<(), String> {
|
||||
let parent = path
|
||||
.parent()
|
||||
.filter(|parent| !parent.as_os_str().is_empty())
|
||||
.unwrap_or_else(|| Path::new("."));
|
||||
std::fs::create_dir_all(parent)
|
||||
.map_err(|error| format!("cannot create `{}`: {error}", parent.display()))?;
|
||||
let temporary = parent.join(format!(
|
||||
".{}.tmp-{}",
|
||||
path.file_name()
|
||||
.map(|name| name.to_string_lossy().to_string())
|
||||
.unwrap_or_else(|| "trace.json".to_string()),
|
||||
std::process::id()
|
||||
));
|
||||
std::fs::write(&temporary, bytes)
|
||||
.map_err(|error| format!("cannot write `{}`: {error}", temporary.display()))?;
|
||||
if let Err(error) = std::fs::rename(&temporary, path) {
|
||||
let _ = std::fs::remove_file(&temporary);
|
||||
return Err(format!("cannot publish `{}`: {error}", path.display()));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn sha256_hex(bytes: &[u8]) -> String {
|
||||
let mut hasher = Sha256::new();
|
||||
hasher.update(bytes);
|
||||
hex::encode(hasher.finalize())
|
||||
}
|
||||
@@ -0,0 +1,207 @@
|
||||
//! 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"], 1);
|
||||
let module = &analysis["modules"][0];
|
||||
assert_eq!(module["id"], "root:default::index.mq.md");
|
||||
assert_eq!(module["package_instance_id"], "root:default");
|
||||
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 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"], 1);
|
||||
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"));
|
||||
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");
|
||||
}
|
||||
@@ -17,7 +17,7 @@ use crate::capability::{Capabilities, CapabilityAudit, CapabilityBroker};
|
||||
use crate::context::ExecutionContext;
|
||||
use crate::fs::ProjectFs;
|
||||
use crate::handles::{contains_plugin_handle, PluginHandleTable};
|
||||
use crate::trace::{EffectTrace, TraceEntry};
|
||||
use crate::trace::{EffectTrace, SemanticEvent, TraceEntry};
|
||||
use marqdo_sandbox::{PlatformCapabilities, SandboxMode};
|
||||
|
||||
/// Host operations reachable from the language surface.
|
||||
@@ -90,6 +90,21 @@ pub trait Host {
|
||||
|
||||
/// Recorded effects.
|
||||
fn trace(&self) -> &[TraceEntry];
|
||||
|
||||
/// Record one semantic event (Trace v1). Default: ignored.
|
||||
fn record_semantic(
|
||||
&mut self,
|
||||
_kind: &str,
|
||||
_function_id: Option<&str>,
|
||||
_span: Option<Span>,
|
||||
_detail: Option<&str>,
|
||||
) {
|
||||
}
|
||||
|
||||
/// Recorded semantic events. Default: empty.
|
||||
fn semantic_events(&self) -> &[SemanticEvent] {
|
||||
&[]
|
||||
}
|
||||
}
|
||||
|
||||
/// Default capability host implementation.
|
||||
@@ -124,6 +139,8 @@ pub struct StdHost {
|
||||
broker_audit: Arc<Mutex<Vec<CapabilityAudit>>>,
|
||||
/// Host-issued opaque plugin handles.
|
||||
pub handles: PluginHandleTable,
|
||||
semantic_events: Vec<SemanticEvent>,
|
||||
next_event_seq: u64,
|
||||
}
|
||||
|
||||
struct PluginSlot {
|
||||
@@ -164,6 +181,8 @@ impl StdHost {
|
||||
vendor_capabilities: BTreeSet::new(),
|
||||
broker_audit: Arc::new(Mutex::new(Vec::new())),
|
||||
handles: PluginHandleTable::default(),
|
||||
semantic_events: Vec::new(),
|
||||
next_event_seq: 0,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -270,6 +289,17 @@ impl StdHost {
|
||||
exports
|
||||
}
|
||||
|
||||
/// Recorded semantic events (Trace v1).
|
||||
pub fn semantic_events(&self) -> &[SemanticEvent] {
|
||||
&self.semantic_events
|
||||
}
|
||||
|
||||
fn next_seq(&mut self) -> u64 {
|
||||
let seq = self.next_event_seq;
|
||||
self.next_event_seq += 1;
|
||||
seq
|
||||
}
|
||||
|
||||
/// Audited plugin capability decisions.
|
||||
pub fn capability_audit(&self) -> Vec<CapabilityAudit> {
|
||||
self.broker_audit
|
||||
@@ -436,12 +466,14 @@ impl Host for StdHost {
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
let started = Instant::now();
|
||||
let seq = self.next_seq();
|
||||
let result = self.dispatch(op, args, ctx);
|
||||
let summary = match &result {
|
||||
Ok(_) => "ok".to_string(),
|
||||
Err(error) => error.code().to_string(),
|
||||
};
|
||||
self.trace.record(
|
||||
seq,
|
||||
op.name(),
|
||||
ctx.module_id.clone(),
|
||||
ctx.span,
|
||||
@@ -470,6 +502,27 @@ impl Host for StdHost {
|
||||
fn trace(&self) -> &[TraceEntry] {
|
||||
self.trace.entries()
|
||||
}
|
||||
|
||||
fn record_semantic(
|
||||
&mut self,
|
||||
kind: &str,
|
||||
function_id: Option<&str>,
|
||||
span: Option<Span>,
|
||||
detail: Option<&str>,
|
||||
) {
|
||||
let seq = self.next_seq();
|
||||
self.semantic_events.push(SemanticEvent {
|
||||
seq,
|
||||
kind: kind.to_string(),
|
||||
function_id: function_id.map(str::to_string),
|
||||
span,
|
||||
detail: detail.map(str::to_string),
|
||||
});
|
||||
}
|
||||
|
||||
fn semantic_events(&self) -> &[SemanticEvent] {
|
||||
&self.semantic_events
|
||||
}
|
||||
}
|
||||
|
||||
fn map_plugin_error(error: PluginError) -> RuntimeError {
|
||||
|
||||
@@ -20,4 +20,4 @@ pub use fs::ProjectFs;
|
||||
pub use handles::{contains_plugin_handle, PluginHandleTable};
|
||||
pub use host::{arity, expect_text, Host, HostOp, StdHost};
|
||||
pub use marqdo_sandbox::{PlatformCapabilities, SandboxMode, StrictIsolation};
|
||||
pub use trace::{EffectTrace, TraceEntry};
|
||||
pub use trace::{EffectTrace, SemanticEvent, TraceEntry};
|
||||
@@ -8,6 +8,9 @@ use serde::{Deserialize, Serialize};
|
||||
/// One recorded host effect.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
pub struct TraceEntry {
|
||||
/// Global event sequence within the run.
|
||||
#[serde(default)]
|
||||
pub seq: u64,
|
||||
/// Operation name (`print`, `fs.read`, `foreign.call`, ...).
|
||||
pub op: String,
|
||||
/// Module that initiated it.
|
||||
@@ -41,6 +44,7 @@ impl EffectTrace {
|
||||
/// Record an effect.
|
||||
pub fn record(
|
||||
&mut self,
|
||||
seq: u64,
|
||||
op: impl Into<String>,
|
||||
module: impl Into<String>,
|
||||
span: Option<Span>,
|
||||
@@ -51,6 +55,7 @@ impl EffectTrace {
|
||||
return;
|
||||
}
|
||||
self.entries.push(TraceEntry {
|
||||
seq,
|
||||
op: op.into(),
|
||||
module: module.into(),
|
||||
span,
|
||||
@@ -64,3 +69,18 @@ impl EffectTrace {
|
||||
&self.entries
|
||||
}
|
||||
}
|
||||
|
||||
/// One semantic event emitted by the interpreter (Trace v1).
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct SemanticEvent {
|
||||
/// Global event sequence within the run.
|
||||
pub seq: u64,
|
||||
/// Stable event kind (`call.enter`, `call.exit`, `branch.eval`, ...).
|
||||
pub kind: String,
|
||||
/// Canonical function id, when inside a call.
|
||||
pub function_id: Option<String>,
|
||||
/// Source span, when known.
|
||||
pub span: Option<Span>,
|
||||
/// Non-sensitive detail (`ok`, `true`, `int`, an error code).
|
||||
pub detail: Option<String>,
|
||||
}
|
||||
@@ -122,9 +122,12 @@ impl<'a> Interpreter<'a> {
|
||||
call_span: Option<Span>,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
let display = function.id.name.clone();
|
||||
let trace_id = function.id.to_string();
|
||||
if self.depth + 1 > 0 {
|
||||
self.host.check_stack(self.depth + 1, call_span)?;
|
||||
}
|
||||
self.host
|
||||
.record_semantic("call.enter", Some(&trace_id), call_span, None);
|
||||
let locals = self.bind_args(function, args, call_span)?;
|
||||
let mut frame = Frame {
|
||||
function: function.id.clone(),
|
||||
@@ -134,6 +137,13 @@ impl<'a> Interpreter<'a> {
|
||||
self.depth += 1;
|
||||
let result = self.exec_stmts(program, &function.body, &mut frame);
|
||||
self.depth -= 1;
|
||||
let status = match &result {
|
||||
Ok(Flow::Next) => "ok",
|
||||
Ok(Flow::Return(_)) => "return",
|
||||
Err(error) => error.code(),
|
||||
};
|
||||
self.host
|
||||
.record_semantic("call.exit", Some(&trace_id), call_span, Some(status));
|
||||
match result {
|
||||
Ok(Flow::Next) => Ok(Value::Unit),
|
||||
Ok(Flow::Return(value)) => Ok(value),
|
||||
@@ -250,8 +260,14 @@ impl<'a> Interpreter<'a> {
|
||||
Stmt::Call { call, span } => {
|
||||
self.exec_call_site(program, call, *span, frame)?;
|
||||
}
|
||||
Stmt::Return { value, .. } => {
|
||||
Stmt::Return { value, span } => {
|
||||
let value = self.eval_expr(value, frame)?;
|
||||
self.host.record_semantic(
|
||||
"return",
|
||||
Some(&frame.function.to_string()),
|
||||
Some(*span),
|
||||
Some(value.type_name()),
|
||||
);
|
||||
return Ok(Flow::Return(value));
|
||||
}
|
||||
Stmt::Branch { arms, .. } => {
|
||||
@@ -267,6 +283,12 @@ impl<'a> Interpreter<'a> {
|
||||
),
|
||||
));
|
||||
};
|
||||
self.host.record_semantic(
|
||||
"branch.eval",
|
||||
Some(&frame.function.to_string()),
|
||||
Some(arm.condition_span),
|
||||
Some(if condition { "true" } else { "false" }),
|
||||
);
|
||||
if condition {
|
||||
match self.exec_stmts(program, &arm.body, frame)? {
|
||||
Flow::Next => break,
|
||||
@@ -290,6 +312,12 @@ impl<'a> Interpreter<'a> {
|
||||
format!("loop condition must be Bool, got {}", value.type_name()),
|
||||
));
|
||||
};
|
||||
self.host.record_semantic(
|
||||
"loop.iteration",
|
||||
Some(&frame.function.to_string()),
|
||||
Some(*condition_span),
|
||||
Some(if value { "continue" } else { "exit" }),
|
||||
);
|
||||
if !value {
|
||||
break;
|
||||
}
|
||||
|
||||
+1
-1
@@ -43,7 +43,7 @@ providers).
|
||||
| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
|
||||
| R2 ABI/Kernel/Broker | **In progress** | `KernelRegistry` external providers; complete-name plugin export routing; `CapabilityBroker` with vendor policy; static `check --plugin` signatures; multi-export C test; provider tests. Isolated worker and handle table still pending |
|
||||
| R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking |
|
||||
| R4 Analysis/Trace v1 | Not started | — |
|
||||
| R4 Analysis/Trace v1 | **Done** | `check --emit` Analysis v1; `run/call --trace-file` Trace v1; deterministic schema tests; independent Python consumer; stale-artifact removal; value redaction |
|
||||
| R5 environment/isolation | Not started | — |
|
||||
| R6 release/consumers | Not started | — |
|
||||
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# ADR-0015: Public Analysis v1 and Trace v1
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-20
|
||||
|
||||
## Context
|
||||
|
||||
Knowledge/Proof/View must consume semantic data without linking private Rust
|
||||
crates or reverse-engineering `inspect --ir`. M0.5 has no stable projection and
|
||||
the internal IR may change freely. At the same time tracing execution must not
|
||||
become a second interpreter or leak values/secrets.
|
||||
|
||||
## Decision
|
||||
|
||||
### Analysis v1
|
||||
|
||||
`marqdo check <file> --emit <path>` writes `spec/analysis-v1.md`:
|
||||
|
||||
* read-only, static, no execution/plugin dlopen/foreign spawn;
|
||||
* package-aware module identity, source digests, units, function signatures,
|
||||
normalized body nodes, imports, resolved/unresolved/external references,
|
||||
call edges and diagnostics;
|
||||
* deterministic byte-for-byte output, atomic write, no artifact on error;
|
||||
* `schema_version` is a major version; additive optional fields are allowed,
|
||||
removals/changes require a bump;
|
||||
* normalized nodes (`literal`, `variable`, `binary`, `call`, `assign`,
|
||||
`branch`, `loop`, `return`, ...) are the contract, not Rust enum serde.
|
||||
|
||||
### Trace v1
|
||||
|
||||
`marqdo run/call --trace-file <path>` writes `spec/trace-v1.md`:
|
||||
|
||||
* optional, versioned, atomic; only execution produces it;
|
||||
* semantic events from the interpreter and effect events from the host share a
|
||||
global sequence; function ids are canonical;
|
||||
* values, secrets and handles are never recorded; effect detail is only a
|
||||
result summary;
|
||||
* a failed run records its terminal status; it is never marked successful;
|
||||
* `source.analysis_digest` lets consumers detect a stale trace;
|
||||
* existing `--trace` human/JSON effect output is unchanged.
|
||||
|
||||
## Alternatives
|
||||
|
||||
1. Expose `marqdo-ir` serde directly. Rejected: locks external repos to Rust
|
||||
implementation details and private optimization.
|
||||
2. Make View call `run` in read-only mode to derive structure. Rejected:
|
||||
read-only rendering must not execute; use Analysis.
|
||||
3. Put arguments/values in traces. Rejected by default privacy policy.
|
||||
4. Add `analyze`/`trace` top-level commands. Rejected: `check --emit` and
|
||||
`--trace-file` are flags on existing paths.
|
||||
|
||||
## Compatibility
|
||||
|
||||
New optional CLI flags and new spec files. No existing language semantics
|
||||
change. Internal IR changes must keep the protocol tests green; breaking the
|
||||
public schema requires Analysis/Trace v2 and version negotiation.
|
||||
|
||||
## Security
|
||||
|
||||
Both exporters are subject to the static/execution boundary: Analysis never
|
||||
executes; Trace only observes an already-authorized run. Knowledge/Proof/View
|
||||
gain no capability from reading either artifact. A trace is evidence of an
|
||||
observed run, not a proof of purity or correctness.
|
||||
|
||||
## Testing
|
||||
|
||||
`crates/cli/tests/analysis_trace.rs` checks determinism, identity, semantic
|
||||
nodes, stale-artifact removal, trace sequencing/status and value redaction.
|
||||
`tests/consumers/analysis_consumer.py` is an independent Python consumer.
|
||||
|
||||
## Migration & rollout
|
||||
|
||||
R4 implements both protocols for the current language subset. Proof-specific
|
||||
extensions or richer View events are additive optional fields or a v2 ADR; the
|
||||
core does not add Knowledge/Proof/View business logic.
|
||||
@@ -18,7 +18,7 @@ marqdo-cli/
|
||||
│ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6
|
||||
│ ├── STATUS.md implementation matrix (P0–P7)
|
||||
│ ├── contributor-guide.md this file
|
||||
│ └── adr/0001..0014-*.md accepted decisions
|
||||
│ └── adr/0001..0015-*.md accepted decisions
|
||||
├── spec/
|
||||
│ ├── markdown-profile.md frozen parser profile `marqdo.md.v1`
|
||||
│ ├── mapping.md AST → program roles
|
||||
@@ -31,7 +31,9 @@ marqdo-cli/
|
||||
│ ├── plugin-abi.md C ABI v1, SDK, host lifecycle
|
||||
│ ├── math.md Formula subset and math.* semantics
|
||||
│ ├── foreign.md Python/Node kernel protocol
|
||||
│ └── tool-v1.md proposed generic external Tool Protocol
|
||||
│ ├── tool-v1.md generic external Tool Protocol v1
|
||||
│ ├── analysis-v1.md public Analysis v1 projection
|
||||
│ └── trace-v1.md public Trace v1 event stream
|
||||
├── crates/
|
||||
│ ├── marqdo-span/ Span, LineCol, LineIndex (leaf)
|
||||
│ ├── marqdo-value/ Value, diagnostics, errors, wire encoding
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
# Marqdo Analysis v1
|
||||
|
||||
Status: **implemented by `marqdo check --emit <path>` (M0.6 R4).** This is a
|
||||
public, read-only projection; it is not a dump of `marqdo-ir`.
|
||||
|
||||
## 1. Invariants
|
||||
|
||||
`check --emit`:
|
||||
|
||||
* never executes the document, loads a plugin shared library, starts a foreign
|
||||
kernel or imports a module implicitly;
|
||||
* validates the loaded program first; on a compile error it writes no artifact
|
||||
and removes a stale file at the target path;
|
||||
* writes atomically (temporary file + rename) only after a successful check;
|
||||
* is deterministic: the same source, tool version and project path produce
|
||||
byte-identical JSON (no timestamps, no random ids);
|
||||
* exposes no private Rust layout, optimization instruction or host pointer.
|
||||
|
||||
## 2. Top-level shape
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.analysis",
|
||||
"schema_version": 1,
|
||||
"producer": {"name": "marqdo", "version": "0.1.0", "markdown_profile": "marqdo.md.v1"},
|
||||
"project": {"root_id": "sha256:...", "lock_digest": "sha256:..."},
|
||||
"modules": [],
|
||||
"diagnostics": []
|
||||
}
|
||||
```
|
||||
|
||||
* `root_id` is a digest of the normalized project root used for this run.
|
||||
* `lock_digest` is a digest of `marqdo.lock`, or `""` when absent.
|
||||
* Modules are sorted by canonical `id`; arrays keep source order.
|
||||
* `schema_version` is a major version. Additive optional fields are allowed;
|
||||
removing/renaming fields or changing units/types requires a major bump.
|
||||
|
||||
## 3. Modules
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "root:default::index.mq.md",
|
||||
"package_instance_id": "root:default",
|
||||
"relative_path": "index.mq.md",
|
||||
"source_digest": "<sha256 hex>",
|
||||
"units": [],
|
||||
"functions": [],
|
||||
"imports": [],
|
||||
"references": [],
|
||||
"calls": [],
|
||||
"resources": 0
|
||||
}
|
||||
```
|
||||
|
||||
Module identity is the package-aware `ModuleId` from
|
||||
`spec/references.md` §2.1. `source_digest` hashes the exact source bytes.
|
||||
|
||||
### 3.1 Units
|
||||
|
||||
Each unit has `id`, `kind` (`root`/`namespace`/`function`/`section`), `name`,
|
||||
`level`, `span` (`{start,end}` byte offsets) and optionally `function`.
|
||||
|
||||
### 3.2 Functions and signatures
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "root:default::index.mq.md::数学.阶乘",
|
||||
"unit_id": "root:default::index.mq.md#数学/阶乘",
|
||||
"local_name": "阶乘",
|
||||
"namespace": "数学",
|
||||
"span": {"start": 0, "end": 100},
|
||||
"heading_span": {"start": 0, "end": 10},
|
||||
"signature": {
|
||||
"kind": "inferred",
|
||||
"params": [{"name": "n", "required": true, "type": null, "default": null, "span": {"start": 0, "end": 0}}]
|
||||
},
|
||||
"effects": ["unknown"],
|
||||
"body": []
|
||||
}
|
||||
```
|
||||
|
||||
`kind` is `explicit` or `inferred`. Inferred signatures only accept named
|
||||
arguments. `effects` is a **conservative** summary; `unknown` is not a proof of
|
||||
purity. Dynamic ABI/Foreign targets remain unknown unless a descriptor says
|
||||
otherwise.
|
||||
|
||||
### 3.3 Normalized body nodes
|
||||
|
||||
Body nodes use a small stable language, never internal IR serialization:
|
||||
|
||||
* `literal` (`type`: `int`/`float`/`text`/`bool`/`none`, `value` when present);
|
||||
* `variable`, `list`, `record`, `member`, `index`;
|
||||
* `unary` (`not`/`neg`/`pos`) and `binary` (`or`, `and`, `eq`, `ne`, `lt`,
|
||||
`le`, `gt`, `ge`, `add`, `sub`, `mul`, `div`, `floor_div`, `mod`, `pow`);
|
||||
* `call` with `callee` and `args`;
|
||||
* `assign`, `expression`, `call_site`, `branch` (ordered arms), `loop`,
|
||||
`return`.
|
||||
|
||||
Every node carries a byte `span`. Nodes outside the supported public subset
|
||||
must be marked `unsupported` (future extension), never silently given invented
|
||||
semantics.
|
||||
|
||||
### 3.4 Imports, references and calls
|
||||
|
||||
* `imports[]`: `{alias, target, span, resolved}`; `resolved` is a module id or
|
||||
null. Imports stay explicit.
|
||||
* `references[]`: Markdown link edges with `{source, url, span, state,
|
||||
target_module, target_unit}`. `state` is `resolved`, `unresolved` or
|
||||
`external`; a failed resolution is never disguised as bound.
|
||||
* `calls[]`: `{function, span, callee, state, target}` where `state` is
|
||||
`function`, `builtin`, `plugin` or `unresolved`.
|
||||
|
||||
Reference edges never execute anything and grant no capability.
|
||||
|
||||
## 4. Diagnostics
|
||||
|
||||
`diagnostics[]` uses the same stable codes/JSON shape as `marqdo check --json`.
|
||||
An analysis emitted after a successful check normally has no error diagnostics
|
||||
(warnings may remain).
|
||||
|
||||
## 5. Consumer contract
|
||||
|
||||
An independent consumer (Python/Go/JavaScript, without linking Rust crates)
|
||||
must be able to:
|
||||
|
||||
* find a function by `id` and read its signature/body;
|
||||
* find recursive/forward calls and `ref` edges;
|
||||
* map every body node back to `source_digest` + byte span;
|
||||
* reject `schema_version` it does not understand.
|
||||
|
||||
`tests/consumers/analysis_consumer.py` is one such black-box consumer and
|
||||
`crates/cli/tests/analysis_trace.rs` runs it when Python is available.
|
||||
|
||||
## 6. Not included
|
||||
|
||||
Internal optimization IR, host pointers, plugin handles, proof status and
|
||||
execution results are deliberately absent. Analysis does not claim that a
|
||||
document runs successfully or that any function is proved.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Marqdo Trace v1
|
||||
|
||||
Status: **implemented by `marqdo run/call --trace-file <path>` (M0.6 R4).**
|
||||
|
||||
## 1. Invariants
|
||||
|
||||
* Tracing is observation, not execution. Only `run`/`call` can produce a trace;
|
||||
`check`, `inspect` and `tool list` never execute a document.
|
||||
* Events come from the interpreter (`call.*`, `branch.eval`,
|
||||
`loop.iteration`, `return`) and the host (`effect`).
|
||||
* The writer is atomic: a failed run does not leave a partially written JSON
|
||||
file; an error run still records the terminal status if execution started.
|
||||
* No argument values, secrets, plugin handles or file contents are recorded.
|
||||
Effect detail is a result summary (`ok` or a stable error code).
|
||||
* `--trace` keeps its existing human/JSON effect output; `--trace-file` is the
|
||||
versioned artifact and does not redefine `--trace`.
|
||||
|
||||
## 2. Shape
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "marqdo.trace",
|
||||
"schema_version": 1,
|
||||
"run": {"id": "pid-nanos", "entry": "root:default::index.mq.md::main", "status": "ok"},
|
||||
"source": {"root_id": "sha256:...", "analysis_digest": "sha256:..."},
|
||||
"events": [
|
||||
{"seq": 0, "kind": "call.enter", "function_id": "root:default::index.mq.md::main", "span": null, "detail": null},
|
||||
{"seq": 1, "kind": "effect", "module": "root:default::index.mq.md", "span": {"start": 40, "end": 52}, "detail": "ok", "operation": "print", "duration_micros": 3},
|
||||
{"seq": 2, "kind": "call.exit", "function_id": "root:default::index.mq.md::main", "span": null, "detail": "ok"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`seq` is globally increasing within one run (semantic and effect events share
|
||||
the counter). `run.status` is `ok` or a stable runtime error code. Span fields
|
||||
use UTF-8 byte offsets into the source identified by `source.root_id` and
|
||||
`source.analysis_digest`.
|
||||
|
||||
## 3. Event kinds
|
||||
|
||||
| kind | detail | Meaning |
|
||||
|---|---|---|
|
||||
| `call.enter` | null | function entry; `function_id` is canonical |
|
||||
| `call.exit` | `ok` / `return` / error code | function exit |
|
||||
| `return` | value type name | explicit `Emph` return; no value content |
|
||||
| `branch.eval` | `true` / `false` | ordered-list branch condition |
|
||||
| `loop.iteration` | `continue` / `exit` | bullet-list loop condition |
|
||||
| `effect` | result summary | a `HostOp` effect; `operation` names it |
|
||||
|
||||
Future event kinds are additive. Consumers must ignore unknown kinds rather
|
||||
than guessing their semantics.
|
||||
|
||||
## 4. Staleness
|
||||
|
||||
`source.analysis_digest` is the digest of the Analysis v1 projection built
|
||||
from the same loaded project. If a consumer compares it with a newer analysis
|
||||
and the digest differs, the trace is `stale` and must not be presented as the
|
||||
current document's execution.
|
||||
|
||||
## 5. Privacy and limits
|
||||
|
||||
* Values and secrets are never serialized into a trace.
|
||||
* Foreign/plugin effects record only the operation and success/error summary.
|
||||
* A trace file can be large for long loops; the current implementation has no
|
||||
event-count cap, but consumers must stream/limit. A future version may add a
|
||||
bounded mode.
|
||||
* A failed/aborted run records the status it reached; it is never marked
|
||||
successful.
|
||||
|
||||
## 6. Not included
|
||||
|
||||
Interactive breakpoints, a debug server, time travel, notebook sessions,
|
||||
WebSocket streaming and full argument-value capture are out of scope for v1.
|
||||
@@ -0,0 +1,29 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Independent Analysis v1 consumer: no Marqdo/Rust imports."""
|
||||
import json
|
||||
import sys
|
||||
|
||||
if len(sys.argv) != 2:
|
||||
raise SystemExit("usage: analysis_consumer.py ANALYSIS.json")
|
||||
|
||||
with open(sys.argv[1], encoding="utf-8") as handle:
|
||||
analysis = json.load(handle)
|
||||
|
||||
if analysis.get("schema") != "marqdo.analysis":
|
||||
raise SystemExit("unexpected schema")
|
||||
if analysis.get("schema_version") != 1:
|
||||
raise SystemExit("unsupported schema_version")
|
||||
|
||||
functions = []
|
||||
for module in analysis["modules"]:
|
||||
if not module["id"].startswith("root:default::"):
|
||||
raise SystemExit("unexpected module identity")
|
||||
if not isinstance(module["source_digest"], str) or len(module["source_digest"]) != 64:
|
||||
raise SystemExit("bad source digest")
|
||||
for function in module["functions"]:
|
||||
body = json.dumps(function["body"], ensure_ascii=False)
|
||||
functions.append((function["id"], body))
|
||||
|
||||
if not functions:
|
||||
raise SystemExit("no functions")
|
||||
print("functions=" + str(len(functions)))
|
||||
Reference in new issue
Block a user