obs(02): add run/call --event-stream jsonl lifecycle, chunks and terminal events
This commit is contained in:
1 parent
d78faaf8e4
commit
e6e497e68b
6 files changed
+1482
-80
No files matched your search
+261
-52
@@ -4,6 +4,7 @@
|
||||
//! runtime helpers, but keeps the run session out of the command table.
|
||||
|
||||
use super::*;
|
||||
use crate::execution_events::{EventStream, ObservationOptions};
|
||||
use crate::provider_manifest;
|
||||
use marqdo_sandbox::StrictChildState;
|
||||
|
||||
@@ -14,16 +15,55 @@ pub fn execute(
|
||||
settings: &SandboxSettings,
|
||||
json: bool,
|
||||
trace: bool,
|
||||
observation: Option<&ObservationOptions>,
|
||||
) -> i32 {
|
||||
let command_name = if function.is_some() { "call" } else { "run" };
|
||||
let prepared = match prepare_project(file, json, &settings.plugins) {
|
||||
Ok(prepared) => prepared,
|
||||
Err(code) => return code,
|
||||
// Open the dedicated protocol channel before any project work so prepare
|
||||
// and authorization failures can still produce `run.rejected`.
|
||||
let events = match observation {
|
||||
Some(options) => match EventStream::open(options) {
|
||||
Ok(stream) => Some(stream),
|
||||
Err(error) => {
|
||||
eprintln!("error[observe.transport_failed]: {error}");
|
||||
return 1;
|
||||
}
|
||||
},
|
||||
None => None,
|
||||
};
|
||||
let stream = events.as_ref();
|
||||
let prepared = if stream.is_some() {
|
||||
let options = PrepareOptions {
|
||||
plugins: settings.plugins.clone(),
|
||||
};
|
||||
match project_prepare::prepare(file, &options) {
|
||||
Ok(prepared) => prepared,
|
||||
Err(error) => return fail_prepare(stream, json, command_name, "prepare", &error),
|
||||
}
|
||||
} else {
|
||||
match prepare_project(file, json, &settings.plugins) {
|
||||
Ok(prepared) => prepared,
|
||||
Err(code) => return code,
|
||||
}
|
||||
};
|
||||
let extension_sources = prepared.loaded.extension_sources.clone();
|
||||
let project = prepared.loaded;
|
||||
let static_plugins = prepared.plugins;
|
||||
if project.has_errors() {
|
||||
if let Some(stream) = stream {
|
||||
let code = project
|
||||
.diagnostics
|
||||
.iter()
|
||||
.find(|item| item.diagnostic.is_error())
|
||||
.map(|item| item.diagnostic.code.clone())
|
||||
.unwrap_or_else(|| "cli.compile_error".to_string());
|
||||
if let Err(error) = stream.rejected(
|
||||
"compile",
|
||||
&code,
|
||||
"refusing to run a project with compile errors",
|
||||
) {
|
||||
return transport_failure(&error);
|
||||
}
|
||||
}
|
||||
if json {
|
||||
output::print_json(&json!({
|
||||
"command": command_name,
|
||||
@@ -48,8 +88,15 @@ pub fn execute(
|
||||
let mode = match settings.sandbox_mode() {
|
||||
Ok(mode) => mode,
|
||||
Err(error) => {
|
||||
emit_error(json, command_name, "cli.invalid_mode", &error);
|
||||
return 2;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"authorization",
|
||||
"cli.invalid_mode",
|
||||
&error,
|
||||
2,
|
||||
);
|
||||
}
|
||||
};
|
||||
// A project-declared extension is activation, not authorization, but it is
|
||||
@@ -68,8 +115,15 @@ pub fn execute(
|
||||
marqdo_package::MANIFEST_FILE,
|
||||
settings.mode
|
||||
);
|
||||
emit_error(json, command_name, code, &message);
|
||||
return 2;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"authorization",
|
||||
code,
|
||||
&message,
|
||||
2,
|
||||
);
|
||||
}
|
||||
let mut kernel_paths = settings.kernels.clone();
|
||||
kernel_paths.extend(
|
||||
@@ -90,9 +144,28 @@ pub fn execute(
|
||||
provider_paths.sort();
|
||||
provider_paths.dedup();
|
||||
if mode == SandboxMode::Strict {
|
||||
if stream.is_some() {
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"strict",
|
||||
"strict.unsupported_grant",
|
||||
"--event-stream jsonl is not supported under --mode strict; strict refuses \
|
||||
trace/event artifacts and never downgrades to project mode",
|
||||
2,
|
||||
);
|
||||
}
|
||||
if let Err(error) = settings.strict_preflight() {
|
||||
emit_error(json, command_name, "strict.unsupported_grant", &error);
|
||||
return 2;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"strict",
|
||||
"strict.unsupported_grant",
|
||||
&error,
|
||||
2,
|
||||
);
|
||||
}
|
||||
match marqdo_sandbox::inspect_strict_child() {
|
||||
// A verified supervisor child may run project code.
|
||||
@@ -101,8 +174,15 @@ pub fn execute(
|
||||
Ok(StrictChildState::NotChild) => {
|
||||
let platform = PlatformCapabilities::detect();
|
||||
if let Err(error) = marqdo_sandbox::enforce(mode, &platform) {
|
||||
emit_error(json, command_name, error.code(), &error.to_string());
|
||||
return 1;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"strict",
|
||||
error.code(),
|
||||
&error.to_string(),
|
||||
1,
|
||||
);
|
||||
}
|
||||
return launch_strict_process(&project.root, file, settings, json, command_name);
|
||||
}
|
||||
@@ -111,30 +191,49 @@ pub fn execute(
|
||||
// module so macOS/Windows builds compile.
|
||||
Err(reason) => {
|
||||
let message = format!("strict isolation verification failed: {reason}");
|
||||
emit_error(json, command_name, "strict.identity_invalid", &message);
|
||||
return 1;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"strict",
|
||||
"strict.identity_invalid",
|
||||
&message,
|
||||
1,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
let platform = PlatformCapabilities::detect();
|
||||
if let Err(error) = marqdo_sandbox::enforce(mode, &platform) {
|
||||
emit_error(
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"authorization",
|
||||
"sandbox.unavailable",
|
||||
&error.to_string(),
|
||||
1,
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
let capabilities = match settings.capabilities() {
|
||||
Ok(capabilities) => capabilities,
|
||||
Err(error) => {
|
||||
emit_error(json, command_name, "cli.invalid_grants", &error);
|
||||
return 2;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"authorization",
|
||||
"cli.invalid_grants",
|
||||
&error,
|
||||
2,
|
||||
);
|
||||
}
|
||||
};
|
||||
let stdin = read_stdin();
|
||||
let mut host = StdHost::new(mode, capabilities, project.root.clone()).with_stdin(stdin);
|
||||
if let Some(stream) = stream {
|
||||
host = host.with_observation(stream.config(), Box::new(stream.host_sink()));
|
||||
}
|
||||
if trace || json || settings.trace_file.is_some() {
|
||||
host = host
|
||||
.with_trace()
|
||||
@@ -161,12 +260,15 @@ pub fn execute(
|
||||
}
|
||||
for kernel_path in &kernel_paths {
|
||||
if let Err(error) = load_kernel_descriptor(&mut host, kernel_path) {
|
||||
if json {
|
||||
output::print_json(&json!({"success": false, "error": error}));
|
||||
} else {
|
||||
eprintln!("error: {error}");
|
||||
}
|
||||
return 2;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"prepare",
|
||||
"ext.kernel_load_failed",
|
||||
&error,
|
||||
2,
|
||||
);
|
||||
}
|
||||
}
|
||||
// T6: verify every selected artifact/path/hash before starting a worker or
|
||||
@@ -180,8 +282,7 @@ pub fn execute(
|
||||
let providers = match provider_manifest::read_provider_manifests(&provider_paths) {
|
||||
Ok(providers) => providers,
|
||||
Err(error) => {
|
||||
emit_prepare_error(json, command_name, &error);
|
||||
return error.exit_code;
|
||||
return fail_prepare(stream, json, command_name, "prepare", &error);
|
||||
}
|
||||
};
|
||||
// `--provider` alone never authorizes; the exact `--allow-provider NAME`
|
||||
@@ -201,8 +302,7 @@ pub fn execute(
|
||||
provider.name, provider.name
|
||||
),
|
||||
);
|
||||
emit_prepare_error(json, command_name, &error);
|
||||
return error.exit_code;
|
||||
return fail_prepare(stream, json, command_name, "authorization", &error);
|
||||
}
|
||||
}
|
||||
// A grant that matches no selected provider is a deterministic option
|
||||
@@ -217,8 +317,7 @@ pub fn execute(
|
||||
providers are never discovered automatically"
|
||||
),
|
||||
);
|
||||
emit_prepare_error(json, command_name, &error);
|
||||
return error.exit_code;
|
||||
return fail_prepare(stream, json, command_name, "authorization", &error);
|
||||
}
|
||||
}
|
||||
for plugin in &static_plugins.plugins {
|
||||
@@ -226,14 +325,12 @@ pub fn execute(
|
||||
&plugin.base_dir,
|
||||
&plugin.artifact_relative,
|
||||
) {
|
||||
emit_prepare_error(json, command_name, &error);
|
||||
return error.exit_code;
|
||||
return fail_prepare(stream, json, command_name, "authorization", &error);
|
||||
}
|
||||
let artifact = plugin.artifact_path();
|
||||
if let Err(error) = extension_descriptors::verify_sha256(&artifact, &plugin.artifact_sha256)
|
||||
{
|
||||
emit_prepare_error(json, command_name, &error);
|
||||
return error.exit_code;
|
||||
return fail_prepare(stream, json, command_name, "authorization", &error);
|
||||
}
|
||||
}
|
||||
// T7: start only selected, granted and verified extensions.
|
||||
@@ -243,19 +340,29 @@ pub fn execute(
|
||||
&plugin.manifest_path,
|
||||
settings.trust_native_plugin,
|
||||
) {
|
||||
if json {
|
||||
output::print_json(&json!({"success": false, "error": message}));
|
||||
} else {
|
||||
eprintln!("error: {message}");
|
||||
}
|
||||
return 1;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"authorization",
|
||||
"ext.plugin_load_failed",
|
||||
&message,
|
||||
1,
|
||||
);
|
||||
}
|
||||
}
|
||||
// T8: exact one-to-one reconciliation with the static descriptors. Never
|
||||
// synthesise a missing signature (`params: Vec::new()`) or guess an export.
|
||||
if let Err(message) = reconcile_plugin_exports(&static_plugins, &host) {
|
||||
emit_error(json, command_name, "ext.plugin_binding_mismatch", &message);
|
||||
return 1;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"authorization",
|
||||
"ext.plugin_binding_mismatch",
|
||||
&message,
|
||||
1,
|
||||
);
|
||||
}
|
||||
// T7b: start only granted and verified provider helpers. Every manifest,
|
||||
// artifact, target, grant and duplicate-kind check above already passed, so
|
||||
@@ -266,8 +373,7 @@ pub fn execute(
|
||||
provider,
|
||||
&settings.allow_provider,
|
||||
) {
|
||||
emit_prepare_error(json, command_name, &error);
|
||||
return error.exit_code;
|
||||
return fail_prepare(stream, json, command_name, "prepare", &error);
|
||||
}
|
||||
}
|
||||
let function_name = function.unwrap_or("main").to_string();
|
||||
@@ -285,12 +391,15 @@ pub fn execute(
|
||||
project.entry_file().path.display()
|
||||
)
|
||||
};
|
||||
if json {
|
||||
emit_error(true, command_name, "sem.no_entry_function", &message);
|
||||
} else {
|
||||
eprintln!("error[sem.no_entry_function]: {message}");
|
||||
}
|
||||
return 1;
|
||||
return fail(
|
||||
stream,
|
||||
json,
|
||||
command_name,
|
||||
"compile",
|
||||
"sem.no_entry_function",
|
||||
&message,
|
||||
1,
|
||||
);
|
||||
}
|
||||
let runtime_args: Vec<EvaluatedArg> = named_args
|
||||
.iter()
|
||||
@@ -304,7 +413,19 @@ pub fn execute(
|
||||
.max_region_memory
|
||||
.unwrap_or(marqdo_runtime::DEFAULT_MAX_REGION_BYTES),
|
||||
};
|
||||
let result = run_with_limits(
|
||||
if let Some(stream) = stream {
|
||||
let entry = format!("{}::{}", project.entry, function_name);
|
||||
let analysis_digest = format!("sha256:{}", crate::analysis::digest(&project));
|
||||
if let Err(error) = stream.started(
|
||||
&entry,
|
||||
mode.as_str(),
|
||||
&project.identity.root_id(),
|
||||
&analysis_digest,
|
||||
) {
|
||||
return transport_failure(&error);
|
||||
}
|
||||
}
|
||||
let mut result = run_with_limits(
|
||||
&project.program,
|
||||
&mut host,
|
||||
&project.entry,
|
||||
@@ -312,17 +433,58 @@ pub fn execute(
|
||||
runtime_args,
|
||||
memory_limits,
|
||||
);
|
||||
// A dead event pipe is a run failure even if the program itself returned.
|
||||
if result.is_ok() {
|
||||
if let Some(message) = host.observation_failure() {
|
||||
result = Err(RuntimeError::new(
|
||||
marqdo_value::ErrorCategory::Observation,
|
||||
None,
|
||||
format!("observe.transport_failed: {message}"),
|
||||
));
|
||||
}
|
||||
}
|
||||
let trace_run_id = stream.map(EventStream::run_id);
|
||||
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) {
|
||||
emit_error(json, command_name, "cli.trace_failed", &error);
|
||||
if let Err(error) = crate::trace::write(
|
||||
&project,
|
||||
&host,
|
||||
&entry,
|
||||
status,
|
||||
path,
|
||||
trace_run_id.as_deref(),
|
||||
) {
|
||||
if let Some(stream) = stream {
|
||||
let _ = stream.failed_error("cli.trace_failed", &error);
|
||||
} else {
|
||||
emit_error(json, command_name, "cli.trace_failed", &error);
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
if let Some(stream) = stream {
|
||||
// The program's stdout/stderr were already emitted as chunk events at
|
||||
// their real host commit points; never replay them on this channel.
|
||||
match &result {
|
||||
Ok(outcome) => {
|
||||
if let Err(error) = stream.completed(&outcome.value) {
|
||||
return transport_failure(&error);
|
||||
}
|
||||
}
|
||||
Err(error) => {
|
||||
if let Err(write_error) = stream.failed(error) {
|
||||
eprintln!("error[observe.transport_failed]: {write_error}");
|
||||
}
|
||||
eprint!("{}", render_runtime_error(error, &project));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
let stdout = host.take_output();
|
||||
let stdout_text = String::from_utf8_lossy(&stdout).to_string();
|
||||
let stderr = host.take_error();
|
||||
@@ -383,6 +545,53 @@ pub fn execute(
|
||||
}
|
||||
}
|
||||
|
||||
fn transport_failure(error: &str) -> i32 {
|
||||
eprintln!("error[observe.transport_failed]: {error}");
|
||||
1
|
||||
}
|
||||
|
||||
/// Emit one pre-execution rejection (or the legacy non-event error form).
|
||||
fn fail(
|
||||
stream: Option<&EventStream>,
|
||||
json: bool,
|
||||
command_name: &str,
|
||||
phase: &str,
|
||||
code: &str,
|
||||
message: &str,
|
||||
exit: i32,
|
||||
) -> i32 {
|
||||
if let Some(stream) = stream {
|
||||
if let Err(error) = stream.rejected(phase, code, message) {
|
||||
return transport_failure(&error);
|
||||
}
|
||||
}
|
||||
if json && stream.is_none() {
|
||||
emit_error(json, command_name, code, message);
|
||||
} else {
|
||||
eprintln!("error[{code}]: {message}");
|
||||
}
|
||||
exit
|
||||
}
|
||||
|
||||
/// Emit one prepare/authorization rejection using a `PrepareError`.
|
||||
fn fail_prepare(
|
||||
stream: Option<&EventStream>,
|
||||
json: bool,
|
||||
command_name: &str,
|
||||
phase: &str,
|
||||
error: &crate::extension_descriptors::PrepareError,
|
||||
) -> i32 {
|
||||
if let Some(stream) = stream {
|
||||
if let Err(write_error) = stream.rejected(phase, &error.code, &error.message) {
|
||||
return transport_failure(&write_error);
|
||||
}
|
||||
eprintln!("error[{}]: {}", error.code, error.message);
|
||||
} else {
|
||||
emit_prepare_error(json, command_name, error);
|
||||
}
|
||||
error.exit_code
|
||||
}
|
||||
|
||||
fn emit_prepare_error(
|
||||
json: bool,
|
||||
command_name: &str,
|
||||
|
||||
@@ -0,0 +1,534 @@
|
||||
//! Execution Events v1 JSONL writer and public envelope.
|
||||
//!
|
||||
//! Normative contract: `spec/execution-events-v1.md`; decision record:
|
||||
//! ADR-0059. The host owns the typed events; this module only assigns the
|
||||
//! public envelope/sequence, encodes bytes as base64 and writes one flushed
|
||||
//! line per event to the CLI protocol stdout.
|
||||
//!
|
||||
//! There is no HTTP, SSE, WebSocket, View or Agent branch here.
|
||||
|
||||
use std::cell::RefCell;
|
||||
use std::collections::BTreeSet;
|
||||
use std::io::{self, Write};
|
||||
use std::rc::Rc;
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
use marqdo_host::{
|
||||
FrameId, ObservationConfig, ObservationError, ObservationEvent, ObservationSink,
|
||||
ParameterSource, ValueState, DEFAULT_MAX_OBSERVATION_BYTES, DEFAULT_MAX_OBSERVATION_EVENTS,
|
||||
DEFAULT_MAX_VALUE_BYTES,
|
||||
};
|
||||
use marqdo_value::{RuntimeError, Value};
|
||||
use serde_json::{json, Value as Json};
|
||||
|
||||
/// Public schema name.
|
||||
pub const SCHEMA: &str = "marqdo.execution-events";
|
||||
/// Public schema major version.
|
||||
pub const SCHEMA_VERSION: u32 = 1;
|
||||
/// The only accepted `--event-stream` format in v1.
|
||||
pub const FORMAT_JSONL: &str = "jsonl";
|
||||
|
||||
/// CLI observation options.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct ObservationOptions {
|
||||
/// Exact local-variable names selected with `--observe-variable`.
|
||||
pub variables: Vec<String>,
|
||||
/// Exact parameter names selected with `--observe-parameter`.
|
||||
pub parameters: Vec<String>,
|
||||
/// Second explicit consent for `Text` bytes.
|
||||
pub allow_text_values: bool,
|
||||
/// Maximum encoded source bytes for one value (`0` = unlimited).
|
||||
pub max_value_bytes: usize,
|
||||
/// Structural/value event budget (`0` = unlimited).
|
||||
pub max_events: u64,
|
||||
/// Approximate structural/value byte budget (`0` = unlimited).
|
||||
pub max_bytes: u64,
|
||||
}
|
||||
|
||||
impl Default for ObservationOptions {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
variables: Vec::new(),
|
||||
parameters: Vec::new(),
|
||||
allow_text_values: false,
|
||||
max_value_bytes: DEFAULT_MAX_VALUE_BYTES,
|
||||
max_events: DEFAULT_MAX_OBSERVATION_EVENTS,
|
||||
max_bytes: DEFAULT_MAX_OBSERVATION_BYTES,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl ObservationOptions {
|
||||
/// Typed host policy for this run.
|
||||
pub fn config(&self) -> ObservationConfig {
|
||||
ObservationConfig {
|
||||
structural: true,
|
||||
selected_variables: self.variables.iter().cloned().collect::<BTreeSet<_>>(),
|
||||
selected_parameters: self.parameters.iter().cloned().collect::<BTreeSet<_>>(),
|
||||
allow_text_values: self.allow_text_values,
|
||||
max_observation_events: self.max_events,
|
||||
max_observation_bytes: self.max_bytes,
|
||||
max_value_bytes: self.max_value_bytes,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// One run's JSONL writer, shared with the host sink.
|
||||
#[derive(Clone)]
|
||||
pub struct EventStream {
|
||||
inner: Rc<RefCell<JsonlWriter>>,
|
||||
config: ObservationConfig,
|
||||
}
|
||||
|
||||
impl EventStream {
|
||||
/// Open the protocol channel and write `stream.opened` as `seq: 0`.
|
||||
pub fn open(options: &ObservationOptions) -> Result<Self, String> {
|
||||
let run_id = new_run_id();
|
||||
let config = options.config();
|
||||
let opened = json!({
|
||||
"producer": {
|
||||
"name": "marqdo",
|
||||
"version": env!("CARGO_PKG_VERSION"),
|
||||
},
|
||||
"protocol": {
|
||||
"name": SCHEMA,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
},
|
||||
"observation": {
|
||||
"level": config.level(),
|
||||
"values": config.values_enabled(),
|
||||
"selected_variables": config.selected_variables.iter().cloned().collect::<Vec<_>>(),
|
||||
"selected_parameters": config.selected_parameters.iter().cloned().collect::<Vec<_>>(),
|
||||
"allow_text_values": config.allow_text_values,
|
||||
},
|
||||
"limits": {
|
||||
"max_observation_events": config.max_observation_events,
|
||||
"max_observation_bytes": config.max_observation_bytes,
|
||||
"max_value_bytes": config.max_value_bytes,
|
||||
},
|
||||
});
|
||||
let mut writer = JsonlWriter {
|
||||
out: Box::new(io::stdout()),
|
||||
run_id: run_id.clone(),
|
||||
seq: 0,
|
||||
};
|
||||
writer.emit("stream.opened", opened)?;
|
||||
Ok(Self {
|
||||
inner: Rc::new(RefCell::new(writer)),
|
||||
config,
|
||||
})
|
||||
}
|
||||
|
||||
/// Opaque run identity shared with Trace v2 when both are requested.
|
||||
pub fn run_id(&self) -> String {
|
||||
self.inner.borrow().run_id.clone()
|
||||
}
|
||||
|
||||
/// Typed policy (used to install the host sink).
|
||||
pub fn config(&self) -> ObservationConfig {
|
||||
self.config.clone()
|
||||
}
|
||||
|
||||
/// Installable host sink handle.
|
||||
pub fn host_sink(&self) -> HostEventSink {
|
||||
HostEventSink {
|
||||
stream: self.clone(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Write one raw public event. Used for lifecycle and terminal events.
|
||||
pub fn emit(&self, kind: &str, payload: Json) -> Result<(), String> {
|
||||
self.inner.borrow_mut().emit(kind, payload)
|
||||
}
|
||||
|
||||
/// Write `run.started`.
|
||||
pub fn started(
|
||||
&self,
|
||||
entry: &str,
|
||||
mode: &str,
|
||||
root_id: &str,
|
||||
analysis_digest: &str,
|
||||
) -> Result<(), String> {
|
||||
self.emit(
|
||||
"run.started",
|
||||
json!({
|
||||
"entry": entry,
|
||||
"mode": mode,
|
||||
"source": {
|
||||
"root_id": root_id,
|
||||
"analysis_digest": analysis_digest,
|
||||
},
|
||||
"started_unix_ms": unix_millis(),
|
||||
}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Write the successful terminal event.
|
||||
pub fn completed(&self, value: &Value) -> Result<(), String> {
|
||||
self.emit(
|
||||
"run.completed",
|
||||
json!({"status": "ok", "value": marqdo_value::to_wire(value)}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Write the failed terminal event.
|
||||
pub fn failed(&self, error: &RuntimeError) -> Result<(), String> {
|
||||
self.emit(
|
||||
"run.failed",
|
||||
json!({
|
||||
"status": "error",
|
||||
"error": {
|
||||
"code": error.code(),
|
||||
"message": error.message,
|
||||
"module_id": error.module_id.as_deref(),
|
||||
"span": error.span.map(span_json),
|
||||
}
|
||||
}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Write a failed terminal event for a CLI-level failure that still has a
|
||||
/// stable code (for example `cli.trace_failed`).
|
||||
pub fn failed_error(&self, code: &str, message: &str) -> Result<(), String> {
|
||||
self.emit(
|
||||
"run.failed",
|
||||
json!({
|
||||
"status": "error",
|
||||
"error": {"code": code, "message": message},
|
||||
}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Write the pre-execution rejection terminal event.
|
||||
pub fn rejected(&self, phase: &str, code: &str, message: &str) -> Result<(), String> {
|
||||
self.emit(
|
||||
"run.rejected",
|
||||
json!({
|
||||
"status": "rejected",
|
||||
"phase": phase,
|
||||
"error": {"code": code, "message": message},
|
||||
}),
|
||||
)
|
||||
}
|
||||
|
||||
/// Encode and write one typed host/runtime observation event.
|
||||
pub fn emit_observation(&self, event: ObservationEvent<'_>) -> Result<(), String> {
|
||||
let (kind, payload) = observation_payload(event);
|
||||
self.emit(kind, payload)
|
||||
}
|
||||
}
|
||||
|
||||
/// `ObservationSink` adapter installed into `StdHost`.
|
||||
pub struct HostEventSink {
|
||||
stream: EventStream,
|
||||
}
|
||||
|
||||
impl ObservationSink for HostEventSink {
|
||||
fn emit(&mut self, event: ObservationEvent<'_>) -> Result<(), ObservationError> {
|
||||
self.stream
|
||||
.emit_observation(event)
|
||||
.map_err(ObservationError::new)
|
||||
}
|
||||
}
|
||||
|
||||
struct JsonlWriter {
|
||||
out: Box<dyn Write>,
|
||||
run_id: String,
|
||||
seq: u64,
|
||||
}
|
||||
|
||||
impl JsonlWriter {
|
||||
fn emit(&mut self, kind: &str, payload: Json) -> Result<(), String> {
|
||||
let event = json!({
|
||||
"schema": SCHEMA,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"run_id": self.run_id,
|
||||
"seq": self.seq,
|
||||
"kind": kind,
|
||||
"payload": payload,
|
||||
});
|
||||
let mut line = serde_json::to_vec(&event)
|
||||
.map_err(|error| format!("cannot encode execution event: {error}"))?;
|
||||
line.push(b'\n');
|
||||
// Flush each line: line-buffered batching would hide real-time output
|
||||
// behind the run duration (RFC-OBS-0001 §5.2).
|
||||
self.out
|
||||
.write_all(&line)
|
||||
.and_then(|()| self.out.flush())
|
||||
.map_err(|error| format!("cannot write execution event stream: {error}"))?;
|
||||
self.seq += 1;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
fn observation_payload(event: ObservationEvent<'_>) -> (&'static str, Json) {
|
||||
match event {
|
||||
ObservationEvent::StdoutChunk { data } => (
|
||||
"stdout.chunk",
|
||||
json!({
|
||||
"encoding": "base64",
|
||||
"data_base64": base64_encode(data),
|
||||
"byte_count": data.len(),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::StderrChunk { data } => (
|
||||
"stderr.chunk",
|
||||
json!({
|
||||
"encoding": "base64",
|
||||
"data_base64": base64_encode(data),
|
||||
"byte_count": data.len(),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::CallEnter {
|
||||
frame_id,
|
||||
parent_frame_id,
|
||||
function_id,
|
||||
module_id,
|
||||
span,
|
||||
} => (
|
||||
"call.enter",
|
||||
json!({
|
||||
"frame_id": frame_id.as_wire(),
|
||||
"parent_frame_id": parent_frame_id.map(FrameId::as_wire),
|
||||
"function_id": function_id,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::CallExit {
|
||||
frame_id,
|
||||
status,
|
||||
module_id,
|
||||
span,
|
||||
} => (
|
||||
"call.exit",
|
||||
json!({
|
||||
"frame_id": frame_id.as_wire(),
|
||||
"status": status,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::Return {
|
||||
frame_id,
|
||||
value_type,
|
||||
module_id,
|
||||
span,
|
||||
} => (
|
||||
"return",
|
||||
json!({
|
||||
"frame_id": frame_id.as_wire(),
|
||||
"value_type": value_type,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::BranchEval {
|
||||
frame_id,
|
||||
result,
|
||||
module_id,
|
||||
span,
|
||||
} => (
|
||||
"branch.eval",
|
||||
json!({
|
||||
"frame_id": frame_id.as_wire(),
|
||||
"result": result,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::LoopIteration {
|
||||
frame_id,
|
||||
decision,
|
||||
module_id,
|
||||
span,
|
||||
} => (
|
||||
"loop.iteration",
|
||||
json!({
|
||||
"frame_id": frame_id.as_wire(),
|
||||
"decision": decision,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::Effect {
|
||||
operation,
|
||||
result_code,
|
||||
module_id,
|
||||
span,
|
||||
} => (
|
||||
"effect",
|
||||
json!({
|
||||
"operation": operation,
|
||||
"result_code": result_code,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
}),
|
||||
),
|
||||
ObservationEvent::VariableAssigned {
|
||||
frame_id,
|
||||
name,
|
||||
value_type,
|
||||
module_id,
|
||||
span,
|
||||
value_state,
|
||||
value,
|
||||
} => (
|
||||
"variable.assigned",
|
||||
value_event_payload(
|
||||
frame_id,
|
||||
name,
|
||||
None,
|
||||
value_type,
|
||||
module_id,
|
||||
span,
|
||||
value_state,
|
||||
value,
|
||||
),
|
||||
),
|
||||
ObservationEvent::ParameterObserved {
|
||||
frame_id,
|
||||
name,
|
||||
source,
|
||||
value_type,
|
||||
module_id,
|
||||
span,
|
||||
value_state,
|
||||
value,
|
||||
} => (
|
||||
"parameter.observed",
|
||||
value_event_payload(
|
||||
frame_id,
|
||||
name,
|
||||
Some(source),
|
||||
value_type,
|
||||
module_id,
|
||||
span,
|
||||
value_state,
|
||||
value,
|
||||
),
|
||||
),
|
||||
ObservationEvent::ObservationTruncated {
|
||||
reason,
|
||||
limit,
|
||||
written,
|
||||
dropped,
|
||||
} => (
|
||||
"observation.truncated",
|
||||
json!({
|
||||
"reason": reason,
|
||||
"limit": limit,
|
||||
"written": written,
|
||||
"dropped": dropped,
|
||||
}),
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
#[allow(clippy::too_many_arguments)]
|
||||
fn value_event_payload(
|
||||
frame_id: FrameId,
|
||||
name: &str,
|
||||
source: Option<ParameterSource>,
|
||||
value_type: &str,
|
||||
module_id: &str,
|
||||
span: Option<marqdo_span::Span>,
|
||||
value_state: ValueState,
|
||||
value: Option<marqdo_host::ObservedValue>,
|
||||
) -> Json {
|
||||
let mut payload = json!({
|
||||
"frame_id": frame_id.as_wire(),
|
||||
"name": name,
|
||||
"value_type": value_type,
|
||||
"module_id": module_id,
|
||||
"span": span.map(span_json),
|
||||
"value_state": value_state.as_str(),
|
||||
});
|
||||
if let Some(source) = source {
|
||||
payload["source"] = Json::String(source.as_str().to_string());
|
||||
}
|
||||
if let Some(value) = value {
|
||||
payload["value"] = value.wire;
|
||||
}
|
||||
payload
|
||||
}
|
||||
|
||||
fn span_json(span: marqdo_span::Span) -> Json {
|
||||
json!({"start": span.start, "end": span.end})
|
||||
}
|
||||
|
||||
fn new_run_id() -> String {
|
||||
format!("{}-{}", std::process::id(), unix_nanos())
|
||||
}
|
||||
|
||||
fn unix_nanos() -> u128 {
|
||||
SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map(|duration| duration.as_nanos())
|
||||
.unwrap_or(0)
|
||||
}
|
||||
|
||||
fn unix_millis() -> u128 {
|
||||
SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map(|duration| duration.as_millis())
|
||||
.unwrap_or(0)
|
||||
}
|
||||
|
||||
/// Standard padded base64 (no external dependency; the protocol only needs
|
||||
/// one canonical encoding).
|
||||
pub fn base64_encode(bytes: &[u8]) -> String {
|
||||
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
|
||||
let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4);
|
||||
for chunk in bytes.chunks(3) {
|
||||
let b0 = chunk[0] as u32;
|
||||
let b1 = chunk.get(1).copied().unwrap_or(0) as u32;
|
||||
let b2 = chunk.get(2).copied().unwrap_or(0) as u32;
|
||||
let triple = (b0 << 16) | (b1 << 8) | b2;
|
||||
out.push(ALPHABET[((triple >> 18) & 0x3f) as usize] as char);
|
||||
out.push(ALPHABET[((triple >> 12) & 0x3f) as usize] as char);
|
||||
out.push(if chunk.len() > 1 {
|
||||
ALPHABET[((triple >> 6) & 0x3f) as usize] as char
|
||||
} else {
|
||||
'='
|
||||
});
|
||||
out.push(if chunk.len() > 2 {
|
||||
ALPHABET[(triple & 0x3f) as usize] as char
|
||||
} else {
|
||||
'='
|
||||
});
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn base64_matches_known_vectors() {
|
||||
assert_eq!(base64_encode(b""), "");
|
||||
assert_eq!(base64_encode(b"f"), "Zg==");
|
||||
assert_eq!(base64_encode(b"fo"), "Zm8=");
|
||||
assert_eq!(base64_encode(b"foo"), "Zm9v");
|
||||
assert_eq!(
|
||||
base64_encode("开始文本\n".as_bytes()),
|
||||
"5byA5aeL5paH5pysCg=="
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_unselected_value_is_encoded() {
|
||||
let options = ObservationOptions {
|
||||
variables: vec!["visible".to_string()],
|
||||
..ObservationOptions::default()
|
||||
};
|
||||
let config = options.config();
|
||||
assert_eq!(config.level(), "values");
|
||||
assert!(config.selected_variables.contains("visible"));
|
||||
assert!(!config.allow_text_values);
|
||||
let empty = ObservationOptions::default().config();
|
||||
assert_eq!(empty.level(), "structural");
|
||||
assert!(!empty.values_enabled());
|
||||
}
|
||||
}
|
||||
+104
-14
@@ -7,6 +7,7 @@
|
||||
mod analysis;
|
||||
mod args;
|
||||
mod commands;
|
||||
mod execution_events;
|
||||
mod extension_descriptors;
|
||||
mod extension_selection;
|
||||
mod loader;
|
||||
@@ -34,6 +35,83 @@ struct Cli {
|
||||
command: Command,
|
||||
}
|
||||
|
||||
/// Execution Events v1 options (RFC-OBS-0001).
|
||||
///
|
||||
/// `--event-stream jsonl` makes the CLI stdout a dedicated NDJSON channel;
|
||||
/// program stdout/stderr become events. It is mutually exclusive with
|
||||
/// `--json` and is not accepted by static commands.
|
||||
#[derive(Args, Clone)]
|
||||
struct ObserveArgs {
|
||||
/// Stream Execution Events v1 as JSON Lines on stdout (only `jsonl`).
|
||||
#[arg(
|
||||
long = "event-stream",
|
||||
value_name = "FORMAT",
|
||||
value_parser = [execution_events::FORMAT_JSONL],
|
||||
conflicts_with = "json"
|
||||
)]
|
||||
event_stream: Option<String>,
|
||||
/// Publish the value of one exactly named local variable (repeatable).
|
||||
#[arg(
|
||||
long = "observe-variable",
|
||||
value_name = "NAME",
|
||||
requires = "event_stream"
|
||||
)]
|
||||
observe_variable: Vec<String>,
|
||||
/// Publish the value of one exactly named parameter (repeatable).
|
||||
#[arg(
|
||||
long = "observe-parameter",
|
||||
value_name = "NAME",
|
||||
requires = "event_stream"
|
||||
)]
|
||||
observe_parameter: Vec<String>,
|
||||
/// Allow selected Text values to be published (second explicit consent).
|
||||
#[arg(long = "observe-text-values", requires = "event_stream")]
|
||||
observe_text_values: bool,
|
||||
/// Maximum encoded source bytes for one observed value (0 = unlimited).
|
||||
#[arg(
|
||||
long = "observe-max-value-bytes",
|
||||
value_name = "BYTES",
|
||||
requires = "event_stream"
|
||||
)]
|
||||
observe_max_value_bytes: Option<usize>,
|
||||
/// Override the structural/value event budget (0 = unlimited).
|
||||
#[arg(
|
||||
long = "observe-max-events",
|
||||
value_name = "COUNT",
|
||||
requires = "event_stream"
|
||||
)]
|
||||
observe_max_events: Option<u64>,
|
||||
/// Override the approximate structural/value byte budget (0 = unlimited).
|
||||
#[arg(
|
||||
long = "observe-max-bytes",
|
||||
value_name = "BYTES",
|
||||
requires = "event_stream"
|
||||
)]
|
||||
observe_max_bytes: Option<u64>,
|
||||
}
|
||||
|
||||
impl ObserveArgs {
|
||||
fn options(&self) -> Option<execution_events::ObservationOptions> {
|
||||
self.event_stream.as_ref()?;
|
||||
let mut options = execution_events::ObservationOptions {
|
||||
variables: self.observe_variable.clone(),
|
||||
parameters: self.observe_parameter.clone(),
|
||||
allow_text_values: self.observe_text_values,
|
||||
..execution_events::ObservationOptions::default()
|
||||
};
|
||||
if let Some(bytes) = self.observe_max_value_bytes {
|
||||
options.max_value_bytes = bytes;
|
||||
}
|
||||
if let Some(events) = self.observe_max_events {
|
||||
options.max_events = events;
|
||||
}
|
||||
if let Some(bytes) = self.observe_max_bytes {
|
||||
options.max_bytes = bytes;
|
||||
}
|
||||
Some(options)
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Subcommand)]
|
||||
enum Command {
|
||||
/// Initialise a new Marqdo project.
|
||||
@@ -201,6 +279,8 @@ struct RunArgs {
|
||||
/// Include the host effect trace.
|
||||
#[arg(long)]
|
||||
trace: bool,
|
||||
#[command(flatten)]
|
||||
observe: ObserveArgs,
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
@@ -220,6 +300,8 @@ struct CallArgs {
|
||||
/// Include the host effect trace.
|
||||
#[arg(long)]
|
||||
trace: bool,
|
||||
#[command(flatten)]
|
||||
observe: ObserveArgs,
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
@@ -432,23 +514,31 @@ fn dispatch() -> i32 {
|
||||
};
|
||||
commands::inspect(args.file.as_deref(), &flags, args.json, &args.plugin)
|
||||
}
|
||||
Command::Run(args) => commands::execute(
|
||||
args.file.as_deref(),
|
||||
None,
|
||||
&[],
|
||||
&args.sandbox.settings(),
|
||||
args.json,
|
||||
args.trace,
|
||||
),
|
||||
Command::Call(args) => match commands::parse_named_args(&args.args) {
|
||||
Ok(named) => commands::execute(
|
||||
Some(&args.file),
|
||||
Some(&args.function),
|
||||
&named,
|
||||
Command::Run(args) => {
|
||||
let observation = args.observe.options();
|
||||
commands::execute(
|
||||
args.file.as_deref(),
|
||||
None,
|
||||
&[],
|
||||
&args.sandbox.settings(),
|
||||
args.json,
|
||||
args.trace,
|
||||
),
|
||||
observation.as_ref(),
|
||||
)
|
||||
}
|
||||
Command::Call(args) => match commands::parse_named_args(&args.args) {
|
||||
Ok(named) => {
|
||||
let observation = args.observe.options();
|
||||
commands::execute(
|
||||
Some(&args.file),
|
||||
Some(&args.function),
|
||||
&named,
|
||||
&args.sandbox.settings(),
|
||||
args.json,
|
||||
args.trace,
|
||||
observation.as_ref(),
|
||||
)
|
||||
}
|
||||
Err(error) => {
|
||||
eprintln!("error: {error}");
|
||||
2
|
||||
|
||||
+13
-8
@@ -21,15 +21,20 @@ pub fn write(
|
||||
entry: &str,
|
||||
status: &str,
|
||||
path: &Path,
|
||||
run_id: Option<&str>,
|
||||
) -> 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)
|
||||
);
|
||||
// A combined `--event-stream` run shares the CLI-generated opaque run id
|
||||
// with Execution Events v1; Trace v2 keeps its schema and field types.
|
||||
let run_id = run_id.map(str::to_string).unwrap_or_else(|| {
|
||||
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 = project.identity.root_id();
|
||||
let state = host.trace_state();
|
||||
|
||||
@@ -133,12 +133,7 @@ fn unknown_tool_name_installs_and_dispatches() {
|
||||
|
||||
#[test]
|
||||
fn public_schemas_are_valid_json_and_versioned() {
|
||||
for name in [
|
||||
"analysis-v1",
|
||||
"trace-v1",
|
||||
"tool-v1",
|
||||
"execution-events-v1",
|
||||
] {
|
||||
for name in ["analysis-v1", "trace-v1", "tool-v1", "execution-events-v1"] {
|
||||
let path = repo()
|
||||
.join("spec/schemas")
|
||||
.join(format!("{name}.schema.json"));
|
||||
|
||||
@@ -0,0 +1,569 @@
|
||||
//! Black-box Execution Events v1 contract tests (RFC-OBS-0001).
|
||||
//!
|
||||
//! These drive the real `marqdo` binary (`CARGO_BIN_EXE_marqdo`) and parse the
|
||||
//! stdout line stream exactly like an external consumer. They cover the P0
|
||||
//! envelope/lifecycle/byte-fidelity contract and the P1 frame/value policy,
|
||||
//! plus trace coexistence, truncation, live delivery and a broken pipe.
|
||||
|
||||
use std::fs;
|
||||
use std::io::{BufRead, BufReader, Read};
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::{Command, Stdio};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use serde_json::Value;
|
||||
|
||||
const BASIC: &str =
|
||||
"## @exec main\n\n`打印(\"START\")`\n\n`n = 10`\n\n`打印(\"DONE\")`\n\n`return n`\n";
|
||||
|
||||
struct TempDir(PathBuf);
|
||||
|
||||
impl TempDir {
|
||||
fn new(tag: &str) -> Self {
|
||||
let nanos = std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|duration| duration.as_nanos())
|
||||
.unwrap_or(0);
|
||||
let path = std::env::temp_dir().join(format!(
|
||||
"marqdo-execution-events-{tag}-{}-{nanos}",
|
||||
std::process::id()
|
||||
));
|
||||
let _ = fs::remove_dir_all(&path);
|
||||
fs::create_dir_all(&path).unwrap();
|
||||
Self(path)
|
||||
}
|
||||
|
||||
fn path(&self) -> &Path {
|
||||
&self.0
|
||||
}
|
||||
|
||||
fn write(&self, name: &str, source: &str) -> PathBuf {
|
||||
let path = self.0.join(name);
|
||||
fs::write(&path, source).unwrap();
|
||||
path
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for TempDir {
|
||||
fn drop(&mut self) {
|
||||
let _ = fs::remove_dir_all(&self.0);
|
||||
}
|
||||
}
|
||||
|
||||
fn cli(dir: &Path, args: &[&str]) -> std::process::Output {
|
||||
Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args(args)
|
||||
.current_dir(dir)
|
||||
.output()
|
||||
.expect("run marqdo")
|
||||
}
|
||||
|
||||
fn parse_events(stdout: &[u8]) -> Vec<Value> {
|
||||
String::from_utf8_lossy(stdout)
|
||||
.lines()
|
||||
.map(|line| {
|
||||
serde_json::from_str(line)
|
||||
.unwrap_or_else(|error| panic!("invalid JSONL line {line:?}: {error}"))
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
fn events_of<'a>(events: &'a [Value], kind: &str) -> Vec<&'a Value> {
|
||||
events
|
||||
.iter()
|
||||
.filter(|event| event["kind"] == kind)
|
||||
.collect()
|
||||
}
|
||||
|
||||
fn chunk_bytes(events: &[Value], kind: &str) -> Vec<u8> {
|
||||
let mut out = Vec::new();
|
||||
for event in events_of(events, kind) {
|
||||
let payload = &event["payload"];
|
||||
assert_eq!(payload["encoding"], "base64");
|
||||
let data = base64_decode(payload["data_base64"].as_str().unwrap());
|
||||
assert_eq!(
|
||||
payload["byte_count"].as_u64().unwrap() as usize,
|
||||
data.len(),
|
||||
"byte_count must equal decoded length"
|
||||
);
|
||||
out.extend(data);
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn base64_decode(text: &str) -> Vec<u8> {
|
||||
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
|
||||
let mut out = Vec::new();
|
||||
let bytes: Vec<u8> = text
|
||||
.bytes()
|
||||
.filter(|byte| *byte != b'=')
|
||||
.map(|byte| {
|
||||
ALPHABET
|
||||
.iter()
|
||||
.position(|item| *item == byte)
|
||||
.unwrap_or_else(|| panic!("invalid base64 byte {byte}")) as u8
|
||||
})
|
||||
.collect();
|
||||
for chunk in bytes.chunks(4) {
|
||||
let mut triple = 0u32;
|
||||
for (index, byte) in chunk.iter().enumerate() {
|
||||
triple |= u32::from(*byte) << (18 - 6 * index);
|
||||
}
|
||||
out.push((triple >> 16) as u8);
|
||||
if chunk.len() > 2 {
|
||||
out.push((triple >> 8) as u8);
|
||||
}
|
||||
if chunk.len() > 3 {
|
||||
out.push(triple as u8);
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn assert_envelope(events: &[Value]) {
|
||||
assert!(!events.is_empty());
|
||||
let first = &events[0];
|
||||
assert_eq!(first["kind"], "stream.opened");
|
||||
assert_eq!(first["schema"], "marqdo.execution-events");
|
||||
assert_eq!(first["schema_version"], 1);
|
||||
assert_eq!(first["seq"], 0);
|
||||
let run_id = first["run_id"].as_str().unwrap().to_string();
|
||||
for (index, event) in events.iter().enumerate() {
|
||||
assert_eq!(event["seq"].as_u64().unwrap(), index as u64);
|
||||
assert_eq!(event["run_id"], run_id);
|
||||
assert_eq!(event["schema_version"], 1);
|
||||
assert!(event["payload"].is_object());
|
||||
}
|
||||
let terminals: Vec<&str> = events
|
||||
.iter()
|
||||
.filter_map(|event| match event["kind"].as_str().unwrap() {
|
||||
"run.completed" | "run.failed" | "run.rejected" => {
|
||||
Some(event["kind"].as_str().unwrap())
|
||||
}
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(terminals.len(), 1, "exactly one terminal event");
|
||||
assert_eq!(events.last().unwrap()["kind"], terminals[0]);
|
||||
assert_eq!(events_of(events, "stream.opened").len(), 1);
|
||||
assert!(events_of(events, "run.started").len() <= 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn basic_stream_is_pure_jsonl_and_reconstructs_program_output() {
|
||||
let dir = TempDir::new("basic");
|
||||
dir.write("index.mq.md", BASIC);
|
||||
let output = cli(
|
||||
dir.path(),
|
||||
&["run", "index.mq.md", "--event-stream", "jsonl"],
|
||||
);
|
||||
assert_eq!(
|
||||
output.status.code(),
|
||||
Some(0),
|
||||
"{}",
|
||||
String::from_utf8_lossy(&output.stderr)
|
||||
);
|
||||
let events = parse_events(&output.stdout);
|
||||
assert_envelope(&events);
|
||||
assert_eq!(events_of(&events, "run.started").len(), 1);
|
||||
assert_eq!(chunk_bytes(&events, "stdout.chunk"), b"START\nDONE\n");
|
||||
let terminal = events.last().unwrap();
|
||||
assert_eq!(terminal["kind"], "run.completed");
|
||||
assert_eq!(terminal["payload"]["status"], "ok");
|
||||
assert_eq!(terminal["payload"]["value"]["decimal"], "10");
|
||||
// Terminal sequence is after all chunk sequences.
|
||||
let terminal_seq = terminal["seq"].as_u64().unwrap();
|
||||
for event in events_of(&events, "stdout.chunk") {
|
||||
assert!(event["seq"].as_u64().unwrap() < terminal_seq);
|
||||
}
|
||||
|
||||
// The normal (non-event) run writes the same bytes and return value.
|
||||
let normal = cli(dir.path(), &["run", "index.mq.md"]);
|
||||
assert_eq!(normal.status.code(), Some(0));
|
||||
assert_eq!(normal.stdout, b"START\nDONE\n");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn event_stream_rejects_mixed_json_and_static_commands() {
|
||||
let dir = TempDir::new("reject");
|
||||
dir.write("index.mq.md", BASIC);
|
||||
let mixed = cli(
|
||||
dir.path(),
|
||||
&["run", "index.mq.md", "--event-stream", "jsonl", "--json"],
|
||||
);
|
||||
assert_eq!(mixed.status.code(), Some(2));
|
||||
assert!(mixed.stdout.is_empty(), "no mixed stdout");
|
||||
assert!(String::from_utf8_lossy(&mixed.stderr).contains("--json"));
|
||||
|
||||
for command in ["check", "inspect"] {
|
||||
let rejected = cli(
|
||||
dir.path(),
|
||||
&[command, "index.mq.md", "--event-stream", "jsonl"],
|
||||
);
|
||||
assert_eq!(
|
||||
rejected.status.code(),
|
||||
Some(2),
|
||||
"{command} must reject the option"
|
||||
);
|
||||
assert!(rejected.stdout.is_empty(), "{command} must not execute");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prepare_and_runtime_failures_have_defined_terminals() {
|
||||
let dir = TempDir::new("failures");
|
||||
dir.write("broken.mq.md", "## @exec main\n\n`if true`\n\n`return 1`\n");
|
||||
let rejected = cli(
|
||||
dir.path(),
|
||||
&["run", "broken.mq.md", "--event-stream", "jsonl"],
|
||||
);
|
||||
assert_eq!(rejected.status.code(), Some(1));
|
||||
let events = parse_events(&rejected.stdout);
|
||||
assert_envelope(&events);
|
||||
assert_eq!(events.last().unwrap()["kind"], "run.rejected");
|
||||
assert_eq!(events.last().unwrap()["payload"]["phase"], "compile");
|
||||
assert!(
|
||||
events_of(&events, "run.started").is_empty(),
|
||||
"a rejected run never starts"
|
||||
);
|
||||
|
||||
dir.write(
|
||||
"runtime.mq.md",
|
||||
"## @exec main\n\n`x = 1 / 0`\n\n`return x`\n",
|
||||
);
|
||||
let failed = cli(
|
||||
dir.path(),
|
||||
&["run", "runtime.mq.md", "--event-stream", "jsonl"],
|
||||
);
|
||||
assert_eq!(failed.status.code(), Some(1));
|
||||
let events = parse_events(&failed.stdout);
|
||||
assert_envelope(&events);
|
||||
assert_eq!(events.last().unwrap()["kind"], "run.failed");
|
||||
assert_eq!(
|
||||
events.last().unwrap()["payload"]["error"]["code"],
|
||||
"runtime.division_by_zero"
|
||||
);
|
||||
assert!(events_of(&events, "run.completed").is_empty());
|
||||
let exit = events_of(&events, "call.exit");
|
||||
assert_eq!(exit.len(), 1, "failure still closes the entered frame");
|
||||
assert_eq!(exit[0]["payload"]["status"], "runtime.division_by_zero");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn value_observation_is_exact_and_requires_text_consent() {
|
||||
let dir = TempDir::new("values");
|
||||
dir.write(
|
||||
"index.mq.md",
|
||||
"## @exec main\n\n`secret_token = \"DO_NOT_LEAK_SENTINEL_1\"`\n\n`visible_count = 42`\n\n`return visible_count`\n",
|
||||
);
|
||||
// Default: metadata only; no value, no sentinel anywhere.
|
||||
let default = cli(
|
||||
dir.path(),
|
||||
&["run", "index.mq.md", "--event-stream", "jsonl"],
|
||||
);
|
||||
assert_eq!(default.status.code(), Some(0));
|
||||
assert!(!String::from_utf8_lossy(&default.stdout).contains("DO_NOT_LEAK_SENTINEL_1"));
|
||||
for event in events_of(&parse_events(&default.stdout), "variable.assigned") {
|
||||
assert_eq!(event["payload"]["value_state"], "not_requested");
|
||||
assert!(event["payload"].get("value").is_none());
|
||||
}
|
||||
|
||||
let selected = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--observe-variable",
|
||||
"visible_count",
|
||||
],
|
||||
);
|
||||
let events = parse_events(&selected.stdout);
|
||||
let visible = events_of(&events, "variable.assigned")
|
||||
.into_iter()
|
||||
.find(|event| event["payload"]["name"] == "visible_count")
|
||||
.expect("visible_count event");
|
||||
assert_eq!(visible["payload"]["value_state"], "observed");
|
||||
assert_eq!(visible["payload"]["value"]["decimal"], "42");
|
||||
// The unselected variable must never carry a value.
|
||||
for event in events_of(&events, "variable.assigned") {
|
||||
if event["payload"]["name"] == "secret_token" {
|
||||
assert_eq!(event["payload"]["value_state"], "not_requested");
|
||||
assert!(event["payload"].get("value").is_none());
|
||||
}
|
||||
}
|
||||
|
||||
// Selecting the text variable is not enough: the bytes stay redacted.
|
||||
let redacted = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--observe-variable",
|
||||
"secret_token",
|
||||
],
|
||||
);
|
||||
assert!(!String::from_utf8_lossy(&redacted.stdout).contains("DO_NOT_LEAK_SENTINEL_1"));
|
||||
let events = parse_events(&redacted.stdout);
|
||||
let secret = events_of(&events, "variable.assigned")
|
||||
.into_iter()
|
||||
.find(|event| event["payload"]["name"] == "secret_token")
|
||||
.expect("secret_token event");
|
||||
assert_eq!(secret["payload"]["value_state"], "redacted");
|
||||
assert!(secret["payload"].get("value").is_none());
|
||||
|
||||
// A second explicit consent publishes only the selected value.
|
||||
let consented = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--observe-variable",
|
||||
"secret_token",
|
||||
"--observe-text-values",
|
||||
],
|
||||
);
|
||||
let stdout = String::from_utf8_lossy(&consented.stdout);
|
||||
assert!(stdout.contains("DO_NOT_LEAK_SENTINEL_1"));
|
||||
let events = parse_events(&consented.stdout);
|
||||
let secret = events_of(&events, "variable.assigned")
|
||||
.into_iter()
|
||||
.find(|event| event["payload"]["name"] == "secret_token")
|
||||
.unwrap();
|
||||
assert_eq!(secret["payload"]["value_state"], "observed");
|
||||
assert_eq!(
|
||||
secret["payload"]["value"]["value"],
|
||||
"DO_NOT_LEAK_SENTINEL_1"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn binary_and_multibyte_output_is_byte_exact() {
|
||||
let dir = TempDir::new("bytes");
|
||||
dir.write(
|
||||
"index.mq.md",
|
||||
"## @exec main\n\n`打印(\"开始文本\")`\n\n`流 = resource.open(\"stdio\", \"stdout\", [\"write\"])`\n\n`内存 = memory.new(1, 1)`\n\n`内存[0] = 255`\n\n`内存[1] = 0`\n\n`内存[2] = 128`\n\n`写入 = resource.write(流, 内存, 0, 3)`\n\n`关闭 = resource.close(流)`\n\n`return 写入`\n",
|
||||
);
|
||||
let normal = cli(dir.path(), &["run", "index.mq.md"]);
|
||||
assert_eq!(
|
||||
normal.status.code(),
|
||||
Some(0),
|
||||
"{}",
|
||||
String::from_utf8_lossy(&normal.stderr)
|
||||
);
|
||||
let streamed = cli(
|
||||
dir.path(),
|
||||
&["run", "index.mq.md", "--event-stream", "jsonl"],
|
||||
);
|
||||
assert_eq!(streamed.status.code(), Some(0));
|
||||
let events = parse_events(&streamed.stdout);
|
||||
let chunks = chunk_bytes(&events, "stdout.chunk");
|
||||
assert_eq!(
|
||||
chunks, normal.stdout,
|
||||
"error text may not go to stdout; concatenated chunks must equal the program bytes"
|
||||
);
|
||||
assert!(chunks.starts_with("开始文本".as_bytes()));
|
||||
assert_eq!(&chunks[chunks.len() - 3..], &[0xff, 0x00, 0x80]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn trace_file_coexists_and_shares_the_run_identity() {
|
||||
let dir = TempDir::new("trace");
|
||||
dir.write("index.mq.md", BASIC);
|
||||
let trace_path = dir.path().join("trace.json");
|
||||
let output = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--trace-file",
|
||||
trace_path.to_str().unwrap(),
|
||||
],
|
||||
);
|
||||
assert_eq!(output.status.code(), Some(0));
|
||||
let events = parse_events(&output.stdout);
|
||||
assert_envelope(&events);
|
||||
let trace: Value = serde_json::from_slice(&fs::read(&trace_path).unwrap()).unwrap();
|
||||
assert_eq!(trace["schema"], "marqdo.trace");
|
||||
assert_eq!(trace["schema_version"], 2);
|
||||
assert_eq!(trace["run"]["id"], events[0]["run_id"]);
|
||||
let started = events_of(&events, "run.started")[0];
|
||||
assert_eq!(
|
||||
started["payload"]["source"]["analysis_digest"],
|
||||
trace["source"]["analysis_digest"]
|
||||
);
|
||||
assert!(
|
||||
events_of(&events, "run.completed").len() == 1,
|
||||
"trace writing does not suppress the terminal event"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structural_budget_truncates_without_losing_critical_events() {
|
||||
let dir = TempDir::new("budget");
|
||||
dir.write("index.mq.md", BASIC);
|
||||
let output = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--observe-max-events",
|
||||
"5",
|
||||
],
|
||||
);
|
||||
assert_eq!(output.status.code(), Some(0));
|
||||
let events = parse_events(&output.stdout);
|
||||
assert_envelope(&events);
|
||||
let markers = events_of(&events, "observation.truncated");
|
||||
assert_eq!(markers.len(), 1);
|
||||
assert_eq!(markers[0]["payload"]["reason"], "event_budget");
|
||||
assert_eq!(chunk_bytes(&events, "stdout.chunk"), b"START\nDONE\n");
|
||||
assert_eq!(events.last().unwrap()["kind"], "run.completed");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn output_budget_still_fails_the_run_and_emits_no_chunk() {
|
||||
let dir = TempDir::new("output-budget");
|
||||
dir.write("index.mq.md", BASIC);
|
||||
let output = cli(
|
||||
dir.path(),
|
||||
&[
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--max-output",
|
||||
"3",
|
||||
],
|
||||
);
|
||||
assert_eq!(output.status.code(), Some(1));
|
||||
let events = parse_events(&output.stdout);
|
||||
assert_envelope(&events);
|
||||
assert!(chunk_bytes(&events, "stdout.chunk").is_empty());
|
||||
assert_eq!(events.last().unwrap()["kind"], "run.failed");
|
||||
assert_eq!(
|
||||
events.last().unwrap()["payload"]["error"]["code"],
|
||||
"resource.exhausted"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn live_chunks_arrive_while_the_program_is_still_running() {
|
||||
let dir = TempDir::new("live");
|
||||
let source = "## @exec main\n\n`打印(\"READY\")`\n\n`i = 0`\n\n`while i < 2000000`\n\n`i = i + 1`\n\n`end`\n\n`打印(\"FINISH\")`\n\n`return i`\n";
|
||||
dir.write("index.mq.md", source);
|
||||
let mut child = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--observe-max-events",
|
||||
"20",
|
||||
"--fuel",
|
||||
"100000000",
|
||||
])
|
||||
.current_dir(dir.path())
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.expect("spawn marqdo");
|
||||
let mut reader = BufReader::new(child.stdout.take().unwrap());
|
||||
let mut events = Vec::new();
|
||||
let mut ready_seen_alive = false;
|
||||
loop {
|
||||
let mut line = String::new();
|
||||
let read = reader.read_line(&mut line).expect("read event line");
|
||||
if read == 0 {
|
||||
break;
|
||||
}
|
||||
let event: Value = serde_json::from_str(line.trim_end()).expect("event JSON");
|
||||
if event["kind"] == "stdout.chunk" {
|
||||
let data = base64_decode(event["payload"]["data_base64"].as_str().unwrap());
|
||||
if data == b"READY\n" || data == b"READY" {
|
||||
assert!(
|
||||
child.try_wait().expect("try_wait").is_none(),
|
||||
"READY was only readable after the process exited; this is not live output"
|
||||
);
|
||||
ready_seen_alive = true;
|
||||
}
|
||||
}
|
||||
events.push(event);
|
||||
}
|
||||
let status = child.wait().expect("wait");
|
||||
assert_eq!(status.code(), Some(0));
|
||||
assert!(
|
||||
ready_seen_alive,
|
||||
"the READY chunk must be readable before the process exits"
|
||||
);
|
||||
assert_eq!(chunk_bytes(&events, "stdout.chunk"), b"READY\nFINISH\n");
|
||||
assert_eq!(events.last().unwrap()["kind"], "run.completed");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn broken_pipe_makes_the_run_fail_instead_of_running_forever() {
|
||||
let dir = TempDir::new("pipe");
|
||||
let source = "## @exec main\n\n`打印(\"START\")`\n\n`i = 0`\n\n`while i < 5000000`\n\n`i = i + 1`\n\n`end`\n\n`return i`\n";
|
||||
dir.write("index.mq.md", source);
|
||||
let mut child = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args([
|
||||
"run",
|
||||
"index.mq.md",
|
||||
"--event-stream",
|
||||
"jsonl",
|
||||
"--observe-max-events",
|
||||
"10",
|
||||
"--fuel",
|
||||
"100000000",
|
||||
])
|
||||
.current_dir(dir.path())
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.expect("spawn marqdo");
|
||||
{
|
||||
let mut reader = BufReader::new(child.stdout.take().unwrap());
|
||||
let mut line = String::new();
|
||||
reader.read_line(&mut line).expect("read one line");
|
||||
assert!(line.contains("stream.opened"));
|
||||
// Dropping the reader closes the pipe; the next write must fail.
|
||||
}
|
||||
let deadline = Instant::now() + Duration::from_secs(20);
|
||||
loop {
|
||||
match child.try_wait().expect("try_wait") {
|
||||
Some(status) => {
|
||||
assert_ne!(
|
||||
status.code(),
|
||||
Some(0),
|
||||
"a broken event pipe must fail the run"
|
||||
);
|
||||
break;
|
||||
}
|
||||
None if Instant::now() > deadline => {
|
||||
let _ = child.kill();
|
||||
panic!("the run kept executing after its event pipe was closed");
|
||||
}
|
||||
None => std::thread::sleep(Duration::from_millis(20)),
|
||||
}
|
||||
}
|
||||
let mut stderr = String::new();
|
||||
child
|
||||
.stderr
|
||||
.take()
|
||||
.unwrap()
|
||||
.read_to_string(&mut stderr)
|
||||
.unwrap();
|
||||
assert!(
|
||||
stderr.contains("observe.transport_failed"),
|
||||
"expected a transport diagnostic on stderr: {stderr}"
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user