3.0 KiB
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:
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 fatalresource.unsupported; it is not a recoverable Result. - Arguments must be
Textpaths.MemoryandResourcehandles are rejected before dispatch, so they still cannot cross the host boundary. - Every call is project-mode only.
pureandstrictreturnpermission.denied; this does not widen strict L1. - Grants:
fs.exists/fs.metadata/fs.listrequirefs_read;fs.mkdir/fs.removerequirefs_write;fs.renamerequiresfs_writeon both paths. Grants are checked before path resolution or any I/O. - Paths use the same
ProjectFs::resolvepolicy: 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 fatalRuntimeErrors. removedeletes a file or an empty directory; it never recurses.renamerefuses an existing target withfs.existsinstead of overwriting.mkdiris single-level: a missing parent returnsfs.not_found.- Every call records one semantic
resource.requestand one effect event withop=fs.<name>. No bytes move through the operation; file content still usesresource.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/fileis a.mq.mdfacade over both ABIs: byte streams for content,resource.requestfor metadata/directories. No Rust algorithm is added.