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

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.

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.

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_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.

extract_sidecars

Extract large blobs from serialized arguments into sidecars.

handle_negotiation

Handle a blob negotiation request on the server side.

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.