> For the complete documentation index, see [llms.txt](https://stemma.sh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stemma.sh/docs/understand-the-model/concepts.md). # Concepts Stemma has one engine pipeline and one downstream comparison path: ``` DOCX bytes -> import -> CanonDoc -> explicit edit -> serialize -> DOCX bytes accepted base + accepted target -> stemma-diff -> engine operations -> redline ``` Four ideas carry the whole system. ## The document is typed, not text Importing a `.docx` produces a **CanonDoc**: an ordered list of blocks (paragraphs, tables, opaque content like images and fields), each with a **stable id** (`p_7`, `tbl_2`). Every read shows these ids and every edit targets them. Content is never addressed by line number or byte offset. Content stemma has no typed model for (an exotic extension, a foreign namespace) is not dropped: it is preserved verbatim and re-emitted in place. A document is more than its body. Footnotes, endnotes, headers, footers, and comments are separate **stories**. They are parallel block sequences that reads, edits, and tracked-change resolution all reach. ## One file is three documents A document carrying tracked changes is really three documents at once: the text **as it stands** (changes pending), the text **if everything is accepted**, and the text **if everything is rejected**. Stemma exposes the resolved readings as **projections** (`read_accepted`, `read_rejected`; the redline itself is `to_text`). Projecting never mutates the source (every verb returns a new value), but the result is not a text view: a projection is a **full `Document`**, so you can read it, project it again, or serialize it as the resolved `.docx` a reviewer will actually receive. ```rust,no_run use stemma::api::{Document, ExportOptions, RuntimeError}; fn three_readings(edited: &Document) -> Result<(), RuntimeError> { // One file, three readings. `to_text()` is the redline (deletion AND // insertion visible); `read_accepted()` resolves everything as accepted; // `read_rejected()` as rejected. let _redline = edited.to_text(); let accepted = edited.read_accepted()?; let rejected = edited.read_rejected()?; assert_ne!( accepted.to_text(), rejected.to_text(), "the two resolutions genuinely differ" ); // A projection is a full Document: serializing the accept-all projection // writes the `.docx` a counterparty's "accept all" button would produce. let _resolved_docx: Vec = accepted.serialize(&ExportOptions::default())?; Ok(()) } ``` Runnable: `cargo run -p stemma --example walk_the_document`. ## Edits are transactions with receipts A typed edit **transaction** is a list of operations plus an author. Either every operation in that transaction lands or none do. Itemized replacement worklists are deliberately different: each item reports its own applied or refused outcome so a caller can reissue only what failed. Every write returns a **receipt** naming exactly what happened: which blocks changed, which revision ids were created, and where a moved block landed. Every refusal names what went wrong and what to do instead. Partial outcomes are always explicit and never reported as complete success. Ops are anchored optimistically: an edit carries the text it `expect`s to find (or a content hash), so an edit planned against stale state fails loudly instead of changing the wrong thing. ## Nothing leaves unvalidated Serialization runs a post-serialization OOXML linker before bytes are written. This structural validation pass checks the emitted package, and it guards **every** exit: `Document::serialize` runs it by default (`ExportOptions::default()` gates at the blocking level; opting out is the explicit, engine-internal `ExportOptions::unchecked`), and `save_docx` refuses to persist a structurally corrupt file. Transport output commits are create-new: inputs and every existing destination are refused. Bytes are staged beside the destination, committed without clobbering, and verified by length and SHA-256 before success. This is collision-safe visibility, not a power-loss durability claim. Next, read [Revisions](/docs/understand-the-model/revisions.md) for the tracked-change type system these concepts exist to serve. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://stemma.sh/docs/understand-the-model/concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.