feat(resource): add grant-checked fs resource operations

This commit is contained in:
Marqdo Agent committed 2026-11-21 08:20:31 +08:00
1 parent cd90f059b4
commit fbe36bcc43
16 files changed
+812 -31

No files matched your search

+26 -14
View File
@@ -62,7 +62,16 @@ fn product_tests() -> Vec<TestFile> {
_ => ("", ""),
};
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"
);
}
+296 -1
View File
@@ -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<Span>,
) -> Result<Value, RuntimeError> {
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<Span>,
) -> Result<PathBuf, RuntimeError> {
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<Span>,
) -> 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<Span>, message: impl Into<String>) -> RuntimeError
RuntimeError::new(ErrorCategory::PermissionDenied, span, message)
}
fn one_arg<'a>(
operation: &str,
args: &'a [String],
span: Option<Span>,
) -> 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<Span>) -> 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::*;
+104
View File
@@ -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<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
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<Span>) -> Result<(), RuntimeError>;
@@ -1089,6 +1106,93 @@ impl Host for StdHost {
Ok(())
}
fn resource_request(
&mut self,
operation: &str,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
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<Span>) -> Result<(), RuntimeError> {
self.budget.consume_fuel(amount, span)
}
@@ -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);
}
+8
View File
@@ -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.
@@ -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,
+17
View File
@@ -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<Value>,
module: &ModuleId,
span: Option<Span>,
) -> Result<Value, RuntimeError> {
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,
+13 -8
View File
@@ -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.
+61
View File
@@ -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<Value>, ctx) -> Result<Value, RuntimeError>
```
* 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.<name>`. 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.
+5 -3
View File
@@ -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.
+1
View File
@@ -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
@@ -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.
+33
View File
@@ -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<Text>}
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 |
+68
View File
@@ -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", [源, 目标])*
+1 -1
View File
@@ -1,5 +1,5 @@
{
"name": "marqdo-stdlib",
"version": "0.1.0",
"digest": "sha256:5e16dc37ef7fcecf8f6839e4065bf02aa552660c5e872b4c17e1eb71dda9d7e7"
"digest": "sha256:3a1544c355ad4b08d679126b4c51f7bc79d282a1b22c9a2bda805f24cc3d4023"
}
+18 -4
View File
@@ -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]*