Versions
VoLCA shows one number to the people who use it, and keeps semantic versioning for the parts that other code depends on.
| Number | Example | Who it is for | What it tells you |
|---|---|---|---|
| VoLCA release | VoLCA 17 | everyone using the web interface or the desktop app | which release you have, and whether a newer one exists |
| Engine version | 0.18.0 | scripts, applications and agents calling the engine | what still works after an upgrade |
| pyvolca version | 0.14.3 | Python code using the client | what still works after an upgrade of the client |
wireVersion | 112 | programs | whether a feature is available on the engine they talk to |
dataVersion | 15 | anyone comparing results | which reference data bundle the engine carries |
The footer of the web interface reads VoLCA 17 · engine 0.18.0: the first number for you, the second for your code.
The VoLCA release
Section titled “The VoLCA release”The web interface and the desktop app show the same number. It moves when a release brings something worth announcing, and it promises nothing about compatibility: read What is new to know what a release changed. Between two releases the hosted web interface can still improve; hover the version in its footer to see the date of the build you are using.
The engine version
Section titled “The engine version”Everything a program can call on the engine shares one version: the HTTP API, the MCP tools, the command line and the volca.toml configuration format. It follows semantic versioning around one question: does code that works today keep working after the upgrade?
- Before 1.0, a release that removes or redefines something a working client relies on (a route, a field or an MCP tool removed, a unit or an identifier redefined) moves the minor number:
0.16.xto0.17.0. Everything else moves the patch number, however large: new routes, tools, formats, configuration keys and fields are additions. - From 1.0 on, the same rule moves the major number, additions move the minor number, and fixes the patch number.
So a client written against 0.16.0 keeps working on every 0.16.x. A removal is never a surprise: the release that introduces a replacement keeps the old shape, and its changelog names the release that drops it.
pyvolca
Section titled “pyvolca”The Python client has its own semantic version, because a change to the client and a change to the engine are not the same event. It checks the engine it talks to the first time it connects, and its compatibility section says which engines a given pyvolca accepts. A name pyvolca publishes keeps working, with a warning, until the next major version of pyvolca.
wireVersion: is this feature there?
Section titled “wireVersion: is this feature there?”GET /api/v1/version answers with both version and wireVersion:
{ "version": "0.18.0", "wireVersion": 112, "dataVersion": "15" }wireVersion goes up each time the engine learns something new to say, and never goes down. The engine version only moves at a release, so between two releases a newer feature can already be there on an engine built from the latest sources. A client that wants to use a feature before relying on a release tests wireVersion against the revision that introduced it, or simply checks that the route answers.
dataVersion
Section titled “dataVersion”The engine carries reference data: units, compartments, geographies, flows, chemical synonyms and characterization methods. dataVersion names that bundle, and it moves on its own: a change of data does not by itself move the engine version. So when two engines of the same version give two scores for the same inputs, read dataVersion: that is where they differ. A change of data that redefines a unit or an identifier also moves the engine version, since code relying on the old meaning would break.