computeLocalState throws "Expected localState to be present" when reading a hasMany after an inverse member is dematerialized

[pjcarly]

Version

• @warp-drive/core@5.8.2

Summary

Reading a hasMany relationship can throw an internal invariant error:

Error: Expected localState to be present

This happens when the relationship's edge in the graph has been left in the state { isDirty: false, localState: null }. Merely reading the relationship (materializing the related records) is enough to trigger it — the consumer does nothing unusual.

Where it throws

graph/-private.js, computeLocalState:

function computeLocalState(storage) {
  if (!storage.isDirty) {
    assert(Array.isArray(storage.localState)); // throws "Expected localState to be present"
    return storage.localState;
  }
  const state = storage.remoteState.slice();
  storage.removals?.forEach(v => { /* ... */ });
  storage.additions?.forEach(v => { /* ... */ });
  storage.localState = state;
  storage.isDirty = false;
  return state;
}

The function relies on the invariant: if an edge is isDirty === false, then localState must already be a materialized array. When isDirty is true, localState is (re)computed from remoteState + additions/removals and cached. But when isDirty is false, it assumes localState is already an array and asserts.

The failing edge violates this invariant: it is { isDirty: false, localState: null }. Because isDirty is false, the recompute branch is skipped and the assertion fires.

How the edge reaches { isDirty: false, localState: null }

The inconsistent state is observed after an inverse member of the relationship is dematerialized — for example when a route reloads its model and a record on the inverse side is unloaded/dematerialized. After this, the collection edge ends up flagged not-dirty but with a null (un-materialized) localState, so the next read of the relationship throws instead of recomputing.

So the bug is an internal graph-cache inconsistency: an edge is marked isDirty: false without localState having been materialized. Either:

• dematerializing an inverse member should not leave the edge as { isDirty: false, localState: null } (it should either keep localState materialized or mark the edge dirty so it recomputes), or
• computeLocalState should treat a null localState while not-dirty as needing recomputation rather than asserting.

Expected behavior

Reading a hasMany relationship should never throw an internal invariant error, regardless of inverse-side dematerialization. It should return the current local state (recomputing from remote state if necessary).

Actual behavior

Reading the relationship throws Expected localState to be present.

Reproduction sketch

We hit this from a rollback routine that recursively reads hasMany relationships after a route reloaded its model (which dematerialized an inverse member). A minimal repro would be roughly:

1. Load a parent record with a hasMany to children, where the children have an inverse belongsTo/hasMany back to the parent.
2. Materialize the relationship at least once.
3. Cause an inverse-side member to be dematerialized (e.g. unload it, or reload the route's model so the inverse record is dropped).
4. Read the parent's hasMany again → throws Expected localState to be present.

I'm happy to put together a runnable reproduction if that would help confirm the exact trigger.

Workaround

Guarding the read and skipping recursion works for us, because a separate cache-level relationship rollback still resets the edge to its remote state:

let children;
try {
  children = record[key]?.slice();
} catch {
  children = undefined;
}

But this only hides the symptom; the underlying graph state { isDirty: false, localState: null } is still inconsistent.

[pjcarly]

PR here: #10533

[runspired]

a reproduction of this is going to be necessary, but in general unloading a record without unloading its full graph is an "at your own risk" sort of dangerous operation, and it ending with this sort of result is expected.

(the reproduction is for me to assess whether this is a case where we by design expect to fail, or if there is a safe recovery here. In general there are very few cases where a relationship can safely recover from one side being unloaded)