feat(host): capability host, budgets, effect tracing and kernel adapters

Implements the single side-effect boundary from blueprint sections 7.3 and 9:

- Capabilities: console/math, project-relative fs globs, net hosts, process,
  foreign, plugins; pure/project defaults deny external I/O and grants are
  explicit, checked at execution time (never at parse time).
- Budget: evaluation fuel, call-stack depth, program output bytes and a
  wall-clock deadline, all reported as resource.exhausted.
- EffectTrace: op/module/span/duration/result entries with no secret data.
- StdHost: canonical Host implementation dispatching print, fs read/write and
  the math/foreign kernels; all errors are structured RuntimeErrors, including
  a permission.denied path with a grant hint.
- ProjectFs: project-rooted, rejects absolute paths, `..` traversal and symlink
  escapes outside the root; bounded UTF-8 reads and safe writes.
- Math adapter: parse/eval/substitute through marqdo-math with exact rational
  binding conversion and explicit unsupported-operation errors.
- Foreign adapter: capability-gated one-shot run/call through marqdo-foreign,
  typed wire input, structured result map, timeout/output limits mapped to
  budget errors.
This commit is contained in:
cflmy committed 2026-11-20 10:43:50 +08:00
1 parent d799617076
commit 17b68da7f9
9 files changed
+1237 -1

No files matched your search

