whiteboard: Skill for Claude Code

Using loro-crdt in this repo

Loro is where this project's data actually lives, and its failure mode is the worst kind: a wrong container choice loses data with no conflict, no error, and both replicas agreeing on the truncated result. Nothing goes red. The loss is found, if ever, by a person noticing their reply is gone.

So the rule here is the repo's rule everywhere else, sharpened: a claim about Loro is worth what its measurement is worth. The version is pinned in pnpm-workspace.yaml (loro-crdt: "1.13.6"), the API has changed under this repo more than once, and loro.dev is not reachable from this environment anyway. What IS reachable and authoritative is shipped inside the package — see "Where the answers actually are" below.

The rule: a lazily-created child container must be mergeable

map.getOrCreateContainer(key, new LoroMap()) mints a regular op-id child. Two replicas that each open the same key having never seen the other's end up with two containers, and the map's conflict resolution keeps one and hides the other.

Measured on 1.13.6 — two peers, no common ancestor for the key, each writing one entry:

opened with	both replicas read
getOrCreateContainer	{"fromB": "reply B"}
ensureMergeableMap	{"fromA": "reply A", "fromB": "reply B"}

Same for ensureMergeableText ("ab" vs "b") and ensureMergeableMovableList (["A","B"] vs ["B"]).

loro-crdt says so itself. 1.13.0's changelog: "getOrCreateContainer is deprecated for lazy map-child creation; migrate those call sites to ensureMergeable*." A mergeable child lives at a deterministic ContainerID derived from (parent, key, kind), so the two peers were editing one container all along.

Use openMergeableMap / openMergeableText / openMergeableMovableList from packages/loro-adapter/src/mergeable-containers.ts, never the raw method. Four things the helper exists for, each measured:

1. ensureMergeable* THROWS on a key that already holds a non-mergeable value — Cannot create a mergeable Map at key "k": the key already holds a non-mergeable value. That is every document written before the helper landed, so a bare swap breaks stored data. The helper takes the mergeable branch only for an ABSENT key and leaves an occupied one exactly as it was, which is what makes this safe with no migration.
2. They live on LoroMap alone. Not on LoroList, LoroMovableList or LoroTree — which is the shape of the problem, not an omission: a list position is already a unique op, so only a map KEY needs two peers to agree on which child it names.
3. A mixed pair still loses one side. One replica opening the key the old way while another opens it mergeable converges on the mergeable one. The fix removes the hazard for containers created from here on; it cannot repair a fork that already happened.
4. getOrCreateContainer reading a container ensureMergeable* created is fine, so a reader on an older code path is not broken by the switch.