A separate core process alongside your application

What the setup consists of

The core runs as a separate process alongside your application, so the scheme has four participants:

• Your desktop application — the window, file access, ties to the operating system, the editor’s web shell.
• The exchange channel — a long-lived session: a JSON line with the request, a JSON line with the response.
• The compute_contract_cli processor — the workbook session, computation, import, and export.
• Local or corporate storage — the source file and the new version.

The actual protocol today

The processor starts in session mode and sends a five-field handshake as its first line:

Field	What’s in it
kind	compute_contract_cli_session_ready — the handshake’s own marker: it’s how you tell it apart from an ordinary response.
transport	native-desktop-binary — how the exchange happens: this is a separate process alongside the application, not a browser and not a server.
protocol	compute-contract-cli-session-v1 — the version of the conversation itself. This is what’s worth checking at startup: a mismatch means the processor is older or newer than your code.
computeContractVersion	The operations contract version.
pid	The process ID: useful for killing a hung one.

After that, it accepts one JSON command per line and answers each with one JSON line. The requestId field comes back in the response — that’s how you match the pair in your own logs.

Not every line you send gets a response

The processor silently skips an empty line — and a line of nothing but spaces: it will never get a response. A client that waits for exactly one line after every send will hang forever on a stray newline. Send the command and its newline as one chunk, and never send empty lines to try to “wake up” the processor.

A line that fails to parse as contract JSON, on the other hand, does get a response: an error envelope with the invalid-compute-request code and the reason spelled out in the details. The session continues either way — the processor doesn’t close and waits for the next command.

The processor answers strictly in order: responses arrive in the same order the requests were sent, so a long operation delays everything sent after it. There’s no point sending the next command before the previous one’s response arrives — it will just wait anyway. If you need parallelism, start a second process.

There’s one exception to “a line in, a line back”, and it’s what trips people up most often. While you’re waiting for the response to an operation that needs the network, the processor can write you a counter-question — a line with a kind field and its own id — and stop until it gets a response with the same id. It has no network of its own: for https and for connecting to Postgres or SQL Server, it turns to you. It has no timeout of its own either, so you’re the one who has to watch the clock; closing the input stream ends the wait with a refusal, not a hang. Parse incoming lines by their kind field, and don’t treat every line as a response to your own request — how the conversation works.

Starting, ending, and restarting the process is on your side.

Strength	Cost / limit
More memory available, and more predictable behavior with large workbooks.	You have to install, update, and monitor an executable.
Direct access to local files and the corporate environment.	You need strict process isolation and checks on paths and permissions.
The interface is the same as in the browser.	You’re responsible for restarting after a crash, timeouts, and cleaning up orphaned processes.

Good fit for

Desktop applications, virtual desktops (VDI), large workbooks, and air-gapped environments where the memory available to a browser isn’t enough.

Other environments

• The core in the browser
• The processor on the server
• Phone and tablet
• The end-to-end scenario and what changes between environments