test(realtime): close lifecycle and recovery coverage

include/paimon/file_store_write.h

@@ -100,6 +100,10 @@ class PAIMON_EXPORT FileStoreWrite {
     /// @param commit_identifier Identifier of this prepare-commit operation in streaming mode.
     /// @return Real-time commit messages with their partition-bucket offset ranges.
     /// @note Calling this method on a non-real-time writer or in batch mode returns an error.
+    /// @note If a write or prepare-commit fails after its in-memory effects may have changed, the
+    ///       caller must discard the writer and `RealtimeContext`, recreate both from the latest
+    ///       committed snapshot, and replay the uncommitted mutations from an external WAL. The
+    ///       real-time store is not a durable WAL and the failed writer must not be reused.
     virtual Result<std::vector<RealtimeCommitProgress>> PrepareCommitWithProgress(
         int64_t commit_identifier);
 

include/paimon/realtime/realtime_context.h

@@ -74,6 +74,10 @@ using RealtimeOffsetMap = std::map<RealtimePartitionBucket, int64_t>;
 /// applications. Customize real-time storage and retrieval through `RealtimeStoreFactory` and
 /// `RealtimeStore` instead.
 ///
+/// A context belongs to one table and branch and supports one active `FileStoreWrite`. Do not
+/// reuse it for another table or branch, or concurrently from multiple active writers. Share that
+/// same context with the table's scan and read contexts so process-local rows remain visible.
+///
 /// A context is valid only for one uninterrupted committed-progress history. Overwrite, truncate,
 /// partition drop, and rollback operations do not automatically clear process-local real-time
 /// state. Applications must coordinate these operations with active real-time writers and recreate