> 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/fidelity.md). # Fidelity This page explains what Stemma guarantees about its output and what it deliberately excludes. The short version: **document semantics, rendering, and native revision behavior are the contract; byte identity of serialized XML is not.** ## What is guaranteed * **Render fidelity.** A document edited by stemma looks the same in Word, outside the edit, as it did before. The model separates *authored* values from *effective* (inherited/computed) ones and serializes only what the document actually said. An authored literal font is never silently replaced by a theme reference. An `auto` color never becomes a theme color, authored-off toggles round-trip as authored-off. * **Content completeness.** Nothing is silently dropped. Constructs the typed model understands are carried typed; constructs it does not are preserved verbatim and re-emitted at their schema position (the `PreservedProp` mechanism); opaque objects (images, equations, fields, unknown elements) are carried byte-for-byte. Where a gap in this coverage is known, it is inventoried and gated (see below), not ignored. * **Fail-loud, with disclosed normalization.** If Stemma cannot import a construct faithfully, it refuses with an error instead of guessing. A narrowly supported deterministic normalization is reported through `Document::diagnostics()`; it never disappears as apparent clean input. Every output is checked by an OOXML validator before bytes leave the engine. * **Tracked-change semantics.** Accepting or rejecting stemma-authored changes in stemma or in Word restores the document's *content and rendering* according to Word's own semantics. This is verified against a real Microsoft Word instance as a behavioral oracle. These properties are enforced by the test suite, including a per-block untouched-content fidelity gate that runs a tracked edit over several hundred real-world documents and censuses every block the edit did not touch. Its list of known residual classes is documented in the gate and only ever shrinks. ## Explicitly out of contract: byte identity Opening a document, making an edit, and saving **rewrites the serialized XML**. Attribute order, namespace prefixes, self-closing style, rsids, revision-id numbering, and whitespace between tags may all change in parts of the file the edit never touched. This is an intentional design decision, not an accident: * **Word does the same.** Open a `.docx` in Word, type one character, save: the whole file is rewritten. No tool in the ecosystem provides byte stability for an edited document. * **Every consumer that matters keys on content, not bytes.** Word, Word and Stemma's own projections consume document meaning rather than raw serialization. The churn is invisible to them; the properties that *are* visible are exactly the guaranteed ones above. * **Byte preservation would grade the wrong thing.** The user-visible fidelity bugs we have found and fixed were all *model expressiveness* bugs. Fixing them in the model fixed them everywhere, including in the edited content itself, where byte-splicing untouched blocks could never reach. Practical consequences, stated plainly: * Checksums, content-addressed stores, and raw-XML diffs (e.g. a git-tracked `.docx`) **will** show changes on untouched content after an edit. Use a content-level or canonical-model comparison instead. * "Reject all changes" restores the document's content and rendering, not its original bytes. Keep the original file if you need it, just as you would before letting Word save over it. * When import reports no normalization, opening and saving **without any edit** round-trips the original package byte-identically. A disclosed import normalization intentionally changes those bytes. If your workflow contractually requires byte-identical untouched content, that requirement is not met today. Tell us about the use case rather than discovering the churn in production. ## Import normalization is explicit Validation applies to exact bytes; parsing establishes editable engine state. Those usually coincide, but v0.6 has one deliberately bounded exception: Word opens a package whose root thumbnail relationship points to an absent thumbnail and removes that dead relationship on save. Stemma can do the same at import, records a warning in `Document::diagnostics()`, and emits the repaired package. Raw `validate` still reports the original dangling relationship. This is not a general repair mode. A missing target used by body content, headers or footers, drawings, hyperlinks, embedded objects, or another active semantic consumer remains a hard error. New tolerances require an explicit Word-compatible rule and a public diagnostic; there is no catch-all recovery. ## The text projection normalizes enumerator separators One deliberate normalization to know before diffing **projections** (as opposed to stored content): when a paragraph begins with an enumerator label, the plain-text and Markdown projections (`stemma extract --format text`, `stemma inspect`, `to_text()`) render the label, then a **tab**, then the body, regardless of the separator character in the stored runs. That covers both real list numbering (`w:numPr`, where the separator is render-time convention anyway) and a *literal* leading label the engine recognizes in plain paragraph text, such as `1. Term` written with an ordinary space. The stored content is untouched: the serialized `.docx` keeps the original space and gains no `w:tab` element. Only the projection normalizes, so enumerated paragraphs read uniformly whichever way the source document encoded its labels. Consequence for content verification: compare projections against projections (both sides normalize identically), never a projection against raw XML or another tool's text extraction. A `space -> tab` difference at a leading `N.`/`a)`/bullet label is this normalization, not corruption. --- # 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/fidelity.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.