YAML round-trip strategy

[jonocodes]

Part of #82

Question

When the editor saves a layout, does it produce canonical (lossy) YAML via Pydantic model_dump(), or does it use ruamel.yaml to preserve comments and formatting? The trade-off: canonical is simple and always valid, but strips inline comments and manual formatting. Preserving comments requires carrying the original raw YAML alongside the parsed model and merging edited fields back in. Decide which path v1 ships.

[jonocodes]

Resolution

Decision: ruamel.yaml comment-preserving round-trip, not canonical model_dump(). The layout files are human-owned, comment-rich artifacts (default.yaml carries 37 comment lines; the Mac fallback opens with a paragraph explaining the overlay loader). Canonicalizing on first save would destroy that documentation and undermine "YAML files remain source of truth."

The strategy, one consistent mechanism:

1. Ownership — file stays human-owned. Editing preserves comments, key order, quote style, and formatting.
2. Editable surface — the ruamel CommentedMap on the daemon side. Pydantic validates only (round-trip the tree → model_validate → reject on error); it is never the edit buffer.
3. Application — id-keyed structural reconcile. The stateless browser sends a full Layout snapshot (keeps Daemon save_layout / create_layout API #84's simple message). The daemon reconciles it onto the preserved tree: widgets match by id — reorder permutes existing nodes so per-widget comments ride along, edits mutate in place, new ids append, vanished ids delete.
4. Uniqueness validator. Add a Layout-level invariant rejecting duplicate widget ids at load and save — it turns the reconcile's key assumption into an enforced guarantee (and duplicate ids are already a latent bug for view-pinning / WidgetUpdateMessage routing, which address widgets by id). New-widget id generation is deferred to Editor interaction model #87.
5. New nodes are emitted in ruamel default block style; a minor quote-style inconsistency for editor-added fields is accepted.
6. Sourcing — re-read from disk with ruamel at save time. No editing-session state in the daemon. Field-level last-save-wins, fine for a single-user desktop tool.
7. Write safety — atomic temp-write + os.replace; let the watchfiles reload flow naturally (validation-before-write guarantees it always sees valid YAML) — that is the save→preview loop for free.
8. Recursion rule — maps recurse key-by-key; the widget list matches by id; all other sequences (match, size, metrics, media lists) are atomic replace-on-change. Only the widget list has stable identity keys and per-element comments worth preserving through reorder.

New dependency: add ruamel.yaml to the daemon (currently PyYAML safe_load + model_validate).

Seam to #89 (this ticket blocks it)

The reconcile's "delete key on absence from snapshot" collides with advanced fields the editor does not expose (macros, media_http, previous_action, art_source, sensor config). Whether the client echoes those untouched or the reconcile preserves-on-absence is #89's policy call. This ticket delivers the mechanism; #89 decides the policy.

Note for #87 (editor interaction)

The round-trip is indifferent to the drag gesture — id-keyed matching handles reorder from any source (drag, up/down arrows, retyped list) at zero extra cost. So: (a) drag-vs-click is a free #87 choice; (b) but per ADR-0010 widget list order is grid position, so dropping reordering entirely means widgets can never be repositioned after creation — decide the gesture and whether repositioning is in v1. Also owns new-widget id generation (client-side, editable, backstopped by the uniqueness validator).

[jonocodes]

Resolved — see resolution comment. Round-trip strategy locked; unblocks #89.