SumDoc session and conventions

How names are written. SumDoc has three different conventions, and you shouldn’t mix them up. Command names use a hyphen or a single word: save-checkpoint, print-window, model, mutate; there isn’t a single underscore in a command name. Field names, by contrast, use an underscore: document_id, paragraph_index, operation_kind, expected_revision. And field values chosen from a list go back to a hyphen: insert-text, delete-line-break, merge-with-next. A spelling mistake returns a refusal that reads as “command not supported”, even though it’s a single character.

And here’s an exception worth knowing in advance. The hyphen rule holds for operation_kind on the mutate command. For the typed apply-text-transaction transaction, the kind of action lives in a different field — command.type — and its values are written with an underscore: insert_text, delete_range, merge_paragraphs, paste_plain_text. So the same action is written differently in the two commands: insert-text for mutate and insert_text for the transaction.

The word “list” is a loose term here: the contract doesn’t declare a single list of edit kinds — they’re documented at the places where they apply. An unknown kind doesn’t break the document and doesn’t come back as an envelope failure: the response is ok: true, result.mutation.result_kind is invalid-request, and the workbook stays unchanged. So the working set of edit kinds comes from what gets settled before integration begins: it’s agreed on together with the confirmation payload and the list of errors.

For comparison: in SumSheet, fields are written in camelCase — subsetId, sheetKey — with no underscores. If you embed both products, don’t look for a name from one in the other.

Two more differences that matter when embedding both. Here, a refusal comes as an error field — a reason in words; SumDoc has no separate code to branch handling on, and this gets settled before integration begins. SumSheet has such a field, called code, and the habit of branching on it doesn’t carry over here — see how to read a response.

And the exchange: here it’s strictly alternating — a request line, a response line. The SumDoc processor never asks questions of its own and never reaches out over the network. SumSheet is different: there, the core can send a line of its own and wait for your answer, so you can’t write one shared stream-reading routine for both products — see how the conversation with SumSheet works.

What sizes are measured in. There are two units, and the field name tells you which. Fields ending in _twips are in twips: a Word markup unit, one 1,440th of an inch. An inch is 1440 twips, a centimeter is about 567, and the standard 2.54 cm page margin is exactly 1440. Fields ending in _milli_px are in thousandths of a pixel: 96000 means 96 px, not ninety-six thousand. The first comes from the document format, the second from the screen, and you shouldn’t mix them.

Correlation. The id field is optional and accepts any JSON value — a string or a number. The core returns it unchanged, so it’s what you use to match a response to a request; the field is always present in the response and is null if the request didn’t carry one.

Order. The session keeps state between commands. A command that needs an open document refuses, before open, with the text no document is open in this session.

Editing. For mutate, operation_kind and paragraph_index are required — the other fields have default values. Paragraphs are numbered from zero. Edit kinds are listed in Request and response objects.

Unsaved changes. The dirty flag means the current model differs from the last saved state, not that the document is corrupted.

Ending the session. The response to shutdown contains shutdown: true and contains none of cmd, elapsed_ms, or result.

Response time. There’s no timeout in the session: the response arrives when the command has been processed. Any time limit is set by the client. The only timeout on the SumDoc side is five seconds for reading an HTTP request in Surface Host.

Saving. The file is published atomically: the write goes to a temporary file next to the target, the content is flushed to disk, and only then does it replace the target. An interrupted write never leaves a half-written DOCX file — see Document lifecycle. The save-checkpoint command additionally checks the file against the state passed in expected_hash, and refuses if it was changed from outside.

The message format and refusal codes are in Transport; the list of commands is in Session Protocol.