//! L0.5 host primitives for official stdlib (`lib/fs`, `time`, `math`, …). //! //! User docs should import L1 wrappers; these `host_*` names are the Rust surface. //! Capabilities default **on** (importing a lib means you intend to use it). //! Soft side-effects (no process::exit; sleep clamp) apply under view / capture only. pub mod agent_rt; pub mod collection; mod dispatch; mod cli; mod csv; mod datetime; mod encoding; pub mod event_bus; #[cfg(feature = "exec-host")] pub mod foreign; #[cfg(feature = "exec-host")] pub mod foreign_doc; #[cfg(feature = "exec-host")] pub mod foreign_session; mod fs; mod hash; mod html_ops; pub(crate) mod json; mod log; pub mod math; mod net; mod path; mod re; mod secrets; mod stats; mod text_ops; mod time; pub(crate) mod toml_ops; mod url_ops; mod uuid_ops; #[cfg(feature = "plugin-host")] pub mod plugin; #[cfg(not(feature = "plugin-host"))] #[path = "plugin_stub.rs"] pub mod plugin; #[cfg(feature = "exec-host")] pub mod subtask; #[cfg(not(feature = "exec-host"))] #[path = "subtask_stub.rs"] pub mod subtask; pub mod sandbox_fs; mod sys; pub mod writeback; pub use dispatch::{call_host, HostFn}; /// Shared `text` argument extraction for host modules. /// /// `` slimming: this used to be copy-pasted in 17 host modules with two /// different wordings; one implementation keeps messages consistent. pub fn as_text<'a>(v: &'a crate::value::Value, label: &str) -> Result<&'a str, String> { match v { crate::value::Value::Text(s) => Ok(s.as_str()), _ => Err(format!("{label} needs text")), } } pub use fs::path_under_root; pub use plugin::PluginState; use std::collections::HashMap; use std::path::{Path, PathBuf}; /// Host capability flags. Default: all enabled. #[derive(Debug, Clone, Copy)] pub struct HostCaps { pub fs_write: bool, pub exec: bool, pub net: bool, pub plugin: bool, } impl Default for HostCaps { fn default() -> Self { Self { fs_write: true, exec: true, net: true, plugin: true, } } } /// SVG plot produced during a run (for CLI auto-write / view embed). #[derive(Debug, Clone)] pub struct PlotArtifact { /// User-requested path, if any. pub path: Option, pub svg: String, } #[derive(Debug)] pub struct HostContext { pub caps: HostCaps, pub fs_root: Option, pub cwd: PathBuf, pub argv: Vec, /// Soft mode: do not `process::exit`; honor sleep_limit (view / capture / export). pub soft_side_effects: bool, pub sleep_limit_ms: Option, /// LCG state for `random` / `random_int`. pub rng: u64, pub plots: Vec, /// lang → interpreter argv (from `set_cmd`). pub foreign_cmds: HashMap>, /// Process-local language registrations (`register` / `set_cmd`). pub foreign_specs: HashMap, /// Project config specs (`.marqdo/foreign.toml`), lower priority than runtime. pub foreign_config_specs: HashMap, /// Whether project config has been discovered/loaded. pub foreign_config_loaded: bool, /// Persistent foreign kernels (`session_open`). #[cfg(feature = "exec-host")] pub foreign_sessions: HashMap, /// Monotonic session id counter. #[cfg(feature = "exec-host")] pub foreign_session_seq: u64, /// Loaded native plugins (ABI v1/v2). pub plugins: PluginState, /// Entry `.mq.md` source text (for ABI host_query / context injection). pub entry_source: Option, pub entry_path: Option, /// Active function names (outer → inner) for call-site injection. pub call_stack: Vec, /// Last statement line (updated by interpreters for call-site queries). pub current_line: u32, /// Entry-file line of each active user call (for writeback anchoring). pub call_site_lines: Vec, /// Bound Artifact Metadata from the entry `.mq.md` (Phase 1 Binding). pub entry_metadata: Vec<(String, crate::value::Value)>, /// Concurrent subtasks (`lib/subtask`): file / function / foreign. #[cfg_attr(not(feature = "exec-host"), allow(dead_code))] pub(crate) subtasks: HashMap, pub subtask_seq: u64, /// Minimum log level (`lib/log`); default Info (20). See `host::log::Level`. pub log_min_level: u8, /// Active `ext/ai/sandbox` CoW session id (nested `sandbox_run`). pub sandbox_session: Option, } impl Default for HostContext { fn default() -> Self { Self { caps: HostCaps::default(), fs_root: None, cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")), argv: Vec::new(), soft_side_effects: false, sleep_limit_ms: Some(30_000), rng: 0xC0FF_EE42_CAFE_BABE, plots: Vec::new(), foreign_cmds: HashMap::new(), foreign_specs: HashMap::new(), foreign_config_specs: HashMap::new(), foreign_config_loaded: false, #[cfg(feature = "exec-host")] foreign_sessions: HashMap::new(), #[cfg(feature = "exec-host")] foreign_session_seq: 0, plugins: PluginState::default(), entry_source: None, entry_path: None, call_stack: Vec::new(), current_line: 1, call_site_lines: Vec::new(), entry_metadata: Vec::new(), subtasks: HashMap::new(), subtask_seq: 0, log_min_level: 20, // Info sandbox_session: None, } } } impl Drop for HostContext { fn drop(&mut self) { subtask::kill_all(self); #[cfg(feature = "exec-host")] foreign_session::shutdown(self); } } impl HostContext { pub fn for_run(path: Option<&Path>, caps: HostCaps, argv: Vec) -> Self { let mut ctx = Self::default(); ctx.caps = caps; ctx.argv = argv; if let Some(p) = path { if let Some(parent) = p.parent() { let parent = if parent.as_os_str().is_empty() { PathBuf::from(".") } else { parent.to_path_buf() }; ctx.cwd = parent.clone(); ctx.fs_root = Some(parent); } } ctx } /// Capture stdout / view / export: soft exit + sleep clamp; same caps as CLI by default. pub fn for_capture(path: Option<&Path>, caps: HostCaps) -> Self { let mut ctx = Self::for_run(path, caps, Vec::new()); ctx.soft_side_effects = true; ctx.sleep_limit_ms = Some(0); ctx } pub fn allow_fs_write(&self) -> bool { self.caps.fs_write } pub fn allow_exec(&self) -> bool { self.caps.exec } pub fn allow_net(&self) -> bool { self.caps.net } pub fn push_call_site_line(&mut self, line: u32) { self.call_site_lines.push(line); } pub fn pop_call_site_line(&mut self) { self.call_site_lines.pop(); } pub fn allow_plugin(&self) -> bool { self.caps.plugin } pub fn next_u64(&mut self) -> u64 { // SplitMix64-ish LCG step self.rng = self .rng .wrapping_mul(6364136223846793005) .wrapping_add(1); let mut z = self.rng; z = (z ^ (z >> 30)).wrapping_mul(0xbf58476d1ce4e5b9); z = (z ^ (z >> 27)).wrapping_mul(0x94d049bb133111eb); z ^ (z >> 31) } pub fn next_f64(&mut self) -> f64 { let x = self.next_u64() >> 11; (x as f64) / ((1u64 << 53) as f64) } pub fn resolve_path(&self, rel: &str) -> Result { let p = Path::new(rel); let abs = if p.is_absolute() { p.to_path_buf() } else { self.cwd.join(p) }; if let Some(root) = &self.fs_root { let root_canon = root.canonicalize().unwrap_or_else(|_| root.clone()); let check = abs.canonicalize().unwrap_or_else(|_| abs.clone()); if !path_under_root(&check, &root_canon) && !path_under_root(&abs, root) { if let Some(parent) = abs.parent() { let parent_ok = parent .canonicalize() .map(|p| path_under_root(&p, &root_canon)) .unwrap_or_else(|_| path_under_root(parent, root)); if !parent_ok { return Err(format!("path escapes sandbox root: {}", abs.display())); } } else { return Err(format!("path escapes sandbox root: {}", abs.display())); } } } Ok(abs) } } /// Write auto-named plot files for CLI runs when `path` was omitted. pub fn flush_auto_plots(source_path: Option<&Path>, plots: &[PlotArtifact]) -> Result<(), String> { let mut auto_i = 0usize; for plot in plots { if plot.path.is_some() { continue; } auto_i += 1; let stem = source_path .and_then(|p| p.file_stem()) .and_then(|s| s.to_str()) .unwrap_or("out"); let stem = stem.trim_end_matches(".mq"); let name = format!("{stem}-plot-{auto_i}.svg"); let dir = source_path .and_then(|p| p.parent()) .unwrap_or_else(|| Path::new(".")); let dest = dir.join(&name); std::fs::write(&dest, plot.svg.as_bytes()) .map_err(|e| format!("failed to write plot {}: {e}", dest.display()))?; println!("plot: {}", dest.display()); } Ok(()) }