---
id: key-matching-algorithm
name: Key-based old↔new child matching
status: pending
depends_on: [review-reactive-host-bridge]
created: 2026-05-18T16:22:57.216123897Z
modified: 2026-05-18T16:22:57.216124341Z
scope: narrow
risk: medium
impact: component
level: implementation
---

# Description

Implement the key-based matching algorithm that maps old children to new children by `key` field. When the tree structure changes (children added, removed, reordered), positional matching is insufficient — it would destroy and recreate instances instead of moving them.

This algorithm builds two maps from the old and new child lists:
- `oldKeyMap`: `Map<key | null, Fiber>` — old children keyed by their `key` field (positional fallback for `null` keys)
- New children are classified as: matched (key exists in old), added (new key), removed (old key not in new)

For matched children:
- Same type: will reconcile props (same as Step 2)
- Type changed: remove old + insert new

Unkeyed children (key = undefined) fall back to positional matching.

## Acceptance Criteria

- [ ] `reconcileChildren` function implemented in `src/host/reconcile.ts`
- [ ] Builds `oldKeyMap` from existing fiber children
- [ ] Classifies new children into matched, added, removed sets
- [ ] Matched children with same type → flag for prop reconciliation
- [ ] Matched children with different type → old removed, new inserted
- [ ] Unkeyed children (key = undefined) use positional matching fallback
- [ ] Duplicate keys: warn and use last-wins (per ADR-004 consequences)
- [ ] Pure function — no side effects, returns classification for downstream use
- [ ] New test: keyed children reordered → matched correctly by key
- [ ] New test: keyed child added at start → old children matched, new child added
- [ ] New test: keyed child removed → classified as removed
- [ ] New test: mixed keyed and unkeyed children → key-based for keyed, positional for unkeyed
- [ ] New test: duplicate key → last-wins, no crash

## References

- docs/architecture/reconciler.md — Step 3 (Reconcile Children, Key-Based)
- docs/architecture/decisions/004-key-as-first-class-field.md — ADR-004, duplicate key behavior

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion