From fbe36bcc431ccadcb95b5aba74ecd7c39113f9ae Mon Sep 17 00:00:00 2001 From: Marqdo Agent Date: Sat, 21 Nov 2026 08:20:31 +0800 Subject: [PATCH] feat(resource): add grant-checked fs resource operations --- crates/cli/tests/stdlib_product.rs | 40 ++- crates/marqdo-host/src/fs.rs | 297 +++++++++++++++++- crates/marqdo-host/src/host.rs | 104 ++++++ crates/marqdo-host/tests/resource_streams.rs | 103 ++++++ crates/marqdo-ir/src/builtins.rs | 8 + crates/marqdo-runtime/src/builtins_impl.rs | 11 + crates/marqdo-runtime/src/interpreter.rs | 17 + docs/STATUS.md | 21 +- docs/adr/0041-resource-operation-fs.md | 61 ++++ docs/architecture/CURRENT.md | 8 +- docs/architecture/README.md | 1 + .../evidence/2026-11-21-resource-operation.md | 47 +++ spec/evaluation.md | 33 ++ stdlib/fs/file.mq.md | 68 ++++ stdlib/stdlib.json | 2 +- stdlib/tests/fs.mq.md | 22 +- 16 files changed, 812 insertions(+), 31 deletions(-) create mode 100644 docs/adr/0041-resource-operation-fs.md create mode 100644 docs/evidence/2026-11-21-resource-operation.md diff --git a/crates/cli/tests/stdlib_product.rs b/crates/cli/tests/stdlib_product.rs index 8b8e927..1283bd3 100644 --- a/crates/cli/tests/stdlib_product.rs +++ b/crates/cli/tests/stdlib_product.rs @@ -62,7 +62,16 @@ fn product_tests() -> Vec { _ => ("", ""), }; let args = if name == "fs.mq.md" { - &["--allow-read", "out/*", "--allow-write", "out/*"][..] + &[ + "--allow-read", + "out", + "--allow-read", + "out/**", + "--allow-write", + "out", + "--allow-write", + "out/**", + ][..] } else { &[][..] }; @@ -148,7 +157,7 @@ fn the_whole_bundled_library_runs_through_std_imports() { } #[test] -fn fs_test_reads_writes_and_copies_project_files() { +fn fs_test_exercises_the_file_operation_surface() { let _guard = lock_fs("fs.mq.md"); let report = run_product_test( product_tests() @@ -157,18 +166,21 @@ fn fs_test_reads_writes_and_copies_project_files() { .expect("fs test"), ); let items = report["value"]["items"].as_array().expect("list"); - assert_eq!(items[0]["decimal"], "7"); - assert_eq!(items[1]["value"], "你好\n"); - assert_eq!(items[2]["decimal"], "7"); - assert_eq!(items[3]["value"], "你好\n"); - let out = stdlib_dir().join("tests/out"); - assert_eq!( - std::fs::read(out.join("fs-a.txt")).unwrap(), - "你好\n".as_bytes() - ); - assert_eq!( - std::fs::read(out.join("fs-b.txt")).unwrap(), - "你好\n".as_bytes() + assert_eq!(items[0]["value"], true); + assert_eq!(items[1]["decimal"], "7"); + assert_eq!(items[2]["value"], true); + assert_eq!(items[3]["value"], "file"); + assert_eq!(items[4]["decimal"], "7"); + assert_eq!(items[5]["items"][0]["value"], "fs-a.txt"); + assert_eq!(items[6]["value"], true); + assert_eq!(items[7]["value"], true); + assert_eq!(items[8]["value"], true); + assert_eq!(items[9]["value"], "你好\n"); + assert_eq!(items[10]["value"], true); + assert_eq!(items[11]["value"], true); + assert!( + !stdlib_dir().join("tests/out").exists(), + "the fs test did not remove its directory" ); } diff --git a/crates/marqdo-host/src/fs.rs b/crates/marqdo-host/src/fs.rs index 10c3015..9703e16 100644 --- a/crates/marqdo-host/src/fs.rs +++ b/crates/marqdo-host/src/fs.rs @@ -7,7 +7,8 @@ use std::path::{Component, Path, PathBuf}; use marqdo_span::Span; -use marqdo_value::{ErrorCategory, RuntimeError}; +use marqdo_value::{ErrorCategory, RuntimeError, Value}; +use std::collections::BTreeMap; /// Maximum size for a single file read. pub const MAX_READ_BYTES: u64 = 8 * 1024 * 1024; @@ -143,6 +144,266 @@ impl ProjectFs { }) } + /// Execute a path operation on the project filesystem. + /// + /// This is the host side of `resource.request`; it validates every path + /// against the project root, then returns the recoverable `Result` map. + /// Capability checks are performed by the host before this method is + /// called. Unknown operations are a programming error and stay fatal. + pub fn request( + &self, + operation: &str, + args: &[String], + span: Option, + ) -> Result { + match operation { + "exists" => { + let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?; + if !absolute.exists() { + return Ok(fs_ok(Value::Bool(false))); + } + self.ensure_inside(&absolute, &relative, span)?; + Ok(fs_ok(Value::Bool(true))) + } + "metadata" => { + let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?; + if !absolute.exists() { + return Ok(fs_error( + "fs.not_found", + &format!("`{relative}` does not exist"), + )); + } + let absolute = self.ensure_inside(&absolute, &relative, span)?; + let metadata = std::fs::metadata(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot stat `{relative}`: {error}"), + ) + })?; + let kind = if metadata.is_file() { + "file" + } else if metadata.is_dir() { + "directory" + } else { + "other" + }; + let size = if metadata.is_file() { + metadata.len() + } else { + 0 + }; + let mut value = BTreeMap::new(); + value.insert("kind".to_string(), Value::text(kind)); + value.insert( + "size".to_string(), + Value::int(size.min(i64::MAX as u64) as i64), + ); + Ok(fs_ok(Value::Map(value))) + } + "list" => { + let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?; + if !absolute.exists() { + return Ok(fs_error( + "fs.not_found", + &format!("`{relative}` does not exist"), + )); + } + let absolute = self.ensure_inside(&absolute, &relative, span)?; + let metadata = std::fs::metadata(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot stat `{relative}`: {error}"), + ) + })?; + if !metadata.is_dir() { + return Ok(fs_error( + "fs.not_directory", + &format!("`{relative}` is not a directory"), + )); + } + let mut names = Vec::new(); + let entries = std::fs::read_dir(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot list `{relative}`: {error}"), + ) + })?; + for entry in entries { + let entry = entry.map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot list `{relative}`: {error}"), + ) + })?; + names.push(entry.file_name().to_string_lossy().to_string()); + } + names.sort(); + Ok(fs_ok(Value::List( + names.into_iter().map(Value::text).collect(), + ))) + } + "mkdir" => { + let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?; + self.ensure_parent_inside(&absolute, &relative, span)?; + if absolute.exists() { + return Ok(fs_error( + "fs.exists", + &format!("`{relative}` already exists"), + )); + } + match std::fs::create_dir(&absolute) { + Ok(()) => Ok(fs_ok(Value::None)), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(fs_error( + "fs.not_found", + &format!("parent directory of `{relative}` does not exist"), + )), + Err(error) => Err(RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot create directory `{relative}`: {error}"), + )), + } + } + "remove" => { + let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?; + if !absolute.exists() { + return Ok(fs_error( + "fs.not_found", + &format!("`{relative}` does not exist"), + )); + } + let absolute = self.ensure_inside(&absolute, &relative, span)?; + let metadata = std::fs::metadata(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot stat `{relative}`: {error}"), + ) + })?; + if metadata.is_dir() { + let mut entries = std::fs::read_dir(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot list `{relative}`: {error}"), + ) + })?; + if entries.next().is_some() { + return Ok(fs_error( + "fs.not_empty", + &format!("`{relative}` is not empty"), + )); + } + std::fs::remove_dir(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot remove `{relative}`: {error}"), + ) + })?; + } else { + std::fs::remove_file(&absolute).map_err(|error| { + let category = if error.kind() == std::io::ErrorKind::PermissionDenied { + ErrorCategory::PermissionDenied + } else { + ErrorCategory::HostError + }; + RuntimeError::new( + category, + span, + format!("cannot remove `{relative}`: {error}"), + ) + })?; + } + Ok(fs_ok(Value::None)) + } + "rename" => { + if args.len() != 2 { + return Err(fs_arity(operation, 2, args.len(), span)); + } + let (from_absolute, from) = self.resolve(&args[0], span)?; + let (to_absolute, to) = self.resolve(&args[1], span)?; + if !from_absolute.exists() { + return Ok(fs_error( + "fs.not_found", + &format!("`{from}` does not exist"), + )); + } + let from_absolute = self.ensure_inside(&from_absolute, &from, span)?; + self.ensure_parent_inside(&to_absolute, &to, span)?; + if to_absolute.exists() { + return Ok(fs_error("fs.exists", &format!("`{to}` already exists"))); + } + match std::fs::rename(&from_absolute, &to_absolute) { + Ok(()) => Ok(fs_ok(Value::None)), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(fs_error( + "fs.not_found", + &format!("parent directory of `{to}` does not exist"), + )), + Err(error) => Err(RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot rename `{from}` to `{to}`: {error}"), + )), + } + } + other => Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + span, + format!("unsupported filesystem operation `{other}`"), + )), + } + } + + fn ensure_inside( + &self, + absolute: &Path, + relative: &str, + span: Option, + ) -> Result { + 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")); + } + Ok(canonical) + } + + fn ensure_parent_inside( + &self, + absolute: &Path, + relative: &str, + span: Option, + ) -> Result<(), RuntimeError> { + 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")); + } + return Ok(()); + } + ancestor = current.parent(); + } + Ok(()) + } + /// Write a file inside the project root, creating parent directories. pub fn write( &self, @@ -204,6 +465,40 @@ fn invalid_path(span: Option, message: impl Into) -> RuntimeError RuntimeError::new(ErrorCategory::PermissionDenied, span, message) } +fn one_arg<'a>( + operation: &str, + args: &'a [String], + span: Option, +) -> Result<&'a str, RuntimeError> { + if args.len() != 1 { + return Err(fs_arity(operation, 1, args.len(), span)); + } + Ok(&args[0]) +} + +fn fs_arity(operation: &str, expected: usize, actual: usize, span: Option) -> RuntimeError { + RuntimeError::new( + ErrorCategory::Arity, + span, + format!("filesystem operation `{operation}` expects {expected} argument(s), got {actual}"), + ) +} + +fn fs_ok(value: Value) -> Value { + let mut map = BTreeMap::new(); + map.insert("ok".to_string(), Value::Bool(true)); + map.insert("value".to_string(), value); + Value::Map(map) +} + +fn fs_error(code: &str, message: &str) -> Value { + let mut map = BTreeMap::new(); + map.insert("ok".to_string(), Value::Bool(false)); + map.insert("code".to_string(), Value::text(code)); + map.insert("message".to_string(), Value::text(message)); + Value::Map(map) +} + #[cfg(test)] mod tests { use super::*; diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index 012b7fe..4422043 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -139,6 +139,23 @@ pub trait Host { )) } + /// Execute one non-streaming resource operation (ADR-0041). + /// + /// Default: unavailable. The standard host implements the `fs.*` group; + /// every call is capability-checked and project-mode only. + fn resource_request( + &mut self, + _operation: &str, + _args: Vec, + ctx: &ExecutionContext, + ) -> Result { + Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + ctx.span, + "this host does not provide resource operations", + )) + } + /// Consume evaluation fuel. fn consume_fuel(&mut self, amount: u64, span: Option) -> Result<(), RuntimeError>; @@ -1089,6 +1106,93 @@ impl Host for StdHost { Ok(()) } + fn resource_request( + &mut self, + operation: &str, + args: Vec, + ctx: &ExecutionContext, + ) -> Result { + let started = Instant::now(); + if self.mode != SandboxMode::Project { + return Err(RuntimeError::new( + ErrorCategory::PermissionDenied, + ctx.span, + "resource operations are available only in project mode", + )); + } + if args.iter().any(Value::contains_memory) || args.iter().any(Value::contains_resource) { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + ctx.span, + "resource operations accept only Text path arguments", + )); + } + let Some(name) = operation.strip_prefix("fs.") else { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + ctx.span, + format!("unsupported resource operation `{operation}`"), + )); + }; + let expected = match name { + "exists" | "metadata" | "list" | "mkdir" | "remove" => 1, + "rename" => 2, + other => { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + ctx.span, + format!("unsupported filesystem operation `{other}`"), + )) + } + }; + if args.len() != expected { + return Err(RuntimeError::new( + ErrorCategory::Arity, + ctx.span, + format!( + "resource operation `{operation}` expects {expected} argument(s), got {}", + args.len() + ), + )); + } + let mut paths = Vec::with_capacity(args.len()); + for value in args { + let value_type = value.type_name(); + let Value::Text(path) = value else { + return Err(RuntimeError::type_error( + ctx.span, + format!( + "resource operation `{operation}` expects Text paths, got {value_type}" + ), + )); + }; + paths.push(path); + } + match name { + "exists" | "metadata" | "list" => { + self.capabilities.check_read(&paths[0], ctx.span)?; + } + "mkdir" | "remove" => { + self.capabilities.check_write(&paths[0], ctx.span)?; + } + "rename" => { + self.capabilities.check_write(&paths[0], ctx.span)?; + self.capabilities.check_write(&paths[1], ctx.span)?; + } + _ => unreachable!(), + } + let result = self.fs.request(name, &paths, ctx.span)?; + self.record_semantic( + "resource.request", + None, + Some(&ctx.module_id), + ctx.span, + Some(&format!("op=fs.{name}")), + ); + self.record_resource_effect("resource.request", ctx, started, &format!("fs.{name}")); + Ok(result) + } + fn consume_fuel(&mut self, amount: u64, span: Option) -> Result<(), RuntimeError> { self.budget.consume_fuel(amount, span) } diff --git a/crates/marqdo-host/tests/resource_streams.rs b/crates/marqdo-host/tests/resource_streams.rs index 5cf89d3..78803ff 100644 --- a/crates/marqdo-host/tests/resource_streams.rs +++ b/crates/marqdo-host/tests/resource_streams.rs @@ -511,3 +511,106 @@ fn tcp_requires_network_grant_and_rejects_dns_names() { assert_eq!(error.category, ErrorCategory::PermissionDenied); } } + +fn field<'a>(value: &'a Value, name: &str) -> &'a Value { + match value { + Value::Map(map) => map.get(name).unwrap_or_else(|| panic!("missing `{name}`")), + other => panic!("expected a Map, got {other:?}"), + } +} + +#[test] +fn resource_requests_are_project_only_and_grant_checked() { + let dir = tempfile::tempdir().unwrap(); + let ctx = context(); + let mut pure = StdHost::new(SandboxMode::Pure, Capabilities::pure(), dir.path()); + let error = pure + .resource_request("fs.exists", vec![Value::text("out")], &ctx) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); + + let mut project = StdHost::new(SandboxMode::Project, Capabilities::project(), dir.path()); + let error = project + .resource_request("fs.mkdir", vec![Value::text("out")], &ctx) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); +} + +#[test] +fn fs_requests_create_list_rename_and_remove() { + let dir = tempfile::tempdir().unwrap(); + let capabilities = Capabilities::project() + .allow_read("out") + .allow_read("out/**") + .allow_write("out") + .allow_write("out/**"); + let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path()); + let ctx = context(); + + let missing = host + .resource_request("fs.exists", vec![Value::text("out")], &ctx) + .unwrap(); + assert_eq!(field(&missing, "value"), &Value::Bool(false)); + + let created = host + .resource_request("fs.mkdir", vec![Value::text("out")], &ctx) + .unwrap(); + assert_eq!(field(&created, "ok"), &Value::Bool(true)); + + std::fs::write(dir.path().join("out/a.txt"), b"hello").unwrap(); + let metadata = host + .resource_request("fs.metadata", vec![Value::text("out/a.txt")], &ctx) + .unwrap(); + assert_eq!( + field(&metadata, "value"), + &Value::Map({ + let mut map = std::collections::BTreeMap::new(); + map.insert("kind".to_string(), Value::text("file")); + map.insert("size".to_string(), Value::int(5)); + map + }) + ); + + let listed = host + .resource_request("fs.list", vec![Value::text("out")], &ctx) + .unwrap(); + assert_eq!( + field(&listed, "value"), + &Value::List(vec![Value::text("a.txt")]) + ); + + let renamed = host + .resource_request( + "fs.rename", + vec![Value::text("out/a.txt"), Value::text("out/b.txt")], + &ctx, + ) + .unwrap(); + assert_eq!(field(&renamed, "ok"), &Value::Bool(true)); + assert!(!dir.path().join("out/a.txt").exists()); + assert!(dir.path().join("out/b.txt").exists()); + + let removed = host + .resource_request("fs.remove", vec![Value::text("out/b.txt")], &ctx) + .unwrap(); + assert_eq!(field(&removed, "ok"), &Value::Bool(true)); + let removed_dir = host + .resource_request("fs.remove", vec![Value::text("out")], &ctx) + .unwrap(); + assert_eq!(field(&removed_dir, "ok"), &Value::Bool(true)); + assert!(!dir.path().join("out").exists()); +} + +#[test] +fn fs_requests_reject_traversal_before_touching_the_filesystem() { + let dir = tempfile::tempdir().unwrap(); + let capabilities = Capabilities::project() + .allow_write("../**") + .allow_read("../**"); + let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path()); + let ctx = context(); + let error = host + .resource_request("fs.mkdir", vec![Value::text("../escape")], &ctx) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); +} diff --git a/crates/marqdo-ir/src/builtins.rs b/crates/marqdo-ir/src/builtins.rs index a864d66..b5b2cb9 100644 --- a/crates/marqdo-ir/src/builtins.rs +++ b/crates/marqdo-ir/src/builtins.rs @@ -298,6 +298,13 @@ const RESOURCE_CLOSE: Builtin = Builtin { named_only: false, effectful: true, }; +const RESOURCE_REQUEST: Builtin = Builtin { + name: "resource.request", + aliases: &[], + params: &[req("operation"), req("arguments")], + named_only: false, + effectful: true, +}; const TABLE_CELL: Builtin = Builtin { name: "table.cell", aliases: &[], @@ -345,6 +352,7 @@ pub const BUILTINS: &[Builtin] = &[ RESOURCE_READ, RESOURCE_WRITE, RESOURCE_CLOSE, + RESOURCE_REQUEST, ]; /// Find a builtin by canonical name or alias. diff --git a/crates/marqdo-runtime/src/builtins_impl.rs b/crates/marqdo-runtime/src/builtins_impl.rs index ad0d70f..5d44298 100644 --- a/crates/marqdo-runtime/src/builtins_impl.rs +++ b/crates/marqdo-runtime/src/builtins_impl.rs @@ -478,6 +478,17 @@ pub(crate) fn dispatch( Err(error) => resource_recoverable(error), } } + "resource.request" => { + let operation = expect_text_value(take(&bound, "operation", builtin, span)?, span)?; + let value_type = bound["arguments"].type_name(); + let Value::List(arguments) = take(&bound, "arguments", builtin, span)? else { + return Err(RuntimeError::type_error( + span, + format!("resource.request arguments must be a List, got {value_type}"), + )); + }; + interpreter.resource_request(&operation, arguments, &module, span) + } other => Err(RuntimeError::new( ErrorCategory::KernelUnavailable, span, diff --git a/crates/marqdo-runtime/src/interpreter.rs b/crates/marqdo-runtime/src/interpreter.rs index 8fb0a91..32ced26 100644 --- a/crates/marqdo-runtime/src/interpreter.rs +++ b/crates/marqdo-runtime/src/interpreter.rs @@ -903,6 +903,23 @@ impl<'a> Interpreter<'a> { }) } + /// Execute one non-streaming resource operation. + pub(crate) fn resource_request( + &mut self, + operation: &str, + args: Vec, + module: &ModuleId, + span: Option, + ) -> Result { + let context = ExecutionContext::new(module.to_string(), span); + self.host + .resource_request(operation, args, &context) + .map_err(|mut error| { + error.mark_callsite(); + error + }) + } + /// Close a resource stream. pub(crate) fn resource_close( &mut self, diff --git a/docs/STATUS.md b/docs/STATUS.md index 2f63b18..de31705 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -58,7 +58,7 @@ byte-identical). cargo fmt --all -- --check PASS cargo clippy --workspace --all-targets -- -D warnings PASS cargo test --workspace --locked PASS - 464 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests + 467 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests ``` The documentation and test migration is local work; re-run this block after it @@ -199,7 +199,9 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL provides select/filter/sort/append/set/join/group/`转GFM` over the logical `Value::Table`; inputs are never mutated; GFM AST laziness and physical T0 storage are unchanged. `std:fs/file` provides bounded `读文本`/`写文本`/`复制文件` - over the existing `resource.*` ABI; metadata/directory operations remain open. + over the existing `resource.*` ABI plus `存在`/`元数据`/`列出目录`/`创建目录`/ + `删除`/`重命名` over `resource.request` (ADR-0041). Append/seek/watch and a + recursive walk remain open. - Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships `format`/`text`/`io`/`fs`; explicit `std:` imports resolve only inside the bundle; a SHA-256 digest over `*.mq.md` is verified before loading; Analysis records @@ -217,9 +219,11 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL stderr are separate capability/output-budget checked buffers; project-file read/write is path/grant checked; file writes buffer until `close` and never flush on drop; a `.mq.md` chunked copy loop reproduces a file without a - Rust `copy_file`; strict permits only the stdio stdout console channel and - refuses stdin/stderr/file/TCP/provider resources (CM-A11 lane PASS). Semantic - fixture 66 and CLI/host tests. + Rust `copy_file`; `resource.request` adds non-streaming `fs.exists`/ + `fs.metadata`/`fs.list`/`fs.mkdir`/`fs.remove`/`fs.rename` (project mode, + grant-checked, recoverable fs Result); strict permits only the stdio stdout + console channel and refuses stdin/stderr/file/TCP/provider resources (CM-A11 + lane PASS). Semantic fixture 66 and CLI/host tests. - Test and documentation migration (review RFC-CM P0/P2): `crates/cli/tests/docs_consistency.rs` pins one current overview, the status/index links and SHA-pinned evidence; `crates/cli/tests/architecture_boundaries.rs` @@ -248,9 +252,10 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL 4. `fs.write`, `net.request`, `process`, `clock`, `random` are not executed broker services; unsupported requests must return `capability.unavailable`. 5. Resource streams cover project-file read/write (including `std:fs/file` - read/write/copy), stdout, compatible print, trusted in-process providers and - IP-literal TCP; file metadata/directories, process, device, DNS/TLS/HTTP, UDP - and provider packaging remain open. Strict permits only stdio and refuses the + read/write/copy), non-streaming `resource.request` `fs.*` metadata/directory + operations, stdout, compatible print, trusted in-process providers and + IP-literal TCP; append/seek/watch, process, device, DNS/TLS/HTTP, UDP and + provider packaging remain open. Strict permits only stdio and refuses the rest (CM-A11 lane PASS). 6. uv/npm/venv provisioning is not implemented. Only a pre-provisioned, digest-pinned directory with a regular-file executable is supported. diff --git a/docs/adr/0041-resource-operation-fs.md b/docs/adr/0041-resource-operation-fs.md new file mode 100644 index 0000000..781a767 --- /dev/null +++ b/docs/adr/0041-resource-operation-fs.md @@ -0,0 +1,61 @@ +# ADR-0041: Non-streaming Resource Operation for filesystem metadata and directories + +Status: **Accepted** +Date: 2026-11-21 +Relates to: ADR-0025, ADR-0026, ADR-0040 +Specs: `spec/evaluation.md`, `spec/security.md` +Evidence: `docs/evidence/2026-11-21-fs-file-product.md`, `docs/evidence/2026-11-21-resource-operation.md` + +## Context + +`resource.open/read/write/close` is a byte-stream ABI. It cannot express +operations that do not return a byte stream: `exists`, `metadata`, directory +listing, `mkdir`, `remove` and `rename`. Adding one Rust builtin per operation, +or faking them by reading a directory as a file, would either grow the language +surface without a contract or overstate what a stream can do. + +The audit RFC's P1 items require a separate, explicit capability class for +these non-streaming operations, not a silent `HostOp` for every filesystem +call. + +## Decision + +Add one builtin and one host trait method: + +```text +resource.request(operation: Text, arguments: List) -> Result +Host::resource_request(operation: &str, arguments: Vec, ctx) -> Result +``` + +* The first version registers only the `fs.*` operation group. An unknown + operation is fatal `resource.unsupported`; it is not a recoverable Result. +* Arguments must be `Text` paths. `Memory` and `Resource` handles are rejected + before dispatch, so they still cannot cross the host boundary. +* Every call is project-mode only. `pure` and `strict` return + `permission.denied`; this does not widen strict L1. +* Grants: `fs.exists`/`fs.metadata`/`fs.list` require `fs_read`; `fs.mkdir`/ + `fs.remove` require `fs_write`; `fs.rename` requires `fs_write` on both + paths. Grants are checked before path resolution or any I/O. +* Paths use the same `ProjectFs::resolve` policy: relative, no `..`, no + absolute path, canonical target must stay inside the project root. +* Expected filesystem conditions are recoverable `{ok:false, code, message}`: + `fs.not_found`, `fs.not_directory`, `fs.exists`, `fs.not_empty`. Capability + denial, traversal, unsupported operations and I/O failures stay fatal + `RuntimeError`s. +* `remove` deletes a file or an **empty** directory; it never recurses. + `rename` refuses an existing target with `fs.exists` instead of overwriting. +* `mkdir` is single-level: a missing parent returns `fs.not_found`. +* Every call records one semantic `resource.request` and one effect event + with `op=fs.`. No bytes move through the operation; file content still + uses `resource.read`/`resource.write`. + +## Consequences + +* The language surface grows by exactly one builtin (`resource.request`), not + one per operation. The operation strings are a versioned stdlib ABI, not new + Markdown syntax. +* A future directory walk, seek, stat or process operation can reuse the same + shape without inventing a new `HostOp`; it still needs its own ADR and + capability group. +* `std:fs/file` is a `.mq.md` facade over both ABIs: byte streams for content, + `resource.request` for metadata/directories. No Rust algorithm is added. diff --git a/docs/architecture/CURRENT.md b/docs/architecture/CURRENT.md index 2b8087d..b7d512d 100644 --- a/docs/architecture/CURRENT.md +++ b/docs/architecture/CURRENT.md @@ -18,7 +18,7 @@ platform". | Dimension | Current state | Source | |---|---|---| | Implemented | Rust workspace `0.1.0`: Markdown/frontend/IR, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` | -| Tested locally | `cargo test --workspace --locked`: **464 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 | +| Tested locally | `cargo test --workspace --locked`: **467 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 | | Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` | | Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 | @@ -87,6 +87,7 @@ review RFC, not a new crate per provider. | project file read | `resource.open("file", path, ["read"])`; path/grant checked; bounded | implemented, project mode | `resource_streams`, `stdlib_product` | | project file write | `resource.open("file", path, ["write"])`; buffers until `close`, never flush-on-drop | implemented, project mode | `resource_streams`, `stdlib_product` | | `std:fs/file` | `fs.读文本`, `fs.写文本`, `fs.复制文件` over `resource.open/read/write/close` and `Memory`; bounded at 8 MiB | implemented (read/write/copy) | `stdlib_product` | +| `resource.request` | `resource.request("fs.exists|metadata|list|mkdir|remove|rename", paths)`; project mode, grant-checked, recoverable fs Result | implemented `fs.*`; no seek/append/watch | `resource_streams`, `stdlib_product` | | file metadata / directory / rename / remove / mkdir | not part of the current Resource contract | **not implemented**; needs a separate Resource Operation ADR | — | | TCP | `resource.open("tcp", ip:port, ["read","write"])`; exact IP grant, 5 s timeout | implemented; no DNS/TLS/server socket/UDP | `tcp_endpoint`, `http_over_tcp` | | HTTP/1.1 | `stdlib/net/http.mq.md`: status/header/chunked-byte parse, request build | implemented over an already-authorized TCP stream; not a DNS/TLS client | `stdlib_http`, `http_over_tcp`, `stdlib_product` | @@ -112,8 +113,8 @@ that a phase is complete. |---|---|---| | P0 | Stdlib release is a bundle in this repo; extraction is deferred (ADR-0039) | accepted, keep in repo | | P0 | Documentation drift between `STATUS.md`, the architecture index and the evidence | being fixed by this migration and the docs gate | -| P1 | `std:fs/file` has read/write/copy; metadata, `exists`, `list`, `mkdir`, `remove` and `rename` need a Resource Operation | open | -| P1 | No file stat/list/rename/remove/mkdir/append/seek capability | open; requires a Resource Operation ADR | +| P1 | `std:fs/file` read/write/copy and `resource.request` fs metadata/directory operations are implemented; append/seek/watch/recursive walk remain open | open | +| P1 | No file append/seek/watch/recursive directory walk | open; future Resource Operation extension | | P1 | JSON/CSV/UTF-8 decode remain mainly under `tests/conformance` | open as product stdlib API | | P1 | `crates/cli/src/commands.rs` and `crates/marqdo-host/src/host.rs` still mix multiple responsibilities | open refactor, behavior-preserving | | P2 | HTTP parsing is Unicode-codepoint oriented; a general byte body is not the only path | open; convert before a general network release | @@ -148,5 +149,6 @@ that a phase is complete. - [Implementation status](../STATUS.md) — executed state and blockers. - [Language/frontmatter blueprint](../DEVELOPMENT_BLUEPRINT.md) — design baseline; not current status. - [Stable-release implementation plan](../STABLE_RELEASE_IMPLEMENTATION.md) — next-phase plan; not implemented behavior. +- [ADR-0041: non-streaming resource operations](../adr/0041-resource-operation-fs.md) — accepted `resource.request` `fs.*` contract. - [Compute-machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) and [core/stdlib RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) — design input. - [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) — review input for this migration. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 72b087e..f84003d 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -45,6 +45,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and | CM-A09 C ABI provider worker binding v1 | [0038](../adr/0038-c-abi-provider-worker-binding.md) | Accepted (trusted helper) | | Stdlib extraction deferral | [0039](../adr/0039-stdlib-extraction-intent.md) | Accepted (in-repo for now) | | Stdio stdin/stderr plus stdlib stream/console APIs | [0040](../adr/0040-stdio-stdin-stderr-and-stdlib-streams.md) | Accepted (stdin read, separate stdout/stderr, product stdlib) | +| Non-streaming `resource.request` `fs.*` operations | [0041](../adr/0041-resource-operation-fs.md) | Accepted (project mode, grant-checked, recoverable fs Result) | | Table physical storage (T1/T2/T3), strict stdin/stderr/file/network resources | — | **Not decided**; do not implement by implication | ## Evidence and status diff --git a/docs/evidence/2026-11-21-resource-operation.md b/docs/evidence/2026-11-21-resource-operation.md new file mode 100644 index 0000000..e99217c --- /dev/null +++ b/docs/evidence/2026-11-21-resource-operation.md @@ -0,0 +1,47 @@ +# Evidence: non-streaming Resource Operation (`fs.*`) + +Date: 2026-11-21 (Asia/Shanghai) +Source baseline: `cd90f059b4a91993f89fba5ae63b400dac4bd2c4` +Repository: `marqdo-cli` +Decision record: [ADR-0041](../adr/0041-resource-operation-fs.md) +RFC item: P1 file metadata/directory operations + +## Implemented + +`resource.request(operation, arguments)` adds one builtin and one host trait +method. The first operation group is `fs.*`: + +| Operation | Arguments | Grant | Recoverable failures | +|---|---|---|---| +| `fs.exists` | path | `fs_read` | — | +| `fs.metadata` | path | `fs_read` | `fs.not_found` | +| `fs.list` | directory | `fs_read` | `fs.not_found`, `fs.not_directory` | +| `fs.mkdir` | path | `fs_write` | `fs.exists`, `fs.not_found` | +| `fs.remove` | path | `fs_write` | `fs.not_found`, `fs.not_empty` | +| `fs.rename` | from, to | `fs_write` on both | `fs.not_found`, `fs.exists` | + +`pure`/`strict` return `permission.denied`; traversal, absolute paths, +unknown operations and I/O failures stay fatal. `remove` never recurses and +`rename` never overwrites. No file bytes move through this ABI. + +`stdlib/fs/file.mq.md` now exposes `存在`, `元数据`, `是文件`, `是目录`, +`列出目录`, `创建目录`, `删除` and `重命名` over `resource.request`, still in +`.mq.md`. + +## Commands + +```text +cargo fmt --all -- --check PASS +cargo clippy --workspace --all-targets -- -D warnings PASS +cargo test --workspace 467 passed, 0 failed, 2 ignored +cargo test -p marqdo-host --test resource_streams 20 passed +cargo test -p marqdo-cli --test stdlib_product 6 passed +python3 tools/pack-stdlib.py PASS +``` + +## Not covered + +No append/seek/watch, recursive removal or recursive directory walk. No +process/device/DNS/TLS/UDP operation. Those need a later ADR and capability +group. `fs.exists`/metadata follow symlinks only when the canonical target +stays inside the project root. diff --git a/spec/evaluation.md b/spec/evaluation.md index 7762c5b..2c36db5 100644 --- a/spec/evaluation.md +++ b/spec/evaluation.md @@ -166,6 +166,7 @@ resource.write(handle, memory: Memory, offset: Int, length: Int) -> {ok:true, value:{count:Int}} | {ok:false, code, message} resource.close(handle) -> {ok:true, value:None} | {ok:false, code, message} +resource.request(operation: Text, arguments: List) -> Result ``` * Providers: `stdio/stdin` with `["read"]` and `stdio/stdout`/`stdio/stderr` @@ -192,6 +193,37 @@ resource.close(handle) * `Memory` arguments never cross the host boundary as handles: the interpreter copies bytes for the call. Resource handles never cross the value wire. +### 3.4 Resource operations (ADR-0041) + +`resource.request(operation, arguments)` is the non-streaming control plane for +operations that are not byte streams. This build registers only `fs.*`: + +```text +resource.request("fs.exists", [path]) -> {ok:true, value:Bool} +resource.request("fs.metadata", [path]) -> {ok:true, value:{kind, size}} +resource.request("fs.list", [path]) -> {ok:true, value:List} +resource.request("fs.mkdir", [path]) -> {ok:true, value:None} +resource.request("fs.remove", [path]) -> {ok:true, value:None} +resource.request("fs.rename", [from, to]) -> {ok:true, value:None} +``` + +* Arguments are `Text` paths only. `Memory`/`Resource` values are rejected. +* Project mode only; `pure`/`strict` are `permission.denied`. Grants: + `exists`/`metadata`/`list` need `fs_read`; `mkdir`/`remove` need `fs_write`; + `rename` needs `fs_write` on both paths. Grants are checked before path + resolution or I/O. +* Paths follow the project-file policy: relative, no `..`, no absolute path, + canonical target inside the root. +* `kind` is `"file"`, `"directory"` or `"other"`; `size` is the file byte size + and `0` for non-files. `list` returns names sorted by their text form. +* Expected conditions are recoverable: `fs.not_found`, `fs.not_directory`, + `fs.exists` (`mkdir`/`rename` target exists) and `fs.not_empty` + (`remove` on a non-empty directory). Unknown operations, traversal, + capability denial and I/O failures stay fatal. +* `remove` never recurses; `rename` never overwrites; `mkdir` is single-level. +* The operation never moves file bytes. Content still uses + `resource.open/read/write/close`. + ## 4. Errors All failures are structured. Compile-time problems produce diagnostics @@ -286,6 +318,7 @@ host boundary. Names are stable; adding one requires a spec update. | `resource.read` | `(handle, memory: Memory, offset: Int, max_bytes: Int) -> Result` | bounded chunk read into Memory; `{count,eof}` | | `resource.write` | `(handle, memory: Memory, offset: Int, length: Int) -> Result` | bounded byte write; `{count}` | | `resource.close` | `(handle) -> Result` | releases the host slot | +| `resource.request` | `(operation: Text, arguments: List) -> Result` | non-streaming `fs.*` operations; project-mode and grant-checked (ADR-0041) | | `math.parse/eval/substitute` | see `spec/math.md` | P5; `math.simplify`/`math.differentiate` are declared but return `math.unsupported` in this build | | `foreign.run/call` | see `spec/foreign.md` | P5, capability-gated | | `fs.read/write` | see `spec/security.md` | capability-gated | diff --git a/stdlib/fs/file.mq.md b/stdlib/fs/file.mq.md index 7f7d9e4..1a68d34 100644 --- a/stdlib/fs/file.mq.md +++ b/stdlib/fs/file.mq.md @@ -109,3 +109,71 @@ import: 3. `true` *{ok: true, value: {count: 写入.value.count}}* + +## 存在 + +`(路径)` + +*resource.request("fs.exists", [路径])* + +## 元数据 + +`(路径)` + +*resource.request("fs.metadata", [路径])* + +## 是文件 + +`(路径)` + +**元数据 = resource.request("fs.metadata", [路径])** + +1. `not 元数据.ok` + + *元数据* + +2. `true` + + *{ok: true, value: 元数据.value.kind == "file"}* + +## 是目录 + +`(路径)` + +**元数据 = resource.request("fs.metadata", [路径])** + +1. `not 元数据.ok` + + *元数据* + +2. `true` + + *{ok: true, value: 元数据.value.kind == "directory"}* + +## 列出目录 + +`(路径)` + +*resource.request("fs.list", [路径])* + +## 创建目录 + +`(路径)` + +*resource.request("fs.mkdir", [路径])* + +## 删除 + +`(路径)` + +删除一个文件或空目录。非空目录返回 `fs.not_empty`,不递归删除。 + +*resource.request("fs.remove", [路径])* + +## 重命名 + +`(源, 目标)` + +目标已存在时返回 `fs.exists`,不覆盖。 + +*resource.request("fs.rename", [源, 目标])* diff --git a/stdlib/stdlib.json b/stdlib/stdlib.json index 19bda8f..9a264bb 100644 --- a/stdlib/stdlib.json +++ b/stdlib/stdlib.json @@ -1,5 +1,5 @@ { "name": "marqdo-stdlib", "version": "0.1.0", - "digest": "sha256:5e16dc37ef7fcecf8f6839e4065bf02aa552660c5e872b4c17e1eb71dda9d7e7" + "digest": "sha256:3a1544c355ad4b08d679126b4c51f7bc79d282a1b22c9a2bda805f24cc3d4023" } diff --git a/stdlib/tests/fs.mq.md b/stdlib/tests/fs.mq.md index bed9745..54157f6 100644 --- a/stdlib/tests/fs.mq.md +++ b/stdlib/tests/fs.mq.md @@ -5,12 +5,26 @@ import: ## main +**创建 = fs.创建目录("out")** + **写入 = fs.写文本("out/fs-a.txt", "你好\n")** -**读取 = fs.读文本("out/fs-a.txt")** +**存在 = fs.存在("out/fs-a.txt")** -**复制 = fs.复制文件("out/fs-a.txt", "out/fs-b.txt")** +**元数据 = fs.元数据("out/fs-a.txt")** -**复制读取 = fs.读文本("out/fs-b.txt")** +**列表 = fs.列出目录("out")** -*[写入.value.count, 读取.value, 复制.value.count, 复制读取.value]* +**是文件 = fs.是文件("out/fs-a.txt")** + +**是目录 = fs.是目录("out")** + +**重命名 = fs.重命名("out/fs-a.txt", "out/fs-b.txt")** + +**读取 = fs.读文本("out/fs-b.txt")** + +**删除 = fs.删除("out/fs-b.txt")** + +**删除目录 = fs.删除("out")** + +*[创建.ok, 写入.value.count, 存在.value, 元数据.value.kind, 元数据.value.size, 列表.value, 是文件.value, 是目录.value, 重命名.ok, 读取.value, 删除.ok, 删除目录.ok]*