Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:
- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.
Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
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
projectmode only, with anfs_writeglob grant matching the normalised relative path.purestill refuses file resources by mode check;strictstill refuses everyresource.open(CM-A11 fail-closed).- Absolute paths,
.., symlink escapes and non-regular targets are rejected byProjectFsexactly like the existingfs.write. - A writer owns an in-memory byte buffer.
resource.writeappends bytes and returns{ok:true, value:{count}}; it does not touch the filesystem. resource.closeflushes the buffer throughProjectFs::write_bytesand 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
closemust not silently publish a partial file. resource.writeis rejected on a file reader;resource.readis rejected on a file writer; stdout remains write-only. Wrong-direction use isresource.unsupported.- A writer buffer is capped at the existing 8 MiB project read/write ceiling
(
MAX_READ_BYTES). Exceeding it isresource.exhaustedand 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.closedfor read/write/close on a closed handle (recoverable).runtime.resourcefor forged/cross-run/stale handles (fatal).resource.exhaustedfor a buffer over the byte ceiling.permission.deniedfor a missing mode/grant or a path policy failure.resource.unsupportedfor a direction/rights combination not implemented.resource.writeon a file writer does not charge the program output budget; the buffer is bounded by the file ceiling.resource.closeperforms oneProjectFs::write_bytescall and recordsresource.closewith the byte count, never the contents.- No partial file is visible on a failed close because the write is a single
std::fs::writeto the validated project path (the same atomicity level as the existingfs.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_bytesis crash-atomic; it is a single validated write, not a transactional replace. - No CM-A07
printmigration in this ADR.
Compatibility
- Additive to ADR-0025: existing
fileread andstdiowrite behavior is unchanged;filewrite was previouslyresource.unsupported. - No new
Valuevariant,HostOp, Markdown node or wire shape. - Error categories/codes are unchanged; the new
resource.exhausteddiagnostic reuses the existing stableresource.exhaustedcode family.
Consequences
.mq.mdcan now implement file copy and bounded format writers by opening a read stream and a write stream, transferring bytes throughMemory, and closing both. This is C09's core shape without acopy_fileRust 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.