Preserve source comments and layout through model token edits

docs/language.rst

@@ -908,7 +908,7 @@ folders consolidate into category modules to avoid thousands of tiny files.
 For every valid P, ``compile_bundle(format_bundle(P)).decoded.project == P``
 when the caller supplies sufficient admission budgets.
 
-``update_bundle(compiled, P, limits)`` is a core prototype update facility. It
+``update_bundle(compiled, P, limits)`` is a core source update facility. It
 checks that the compiled document/index/model snapshot still agrees, preserves
 existing declaration file ownership and all untouched document bytes, and
 recompiles the result before returning it. New children inherit their owner's
@@ -917,15 +917,43 @@ Removed declarations do not delete source files. Alias changes also update
 declarations containing references to that alias. Invalid or stale updates
 return errors without mutating the input workspace.
 
-The current update facility canonicalizes each changed declaration in full.
-It therefore DOES NOT preserve inline comments or custom layout inside that
-declaration, even for a single scalar edit. This is an explicit prototype
-limitation, not final authoring/save acceptance. A lossless project editor needs
-minimal header/field/value edits that preserve unrelated tokens and comments;
-the available source spans provide the starting point. Canonical modular export
-is a distinct, explicit operation and does not promise original comment/layout
-preservation. No native multi-file editor, project save transaction or REST
-bundle endpoint is claimed by the pure core APIs.
+Updates MUST NOT canonicalize surviving declarations in full. Header, field and
+nested value positions are derived from the existing syntax parser. Unchanged
+fields retain their exact bytes, including field order, omitted defaults, number
+and string spelling, comments, indentation and line endings. Changed literals and
+references replace only the required tokens; a reference with comments between
+``@`` and its alias retains those comments. A previously omitted default is
+inserted only if its semantic value changes. New fields use the existing record's
+indentation and line-ending style without reformatting its other fields.
+
+A constructor tag change retains shared nested fields in place. Removed fields,
+constructors and declarations remove syntax tokens, retaining their comments
+and whitespace as annotations in the enclosing record or file. A complete value
+shape replacement likewise retains the old value's comments beside the new value.
+The updater does not invent an engineering interpretation for orphaned comments.
+
+List entries use stable referenced UUIDs, message-value ``field`` references or
+lifeline-binding ``referenced`` identities when these keys are unique. Literal
+entries use their literal value. Retained entries carry their authored value
+text and inter-separator comments when reordered. Trivia after a preceding comma
+belongs to the following entry; trivia before the next comma belongs to the
+preceding entry. Separators are reconstructed before trailing line comments so
+that the result remains valid syntax. Unkeyed or duplicate-key lists use source
+positions. Removed-entry comments remain as annotations in the list; newly added
+entries receive formatted syntax. These rules preserve comments without silently
+attaching new semantic identity to an ambiguous list entry.
+
+Retained declaration UUIDs and source ownership remain unchanged. Records match
+by UUID, not display name or alias; an explicit UUID replacement is a removal
+and creation, retaining the removed record's comments in its original file. The
+result is recompiled, reindexed and checked for equality with the requested
+model before return. Source changes needed for undo are workspace history data;
+callers should retain complete compiled workspace snapshots rather than infer
+past omission/layout choices from a model-only undo.
+
+Canonical modular export is a distinct, explicit operation and does not promise
+original comment/layout preservation. No native multi-file editor, project save
+transaction or REST bundle endpoint is claimed by the pure core APIs.
 
 ``parse`` returns a complete structurally validated candidate or error
 diagnostics and no model. Engineering warnings alone MUST NOT reject a valid