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:
cflmy committed 2026-11-20 11:46:37 +08:00
1 parent 25a1faa6ef
commit b5a28a9825
16 files changed
+1365 -13

No files matched your search

+3 -2
View File
@@ -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.
+579
View File
@@ -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())
}
+29 -2
View File
@@ -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
View File
@@ -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,
+107
View File
@@ -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())
}
+207
View File
@@ -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");
}
+54 -1
View File
@@ -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 {
+1 -1
View File
@@ -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};
+20
View File
@@ -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>,
}
+29 -1
View File
@@ -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
View File
@@ -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 | — |
+75
View File
@@ -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.
+4 -2
View File
@@ -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
+138
View File
@@ -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.
+73
View File
@@ -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.
+29
View File
@@ -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)))