## TL;DR

The agent patched the field list and broke the sync mapping (wrong names, dropped fields). Version every mapping, diff the patch against the live mapping before applying, and keep the last known good version for instant rollback. Mapping edits are deployments, not tweaks.

## Error

```text
Sync error: mapping references unknown field; 12 fields dropped from sync after mapping update.
```

## Steps

1. Roll back to the last known good mapping version immediately. Expected: the sync recovers.
2. Diff the bad patch against the good version. Expected: you see exactly what the patch changed.
3. Fix the patch: correct names, restore dropped fields. Expected: a clean diff.
4. Validate the fixed mapping in a dry run or sandbox before applying. Expected: no surprises.
5. Store mappings in version control with change history going forward. Expected: every future patch is reviewable and reversible.

## When to use

- A mapping edit breaks the sync.
- An agent auto-updates field lists.
- After a bad deploy of mapping changes.

## When not to use

- Salesforce schema changes (re-describe, different fix).
- Initial mapping creation.

## Tool compatibility

- Any sync tool with field mappings; version control.
- Dry-run validation.

## Variant phrasings

### mapping update broke sync

Roll back, diff, fix, validate.

### fields dropped after patch

The patch rewrote the list instead of merging.

## Why it happens

Field lists are edited as whole blobs; a patch that regenerates the list from a stale schema silently drops fields added since. Without versioning, there is no diff and no rollback.

## Edge cases

- Patches must merge with the live mapping, never replace it wholesale.
- Validate field existence against describe before applying any patch.
- Alert on mapping changes; silent auto-patches hide breakage.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Nk5bgskSvGpqS0bUOAe80g