A .dxn document with everything it holds: its value, and every comment, blank line and comma around it (design/comment-retention.md).

Dextrin.decode/2 keeps only the value, which is right for data and wrong for a file people annotate: decoding, changing one entry and encoding again deletes every comment. A document keeps the full-fidelity syntax tree instead -- every token, trivia included (Ichor.Syntax) -- with the value as a projection of it:

{:ok, doc} = Dextrin.Document.parse(source)
Dextrin.Document.to_value(doc)   # what Dextrin.decode/2 returns
Dextrin.Document.render(doc)     # source, byte for byte

One grammar, parsed one way. The tree comes from the same priv/grammar/dxn.aether as decode/2, through the lossless entry point Ichor generates beside the fast one, and the same actions build the value -- so a document parses exactly when decode/2 would, and refuses with the same errors.

An untouched node renders its own bytes. Preservation is a property of rendering, not something a printer has to get right.

Edits

replace/3, delete/2 and insert/4 name what they change by a path from the document's value: a map's key as it decodes (:deps, "x"), a struct's field name ("y"), a list's, tuple's or set's index. Each splices the source text at the edited node and parses the result again, so every byte it does not touch is rendered as it was, and the edited document is checked by the same parser as any other.

A comment belongs to an entry (design/comment-retention.md, "Trivia ownership"), by lines alone: a block starting on an entry's own line is that entry's trailing block, however many lines it runs to; every other block of comment lines is above the next entry, and a blank line separates blocks. So a deleted entry takes its trailing block and the blocks above it, and nobody else's; a replaced value keeps every comment around it, even one it has made stale; an inserted entry goes above the comments of the entry it lands before, so they stay with that entry.

Updating to a new value

update/3 is a convenience over the edits, for a caller who has only the new value: it compares it with the document's, leaves what is equal alone -- 1.50 stays 1.50 when the new value is 1.5 -- and answers the edits it made as a changeset. Lists are compared with List.myers_difference/2. A deleted item followed by an inserted one is ambiguous: a replace keeps the deleted item's comments, a delete and an insert drop them. on_ambiguity: decides -- :safe (the default) takes it as a replace where the deleted item owns no comment, and refuses where it does; :guess always takes it as a replace; :error refuses every such pair.