obs(01): typed host observation facade, real stdio chunks, frame identity and budgets
This commit is contained in:
1 parent
d38736c0a0
commit
d78faaf8e4
8 files changed
+1817
-12
No files matched your search
@@ -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<Span>,
|
||||
) -> Result<Option<FrameId>, RuntimeError> {
|
||||
Ok(None)
|
||||
}
|
||||
|
||||
/// Close a previously announced frame, including failure paths.
|
||||
fn observation_end_frame(
|
||||
&mut self,
|
||||
_frame_id: Option<FrameId>,
|
||||
_status: &str,
|
||||
_module_id: &str,
|
||||
_span: Option<Span>,
|
||||
) -> 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<SemanticEvent>,
|
||||
next_event_seq: u64,
|
||||
trace_state: TraceState,
|
||||
observation: Option<ObservationState>,
|
||||
observation_error: Option<String>,
|
||||
}
|
||||
|
||||
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<dyn ObservationSink>,
|
||||
) -> 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<Span>) -> 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<Span>) -> 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<Span>,
|
||||
) -> Result<Option<FrameId>, 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<FrameId>,
|
||||
status: &str,
|
||||
module_id: &str,
|
||||
span: Option<Span>,
|
||||
) -> 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<u8> {
|
||||
std::mem::take(&mut self.output)
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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};
|
||||
@@ -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<String>,
|
||||
/// Exact parameter names allowed to publish a value.
|
||||
pub selected_parameters: BTreeSet<String>,
|
||||
/// 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<FrameId>,
|
||||
function_id: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A frame finished, including failure paths.
|
||||
CallExit {
|
||||
frame_id: FrameId,
|
||||
status: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A `return` statement committed its value.
|
||||
Return {
|
||||
frame_id: FrameId,
|
||||
value_type: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A branch condition was evaluated.
|
||||
BranchEval {
|
||||
frame_id: FrameId,
|
||||
result: bool,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A loop condition was evaluated.
|
||||
LoopIteration {
|
||||
frame_id: FrameId,
|
||||
decision: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// The host completed a controlled effect attempt.
|
||||
Effect {
|
||||
operation: &'a str,
|
||||
result_code: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A local assignment was committed.
|
||||
VariableAssigned {
|
||||
frame_id: FrameId,
|
||||
name: &'a str,
|
||||
value_type: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
value_state: ValueState,
|
||||
value: Option<ObservedValue>,
|
||||
},
|
||||
/// A function parameter was bound.
|
||||
ParameterObserved {
|
||||
frame_id: FrameId,
|
||||
name: &'a str,
|
||||
source: ParameterSource,
|
||||
value_type: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
value_state: ValueState,
|
||||
value: Option<ObservedValue>,
|
||||
},
|
||||
/// The structural/value observation budget was exhausted.
|
||||
ObservationTruncated {
|
||||
reason: &'a str,
|
||||
limit: u64,
|
||||
written: u64,
|
||||
dropped: Option<u64>,
|
||||
},
|
||||
}
|
||||
|
||||
/// Borrowed runtime notification accepted by [`crate::Host::observe_runtime`].
|
||||
///
|
||||
/// Every variant carries an `Option<FrameId>`; 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<FrameId>,
|
||||
value_type: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A branch condition evaluated.
|
||||
BranchEval {
|
||||
frame_id: Option<FrameId>,
|
||||
result: bool,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A loop condition evaluated.
|
||||
LoopIteration {
|
||||
frame_id: Option<FrameId>,
|
||||
decision: &'a str,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A local variable assignment committed.
|
||||
VariableAssigned {
|
||||
frame_id: Option<FrameId>,
|
||||
name: &'a str,
|
||||
value: &'a Value,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
/// A parameter was bound.
|
||||
ParameterBound {
|
||||
frame_id: Option<FrameId>,
|
||||
name: &'a str,
|
||||
source: ParameterSource,
|
||||
value: &'a Value,
|
||||
module_id: &'a str,
|
||||
span: Option<Span>,
|
||||
},
|
||||
}
|
||||
|
||||
/// 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<String>) -> 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<dyn ObservationSink>,
|
||||
next_frame: u64,
|
||||
frames: Vec<FrameId>,
|
||||
written: u64,
|
||||
bytes: u64,
|
||||
truncated: bool,
|
||||
}
|
||||
|
||||
impl ObservationState {
|
||||
pub(crate) fn new(config: ObservationConfig, sink: Box<dyn ObservationSink>) -> 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<FrameId> {
|
||||
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<ObservedValue>) {
|
||||
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)
|
||||
}
|
||||
@@ -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<u8>),
|
||||
Stderr(Vec<u8>),
|
||||
Enter {
|
||||
frame: FrameId,
|
||||
parent: Option<FrameId>,
|
||||
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<serde_json::Value>,
|
||||
},
|
||||
Parameter {
|
||||
frame: FrameId,
|
||||
name: String,
|
||||
source: ParameterSource,
|
||||
state: ValueState,
|
||||
value: Option<serde_json::Value>,
|
||||
},
|
||||
Effect {
|
||||
operation: String,
|
||||
result_code: String,
|
||||
},
|
||||
Truncated {
|
||||
reason: String,
|
||||
limit: u64,
|
||||
written: u64,
|
||||
},
|
||||
}
|
||||
|
||||
impl From<ObservationEvent<'_>> 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<RefCell<Vec<Recorded>>>,
|
||||
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<RefCell<Vec<Recorded>>>) {
|
||||
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<_>>(),
|
||||
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<Vec<u8>> = 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());
|
||||
}
|
||||
@@ -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<String, Value>,
|
||||
/// Run-unique call-instance identity; `None` when observation is off.
|
||||
id: Option<FrameId>,
|
||||
}
|
||||
|
||||
/// Locals plus where each parameter's value came from.
|
||||
struct BoundArgs {
|
||||
locals: BTreeMap<String, Value>,
|
||||
provenance: BTreeMap<String, (ParameterSource, Span)>,
|
||||
}
|
||||
|
||||
/// 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<EvaluatedArg>,
|
||||
limits: MemoryLimits,
|
||||
) -> Result<RunOutcome, RuntimeError> {
|
||||
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<EvaluatedArg>,
|
||||
call_span: Option<Span>,
|
||||
) -> Result<BTreeMap<String, Value>, RuntimeError> {
|
||||
) -> Result<BoundArgs, RuntimeError> {
|
||||
let mut provided: BTreeMap<String, Value> = 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;
|
||||
}
|
||||
|
||||
@@ -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<u64>,
|
||||
name: String,
|
||||
value_type: String,
|
||||
state: Option<ValueState>,
|
||||
wire: Option<serde_json::Value>,
|
||||
source: Option<ParameterSource>,
|
||||
decision: String,
|
||||
}
|
||||
|
||||
struct Recorder(Rc<RefCell<Vec<Seen>>>);
|
||||
|
||||
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<Seen>) {
|
||||
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<u64> = 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<_>>(),
|
||||
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::<Vec<_>>()
|
||||
)
|
||||
.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::<Vec<_>>();
|
||||
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<_>>(),
|
||||
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"
|
||||
);
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user