Document lifecycle

Integration is built around the session, commands, revisions, and events, not around direct access to the editor’s internal markup.

1. Your application receives the document. Your system verifies the user and passes the bytes of an allowed DOCX or a safe path to the file.

2. SumDoc opens a session. The core parses the file and builds the document model, the profile of available capabilities, and the first revision.

3. The surface shows the document. The user sees the pages and the available commands, and your application receives a readiness event.

4. A command arrives. It says what to do, where in the document, and which revision it expects. Nobody edits the file markup directly.

5. The core applies or rejects. On success, a new revision appears along with an unsaved-changes flag. A refusal doesn’t leave the document half-changed.

6. Your application saves the result. The core writes the changes to the file and returns the DOCX, and you create a version and a log entry. If the opened document carried a digital signature, editing and saving invalidate it — otherwise Word would later declare the file modified. The core warns about this on opening; for developers: the warning comes not as a response but as a line on the error stream.

7. Reopening confirms. The saved file is opened again in a new process — this proves the change reached the disk rather than staying on screen.

Core API objects

Object	Purpose
Session	The lifecycle of one open document, isolated from the others.
Command, or intent	An action of a known kind: what to do, with what, and at which expected revision.
Result envelope	Success or an explicit refusal with a reason, diagnostics, and an identifier that links the response to the request. There’s no separate warnings field here — unlike spreadsheets, where the response has warnings.
Event	Readiness, unsaved changes, save, error, and other state changes.
Capability profile	The list of available commands and limits — no defaults assumed.
Artifact	DOCX bytes, a checkpoint, or diagnostics — everything your application manages.

How the result is published

Saving doesn’t write over the existing file. First a temporary file is created alongside, its contents are flushed to disk, and only then does the temporary file take the target’s place in one step. An interrupted save doesn’t leave a half-written DOCX: the disk holds either the previous version or the new one in full. So the file appearing at the expected path is already a sign of a completed write; there’s no need to wait and check the size.

Checkpoint saving takes one more step: before publishing, it compares the file against the state your application last saw, and refuses if something changed it from outside — another program, a second session, or sync. Someone else’s edit is never silently overwritten.

Next

• How requests and responses work — Request and response objects.
• What the product does with the document — the capability map.
• Today’s boundaries — Readiness and boundaries.