Files
marqdo-cli/docs/adr/0026-buffered-project-file-write-streams.md
cflmy e26971f489 feat(cli): route print through the bundled stdlib (Compat-B)
- Add Program.print_override and lazy stdlib injection: only programs that
  call 打印/print load std:io and route to io.写值 (ADR-0030).
- Record resource.open/read/write/close as trace effect events so the stdlib
  print path is auditable; HostOp::Print no longer runs on that path.
- Permit only stdio/stdout (existing console) in strict; file/network
  resource opens remain permission.denied.
- Exclude std: modules from the human-readable checked-module count; update
  the Python analysis consumer to accept std: instance ids.
- Add print-routing and strict-console tests, ADR-0030 and evidence.

Gate: fmt, clippy -D warnings, 418 tests passed.
2026-11-20 22:10:59 +08:00

117 lines
5.3 KiB
Markdown

# ADR-0026: Buffered project-file write streams (CM-A06 extension)
Status: **Accepted**
Date: 2026-11-20
Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md`
(CM-A06, CM-A09, CM-A11), ADR-0024, ADR-0025
Specs: `spec/evaluation.md`, `spec/security.md`
Evidence: `docs/evidence/2026-11-20-resource-file-write-p3.md`
## Context
ADR-0025 froze the first resource ABI slice with `stdio/stdout` write and
project-file **read**. A standard library cannot implement file copy, file
format writers or "write then verify" without a write-capable file resource.
The RFC's P3 target is explicit `open/read/write/close` for project files in
`project` mode; strict must remain fail-closed.
Direct per-write file I/O would expose partial writes and OS error timing to
every caller and would make it easy to leave a half-written project file. This
ADR adds the smallest honest write path: an in-memory buffer per file writer,
flushed through the existing project path policy on `close`.
## Decision
### 1. Provider shape
Add a third stream shape to the host resource table (ADR-0025):
```text
resource.open("file", "<project-relative path>", ["write"]) -> Resource
```
* `project` mode only, with an `fs_write` glob grant matching the normalised
relative path.
* `pure` still refuses file resources by mode check; `strict` still refuses
file resources (only the existing stdio console channel is permitted,
ADR-0030).
* Absolute paths, `..`, symlink escapes and non-regular targets are rejected by
`ProjectFs` exactly like the existing `fs.write`.
* A writer owns an in-memory byte buffer. `resource.write` appends bytes and
returns `{ok:true, value:{count}}`; it does **not** touch the filesystem.
* `resource.close` flushes the buffer through `ProjectFs::write_bytes` and then
marks the handle closed. If the flush fails, the handle stays open with its
buffer intact and the error is reported; the caller may retry or close again.
* If the program exits without closing, no file is written. This is a
deliberate "no flush on drop" rule: a crash or a missing `close` must not
silently publish a partial file.
* `resource.write` is rejected on a file reader; `resource.read` is rejected on
a file writer; stdout remains write-only. Wrong-direction use is
`resource.unsupported`.
* A writer buffer is capped at the existing 8 MiB project read/write ceiling
(`MAX_READ_BYTES`). Exceeding it is `resource.exhausted` and the append is
atomic: the buffer and file are unchanged.
### 2. Rights and modes
| Kind | Descriptor | Rights | Mode | Grant |
|---|---|---|---|---|
| `file` | project-relative path | `["read"]` | project | `fs_read` glob |
| `file` | project-relative path | `["write"]` | project | `fs_write` glob |
| `stdio` | `stdout` | `["write"]` | pure/project | `console` |
Mixed rights (`["read","write"]`) and other kinds/rights are
`resource.unsupported` in this slice. There is no truncate/append/seek flag:
every writer starts empty and replaces the file on flush.
### 3. Errors, budgets and tracing
* `resource.closed` for read/write/close on a closed handle (recoverable).
* `runtime.resource` for forged/cross-run/stale handles (fatal).
* `resource.exhausted` for a buffer over the byte ceiling.
* `permission.denied` for a missing mode/grant or a path policy failure.
* `resource.unsupported` for a direction/rights combination not implemented.
* `resource.write` on a file writer does not charge the program output budget;
the buffer is bounded by the file ceiling. `resource.close` performs one
`ProjectFs::write_bytes` call and records `resource.close` with the byte
count, never the contents.
* No partial file is visible on a failed close because the write is a single
`std::fs::write` to the validated project path (the same atomicity level as
the existing `fs.write`; no temp-file rename is claimed).
### 4. Explicit non-goals
* No append/truncate/seek flags, no random access, no directory or metadata
operations.
* No file write in pure or strict mode.
* No network/process/device/clock/random resources.
* No generic provider registry (CM-A09), no async/nonblocking I/O.
* No claim that `ProjectFs::write_bytes` is crash-atomic; it is a single
validated write, not a transactional replace.
* No CM-A07 `print` migration in this ADR.
## Compatibility
* Additive to ADR-0025: existing `file` read and `stdio` write behavior is
unchanged; `file` write was previously `resource.unsupported`.
* No new `Value` variant, `HostOp`, Markdown node or wire shape.
* Error categories/codes are unchanged; the new `resource.exhausted` diagnostic
reuses the existing stable `resource.exhausted` code family.
## Consequences
* `.mq.md` can now implement file copy and bounded format writers by opening a
read stream and a write stream, transferring bytes through `Memory`, and
closing both. This is C09's core shape without a `copy_file` Rust builtin.
* Buffered close gives deterministic "all or nothing within one write call"
behavior and keeps OS write errors at a point where the caller still has a
Result path.
* Large files require chunked writes; the 8 MiB ceiling is the first-slice
limit, not a permanent design.
## Verification
`docs/evidence/2026-11-20-resource-file-write-p3.md` records host unit tests
(grants, pure/strict refusal, traversal, buffer ceiling, retry-after-failure),
CLI tests for write-then-read and missing grants, and the full workspace gate.