Module resource_plane 

The resource plane: the read-only file surface a capsule declares under exports.files.

Two verbs, list and read, served host-side off the ordinary host path the runtime already holds for the workdir. No wasm is instantiated, no store is locked and no running turn is consulted, so the plane answers whether the capsule is idle or mid-task — and a read never costs an inference turn.

Three responsibilities are kept apart:

• The agent owns what a file contains. Nothing here asks it anything.
• The runtime owns who may read it. Path resolution lives entirely in this module: a caller never sanitises a path, because a gateway that normalises .. into something servable has taken over the containment boundary, and the component holding that boundary must not think. Every escaping request is refused, never repaired.
• The trace owns the record. Every read and every refusal lands in trace.jsonl at the moment of the request, because the agent has been removed from the loop and the trace is the only account of what left the capsule and when.

Declaring an export does not change the achieved containment class — see crate::containment. Containment describes the guest’s reach outward; an export widens the operator’s reach inward and hands the guest nothing.

The filesystem work is synchronous std::fs run on tokio::task::spawn_blocking, and the resolve-then-verify-prefix path is the only one: openat2(RESOLVE_BENEATH) is Linux-only and could never be more than an extra layer over a portable path that has to be correct by itself, so this module keeps the portable path alone rather than two that can disagree.

Structs

DeclaredExport

One exports.files block, with its root already resolved against the session’s accessible workdir.

ListEntry

One regular file under the export root. size_bytes, mtime_ms and sha256 all come from a single open of that file, so they describe one version of it and never a mixture of two.

ListResponse

ReadResponse

The bytes of one file together with the validator that describes those bytes.

ResourcePlane

Everything the resource plane needs to answer a request, and nothing that a running task leaves behind.

ResourceResponse

A status, headers and a body — everything a transport needs and nothing about the transport.

Enums

ResourceError

SymlinkPolicy

Constants

RESOURCE_PATH_PREFIX

Path prefix the plane answers under. Everything below it is GET-only.

Functions

check_export_root

Refuses a launch whose declared export root already resolves outside the accessible workdir.

check_peer_files_root

Refuses a launch whose declared exports.peer_files.root already resolves outside the accessible workdir — check_export_root for the peer plane’s root, and the same refusal.

handle_resource_request

Answers one resource-plane request: a method, a raw request path, and nothing else.

reason_phrase

The reason phrase for a status either plane can return. Only these appear; anything else is a programming error rather than a response shape callers depend on.

symlink_policy

What a symlink under the export root means at each achieved containment class.