fix(loro.js): drop containers deleted before the shallow root, keep tree node metadata

.changeset/loro-js-shallow-deleted-containers.md

@@ -0,0 +1,5 @@
+---
+"loro.js": patch
+---
+
+Shallow snapshots exported by `loro.js` no longer contain containers deleted before the shallow root, such as a map child removed before the cut. Before, every container ever created was written to both the root state and the latest state. Tree node metadata is still kept for all nodes, including deleted ones, because a later move can revive such a node, and every mergeable child is kept, because re-ensuring it after its marker was deleted or replaced shows its state again. Re-exporting an older blob at its own root also drops these containers.

context/internal-encoding.md

@@ -164,6 +164,18 @@ regressions are `cached_root_*` unit tests in `shallow_snapshot.rs`.
 `crates/loro/tests/perf_shallow_reexport.rs` is the ignored release benchmark
 for first and repeated re-export and import.
 
+The pure TypeScript runtime (`loro-js`) uses the same retention rule when it
+rebuilds both states in `LoroDoc.#encodeShallowSnapshot`. The root state keeps
+`#retainedContainerKeys()` at the root: root containers (every mergeable
+container is one, as in Rust's `existing_retention_roots`, so a child hidden by
+a deleted or different-kind marker keeps its state), visible Map/List children,
+and every tree node's meta, including deleted nodes. The latest state
+additionally keeps containers alive at the latest version and containers whose
+creation id the root version does not include. `loro-js` always rebuilds the
+root state by replay instead of reusing its cached root store, so re-exporting
+an older blob at the same root also prunes it (the #1123 case). Tests are in
+`loro-js/tests/shallow-snapshot-deleted-containers.test.ts`.
+
 Two import-side pieces support revived tree nodes. `TreeOpGroup::record_shallow_root_state`
 seeds the tree diff cache with deleted nodes as well (directly deleted as
 `Delete`, their descendants as `Create` under their real parent); with only

context/mergeable-containers.md

@@ -174,7 +174,8 @@ flushed KV entry; the shallow alive walk retains them explicitly). An
 ensured-but-empty mergeable child has no KV entry of its own: full export omits
 it and importers resolve it from the parent map's marker. This is covered by
 `tests/mergeable_container/snapshot.rs`, including shallow snapshot tests for
-losing-kind state.
+losing-kind state. loro.js follows the same rule in `#retainedContainerKeys`
+(`loro-js/tests/shallow-snapshot-deleted-containers.test.ts`).
 
 Raw marker bytes are the wire/storage representation. Public read and diff
 surfaces should translate an active marker to a container value. APIs that expose

loro-js/src/runtime/document.ts

@@ -6302,13 +6302,25 @@ export class LoroDoc<T extends Record<string, Container> = Record<string, Contai
     const latestFrontiers = this.#frontiersForVersion(latestVersion);
     const restoreVersion = this.version();
 
+    // Only containers a retained op can still reach are exported; content
+    // deleted before the root must not survive in either state section.
+    // See context/internal-encoding.md (shallow snapshot retention set).
     // The root state of a container that loro.js cannot replay is its replay
     // (as without snapshot states): its snapshot state is at a later version
     // and cannot restore what was deleted before it.
     this.#rebuildFromHistory(rootVersion, restoreVersion, true);
-    const rootStore = this.#buildStateStore(startFrontiers);
+    const rootRetained = this.#retainedContainerKeys();
+    const rootStore = this.#buildStateStore(startFrontiers, rootRetained);
     this.#rebuildFromHistory(latestVersion, rootVersion);
-    const latestStore = this.#buildStateStore();
+    const latestRetained = this.#retainedContainerKeys();
+    for (const key of rootRetained) latestRetained.add(key);
+    for (const [key, container] of this.#containers) {
+      const id = container._codecId;
+      if (id?.kind === "normal" && id.counter >= (rootVersion.get(id.peer) ?? 0)) {
+        latestRetained.add(key);
+      }
+    }
+    const latestStore = this.#buildStateStore(undefined, latestRetained);
     if (restoreVersion.compare(latestVersion) !== 0) {
       this.#rebuildFromHistory(restoreVersion, latestVersion);
     }
@@ -6420,11 +6432,59 @@ export class LoroDoc<T extends Record<string, Container> = Record<string, Contai
       : undefined;
   }
 
-  #buildStateStore(frontiers?: readonly CodecId[]): StateSnapshotStore {
+  /**
+   * Containers reachable from the root containers in the current state. As in
+   * Rust, every mergeable container is a root too: its deterministic ID
+   * survives a deleted or replaced marker, and re-ensuring the same kind shows
+   * its state again. Tree node metadata is followed for every node, including
+   * deleted ones: a retained move can revive a deleted node together with its
+   * old metadata. Deleted Map and List children are not followed; re-inserting
+   * one creates a new container ID.
+   */
+  #retainedContainerKeys(): Set<string> {
+    const retained = new Set<string>();
+    const pending: LoroContainer[] = [];
+    const visit = (container: LoroContainer): void => {
+      const id = container._codecId;
+      if (id === undefined) return;
+      const key = this.#containerKey(id);
+      if (retained.has(key)) return;
+      retained.add(key);
+      pending.push(container);
+    };
+    for (const container of this.#containers.values()) {
+      if (container._codecId?.kind === "root") visit(container);
+    }
+    for (
+      let container = pending.pop();
+      container !== undefined;
+      container = pending.pop()
+    ) {
+      if (container instanceof LoroMap) {
+        for (const record of container._entries.values()) {
+          if (!record.deleted && record.value instanceof LoroContainer)
+            visit(record.value);
+        }
+      } else if (container instanceof LoroList) {
+        for (const element of container._visibleElements()) {
+          if (element.value instanceof LoroContainer) visit(element.value);
+        }
+      } else if (container instanceof LoroTree) {
+        for (const record of container._nodes.values()) visit(record.data);
+      }
+    }
+    return retained;
+  }
+
+  #buildStateStore(
+    frontiers?: readonly CodecId[],
+    retained?: ReadonlySet<string>,
+  ): StateSnapshotStore {
     const containers: StateSnapshotContainerEntry[] = [];
     for (const container of this.#containers.values()) {
       const id = container._codecId;
       if (id === undefined) continue;
+      if (retained !== undefined && !retained.has(this.#containerKey(id))) continue;
       const parent = container.parent()?._codecId;
       containers.push({
         id,