diff --git a/README.md b/README.md index aad0cf1..1bfa3d1 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/crates/cli/src/analysis.rs b/crates/cli/src/analysis.rs new file mode 100644 index 0000000..f39055c --- /dev/null +++ b/crates/cli/src/analysis.rs @@ -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::>(), + "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::>(), + "references": reference_edges(project, module_id), + "calls": module.functions.iter().flat_map(|function| calls_json(project, module, function)).collect::>(), + "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 { + 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::>(), + }, + "effects": ["unknown"], + "body": function.body.iter().map(stmt_json).collect::>(), + }) +} + +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::>(), + "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::>(), + "span": span_json(arm.span), + })).collect::>(), + "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::>(), + "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::>(),"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::>(), + "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::>(), + "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 { + 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 { + 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, +) { + 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, +) { + 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()) +} diff --git a/crates/cli/src/commands.rs b/crates/cli/src/commands.rs index 126d3ad..1e5daa9 100644 --- a/crates/cli/src/commands.rs +++ b/crates/cli/src/commands.rs @@ -38,6 +38,8 @@ pub struct SandboxSettings { pub plugins: Vec, /// Explicit trust decision for in-process native plugin loading. pub trust_native_plugin: bool, + /// Optional Trace v1 output path. + pub trace_file: Option, } impl SandboxSettings { @@ -266,7 +268,13 @@ fn plugin_signature(raw: &str) -> Result, 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(); diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 53cc44e..84e019f 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -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, + /// Write a versioned Trace v1 file for this run. + #[arg(long = "trace-file", value_name = "PATH")] + trace_file: Option, /// 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, + /// Write the public Analysis v1 projection (only on successful check). + #[arg(long, value_name = "PATH")] + emit: Option, /// 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, diff --git a/crates/cli/src/trace.rs b/crates/cli/src/trace.rs new file mode 100644 index 0000000..ee82f9d --- /dev/null +++ b/crates/cli/src/trace.rs @@ -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 = 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()) +} diff --git a/crates/cli/tests/analysis_trace.rs b/crates/cli/tests/analysis_trace.rs new file mode 100644 index 0000000..0baeb61 --- /dev/null +++ b/crates/cli/tests/analysis_trace.rs @@ -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"); +} diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index d7ff1f6..966944d 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -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, + _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>>, /// Host-issued opaque plugin handles. pub handles: PluginHandleTable, + semantic_events: Vec, + 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 { self.broker_audit @@ -436,12 +466,14 @@ impl Host for StdHost { ctx: &ExecutionContext, ) -> Result { 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, + 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 { diff --git a/crates/marqdo-host/src/lib.rs b/crates/marqdo-host/src/lib.rs index f50b8dc..cf5b33d 100644 --- a/crates/marqdo-host/src/lib.rs +++ b/crates/marqdo-host/src/lib.rs @@ -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}; diff --git a/crates/marqdo-host/src/trace.rs b/crates/marqdo-host/src/trace.rs index 72d120f..f7385dd 100644 --- a/crates/marqdo-host/src/trace.rs +++ b/crates/marqdo-host/src/trace.rs @@ -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, module: impl Into, span: Option, @@ -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, + /// Source span, when known. + pub span: Option, + /// Non-sensitive detail (`ok`, `true`, `int`, an error code). + pub detail: Option, +} diff --git a/crates/marqdo-runtime/src/interpreter.rs b/crates/marqdo-runtime/src/interpreter.rs index 6eb8ea0..97ca00f 100644 --- a/crates/marqdo-runtime/src/interpreter.rs +++ b/crates/marqdo-runtime/src/interpreter.rs @@ -122,9 +122,12 @@ impl<'a> Interpreter<'a> { call_span: Option, ) -> Result { 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; } diff --git a/docs/STATUS.md b/docs/STATUS.md index 600d66b..224961a 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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 | — | diff --git a/docs/adr/0015-public-analysis-trace-v1.md b/docs/adr/0015-public-analysis-trace-v1.md new file mode 100644 index 0000000..cc23fc3 --- /dev/null +++ b/docs/adr/0015-public-analysis-trace-v1.md @@ -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 --emit ` 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 ` 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. diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md index f10704f..f34d5ee 100644 --- a/docs/contributor-guide.md +++ b/docs/contributor-guide.md @@ -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 diff --git a/spec/analysis-v1.md b/spec/analysis-v1.md new file mode 100644 index 0000000..5f904e3 --- /dev/null +++ b/spec/analysis-v1.md @@ -0,0 +1,138 @@ +# Marqdo Analysis v1 + +Status: **implemented by `marqdo check --emit ` (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": "", + "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. diff --git a/spec/trace-v1.md b/spec/trace-v1.md new file mode 100644 index 0000000..d4aff64 --- /dev/null +++ b/spec/trace-v1.md @@ -0,0 +1,73 @@ +# Marqdo Trace v1 + +Status: **implemented by `marqdo run/call --trace-file ` (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. diff --git a/tests/consumers/analysis_consumer.py b/tests/consumers/analysis_consumer.py new file mode 100644 index 0000000..8bade6b --- /dev/null +++ b/tests/consumers/analysis_consumer.py @@ -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)))