Files
marqdo-cli/docs/adr/0026-buffered-project-file-write-streams.md
T
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

5.3 KiB

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):

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.