docs: correct DM payload, history and transfer cancellation contracts

src/dm/dm_core.h

@@ -80,7 +80,8 @@ int dm_start(struct UTUN_INSTANCE* inst, uint64_t peer_node_id,
 /* Отправить сообщение в беседу. Шифрует, подписывает, сохраняет локально и
  * доставляет (прямое соединение при доступности пира, иначе mailbox).
  * conv_id — строковое представление (как в dm_conversations.conv_id).
- * Для ct="file" data=[descriptor:56][basename:utf8], только после подготовки dm_media.
+ * Для ct="file" data=[descriptor:56][attachment_info в формате attachment_encode()], после подготовки dm_media.
+ * Descriptor подписывается открыто, метаданные вложения шифруются; формат — media_async/attachment.h.
  * Для ct="invite" data=[group_name:utf8][NUL][полная ссылка:utf8], без завершающего NUL.
  * Имя и ссылка шифруются и подписываются вместе; GUI получает data=ссылка, tags.group_name=имя. */
 int dm_send(struct UTUN_INSTANCE* inst, const char* conv_id, const char* content_type,
@@ -94,8 +95,11 @@ void dm_cancel_pending_history(struct UTUN_INSTANCE* inst, const char* conv);
 /* Список бесед в JSON: [{conv_id,peer_node_id,peer_name,last_ts,out_seq,in_seq}] */
 int dm_list_conversations_json(struct UTUN_INSTANCE* inst, char* buf, size_t buf_size, size_t* out_len);
 
-/* Сообщения беседы в JSON (расшифрованные): [{dir,seq,ts,author,ct,data}]
- *  count=0 → все, offset=0 → с начала. */
+/* Сообщения беседы в JSON: расшифрованное содержимое, статусы доставки и медиа.
+ * count=1..200 задаёт предел; count<=0 или count>200 означает 200.
+ * offset>=0 отсчитывается от новых сообщений; offset=0 выбирает последние count.
+ * Выбранная страница возвращается по возрастанию ts, seq, dir.
+ * buf — выходной буфер с NUL; 0 и *out_len байт без NUL при успехе, -1 при ошибке. */
 int dm_list_messages_json(struct UTUN_INSTANCE* inst, const char* conv_id, int count, int offset,
                           char* buf, size_t buf_size, size_t* out_len);
 

src/media_delivery/file_transfer.h

@@ -20,7 +20,8 @@ typedef int (*file_transfer_lookup_fn)(void* arg, uint64_t group, uint64_t peer,
 typedef void (*file_transfer_done_fn)(void* arg, int error);
 
 /* 0 в done означает точный приём size байт и закрытие файла, а не custody ACK.
- * Возврат NULL означает отказ запуска, done не вызывается. cancel вызывает done(-2).
+ * Возврат NULL означает отказ запуска, done не вызывается.
+ * cancel синхронно вызывает done(-2); ошибка fclose заменяет результат на -1, в том числе при отмене.
  * Handle перестаёт существовать перед вызовом done, его нужно обнулить в callback. */
 struct file_transfer* file_transfer_create(struct UTUN_INSTANCE* inst, file_transfer_lookup_fn lookup, void* arg);
 void file_transfer_destroy(struct file_transfer* ft);
@@ -28,7 +29,7 @@ struct file_transfer_op* file_transfer_pull(struct file_transfer* ft, uint64_t g
                                            const uint8_t object[16], uint64_t size, const char* destination,
                                            file_transfer_done_fn done, void* arg);
 void file_transfer_cancel(struct file_transfer_op* op);
-/* Отозвать все операции объекта (TTL/delete); callbacks приёма вызываются с -2. */
+/* Отозвать все операции объекта (TTL/delete); callbacks приёма вызываются синхронно с -2, при ошибке fclose — с -1. */
 void file_transfer_cancel_object(struct file_transfer* ft, const uint8_t object[16]);
 
 #endif