---
id: commit-mutations
name: Commit insert/move/remove effects in tree order
status: pending
depends_on: [lis-move-detection]
created: 2026-05-18T16:22:57.246628537Z
modified: 2026-05-18T16:22:57.246628975Z
scope: moderate
risk: high
impact: phase
level: implementation
---

# Description

Implement the commit phase that applies all pending effects (insert, move, remove, update) to the host in the correct order. This is where fiber effects become host mutations.

The commit order matters for host correctness:
1. **Removes** — reverse order (children before parents, bottom-up)
2. **Inserts + Moves** — left-to-right using `insertBefore` or `appendChild`
3. **Updates** — top-down (parent before child, so parent state is consistent)

This task also creates new fibers for inserted children (via `mountNode`-style recursive creation) and updates the fiber tree structure after commit.

`commitMutations` is called after the reconciliation algorithm has classified all changes and queued effects on fibers. It walks the fiber tree and applies effects in the specified order.

## Acceptance Criteria

- [ ] `commitMutations(rootFiber, ctx)` function implemented in `src/host/reconcile.ts`
- [ ] Removes committed in reverse order (children before parents)
- [ ] `host.removeChild(parent, child, ctx)` called for each removal
- [ ] Inserts committed left-to-right, using `host.appendChild` or `host.insertBefore`
- [ ] New fibers created for inserted children, linked into parent's children array
- [ ] Moves committed left-to-right using `host.insertBefore(parent, child, before, ctx)`
- [ ] Updates committed top-down (parent before child) via `host.commitUpdate`
- [ ] Fiber tree is updated after commit: new children added, removed children pruned, moved children reordered
- [ ] Order guarantee: removes → inserts/moves → updates
- [ ] Existing tests pass
- [ ] New test: adding a child calls `host.appendChild`
- [ ] New test: removing a child calls `host.removeChild`
- [ ] New test: reordering children calls `host.insertBefore` for moved children
- [ ] New test: mixed add+remove+update operations apply in correct order
- [ ] New test: `insertBefore` falls back to `appendChild` if `before` is null

## References

- docs/architecture/reconciler.md — Step 3 (commit order), Step 4 (Commit Effects), Effect Types
- docs/architecture/host-config.md — insertBefore, removeChild, appendChild

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion