[zxch3n]

Related issue

No linked issue. Same-repository investigation and review handoff.

Problem / pressure

A reported idle-night traffic spike requires separating network-error symptoms from mechanisms that repeatedly transfer full snapshots. Source inspection and bounded synthetic experiments found a reproducible incomplete-import recovery loop and a separate pending-update persistence gap; neither establishes the reporter's actual traffic source.

Summary

• Add one bilingual proposed investigation note covering snapshot uploads, disposable prefetch, cursor/reconnect behavior, sleep/proxy boundaries, incomplete-import recovery, and available diagnostics.
• Record the received-B/missing-A persistence reproduction, the pending-export contract, and the remaining storage/recovery responsibilities. Persistent pending-encoding errors must be surfaced during future integration while retaining the previous checkpoint.
• Preserve evidence limits: this PR changes documentation only. Lody/Streams integration and bounded-recovery changes remain proposals.

Related implementation PRs: Loro core #1220, FFI #17, website #54.

Visual explanation

flowchart LR
  B["Receive B while A is missing"] --> P["B remains pending"]
  P --> S["Ordinary snapshot excludes B"]
  P --> E["Export pending bytes separately"]
  E --> C["Persist snapshot and pending consistently"]
  C --> R["Restore both; import real A to apply B"]

Loading

The diagram explains the persistence boundary. A durable receive checkpoint is distinct from applied completeness and synchronization.

Before / after

Before	After
Investigation mechanisms and evidence limits were not recorded in this branch.	English/Chinese proposed notes make the verified mechanisms, unconfirmed incident attribution, and deferred implementation explicit.

Test plan

• pnpm run docs status: completed.
• pnpm run docs check: still reports 84 existing errors and 71 warnings; none references the new note, and no SHA-protected topic changes were reported.
• git diff --cached --check: passed before commit.
• pnpm check and pnpm format: attempted; this checkout has no installed workspace dependencies, so they stop on missing tsgo / oxfmt. No application-wide green-check claim is made.
• The note reports bounded synthetic SDK/Loro experiments performed during the investigation; these are mechanism evidence, not a production traffic capture. No product code or deployment changes are included.

Context handoff

This internal contribution prepares the complete investigation and the related core/binding/documentation changes for independent review on another computer. Review the linked PR heads rather than relying on previous completion summaries. Core #1220 has been rebased onto main 136b944f, retains the released Rust 1.16.2 fixes, and is verified at ed71753b7a689eb77097b54102b8e20b92444ef6. FFI review pins must retain that released baseline; publishing still requires a released core containing the API. No authoring transcript or private user payload is included.