Patch-based AI edits for dashboard YAML

Problem

When AI refines an existing dashboard, it currently regenerates the entire YAML file. This has three problems:

1. Token waste: A 200-line dashboard YAML costs ~800 tokens to regenerate even if the edit is a single field change.
2. Error-prone: Full regeneration risks unintended changes — the LLM might silently drop a query, rename a variable, or reorder charts.
3. Merge conflicts: In multi-agent or collaborative workflows, full-file rewrites create unnecessary merge conflicts. A surgical patch to one chart wouldn't conflict with a patch to another.

json-render (Vercel Labs, 12k+ stars) solved this with three edit modes for multi-turn spec refinement: RFC 6902 JSON Patch, RFC 7396 JSON Merge Patch, and unified diff. Their system auto-selects the mode based on edit complexity. See ai_notes/research/json-render-deep-dive.md.

Context

• Research origin: ai_notes/research/json-render-deep-dive.md — Priority 2 section. Inspired by Vercel's json-render edit modes (RFC 6902/7396/unified diff).
• Current AI integration: dataface/ai/ — MCP server, prompts, tools
• YAML compilation: dataface/core/compile/ — normalizer is source of truth
• Cloud editor: apps/cloud/ — live YAML editing with htmx
• YAML is nested (rows > charts > encodings), unlike json-render's flat element trees — this affects which patch strategies work well
• Related task: streaming-yaml-generation-with-early-query-execution.md — streaming generation would pair naturally with patch-based edits

Possible Solutions

A. YAML-native merge patches (deep dict merge)

Define a simple merge-patch format in YAML itself:

# Merge patch: add color encoding to revenue chart
charts:
  revenue:
    color: region

Apply via deep merge (RFC 7396 semantics: null deletes, objects recurse, scalars replace). The AI outputs only the diff fragment, not the full file.

Pros: Simple, YAML-native, easy for LLMs to generate, human-readable. Cons: Can't express array insertions, reorderings, or deletions of non-null fields cleanly.

B. JSON Patch (RFC 6902) over compiled YAML

Use RFC 6902 patch operations targeting YAML paths:

[
  {"op": "add", "path": "/charts/revenue/color", "value": "region"},
  {"op": "remove", "path": "/queries/old_query"}
]

Pros: Full expressiveness (add, remove, replace, move, copy, test). Well-specified standard. Cons: JSON Patch paths don't map perfectly to YAML (arrays are index-based). More verbose for LLMs to generate. Less human-readable.

C. Unified diff on YAML text Recommended

AI generates a unified diff against the current YAML:

 charts:
   revenue:
     type: bar
     x: month
     y: revenue
+    color: region

Apply with standard diff/patch tooling or a simple Python patcher.

Pros: LLMs are very good at generating diffs. Human-readable. Handles any edit type. Familiar to developers. Works with existing diff/patch tooling. Cons: Fragile if the base YAML has been modified since the diff was generated (context mismatch). Requires line-level precision from the LLM.

D. Hybrid: merge for simple edits, diff for complex ones

Use merge patches (A) for single-field additions/changes. Fall back to unified diff (C) for structural changes (reordering rows, adding new sections). The AI prompt instructs the LLM which mode to use based on edit complexity.

Pros: Best of both worlds — simple edits stay simple, complex edits stay expressive. Cons: Two code paths to maintain. AI must choose correctly.

Plan

1. Define the patch representation and the classes of dashboard edits it needs to support first.
2. Design the apply-and-validate loop, including schema validation, conflict handling, and fallback to full regeneration when a patch cannot be trusted.
3. Wire the patch path into one editing surface and compare its cost, diff quality, and failure modes against full regeneration.
4. Add focused tests for common edits, conflicting changes, and invalid patch output before broadening the feature surface.

Implementation Progress

Review Feedback

• [ ] Review cleared