feat(stdlib): add bounded std:fs/file read, write and copy

This commit is contained in:
Marqdo Agent committed 2026-11-21 08:10:10 +08:00
1 parent 8dd3d5eb76
commit cd90f059b4
9 files changed
+248 -11

No files matched your search

+10 -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
463 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
464 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
@@ -198,9 +198,10 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
- Table stdlib algorithms (CM-A08, ADR-0032): `stdlib/data/table.mq.md`
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.
storage are unchanged. `std:fs/file` provides bounded `读文本`/`写文本`/`复制文件`
over the existing `resource.*` ABI; metadata/directory operations remain open.
- Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships
`format`/`text`/`io`; explicit `std:` imports resolve only inside the bundle;
`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
`project.stdlib`; a frozen-binary test asserts the CLI hash is unchanged after
running a `std:io` project and that tampering is rejected. `打印/print` is
@@ -224,7 +225,7 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
status/index links and SHA-pinned evidence; `crates/cli/tests/architecture_boundaries.rs`
pins the workspace graph, `marqdo-runtime -> marqdo-host`, the bundled stdlib
digest and the stdio/file/TCP endpoints; `crates/cli/tests/stdlib_product.rs`
runs every public stdlib module (`console/demo/format/http/io/stream/table/text/utf8`)
runs every public stdlib module (`console/demo/format/fs/http/io/stream/table/text/utf8`)
through `std:` imports over `stdlib/tests/*.mq.md`. `tools/pack-stdlib.py`
now sorts `.mq.md` by the same relative path key as the CLI. Source/test baseline
`0d40de7`; later docs-only commits keep code/test bytes identical. Evidence:
@@ -246,10 +247,11 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
fixture lane, Unix-gated worker tests).
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, stdout, compatible print,
trusted in-process providers and IP-literal TCP; directories, process,
device, DNS/TLS/HTTP, UDP and provider packaging remain open. Strict permits
only stdio and refuses the rest (CM-A11 lane PASS).
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
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.
7. No Windows/macOS RC archive exists from this host. The release-candidate
+3 -2
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`: **463 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 |
| Tested locally | `cargo test --workspace --locked`: **464 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 |
@@ -86,6 +86,7 @@ review RFC, not a new crate per provider.
| stdio stderr | `resource.open("stdio","stderr",["write"])`; separate from stdout and CLI diagnostics | implemented | `resource_streams`, `stdlib_product` |
| 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` |
| 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` |
@@ -111,7 +112,7 @@ 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 | No `std:fs/file` product module; only a bundled first slice and Resource streams | open |
| 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 | 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 |
@@ -0,0 +1,45 @@
# Evidence: `std:fs/file` product module
Date: 2026-11-21 (Asia/Shanghai)
Source baseline: `8dd3d5eb76e1acf6a7a015b69515933fb6bbf8e3`
Repository: `marqdo-cli`
Decision input: architecture audit and refactor RFC, P1 file API
## Implemented
`stdlib/fs/file.mq.md` exports three `.mq.md` functions over the existing
resource ABI:
| Function | Contract |
|---|---|
| `读文本(路径)` | `resource.open("file", path, ["read"])` -> one bounded 8 MiB read -> `utf8.解码` |
| `写文本(路径, 文本)` | UTF-8 encode into `Memory` -> `resource.write` -> `resource.close` flushes |
| `复制文件(源, 目标)` | bounded byte read from source -> bounded byte write to destination |
No Rust builtin, `HostOp` or parser change was added. Path checks, grants,
the 8 MiB read/write ceiling and close-flush behavior remain the host
resource ABI (ADR-0025/0026/0040). Metadata, `exists`, directory listing,
`mkdir`, `remove` and `rename` are **not** implemented; they need a Resource
Operation ADR.
## Tests
`stdlib/tests/fs.mq.md` runs through the real `std:fs/file` import with
`--allow-read out/*` and `--allow-write out/*`; it writes, reads back and
copies a UTF-8 file. `crates/cli/tests/stdlib_product.rs` pins the result
`[7, "你好\n", 7, "你好\n"]` and the bytes on disk. The test output directory
`stdlib/tests/out/` is ignored.
```text
cargo fmt --all -- --check PASS
cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace 464 passed, 0 failed, 2 ignored
cargo test -p marqdo-cli --test stdlib_product 6 passed
python3 tools/pack-stdlib.py PASS
```
## Not covered
A caller can still open a `file` resource directly with the lower-level
builtins (that is the existing public ABI). Binary files up to the 8 MiB
ceiling are byte-exact for copy; text read requires valid UTF-8 by design.