- 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.
8.3 KiB
ADR-0025: Minimal Resource/Stream ABI and byte transfer through Memory (RFC-CM CM-A06)
Status: Accepted
Date: 2026-11-20
Relates to: docs/MARQDO_COMPUTE_MACHINE_RFC_0001.md,
docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md (CM-A06, CM-A09,
CM-A11, P3), ADR-0022, ADR-0024
Specs: spec/evaluation.md, spec/security.md, spec/value-wire.md
Evidence: docs/evidence/2026-11-20-resource-stream-p3.md
Context
P1/P2 give .mq.md managed values, addressable Memory, structure primitives,
a recoverable Result convention and a substantial set of in-language
algorithms. Nothing yet lets a standard-library function perform a real byte
transfer to the outside world without a dedicated HostOp per high-level
function.
CM-A06 asks for a stable, authorized, versioned resource boundary: obtain a granted resource, call the operations it promises, release it. CM-A09 says to extend the existing host/ABI rather than build a second plugin system. CM-A11 says strict must stay fail-closed until a provider is actually verified.
This ADR freezes a first, deliberately small slice:
- one opaque host-issued
ResourceHandlevalue; resource.open/read/write/closeas pure language builtins, not newHostOpvariants;- byte transfer through
Memory, never through host pointers; - stdio
stdoutwrite and project-file read only; Resultmaps for EOF/closed/write counts, fatal errors for invalid handle or capability denial.
File write, directories, network, processes, TLS, asynchronous I/O and a generic provider registry remain open.
Decision
1. Opaque handle
Value::ResourceHandle(ResourceHandle) is a host-issued opaque identity with
private (run_id, resource_id, generation) fields and a hidden constructor.
It is not Serialize/Deserialize, is rejected by the wire, is never
synthesized from a number or a JSON value, and renders as Resource in
display/repr without exposing the id.
It is a separate domain from Memory: a handle is not indexable, not
byte-addressable and not a capability token the user can manufacture.
2. First resource kinds
| Kind | Descriptor | Rights | Availability |
|---|---|---|---|
stdio |
stdout |
write |
pure and project when the console grant is present; strict rejects until verified |
file |
project-relative path | read |
project with an fs_read grant |
file streams are opened by reading a bounded regular file (existing
ProjectFs::MAX_READ_BYTES = 8 MiB limit) into host-owned bytes; read
returns successive chunks and eof when the position reaches the end. This is
honest about being a first provider: it does not expose a host file descriptor,
does not support seeking, writing, directories, network, processes, devices or
paths outside the project root.
Any other kind/descriptor/right combination is an explicit
resource.unsupported/permission.denied diagnostic, never a silent fallback.
3. Builtins
resource.open(kind: Text, descriptor: Text, rights: List) -> Resource
resource.read(handle: Resource, memory: Memory, offset: Int, max_bytes: Int)
-> {ok:true, value:{count:Int, eof:Bool}} | {ok:false, code, message}
resource.write(handle: Resource, memory: Memory, offset: Int, length: Int)
-> {ok:true, value:{count:Int}} | {ok:false, code, message}
resource.close(handle: Resource)
-> {ok:true, value:None} | {ok:false, code, message}
resource.openis effectful and capability-checked at execution time.resource.readvalidatesoffsetand the remaining buffer before asking the provider, so a failed range check cannot consume stream data. It caps the request to the remaining region, writes the returned bytes intoMemoryand returns the actual count and EOF flag. EOF is a success witheof:true.resource.writecopies bytes out ofMemoryonly for the duration of the call. A short write is reported as a count; the caller loops. It never stores a host pointer into a region that could later grow.resource.closecloses the host slot. Reading/writing/closing an already closed handle returns{ok:false, code:"resource.closed", ...}(recoverable). A forged, cross-run or stale handle isruntime.resource(fatal).- All four are pure interpreter operations over host trait methods; they add no
HostOpvariant. Invalid capacity/bounds remainsruntime.index; wrong operand types remainruntime.type.
4. Authorization and modes
- Authorization is the intersection of the requested operation, the effective
Capabilitiesgrant and the mode:stdio/stdout/writerequiresconsole(the same grant打印uses);file/.../readrequires anfs_readpattern match and project-root path validation (.., absolute paths and symlink escapes rejected);
pure: stdio stdout is allowed because console is already a pure-mode console grant; file resources are refused by the mode check, even if a caller constructs aCapabilitiesset with a matchingfs_readpattern. Network/process resources do not exist in this slice.project: stdio stdout and explicitly granted project-file reads.strict: only the existing stdio/stdout console channel is permitted (resource.open("stdio","stdout",["write"]), console grant); every file, network, process or device resource open is refused withpermission.denied. This is the existing console capability reached through the resource ABI, not a new OS capability (ADR-0030). Strict L1 is otherwise unchanged.- Manifest capability requests are not grants; only the operator-provided effective set is consulted.
5. Errors, budgets and tracing
New stable categories:
| Code | Meaning |
|---|---|
runtime.resource |
forged/cross-run/stale handle, invalid resource state |
resource.closed |
read/write/close on an already closed handle (recoverable) |
resource.unsupported |
kind/descriptor/rights not implemented in this slice |
resource.write to stdout charges the existing output budget and appends to
the host output buffer exactly like 打印; capability denial is
permission.denied. Trace records resource.open, resource.read,
resource.write and resource.close with kind/count/eof metadata, never raw
file bytes or handles.
6. Wire and boundary
to_wire(Resource)emits{"type":"resource"}only; decoding it is a hard error (same rule asMemory).- The generic
Host::invokeboundary rejects arguments containing a resource handle, so plugins/foreign kernels/file adapters never receive one. - Plugin output cannot mint a handle: the constructor is host-only and the value is not decodable from plugin wire.
7. Non-goals
- No
printmigration in this ADR; that is CM-A07 and a later increment. - File write is added by ADR-0026, not this decision; this ADR remains read-only for files.
- No file write, directory listing, rename, metadata, network, DNS, TLS, process, clock, random or device operations.
- No generic third-party provider registration; CM-A09 remains open.
- No zero-copy, async, deadlines per stream, seek or shared memory.
- No strict-mode file/network/process resource support and no claim that host-in-process I/O is a sandbox; strict stdio is the existing console.
Compatibility
- Additive value variant; old programs never produce
Resource. - New builtins only; existing
fs.read/write,打印, plugin and foreign behavior is unchanged. - No wire version bump: the new tag is rejected, not accepted.
- New error categories are additive; existing categories/codes are unchanged.
Consequences
.mq.mdcan implementwrite_text-style output by encoding text intoMemory(fixture 59) and callingresource.write, and can implement chunked file readers withresource.read/Result/EOF.- The remaining high-level I/O surface can grow in the standard library without
a new
HostOpper function. - The resource table is host state per run; closed slots are not reused in this slice, so generation checks are straightforward.
- Strict remains conservative;
.mq.mdresource code runs inpure(stdout) orproject(file read) only.
Verification
docs/evidence/2026-11-20-resource-stream-p3.md records unit tests for grants,
mode refusal, traversal rejection, forged/closed handles, output budget,
file chunking/EOF, wire rejection and a .mq.md stdout fixture.