Inconsistent failure behavior: revert silently skips bad targets while diff/items throw

[maxjay]

Problem

The keyed-array APIs disagree on what to do when something is wrong:

• diff() and items() throw on contract violations (duplicate identities, items missing the key field) — buildIdentityMap in src/engine.ts.
• revert() silently skips targets it cannot apply:
  • a target resolvable in neither base nor draft,
  • a deleted field whose remainder crosses an identity segment (the keyed element itself is gone),
  • a ghost whose parent array no longer resolves in draft.

The skip semantics are intentional (reverting the missing ancestor is the right tool, and a revert that throws halfway through a multi-target plan would be worse), but:

1. The inconsistency between APIs is undocumented — revert's skip behavior appears nowhere in the README or docs/engine.md.
2. A caller has no way to know a target was skipped (no return value, no error, nothing on the recorded op).

Possible directions

• Document the skip semantics (minimum bar).
• Have revert() return a summary (e.g. counts or the canonical paths applied/skipped) so callers can surface "couldn't revert X".
• Align error-message conventions across diff: / items: / revert: prefixes while at it.

Origin: self-review finding #4 on the identity-paths change set (0.13–0.15, branch claude/practical-shannon-jr19ie).