obs(01): typed host observation facade, real stdio chunks, frame identity and budgets

This commit is contained in:
cflmy committed 2026-11-22 15:42:41 +08:00
1 parent d38736c0a0
commit d78faaf8e4
8 files changed
+1817 -12

No files matched your search

+336
View File
@@ -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)
}
+3
View File
@@ -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);
}
}
+7
View File
@@ -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};
+540
View File
@@ -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)
}
+454
View File
@@ -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());
}
+103 -12
View File
@@ -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(&param.name).copied() else {
continue;
};
let Some(value) = bound.locals.get(&param.name) else {
continue;
};
self.host
.observe_runtime(RuntimeObservation::ParameterBound {
frame_id: Some(frame_id),
name: &param.name,
source,
value,
module_id: &parameter_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(&param.name) {
Some(value) => {
locals.insert(param.name.clone(), value);
}
let (value, source) = match provided.remove(&param.name) {
Some(value) => (value, ParameterSource::Provided),
None => {
if let Some(default) = &param.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;
}
+368
View File
@@ -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, &registry);
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"
);
}
+6
View File
@@ -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,
}
}