Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublicTeam
Assigneesstack72

Relationships

#1842 model update rewrites the definition file and strips all comments

Opened by sbahra · 8/26/2026· Shipped 8/26/2026

We keep a lot of important context in our model YAML as comments. Things like why a particular root volume is 64GB and not 30, or why a host has no KeyName. That context is the reason someone does not undo a decision six months later.

Running swamp model method run <name> update wipes all of it. We ran update on 8 EC2 instance models today and every one came back with zero comments. Three files went from 12-13 comments to none. We had to restore them by hand.

The write path is in yaml_definition_repository.ts, in save(). It does JSON.parse(JSON.stringify(data)) and then stringify from @std/yaml, and @std/yaml has no concept of comments in either direction. So the comments are actually already gone at parse time. There is nothing left to write by the time save() runs.

Two things we would like, and we think the first is much more important than the second.

  1. Do not write the definition file at all when the definition has not changed.

This is the one that actually bit us. For 5 of those 8 models, nothing in globalArguments changed. The model already said what we wanted, AWS was just missing a tag. swamp rewrote the file anyway, and the only difference in the whole commit was the typeVersion field being bumped.

So an operation whose job is pushing state to AWS is rewriting our source files as a side effect, to bump a version number. That feels like the real bug and comment loss is just the symptom. If save() compared the serialized data against what is on disk and skipped the write when they match, or if the typeVersion bump were its own explicit command, most of this problem disappears. It looks like a small change.

  1. Preserve comments when the definition genuinely does change.

npm:yaml is already a dependency (we see it in src/domain/models/bundle_test.ts). Its parseDocument keeps comments and doc.toString() round-trips them. parseDocument is not used anywhere in the codebase yet. The work would be in save(): read the existing file as a Document and apply changed values onto its nodes instead of serializing a fresh object. The awkward part is comments attached to a key that gets removed, and you would need to decide whether those get dropped or floated.

We are not asking for this heuristically. We tried re-attaching comments after the fact with our own script and it silently corrupted two model files, because those two indent list items with two spaces instead of four and our pattern did not match. Doing it properly through the Document API is exact, which is the whole point.

  1. Is there another idiom for this that we are missing?

We may just be using comments for something you intended to solve another way. We looked at DefinitionSchema and there is no description or notes or annotations field on a definition. The only description fields are inside the JSON schema property definitions, which are for extension authors documenting global arguments, not for an instance of a model.

The closest thing is tags, which is Record<string, string>. That would survive the round trip since it is real data, but it is a flat string map. It is fine for owner: platform and no good for a paragraph explaining a sizing decision. It also reads confusingly next to AWS Tags inside globalArguments, since those are a different thing with the same name.

If there is a supported place to put this kind of reasoning that we have overlooked, we would rather use that than ask you to preserve comments. If there is not, a description or notes field on a definition would work for us too, and might be easier than comment preservation.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 7 MOREREVIEW+ 10 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

8/26/2026, 5:14:24 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack728/26/2026, 3:35:36 PM
Editable. Press Enter to edit.

stack72 commented 8/26/2026, 5:14:33 PM

Thanks @sbahra for reporting this! The fix has been merged and a release is on its way. We appreciate your contribution to swamp.

Sign in to post a ripple.