From f46fc8c7ad41581e5bd8b4eb1144a1159cd7d3fc Mon Sep 17 00:00:00 2001 From: Piotr Durlej Date: Mon, 6 Jul 2026 11:39:19 +0200 Subject: [PATCH] docs(channels): clarify message receipt evidence (#90063) Co-authored-by: Peter Steinberger --- docs/docs_map.md | 2 ++ docs/plugins/sdk-channel-outbound.md | 21 +++++++++++++++------ 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/docs_map.md b/docs/docs_map.md index b2b69d140f1e..0fb718e1c25c 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -2361,6 +2361,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - H2: Layout and names - H2: Provision ignored files - H2: Run repository setup + - H2: Session worktrees - H2: Snapshots, cleanup, and restore - H2: CLI - H2: Gateway methods @@ -6907,6 +6908,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - Route: /plugins/sdk-channel-outbound - Headings: - H2: Adapter + - H2: Delivery Evidence - H2: Existing outbound adapters - H2: Durable sends - H2: Compatibility dispatch diff --git a/docs/plugins/sdk-channel-outbound.md b/docs/plugins/sdk-channel-outbound.md index 1e24c8e48b91..d403c5b3fb48 100644 --- a/docs/plugins/sdk-channel-outbound.md +++ b/docs/plugins/sdk-channel-outbound.md @@ -66,6 +66,15 @@ Only declare capabilities the native transport actually preserves. Cover each declared send, receipt, live-preview, and receive-ack capability with the contract helpers exported from this subpath. +## Delivery Evidence + +A `MessageReceipt` records the result returned by a channel adapter. Concrete +platform message identifiers show that the platform send path accepted the +message; they do not prove that a recipient's device displayed or read it. +Receipts without platform message identifiers are local receipt metadata only. +Channels with read receipts or device-delivery state should track those facts +through a separate channel-specific path. + ## Existing outbound adapters If the channel already has a compatible `outbound` adapter, derive the @@ -97,12 +106,12 @@ Runtime send helpers also live on `channel-outbound`: `sendDurableMessageBatch(...)` returns one explicit outcome: -| Outcome | Meaning | -| ---------------- | ---------------------------------------------------------------------------------------- | -| `sent` | at least one visible platform message was delivered | -| `suppressed` | no platform message should be treated as missing | -| `partial_failed` | at least one platform message was delivered before a later payload or side effect failed | -| `failed` | no platform receipt was produced | +| Outcome | Meaning | +| ---------------- | --------------------------------------------------------------------------------------- | +| `sent` | at least one visible platform message was accepted by the platform send path | +| `suppressed` | no platform message should be treated as missing | +| `partial_failed` | at least one platform message was accepted before a later payload or side effect failed | +| `failed` | no platform receipt was produced | Use `payloadOutcomes` when a batch mixes sent, suppressed, and failed payloads. Do not infer hook cancellation from an empty legacy