---
id: value-diff-payloads
name: Value.Diff granular prop payloads
status: pending
depends_on: [value-hash-detection]
created: 2026-05-18T16:22:57.384875485Z
modified: 2026-05-18T16:22:57.384875927Z
scope: narrow
risk: medium
impact: component
level: implementation
---

# Description

Add `Value.Diff` to produce granular property-level diff payloads for `commitUpdate`. Instead of passing the full `prevProps` and `nextProps` to the host, `Value.Diff` identifies exactly which properties changed, allowing hosts to apply targeted updates.

This is the lowest-priority optimization per the architecture doc — "nice-to-have for hosts wanting granular updates." It's optional and the reconciler is correct without it.

**Critical constraint:** `Value.Diff` throws `ValueDiffError` on function values. Since `PropValue` includes functions, `Value.Diff` must either strip function props before diffing or catch the error and fall back to full replacement.

Implementation approach:
1. Before calling `Value.Diff`, strip function-valued props
2. Call `Value.Diff(cleanPrevProps, cleanNextProps)`
3. If `Value.Diff` throws (unexpected function somehow), catch and fall back to full `prepareUpdate`
4. Use the diff result as the payload for `commitUpdate`

## Acceptance Criteria

- [ ] `Value.Diff` imported from `@alkdev/typebox/value`
- [ ] Function-valued props stripped before `Value.Diff` call
- [ ] `ValueDiffError` caught and falls back to full `prepareUpdate`
- [ ] Diff result used as `commitUpdate` payload
- [ ] Hosts that don't need granular diffs can ignore the diff payload and use `prevProps`/`nextProps`
- [ ] Existing tests pass
- [ ] New test: `Value.Diff` payload contains only changed keys
- [ ] New test: function-valued props don't crash `Value.Diff` (stripped or caught)
- [ ] New test: diff error falls back gracefully to `prepareUpdate`

## References

- docs/architecture/reconciler.md — TypeBox Optimization Layer, Value.Diff row, Value.Diff on Functions
- docs/architecture/reconciler.md — Optimization Strategy (step 5, optional)
- docs/architecture/schema.md — PropValue includes functions

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion