fix(apollo-forest-run): tolerate divergent null/object node chunks during update

[vladar]

Summary

Relaxes an overly strict invariant that caused Invariant violation during cache.write:

Invariant violation: Failed to update "<query>" at path <field>: expected CompositeNull, got ObjectDifference
Invariant violation: Failed to update "<query>" at path 0: expected CompositeUndefined, got ObjectDifference

Root cause

A normalized node can end up with two chunks for the same position (a field or a list item): one where it is a real embedded object/list and another where it is an explicit null (CompositeNull) or missing (CompositeUndefined). This happens with aliased selections, a repeated node id in a single write, or a partial/errored write.

A later write produces a single ObjectDifference/CompositeListDifference, which updateAffectedTrees → updateTree → resolveAffectedChunks applies to every chunk of the node. On the null/missing chunk, updateValue hits assert(isObjectValue(base)) / assert(isCompositeListValue(base)) and throws. The pre-existing "inconsistent state" guard only covered missing field values (isMissingValue on undefined) — not explicit nulls, and not list items at all (list items reach updateValue via updateCompositeListValue without any guard).

Fix

Consolidated the tolerance into updateValue: when an ObjectDifference/CompositeListDifference is applied to a base that is CompositeNull or CompositeUndefined, the chunk is skipped (left unchanged) and a descriptive warn is logged — for both field and list-item locations. Genuine type mismatches (leaf null, scalars, complex scalars) still assert.

The warn is at least as descriptive as the previous invariant and adds actionable advice, e.g.:

Skipping update for "<query>" at path <field> (in <Type>): field is an explicit null
(CompositeNull) in this chunk, but the incoming ObjectDifference expects a composite
object; the node has divergent chunks for this field (null in one, object in another).
Leaving the null value unchanged. This usually means the same node was written with
conflicting values in a single operation (e.g. aliased selections or a repeated node id)
or via a partial/errored write; ensure such selections resolve this field consistently.

Incorporates #689 (full data path in invariant/diagnostic messages)

Merged #689, which reports the full data path (not just the last field/index) when the failing value is a non-addressable CompositeNull/CompositeUndefined — deriving the path from the parent chunk. This benefits both the remaining genuine-mismatch invariants and the new divergent-null warning above, which now also carries the full path (e.g. listContainer.items.0.value (in Entity)). #689's message builders are wrapped defensively so path resolution never throws over the invariant being reported.

Since this PR relaxes the very invariant #689's nested-CompositeNull test asserted, that test was updated to reflect the new behaviour: the divergent-null case no longer throws — it logs a warning that still contains the full path.

Tests

• regression.test.ts — three tests (public ForestRun API only): divergent null/object at a field via aliases, via a repeated node id in a list, and at a list-item position.
• updateObject.test.ts — full path is reported for a nested non-addressable value; the divergent-null warning carries the full path without throwing; and the message builder degrades gracefully (still surfaces the invariant) when findParent throws.

Validation

• yarn test:own — 25 suites / 1099 tests pass
• yarn types — clean
• yarn lint — 0 errors (only pre-existing warnings)

[github-actions]

📊 Benchmark Analysis Report

✅ No significant performance changes detected

---

Threshold: 5% change

---

Updated: 2026-07-13T14:58:35.171Z