feat(trace): Trace v2 identity, module-owned events and capacity bounds (B-16)
- bind traces to the logical project identity and the exact emitted Analysis digest; every span-bearing event carries module_id - add host TraceState budgets (100k events / 32 MiB defaults), CLI --trace-max-events/--trace-max-bytes, terminal trace.truncated events, and a final serialized byte cap; budgets never change run.status - disable semantic recording when no trace is requested - cap worker frames at 8 MiB, align request/result/capability wire caps, make clean EOF distinct from protocol errors, and mark/kill a worker after a transport failure instead of reusing it - add trace-v2 spec/schema, independent trace consumer, CI check and tests - record the S2/C state in STATUS
This commit is contained in:
1 parent
55dcb57553
commit
d890686a2b
21 files changed
+732
-84
No files matched your search
@@ -38,8 +38,12 @@ 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.
|
||||
/// Optional Trace v2 output path.
|
||||
pub trace_file: Option<PathBuf>,
|
||||
/// Trace event budget override (0 = unlimited).
|
||||
pub trace_max_events: Option<usize>,
|
||||
/// Trace approximate byte budget override (0 = unlimited).
|
||||
pub trace_max_bytes: Option<usize>,
|
||||
/// External foreign-kernel descriptor paths.
|
||||
pub kernels: Vec<PathBuf>,
|
||||
}
|
||||
@@ -690,7 +694,16 @@ pub fn execute(
|
||||
};
|
||||
let mut host = StdHost::new(mode, capabilities, project.root.clone());
|
||||
if trace || json || settings.trace_file.is_some() {
|
||||
host = host.with_trace();
|
||||
host = host
|
||||
.with_trace()
|
||||
.with_trace_budget(marqdo_host::TraceBudget {
|
||||
max_events: settings
|
||||
.trace_max_events
|
||||
.unwrap_or(marqdo_host::trace::DEFAULT_MAX_TRACE_EVENTS),
|
||||
max_bytes: settings
|
||||
.trace_max_bytes
|
||||
.unwrap_or(marqdo_host::trace::DEFAULT_MAX_TRACE_BYTES),
|
||||
});
|
||||
}
|
||||
if let Some(fuel) = settings.fuel {
|
||||
host.budget.fuel = fuel;
|
||||
|
||||
@@ -109,9 +109,15 @@ 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.
|
||||
/// Write a versioned Trace v2 file for this run.
|
||||
#[arg(long = "trace-file", value_name = "PATH")]
|
||||
trace_file: Option<PathBuf>,
|
||||
/// Override the trace event budget (0 = unlimited).
|
||||
#[arg(long = "trace-max-events")]
|
||||
trace_max_events: Option<usize>,
|
||||
/// Override the approximate trace byte budget (0 = unlimited).
|
||||
#[arg(long = "trace-max-bytes")]
|
||||
trace_max_bytes: Option<usize>,
|
||||
/// Register an external foreign-kernel provider (repeatable).
|
||||
#[arg(long = "kernel", value_name = "PATH")]
|
||||
kernel: Vec<PathBuf>,
|
||||
@@ -135,6 +141,8 @@ impl SandboxArgs {
|
||||
plugins: self.plugin.clone(),
|
||||
trust_native_plugin: self.trust_native_plugin,
|
||||
trace_file: self.trace_file.clone(),
|
||||
trace_max_events: self.trace_max_events,
|
||||
trace_max_bytes: self.trace_max_bytes,
|
||||
kernels: self.kernel.clone(),
|
||||
}
|
||||
}
|
||||
|
||||
+54
-12
@@ -1,4 +1,4 @@
|
||||
//! Public Trace v1 writer (spec/trace-v1.md).
|
||||
//! Public Trace v2 writer (spec/trace-v2.md).
|
||||
//!
|
||||
//! Events come from the interpreter (semantic) and the capability host
|
||||
//! (effects). No argument values, secrets or handles are recorded.
|
||||
@@ -12,7 +12,7 @@ use crate::loader::LoadedProject;
|
||||
|
||||
/// Schema name and version.
|
||||
pub const SCHEMA: &str = "marqdo.trace";
|
||||
pub const SCHEMA_VERSION: u32 = 1;
|
||||
pub const SCHEMA_VERSION: u32 = 2;
|
||||
|
||||
/// Write a trace atomically for one run.
|
||||
pub fn write(
|
||||
@@ -32,6 +32,7 @@ pub fn write(
|
||||
);
|
||||
let analysis_digest = crate::analysis::digest(project);
|
||||
let root_id = project.identity.root_id();
|
||||
let state = host.trace_state();
|
||||
let mut events: Vec<Value> = host
|
||||
.semantic_events()
|
||||
.iter()
|
||||
@@ -39,15 +40,55 @@ pub fn write(
|
||||
.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}"))?;
|
||||
|
||||
let mut truncation = state.truncation.clone();
|
||||
let max_bytes = state.budget.max_bytes;
|
||||
let bytes = loop {
|
||||
let mut all = events.clone();
|
||||
if let Some(truncation) = &truncation {
|
||||
let seq = all
|
||||
.last()
|
||||
.and_then(|event| event.get("seq"))
|
||||
.and_then(Value::as_u64)
|
||||
.unwrap_or(0)
|
||||
+ 1;
|
||||
all.push(json!({
|
||||
"seq": seq,
|
||||
"kind": "trace.truncated",
|
||||
"module_id": null,
|
||||
"span": null,
|
||||
"detail": truncation.reason,
|
||||
}));
|
||||
}
|
||||
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}"),
|
||||
},
|
||||
"limits": {
|
||||
"max_events": state.budget.max_events,
|
||||
"max_bytes": state.budget.max_bytes,
|
||||
},
|
||||
"truncated": truncation,
|
||||
"events": all,
|
||||
});
|
||||
let bytes = serde_json::to_vec_pretty(&trace)
|
||||
.map_err(|error| format!("cannot encode trace: {error}"))?;
|
||||
if max_bytes == 0 || bytes.len() <= max_bytes || events.is_empty() {
|
||||
break bytes;
|
||||
}
|
||||
events.pop();
|
||||
if truncation.is_none() {
|
||||
truncation = Some(marqdo_host::TraceTruncation {
|
||||
reason: "byte_budget".to_string(),
|
||||
limit: max_bytes as u64,
|
||||
written: events.len() as u64,
|
||||
});
|
||||
}
|
||||
};
|
||||
atomic_write(path, &bytes)
|
||||
}
|
||||
|
||||
@@ -56,6 +97,7 @@ fn semantic_json(event: &SemanticEvent) -> Value {
|
||||
"seq": event.seq,
|
||||
"kind": event.kind,
|
||||
"function_id": event.function_id,
|
||||
"module_id": event.module_id,
|
||||
"span": event.span.map(|span| json!({"start": span.start, "end": span.end})),
|
||||
"detail": event.detail,
|
||||
})
|
||||
@@ -65,7 +107,7 @@ fn effect_json(entry: &TraceEntry) -> Value {
|
||||
json!({
|
||||
"seq": entry.seq,
|
||||
"kind": "effect",
|
||||
"module": entry.module,
|
||||
"module_id": entry.module,
|
||||
"span": entry.span.map(|span| json!({"start": span.start, "end": span.end})),
|
||||
"detail": entry.result,
|
||||
"operation": entry.op,
|
||||
|
||||
@@ -241,6 +241,52 @@ print(1)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn trace_v2_budget_truncates_long_loops_without_failing_the_run() {
|
||||
let dir = TempDir::new("trace-budget");
|
||||
write(
|
||||
dir.path(),
|
||||
"index.mq.md",
|
||||
"## main\n\n**i = 0**\n\n- `i < 500`\n\n **i = i + 1**\n\n*i*\n",
|
||||
);
|
||||
let trace_path = dir.path().join("trace.json");
|
||||
let output = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--trace-file",
|
||||
trace_path.to_str().unwrap(),
|
||||
"--trace-max-events",
|
||||
"20",
|
||||
],
|
||||
);
|
||||
assert_eq!(
|
||||
output.status.code(),
|
||||
Some(0),
|
||||
"{}",
|
||||
String::from_utf8_lossy(&output.stderr)
|
||||
);
|
||||
let trace: serde_json::Value =
|
||||
serde_json::from_slice(&std::fs::read(&trace_path).unwrap()).unwrap();
|
||||
assert_eq!(trace["schema_version"], 2);
|
||||
assert_eq!(trace["run"]["status"], "ok");
|
||||
assert_eq!(trace["limits"]["max_events"], 20);
|
||||
assert_eq!(trace["truncated"]["reason"], "event_budget");
|
||||
assert_eq!(trace["truncated"]["limit"], 20);
|
||||
let events = trace["events"].as_array().unwrap();
|
||||
assert!(events.len() <= 21, "events: {}", events.len());
|
||||
assert_eq!(events.last().unwrap()["kind"], "trace.truncated");
|
||||
let mut previous = None;
|
||||
for event in events {
|
||||
let seq = event["seq"].as_u64().unwrap();
|
||||
if let Some(previous) = previous {
|
||||
assert!(seq > previous);
|
||||
}
|
||||
previous = Some(seq);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn failed_check_removes_stale_analysis() {
|
||||
let dir = TempDir::new("analysis-error");
|
||||
@@ -282,11 +328,14 @@ fn trace_records_calls_effects_and_status_without_secrets() {
|
||||
);
|
||||
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["schema_version"], 2);
|
||||
assert_eq!(trace["run"]["status"], "ok");
|
||||
assert_eq!(trace["run"]["entry"], "root:default::index.mq.md::main");
|
||||
let events = trace["events"].as_array().unwrap();
|
||||
assert!(events.iter().any(|event| event["kind"] == "call.enter"));
|
||||
assert!(events
|
||||
.iter()
|
||||
.any(|event| event["kind"] == "call.enter"
|
||||
&& event["module_id"] == "root:default::index.mq.md"));
|
||||
assert!(events.iter().any(|event| event["kind"] == "effect"));
|
||||
assert!(events.iter().any(|event| event["kind"] == "call.exit"));
|
||||
let mut previous = None;
|
||||
|
||||
Reference in new issue
Block a user