From d78faaf8e4060bf30a5a04259ca15ab1aba13043 Mon Sep 17 00:00:00 2001 From: cflmy Date: Sun, 22 Nov 2026 15:42:41 +0800 Subject: [PATCH] obs(01): typed host observation facade, real stdio chunks, frame identity and budgets --- crates/marqdo-host/src/host.rs | 336 +++++++++++++ crates/marqdo-host/src/host/effects.rs | 3 + crates/marqdo-host/src/lib.rs | 7 + crates/marqdo-host/src/observe.rs | 540 +++++++++++++++++++++ crates/marqdo-host/tests/observation.rs | 454 +++++++++++++++++ crates/marqdo-runtime/src/interpreter.rs | 115 ++++- crates/marqdo-runtime/tests/observation.rs | 368 ++++++++++++++ crates/marqdo-value/src/error.rs | 6 + 8 files changed, 1817 insertions(+), 12 deletions(-) create mode 100644 crates/marqdo-host/src/observe.rs create mode 100644 crates/marqdo-host/tests/observation.rs create mode 100644 crates/marqdo-runtime/tests/observation.rs diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index 0fceb9c..6c9e99d 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -22,6 +22,10 @@ use crate::capability::{Capabilities, CapabilityAudit, CapabilityBroker}; use crate::context::ExecutionContext; use crate::fs::ProjectFs; use crate::handles::{contains_plugin_handle, PluginHandleTable}; +use crate::observe::{ + encode_value, estimate_event_bytes, FrameId, ObservationConfig, ObservationError, + ObservationEvent, ObservationSink, ObservationState, RuntimeObservation, +}; use crate::plugin_worker::WorkerPlugin; use crate::provider_c::{load_package, CResourceProvider}; use crate::provider_worker::WorkerResourceProvider; @@ -209,6 +213,44 @@ pub trait Host { fn semantic_events(&self) -> &[SemanticEvent] { &[] } + + /// Whether the host has an installed observation sink. + /// + /// The default host is inert; the interpreter uses this to skip building + /// any observation event when the run has no `--event-stream`. + fn observation_enabled(&self) -> bool { + false + } + + /// Announce a successfully bound call frame. + /// + /// Returns the run-unique frame identity, or `None` when observation is + /// disabled. Argument binding must have completed before this is called; + /// a binding failure never produces a frame. + fn observation_begin_frame( + &mut self, + _function_id: &str, + _module_id: &str, + _span: Option, + ) -> Result, RuntimeError> { + Ok(None) + } + + /// Close a previously announced frame, including failure paths. + fn observation_end_frame( + &mut self, + _frame_id: Option, + _status: &str, + _module_id: &str, + _span: Option, + ) -> Result<(), RuntimeError> { + Ok(()) + } + + /// Emit one borrowed runtime observation event. Default: ignored. + fn observe_runtime(&mut self, _event: RuntimeObservation<'_>) -> Result<(), RuntimeError> { + Ok(()) + } } /// Default capability host implementation. @@ -254,6 +296,8 @@ pub struct StdHost { semantic_events: Vec, next_event_seq: u64, trace_state: TraceState, + observation: Option, + observation_error: Option, } struct PluginSlot { @@ -318,6 +362,8 @@ impl StdHost { semantic_events: Vec::new(), next_event_seq: 0, trace_state: TraceState::default(), + observation: None, + observation_error: None, } } @@ -510,6 +556,95 @@ impl StdHost { self } + /// Install the typed observation sink and policy (RFC-OBS-0001). + /// + /// Without this call the host has no observation state: it does not + /// allocate events, clone values or serialize anything. + pub fn with_observation( + mut self, + config: ObservationConfig, + sink: Box, + ) -> Self { + self.observation = Some(ObservationState::new(config, sink)); + self + } + + /// The installed observation policy, when event mode is active. + pub fn observation_config(&self) -> Option<&ObservationConfig> { + self.observation.as_ref().map(|state| &state.config) + } + + /// A saved observation transport failure (if any). + /// + /// The interpreter surfaces this at the next budget boundary; the CLI also + /// checks it after the run so a successful return cannot mask a dead + /// event pipe. + pub fn observation_failure(&self) -> Option<&str> { + self.observation_error.as_deref() + } + + fn emit_observation( + &mut self, + event: ObservationEvent<'_>, + critical: bool, + ) -> Result<(), RuntimeError> { + let Some(state) = self.observation.as_mut() else { + return Ok(()); + }; + let mut pending = Some(event); + if !critical { + if state.is_truncated() { + return Ok(()); + } + let estimate = estimate_event_bytes(pending.as_ref().expect("event present")); + if !state.admit(estimate) { + let reason = state.truncation_reason(estimate); + let limit = state.limit_for(reason); + let written = state.written(); + pending = Some(ObservationEvent::ObservationTruncated { + reason, + limit, + written, + dropped: None, + }); + } + } + let result = match pending { + Some(event) => state.sink.emit(event), + None => Ok(()), + }; + match result { + Ok(()) => Ok(()), + Err(error) => Err(self.record_observation_error(error)), + } + } + + fn record_observation_error(&mut self, error: ObservationError) -> RuntimeError { + self.observation_error = Some(error.message.clone()); + error.into_runtime_error() + } + + pub(crate) fn observe_effect( + &mut self, + operation: &str, + result_code: &str, + ctx: &ExecutionContext, + ) { + let result = self.emit_observation( + ObservationEvent::Effect { + operation, + result_code, + module_id: &ctx.module_id, + span: ctx.span, + }, + false, + ); + // Effect recording is an existing infallible path. The failure is + // stored and surfaced by the next fuel/deadline boundary and by the + // CLI after the run; it is never silently forgotten. + let _ = result; + } + /// Override the budget. pub fn with_budget(mut self, budget: Budget) -> Self { self.budget = budget; @@ -703,6 +838,17 @@ impl Host for StdHost { } else { self.output.extend_from_slice(&bytes[..count]); } + // Real-time boundary: emit exactly the bytes the host just + // committed, at this write, never by splitting the final buffer. + let committed = &bytes[..count]; + for chunk in committed.chunks(crate::observe::MAX_STREAM_CHUNK_BYTES) { + let event = if stdio == Some("stderr") { + ObservationEvent::StderrChunk { data: chunk } + } else { + ObservationEvent::StdoutChunk { data: chunk } + }; + self.emit_observation(event, true)?; + } } self.record_semantic( "resource.write", @@ -1384,6 +1530,13 @@ impl Host for StdHost { } fn consume_fuel(&mut self, amount: u64, span: Option) -> Result<(), RuntimeError> { + if let Some(message) = &self.observation_error { + return Err(RuntimeError::new( + ErrorCategory::Observation, + span, + format!("observe.transport_failed: {message}"), + )); + } self.budget.consume_fuel(amount, span) } @@ -1392,9 +1545,192 @@ impl Host for StdHost { } fn check_deadline(&self, span: Option) -> Result<(), RuntimeError> { + if let Some(message) = &self.observation_error { + return Err(RuntimeError::new( + ErrorCategory::Observation, + span, + format!("observe.transport_failed: {message}"), + )); + } self.budget.check_deadline(span) } + fn observation_enabled(&self) -> bool { + self.observation.is_some() + } + + fn observation_begin_frame( + &mut self, + function_id: &str, + module_id: &str, + span: Option, + ) -> Result, RuntimeError> { + let Some(state) = self.observation.as_mut() else { + return Ok(None); + }; + let frame_id = state.begin_frame(); + let parent_frame_id = state.parent_frame(); + state.push_frame(frame_id); + self.emit_observation( + ObservationEvent::CallEnter { + frame_id, + parent_frame_id, + function_id, + module_id, + span, + }, + false, + )?; + Ok(Some(frame_id)) + } + + fn observation_end_frame( + &mut self, + frame_id: Option, + status: &str, + module_id: &str, + span: Option, + ) -> Result<(), RuntimeError> { + let Some(frame_id) = frame_id else { + return Ok(()); + }; + if let Some(state) = self.observation.as_mut() { + state.pop_frame(frame_id); + } + self.emit_observation( + ObservationEvent::CallExit { + frame_id, + status, + module_id, + span, + }, + false, + ) + } + + fn observe_runtime(&mut self, event: RuntimeObservation<'_>) -> Result<(), RuntimeError> { + if self.observation.is_none() { + return Ok(()); + } + match event { + RuntimeObservation::Return { + frame_id, + value_type, + module_id, + span, + } => { + let Some(frame_id) = frame_id else { + return Ok(()); + }; + self.emit_observation( + ObservationEvent::Return { + frame_id, + value_type, + module_id, + span, + }, + false, + ) + } + RuntimeObservation::BranchEval { + frame_id, + result, + module_id, + span, + } => { + let Some(frame_id) = frame_id else { + return Ok(()); + }; + self.emit_observation( + ObservationEvent::BranchEval { + frame_id, + result, + module_id, + span, + }, + false, + ) + } + RuntimeObservation::LoopIteration { + frame_id, + decision, + module_id, + span, + } => { + let Some(frame_id) = frame_id else { + return Ok(()); + }; + self.emit_observation( + ObservationEvent::LoopIteration { + frame_id, + decision, + module_id, + span, + }, + false, + ) + } + RuntimeObservation::VariableAssigned { + frame_id, + name, + value, + module_id, + span, + } => { + let Some(frame_id) = frame_id else { + return Ok(()); + }; + let Some(config) = self.observation.as_ref().map(|state| &state.config) else { + return Ok(()); + }; + let selected = config.selected_variables.contains(name); + let (value_state, observed) = encode_value(config, selected, value); + self.emit_observation( + ObservationEvent::VariableAssigned { + frame_id, + name, + value_type: value.type_name(), + module_id, + span, + value_state, + value: observed, + }, + false, + ) + } + RuntimeObservation::ParameterBound { + frame_id, + name, + source, + value, + module_id, + span, + } => { + let Some(frame_id) = frame_id else { + return Ok(()); + }; + let Some(config) = self.observation.as_ref().map(|state| &state.config) else { + return Ok(()); + }; + let selected = config.selected_parameters.contains(name); + let (value_state, observed) = encode_value(config, selected, value); + self.emit_observation( + ObservationEvent::ParameterObserved { + frame_id, + name, + source, + value_type: value.type_name(), + module_id, + span, + value_state, + value: observed, + }, + false, + ) + } + } + } + fn take_output(&mut self) -> Vec { std::mem::take(&mut self.output) } diff --git a/crates/marqdo-host/src/host/effects.rs b/crates/marqdo-host/src/host/effects.rs index af41181..2735f62 100644 --- a/crates/marqdo-host/src/host/effects.rs +++ b/crates/marqdo-host/src/host/effects.rs @@ -37,5 +37,8 @@ impl StdHost { started.elapsed(), summary.to_string(), ); + // Executed regardless of Trace v2 being enabled: the two writers are + // independent observation outputs (RFC-OBS-0001 §4.6). + self.observe_effect(op, summary, ctx); } } diff --git a/crates/marqdo-host/src/lib.rs b/crates/marqdo-host/src/lib.rs index 915c84b..a9aadb9 100644 --- a/crates/marqdo-host/src/lib.rs +++ b/crates/marqdo-host/src/lib.rs @@ -11,6 +11,7 @@ pub mod fs; pub mod handles; pub mod host; pub mod kernels; +pub mod observe; mod plugin_worker; mod process; mod provider_c; @@ -28,5 +29,11 @@ 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 observe::{ + encode_value, estimate_event_bytes, FrameId, ObservationConfig, ObservationError, + ObservationEvent, ObservationSink, ObservedValue, ParameterSource, RuntimeObservation, + ValueState, DEFAULT_MAX_OBSERVATION_BYTES, DEFAULT_MAX_OBSERVATION_EVENTS, + DEFAULT_MAX_VALUE_BYTES, MAX_STREAM_CHUNK_BYTES, +}; pub use resource::{ResourceProvider, ResourceRead, ResourceTable, SharedResourceProvider}; pub use trace::{EffectTrace, SemanticEvent, TraceBudget, TraceEntry, TraceState, TraceTruncation}; diff --git a/crates/marqdo-host/src/observe.rs b/crates/marqdo-host/src/observe.rs new file mode 100644 index 0000000..e409932 --- /dev/null +++ b/crates/marqdo-host/src/observe.rs @@ -0,0 +1,540 @@ +//! Typed runtime observation facade (RFC-OBS-0001, ADR-0059). +//! +//! This module is internal to the workspace. It defines the typed events the +//! interpreter and host emit at real commit points, the optional sink the CLI +//! installs, the run-scoped frame identity and the bounded observation budget. +//! It does **not** know JSONL, HTTP, SSE, View, agents or the public envelope; +//! the CLI composes the public Execution Events v1 protocol from these events. +//! +//! Defaults are deliberately inert: no sink means no allocation and no +//! serialization. The facade never exposes `Frame.locals`, the whole +//! `MemoryStore`, raw OS pointers or host handles. + +use std::collections::BTreeSet; + +use marqdo_span::Span; +use marqdo_value::{ErrorCategory, RuntimeError, Value}; + +/// Default maximum number of structural/value observation events per run. +pub const DEFAULT_MAX_OBSERVATION_EVENTS: u64 = 100_000; +/// Default approximate maximum encoded bytes for structural/value events. +pub const DEFAULT_MAX_OBSERVATION_BYTES: u64 = 16 * 1024 * 1024; +/// Default maximum encoded bytes for one selected value. +pub const DEFAULT_MAX_VALUE_BYTES: usize = 256; +/// Maximum committed stdio bytes carried by one chunk event. +pub const MAX_STREAM_CHUNK_BYTES: usize = 64 * 1024; + +/// Opaque run-scoped call-instance identity. +/// +/// Not a function identity, not a source location and never a memory pointer. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct FrameId(pub u64); + +impl FrameId { + /// Stable wire form used by the public protocol (`f1`, `f2`, ...). + pub fn as_wire(self) -> String { + format!("f{}", self.0) + } +} + +/// Where a bound parameter's value came from. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ParameterSource { + /// Supplied by the caller (CLI `--arg` or a Marqdo call). + Provided, + /// Evaluated from the declared default expression. + Default, +} + +impl ParameterSource { + /// Stable wire name. + pub const fn as_str(self) -> &'static str { + match self { + ParameterSource::Provided => "provided", + ParameterSource::Default => "default", + } + } +} + +/// Observation policy for one run. +/// +/// `structural` always implies frame identity; value events only exist for +/// exact names in `selected_variables`/`selected_parameters`. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ObservationConfig { + /// Publish lifecycle/frame/branch/loop/effect events. + pub structural: bool, + /// Exact local-variable names allowed to publish a value. + pub selected_variables: BTreeSet, + /// Exact parameter names allowed to publish a value. + pub selected_parameters: BTreeSet, + /// Second explicit consent required to publish `Text` bytes. + pub allow_text_values: bool, + /// Structural/value event budget (`0` = unlimited). + pub max_observation_events: u64, + /// Approximate structural/value byte budget (`0` = unlimited). + pub max_observation_bytes: u64, + /// Maximum source bytes encoded for one value (`0` = unlimited). + pub max_value_bytes: usize, +} + +impl Default for ObservationConfig { + fn default() -> Self { + Self { + structural: true, + selected_variables: BTreeSet::new(), + selected_parameters: BTreeSet::new(), + allow_text_values: false, + max_observation_events: DEFAULT_MAX_OBSERVATION_EVENTS, + max_observation_bytes: DEFAULT_MAX_OBSERVATION_BYTES, + max_value_bytes: DEFAULT_MAX_VALUE_BYTES, + } + } +} + +impl ObservationConfig { + /// Whether any value can ever be published. + pub fn values_enabled(&self) -> bool { + !self.selected_variables.is_empty() || !self.selected_parameters.is_empty() + } + + /// Negotiated observation level (`base`, `structural` or `values`). + pub fn level(&self) -> &'static str { + if self.values_enabled() { + "values" + } else if self.structural { + "structural" + } else { + "base" + } + } +} + +/// Why a value has (or has not) a wire encoding. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ValueState { + /// Name not selected; no value encoded. + NotRequested, + /// Name selected but policy hides the value. + Redacted, + /// Encoded but truncated to the configured maximum. + Truncated, + /// Type not supported by the v1 scalar policy. + Unsupported, + /// Encoded normally. + Observed, +} + +impl ValueState { + /// Stable wire name. + pub const fn as_str(self) -> &'static str { + match self { + ValueState::NotRequested => "not_requested", + ValueState::Redacted => "redacted", + ValueState::Truncated => "truncated", + ValueState::Unsupported => "unsupported", + ValueState::Observed => "observed", + } + } +} + +/// A bounded, policy-filtered value encoding (the `marqdo.value.v1` wire +/// object plus optional truncation metadata). +#[derive(Debug, Clone, PartialEq)] +pub struct ObservedValue { + /// JSON object safe to publish. + pub wire: serde_json::Value, +} + +/// One typed internal observation event. +/// +/// Borrows strings and stdio bytes so the default disabled path never clones a +/// frame, argument list or whole `Value`. The sink must consume it +/// synchronously before returning. +#[derive(Debug, Clone, PartialEq)] +pub enum ObservationEvent<'a> { + /// Bytes committed to the program's stdout by the host. + StdoutChunk { data: &'a [u8] }, + /// Bytes committed to the program's stderr by the host. + StderrChunk { data: &'a [u8] }, + /// A new frame exists (arguments already bound). + CallEnter { + frame_id: FrameId, + parent_frame_id: Option, + function_id: &'a str, + module_id: &'a str, + span: Option, + }, + /// A frame finished, including failure paths. + CallExit { + frame_id: FrameId, + status: &'a str, + module_id: &'a str, + span: Option, + }, + /// A `return` statement committed its value. + Return { + frame_id: FrameId, + value_type: &'a str, + module_id: &'a str, + span: Option, + }, + /// A branch condition was evaluated. + BranchEval { + frame_id: FrameId, + result: bool, + module_id: &'a str, + span: Option, + }, + /// A loop condition was evaluated. + LoopIteration { + frame_id: FrameId, + decision: &'a str, + module_id: &'a str, + span: Option, + }, + /// The host completed a controlled effect attempt. + Effect { + operation: &'a str, + result_code: &'a str, + module_id: &'a str, + span: Option, + }, + /// A local assignment was committed. + VariableAssigned { + frame_id: FrameId, + name: &'a str, + value_type: &'a str, + module_id: &'a str, + span: Option, + value_state: ValueState, + value: Option, + }, + /// A function parameter was bound. + ParameterObserved { + frame_id: FrameId, + name: &'a str, + source: ParameterSource, + value_type: &'a str, + module_id: &'a str, + span: Option, + value_state: ValueState, + value: Option, + }, + /// The structural/value observation budget was exhausted. + ObservationTruncated { + reason: &'a str, + limit: u64, + written: u64, + dropped: Option, + }, +} + +/// Borrowed runtime notification accepted by [`crate::Host::observe_runtime`]. +/// +/// Every variant carries an `Option`; observation of values and +/// structural events only happens while a frame identity exists. +#[derive(Debug)] +pub enum RuntimeObservation<'a> { + /// A `return` statement committed (before the call exits). + Return { + frame_id: Option, + value_type: &'a str, + module_id: &'a str, + span: Option, + }, + /// A branch condition evaluated. + BranchEval { + frame_id: Option, + result: bool, + module_id: &'a str, + span: Option, + }, + /// A loop condition evaluated. + LoopIteration { + frame_id: Option, + decision: &'a str, + module_id: &'a str, + span: Option, + }, + /// A local variable assignment committed. + VariableAssigned { + frame_id: Option, + name: &'a str, + value: &'a Value, + module_id: &'a str, + span: Option, + }, + /// A parameter was bound. + ParameterBound { + frame_id: Option, + name: &'a str, + source: ParameterSource, + value: &'a Value, + module_id: &'a str, + span: Option, + }, +} + +/// Sink installed by the composition root (the CLI JSONL writer in product +/// builds, an in-memory recorder in tests). +pub trait ObservationSink { + /// Consume one event synchronously. + fn emit(&mut self, event: ObservationEvent<'_>) -> Result<(), ObservationError>; +} + +/// A sink failed to accept an event (usually a closed/broken output pipe). +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ObservationError { + /// Human-readable transport reason (safe to print to OS stderr). + pub message: String, +} + +impl ObservationError { + /// Construct an observation transport error. + pub fn new(message: impl Into) -> Self { + Self { + message: message.into(), + } + } + + /// Convert into the stable runtime failure used to abort the run. + pub fn into_runtime_error(self) -> RuntimeError { + RuntimeError::new( + ErrorCategory::Observation, + None, + format!("observe.transport_failed: {}", self.message), + ) + } +} + +impl std::fmt::Display for ObservationError { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + formatter.write_str(&self.message) + } +} + +impl std::error::Error for ObservationError {} + +/// Mutable per-run observation state owned by `StdHost`. +pub(crate) struct ObservationState { + pub(crate) config: ObservationConfig, + pub(crate) sink: Box, + next_frame: u64, + frames: Vec, + written: u64, + bytes: u64, + truncated: bool, +} + +impl ObservationState { + pub(crate) fn new(config: ObservationConfig, sink: Box) -> Self { + Self { + config, + sink, + next_frame: 0, + frames: Vec::new(), + written: 0, + bytes: 0, + truncated: false, + } + } + + pub(crate) fn begin_frame(&mut self) -> FrameId { + self.next_frame += 1; + FrameId(self.next_frame) + } + + pub(crate) fn parent_frame(&self) -> Option { + self.frames.last().copied() + } + + pub(crate) fn push_frame(&mut self, frame: FrameId) { + self.frames.push(frame); + } + + /// Pop the frame if it is on the stack. A mismatch is a runtime bug, not a + /// consumer-visible event, so it is repaired defensively rather than + /// panicking inside the host. + pub(crate) fn pop_frame(&mut self, frame: FrameId) { + if self.frames.last().copied() == Some(frame) { + self.frames.pop(); + } else if let Some(position) = self.frames.iter().rposition(|item| *item == frame) { + self.frames.truncate(position); + } + } + + /// Estimate one encoded event and accept it if the budget allows. + /// + /// Returns `Ok(true)` when the event was admitted, `Ok(false)` when the + /// budget was already exhausted, and writes the single truncation marker + /// through `emit_truncated` on the transition. + pub(crate) fn admit(&mut self, estimate: u64) -> bool { + if self.truncated { + return false; + } + let event_limit = self.config.max_observation_events; + let byte_limit = self.config.max_observation_bytes; + if (event_limit > 0 && self.written >= event_limit) + || (byte_limit > 0 && self.bytes.saturating_add(estimate) > byte_limit) + { + self.truncated = true; + return false; + } + self.written += 1; + self.bytes = self.bytes.saturating_add(estimate); + true + } + + pub(crate) fn truncation_reason(&self, estimate: u64) -> &'static str { + let event_limit = self.config.max_observation_events; + if event_limit > 0 && self.written >= event_limit { + "event_budget" + } else if self.config.max_observation_bytes > 0 + && self.bytes.saturating_add(estimate) > self.config.max_observation_bytes + { + "byte_budget" + } else { + "event_budget" + } + } + + pub(crate) fn is_truncated(&self) -> bool { + self.truncated + } + + pub(crate) fn written(&self) -> u64 { + self.written + } + + pub(crate) fn limit_for(&self, reason: &str) -> u64 { + if reason == "byte_budget" { + self.config.max_observation_bytes + } else { + self.config.max_observation_events + } + } +} + +/// Encode a selected value under the v1 scalar policy. +/// +/// No `Debug`, no recursive container expansion and no handle serialization. +pub fn encode_value( + config: &ObservationConfig, + selected: bool, + value: &Value, +) -> (ValueState, Option) { + if !selected { + return (ValueState::NotRequested, None); + } + match value { + Value::Int(_) | Value::Float(_) | Value::Bool(_) => ( + ValueState::Observed, + Some(ObservedValue { + wire: marqdo_value::to_wire(value), + }), + ), + Value::Text(text) => { + if !config.allow_text_values { + return (ValueState::Redacted, None); + } + let limit = config.max_value_bytes; + if limit == 0 || text.len() <= limit { + return ( + ValueState::Observed, + Some(ObservedValue { + wire: marqdo_value::to_wire(value), + }), + ); + } + let mut cut = limit.min(text.len()); + while cut > 0 && !text.is_char_boundary(cut) { + cut -= 1; + } + let prefix = Value::Text(text[..cut].to_string()); + let mut wire = marqdo_value::to_wire(&prefix); + if let serde_json::Value::Object(map) = &mut wire { + map.insert("truncated".to_string(), serde_json::Value::Bool(true)); + map.insert( + "original_byte_count".to_string(), + serde_json::Value::from(text.len() as u64), + ); + } + (ValueState::Truncated, Some(ObservedValue { wire })) + } + _ => (ValueState::Unsupported, None), + } +} + +/// Approximate encoded size, used only for the observation byte budget. +pub fn estimate_event_bytes(event: &ObservationEvent<'_>) -> u64 { + let mut total: u64 = 160; + let mut add_text = |text: &str| total = total.saturating_add(text.len() as u64); + match event { + ObservationEvent::StdoutChunk { data } | ObservationEvent::StderrChunk { data } => { + total = total.saturating_add((data.len() as u64).saturating_mul(4) / 3); + } + ObservationEvent::CallEnter { + function_id, + module_id, + .. + } => { + add_text(function_id); + add_text(module_id); + } + ObservationEvent::CallExit { + status, module_id, .. + } => { + add_text(status); + add_text(module_id); + } + ObservationEvent::Return { + value_type, + module_id, + .. + } => { + add_text(value_type); + add_text(module_id); + } + ObservationEvent::BranchEval { module_id, .. } + | ObservationEvent::LoopIteration { module_id, .. } + | ObservationEvent::Effect { module_id, .. } => { + add_text(module_id); + if let ObservationEvent::LoopIteration { decision, .. } = event { + add_text(decision); + } + if let ObservationEvent::Effect { operation, .. } = event { + add_text(operation); + } + } + ObservationEvent::VariableAssigned { + name, + value_type, + module_id, + value, + .. + } + | ObservationEvent::ParameterObserved { + name, + value_type, + module_id, + value, + .. + } => { + add_text(name); + add_text(value_type); + add_text(module_id); + if let Some(value) = value { + total = total.saturating_add(encoded_len(&value.wire)); + } + } + ObservationEvent::ObservationTruncated { reason, .. } => add_text(reason), + } + total +} + +fn encoded_len(value: &serde_json::Value) -> u64 { + serde_json::to_vec(value) + .map(|bytes| bytes.len() as u64) + .unwrap_or(0) +} diff --git a/crates/marqdo-host/tests/observation.rs b/crates/marqdo-host/tests/observation.rs new file mode 100644 index 0000000..d3ee28a --- /dev/null +++ b/crates/marqdo-host/tests/observation.rs @@ -0,0 +1,454 @@ +//! Host observation facade tests (RFC-OBS-0001 / ADR-0059). +//! +//! These pin the internal contract: stdio chunks come from the real host +//! commit point, the default path is inert, frames are paired, budgets +//! truncate only non-critical events and a broken sink aborts the run. + +use std::cell::RefCell; +use std::rc::Rc; + +use marqdo_host::{ + encode_value, Capabilities, ExecutionContext, FrameId, Host, ObservationConfig, + ObservationError, ObservationEvent, ObservationSink, ParameterSource, RuntimeObservation, + StdHost, ValueState, +}; +use marqdo_sandbox::SandboxMode; +use marqdo_value::{ErrorCategory, Value}; + +fn context() -> ExecutionContext { + ExecutionContext::new("index.mq.md".to_string(), None) +} + +#[derive(Debug, Clone, PartialEq)] +enum Recorded { + Stdout(Vec), + Stderr(Vec), + Enter { + frame: FrameId, + parent: Option, + function: String, + }, + Exit { + frame: FrameId, + status: String, + }, + Return { + frame: FrameId, + value_type: String, + }, + Branch { + frame: FrameId, + result: bool, + }, + Loop { + frame: FrameId, + decision: String, + }, + Variable { + frame: FrameId, + name: String, + value_type: String, + state: ValueState, + value: Option, + }, + Parameter { + frame: FrameId, + name: String, + source: ParameterSource, + state: ValueState, + value: Option, + }, + Effect { + operation: String, + result_code: String, + }, + Truncated { + reason: String, + limit: u64, + written: u64, + }, +} + +impl From> for Recorded { + fn from(event: ObservationEvent<'_>) -> Self { + match event { + ObservationEvent::StdoutChunk { data } => Recorded::Stdout(data.to_vec()), + ObservationEvent::StderrChunk { data } => Recorded::Stderr(data.to_vec()), + ObservationEvent::CallEnter { + frame_id, + parent_frame_id, + function_id, + .. + } => Recorded::Enter { + frame: frame_id, + parent: parent_frame_id, + function: function_id.to_string(), + }, + ObservationEvent::CallExit { + frame_id, status, .. + } => Recorded::Exit { + frame: frame_id, + status: status.to_string(), + }, + ObservationEvent::Return { + frame_id, + value_type, + .. + } => Recorded::Return { + frame: frame_id, + value_type: value_type.to_string(), + }, + ObservationEvent::BranchEval { + frame_id, result, .. + } => Recorded::Branch { + frame: frame_id, + result, + }, + ObservationEvent::LoopIteration { + frame_id, decision, .. + } => Recorded::Loop { + frame: frame_id, + decision: decision.to_string(), + }, + ObservationEvent::Effect { + operation, + result_code, + .. + } => Recorded::Effect { + operation: operation.to_string(), + result_code: result_code.to_string(), + }, + ObservationEvent::VariableAssigned { + frame_id, + name, + value_type, + value_state, + value, + .. + } => Recorded::Variable { + frame: frame_id, + name: name.to_string(), + value_type: value_type.to_string(), + state: value_state, + value: value.map(|value| value.wire), + }, + ObservationEvent::ParameterObserved { + frame_id, + name, + source, + value_state, + value, + .. + } => Recorded::Parameter { + frame: frame_id, + name: name.to_string(), + source, + state: value_state, + value: value.map(|value| value.wire), + }, + ObservationEvent::ObservationTruncated { + reason, + limit, + written, + .. + } => Recorded::Truncated { + reason: reason.to_string(), + limit, + written, + }, + } + } +} + +struct Recorder { + events: Rc>>, + fail: bool, +} + +impl ObservationSink for Recorder { + fn emit(&mut self, event: ObservationEvent<'_>) -> Result<(), ObservationError> { + if self.fail { + return Err(ObservationError::new("synthetic broken pipe")); + } + self.events.borrow_mut().push(event.into()); + Ok(()) + } +} + +fn observed_host(config: ObservationConfig) -> (StdHost, Rc>>) { + let events = Rc::new(RefCell::new(Vec::new())); + let host = StdHost::new( + SandboxMode::Project, + Capabilities::pure(), + std::env::temp_dir(), + ) + .with_observation( + config, + Box::new(Recorder { + events: Rc::clone(&events), + fail: false, + }), + ); + (host, events) +} + +#[test] +fn stdout_and_stderr_chunks_are_emitted_at_the_commit_point() { + let (mut host, events) = observed_host(ObservationConfig::default()); + let ctx = context(); + let stdout = match host + .resource_open("stdio", "stdout", &["write".to_string()], &ctx) + .unwrap() + { + Value::Resource(handle) => handle, + other => panic!("expected a resource handle, got {other:?}"), + }; + let stderr = match host + .resource_open("stdio", "stderr", &["write".to_string()], &ctx) + .unwrap() + { + Value::Resource(handle) => handle, + other => panic!("expected a resource handle, got {other:?}"), + }; + host.resource_write(stdout, b"START\n", &ctx).unwrap(); + host.resource_write(stderr, &[0xff, 0x00, 0xfe], &ctx) + .unwrap(); + host.resource_write(stdout, b"DONE\n", &ctx).unwrap(); + let events = events.borrow(); + assert_eq!( + events + .iter() + .filter_map(|event| match event { + Recorded::Stdout(bytes) => Some(bytes.clone()), + _ => None, + }) + .collect::>(), + vec![b"START\n".to_vec(), b"DONE\n".to_vec()], + "each committed stdout write must produce its own chunk event" + ); + assert!(events.contains(&Recorded::Stderr(vec![0xff, 0x00, 0xfe]))); + assert_eq!(host.take_output(), b"START\nDONE\n"); +} + +#[test] +fn rejected_output_write_emits_no_chunk() { + let (mut host, events) = observed_host(ObservationConfig::default()); + host.budget.max_output_bytes = 3; + let ctx = context(); + let stdout = match host + .resource_open("stdio", "stdout", &["write".to_string()], &ctx) + .unwrap() + { + Value::Resource(handle) => handle, + other => panic!("expected a resource handle, got {other:?}"), + }; + let error = host.resource_write(stdout, b"hello", &ctx).unwrap_err(); + assert_eq!(error.category, ErrorCategory::ResourceExhausted); + assert!( + events + .borrow() + .iter() + .all(|event| !matches!(event, Recorded::Stdout(_))), + "an output write rejected by the host budget must not be observed" + ); + assert!(host.take_output().is_empty()); +} + +#[test] +fn large_writes_are_split_into_bounded_chunks() { + let (mut host, events) = observed_host(ObservationConfig::default()); + let ctx = context(); + let stdout = match host + .resource_open("stdio", "stdout", &["write".to_string()], &ctx) + .unwrap() + { + Value::Resource(handle) => handle, + other => panic!("expected a resource handle, got {other:?}"), + }; + let data = vec![b'x'; 150_000]; + host.resource_write(stdout, &data, &ctx).unwrap(); + let chunks: Vec> = events + .borrow() + .iter() + .filter_map(|event| match event { + Recorded::Stdout(bytes) => Some(bytes.clone()), + _ => None, + }) + .collect(); + assert_eq!(chunks.len(), 3); + assert!(chunks.iter().all(|chunk| chunk.len() <= 64 * 1024)); + assert_eq!(chunks.concat(), data); +} + +#[test] +fn frames_are_unique_paired_and_parented() { + let (mut host, events) = observed_host(ObservationConfig::default()); + let main = host + .observation_begin_frame("root::main", "root::index.mq.md", None) + .unwrap() + .expect("observation enabled must allocate a frame"); + let child = host + .observation_begin_frame("root::f", "root::index.mq.md", None) + .unwrap() + .unwrap(); + let grandchild = host + .observation_begin_frame("root::g", "root::index.mq.md", None) + .unwrap() + .unwrap(); + host.observe_runtime(RuntimeObservation::Return { + frame_id: Some(grandchild), + value_type: "Int", + module_id: "root::index.mq.md", + span: None, + }) + .unwrap(); + host.observation_end_frame(Some(grandchild), "return", "root::index.mq.md", None) + .unwrap(); + host.observation_end_frame(Some(child), "ok", "root::index.mq.md", None) + .unwrap(); + host.observation_end_frame(Some(main), "ok", "root::index.mq.md", None) + .unwrap(); + + let events = events.borrow(); + let enters: Vec<_> = events + .iter() + .filter_map(|event| match event { + Recorded::Enter { frame, parent, .. } => Some((*frame, *parent)), + _ => None, + }) + .collect(); + assert_eq!(enters.len(), 3); + assert_eq!(enters[0].1, None); + assert_eq!(enters[1].1, Some(main)); + assert_eq!(enters[2].1, Some(child)); + let exits = events + .iter() + .filter(|event| matches!(event, Recorded::Exit { .. })) + .count(); + assert_eq!(exits, 3); +} + +#[test] +fn structural_budget_truncates_with_one_marker_and_keeps_critical_events() { + let config = ObservationConfig { + max_observation_events: 2, + ..ObservationConfig::default() + }; + let (mut host, events) = observed_host(config); + let ctx = context(); + let stdout = match host + .resource_open("stdio", "stdout", &["write".to_string()], &ctx) + .unwrap() + { + Value::Resource(handle) => handle, + other => panic!("expected a resource handle, got {other:?}"), + }; + let first = host + .observation_begin_frame("f1", "m", None) + .unwrap() + .unwrap(); + host.observation_end_frame(Some(first), "ok", "m", None) + .unwrap(); + // Third structural event exceeds the two-event budget. + host.observation_begin_frame("f2", "m", None).unwrap(); + host.resource_write(stdout, b"still-visible", &ctx).unwrap(); + + let events = events.borrow(); + let markers = events + .iter() + .filter(|event| matches!(event, Recorded::Truncated { .. })) + .count(); + assert_eq!(markers, 1, "exactly one truncation marker"); + assert!( + events.contains(&Recorded::Stdout(b"still-visible".to_vec())), + "stdout chunks are critical and survive the structural budget" + ); + assert!(events.iter().any(|event| matches!( + event, + Recorded::Truncated { reason, limit, written } + if reason == "event_budget" && *limit == 2 && *written == 2 + ))); +} + +#[test] +fn broken_sink_aborts_and_is_saved_for_the_next_boundary() { + let events = Rc::new(RefCell::new(Vec::new())); + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::pure(), + std::env::temp_dir(), + ) + .with_observation( + ObservationConfig::default(), + Box::new(Recorder { + events: Rc::clone(&events), + fail: true, + }), + ); + let error = host + .observation_begin_frame("f", "m", None) + .expect_err("a broken sink must propagate"); + assert_eq!(error.category, ErrorCategory::Observation); + assert_eq!(error.code(), "observe.transport_failed"); + assert_eq!(host.observation_failure(), Some("synthetic broken pipe")); + let boundary = host.consume_fuel(1, None).expect_err("next boundary fails"); + assert_eq!(boundary.category, ErrorCategory::Observation); +} + +#[test] +fn default_host_has_no_observation_state() { + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::pure(), + std::env::temp_dir(), + ); + assert!(!host.observation_enabled()); + assert!(host.observation_config().is_none()); + assert_eq!(host.observation_begin_frame("f", "m", None).unwrap(), None); + host.observation_end_frame(None, "ok", "m", None).unwrap(); +} + +#[test] +fn value_encoding_is_selected_bounded_and_handle_safe() { + let mut config = ObservationConfig { + max_value_bytes: 8, + ..ObservationConfig::default() + }; + assert_eq!( + encode_value(&config, false, &Value::int(42)), + (ValueState::NotRequested, None) + ); + let (state, value) = encode_value(&config, true, &Value::int(42)); + assert_eq!(state, ValueState::Observed); + assert_eq!(value.unwrap().wire["decimal"], "42"); + + const SENTINEL: &str = "DO_NOT_LEAK_SENTINEL_1"; + let (state, value) = encode_value(&config, true, &Value::text(SENTINEL)); + assert_eq!(state, ValueState::Redacted); + assert!(value.is_none(), "text requires explicit consent"); + + config.allow_text_values = true; + let (state, value) = encode_value(&config, true, &Value::text(SENTINEL)); + assert_eq!(state, ValueState::Truncated); + let wire = value.unwrap().wire; + assert_eq!(wire["truncated"], true); + assert!(wire["value"].as_str().unwrap().len() <= 8); + assert!(!wire.to_string().contains(SENTINEL)); + + config.allow_text_values = true; + let text = "开始文本\n"; + let (state, value) = encode_value(&config, true, &Value::text(text)); + assert_eq!(state, ValueState::Truncated); + let wire = value.unwrap().wire; + assert!( + text.starts_with(wire["value"].as_str().unwrap()), + "truncation must keep a UTF-8 scalar prefix" + ); + + let handle_value = Value::None; + let (state, _) = encode_value(&config, true, &handle_value); + assert_eq!(state, ValueState::Unsupported); + let (state, value) = encode_value(&config, true, &Value::List(vec![Value::int(1)])); + assert_eq!(state, ValueState::Unsupported); + assert!(value.is_none()); +} diff --git a/crates/marqdo-runtime/src/interpreter.rs b/crates/marqdo-runtime/src/interpreter.rs index cdcb8f3..ec36fe6 100644 --- a/crates/marqdo-runtime/src/interpreter.rs +++ b/crates/marqdo-runtime/src/interpreter.rs @@ -3,7 +3,9 @@ use std::collections::BTreeMap; use marqdo_expression::{BinaryOp, Expr, RecordEntry}; -use marqdo_host::{ExecutionContext, Host, HostOp, ResourceRead}; +use marqdo_host::{ + ExecutionContext, FrameId, Host, HostOp, ParameterSource, ResourceRead, RuntimeObservation, +}; use marqdo_ir::{builtins, Function, FunctionId, ModuleId, PlaceTarget, Program, Stmt}; use marqdo_span::Span; use marqdo_value::{ErrorCategory, ResourceHandle, RuntimeError, Value}; @@ -55,6 +57,14 @@ pub struct RunOutcome { struct Frame { function: FunctionId, locals: BTreeMap, + /// Run-unique call-instance identity; `None` when observation is off. + id: Option, +} + +/// Locals plus where each parameter's value came from. +struct BoundArgs { + locals: BTreeMap, + provenance: BTreeMap, } /// Flow of one statement list. @@ -69,6 +79,9 @@ pub struct Interpreter<'a> { host: &'a mut dyn Host, depth: usize, memory: MemoryStore, + /// Cached `Host::observation_enabled()`: the default path skips building + /// observation events entirely. + observe: bool, } /// Run a named function with already-evaluated arguments. @@ -98,11 +111,13 @@ pub fn run_with_limits( args: Vec, limits: MemoryLimits, ) -> Result { + let observe = host.observation_enabled(); let mut interpreter = Interpreter { program, host, depth: 0, memory: MemoryStore::new(limits), + observe, }; let value = interpreter.call_by_name(module, function, args, None)?; Ok(RunOutcome { value }) @@ -167,8 +182,8 @@ impl<'a> Interpreter<'a> { call_span, None, ); - let locals = match self.bind_args(function, args, call_span) { - Ok(locals) => locals, + let bound = match self.bind_args(function, args, call_span) { + Ok(bound) => bound, Err(mut error) => { if let Some(module) = caller_module { error.attribute_module(module.canonical()); @@ -176,9 +191,38 @@ impl<'a> Interpreter<'a> { return Err(error); } }; + // A frame is announced only after argument binding succeeded, so a + // binding failure can never leave a dangling call frame. + let frame_id = if self.observe { + self.host + .observation_begin_frame(&trace_id, &trace_module, call_span)? + } else { + None + }; + if let Some(frame_id) = frame_id { + let parameter_module = function.id.module.canonical(); + for param in &function.params { + let Some((source, span)) = bound.provenance.get(¶m.name).copied() else { + continue; + }; + let Some(value) = bound.locals.get(¶m.name) else { + continue; + }; + self.host + .observe_runtime(RuntimeObservation::ParameterBound { + frame_id: Some(frame_id), + name: ¶m.name, + source, + value, + module_id: ¶meter_module, + span: Some(span), + })?; + } + } let mut frame = Frame { function: function.id.clone(), - locals, + locals: bound.locals, + id: frame_id, }; self.depth += 1; let result = self.exec_stmts(program, &function.body, &mut frame); @@ -195,6 +239,12 @@ impl<'a> Interpreter<'a> { call_span, Some(status), ); + let close = self + .host + .observation_end_frame(frame_id, status, &trace_module, call_span); + if result.is_ok() { + close?; + } match result { Ok(Flow::Next) => Ok(Value::Unit), Ok(Flow::Return(value)) => Ok(value), @@ -215,7 +265,7 @@ impl<'a> Interpreter<'a> { function: &Function, args: Vec, call_span: Option, - ) -> Result, RuntimeError> { + ) -> Result { let mut provided: BTreeMap = BTreeMap::new(); let mut positional = 0usize; for arg in args { @@ -264,11 +314,10 @@ impl<'a> Interpreter<'a> { } } let mut locals = BTreeMap::new(); + let mut provenance = BTreeMap::new(); for param in &function.params { - match provided.remove(¶m.name) { - Some(value) => { - locals.insert(param.name.clone(), value); - } + let (value, source) = match provided.remove(¶m.name) { + Some(value) => (value, ParameterSource::Provided), None => { if let Some(default) = ¶m.default { // Defaults are compile-time constants; evaluate them in @@ -276,9 +325,10 @@ impl<'a> Interpreter<'a> { let mut empty = Frame { function: function.id.clone(), locals: BTreeMap::new(), + id: None, }; let value = self.eval_expr(default, &mut empty)?; - locals.insert(param.name.clone(), value); + (value, ParameterSource::Default) } else { return Err(RuntimeError::new( ErrorCategory::Arity, @@ -290,9 +340,11 @@ impl<'a> Interpreter<'a> { )); } } - } + }; + provenance.insert(param.name.clone(), (source, param.span)); + locals.insert(param.name.clone(), value); } - Ok(locals) + Ok(BoundArgs { locals, provenance }) } fn exec_stmts( @@ -323,6 +375,20 @@ impl<'a> Interpreter<'a> { PlaceTarget::Local { name, .. } => { let value = self.eval_expr(value, frame)?; frame.locals.insert(name.clone(), value); + if self.observe { + if let Some(committed) = frame.locals.get(name) { + let module = frame.function.module.canonical(); + self.host.observe_runtime( + RuntimeObservation::VariableAssigned { + frame_id: frame.id, + name, + value: committed, + module_id: &module, + span: Some(stmt.span()), + }, + )?; + } + } } PlaceTarget::Index { base, index, span } => { // Frozen order (ADR-0022): base, index, then RHS. @@ -351,6 +417,14 @@ impl<'a> Interpreter<'a> { Some(*span), Some(value.type_name()), ); + if self.observe { + self.host.observe_runtime(RuntimeObservation::Return { + frame_id: frame.id, + value_type: value.type_name(), + module_id: &module, + span: Some(*span), + })?; + } return Ok(Flow::Return(value)); } Stmt::Branch { arms, .. } => { @@ -374,6 +448,14 @@ impl<'a> Interpreter<'a> { Some(arm.condition_span), Some(if condition { "true" } else { "false" }), ); + if self.observe { + self.host.observe_runtime(RuntimeObservation::BranchEval { + frame_id: frame.id, + result: condition, + module_id: &module, + span: Some(arm.condition_span), + })?; + } if condition { match self.exec_stmts(program, &arm.body, frame)? { Flow::Next => break, @@ -405,6 +487,15 @@ impl<'a> Interpreter<'a> { Some(*condition_span), Some(if value { "continue" } else { "exit" }), ); + if self.observe { + self.host + .observe_runtime(RuntimeObservation::LoopIteration { + frame_id: frame.id, + decision: if value { "continue" } else { "exit" }, + module_id: &module, + span: Some(*condition_span), + })?; + } if !value { break; } diff --git a/crates/marqdo-runtime/tests/observation.rs b/crates/marqdo-runtime/tests/observation.rs new file mode 100644 index 0000000..e59fc09 --- /dev/null +++ b/crates/marqdo-runtime/tests/observation.rs @@ -0,0 +1,368 @@ +//! Runtime observation integration tests (RFC-OBS-0001 / ADR-0059). +//! +//! The real frontend/IR/runtime path is exercised with an in-memory sink: +//! frame identity, branch/loop/return attribution, committed assignment +//! events, exact parameter selection and redaction of unselected values. + +use std::cell::RefCell; +use std::rc::Rc; + +use marqdo_host::{ + Capabilities, ObservationConfig, ObservationError, ObservationEvent, ObservationSink, + ParameterSource, StdHost, ValueState, +}; +use marqdo_ir::{ModuleId, Program}; +use marqdo_runtime::run; +use marqdo_sandbox::SandboxMode; +use marqdo_value::Value; + +#[derive(Debug, Clone)] +struct Seen { + kind: &'static str, + frame: Option, + name: String, + value_type: String, + state: Option, + wire: Option, + source: Option, + decision: String, +} + +struct Recorder(Rc>>); + +impl ObservationSink for Recorder { + fn emit(&mut self, event: ObservationEvent<'_>) -> Result<(), ObservationError> { + let seen = match event { + ObservationEvent::CallEnter { frame_id, .. } => Seen { + kind: "enter", + frame: Some(frame_id.0), + name: String::new(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + ObservationEvent::CallExit { + frame_id, status, .. + } => Seen { + kind: "exit", + frame: Some(frame_id.0), + name: status.to_string(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + ObservationEvent::Return { + frame_id, + value_type, + .. + } => Seen { + kind: "return", + frame: Some(frame_id.0), + name: String::new(), + value_type: value_type.to_string(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + ObservationEvent::BranchEval { + frame_id, result, .. + } => Seen { + kind: "branch", + frame: Some(frame_id.0), + name: result.to_string(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + ObservationEvent::LoopIteration { + frame_id, decision, .. + } => Seen { + kind: "loop", + frame: Some(frame_id.0), + name: String::new(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: decision.to_string(), + }, + ObservationEvent::VariableAssigned { + frame_id, + name, + value_type, + value_state, + value, + .. + } => Seen { + kind: "variable", + frame: Some(frame_id.0), + name: name.to_string(), + value_type: value_type.to_string(), + state: Some(value_state), + wire: value.map(|value| value.wire), + source: None, + decision: String::new(), + }, + ObservationEvent::ParameterObserved { + frame_id, + name, + source, + value_type, + value_state, + value, + .. + } => Seen { + kind: "parameter", + frame: Some(frame_id.0), + name: name.to_string(), + value_type: value_type.to_string(), + state: Some(value_state), + wire: value.map(|value| value.wire), + source: Some(source), + decision: String::new(), + }, + ObservationEvent::Effect { operation, .. } => Seen { + kind: "effect", + frame: None, + name: operation.to_string(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + ObservationEvent::ObservationTruncated { reason, .. } => Seen { + kind: "truncated", + frame: None, + name: reason.to_string(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + ObservationEvent::StdoutChunk { .. } | ObservationEvent::StderrChunk { .. } => Seen { + kind: "chunk", + frame: None, + name: String::new(), + value_type: String::new(), + state: None, + wire: None, + source: None, + decision: String::new(), + }, + }; + self.0.borrow_mut().push(seen); + Ok(()) + } +} + +fn build(source: &str) -> Program { + let result = marqdo_frontend::analyze_source("index.mq.md", source); + assert!(!result.has_errors(), "{:#?}", result.diagnostics); + let module_id = ModuleId::from("index.mq.md"); + let mut program = Program { + main_module: Some(module_id.clone()), + ..Program::default() + }; + program.insert(result.module); + let registry = program.callable_registry(); + let bound = marqdo_frontend::calls::bind_program_calls(&program, ®istry); + assert!(bound.diagnostics.is_empty(), "{:#?}", bound.diagnostics); + program.set_call_bindings(bound.bindings); + program +} + +fn source() -> &'static str { + "## @exec f\n\n`params(n: Int)`\n\n`if n <= 0`\n\n`return 0`\n\n`end`\n\n`x = n`\n\n`return x + f(n=n-1)`\n\n## @exec main\n\n`i = 0`\n\n`while i < 2`\n\n`i = i + 1`\n\n`end`\n\n`visible = 42`\n\n`secret = \"DO_NOT_LEAK_SENTINEL_1\"`\n\n`return f(n=2)`\n" +} + +fn run_observed(config: ObservationConfig) -> (Value, Vec) { + let program = build(source()); + let seen = Rc::new(RefCell::new(Vec::new())); + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::pure(), + std::env::temp_dir(), + ) + .with_observation(config, Box::new(Recorder(Rc::clone(&seen)))); + let outcome = run( + &program, + &mut host, + &ModuleId::from("index.mq.md"), + "main", + Vec::new(), + ); + let value = outcome.map(|outcome| outcome.value).unwrap(); + let seen = seen.borrow().clone(); + (value, seen) +} + +#[test] +fn recursive_calls_get_unique_frames_and_correct_parents() { + let (value, seen) = run_observed(ObservationConfig::default()); + assert_eq!(value, Value::int(3)); + + let enters: Vec<_> = seen.iter().filter(|event| event.kind == "enter").collect(); + assert_eq!(enters.len(), 4, "main + f(2) + f(1) + f(0)"); + let mut ids: Vec = enters.iter().filter_map(|event| event.frame).collect(); + ids.sort_unstable(); + ids.dedup(); + assert_eq!(ids.len(), 4, "frame ids must be run-unique"); + assert_eq!( + enters[0].frame, + Some(1), + "the entry frame is the first frame" + ); + // Nested calls are announced in call order; each later frame has a parent. + for pair in enters.windows(2).skip(1).take(2) { + assert!(pair[1].frame.unwrap() > pair[0].frame.unwrap()); + } + let exits = seen.iter().filter(|event| event.kind == "exit").count(); + assert_eq!(exits, 4, "every entered frame closes, including recursion"); + let returns = seen.iter().filter(|event| event.kind == "return").count(); + assert_eq!(returns, 4); + assert!( + seen.iter().all(|event| event.wire.is_none()), + "default observation publishes no value payloads" + ); +} + +#[test] +fn branch_loop_and_assignments_are_attributed_and_default_hides_values() { + let (_value, seen) = run_observed(ObservationConfig::default()); + let branches: Vec<_> = seen.iter().filter(|event| event.kind == "branch").collect(); + assert_eq!( + branches.len(), + 3, + "one condition per call: f(2), f(1), f(0)" + ); + assert_eq!( + branches.iter().filter(|event| event.name == "true").count(), + 1, + "only the n <= 0 branch is true" + ); + let loops: Vec<_> = seen.iter().filter(|event| event.kind == "loop").collect(); + assert_eq!( + loops + .iter() + .map(|event| event.decision.as_str()) + .collect::>(), + vec!["continue", "continue", "exit"] + ); + + let mut variables: Vec<(&str, &str)> = seen + .iter() + .filter(|event| event.kind == "variable") + .map(|event| (event.name.as_str(), event.value_type.as_str())) + .collect(); + variables.sort(); + assert!(variables.contains(&("i", "Int"))); + assert!(variables.contains(&("visible", "Int"))); + assert!(variables.contains(&("secret", "Text"))); + assert!(variables.contains(&("x", "Int"))); + for event in seen.iter().filter(|event| event.kind == "variable") { + assert_eq!(event.state, Some(ValueState::NotRequested)); + assert!( + event.wire.is_none(), + "default event mode publishes no values" + ); + } + assert!(!serde_json::to_string( + &seen + .iter() + .filter_map(|event| event.wire.clone()) + .collect::>() + ) + .unwrap() + .contains("DO_NOT_LEAK_SENTINEL_1")); +} + +#[test] +fn exact_selection_publishes_only_selected_scalars_and_redacts_text() { + let mut config = ObservationConfig::default(); + config.selected_variables.insert("visible".to_string()); + config.selected_variables.insert("secret".to_string()); + config.selected_parameters.insert("n".to_string()); + let (_value, seen) = run_observed(config); + + let visible = seen + .iter() + .find(|event| event.kind == "variable" && event.name == "visible") + .expect("visible assignment event"); + assert_eq!(visible.state, Some(ValueState::Observed)); + assert_eq!( + visible.wire.as_ref().unwrap()["decimal"], + serde_json::Value::from("42") + ); + + let secret = seen + .iter() + .filter(|event| event.kind == "variable" && event.name == "secret") + .collect::>(); + assert!(!secret.is_empty()); + for event in secret { + assert_eq!(event.state, Some(ValueState::Redacted)); + assert!(event.wire.is_none(), "text needs a second explicit consent"); + } + + let unselected: Vec<_> = seen + .iter() + .filter(|event| event.kind == "variable" && (event.name == "x" || event.name == "i")) + .collect(); + assert!(!unselected.is_empty()); + for event in unselected { + assert_eq!(event.state, Some(ValueState::NotRequested)); + assert!(event.wire.is_none(), "unselected names never carry values"); + } + + let parameters: Vec<_> = seen + .iter() + .filter(|event| event.kind == "parameter" && event.name == "n") + .collect(); + assert_eq!(parameters.len(), 3, "f(2), f(1), f(0)"); + assert_eq!( + parameters + .iter() + .map(|event| event.wire.as_ref().unwrap()["decimal"].as_str().unwrap()) + .collect::>(), + vec!["2", "1", "0"] + ); + assert!(parameters + .iter() + .all(|event| event.source == Some(ParameterSource::Provided))); +} + +#[test] +fn argument_binding_failure_creates_no_frame() { + let program = build(source()); + let seen = Rc::new(RefCell::new(Vec::new())); + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::pure(), + std::env::temp_dir(), + ) + .with_observation( + ObservationConfig::default(), + Box::new(Recorder(Rc::clone(&seen))), + ); + let result = run( + &program, + &mut host, + &ModuleId::from("index.mq.md"), + "f", + vec![], + ); + assert!(result.is_err(), "f requires n"); + assert!( + seen.borrow().iter().all(|event| event.kind != "enter"), + "a frame is announced only after successful binding" + ); +} diff --git a/crates/marqdo-value/src/error.rs b/crates/marqdo-value/src/error.rs index 16ce085..232b60c 100644 --- a/crates/marqdo-value/src/error.rs +++ b/crates/marqdo-value/src/error.rs @@ -55,6 +55,11 @@ pub enum ErrorCategory { ForeignFailure, /// A host operation failed for an environmental reason. HostError, + /// The observation event transport failed (broken pipe/write error). + /// + /// This aborts the run rather than letting a program with side effects + /// continue after its event channel died (RFC-OBS-0001 §5.3). + Observation, /// Internal invariant violation. Internal, } @@ -84,6 +89,7 @@ impl ErrorCategory { ErrorCategory::PluginFailure => "plugin.failure", ErrorCategory::ForeignFailure => "foreign.failure", ErrorCategory::HostError => "host.error", + ErrorCategory::Observation => "observe.transport_failed", ErrorCategory::Internal => codes::INTERNAL, } }