MessageRepository Branch Pointer Invariant#

MessageRepository is the branching message-tree data structure at the core of assistant-ui threads. Every node is a RepositoryMessage with three pointer fields:

• prev — parent node (null at root)
• next — currently-selected child (null for leaf nodes)
• children — ordered list of all child IDs

The active thread is the path from root.next to the leaf found by following next pointers; head always points to that leaf 1.

The invariant: Every next pointer on the path from root to head must point toward head. For each node n on that path, n.next must be the child that is an ancestor-or-equal of head. If any pointer on that path diverges to a sibling branch, findHead() and getMessages() return inconsistent results — findHead follows next pointers forward from any node, while getMessages walks prev pointers backward from head 1.

The private selectPathTo(message) method is the canonical way to repair ancestor pointers: it walks the full prev chain from the target message back to the root, setting each ancestor's next toward the target 2.

switchToBranch — Stale Ancestor Pointers (pre-PR #6978)#

The classic stale-pointer bug: switchToBranch previously updated only the immediate parent's next pointer before setting this.head. Every ancestor above that parent retained their old next, pointing at whatever branch was active before the switch.

Reproduction: Tree r → a → x and r → b → y. Switch to y (so r.next = b, b.next = y). Then call switchToBranch("r"). The root's next was still a (stale), so findHead(root) returned x, not y. getMessages() returned [r, a, x] instead of [r, b, y] 1.

PR #6978 fixed this by delegating to selectPathTo, which walks the full ancestor chain on every switchToBranch call 3. The regression test is "keeps a nested branch selected when revisiting its ancestor" 1.

resetHead — Descendant Eviction + Ancestor Repair#

resetHead(messageId) truncates the tree to a given node. It must handle two concerns:

1. Descendant eviction — all children and their descendants are deleted from this.messages, and message.children / message.next are set to null 4. Without this, dangling children linger and can be accidentally resurrected via switchToBranch.

2. Ancestor pointer repair — after truncation, selectPathTo(message) is called to walk the full prev chain and update every ancestor's next toward the new head 5. This mirrors the switchToBranch fix and prevents stale pointers when resetHead targets a non-leaf node.

Regression test: "keeps the selected root branch when deletion selects from the root" 1.

performOp / relink — Partial Repair Only#

performOp handles link, cut, and relink. For cut and relink, if the removed child was the parent's current next, the parent falls back to the last remaining sibling 6. This only fixes the direct parent. Any ancestor that pointed toward the removed node through that parent remains stale. Callers that relink a message mid-chain must subsequently call switchToBranch or resetHead to repair higher ancestor pointers 1.

For link, performOp calls selectPathTo only when the new child's subtree contains the current head 7 — this prevents silently hijacking the active branch when a sibling is appended.

Other Invariants#

Related PRs & Bug History#