overengineeringstudio / overengineeringstudio/effect-utils

notion-react: latent diff bugs — sibling blockKey collision + same-key type-change

Open
#595 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

origin:agent type:bug
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 buildCandidateTree with 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. paragraphheading_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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.