feat(host,runtime,cli): explicit plugin invocation from documents

Blueprint section 10 / P6: exports of an explicitly trusted plugin are callable
from a `.mq.md` file through a bound namespace.

- host: StdHost::load_plugin requires an explicit trust decision and a granted
  plugin capability, loads the native artifact through the ABI v1 loader with
  no capability handler (all plugin host-capability requests denied), and
  dispatches HostOp::PluginInvoke through the typed wire request/response.
  In-process native code is documented as sharing the host address space; no
  isolated worker transport exists in this build.
- runtime: a qualified call whose base is not a local value, import alias or
  builtin namespace is routed to the plugin namespace; plugin calls take named
  arguments only and plugin values become Marqdo values (Unit when absent).
- cli: run/call gain `--plugin <path>`, `--trust-native-plugin` and reuse
  `--allow-plugin <package>`; missing trust/grant/loaded namespace surface as
  structured errors.
- frontend: member-call bases are namespaces (builtin/import/plugin), never
  inferred parameters, so `solver.add(...)` does not invent a parameter.
This commit is contained in:
cflmy committed 2026-11-20 10:46:23 +08:00
1 parent 6f04c17f7a
commit 7fbd5e9ec1
7 files changed
+221 -12

No files matched your search

Generated
+1
View File
@@ -388,6 +388,7 @@ dependencies = [
"glob",
"marqdo-foreign",
"marqdo-math",
"marqdo-plugin-abi",
"marqdo-sandbox",
"marqdo-span",
"marqdo-value",
+45 -1
View File
@@ -36,6 +36,10 @@ pub struct SandboxSettings {
pub max_output: Option<usize>,
/// Wall-clock timeout in seconds.
pub timeout: Option<u64>,
/// Explicitly trusted plugin manifests to load.
pub plugins: Vec<PathBuf>,
/// Explicit trust decision for in-process native plugin loading.
pub trust_native_plugin: bool,
}
impl SandboxSettings {
@@ -497,6 +501,18 @@ pub fn execute(
if let Some(timeout) = settings.timeout {
host.budget.deadline = Some(Instant::now() + Duration::from_secs(timeout));
}
for plugin_path in &settings.plugins {
if let Err(message) =
load_plugin_into_host(&mut host, plugin_path, settings.trust_native_plugin)
{
if json {
output::print_json(&json!({"success": false, "error": message}));
} else {
eprintln!("error: {message}");
}
return 1;
}
}
let function_name = function.unwrap_or("main").to_string();
let entry_module = &project.program.modules[&project.entry];
if entry_module.function(&function_name).is_none() {
@@ -566,6 +582,31 @@ pub fn execute(
}
}
fn load_plugin_into_host(host: &mut StdHost, path: &Path, trusted: bool) -> Result<String, String> {
let manifest_path = if path.is_dir() {
path.join("plugin.yaml")
} else {
path.to_path_buf()
};
let base_dir = manifest_path
.parent()
.map(|parent| parent.to_path_buf())
.unwrap_or_else(|| PathBuf::from("."));
let manifest = marqdo_plugin_abi::PluginManifest::load(&manifest_path)
.map_err(|error| format!("{}: {}", error.code, error.message))?;
manifest
.validate()
.map_err(|error| format!("{}: {}", error.code, error.message))?;
if !trusted {
return Err(format!(
"loading `{}` in-process requires --trust-native-plugin: no isolated worker transport is implemented in this build",
manifest.plugin.name
));
}
host.load_plugin(&manifest, &base_dir, trusted)
.map_err(|error| format!("{}: {}", error.code(), error.message))
}
fn runtime_error_json(error: &RuntimeError, project: &LoadedProject) -> serde_json::Value {
let entry = project.entry_file();
let span = error.span.map(|span| {
@@ -968,7 +1009,10 @@ pub fn add(
}));
} else {
println!("added dependency `{name}` to {}", manifest_path.display());
println!("run `marqdo lock` to pin it in {}", marqdo_package::LOCK_FILE);
println!(
"run `marqdo lock` to pin it in {}",
marqdo_package::LOCK_FILE
);
}
0
}
+8
View File
@@ -86,6 +86,12 @@ struct SandboxArgs {
/// Wall-clock timeout in seconds.
#[arg(long)]
timeout: Option<u64>,
/// Explicitly trusted plugin manifest/directory to load (repeatable).
#[arg(long = "plugin", value_name = "PATH")]
plugin: Vec<PathBuf>,
/// Explicitly trust in-process native plugin loading (unsafe by nature).
#[arg(long = "trust-native-plugin")]
trust_native_plugin: bool,
}
impl SandboxArgs {
@@ -100,6 +106,8 @@ impl SandboxArgs {
stack: self.stack,
max_output: self.max_output,
timeout: self.timeout,
plugins: self.plugin.clone(),
trust_native_plugin: self.trust_native_plugin,
}
}
}
+7 -6
View File
@@ -145,12 +145,13 @@ impl<'a> Analyzer<'a> {
match callee.as_ref() {
Expr::Ident(_) => {}
Expr::Member { base, name, .. } => {
let is_builtin_namespace = matches!(
base.as_ref(),
Expr::Ident(ident)
if marqdo_ir::builtins::find(&format!("{}.{name}", ident.name)).is_some()
);
if !is_builtin_namespace {
// `ns.f(...)` bases are namespaces: builtin namespaces,
// imported module aliases or explicitly trusted plugin
// namespaces bound at run time. They are never inferred
// parameters. Non-identifier bases are values and are
// still read normally.
let _ = name;
if !matches!(base.as_ref(), Expr::Ident(_)) {
self.read_expr(base, state);
}
}
+1
View File
@@ -9,6 +9,7 @@ repository.workspace = true
authors.workspace = true
[dependencies]
marqdo-plugin-abi = { workspace = true }
glob = { workspace = true }
marqdo-span = { workspace = true }
marqdo-value = { workspace = true }
+131 -5
View File
@@ -6,6 +6,7 @@
use std::time::{Duration, Instant};
use marqdo_plugin_abi::{ErrorKind as PluginErrorKind, LoadedPlugin, PluginError, PluginManifest};
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError, Value};
@@ -108,6 +109,16 @@ pub struct StdHost {
pub foreign_output_limit: usize,
output: Vec<u8>,
trace_id: u64,
/// Explicitly trusted, in-process native plugins keyed by namespace.
plugins: Vec<PluginSlot>,
}
struct PluginSlot {
/// Call namespace (prefix of the export name, e.g. `solver`).
namespace: String,
/// Package name used for capability grants.
package: String,
plugin: LoadedPlugin,
}
impl StdHost {
@@ -132,9 +143,68 @@ impl StdHost {
foreign_output_limit: 1024 * 1024,
output: Vec::new(),
trace_id,
plugins: Vec::new(),
}
}
/// Load a native plugin in-process after an explicit trust decision.
///
/// In-process native code shares the host address space and is **not**
/// sandboxed; this build has no isolated worker transport. The caller must
/// pass `trusted = true` and grant the plugin capability. Returns the call
/// namespace derived from the plugin's export names.
pub fn load_plugin(
&mut self,
manifest: &PluginManifest,
base_dir: &std::path::Path,
trusted: bool,
) -> Result<String, RuntimeError> {
if !trusted {
let mut error = RuntimeError::new(
ErrorCategory::PermissionDenied,
None,
"loading an in-process native plugin requires explicit trust",
);
error.effect_trace.push(
"hint: no isolated plugin worker transport is implemented in this build; in-process native code shares the host address space"
.to_string(),
);
return Err(error);
}
self.capabilities
.check_plugin(&manifest.plugin.name, None)?;
manifest.validate().map_err(map_plugin_error)?;
let namespace = manifest
.plugin
.exports
.first()
.and_then(|export| {
export
.name
.split_once('.')
.map(|(namespace, _)| namespace.to_string())
})
.ok_or_else(|| {
RuntimeError::new(
ErrorCategory::PluginAbi,
None,
"plugin manifest declares no namespaced exports",
)
})?;
let loaded = LoadedPlugin::open_with(
manifest,
base_dir,
marqdo_plugin_abi::LoadOptions::default(),
)
.map_err(map_plugin_error)?;
self.plugins.push(PluginSlot {
namespace: namespace.clone(),
package: manifest.plugin.name.clone(),
plugin: loaded,
});
Ok(namespace)
}
/// Enable effect tracing.
pub fn with_trace(mut self) -> Self {
self.trace = EffectTrace::enabled();
@@ -175,11 +245,7 @@ impl StdHost {
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",
)),
HostOp::PluginInvoke => self.op_plugin_invoke(args, ctx),
}
}
@@ -209,6 +275,55 @@ impl StdHost {
Ok(Value::Text(contents))
}
fn op_plugin_invoke(
&mut self,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
if args.len() != 3 {
return Err(arity(ctx.span, "plugin.invoke", 3, args.len()));
}
let Value::Text(namespace) = &args[0] else {
return Err(RuntimeError::type_error(
ctx.span,
"plugin namespace must be Text",
));
};
let Value::Text(export) = &args[1] else {
return Err(RuntimeError::type_error(
ctx.span,
"plugin export must be Text",
));
};
let Value::Map(named_args) = &args[2] else {
return Err(RuntimeError::type_error(
ctx.span,
"plugin call arguments must be named",
));
};
let slot = self
.plugins
.iter_mut()
.find(|slot| &slot.namespace == namespace)
.ok_or_else(|| {
RuntimeError::new(
ErrorCategory::UnknownSymbol,
ctx.span,
format!("no plugin namespace `{namespace}` is loaded"),
)
})?;
self.capabilities
.check_plugin(&slot.package.clone(), ctx.span)?;
let function = format!("{namespace}.{export}");
let mut request = marqdo_plugin_abi::WireRequest::new(function.clone());
for (name, value) in named_args {
request = request.with_arg(name.clone(), value);
}
let response = slot.plugin.invoke(&request).map_err(map_plugin_error)?;
let value = response.typed_value().map_err(map_plugin_error)?;
Ok(value.unwrap_or(Value::Unit))
}
fn op_fs_write(
&mut self,
args: Vec<Value>,
@@ -266,6 +381,17 @@ impl Host for StdHost {
}
}
fn map_plugin_error(error: PluginError) -> RuntimeError {
let category = match error.kind {
PluginErrorKind::Abi => ErrorCategory::PluginAbi,
PluginErrorKind::Capability => ErrorCategory::PermissionDenied,
PluginErrorKind::Wire => ErrorCategory::Type,
PluginErrorKind::Unsupported => ErrorCategory::KernelUnavailable,
_ => ErrorCategory::PluginFailure,
};
RuntimeError::new(category, None, format!("{}: {}", error.code, error.message))
}
/// Type-checked argument helper.
pub fn expect_text(
args: &[Value],
+28
View File
@@ -500,6 +500,34 @@ impl<'a> Interpreter<'a> {
let args = self.eval_args(args, frame)?;
return self.call_builtin(builtin, args, Some(span), frame);
}
if !frame.locals.contains_key(&alias.name) {
// Not a local value or imported module: try an explicitly
// trusted plugin namespace. Plugin calls take named
// arguments only in this build.
let evaluated = self.eval_args(args, frame)?;
let mut named = std::collections::BTreeMap::new();
for argument in evaluated {
let Some(argument_name) = argument.name else {
return Err(RuntimeError::new(
ErrorCategory::Type,
Some(argument.span),
"plugin calls require named arguments",
));
};
named.insert(argument_name, argument.value);
}
let module = frame.function.module.clone();
return self.host_invoke(
HostOp::PluginInvoke,
vec![
Value::Text(alias.name.clone()),
Value::Text(name.clone()),
Value::Map(named),
],
Some(span),
&module,
);
}
}
let callee_value = self.eval_expr(callee, frame)?;
let args = self.eval_args(args, frame)?;