One Run Contract, Many Compute Boundaries

OpenResearch gives a run one local identity even when the work can execute in very different places. This chapter focuses on the common contract shared by its compute adapters and the differences that reappear at each boundary. The practical judgment is conditional: choose local execution, a user-owned host, a scheduler or serverless provider, or an ephemeral managed machine according to workload, trust, evidence, and cost—not because a backend label implies that all environments are equivalent.

The point of a common interface is not to erase infrastructure. It is to keep the research meaning of a run stable while the transport and operating conditions change. A committed experiment branch should still produce a source snapshot, a run record, logs, and a terminal outcome whether the payload runs beside the dashboard or on a remote machine. But the conditions under which those records are produced can be substantially different.

The contract that travels with the run

OpenResearch's compute layer gives adapters a shared lifecycle. A backend exposes capabilities and preflight checks, stages the source, submits the run, reports status, provides logs, handles cancellation, and cleans up. The local experiment plane resolves the selected backend and launches through orx exp run rather than asking a provider's command-line tool to create an untracked job. That common path keeps the run attached to the local experiment row and its recorded source snapshot.

Preflight is the first meaningful difference inside the common contract. It can check whether a required flavor, credential, host, toolchain, cluster, or provider connection is available before source submission. A backend that is registered in the codebase is not automatically ready in a particular installation. Capacity may be unavailable, an SSH host may lack the required tools, or a managed service may require login and an organization context. The common lifecycle makes the failure visible as a backend readiness problem instead of letting it masquerade as a failed scientific experiment.

Source staging is the second invariant. Before submission, OpenResearch archives the recorded commit and attaches the content digest and archive details to the backend descriptor. The adapter then transports that snapshot according to its boundary. The local backend extracts an archive on the same machine. SSH can stream it to a user-owned host. Other adapters use their own transport or provider package. The experiment still refers to the same recorded source, but the path by which the bytes move is different.

Submission, status, logs, cancellation, and cleanup are likewise shared concepts with different implementations. A local process has a run directory and process group. A remote host has a remote run directory and an SSH connection. A scheduler has a provider job handle. An ephemeral machine has a provisioning lifecycle followed by a remote payload and eventual teardown. The local store needs one run vocabulary, while the adapter descriptor keeps the provider-specific handle required to reattach and clean up.