Module remote 

Per-function remote execution support

This module provides the types and executor for transferring function execution to another machine. The design sends the full compiled BytecodeProgram + a “call this function with these args” message, running it on a full Shape VM on the remote side.

Architecture

Layer 4: @remote / @distributed annotations    (Shape stdlib — user-defined policy)
Layer 3: RemoteCallRequest/Response            (this module)
Layer 2: shape-wire codec (MessagePack)        (encode_message / decode_message)
Layer 1: Transport (TCP/QUIC/Unix socket)      (user-provided, pluggable)

Layer 0 (the foundation): Full Shape VM on both sides, same BytecodeProgram, same Executor.

Closure semantics

Arc<RwLock<ValueWord>> upvalues become value copies on serialization. If the remote side mutates a captured variable, the sender doesn’t see it. This is the correct semantic for distributed computing — a send-copy model.

Structs

AuthRequest

Authentication request for non-localhost connections.

AuthResponse

Authentication response.

BlobNegotiationRequest

Request to check which function blobs the remote side already has cached.

BlobNegotiationResponse

Response indicating which offered blobs are already cached on the remote side.

BlobSidecar

A large binary payload sent as a separate message before the call request.

ExecuteFileRequest

Request to execute a Shape file on the server.

ExecuteProjectRequest

Request to execute a Shape project (shape.toml) on the server.

ExecuteRequest

Request to execute Shape source code on the server.

ExecuteResponse

Response from executing Shape source code.

ExecutionMetrics

Execution performance metrics.

PingRequest

Ping request (empty payload for wire format consistency).

RemoteBlobCache

Per-connection cache of function blobs received from a remote peer.

RemoteCallError

Error from remote execution.

RemoteCallRequest

Request to execute a function on a remote VM.

RemoteCallResponse

Response from a remote function execution.

ServerInfo

Server information returned in Pong responses.

ValidatePathRequest

Request to validate a Shape file or project without executing.

ValidateRequest

Request to validate Shape source code without executing it.

ValidateResponse

Response from validating Shape source code.

WireDiagnostic

A diagnostic message (error, warning, info).

Enums

RemoteErrorKind

Classification of remote execution errors.

WireMessage

Envelope for all wire protocol messages.

Constants

SIDECAR_THRESHOLD

Minimum blob size (in bytes) to extract as a sidecar. Blobs smaller than this are left inline in the serialized payload.

Functions

build_call_request

Build a RemoteCallRequest for a named function.

build_call_request_negotiated

Build a RemoteCallRequest that strips function blobs the remote already has.

build_call_request_with_negotiation

Build a RemoteCallRequest for a named function, with blob negotiation.

build_closure_call_request

Build a RemoteCallRequest for a closure.

build_minimal_blobs

Backwards-compatible name-based wrapper around build_minimal_blobs_by_hash.

build_minimal_blobs_by_hash

Build a minimal set of function blobs for a function hash and its transitive dependencies from a content-addressed Program.

execute_remote_call

Execute a remote call request on this machine.

execute_remote_call_with_runtimes

Execute a remote call with pre-loaded language runtime extensions.

extract_sidecars

Extract large blobs from serialized arguments into sidecars.

handle_negotiation

Handle a blob negotiation request on the server side.

handle_wire_message

Handle a WireMessage by dispatching to the appropriate handler.

negotiate_blobs

Perform blob negotiation before sending a call request.

program_from_blobs

Backwards-compatible name-based wrapper around program_from_blobs_by_hash.

program_from_blobs_by_hash

Build a minimal Program from function blobs and an explicit entry hash.

program_hash

Compute a SHA-256 hash of a BytecodeProgram for caching.

reassemble_sidecars

Reassemble sidecars back into the serialized payload.