overengineeringstudio / overengineeringstudio/effect-utils
notion-react: latent diff bugs — sibling blockKey collision + same-key type-change
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 82
- Forks
- 2
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 121
Description
Found during principal-engineer e2e review (packages/@overeng/notion-react/context/testing/e2e-review.md, commit a076493e). Two reachable correctness holes in src/renderer/sync-diff.ts:
1. Sibling blockKey collision (C1)
diffChildren builds cacheByKey as a plain Map keyed on instanceKey(inst, i). If two siblings share the same blockKey, one silently overwrites the other. No error, no warning, and the resulting op plan is non-deterministic relative to candidate order.
Reference: src/renderer/sync-diff.ts:160.
Options:
- Reject at
buildCandidateTreewith a typed error. - Document "last-wins" and add a dev-mode warning.
Either is defensible; today's behavior is neither.
2. Same-key type change (C2)
When a cached node and a candidate node share a key but differ in type (e.g. paragraph → heading_2), the diff currently emits:
{ kind: 'update', blockId: prior.blockId, type: cand.type, props: cand.props }
Notion's blocks.update does not support changing a block's type — the API will 400. The diff should detect prior.type !== cand.type and emit a remove + insert pair instead of an update.
Reference: src/renderer/sync-diff.ts:193-203.
Repro scenarios
No e2e tests exist for either case. See e2e-review.md §"Concrete test scenarios" for suggested fixtures (diff/key-collision, diff/type-change-same-key).
Scope
Page-renderer only; this issue does not affect database sync (out of scope for this library — use @overeng/notion-effect-client).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/renderer/sync-diff.ts, especially diffChildren around line 160 and same-key handling around lines 193-203. Read packages/@overeng/notion-react/context/testing/e2e-review.md and its Concrete test scenarios, then add coverage for diff/key-collision and diff/type-change-same-key. Done means sibling key collisions have an explicit supported behavior and same-key type changes produce remove plus insert rather than an invalid update.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100