SumSheet transport and message format

The processor is launched with the compute_contract_cli --session command. After the greeting line, it accepts one JSON request per line and responds with one line for each. The browser uses the same format — through a session call in WebAssembly.

Not every incoming line is a response to your request. For an operation that needs the network, the processor writes a counter-line with a kind field and its own id, and stops until it gets a response with the same id: it has no network of its own, and reaches out to you for https and for connecting to Postgres or SQL Server. Sort incoming lines by kind; the processor has no timeout of its own, and watching the clock is your job. In detail — how the session works and what depends on the build.

# the path inside the installed application — see “SumSheet installation”
"$F1_CLI" --session

Common request fields

Field	TypeScript type	Req.	What it is
operation	ComputeRequest["operation"]	yes	The operation name; the core uses it to decide what to do.
requestedBackend	"wasm" | "native-desktop" | "service-host" | null	no	Where you’re asking the request to run.
requestId	string	no	Your request number. The core returns it in the response unchanged — that’s how a response is tied to a request by identity, not by arrival order.

Response on success — ComputeSuccessEnvelope

Field	TypeScript type	Req.	What it is
ok	true	yes	The request was executed.
requestId	string	no	The same number you sent.
requestedBackend	ComputeBackendKind	yes	Where you asked it to run.
backendUsed	ComputeBackendKind	yes	Where it actually ran.
fallbackUsed	boolean	yes	true if the requested runtime was unavailable and the core ran the request in a different one.
warnings	ComputeWarning[]	yes	Warnings: they don’t affect success, but two of them change how you should write your code: after opening a large workbook, its size fields may describe less than the whole sheet, and formula values may arrive exactly as Excel last saved them. What kinds there are.
responsiveRecalc	ContractResponsiveRecalcSnapshot | null	no	The state of background recalculation at the moment of the response, if it’s enabled.
payload	ComputeResponsePayload	yes	The result of the operation itself; its shape is different for every operation.

Response on refusal — ComputeErrorEnvelope

Field	TypeScript type	Req.	What it is
ok	false	yes	The request was rejected; the workbook didn’t change.
requestId	string	no	The same number you sent.
requestedBackend	ComputeBackendKind	yes	Where you asked it to run.
backendUsed	ComputeBackendKind	yes	Where it actually ran.
fallbackUsed	boolean	yes	true if the requested runtime was unavailable and the core ran the request in a different one.
warnings	ComputeWarning[]	yes	Warnings: they don’t affect success, but two of them change how you should write your code: after opening a large workbook, its size fields may describe less than the whole sheet, and formula values may arrive exactly as Excel last saved them. What kinds there are.
code	string	yes	The refusal code — a stable string you use to tell refusals apart in code. The field’s type is exactly string, and that’s not a simplification: the contract doesn’t declare a closed list of codes; they arise at the point of refusal. Branch on the ones you need, and keep a default branch: an unfamiliar code is business as usual, not a sign of breakage.
message	string	yes	An explanation in words.
details	string | null	no	Details, if the core has anything to add.
dataValidationSource	ContractDataValidationSourceValidation | null	no	Filled in when the refusal is caused by data validation: which field wasn’t accepted, and why.
calculationStatus	ContractCalculationStatus | null	no	The calculation state, if the refusal is related to it.

Refusal codes

The contract declares code as a plain string, not a closed list of values. So what’s described here is the exact response schema, not a list of every possible code: there simply isn’t one. The codes that matter for your work are declared by whichever part of the core is responsible for that specific operation.

What the two envelope types consist of

Their names appear in both tables above, but they don’t have their own pages in the catalog: the catalog describes operation data, and these are types of the envelope itself.

ComputeWarning — a single warning:

Field	TypeScript type	Req.	What it is
code	string	yes	The warning code — a stable string to branch on.
message	string	yes	An explanation in words.
details	string | null	no	Details, if the core has anything to add.

It’s built the same way as a refusal, and you tell them apart not by their shape but by the envelope’s ok field: a warning can arrive on success too.

ContractResponsiveRecalcSnapshot — the state of background recalculation:

Field	TypeScript type	Req.	What it is
enabled	boolean	yes	Whether background recalculation is enabled at all.
latestGeneration	number	yes	The number of the last requested recalculation.
committedGeneration	number	yes	The number of the last one completed.
pendingGeneration	number | null	no	The number of the one being computed right now.
status	ContractResponsiveRecalcStatus	yes	State: computing, ready, canceled.
trigger	ContractResponsiveRecalcTrigger | null	no	What started it.
scope	ContractResponsiveRecalcScope | null	no	How wide a scope the recalculation covers.
supersededGenerationCount	number	yes	How many recalculations were superseded by newer ones.
staleCommitRejectionCount	number	yes	How many times a finished recalculation was discarded: the workbook moved on while it was still computing.
note	string	yes	An explanation in words — for showing to a person, not for branching on.

Comparing latestGeneration with committedGeneration tells you whether recalculation has caught up with the latest edit: equal means it has.