feat: add mergeable containers (#759)

[typedrat]

Adds mergeable child containers, which are child containers that you can create under map keys that merge across peers instead of creating two separate containers. Closes #759.

const a = new LoroDoc(), b = new LoroDoc();
a.getMap("state").getMergeableCounter("revision").increment(1);
b.getMap("state").getMergeableCounter("revision").increment(1);
// after sync: one counter == 2, not two conflicting counters

They're available as getMergeable{Counter,Map,List,MovableList,Text,Tree} on LoroMap, in the loro, loro-internal, and WASM crates.

Problem

Right now, if two peers each create a child container at the same map key, they end up with two different containers, because the ContainerID is derived from the creating op's id. One of them wins and the other peer's edits are stranded on a container nobody looks at. That's a problem any time you want a single shared object regardless of who created it first - a revision counter, a settings sub-map, a shared text body, etc.

Approach

A mergeable child is a ContainerID::Root with a deterministic name derived from (parent, key, kind), in a reserved "🤝:" namespace. Both peers compute the same id, so they're talking about the same container.

Which child is "live" is decided by the parent map slot, not by separate bookkeeping. When you call getMergeable*, the parent map stores a "🤝:<kind>" discriminator string at that key, and the active child is just whatever that key's normal LWW resolves to. Letting the existing map machinery own this gets us a few things mostly for free:

• Delete is just clearing the key (an ordinary MapSet { value: None }). No new op types, and no tombstone tracking to keep in sync.
• If two peers pick different kinds for the same key, the map's LWW picks the winner like it would for any value. The loser's container is still reachable by its deterministic name if you ask for that kind again.
• Asking for a different kind under an existing key overwrites the discriminator. The previous kind's contents stick around and come back if you request that kind later.
• Snapshots don't need anything special - the discriminator travels like any other map value. The only thing rebuilt on import is the in-memory parent-edge index.

Commits

I split this into 6 commits by layer, each one carrying its own tests:

1. feat(common) - cid namespace + discriminator encode/parse helpers
2. feat(internal) - core mergeable state in DocState
3. feat(internal) - get_mergeable_* handler API
4. feat(loro) - public LoroMap wrappers
5. feat(wasm) - getMergeable* bindings
6. test(fuzz) - opt-in mergeable fuzz surface

There's also a trailing chore: commit with the changeset.

Compatibility

This is all new methods - no existing signatures change, so it shouldn't break anyone. Root names that start with the "🤝:" prefix are rejected by check_root_container_name so user code can't fabricate one.

Testing

57 tests across the internal (43), public-API (8), and cid-encoding (6) targets, plus a WASM suite in mergeable.test.ts that covers each kind and the subscription-flush invariant from AGENTS.md. There's also an opt-in fuzz target (cargo +nightly fuzz run mergeable); the fuzz crate builds with and without the mergeable feature.

Between them they cover concurrent same- and different-kind creation, three-peer convergence, delete + recreate, snapshot/update import round-trips, event and path resolution, and has_container for mergeable cids.

AI usage disclosure

Most of the lines in this PR were written by an AI coding assistant (Claude Opus 4.7, primarily). I want to be upfront about that, and equally upfront that the engineering wasn't outsourced. I read every diff and handled every non-trivial engineering decision myself, although I did regularly seek the advice of the agent during the process.

So: the assistant did most of the typing, I did the deciding and the reviewing. I've reviewed the whole change and I stand behind its correctness; treat it as my work and review it as critically as you would anything else.

[typedrat]

Fuzzed via cargo +nightly fuzz run all --features fuzz/mergeable -- -max_total_time=86400 -fork=192 -rss_limit_mb=4096 -ignore_crashes=1 -ignore_ooms=1 -ignore_timeouts=1 on a 192-core c8g.metal-48xl instance. 24h, 402.7M executions, 0 crashes/OOMs/timeouts, final coverage 32,236 edges (saturated).

[zxch3n]

P1: Invalidate deleted-cache entries when a mergeable child becomes active again

A mergeable child can become reachable again after it was previously deleted.

Example flow:

1. get_mergeable_counter("revision") creates/activates mergeable cid X.
2. delete("revision") clears the discriminator, so X becomes unreachable.
3. Mutating an old handle to X correctly fails and may cache X as deleted.
4. Calling get_mergeable_counter("revision") again writes the discriminator back, so X is reachable again.
5. In release builds, is_deleted() may still trust the old deleted-cache entry and keep treating X as deleted.

When sync_mergeable_side_table_for_op() registers an active mergeable cid, it should invalidate the corresponding deleted-cache entry, or conservatively clear the whole dead_containers_cache.

P1: Clarify or restrict get_mergeable_* overwriting existing non-mergeable values

get_mergeable_* currently writes a 🤝:<kind> discriminator into the parent map slot. That means if the key already contains a normal scalar value or a normal child container, the call silently overwrites it.

That behavior may be intentional, but the name get_mergeable_* makes it easy to read this as a harmless “get or create if empty” API.

I think this should be made explicit in one of these ways:

• Return ArgErr when the key already contains a non-mergeable value.
• Rename the API to something that signals mutation/overwrite semantics, such as ensure_mergeable_* or set_mergeable_*.
• At minimum, document clearly that this call may overwrite the existing map slot with a mergeable discriminator.

P2: Do not treat every 🤝: root name as a valid mergeable container

If the intended semantics are:

Users may create root names starting with 🤝:, but only names that successfully parse as the mergeable encoding should be treated as mergeable containers.

then is_mergeable() should not be implemented as a simple prefix check.

A root name like 🤝:not-valid-hex or 🤝:abc should remain a normal root container, not a half-valid mergeable container with missing parent/key metadata.

Suggested direction:

pub fn is_mergeable(&self) -> bool {
    self.parse_mergeable().is_some()
}

or at least make all critical code paths distinguish between “has the mergeable-looking prefix” and “is a valid parsed mergeable cid”.

P2: Reject 🤝:Unknown(n) discriminators

parse_mergeable_discriminator() should reject 🤝:Unknown(n).

The discriminator controls which child kind is active under a map key. Unknown(_) does not have a valid user-facing mergeable-container behavior here, and downstream code may hit unreachable/default-value paths for unknown container types.

The parser should only accept supported concrete kinds:

Map, List, MovableList, Text, Tree, Counter

and explicitly reject Unknown(_). A small regression test for 🤝:Unknown(7) would be enough.

[zxch3n]

Snapshot import does not need to scan/decode every Map to rebuild mergeable parent edges.

For mergeable children that have state entries, the mergeable root cid already encodes (parent, key, kind). We can discover those candidates by scanning container ids for valid 🤝:<hex> mergeable cids, then only verify the corresponding parent map slot still contains the matching discriminator.

The current implementation instead walks all Map containers and reads every Map's shallow value. That is much broader than necessary.

One subtle case is unmutated mergeable children: they may only exist as a discriminator in the parent map and may not have a child state entry yet. If we need those to have side-table entries immediately after snapshot import, then scanning discriminators is one way to find them. But that could also be handled lazily when the child is accessed or when path/reachability is queried.

So I think the import-time recovery should avoid iter_all_container_ids() -> load_all() and either:

• rebuild from valid mergeable root cids plus targeted parent-slot verification, or
• make mergeable side-table reconstruction lazy.

[zxch3n]

It's an awesome PR overall. I can push the fixes that address these comments directly to this branch if you want