add concepts from Franck's PR #89

standards/application/reliable-channel-api.md

@@ -128,6 +128,27 @@ types:
         type: RequestId
         description: "The request id this chunk belongs to. This is generated by the send function and its type is defined in messaging-api."
 
+  SyncStatusDetail:
+    type: object
+    description: "Provides a snapshot of the channel's synchronisation state."
+    fields:
+      received:
+        type: uint
+        description: "Number of messages successfully received."
+      missing:
+        type: uint
+        description: "Number of messages detected as missing but not yet retrieved."
+      lost:
+        type: uint
+        description: "Number of messages that could not be retrieved after all attempts."
+
+  SyncStatus:
+    type: enum
+    description: "Indicates whether the channel has detected any outstanding missing messages."
+    values:
+      - synced: "No known missing messages (some may be permanently lost)."
+      - syncing: "Actively attempting to retrieve one or more missing messages."
+
   IEncryption:
     type: object
     description: "Interface for a pluggable encryption mechanism.
@@ -172,7 +193,9 @@ types:
         type: string
         default: ""
         description: "Reliable channel identifier.
-        If empty, the message is considered ephemeral and is not sent reliably.
+        If empty, the message is considered ephemeral: it is not tracked by SDS, never retransmitted, and NEVER segmented.
+        Ephemeral payloads exceeding the network size limit MUST be rejected with an error.
+        When the rate limit is approached, ephemeral messages are dropped immediately rather than queued.
         If != empty, the messageEnvelope will be segmented, SDS'ed and encrypted under the given reliable channel."
 
   ReliableChannel:
@@ -185,6 +208,9 @@ types:
       messageEvents:
         type: ReliableMessageEvents
         description: "Event emitter for message-related events on this channel"
+      syncStatus:
+        type: SyncStatus
+        description: "Current synchronisation status of the channel. Transitions between 'syncing' and 'synced' as missing messages are detected and resolved."
 
   ReliableChannelConfig:
     type: object
@@ -358,6 +384,33 @@ types:
         type: string
         description: "Error message describing what went wrong"
 
+  ReliableMessageAcknowledgedEvent:
+    type: object
+    description: "Event emitted when the message has been definitively acknowledged via causal history."
+    fields:
+      requestId:
+        type: RequestId
+        description: "The request ID associated with the acknowledged message"
+
+  ReliableIrretrievableMessageEvent:
+    type: object
+    description: "Event emitted when a missing message could not be retrieved after all store-query attempts."
+    fields:
+      requestId:
+        type: RequestId
+        description: "The request ID of the unrecoverable message"
+
+  ReliableSyncStatusEvent:
+    type: object
+    description: "Event emitted when the channel's sync status transitions between 'synced' and 'syncing'."
+    fields:
+      status:
+        type: SyncStatus
+        description: "The new sync status"
+      detail:
+        type: SyncStatusDetail
+        description: "Counters describing the current sync state"
+
   ReliableMessageEvents:
     type: event_emitter
     description: "Event source for reliable message events on a channel"
@@ -366,8 +419,17 @@ types:
         type: ReliableMessageReceivedEvent
       "reliable:message:sent":
         type: ReliableMessageSentEvent
+      "reliable:message:acknowledged":
+        type: ReliableMessageAcknowledgedEvent
+        description: "Message definitively acknowledged via causal history."
       "reliable:message:send-error":
         type: ReliableMessageSendErrorEvent
+      "reliable:message:irretrievable":
+        type: ReliableIrretrievableMessageEvent
+        description: "Missing message could not be retrieved after all store-query attempts."
+      "reliable:sync:status":
+        type: ReliableSyncStatusEvent
+        description: "Channel sync status changed between 'synced' and 'syncing'."
 ```
 
 #### Messaging function definitions