+4 -1
View File
@@ -9,13 +9,16 @@ repository.workspace = true
authors.workspace = true
[dependencies]
glob = { workspace = true }
marqdo-span = { workspace = true }
marqdo-value = { workspace = true }
marqdo-math = { workspace = true }
marqdo-foreign = { workspace = true }
marqdo-plugin-abi = { workspace = true }
marqdo-sandbox = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
tempfile = { workspace = true }
+143
View File
@@ -0,0 +1,143 @@
//! Resource budgets: fuel, stack depth, output bytes and wall-clock deadline.
use std::time::Instant;
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError};
/// Default evaluation fuel for one run.
pub const DEFAULT_FUEL: u64 = 5_000_000;
/// Default call-stack depth.
pub const DEFAULT_STACK_LIMIT: usize = 256;
/// Default program output limit (bytes).
pub const DEFAULT_OUTPUT_BYTES: usize = 1 << 20;
/// Bounded resources for a run.
#[derive(Debug, Clone)]
pub struct Budget {
/// Remaining evaluation fuel.
pub fuel: u64,
/// Maximum call-stack depth.
pub stack_limit: usize,
/// Maximum program output in bytes.
pub max_output_bytes: usize,
/// Output bytes produced so far.
pub output_bytes: usize,
/// Optional wall-clock deadline.
pub deadline: Option<Instant>,
}
impl Default for Budget {
fn default() -> Self {
Self {
fuel: DEFAULT_FUEL,
stack_limit: DEFAULT_STACK_LIMIT,
max_output_bytes: DEFAULT_OUTPUT_BYTES,
output_bytes: 0,
deadline: None,
}
}
}
impl Budget {
/// Consume fuel, failing with `resource.exhausted` when it runs out.
pub fn consume_fuel(&mut self, amount: u64, span: Option<Span>) -> Result<(), RuntimeError> {
if amount > self.fuel {
self.fuel = 0;
return Err(RuntimeError::new(
ErrorCategory::ResourceExhausted,
span,
"evaluation fuel exhausted",
));
}
self.fuel -= amount;
Ok(())
}
/// Remaining fuel.
pub fn remaining_fuel(&self) -> u64 {
self.fuel
}
/// Check call-stack depth.
pub fn check_stack(&self, depth: usize, span: Option<Span>) -> Result<(), RuntimeError> {
if depth > self.stack_limit {
return Err(RuntimeError::new(
ErrorCategory::ResourceExhausted,
span,
format!(
"call stack depth limit ({} frames) exceeded",
self.stack_limit
),
));
}
Ok(())
}
/// Account for program output, failing when the limit is exceeded.
pub fn consume_output(
&mut self,
amount: usize,
span: Option<Span>,
) -> Result<(), RuntimeError> {
let next = self.output_bytes.saturating_add(amount);
if next > self.max_output_bytes {
return Err(RuntimeError::new(
ErrorCategory::ResourceExhausted,
span,
format!(
"program output limit ({} bytes) exceeded",
self.max_output_bytes
),
));
}
self.output_bytes = next;
Ok(())
}
/// Check the wall-clock deadline.
pub fn check_deadline(&self, span: Option<Span>) -> Result<(), RuntimeError> {
if let Some(deadline) = self.deadline {
if Instant::now() >= deadline {
return Err(RuntimeError::new(
ErrorCategory::ResourceExhausted,
span,
"wall-clock time limit exceeded",
));
}
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn fuel_is_bounded() {
let mut budget = Budget {
fuel: 10,
..Budget::default()
};
assert!(budget.consume_fuel(4, None).is_ok());
assert_eq!(budget.remaining_fuel(), 6);
assert_eq!(
budget.consume_fuel(7, None).unwrap_err().category,
ErrorCategory::ResourceExhausted
);
}
#[test]
fn output_and_stack_limits() {
let mut budget = Budget {
max_output_bytes: 5,
stack_limit: 2,
..Budget::default()
};
assert!(budget.consume_output(5, None).is_ok());
assert!(budget.consume_output(1, None).is_err());
assert!(budget.check_stack(2, None).is_ok());
assert!(budget.check_stack(3, None).is_err());
}
}
+195
View File
@@ -0,0 +1,195 @@
//! Capability model.
//!
//! A project manifest can *request* capabilities, but requests are not grants.
//! Effective permissions are the host default for the sandbox mode intersected
//! with what the operator/CLI explicitly granted. Every host operation checks
//! against this set at the point of execution.
use glob::Pattern;
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError};
/// Effective capability grants for one run.
#[derive(Debug, Clone, Default)]
pub struct Capabilities {
/// Write to program standard output (`打印`).
pub console: bool,
/// Use the native math kernel.
pub math: bool,
/// Readable project-relative path patterns.
pub fs_read: Vec<String>,
/// Writable project-relative path patterns.
pub fs_write: Vec<String>,
/// Allowed network hosts (empty = no network).
pub net_hosts: Vec<String>,
/// May spawn processes (foreign kernels).
pub process: bool,
/// May run foreign kernels (Python/Node).
pub foreign: bool,
/// Allowed plugin names.
pub plugins: Vec<String>,
}
impl Capabilities {
/// Default grants for pure mode: no external I/O, math and console only.
pub fn pure() -> Self {
Self {
console: true,
math: true,
fs_read: Vec::new(),
fs_write: Vec::new(),
net_hosts: Vec::new(),
process: false,
foreign: false,
plugins: Vec::new(),
}
}
/// Default grants for project mode: the same baseline; operators add
/// explicit grants for files, processes or plugins.
pub fn project() -> Self {
Self::pure()
}
/// Grant read access to a project-relative glob pattern.
pub fn allow_read(mut self, pattern: impl Into<String>) -> Self {
self.fs_read.push(pattern.into());
self
}
/// Grant write access to a project-relative glob pattern.
pub fn allow_write(mut self, pattern: impl Into<String>) -> Self {
self.fs_write.push(pattern.into());
self
}
/// Grant foreign kernel execution.
pub fn allow_foreign(mut self) -> Self {
self.foreign = true;
self.process = true;
self
}
/// Grant a plugin name.
pub fn allow_plugin(mut self, name: impl Into<String>) -> Self {
self.plugins.push(name.into());
self
}
/// Whether a project-relative path matches a granted pattern.
///
/// Patterns and paths are normalised by stripping a leading `./` so that
/// `--allow-read ./data/**` and the path `data/a.csv` agree.
fn matches(patterns: &[String], relative: &str) -> bool {
let relative = relative.trim_start_matches("./");
patterns.iter().any(|pattern| {
let pattern = pattern.trim_start_matches("./");
Pattern::new(pattern)
.map(|pattern| pattern.matches(relative))
.unwrap_or(false)
})
}
/// Check read access.
pub fn check_read(&self, relative: &str, span: Option<Span>) -> Result<(), RuntimeError> {
if Self::matches(&self.fs_read, relative) {
Ok(())
} else {
Err(denied(
span,
format!("read access to `{relative}` was not granted"),
format!("grant it with --allow-read {relative} or a project capability"),
))
}
}
/// Check write access.
pub fn check_write(&self, relative: &str, span: Option<Span>) -> Result<(), RuntimeError> {
if Self::matches(&self.fs_write, relative) {
Ok(())
} else {
Err(denied(
span,
format!("write access to `{relative}` was not granted"),
format!("grant it with --allow-write {relative} or a project capability"),
))
}
}
/// Check network access for a host.
pub fn check_net(&self, host: &str, span: Option<Span>) -> Result<(), RuntimeError> {
if self.net_hosts.iter().any(|allowed| allowed == host) {
Ok(())
} else {
Err(denied(
span,
format!("network access to `{host}` was not granted"),
"network access is denied by default",
))
}
}
/// Check foreign kernel execution.
pub fn check_foreign(&self, span: Option<Span>) -> Result<(), RuntimeError> {
if self.foreign && self.process {
Ok(())
} else {
Err(denied(
span,
"foreign kernel execution was not granted",
"grant it with --allow-foreign (project/strict policy permitting)",
))
}
}
/// Check plugin execution.
pub fn check_plugin(&self, name: &str, span: Option<Span>) -> Result<(), RuntimeError> {
if self.plugins.iter().any(|allowed| allowed == name) {
Ok(())
} else {
Err(denied(
span,
format!("plugin `{name}` was not granted execution permission"),
"installing a plugin does not grant permission to run it",
))
}
}
}
fn denied(span: Option<Span>, message: impl Into<String>, hint: impl Into<String>) -> RuntimeError {
let mut error = RuntimeError::new(ErrorCategory::PermissionDenied, span, message);
error.effect_trace.push(format!("hint: {}", hint.into()));
error
}
#[cfg(test)]
mod tests {
use super::*;
use marqdo_value::ErrorCategory;
#[test]
fn defaults_deny_external_io() {
let capabilities = Capabilities::pure();
assert!(capabilities.math);
assert!(capabilities.console);
assert_eq!(
capabilities
.check_read("data/a.txt", None)
.unwrap_err()
.category,
ErrorCategory::PermissionDenied
);
assert!(capabilities.check_foreign(None).is_err());
}
#[test]
fn explicit_grants_are_glob_scoped() {
let capabilities = Capabilities::project()
.allow_read("./data/**")
.allow_write("./output/**");
assert!(capabilities.check_read("data/a.csv", None).is_ok());
assert!(capabilities.check_read("secrets/key", None).is_err());
assert!(capabilities.check_write("output/result.txt", None).is_ok());
assert!(capabilities.check_write("data/a.csv", None).is_err());
}
}
+31
View File
@@ -0,0 +1,31 @@
//! Per-call execution context passed to the host boundary.
use marqdo_span::Span;
/// Context attached to every host invocation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExecutionContext {
/// Canonical module that initiated the operation.
pub module_id: String,
/// Source span of the call site, when known.
pub span: Option<Span>,
/// Correlates trace entries belonging to one run.
pub trace_id: u64,
}
impl ExecutionContext {
/// Create a context.
pub fn new(module_id: impl Into<String>, span: Option<Span>) -> Self {
Self {
module_id: module_id.into(),
span,
trace_id: 0,
}
}
/// Set the trace id.
pub fn with_trace_id(mut self, trace_id: u64) -> Self {
self.trace_id = trace_id;
self
}
}
+208
View File
@@ -0,0 +1,208 @@
//! Project-scoped filesystem access.
//!
//! Paths are always project-relative. Absolute paths, `..` components and
//! symlink escapes outside the project root are rejected before the capability
//! check, and the capability check happens before any I/O.
use std::path::{Component, Path, PathBuf};
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError};
/// Maximum size for a single file read.
pub const MAX_READ_BYTES: u64 = 8 * 1024 * 1024;
/// A filesystem view rooted at the project directory.
#[derive(Debug, Clone)]
pub struct ProjectFs {
root: PathBuf,
}
impl ProjectFs {
/// Create a filesystem view. The root is canonicalised when possible.
pub fn new(root: impl Into<PathBuf>) -> Self {
let root = root.into();
let root = root.canonicalize().unwrap_or(root);
Self { root }
}
/// Project root.
pub fn root(&self) -> &Path {
&self.root
}
/// Normalise a user supplied project-relative path.
///
/// Returns the normalised relative string (with `/` separators) used for
/// capability matching and the absolute path inside the project root.
pub fn resolve(
&self,
user_path: &str,
span: Option<Span>,
) -> Result<(PathBuf, String), RuntimeError> {
if user_path.is_empty() {
return Err(invalid_path(span, "path must not be empty"));
}
let path = Path::new(user_path);
if path.is_absolute() {
return Err(invalid_path(
span,
format!("absolute paths are not allowed: `{user_path}`"),
));
}
let mut normalised = PathBuf::new();
for component in path.components() {
match component {
Component::Normal(part) => normalised.push(part),
Component::CurDir => {}
Component::ParentDir => {
return Err(invalid_path(
span,
format!("path traversal is not allowed: `{user_path}`"),
));
}
Component::RootDir | Component::Prefix(_) => {
return Err(invalid_path(
span,
format!("absolute paths are not allowed: `{user_path}`"),
));
}
}
}
if normalised.as_os_str().is_empty() {
return Err(invalid_path(span, "path must name a file"));
}
let relative = normalised
.components()
.map(|component| component.as_os_str().to_string_lossy().to_string())
.collect::<Vec<_>>()
.join("/");
let absolute = self.root.join(&normalised);
Ok((absolute, relative))
}
/// Read a UTF-8 file, bounded by [`MAX_READ_BYTES`].
pub fn read(&self, user_path: &str, span: Option<Span>) -> Result<String, RuntimeError> {
let (absolute, relative) = self.resolve(user_path, span)?;
let metadata = std::fs::metadata(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot read `{relative}`: {error}"),
)
})?;
if !metadata.is_file() {
return Err(RuntimeError::new(
ErrorCategory::HostError,
span,
format!("`{relative}` is not a regular file"),
));
}
if metadata.len() > MAX_READ_BYTES {
return Err(RuntimeError::new(
ErrorCategory::ResourceExhausted,
span,
format!(
"`{relative}` exceeds the {} byte read limit",
MAX_READ_BYTES
),
));
}
let canonical = absolute.canonicalize().map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot resolve `{relative}`: {error}"),
)
})?;
if !canonical.starts_with(&self.root) {
return Err(invalid_path(span, "path escapes the project root"));
}
let bytes = std::fs::read(&canonical).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot read `{relative}`: {error}"),
)
})?;
String::from_utf8(bytes).map_err(|_| {
RuntimeError::new(
ErrorCategory::Type,
span,
format!("`{relative}` is not valid UTF-8"),
)
})
}
/// Write a file inside the project root, creating parent directories.
pub fn write(
&self,
user_path: &str,
contents: &str,
span: Option<Span>,
) -> Result<(), RuntimeError> {
let (absolute, relative) = self.resolve(user_path, span)?;
// Validate the closest existing ancestor stays inside the root.
let mut ancestor = absolute.parent();
while let Some(current) = ancestor {
if current.exists() {
let canonical = current.canonicalize().map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot resolve `{relative}`: {error}"),
)
})?;
if !canonical.starts_with(&self.root) {
return Err(invalid_path(span, "path escapes the project root"));
}
break;
}
ancestor = current.parent();
}
if let Some(parent) = absolute.parent() {
std::fs::create_dir_all(parent).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot create parent directory for `{relative}`: {error}"),
)
})?;
}
std::fs::write(&absolute, contents).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot write `{relative}`: {error}"),
)
})
}
}
fn invalid_path(span: Option<Span>, message: impl Into<String>) -> RuntimeError {
RuntimeError::new(ErrorCategory::PermissionDenied, span, message)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_traversal_and_absolute_paths() {
let dir = tempfile::tempdir().unwrap();
let fs = ProjectFs::new(dir.path());
assert!(fs.resolve("../etc/passwd", None).is_err());
assert!(fs.resolve("/etc/passwd", None).is_err());
assert!(fs.resolve("data/../x.txt", None).is_err());
assert!(fs.resolve("", None).is_err());
assert_eq!(fs.resolve("./data/a.txt", None).unwrap().1, "data/a.txt");
}
#[test]
fn reads_and_writes_inside_root() {
let dir = tempfile::tempdir().unwrap();
let fs = ProjectFs::new(dir.path());
fs.write("output/result.txt", "hello", None).unwrap();
assert_eq!(fs.read("output/result.txt", None).unwrap(), "hello");
}
}
+293
View File
@@ -0,0 +1,293 @@
//! CapabilityHost: the only entry point for side effects.
//!
//! The runtime never touches files, processes or the math kernel directly; it
//! calls [`Host::invoke`]. Authorization is checked here, at the point of
//! execution, not at parse/compile time.
use std::time::{Duration, Instant};
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError, Value};
use crate::budget::Budget;
use crate::capability::Capabilities;
use crate::context::ExecutionContext;
use crate::fs::ProjectFs;
use crate::trace::{EffectTrace, TraceEntry};
use marqdo_sandbox::{PlatformCapabilities, SandboxMode};
/// Host operations reachable from the language surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostOp {
/// Write a value to program stdout.
Print,
/// Parse a formula.
MathParse,
/// Evaluate a formula.
MathEval,
/// Substitute variables in a formula.
MathSubstitute,
/// Simplify a formula.
MathSimplify,
/// Differentiate a formula.
MathDifferentiate,
/// One-shot foreign execution.
ForeignRun,
/// Typed foreign call.
ForeignCall,
/// Read a project file.
FsRead,
/// Write a project file.
FsWrite,
/// Invoke a plugin export.
PluginInvoke,
}
impl HostOp {
/// Stable operation name used in traces and diagnostics.
pub const fn name(self) -> &'static str {
match self {
HostOp::Print => "print",
HostOp::MathParse => "math.parse",
HostOp::MathEval => "math.eval",
HostOp::MathSubstitute => "math.substitute",
HostOp::MathSimplify => "math.simplify",
HostOp::MathDifferentiate => "math.differentiate",
HostOp::ForeignRun => "foreign.run",
HostOp::ForeignCall => "foreign.call",
HostOp::FsRead => "fs.read",
HostOp::FsWrite => "fs.write",
HostOp::PluginInvoke => "plugin.invoke",
}
}
}
/// The host boundary used by the interpreter and future View/IDE frontends.
pub trait Host {
/// Invoke one operation with already-evaluated arguments.
fn invoke(
&mut self,
op: HostOp,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError>;
/// Consume evaluation fuel.
fn consume_fuel(&mut self, amount: u64, span: Option<Span>) -> Result<(), RuntimeError>;
/// Check call-stack depth.
fn check_stack(&self, depth: usize, span: Option<Span>) -> Result<(), RuntimeError>;
/// Check the wall-clock deadline.
fn check_deadline(&self, span: Option<Span>) -> Result<(), RuntimeError>;
/// Take the buffered program output.
fn take_output(&mut self) -> Vec<u8>;
/// Recorded effects.
fn trace(&self) -> &[TraceEntry];
}
/// Default capability host implementation.
pub struct StdHost {
/// Requested sandbox mode.
pub mode: SandboxMode,
/// Platform capability report.
pub platform: PlatformCapabilities,
/// Effective grants.
pub capabilities: Capabilities,
/// Bounded resources.
pub budget: Budget,
/// Filesystem view.
pub fs: ProjectFs,
/// Effect trace.
pub trace: EffectTrace,
/// Maximum wall-clock time for one foreign kernel call.
pub foreign_timeout: Duration,
/// Maximum captured bytes per foreign stream.
pub foreign_output_limit: usize,
output: Vec<u8>,
trace_id: u64,
}
impl StdHost {
/// Create a host with the given mode and effective capabilities.
pub fn new(
mode: SandboxMode,
capabilities: Capabilities,
project_root: impl Into<std::path::PathBuf>,
) -> Self {
let trace_id = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_nanos() as u64)
.unwrap_or(0);
Self {
mode,
platform: PlatformCapabilities::detect(),
capabilities,
budget: Budget::default(),
fs: ProjectFs::new(project_root),
trace: EffectTrace::default(),
foreign_timeout: Duration::from_secs(10),
foreign_output_limit: 1024 * 1024,
output: Vec::new(),
trace_id,
}
}
/// Enable effect tracing.
pub fn with_trace(mut self) -> Self {
self.trace = EffectTrace::enabled();
self
}
/// Override the budget.
pub fn with_budget(mut self, budget: Budget) -> Self {
self.budget = budget;
self
}
/// Current execution context for a call site.
pub fn context(&self, module: impl Into<String>, span: Option<Span>) -> ExecutionContext {
ExecutionContext::new(module, span).with_trace_id(self.trace_id)
}
/// Buffered program output without consuming it.
pub fn output(&self) -> &[u8] {
&self.output
}
fn dispatch(
&mut self,
op: HostOp,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
match op {
HostOp::Print => self.op_print(args, ctx),
HostOp::FsRead => self.op_fs_read(args, ctx),
HostOp::FsWrite => self.op_fs_write(args, ctx),
HostOp::MathParse
| HostOp::MathEval
| HostOp::MathSubstitute
| HostOp::MathSimplify
| HostOp::MathDifferentiate => crate::kernels::math(self, op, args, ctx),
HostOp::ForeignRun | HostOp::ForeignCall => {
crate::kernels::foreign(self, op, args, ctx)
}
HostOp::PluginInvoke => Err(RuntimeError::new(
ErrorCategory::KernelUnavailable,
ctx.span,
"no plugin runtime is loaded in this build",
)),
}
}
fn op_print(
&mut self,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
if args.len() != 1 {
return Err(arity(ctx.span, "打印", 1, args.len()));
}
let text = format!("{}\n", args[0].display());
self.budget.consume_output(text.len(), ctx.span)?;
self.output.extend_from_slice(text.as_bytes());
Ok(Value::Unit)
}
fn op_fs_read(
&mut self,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
let path = expect_text(&args, 0, "fs.read path", ctx.span)?;
self.capabilities.check_read(&path, ctx.span)?;
let contents = self.fs.read(&path, ctx.span)?;
self.budget.consume_output(contents.len(), ctx.span)?;
Ok(Value::Text(contents))
}
fn op_fs_write(
&mut self,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
let path = expect_text(&args, 0, "fs.write path", ctx.span)?;
let contents = expect_text(&args, 1, "fs.write contents", ctx.span)?;
self.capabilities.check_write(&path, ctx.span)?;
self.fs.write(&path, &contents, ctx.span)?;
Ok(Value::Unit)
}
}
impl Host for StdHost {
fn invoke(
&mut self,
op: HostOp,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
let started = Instant::now();
let result = self.dispatch(op, args, ctx);
let summary = match &result {
Ok(_) => "ok".to_string(),
Err(error) => error.code().to_string(),
};
self.trace.record(
op.name(),
ctx.module_id.clone(),
ctx.span,
started.elapsed(),
summary,
);
result
}
fn consume_fuel(&mut self, amount: u64, span: Option<Span>) -> Result<(), RuntimeError> {
self.budget.consume_fuel(amount, span)
}
fn check_stack(&self, depth: usize, span: Option<Span>) -> Result<(), RuntimeError> {
self.budget.check_stack(depth, span)
}
fn check_deadline(&self, span: Option<Span>) -> Result<(), RuntimeError> {
self.budget.check_deadline(span)
}
fn take_output(&mut self) -> Vec<u8> {
std::mem::take(&mut self.output)
}
fn trace(&self) -> &[TraceEntry] {
self.trace.entries()
}
}
/// Type-checked argument helper.
pub fn expect_text(
args: &[Value],
index: usize,
what: &str,
span: Option<Span>,
) -> Result<String, RuntimeError> {
match args.get(index) {
Some(Value::Text(text)) => Ok(text.clone()),
Some(other) => Err(RuntimeError::type_error(
span,
format!("{what} must be Text, got {}", other.type_name()),
)),
None => Err(arity(span, what, index + 1, args.len())),
}
}
/// Arity error helper.
pub fn arity(span: Option<Span>, name: &str, expected: usize, actual: usize) -> RuntimeError {
RuntimeError::new(
ErrorCategory::Arity,
span,
format!("`{name}` expects {expected} argument(s), got {actual}"),
)
}
+276
View File
@@ -0,0 +1,276 @@
//! Math and foreign kernel adapters.
//!
//! These functions are the only bridge between the capability host and the
//! native math / foreign crates. Every operation is capability-checked before
//! the kernel is touched; kernel failures are converted to structured runtime
//! errors, never panics.
use std::collections::BTreeMap;
use std::time::Duration;
use marqdo_value::{to_wire, ErrorCategory, FormulaValue, RuntimeError, Value};
use crate::context::ExecutionContext;
use crate::host::{arity, expect_text, HostOp, StdHost};
pub(crate) fn math(
host: &mut StdHost,
op: HostOp,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
if !host.capabilities.math {
return Err(denied(ctx, "the math capability was not granted"));
}
let span = ctx.span;
match op {
HostOp::MathParse => {
let source = expect_text(&args, 0, "math.parse source", span)?;
let formula = marqdo_math::parse(&source).map_err(|error| math_error(error, span))?;
Ok(Value::Formula(FormulaValue {
latex: formula.source,
unit: None,
display: false,
span,
}))
}
HostOp::MathEval => {
if args.len() < 2 {
return Err(arity(span, "math.eval", 2, args.len()));
}
let formula = formula_source(&args[0], span)?;
let bindings = math_bindings(&args[1], span)?;
let target = match args.get(2) {
Some(Value::Text(target)) => Some(target.clone()),
Some(Value::None) | None => None,
Some(other) => {
return Err(RuntimeError::type_error(
span,
format!("math.eval target must be Text, got {}", other.type_name()),
))
}
};
let parsed = marqdo_math::parse(&formula).map_err(|error| math_error(error, span))?;
marqdo_math::evaluate(&parsed, &bindings, target.as_deref())
.map_err(|error| math_error(error, span))
}
HostOp::MathSubstitute => {
if args.len() < 2 {
return Err(arity(span, "math.substitute", 2, args.len()));
}
let source = formula_source(&args[0], span)?;
let bindings = math_bindings(&args[1], span)?;
let parsed = marqdo_math::parse(&source).map_err(|error| math_error(error, span))?;
let substituted = marqdo_math::substitute(&parsed, &bindings)
.map_err(|error| math_error(error, span))?;
Ok(Value::Formula(FormulaValue {
latex: substituted.source,
unit: None,
display: false,
span,
}))
}
HostOp::MathSimplify | HostOp::MathDifferentiate => Err(RuntimeError::new(
ErrorCategory::MathUnsupported,
span,
format!(
"`{}` is not part of the supported math subset in this build",
op.name()
),
)),
_ => Err(RuntimeError::new(
ErrorCategory::Internal,
span,
"unexpected math operation",
)),
}
}
fn formula_source(value: &Value, span: Option<marqdo_span::Span>) -> Result<String, RuntimeError> {
match value {
Value::Formula(formula) => Ok(formula.latex.clone()),
Value::Text(text) => Ok(text.clone()),
other => Err(RuntimeError::type_error(
span,
format!("expected Formula or Text, got {}", other.type_name()),
)),
}
}
fn math_bindings(
value: &Value,
span: Option<marqdo_span::Span>,
) -> Result<BTreeMap<String, Value>, RuntimeError> {
match value {
Value::Map(map) => {
let mut bindings = BTreeMap::new();
for (name, value) in map {
match value {
Value::Int(_) | Value::Float(_) => {
bindings.insert(name.clone(), value.clone());
}
other => {
return Err(RuntimeError::type_error(
span,
format!(
"math binding `{name}` must be Int or Float, got {}",
other.type_name()
),
))
}
}
}
Ok(bindings)
}
other => Err(RuntimeError::type_error(
span,
format!("math bindings must be a Map, got {}", other.type_name()),
)),
}
}
fn math_error(error: marqdo_math::MathError, span: Option<marqdo_span::Span>) -> RuntimeError {
use marqdo_math::MathErrorKind;
let category = match error.kind {
MathErrorKind::Parse | MathErrorKind::Unsupported => ErrorCategory::MathUnsupported,
MathErrorKind::UndefinedVariable => ErrorCategory::UnknownSymbol,
MathErrorKind::Type => ErrorCategory::Type,
};
let mut message = error.message;
if let Some(position) = error.position {
message = format!("{message} (at byte {position} of the formula)");
}
RuntimeError::new(category, span, message)
}
pub(crate) fn foreign(
host: &mut StdHost,
op: HostOp,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
host.capabilities.check_foreign(ctx.span)?;
let span = ctx.span;
let Some(Value::Code(code)) = args.first() else {
return Err(RuntimeError::type_error(
span,
"foreign kernel expects a Code value from `ref(\"#代码块\")`",
));
};
if code.language.trim().is_empty() {
return Err(RuntimeError::new(
ErrorCategory::KernelUnavailable,
span,
"code fence has no language, so no kernel can be selected",
));
}
let input = match args.get(1) {
None | Some(Value::None) => None,
Some(value) => Some(to_wire(value)),
};
let request = marqdo_foreign::RunRequest {
language: code.language.clone(),
source: code.source.clone(),
input,
timeout: host.foreign_timeout,
max_output_bytes: host.foreign_output_limit,
};
match op {
HostOp::ForeignRun => {
let result =
marqdo_foreign::run(&request).map_err(|error| foreign_error(error, span))?;
Ok(foreign_result_map(result))
}
HostOp::ForeignCall => {
let result =
marqdo_foreign::call(&request).map_err(|error| foreign_error(error, span))?;
if result.status != marqdo_foreign::RunStatus::Success {
return Err(RuntimeError::new(
ErrorCategory::ForeignFailure,
span,
format!(
"foreign call failed (status {:?}): {}",
result.status, result.stderr
),
));
}
result.value.ok_or_else(|| {
RuntimeError::new(
ErrorCategory::ForeignFailure,
span,
"foreign call returned no typed value",
)
})
}
_ => Err(RuntimeError::new(
ErrorCategory::Internal,
span,
"unexpected foreign operation",
)),
}
}
fn foreign_result_map(result: marqdo_foreign::RunResult) -> Value {
let mut map = BTreeMap::new();
map.insert(
"status".to_string(),
Value::text(match result.status {
marqdo_foreign::RunStatus::Success => "success",
marqdo_foreign::RunStatus::Failed => "failed",
marqdo_foreign::RunStatus::TimedOut => "timed_out",
}),
);
map.insert("stdout".to_string(), Value::text(result.stdout));
map.insert("stderr".to_string(), Value::text(result.stderr));
map.insert(
"exit_code".to_string(),
match result.exit_code {
Some(code) => Value::int(code as i64),
None => Value::None,
},
);
map.insert(
"duration_ms".to_string(),
Value::int(result.duration.as_millis() as i64),
);
map.insert(
"value".to_string(),
match result.value {
Some(value) => value,
None => Value::None,
},
);
Value::Map(map)
}
fn foreign_error(
error: marqdo_foreign::ForeignError,
span: Option<marqdo_span::Span>,
) -> RuntimeError {
use marqdo_foreign::ForeignError;
let (category, message) = match error {
ForeignError::KernelUnavailable { language, hint } => (
ErrorCategory::KernelUnavailable,
format!("foreign kernel `{language}` is unavailable: {hint}"),
),
ForeignError::Spawn { message } => (ErrorCategory::HostError, message),
ForeignError::Io { message } => (ErrorCategory::HostError, message),
ForeignError::Timeout { seconds } => (
ErrorCategory::ResourceExhausted,
format!("foreign kernel exceeded its {seconds}s timeout"),
),
ForeignError::Protocol { message } => (ErrorCategory::ForeignFailure, message),
ForeignError::OutputTooLarge { limit } => (
ErrorCategory::ResourceExhausted,
format!("foreign kernel exceeded the {limit} byte output limit"),
),
};
RuntimeError::new(category, span, message)
}
fn denied(ctx: &ExecutionContext, message: impl Into<String>) -> RuntimeError {
RuntimeError::new(ErrorCategory::PermissionDenied, ctx.span, message)
}
/// Default per-call foreign timeout used by the CLI.
pub const DEFAULT_FOREIGN_TIMEOUT: Duration = Duration::from_secs(10);
+21
View File
@@ -0,0 +1,21 @@
//! CapabilityHost: capability checks, resource budgets, effect tracing and the
//! only bridge to math, foreign kernels, files and plugins.
//!
//! Blueprint §9 and §7.3: every side effect goes through this boundary, checks
//! happen at the point of execution, and host failures are structured errors.
pub mod budget;
pub mod capability;
pub mod context;
pub mod fs;
pub mod host;
pub mod kernels;
pub mod trace;
pub use budget::{Budget, DEFAULT_FUEL, DEFAULT_OUTPUT_BYTES, DEFAULT_STACK_LIMIT};
pub use capability::Capabilities;
pub use context::ExecutionContext;
pub use fs::ProjectFs;
pub use host::{arity, expect_text, Host, HostOp, StdHost};
pub use marqdo_sandbox::{PlatformCapabilities, SandboxMode, StrictIsolation};
pub use trace::{EffectTrace, TraceEntry};
+66
View File
@@ -0,0 +1,66 @@
//! Effect tracing.
use std::time::Duration;
use marqdo_span::Span;
use serde::{Deserialize, Serialize};
/// One recorded host effect.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TraceEntry {
/// Operation name (`print`, `fs.read`, `foreign.call`, ...).
pub op: String,
/// Module that initiated it.
pub module: String,
/// Source span of the call site.
#[serde(skip_serializing_if = "Option::is_none")]
pub span: Option<Span>,
/// Wall-clock duration.
pub duration_micros: u64,
/// Result summary (`ok`, or a diagnostic code). Never contains secrets.
pub result: String,
}
/// Collected effects for one run.
#[derive(Debug, Clone, Default)]
pub struct EffectTrace {
entries: Vec<TraceEntry>,
/// Whether tracing is enabled.
pub enabled: bool,
}
impl EffectTrace {
/// Enable tracing.
pub fn enabled() -> Self {
Self {
entries: Vec::new(),
enabled: true,
}
}
/// Record an effect.
pub fn record(
&mut self,
op: impl Into<String>,
module: impl Into<String>,
span: Option<Span>,
duration: Duration,
result: impl Into<String>,
) {
if !self.enabled {
return;
}
self.entries.push(TraceEntry {
op: op.into(),
module: module.into(),
span,
duration_micros: duration.as_micros() as u64,
result: result.into(),
});
}
/// Recorded entries.
pub fn entries(&self) -> &[TraceEntry] {
&self.entries
}
}