The Operating Model: From Intent to Runtime
At this point, nvm-sh/nvm is easiest to understand as one connected system rather than as a collection of commands: a description expresses intent, a resolver chooses a concrete version, an installer obtains or builds it, and a shell environment makes it the runtime a process will actually find. This checkpoint connects those already-established ideas and gives the reader a practical test: when nvm behaves unexpectedly, can the surprise be located in intent, resolution, acquisition, validation, or activation?
The distinction is more useful than memorizing the names of every option. The same version request can pass through different paths depending on whether it is exact or symbolic, whether the project supplies an .nvmrc, whether the needed artifact is already cached, and whether the current shell has activated the resulting tree. Those variations change the route, but not the underlying model.
One request, five states
The first state is intent. A user, project, or script expresses a desired runtime as an exact version, a partial line, an alias, an LTS label, or a file-derived value. Intent answers “what should be used?” It does not yet identify files on disk. A project’s .nvmrc can make that intent visible to every command launched under a directory, but the text in the file remains a selector until nvm interprets it.
The second state is resolution. Nvm interprets the selector against a candidate set. A local operation may search versions already installed. An online installation can consult remote release metadata. An offline operation is restricted to installed versions and cached downloads. The same word—node, for example—can therefore be resolved against different candidate sets without changing its meaning. Resolution answers “which concrete version satisfies this request in this context?”
The third state is acquisition. Once a concrete version is known, nvm can decide whether an existing cache or a new artifact will provide it. A compatible binary is normally the shortest route. If no suitable binary is available and source fallback is allowed, nvm can obtain source and build it locally. In offline mode, no new artifact can be obtained at all. Acquisition answers “where will the runtime’s material come from?”
The fourth state is installation and validation. The artifact must become a version-specific tree with the shape nvm expects. A successful download is not enough; extraction or compilation must complete, and the resulting tree must pass checks such as the presence of a nonempty executable Node binary and a non-dangling npm entry when one is present. This state answers “is there a usable installation to select?”
The fifth state is activation. Nvm changes the current shell’s lookup environment so the installed tree’s commands are found, or prepares a child process to use that tree. A directory can be fully installed while another terminal continues to use a different version. Activation answers “which runtime will this process actually execute?”
These states are related, but they do not prove one another. Valid intent does not prove that a matching release exists. A resolved version does not prove that the host has a binary for it. A cached archive does not prove that its contents passed the normal online checksum path. A directory with files does not prove that its installation is complete. An installed tree does not prove that the current shell’s PATH points to it.
A single example makes the ownership changes concrete. Suppose a project contains an exact version in .nvmrc, but that version is not installed.